@starci/hfs 4.0.7 → 4.0.9

package/runtime/scripts/{checks → hfs}/typescript-programs.mjs

@@ -75,8 +75,3 @@ export function resolveTypeScriptModule(ts, specifier, from, options, host = ts.
   return ts.resolveModuleName(specifier, from, options, host).resolvedModule?.resolvedFileName;
 }
 
-/** Configuration imports prefer Node's package resolution, then the selected TypeScript project. */
-export function resolveNodeOrTypeScriptModule(ts, specifier, from, options, host = ts.sys) {
-  try { return createRequire(from).resolve(specifier); }
-  catch { return resolveTypeScriptModule(ts, specifier, from, options, host); }
-}

package/runtime/scripts/{lib/hfs-view.mjs → hfs/view.mjs}

@@ -1,10 +1,10 @@
 // hfs-view.mjs - the frozen view of one side of an app (be/ or fe/, the side folder as its root) that the lint factories hand
 // their rules (`settings.starci.hfs`). Both @starci/eslint-canon-be and @starci/eslint-canon-fe ship a byte copy of this file in their
-// runtime/ bundle (packages/hfs/scripts/sync-runtime.mjs), so a path-scoped rule in either package asks the SAME resolver the
-// architecture machine and `hfs check` use, and never tests a path with a regular expression of its own.
+// runtime/ bundle (scripts/hfs/sync-runtime.mjs), so a path-scoped rule in either package asks the SAME resolver the
+// architecture machine and `starci app check` use, and never tests a path with a regular expression of its own.
 import path from 'node:path';
-import { allowsFile } from './hfs-allows.mjs';
-import { openHfs } from './hfs-slots.mjs';
+import { allowsFile } from './allows.mjs';
+import { openHfs } from './slots.mjs';
 
 const posix = (p) => String(p).replace(/\\/g, '/');
 const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(text);
