@starci/hfs 4.11.21 → 4.12.0

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

@@ -1,22 +1,34 @@
 // event-items.mjs - the open items of an owed/resolved event pair, replayed from a workflow ledger (read only).
-
 /**
  * The workflow's open items of an owed/resolved event pair (grammar proposals, asset slots): replay the kinds in seq
  * order — a `resolvedKind` row deletes the item `keyOf` names, an `owedKind` row sets `item(payload,row)`; a row
  * whose key is falsy is skipped. Returns the open items in first-seen order, [] when the table cannot be read.
  */
-export function openEventItems(db,workflowId,{owedKind,resolvedKind,keyOf,item}){
-  let rows=[];
-  try{rows=db.prepare('SELECT kind,payload_json,created_at FROM events WHERE workflow_id=? AND kind IN (?,?) ORDER BY seq').all(workflowId,owedKind,resolvedKind);}
-  catch{return[];}
-  const open=new Map();
-  for(const row of rows){
-    let p={};
-    try{p=JSON.parse(row.payload_json??'{}')??{};}catch{p={};}
-    const key=keyOf(p);
-    if(!key)continue;
-    if(row.kind===resolvedKind){open.delete(key);continue;}
-    open.set(key,item(p,row));
-  }
-  return[...open.values()];
+export function openEventItems(db, workflowId, { owedKind, resolvedKind, keyOf, item }) {
+    let rows = [];
+    try {
+        rows = db.prepare('SELECT kind,payload_json,created_at FROM events WHERE workflow_id=? AND kind IN (?,?) ORDER BY seq').all(workflowId, owedKind, resolvedKind);
+    }
+    catch {
+        return [];
+    }
+    const open = new Map();
+    for (const row of rows) {
+        let p = {};
+        try {
+            p = JSON.parse(row.payload_json ?? '{}') ?? {};
+        }
+        catch {
+            p = {};
+        }
+        const key = keyOf(p);
+        if (!key)
+            continue;
+        if (row.kind === resolvedKind) {
+            open.delete(key);
+            continue;
+        }
+        open.set(key, item(p, row));
+    }
+    return [...open.values()];
 }

package/runtime/scripts/lib/example-refs.d.mts

@@ -0,0 +1,69 @@
+/** One row of the example catalog (examples/index.yaml). */
+export interface ExampleRow {
+    id: string;
+    path: string;
+    entrypoint: string;
+    files: string[];
+    projects: string[];
+    tests: string[];
+    relatedRules: string[];
+}
+/** The example catalog document. */
+export interface ExampleCatalog {
+    examples: ExampleRow[];
+}
+/** The runtime's example tree root. */
+export declare const EXAMPLES_ROOT = "examples";
+/** Curated basic sample source; operational artifact writers remain external. */
+export declare const EXAMPLE_RUNTIMES_ROOT = "examples/.runtimes";
+/** Every examples/<name>/hfs.json declaration of kind app, sorted by name. */
+export declare function discoverExampleApps(root: string): string[];
+/** The example apps that declare a browser journey (hfs.json `browser: true`, the opt-in slot app.browser-config), sorted by name: the matrix of the examples workflow's browser job. */
+export declare function discoverBrowserExampleApps(root: string): string[];
+/** The generic services-block template a starcistacks follow-up leg is pointed at (S11-02: one template
+ *  for every repository). */
+export declare const STACK_DECLARATION_TEMPLATE = "examples/starcistacks-services/template.services.yaml";
+/** The reference app declaration scripts/hfs/derived-fields.mjs samples for per-field slot ownership. */
+export declare const REFERENCE_APP_MANIFEST = "examples/full-app/hfs.json";
+/** The example app whose installed tree an fe-kit peer link points at by default. */
+export declare const REFERENCE_EXAMPLE_APP = "full-app";
+/** The grammar css families a product repository may declare (`[data-grammar-family="<id>"]`), keyed by the
+ *  canonical catalog id; the runtime's own product maps to the core sheet. */
+export declare const GRAMMAR_FAMILIES: Readonly<{
+    core: "core";
+    nivo: "nivo";
+    'offset-pop': "offset-pop";
+}>;
+/** A css family key through the Grammar catalog's alias table (`starci` reads as `core`); an id the catalog does not declare is kept. */
+export declare function grammarCssFamilyKey(family: string): string;
+export declare function grammarCssFamilyKey(family: unknown): unknown;
+/** A feature-folder segment that is only the product's own name - no useful leaf (display-names pathLabel). */
+export declare const PRODUCT_NAME_SEGMENT: RegExp;
+/** The closed list of product names this runtime shipped against - the names R206
+ *  (check-example-coupling.mjs) refuses anywhere in runtime source outside this file. */
+export declare const PRODUCT_NAMES: readonly string[];
+/** The catalog of stable pattern IDs pointing at actual executable example source. */
+export declare const EXAMPLE_CATALOG_FILE = "examples/index.yaml";
+/** Source, compiler and test inputs of selected stable IDs, relative to the runtime.
+ * A null selection requests the declared whole catalog; unknown IDs refuse. */
+export declare function exampleSourcePaths(root: string, ids?: Iterable<string> | null, options?: {
+    file?: string;
+}): string[];
+/** Actual example apps' own Work trees in app-name order. Dependency/template
+ * trees are not app Work; an absent own tree contributes no checker input. */
+export declare function exampleWorkRoots(root: string): string[];
+/**
+ * The runtime checkout that holds `workRoot` when it is one of that checkout's example Work trees
+ * (`<checkout>/examples/<app>/.starciwork` beside `<checkout>/examples/.runtimes`), else null. An example is judged against its
+ * own checkout's fixture store: a lane's example by the lane's store, whichever runtime runs the check (the shared pre-commit hook
+ * runs the canonical runtime over a lane's staged files).
+ */
+export declare function exampleCheckoutOf(workRoot: unknown): string | null;
+/** Per-call READ options for an actual HFS app's own Work tree. A real project
+ * uses the default external store; an example never falls back to that store.
+ * The fixture CAS is curated source, not a destination for operational writers. */
+export declare function exampleArtifactReadOptions(runtimeRoot: unknown, workRoot: unknown, { resolveRoot }?: {
+    resolveRoot?: string;
+}): Readonly<{
+    root?: string;
+}>;

package/runtime/scripts/lib/example-refs.mjs

@@ -4,7 +4,6 @@
 // this file's name only - a declared read, never a path allowlist. A constant belongs here only when the
 // runtime genuinely reads that tree or names that product at run time; a pointer that can be generic must
 // be generic in the file that holds it.
-
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml } from '../../engine/yaml.mjs';
@@ -14,164 +13,175 @@ import { resolveGrammarFamily } from './grammar-lint.mjs';
 import { byCodeUnit } from './list.mjs';
 import { isLiteWorkRoot, workPathAllowed } from './work-edition.mjs';
 import { WORK_DIR_NAME } from './roots.mjs';
