@starci/hfs 4.11.22 → 4.12.2

package/runtime/packages/cli/src/validate-args.d.mts

@@ -0,0 +1,74 @@
+/** One option of a catalogued verb (or a global one). */
+export interface CatalogFlag {
+    name: string;
+    type: string;
+    summary?: string;
+    required?: boolean;
+    default?: unknown;
+    enum?: readonly unknown[];
+    global?: boolean;
+}
+/** One positional slot of a catalogued verb. */
+export interface CatalogPositional {
+    name: string;
+    required?: boolean;
+    variadic?: boolean;
+    enum?: readonly unknown[];
+}
+/** The catalog entry validateArgs judges a command line against, with the group and verb names a dispatcher adds. */
+export interface CatalogVerb {
+    verb?: string;
+    group?: string;
+    flags?: CatalogFlag[];
+    positional?: CatalogPositional[];
+    internalFlags?: Array<{
+        name: string;
+        pointer: string;
+    }>;
+    editions?: string[];
+    json?: string;
+    operationPolicy?: Record<string, {
+        action?: unknown;
+        credentials?: unknown;
+    } | undefined>;
+}
+/** validateArgs' answer: the typed values or the refusal (code 2). */
+export type ValidatedArgs = {
+    ok: true;
+    values: Values;
+    args: Values;
+    global: Values;
+    localArgs: string[];
+    positionals: string[];
+    operationPolicy: {
+        action?: unknown;
+        credentials?: unknown;
+    } | null;
+} | {
+    ok: false;
+    code: 2;
+    error: string;
+};
+type Values = Record<string, unknown>;
+/**
+ * Validate the arguments after a catalog group and verb.
+ *
+ * Global options are returned separately so dispatchers can implement them once;
+ * localArgs contains only the verb's positionals and local options, in input order.
+ * Everything after a bare `--` is passed through unchanged: it is never parsed as an option and
+ * only fills positional slots the verb declares.
+ */
+export declare function validateArgs(argv: string[], verb: CatalogVerb, globalFlags?: CatalogFlag[]): ValidatedArgs;
+/** Insert dispatcher-owned flags before a pass-through `--`, where handlers still parse them as options. */
+export declare function withFlagsBeforeDashes(args: string[], extra: string[]): string[];
+/**
+ * Find the group and verb while allowing catalog global options before them.
+ * `help` is true when --help or -h appears before any bare `--`; everything after `--` is pass-through.
+ */
+export declare function splitCommand(argv: string[], globalFlags?: CatalogFlag[]): {
+    group: string | null;
+    verb: string | null;
+    args: string[];
+    help: boolean;
+};
+export {};

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

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

package/runtime/packages/jest-preset/sonar-exclusions.cjs

@@ -1,8 +1,8 @@
-"use strict"
-
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Sonar `sonar.exclusions`: specs, e2e specs, dist and coverage output are not analysed at all. A plain list with no require, so
- * @starci/hfs ships this file byte for byte (packages/hfs/runtime, scripts/hfs/sync-runtime.mjs) and `starci app scaffold` renders
- * the same exclusions before any app dependency is installed.
+ * @starci/hfs ships the built sonar-exclusions.cjs (packages/hfs/runtime) and `starci app scaffold` renders the same exclusions
+ * before any app dependency is installed.
  */
-module.exports = Object.freeze(["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"])
+module.exports = Object.freeze(["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"]);

package/runtime/scripts/api/fs/claim-file.d.mts

@@ -0,0 +1,12 @@
+/** The outcome of claimFile: the claim, or the pid of the live holder (null when unknown). */
+export type FileClaim = {
+    ok: true;
+    release: () => void;
+} | {
+    ok: false;
+    holder: number | null;
+};
+/** {ok: true, release} once this process holds the claim of `file`; {ok: false, holder} while a live process (this one included) holds it. `pid` is the claiming process. */
+export declare function claimFile(file: string, { pid }?: {
+    pid?: number;
+}): FileClaim;

package/runtime/scripts/api/fs/claim-file.mjs

@@ -3,28 +3,42 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pidAlive } from '../../lib/pid-alive.mjs';
-
+import { errorCode } from './lib.mjs';
 const UNREADABLE_HELD_MS = 10_000;
 const holderOf = (lock) => {
-  try { const pid = JSON.parse(fs.readFileSync(lock, 'utf8')).pid; return Number.isInteger(pid) ? pid : null; } catch { return null; }
+    try {
+        const pid = JSON.parse(fs.readFileSync(lock, 'utf8')).pid;
+        return Number.isInteger(pid) ? pid : null;
+    }
+    catch {
+        return null;
+    }
 };
 /** A lock a claimant created but has not yet written is held for a moment: only an old unreadable lock is a crashed claim. */
