@blamejs/core 0.4.1

package/lib/deprecate.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * deprecate — runtime deprecation API for the framework's LTS contract.
+ *
+ * Operators see a one-time stderr warning the first time deprecated
+ * surface is used, with the version it was deprecated in and the
+ * version it'll be removed in. Production runs suppress warnings by
+ * default (operators don't want stderr noise from deprecated paths in
+ * code they don't own), but BLAMEJS_DEPRECATIONS env var inverts that
+ * for visibility-on-demand.
+ *
+ *   var dep = b.deprecate;
+ *
+ *   // Direct warning at the call site
+ *   dep.warn("auth.legacyVerify", {
+ *     since:    "0.2.0",
+ *     removeIn: "0.4.0",
+ *     message:  "use auth.password.verify(stored, plain) instead",
+ *     hint:     "see MIGRATING.md#0-2-to-0-4",
+ *   });
+ *
+ *   // Wrap an old function so calls trigger the warning automatically
+ *   var legacyVerify = dep.wrap(newVerify, "auth.legacyVerify", {
+ *     since: "0.2.0", removeIn: "0.4.0",
+ *     message: "renamed to auth.password.verify",
+ *   });
+ *
+ *   // Mark a property as deprecated; access triggers the warning
+ *   dep.alias(targetObj, "oldKey", "newKey", {
+ *     since: "0.2.0", removeIn: "0.4.0",
+ *   });
+ *
+ *   dep.list();   // → [{ name, since, removeIn, callCount, firstSeen }]
+ *   dep.reset();  // clears the seen-set; tests
+ *
+ * BLAMEJS_DEPRECATIONS env var controls runtime behavior:
+ *   "warn"    — stderr warning on first use of each (name, since) pair
+ *               (default outside production)
+ *   "silent"  — skip entirely (default in production)
+ *   "error"   — throw on first use; development tool to surface every
+ *               deprecated call site as a hard failure during a sweep
+ *
+ * Mode resolution order:
+ *   1. process.env.BLAMEJS_DEPRECATIONS if set
+ *   2. "silent" when process.env.NODE_ENV === "production"
+ *   3. "warn" otherwise
+ *
+ * Warnings dedupe by (name, since) — calling deprecate.warn(...) ten
+ * thousand times with the same args produces one stderr line. The
+ * call counter is still incremented so dep.list() shows usage volume.
+ */
+
+var { FrameworkError } = require("./framework-error");
+
+class DeprecateError extends FrameworkError {
+  constructor(code, message) {
+    super(message, code);
+    this.name = "DeprecateError";
+    this.permanent = true;
+    this.isDeprecateError = true;
+  }
+}
+
+// Map of "<name>:<since>" → { name, since, removeIn, callCount, firstSeen }
+var _seen = new Map();
+
+function _modeFromEnv() {
+  var env = process.env.BLAMEJS_DEPRECATIONS;
+  if (typeof env === "string" && env.length > 0) {
+    var v = env.toLowerCase();
+    if (v === "warn" || v === "silent" || v === "error") return v;
+  }
+  if (process.env.NODE_ENV === "production") return "silent";
+  return "warn";
+}
+
+function _format(name, opts) {
+  opts = opts || {};
+  var line = "[blamejs:deprecated] " + name;
+  if (opts.since)    line += " (since " + opts.since + ")";
+  if (opts.removeIn) line += "; removed in " + opts.removeIn;
+  if (opts.message)  line += " — " + opts.message;
+  if (opts.hint)     line += " · " + opts.hint;
+  return line;
+}
+
+function _validateOpts(opts, fnName) {
+  if (!opts || typeof opts !== "object") {
+    throw new DeprecateError("deprecate/bad-opts",
+      fnName + ": opts is required (with at least 'since' and 'removeIn')");
+  }
+  if (typeof opts.since !== "string" || opts.since.length === 0) {
+    throw new DeprecateError("deprecate/bad-opts",
+      fnName + ": opts.since (version string) is required");
+  }
+  if (typeof opts.removeIn !== "string" || opts.removeIn.length === 0) {
+    throw new DeprecateError("deprecate/bad-opts",
+      fnName + ": opts.removeIn (version string) is required");
+  }
+}
+
+function warn(name, opts) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new DeprecateError("deprecate/bad-name",
+      "warn: name is required (the public identifier being deprecated)");
+  }
+  _validateOpts(opts, "warn");
+
+  var key = name + ":" + opts.since;
+  var entry = _seen.get(key);
+  if (!entry) {
+    entry = {
+      name:      name,
+      since:     opts.since,
+      removeIn:  opts.removeIn,
+      message:   opts.message || null,
+      hint:      opts.hint    || null,
+      callCount: 0,
+      firstSeen: new Date().toISOString(),
+    };
+    _seen.set(key, entry);
+  }
+  entry.callCount++;
+
+  var mode = _modeFromEnv();
+  if (mode === "silent") return;
+
+  // Emit on first occurrence only (dedupe)
+  if (entry.callCount > 1) return;
+
+  var line = _format(name, opts);
+  if (mode === "error") {
+    throw new DeprecateError("deprecate/used-in-error-mode",
+      line + " — BLAMEJS_DEPRECATIONS=error in effect");
+  }
+  // mode === "warn"
+  try { process.stderr.write(line + "\n"); }
+  catch (_e) { /* stderr write best-effort */ }
+}
+
+// Wrap a function so calling it issues a deprecation warning + delegates.
+// The wrapper preserves the original function's `.length` (arity) so
+// callers introspecting it as a callable see the same shape.
+function wrap(fn, name, opts) {
+  if (typeof fn !== "function") {
+    throw new DeprecateError("deprecate/bad-target",
+      "wrap: first arg must be the replacement function (the new API)");
+  }
+  if (typeof name !== "string" || name.length === 0) {
+    throw new DeprecateError("deprecate/bad-name",
+      "wrap: name is required (the deprecated identifier)");
+  }
+  _validateOpts(opts, "wrap");
+  var wrapper = function () {
+    warn(name, opts);
+    return fn.apply(this, arguments);
+  };
+  // Preserve identity hints
+  Object.defineProperty(wrapper, "name", { value: name + ":deprecated", configurable: true });
+  return wrapper;
+}
+
+// Define `oldKey` on `target` as a getter that warns then returns
+// `target[newKey]`. The setter writes through so existing assignments
+// still work, but the getter access trips the warning.
+function alias(target, oldKey, newKey, opts) {
+  if (!target || typeof target !== "object") {
+    throw new DeprecateError("deprecate/bad-target",
+      "alias: target must be an object");
+  }
+  if (typeof oldKey !== "string" || oldKey.length === 0) {
+    throw new DeprecateError("deprecate/bad-name",
+      "alias: oldKey is required");
+  }
+  if (typeof newKey !== "string" || newKey.length === 0) {
+    throw new DeprecateError("deprecate/bad-name",
+      "alias: newKey is required");
+  }
+  _validateOpts(opts, "alias");
+  var aliasName = opts.aliasName ||
+    ((target.constructor && target.constructor.name &&
+      target.constructor.name !== "Object" ? target.constructor.name + "." : "") + oldKey);
+  var fullOpts = Object.assign({
+    message: "use '" + newKey + "' instead",
+  }, opts);
+  Object.defineProperty(target, oldKey, {
+    configurable: true,
+    enumerable:   false,
+    get: function () { warn(aliasName, fullOpts); return target[newKey]; },
+    set: function (v) { warn(aliasName, fullOpts); target[newKey] = v; },
+  });
+}
+
+function list() {
+  var out = [];
+  _seen.forEach(function (v) {
+    out.push({
+      name:      v.name,
+      since:     v.since,
+      removeIn:  v.removeIn,
+      callCount: v.callCount,
+      firstSeen: v.firstSeen,
+    });
+  });
+  // Stable order: most-frequent first, ties broken by first-seen
+  out.sort(function (a, b) {
+    if (a.callCount !== b.callCount) return b.callCount - a.callCount;
+    return a.firstSeen < b.firstSeen ? -1 : 1;
+  });
+  return out;
+}
+
+function reset() { _seen.clear(); }
+
+// Export the resolved mode so tests + ops dashboards can introspect
+function getMode() { return _modeFromEnv(); }
+
+module.exports = {
+  warn:               warn,
+  wrap:               wrap,
+  alias:              alias,
+  list:               list,
+  reset:              reset,
+  getMode:            getMode,
+  DeprecateError:   DeprecateError,
+};