@@ -16,7 +16,7 @@ const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(tex
  * @param {string} repoRoot - The absolute repository root.
  * @returns {object} The frozen view: profile, apps, connections, ruleParams, relative, classify, slotOf, tierOf, ownerOf, slot.
  */
-export function hfsView(opened, repoRoot) {
+function hfsView(opened, repoRoot) {
   const rel = (file) => {
     const text = posix(file);
     if (!isAbsoluteAny(text)) return text.replace(/^\.\//, '');
@@ -32,6 +32,7 @@ export function hfsView(opened, repoRoot) {
     repoRoot,
     profile: opened.repo.profile,
     side: opened.repo.side ?? null,
+    edition: opened.repo.edition ?? 'full',
     apps: opened.repo.apps,
     connections: opened.repo.connections,
     ruleParams: opened.ruleParams(),

package/runtime/scripts/lib/dockerfile.mjs

@@ -0,0 +1,124 @@
+// dockerfile.mjs - a Dockerfile read by its own grammar (no regular-expression matching of instruction names inside the text):
+// one statement per logical line (a trailing backslash continues it, comment lines inside a continuation are dropped), the
+// instruction keyword is the first word, the stages open at each FROM. Parser directives (`# syntax=`, `# escape=`) and
+// comments are kept apart from the instructions. Here-documents are not part of the subset the canon uses and are read as text.
+
+/** Split a shell-form or exec-form argument string into its words (quotes group a word and are removed). */
+export function 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 (char === ' ' || char === '\t' || char === '\n') {
+      if (started || current) out.push(current);
+      current = '';
+      started = false;
+    } else {
+      current += char;
+    }
+  }
+  if (started || current) out.push(current);
+  return out;
+}
+
+/** The exec-form array of an instruction's argument text (`["node", "x.js"]`), or null when it is not a JSON array of strings. */
+export function execForm(text) {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith('[')) return null;
+  try {
+    const value = JSON.parse(trimmed);
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The commands of a shell-form RUN body: the text split at `&&`, `||`, `;` and `|` outside quotes, each as its words. */
+export function shellCommands(body) {
+  const commands = [];
+  let current = '';
+  let quote = null;
+  const flush = () => {
+    const parts = words(current);
+    if (parts.length) commands.push(parts);
+    current = '';
+  };
+  for (let i = 0; i < body.length; i += 1) {
+    const char = body[i];
+    if (quote) {
+      current += char;
+      if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      current += char;
+    } else if (char === ';' || char === '|' || (char === '&' && body[i + 1] === '&')) {
+      if (char !== ';' && body[i + 1] === char) i += 1;
+      flush();
+    } else if (char === '\\' && body[i + 1] === '\n') {
+      i += 1;
+    } else {
+      current += char;
+    }
+  }
+  flush();
+  return commands;
+}
+
+/**
+ * Parse a Dockerfile: { instructions: [{ keyword, text, line, stage }], stages: [{ index, name, image, line, instructions }],
+ * comments: [{ text, line }], preamble: [instruction before the first FROM (ARG)] }. `keyword` is upper-case; `text` is the
+ * argument text of the logical line; `stage` is the index of the stage the instruction belongs to (-1 before the first FROM).
+ */
+export function parseDockerfile(source) {
+  const lines = String(source).replace(/\r\n/g, '\n').split('\n');
+  const instructions = [];
+  const comments = [];
+  let escape = '\\';
+  let directives = true;
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    if (trimmed === '') { directives = false; continue; }
+    if (trimmed.startsWith('#')) {
+      const body = trimmed.slice(1).trim();
+      const directive = directives ? /^(syntax|escape|check)\s*=\s*(\S+)$/i.exec(body) : null;
+      if (directive) { if (directive[1].toLowerCase() === 'escape') escape = directive[2]; continue; }
+      directives = false;
+      comments.push({ text: body, line: i + 1 });
+      continue;
+    }
+    directives = false;
+    const start = i + 1;
+    let logical = trimmed;
+    while (logical.endsWith(escape) && i + 1 < lines.length) {
+      logical = logical.slice(0, -1).trimEnd();
+      i += 1;
+      while (i < lines.length && lines[i].trim().startsWith('#')) i += 1;
+      if (i >= lines.length) break;
+      logical = `${logical} ${lines[i].trim()}`;
+    }
+    const split = logical.search(/\s/);
+    const keyword = (split < 0 ? logical : logical.slice(0, split)).toUpperCase();
+    instructions.push({ keyword, text: split < 0 ? '' : logical.slice(split).trim(), line: start, stage: -1 });
+  }
+  const stages = [];
+  const preamble = [];
+  for (const instruction of instructions) {
+    if (instruction.keyword === 'FROM') {
+      const parts = words(instruction.text).filter((part) => !part.startsWith('--'));
+      const asAt = parts.findIndex((part, index) => index > 0 && part.toUpperCase() === 'AS');
+      stages.push({ index: stages.length, name: asAt > 0 ? parts[asAt + 1] ?? null : null, image: parts[0] ?? '', line: instruction.line, instructions: [] });
+    }
+    instruction.stage = stages.length - 1;
+    if (stages.length) stages.at(-1).instructions.push(instruction);
+    else preamble.push(instruction);
+  }
+  return { instructions, stages, comments, preamble };
+}

package/runtime/scripts/lib/env.mjs

@@ -0,0 +1,10 @@
+// env.mjs - the one place the runtime reads a named environment variable (smell S8-01/S8-02/S11-04; scripts/checks/check-env.mjs).
+// modules/schemas/env.yaml catalogues every variable with its purpose and kind. Production code reads a variable here
+// (readEnv) or takes an injected `env` parameter; it never reads `process.env.NAME` itself. The test runner is observed
+// in exactly one place, isSpecRun: code that must not touch the host's real state during a spec asks it.
+
+/** The value of the environment variable `name` in `env` (default: the process environment), or undefined. */
+export const readEnv = (name, env = process.env) => env[name];
+
+/** True when `env` (default: the process environment) belongs to a spec run (`node --test` marks its children with NODE_TEST_CONTEXT). */
+export const isSpecRun = (env = process.env) => Boolean(env.NODE_TEST_CONTEXT);

package/runtime/scripts/lib/event-contract.mjs

@@ -0,0 +1,103 @@
+// event-contract.mjs - the async contract between the services of one product (R166 HFS_EVENT_CONTRACT).
+// The one source of the contract is the typed event classes of a service, `be/src/modules/events/<service>/<event>.event.ts`:
+//   export interface OrderPlacedPayload { readonly orderId: string; readonly totalMinorUnits: number }
+//   export class OrderPlacedEvent extends BaseEvent {
+//     static readonly eventName = "order.placed"; static readonly version = 1
+//     static readonly compensates = "order.placed"            // only an event that reports the failure of a step
+//     static create(payload: OrderPlacedPayload): OrderPlacedEvent { ... }
+//   }
+// `starci app emit` writes `be/contracts/<service>/events.json` from them (name, version, compensates, and the payload fields of the
+// interface `create` takes); `starci app check` compares the committed file with the same reader. Nothing is executed: both walk the TypeScript
+// syntax tree. The functions take the `ts` module the caller loaded (the repository's own, else the runtime's); this file imports nothing.
+
+const EVENT_CONTRACT_SCHEMA = 'starci/event-contract@1';
+const FIELD_TYPE = /^(?:string|number|boolean|string\[\]|number\[\])\??$/;
+
+const hasStatic = (ts, member) => member.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword) === true;
+
+/** The literal of a `static readonly <name> = <literal>` member: `{ text }` for a string, `{ number }` for an integer, or null. */
+function staticLiteral(ts, member) {
+  if (!ts.isPropertyDeclaration(member) || !hasStatic(ts, member) || !ts.isIdentifier(member.name) || member.initializer === undefined) return null;
+  let value = member.initializer;
+  while (ts.isAsExpression(value) || ts.isParenthesizedExpression(value)) value = value.expression;
+  if (ts.isStringLiteralLike(value)) return { name: member.name.text, text: value.text };
+  if (ts.isNumericLiteral(value) && Number.isInteger(Number(value.text))) return { name: member.name.text, number: Number(value.text) };
+  return null;
+}
+
+/** The text of a type node when it is one of the wire field types (`string`, `number`, `boolean`, `string[]`, `number[]`), else null. */
+function fieldType(ts, node) {
+  if (node.kind === ts.SyntaxKind.StringKeyword) return 'string';
+  if (node.kind === ts.SyntaxKind.NumberKeyword) return 'number';
+  if (node.kind === ts.SyntaxKind.BooleanKeyword) return 'boolean';
+  if (ts.isArrayTypeNode(node)) {
+    const element = fieldType(ts, node.elementType);
+    return element === 'string' || element === 'number' ? `${element}[]` : null;
+  }
+  return null;
+}
+
+/** The payload fields of the interface or type literal named `typeName` in the file: `{ <field>: <type> }`, optional fields with a `?`. */
+function payloadOf(ts, sourceFile, typeName, problems, where) {
+  let members = null;
+  for (const statement of sourceFile.statements) {
+    if (ts.isInterfaceDeclaration(statement) && statement.name.text === typeName) members = statement.members;
+    if (ts.isTypeAliasDeclaration(statement) && statement.name.text === typeName && ts.isTypeLiteralNode(statement.type)) members = statement.type.members;
+  }
+  if (members === null) {
+    problems.push(`${where}: the payload type ${typeName} is not an interface or type literal of the file`);
+    return {};
+  }
+  const payload = {};
+  for (const member of members) {
+    if (!ts.isPropertySignature(member) || !ts.isIdentifier(member.name) || member.type === undefined) {
+      problems.push(`${where}: the payload ${typeName} holds a member that is not \`name: type\``);
+      continue;
+    }
+    const type = fieldType(ts, member.type);
+    const written = type === null ? null : `${type}${member.questionToken ? '?' : ''}`;
+    if (written === null || !FIELD_TYPE.test(written)) problems.push(`${where}: payload field ${member.name.text} must be string, number, boolean, string[] or number[]`);
+    else payload[member.name.text] = written;
+  }
+  return payload;
+}
+
+/**
+ * The event classes of one source text: `{ events: [{ className, name, version, compensates, payload }], problems: [text] }`. A class is an event
+ * when it declares `static readonly eventName`; `version` is required, `create(payload: <Interface>)` names the payload.
+ */
+export function readEventClasses(ts, text, file = 'event.ts') {
+  const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const events = [];
+  const problems = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts.isClassDeclaration(statement) || statement.name === undefined) continue;
+    const literals = statement.members.map((member) => staticLiteral(ts, member)).filter((literal) => literal !== null);
+    const name = literals.find((literal) => literal.name === 'eventName')?.text;
+    if (name === undefined) continue;
+    const className = statement.name.text;
+    const version = literals.find((literal) => literal.name === 'version')?.number;
+    const compensates = literals.find((literal) => literal.name === 'compensates')?.text;
+    if (version === undefined || version < 1) problems.push(`${className} needs \`static readonly version\` as a positive integer`);
+    const create = statement.members.find((member) => ts.isMethodDeclaration(member) && hasStatic(ts, member) && ts.isIdentifier(member.name) && member.name.text === 'create');
+    const parameter = create?.parameters[0]?.type;
+    if (parameter === undefined || !ts.isTypeReferenceNode(parameter) || !ts.isIdentifier(parameter.typeName)) {
+      problems.push(`${className} needs \`static create(payload: <Interface>)\` naming its payload interface`);
+      continue;
+    }
+    events.push({ className, name, version: version ?? 0, ...(compensates === undefined ? {} : { compensates }), payload: payloadOf(ts, sourceFile, parameter.typeName.text, problems, className) });
+  }
+  return { events, problems };
+}
+
+/** The sorted object: keys in code-point order, recursively (what the snapshot prints). */
+const sorted = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])])) : value);
+
+/** The text of the snapshot of a service from its event classes: 2-space JSON, sorted keys, one final newline. */
+export function snapshotText(service, events) {
+  const table = Object.fromEntries(events.map(({ name, version, compensates, payload }) => [name, { version, payload, ...(compensates === undefined ? {} : { compensates }) }]));
+  return `${JSON.stringify(sorted({ schema: EVENT_CONTRACT_SCHEMA, service, events: table }), null, 2)}\n`;
+}
+
+/** The snapshot's text with line endings folded, for comparing a committed file to a fresh one. */
+export const folded = (text) => text.replace(/\r\n/g, '\n');

