@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/api/sops/resolve-sops.d.mts

@@ -0,0 +1,3 @@
+import { type ResolveSopsOptions } from './lib.mjs';
+/** The absolute sops path, or null. `options`: platform, pathext (PATHEXT names), wingetPackageTree (the full package tree), filesystem (a probe). */
+export declare function resolveSops(env?: NodeJS.ProcessEnv, options?: ResolveSopsOptions): string | null;

package/runtime/scripts/api/sops/resolve-sops.mjs

@@ -1,7 +1,6 @@
 // resolve-sops.mjs — find the sops executable: PATH, and on Windows the WinGet links and packages.
 import { resolveSops as resolve } from './lib.mjs';
-
 /** The absolute sops path, or null. `options`: platform, pathext (PATHEXT names), wingetPackageTree (the full package tree), filesystem (a probe). */
 export function resolveSops(env = process.env, options = {}) {
-  return resolve(env, options);
+    return resolve(env, options);
 }

package/runtime/scripts/api/sops/seal.d.mts

@@ -0,0 +1,19 @@
+import { type SopsInvocation, type SopsResult } from './lib.mjs';
+/**
+ * Run `<bin> encrypt` (bin null: the sops resolveSops finds) over `plaintext` of format `inputType` (json, yaml or dotenv). Sops reads stdin only with a `--filename-override`, the path the sealed
+ * file will have: recipients are age keys (`--age`), and when none are given sops picks them from the repository's .sops.yaml for that path. `config` names
+ * the sops configuration to read instead of the repository's (a rule-less member sealed to its own recipients). {status, stdout, stderr, error}.
+ */
+export declare function seal(bin: string | null, { inputType, plaintext, recipients, filenameOverride, config }: {
+    inputType: string;
+    plaintext: string | Buffer;
+    recipients?: string[];
+    filenameOverride: string;
+    config?: string | null;
+}, { invocation, env, cwd, maxBuffer, timeout }?: {
+    invocation?: SopsInvocation | null;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string | undefined;
+    maxBuffer?: number;
+    timeout?: number | undefined;
+}): SopsResult;

package/runtime/scripts/api/sops/seal.mjs

@@ -4,20 +4,24 @@
 import { spawnSync } from 'node:child_process';
 import { sopsIdentityEnv } from '../../../engine/secrets.mjs';
 import { resolveSops, runSelectedSops } from './lib.mjs';
-
 /**
  * Run `<bin> encrypt` (bin null: the sops resolveSops finds) over `plaintext` of format `inputType` (json, yaml or dotenv). Sops reads stdin only with a `--filename-override`, the path the sealed
  * file will have: recipients are age keys (`--age`), and when none are given sops picks them from the repository's .sops.yaml for that path. `config` names
  * the sops configuration to read instead of the repository's (a rule-less member sealed to its own recipients). {status, stdout, stderr, error}.
  */
 export function seal(bin, { inputType, plaintext, recipients = [], filenameOverride, config = null }, { invocation = null, env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024, timeout = undefined } = {}) {
-  const args = [...(config ? ['--config', config] : []), 'encrypt', '--input-type', inputType, '--output-type', inputType, '--filename-override', filenameOverride];
-  if (recipients.length) args.push('--age', recipients.join(','));
-  const selected = sopsIdentityEnv(env);
-  if (selected.error?.identityRefusal === 'inline-context-unqualified') return runSelectedSops(bin, { operation: 'seal', params: { inputType, plaintext, recipients, filenameOverride } }, { selection: selected, invocation, env, cwd, maxBuffer, timeout });
-  if (selected.error) return { status: null, stdout: '', stderr: '', error: selected.error };
-  const exe = bin ?? resolveSops(selected.env);
-  if (!exe) return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
-  const r = spawnSync(exe, args, { cwd, env: selected.env, input: plaintext, encoding: 'utf8', windowsHide: true, maxBuffer });
-  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
+    const args = [...(config ? ['--config', config] : []), 'encrypt', '--input-type', inputType, '--output-type', inputType, '--filename-override', filenameOverride];
+    if (recipients.length)
+        args.push('--age', recipients.join(','));
+    const selected = sopsIdentityEnv(env);
+    if (selected.error?.identityRefusal === 'inline-context-unqualified')
+        return runSelectedSops(bin, { operation: 'seal', params: { inputType, plaintext, recipients, filenameOverride } }, { selection: selected, invocation, env, cwd, maxBuffer, timeout });
+    if (selected.error)
+        return { status: null, stdout: '', stderr: '', error: selected.error };
+    const selectedEnv = selected.env; // every SopsIdentity without an error carries its env
+    const exe = bin ?? resolveSops(selectedEnv);
+    if (!exe)
+        return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
+    const r = spawnSync(exe, args, { cwd, env: selectedEnv, input: plaintext, encoding: 'utf8', windowsHide: true, maxBuffer });
+    return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
 }