-
 /** The runtime's example tree root. */
 export const EXAMPLES_ROOT = 'examples';
-
 /** Curated basic sample source; operational artifact writers remain external. */
 export const EXAMPLE_RUNTIMES_ROOT = `${EXAMPLES_ROOT}/.runtimes`;
-
 /** Every examples/<name>/hfs.json declaration of kind app, sorted by name. */
 export function discoverExampleApps(root) {
-  const directory = path.join(root, EXAMPLES_ROOT);
-  let entries;
-  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return []; }
-  return entries.filter((entry) => entry.isDirectory()).filter((entry) => {
-    try { return JSON.parse(fs.readFileSync(path.join(directory, entry.name, 'hfs.json'), 'utf8'))?.kind === 'app'; }
-    catch { return false; }
-  }).map((entry) => entry.name).sort(byCodeUnit);
-}
-
+    const directory = path.join(root, EXAMPLES_ROOT);
+    let entries;
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((entry) => entry.isDirectory()).filter((entry) => {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(directory, entry.name, 'hfs.json'), 'utf8'))?.kind === 'app';
+        }
+        catch {
+            return false;
+        }
+    }).map((entry) => entry.name).sort(byCodeUnit);
+}
 /** The example apps that declare a browser journey (hfs.json `browser: true`, the opt-in slot app.browser-config), sorted by name: the matrix of the examples workflow's browser job. */
 export function discoverBrowserExampleApps(root) {
-  return discoverExampleApps(root).filter((name) => {
-    try { return JSON.parse(fs.readFileSync(path.join(root, EXAMPLES_ROOT, name, 'hfs.json'), 'utf8'))?.browser === true; }
-    catch { return false; }
-  });
+    return discoverExampleApps(root).filter((name) => {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(root, EXAMPLES_ROOT, name, 'hfs.json'), 'utf8'))?.browser === true;
+        }
+        catch {
+            return false;
+        }
+    });
 }
