@starci/hfs 4.2.17 → 4.4.0

package/runtime/packages/cli/src/validate-args.mjs

@@ -0,0 +1,213 @@
+const optionName = (token) => token.slice(2).split('=', 1)[0];
+
+// A value may start with a single dash; one that is `--` or names a known flag is a missing value (use --flag=value).
+const looksLikeFlag = (token, known) => token === '--' || (token.startsWith('--') && known.has(optionName(token)));
+
+const optionValue = (argv, index, flag, known) => {
+  const token = argv[index];
+  const equals = token.indexOf('=');
+  if (equals >= 0) return { value: token.slice(equals + 1), consumed: 0 };
+  if (flag.type === 'boolean') return { value: true, consumed: 0 };
+  if (index + 1 >= argv.length || looksLikeFlag(argv[index + 1], known)) {
+    throw new Error(`--${flag.name} needs a value (use --${flag.name}=<value> for a value that looks like an option)`);
+  }
+  return { value: argv[index + 1], consumed: 1 };
+};
+
+const typedValue = (flag, raw) => {
+  if (flag.type === 'boolean') {
+    if (raw === true || raw === 'true') return true;
+    if (raw === 'false') return false;
+    throw new Error(`--${flag.name} expects true or false`);
+  }
+  if (flag.type === 'number') {
+    const value = String(raw).trim() === '' ? Number.NaN : Number(raw);
+    if (!Number.isFinite(value)) throw new Error(`--${flag.name} expects a number`);
+    return value;
+  }
+  if (flag.type === 'enum' && !flag.enum?.includes(raw)) {
+    throw new Error(`--${flag.name} expects one of: ${(flag.enum ?? []).join(', ')}`);
+  }
+  return raw;
+};
+
+/** The values a list flag takes after its first one when the verb has no positional slot: every following token that is no option (`--knowledge a b c`), as the contracts write it. */
+const listTail = (argv, index, flag, verb) => {
+  if (flag.type !== 'list' || (verb.positional ?? []).length > 0) return [];
+  const tail = [];
+  while (index + 2 + tail.length < argv.length && !argv[index + 2 + tail.length].startsWith('-')) tail.push(argv[index + 2 + tail.length]);
+  return tail;
+};
+
+/** One `--name[=value]` token: type-check it into values/global, or pass it through to localArgs. */
+const applyOption = (argv, index, token, { known, internal, values, global, localArgs, verb }) => {
+  const name = optionName(token);
+  const flag = known.get(name);
+  if (!flag) throw new Error(internal.has(name) ? `unknown option --${name}: it is a call of the runtime itself, not a CLI option; ${internal.get(name)}` : `unknown option --${name}`);
+  const { value: raw, consumed } = optionValue(argv, index, flag, known);
+  const value = typedValue(flag, raw);
+  const tail = consumed ? listTail(argv, index, flag, verb) : [];
+  if (flag.type === 'list') {
+    values[name] = [...(values[name] ?? []), value, ...tail];
+  } else if (Object.hasOwn(values, name)) {
+    throw new Error(`--${name} may be given only once`);
+  } else {
+    values[name] = value;
+  }
+  if (flag.global) { global[name] = values[name]; }
+  else {
+    localArgs.push(token);
+    if (consumed) localArgs.push(argv[index + consumed]);
+    // each further value of a list flag reaches the handler as a repeated option, the form every list-flag handler parses
+    for (const extra of tail) localArgs.push(token, extra);
+  }
+  return consumed + tail.length;
+};
+
+/** Every required local option must have been given. */
+const requiredCheck = (locals, values) => {
+  for (const flag of locals.values()) {
+    if (flag.required && !Object.hasOwn(values, flag.name)) throw new Error(`missing required option --${flag.name}`);
+  }
+};
+
+/** The values one positional slot holds: a variadic slot's list, a single value, or none. */
+const candidatesOf = (supplied) => {
+  if (Array.isArray(supplied)) return supplied;
+  return supplied === undefined ? [] : [supplied];
+};
+
+/** A slot with an enum accepts only its members. */
+const checkEnum = (schema, candidates) => {
+  for (const candidate of candidates) {
+    if (schema.enum && !schema.enum.includes(candidate)) throw new Error(`${schema.name} expects one of: ${schema.enum.join(', ')}`);
+  }
+};
+
+/** Positional arity and enum checks; passthrough tokens fill free slots first. */
+const checkPositionals = (verb, positionals, passthrough) => {
+  const positionalSchema = verb.positional ?? [];
+  const variadicAt = positionalSchema.findIndex((entry) => entry.variadic === true);
+  const maximum = variadicAt >= 0 ? Infinity : positionalSchema.length;
+  if (positionals.length > maximum) throw new Error(`too many positional arguments for ${verb.verb ?? 'command'}`);
+  positionals.push(...passthrough.slice(0, Math.max(0, maximum - positionals.length)));
+  for (const [index, schema] of positionalSchema.entries()) {
+    const supplied = variadicAt === index ? positionals.slice(index) : positionals[index];
+    const empty = Array.isArray(supplied) ? supplied.length === 0 : supplied === undefined;
+    if (schema.required && empty) throw new Error(`missing required positional ${schema.name}`);
+    checkEnum(schema, candidatesOf(supplied));
+  }
+};
+
+/** Edition availability, --cwd emptiness and --json support. */
+const checkGlobals = (verb, global) => {
+  if (global.edition !== undefined && Array.isArray(verb.editions) && !verb.editions.includes(global.edition)) {
+    throw new Error(`${verb.group ?? 'this command'} ${verb.verb ?? ''}`.trim() + ` is not available in the ${global.edition} edition (editions: ${verb.editions.join(', ')})`);
+  }
+  if (global.cwd === '') throw new Error('--cwd needs a value');
+  if (global.json === true && verb.json === 'none') {
+    throw new Error(`${verb.group ?? 'this command'} ${verb.verb ?? ''}`.trim() + ' has no machine output');
+  }
+};
+
+/** args = supplied locals, else their declared defaults (a list flag's scalar default wraps in an array). */
+const defaultArgs = (locals, values) => {
+  const args = {};
+  for (const flag of locals.values()) {
+    if (Object.hasOwn(values, flag.name)) args[flag.name] = values[flag.name];
+    else if (flag.default !== undefined) args[flag.name] = flag.type === 'list' && !Array.isArray(flag.default) ? [flag.default] : flag.default;
+  }
+  return args;
+};
+
+/**
+ * Validate the arguments after a catalog group and verb.
+ *
+ * Global options are returned separately so dispatchers can implement them once;
+ * localArgs contains only the verb's positionals and local options, in input order.
+ * Everything after a bare `--` is passed through unchanged: it is never parsed as an option and
+ * only fills positional slots the verb declares.
+ */
+export function validateArgs(argv, verb, globalFlags = []) {
+  const globals = new Map(globalFlags.map((flag) => [flag.name, { ...flag, global: true }]));
+  const locals = new Map((verb.flags ?? []).map((flag) => [flag.name, flag]));
+  const known = new Map([...globals, ...locals]);
+  // Flags the runtime's own scripts take and the CLI refuses, each with the pointer a person is given instead.
+  const internal = new Map((verb.internalFlags ?? []).map((entry) => [entry.name, entry.pointer]));
+  const values = {};
+  const global = {};
+  const localArgs = [];
+  const positionals = [];
+  const passthrough = [];
+  let positionalOnly = false;
+
+  try {
+    for (let index = 0; index < argv.length; index += 1) {
+      const token = argv[index];
+      if (positionalOnly) {
+        passthrough.push(token);
+        localArgs.push(token);
+        continue;
+      }
+      if (token === '--') {
+        positionalOnly = true;
+        localArgs.push(token);
+        continue;
+      }
+      if (token.startsWith('--')) {
+        index += applyOption(argv, index, token, { known, internal, values, global, localArgs, verb });
+        continue;
+      }
+      if (token.startsWith('-')) throw new Error(`unknown option ${token}`);
+      positionals.push(token);
+      localArgs.push(token);
+    }
+
+    requiredCheck(locals, values);
+    checkPositionals(verb, positionals, passthrough);
+    checkGlobals(verb, global);
+    return { ok: true, values, args: defaultArgs(locals, values), global, localArgs, positionals };
+  } catch (error) {
+    return { ok: false, code: 2, error: String(error?.message ?? error) };
+  }
+}
+
+/** Insert dispatcher-owned flags before a pass-through `--`, where handlers still parse them as options. */
+export function withFlagsBeforeDashes(args, extra) {
+  const at = args.indexOf('--');
+  return at < 0 ? [...args, ...extra] : [...args.slice(0, at), ...extra, ...args.slice(at)];
+}
+
+const isHelpToken = (token) => token === '--help' || token === '-h' || token === '--help=true';
+
+/**
+ * Find the group and verb while allowing catalog global options before them.
+ * `help` is true when --help or -h appears before any bare `--`; everything after `--` is pass-through.
+ */
+export function splitCommand(argv, globalFlags = []) {
+  const globals = new Map(globalFlags.map((flag) => [flag.name, flag]));
+  const command = [];
+  const args = [];
+  let help = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--') {
+      args.push(...argv.slice(index));
+      break;
+    }
+    if (isHelpToken(token)) {
+      help = true;
+      continue;
+    }
+    if (token.startsWith('--')) {
+      const flag = globals.get(optionName(token));
+      args.push(token);
+      const next = argv[index + 1];
+      if (flag && flag.type !== 'boolean' && !token.includes('=') && next !== undefined && !looksLikeFlag(next, globals)) args.push(argv[++index]);
+    } else if (token.startsWith('-') && token.length > 1) {
+      args.push(token);
+    } else if (command.length < 2) command.push(token);
+    else args.push(token);
+  }
+  return { group: command[0] ?? null, verb: command[1] ?? null, args, help };
+}