package/runtime/scripts/api/sops/selected-age-recipient.d.mts

@@ -0,0 +1,3 @@
+import { type PublicAgeRequest, type PublicAgeOutcome } from './lib.mjs';
+/** Return a public recipient or a typed refusal; selected inline identity bytes never leave the owner. */
+export declare function selectedAgeRecipient(options?: Partial<PublicAgeRequest>): PublicAgeOutcome;

package/runtime/scripts/api/sops/selected-age-recipient.mjs

@@ -1,7 +1,6 @@
 // selected-age-recipient.mjs - public recipient derivation for app secret initialization.
 import { selectedAgeRecipient as selectedRecipient } from './lib.mjs';
-
 /** Return a public recipient or a typed refusal; selected inline identity bytes never leave the owner. */
 export function selectedAgeRecipient(options = {}) {
-  return selectedRecipient(options);
+    return selectedRecipient(options);
 }

package/runtime/scripts/api/sops/update-keys.d.mts

@@ -0,0 +1,16 @@
+import { type SopsInvocation, type SopsResult } from './lib.mjs';
+/**
+ * Run `<bin> --config <config> updatekeys -y --input-type <inputType> <file>` (bin null: the sops resolveSops finds). An inline
+ * SOPS_AGE_KEY goes through the selected isolation (runSelectedUpdateKeys); a SOPS_AGE_KEY_FILE runs with the selected environment.
+ * {status, stdout, stderr, error}; stdout and stderr carry public key names only.
+ */
+export declare function updateKeys(bin: string | null, { file, config, inputType }: {
+    file: string;
+    config: string;
+    inputType: string;
+}, { invocation, env, cwd, timeout }?: {
+    invocation?: SopsInvocation | null;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string | undefined;
+    timeout?: number | undefined;
+}): SopsResult;

package/runtime/scripts/api/sops/update-keys.mjs

@@ -3,18 +3,21 @@
 import { spawnSync } from 'node:child_process';
 import { sopsIdentityEnv } from '../../../engine/secrets.mjs';
 import { resolveSops, runSelectedUpdateKeys } from './lib.mjs';
-
 /**
  * Run `<bin> --config <config> updatekeys -y --input-type <inputType> <file>` (bin null: the sops resolveSops finds). An inline
  * SOPS_AGE_KEY goes through the selected isolation (runSelectedUpdateKeys); a SOPS_AGE_KEY_FILE runs with the selected environment.
  * {status, stdout, stderr, error}; stdout and stderr carry public key names only.
  */
 export function updateKeys(bin, { file, config, inputType }, { invocation = null, env = process.env, cwd = undefined, timeout = undefined } = {}) {
-  const selected = sopsIdentityEnv(env, { required: true });
-  if (selected.error?.identityRefusal === 'inline-context-unqualified') return runSelectedUpdateKeys(bin, { file, config, inputType }, { selection: selected, invocation, env, cwd, timeout });
-  if (selected.error) return { status: null, stdout: '', stderr: '', error: selected.error };
-  const exe = bin ?? resolveSops(selected.env);
-  if (!exe) return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
-  const r = spawnSync(exe, ['--disable-version-check', '--config', config, 'updatekeys', '-y', '--input-type', inputType, file], { cwd, env: selected.env, encoding: 'utf8', windowsHide: true, timeout, stdio: ['ignore', 'pipe', 'pipe'] });
-  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
+    const selected = sopsIdentityEnv(env, { required: true });
+    if (selected.error?.identityRefusal === 'inline-context-unqualified')
+        return runSelectedUpdateKeys(bin, { file, config, inputType }, { selection: selected, invocation, env, cwd, timeout });
+    if (selected.error)
+        return { status: null, stdout: '', stderr: '', error: selected.error };
+    const selectedEnv = selected.env; // every SopsIdentity without an error carries its env
+    const exe = bin ?? resolveSops(selectedEnv);
+    if (!exe)
+        return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
+    const r = spawnSync(exe, ['--disable-version-check', '--config', config, 'updatekeys', '-y', '--input-type', inputType, file], { cwd, env: selectedEnv, encoding: 'utf8', windowsHide: true, timeout, stdio: ['ignore', 'pipe', 'pipe'] });
+    return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
 }

