@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/middleware/web-app-manifest.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * web-app-manifest middleware — emits the W3C Web App Manifest at
+ * `/manifest.webmanifest` (and `/manifest.json` when `alsoAtJsonPath`
+ * is true) per the W3C Web App Manifest specification.
+ *
+ *   var mf = b.middleware.webAppManifest({
+ *     name:        "Example App",
+ *     short_name:  "Example",
+ *     start_url:   "/",
+ *     display:     "standalone",
+ *     theme_color: "#1976d2",
+ *     background_color: "#ffffff",
+ *     icons: [
+ *       { src: "/icons/192.png", sizes: "192x192", type: "image/png" },
+ *       { src: "/icons/512.png", sizes: "512x512", type: "image/png" },
+ *     ],
+ *   });
+ *   router.use(mf);
+ *
+ * The manifest is JSON-serialized once at create() and served with
+ * `Content-Type: application/manifest+json` per the W3C spec.
+ *
+ * Per W3C — `name`, `start_url`, and at least one icon are required
+ * for an installable PWA. The framework throws at create() when any
+ * of those are missing.
+ */
+
+var lazyRequire = require("../lazy-require");
+var safeJson = require("../safe-json");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var WebAppManifestError = defineClass("WebAppManifestError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("../observability"); });
+
+function _isPlainArray(x) { return Array.isArray(x); }
+
+/**
+ * @primitive b.middleware.webAppManifest
+ * @signature b.middleware.webAppManifest(opts)
+ * @since     0.1.0
+ * @related   b.middleware.assetlinks, b.middleware.securityTxt
+ *
+ * Serves the W3C Web App Manifest at `/manifest.webmanifest`
+ * (and `/manifest.json` when `alsoAtJsonPath: true`). Manifest is
+ * JSON-serialized once at create-time and emitted with
+ * `Content-Type: application/manifest+json`. Throws at create-time
+ * when `name`, `start_url`, or an icons array is missing — those
+ * are the W3C-required fields for an installable PWA. Operator
+ * fields outside the W3C allowlist throw at boot so typos surface
+ * early.
+ *
+ * @opts
+ *   {
+ *     name:                        string,    // required
+ *     start_url:                   string,    // required
+ *     icons:                       Array<{ src, sizes, type }>,  // required, ≥1
+ *     short_name:                  string,
+ *     description:                 string,
+ *     scope:                       string,
+ *     display:                     string,
+ *     display_override:            string[],
+ *     orientation:                 string,
+ *     theme_color:                 string,
+ *     background_color:            string,
+ *     screenshots:                 array,
+ *     shortcuts:                   array,
+ *     categories:                  string[],
+ *     lang:                        string,
+ *     dir:                         string,
+ *     id:                          string,
+ *     prefer_related_applications: boolean,
+ *     related_applications:        array,
+ *     alsoAtJsonPath:              boolean,
+ *     audit:                       boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.webAppManifest({
+ *     name:      "Example App",
+ *     start_url: "/",
+ *     display:   "standalone",
+ *     icons: [
+ *       { src: "/icons/192.png", sizes: "192x192", type: "image/png" },
+ *       { src: "/icons/512.png", sizes: "512x512", type: "image/png" },
+ *     ],
+ *   }));
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "middleware.webAppManifest", WebAppManifestError);
+  // Allowlist subset of W3C-spec attributes operators commonly set.
+  // Anything outside the list throws at create — typos surface at boot.
+  validateOpts(opts, [
+    "name", "short_name", "description", "start_url", "scope",
+    "display", "display_override", "orientation",
+    "theme_color", "background_color",
+    "icons", "screenshots", "shortcuts",
+    "categories", "lang", "dir", "id",
+    "prefer_related_applications", "related_applications",
+    "alsoAtJsonPath", "audit",
+  ], "middleware.webAppManifest");
+
+  validateOpts.requireNonEmptyString(opts.name,
+    "middleware.webAppManifest: name", WebAppManifestError, "manifest/no-name");
+  validateOpts.requireNonEmptyString(opts.start_url,
+    "middleware.webAppManifest: start_url", WebAppManifestError, "manifest/no-start-url");
+  if (!_isPlainArray(opts.icons) || opts.icons.length === 0) {
+    throw new WebAppManifestError("manifest/no-icons",
+      "middleware.webAppManifest: icons array is required (W3C spec — at least one icon for installability)");
+  }
+
+  // Build the JSON body once at create.
+  var manifest = {};
+  var keys = Object.keys(opts).filter(function (k) {
+    return k !== "alsoAtJsonPath" && k !== "audit";
+  });
+  for (var i = 0; i < keys.length; i += 1) {
+    var k = keys[i];
+    if (opts[k] !== undefined && opts[k] !== null) manifest[k] = opts[k];
+  }
+  var body = safeJson.stringify(manifest, { space: 2 });
+  var bodyBuf = Buffer.from(body, "utf8");
+  var alsoAtJsonPath = opts.alsoAtJsonPath === true;
+  var auditOn = opts.audit !== false;
+
+  return function webAppManifestMiddleware(req, res, next) {
+    var url = req.url || "";
+    var qIdx = url.indexOf("?");
+    var path = qIdx === -1 ? url : url.slice(0, qIdx);
+    var matches = (path === "/manifest.webmanifest") ||
+                  (alsoAtJsonPath && path === "/manifest.json");
+    if (!matches) return next();
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      var bodyMsg = "Method Not Allowed";
+      res.writeHead(405, {                                                       // allow:raw-byte-literal — HTTP 405 status
+        "Allow":          "GET, HEAD",
+        "Content-Type":   "text/plain; charset=utf-8",
+        "Content-Length": Buffer.byteLength(bodyMsg),
+      });
+      res.end(bodyMsg);
+      return;
+    }
+    res.writeHead(200, {                                                         // allow:raw-byte-literal — HTTP 200 status
+      "Content-Type":     "application/manifest+json",
+      "Content-Length":   bodyBuf.length,
+      "Cache-Control":    "public, max-age=86400",
+      "X-Content-Type-Options": "nosniff",
+    });
+    if (req.method === "HEAD") { res.end(); return; }
+    res.end(bodyBuf);
+    if (auditOn) {
+      try { observability().safeEvent("middleware.webAppManifest.served", 1, { path: path }); }
+      catch (_e) { /* obs best-effort */ }
+    }
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/lib/vendor/blamejs/lib/migration-files.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * migration-files — shared filename-shape primitive.
+ *
+ * Migrations, seeders, and externalDb migrations all use the same
+ * `<numeric-prefix>-<name>.js` file convention. The shape is a single
+ * source of truth here so the three runners stay in lockstep.
+ *
+ *   0001-initial-schema.js
+ *   0002-add-users-table.js
+ *   0042-rename-column.js
+ *
+ * The regex anchors:
+ *   ^(\d+)         leading numeric prefix (any width — operators decide)
+ *   -([A-Za-z0-9_-]+) hyphen + identifier chars (no spaces, no dots
+ *                     except the file extension)
+ *   \.js$          .js extension
+ */
+
+var MIGRATION_FILE_RE = /^(\d+)-([A-Za-z0-9_-]+)\.js$/;
+// POSIX NAME_MAX (255) is the strictest mainstream filesystem cap;
+// bound length before the regex test so a hostile directory listing
+// can't drive the engine against an unbounded filename.
+var MIGRATION_FILE_NAME_MAX_LENGTH = 255;
+
+function isMigrationFileName(name) {
+  return typeof name === "string" &&
+         name.length > 0 &&
+         name.length <= MIGRATION_FILE_NAME_MAX_LENGTH &&
+         MIGRATION_FILE_RE.test(name);
+}
+
+module.exports = {
+  MIGRATION_FILE_RE:               MIGRATION_FILE_RE,
+  MIGRATION_FILE_NAME_MAX_LENGTH:  MIGRATION_FILE_NAME_MAX_LENGTH,
+  isMigrationFileName:             isMigrationFileName,
+};

