@starci/hfs 4.7.47 → 4.9.0

package/runtime/scripts/lib/canon-binding-text.mjs

@@ -1,129 +0,0 @@
-// Canon release binding edits preserve authored profile text and update only the selected binding's identity.
-
-const KEY = /^[A-Za-z_][A-Za-z0-9_-]*$/;
-
-function supportedBinding(value) {
-  const keys = typeof value === 'string' ? value.split('.') : [];
-  return (keys.length === 1 && keys[0] === 'canon') || (keys.length === 2 && keys[0] === 'familyCanons' && KEY.test(keys[1]));
-}
-
-function lineEntry(line, index) {
-  const text = line.slice(0, line.length - lineEnding(line).length);
-  if (!text.trim() || text.trimStart().startsWith('#')) return null;
-  let indent = 0;
-  while (text[indent] === ' ') indent++;
-  const colon = text.indexOf(':', indent);
-  const key = colon < 0 ? '' : text.slice(indent, colon);
-  if (!KEY.test(key)) return { index, indent };
-  let valueAt = colon + 1;
-  while (text[valueAt] === ' ' || text[valueAt] === '\t') valueAt++;
-  return { index, indent, key, prefix: text.slice(0, valueAt), value: text.slice(valueAt) };
-}
-
-function lineEnding(line) {
-  if (line.endsWith('\r\n')) return '\r\n';
-  return line.endsWith('\n') ? '\n' : '';
-}
-
-function linesOf(text) {
-  const lines = [];
-  let start = 0;
-  for (let index = 0; index < text.length; index++) {
-    if (text[index] !== '\n') continue;
-    lines.push(text.slice(start, index + 1));
-    start = index + 1;
-  }
-  if (start < text.length) lines.push(text.slice(start));
-  return lines;
-}
-
-function child(entries, parent, key, at) {
-  const nested = entries.filter(entry => entry.index > parent.start && entry.index < parent.end && entry.indent > parent.indent);
-  const directIndent = Math.min(...nested.map(entry => entry.indent));
-  const found = nested.filter(entry => entry.indent === directIndent && entry.key === key);
-  if (found.length !== 1) throw new Error(`${at}: expected one ${key} field, found ${found.length}`);
-  const entry = found[0];
-  const boundary = entries.find(candidate => candidate.index > entry.index && candidate.index < parent.end && candidate.indent <= entry.indent);
-  return { ...entry, start: entry.index, end: boundary?.index ?? parent.end };
-}
-
-function mapping(entries, parent, key, at) {
-  const node = child(entries, parent, key, at);
-  if (node.value.trim() && !node.value.trim().startsWith('#')) throw new Error(`${at}.${key}: expected a block mapping`);
-  return node;
-}
-
-function scalar(entries, parent, key, at) {
-  const node = child(entries, parent, key, at);
-  if (!node.value.trim() || node.value.trim().startsWith('#')) throw new Error(`${at}.${key}: expected a scalar value`);
-  return node;
-}
-
-function scalarParts(value) {
-  const quote = value[0] === "'" || value[0] === '"' ? value[0] : null;
-  let end = quote ? value.indexOf(quote, 1) : 0;
-  if (quote && end < 1) return null;
-  if (quote) end++;
-  else {
-    while (end < value.length && value[end].trim() && !['#', "'", '"'].includes(value[end])) end++;
-  }
-  if (!end) return null;
-  let tail = end;
-  while (value[tail] === ' ' || value[tail] === '\t') tail++;
-  if (tail < value.length && (tail === end || value[tail] !== '#')) return null;
-  return { value: quote ? value.slice(1, end - 1) : value.slice(0, end), suffix: value.slice(end) };
-}
-
-function packageValue(value) {
-  return scalarParts(value)?.value;
-}
-
-function replaceScalar(lines, node, value) {
-  const parts = scalarParts(node.value);
-  if (!parts) throw new Error(`Cannot replace malformed scalar ${node.key}`);
-  lines[node.index] = `${node.prefix}${value}${parts.suffix}${lineEnding(lines[node.index])}`;
-}
-
-function bindingNode(entries, root, row) {
-  const at = `profiles.${row.profile}.${row.binding}`;
-  let node = mapping(entries, root, 'profiles', 'document');
-  node = mapping(entries, node, row.profile, 'profiles');
-  for (const key of row.binding.split('.')) node = mapping(entries, node, key, at);
-  const declared = scalar(entries, node, 'package', at);
-  if (packageValue(declared.value) !== row.package) throw new Error(`${at}: package does not match ${row.package}`);
-  return { node, at };
-}
-
-/**
- * Render release version and digest updates at their exact profile binding paths without reserializing authored YAML.
- * Unrelated bytes, comments and newline style are preserved. Missing or duplicate mapping paths, unexpected packages,
- * incomplete digest blocks and invalid replacement identities throw before any caller writes the returned text.
- * @param {string} original - The authored code-pattern profile YAML.
- * @param {Array<{profile: string, binding: string, package: string, to: {version: string, value: string, files: number}}>} rows - Exact canon or family binding identities to replace.
- * @returns {string} Updated profile YAML; the input is returned unchanged when no rows are supplied.
- */
-export function renderCanonBindingChanges(original, rows) {
-  if (typeof original !== 'string' || !Array.isArray(rows)) throw new Error('canon binding changes need YAML text and identity rows');
-  const lines = linesOf(original);
-  const entries = lines.map((line, index) => lineEntry(line, index)).filter(Boolean);
-  const root = { start: -1, end: lines.length, indent: -1 };
-  const selected = new Set();
-  for (const row of rows) {
-    if (!KEY.test(row?.profile ?? '') || !supportedBinding(row?.binding) || typeof row?.package !== 'string' || !row.package) throw new Error('canon binding changes need a supported profile, package and binding path');
-    const identity = `${row.profile}.${row.binding}`;
-    if (selected.has(identity)) throw new Error(`${identity}: duplicate binding change`);
-    selected.add(identity);
-    if (!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(row.to?.version ?? '') || !/^[a-f0-9]{64}$/i.test(row.to?.value ?? '')
-      || !Number.isSafeInteger(row.to?.files) || row.to.files < 1) throw new Error(`${identity}: invalid replacement version or digest`);
-    const { node, at } = bindingNode(entries, root, row);
-    const version = scalar(entries, node, 'version', at);
-    const digest = mapping(entries, node, 'contentDigest', at);
-    const value = scalar(entries, digest, 'value', `${at}.contentDigest`);
-    const files = scalar(entries, digest, 'files', `${at}.contentDigest`);
-    replaceScalar(lines, version, row.to.version);
-    // A hexadecimal digest can contain digits only; quoting preserves its string identity in YAML.
-    replaceScalar(lines, value, `'${row.to.value}'`);
-    replaceScalar(lines, files, row.to.files);
-  }
-  return lines.join('');
-}

