@omega.js/web 0.1.0

package/dist/vendor/devkit/command-path.js

@@ -0,0 +1,46 @@
+/**
+ * "Is this tool installed?" — the ONE cross-platform PATH probe.
+ *
+ * Every framework asks it of an external CLI it shells out to (mkcert,
+ * nodemon, the Stripe CLI) and the answer decides whether a lane runs or
+ * degrades. The probe itself is platform-specific: Unix has `which`, Windows
+ * has `where`, and each host has only its own — a bare `which` on Windows is
+ * not "not installed", it's a crash the caller reads as "not installed".
+ */
+const { execSync } = require('child_process');
+
+/**
+ * Is a command installed? An EXISTENCE probe.
+ *
+ * **Never spawn what this returns.** The path is for REPORTING — a log line, a
+ * diagnostic, a "which one did we find". Running the tool means naming it BARE
+ * and letting the host resolve it (`spawnOnPath` in @omega.js/backend does
+ * exactly that), because on Windows `where` prints the extensionless shell shim
+ * FIRST, and neither that shim nor the `.cmd` beside it is something Node's
+ * CreateProcess can execute — only a shell can, and only a shell applies
+ * PATHEXT. Truthiness is the answer this exists to give.
+ *
+ * @param {string} name - Command name, e.g. 'mkcert'
+ * @param {object} [options]
+ * @param {string} [options.platform] - Host platform (test seam)
+ * @param {function} [options.exec] - execSync (test seam)
+ * @returns {string|null} The first path the probe reported, or null when it is not installed
+ */
+function commandOnPath(name, { platform = process.platform, exec = execSync } = {}) {
+  const probe = platform === 'win32' ? 'where' : 'which';
+
+  try {
+    const found = exec(`${probe} ${name}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+
+    // `where` prints EVERY match, one per line (`which` prints one); the first
+    // is the one the shell would pick — on Windows that is the extensionless
+    // shim, which is why this answer is reported and not spawned.
+    return String(found).split(/\r?\n/)[0].trim() || null;
+  } catch (e) {
+    // Both probes exit nonzero when the name isn't found — the expected answer,
+    // not a failure.
+    return null;
+  }
+}
+
+module.exports = { commandOnPath };

package/dist/vendor/devkit/defaults-engine.js

@@ -0,0 +1,372 @@
+// applyDefaults(config) — the shared OMEGA defaults-scaffolding engine.
+//
+// Every framework ships a defaults tree (src/defaults/ → dist/defaults/) that
+// setup copies into the consumer project. The copy rules lived as two divergent
+// implementations (BXM's gulp FILE_MAP task — the real one — and EM's plain-fs
+// copyDefaults; UJM carries a third copy of the BXM shape). This is the single
+// plain-fs engine, a normalized superset of both.
+//
+// File-map rules: minimatch patterns (dot:true) matched against the RAW path
+// relative to defaultsDir, last-match-wins option merging. Per-rule options:
+//   overwrite  bool|fn(item)  default true — write even if the destination exists
+//   skip       bool|fn(item)  default false — never process this file
+//   name       fn(item)       rename the output file
+//   path       fn(item)       re-destination the output (relative dir)
+//   template   object         render `{{ key.path }}` tokens with this data
+//                             (tolerant: unknown keys survive verbatim, so GitHub
+//                             Actions' `${{ secrets.X }}` passes through)
+//   merge      bool           JSON5 defaults-merge with the existing file
+//   mergeLines bool           OMEGA marker-section line merge (.env/.gitignore/AGENTS.md)
+//   retire     bool           brand-context per-target doc retirement: NEVER scaffold
+//                             the file; an existing framework-owned-only copy is
+//                             DELETED (one-time heal — the brand root is the doc
+//                             home), a copy carrying consumer content stays with a
+//                             loud move-it warning (never destroyed)
+//
+// Engine built-ins (not expressed in the file map):
+//   - `_.name` segments lose the leading `_` (dotfiles ship past npm's filter)
+//   - non-final segments starting `_` (but not `_.`) are ARCHIVE dirs — skipped
+//     (reference material that ships in the framework package, e.g. EM's `_mas/`)
+//   - `.gitkeep` creates the destination directory, the file itself never copies
+//   - `.DS_Store` never copies
+//   - text writes are skipped when the destination is byte-identical (idempotent
+//     re-runs report zero writes)
+//   - a destination carrying the OMEGA section markers when the current template
+//     no longer does is a PRIOR-GENERATION generated file: framework-owned, so
+//     `retire` sweeps it and `overwrite: false` still heals it
+//   - binary files (by extension) copy verbatim — never templated/merged/transformed
+
+const path = require('path');
+const fs = require('fs');
+const jetpack = require('fs-jetpack');
+const { minimatch } = require('minimatch');
+const { mergeLineBasedFiles, hasSectionMarkers, getCustomSection } = require('./merge-line-files');
+
+// Files with these extensions copy byte-for-byte and never go through
+// template/merge/transform (matches BXM's binary detection list).
+const BINARY_EXTENSIONS = /\.(jpg|jpeg|png|gif|webp|svg|ico|woff|woff2|ttf|otf|eot|pdf|zip|tar|gz|mp3|mp4|avi|mov)$/i;
+
+const RULE_DEFAULTS = {
+  overwrite: true,
+  skip: false,
+  name: null,
+  path: null,
+  template: null,
+  merge: false,
+  mergeLines: false,
+  retire: false,
+  rule: null,
+};
+
+/**
+ * Scaffold a framework defaults tree into a consumer project.
+ *
+ * @param {object} config
+ * @param {string} config.defaultsDir - Absolute root of the defaults tree (e.g. <framework>/dist/defaults)
+ * @param {string} config.outputDir - Absolute consumer project root to scaffold into
+ * @param {Object<string, object>} [config.fileMap] - minimatch pattern → rule options (see header)
+ * @param {string[]} [config.files] - Only process these absolute source paths (watch single-file mode)
+ * @param {Function} [config.transform] - `(contents, item) => contents` global hook, run on every
+ *   non-binary file after per-rule processing (BXM's site-token templating pass)
+ * @param {object} [config.logger] - `{ log, warn, error }` (defaults to console)
+ * @returns {{ written: string[], merged: string[], skipped: string[], removed: string[] }} destination-relative paths per outcome
+ */
+function applyDefaults(config) {
+  config = config || {};
+
+  const defaultsDir = config.defaultsDir;
+  const outputDir = config.outputDir;
+  const fileMap = config.fileMap || {};
+  const only = config.files ? config.files.map((f) => path.resolve(f)) : null;
+  const transform = config.transform || null;
+  const logger = config.logger || console;
+
+  if (!defaultsDir || !outputDir) {
+    throw new Error('[devkit defaults-engine] defaultsDir and outputDir are required');
+  }
+  if (!jetpack.exists(defaultsDir)) {
+    throw new Error(`[devkit defaults-engine] defaultsDir does not exist: ${defaultsDir}`);
+  }
+
+  const result = { written: [], merged: [], skipped: [], removed: [] };
+
+  for (const source of walkFiles(defaultsDir)) {
+    if (only && !only.includes(source)) {
+      continue;
+    }
+
+    const relative = path.relative(defaultsDir, source).split(path.sep).join('/');
+    const segments = relative.split('/');
+    const basename = segments[segments.length - 1];
+
+    // Archive dirs: any non-final `_x` segment (but `_.x` files are renames, not archives).
+    const dirSegments = segments.slice(0, -1);
+    if (dirSegments.some((s) => s.startsWith('_') && !s.startsWith('_.'))) {
+      continue;
+    }
+
+    if (basename === '.DS_Store') {
+      continue;
+    }
+
+    // `.gitkeep` → ensure the directory exists, never copy the file itself.
+    if (basename === '.gitkeep') {
+      jetpack.dir(path.join(outputDir, ...strippedSegments(segments).slice(0, -1)));
+      continue;
+    }
+
+    const options = resolveOptions(relative, fileMap);
+
+    // Item passed to rule functions — built from the `_.`-stripped path.
+    const stripped = strippedSegments(segments);
+    const item = {
+      source: path.dirname(source),
+      name: stripped[stripped.length - 1],
+      destination: stripped.slice(0, -1).join('/'),
+    };
+
+    if (typeof options.name === 'function') {
+      item.name = options.name(item);
+    }
+    if (typeof options.path === 'function') {
+      item.destination = options.path(item);
+    }
+    if (typeof options.skip === 'function') {
+      options.skip = options.skip(item);
+    }
+    if (typeof options.overwrite === 'function') {
+      options.overwrite = options.overwrite(item);
+    }
+
+    const finalRelative = path.join(item.destination, item.name);
+    const destination = path.join(outputDir, finalRelative);
+    const exists = jetpack.exists(destination);
+    const isBinary = BINARY_EXTENSIONS.test(item.name);
+
+    if (options.skip) {
+      result.skipped.push(finalRelative);
+      continue;
+    }
+
+    // Retire: the file never scaffolds. An existing framework-owned-only copy
+    // is deleted (one-time heal); consumer content is never destroyed.
+    if (options.retire) {
+      if (!exists) {
+        result.skipped.push(finalRelative);
+        continue;
+      }
+
+      let owned;
+      if (isBinary) {
+        owned = jetpack.read(source, 'buffer').equals(jetpack.read(destination, 'buffer'));
+      } else {
+        // Render the template through the same pipeline the scaffold used, so
+        // an untouched consumer copy compares equal.
+        let rendered = jetpack.read(source);
+        if (options.template) {
+          rendered = renderTemplate(rendered, options.template);
+        }
+        if (transform) {
+          rendered = transform(rendered, item);
+        }
+        owned = isFrameworkOwned(jetpack.read(destination), rendered);
+      }
+
+      if (owned) {
+        jetpack.remove(destination);
+        pruneEmptyDirs(path.dirname(destination), outputDir);
+        result.removed.push(finalRelative);
+        logger.warn(`Retired ${finalRelative} — framework-owned per-target doc; in a brand monorepo the BRAND ROOT (AGENTS.md / CHANGELOG.md / docs/) is the one doc home`);
+      } else {
+        result.skipped.push(finalRelative);
+        logger.warn(`Kept ${finalRelative} — it carries consumer content. Per-target docs are retired in brand monorepos: move that content to the brand root (AGENTS.md notes / brand CHANGELOG.md / brand docs/), then delete the file`);
+      }
+      continue;
+    }
+
+    // Binary: copy or preserve — no content processing.
+    if (isBinary) {
+      if (exists && !options.overwrite) {
+        result.skipped.push(finalRelative);
+        continue;
+      }
+      jetpack.copy(source, destination, { overwrite: true });
+      result.written.push(finalRelative);
+      continue;
+    }
+
+    let contents = jetpack.read(source);
+    let didMerge = false;
+
+    // Per-rule template render happens BEFORE merging, so merges compare
+    // rendered framework defaults against the consumer's file (EM semantic).
+    if (options.template) {
+      contents = renderTemplate(contents, options.template);
+    }
+
+    if (options.merge && exists) {
+      try {
+        const JSON5 = require('json5');
+        const merged = mergeJson5Defaults(JSON5.parse(jetpack.read(destination)), JSON5.parse(contents));
+        contents = JSON5.stringify(merged, null, 2);
+        didMerge = true;
+      } catch (error) {
+        logger.error(`Error merging config file ${finalRelative}: ${error.message}`);
+        // Fall through to normal processing.
+      }
+    }
+
+    if (options.mergeLines && exists) {
+      try {
+        contents = mergeLineBasedFiles(jetpack.read(destination), contents, item.name);
+        didMerge = true;
+      } catch (error) {
+        logger.error(`Error merging line-based file ${finalRelative}: ${error.message}`);
+      }
+    }
+
+    // Preserve the consumer's file unless a rule says otherwise — except a
+    // prior-generation marker artifact, which the framework owns and heals to
+    // the current template even under `overwrite: false` (the standalone twin
+    // of the retire sweep below).
+    if (exists && !options.overwrite && !didMerge && !isLegacyMarkerArtifact(jetpack.read(destination), contents)) {
+      result.skipped.push(finalRelative);
+      continue;
+    }
+
+    if (transform) {
+      contents = transform(contents, item);
+    }
+
+    // Idempotency: identical content is not a write.
+    if (exists && jetpack.read(destination) === contents) {
+      result.skipped.push(finalRelative);
+      continue;
+    }
+
+    jetpack.write(destination, contents);
+    (didMerge ? result.merged : result.written).push(finalRelative);
+    logger.log(`${didMerge ? 'Merged' : 'Scaffolded'} → ${finalRelative}`);
+  }
+
+  return result;
+}
+
+// Judge whether an existing consumer file is framework-owned-only (safe to
+// retire). Marker files are judged by their Custom section — empty,
+// whitespace-only, or exactly the template's shipped boilerplate all count as
+// untouched. Marker-less files must match the rendered template outright.
+function isFrameworkOwned(existing, rendered) {
+  if (hasSectionMarkers(existing)) {
+    if (isLegacyMarkerArtifact(existing, rendered)) return true;
+    const existingCustom = getCustomSection(existing).trim();
+    return existingCustom === '' || existingCustom === getCustomSection(rendered).trim();
+  }
+  return existing.trim() === rendered.trim();
+}
+
+// A generation change: the destination carries the OMEGA marker grammar — which
+// only this framework's own scaffold writes — while the current template has
+// dropped it. That file is a PRIOR GENERATION's generated copy (e.g. the
+// content-bearing CLAUDE.md written before it became the one-line `@AGENTS.md`
+// pointer), so comparing it against the current render can never match and the
+// framework, not the consumer, owns it.
+function isLegacyMarkerArtifact(existing, rendered) {
+  return hasSectionMarkers(existing) && !hasSectionMarkers(rendered);
+}
+
+// Remove now-empty ancestor dirs of a retired file, stopping at (and never
+// removing) rootDir — a retired docs/README.md takes its empty docs/ with it.
+function pruneEmptyDirs(dir, rootDir) {
+  const root = path.resolve(rootDir);
+  let current = path.resolve(dir);
+  while (current !== root && current.startsWith(root + path.sep)) {
+    if ((jetpack.list(current) || []).length > 0) return;
+    jetpack.remove(current);
+    current = path.dirname(current);
+  }
+}
+
+// Depth-first file walk that never follows symlinks.
+function* walkFiles(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      yield* walkFiles(abs);
+    } else if (entry.isFile()) {
+      yield abs;
+    }
+  }
+}
+
+// `_.name` → `.name` on every segment (dotfiles ship past npm's tarball filter).
+function strippedSegments(segments) {
+  return segments.map((s) => (s.startsWith('_.') ? s.slice(1) : s));
+}
+
+// Last-match-wins option resolution across the file map (BXM's getFileOptions).
+function resolveOptions(relativePath, fileMap) {
+  let options = { ...RULE_DEFAULTS };
+
+  for (const pattern in fileMap) {
+    if (minimatch(relativePath, pattern, { dot: true })) {
+      options = { ...options, ...fileMap[pattern] };
+      options.rule = pattern;
+    }
+  }
+
+  return options;
+}
+
+// Minimal `{{ key.path }}` substitution (EM's tolerant renderer — the standard).
+// Unknown keys render as the original `{{ ... }}` string, so non-template content
+// with literal braces (e.g. GitHub Actions `${{ secrets.X }}`) survives.
+function renderTemplate(content, context) {
+  if (typeof content !== 'string' || !content.includes('{{')) return content;
+  return content.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (full, keyPath) => {
+    const value = keyPath.split('.').reduce((acc, k) => (acc == null ? acc : acc[k]), context);
+    return (value === undefined || value === null) ? full : String(value);
+  });
+}
+
+// JSON5 defaults merge (BXM's mergeConfigs): framework defaults provide shape and
+// order; the consumer's values win unless they're the literal string 'default';
+// consumer-only keys survive at every nesting level.
+function mergeJson5Defaults(existingConfig, newConfig) {
+  const merged = { ...newConfig };
+
+  function mergeNested(target, source, newDefaults) {
+    for (const key in newDefaults) {
+      if (Object.prototype.hasOwnProperty.call(newDefaults, key)) {
+        const newValue = newDefaults[key];
+        const existingValue = source[key];
+
+        if (typeof newValue === 'object' && newValue !== null && !Array.isArray(newValue)) {
+          target[key] = target[key] || {};
+          mergeNested(target[key], existingValue || {}, newValue);
+        } else if (Object.prototype.hasOwnProperty.call(source, key) && existingValue !== 'default') {
+          target[key] = existingValue;
+        } else {
+          target[key] = newValue;
+        }
+      }
+    }
+
+    // Consumer-only keys survive at every level.
+    for (const key in source) {
+      if (!Object.prototype.hasOwnProperty.call(newDefaults, key)) {
+        target[key] = source[key];
+      }
+    }
+  }
+
+  mergeNested(merged, existingConfig, newConfig);
+
+  return merged;
+}
+
+module.exports = { applyDefaults, mergeJson5Defaults, renderTemplate };

package/dist/vendor/devkit/deploy-precheck.js

@@ -0,0 +1,54 @@
+/**
+ * runDeployPrecheck — the shared runner for the NETWORK half `omega setup`
+ * used to own ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+ *
+ * Setup's local half rides every verb (each framework's ensure-target); what
+ * needs the network rides the ONE verb that needs the remote side right —
+ * `omega deploy` — as a precheck before the dispatch. The STEPS differ per
+ * framework (desktop signs and provisions release repos, extension checks its
+ * own freshness, web publishes Actions secrets); the RUNNER does not, so it
+ * lives here and every framework file is its list.
+ *
+ * The contract the runner guarantees:
+ *   - `--no-secrets` (yargs: `secrets: false`) skips the whole precheck — the
+ *     same opt-out name on web, desktop and extension (parity; desktop's old
+ *     `--quick` is gone).
+ *   - Every step is SOFT: a throwing step is reported as a warning and the run
+ *     continues. A precheck reports; the deploy is the caller's decision.
+ *   - Steps run in list order and `ran` names the ones that finished, so a test
+ *     hands its own recorder in and reads back exactly what happened.
+ */
+
+/**
+ * @param {object} input
+ * @param {string} input.projectDir - The target root.
+ * @param {object} [input.options] - The parsed CLI options (`secrets: false` = opted out).
+ * @param {object} input.logger - `{ log, warn, error }`.
+ * @param {Array<{ name: string, run: function }>} input.steps - The framework's step list.
+ * @returns {Promise<{ skipped: string }|{ ran: string[] }>} The steps that ran, or the opt-out marker.
+ */
+async function runDeployPrecheck({ projectDir, options, logger, steps }) {
+  // yargs turns `--no-secrets` into `secrets: false`.
+  if (options && options.secrets === false) {
+    logger.log('Skipping the network prechecks (--no-secrets)');
+    return { skipped: 'opt-out' };
+  }
+
+  const log = (line) => logger.log(line);
+  const warn = (line) => logger.warn(line);
+  const ran = [];
+
+  for (const step of steps) {
+    try {
+      await step.run({ projectDir, log, warn });
+      ran.push(step.name);
+    } catch (e) {
+      // A precheck REPORTS; the deploy is the caller's decision.
+      warn(`${step.name} failed during the deploy precheck (non-fatal): ${e.message}`);
+    }
+  }
+
+  return { ran };
+}
+
+module.exports = { runDeployPrecheck };

package/dist/vendor/devkit/deploy-record.js

@@ -0,0 +1,180 @@
+/**
+ * The per-brand deploy record — `<target>` under the `deploy` section of
+ * `.omega/state.json` (gitignored, per-machine). Multi-instance targets key
+ * per target: the primary stays `<target>`, other instances record under
+ * `<target>:<id>` (see deployKey).
+ *
+ * Written by every framework's deploy verb on success; read by the
+ * manager's testing service to tell "never deployed" (live-URL checks skip
+ * with a nudge) from "deployed but down" (an honest error). A record-less
+ * brand whose live URL answers gets ADOPTED — recorded on the spot — so
+ * fresh clones of long-deployed brands self-heal on their first manage run
+ * (Ian 2026-07-17).
+ *
+ * state.json is the ONE per-machine record file, sectioned per fact kind
+ * (#479): future record-shaped facts join it as sibling top-level sections, so
+ * this module reads and writes ONLY `deploy` and passes every other section
+ * through verbatim — including the config-shaped keys an unmigrated brand
+ * still carries from the retired state CONTENT (#434), which belong to the
+ * state-retirement migration and to nothing here.
+ *
+ * The record spent 0.45.0 in a `.omega/deploys.json` of its own (#449); a
+ * brand still carrying that file has it adopted here, once and loudly.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const Logger = require('./logger.js');
+const { findBrandRoot } = require('./local.js');
+
+const logger = new Logger('deploy-record');
+
+function stateFile(dir) {
+  return path.join(findBrandRoot(dir), '.omega', 'state.json');
+}
+
+/**
+ * Read the machine state with its `deploy` section resolved, folding in the
+ * interim `.omega/deploys.json` (#449) on the way — one-time and LOUD, so a
+ * brand that deployed on 0.45.0 keeps its stamps and the operator sees where
+ * they went. Records already in state.json WIN: newest write, newest home.
+ *
+ * A brand whose state.json already carries a `deploy` key is home — the
+ * records are read in place, silently, whatever else the file still holds.
+ *
+ * Rewrites the files it touches, so callers hold the lock.
+ *
+ * @param {string} file - The state.json path.
+ * @returns {Object} The machine state, `deploy` section included.
+ */
+function loadState(file) {
+  const state = jetpack.read(file, 'json') || {};
+  const records = state.deploy || {};
+
+  const deploysFile = path.join(path.dirname(file), 'deploys.json');
+  const deploys = jetpack.read(deploysFile, 'json');
+
+  state.deploy = deploys ? { ...deploys, ...records } : records;
+  if (!deploys) return state;
+
+  // The new home lands before the old file goes: a crash between the two
+  // writes must never leave the records with no file at all.
+  jetpack.write(file, state, { jsonIndent: 2 });
+  jetpack.remove(deploysFile);
+
+  if (Object.keys(deploys).length > 0) {
+    logger.log(`Adopted ${describe(deploys)} from .omega/deploys.json into .omega/state.json — the old file was removed.`);
+  }
+
+  return state;
+}
+
+/**
+ * "1 deploy record" / "3 deploy records" — the adoption line's subject.
+ * @param {Object} records - key → record.
+ * @returns {string}
+ */
+function describe(records) {
+  const count = Object.keys(records).length;
+  return `${count} deploy record${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * Record key for a target's instance (multi-instance targets): the primary
+ * keeps today's bare target key (zero breaking change — existing records
+ * stay valid); any other instance keys `<target>:<id>`, matching the
+ * per-target deploy model (each target deploys its own instance).
+ * @param {string} target - Target key (web/backend/desktop/extension)
+ * @param {string} [instance] - Instance id ('main' or absent = the primary)
+ * @returns {string} The deploy-record key
+ */
+function deployKey(target, instance) {
+  return instance && instance !== 'main' ? `${target}:${instance}` : target;
+}
+
+/**
+ * Run fn under a best-effort cross-process lock on the records file, so two
+ * targets deploying in parallel can't drop each other's record in the
+ * read-modify-write. Lock contention waits briefly; a stale lock (owner
+ * crashed) is stolen after 5s; on timeout we proceed unlocked — a deploy
+ * must never fail over its bookkeeping.
+ * @param {string} file - Records file path.
+ * @param {function} fn - Critical section.
+ * @returns {*} fn's result.
+ */
+function withStateLock(file, fn) {
+  const lockDir = `${file}.lock`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  const deadline = Date.now() + 2000;
+  let locked = false;
+  while (Date.now() < deadline) {
+    try {
+      fs.mkdirSync(lockDir);
+      locked = true;
+      break;
+    } catch (e) {
+      try {
+        if (Date.now() - fs.statSync(lockDir).mtimeMs > 5000) {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+          continue;
+        }
+      } catch (statError) {
+        continue; // Lock vanished between mkdir and stat — retry immediately
+      }
+      // Synchronous 25ms wait (no async surface here by design)
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    if (locked) {
+      fs.rmSync(lockDir, { recursive: true, force: true });
+    }
+  }
+}
+
+/**
+ * Record a successful deploy for a target.
+ *
+ * @param {Object} options
+ * @param {string} options.dir - Any directory inside the brand (target or root)
+ * @param {string} options.target - Target key (web/backend/desktop/extension)
+ * @param {string} [options.instance] - Instance id; non-main instances record
+ *   under their own `<target>:<id>` key (per-target deploy records)
+ * @param {Object} [options.detail] - Extra fields (method, adopted, …)
+ * @returns {Object} The written record
+ */
+function recordDeploy(options) {
+  const file = stateFile(options.dir);
+  const key = deployKey(options.target, options.instance);
+
+  return withStateLock(file, () => {
+    const state = loadState(file);
+
+    state.deploy[key] = { at: new Date().toISOString(), ...(options.detail || {}) };
+    jetpack.write(file, state, { jsonIndent: 2 });
+
+    return state.deploy[key];
+  });
+}
+
+/**
+ * The recorded deploy for a target's instance — null when the brand has
+ * never deployed it from this machine (and no manage run has adopted a live
+ * site yet).
+ *
+ * @param {Object} options - { dir, target, instance? }
+ * @returns {Object|null}
+ */
+function readDeployRecord(options) {
+  const file = stateFile(options.dir);
+  // Under the lock because the read is also where a legacy record is adopted
+  const state = withStateLock(file, () => loadState(file));
+  return state.deploy[deployKey(options.target, options.instance)] || null;
+}
+
+module.exports = { recordDeploy, readDeployRecord, deployKey };