@starci/hfs 4.4.0 → 4.5.0

package/runtime/scripts/hfs/rules/fe-build-args.mjs

@@ -0,0 +1,142 @@
+// R300 FE_PUBLIC_BUILD_ARG_MISSING: every required browser build value has a Dockerfile ARG default or a buildArgs name in every environment deploying that app; literal fallback reads are optional.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { parseDockerfile, words } from '../../lib/dockerfile.mjs';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+import { found, readText } from './read.mjs';
+
+export const FE_PUBLIC_BUILD_ARG_MISSING = 'FE_PUBLIC_BUILD_ARG_MISSING';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PUBLIC = /^NEXT_PUBLIC_[A-Z0-9_]+$/u;
+const SOURCE = /\.[cm]?[jt]sx?$/u;
+const SCHEMA = /(?:^|[/.-])(?:env|schema)(?:[/.-]|$)/u;
+const DECLARATION = '.starcistacks/application-stacks.yaml';
+
+function declarationOf(root) {
+  try { return parseYaml(readText(root, DECLARATION) ?? '') ?? {}; } catch { return {}; }
+}
+
+/** Parentheses and TypeScript assertions do not alter whether a read has a literal fallback. */
+function unwrappedParent(ts, node) {
+  let current = node;
+  while (current.parent && (ts.isParenthesizedExpression(current.parent) || ts.isAsExpression(current.parent) || ts.isNonNullExpression(current.parent))) current = current.parent;
+  return current;
+}
+
+function literalFallback(ts, node) {
+  const current = unwrappedParent(ts, node);
+  const parent = current.parent;
+  if (!parent || !ts.isBinaryExpression(parent) || parent.left !== current) return false;
+  const fallback = parent.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken || parent.operatorToken.kind === ts.SyntaxKind.BarBarToken;
+  return fallback && ts.isStringLiteralLike(parent.right);
+}
+
+function publicRead(ts, node) {
+  if (!ts.isPropertyAccessExpression(node) || !PUBLIC.test(node.name.text)) return null;
+  const owner = node.expression;
+  const env = ts.isIdentifier(owner) && owner.text === 'env';
+  const processEnv = ts.isPropertyAccessExpression(owner) && owner.name.text === 'env' && ts.isIdentifier(owner.expression) && owner.expression.text === 'process';
+  return env || processEnv ? node.name.text : null;
+}
+
+function optionalSchema(ts, node) {
+  if (!node) return false;
+  if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+    if (['optional', 'default', 'catch', 'nullish'].includes(node.expression.name.text)) return true;
+    return optionalSchema(ts, node.expression.expression);
+  }
+  return false;
+}
+
+function schemaKey(ts, node) {
+  if (!ts.isPropertyAssignment(node) && !ts.isPropertySignature(node)) return null;
+  const name = node.name?.text;
+  if (!PUBLIC.test(name ?? '') || node.questionToken || optionalSchema(ts, node.initializer)) return null;
+  return name;
+}
+
+function sourceRequirements(ts, file, text) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+  const required = new Set();
+  const schema = SCHEMA.test(file);
+  const visit = node => {
+    const name = publicRead(ts, node);
+    if (name && !literalFallback(ts, node)) required.add(name);
+    const key = schema ? schemaKey(ts, node) : null;
+    if (key) required.add(key);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return required;
+}
+
+/** JSON/YAML environment schemas declare required names explicitly; optional properties impose no build requirement. */
+function schemaRequirements(text) {
+  let schema;
+  try { schema = parseYaml(text); } catch { return []; }
+  const names = [];
+  const visit = value => {
+    if (!value || typeof value !== 'object') return;
+    if (Array.isArray(value.required)) names.push(...value.required.filter(name => typeof name === 'string' && PUBLIC.test(name)));
+    Object.values(value).forEach(child => { if (child && typeof child === 'object') visit(child); });
+  };
+  visit(schema);
+  return names;
+}
+
+function requiredNames(root, files, app, ts) {
+  const prefix = `fe/apps/${app}/`;
+  const names = new Set();
+  for (const file of files.filter(file => file.startsWith(prefix))) {
+    const local = file.slice(prefix.length);
+    const source = SOURCE.test(local) && (local.startsWith('src/') || /^next\.config\./u.test(local) || SCHEMA.test(local));
+    const schema = SCHEMA.test(local) && /\.(?:json|ya?ml)$/u.test(local);
+    if (!source && !schema) continue;
+    const text = readText(root, file);
+    if (text === null) continue;
+    const required = source ? sourceRequirements(ts, local, text) : schemaRequirements(text);
+    for (const name of required) names.add(name);
+  }
+  return [...names].sort(byCodeUnit);
+}
+
+function dockerDefaults(text) {
+  return new Set(parseDockerfile(text).instructions.filter(item => item.keyword === 'ARG')
+    .flatMap(item => words(item.text)).filter(word => word.includes('='))
+    .map(word => word.slice(0, word.indexOf('='))));
+}
+
+function missingForEnvironment(environment, app, required) {
+  const images = Object.values(environment?.deploy?.images ?? {}).filter(image => image?.app === app);
+  if (!images.length) return [];
+  return required.filter(name => images.some(image => {
+    const args = image.buildArgs ?? {};
+    return !Object.hasOwn(args.values ?? {}, name) && !(args.sealed?.keys ?? []).includes(name);
+  }));
+}
+
+function appFindings(context, app, environments, ts) {
+  const { repoRoot, files } = context;
+  const file = `fe/apps/${app}/Dockerfile`;
+  if (!files.includes(file)) return [];
+  const defaults = dockerDefaults(readText(repoRoot, file) ?? '');
+  const required = requiredNames(repoRoot, files, app, ts).filter(name => !defaults.has(name));
+  const missing = Object.entries(environments).flatMap(([environment, entry]) => {
+    const names = missingForEnvironment(entry, app, required);
+    return names.length ? [{ environment, names }] : [];
+  });
+  if (!missing.length) return [];
+  const detail = missing.map(entry => `${entry.environment}: ${entry.names.join(', ')}`).join('; ');
+  return [found(FE_PUBLIC_BUILD_ARG_MISSING, file, `${FE_PUBLIC_BUILD_ARG_MISSING}: ${file} requires public build values without ARG defaults or deploy image buildArgs (${detail}).`, { missing })];
+}
+
+/** Judge front-end Dockerfiles at the app root in both editions; only names are read, and sealed members are never opened. */
+export function feBuildArgsFindings({ repoRoot, files = [], all = files, repo, isRoot = true }) {
+  if (!repoRoot || !isRoot || !repo?.sides?.fe) return [];
+  const ts = loadTypescript(repoRoot, HERE);
+  if (!ts) return [];
+  const environments = declarationOf(repoRoot).environments ?? {};
+  return repo.sides.fe.apps.flatMap(app => appFindings({ repoRoot, files: all }, app.name, environments, ts));
+}