package/runtime/scripts/lib/check-format.mjs

@@ -1,7 +0,0 @@
-// check-format.mjs — the one-line-per-check report every canon check CLI shares.
-
-const MARK = { pass: 'pass', fail: 'FAIL', skip: 'skip' };
-
-/** `header` plus one '  [outcome] id: detail' line per check of `checks`, joined with '\n'. */
-export const formatCheckLines = (header, checks) =>
-  [header, ...(checks ?? []).map((entry) => `  [${MARK[entry.outcome]}] ${entry.id}: ${entry.detail}`)].join('\n');

package/runtime/scripts/lib/failure-code-reads.mjs

@@ -1,100 +0,0 @@
-// failure-code-reads.mjs - the UPPER_SNAKE literals of a script that READ a value another producer made, or only describe one in a comment,
-// and so are not emitted failure codes (scripts/checks/check-failure-codes.mjs adds these quote offsets to its exact-AST exclusions).
-//   - a literal inside a comment (a name mentioned in prose is not emitted);
-//   - an operand of ===, !==, == or != against a non-literal, or a `case` label (the code is compared, not produced);
-//   - an argument of a string or collection query (endsWith, startsWith, includes, indexOf, has, get);
-//   - an element of an array literal whose only use here is `.includes(x)` / `.indexOf(x)` against a non-literal (a membership test);
-//   - the symbol half of a (symbol, package) argument pair such as `providersOf(root, 'APP_GUARD', '@nestjs/core')`: a name another package exports;
-//   - a literal the script declares as an enum member by identity (`Scalar.QUOTE_DOUBLE = "QUOTE_DOUBLE"`), wherever it then appears: the value of an enum-like constant, not a code;
-//   - the value of a property named `type` (a discriminator of someone else's API, such as a token type).
-// Emission sites (code:, reason:, finding(...), thrown messages, code lists) are never matched here. Proven by the package spec
-// src/failure-code-reads.spec.mjs over the bundled copy of this file.
-
-const EQUALITY = new Set(['===', '!==', '==', '!=']);
-const QUERY_METHODS = new Set(['endsWith', 'startsWith', 'includes', 'indexOf', 'has', 'get']);
-const MEMBERSHIP_METHODS = new Set(['includes', 'indexOf']);
-
-const isText = (t, node) => t.isStringLiteralLike(node);
-
-/** Whether `node` is the operand of an equality against a value that is not itself a literal. */
-function comparedValue(t, source, node) {
-  const parent = node.parent;
-  if (!parent || !t.isBinaryExpression(parent) || !EQUALITY.has(parent.operatorToken.getText(source))) return false;
-  const other = parent.left === node ? parent.right : parent.left;
-  return !isText(t, other);
-}
-
-/** Whether `node` is an argument of a string/collection query call such as `key.endsWith('X_Y')`. */
-function queryArgument(t, node) {
-  const call = node.parent;
-  return Boolean(call && t.isCallExpression(call) && call.arguments.includes(node)
-    && t.isPropertyAccessExpression(call.expression) && QUERY_METHODS.has(call.expression.name.text));
-}
-
-/** Whether `node` is an element of an array literal that is only tested with `.includes(value)` for a non-literal value. */
-function membershipElement(t, node) {
-  const array = node.parent;
-  if (!array || !t.isArrayLiteralExpression(array)) return false;
-  const access = array.parent;
-  if (!access || !t.isPropertyAccessExpression(access) || access.expression !== array || !MEMBERSHIP_METHODS.has(access.name.text)) return false;
-  const call = access.parent;
-  return Boolean(call && t.isCallExpression(call) && call.expression === access && call.arguments.length >= 1 && !isText(t, call.arguments[0]));
-}
-
-const PACKAGE_SPECIFIER = /^(?:@[\w.-]+\/[\w.-]+(?:\/[\w./-]+)?|\.{1,2}\/[\w./-]+)$/;
-
-/** Whether `node` is a call argument directly followed by a package or relative module specifier: the name of a symbol that module exports. */
-function importedSymbol(t, node) {
-  const call = node.parent;
-  if (!call || !t.isCallExpression(call)) return false;
-  const next = call.arguments[call.arguments.indexOf(node) + 1];
-  return Boolean(next && isText(t, next) && PACKAGE_SPECIFIER.test(next.text));
-}
-
-const caseLabel = (t, node) => Boolean(node.parent && t.isCaseClause(node.parent) && node.parent.expression === node);
-
-const discriminator = (t, node) => Boolean(node.parent && t.isPropertyAssignment(node.parent) && node.parent.initializer === node
-  && t.isIdentifier(node.parent.name) && node.parent.name.text === 'type');
-
-/** The [pos, end) ranges of every comment of `source`. */
-function commentRanges(t, source) {
-  const text = source.text, ranges = [];
-  const visit = (node) => {
-    for (const range of t.getLeadingCommentRanges(text, node.getFullStart()) ?? []) ranges.push([range.pos, range.end]);
-    for (const range of t.getTrailingCommentRanges(text, node.end) ?? []) ranges.push([range.pos, range.end]);
-    t.forEachChild(node, visit);
-  };
-  visit(source);
-  return ranges;
-}
-
-/**
- * The offsets to leave out of UPPER literal discovery for a parsed script: the opening quote of every read literal, and the start
- * of every `patterns` match (RegExp with the g flag) that lies inside a comment.
- */
-export function nonEmittingOffsets(t, source, patterns = []) {
-  const offsets = new Set();
-  const members = new Set();
-  const collect = (node) => {
-    if (t.isBinaryExpression(node) && node.operatorToken.kind === t.SyntaxKind.EqualsToken && t.isPropertyAccessExpression(node.left)
-      && isText(t, node.right) && node.right.text === node.left.name.text) members.add(node.right.text);
-    t.forEachChild(node, collect);
-  };
-  collect(source);
-  const visit = (node) => {
-    if (isText(t, node) && (members.has(node.text) || comparedValue(t, source, node) || queryArgument(t, node) || membershipElement(t, node) || caseLabel(t, node) || importedSymbol(t, node) || discriminator(t, node))) {
-      offsets.add(node.getStart(source));
-    }
-    t.forEachChild(node, visit);
-  };
-  visit(source);
-  const ranges = commentRanges(t, source);
-  if (ranges.length) {
-    for (const pattern of patterns) {
-      for (const match of source.text.matchAll(pattern)) {
-        if (ranges.some(([pos, end]) => match.index >= pos && match.index < end)) offsets.add(match.index);
-      }
-    }
-  }
-  return offsets;
-}