-
 /** The generic services-block template a starcistacks follow-up leg is pointed at (S11-02: one template
  *  for every repository). */
 export const STACK_DECLARATION_TEMPLATE = `${EXAMPLES_ROOT}/starcistacks-services/template.services.yaml`;
-
 /** The reference app declaration scripts/hfs/derived-fields.mjs samples for per-field slot ownership. */
 export const REFERENCE_APP_MANIFEST = `${EXAMPLES_ROOT}/full-app/hfs.json`;
-
 /** The example app whose installed tree an fe-kit peer link points at by default. */
 export const REFERENCE_EXAMPLE_APP = 'full-app';
-
 /** The grammar css families a product repository may declare (`[data-grammar-family="<id>"]`), keyed by the
  *  canonical catalog id; the runtime's own product maps to the core sheet. */
 export const GRAMMAR_FAMILIES = Object.freeze({ core: 'core', nivo: 'nivo', 'offset-pop': 'offset-pop' });
-
-/** A css family key through the Grammar catalog's alias table (`starci` reads as `core`); an id the catalog does not declare is kept. */
 export function grammarCssFamilyKey(family) {
-  if (typeof family !== 'string' || !family) return family;
-  try { return resolveGrammarFamily(family).id; } catch { return family; }
+    if (typeof family !== 'string' || !family)
+        return family;
+    try {
+        return resolveGrammarFamily(family).id;
+    }
+    catch {
+        return family;
+    }
 }
-
 /** A feature-folder segment that is only the product's own name - no useful leaf (display-names pathLabel). */
 export const PRODUCT_NAME_SEGMENT = /^(nivo|starci|mia)[-\w]*$/i;
-
 /** The closed list of product names this runtime shipped against - the names R206
  *  (check-example-coupling.mjs) refuses anywhere in runtime source outside this file. */
 export const PRODUCT_NAMES = Object.freeze(['mia-mia', 'miamia', 'nivo', 'starci-academy', 'full-app', 'shape-slot']);
-
 /** The catalog of stable pattern IDs pointing at actual executable example source. */
 export const EXAMPLE_CATALOG_FILE = `${EXAMPLES_ROOT}/index.yaml`;
