index.js

// Generated by CoffeeScript 2.3.1
// # `nikita.file(options, callback)`

// Write a file or a portion of an existing file.

// ## Options

// * `append`   
//   Append the content to the target file. If target does not exist,
//   the file will be created.
// * `backup` (string|boolean)   
//   Create a backup, append a provided string to the filename extension or a
//   timestamp if value is not a string, only apply if the target file exists and
//   is modified.
// * `backup_mode`   
//   Backup file mode (permission and sticky bits), defaults to `0o0400`, in the 
//   form of `{mode: 0o0400}` or `{mode: "0400"}`.
// * `content`   
//   Text to be written, an alternative to source which reference a file.
// * `diff` (boolean | function)   
//   Print diff information, pass a readable diff and the result of [jsdiff.diffLines][diffLines] as
//   arguments if a function, default to true.
// * `eof`   
//   Ensure the file ends with this charactere sequence, special values are
//   'windows', 'mac', 'unix' and 'unicode' (respectively "\r\n", "\r", "\n",
//   "\u2028"), will be auto-detected if "true", default to false or "\n" if
//   "true" and not detected.
// * `from`   
//   Replace from after this marker, a string or a regular expression.
// * `gid`   
//   File group name or group id.
// * `local`   
//   Treat the source as local instead of remote, only apply with "ssh"
//   option.
// * `match`   
//   Replace this marker, a string or a regular expression, default to the
//   replaced string if missing.
// * `mode`   
//   File mode (permission and sticky bits), default to `0o0644`, in the form of
//   `{mode: 0o0744}` or `{mode: "0744"}`.
// * `place_before` (string, boolean, regex)   
//   Place the content before the match.
// * `replace`   
//   The content to be inserted, used conjointly with the from, to or match
//   options.
// * `source`   
//   File path from where to extract the content, do not use conjointly with
//   content.
// * `target`   
//   File path where to write content to.
// * `to`   
//   Replace to before this marker, a string or a regular expression.
// * `uid`   
//   File user name or user id.
// * `unlink` (boolean)   
//   Replace the existing link, leaving the refered file untouched.
// * `write`   
//   An array containing multiple transformation where a transformation is an
//   object accepting the options `from`, `to`, `match` and `replace`.

// ## Callback parameters

// * `err`   
//   Error object if any.
// * `status`   
//   Indicate file modifications.

// ## Implementation details

// Internally, this function uses the "chmod" and "chown" function and, thus,
// honor all their options including "mode", "uid" and "gid".

// ## Diff Lines

// Diff can be obtained when the options "diff" is set to true or a function. The
// information is provided in two ways:

// * when `true`, a formated string written to the "stdout" option.
// * when a function, a readable diff and the array returned by the function 
//   `diff.diffLines`, see the [diffLines] package for additionnal information.

// ## More about the `append` option

// The `append` option allows more advanced usages. If `append` is "null", it will
// add the value of the "replace" option at the end of the file when no match
// is found and when the value is a string.

// Using the `append` option conjointly with the `match` and `replace` options gets
// even more interesting. If append is a string or a regular expression, it will
// place the value of the "replace" option just after the match. Internally, a
// string value will be converted to a regular expression. For example the string
// "test" will end up converted to the regular expression `/test/mg`.

// ## Replacing part of a file using from and to markers

// ```js
// require('nikita').file({
//   content: 'here we are\n# from\nlets try to replace that one\n# to\nyou coquin',
//   from: '# from\n',
//   to: '# to',
//   replace: 'my friend\n',
//   target: scratch+'/a_file'
// }, function(err, written){
//   // '# here we are\n# from\nmy friend\n# to\nyou coquin'
// })
// ```

// ## Replacing a matched line by a string

// ```js
// require('nikita').file({
//   content: 'email=david(at)adaltas(dot)com\nusername=root',
//   match: /(username)=(.*)/,
//   replace: '$1=david (was $2)',
//   target: scratch+'/a_file'
// }, function(err, written){
//   // '# email=david(at)adaltas(dot)com\nusername=david (was root)'
// })
// ```

// ## Replacing part of a file using a regular expression

// ```js
// require('nikita').file({
//   content: 'here we are\nlets try to replace that one\nyou coquin',
//   match: /(.*try) (.*)/,
//   replace: ['my friend, $1'],
//   target: scratch+'/a_file'
// }, function(err, written){
//   // '# here we are\nmy friend, lets try\nyou coquin'
// })
// ```