package/runtime/scripts/lib/failure-code-template-errors.mjs

@@ -1,161 +0,0 @@
-// Canonical platform templates can own shared application failures as well as runtime findings.
-// A catalog entry stays current only when production code instantiates its genuine DomainError enum member.
-import path from 'node:path';
-
-const CODE = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/;
-const exported = (t, node) => node.modifiers?.some((modifier) => modifier.kind === t.SyntaxKind.ExportKeyword);
-const textName = (t, node) => node && (t.isIdentifier(node) || t.isStringLiteralLike(node)) ? node.text : null;
-
-/** An import path resolves inside the virtual backend source tree declared by the pattern files. */
-function sourceTarget(specifier, owner, sources) {
-  let target = null;
-  if (specifier.startsWith('@modules/')) target = `src/modules/${specifier.slice('@modules/'.length)}`;
-  else if (specifier.startsWith('.')) target = path.posix.normalize(path.posix.join(path.posix.dirname(owner), specifier));
-  if (target === null) return null;
-  return [target, `${target}.ts`, `${target}/index.ts`].find((candidate) => sources.has(candidate)) ?? null;
-}
-
-/** Index module bindings and explicit exports without importing or running a template. */
-function moduleInfo(t, name, entry) {
-  const source = t.createSourceFile(name, entry.text, t.ScriptTarget.Latest, true, t.ScriptKind.TS);
-  const info = { name, file: entry.file, source, imports: new Map(), namespaces: new Map(), locals: new Map(), exports: new Map(), shadows: new Set() };
-  for (const statement of source.statements) {
-    if (t.isImportDeclaration(statement)) indexImport(t, info, statement);
-    if (t.isExportDeclaration(statement)) indexExport(t, info, statement);
-    if ((t.isEnumDeclaration(statement) || t.isClassDeclaration(statement)) && statement.name) {
-      const key = statement.name.text;
-      info.locals.set(key, statement);
-      if (exported(t, statement)) info.exports.set(key, { local: key });
-    }
-  }
-  const visit = (node) => {
-    const binding = scopedBinding(t, node);
-    if (binding) info.shadows.add(binding);
-    t.forEachChild(node, visit);
-  };
-  visit(source);
-  return info;
-}
-
-/** A nested declaration makes a text-only binding ambiguous; it cannot supply catalog evidence. */
-function scopedBinding(t, node) {
-  const named = t.isVariableDeclaration(node) || t.isParameter(node) || t.isBindingElement(node)
-    || t.isClassDeclaration(node) || t.isEnumDeclaration(node) || t.isFunctionDeclaration(node);
-  if (!named || !node.name || !t.isIdentifier(node.name)) return null;
-  let scope = node.parent;
-  while (scope && !t.isSourceFile(scope)) {
-    if (t.isBlock(scope) || t.isFunctionLike(scope)) return node.name.text;
-    scope = scope.parent;
-  }
-  return null;
-}
-
-function indexImport(t, info, statement) {
-  const bindings = statement.importClause?.namedBindings;
-  if (!bindings || !t.isStringLiteralLike(statement.moduleSpecifier)) return;
-  const specifier = statement.moduleSpecifier.text;
-  if (t.isNamespaceImport(bindings)) info.namespaces.set(bindings.name.text, specifier);
-  else for (const binding of bindings.elements) info.imports.set(binding.name.text, { name: (binding.propertyName ?? binding.name).text, specifier });
-}
-
-function indexExport(t, info, statement) {
-  const clause = statement.exportClause;
-  if (!clause || !t.isNamedExports(clause)) return;
-  const specifier = statement.moduleSpecifier && t.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
-  for (const binding of clause.elements) {
-    const name = (binding.propertyName ?? binding.name).text;
-    info.exports.set(binding.name.text, specifier ? { name, specifier } : { local: name });
-  }
-}
-
-/** Only a declared binding or a named import/export can establish an error family or enum identity. */
-function localValue(info, name, modules, seen = new Set()) {
-  const identity = `${info.name}:${name}`;
-  if (seen.has(identity) || info.shadows.has(name)) return null;
-  const visited = new Set(seen).add(identity);
-  if (info.locals.has(name)) return { info, declaration: info.locals.get(name) };
-  const binding = info.imports.get(name);
-  return binding ? importedValue(info, binding, modules, visited) : null;
-}
-
-function importedValue(info, binding, modules, seen) {
-  const target = sourceTarget(binding.specifier, info.name, modules);
-  const owner = target && modules.get(target);
-  const identity = owner && `export:${owner.name}:${binding.name}`;
-  if (!owner || seen.has(identity)) return null;
-  const visited = new Set(seen).add(identity);
-  const exposed = owner?.exports.get(binding.name);
-  if (!exposed) return null;
-  return exposed.local ? localValue(owner, exposed.local, modules, visited) : importedValue(owner, exposed, modules, visited);
-}
-
-const accessParts = (t, expression) => {
-  if (t.isPropertyAccessExpression(expression) || t.isQualifiedName(expression)) {
-    return { base: expression.expression ?? expression.left, member: (expression.name ?? expression.right).text };
-  }
-  if (t.isElementAccessExpression(expression) && t.isStringLiteralLike(expression.argumentExpression)) return { base: expression.expression, member: expression.argumentExpression.text };
-  return null;
-};
-
-function expressionValue(t, info, expression, modules) {
-  if (t.isIdentifier(expression)) return localValue(info, expression.text, modules);
-  const access = accessParts(t, expression);
-  const specifier = access && t.isIdentifier(access.base) && !info.shadows.has(access.base.text) && info.namespaces.get(access.base.text);
-  return specifier ? importedValue(info, { specifier, name: access.member }, modules, new Set()) : null;
-}
-
-/** DomainError is the canonical imported base, not an identically named local class. */
-function domainBase(t, info, expression) {
-  if (!t.isIdentifier(expression)) return false;
-  const binding = info.imports.get(expression.text);
-  return !info.shadows.has(expression.text) && binding?.name === 'DomainError' && binding.specifier === '@modules/platform/errors';
-}
-
-/** The generic enum on the real DomainError base owns the family's permitted codes. */
-function errorEnum(t, value, modules) {
-  const node = value?.declaration;
-  if (!node || !t.isClassDeclaration(node) || node.members.some(t.isConstructorDeclaration)) return null;
-  const clause = node.heritageClauses?.find((item) => item.token === t.SyntaxKind.ExtendsKeyword);
-  const base = clause?.types[0];
-  const argument = base?.typeArguments?.[0];
-  if (!base || !domainBase(t, value.info, base.expression) || base.typeArguments?.length !== 1 || !argument || !t.isTypeReferenceNode(argument)) return null;
-  const enumeration = expressionValue(t, value.info, argument.typeName, modules);
-  return enumeration && t.isEnumDeclaration(enumeration.declaration) ? enumeration : null;
-}
-
-/** A static code field survives only when no later spread or dynamic key can replace it. */
-function codeField(t, expression) {
-  if (!expression || !t.isObjectLiteralExpression(expression)) return null;
-  let code = null;
-  for (const property of expression.properties) {
-    if (t.isSpreadAssignment(property) || textName(t, property.name) === null) code = null;
-    else if (textName(t, property.name) === 'code') code = t.isPropertyAssignment(property) ? property.initializer : null;
-  }
-  return code;
-}
-
-/** Constructor and code expression must resolve to the same declared enum, including through public barrels. */
-function constructedCode(t, info, node, modules) {
-  const family = errorEnum(t, expressionValue(t, info, node.expression, modules), modules);
-  const field = codeField(t, node.arguments?.[0]);
-  const access = field && accessParts(t, field);
-  const enumeration = access && expressionValue(t, info, access.base, modules);
-  if (!family || !enumeration || enumeration.declaration !== family.declaration) return null;
-  const member = family.declaration.members.find((item) => textName(t, item.name) === access.member);
-  return member?.initializer && t.isStringLiteralLike(member.initializer) && CODE.test(member.initializer.text) ? member.initializer.text : null;
-}
-
-/** Actual typed error constructions in declared production platform templates, with their source locations. */
-export function templateErrorCodes(t, sources) {
-  const modules = new Map([...sources].map(([name, entry]) => [name, moduleInfo(t, name, entry)]));
-  const emitted = new Map();
-  for (const info of modules.values()) {
-    const visit = (node) => {
-      const code = t.isNewExpression(node) && constructedCode(t, info, node, modules);
-      if (code) emitted.set(code, { code, file: info.file, line: info.source.getLineAndCharacterOfPosition(node.getStart(info.source)).line + 1 });
-      t.forEachChild(node, visit);
-    };
-    visit(info.source);
-  }
-  return [...emitted.values()];
-}