package/runtime/scripts/cli/gen-catalog.d.mts

@@ -0,0 +1,42 @@
+export declare const CATALOG_FILE: string;
+/** The options the program itself takes before any verb (cli/src/main.ts buildProgram), plus commander's --help. */
+interface RegistryFlag {
+    kind: string;
+    summary: string;
+    positional?: boolean;
+    required?: boolean;
+}
+/** One verb of the starci CLI registry (cli/src/registry.ts ALL_VERBS). */
+export interface RegistryVerb {
+    path: readonly [string, (string | undefined)?];
+    summary: string;
+    flags: Record<string, RegistryFlag>;
+    editions: readonly string[];
+}
+interface CatalogEntry {
+    summary: string;
+    flags: Array<Record<string, unknown>>;
+    positional: Array<{
+        name: string;
+        required: boolean;
+        variadic: boolean;
+    }>;
+    editions: string[];
+    json: string;
+}
+interface CatalogGroup {
+    verbs: Record<string, CatalogEntry>;
+    self?: CatalogEntry;
+}
+/** The catalog of `verbs`: a two-word verb under its group, a one-word verb (`starci explain [term]`) as the group's `self`. */
+export declare function catalogOf(verbs: RegistryVerb[]): {
+    schema: string;
+    global: {
+        name: string;
+        type: string;
+        summary: string;
+    }[];
+    groups: Record<string, CatalogGroup>;
+};
+export declare const catalogText: (catalog: unknown) => string;
+export {};

package/runtime/scripts/cli/gen-catalog.mjs