package/lib/dev.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * dev — file-watch + child-process restart for iteration loops.
+ *
+ * The framework's hot-reload primitive. Spawn the app as a child
+ * process, watch the source directories, and restart the child when a
+ * file changes. On-disk state (vault keys, encrypted DB, sealed
+ * cookies) survives the restart because the child re-opens the files
+ * — only in-process state is lost, which is the correct semantic for
+ * "I just edited a route handler and want to see it."
+ *
+ *   var dev = b.dev.create({
+ *     command: "node",
+ *     args:    ["./server.js"],
+ *     watch:   ["./routes", "./views", "./public", "./lib"],
+ *     ignore:  [/node_modules/, /\.db$/, /\.tmp$/, /^\./],
+ *     graceMs: 250,           // debounce: collapse bursts into one restart
+ *     killSignal:    "SIGTERM",
+ *     killTimeoutMs: 4000,    // SIGKILL after this if SIGTERM is ignored
+ *     log:     logInstance,   // optional structured logger
+ *     env:     { ...process.env, BLAMEJS_DEV: "1" },
+ *     cwd:     process.cwd(),
+ *   });
+ *
+ *   await dev.start();        // launches child + arms watchers
+ *   await dev.stop();         // signals child + closes watchers
+ *
+ *   dev.stats();              // → { pid, running, restarts, lastRestartAt }
+ *
+ * Operator-side, this is what `blamejs dev` will call (next CLI slice).
+ *
+ * Engine hygiene:
+ *   - Bursts of file events (a saved-everything keystroke, a multi-
+ *     file format-on-save) collapse into one restart via debounce.
+ *   - The child is spawned with stdio: 'inherit' so the operator sees
+ *     their app's output unchanged.
+ *   - Parent SIGINT/SIGTERM are forwarded: stop() before exit so an
+ *     orphan child can't outlive the dev session.
+ *   - Restart in-flight when a new event arrives: queue one followup,
+ *     no more — many edits during a slow restart still result in only
+ *     two restarts, not N.
+ *
+ * Test seams:
+ *   opts._spawn(cmd, args, sopts)        → child-process-shaped object
+ *   opts._watch(dir, wopts, listener)    → fs.watcher-shaped object
+ *   These default to child_process.spawn and fs.watch; tests pass
+ *   fakes to drive the engine without real subprocesses.
+ */
+
+var path = require("path");
+var { FrameworkError } = require("./framework-error");
+
+class DevError extends FrameworkError {
+  constructor(code, message) {
+    super(message, code);
+    this.name = "DevError";
+    this.permanent = true;
+    this.isDevError = true;
+  }
+}
+
+var DEFAULT_GRACE_MS         = 250;
+var DEFAULT_KILL_TIMEOUT_MS  = 4000;
+var DEFAULT_KILL_SIGNAL      = "SIGTERM";
+var DEFAULT_IGNORE = [
+  /node_modules/,
+  /\.git\b/,
+  /^\./,                // dotfiles + dotdirs
+  /\.db$/, /\.db-journal$/, /\.db-wal$/, /\.db-shm$/,
+  /\.log$/,
+  /\.swp$/, /~$/,       // editor scratch files
+];
+
+function _matchesAny(patterns, value) {
+  for (var i = 0; i < patterns.length; i++) {
+    var p = patterns[i];
+    if (p instanceof RegExp) { if (p.test(value)) return true; }
+    else if (typeof p === "string") { if (value.indexOf(p) !== -1) return true; }
+  }
+  return false;
+}
+
+function _logVia(log, level, message, fields) {
+  if (log && typeof log[level] === "function") {
+    try { log[level](message, fields); }
+    catch (_e) { /* logger best-effort */ }
+    return;
+  }
+  // Fallback: prefixed line on stdout/stderr
+  var line = "[blamejs:dev] " + message + (fields ? " " + JSON.stringify(fields) : "");
+  if (level === "error" || level === "warn" || level === "fatal") console.error(line);
+  else console.log(line);
+}
+
+function create(opts) {
+  opts = opts || {};
+  if (typeof opts.command !== "string" || opts.command.length === 0) {
+    throw new DevError("dev/no-command",
+      "dev.create requires opts.command (the program to spawn)");
+  }
+  var args         = Array.isArray(opts.args) ? opts.args.slice() : [];
+  var watch        = Array.isArray(opts.watch) && opts.watch.length > 0
+    ? opts.watch.slice() : ["."];
+  var ignore       = Array.isArray(opts.ignore)
+    ? DEFAULT_IGNORE.concat(opts.ignore)
+    : DEFAULT_IGNORE.slice();
+  var graceMs      = typeof opts.graceMs === "number" && opts.graceMs >= 0
+    ? opts.graceMs : DEFAULT_GRACE_MS;
+  var killSignal   = typeof opts.killSignal === "string" ? opts.killSignal : DEFAULT_KILL_SIGNAL;
+  var killTimeoutMs = typeof opts.killTimeoutMs === "number" && opts.killTimeoutMs >= 0
+    ? opts.killTimeoutMs : DEFAULT_KILL_TIMEOUT_MS;
+  var log          = opts.log || null;
+  var env          = opts.env || process.env;
+  var cwd          = opts.cwd || process.cwd();
+
+  // Test seams
+  var spawnFn = opts._spawn || function (cmd, sargs, sopts) {
+    return require("child_process").spawn(cmd, sargs, sopts);
+  };
+  var watchFn = opts._watch || function (dir, wopts, listener) {
+    return require("fs").watch(dir, wopts, listener);
+  };
+  var setTimeoutFn  = opts._setTimeout  || setTimeout;
+  var clearTimeoutFn = opts._clearTimeout || clearTimeout;
+
+  var child           = null;
+  var watchers        = [];
+  var debounceTimer   = null;
+  var killTimer       = null;
+  var started         = false;
+  var stopping        = false;
+  var restarting      = false;
+  var queuedRestart   = false;
+  var restartCount    = 0;
+  var lastRestartAt   = null;
+
+  function _spawnChild() {
+    var c = spawnFn(opts.command, args, {
+      stdio: opts.stdio || "inherit",
+      env:   env,
+      cwd:   cwd,
+    });
+    c.on("exit", function (code, signal) {
+      // If the child exits while we're not stopping/restarting, that's
+      // a crash — log it and wait for a file change to retry. This
+      // matches nodemon's behavior: a bad commit leaves the child
+      // corpse around without spawn-thrashing.
+      if (!stopping && !restarting) {
+        _logVia(log, "warn",
+          "child exited unexpectedly — waiting for file change to restart",
+          { code: code, signal: signal });
+        child = null;
+      }
+    });
+    c.on("error", function (err) {
+      _logVia(log, "error", "spawn error", { error: (err && err.message) || String(err) });
+    });
+    return c;
+  }
+
+  function _killChild() {
+    return new Promise(function (resolve) {
+      if (!child) return resolve();
+      var c = child;
+      var settled = false;
+      function done() {
+        if (settled) return;
+        settled = true;
+        if (killTimer) { try { clearTimeoutFn(killTimer); } catch (_e) {} killTimer = null; }
+        resolve();
+      }
+      c.once("exit", done);
+      try { c.kill(killSignal); }
+      catch (e) {
+        _logVia(log, "warn", "kill threw, child may already be gone",
+          { error: (e && e.message) || String(e) });
+        return done();
+      }
+      // Hard-kill if the child ignores SIGTERM
+      killTimer = setTimeoutFn(function () {
+        if (settled) return;
+        _logVia(log, "warn",
+          "child did not exit after " + killTimeoutMs + "ms — sending SIGKILL");
+        try { c.kill("SIGKILL"); }
+        catch (_e) { done(); }
+      }, killTimeoutMs);
+      if (killTimer && typeof killTimer.unref === "function") killTimer.unref();
+    });
+  }
+
+  async function _restart() {
+    if (restarting) {
+      // Coalesce: a restart-in-flight gets one followup queued, never more.
+      queuedRestart = true;
+      return;
+    }
+    restarting = true;
+    try {
+      await _killChild();
+      child = null;
+      if (stopping) return;
+      child = _spawnChild();
+      restartCount += 1;
+      lastRestartAt = new Date().toISOString();
+      _logVia(log, "info", "restarted",
+        { pid: child && child.pid, restarts: restartCount });
+    } catch (e) {
+      _logVia(log, "error", "restart failed",
+        { error: (e && e.message) || String(e) });
+    } finally {
+      restarting = false;
+      if (queuedRestart && !stopping) {
+        queuedRestart = false;
+        // Tail-call the queued restart on the next microtask so we
+        // unwind the current stack first.
+        Promise.resolve().then(_restart);
+      }
+    }
+  }
+
+  function _scheduleRestart(reason) {
+    if (stopping) return;
+    if (debounceTimer) clearTimeoutFn(debounceTimer);
+    debounceTimer = setTimeoutFn(function () {
+      debounceTimer = null;
+      _logVia(log, "info", "change detected, restarting", { reason: reason });
+      _restart();
+    }, graceMs);
+    if (debounceTimer && typeof debounceTimer.unref === "function") debounceTimer.unref();
+  }
+
+  function _onWatchEvent(dir, eventType, filename) {
+    if (!filename) return;
+    var rel = String(filename);
+    var full = path.join(dir, rel);
+    if (_matchesAny(ignore, rel) || _matchesAny(ignore, full)) return;
+    _scheduleRestart(eventType + ":" + rel);
+  }
+
+  function _armWatchers() {
+    for (var i = 0; i < watch.length; i++) {
+      (function (dir) {
+        var resolved = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+        var w;
+        try {
+          w = watchFn(resolved, { recursive: true, persistent: false }, function (eventType, filename) {
+            _onWatchEvent(resolved, eventType, filename);
+          });
+        } catch (e) {
+          // Missing dir, permission error, platform that doesn't
+          // support recursive — log and move on so a bad watch entry
+          // doesn't take the whole dev loop down.
+          _logVia(log, "warn", "could not watch " + resolved,
+            { error: (e && e.message) || String(e) });
+          return;
+        }
+        if (w && typeof w.on === "function") {
+          w.on("error", function (err) {
+            _logVia(log, "warn", "watcher error on " + resolved,
+              { error: (err && err.message) || String(err) });
+          });
+        }
+        watchers.push(w);
+      })(watch[i]);
+    }
+  }
+
+  function _disarmWatchers() {
+    for (var i = 0; i < watchers.length; i++) {
+      try { if (watchers[i] && typeof watchers[i].close === "function") watchers[i].close(); }
+      catch (_e) { /* close best-effort */ }
+    }
+    watchers = [];
+  }
+
+  async function start() {
+    if (started) return;
+    started = true;
+    stopping = false;
+    _armWatchers();
+    child = _spawnChild();
+    _logVia(log, "info", "started", { pid: child && child.pid, watch: watch });
+  }
+
+  async function stop() {
+    if (!started) return;
+    stopping = true;
+    if (debounceTimer) { try { clearTimeoutFn(debounceTimer); } catch (_e) {} debounceTimer = null; }
+    _disarmWatchers();
+    await _killChild();
+    child = null;
+    started = false;
+    stopping = false;
+    queuedRestart = false;
+    _logVia(log, "info", "stopped", { restarts: restartCount });
+  }
+
+  async function restart() { await _restart(); }
+
+  function stats() {
+    return {
+      pid:           child && child.pid !== undefined ? child.pid : null,
+      running:       !!child && started && !stopping,
+      restarts:      restartCount,
+      lastRestartAt: lastRestartAt,
+      watchers:      watchers.length,
+    };
+  }
+
+  return {
+    start:    start,
+    stop:     stop,
+    restart:  restart,
+    stats:    stats,
+    // Test hook: simulate a watcher event for engine tests
+    _emit:    function (dir, eventType, filename) { _onWatchEvent(dir, eventType, filename); },
+  };
+}
+
+module.exports = {
+  create:    create,
+  DevError:  DevError,
+  DEFAULT_IGNORE: DEFAULT_IGNORE,
+};