package/runtime/scripts/lib/git-dir.mjs

@@ -1,120 +0,0 @@
-// git-dir.mjs — a checkout's git directory and the git processes that may hold it, read without running git: the pure
-// half of the stale `.git/index.lock` recovery (scripts/api/git/index-lock.mjs indexLock removes the lock;
-// scripts/machine/lock-recovery.mjs reads the process table, records the removal and runs the command guard's pre-flight).
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathKey } from './path-key.mjs';
-
-/** git.exe and its helpers (git-remote-https.exe, git-lfs.exe, ...). */
-const GIT_IMAGE = /^git(?:-[\w.-]+)?(?:\.exe)?$/i;
-/** Whether a process image name is git or one of its helpers. */
-export const isGitImage = (name) => GIT_IMAGE.test(String(name ?? ''));
-/** `file`'s lstat, or null when it cannot be read. */
-export const lockStat = (file) => { try { return fs.lstatSync(file); } catch { return null; } };
-
-const GITDIR_LINE = new RegExp([
-  '^gitdir:',
-  String.raw`\s*(.+)$`,
-].join(''), 'm');
-
-/** The git dir of the checkout at `repo`: `.git` itself, or the `gitdir:` a worktree's `.git` file names. Null when none. */
-export function gitDirOf(repo) {
-  const dotGit = path.join(path.resolve(repo), '.git');
-  let st;
-  try { st = fs.lstatSync(dotGit); } catch { return null; }
-  if (st.isDirectory()) return dotGit;
-  if (!st.isFile()) return null;
-  try {
-    const m = GITDIR_LINE.exec(fs.readFileSync(dotGit, 'utf8'));
-    return m ? path.resolve(path.dirname(dotGit), m[1].trim()) : null;
-  } catch { return null; }
-}
-
-/** The checkout `start` is in: the nearest directory at or above it holding `.git`, or null. */
-export function checkoutOf(start) {
-  for (let dir = path.resolve(String(start ?? '.')); ; dir = path.dirname(dir)) {
-    if (lockStat(path.join(dir, '.git'))) return dir;
-    if (path.dirname(dir) === dir) return null;
-  }
-}
-
-const FULL_SHA = /^[0-9a-f]{40}$/;
-
-function looseHeadRef(gitDir, common, ref, commonOnly) {
-  for (const dir of commonOnly ? [common] : [gitDir, common]) {
-    try {
-      const loose = fs.readFileSync(path.join(dir, ref), 'utf8').trim();
-      if (FULL_SHA.test(loose)) return loose;
-    } catch { /* packed */ }
-  }
-  return null;
-}
-
-function packedHeadRef(common, ref) {
-  for (const line of fs.readFileSync(path.join(common, 'packed-refs'), 'utf8').split('\n')) {
-    const [sha, name] = line.trim().split(' ');
-    if (name === ref && FULL_SHA.test(sha)) return sha;
-  }
-  return null;
-}
-
-const HEADS_REF_LINE = new RegExp([
-  String.raw`^ref:\s*(refs\/heads\/\S+)`,
-  '$',
-].join(''));
-const ANY_REF_LINE = new RegExp([
-  String.raw`^ref:\s*(.+)`,
-  '$',
-].join(''));
-/**
- * The commit the HEAD of the checkout at `root` names, read from .git with no spawn; null when it cannot be told that
- * way (not a top level, reftable, an unreadable ref) and the read then runs live. `headsOnly` accepts only
- * refs/heads/* symbolic refs; a loose ref reads from the common dir, as git does for a linked worktree — plus the git
- * dir itself first unless `commonOnly`.
- */
-export function headShaOf(root, { headsOnly = false, commonOnly = false } = {}) {
-  try {
-    let gitDir = path.join(root, '.git');
-    if (fs.statSync(gitDir).isFile()) {
-      const pointer = GITDIR_LINE.exec(fs.readFileSync(gitDir, 'utf8'))?.[1];
-      if (!pointer) return null;
-      gitDir = path.resolve(root, pointer.trim());
-    }
-    const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
-    if (FULL_SHA.test(head)) return head;
-    const ref = headsOnly ? HEADS_REF_LINE.exec(head)?.[1] : ANY_REF_LINE.exec(head)?.[1]?.trim();
-    if (!ref) return null;
-    let common = gitDir;
-    try { common = path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim()); } catch { /* not a linked worktree */ }
-    const loose = looseHeadRef(gitDir, common, ref, commonOnly);
-    if (loose) return loose;
-    return packedHeadRef(common, ref);
-  } catch { /* no git metadata */ }
-  return null;
-}
-
-/** Command-line words, double quotes grouping (Windows command lines quote paths with spaces). */
-const words = (line) => [...String(line ?? '').matchAll(/"([^"]*)"|(\S+)/g)].map((m) => m[1] ?? m[2]);
-
-/** The repositories a git command line names by -C, --git-dir or --work-tree (as given, unresolved). */
-function reposNamed(commandLine) {
-  const w = words(commandLine), out = [];
-  for (let i = 0; i < w.length; i += 1) {
-    if (w[i] === '-C' || w[i] === '--git-dir' || w[i] === '--work-tree') { if (w[i + 1]) { out.push(w[i + 1]); } i += 1; continue; }
-    const m = /^--(?:git-dir|work-tree)=(.+)$/.exec(w[i]);
-    if (m) out.push(m[1]);
-  }
-  return out;
-}
-
-/**
- * Whether one git process may hold `repo`'s index: 'this' (it names the repo or a path inside it), 'other'
- * (every repository it names is elsewhere) or 'unknown' (it names none; its cwd may be this repo).
- */
-export function processOnRepo(proc, repo) {
-  const named = reposNamed(proc?.commandLine);
-  if (!named.length) return 'unknown';
-  const key = pathKey(path.resolve(repo));
-  const hit = named.some((p) => { const k = pathKey(path.resolve(p)); return k === key || k.startsWith(`${key}/`) || key.startsWith(`${k}/`); });
-  return hit ? 'this' : 'other';
-}