// ## Replacing with the global and multiple lines options

// ```js
// require('nikita').file({
//   content: '#A config file\n#property=30\nproperty=10\n#End of Config',
//   match: /^property=.*$/mg,
//   replace: 'property=50',
//   target: scratch+'/a_file'
// }, function(err, written){
//   // '# A config file\n#property=30\nproperty=50\n#End of Config'
// })
// ```

// ## Appending a line after each line containing "property"

// ```js
// require('nikita').file({
//   content: '#A config file\n#property=30\nproperty=10\n#End of Config',
//   match: /^.*comment.*$/mg,
//   replace: '# comment',
//   target: scratch+'/a_file',
//   append: 'property'
// }, function(err, written){
//   // '# A config file\n#property=30\n# comment\nproperty=50\n# comment\n#End of Config'
// })
// ```

// ## Multiple transformations

// ```js
// require('nikita').file({
//   content: 'username: me\nemail: my@email\nfriends: you',
//   write: [
//     {match: /^(username).*$/mg, replace: '$1: you'},
//     {match: /^email.*$/mg, replace: ''},
//     {match: /^(friends).*$/mg, replace: '$1: me'}
//   ],
//   target: scratch+'/a_file'
// }, function(err, written){
//   // 'username: you\n\nfriends: me'
// })
// ```

// ## Source Code
var diff, misc, nunjucks, path, string;