-
 function referenceFile(root, relative, { directory = false, exact = false } = {}) {
-  if (typeof relative !== 'string' || !relative || relative.includes('\\') || relative.includes(':') || path.isAbsolute(relative)
-    || relative.split('/').some((part) => !part || part === '.' || part === '..')) throw new Error(`invalid example input: ${relative}`);
-  const file = path.resolve(root, relative);
-  if (!insidePath(root, file)) throw new Error(`example input is outside its declared root: ${relative}`);
-  const realRoot = fs.realpathSync.native(root), base = path.resolve(root);
-  let at = base, expected = realRoot; // the root's own spelling (8.3 short name, symlinked prefix) is not a link inside the tree
-  for (const segment of path.relative(base, file).split(path.sep).filter(Boolean)) {
-    at = path.join(at, segment); expected = path.join(expected, segment);
-    if (fs.lstatSync(at).isSymbolicLink() || !samePath(fs.realpathSync.native(at), expected)
-      || (exact && !fs.readdirSync(path.dirname(at)).includes(path.basename(at))))
-      throw new Error(`linked example input: ${relative}`);
-  }
-  if (!(directory ? fs.lstatSync(file).isDirectory() : fs.lstatSync(file).isFile())
-    || !insidePath(realRoot, fs.realpathSync.native(file)))
-    throw new Error(`example input is not a contained regular file: ${relative}`);
-  return file;
-}
-
+    if (typeof relative !== 'string' || !relative || relative.includes('\\') || relative.includes(':') || path.isAbsolute(relative)
+        || relative.split('/').some((part) => !part || part === '.' || part === '..'))
+        throw new Error(`invalid example input: ${relative}`);
+    const file = path.resolve(root, relative);
+    if (!insidePath(root, file))
+        throw new Error(`example input is outside its declared root: ${relative}`);
+    const realRoot = fs.realpathSync.native(root), base = path.resolve(root);
+    let at = base, expected = realRoot; // the root's own spelling (8.3 short name, symlinked prefix) is not a link inside the tree
+    for (const segment of path.relative(base, file).split(path.sep).filter(Boolean)) {
+        at = path.join(at, segment);
+        expected = path.join(expected, segment);
+        if (fs.lstatSync(at).isSymbolicLink() || !samePath(fs.realpathSync.native(at), expected)
+            || (exact && !fs.readdirSync(path.dirname(at)).includes(path.basename(at))))
+            throw new Error(`linked example input: ${relative}`);
+    }
+    if (!(directory ? fs.lstatSync(file).isDirectory() : fs.lstatSync(file).isFile())
+        || !insidePath(realRoot, fs.realpathSync.native(file)))
+        throw new Error(`example input is not a contained regular file: ${relative}`);
+    return file;
+}
 /** Read and validate complete source references. Duplicate IDs refuse before
  * lookup; source, compiler and test pointers stay within one declared HFS app. */
 function loadExampleCatalog(root, { file = EXAMPLE_CATALOG_FILE } = {}) {
-  const catalog = parseYaml(fs.readFileSync(referenceFile(root, file), 'utf8'));
-  const schema = parseYaml(fs.readFileSync(referenceFile(root, 'modules/schemas/code-example-catalog.schema.yaml'), 'utf8'));
-  const errors = validateAgainstSchema(catalog, schema);
-  if (errors.length) throw new Error(`invalid example catalog: ${errors.join('; ')}`);
-  assertUniqueExampleIds(catalog.examples);
-  for (const row of catalog.examples) assertExampleRow(root, row);
-  return catalog;
-}
-
+    const catalog = parseYaml(fs.readFileSync(referenceFile(root, file), 'utf8'));
+    const schema = parseYaml(fs.readFileSync(referenceFile(root, 'modules/schemas/code-example-catalog.schema.yaml'), 'utf8'));
+    const errors = validateAgainstSchema(catalog, schema);
+    if (errors.length)
+        throw new Error(`invalid example catalog: ${errors.join('; ')}`);
+    assertUniqueExampleIds(catalog.examples);
+    for (const row of catalog.examples)
+        assertExampleRow(root, row);
+    return catalog;
+}
 function assertUniqueExampleIds(examples) {
-  const ids = new Set();
-  for (const row of examples) {
-    if (ids.has(row.id)) throw new Error(`duplicate example id: ${row.id}`);
-    ids.add(row.id);
-  }
+    const ids = new Set();
+    for (const row of examples) {
+        if (ids.has(row.id))
+            throw new Error(`duplicate example id: ${row.id}`);
+        ids.add(row.id);
+    }
 }
-
 function assertExampleRow(root, row) {
-  const app = exampleAppRoot(root, row);
-  assertExampleEntrypoint(row);
-  assertUniqueRowValues(row, 'relatedRules');
-  for (const key of ['files', 'projects', 'tests']) assertExampleInputs(app, row, key);
-  assertSupportedExampleSources(row);
+    const app = exampleAppRoot(root, row);
+    assertExampleEntrypoint(row);
+    assertUniqueRowValues(row, 'relatedRules');
+    for (const key of ['files', 'projects', 'tests'])
+        assertExampleInputs(app, row, key);
+    assertSupportedExampleSources(row);
 }