package/runtime/scripts/lib/guard-command.mjs

@@ -1,24 +0,0 @@
-// guard-command.mjs — the one spelling of the hook command that registers a StarCi guard verb with an agent host.
-//
-// A host chooses the shell that runs a hook. The linked runtime supplies the absolute CLI path shared by launch trust
-// and preflight. Hook deadlines belong to the guard process; shell termination does not bound native children on Windows.
-import process from 'node:process';
-import path from 'node:path';
-import { readRuntimeRecord } from './runtime-location.mjs';
-
-const GUARD_COMMAND_END = /starci(?:\.mjs|\.cmd)?"? guard command$/;
-const quotedPath = (file) => `"${String(file).replaceAll('\\', '/')}"`;
-
-/** The command guard hook for the linked runtime; a missing or stale runtime record refuses registration. */
-export function toolGuardCommand({ home, nodePath = process.execPath, cliPath = null } = {}) {
-  if (!cliPath) {
-    const skipped = [];
-    const installed = readRuntimeRecord({ home, skipped });
-    if (!installed) throw new Error(skipped.join('; ') || 'no linked runtime; run starci runtime link');
-    cliPath = path.join(installed.root, 'packages', 'cli', 'bin', 'starci.mjs');
-  }
-  return `${quotedPath(nodePath)} ${quotedPath(cliPath)} guard command`;
-}
-
-/** Recognize the direct Node hook and launcher spellings so trust preparation replaces an older registered guard. */
-export const isGuardCommand = (command) => GUARD_COMMAND_END.test(String(command ?? ''));