package/runtime/scripts/api/git/add.mjs

@@ -0,0 +1,5 @@
+// add.mjs — `git add <args>`: paths staged into the index.
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git add ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const add = (args = [], options = {}) => runGit(['add', ...args], options);

package/runtime/scripts/api/git/cat-file.mjs

@@ -0,0 +1,5 @@
+// cat-file.mjs — `git cat-file <args>`: the type, size or content of repository objects (-e, -p, --batch).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git cat-file ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const catFile = (args = [], options = {}) => runGit(['cat-file', ...args], options);

package/runtime/scripts/api/git/init.mjs

@@ -0,0 +1,7 @@
+// init.mjs — `git -c init.defaultBranch=<branch> init --quiet`: create an empty repository in `cwd` (the install sandbox's app repository).
+import { gitRunner } from './lib.mjs';
+
+/** {ok, stdout, stderr}. `env` replaces the process env (a sandbox's own home); git: the caller's runner or null. */
+export function init(cwd, { branch = 'main', env = undefined, git = null } = {}) {
+  return gitRunner(git)(['-c', `init.defaultBranch=${branch}`, 'init', '--quiet'], env ? { cwd, env } : { cwd });
+}

package/runtime/scripts/api/git/lib.mjs

@@ -75,3 +75,6 @@ export const gitExecutable = (options = null) => {
   if (!options) cachedGit = found;
   return found;
 };