-
 function exampleAppRoot(root, row) {
-  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.path)) throw new Error(`invalid example app: ${row.path}`);
-  const app = path.join(root, EXAMPLES_ROOT, row.path);
-  const declaration = JSON.parse(fs.readFileSync(referenceFile(root, `${EXAMPLES_ROOT}/${row.path}/hfs.json`), 'utf8'));
-  if (declaration.kind !== 'app') throw new Error(`example has no HFS app declaration: ${row.id}`);
-  return app;
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.path))
+        throw new Error(`invalid example app: ${row.path}`);
+    const app = path.join(root, EXAMPLES_ROOT, row.path);
+    const declaration = JSON.parse(fs.readFileSync(referenceFile(root, `${EXAMPLES_ROOT}/${row.path}/hfs.json`), 'utf8'));
+    if (declaration.kind !== 'app')
+        throw new Error(`example has no HFS app declaration: ${row.id}`);
+    return app;
 }
-
 function assertExampleEntrypoint(row) {
-  if (!row.files.includes(row.entrypoint) || !/\.tsx?$/.test(row.entrypoint)) throw new Error(`example entrypoint is not a listed source: ${row.id}`);
+    if (!row.files.includes(row.entrypoint) || !/\.tsx?$/.test(row.entrypoint))
+        throw new Error(`example entrypoint is not a listed source: ${row.id}`);
 }
-
 function assertUniqueRowValues(row, key) {
-  if (new Set(row[key]).size !== row[key].length) throw new Error(`duplicate example ${key}: ${row.id}`);
+    if (new Set(row[key]).size !== row[key].length)
+        throw new Error(`duplicate example ${key}: ${row.id}`);
 }
-
 function assertExampleInputs(app, row, key) {
-  assertUniqueRowValues(row, key);
-  for (const relative of row[key]) assertAuthoredExampleInput(app, relative);
+    assertUniqueRowValues(row, key);
+    for (const relative of row[key])
+        assertAuthoredExampleInput(app, relative);
 }
-
 function assertAuthoredExampleInput(app, relative) {
-  if (relative.split('/').some((part) => ['node_modules', 'dist', '.next', '_derived', '.git'].includes(part)))
-    throw new Error(`derived or installed example input: ${relative}`);
-  referenceFile(app, relative);
+    if (relative.split('/').some((part) => ['node_modules', 'dist', '.next', '_derived', '.git'].includes(part)))
+        throw new Error(`derived or installed example input: ${relative}`);
+    referenceFile(app, relative);
 }
-
 function assertSupportedExampleSources(row) {
-  if (row.files.some((relative) => !/\.(?:tsx?|json)$/.test(relative))) throw new Error(`unsupported example source: ${row.id}`);
+    if (row.files.some((relative) => !/\.(?:tsx?|json)$/.test(relative)))
+        throw new Error(`unsupported example source: ${row.id}`);
 }
-
 /** Source, compiler and test inputs of selected stable IDs, relative to the runtime.
  * A null selection requests the declared whole catalog; unknown IDs refuse. */
 export function exampleSourcePaths(root, ids = null, options = {}) {
-  const catalog = loadExampleCatalog(root, options), selected = new Set(ids ?? catalog.examples.map((row) => row.id));
-  const known = new Set(catalog.examples.map((row) => row.id));
-  for (const id of selected) if (!known.has(id)) throw new Error(`unknown example id: ${id}`);
-  return [...new Set(catalog.examples.filter((row) => selected.has(row.id))
-    .flatMap((row) => [...row.files, ...row.projects, ...row.tests].map((relative) => `${EXAMPLES_ROOT}/${row.path}/${relative}`)))];
+    const catalog = loadExampleCatalog(root, options), selected = new Set(ids ?? catalog.examples.map((row) => row.id));
+    const known = new Set(catalog.examples.map((row) => row.id));
+    for (const id of selected)
+        if (!known.has(id))
+            throw new Error(`unknown example id: ${id}`);
+    return [...new Set(catalog.examples.filter((row) => selected.has(row.id))
+            .flatMap((row) => [...row.files, ...row.projects, ...row.tests].map((relative) => `${EXAMPLES_ROOT}/${row.path}/${relative}`)))];
 }
