@starci/cli 1.0.0

package/src/completion.mjs

@@ -0,0 +1,17 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const FILES = {
+  bash: 'starci.bash',
+  zsh: '_starci',
+  fish: 'starci.fish',
+  powershell: 'starci.ps1',
+};
+
+export const completionShells = Object.freeze(Object.keys(FILES));
+
+export function completionFor(shell, { read = readFileSync } = {}) {
+  const file = FILES[shell];
+  if (!file) return null;
+  return read(fileURLToPath(new URL(`../completions/${file}`, import.meta.url)), 'utf8');
+}

package/src/help.mjs

@@ -0,0 +1,84 @@
+const usageTail = (verb) => {
+  const positional = (verb.positional ?? []).map((entry) => {
+    const value = entry.enum?.length ? entry.enum.join('|') : entry.name;
+    const rendered = entry.variadic ? `${value}...` : value;
+    return entry.required ? `<${rendered}>` : `[${rendered}]`;
+  });
+  return positional.length ? ` ${positional.join(' ')}` : '';
+};
+
+const rows = (entries) => {
+  const width = Math.max(0, ...entries.map(([name]) => name.length));
+  return entries.map(([name, summary]) => `  ${name.padEnd(width)}  ${summary}`).join('\n');
+};
+
+export function topHelp(catalog, version = null) {
+  const groups = Object.entries(catalog.groups ?? {}).map(([name, group]) => [name, group.summary ?? '']);
+  const options = (catalog.global ?? []).map((flag) => [`--${flag.name}${flag.type === 'boolean' ? '' : ` <${flag.name}>`}`, flag.summary ?? '']);
+  const explainUsage = (catalog.commands ?? []).includes('explain') ? ['       starci explain <group> <verb>'] : [];
+  return [
+    `starci${version ? ` ${version}` : ''} - one CLI for apps and the StarCi runtime`,
+    '',
+    'Usage: starci <group> <verb> [options]',
+    '       starci help',
+    '       starci completion <bash|zsh|fish|powershell>',
+    ...explainUsage,
+    '',
+    'Groups:',
+    rows(groups),
+    '',
+    'Global options:',
+    rows(options),
+    '',
+  ].join('\n');
+}
+
+export function groupHelp(catalog, groupName) {
+  const group = catalog.groups?.[groupName];
+  if (!group) return null;
+  const verbs = Object.entries(group.verbs ?? {}).map(([name, verb]) => {
+    const effect = verb.effect && verb.effect !== 'read' ? `[${verb.effect}] ` : '';
+    return [name, `${effect}${verb.summary ?? ''}`];
+  });
+  return [
+    `starci ${groupName} - ${group.summary ?? ''}`,
+    '',
+    `Usage: starci ${groupName} <verb> [options]`,
+    '',
+    'Verbs:',
+    rows(verbs),
+    '',
+  ].join('\n');
+}
+
+export function verbHelp(catalog, groupName, verbName) {
+  const verb = catalog.groups?.[groupName]?.verbs?.[verbName];
+  if (!verb) return null;
+  const local = (verb.flags ?? []).map((flag) => {
+    const value = flag.type === 'boolean' ? '' : flag.type === 'enum' ? ` <${(flag.enum ?? []).join('|')}>` : ` <${flag.name}>`;
+    const required = flag.required ? ' (required)' : '';
+    return [`--${flag.name}${value}`, `${flag.summary ?? ''}${required}`];
+  });
+  const exits = Object.entries(verb.exit ?? {}).map(([code, summary]) => [code, summary]);
+  return [
+    `starci ${groupName} ${verbName} - ${verb.summary ?? ''}`,
+    '',
+    `Usage: starci ${groupName} ${verbName}${usageTail(verb)} [options]`,
+    ...(local.length ? ['', 'Options:', rows(local)] : []),
+    ...(verb.effect ? ['', `Effect: ${verb.effect}`] : []),
+    ...(verb.roles?.length ? [`Roles: ${verb.roles.join(', ')}`] : []),
+    ...(verb.conventions?.length ? ['', 'Conventions:', ...verb.conventions.map((line) => `  - ${line}`)] : []),
+    ...(exits.length ? ['', 'Exit codes:', rows(exits)] : []),
+    ...(verb.json ? ['', `JSON: ${verb.json}`] : []),
+    ...((verb.examples ?? []).length ? ['', 'Examples:', ...(verb.examples ?? []).map((example) => `  ${example}`)] : []),
+    '',
+  ].join('\n');
+}
+
+/** Full verb help plus the retired raw spellings the catalogued verb replaces. */
+export function explainHelp(catalog, groupName, verbName) {
+  const verb = catalog.groups?.[groupName]?.verbs?.[verbName];
+  if (!verb) return null;
+  const help = verbHelp(catalog, groupName, verbName).trimEnd();
+  return `${help}${verb.removed?.length ? `\n\nReplaces: ${verb.removed.join(', ')}` : ''}\n`;
+}