+
+/** The output ceiling of the whole-diff and `cat-file --batch` calls `test affected` batches (a release diff is tens of megabytes). */
+export const BATCH_MAX_BUFFER = 1024 * 1024 * 1024;

package/runtime/scripts/api/git/tag.mjs

@@ -0,0 +1,5 @@
+// tag.mjs — `git tag <args>`: list or create tags (--points-at <rev>, -l <pattern>, -a <name> -m <message>).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git tag ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const tag = (args = [], options = {}) => runGit(['tag', ...args], options);

package/runtime/scripts/api/node/lib.mjs

@@ -0,0 +1,20 @@
+// scripts/api/node/lib.mjs — the runner of the runtime's own scripts as child processes: the node binary that runs this
+// process (process.execPath), a hidden window, utf8 text. The call files beside it (run-script.mjs, syntax-check.mjs,
+// run-node.mjs, spawn-node.mjs, exec-node.mjs) each name one use; nothing outside scripts/api/node imports this runner.
+import { assertMutationFence } from '../../lib/mutation-fence.mjs';
+import { execFile, spawn, spawnSync } from 'node:child_process';
+import { withTempEnv } from '../../../engine/temp-root.mjs';
+import { withoutTestRunner } from '../../lib/env.mjs';
+
+/** Whether `node <args>` starts the test runner (`--test`, `--test=...` before any script): its env must not carry an enclosing run's mark. THE one seam of every runtime child that runs specs. */
+const startsTestRunner = (args) => args.some((arg) => arg === '--test' || String(arg).startsWith('--test='));
+const forChild = (args, options) => (startsTestRunner(args) ? { ...options, env: withoutTestRunner(options?.env ?? process.env) } : options);
+
+/** `node <args>` with this process's node binary, waited for; options pass through last (cwd, stdio, env, timeout, maxBuffer, input). */
+export const nodeSpawn = (args, options = {}) => { assertMutationFence({ kind: 'node-effect', args }); return spawnSync(process.execPath, args, withTempEnv({ encoding: 'utf8', windowsHide: true, ...forChild(args, options) })); };
+
+/** `node <args>` with this process's node binary, started and not waited for: the ChildProcess (detached, stdio, env pass through). */
+export const nodeStart = (args, options = {}) => { assertMutationFence({ kind: 'node-effect', args }); return spawn(process.execPath, args, withTempEnv({ windowsHide: true, ...forChild(args, options) })); };
+
+/** `node <args>` with this process's node binary, waited for without blocking the thread: callback(error, stdout, stderr). */
+export const nodeExecFile = (args, options, callback) => { assertMutationFence({ kind: 'node-effect', args }); return execFile(process.execPath, args, withTempEnv({ encoding: 'utf8', windowsHide: true, ...forChild(args, options) }), callback); };