package/runtime/scripts/hfs/rules/frontend-tree.mjs

@@ -22,7 +22,7 @@ const I18N_CATALOG = 'FE_I18N_CATALOG';
 export const DEFAULT_LOCALE = 'vi';
 const ROUTE_FILE = /\/(?:page|layout|template|loading|error|not-found)\.[jt]sx?$/;
 const LOCALE = /^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/;
-export const WIRE_SCHEMA_STAMP = '.schema-sha256';
+const WIRE_SCHEMA_STAMP = '.schema-sha256';
 
 /** Every leaf key of a parsed catalog as a dotted path. */
 function catalogKeys(value, prefix = '') {
@@ -32,7 +32,7 @@ function catalogKeys(value, prefix = '') {
 }
 
 /** Digest protocol for codegen: sorted app-relative schema path, NUL, LF-normalized source, NUL. */
-export function wireSchemaDigest(repoRoot, snapshots) {
+function wireSchemaDigest(repoRoot, snapshots) {
   const hash = createHash('sha256');
   for (const snapshot of [...snapshots].sort(byCodeUnit)) {
     let source;

package/runtime/scripts/hfs/rules/supabase-secrets.mjs

@@ -77,7 +77,7 @@ function providerSecretFindings(repoRoot, file, repo, findings) {
 }
 
 /** Raw L17 findings. The catalog-driven findings filter decides which editions judge them. */
-export function liteSecretCustodyFindings({ repoRoot, files, repo }) {
+function liteSecretCustodyFindings({ repoRoot, files, repo }) {
   const findings = [];
   for (const file of files) {
     if (custodyPathFinding(file, repo, findings)) continue;

package/runtime/scripts/hfs/rules/supply-chain.mjs

@@ -1,5 +1,5 @@
 // R269: app repositories in both editions declare dependency updates, a production audit gate, and image SBOM/provenance.
-import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
+import { parseWorkflow, workflowFindings } from '../runtime-rules/workflow-source.mjs';
 import { found, readText } from './read.mjs';
 
 const DEPENDABOT = '.github/dependabot.yml';
@@ -85,12 +85,48 @@ function stepsOf(workflow) {
   return Object.values(workflow?.jobs ?? {}).filter(enabled).flatMap((job) => Array.isArray(job.steps) ? job.steps.filter(enabled) : []);
 }
 
+/** npm groups admit only minor and patch updates; canon packages are ignored for every update type. */
+function hasNpmPolicy(update) {
+  const groups = update.groups && typeof update.groups === 'object' && !Array.isArray(update.groups) ? Object.values(update.groups) : [];
+  const minorPatch = (group) => Array.isArray(group?.['update-types']) && group['update-types'].includes('minor') && group['update-types'].includes('patch');
+  return groups.length > 0 && groups.every((group) => Array.isArray(group?.['update-types']) && group['update-types'].length > 0 && group['update-types'].every((type) => ['minor', 'patch'].includes(type))) &&
+    groups.some((group) => minorPatch(group) && [undefined, 'version-updates'].includes(group['applies-to'])) &&
+    groups.some((group) => group['applies-to'] === 'security-updates') &&
+    Array.isArray(update.ignore) && update.ignore.some((entry) => entry?.['dependency-name'] === '@starci/*' && entry.versions === undefined && entry['update-types'] === undefined);
+}
+
 function hasDependabot(document) {
   const directory = (value) => typeof value === 'string' && value.startsWith('/');
   return document?.version === 2 && Array.isArray(document.updates) && ECOSYSTEMS.every((ecosystem) => document.updates.some((update) =>
     update?.['package-ecosystem'] === ecosystem &&
     (directory(update.directory) || Array.isArray(update.directories) && update.directories.length > 0 && update.directories.every(directory)) &&
-    ['daily', 'weekly', 'monthly'].includes(update.schedule?.interval)));
+    ['daily', 'weekly', 'monthly'].includes(update.schedule?.interval))) &&
+    document.updates.filter((update) => update?.['package-ecosystem'] === 'npm').every(hasNpmPolicy);
+}
+
+function pinnedAction(value) {
+  return typeof value === 'string' && (/^\.\/[\w./-]+$/.test(value) ||
+    /^[\w.-]+\/[\w.-]+(?:\/[\w.-]+)*@[a-f\d]{40}$/i.test(value) ||
+    /^docker:\/\/[^\s@]+@sha256:[a-f\d]{64}$/i.test(value));
+}
+
+/** Mark YAML keys before parsing so comments and script scalars are ignored while flow maps and quoted keys retain their source lines. */
+function workflowPinFindings({ path: file, text }) {
+  const marked = text.replace(/(^|[\s{,])(?:"uses"|'uses'|uses)([ \t]*:)/gm, (match, prefix, colon, offset) => {
+    const line = text.slice(0, offset + prefix.length).split('\n').length;
+    return `${prefix}__hfs_action_uses_line_${line}__${colon}`;
+  });
+  const findings = [];
+  function visit(value) {
+    if (!value || typeof value !== 'object') return;
+    for (const [key, member] of Object.entries(value)) {
+      const line = /^__hfs_action_uses_line_(\d+)__$/.exec(key)?.[1];
+      if (line && !pinnedAction(member)) findings.push(found('HFS_WORKFLOW_PIN', file, `${file}:${line}: every remote uses entry needs a full 40-hex commit SHA; container actions need a sha256 digest.`, { line: Number(line) }));
+      visit(member);
+    }
+  }
+  visit(parseWorkflow(marked));
+  return findings;
 }
 
 function hasAudit(steps) {
@@ -160,8 +196,9 @@ export function supplyChainFindings({ repoRoot, files, all = files, repo, isRoot
   const tracked = new Set(all);
   const parsed = (file) => tracked.has(file) ? parseWorkflow(readText(repoRoot, file) ?? '') : null;
   const findings = [];
-  if (inScope(DEPENDABOT) && !hasDependabot(parsed(DEPENDABOT))) findings.push(found('HFS_DEPENDABOT_MISSING', DEPENDABOT, 'Declare Dependabot version 2 updates for npm, github-actions and docker, each with a directory and schedule.'));
+  if (inScope(DEPENDABOT) && !hasDependabot(parsed(DEPENDABOT))) findings.push(found('HFS_DEPENDABOT_MISSING', DEPENDABOT, 'Declare Dependabot version 2 updates for npm, github-actions and docker, each with a directory and schedule; every npm update must group minor+patch version updates, restrict every group to minor/patch (never major), include a security-updates group, and ignore all @starci/* updates (canon pins move only by starci upgrade).'));
   if (inScope(CI) && !hasAudit(stepsOf(parsed(CI)))) findings.push(found('HFS_AUDIT_STEP_MISSING', CI, 'CI must run npm audit --omit=dev in an enabled step whose failure stops the job.'));
   if (inScope(IMAGES) && !imageEvidence(stepsOf(parsed(IMAGES)))) findings.push(found('HFS_SBOM_MISSING', IMAGES, 'The images workflow must generate an SBOM and provenance for its release images in enabled steps.'));
+  findings.push(...workflowFindings({ files: [...tracked].filter((file) => inScope(file)), read: (file) => readText(repoRoot, file) }, workflowPinFindings));
   return findings;
 }

package/runtime/scripts/hfs/rules/workflow-contexts.mjs

@@ -0,0 +1,103 @@
+// R299: GitHub Actions expressions use only contexts available at their workflow key.
+import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
+import { found } from './read.mjs';
+import { appWorkflowFindings } from './app-workflow-findings.mjs';
+
+const WORKFLOW = ['github', 'inputs', 'vars'];
+const JOB_IF = ['github', 'needs', 'vars', 'inputs'];
+const JOB = [...JOB_IF, 'strategy', 'matrix'];
+const JOB_ENV = [...JOB, 'secrets'];
+const EXECUTION = [...JOB_ENV, 'job', 'runner', 'env'];
+const CONTEXTS = [...EXECUTION, 'steps'];
+const JOB_KEYS = new Set(['name', 'runs-on', 'concurrency', 'strategy', 'timeout-minutes', 'continue-on-error', 'with']);
+
+/** Container and service images are chosen before a runner exists; their other properties use execution contexts. */
+function containerContexts(keys) {
+  if (keys[2] === 'services') return keys[4] === 'image' ? JOB : EXECUTION;
+  return keys.length === 3 || keys[3] === 'image' ? JOB : EXECUTION;
+}
+
+/** The most specific row of GitHub's Context availability table governs each descendant value. */
+function jobContexts(keys) {
+  const key = keys[2];
+  if (key === 'steps') return CONTEXTS;
+  if (key === 'if') return JOB_IF;
+  if (key === 'strategy') return JOB_IF;
+  if (key === 'env' || key === 'secrets') return JOB_ENV;
+  if (key === 'outputs') return CONTEXTS;
+  if (key === 'defaults' && keys[3] === 'run') return [...JOB, 'env'];
+  if (key === 'environment') return keys[3] === 'url' ? CONTEXTS.filter((context) => context !== 'secrets') : JOB;
+  if (key === 'container' || key === 'services') return containerContexts(keys);
+  if (JOB_KEYS.has(key)) return JOB;
+  return [];
+}
+
+/** Unlisted workflow keys admit no contexts; reusable workflow outputs alone may read jobs. */
+function allowedContexts(keys) {
+  if (keys[0] === 'jobs') return jobContexts(keys);
+  if (keys[0] === 'env') return [...WORKFLOW, 'secrets'];
+  if (keys[0] === 'run-name' || keys[0] === 'concurrency') return WORKFLOW;
+  if (keys.slice(0, 3).join('.') === 'on.workflow_call.inputs' && keys[4] === 'default') return WORKFLOW;
+  if (keys.slice(0, 3).join('.') === 'on.workflow_call.outputs' && keys[4] === 'value') return [...WORKFLOW, 'jobs'];
+  return [];
+}
+
+/** Strings and property names are not context roots; bracket access and case-insensitive roots still are. */
+function expressionContexts(expression) {
+  const unquoted = expression.replace(/'(?:[^']|'')*'/g, ' ');
+  const tokens = unquoted.match(/[A-Za-z_][\w-]*|[^\s]/g) ?? [];
+  const roots = tokens.filter((token, index) => tokens[index - 1] !== '.' &&
+    ([...CONTEXTS, 'jobs'].includes(token.toLowerCase()) || ['.', '['].includes(tokens[index + 1]))).map((token) => token.toLowerCase());
+  return [...new Set(roots)];
+}
+
+/** A closing delimiter inside an Actions single-quoted string cannot end an expression. */
+function expressionEnd(value, start) {
+  let quoted = false;
+  for (let index = start; index < value.length; index++) {
+    if (value[index] === "'") quoted = !quoted;
+    if (!quoted && value.slice(index, index + 2) === '}}') return index;
+  }
+  return value.length;
+}
+
+/** Read marked expressions without ambiguous regex repetition or losing delimiters inside string literals. */
+function expressions(value) {
+  const result = [];
+  const marker = /\$\{\{ __hfs_context_line_(\d+)__ /g;
+  let match;
+  while ((match = marker.exec(value)) !== null) {
+    const end = expressionEnd(value, marker.lastIndex);
+    result.push({ line: Number(match[1]), body: value.slice(marker.lastIndex, end) });
+    marker.lastIndex = end + 2;
+  }
+  return result;
+}
+
+/** Source markers travel inside parsed scalar expressions, preserving flow maps, quoted keys and repeated values without matching comments. */
+function workflowContextFindings({ path: file, text }) {
+  const marked = text.replace(/\$\{\{/g, (match, offset) => `${match} __hfs_context_line_${text.slice(0, offset).split('\n').length}__ `);
+  const findings = [];
+  function inspect(value, keys) {
+    const allowed = allowedContexts(keys);
+    for (const { line, body } of expressions(value)) {
+      for (const context of expressionContexts(body)) {
+        if (allowed.includes(context)) continue;
+        const keyPath = keys.join('.');
+        findings.push(found('HFS_WORKFLOW_CONTEXT', file, `HFS_WORKFLOW_CONTEXT: ${file}:${line}: ${keyPath} forbids context ${context}.`, { line, keyPath, context }));
+      }
+    }
+  }
+  function visit(value, keys = []) {
+    if (typeof value === 'string') inspect(value, keys);
+    if (!value || typeof value !== 'object') return;
+    for (const [key, member] of Object.entries(value)) visit(member, [...keys, key]);
+  }
+  visit(parseWorkflow(marked));
+  return findings;
+}
+
+/** Judge every tracked workflow in scope at the full or lite app root, using the shared workflow selector. */
+export function workflowContextsFindings(ctx) {
+  return appWorkflowFindings(ctx, workflowContextFindings, { dedupe: true });
+}

package/runtime/scripts/hfs/runtime-rules/workflow-source.mjs

@@ -4,8 +4,8 @@ import { parseYaml } from '../../../engine/yaml.mjs';
 
 const WORKFLOW = /(?:^|\/)\.?(?:github\/)?workflows\/[^/]+\.ya?ml$/;
 
-/** The tracked workflow files of the runtime, its examples and the hfs templates (never a spec fixture under tests/). */
-const workflowFiles = (files) => files.filter((file) => WORKFLOW.test(file) && !file.startsWith('tests/'));
+/** The tracked workflow files of the runtime, its examples and the hfs templates. */
+const workflowFiles = (files) => files.filter((file) => WORKFLOW.test(file));
 
 /** The parsed workflow, or null when the text is not YAML (the other checks name that). */
 export function parseWorkflow(text) {

package/runtime/scripts/hfs/slots.mjs

@@ -5,7 +5,7 @@
 //   is this path tracked             isTracked(P) / trackingOf(P); the rule catalog (knowledge/hfs/rules.yaml, modules/schemas/hfs-rules.schema.yaml) loads through loadRuleCatalog / rules().
 // Every check and lint rule of HFS reads knowledge/hfs/slots.yaml through this module; none keeps its own path
 // list. The manifest shape is modules/schemas/hfs-slots.schema.yaml and hfs.json is modules/schemas/hfs-repo.schema.yaml;
-// the installed runtime carries no npm dependency, so this file re-states those shapes instead of loading ajv (tests/hfs/hfs-slots.spec.mjs proves the two agree).
+// the installed runtime carries no npm dependency, so this file re-states those shapes instead of loading ajv.
 //
 // A product is ONE app repository: hfs.json at the app root has kind `app` and declares its two sides, `be` and `fe`, each in
 // the folder of that name. The resolver of the app answers for the whole tree: a root path with the slots of profile `app`,
@@ -41,7 +41,7 @@ export { HfsSlotsError } from './slot-errors.mjs';
 export { loadRuleCatalog };
 export { rules } from './rule-catalog.mjs';
 export { APP_SCOPE };
-export const HFS_MANIFEST_FILE = 'knowledge/hfs/slots.yaml';
+const HFS_MANIFEST_FILE = 'knowledge/hfs/slots.yaml';
 /** The manifest of kind runtime: the standard tree of the StarCi runtime repository (judged by scripts/hfs/runtime-check.mjs). */
 export const RUNTIME_MANIFEST_FILE = 'knowledge/hfs/runtime-slots.yaml';
 export const HFS_DECLARATION_FILE = 'hfs.json';

package/runtime/scripts/hfs/typescript-programs.mjs

@@ -9,14 +9,6 @@ import { byCodeUnit } from '../lib/list.mjs';
 // builds afresh.
 const runs = new AsyncLocalStorage();
 
-/** A program run: run(fn) shares what is built inside fn; release() drops it. */
-export function typeScriptProgramRun() {
-  const values = new Map();
-  return {
-    run: fn => runs.run(values, fn),
-    release: () => values.clear(),
-  };
-}
 
 function keyOf(value) {
   if (value === undefined) return 'u';

package/runtime/scripts/lib/env.mjs

@@ -11,8 +11,8 @@ export const isSpecRun = (env = process.env) => Boolean(env.NODE_TEST_CONTEXT);
 
 /**
  * The environment for a child that is itself a test runner: `env` without the mark of an enclosing spec run. A `node --test` that inherits NODE_TEST_CONTEXT believes it is a
- * subtest of that run: it reports to its parent and exits 0 whatever its tests did, so a verb that runs specs as a child (starci test affected, the land gate, the release cut, the
- * suite) would pass red specs from inside a test process. The runner marks the spec files it starts itself, so isSpecRun stays true inside them.
+ * subtest of that run: it reports to its parent and exits 0 whatever its tests did, so a verb that runs specs as a child (the package clean-test, the scaffold e2e, the release cut)
+ * would pass red specs from inside a test process. The runner marks the spec files it starts itself, so isSpecRun stays true inside them.
  */
 export function withoutTestRunner(env = process.env) {
   const { NODE_TEST_CONTEXT: _enclosing, ...rest } = env;

package/runtime/scripts/lib/git.mjs

@@ -12,7 +12,7 @@ export const unquoteDiffPath = (value) =>
 
 // git's repository-local variables (git rev-parse --local-env-vars). A hook or alias run in a linked worktree exports
 // GIT_DIR=<main>/.git/worktrees/<wt>; a spec inheriting it pointed every fixture git at the LIVE .claude repo and re-inited
-// it core.bare=true (2026-09-29, a6f60352c). tests/setup/isolated-registry.mjs drops the same list.
+// it core.bare=true (2026-09-29, a6f60352c). e2e/setup/isolated-registry.mjs drops the same list.
 export const GIT_LOCAL_ENV_VARS = ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_IMPLICIT_WORK_TREE', 'GIT_PREFIX', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG_COUNT', 'GIT_GRAFT_FILE', 'GIT_NO_REPLACE_OBJECTS', 'GIT_REPLACE_REF_BASE', 'GIT_SHALLOW_FILE', 'GIT_INTERNAL_SUPER_PREFIX'];
 /** `parent` (the caller's env) without git's repository-local variables (GIT_CONFIG_KEY_n/VALUE_n go with GIT_CONFIG_COUNT). Pure. */
 export function withoutGitLocalEnv(parent) {

package/runtime/scripts/lib/i18n.mjs

@@ -49,8 +49,6 @@ export function loadCatalog(root = skillRoot, { scope = 'runtime' } = {}) {
   return cache.get(key);
 }
 
-/** Forget the cached catalogs (a spec that rewrites a catalog file). */
-export const resetCatalogCache = () => cache.clear();
 
 /** The names each `pattern` match captures (group 1) in `text`, in match order (`sort` sorts them). */
 export const captureNames = (text, pattern, { sort = false } = {}) => {

package/runtime/scripts/lib/language.mjs

@@ -76,7 +76,7 @@ const I18N_CATALOG_DIR = 'modules/i18n/messages/';
 const OP_MANIFEST_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']) });
 const OP_MANIFEST_DIR = 'modules/ops/ops/';
 /** The declared Vietnamese fields of `rel`: its own entry, or the op-manifest text field for a manifest of modules/ops/ops. */
-export const declaredVietnameseFieldsOf = (rel) => DECLARED_VIETNAMESE_FIELDS[rel]
+const declaredVietnameseFieldsOf = (rel) => DECLARED_VIETNAMESE_FIELDS[rel]
   ?? (rel.startsWith(I18N_CATALOG_DIR) && !rel.slice(I18N_CATALOG_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? I18N_CATALOG_VIETNAMESE_FIELDS : null)
   ?? (rel.startsWith(OP_MANIFEST_DIR) && !rel.slice(OP_MANIFEST_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? OP_MANIFEST_VIETNAMESE_FIELDS : null);
 

package/runtime/scripts/lib/roots.mjs

@@ -17,16 +17,14 @@
 // directory or from the Work directory name outside this module.
 import fs from 'node:fs';
 import path from 'node:path';
-import { skillRoot, runtimeStateDir, starciLocalRoot, starciSourceRoot } from '../../engine/runtime-root.mjs';
+import { skillRoot, starciLocalRoot, starciSourceRoot } from '../../engine/runtime-root.mjs';
 import { tempRoot } from '../../engine/temp-root.mjs';
 
 export { tempRoot, starciLocalRoot, starciSourceRoot };
 
 /** The runtime tree this code runs from. */
-export const runtimeTree = skillRoot;
+const runtimeTree = skillRoot;
 
-/** The state directory of a runtime tree (default: this one). */
-export const runtimeState = (tree = runtimeTree) => runtimeStateDir(tree);
 
 /** The name of the Work records directory inside a product tree. */
 export const WORK_DIR_NAME = '.starciwork';

package/runtime/scripts/lib/secret-patterns.mjs

@@ -43,11 +43,11 @@ const SECRET_NAME = [
   String.raw`[A-Za-z_$][A-Za-z0-9_$.-]*\s*[:=]\s*`,
 ].join('');
 
-// `password = "hunter2hunter2"` — the quoted literal. `env(NAME)` is a reference, never a secret.
+// `password = "example-password-1"` — the quoted literal. `env(NAME)` is a reference, never a secret.
 const ASSIGNED_QUOTED = new RegExp(
   SECRET_NAME + String.raw`['"\`](?!env\([A-Z_][A-Z0-9_]*\)['"\`])([^'"\`\n\s$<{]{12,})['"\`]`,
 );
-// `DB_PASSWORD=hunter2hunter2` — the compose list-item and dotenv form; the dotenv value has no `:` so
+// `DB_PASSWORD=example-password-1` — the compose list-item and dotenv form; the dotenv value has no `:` so
 // `password: secret:db/password` and `token: ref:vault/api` stay references, and the end boundary keeps
 // calls and member/index references such as `secret = credentialsSource.current` out of the literals.
 const ASSIGNED_UNQUOTED = new RegExp(

package/scaffold/add-fe-overlay.mjs

@@ -1,122 +1 @@
-import { createRequire } from "node:module";
-import path from "node:path";
-import { ScaffoldError, pascalOf } from "./service.mjs";
-import { feName, readFeContext, readFeFile, requireNewFeOwner, planFeCatalogs, writeFePlan } from "./add-fe-page.mjs";
 
-function loadTypeScript(root) {
-  try { return createRequire(path.join(root, "package.json"))("typescript"); } catch {
-    throw new ScaffoldError("HFS_ADD_TYPESCRIPT_MISSING", "add overlay reads the host page with its installed TypeScript compiler");
-  }
-}
-
-function pageArrow(ts, source, symbol) {
-  for (const statement of source.statements) {
-    if (!ts.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
-    const candidate = statement.declarationList.declarations.find((declaration) => declaration.name.getText(source) === symbol);
-    if (candidate?.initializer && ts.isArrowFunction(candidate.initializer)) return candidate.initializer;
-  }
-  return null;
-}
-
-function pageRender(ts, arrow) {
-  if (!arrow) return null;
-  if (!ts.isBlock(arrow.body)) {
-    let body = arrow.body;
-    while (ts.isParenthesizedExpression(body)) body = body.expression;
-    return body;
-  }
-  const returns = arrow.body.statements.filter(ts.isReturnStatement);
-  const unconditional = arrow.body.statements.every((statement) => ts.isVariableStatement(statement) || ts.isExpressionStatement(statement) || ts.isReturnStatement(statement));
-  if (!unconditional || returns.length !== 1) return null;
-  let render = returns[0].expression;
-  while (render && ts.isParenthesizedExpression(render)) render = render.expression;
-  return render;
-}
-
-function mountOverlay({ ts, before, relative, pageSymbol, symbol }) {
-  const source = ts.createSourceFile(relative, before, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-  const client = source.statements.some((statement) => ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression) && statement.expression.text === "use client");
-  const render = pageRender(ts, pageArrow(ts, source, pageSymbol));
-  const isJsx = render && (ts.isJsxElement(render) || ts.isJsxSelfClosingElement(render) || ts.isJsxFragment(render));
-  if (source.parseDiagnostics.length || client || !isJsx) {
-    throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `${relative} must export the server ${pageSymbol} arrow with one unconditional JSX return`);
-  }
-  if (before.split(/[^A-Za-z0-9_]/).includes(symbol)) {
-    throw new ScaffoldError("HFS_ADD_EXISTS", `${relative} already references ${symbol}`);
-  }
-  const from = render.getStart(source);
-  const wrapped = ["(", "        <>", `            ${before.slice(from, render.end)}`, `            <${symbol} />`, "        </>", "    )"].join("\n");
-  const body = before.slice(0, from) + wrapped + before.slice(render.end);
-  const imports = source.statements.filter(ts.isImportDeclaration);
-  const last = imports.at(-1)?.end ?? 0;
-  const importLine = `import { ${symbol} } from "@/features/overlays/${symbol}"`;
-  return `${body.slice(0, last)}\n${importLine}${body.slice(last)}`;
-}
-
-function overlaySources(symbol, namespace) {
-  return {
-    entry: `"use client"
-
-import { useTranslations } from "next-intl"
-import { ${symbol}Base } from "./component"
-
-/** Resolve the overlay's copy at its client interaction boundary. */
-export const ${symbol} = () => {
-    const t = useTranslations(${JSON.stringify(namespace)})
-    return <${symbol}Base props={{ title: t("title"), open: t("open"), close: t("close"), description: t("description") }} />
-}
-`,
-    component: `import { Button, Dialog, Text } from "@starci/grammar/common"
-
-/** Settled labels and content for the overlay's accessible dialog. */
-export interface ${symbol}BaseProps {
-    readonly props: {
-        readonly title: string
-        readonly open: string
-        readonly close: string
-        readonly description: string
-    }
-}
-
-/** Draw an accessible dialog with an intrinsic trigger and dismissal. */
-export const ${symbol}Base = (props: ${symbol}BaseProps) => (
-    <Dialog
-        title={props.props.title}
-        closeLabel={props.props.close}
-        trigger={<Button>{props.props.open}</Button>}
-    >
-        <Text>{props.props.description}</Text>
-    </Dialog>
-)
-`,
-  };
-}
-
-/** Add a localized client overlay and mount its public entry in a server feature page. */
-export function addFeOverlay({ root, app, name, page, messages, ts }) {
-  feName(name, "overlay name");
-  if (page === undefined) throw new ScaffoldError("HFS_ADD_OPTION_MISSING", "add overlay needs --page naming its server feature page");
-  feName(page, "host page name");
-  const context = readFeContext({ root, app });
-  const symbol = `${pascalOf(name)}Overlay`;
-  const owner = `${context.source}/features/overlays/${symbol}`;
-  requireNewFeOwner(context, owner);
-  const pageSymbol = `${pascalOf(page)}Page`;
-  const relative = `${context.source}/features/pages/${pageSymbol}/index.tsx`;
-  const before = readFeFile(context, relative);
-  const body = mountOverlay({ ts: ts ?? loadTypeScript(context.root), before, relative, pageSymbol, symbol });
-  const catalogs = planFeCatalogs(context, {
-    group: "overlays", name, messages,
-    defaults: {
-      vi: { title: "Th\u00f4ng tin", open: "M\u1edf th\u00f4ng tin", close: "\u0110\u00f3ng", description: "Xem th\u00f4ng tin c\u1ee7a trang n\u00e0y." },
-      en: { title: "Information", open: "Open information", close: "Close", description: "View information about this page." },
-    },
-  });
-  const sources = overlaySources(symbol, catalogs.namespace);
-  const created = [
-    { relative: `${owner}/index.tsx`, body: sources.entry },
-    { relative: `${owner}/component.tsx`, body: sources.component },
-  ];
-  const updates = [...catalogs.updates, { relative, before, body }];
-  return { ...writeFePlan(context, created, updates), registered: { app: context.app, overlay: symbol, page: pageSymbol } };
-}