@@ -0,0 +1,72 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// gen-catalog.mjs - writes packages/cli/src/catalog.generated.mjs, the command table the documentation check judges a `starci ...` text against
+// (scripts/hfs/doc-commands.mjs checkCommand; rules/doc-fresh.mjs HFS_DOC_COMMAND_UNKNOWN), from the one owner of every verb: the registry of
+// the starci CLI (cli/src/registry.ts ALL_VERBS, built to cli/dist/registry.js). Run it from the harness repository after the CLI is built:
+//   node packages/hfs/runtime/scripts/cli/gen-catalog.mjs [--registry <registry.js>] [--check]
+// --check writes nothing and exits 1 when the committed catalog differs from the registry's.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isMain } from '../lib/is-main.mjs';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const CATALOG_FILE = path.resolve(HERE, '../../packages/cli/src/catalog.generated.mjs');
+const DEFAULT_REGISTRY = path.resolve(HERE, '../../../../../cli/dist/registry.js');
+const GLOBAL = [
+    { name: 'json', type: 'boolean', summary: 'print one json envelope instead of human text' },
+    { name: 'cwd', type: 'string', summary: 'run as if started in this directory' },
+    { name: 'help', type: 'boolean', summary: 'print the help of the command' },
+];
+const TYPES = { boolean: 'boolean', string: 'string', list: 'list' };
+/** One registry verb as the catalog entry validate-args.mjs reads: its options, its positional slots in order, its editions. */
+function entryOf(verb) {
+    const specs = Object.entries(verb.flags);
+    return {
+        summary: verb.summary,
+        flags: specs.filter(([, spec]) => spec.positional !== true && spec.kind !== 'rest')
+            .map(([name, spec]) => ({ name, type: TYPES[spec.kind], summary: spec.summary, ...(spec.required === true ? { required: true } : {}) })),
+        positional: specs.filter(([, spec]) => spec.positional === true || spec.kind === 'rest')
+            .map(([name, spec]) => ({ name, required: spec.required === true, variadic: spec.kind === 'rest' })),
+        editions: [...verb.editions],
+        json: 'flag',
+    };
+}
+/** The catalog of `verbs`: a two-word verb under its group, a one-word verb (`starci explain [term]`) as the group's `self`. */
+export function catalogOf(verbs) {
+    const groups = {};
+    for (const verb of verbs) {
+        const [group, name] = verb.path;
+        groups[group] ??= { verbs: {} };
+        if (name === undefined)
+            groups[group].self = entryOf(verb);
+        else
+            groups[group].verbs[name] = entryOf(verb);
+    }
+    return { schema: 'starci/cli-catalog@2', global: GLOBAL, groups };
+}
+export const catalogText = (catalog) => `// GENERATED by runtime/scripts/cli/gen-catalog.mjs from the starci CLI registry (cli/src/registry.ts) - do not edit
+export const CATALOG = ${JSON.stringify(catalog, null, 2)};
+`;
+async function main(argv) {
+    const at = argv.indexOf('--registry');
+    const registry = at >= 0 ? path.resolve(argv[at + 1] ?? '') : DEFAULT_REGISTRY;
+    // reason: the registry is the built starci CLI, a dynamic import whose module type is not known here; ALL_VERBS is typed on receipt
+    const { ALL_VERBS } = await import(__rewriteRelativeImportExtension(pathToFileURL(registry).href));
+    const text = catalogText(catalogOf(ALL_VERBS));
+    if (argv.includes('--check')) {
+        const same = fs.existsSync(CATALOG_FILE) && fs.readFileSync(CATALOG_FILE, 'utf8') === text;
+        process.stdout.write(same ? 'catalog.generated.mjs matches the registry\n' : 'catalog.generated.mjs differs from the registry: run gen-catalog.mjs\n');
+        return same ? 0 : 1;
+    }
+    fs.writeFileSync(CATALOG_FILE, text);
+    process.stdout.write(`wrote ${path.relative(process.cwd(), CATALOG_FILE)} (${ALL_VERBS.length} verbs)\n`);
+    return 0;
+}
+if (isMain(import.meta.url))
+    process.exitCode = await main(process.argv.slice(2));

package/runtime/scripts/gates/runtime-host.d.mts

@@ -0,0 +1,23 @@
+/** The repository hosting this runtime: STARCI_SOURCE_ROOT, else the folder holding the runtime's main checkout. */
+export declare function runtimeHostRoot(env?: NodeJS.ProcessEnv): string;
+/** The canonical runtime main root of a runtime checkout or lane (its secret.env lives there); throws when the root is not a verified Git top level. */
+export declare function verifiedRuntimeMain(runtimeRoot: unknown, env: NodeJS.ProcessEnv): string;
+/**
+ * Load host-local credentials from this runtime's verified main tree, or its installed physical tree.
+ * A lane never reads its own alternate file. The actual environment wins; no process state is mutated.
+ */
+export declare function runtimeSecretEnv(env?: NodeJS.ProcessEnv, runtimeRoot?: string): NodeJS.ProcessEnv;
+/**
+ * The checkout of the repository a declaration names: the declaring repository itself, the runtime host, or a sibling
+ * checkout of either (by repository identity, so a worktree and its main checkout are one repository). Null when the
+ * repository is not checked out on this machine.
+ */
+export declare function resolveDeclaredRepository(name: unknown, { fromRepo }?: {
+    fromRepo?: string | null | undefined;
+}): string | null;
+/**
+ * A custody path of a declared repository as a file on this machine. A path under `.claude/` of the runtime host is a member of
+ * the runtime tree in use (this checkout, a lane worktree included), the same rule a host-owned stack root `.claude/ext/<service>`
+ * follows; any other path is joined to the repository's checkout. A path with a `..` segment is refused (null).
+ */
+export declare function resolveCustodyFile(repo: string | null | undefined, rel: string | null | undefined): string | null;