package/runtime/scripts/lib/interrupt-cleanup.mjs

@@ -1,38 +0,0 @@
-// interrupt-cleanup.mjs - the one owner of "what a long verb leaves behind when it is interrupted". A verb that creates something outside its own return path (a lock, a temp file,
-// a container) registers the undo with `onInterrupt(undo)`; the undo runs when the process receives SIGINT, SIGTERM, SIGBREAK or SIGHUP (then the process exits with 128 + the signal number)
-// and when the process exits while the registration is still open, and never twice. The returned disposer removes the registration once the verb released the thing itself.
-// The process handlers are installed with the first registration and removed with the last. The registry takes the process as a seam (`proc`: on, off, exit).
-const SIGNALS = Object.freeze({ SIGHUP: 1, SIGINT: 2, SIGTERM: 15, SIGBREAK: 21 });
-
-/** A registry of undo functions bound to `proc`. */
-function createInterruptRegistry({ proc = process } = {}) {
-  const undos = new Set();
-  const handlers = new Map();
-
-  const runAll = () => {
-    for (const undo of [...undos].reverse()) {
-      undos.delete(undo);
-      try { undo(); } catch { /* one failing undo never stops the others */ }
-    }
-  };
-  const uninstall = () => {
-    for (const [event, handler] of handlers) proc.off(event, handler);
-    handlers.clear();
-  };
-  const install = () => {
-    if (handlers.size) return;
-    for (const [signal, number] of Object.entries(SIGNALS)) handlers.set(signal, () => { runAll(); uninstall(); proc.exit(128 + number); });
-    handlers.set('exit', runAll);
-    for (const [event, handler] of handlers) proc.on(event, handler);
-  };
-
-  /** Register `undo`; returns the disposer that removes it (and the process handlers when it was the last). */
-  const onInterrupt = (undo) => {
-    undos.add(undo);
-    install();
-    return () => { undos.delete(undo); if (!undos.size) uninstall(); };
-  };
-  return { onInterrupt, pending: () => undos.size };
-}
-
-export const { onInterrupt } = createInterruptRegistry();