package/runtime/scripts/api/node/run-node.mjs

@@ -0,0 +1,6 @@
+// run-node.mjs — `node <args>` with this process's node binary, waited for: a runtime script (or `-e`/`--test`) as a child
+// whose output the caller reads. Returns the spawnSync result {status, stdout, stderr, error, signal} (utf8 text).
+import { nodeSpawn } from './lib.mjs';
+
+/** Runs `node <args>`; options (cwd, env, timeout, input, maxBuffer, stdio) pass through. */
+export const runNode = (args, options = {}) => nodeSpawn(args, options);

package/runtime/scripts/api/sops/lib.mjs

@@ -212,6 +212,47 @@ const toolProfileSupported = (version, ageVersion) => captured(version) && captu
 
 const invalidCaptureBudget = (deadline, maxBuffer) => !Number.isInteger(deadline) || deadline < 1 || deadline > 2_147_483_647 || !Number.isInteger(maxBuffer) || maxBuffer < 1;
 
+const publicAgeFailure = reason => ({ ok: false, reason });
+const publicAgeRequestValid = ({ env, cwd, invocation }) => env && typeof env === 'object' && !Array.isArray(env)
+  && path.isAbsolute(cwd ?? '') && typeof invocation?.runProgram === 'function'
+  && typeof invocation?.resolveRealTool === 'function';
+const publicAgeCapture = result => captured(result) && result.stdout.length <= CREDENTIAL_FILE_MAX_BYTES
+  && result.stderr.length <= CREDENTIAL_FILE_MAX_BYTES;
+
+const deriveSelectedAgeRecipient = (state, { env, cwd, invocation }, selection) => {
+  const key = env[selection.inlineName];
+  if (typeof key !== 'string' || !/^AGE-SECRET-KEY-1[0-9A-Z]+$/.test(key.trim())) return publicAgeFailure('invalid-inline');
+  const age = invocation.resolveRealTool('age-keygen', { env });
+  if (!nativeFile(age)) return publicAgeFailure('native-tool-unavailable');
+  const publicEnv = isolatedSopsEnv(env, null);
+  const options = { cwd, shell: false, encoding: 'buffer', windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: IDENTITY_TIMEOUT_MS, maxBuffer: CREDENTIAL_FILE_MAX_BYTES };
+  const run = selectedRunner(invocation, options, state.captures, publicEnv);
+  const version = run(age, ['--version']);
+  if (!publicAgeCapture(version) || !SELECTED_AGE_VERSIONS.has(/^v?(\d+\.\d+\.\d+)/.exec(decoded(version.stdout))?.[1])) return publicAgeFailure('unsupported-tool-profile');
+  state.identity = Buffer.from(key.trim(), 'utf8');
+  const derived = run(age, ['-y'], state.identity);
+  if (!publicAgeCapture(derived)) return publicAgeFailure('recipient-unproven');
+  const recipient = recipientOf(derived.stdout);
+  if (recipient === null) return publicAgeFailure('recipient-unproven');
+  return { ok: true, publicRecipient: recipient };
+};
+
+/** Derive only the public recipient of an explicitly selected inline identity; no private capture escapes. */
+export function selectedAgeRecipient(options = {}) {
+  if (!publicAgeRequestValid(options)) return publicAgeFailure('invalid-request');
+  const selection = sopsIdentityEnv(options.env, { required: true });
+  if (selection.error?.identityRefusal !== 'inline-context-unqualified') return publicAgeFailure(selection.error?.identityRefusal ?? 'selected-inline-required');
+  const state = { identity: undefined, captures: [] };
+  try {
+    return deriveSelectedAgeRecipient(state, options, selection);
+  } catch { return publicAgeFailure('selected-native-refused'); }
+  finally {
+    state.identity?.fill(0);
+    wipeCaptures(state.captures);
+  }
+}
+
 // The document bytes into `state.input`; the refusal when they are unavailable or over budget, else null.
 const readSelectedInput = (state, request, spec, file) => {
   try { state.input = request.operation === 'seal' ? Buffer.from(spec.plaintext) : readSecretBytes(file); } catch { return held('actual-document-unavailable'); }

package/runtime/scripts/api/sops/resolve-sops.mjs

@@ -0,0 +1,7 @@
+// resolve-sops.mjs — find the sops executable: PATH, and on Windows the WinGet links and packages.
+import { resolveSops as resolve } from './lib.mjs';
+
+/** The absolute sops path, or null. `options`: platform, pathext (PATHEXT names), wingetPackageTree (the full package tree), filesystem (a probe). */
+export function resolveSops(env = process.env, options = {}) {
+  return resolve(env, options);
+}

package/runtime/scripts/api/sops/seal.mjs

@@ -1,4 +1,4 @@
-// seal.mjs - one `sops encrypt` of a plaintext document held in memory: the canon command `starci app secret set` and `starci app secret gen`
+// seal.mjs - one `sops encrypt` of a plaintext document held in memory: `starci app secret set` (including --generate)
 // (scripts/hfs/secret.mjs). The plaintext travels on the child's stdin and never on its argument list, so it is not visible in a
 // process listing; the ciphertext comes back on stdout.
 import { spawnSync } from 'node:child_process';

package/runtime/scripts/api/sops/selected-age-recipient.mjs

@@ -0,0 +1,7 @@
+// selected-age-recipient.mjs - public recipient derivation for app secret initialization.
+import { selectedAgeRecipient as selectedRecipient } from './lib.mjs';
+
+/** Return a public recipient or a typed refusal; selected inline identity bytes never leave the owner. */
+export function selectedAgeRecipient(options = {}) {
+  return selectedRecipient(options);
+}

package/runtime/scripts/api/supabase/database-dump.mjs

@@ -0,0 +1,5 @@
+// database-dump.mjs - schema dump for an app's local or linked Supabase database.
+import { supabaseCall } from './lib.mjs';
+
+/** The spawn result of supabase db dump; arguments and runner options remain with the caller. */
+export function databaseDump(...args) { return supabaseCall(['db', 'dump'], ...args); }

package/runtime/scripts/api/supabase/database-query.mjs

@@ -0,0 +1,5 @@
+// database-query.mjs - database query for an app's local or linked Supabase database.
+import { supabaseCall } from './lib.mjs';
+
+/** The spawn result of supabase db query; arguments and runner options remain with the caller. */
+export function databaseQuery(...args) { return supabaseCall(['db', 'query'], ...args); }

package/runtime/scripts/api/supabase/lib.mjs

@@ -0,0 +1,44 @@
+// lib.mjs - resolve and spawn the app-local Supabase CLI for this API system, with no shell.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const candidateNames = (platform) => platform === 'win32'
+  ? ['supabase.exe', 'supabase', 'supabase.cmd']
+  : ['supabase'];
+
+/** Resolve the app-local Supabase CLI first, then PATH, retaining a PATH lookup fallback for useful spawn errors. */
+function resolveSupabase(appRoot, { env = process.env, platform = process.platform, exists = fs.existsSync } = {}) {
+  const names = candidateNames(platform);
+  const local = path.join(appRoot, 'node_modules', '.bin');
+  for (const name of names) {
+    const file = path.join(local, name);
+    if (exists(file)) return file;
+  }
+  const delimiter = platform === 'win32' ? ';' : ':';
+  for (const directory of String(env.PATH ?? '').split(delimiter).filter(Boolean)) {
+    for (const name of names) {
+      const file = path.join(directory, name);
+      if (exists(file)) return file;
+    }
+  }
+  return 'supabase';
+}
+
+/** Run one Supabase call for an app root; options retain the injectable spawn seam used by focused specs. */
+export const supabaseSpawn = (appRoot, args, {
+  env = process.env,
+  supabase,
+  timeout = 60_000,
+  run = spawnSync,
+} = {}) => run(supabase ?? resolveSupabase(appRoot, { env }), args, {
+  cwd: appRoot,
+  encoding: 'utf8',
+  env,
+  timeout,
+  windowsHide: true,
+});
+
+/** Invoke one Supabase command prefix with caller arguments and runner options. */
+export const supabaseCall = (prefix, appRoot, args = [], options = {}) =>
+  supabaseSpawn(appRoot, [...prefix, ...args], options);

package/runtime/scripts/api/supabase/migration-repair.mjs

@@ -0,0 +1,5 @@
+// migration-repair.mjs - migration history repair for an app's local or linked Supabase database.
+import { supabaseCall } from './lib.mjs';
+
+/** The spawn result of supabase migration repair; arguments and runner options remain with the caller. */
+export function migrationRepair(...args) { return supabaseCall(['migration', 'repair'], ...args); }

package/runtime/scripts/hfs/app-wiring.mjs

@@ -0,0 +1,201 @@
+// R272: compile the actual Nest AppModule in a child, with explicit infrastructure doubles.
+// Dynamic roots need public fixture options: src/tests/fixtures/builders/<app>.builder.ts may export
+// buildWiringProof(AppModule) => { options, overrides: [{ token, value }], request? }. The runner always chooses
+// the real root; a fixture cannot substitute an empty module. No environment parser or main.ts runs.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { runNode } from '../api/node/run-node.mjs';
+import { fileURLToPath } from 'node:url';
+import { invocationDir } from '../lib/roots.mjs';
+import { isMain } from '../lib/is-main.mjs';
+import { readJson } from './rules/read.mjs';
+
+export const BOOT_PROOF_CODE = 'BE_APP_BOOT_PROOF_MISSING';
+const WORKER = fileURLToPath(import.meta.url);
+const DEFAULT_TIMEOUT = 15000;
+const DI_FAILURES = new Map([
+  ['UnknownDependenciesException', 'unresolved DI provider'],
+  ['CircularDependencyException', 'circular DI dependency'],
+  ['UndefinedModuleException', 'undefined or circular module import'],
+  ['WiringTimeout', 'DI compilation timed out'],
+]);
+const COMPILATION_FAILURE = 'module or proof could not be compiled';
+const WORKER_FAILURE = 'proof worker failed or timed out';
+const SAFE_REASONS = new Set([...DI_FAILURES.values(), COMPILATION_FAILURE]);
+const modulePath = app => `apps/${app}/src/app.module.ts`;
+export const wiringFixturePath = app => `src/tests/fixtures/builders/${app}.builder.ts`;
+
+const refusal = (file, reason) => ({ code: BOOT_PROOF_CODE, level: 'error', path: file,
+  message: `${file}: lite boot proof failed (${reason}); compile the real AppModule with explicit fixture options and infrastructure doubles using starci app check --wiring`, reason });
+
+/** Stable diagnostics never forward exception text, source values or child output. */
+function failureReason(error) {
+  // Nest exceptions inherit Error.name; their constructor identifies the refusal.
+  return DI_FAILURES.get(error?.constructor?.name) ?? DI_FAILURES.get(error?.name) ?? COMPILATION_FAILURE;
+}
+
+/** Nest bootstrap defers request/transient trees: prove them in their original module's scope too. */
+async function compileGraph(builder, Nest, request) {
+  const compiled = await builder.compile();
+  const { ContextIdFactory, ModuleRef } = Nest;
+  const contextId = ContextIdFactory.create();
+  compiled.registerRequestByContextId(request, contextId);
+  const resolutions = [];
+  // Read the actual compiled container, not an application provider claiming to be ModulesContainer.
+  for (const module of compiled.container.getModules().values()) {
+    // Native REQUEST/INQUIRER factories belong to Nest itself; their empty result is intentional.
+    if (module === compiled.container.getInternalCoreModuleRef()) continue;
+    const moduleRef = module.providers.get(ModuleRef)?.instance;
+    for (const wrappers of [module.providers, module.controllers, module.injectables]) {
+      for (const wrapper of wrappers.values()) {
+        if (wrapper.isTransient || !wrapper.isDependencyTreeStatic()) {
+          resolutions.push(() => moduleRef.resolve(wrapper.token, contextId, { strict: true }));
+        }
+      }
+    }
+  }
+  await Promise.all(resolutions.map(resolve => resolve()));
+}
+
+/** Compile a real root, with overrides of existing tokens only; never auto-mock an unresolved dependency. */
+async function compileAppModule({ AppModule, options, overrides = [], request = {}, Test, Nest, timeout = DEFAULT_TIMEOUT }) {
+  if (typeof AppModule !== 'function') throw new Error('the actual AppModule is missing');
+  if (typeof AppModule.register === 'function' && options === undefined) throw new Error('dynamic AppModule needs fixture options');
+  const root = typeof AppModule.register === 'function' ? await AppModule.register(options) : AppModule;
+  if (root?.module && root.module !== AppModule) throw new Error('registration must return the actual AppModule');
+  const builder = Test.createTestingModule({ imports: [root] });
+  for (const override of overrides) {
+    if (!override || !Object.hasOwn(override, 'token') || !Object.hasOwn(override, 'value')) throw new Error('an infrastructure double needs a token and value');
+    builder.overrideProvider(override.token).useValue(override.value);
+  }
+  let deadline;
+  const expired = new Promise((_, reject) => { deadline = setTimeout(() => {
+    const error = new Error('compilation deadline'); error.name = 'WiringTimeout'; reject(error);
+  }, timeout); });
+  try {
+    // compile proves DI. Neither init nor close runs: both invoke application lifecycle hooks.
+    // The isolated worker exits naturally once every infrastructure resource has a double.
+    await Promise.race([compileGraph(builder, Nest, request), expired]);
+  } finally { clearTimeout(deadline); }
+}
+
+/** The strict in-memory TS loader uses this app's installed compiler and Nest, including inherited aliases. */
+function sourceLoader(repoRoot, entry, fixture) {
+  const require = createRequire(path.join(repoRoot, 'package.json'));
+  const ts = require('typescript');
+  const config = ts.getParsedCommandLineOfConfigFile(path.join(repoRoot, 'tsconfig.json'), {},
+    { ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => { throw new Error('invalid TypeScript project'); } });
+  if (!config || config.errors.length) throw new Error('invalid TypeScript project');
+  const options = { ...config.options, module: ts.ModuleKind.CommonJS, moduleResolution: ts.ModuleResolutionKind.Node10,
+    experimentalDecorators: true, emitDecoratorMetadata: true, noEmit: false, noEmitOnError: false,
+    declaration: false, declarationMap: false, sourceMap: false, inlineSourceMap: false,
+    incremental: false, composite: false, tsBuildInfoFile: undefined, outDir: undefined, rootDir: undefined };
+  const program = ts.createProgram({ rootNames: [entry, ...(fixture ? [fixture] : [])], options });
+  if (program.getSyntacticDiagnostics().length) throw new Error('invalid TypeScript source');
+  const outputs = new Map();
+  program.emit(undefined, (file, text, _bom, _error, sources) => {
+    if (file.endsWith('.js')) for (const source of sources ?? []) outputs.set(path.resolve(source.fileName), text);
+  });
+  const NodeModule = require('node:module');
+  const resolve = NodeModule._resolveFilename;
+  NodeModule._resolveFilename = function resolveSource(request, parent, ...rest) {
+    if (parent?.filename && (request.startsWith('.') || Object.keys(options.paths ?? {}).some(alias => request.startsWith(alias.replace(/\*$/, ''))))) {
+      const resolved = ts.resolveModuleName(request, parent.filename, options, ts.sys).resolvedModule;
+      if (resolved && !resolved.isExternalLibraryImport && !resolved.resolvedFileName.endsWith('.d.ts')) return resolved.resolvedFileName;
+    }
+    return resolve.call(this, request, parent, ...rest);
+  };
+  require.extensions['.ts'] = (loaded, file) => {
+    const output = outputs.get(path.resolve(file));
+    if (output === undefined) throw new Error('source is outside the compiled graph');
+    loaded._compile(output, file);
+  };
+  require('reflect-metadata');
+  return require;
+}
+
+async function wiringWorker({ repoRoot, app, fixture, timeout }) {
+  // Disable network entry points before loading application source. A forgotten resource double is a refusal.
+  const systemRequire = createRequire(import.meta.url);
+  for (const [packageName, methods] of [['node:net', ['connect', 'createConnection']], ['node:tls', ['connect']],
+    ['node:http', ['request', 'get']], ['node:https', ['request', 'get']]]) {
+    const api = systemRequire(packageName);
+    for (const method of methods) api[method] = () => { throw new Error('wiring needs an infrastructure double'); };
+  }
+  systemRequire('node:net').Socket.prototype.connect = () => { throw new Error('wiring needs an infrastructure double'); };
+  systemRequire('node:net').Server.prototype.listen = () => { throw new Error('wiring needs an infrastructure double'); };
+  globalThis.fetch = () => { throw new Error('wiring needs an infrastructure double'); };
+  const entry = path.join(repoRoot, modulePath(app));
+  const fixtureFile = fixture ? path.join(repoRoot, fixture) : null;
+  const require = sourceLoader(repoRoot, entry, fixtureFile);
+  const { AppModule } = require(entry);
+  const proof = fixtureFile ? await require(fixtureFile).buildWiringProof(AppModule) : {};
+  if (!proof || typeof proof !== 'object') throw new Error('invalid wiring fixture');
+  await compileAppModule({ AppModule, options: proof.options, overrides: proof.overrides, request: proof.request,
+    Test: require('@nestjs/testing').Test, Nest: require('@nestjs/core'), timeout });
+}
+
+function wiringApps(repo, files, prefix) {
+  const declared = (repo.sides?.be?.apps ?? repo.apps ?? []).map(app => app.name);
+  const observed = (files ?? []).flatMap(file => {
+    const match = file.match(new RegExp(String.raw`^${prefix}apps/([^/]+)/src/app\.module\.ts$`));
+    return match ? [match[1]] : [];
+  });
+  return [...new Set([...declared, ...observed])];
+}
+
+function appWiringFinding({ repoRoot, beRoot, prefix, app, files, fixtures, timeout, run }) {
+  const file = `${prefix}${modulePath(app)}`;
+  if (!/^[a-z][a-z0-9-]*$/.test(app) || !fs.existsSync(path.join(repoRoot, file)) || (files && !files.includes(file))) {
+    return refusal(file, 'app module is missing');
+  }
+  const fixture = fixtures[app] ?? wiringFixturePath(app);
+  const fixtureExists = fs.existsSync(path.join(beRoot, fixture)) && (!files || files.includes(`${prefix}${fixture}`));
+  const args = [WORKER, '--worker', JSON.stringify({ repoRoot: beRoot, app, fixture: fixtureExists ? fixture : null, timeout })];
+  const options = { cwd: beRoot, encoding: 'utf8', env: {}, windowsHide: true, timeout: Math.max(60000, timeout * 4) + 2000, maxBuffer: 1024 * 1024 };
+  const result = run ? run(process.execPath, args, options) : runNode(args, options);
+  let proof;
+  try { proof = JSON.parse(result.stdout ?? ''); } catch { /* Output from app source cannot serve as a proof. */ }
+  if (result.status !== 0 || proof?.ok !== true) return refusal(file, SAFE_REASONS.has(proof?.reason) ? proof.reason : WORKER_FAILURE);
+  return null;
+}
+
+/** Synchronous check seam for the dispatcher and content finder. Paths in findings are relative to repoRoot. */
+export function appWiring({ repoRoot, repo = readJson(repoRoot, 'hfs.json'), files, fixtures = {}, timeout = DEFAULT_TIMEOUT, run } = {}) {
+  if (repo?.edition !== 'lite' || repo?.profile === 'fe' || repo?.kind === 'fe') return { ok: true, status: 'skipped', findings: [], apps: [] };
+  const appRoot = Boolean(repo.sides);
+  const beRoot = appRoot ? path.join(repoRoot, 'be') : repoRoot;
+  const prefix = appRoot ? 'be/' : '';
+  const apps = wiringApps(repo, files, prefix);
+  const findings = [];
+  for (const app of apps) {
+    const finding = appWiringFinding({ repoRoot, beRoot, prefix, app, files, fixtures, timeout, run });
+    if (finding) findings.push(finding);
+  }
+  return { ok: findings.length === 0, status: 'checked', apps, findings };
+}
+
+/** Optional standalone entry; coordinator connects the same seam to app check --wiring. */
+export function appWiringMain(argv, { cwd = invocationDir(), stdout = text => process.stdout.write(text), stderr = text => process.stderr.write(text) } = {}) {
+  let directory = cwd, json = false;
+  for (let at = 0; at < argv.length; at += 1) {
+    if (argv[at] === '--cwd' && argv[at + 1]) directory = path.resolve(cwd, argv[++at]);
+    else if (argv[at] === '--json') json = true;
+    else if (argv[at] !== '--wiring') { stderr('usage: starci app check --wiring [--cwd <dir>] [--json]\n'); return 2; }
+  }
+  const repo = readJson(directory, 'hfs.json');
+  if (!repo) { stderr('wiring needs a readable hfs.json\n'); return 2; }
+  const result = appWiring({ repoRoot: directory, repo });
+  const trailingNewline = result.findings.length ? '\n' : '';
+  const report = `${result.status}: ${result.apps.length} app(s), ${result.findings.length} boot proof failure(s)\n${result.findings.map(f => f.message).join('\n')}${trailingNewline}`;
+  stdout(json ? `${JSON.stringify(result)}\n` : report);
+  return result.ok ? 0 : 1;
+}
+
+if (isMain(import.meta.url)) {
+  if (process.argv[2] === '--worker') {
+    try { await wiringWorker(JSON.parse(process.argv[3])); process.stdout.write(JSON.stringify({ ok: true })); }
+    catch (error) { process.stdout.write(JSON.stringify({ ok: false, reason: failureReason(error) })); }
+  } else process.exitCode = appWiringMain(process.argv.slice(2));
+}