package/runtime/scripts/gates/runtime-host.mjs

@@ -13,71 +13,78 @@ import { repositoryHome, repositoryName } from '../hfs/repo-identity.mjs';
 import { secretEnv } from '../../engine/secrets.mjs';
 import { revParseQuery } from '../api/git/rev-parse-query.mjs';
 import { gitOutputOf } from '../lib/git.mjs';
-
+import { errorCode } from '../api/fs/lib.mjs';
 /** The repository hosting this runtime: STARCI_SOURCE_ROOT, else the folder holding the runtime's main checkout. */
 export function runtimeHostRoot(env = process.env) {
-  if (env.STARCI_SOURCE_ROOT) return starciSourceRoot(env);
-  return path.dirname(repositoryHome(skillRoot));
+    if (env.STARCI_SOURCE_ROOT)
+        return starciSourceRoot(env);
+    return path.dirname(repositoryHome(skillRoot));
 }
-
 /** The canonical runtime main root of a runtime checkout or lane (its secret.env lives there); throws when the root is not a verified Git top level. */
 export function verifiedRuntimeMain(runtimeRoot, env) {
-  if (typeof runtimeRoot !== 'string' || !path.isAbsolute(runtimeRoot))
-    throw new TypeError('runtimeSecretEnv requires an absolute runtime root');
-  const stat = fs.lstatSync(runtimeRoot);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('runtime root must be a regular directory');
-  const root = fs.realpathSync.native(runtimeRoot), marker = path.join(root, '.git');
-  let gitMarker;
-  try { gitMarker = fs.lstatSync(marker); } catch (error) {
-    if (error?.code === 'ENOENT') return root;
-    throw error;
-  }
-  if (gitMarker.isSymbolicLink() || (!gitMarker.isFile() && !gitMarker.isDirectory()))
-    throw new Error('runtime Git identity is unavailable');
-  const topLevel = cwd => fs.realpathSync.native(path.resolve(cwd,
-    gitOutputOf(revParseQuery(['--show-toplevel'], { cwd, env })).trim()));
-  if (!same(topLevel(root), root)) throw new Error('runtime must be its Git top level');
-  const main = fs.realpathSync.native(repositoryHome(root)), mainMarker = fs.lstatSync(path.join(main, '.git'));
-  if (!mainMarker.isDirectory() || mainMarker.isSymbolicLink() || !same(topLevel(main), main))
-    throw new Error('runtime main Git identity is unavailable');
-  return main;
+    if (typeof runtimeRoot !== 'string' || !path.isAbsolute(runtimeRoot))
+        throw new TypeError('runtimeSecretEnv requires an absolute runtime root');
+    const stat = fs.lstatSync(runtimeRoot);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('runtime root must be a regular directory');
+    const root = fs.realpathSync.native(runtimeRoot), marker = path.join(root, '.git');
+    let gitMarker;
+    try {
+        gitMarker = fs.lstatSync(marker);
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return root;
+        throw error;
+    }
+    if (gitMarker.isSymbolicLink() || (!gitMarker.isFile() && !gitMarker.isDirectory()))
+        throw new Error('runtime Git identity is unavailable');
+    const topLevel = (cwd) => fs.realpathSync.native(path.resolve(cwd, gitOutputOf(revParseQuery(['--show-toplevel'], { cwd, env })).trim()));
+    if (!same(topLevel(root), root))
+        throw new Error('runtime must be its Git top level');
+    const main = fs.realpathSync.native(repositoryHome(root)), mainMarker = fs.lstatSync(path.join(main, '.git'));
+    if (!mainMarker.isDirectory() || mainMarker.isSymbolicLink() || !same(topLevel(main), main))
+        throw new Error('runtime main Git identity is unavailable');
+    return main;
 }