package/runtime/scripts/lib/git.mjs

@@ -0,0 +1,36 @@
+// git.mjs — pure helpers over git's text output, spawn results and env. The git spawn itself lives in scripts/api/git/ (lib.mjs and its call files).
+
+/**
+ * git's C-quoted diff path decoded - `"b\303\251"` a `+++ ` header line prints when core.quotePath
+ * covers the name. Octal escapes become \u00XX for JSON.parse (which answers \n, \t, \" and \\);
+ * a value not wrapped in quotes passes through unchanged.
+ */
+export const unquoteDiffPath = (value) =>
+  /^".*"$/.test(value)
+    ? JSON.parse(value.replace(/\\([0-7]{3})/g, (_, octal) => `\\u00${Number.parseInt(octal, 8).toString(16).padStart(2, '0')}`))
+    : value;
+
+// git's repository-local variables (git rev-parse --local-env-vars). A hook or alias run in a linked worktree exports
+// GIT_DIR=<main>/.git/worktrees/<wt>; a spec inheriting it pointed every fixture git at the LIVE .claude repo and re-inited
+// it core.bare=true (2026-09-29, a6f60352c). tests/setup/isolated-registry.mjs drops the same list.
+export const GIT_LOCAL_ENV_VARS = ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_IMPLICIT_WORK_TREE', 'GIT_PREFIX', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG_COUNT', 'GIT_GRAFT_FILE', 'GIT_NO_REPLACE_OBJECTS', 'GIT_REPLACE_REF_BASE', 'GIT_SHALLOW_FILE'];
+/** `parent` (the caller's env) without git's repository-local variables (GIT_CONFIG_KEY_n/VALUE_n go with GIT_CONFIG_COUNT). Pure. */
+export function withoutGitLocalEnv(parent) {
+  const env = { ...parent };
+  for (const key of Object.keys(env)) if (GIT_LOCAL_ENV_VARS.includes(key) || /^GIT_CONFIG_(KEY|VALUE)_\d+$/.test(key)) delete env[key];
+  return env;
+}
+
+/** A git spawn result (a scripts/api/git call file's) as {ok, stdout, error}: ok only on a clean exit, error from stderr or the spawn. Pure. */
+export const gitResultOf = (r) => ({
+  ok: !r.error && r.status === 0,
+  stdout: r.stdout ?? '',
+  error: (r.stderr ?? '').trim() || String(r.error?.message ?? (r.status == null ? 'timed out' : `exit ${r.status}`)),
+});
+
+/** A git spawn result's stdout text; throws the spawn error, or an Error naming `what` with git's stderr and exit status, unless git exited 0. Pure. */
+export function gitOutputOf(r, what = 'git') {
+  if (r.error) throw r.error;
+  if (r.status !== 0) throw Object.assign(new Error(`${what} exited ${r.status}: ${(r.stderr ?? '').trim()}`), { status: r.status, stderr: r.stderr });
+  return r.stdout;
+}