-
 /** Actual example apps' own Work trees in app-name order. Dependency/template
  * trees are not app Work; an absent own tree contributes no checker input. */
 export function exampleWorkRoots(root) {
-  return discoverExampleApps(root).flatMap((app) => {
-    const relative = `${EXAMPLES_ROOT}/${app}/.starciwork/index.yaml`;
-    const directory = path.dirname(path.join(root, relative)), stat = fs.lstatSync(directory, { throwIfNoEntry: false });
-    if (!stat) return [];
-    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`invalid example Work directory: ${app}`);
-    referenceFile(root, `${EXAMPLES_ROOT}/${app}/.starciwork`, { directory: true });
-    if (!isLiteWorkRoot(directory)) referenceFile(root, relative);
-    return [directory];
-  });
-}
-
+    return discoverExampleApps(root).flatMap((app) => {
+        const relative = `${EXAMPLES_ROOT}/${app}/.starciwork/index.yaml`;
+        const directory = path.dirname(path.join(root, relative)), stat = fs.lstatSync(directory, { throwIfNoEntry: false });
+        if (!stat)
+            return [];
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error(`invalid example Work directory: ${app}`);
+        referenceFile(root, `${EXAMPLES_ROOT}/${app}/.starciwork`, { directory: true });
+        if (!isLiteWorkRoot(directory))
+            referenceFile(root, relative);
+        return [directory];
+    });
+}
 /**
  * The runtime checkout that holds `workRoot` when it is one of that checkout's example Work trees
  * (`<checkout>/examples/<app>/.starciwork` beside `<checkout>/examples/.runtimes`), else null. An example is judged against its
@@ -179,34 +189,40 @@ export function exampleWorkRoots(root) {
  * runs the canonical runtime over a lane's staged files).
  */
 export function exampleCheckoutOf(workRoot) {
-  if (typeof workRoot !== 'string') return null;
-  const work = path.resolve(workRoot);
-  const appDir = path.dirname(work), examplesDir = path.dirname(appDir), checkout = path.dirname(examplesDir);
-  if (path.basename(work) !== WORK_DIR_NAME || path.basename(examplesDir) !== EXAMPLES_ROOT) return null;
-  return fs.existsSync(path.join(examplesDir, '.runtimes')) && fs.existsSync(path.join(appDir, 'hfs.json')) ? checkout : null;
+    if (typeof workRoot !== 'string')
+        return null;
+    const work = path.resolve(workRoot);
+    const appDir = path.dirname(work), examplesDir = path.dirname(appDir), checkout = path.dirname(examplesDir);
+    if (path.basename(work) !== WORK_DIR_NAME || path.basename(examplesDir) !== EXAMPLES_ROOT)
+        return null;
+    return fs.existsSync(path.join(examplesDir, '.runtimes')) && fs.existsSync(path.join(appDir, 'hfs.json')) ? checkout : null;
 }