module.exports = function(options) {
  var j, len, ref, ssh, target, targetHash, targetStat, w;
  this.log({
    message: "Entering file",
    level: 'DEBUG',
    module: 'nikita/lib/file'
  });
  // SSH connection
  ssh = this.ssh(options.ssh);
  if (!((options.source || (options.content != null)) || options.replace || (options.write != null))) {
    // Validate parameters
    throw Error('Missing source or content');
  }
  if (options.source && options.content) {
    throw Error('Define either source or content');
  }
  if (!options.target) {
    throw Error('Missing target');
  }
  this.log({
    message: `Source is "${options.source}"`,
    level: 'DEBUG',
    module: 'nikita/lib/file'
  });
  this.log({
    message: `Destination is "${options.target}"`,
    level: 'DEBUG',
    module: 'nikita/lib/file'
  });
  if (options.content && Buffer.isBuffer(options.content)) {
    options.content = options.content.toString();
  }
  if (typeof options.content === 'function') {
    options.content = options.content(options);
  }
  if (options.diff == null) {
    options.diff = options.diff || !!options.stdout;
  }
  if (options.engine == null) {
    options.engine = 'nunjunks';
  }
  if (options.unlink == null) {
    options.unlink = false;
  }
  if (options.encoding == null) {
    options.encoding = 'utf8';
  }
  switch (options.eof) {
    case 'unix':
      options.eof = "\n";
      break;
    case 'mac':
      options.eof = "\r";
      break;
    case 'windows':
      options.eof = "\r\n";
      break;
    case 'unicode':
      options.eof = "\u2028";
  }
  target = null;
  targetHash = null;
  if (options.write == null) {
    options.write = [];
  }
  if ((options.from != null) || (options.to != null) || (options.match != null) || (options.replace != null) || (options.place_before != null)) {
    options.write.push({
      from: options.from,
      to: options.to,
      match: options.match,
      replace: options.replace,
      append: options.append,
      place_before: options.place_before
    });
    options.append = false;
  }
  ref = options.write;
  for (j = 0, len = ref.length; j < len; j++) {
    w = ref[j];
    if ((w.from == null) && (w.to == null) && (w.match == null) && (w.replace != null)) {
      w.match = w.replace;
    }
  }
  // Start work
  this.call(function(_, callback) { // read source
    var source;
    if (options.content != null) {
      if (typeof options.content === 'number') {
        options.content = `${options.content}`;
      }
      return callback();
    }
    // Option "local" force to bypass the ssh
    // connection, use by the upload function
    source = options.source || options.target;
    this.log({
      message: `Force local source is "${(options.local ? 'true' : 'false')}"`,
      level: 'DEBUG',
      module: 'nikita/lib/file'
    });
    return this.fs.exists({
      ssh: options.local ? false : options.ssh,
      target: source
    }, function(err, exists) {
      if (err) {
        return callback(err);
      }
      if (!exists) {
        if (options.source) {
          return callback(Error(`Source does not exist: ${JSON.stringify(options.source)}`));
        }
        options.content = '';
        return callback();
      }
      this.log({
        message: "Reading source",
        level: 'DEBUG',
        module: 'nikita/lib/file'
      });
      return this.fs.readFile({
        ssh: options.local ? false : options.ssh,
        target: source,
        encoding: options.encoding
      }, function(err, src) {
        if (err) {
          return callback(err);
        }
        options.content = src;
        return callback();
      });
    });
  });
  targetStat = null;
  this.call(function(_, callback) { // read target
    var do_mkdir, do_read, exists;
    if (typeof options.target === 'function') {
      // no need to test changes if target is a callback
      return callback();
    }
    exists = () => {
      this.log({
        message: "Stat target",
        level: 'DEBUG',
        module: 'nikita/lib/file'
      });
      return this.fs.lstat({
        ssh: options.ssh,
        target: options.target,
        relax: true
      }, function(err, stat) {
        if ((err != null ? err.code : void 0) === 'ENOENT') {
          return do_mkdir();
        }
        if (err) {
          return callback(err);
        }
        targetStat = stat;
        if (stat.isDirectory()) {
          options.target = `${options.target}/${path.basename(options.source)}`;
          this.log({
            message: "Destination is a directory and is now \"options.target\"",
            level: 'INFO',
            module: 'nikita/lib/file'
          });
          // Destination is the parent directory, let's see if the file exist inside
          return this.fs.stat({
            ssh: options.ssh,
            target: options.target
          }, function(err, stat) {
            if ((err != null ? err.code : void 0) === 'ENOENT') {
              this.log({
                message: "New target does not exist",
                level: 'INFO',
                module: 'nikita/lib/file'
              });
              return callback();
            }
            if (err) {
              return callback(err);
            }
            if (!stat.isFile()) {
              return callback(Error(`Destination is not a file: ${options.target}`));
            }
            this.log({
              message: "New target exist",
              level: 'INFO',
              module: 'nikita/lib/file'
            });
            targetStat = stat;
            return do_read();
          });
        } else if (stat.isSymbolicLink()) {
          this.log({
            message: "Destination is a symlink",
            level: 'INFO',
            module: 'nikita/lib/file'
          });
          if (!options.unlink) {
            return do_read();
          }
          return this.fs.unlink({
            ssh: options.ssh,
            target: options.target
          }, function(err) {
            if (err) {
              return callback(err);
            }
            return callback(); // Dont go to mkdir since parent dir exists
          });
        } else if (stat.isFile()) {
          this.log({
            message: "Destination is a file",
            level: 'INFO',
            module: 'nikita/lib/file'
          });
          return do_read();
        } else {
          return callback(Error(`Invalid File Type Destination: ${options.target}`));
        }
      });
    };
    do_mkdir = () => {
      if (typeof options.mode === 'string') {
        options.mode = parseInt(options.mode, 8);
      }
      return this.system.mkdir({
        target: path.dirname(options.target),
        uid: options.uid,
        gid: options.gid,
        // force execution right on mkdir
        mode: options.mode ? options.mode | 0o111 : 0o755,
        
        // Modify uid and gid if the dir does not yet exists
        unless_exists: path.dirname(options.target)
      }, function(err, created) {
        if (err) {
          return callback(err);
        }
        return callback();
      });
    };
    do_read = () => {
      this.log({
        message: "Reading target",
        level: 'DEBUG',
        module: 'nikita/lib/file'
      });
      return this.fs.readFile({
        ssh: options.ssh,
        target: options.target,
        encoding: options.encoding
      }, function(err, dest) {
        if (err) {
          return callback(err);
        }
        target = dest; // only used by diff
        targetHash = string.hash(dest);
        return callback();
      });
    };
    return exists();
  });
  this.call(function() { // render
    if (options.context != null) {
      return string.render.call(this, options);
    }
  });
  this.call(function() { // skip_empty_lines
    if (options.skip_empty_lines == null) {
      return;
    }
    this.log({
      message: "Skip empty lines",
      level: 'DEBUG',
      module: 'nikita/lib/file'
    });
    return options.content = options.content.replace(/(\r\n|[\n\r\u0085\u2028\u2029])\s*(\r\n|[\n\r\u0085\u2028\u2029])/g, "$1");
  });
  this.call(function() { // replace_partial
    if (options.write.length) {
      return string.replace_partial.call(this, options);
    }
  });
  this.call(function() { // eof
    var char, i, k, len1, ref1;
    if (options.eof == null) {
      return;
    }
    this.log({
      message: 'Checking option eof',
      level: 'DEBUG',
      module: 'nikita/lib/file'
    });
    if (options.eof === true) {
      ref1 = options.content;
      for (i = k = 0, len1 = ref1.length; k < len1; i = ++k) {
        char = ref1[i];
        if (char === '\r') {
          options.eof = options.content[i + 1] === '\n' ? '\r\n' : char;
          break;
        }
        if (char === '\n' || char === '\u2028') {
          options.eof = char;
          break;
        }
      }
      if (options.eof === true) {
        options.eof = '\n';
      }
      this.log({
        message: `Option eof is true, guessing as ${JSON.stringify(options.eof)}`,
        level: 'INFO',
        module: 'nikita/lib/file'
      });
    }
    if (!string.endsWith(options.content, options.eof)) {
      this.log({
        message: 'Add eof',
        level: 'INFO',
        module: 'nikita/lib/file'
      });
      return options.content += options.eof;
    }
  });
  this.call(function(_, callback) { // diff
    var raw, text;
    if (targetHash === string.hash(options.content)) {
      return callback();
    }
    this.log({
      message: `File content has changed: ${options.target}`,
      level: 'WARN',
      module: 'nikita/lib/file'
    });
    ({raw, text} = diff(target, options.content, options));
    if (typeof options.diff === 'function') {
      options.diff(text, raw);
    }
    this.log({
      message: text,
      type: 'diff',
      level: 'INFO',
      module: 'nikita/lib/file'
    });
    return callback(null, true);
  });
  this.call(function() { // backup
    var backup;
    if (!this.status()) {
      return;
    }
    if (!(options.backup && targetHash)) {
      return;
    }
    this.log({
      message: "Create backup",
      level: 'INFO',
      module: 'nikita/lib/file'
    });
    if (options.backup_mode == null) {
      options.backup_mode = 0o0400;
    }
    backup = typeof options.backup === 'string' ? options.backup : `.${Date.now()}`;
    return this.system.copy({
      ssh: options.ssh,
      source: options.target,
      target: `${options.target}${backup}`,
      mode: options.backup_mode
    });
  });
  this.call(function(_, callback) { // file
    if (!this.status()) {
      return callback();
    }
    if (typeof options.target === 'function') {
      this.log({
        message: 'Write target with user function',
        level: 'INFO',
        module: 'nikita/lib/file'
      });
      options.target(options.content);
      return callback();
    }
    if (options.append) {
      if (options.flags == null) {
        options.flags = 'a';
      }
    }
    // Ownership and permission are also handled
    // Mode is setted by default here to avoid a chmod 644 on existing file if option.mode is not specified
    if (options.mode == null) {
      options.mode = 0o0644;
    }
    return this.fs.writeFile({
      target: options.target,
      flags: options.flags,
      content: options.content
    }, callback);
  });
  this.system.uid_gid({
    uid: options.uid,
    gid: options.gid,
    shy: true
  }, function(err, status, {uid, gid, default_gid}) {
    options.uid = uid;
    return options.gid = !targetStat ? default_gid : gid;
  });
  this.call(function() {
    // Option gid is set at runtime if target is a new file
    return this.system.chown({
      target: options.target,
      stat: targetStat,
      ssh: options.ssh,
      sudo: options.sudo,
      uid: options.uid,
      gid: options.gid,
      if: (options.uid != null) || (options.gid != null),
      unless: options.target === 'function'
    });
  });
  return this.system.chmod({
    target: options.target,
    stat: targetStat,
    ssh: options.ssh,
    sudo: options.sudo,
    mode: options.mode,
    if: options.mode != null,
    unless: options.target === 'function'
  });
};

// ## Dependencies
path = require('path');

nunjucks = require('nunjucks/src/environment');

misc = require('../misc');

diff = require('../misc/diff');

string = require('../misc/string');

// [diffLines]: https://github.com/kpdecker/jsdiff