-
 /**
  * Load host-local credentials from this runtime's verified main tree, or its installed physical tree.
  * A lane never reads its own alternate file. The actual environment wins; no process state is mutated.
  */
 export function runtimeSecretEnv(env = process.env, runtimeRoot = skillRoot) {
-  return secretEnv(verifiedRuntimeMain(runtimeRoot, env), env);
+    return secretEnv(verifiedRuntimeMain(runtimeRoot, env), env);
 }
-
 const same = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
-
 /**
  * The checkout of the repository a declaration names: the declaring repository itself, the runtime host, or a sibling
  * checkout of either (by repository identity, so a worktree and its main checkout are one repository). Null when the
  * repository is not checked out on this machine.
  */
 export function resolveDeclaredRepository(name, { fromRepo } = {}) {
-  const wanted = typeof name === 'string' && name.trim() ? name.trim() : null;
-  if (!wanted) return null;
-  const candidates = [...(fromRepo ? [path.resolve(fromRepo)] : []), runtimeHostRoot()];
-  for (const dir of candidates) if (same(repositoryName(dir), wanted) && isDir(dir)) return dir;
-  for (const dir of candidates) {
-    const sibling = path.join(path.dirname(repositoryHome(dir)), wanted);
-    if (isDir(sibling)) return sibling;
-  }
-  return null;
+    const wanted = typeof name === 'string' && name.trim() ? name.trim() : null;
+    if (!wanted)
+        return null;
+    const candidates = [...(fromRepo ? [path.resolve(fromRepo)] : []), runtimeHostRoot()];
+    for (const dir of candidates)
+        if (same(repositoryName(dir), wanted) && isDir(dir))
+            return dir;
+    for (const dir of candidates) {
+        const sibling = path.join(path.dirname(repositoryHome(dir)), wanted);
+        if (isDir(sibling))
+            return sibling;
+    }
+    return null;
 }
-
 /**
  * A custody path of a declared repository as a file on this machine. A path under `.claude/` of the runtime host is a member of
  * the runtime tree in use (this checkout, a lane worktree included), the same rule a host-owned stack root `.claude/ext/<service>`
  * follows; any other path is joined to the repository's checkout. A path with a `..` segment is refused (null).
  */
 export function resolveCustodyFile(repo, rel) {
-  if (!repo || !rel || String(rel).split(/[\\/]/).includes('..')) return null;
-  const posix = String(rel).replaceAll('\\', '/');
-  if (posix.startsWith('.claude/') && same(path.resolve(repo), path.resolve(runtimeHostRoot()))) return path.join(skillRoot, posix.slice('.claude/'.length));
-  return path.join(repo, rel);
+    if (!repo || !rel || String(rel).split(/[\\/]/).includes('..'))
+        return null;
+    const posix = String(rel).replaceAll('\\', '/');
+    if (posix.startsWith('.claude/') && same(path.resolve(repo), path.resolve(runtimeHostRoot())))
+        return path.join(skillRoot, posix.slice('.claude/'.length));
+    return path.join(repo, rel);
 }

package/runtime/scripts/gates/sonar-gate.d.mts

