@starci/hfs 4.0.7 → 4.0.9

package/runtime/scripts/lib/package-at.mjs

@@ -1,13 +1,32 @@
 // scripts/lib/package-at.mjs — a package the runtime does not ship (playwright, esbuild, tailwindcss) comes from the
 // project that owns it: node resolution from that project's directory, walking up its node_modules.
+import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { skillRoot } from '../../engine/runtime-root.mjs';
 
 /** The package.json of `name` as resolved from `dir`, or null. */
 export const packageAt = (dir, name) => {
   try { return createRequire(path.join(dir, 'package.json')).resolve(`${name}/package.json`); } catch { return null; }
 };
 
+/** This runtime's own `starci` bin (packages/cli is the only package that declares one). */
+const RUNTIME_STARCI_BIN = path.join(skillRoot, 'packages', 'cli', 'bin', 'starci.mjs');
+
+/** The `starci` bin of the @starci/cli that `dir` installs (a product runs its own pinned CLI), else this runtime's own. */
+export function starciBin(dir) {
+  const packageFile = packageAt(dir, '@starci/cli');
+  if (packageFile) {
+    try {
+      const { bin } = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+      const rel = typeof bin === 'string' ? bin : bin?.starci;
+      const file = rel ? path.join(path.dirname(packageFile), rel) : null;
+      if (file && fs.existsSync(file)) return file;
+    } catch { /* an unreadable install falls back to the runtime's own CLI */ }
+  }
+  return RUNTIME_STARCI_BIN;
+}
+
 /** The first of `names` resolvable from the first of `dirs` that has one: {name, root, packageFile, version} or null. */
 export function findPackage(dirs, names) {
   for (const dir of dirs.filter(Boolean)) {
@@ -23,3 +42,21 @@ export function findPackage(dirs, names) {
 
 /** The CommonJS entry of a package found by findPackage. */
 export const requirePackage = (found) => createRequire(found.packageFile)(found.name);
+
+/** The TypeScript compiler resolvable from the first of `dirs` (an app root, then the caller's own), or null. */
+export const loadTypescript = (...dirs) => {
+  const located = findPackage(dirs, ['typescript']);
+  return located ? requirePackage(located) : null;
+};
+
+/**
+ * The app's command line and the app implementation behind it: `bin` the `starci` bin of the app's installed @starci/cli, else
+ * this runtime's packages/cli/bin/starci.mjs (starciBin); `dir` the @starci/hfs that answers
+ * `starci app` - the app's own install, else the one beside its @starci/cli, else this runtime's packages/hfs - whose runtime
+ * slice the gate's base lint (scripts/gates/gate.mjs) and the READ digest (scripts/gates/read-digest.mjs) load in-process.
+ */
+export function hfsEntry(root) {
+  const cli = packageAt(root, '@starci/cli');
+  const manifest = packageAt(root, '@starci/hfs') ?? (cli && packageAt(path.dirname(cli), '@starci/hfs'));
+  return { dir: manifest ? path.dirname(manifest) : path.join(skillRoot, 'packages', 'hfs'), bin: starciBin(root) };
+}

package/runtime/scripts/lib/path-key.mjs

@@ -1,4 +1,5 @@
 // path-key.mjs — spelling and comparing paths the way this host's filesystem does.
+import fs from 'node:fs';
 import path from 'node:path';
 
 const WIN = process.platform === 'win32';
@@ -13,5 +14,61 @@ export const sameOrUnder = (file, prefix) => file === prefix || file.startsWith(
 export const foldCase = (p) => (WIN ? p.toLowerCase() : p);
 /** Whether two spellings name the same path on this host's filesystem. */
 export const samePath = (a, b) => foldCase(a) === foldCase(b);
-/** A path's comparable identity: absolute, forward slashes, no trailing slash, case-folded on Windows. */
-export const pathKey = (p) => foldCase(slash(path.resolve(p)).replace(/\/+$/, ''));
+/**
+ * A path's comparable identity: absolute, forward slashes, no trailing slash, case-folded on Windows.
+ * `fold: true` folds case on every platform (a comparison against a lowercase-stored root needs it).
+ */
+export const pathKey = (p, { fold = WIN } = {}) => {
+  const key = slash(path.resolve(p)).replace(/\/+$/, '');
+  return fold ? key.toLowerCase() : key;
+};
+/** `a` is `b` or under it, or the reverse: two path spellings whose trees touch. */
+export const pathsOverlap = (a, b) => sameOrUnder(a, b) || sameOrUnder(b, a);
+/**
+ * A path-ish string in compare form, options in spelling order:
+ * `trim` blanks at the ends, `collapse` folds '//' runs to '/', `dot` drops a leading './',
+ * `glob` strips a trailing glob ('star': '*'/'**' with their slash, 'double': a '/**' only),
+ * `fold` lowercases. A trailing '/' always goes. Null reads as ''.
+ */
+export const normPath = (p, { trim = false, collapse = false, dot = false, glob = null, fold = false } = {}) => {
+  let s = String(p ?? '');
+  if (trim) s = s.trim();
+  s = slash(s);
+  if (collapse) s = s.replace(/\/{2,}/g, '/');
+  if (dot) s = s.replace(/^\.\//, '');
+  if (glob === 'star') s = s.replace(/\/?\*+$/, '');
+  else if (glob === 'double') s = s.replace(/\/\*\*$/, '');
+  s = s.replace(/\/+$/, '');
+  return fold ? s.toLowerCase() : s;
+};
+/** A work-relative path in one spelling: forward slashes, no leading ./, no trailing slash. */
+export const normWork = (p) => String(p ?? '').trim().replaceAll('\\', '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+
+/** `p` resolved and dereferenced (realpath where the path exists) — the canonical spelling of a checkout dir. */
+export const realPath = (p) => {
+  const resolved = path.resolve(p);
+  try { return fs.realpathSync.native(resolved); } catch { return resolved; }
+};
+/** `p` resolved and case-folded where the filesystem ignores case — the Map key of an absolute path. */
+export const resolvedKey = (p) => foldCase(path.resolve(p));
+/** Whether `a` and `b` resolve to the same path (always case-folded, so differently-cased spellings count). */
+export const sameResolvedPath = (a, b) => pathKey(a, { fold: true }) === pathKey(b, { fold: true });
+/**
+ * Whether `file` sits strictly under `root`. `key` normalizes both sides first (e.g. the registry's
+ * realpath-folded treeKey) when the callers' spellings need it.
+ */
+export const insidePath = (root, file, { key = (p) => p } = {}) => {
+  const rel = path.relative(key(root), key(file));
+  return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+/**
+ * A path-ish value (a string or a {path} entry) in relative compare form: trimmed, forward slashes,
+ * no trailing '/**' glob or slashes, no leading './'; `fold` lowercases for a case-insensitive key.
+ */
+export const normRel = (p, { fold = false } = {}) => {
+  const s = String(typeof p === 'string' ? p : p?.path ?? '').trim().replace(/\\/g, '/').replace(/\/\*\*$/, '').replace(/\/+$/, '').replace(/^\.\//, '');
+  return fold ? s.toLowerCase() : s;
+};
+/** Whether `file` equals or sits under one of `prefixes` (posix spellings; `dot` counts a '.' prefix as covering all). */
+export const underAny = (file, prefixes, { dot = false } = {}) =>
+  (prefixes ?? []).some((p) => (dot && p === '.') || sameOrUnder(file, p));

package/runtime/scripts/lib/read-text.mjs

@@ -0,0 +1,34 @@
+// read-text.mjs — the forgiving text read: a missing or unreadable file is the caller's fallback,
+// never a throw (the JSON twin is ./json.mjs readJsonFile, the YAML twin ./read-yaml.mjs).
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The text of `rel` under `root` ('/'-separated rel), or null when it is missing or unreadable. */
+export const readTextFile = (root, rel) => {
+  try { return fs.readFileSync(path.join(root, ...String(rel).split('/')), 'utf8'); } catch { return null; }
+};
+
+/** `file` read and parsed by `parse`, or `fallback` when it is missing, unreadable or malformed. */
+export const readParsedFile = (file, parse, fallback = null) => {
+  try { return parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+};
+
+/**
+ * Feed `file`'s lines to `onLine` reading in bounded chunks — a diff or a patch can exceed any single
+ * string. `eol` is the line-ending pattern or literal (default CRLF-aware); a last unterminated line is fed too.
+ */
+export function forEachFileLine(file, onLine, { chunkBytes = 8 * 1024 * 1024, eol = /\r?\n/ } = {}) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(chunkBytes);
+    let carry = '';
+    for (;;) {
+      const n = fs.readSync(fd, buf, 0, chunkBytes, null);
+      if (n <= 0) break;
+      const lines = (carry + buf.toString('utf8', 0, n)).split(eol);
+      carry = lines.pop();
+      for (const l of lines) onLine(l);
+    }
+    if (carry) onLine(carry);
+  } finally { fs.closeSync(fd); }
+}

package/runtime/scripts/lib/regex.mjs

@@ -0,0 +1,4 @@
+// regex.mjs - building a RegExp from text.
+
+/** `text` with every regular-expression metacharacter escaped, so it matches itself literally. */
+export const escapeRegExp = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/runtime/scripts/lib/same-text.mjs

@@ -0,0 +1,5 @@
+// same-text.mjs - text equality that ignores the line-ending form and a trailing blank tail (a git runner may trim stdout, a work tree may
+// carry CRLF): the one comparison the database rules use for a committed file against its base or against a regenerated one.
+
+/** True when both texts exist and are equal once CRLF is folded to LF and trailing whitespace at the end is dropped. */
+export const sameText = (a, b) => a !== null && b !== null && a.replace(/\r\n/g, '\n').trimEnd() === b.replace(/\r\n/g, '\n').trimEnd();

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

@@ -23,11 +23,12 @@ export const SECRET_PATTERNS = [
   { name: 'telegram-bot-token', re: /\b\d{8,10}:AA[0-9A-Za-z_-]{33}\b/ },
   { name: 'stripe-secret', re: /\b(?:sk|rk)_live_[0-9A-Za-z]{20,}\b/ },
   { name: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+  // A value written `env(NAME)` (the Supabase config.toml reference form) names a variable, not a secret.
   // A keyword-assigned value that names itself a stand-in (a test stub's `accessToken: "fixture-..."`) is no
   // candidate; only this heuristic takes the exemption, never a provider-shaped token above.
-  // A spec file's keyword-assigned values are test inputs (nivo-fe AuthenticationPage/index.spec.tsx: the sign-in
-  // form's password and a mocked accessToken refused the push, 2026-09-24): the heuristic skips spec files too.
-  { name: 'assigned-secret', re: /\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|client[_-]?secret)\b\s*[:=]\s*['"]([^'"\s$<{]{12,})['"]/i, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+  // A spec file's keyword-assigned values are test inputs (a spec's sign-in
+  // form password and a mocked accessToken once refused a push): the heuristic skips spec files too.
+  { name: 'assigned-secret', re: /\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|client[_-]?secret)\b\s*[:=]\s*['"](?!env\([A-Z_][A-Z0-9_]*\)['"])([^'"\s$<{]{12,})['"]/i, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
     skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$/ },
 ];
 

package/runtime/scripts/lib/sleep-sync.mjs

@@ -6,8 +6,9 @@
  * waiting, counted logically by their callers, not by the wall clock) cost milliseconds and the run no longer
  * depends on machine load. Unset in production.
  */
+import { readEnv } from './env.mjs';
 const scaleOf = () => {
-  const raw = process.env.STARCI_SLEEP_SCALE;
+  const raw = readEnv('STARCI_SLEEP_SCALE');
   if (raw === undefined || raw === '') return 1;
   const value = Number(raw);
   return Number.isFinite(value) && value >= 0 ? value : 1;

package/runtime/scripts/lib/sops-envelope.mjs

@@ -0,0 +1,58 @@
+// sops-envelope.mjs — the pure rules of a test credential (owner ruling push-scan-test-secrets-encrypted, 2026-09-28):
+// where it lives in a product repository's `.starcistacks`, the command that stores it, the sops format of its path, and
+// whether a committed file is a sops envelope with no plaintext value (the push secret scan's test). Reading one is
+// scripts/uat/test-secret.mjs; the sops binary is found by scripts/api/sops/lib.mjs.
+import path from 'node:path';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const STACK = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/** One sops-encrypted leaf: `ENC[AES256_GCM,data:...,iv:...,tag:...,type:...]` (data may be empty). */
+const SOPS_VALUE = /^ENC\[AES256_GCM,data:[A-Za-z0-9+/=]*,iv:[A-Za-z0-9+/=]+,tag:[A-Za-z0-9+/=]+,type:[a-z]+\]$/;
+
+/** Where test credential `name` of `stack` lives in `repo`: {plain, enc, rel}. `rel` is the path the repo's
+ *  `stack-secret.mjs set` takes. */
+export function testSecretPaths(name, { repo, stack = 'dev' } = {}) {
+  if (!NAME.test(String(name ?? ''))) throw new Error(`test secret name must match ${NAME} (got ${JSON.stringify(name)})`);
+  if (!STACK.test(String(stack ?? ''))) throw new Error(`stack must match ${STACK} (got ${JSON.stringify(stack)})`);
+  if (!repo) throw new Error('test secret needs {repo}: the product repository whose .starcistacks holds it');
+  const rel = `${stack}/secrets/test/${name}`;
+  const plain = path.join(path.resolve(String(repo)), '.starcistacks', stack, 'secrets', 'test', name);
+  return { plain, enc: `${plain}.enc`, rel };
+}
+
+/** The command that stores a test credential, in the product repository's own tooling. */
+export const setCommand = (name = '<name>', stack = 'dev') => `node scripts/stack-secret.mjs set ${stack}/secrets/test/${name}`;
+
+/** sops' format for a plaintext path, as the repository's stack-secret.mjs formatFor decides it. */
+export const sopsFormatFor = (file) => (file.endsWith('.env') ? 'dotenv' : /\.json$/.test(file) ? 'json' : /\.(ya?ml|kubeconfig)$/.test(file) ? 'yaml' : 'binary');
+
+/** Every leaf outside the `sops` block is an ENC[...] value (or null); the block itself carries a mac. */
+const allEncrypted = (node) => {
+  if (node === null) return true;
+  if (Array.isArray(node)) return node.every(allEncrypted);
+  if (typeof node === 'object') return Object.values(node).every(allEncrypted);
+  return typeof node === 'string' && SOPS_VALUE.test(node);
+};
+const sopsTree = (doc) => !!doc && typeof doc === 'object' && !Array.isArray(doc) && !!doc.sops && typeof doc.sops === 'object'
+  && typeof doc.sops.mac === 'string' && SOPS_VALUE.test(doc.sops.mac)
+  && Object.keys(doc).length > 1 && Object.entries(doc).every(([k, v]) => k === 'sops' || allEncrypted(v));
+
+/**
+ * True only for a sops-encrypted file with no plaintext value: binary/json form ({"data": ENC[...], "sops": {...}}),
+ * yaml form (every value ENC[...] plus the sops block) or dotenv form (KEY=ENC[...] lines plus sops_* metadata).
+ * The sops metadata must carry its mac. A key kept plaintext through `unencrypted_suffix` does not pass.
+ */
+export function isSopsEnvelope(text) {
+  const src = String(text ?? '').replace(/^/, '');
+  if (!src.trim()) return false;
+  try { return sopsTree(JSON.parse(src)); } catch { /* not JSON */ }
+  const lines = src.split(/\r?\n/).filter((l) => l.trim() && !/^\s*#/.test(l));
+  if (lines.length && lines.every((l) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(l))) {
+    const pairs = lines.map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)]);
+    const meta = pairs.filter(([k]) => k.startsWith('sops_'));
+    const vals = pairs.filter(([k]) => !k.startsWith('sops_'));
+    return vals.length > 0 && vals.every(([, v]) => SOPS_VALUE.test(v)) && meta.some(([k, v]) => k === 'sops_mac' && SOPS_VALUE.test(v));
+  }
+  try { return sopsTree(parseYaml(src)); } catch { return false; }
+}

package/runtime/scripts/lib/stack-declaration.mjs

@@ -1,6 +1,6 @@
 // stack-declaration.mjs - the one reader of a repository's stack declaration (.starcistacks/application-stacks.yaml): where it
-// lives, its bounded read and parse, and the stack block of one service as declared. scripts/checks/check-starcistacks.mjs (the
-// services contract) and scripts/lib/hfs-rules/stacks.mjs (the .starcistacks shape, R10) both read it here; this file imports
+// lives, its bounded read and parse, and the stack block of one service as declared. scripts/gates/starcistacks.mjs (the
+// services contract) and scripts/hfs/rules/stacks.mjs (the .starcistacks shape, R10) both read it here; this file imports
 // nothing of the kernel, so the published @starci/hfs bundle carries it without the ledger.
 import fs from 'node:fs';
 import path from 'node:path';

package/runtime/scripts/lib/stack-services.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml } from '../../engine/yaml.mjs';
+import { words } from './dockerfile.mjs';
 
 /**
  * The services of a repository's own stack definition, read from `.starcistacks/application-stacks.yaml` and the compose
@@ -14,11 +15,11 @@ import { parseYaml } from '../../engine/yaml.mjs';
  * service and is returned as `proxy`.
  */
 export const STACKS_DIRECTORY = '.starcistacks';
-export const STACKS_FILE = 'application-stacks.yaml';
+const STACKS_FILE = 'application-stacks.yaml';
 export const DEFAULT_ENVIRONMENT = 'dev';
 
 /** Test-only value the `*_FILE` secret variables of a compose service become (the file variable is replaced by the plain variable of the same name). Never a real secret: the test stack listens on loopback only. */
-export const TEST_SECRET_VALUE = 'starci-test-secret';
+const TEST_SECRET_VALUE = 'starci-test-secret';
 
 const NOT_RUN_ROLES = new Set(['service', 'observability']);
 const NOT_RUN_PROFILES = new Set(['app']);
@@ -44,8 +45,6 @@ const KNOWN_IMAGES = Object.freeze({
   clickhouse: { kind: 'database', aliases: ['clickhouse', 'database', 'db'], probe: { tcp: true } },
   kafka: { kind: 'queue', aliases: ['kafka', 'queue', 'broker'], probe: { tcp: true } },
   redpanda: { kind: 'queue', aliases: ['redpanda', 'kafka', 'queue', 'broker'], probe: { tcp: true } },
-  rabbitmq: { kind: 'queue', aliases: ['rabbitmq', 'amqp', 'queue', 'broker'], probe: { tcp: true } },
-  nats: { kind: 'queue', aliases: ['nats', 'queue', 'broker'], probe: { tcp: true } },
   elasticsearch: { kind: 'search', aliases: ['elasticsearch', 'elastic', 'search'], probe: { tcp: true } },
   opensearch: { kind: 'search', aliases: ['opensearch', 'search'], probe: { tcp: true } },
 });
@@ -58,14 +57,14 @@ const KNOWN_IMAGES = Object.freeze({
 export const STATEFUL_KINDS = Object.freeze(new Set(['database', 'cache', 'identity', 'storage', 'mail', 'queue', 'search']));
 
 /** The repository name of an image reference: `quay.io/keycloak/keycloak:26.0` -> `keycloak`. */
-export const repositoryOf = image => {
+const repositoryOf = image => {
   const withoutDigest = image.split('@')[0];
   const lastSegment = withoutDigest.split('/').at(-1) ?? withoutDigest;
   return lastSegment.split(':')[0];
 };
 
 /** The repository path of an image reference without its tag: `quay.io/keycloak/keycloak:26.0` -> `quay.io/keycloak/keycloak`. */
-export const imagePathOf = image => {
+const imagePathOf = image => {
   const withoutDigest = image.split('@')[0];
   const lastSlash = withoutDigest.lastIndexOf('/');
   const colon = withoutDigest.indexOf(':', lastSlash + 1);
@@ -73,30 +72,7 @@ export const imagePathOf = image => {
 };
 
 /** True when the image reference carries a tag or digest (an external image, not a placeholder of the repository's own build). */
-export const isTagged = image => image.includes('@') || image.slice(image.lastIndexOf('/') + 1).includes(':');
-
-/** The shell-like words of a compose `command` string, double and single quotes grouping a word. */
-const words = text => {
-  const out = [];
-  let current = '';
-  let quote = null;
-  let started = false;
-  for (const char of text) {
-    if (quote) {
-      if (char === quote) quote = null;
-      else current += char;
-    } else if (char === '"' || char === "'") {
-      quote = char;
-      started = true;
-    } else if (/\s/u.test(char)) {
-      if (started || current) out.push(current);
-      current = '';
-      started = false;
-    } else current += char;
-  }
-  if (started || current) out.push(current);
-  return out;
-};
+const isTagged = image => image.includes('@') || image.slice(image.lastIndexOf('/') + 1).includes(':');
 
 const asList = value => (Array.isArray(value) ? value : value === undefined || value === null ? [] : [value]);
 
@@ -129,7 +105,7 @@ const mountsOf = (value, directory) => {
       continue;
     }
     const parts = String(entry).split(':');
-    // A Windows drive letter is not a separator: `C:\x:/y` keeps its drive.
+    // A Windows drive letter is not a separator: a `<drive>:<path>:/y` mount keeps its drive.
     const source = /^[A-Za-z]$/u.test(parts[0]) && parts.length > 2 ? `${parts.shift()}:${parts.shift()}` : parts.shift();
     const target = parts.shift();
     if (!source || !target || !(source.startsWith('.') || path.isAbsolute(source))) continue;

package/runtime/scripts/lib/ts-ast.mjs

@@ -0,0 +1,35 @@
+// ts-ast.mjs — the small reads the hfs checks share over TypeScript's own AST: a node's name or
+// literal text, a node's 1-based position, a named property's initializer text. `ts` is the caller's
+// already-resolved compiler (see package-at.mjs loadTypescript); nothing here resolves a package.
+
+/** The text of an identifier or a string-literal-like `node`, or null (property names, literal specifiers). */
+export const nameText = (ts, node) => (node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : null);
+
+/** The text of a string-literal-like `node` (a string literal or a no-substitution template), or null. */
+export const literalText = (ts, node) => (node && ts.isStringLiteralLike(node) ? node.text : null);
+
+/** The 1-based {line, column} of `node` in `sourceFile`. */
+export const sourceLocation = (sourceFile, node) => {
+  const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { line: position.line + 1, column: position.character + 1 };
+};
+
+/**
+ * The `.text` of `key`'s property initializer in `text` (parsed as `file`): a property assignment
+ * inside an object literal, or — `declaration: true` — a class property declaration. `kind` is
+ * 'string' (a string-literal-like initializer) or 'identifier'. The last match wins; null when none.
+ */
+export function propertyText(ts, text, { file = 'source.ts', key, declaration = false, kind = 'string' } = {}) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  let value = null;
+  const visit = (node) => {
+    const isProp = declaration ? ts.isPropertyDeclaration(node) : ts.isPropertyAssignment(node);
+    if (isProp && node.name && ts.isIdentifier(node.name) && node.name.text === key && node.initializer) {
+      const ok = kind === 'identifier' ? ts.isIdentifier(node.initializer) : ts.isStringLiteralLike(node.initializer);
+      if (ok) value = node.initializer.text;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return value;
+}

package/runtime/scripts/{checks/common.mjs → lib/walk.mjs}

@@ -1,23 +1,13 @@
+// walk.mjs - filesystem walking helpers: isInside (containment) and walkFiles (depth-first file listing).
 import fs from 'node:fs';
 import path from 'node:path';
-import {fileURLToPath} from 'node:url';
 
-/** Whether `target` is `root` itself or inside it (filesystem paths, either separator). */
-export function isInside(root, target) {
+/** Whether `target` is `root` itself or inside it (filesystem paths, either separator). `includeSelf: false` excludes `target === root`. */
+export function isInside(root, target, { includeSelf = true } = {}) {
   const relative = path.relative(root, target);
-  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+  if (relative === '') return includeSelf;
+  return !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative);
 }
-
-/** True when this module is the process entry point (`node file.mjs`, not an import). */
-/** The real path of a file, or its resolved path when it cannot be read (a missing file is never the entry module). */
-const realPathOf = (file) => { try { return fs.realpathSync.native(path.resolve(file)); } catch { return path.resolve(file); } };
-/**
- * True when the module at `metaUrl` is the process entry point. Both sides are compared as REAL paths: Node gives a module
- * its symlink-resolved URL, while argv[1] keeps the path it was started with, so an entry reached through a node_modules
- * junction or symlink (a lane worktree, an npx shim) would otherwise look like an import and silently do nothing.
- */
-export const isMain = (metaUrl, argv = process.argv) => Boolean(argv[1]) && realPathOf(argv[1]) === realPathOf(fileURLToPath(metaUrl));
-
 /**
  * Every entry under `dir` that is not a directory, depth-first; `filter` sees the entry name and full
  * path. `sorted` sorts each directory's entries by name (default: readdir order). `exclude`

package/scaffold/add-app.mjs

@@ -0,0 +1,174 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  loadSlotManifest,
+  readRepoDeclaration,
+  resolveRepoDeclaration,
+} from "../runtime/scripts/hfs/slots.mjs";
+import { imageFiles, TEMPLATES_DIR } from "../sync/index.mjs";
+import { ScaffoldError, pascalOf } from "./service.mjs";
+import { jsonText, packageJsonText } from "./app.mjs";
+
+const NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+const listFiles = (dir, base = dir) =>
+  fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(dir, entry.name);
+    return entry.isDirectory()
+      ? listFiles(full, base)
+      : [path.relative(base, full).split(path.sep).join("/")];
+  });
+
+const fill = (text, values, file) =>
+  text.replace(/\{\{(project|app|appPascal)\}\}/g, (whole, key) => {
+    if (values[key] === undefined)
+      throw new ScaffoldError(
+        "HFS_ADD_PLACEHOLDER_UNKNOWN",
+        `app template ${file} uses ${whole}, which add app does not provide`,
+      );
+    return values[key];
+  });
+
+/**
+ * Adds one Next workspace from the edition's canonical app skeleton, then registers it in hfs.json.
+ * The root workspace glob is added only when an older app manifest does not already carry it.
+ */
+export function addApp({ root, name }) {
+  if (!NAME.test(String(name)))
+    throw new ScaffoldError(
+      "HFS_ADD_NAME_INVALID",
+      `app name ${name} must be kebab-case (letters, digits and single dashes)`,
+    );
+  const declarationFile = path.join(root, "hfs.json");
+  const packageFile = path.join(root, "package.json");
+  if (!fs.existsSync(declarationFile) || !fs.existsSync(packageFile))
+    throw new ScaffoldError(
+      "HFS_ADD_NOT_AN_APP",
+      "add app runs at the app root containing hfs.json and package.json",
+    );
+  const manifest = loadSlotManifest();
+  const repo = readRepoDeclaration(manifest, root);
+  if (!repo.sides?.fe)
+    throw new ScaffoldError(
+      "HFS_ADD_NO_FRONT_END",
+      "this app has no front-end side",
+    );
+  if (repo.edition === "lite")
+    throw new ScaffoldError(
+      "HFS_ADD_LITE_SINGLE_APP",
+      "a lite app has one front-end app; a second app needs the shared <project>-ui and <project>-i18n packages: run starci app upgrade --edition full",
+    );
+  if (repo.sides.fe.apps.some((app) => app.name === name))
+    throw new ScaffoldError(
+      "HFS_ADD_EXISTS",
+      `front-end app ${name} is already declared`,
+    );
+
+  const source = path.join(
+    TEMPLATES_DIR,
+    "fe",
+    repo.edition === "lite" ? "skeleton-lite/apps/web" : "skeleton/apps/app",
+  );
+  if (!fs.existsSync(source))
+    throw new ScaffoldError(
+      "HFS_ADD_TEMPLATE_MISSING",
+      `the ${repo.edition} Next app skeleton is not carried by this package`,
+    );
+  const values = {
+    project: repo.project,
+    app: name,
+    appPascal: pascalOf(name),
+  };
+  const targetBase = `fe/apps/${name}`;
+  const planned = listFiles(source).map((relative) => ({
+    relative: `${targetBase}/${relative}`,
+    body: fill(
+      fs
+        .readFileSync(path.join(source, ...relative.split("/")), "utf8")
+        .replace(/\r\n/g, "\n"),
+      values,
+      relative,
+    ),
+  }));
+
+  const firstApp = repo.sides.fe.apps.find((app) => app.kind === "next");
+  const firstPackage = firstApp
+    ? path.join(root, "fe", "apps", firstApp.name, "package.json")
+    : null;
+  if (!firstPackage || !fs.existsSync(firstPackage))
+    throw new ScaffoldError(
+      "HFS_ADD_APP_PACKAGE_SOURCE",
+      "add app needs the package.json of an existing declared Next app as the edition-matched dependency source",
+    );
+  const workspacePackage = JSON.parse(fs.readFileSync(firstPackage, "utf8"));
+  workspacePackage.name = `@${repo.project}/${name}`;
+  const appTemplates = path.join(TEMPLATES_DIR, "fe", "app");
+  planned.push(
+    {
+      relative: `${targetBase}/package.json`,
+      body:
+        fs
+          .readFileSync(path.join(appTemplates, "package.json.tpl"), "utf8")
+          .replace("{{packageJson}}", packageJsonText(workspacePackage).trimEnd()),
+    },
+    {
+      relative: `${targetBase}/tsconfig.json`,
+      body: fs.readFileSync(path.join(appTemplates, "tsconfig.json"), "utf8"),
+    },
+  );
+  const declaration = JSON.parse(fs.readFileSync(declarationFile, "utf8"));
+  declaration.sides.fe.apps.push({ name, kind: "next" });
+  if (repo.edition === "full") {
+    const image = imageFiles(
+      resolveRepoDeclaration(manifest, declaration),
+    ).find((file) => file.path === `${targetBase}/Dockerfile`);
+    if (!image)
+      throw new ScaffoldError(
+        "HFS_ADD_TEMPLATE_MISSING",
+        `the Dockerfile of front-end app ${name} did not render`,
+      );
+    planned.push({ relative: image.path, body: image.content });
+  }
+
+  const clashes = planned
+    .filter((file) =>
+      fs.existsSync(path.join(root, ...file.relative.split("/"))),
+    )
+    .map((file) => file.relative);
+  if (clashes.length)
+    throw new ScaffoldError(
+      "HFS_ADD_EXISTS",
+      `front-end app ${name} already exists: ${clashes.join(", ")}`,
+    );
+
+  const rootPackage = JSON.parse(fs.readFileSync(packageFile, "utf8"));
+  const oldDeclaration = fs.readFileSync(declarationFile, "utf8");
+  const oldPackage = fs.readFileSync(packageFile, "utf8");
+  rootPackage.workspaces = [
+    ...new Set([...(rootPackage.workspaces ?? []), "fe/apps/*"]),
+  ];
+  const created = [];
+  try {
+    for (const file of planned) {
+      const target = path.join(root, ...file.relative.split("/"));
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, file.body);
+      created.push(target);
+    }
+    fs.writeFileSync(declarationFile, jsonText(declaration));
+    fs.writeFileSync(packageFile, packageJsonText(rootPackage));
+  } catch (error) {
+    for (const file of [...created].reverse())
+      if (fs.existsSync(file)) fs.rmSync(file);
+    const appDir = path.join(root, "fe", "apps", name);
+    if (fs.existsSync(appDir))
+      fs.rmSync(appDir, { recursive: true, force: true });
+    fs.writeFileSync(declarationFile, oldDeclaration);
+    fs.writeFileSync(packageFile, oldPackage);
+    throw error;
+  }
+  return {
+    created: planned.map((file) => file.relative),
+    registered: { app: name, workspace: "fe/apps/*" },
+  };
+}