package/src/main.mjs

@@ -0,0 +1,265 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { locateRuntime, runtimeEntryOf } from './runtime-locate.mjs';
+import { runtimeEnv } from './shim.mjs';
+
+const packageFile = fileURLToPath(new URL('../package.json', import.meta.url));
+const cliVersion = () => JSON.parse(readFileSync(packageFile, 'utf8')).version;
+const GUARD_FAST_PATH = Object.freeze({ command: 'command-guard.mjs', 'seat-tools': 'seat-tools.mjs' });
+
+const importHfs = async () => {
+  try {
+    return await import('@starci/hfs');
+  } catch (error) {
+    if (error?.code !== 'ERR_MODULE_NOT_FOUND' || !String(error?.message ?? '').includes('@starci/hfs')) throw error;
+    // The StarCi runtime ships packages/cli and packages/hfs side by side without
+    // making the repository an npm workspace. Published @starci/cli resolves its
+    // normal exact dependency above; the embedded runtime uses this payload path.
+    return import(new URL('../../hfs/src/main.mjs', import.meta.url));
+  }
+};
+
+const writeTo = (target, text) => {
+  if (typeof target === 'function') target(text);
+  else target.write(text);
+};
+
+const noRuntime = (stderr, group, skipped) => {
+  for (const note of skipped) writeTo(stderr, `starci: ignored: ${note}\n`);
+  return fail(stderr, `the runtime group "${group}" needs the StarCi runtime, which is not installed (run: starci runtime install)`, 3);
+};
+
+const fail = (stderr, message, code = 2) => {
+  writeTo(stderr, `starci: ${message}\n`);
+  return code;
+};
+
+/**
+ * The hooks run on every tool call. Exact hook invocations bypass the generated catalog, help modules and a second
+ * Node process; help and malformed invocations fall through to the catalog-driven dispatcher below.
+ */
+const guardFastPath = async (argv, io) => {
+  if (argv.length !== 2 || argv[0] !== 'guard' || !Object.hasOwn(GUARD_FAST_PATH, argv[1])) return null;
+  const stderr = io.stderr ?? process.stderr;
+  const cwd = io.cwd ?? process.cwd();
+  const skipped = [];
+  const located = (io.locateRuntime ?? locateRuntime)({ cwd, env: io.env ?? process.env, skipped, ...(io.home ? { home: io.home } : {}) });
+  if (!located) return noRuntime(stderr, 'guard', skipped);
+  try {
+    const file = path.join(located.root, 'scripts', 'guards', GUARD_FAST_PATH[argv[1]]);
+    const guard = await (io.importGuard ?? ((target) => import(pathToFileURL(target).href)))(file);
+    if (typeof guard.main !== 'function') return fail(stderr, `guard ${argv[1]} has no in-process entry`, 1);
+    return Number(await guard.main({
+      stdin: io.stdin ?? process.stdin,
+      stdout: io.stdout ?? process.stdout,
+      stderr,
+      env: io.env ?? process.env,
+    })) || 0;
+  } catch (error) {
+    return fail(stderr, `cannot load guard ${argv[1]}: ${error?.message ?? error}`, 1);
+  }
+};
+
+// `starci <old>` spellings match from the program name; the retired `hfs` and `starci-test-stack` bins also match behind it.
+const RETIRED_BINS = new Set(['hfs', 'starci-test-stack']);
+const retiredMatch = (words, retired) => {
+  const input = ['starci', ...words];
+  const candidates = retired
+    .map((entry) => {
+      const tokens = entry.spelling.split(/\s+/);
+      if (tokens[0] === 'starci') return { ...entry, tokens, offset: 0 };
+      return RETIRED_BINS.has(tokens[0]) ? { ...entry, tokens, offset: 1 } : null;
+    })
+    .filter((entry) => entry && entry.tokens.every((token, index) => input[index + entry.offset] === token))
+    .sort((a, b) => b.tokens.length - a.tokens.length);
+  const match = candidates[0];
+  if (!match) return null;
+  const suffix = input.slice(match.offset + match.tokens.length);
+  return {
+    spelling: [...input.slice(0, match.offset), ...match.tokens, ...suffix].join(' '),
+    use: [...match.use.split(/\s+/), ...suffix].join(' '),
+  };
+};
+
+const handlerArgs = (validated, command, withFlagsBeforeDashes, { includeQuiet = true } = {}) => {
+  const extra = [];
+  if (validated.global.json === true && command.json !== 'always') extra.push('--json');
+  if (validated.global.edition !== undefined) extra.push('--edition', validated.global.edition);
+  if (includeQuiet && validated.global.quiet === true) extra.push('--quiet');
+  return withFlagsBeforeDashes(validated.localArgs, extra);
+};
+
+/** The published CLI entry, with I/O and process seams for deterministic specs. */
+export async function main(argv = process.argv.slice(2), io = {}) {
+  const guarded = await guardFastPath(argv, io);
+  if (guarded !== null) return guarded;
+  const [catalogModule, completionModule, helpModule, installModule, linkModule, argsModule] = await Promise.all([
+    import('./catalog.generated.mjs'),
+    import('./completion.mjs'),
+    import('./help.mjs'),
+    import('./runtime-install.mjs'),
+    import('./runtime-link.mjs'),
+    import('./validate-args.mjs'),
+  ]);
+  const { CATALOG, RETIRED } = catalogModule;
+  const { completionFor, completionShells } = completionModule;
+  const { explainHelp, groupHelp, topHelp, verbHelp } = helpModule;
+  const { installRuntime } = installModule;
+  const { linkRuntime } = linkModule;
+  const { splitCommand, validateArgs, withFlagsBeforeDashes } = argsModule;
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const catalog = io.catalog ?? CATALOG;
+  const retired = io.retired ?? RETIRED;
+  const version = io.version ?? cliVersion();
+  const home = io.home;
+  const env = io.env ?? process.env;
+  const initialCwd = io.cwd ?? process.cwd();
+
+  if (argv.length === 0 || (argv.length === 1 && ['help', '--help', '-h'].includes(argv[0]))) {
+    writeTo(stdout, topHelp(catalog, version));
+    return 0;
+  }
+  if (argv.length === 1 && argv[0] === '--version') {
+    writeTo(stdout, `${version}\n`);
+    return 0;
+  }
+
+  const split = splitCommand(argv, catalog.global ?? []);
+  const removed = split.group ? retiredMatch([split.group, ...(split.verb ? [split.verb] : []), ...split.args], retired) : null;
+  if (removed) return fail(stderr, `"${removed.spelling}" was removed; use "${removed.use}"`);
+
+  if (split.group === 'help') {
+    const [verbName] = split.args.filter((token) => !token.startsWith('-'));
+    const target = split.verb ? catalog.groups?.[split.verb] : null;
+    if (split.verb && !target) return fail(stderr, `unknown group "${split.verb}"`);
+    if (verbName && !target.verbs?.[verbName]) return fail(stderr, `unknown verb "${verbName}" for group "${split.verb}"`);
+    writeTo(stdout, !split.verb ? topHelp(catalog, version) : verbName ? verbHelp(catalog, split.verb, verbName) : groupHelp(catalog, split.verb));
+    return 0;
+  }
+  if (split.group === 'completion') {
+    const shell = split.verb;
+    if (split.help && !split.args.length) {
+      writeTo(stdout, `Usage: starci completion <${completionShells.join('|')}>\n`);
+      return 0;
+    }
+    if (!completionShells.includes(shell) || split.args.length) {
+      return fail(stderr, `completion expects one of: ${completionShells.join(', ')}`);
+    }
+    const text = (io.completionFor ?? completionFor)(shell);
+    if (text == null) return fail(stderr, `completion expects one of: ${completionShells.join(', ')}`);
+    writeTo(stdout, text);
+    return 0;
+  }
+  if (split.group === 'explain' && (catalog.commands ?? []).includes('explain')) {
+    if (split.help && !split.verb && !split.args.length) {
+      writeTo(stdout, 'Usage: starci explain <group> <verb>\n');
+      return 0;
+    }
+    const groupName = split.verb;
+    const verbNames = split.args.filter((token) => !token.startsWith('-'));
+    if (!groupName || verbNames.length !== 1) return fail(stderr, 'explain expects <group> <verb>');
+    const target = catalog.groups?.[groupName];
+    if (!target) return fail(stderr, `unknown group "${groupName}"`);
+    const verbName = verbNames[0];
+    if (!target.verbs?.[verbName]) {
+      return fail(stderr, `unknown verb "${verbName}" for group "${groupName}" (available: ${Object.keys(target.verbs ?? {}).join(', ')})`);
+    }
+    writeTo(stdout, explainHelp(catalog, groupName, verbName));
+    return 0;
+  }
+
+  const wantsHelp = split.help;
+  if (!split.group) {
+    if (wantsHelp) {
+      writeTo(stdout, topHelp(catalog, version));
+      return 0;
+    }
+    return fail(stderr, 'missing command group');
+  }
+  const group = catalog.groups?.[split.group];
+  if (!group) return fail(stderr, `unknown group "${split.group}"`);
+  if (!split.verb) {
+    if (wantsHelp) {
+      writeTo(stdout, groupHelp(catalog, split.group));
+      return 0;
+    }
+    return fail(stderr, `missing verb for group "${split.group}"`);
+  }
+  const command = group.verbs?.[split.verb];
+  if (!command) return fail(stderr, `unknown verb "${split.verb}" for group "${split.group}"`);
+  if (wantsHelp) {
+    writeTo(stdout, verbHelp(catalog, split.group, split.verb));
+    return 0;
+  }
+
+  const validated = validateArgs(split.args, { ...command, group: split.group, verb: split.verb }, catalog.global ?? []);
+  if (!validated.ok) return fail(stderr, validated.error, validated.code);
+  const cwd = path.resolve(initialCwd, validated.global.cwd ?? '.');
+  const args = handlerArgs(validated, command, withFlagsBeforeDashes);
+
+  if (split.group === 'runtime' && split.verb === 'install') {
+    const install = io.installRuntime ?? installRuntime;
+    return await install({
+      cwd,
+      ...(home ? { home } : {}),
+      force: validated.values.force === true,
+      hosts: validated.values.hosts ?? null,
+      noBootstrap: validated.values['no-bootstrap'] === true,
+    }, io.runtimeInstallDeps ?? {});
+  }
+
+  if (split.group === 'runtime' && split.verb === 'link') {
+    const link = io.linkRuntime ?? linkRuntime;
+    return await link({
+      cwd,
+      ...(home ? { home } : {}),
+      root: validated.values.root ?? null,
+      json: validated.global.json === true,
+      quiet: validated.global.quiet === true,
+      stdout,
+      stderr,
+    }, io.runtimeLinkDeps ?? {});
+  }
+
+  if (group.owner === '@starci/hfs') {
+    try {
+      const hfs = await (io.importHfs ?? importHfs)();
+      const entry = hfs.main ?? hfs.default?.main;
+      if (typeof entry !== 'function') return fail(stderr, '@starci/hfs does not export main(argv, io)', 1);
+      return Number(await entry([split.verb, ...args], {
+        ...io,
+        cwd,
+        stdout: (text) => writeTo(stdout, text),
+        stderr: (text) => writeTo(stderr, text),
+      })) || 0;
+    } catch (error) {
+      return fail(stderr, `cannot load @starci/hfs: ${error?.message ?? error}`, 1);
+    }
+  }
+
+  const skipped = [];
+  const located = (io.locateRuntime ?? locateRuntime)({ cwd, env, skipped, ...(home ? { home } : {}) });
+  if (!located) return noRuntime(stderr, split.group, skipped);
+  const spawn = io.spawn ?? spawnSync;
+  let result;
+  try {
+    result = spawn(process.execPath, [runtimeEntryOf(located.root), split.group, split.verb, ...args], {
+      cwd,
+      env: runtimeEnv(env, home ? { home } : {}),
+      stdio: 'inherit',
+      windowsHide: true,
+    });
+  } catch (error) {
+    return fail(stderr, `cannot run the runtime: ${error?.message ?? error}`, 1);
+  }
+  if (result?.error) {
+    if (result.error.code === 'ENOENT' && !existsSync(cwd)) return fail(stderr, `--cwd "${cwd}" is not a directory`);
+    return fail(stderr, `cannot run the runtime: ${result.error.message ?? result.error}`, 1);
+  }
+  if (result?.status == null) return fail(stderr, `the runtime stopped on signal ${result?.signal ?? 'unknown'}`, 1);
+  return result.status;
+}