package/runtime/scripts/lib/json-formats.mjs

@@ -1,34 +0,0 @@
-// json-formats.mjs - the JSON files whose format a tool requires, declared once by rule (a basename, a tool-fixed folder or a managed
-// fragment) and not file by file. A file of a listed format is not authored declarative source: npm, tsc, turbo, next-intl, Claude Code,
-// the stack tooling and Keycloak read it as JSON and nothing else, so no YAML or JS form of it exists. Everything else that is authored
-// config belongs in YAML, and the json-exceptions check (scripts/checks/check-json-exceptions.mjs) refuses it. Proven by the package spec
-// src/json-formats.spec.mjs over the bundled copy of this file.
-
-/** The base name of a slash path. */
-const baseOf = (rel) => rel.slice(rel.lastIndexOf('/') + 1);
-
-/**
- * The declared formats: `id`, the `tool` that fixes the format and a `match(rel)` over a skill-relative slash path. A format names a
- * kind of file (a base name or a folder the tool reads by position), never one path of this repository.
- */
-export const JSON_FORMATS = Object.freeze([
-  { id: 'npm-manifest', tool: 'npm', match: (rel) => baseOf(rel) === 'package.json' || baseOf(rel) === 'package-lock.json' },
-  { id: 'typescript-config', tool: 'tsc', match: (rel) => /^tsconfig(\.[A-Za-z0-9-]+)*\.json$/.test(baseOf(rel)) },
-  { id: 'shared-tsconfig-preset', tool: 'tsc (extends)', match: (rel) => /^packages\/tsconfig\/[^/]+\.json$/.test(rel) },
-  { id: 'turbo-pipeline', tool: 'turbo', match: (rel) => baseOf(rel) === 'turbo.json' },
-  { id: 'nest-cli', tool: '@nestjs/cli', match: (rel) => baseOf(rel) === 'nest-cli.json' },
-  { id: 'tree-kind', tool: 'starci hfs (hfs.json at a tree root)', match: (rel) => baseOf(rel) === 'hfs.json' },
-  { id: 'claude-code-settings', tool: 'Claude Code', match: (rel) => /(^|\/)\.claude\/settings\.json$/.test(rel) },
-  { id: 'i18n-message-catalog', tool: 'next-intl', match: (rel) => /(^|\/)modules\/i18n\/messages\/[a-z]{2}(-[A-Za-z]+)?\.json$/.test(rel) },
-  { id: 'stack-environment', tool: 'starci stack (.starcistacks layout)', match: (rel) => /(^|\/)\.starcistacks\/[^/]+\/environment\.json$/.test(rel) },
-  { id: 'stack-infra-metadata', tool: 'starci stack (.starcistacks layout)', match: (rel) => /(^|\/)\.starcistacks\/[^/]+\/infra\/metadata\.json$/.test(rel) },
-  { id: 'keycloak-realm-import', tool: 'Keycloak realm import', match: (rel) => /(^|\/)\.starcistacks\/[^/]+\/infra\/compose\/realm-[^/]+\.json$/.test(rel) },
-  { id: 'package-scripts-fragment', tool: 'npm (scripts rendered into package.json)', match: (rel) => /^packages\/hfs\/templates\/app\/package-scripts[^/]*\/[^/]+\.json$/.test(rel) },
-  { id: 'async-event-contract', tool: 'starci app emit', match: (rel) => /(^|\/)be\/contracts\/[^/]+\/events(\.pin)?\.json$/.test(rel) },
-  { id: 'operation-contract', tool: 'starci app emit', match: (rel) => /(^|\/)be\/contracts\/[^/]+\/openapi\.json$/.test(rel) },
-]);
-
-/** The declared format that fixes `rel`, or null: the file is authored JSON the check must refuse. */
-export function jsonFormatOf(rel) {
-  return JSON_FORMATS.find((format) => format.match(rel)) ?? null;
-}