@omega.js/web 0.1.0

package/dist/vendor/devkit/scaffold-guard.js

@@ -0,0 +1,96 @@
+/**
+ * scaffold-guard — the refusal every framework's ensure-target runs before it
+ * writes anything.
+ *
+ * Every verb heals its target on the way past ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)),
+ * which makes the cwd load-bearing: `omega deploy` run at a workspace ROOT
+ * scaffolded a whole desktop target into it — gulpfile, src/, workflows, rewritten
+ * root scripts — before failing anyway ([#699](https://github.com/Omega-JS-Stack/omega/issues/699)).
+ * A workspace root is never a target: a target is a MEMBER of one. So a scaffold
+ * aimed at a manifest declaring `workspaces` is a misfire, not a fresh project.
+ *
+ * Twin of the dispatcher's own refusal (`@omega.js/devkit/omega-bin`), one layer
+ * lower and same shape: that one catches a verb run where NO context resolves,
+ * this one catches a verb that reached a framework CLI anyway. Throwing is the
+ * loud stop — every framework CLI prints the message and exits nonzero.
+ *
+ * Stdlib-only (fs/path), like the dispatcher: it is vendored into every framework
+ * dist and runs before the framework's own dependencies matter.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * The nearest package.json walking up from startDir, BOUNDED at the nearest
+ * `.git` (that directory is still checked) — past the repo boundary is somebody
+ * else's tree. Same bound as the dispatcher's findTarget.
+ *
+ * @param {string} startDir - Where to start the walk.
+ * @returns {{ dir: string, manifestPath: string }|null} null when nothing is found.
+ */
+function nearestManifest(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const manifestPath = path.join(dir, 'package.json');
+    if (fs.existsSync(manifestPath)) return { dir, manifestPath };
+
+    if (fs.existsSync(path.join(dir, '.git'))) return null;
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * A refusal: crafted text a human is meant to read, flagged so every surface
+ * prints it the same way — the message alone, nothing added. `@omega.js/backend`'s
+ * bin and devkit's cli-router both branch on the flag, so a refused command
+ * never renders as a bug (a red ✗ there, a raw stack here) ([#706](https://github.com/Omega-JS-Stack/omega/issues/706)).
+ *
+ * @param {string} message - The lines to print verbatim.
+ * @returns {Error} The flagged error to throw.
+ */
+function refusal(message) {
+  const error = new Error(message);
+  error.refusal = true;
+  return error;
+}
+
+/**
+ * Throw unless projectDir can legitimately be scaffolded as a target. A fresh
+ * directory with no manifest above it stays allowed — that is the standalone
+ * bootstrap case every verb supports.
+ *
+ * @param {string} projectDir - The directory ensure-target is about to write to.
+ * @returns {void}
+ * @throws {Error} When the nearest manifest declares `workspaces`, or cannot be read.
+ */
+function assertScaffoldable(projectDir) {
+  const nearest = nearestManifest(projectDir);
+  if (!nearest) return;
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(nearest.manifestPath, 'utf8'));
+  } catch (e) {
+    // Unreadable is not "not a workspace root". Scaffolding on that guess is the
+    // exact accident this guard exists to stop, so it refuses — and names the
+    // file, which a raw SyntaxError out of JSON.parse never did.
+    throw refusal(
+      `omega: refusing to scaffold into ${path.resolve(projectDir)} — ${nearest.manifestPath} could not be read `
+      + `(${e.message}), so whether this is a workspace root cannot be known. Nothing was scaffolded.\n`
+      + 'Fix that manifest, or run the verb from inside a target (e.g. targets/<name>).',
+    );
+  }
+
+  if (!manifest.workspaces) return;
+
+  throw refusal(
+    `omega: refusing to scaffold into ${path.resolve(projectDir)} — ${nearest.manifestPath} declares "workspaces", `
+    + 'so this is a workspace root (a brand or monorepo root), not an OMEGA target. Nothing was scaffolded.\n'
+    + 'Run the verb from inside a target (e.g. targets/<name>), or `npx omega onboard` to create one.',
+  );
+}
+
+module.exports = { assertScaffoldable, nearestManifest };

package/dist/vendor/devkit/stop-signals.js

@@ -0,0 +1,28 @@
+/**
+ * "How is this run asked to stop?" The ONE list every supervisor registers.
+ *
+ * A supervisor is any process that owns a child, a watcher or a long-running
+ * loop it must unwind before it goes: the backend's emulator and test runner,
+ * the manager's `omega dev`, the web dev server, the log tails. Each of them
+ * used to hand-type its own subset, and the subsets disagreed. The manager
+ * registered SIGINT and SIGTERM only, so a CLOSED TERMINAL (SIGHUP) killed the
+ * orchestrator outright and its detached legs, the emulator tree among them,
+ * orphaned with their ports ([#629](https://github.com/Omega-JS-Stack/omega/issues/629)).
+ *
+ * A signal with no listener is not a shutdown: node kills THIS process only,
+ * and anything detached below it survives. So all three take the SAME teardown:
+ * Ctrl+C (SIGINT), a programmatic stop (a supervisor's own shutdown, `omega
+ * dev`'s stop, the journey lane, all SIGTERM), and a closed terminal (SIGHUP).
+ *
+ * Stdlib-only on purpose: a vendored module must not push a dependency onto
+ * its hosts.
+ */
+
+/**
+ * Every way a run is asked to stop.
+ *
+ * @type {string[]}
+ */
+const STOP_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+module.exports = { STOP_SIGNALS };

package/dist/vendor/devkit/strip-dev-blocks-plugin.js

@@ -0,0 +1,29 @@
+/**
+ * esbuild plugin form of the `@dev-only` strip (#18, #736).
+ *
+ * A thin binding to the ONE cut in `strip-dev-blocks.js` (the webpack loader
+ * twin was deleted with the last webpack lane in
+ * [#738](https://github.com/Omega-JS-Stack/omega/issues/738)), and
+ * unconditional — the lane that registers the plugin decides WHEN. `bundle.js`
+ * registers it for production builds only, so a dev build keeps its warnings
+ * and simulation hooks.
+ */
+
+const fs = require('node:fs');
+
+const { stripDevBlocks, START_MARKER } = require('./strip-dev-blocks.js');
+
+const stripDevBlocksPlugin = {
+  name: 'omega-strip-dev-blocks',
+  setup(build) {
+    build.onLoad({ filter: /\.js$/ }, (args) => {
+      const source = fs.readFileSync(args.path, 'utf8');
+      if (!source.includes(START_MARKER)) {
+        return null; // untouched — let esbuild load it normally
+      }
+      return { contents: stripDevBlocks(source), loader: 'js' };
+    });
+  },
+};
+
+module.exports = { stripDevBlocksPlugin };

package/dist/vendor/devkit/strip-dev-blocks.js

@@ -0,0 +1,32 @@
+/**
+ * The `@dev-only` marker contract — ONE home (#18).
+ *
+ * Code between the markers runs in development and is cut out of every
+ * PRODUCTION bundle, so dev warnings and simulation hooks never ship. Each
+ * Every framework registers the strip the same way now — the esbuild plugin
+ * beside this file, which `bundle.js` composes for production builds — but the
+ * markers and the cut itself live here, once.
+ */
+
+const START_MARKER = '/* @dev-only:start */';
+const END_MARKER = '/* @dev-only:end */';
+
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const BLOCK_PATTERN = new RegExp(`${escapeRegex(START_MARKER)}[\\s\\S]*?${escapeRegex(END_MARKER)}`, 'g');
+
+/**
+ * Strip every dev-only block from a source string.
+ * @param {string} source
+ * @returns {string}
+ */
+function stripDevBlocks(source) {
+  // Fast path — most files carry no markers at all, and this runs over every
+  // module a bundle pulls in (dependencies included).
+  if (!source.includes(START_MARKER)) {
+    return source;
+  }
+
+  return source.replace(BLOCK_PATTERN, '');
+}
+
+module.exports = { stripDevBlocks, START_MARKER, END_MARKER };

package/dist/vendor/devkit/target-secrets.js

@@ -0,0 +1,165 @@
+/**
+ * The `.env` → GitHub Actions secrets publisher, once, for every target that
+ * publishes plain string secrets
+ * ([#627](https://github.com/Omega-JS-Stack/omega/issues/627) review).
+ *
+ * Web built it first (#189) and the extension needed the same thing (#680), so
+ * for one wave there were two near-byte-identical copies — same five skip
+ * cases, same declared-repo guard, same `gh` transport, same wording. This is
+ * the ONE copy; each framework binds it with its own target string and nothing
+ * else.
+ *
+ *   1. DERIVE — the KEY SET is the env schema's: every entry whose `delivery`
+ *      names the target (`publishSecretKeys(target)`, @omega.js/config). Never
+ *      "whatever the composed .env holds", which published a brand's unrelated
+ *      keys to a runner.
+ *   2. COLLECT — the VALUES come from the target's COMPOSED env
+ *      (`composeTargetEnv`, [#678](https://github.com/Omega-JS-Stack/omega/issues/678)):
+ *      company ← brand ← target `.env`, the brand-side layers schema-filtered
+ *      to the keys that target reads with `deliverAs` applied (a brand's
+ *      GOOGLE_ANALYTICS_SECRET_WEB arrives as GOOGLE_ANALYTICS_SECRET). FILES
+ *      only — the shell is never a source, so CI gets what the brand's files
+ *      say under any shell. `machineLocal` keys (#454) need no filter here: the
+ *      schema drops them from the delivered set itself.
+ *   3. GUARD — secrets belong to the repo whose Actions run the workflow, and
+ *      the only acceptable proof of which repo that is, is the brand's own
+ *      config (`repo.providers.github`). An inferred git remote is not proof: a
+ *      target vendored into a framework/test monorepo, a cloned starter still
+ *      pointing at the template author, or any fork would publish this brand's
+ *      `.env` to a stranger's Actions.
+ *   4. PUBLISH — each collected key becomes a repo Actions secret via devkit's
+ *      `gh` boundary (values on stdin, never logged).
+ *
+ * Every skip is LOUD (a line, never silence). A missing/signed-out `gh` is NOT
+ * a skip — it throws the boundary's instructions (install, `gh auth login`, or
+ * `omega deploy --no-secrets`).
+ *
+ * Desktop binds it too ([#682](https://github.com/Omega-JS-Stack/omega/issues/682)),
+ * over the `resolveValue` seam: its signing secrets are named by PATH in the
+ * cascade (`CSC_LINK=config/certs/dev-id.p12`) and what CI needs is the FILE, so
+ * it base64-encodes an existing file between COLLECT and PUBLISH. That seam is
+ * the only shape difference between the three binds — the transport is one.
+ */
+const { composeTargetEnv } = require('../config/index.js');
+const { publishSecretKeys } = require('../config/env-delivery.js');
+const { publishActionsSecrets } = require('./actions-secrets.js');
+const { resolveRepo } = require('./deploy.js');
+
+/**
+ * The publishable secrets for a target: the schema's delivery set for it,
+ * valued from the composed env. An empty value never claims a key.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root (its .env is the local layer).
+ * @param {string} options.target - Target name ('web', 'extension', …).
+ * @param {function} [options.resolveValue] - `(value, key) => string`, the seam
+ *   applied to each collected value before it travels (desktop base64-encodes
+ *   its file-path signing secrets). A falsy return DROPS the key, exactly as an
+ *   empty composed value does.
+ * @returns {Object<string, string>} key → value, ready to publish.
+ */
+function collectTargetSecrets(options) {
+  const { targetDir, target, resolveValue } = options;
+  // PRODUCTION, named rather than sniffed: these values fuel the runner's
+  // release build, and the composer would otherwise default to whatever
+  // environment this shell happens to be
+  // ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)) — the same
+  // determinism the "FILES only, never the shell" rule above buys.
+  const { values } = composeTargetEnv({ targetDir, target, environment: 'production' });
+
+  const secrets = {};
+  for (const key of publishSecretKeys(target)) {
+    if (!values[key]) continue;
+    const value = resolveValue ? resolveValue(values[key], key) : values[key];
+    if (value) secrets[key] = value;
+  }
+
+  return secrets;
+}
+
+/**
+ * The brand's OWN repo as `owner/name`, from the target's resolved config — the
+ * same derivation `omega deploy --direct` uses (`repo.providers.github`, name
+ * falling back to brand.id). Null when the config declares nothing usable or
+ * doesn't load.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @param {string} options.target - Target name ('web', 'extension', …).
+ * @returns {string|null}
+ */
+function declaredBrandRepo(options) {
+  try {
+    const { loadConfig, brandRepoOwner, brandRepoName } = require('../config/index.js');
+    const { config } = loadConfig(options.targetDir, options.target);
+    if (!config) return null;
+
+    const owner = brandRepoOwner(config);
+    const name = brandRepoName(config);
+    return owner && name ? `${owner}/${name}` : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * The `omega deploy` precheck: publish the target's collected `.env` values as
+ * repo Actions secrets.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @param {string} options.target - Target name ('web', 'extension', …).
+ * @param {object} options.logger - `{ log, warn, error }`.
+ * @param {object} [options.env] - Env map (default: process.env).
+ * @param {function} [options.resolveValue] - Value seam (see collectTargetSecrets).
+ * @param {function} [options.execFn] - Injectable `gh` exec (tests).
+ * @param {function} [options.gitExecFn] - Injectable `git` exec for remote discovery (tests).
+ * @returns {{ skipped: string }|{ published: string[], failed: Array<object> }}
+ */
+function publishTargetSecrets(options) {
+  options = options || {};
+  const { targetDir, target, logger } = options;
+  const env = options.env || process.env;
+
+  // CI runs the generated workflow as its build/publish step — the secrets
+  // already exist there and the runner token can't write them.
+  if (env.GITHUB_ACTIONS === 'true' || env.CI === 'true') {
+    logger.log('Skipping secret publication — CI already has the repo secrets');
+    return { skipped: 'ci' };
+  }
+
+  const secrets = collectTargetSecrets({ targetDir, target, resolveValue: options.resolveValue });
+  const keys = Object.keys(secrets);
+  if (!keys.length) {
+    logger.warn('Skipping secret publication — no keys composed for this target from the .env cascade (company/brand/target)');
+    return { skipped: 'no-secrets' };
+  }
+
+  let repo;
+  try {
+    const { owner, repo: name } = resolveRepo({ cwd: targetDir, execFn: options.gitExecFn });
+    repo = `${owner}/${name}`;
+  } catch (e) {
+    logger.warn(`Skipping secret publication — no GitHub remote here (${e.message})`);
+    return { skipped: 'no-remote' };
+  }
+
+  const declared = declaredBrandRepo({ targetDir, target });
+  if (!declared) {
+    logger.warn('Skipping secret publication — this brand names no GitHub repo in config (repo.providers.github). Set it, then re-run `omega deploy`.');
+    return { skipped: 'no-declared-repo' };
+  }
+  if (declared.toLowerCase() !== repo.toLowerCase()) {
+    logger.warn(`Skipping secret publication — the git remote here is ${repo}, but this brand's repo is ${declared}. Run \`omega deploy\` from the brand's own checkout.`);
+    return { skipped: 'repo-mismatch' };
+  }
+
+  logger.log(`Publishing ${keys.length} secret(s) to ${repo}: ${keys.join(', ')}`);
+
+  const result = publishActionsSecrets({ repo, secrets, logger, execFn: options.execFn });
+  logger.log(`Published ${result.published.length}/${keys.length} secret(s) to ${repo}`);
+
+  return result;
+}
+
+module.exports = { collectTargetSecrets, declaredBrandRepo, publishTargetSecrets };

package/dist/vendor/devkit/test/scope.js

@@ -0,0 +1,162 @@
+/**
+ * Test-scope grammar (C5) — ONE parser for `omega test` targets across every
+ * framework, so scoping means the same thing in a web app, a backend, a
+ * desktop app, and an extension:
+ *
+ *   npx omega test                     → PROJECT tests only (consumer context)
+ *   npx omega test pages/              → project tests under pages/
+ *   npx omega test project:pages/      → same, explicit (`brand:` = alias)
+ *   npx omega test framework:          → the framework's own suite
+ *   npx omega test framework:routes/   → framework suite, scoped
+ *   npx omega test full:               → both sources
+ *   npx omega test full:auth           → both sources, path-scoped
+ *
+ * `omega:` and `mgr:` are universal framework aliases; each framework also
+ * answers to its own id (`backend:`, `desktop:`, `extension:`, `web:`) via
+ * `frameworkAliases`. Bare paths bind to the PROJECT source — reaching the
+ * framework suite is always an explicit choice (Ian 2026-07-11: bare runs
+ * from a brand must never drag the framework corpus in).
+ *
+ * Framework SELF context (running inside the framework package itself —
+ * `selfTest: true`) flips the no-target default to the framework suite, so
+ * each package's own `npm test` keeps meaning "run my suite".
+ */
+
+const UNIVERSAL_FRAMEWORK_ALIASES = ['framework', 'omega', 'mgr'];
+const PROJECT_ALIASES = ['project', 'brand'];
+const FULL_ALIASES = ['full'];
+
+// Per-framework id prefixes, keyed by package name. The SSOT for "which
+// prefixes does each framework answer to": framework runners pass their own
+// entry as `frameworkAliases`, and the manager's brand-root `test` fan-out
+// routes `web:`/`desktop:`/… targets to the target owning that framework.
+// Legacy short ids (ujm/em/bxm) retired with cp262's legacy-name sweep.
+const FRAMEWORK_IDS = {
+  '@omega.js/web': ['web'],
+  '@omega.js/backend': ['backend'],
+  '@omega.js/desktop': ['desktop'],
+  '@omega.js/extension': ['extension'],
+};
+
+/**
+ * Parse `omega test` positional targets into sources + per-source path filters.
+ *
+ * @param {string[]} rawTargets - Positional targets (may be empty)
+ * @param {Object} [options]
+ * @param {string[]} [options.frameworkAliases] - Extra framework prefixes for
+ *   this framework (e.g. ['backend'], ['desktop'], ['extension'], ['web'])
+ * @param {boolean} [options.selfTest] - True when running inside the framework
+ *   package itself (no consumer project)
+ * @returns {{
+ *   sources: string[],                             // subset of ['framework', 'project']
+ *   filters: { framework: string[], project: string[] }, // prefix-stripped path filters per source
+ *   invalid: string[],                             // unrecognized `<word>:` prefixes (likely typos)
+ * }}
+ */
+function parseTestScope(rawTargets, options = {}) {
+  const frameworkAliases = new Set([
+    ...UNIVERSAL_FRAMEWORK_ALIASES,
+    ...(options.frameworkAliases || []),
+  ]);
+
+  const sources = new Set();
+  const filters = { framework: [], project: [] };
+  const invalid = [];
+
+  for (const raw of rawTargets || []) {
+    const target = String(raw).trim();
+    if (!target) continue;
+
+    const match = target.match(/^([a-z-]+):(.*)$/);
+
+    if (!match) {
+      // Bare path — binds to the PROJECT source.
+      sources.add('project');
+      filters.project.push(target);
+      continue;
+    }
+
+    const [, prefix, pathPart] = match;
+
+    if (frameworkAliases.has(prefix)) {
+      sources.add('framework');
+      if (pathPart) filters.framework.push(pathPart);
+    } else if (PROJECT_ALIASES.includes(prefix)) {
+      sources.add('project');
+      if (pathPart) filters.project.push(pathPart);
+    } else if (FULL_ALIASES.includes(prefix)) {
+      sources.add('framework');
+      sources.add('project');
+      if (pathPart) {
+        filters.framework.push(pathPart);
+        filters.project.push(pathPart);
+      }
+    } else {
+      // Unknown prefix — surface it rather than silently matching nothing.
+      invalid.push(target);
+    }
+  }
+
+  // No targets (or only invalid ones): consumer default = project only;
+  // framework self context = the framework's own suite.
+  if (sources.size === 0) {
+    sources.add(options.selfTest ? 'framework' : 'project');
+  }
+
+  return {
+    sources: ['framework', 'project'].filter((s) => sources.has(s)),
+    filters,
+    invalid,
+  };
+}
+
+/**
+ * Did the run ask for test files BY NAME? A path filter (`build/x`,
+ * `project:x`, `desktop:x`, `full:x`) names files; a bare run, or a bare
+ * source prefix, asks for a source. Only the first kind can be a typo, so
+ * only the first kind fails when it selects nothing
+ * ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)).
+ *
+ * @param {{filters: {framework: string[], project: string[]}}} scope - A parseTestScope() result
+ * @returns {boolean} True when at least one path filter was given
+ */
+function isPathTargeted(scope) {
+  return scope.filters.framework.length > 0 || scope.filters.project.length > 0;
+}
+
+/**
+ * The ONE line every framework prints when a named target selects zero test
+ * files: the same sentence in a web app, a backend, a desktop app and an
+ * extension ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)).
+ *
+ * @param {string} target - The target as the caller spelled it
+ * @returns {string} The message (the caller adds its own log tag)
+ */
+function noMatchMessage(target) {
+  return `No test file matches "${target}".`;
+}
+
+// A brand-root run fans ONE target out over every target, where a target that
+// does not carry that path is a legitimate no-op rather than a typo. The
+// manager sets this signal on the runs it forwards and reads the exit code
+// below to tell a miss from a failure
+// ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)). Its presence is
+// the whole signal, the way OMEGA_CASE_RUNNER's is.
+const FANOUT_ENV = 'OMEGA_TEST_FANOUT';
+
+// The exit code a no-match answers with under that signal: distinct, so the
+// fan-out counts misses without confusing them with failures. A standalone run
+// stays 1, the code every human and every CI already reads as "this failed".
+const NO_MATCH_EXIT_CODE = 3;
+
+/**
+ * The exit code a no-match run ends on, given its environment.
+ *
+ * @param {object} [env] - The environment to read (defaults to process.env)
+ * @returns {number} NO_MATCH_EXIT_CODE inside a brand-root fan-out, else 1
+ */
+function noMatchExitCode(env = process.env) {
+  return env[FANOUT_ENV] ? NO_MATCH_EXIT_CODE : 1;
+}
+
+module.exports = { parseTestScope, isPathTargeted, noMatchMessage, noMatchExitCode, NO_MATCH_EXIT_CODE, FANOUT_ENV, UNIVERSAL_FRAMEWORK_ALIASES, PROJECT_ALIASES, FULL_ALIASES, FRAMEWORK_IDS };

package/dist/vendor/devkit/translate/cache.js

@@ -0,0 +1,84 @@
+/**
+ * The committed translation cache — per-string maps keyed by a hash of the
+ * SOURCE string, stored as reviewable JSON in the consumer's `translations/`
+ * directory (committed to git, replacing both the legacy gitignored `.cache/`
+ * and the cache-uj-translation GitHub-branch flow). A source edit changes the
+ * hash → cache miss → only that string re-translates; a human can hand-fix a
+ * translation VALUE and it sticks for as long as the source is unchanged.
+ *
+ * Layout: <rootDir>/<lang>/<namespace>.json  →  { "<hash12>": "translation" }
+ * (namespace = a page path for web, 'messages'/'description' for extension).
+ */
+const path = require('node:path');
+const crypto = require('node:crypto');
+const jetpack = require('fs-jetpack');
+
+/**
+ * Cache key for a source string.
+ * @param {string} source - the source-language string
+ * @returns {string} 12-hex-char sha256 prefix
+ */
+function hashKey(source) {
+  return crypto.createHash('sha256').update(source).digest('hex').slice(0, 12);
+}
+
+/**
+ * Resolve a namespace's cache file path.
+ * @param {string} rootDir - translations root (e.g. <consumer>/translations)
+ * @param {string} lang - language code
+ * @param {string} namespace - cache namespace (slashes allowed)
+ * @returns {string}
+ */
+function cachePath(rootDir, lang, namespace) {
+  return path.join(rootDir, lang, `${namespace}.json`);
+}
+
+/**
+ * Load a namespace's hash → translation map ({} when absent/corrupt).
+ * @param {string} rootDir - translations root
+ * @param {string} lang - language code
+ * @param {string} namespace - cache namespace
+ * @returns {object}
+ */
+function loadCache(rootDir, lang, namespace) {
+  const file = cachePath(rootDir, lang, namespace);
+
+  if (!jetpack.exists(file)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(jetpack.read(file)) || {};
+  } catch (e) {
+    return {};
+  }
+}
+
+/**
+ * Save a namespace's map, pruned to the CURRENT source strings so stale
+ * entries never accumulate. No-op delete when the map is empty.
+ * @param {string} rootDir - translations root
+ * @param {string} lang - language code
+ * @param {string} namespace - cache namespace
+ * @param {object} map - hash → translation
+ * @param {string[]} [currentSources] - prune to these sources' hashes
+ */
+function saveCache(rootDir, lang, namespace, map, currentSources) {
+  let pruned = map;
+
+  if (currentSources) {
+    const keep = new Set(currentSources.map(hashKey));
+    pruned = Object.fromEntries(Object.entries(map).filter(([key]) => keep.has(key)));
+  }
+
+  const file = cachePath(rootDir, lang, namespace);
+
+  if (!Object.keys(pruned).length) {
+    jetpack.remove(file);
+    return;
+  }
+
+  jetpack.write(file, `${JSON.stringify(pruned, null, 2)}\n`);
+}
+
+module.exports = { hashKey, cachePath, loadCache, saveCache };