package/src/package-entry.spec.mjs

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { lstatSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { main } from './main.mjs';
+
+const bin = fileURLToPath(new URL('../bin/starci.mjs', import.meta.url));
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const run = (...args) => spawnSync(process.execPath, [bin, ...args], { encoding: 'utf8', windowsHide: true, timeout: 30_000 });
+
+test('the exact installed HFS dependency loads its real published module graph', async () => {
+  const file = fileURLToPath(import.meta.resolve('@starci/hfs/package.json'));
+  const installed = JSON.parse(readFileSync(file, 'utf8'));
+  assert.equal(installed.name, '@starci/hfs');
+  const declared = manifest.dependencies[installed.name];
+  if (declared.startsWith('file:')) {
+    const archive = path.resolve(fileURLToPath(new URL('../', import.meta.url)), declared.slice('file:'.length));
+    assert.equal(path.extname(archive), '.tgz');
+    assert.equal(lstatSync(archive).isFile(), true);
+    // The clean-package owner verifies the original exact version and archive identity in preparePackedDependencies,
+    // then every installed archive byte in verifyPackedDependencies, before running this spec with its scratch alias.
+  } else assert.equal(installed.version, declared);
+  const root = path.dirname(file);
+  assert.equal(lstatSync(root).isDirectory(), true);
+  assert.equal(realpathSync.native(root), path.join(realpathSync.native(fileURLToPath(new URL('../', import.meta.url))), 'node_modules', '@starci', 'hfs'));
+  const hfs = await import('@starci/hfs');
+  assert.equal(typeof hfs.main, 'function');
+});
+
+test('the real binary dispatches finite app explanations through installed HFS', (t) => {
+  const cwd = mkdtempSync(path.join(os.tmpdir(), 'starci-app-main-'));
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+  const declaration = JSON.stringify({ hfs: 2, kind: 'app', project: 'package-entry', sides: {
+    be: { apps: [{ name: 'api', kind: 'api' }] },
+    fe: { apps: [{ name: 'web', kind: 'next' }], reads: ['be/contracts/'] },
+  } });
+  writeFileSync(path.join(cwd, 'hfs.json'), declaration);
+  const owned = run('app', 'explain', 'hfs.json', '--cwd', cwd, '--json');
+  assert.equal(owned.status, 0, owned.stderr || String(owned.error ?? ''));
+  const explained = JSON.parse(owned.stdout);
+  assert.deepEqual([explained.path, explained.status, explained.slot], ['hfs.json', 'owned', 'app.declaration']);
+  const unowned = run('app', 'explain', 'unowned.fixture', '--cwd', cwd, '--json');
+  assert.equal(unowned.status, 1, unowned.stderr || String(unowned.error ?? ''));
+  const refused = JSON.parse(unowned.stdout);
+  assert.deepEqual([refused.path, refused.status, refused.code], ['unowned.fixture', 'no-slot', 'HFS_SLOT_UNDECLARED']);
+  assert.equal(readFileSync(path.join(cwd, 'hfs.json'), 'utf8'), declaration);
+  assert.deepEqual(readdirSync(cwd), ['hfs.json']);
+});
+
+test('the published binary serves its own version and catalog help', () => {
+  const version = run('--version');
+  assert.equal(version.status, 0, version.stderr);
+  assert.equal(version.stdout.trim(), manifest.version);
+  const help = run('--help');
+  assert.equal(help.status, 0, help.stderr);
+  assert.match(help.stdout, /Usage: starci <group> <verb>/);
+  assert.match(help.stdout, /Groups:/);
+  const appHelp = run('app', 'check', '--help');
+  assert.equal(appHelp.status, 0, appHelp.stderr);
+  assert.match(appHelp.stdout, /starci app check/);
+});
+
+test('the published binary refuses unknown commands and invalid flags', () => {
+  const unknown = run('package-entry-unknown');
+  assert.equal(unknown.status, 2);
+  assert.match(unknown.stderr, /unknown group/);
+  const invalid = run('app', 'check', '--package-entry-unknown');
+  assert.equal(invalid.status, 2);
+  assert.match(invalid.stderr, /unknown (?:flag|option)/);
+});
+
+test('the package dispatcher preserves app arguments, cwd and owner exit status', async () => {
+  let called;
+  const code = await main(['--cwd', 'selected-app', 'app', 'check', '--json'], {
+    cwd: path.resolve('package-entry-base'), stdout: () => {}, stderr: () => {},
+    importHfs: async () => ({ main: async (argv, io) => { called = { argv, cwd: io.cwd }; return 1; } }),
+  });
+  assert.equal(code, 1);
+  assert.deepEqual(called, { argv: ['check', '--json'], cwd: path.resolve('package-entry-base', 'selected-app') });
+});

package/src/runtime-install.mjs

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { writeRuntimeShim } from './shim.mjs';
+
+export const RUNTIME_VERSION = '1.0.0-alpha.4';
+
+const writeTo = (target, text) => {
+  if (typeof target === 'function') target(text);
+  else target.write(text);
+};
+
+const npmEntryCandidates = ({ execPath = process.execPath, env = process.env } = {}) => {
+  const nodeDirectory = path.dirname(path.resolve(execPath));
+  const candidates = [];
+  if (typeof env?.npm_execpath === 'string' && path.basename(env.npm_execpath).toLowerCase() === 'npm-cli.js') {
+    candidates.push(path.resolve(env.npm_execpath));
+  }
+  candidates.push(path.join(nodeDirectory, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+  candidates.push(path.join(path.dirname(nodeDirectory), 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+  return [...new Set(candidates)];
+};
+
+/** Find npm's JavaScript entry so Node can execute it without a command shell. */
+export function resolveNpmEntry({ execPath = process.execPath, env = process.env, exists = existsSync } = {}) {
+  return npmEntryCandidates({ execPath, env }).find((candidate) => exists(candidate)) ?? null;
+}
+
+const statusOf = (result, label, report) => {
+  if (typeof result === 'number') return result;
+  if (result?.error) {
+    report(`${label} failed to start: ${result.error.message ?? result.error}`);
+    return 1;
+  }
+  if (result?.status == null) {
+    report(`${label} stopped on signal ${result?.signal ?? 'unknown'}`);
+    return 1;
+  }
+  return result.status;
+};
+
+/**
+ * Install the pinned runtime package and run its own installer.
+ * All network/process work is injectable; specs never need npm or the network.
+ */
+export function installRuntime({ cwd = process.cwd(), home = os.homedir(), force = false, hosts = null, noBootstrap = false, stderr = process.stderr } = {}, deps = {}) {
+  const exists = deps.exists ?? existsSync;
+  const mkdir = deps.mkdir ?? ((directory) => mkdirSync(directory, { recursive: true }));
+  const node = process.execPath;
+  const env = deps.env ?? process.env;
+  const spawn = deps.spawn ?? spawnSync;
+  const report = (message) => writeTo(deps.stderr ?? stderr, `starci: ${message}\n`);
+  const npmEntryResolver = deps.resolveNpmEntry ?? resolveNpmEntry;
+  const runNpm = deps.runNpm ?? ((args, options) => {
+    const npmEntry = npmEntryResolver({ execPath: node, env, exists });
+    if (!npmEntry) {
+      const probed = npmEntryCandidates({ execPath: node, env }).map((candidate) => `"${candidate}"`).join(', ');
+      report(`cannot find npm-cli.js; probed: ${probed}. Install npm alongside Node.js or set npm_execpath to an existing npm-cli.js.`);
+      return 1;
+    }
+    return spawn(node, [npmEntry, ...args], options);
+  });
+  const runNode = deps.runNode ?? ((args, options) => spawn(node, args, options));
+  const installRoot = path.join(home, '.starci', 'runtime');
+  const packageSpec = `starci@${deps.runtimeVersion ?? RUNTIME_VERSION}`;
+  const fetchRuntime = deps.fetchRuntime ?? (() => runNpm(['install', '--prefix', installRoot, packageSpec], {
+    cwd,
+    stdio: 'inherit',
+    windowsHide: true,
+    shell: false,
+  }));
+
+  mkdir(installRoot);
+  let fetched;
+  try {
+    fetched = fetchRuntime({ installRoot, packageSpec, cwd });
+  } catch (error) {
+    report(`npm install failed to start: ${error?.message ?? error}`);
+    return 1;
+  }
+  const fetchStatus = statusOf(fetched, 'npm install', report);
+  if (fetchStatus !== 0) return fetchStatus;
+
+  const runtimeRoot = path.join(installRoot, 'node_modules', 'starci');
+  const installer = path.join(runtimeRoot, 'scripts', 'install', 'install.mjs');
+  if (!exists(installer)) {
+    report(`installed runtime is missing its installer: ${installer}`);
+    return 1;
+  }
+  const verb = exists(path.join(cwd, '.claude')) ? 'update' : 'init';
+  const installerArgs = [installer, verb, '--dir', path.resolve(cwd)];
+  if (force) installerArgs.push('--force');
+  if (hosts) installerArgs.push('--hosts', hosts);
+  if (noBootstrap) installerArgs.push('--no-bootstrap');
+  let installed;
+  try {
+    installed = runNode(installerArgs, { cwd, stdio: 'inherit', windowsHide: true, shell: false });
+  } catch (error) {
+    report(`runtime installer failed to start: ${error?.message ?? error}`);
+    return 1;
+  }
+  const installStatus = statusOf(installed, 'runtime installer', report);
+  if (installStatus !== 0) return installStatus;
+
+  writeRuntimeShim({ root: runtimeRoot, home, cli: fileURLToPath(new URL('../bin/starci.mjs', import.meta.url)) }, deps);
+  return 0;
+}

package/src/runtime-link.mjs

@@ -0,0 +1,71 @@
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { writeRuntimeShim } from './shim.mjs';
+
+export const RUNTIME_ROOT_FILES = Object.freeze([
+  path.join('scripts', 'cli', 'main.mjs'),
+  path.join('packages', 'cli', 'bin', 'starci.mjs'),
+]);
+
+const writeTo = (target, text) => {
+  if (typeof target === 'function') target(text);
+  else target.write(text);
+};
+
+const missingAt = (root, exists) => RUNTIME_ROOT_FILES.filter((relative) => !exists(path.join(root, relative)));
+
+const hookLines = (result) => result?.ok
+  ? result.hooks.map((hook) => `git hook ${hook.name}: ${hook.state} ${hook.path}`)
+  : [`git hooks: ${result?.reason ?? 'not installed'}`];
+
+const gitHookInstaller = async (root) => {
+  const module = await import(pathToFileURL(path.join(root, 'scripts', 'guards', 'git-hooks.mjs')).href);
+  if (typeof module.installGitHooks !== 'function') throw new Error('scripts/guards/git-hooks.mjs does not export installGitHooks');
+  return module.installGitHooks;
+};
+
+/** Find the nearest checkout or installed .claude runtime at or above cwd. */
+export function findRuntimeRoot({ cwd = process.cwd(), exists = existsSync } = {}) {
+  let directory = path.resolve(cwd);
+  for (;;) {
+    for (const candidate of [directory, path.join(directory, '.claude')]) {
+      if (missingAt(candidate, exists).length === 0) return candidate;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+/** Point the per-user StarCi launcher at a live runtime checkout. */
+export async function linkRuntime({ cwd = process.cwd(), home = os.homedir(), root = null, json = false, quiet = false,
+  stdout = process.stdout, stderr = process.stderr } = {}, deps = {}) {
+  const exists = deps.exists ?? existsSync;
+  const requested = root == null ? null : path.resolve(cwd, root);
+  const runtimeRoot = requested ?? findRuntimeRoot({ cwd, exists });
+  if (!runtimeRoot) {
+    writeTo(stderr, `starci: no StarCi runtime root found upward from "${path.resolve(cwd)}"; missing ${RUNTIME_ROOT_FILES.join(', ')}\n`);
+    return 2;
+  }
+
+  const missing = missingAt(runtimeRoot, exists);
+  if (missing.length) {
+    writeTo(stderr, `starci: "${runtimeRoot}" is not a StarCi runtime root; missing ${missing.join(', ')}\n`);
+    return 2;
+  }
+
+  try {
+    const result = writeRuntimeShim({ root: runtimeRoot, home }, deps);
+    const installGitHooks = deps.installGitHooks ?? await gitHookInstaller(runtimeRoot);
+    const hooks = await installGitHooks({ root: runtimeRoot });
+    if (json) writeTo(stdout, `${JSON.stringify(result)}\n`);
+    else if (!quiet) writeTo(stdout, `${[result.runtimeJson, result.shim, ...hookLines(hooks)].join('\n')}\n`);
+    return 0;
+  } catch (error) {
+    writeTo(stderr, `starci: cannot link runtime: ${error?.message ?? error}\n`);
+    return 1;
+  }
+}