@@ -0,0 +1,219 @@
+export declare const GATE_SCHEMA = "starci/sonar-gate@1";
+export declare const SCAN_SCHEMA_PREFIX = "starci/sonar-local-scan@";
+/** A coverage policy descriptor: the Sonar metric and the per-file minimum percent. */
+export interface GateCoverage {
+    metric: string;
+    minPercent: number;
+}
+interface GateMetric {
+    metric: string;
+}
+/** The new-code half of the gate. */
+export interface GateNewCode {
+    coverage?: GateCoverage;
+    ignoreBelowChangedLines: number;
+    duplication: GateMetric & {
+        maxPercent: number;
+    };
+    hotspots: GateMetric & {
+        minReviewedPercent: number;
+        unreviewedMax: number;
+    };
+    issues: {
+        blockingSeverities: string[];
+        metrics: Record<string, string>;
+        max: number;
+    };
+}
+/** The overall-code half of the gate. */
+export interface GateOverall {
+    coverage?: GateCoverage;
+    issues: GateMetric & {
+        max: number;
+        types: Record<string, unknown>;
+    };
+    hotspots: GateMetric & {
+        minReviewedPercent: number;
+    };
+    duplication: GateMetric & {
+        maxPercent: number;
+    };
+}
+/** knowledge/sonar-gate.yaml: the one Sonar quality gate; an edition key (lite) overlays its own gate, newCode and overall. */
+export interface SonarGate {
+    schema: string;
+    gate: {
+        name: string;
+    };
+    newCode: GateNewCode;
+    overall: GateOverall;
+    enforcedOps: string[];
+    [edition: string]: unknown;
+}
+type Measures = Record<string, unknown>;
+type Numbers = Record<string, number | null>;
+interface NotRequiredCoverage {
+    applied: false;
+    status: string;
+    files: never[];
+    failures: never[];
+    note: string;
+}
+/** The parsed scan summary a slice attaches as sonar.json (JSON read from disk; every field is checked where it is read). */
+export interface ScanSummary {
+    schema?: unknown;
+    outcome?: unknown;
+    scope?: unknown;
+    reason?: unknown;
+    code?: unknown;
+    ownerMode?: {
+        coverage?: unknown;
+        note?: unknown;
+    } | null;
+    slice?: {
+        failures?: unknown;
+    } | null;
+}
+/** A server gate condition (SonarQube api/qualitygates). */
+export interface GateCondition {
+    metric: string | undefined;
+    op: string;
+    error: string;
+}
+/** The coverage scope of a sonar-project.properties map. */
+export interface CoverageScope {
+    exclusions: string[];
+    sources: string[];
+    excluded: string[];
+    tests: string[];
+}
+/** The coverage measure of one file (null when Sonar holds none). */
+export interface FileCoverage {
+    path: string;
+    coverage: unknown;
+}
+/** judgeCoverage's verdict. */
+export interface CoverageVerdict {
+    applied: boolean;
+    exclusions: string[];
+    minPercent: number;
+    files: Array<{
+        path: string;
+        coverage: number | null;
+        ok: boolean;
+    }>;
+    failures: string[];
+    note?: string;
+}
+/** Read the canonical gate for the repository's declared edition; cache the document, never a selected app view. */
+export declare function loadSonarGate({ base, file, cwd }?: {
+    base?: string;
+    file?: string | null;
+    cwd?: string | null;
+}): SonarGate;
+/**
+ * The conditions the server gate carries: [{metric, op, error}] (SonarQube api/qualitygates conditions): the new-code ones
+ * (coverage, duplication, hotspots, blocking issues), then the overall-code ones (coverage, open issues of any origin,
+ * imported HFS/ESLint/stylelint findings included, reviewed hotspots and duplication). Coverage is the services' coverage:
+ * the scope is what sonar.coverage.exclusions of the managed sonar-project.properties leaves (coverageScopeOf).
+ */
+export declare function serverConditions(gate: SonarGate): GateCondition[];
+/** The ops the runtime holds to the gate at settle. */
+export declare const enforcedOps: (gate: SonarGate) => Set<string>;
+/** What the slice verdict is judged against: the numbers a scan copies into its summary (`gate`). */
+export declare function thresholdsOf(gate: SonarGate): {
+    name: string;
+    ignoreBelowChangedLines: number;
+    duplicationMaxPercent: number;
+    blockingSeverities: string[];
+    blockingIssuesMax: number;
+    unreviewedHotspotsMax: number;
+    coverageMinPercent: number | null;
+};
+/**
+ * The coverage scope of a sonar-project.properties map (readProperties), as Sonar computes it: SonarQube has no coverage
+ * inclusions, so the files it measures coverage on are the source files of `sonar.sources` that neither `sonar.exclusions`,
+ * `sonar.coverage.exclusions` nor the test patterns (`sonar.test.inclusions`) take. The managed properties render
+ * sonar.coverage.exclusions as the complement of the services (starci app sync coverageExclusions), so what is left is the services.
+ * Returns {exclusions, sources, excluded, tests}; `exclusions` empty means the repository declares no coverage scope.
+ */
+export declare function coverageScopeOf(props?: Record<string, unknown>): CoverageScope;
+/** True for a repository-relative path Sonar measures coverage on under `scope` (coverageScopeOf; Sonar's glob subset, scripts/lib/glob.mjs). */
+export declare function coverageTargetOf(scope: Partial<CoverageScope>): (file: unknown) => boolean;
+/**
+ * The per-file coverage verdict: `files` are [{path, coverage}] (coverage the Sonar `coverage` measure of the file, a number
+ * or null when Sonar has none), `scope` the repository's coverage scope (coverageScopeOf). Only a file of the scope is a
+ * coverage target: every other file (a handler, a resolver, a module, a config file, a test, anything under fe/) is not
+ * judged and not listed, whatever its measure. A target below `minPercent` fails, and so does a target Sonar holds no
+ * coverage for (the lcov report was not imported or does not name it): a missing number is never a pass. With no
+ * sonar.coverage.exclusions the repository declares no coverage scope and nothing is judged (`applied` false).
+ * Returns {applied, exclusions, minPercent, files: [{path, coverage, ok}], failures: [text]}.
+ */
+export declare function judgeCoverage(files: FileCoverage[], { scope, minPercent }: {
+    scope?: CoverageScope;
+    minPercent: number;
+}): CoverageVerdict;
+/**
+ * The dashboard verdict of a whole project (`sonar-local dashboard`): `measures` the project's measures by metric key
+ * (bugs, code_smells, vulnerabilities, security_hotspots, security_hotspots_reviewed, duplicated_lines_density, coverage), `files` the per-file
+ * coverage of the project (as judgeCoverage takes it), `scope` its coverage scope (coverageScopeOf). It fails unless every
+ * issue type of `overall.issues.types` is at `overall.issues.max`, every hotspot is reviewed (a project with no hotspot has
+ * none to review), duplication meets its declared maximum, and required coverage meets its per-file threshold. Returns {verdict, numbers, coverage, failures}.
+ */
+export declare function judgeDashboard({ measures, files, scope }: {
+    measures?: Measures;
+    files?: FileCoverage[];
+    scope?: CoverageScope;
+}, gate: SonarGate): {
+    verdict: string;
+    numbers: Numbers;
+    coverage: NotRequiredCoverage | CoverageVerdict;
+    failures: string[];
+};
+/**
+ * What a filed sonar.json says, as a settle judgment. `summary` is the parsed scan summary (or null when the op attached
+ * none). Returns {status, code, detail, findings[]}:
+ *   pass         the slice meets the gate (or Sonar is disabled by the repository's own declaration - noted)
+ *   red          the slice fails the gate on new code: findings[] names every failing condition
+ *   unavailable  the scan could not run (server down, custody missing, token rejected): never a pass
+ *   refused      the scan was refused before it ran (unknown base, empty slice ...): the op fixes and reruns
+ *   missing      no sonar.json (or one that is not a scan summary) is attached
+ * A slice that changed no file is a pass with `note`: there is nothing new to fail.
+ * Owner mode: a summary that says `ownerMode.coverage: not-measured` (the owner's specs.unit off) passes on its other
+ * conditions with `coverage: 'not-measured'` and the owner-mode `note`, never as a plain pass, and only when `specs` (the
+ * owner switches the caller read) confirms unit is off; otherwise the claim is refused as sonar-proof-missing.
+ */
+export declare function judgeSummary(summary: ScanSummary | null | undefined, _gate: SonarGate, { specs }?: {
+    specs?: {
+        unit?: boolean;
+    } | null;
+}): {
+    status: string;
+    code: null;
+    detail: null;
+    coverage: string;
+    note: string;
+    findings: never[];
+} | {
+    status: string;
+    code: null;
+    detail: null;
+    findings: never[];
+    coverage?: never;
+    note?: never;
+} | {
+    status: string;
+    code: string;
+    detail: string;
+    findings: string[];
+    coverage?: never;
+    note?: never;
+} | {
+    status: string;
+    code: null;
+    detail: null;
+    note: string;
+    findings: never[];
+    coverage?: never;
+};
+export {};