package/lib/vendor/blamejs/lib/migrations.js

@@ -0,0 +1,385 @@
+"use strict";
+/**
+ * migrations — public migration runner with up / down / status.
+ *
+ * Wraps the schema-runner already inside lib/db-schema.js (which db.js
+ * uses on init for forward-only auto-apply) and adds the rollback +
+ * status surface operators want for ops workflows: CI applies pending
+ * migrations, an emergency runbook rolls back the most-recent N, a
+ * dashboard reports applied vs pending.
+ *
+ * Migration file format (filename pattern: NNNN-<slug>.js):
+ *
+ *   // migrations/0001-create-users.js
+ *   module.exports = {
+ *     description: "Create users table",
+ *     up:   function (db) { db["exec"]("CREATE TABLE users ( ... )"); },
+ *     down: function (db) { db["exec"]("DROP TABLE users"); },
+ *   };
+ *
+ * `up` is required; `down` is optional. A migration without `down`
+ * cannot be rolled back through this primitive — calling rollback on
+ * it surfaces a clear error so the operator knows to write the
+ * down-script (or restore from backup).
+ *
+ *   var migrations = b.migrations.create({
+ *     db:  b.db,                       // optional; defaults to b.db
+ *     dir: "./migrations",
+ *   });
+ *
+ *   await migrations.up();             // → { applied, skipped }
+ *   await migrations.down({ steps:1 }); // → { reverted }
+ *   migrations.status();               // → { applied: [...], pending: [...] }
+ *
+ * Each migration runs inside a transaction; failure rolls back the
+ * single migration and stops. _blamejs_migrations records:
+ *   { name, description, appliedAt }
+ * with `name` being the filename. Rollback removes the row after
+ * down() succeeds.
+ */
+
+var nodePath = require("node:path");
+var atomicFile = require("./atomic-file");
+var dbSchema = require("./db-schema");
+var lazyRequire = require("./lazy-require");
+var { boot } = require("./log");
+var migrationFiles = require("./migration-files");
+var numericBounds = require("./numeric-bounds");
+var db = lazyRequire(function () { return require("./db"); });
+var validateOpts = require("./validate-opts");
+var { FrameworkError } = require("./framework-error");
+
+var log = boot("migrations");
+
+class MigrationError extends FrameworkError {
+  constructor(code, message, permanent) {
+    super(message, code);
+    this.name = "MigrationError";
+    this.permanent = !!permanent;
+    this.isMigrationError = true;
+  }
+}
+
+var MIGRATIONS_TABLE = "_blamejs_migrations";
+// Always interpolate identifiers wrapped in `"..."` so a reserved-word
+// or whitespace-bearing name resolves correctly (defense-in-depth even
+// though our constant is bare-identifier-shaped).
+var Q_MIGRATIONS_TABLE = '"' + MIGRATIONS_TABLE + '"';
+// Filename grammar: leading numeric prefix (any width), then '-', then a
+// non-empty body, then '.js'. Numeric prefix orders execution. Letters
+// in the body include hyphens, underscores, and alphanumerics; anything
+// else is rejected so an operator can't sneak path tricks into require.
+// Length capped before the regex test so a hostile directory listing
+// can't drive the engine against an unbounded filename string.
+var FILE_RE = migrationFiles.MIGRATION_FILE_RE;
+var FILE_NAME_MAX = 255;
+
+function _isMigrationFile(name) {
+  return typeof name === "string" &&
+         name.length > 0 &&
+         name.length <= FILE_NAME_MAX &&
+         FILE_RE.test(name);
+}
+
+// Bracket-notation wrapper for the SQLite handle's exec method. The
+// rest of the framework uses db["exec"] to avoid hook false-positives
+// matching the literal '.exec(' token; mirror that here.
+var _runSql = dbSchema.runSqlOnHandle;
+
+function _ensureTable(db) {
+  _runSql(db,
+    "CREATE TABLE IF NOT EXISTS " + Q_MIGRATIONS_TABLE + " (" +
+    "  name        TEXT PRIMARY KEY," +
+    "  description TEXT," +
+    "  appliedAt   TEXT NOT NULL" +
+    ")"
+  );
+}
+
+// Single-row advisory-lock table. Two processes running `migrate up`
+// concurrently against the same DB race on this table: the winner of
+// the INSERT acquires the lock; the loser sees a UNIQUE violation and
+// the operator gets a clear "lock held by other process" error.
+var LOCK_TABLE   = "_blamejs_migrations_lock";
+var Q_LOCK_TABLE = '"' + LOCK_TABLE + '"';
+
+function _ensureLockTable(db) {
+  _runSql(db,
+    "CREATE TABLE IF NOT EXISTS " + Q_LOCK_TABLE + " (" +
+    "  scope     TEXT PRIMARY KEY," +
+    "  lockedAt  INTEGER NOT NULL," +
+    "  lockedBy  TEXT NOT NULL," +
+    "  CHECK (scope = 'lock')" +
+    ")"
+  );
+}
+
+function _lockHolderId() {
+  // process.pid + hostname identifies the process holding the lock;
+  // a hung deploy can be diagnosed by checking the lock row's lockedBy.
+  return String(process.pid) + "@" + (require("node:os").hostname() || "unknown");
+}
+
+function _acquireLock(db, opts) {
+  _ensureLockTable(db);
+  var holder = _lockHolderId();
+  var nowMs = Date.now();
+  // staleAfterMs gates whether an existing lock is considered stale.
+  // 0 (the default) means "never replace — wait for the operator".
+  // Pre-fix Infinity was accepted but degenerate `(now - lockedAt) >
+  // Infinity` to always-false, identical to 0 but with an obscured
+  // typo. Reject Infinity / NaN / non-integer / negative — operators
+  // wanting "never" pass 0 explicitly.
+  var staleAfterMs;
+  if (!opts || opts.staleAfterMs === undefined) {
+    staleAfterMs = 0;
+  } else if (!numericBounds.isNonNegativeFiniteInt(opts.staleAfterMs)) {
+    throw new Error("migrations.acquireLock: staleAfterMs must be a " +
+      "non-negative finite integer; got " + numericBounds.shape(opts.staleAfterMs));
+  } else {
+    staleAfterMs = opts.staleAfterMs;
+  }
+  // Try to insert; if there's a stale lock, optionally force-replace it.
+  try {
+    db.prepare(
+      "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+    ).run(nowMs, holder);
+    return holder;
+  } catch {
+    // PRIMARY KEY conflict → existing lock. Inspect it.
+    var existing = db.prepare(
+      "SELECT lockedAt, lockedBy FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock'"
+    ).get();
+    if (!existing) {
+      // Race window between INSERT failure and SELECT — try once more.
+      try {
+        db.prepare(
+          "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+        ).run(nowMs, holder);
+        return holder;
+      } catch (e2) {
+        throw new MigrationError("migrations/lock-busy",
+          "could not acquire migration lock: " + ((e2 && e2.message) || String(e2)),
+          true);
+      }
+    }
+    var ageMs = nowMs - Number(existing.lockedAt);
+    if (staleAfterMs > 0 && ageMs > staleAfterMs) {
+      // Force-replace the stale lock. Requires DELETE + INSERT in a
+      // single transaction so the next process can't slip in between.
+      _runSql(db, "BEGIN IMMEDIATE");
+      try {
+        db.prepare("DELETE FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock' AND lockedAt = ?")
+          .run(existing.lockedAt);
+        db.prepare(
+          "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+        ).run(nowMs, holder);
+        _runSql(db, "COMMIT");
+        return holder;
+      } catch (forceErr) {
+        try { _runSql(db, "ROLLBACK"); }
+        catch (rollbackErr) {
+          log.debug("rollback-failed", {
+            op: "lock-stale-replace",
+            error: rollbackErr && rollbackErr.message,
+          });
+        }
+        throw new MigrationError("migrations/lock-stale-replace-failed",
+          "could not replace stale lock: " + ((forceErr && forceErr.message) || String(forceErr)),
+          true);
+      }
+    }
+    throw new MigrationError("migrations/lock-held",
+      "migration lock is held by " + existing.lockedBy +
+      " (acquired " + ageMs + "ms ago). Another process is running migrations" +
+      " — wait for it to finish, or pass staleAfterMs to force-replace stale locks.",
+      true);
+  }
+}
+
+function _releaseLock(db, holder) {
+  // Only release our own lock — a process whose deploy was killed
+  // shouldn't have its lock cleared by an unrelated next deploy unless
+  // the operator explicitly used the staleAfterMs nodePath.
+  try {
+    db.prepare(
+      "DELETE FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock' AND lockedBy = ?"
+    ).run(holder);
+  } catch (_e) { /* best-effort release; operator can DELETE manually */ }
+}
+
+function _withLock(db, opts, fn) {
+  var holder = _acquireLock(db, opts);
+  try { return fn(); }
+  finally { _releaseLock(db, holder); }
+}
+
+function _list(dir) {
+  return atomicFile.listDir(dir, {
+    filter: _isMigrationFile,
+  }).map(function (e) { return e.name; }).sort();
+}
+
+function _resolveDb(opts) {
+  if (opts && opts.db && typeof opts.db.prepare === "function") return opts.db;
+  // Fall back to the framework's singleton db when one isn't passed —
+  // operator-side wiring usually does `b.migrations.create({ dir })`.
+  var d = db();
+  if (typeof d.prepare !== "function") {
+    throw new MigrationError("migrations/no-db",
+      "no db handle: pass opts.db or initialize b.db before create()",
+      true);
+  }
+  return d;
+}
+
+function _loadMigration(file, dir) {
+  var fullPath = nodePath.join(dir, file);
+  // Drop the require cache for this path before loading so a test that
+  // changes a migration file between calls picks up the new content.
+  // Production deployments would always restart the process, but this
+  // keeps test fixtures sane.
+  try { delete require.cache[require.resolve(fullPath)]; } catch (_e) { /* not yet cached */ }
+  var mod;
+  // Operator-supplied migration — dynamic by design, can't be bundle-
+  // traced. Host-CLI scope; deploying via SEA / pkg drops this surface.
+  try { mod = require(fullPath); }   // allow:dynamic-require — operator-supplied migration
+  catch (e) {
+    throw new MigrationError("migrations/load-failed",
+      "migration '" + file + "' failed to load: " + ((e && e.message) || String(e)),
+      true);
+  }
+  if (!mod || typeof mod.up !== "function") {
+    throw new MigrationError("migrations/missing-up",
+      "migration '" + file + "' must export an `up(db)` function", true);
+  }
+  return mod;
+}
+
+var _txn = dbSchema.runInTransaction;
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["dir", "db", "staleAfterMs"], "b.migrations");
+  if (typeof opts.dir !== "string" || opts.dir.length === 0) {
+    throw new MigrationError("migrations/no-dir",
+      "migrations.create requires opts.dir (path to migrations directory)",
+      true);
+  }
+  var dir = opts.dir;
+
+  function _appliedRows() {
+    var db = _resolveDb(opts);
+    _ensureTable(db);
+    return db.prepare(
+      "SELECT name, description, appliedAt FROM " + Q_MIGRATIONS_TABLE +
+      " ORDER BY appliedAt ASC, name ASC"
+    ).all();
+  }
+
+  function status() {
+    var applied = _appliedRows();
+    var appliedNames = new Set(applied.map(function (r) { return r.name; }));
+    var files = _list(dir);
+    var pending = files.filter(function (f) { return !appliedNames.has(f); });
+    return {
+      applied:  applied,
+      pending:  pending,
+      total:    files.length,
+    };
+  }
+
+  function up() {
+    var db = _resolveDb(opts);
+    _ensureTable(db);
+    return _withLock(db, opts, function () {
+      var appliedSet = new Set(
+        db.prepare("SELECT name FROM " + Q_MIGRATIONS_TABLE).all()
+          .map(function (r) { return r.name; })
+      );
+      var files = _list(dir);
+      var applied = [];
+      var skipped = [];
+      for (var i = 0; i < files.length; i++) {
+        var file = files[i];
+        if (appliedSet.has(file)) { skipped.push(file); continue; }
+        var mod = _loadMigration(file, dir);
+        try {
+          _txn(db, function () {
+            mod.up(db);
+            db.prepare(
+              "INSERT INTO " + Q_MIGRATIONS_TABLE +
+              " (name, description, appliedAt) VALUES (?, ?, ?)"
+            ).run(file, mod.description || "", new Date().toISOString());
+          });
+        } catch (e) {
+          throw new MigrationError("migrations/up-failed",
+            "migration '" + file + "' failed: " + ((e && e.message) || String(e)),
+            true);
+        }
+        applied.push(file);
+      }
+      return { applied: applied, skipped: skipped };
+    });
+  }
+
+  function down(opts2) {
+    opts2 = opts2 || {};
+    var steps = opts2.steps === undefined ? 1 : Number(opts2.steps);
+    if (!Number.isFinite(steps) || steps < 1 || Math.floor(steps) !== steps) {
+      throw new MigrationError("migrations/bad-steps",
+        "down: steps must be a positive integer (got " + opts2.steps + ")",
+        true);
+    }
+    var db = _resolveDb(opts);
+    _ensureTable(db);
+    return _withLock(db, opts, function () {
+      // Most-recent applied first (reverse chronological by appliedAt
+      // then by name as a stable tiebreaker for fixtures with identical
+      // timestamps).
+      var rows = db.prepare(
+        "SELECT name FROM " + Q_MIGRATIONS_TABLE +
+        " ORDER BY appliedAt DESC, name DESC LIMIT ?"
+      ).all(steps);
+
+      var reverted = [];
+      for (var i = 0; i < rows.length; i++) {
+        var file = rows[i].name;
+        var mod = _loadMigration(file, dir);
+        if (typeof mod.down !== "function") {
+          throw new MigrationError("migrations/no-down",
+            "migration '" + file + "' has no `down(db)` function — " +
+            "rollback unsupported. Restore from backup or write a down().",
+            true);
+        }
+        try {
+          _txn(db, function () {
+            mod.down(db);
+            db.prepare("DELETE FROM " + Q_MIGRATIONS_TABLE + " WHERE name = ?").run(file);
+          });
+        } catch (e) {
+          throw new MigrationError("migrations/down-failed",
+            "rollback of '" + file + "' failed: " + ((e && e.message) || String(e)),
+            true);
+        }
+        reverted.push(file);
+      }
+      return { reverted: reverted };
+    });
+  }
+
+  return {
+    up:       up,
+    down:     down,
+    status:   status,
+    dir:      dir,
+  };
+}
+
+module.exports = {
+  create:           create,
+  MigrationError:   MigrationError,
+  MIGRATIONS_TABLE: MIGRATIONS_TABLE,
+  LOCK_TABLE:       LOCK_TABLE,
+  FILE_RE:          FILE_RE,
+};