-const freshlyCreated = (lock) => { try { return Date.now() - fs.statSync(lock).mtimeMs < UNREADABLE_HELD_MS; } catch { return false; } };
-
+const freshlyCreated = (lock) => { try {
+    return Date.now() - fs.statSync(lock).mtimeMs < UNREADABLE_HELD_MS;
+}
+catch {
+    return false;
+} };
 /** {ok: true, release} once this process holds the claim of `file`; {ok: false, holder} while a live process (this one included) holds it. `pid` is the claiming process. */
 export function claimFile(file, { pid = process.pid } = {}) {
-  const lock = path.join(path.dirname(file), `.${path.basename(file)}.lock`);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      fs.writeFileSync(lock, JSON.stringify({ pid }), { flag: 'wx', mode: 0o600 });
-      return { ok: true, release: () => { if (holderOf(lock) === pid) fs.rmSync(lock, { force: true }); } };
-    } catch (error) {
-      if (error?.code !== 'EEXIST') throw error;
-      const holder = holderOf(lock);
-      if (holder !== null ? pidAlive(holder) : freshlyCreated(lock)) return { ok: false, holder };
-      fs.rmSync(lock, { force: true });
+    const lock = path.join(path.dirname(file), `.${path.basename(file)}.lock`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            fs.writeFileSync(lock, JSON.stringify({ pid }), { flag: 'wx', mode: 0o600 });
+            return { ok: true, release: () => { if (holderOf(lock) === pid)
+                    fs.rmSync(lock, { force: true }); } };
+        }
+        catch (error) {
+            if (errorCode(error) !== 'EEXIST')
+                throw error;
+            const holder = holderOf(lock);
+            if (holder !== null ? pidAlive(holder) : freshlyCreated(lock))
+                return { ok: false, holder };
+            fs.rmSync(lock, { force: true });
+        }
     }
-  }
-  return { ok: false, holder: null };
+    return { ok: false, holder: null };
 }

package/runtime/scripts/api/fs/ensure-temp-root.d.mts

@@ -0,0 +1,4 @@
+/** The temp root of `env`, created when it is missing. Throws an Error with code TEMP_ROOT_UNUSABLE when it cannot be created or written. */
+export declare function ensureTempRoot({ env }?: {
+    env?: NodeJS.ProcessEnv;
+}): string;

package/runtime/scripts/api/fs/ensure-temp-root.mjs

@@ -2,26 +2,27 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { tempRoot, TEMP_ROOT_ENV } from '../../../engine/temp-root.mjs';
-
+import { errorCode } from './lib.mjs';
 const TEMP_ROOT_UNUSABLE = 'TEMP_ROOT_UNUSABLE';
 const writable = new Set();
-
 const unusable = (root, reason) => Object.assign(new Error(`${TEMP_ROOT_UNUSABLE}: the temp root ${root} ${reason}; set roots.temp in config.yaml (or ${TEMP_ROOT_ENV}) to a directory the runtime can create and write - it is not replaced by the operating-system temp directory`), { code: TEMP_ROOT_UNUSABLE, root });
-
 /** Writes and removes one probe file in `root`: a directory that exists can still refuse writes. */
 function probeWritable(root) {
-  const probe = path.join(root, `.starci-write-probe-${process.pid}`);
-  fs.writeFileSync(probe, '');
-  fs.rmSync(probe, { force: true });
+    const probe = path.join(root, `.starci-write-probe-${process.pid}`);
+    fs.writeFileSync(probe, '');
+    fs.rmSync(probe, { force: true });
 }
-
 /** The temp root of `env`, created when it is missing. Throws an Error with code TEMP_ROOT_UNUSABLE when it cannot be created or written. */
 export function ensureTempRoot({ env = process.env } = {}) {
-  const root = tempRoot({ env });
-  try {
-    fs.mkdirSync(root, { recursive: true });
-    if (!writable.has(root)) probeWritable(root);
-  } catch (error) { throw unusable(root, `cannot be created or written (${error.code ?? error.message})`); }
-  writable.add(root);
-  return root;
+    const root = tempRoot({ env });
+    try {
+        fs.mkdirSync(root, { recursive: true });
+        if (!writable.has(root))
+            probeWritable(root);
+    }
+    catch (error) {
+        throw unusable(root, `cannot be created or written (${errorCode(error) ?? (error instanceof Error ? error.message : String(error))})`);
+    }
+    writable.add(root);
+    return root;
 }

package/runtime/scripts/api/fs/forbidden-root.d.mts

@@ -0,0 +1,15 @@
+/**
+ * A path the runtime must never remove whole: a filesystem root, the home or temp directory, the runtime, the
+ * repository that hosts it, the repositories root, or a primary git checkout (its .git is a directory; the
+ * scratch trees the runtime removes are temp directories and linked worktrees, whose .git is a file).
+ * `checkoutsUnder` names a disposable root (hk-tmp's temp root): a checkout strictly inside it by real path
+ * is a spec fixture, not a live repository, and is not refused for its .git. Every other refusal stands.
+ * `hold(path)` is the caller's artifact-hold check (scripts/machine/artifact-hold.mjs artifactHoldReason: a tree holding
+ * an indexed job artifact, or inside an evidence directory holding one, whatever the workflow's phase), its refusal line
+ * or null. It is required: without one every path is refused (fail closed); a caller that removes only a scratch tree
+ * it made itself, outside every ledger's repository, says so with `hold: () => null`.
+ */
+export declare function forbiddenRoot(p: string, { checkoutsUnder, hold }?: {
+    checkoutsUnder?: string | null;
+    hold?: ((path: string) => string | null) | undefined;
+}): string | null;