@starci/hfs 4.0.9 → 4.1.0

package/runtime/scripts/hfs/sql/pg-parse.mjs

@@ -37,8 +37,11 @@ export async function parsePlpgsqlBody(body, parameters = [], returnKind = 'void
   let tag = `$hfs_probe_${i}$`;
   while (body.includes(tag)) { i += 1; tag = `$hfs_probe_${i}$`; }
   const args = parameters.map((parameter) => parameter?.FunctionParameter?.name).filter(Boolean)
-    .map((name) => `"${name.replace(/"/g, '""')}" text`).join(', ');
-  const returns = returnKind === 'setof' ? 'setof text' : returnKind === 'trigger' ? 'trigger' : returnKind === 'scalar' ? 'text' : 'void';
+    .map((name) => `"${name.replaceAll('"', '""')}" text`).join(', ');
+  let returns = 'void';
+  if (returnKind === 'setof') returns = 'setof text';
+  else if (returnKind === 'trigger') returns = 'trigger';
+  else if (returnKind === 'scalar') returns = 'text';
   const result = await (await loadPgParser()).parsePlPgSQLSync(
     `create function hfs_probe(${args}) returns ${returns} language plpgsql as ${tag}${body}${tag};`,
   );

package/runtime/scripts/hfs/trailing-slashes.mjs

@@ -0,0 +1,8 @@
+// Trailing-slash trimming for slot paths and generated roots, linear in the length of the text.
+
+/** `text` without its trailing `/` characters. */
+export function trimTrailingSlashes(text) {
+  let end = text.length;
+  while (end > 0 && text.codePointAt(end - 1) === 47) end -= 1;
+  return text.slice(0, end);
+}

package/runtime/scripts/hfs/tree.mjs

@@ -49,6 +49,24 @@ export function readTree(repoRoot, { isIgnored }) {
 const holdsNoFile = (node) => node.files === 0 && node.dirs.every(holdsNoFile);
 const countDirs = (node) => node.dirs.reduce((sum, child) => sum + 1 + countDirs(child), 0);
 
+function collectGhosts(node, ghosts) {
+  for (const [i, a] of node.dirs.entries()) {
+    for (const b of node.dirs.slice(i + 1)) {
+      if (editDistance(a.name, b.name) > GHOST_DISTANCE) continue;
+      if (holdsNoFile(a)) ghosts.push({ path: a.rel, of: b.rel, distance: editDistance(a.name, b.name) });
+      if (holdsNoFile(b)) ghosts.push({ path: b.rel, of: a.rel, distance: editDistance(a.name, b.name) });
+    }
+  }
+}
+
+function collectTreeFacts(node, empty, ghosts) {
+  for (const child of node.dirs) {
+    if (holdsNoFile(child)) empty.push({ path: child.rel, below: countDirs(child) });
+    else collectTreeFacts(child, empty, ghosts);
+  }
+  collectGhosts(node, ghosts);
+}
+
 /**
  * The tree's own findings: `empty` are the topmost directories with no file anywhere below them (each with the number of
  * directories it holds); `ghosts` are pairs of sibling directories within GHOST_DISTANCE edits where `ghost` has no file
@@ -57,20 +75,7 @@ const countDirs = (node) => node.dirs.reduce((sum, child) => sum + 1 + countDirs
 export function treeFacts(tree) {
   const empty = [];
   const ghosts = [];
-  const visit = (node) => {
-    for (const child of node.dirs) {
-      if (holdsNoFile(child)) empty.push({ path: child.rel, below: countDirs(child) });
-      else visit(child);
-    }
-    for (const [i, a] of node.dirs.entries()) {
-      for (const b of node.dirs.slice(i + 1)) {
-        if (editDistance(a.name, b.name) > GHOST_DISTANCE) continue;
-        if (holdsNoFile(a)) ghosts.push({ path: a.rel, of: b.rel, distance: editDistance(a.name, b.name) });
-        if (holdsNoFile(b)) ghosts.push({ path: b.rel, of: a.rel, distance: editDistance(a.name, b.name) });
-      }
-    }
-  };
-  visit(tree);
+  collectTreeFacts(tree, empty, ghosts);
   return { empty, ghosts };
 }
 

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

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { createRequire } from 'node:module';
 import path from 'node:path';
+import { byCodeUnit } from '../lib/list.mjs';
 
 // One TypeScript program per (compiler, root names, compiler options, project references) inside a program run, and
 // one value per (kind, compiler, input) for what callers derive from those programs (the architecture context).
@@ -27,7 +27,7 @@ function keyOf(value) {
   }
   if (typeof value !== 'object' || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) return null;
   const entries = [];
-  for (const name of Object.keys(value).sort()) {
+  for (const name of Object.keys(value).sort(byCodeUnit)) {
     const item = keyOf(value[name]);
     if (item === null) return null;
     entries.push(`${JSON.stringify(name)}:${item}`);
@@ -44,7 +44,10 @@ export function sharedInProgramRun(kind, ts, input, build) {
   const key = values ? keyOf(input) : null;
   if (key === null) return build();
   let byKey = values.get(ts);
-  if (!byKey) values.set(ts, byKey = new Map());
+  if (!byKey) {
+    byKey = new Map();
+    values.set(ts, byKey);
+  }
   const id = `${kind}\0${key}`;
   if (!byKey.has(id)) byKey.set(id, build());
   return byKey.get(id);
@@ -74,4 +77,3 @@ export function typeScriptProjectReferencePath(ts, reference) {
 export function resolveTypeScriptModule(ts, specifier, from, options, host = ts.sys) {
   return ts.resolveModuleName(specifier, from, options, host).resolvedModule?.resolvedFileName;
 }
-

package/runtime/scripts/hfs/view.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { allowsFile } from './allows.mjs';
 import { openHfs } from './slots.mjs';
 
-const posix = (p) => String(p).replace(/\\/g, '/');
+const posix = (p) => String(p).replaceAll('\\', '/');
 const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(text);
 
 /**

package/runtime/scripts/lib/dockerfile.mjs

@@ -58,8 +58,8 @@ export function shellCommands(body) {
     } else if (char === '"' || char === "'") {
       quote = char;
       current += char;
-    } else if (char === ';' || char === '|' || (char === '&' && body[i + 1] === '&')) {
-      if (char !== ';' && body[i + 1] === char) i += 1;
+    } else if (isCommandSeparator(body, i, char)) {
+      i += commandSeparatorAdvance(body, i, char);
       flush();
     } else if (char === '\\' && body[i + 1] === '\n') {
       i += 1;
@@ -71,43 +71,17 @@ export function shellCommands(body) {
   return commands;
 }
 
+const isCommandSeparator = (body, index, char) => char === ';' || char === '|' || (char === '&' && body[index + 1] === '&');
+const commandSeparatorAdvance = (body, index, char) => char !== ';' && body[index + 1] === char ? 1 : 0;
+
 /**
  * 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 lines = String(source).replaceAll('\r\n', '\n').split('\n');
+  const { instructions, comments } = parseInstructions(lines);
   const stages = [];
   const preamble = [];
   for (const instruction of instructions) {
@@ -122,3 +96,52 @@ export function parseDockerfile(source) {
   }
   return { instructions, stages, comments, preamble };
 }
+
+function parseInstructions(lines) {
+  const instructions = [];
+  const comments = [];
+  const state = { escape: '\\', directives: true };
+  let i = 0;
+  while (i < lines.length) {
+    const parsed = parseInstructionLine(lines, i, state);
+    if (parsed.comment) comments.push(parsed.comment);
+    if (parsed.instruction) instructions.push(parsed.instruction);
+    i = parsed.nextLine + 1;
+  }
+  return { instructions, comments };
+}
+
+function parseInstructionLine(lines, index, state) {
+  const trimmed = lines[index].trim();
+  if (trimmed === '') { state.directives = false; return { nextLine: index }; }
+  if (trimmed.startsWith('#')) return parseCommentLine(trimmed, index, state);
+  state.directives = false;
+  const { logical, nextLine } = logicalInstructionOf(lines, index, state.escape);
+  const split = logical.search(/\s/);
+  const keyword = (split < 0 ? logical : logical.slice(0, split)).toUpperCase();
+  return { nextLine, instruction: { keyword, text: split < 0 ? '' : logical.slice(split).trim(), line: index + 1, stage: -1 } };
+}
+
+function parseCommentLine(trimmed, index, state) {
+  const body = trimmed.slice(1).trim();
+  const directive = state.directives ? /^(syntax|escape|check)\s*=\s*(\S+)$/i.exec(body) : null;
+  if (directive) {
+    if (directive[1].toLowerCase() === 'escape') state.escape = directive[2];
+    return { nextLine: index };
+  }
+  state.directives = false;
+  return { nextLine: index, comment: { text: body, line: index + 1 } };
+}
+
+function logicalInstructionOf(lines, index, escape) {
+  let logical = lines[index].trim();
+  let nextLine = index;
+  while (logical.endsWith(escape) && nextLine + 1 < lines.length) {
+    logical = logical.slice(0, -1).trimEnd();
+    nextLine += 1;
+    while (nextLine < lines.length && lines[nextLine].trim().startsWith('#')) nextLine += 1;
+    if (nextLine >= lines.length) break;
+    logical = `${logical} ${lines[nextLine].trim()}`;
+  }
+  return { logical, nextLine };
+}

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

@@ -8,7 +8,8 @@
 //   }
 // `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.
+// syntax tree. The functions take the `ts` module the caller loaded (the repository's own, else the runtime's); this file imports only the code-unit comparator.
+import { byCodeUnit } from './list.mjs';
 
 const EVENT_CONTRACT_SCHEMA = 'starci/event-contract@1';
 const FIELD_TYPE = /^(?:string|number|boolean|string\[\]|number\[\])\??$/;
@@ -37,6 +38,18 @@ function fieldType(ts, node) {
   return null;
 }
 
+function appendPayloadMember(ts, member, typeName, problems, where, payload) {
+  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\``);
+    return;
+  }
+  const type = fieldType(ts, member.type);
+  let written = null;
+  if (type !== null) written = `${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;
+}
+
 /** 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;
@@ -49,16 +62,7 @@ function payloadOf(ts, sourceFile, typeName, problems, where) {
     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;
-  }
+  for (const member of members) appendPayloadMember(ts, member, typeName, problems, where, payload);
   return payload;
 }
 
@@ -91,7 +95,7 @@ export function readEventClasses(ts, text, file = 'event.ts') {
 }
 
 /** 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);
+const sorted = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.keys(value).sort(byCodeUnit).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) {
@@ -100,4 +104,4 @@ export function snapshotText(service, events) {
 }
 
 /** 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');
+export const folded = (text) => text.replaceAll('\r\n', '\n');

package/runtime/scripts/lib/fs-kind.mjs

@@ -2,9 +2,19 @@
 // A missing or unreadable path is false/null, never a throw; the stat syscall decides kind.
 import fs from 'node:fs';
 
-/** `p` names a file; false on any stat error (missing path, dangling link, EPERM). */
-export const isFile = (p) => { try { return fs.statSync(p).isFile(); } catch { return false; } };
-/** `p` names a directory; false on any stat error. */
-export const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+/** `p` names a file within `maxBytes`; false on any stat error. `followLinks: false` probes the entry itself. */
+export const isFile = (p, { followLinks = true, maxBytes = Infinity } = {}) => {
+  try {
+    const stat = followLinks ? fs.statSync(p) : fs.lstatSync(p);
+    return stat.isFile() && (followLinks || !stat.isSymbolicLink()) && stat.size <= maxBytes;
+  } catch { return false; }
+};
+/** `p` names a directory; false on any stat error. `followLinks: false` refuses linked entries. */
+export const isDir = (p, { followLinks = true } = {}) => {
+  try {
+    const stat = followLinks ? fs.statSync(p) : fs.lstatSync(p);
+    return stat.isDirectory() && (followLinks || !stat.isSymbolicLink());
+  } catch { return false; }
+};
 /** `p`'s canonical spelling via the filesystem (links resolved), or null when it cannot be read. */
 export const realpathOr = (p) => { try { return fs.realpathSync.native(p); } catch { return null; } };

package/runtime/scripts/lib/git.mjs

@@ -7,13 +7,13 @@
  */
 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')}`))
+    ? JSON.parse(value.replace(/\\([0-7]{3})/g, (_, octal) => String.raw`\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'];
+export const GIT_LOCAL_ENV_VARS = ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_IMPLICIT_WORK_TREE', 'GIT_PREFIX', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG_COUNT', 'GIT_GRAFT_FILE', 'GIT_NO_REPLACE_OBJECTS', 'GIT_REPLACE_REF_BASE', 'GIT_SHALLOW_FILE', 'GIT_INTERNAL_SUPER_PREFIX'];
 /** `parent` (the caller's env) without git's repository-local variables (GIT_CONFIG_KEY_n/VALUE_n go with GIT_CONFIG_COUNT). Pure. */
 export function withoutGitLocalEnv(parent) {
   const env = { ...parent };