-
 /** Per-call READ options for an actual HFS app's own Work tree. A real project
  * uses the default external store; an example never falls back to that store.
  * The fixture CAS is curated source, not a destination for operational writers. */
 export function exampleArtifactReadOptions(runtimeRoot, workRoot, { resolveRoot = workRoot } = {}) {
-  if (typeof runtimeRoot !== 'string' || typeof workRoot !== 'string') throw new TypeError('example artifact context needs runtime and Work paths');
-  const base = path.resolve(runtimeRoot), target = path.resolve(workRoot);
-  const relative = slash(path.relative(base, target)), parts = relative.split('/');
-  if (parts[0]?.toLowerCase() !== EXAMPLES_ROOT) return Object.freeze({});
-  const app = parts[1];
-  if (parts[0] !== EXAMPLES_ROOT || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(app ?? '')
-    || !discoverExampleApps(base).includes(app) || parts[2] !== WORK_DIR_NAME)
-    throw new Error(`invalid example Work artifact context: ${relative}`);
-  referenceFile(base, `${EXAMPLES_ROOT}/${app}/hfs.json`, { exact: true });
-  const ownWork = path.join(base, EXAMPLES_ROOT, app, WORK_DIR_NAME);
-  if (!isLiteWorkRoot(ownWork)) referenceFile(base, `${EXAMPLES_ROOT}/${app}/.starciwork/index.yaml`, { exact: true });
-  if (!workPathAllowed(ownWork, target, { dir: true })) throw new Error('lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore)');
-  referenceFile(base, relative, { directory: true, exact: true });
-  const resolution = path.resolve(resolveRoot);
-  if (!workPathAllowed(ownWork, resolution, { dir: true })) throw new Error('lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore)');
-  if (!insidePath(resolution, target, { includeSelf: true }) || !insidePath(ownWork, resolution, { includeSelf: true }))
-    throw new Error('selected example validation and resolution must share its own Work root');
-  referenceFile(base, slash(path.relative(base, resolution)), { directory: true, exact: true });
-  return Object.freeze({ root: path.join(base, EXAMPLE_RUNTIMES_ROOT, app, 'artifacts') });
+    if (typeof runtimeRoot !== 'string' || typeof workRoot !== 'string')
+        throw new TypeError('example artifact context needs runtime and Work paths');
+    const base = path.resolve(runtimeRoot), target = path.resolve(workRoot);
+    const relative = slash(path.relative(base, target)), parts = relative.split('/');
+    if (parts[0]?.toLowerCase() !== EXAMPLES_ROOT)
+        return Object.freeze({});
+    const app = parts[1]; // an absent segment fails the checks below
+    if (parts[0] !== EXAMPLES_ROOT || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(app ?? '')
+        || !discoverExampleApps(base).includes(app) || parts[2] !== WORK_DIR_NAME)
+        throw new Error(`invalid example Work artifact context: ${relative}`);
+    referenceFile(base, `${EXAMPLES_ROOT}/${app}/hfs.json`, { exact: true });
+    const ownWork = path.join(base, EXAMPLES_ROOT, app, WORK_DIR_NAME);
+    if (!isLiteWorkRoot(ownWork))
+        referenceFile(base, `${EXAMPLES_ROOT}/${app}/.starciwork/index.yaml`, { exact: true });
+    if (!workPathAllowed(ownWork, target, { dir: true }))
+        throw new Error('lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore)');
+    referenceFile(base, relative, { directory: true, exact: true });
+    const resolution = path.resolve(resolveRoot);
+    if (!workPathAllowed(ownWork, resolution, { dir: true }))
+        throw new Error('lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore)');
+    if (!insidePath(resolution, target, { includeSelf: true }) || !insidePath(ownWork, resolution, { includeSelf: true }))
+        throw new Error('selected example validation and resolution must share its own Work root');
+    referenceFile(base, slash(path.relative(base, resolution)), { directory: true, exact: true });
+    return Object.freeze({ root: path.join(base, EXAMPLE_RUNTIMES_ROOT, app, 'artifacts') });
 }

package/runtime/scripts/lib/fs-kind.d.mts

@@ -0,0 +1,12 @@
+import fs from 'node:fs';
+/** `p` names a file within `maxBytes`; false on any stat error. `followLinks: false` probes the entry itself. */
+export declare const isFile: (p: fs.PathLike, { followLinks, maxBytes }?: {
+    followLinks?: boolean;
+    maxBytes?: number;
+}) => boolean;
+/** `p` names a directory; false on any stat error. `followLinks: false` refuses linked entries. */
+export declare const isDir: (p: fs.PathLike, { followLinks }?: {
+    followLinks?: boolean;
+}) => boolean;
+/** `p`'s canonical spelling via the filesystem (links resolved), or null when it cannot be read. */
+export declare const realpathOr: (p: fs.PathLike) => string | null;

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

@@ -1,20 +1,30 @@
 // fs-kind.mjs — the forgiving fs.statSync probes a dozen scripts re-declared by hand.
 // 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 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; }
+    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; }
+    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; } };
+export const realpathOr = (p) => { try {
+    return fs.realpathSync.native(p);
+}
+catch {
+    return null;
+} };

package/runtime/scripts/lib/git-hooks-dir.d.mts

@@ -0,0 +1,15 @@
+/** The state of a hooks folder: `unreadable` carries the error text. */
+export type HooksDirState = {
+    state: 'installed' | 'missing' | 'empty';
+    dir: string;
+} | {
+    state: 'unreadable';
+    dir: string;
+    error: string;
+};
+/**
+ * The state of the hooks folder `hooksPath` (a core.hooksPath value, relative to the checkout `root` or absolute):
+ * `{ state, dir }` with state `installed`, `missing` (no such folder), `empty` (no hook file; for husky's `.husky/_`, no
+ * dispatcher `h`) or `unreadable` (with `error`).
+ */
+export declare function hooksDirState(root: string, hooksPath: unknown): HooksDirState;

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

@@ -1,30 +1,30 @@
-// git-hooks-dir.mjs - whether a checkout's hooks folder holds installed hooks. The one judgement read by `starci npm ci` and
-// `starci npm install` (scripts/machine/npm-hooks.mjs, which runs the app's hook installer when it fails) and by the HFS check
+// git-hooks-dir.mjs - whether a checkout's hooks folder holds installed hooks: the judgement of the HFS check
 // HFS_HOOKS_NOT_INSTALLED (scripts/hfs/architecture/hfs.mjs). husky's `.husky/_` is generated per checkout: a linked worktree or
 // an install whose lifecycle scripts were ignored has none, or only the runtime's own wrapped hooks, so git runs no pre-commit gate.
 import fs from 'node:fs';
 import path from 'node:path';
-
 /** husky's generated hooks folder; every hook file in it sources the dispatcher `h`, which runs the tracked `.husky/<hook>`. */
 const HUSKY_GENERATED = /^\.husky\/_\/?$/u;
 const HUSKY_DISPATCHER = 'h';
-
 /**
  * The state of the hooks folder `hooksPath` (a core.hooksPath value, relative to the checkout `root` or absolute):
  * `{ state, dir }` with state `installed`, `missing` (no such folder), `empty` (no hook file; for husky's `.husky/_`, no
  * dispatcher `h`) or `unreadable` (with `error`).
  */
 export function hooksDirState(root, hooksPath) {
-  const value = String(hooksPath ?? '').trim().replaceAll('\\', '/');
-  const dir = path.resolve(root, value);
-  let entries;
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch (error) {
-    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return { state: 'missing', dir };
-    return { state: 'unreadable', dir, error: String(error?.message ?? error) };
-  }
-  const files = entries.filter((entry) => entry.isFile() && entry.name !== '.gitignore').map((entry) => entry.name);
-  const installed = HUSKY_GENERATED.test(value) ? files.includes(HUSKY_DISPATCHER) : files.length > 0;
-  return { state: installed ? 'installed' : 'empty', dir };
+    const value = String(hooksPath ?? '').trim().replaceAll('\\', '/');
+    const dir = path.resolve(root, value);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        const failure = error;
+        if (failure?.code === 'ENOENT' || failure?.code === 'ENOTDIR')
+            return { state: 'missing', dir };
+        return { state: 'unreadable', dir, error: String(failure?.message ?? error) };
+    }
+    const files = entries.filter((entry) => entry.isFile() && entry.name !== '.gitignore').map((entry) => entry.name);
+    const installed = HUSKY_GENERATED.test(value) ? files.includes(HUSKY_DISPATCHER) : files.length > 0;
+    return { state: installed ? 'installed' : 'empty', dir };
 }

package/runtime/scripts/lib/git.d.mts

@@ -0,0 +1,24 @@
+/** The fields of a git spawn result (a child_process spawnSync result) these helpers read. */
+export interface GitSpawnResult {
+    error?: Error | undefined;
+    status?: number | null | undefined;
+    stdout?: string | null | undefined;
+    stderr?: string | null | undefined;
+}
+/**
+ * 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 declare const unquoteDiffPath: (value: string) => string;
+export declare const GIT_LOCAL_ENV_VARS: string[];
+/** `parent` (the caller's env) without git's repository-local variables (GIT_CONFIG_KEY_n/VALUE_n go with GIT_CONFIG_COUNT). Pure. */
+export declare function withoutGitLocalEnv<E extends Record<string, string | undefined>>(parent: E): E;
+/** 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 declare const gitResultOf: (r: GitSpawnResult) => {
+    ok: boolean;
+    stdout: string;
+    error: string;
+};
+/** 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 declare function gitOutputOf<R extends GitSpawnResult>(r: R, what?: string): R['stdout'];