@starci/cli 1.0.0 → 1.1.0

package/src/help.mjs

@@ -14,10 +14,10 @@ const rows = (entries) => {
 
 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 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`,
+    `starci${version ? ' ' + version : ''} - one CLI for apps and the StarCi runtime`,
     '',
     'Usage: starci <group> <verb> [options]',
     '       starci help',
@@ -55,7 +55,9 @@ 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}>`;
+    let value = ` <${flag.name}>`;
+    if (flag.type === 'boolean') value = '';
+    else if (flag.type === 'enum') value = ` <${(flag.enum ?? []).join('|')}>`;
     const required = flag.required ? ' (required)' : '';
     return [`--${flag.name}${value}`, `${flag.summary ?? ''}${required}`];
   });
@@ -75,10 +77,7 @@ export function verbHelp(catalog, groupName, verbName) {
   ].join('\n');
 }
 
-/** Full verb help plus the retired raw spellings the catalogued verb replaces. */
+/** Full verb help for a catalogued verb; null when the verb is unknown. */
 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`;
+  return verbHelp(catalog, groupName, verbName);
 }

package/src/main.mjs

@@ -3,7 +3,7 @@ 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 { foreignRuntimeNotice, locateRuntime, ownRuntimeRoot, runtimeEntryOf } from './runtime-locate.mjs';
 import { runtimeEnv } from './shim.mjs';
 
 const packageFile = fileURLToPath(new URL('../package.json', import.meta.url));
@@ -63,27 +63,6 @@ const guardFastPath = async (argv, io) => {
   }
 };
 
-// `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');
@@ -92,118 +71,96 @@ const handlerArgs = (validated, command, withFlagsBeforeDashes, { includeQuiet =
   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();
+const ioCtx = (io) => ({ io, stdout: io.stdout ?? process.stdout, stderr: io.stderr ?? process.stderr, env: io.env ?? process.env, home: io.home });
 
+/** Bare `starci`, `help`/`--help`/`-h` and `--version`; null when argv needs the dispatcher. */
+const earlyOut = (argv, { catalog, version, help, stdout }) => {
   if (argv.length === 0 || (argv.length === 1 && ['help', '--help', '-h'].includes(argv[0]))) {
-    writeTo(stdout, topHelp(catalog, version));
+    writeTo(stdout, help.topHelp(catalog, version));
     return 0;
   }
   if (argv.length === 1 && argv[0] === '--version') {
     writeTo(stdout, `${version}\n`);
     return 0;
   }
+  return null;
+};
 
-  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}"`);
+/** `starci help [group] [verb]`; null when argv is not a help invocation. */
+const helpDispatch = (split, { catalog, version, help, stdout, stderr }) => {
+  if (split.group !== 'help') return null;
+  const verbName = split.args.find((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}"`);
+  let text;
+  if (!split.verb) text = help.topHelp(catalog, version);
+  else if (verbName) text = help.verbHelp(catalog, split.verb, verbName);
+  else text = help.groupHelp(catalog, split.verb);
+  writeTo(stdout, text);
+  return 0;
+};
 
-  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));
+/** `starci completion <shell>`; null when argv is not a completion invocation. */
+const completionDispatch = (split, { io, completionFor, completionShells, stdout, stderr }) => {
+  if (split.group !== 'completion') return null;
+  const shell = split.verb;
+  if (split.help && !split.args.length) {
+    writeTo(stdout, `Usage: starci completion <${completionShells.join('|')}>\n`);
     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);
+  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;
+};
+
+/** `starci explain <group> <verb>`; null when argv is not explain or the catalog lacks the command. */
+const explainDispatch = (split, { catalog, help, stdout, stderr }) => {
+  if (split.group !== 'explain' || !(catalog.commands ?? []).includes('explain')) return null;
+  if (split.help && !split.verb && !split.args.length) {
+    writeTo(stdout, 'Usage: starci explain <group> <verb>\n');
     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 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, help.explainHelp(catalog, groupName, verbName));
+  return 0;
+};
 
+/** Resolve group/verb against the catalog (printing help or failing); {command, group} or {code}. */
+const resolveCommand = (split, { catalog, version, help, stdout, stderr }) => {
   const wantsHelp = split.help;
   if (!split.group) {
-    if (wantsHelp) {
-      writeTo(stdout, topHelp(catalog, version));
-      return 0;
-    }
-    return fail(stderr, 'missing command group');
+    if (wantsHelp) { writeTo(stdout, help.topHelp(catalog, version)); return { code: 0 }; }
+    return { code: fail(stderr, 'missing command group') };
   }
   const group = catalog.groups?.[split.group];
-  if (!group) return fail(stderr, `unknown group "${split.group}"`);
+  if (!group) return { code: 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}"`);
+    if (wantsHelp) { writeTo(stdout, help.groupHelp(catalog, split.group)); return { code: 0 }; }
+    return { code: 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 (!command) return { code: fail(stderr, `unknown verb "${split.verb}" for group "${split.group}"`) };
+  if (wantsHelp) { writeTo(stdout, help.verbHelp(catalog, split.group, split.verb)); return { code: 0 }; }
+  return { command, group };
+};
 
-  if (split.group === 'runtime' && split.verb === 'install') {
+/** `starci runtime install|link`; null for any other verb. */
+const runtimeVerb = (split, validated, { io, installRuntime, linkRuntime, home, cwd, stdout, stderr }) => {
+  if (split.group !== 'runtime') return null;
+  if (split.verb === 'install') {
     const install = io.installRuntime ?? installRuntime;
-    return await install({
+    return install({
       cwd,
       ...(home ? { home } : {}),
       force: validated.values.force === true,
@@ -211,10 +168,9 @@ export async function main(argv = process.argv.slice(2), io = {}) {
       noBootstrap: validated.values['no-bootstrap'] === true,
     }, io.runtimeInstallDeps ?? {});
   }
-
-  if (split.group === 'runtime' && split.verb === 'link') {
+  if (split.verb === 'link') {
     const link = io.linkRuntime ?? linkRuntime;
-    return await link({
+    return link({
       cwd,
       ...(home ? { home } : {}),
       root: validated.values.root ?? null,
@@ -224,26 +180,34 @@ export async function main(argv = process.argv.slice(2), io = {}) {
       stderr,
     }, io.runtimeLinkDeps ?? {});
   }
+  return null;
+};
 
-  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);
-    }
+/** A group owned by @starci/hfs runs in-process; null for runtime-owned groups. */
+const hfsDispatch = async (split, group, args, { io, cwd, stdout, stderr }) => {
+  if (group.owner !== '@starci/hfs') return null;
+  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);
   }
+};
 
+/** Spawn the located runtime for the resolved verb; its exit status is the command's. */
+const runRuntime = (split, args, { io, cwd, env, home, stderr }) => {
   const skipped = [];
   const located = (io.locateRuntime ?? locateRuntime)({ cwd, env, skipped, ...(home ? { home } : {}) });
   if (!located) return noRuntime(stderr, split.group, skipped);
+  const notice = foreignRuntimeNotice(located, (io.ownRuntimeRoot ?? ownRuntimeRoot)());
+  if (notice) writeTo(stderr, notice);
   const spawn = io.spawn ?? spawnSync;
   let result;
   try {
@@ -262,4 +226,47 @@ export async function main(argv = process.argv.slice(2), io = {}) {
   }
   if (result?.status == null) return fail(stderr, `the runtime stopped on signal ${result?.signal ?? 'unknown'}`, 1);
   return result.status;
+};
+
+/** 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 = io.catalog ?? catalogModule.CATALOG;
+  const ctx = {
+    ...ioCtx(io), catalog, version: io.version ?? cliVersion(), initialCwd: io.cwd ?? process.cwd(), globals: catalog.global ?? [],
+    help: helpModule, completionFor: completionModule.completionFor, completionShells: completionModule.completionShells,
+    installRuntime: installModule.installRuntime, linkRuntime: linkModule.linkRuntime,
+  };
+  const { splitCommand, validateArgs, withFlagsBeforeDashes } = argsModule;
+
+  const early = earlyOut(argv, ctx);
+  if (early !== null) return early;
+  const split = splitCommand(argv, ctx.globals);
+  for (const dispatch of [helpDispatch, completionDispatch, explainDispatch]) {
+    const out = dispatch(split, ctx);
+    if (out !== null) return out;
+  }
+  const resolved = resolveCommand(split, ctx);
+  if (!resolved.command) return resolved.code;
+  const { command, group } = resolved;
+
+  const validated = validateArgs(split.args, { ...command, group: split.group, verb: split.verb }, ctx.globals);
+  if (!validated.ok) return fail(ctx.stderr, validated.error, validated.code);
+  const cwd = path.resolve(ctx.initialCwd, validated.global.cwd ?? '.');
+  const args = handlerArgs(validated, command, withFlagsBeforeDashes);
+
+  const runtimeOut = await runtimeVerb(split, validated, { ...ctx, cwd });
+  if (runtimeOut !== null) return runtimeOut;
+  const hfsOut = await hfsDispatch(split, group, args, { ...ctx, cwd });
+  if (hfsOut !== null) return hfsOut;
+  return runRuntime(split, args, { ...ctx, cwd });
 }

package/src/runtime-install.generated.mjs

@@ -0,0 +1,2 @@
+// GENERATED by scripts/cli/gen-catalog.mjs — do not edit
+export const RUNTIME_VERSION = "1.0.0-alpha.7";

package/src/runtime-install.mjs

@@ -6,7 +6,8 @@ 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';
+import { RUNTIME_VERSION } from './runtime-install.generated.mjs';
+export { RUNTIME_VERSION };
 
 const writeTo = (target, text) => {
   if (typeof target === 'function') target(text);
@@ -19,8 +20,8 @@ const npmEntryCandidates = ({ execPath = process.execPath, env = process.env } =
   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'));
+  candidates.push(path.join(nodeDirectory, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(path.dirname(nodeDirectory), 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'));
   return [...new Set(candidates)];
 };
 
@@ -105,6 +106,7 @@ export function installRuntime({ cwd = process.cwd(), home = os.homedir(), force
   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);
+  // The download cache supplies the installer; runtime commands must read the installed host's config and bindings.
+  writeRuntimeShim({ root: path.resolve(cwd, '.claude'), home, cli: fileURLToPath(new URL('../bin/starci.mjs', import.meta.url)) }, deps);
   return 0;
 }

package/src/runtime-locate.mjs

@@ -51,4 +51,17 @@ export function locateRuntime({ cwd = process.cwd(), env = process.env, home = o
   return null;
 }
 
+/** The runtime root of the checkout this CLI file lives in, or null when that checkout is not a runtime root (a published install). */
+export const ownRuntimeRoot = ({ exists = existsSync, embeddedRoot = embeddedRuntimeRoot } = {}) => usableRoot(embeddedRoot, exists);
+
+/**
+ * The one stderr line naming a located runtime that is not the checkout the CLI runs from, or null when they are the same
+ * or the CLI lives outside a runtime. The record and STARCI_RUNTIME outrank the checkout, so the mismatch is said, never silent.
+ */
+export function foreignRuntimeNotice(located, own) {
+  if (!located || !own) return null;
+  const same = process.platform === 'win32' ? located.root.toLowerCase() === own.toLowerCase() : located.root === own;
+  return same ? null : `starci: running the runtime at ${located.root} (${located.source}), not this checkout's ${own}; set STARCI_RUNTIME=${own} to use the checkout\n`;
+}
+
 export const runtimeEntryOf = runtimeEntry;

package/src/shim.mjs

@@ -10,6 +10,12 @@ const wrapperName = (program, platform) => platform === 'win32' ? `${program}.cm
 const wrapperText = ({ program, platform, node, cli }) => platform === 'win32'
   ? `@echo off\r\n"${node}" "${cli}" guard raw ${program} -- %*\r\n`
   : `#!/bin/sh\nexec "${node}" "${cli}" guard raw ${program} -- "$@"\n`;
+// The extensionless launcher bash runs (scripts/lib/guard-command.mjs spells the hook command that names it); on Windows
+// its paths use forward slashes, which bash and node both accept.
+const launcherText = ({ platform, node, cli }) => {
+  const spelled = (file) => platform === 'win32' ? file.replaceAll('\\', '/') : file;
+  return `#!/bin/sh\nexec "${spelled(node)}" "${spelled(cli)}" "$@"\n`;
+};
 
 /** Write the per-user runtime record, StarCi launcher and guarded PATH tool wrappers for that runtime. */
 export function writeRuntimeShim({ root, home = os.homedir(), cli: launcher = null } = {}, deps = {}) {
@@ -29,14 +35,16 @@ export function writeRuntimeShim({ root, home = os.homedir(), cli: launcher = nu
   if (platform === 'win32') {
     const shim = path.join(shimDir, 'starci.cmd');
     write(shim, `@echo off\r\n"${node}" "${cli}" %*\r\n`);
+    const posixShim = path.join(shimDir, 'starci');
+    write(posixShim, launcherText({ platform, node, cli }));
     for (const program of TOOL_WRAPPERS) {
       write(path.join(shimDir, wrapperName(program, platform)), wrapperText({ program, platform, node, cli }));
     }
-    return { root: runtimeRoot, runtimeJson, shim };
+    return { root: runtimeRoot, runtimeJson, shim, posixShim };
   }
 
   const shim = path.join(shimDir, 'starci');
-  write(shim, `#!/bin/sh\nexec "${node}" "${cli}" "$@"\n`);
+  write(shim, launcherText({ platform, node, cli }));
   chmod(shim, 0o755);
   for (const program of TOOL_WRAPPERS) {
     const wrapper = path.join(shimDir, wrapperName(program, platform));

package/src/validate-args.mjs

@@ -31,6 +31,84 @@ const typedValue = (flag, raw) => {
   return raw;
 };
 
+/** One `--name[=value]` token: type-check it into values/global, or pass it through to localArgs. */
+const applyOption = (argv, index, token, { known, values, global, localArgs }) => {
+  const name = optionName(token);
+  const flag = known.get(name);
+  if (!flag) throw new Error(`unknown option --${name}`);
+  const { value: raw, consumed } = optionValue(argv, index, flag, known);
+  const value = typedValue(flag, raw);
+  if (flag.type === 'list') {
+    values[name] = [...(values[name] ?? []), value];
+  } 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]);
+  }
+  return consumed;
+};
+
+/** 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}`);
+  }
+};
+
+/** 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];
+};
+
+/** 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(', ')}`);
+  }
+};
+
+/** 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));
+  }
+};
+
+/** 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');
+  }
+};
+
+/** 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;
+};
+
 /**
  * Validate the arguments after a catalog group and verb.
  *
@@ -64,24 +142,7 @@ export function validateArgs(argv, verb, globalFlags = []) {
         continue;
       }
       if (token.startsWith('--')) {
-        const name = optionName(token);
-        const flag = known.get(name);
-        if (!flag) throw new Error(`unknown option --${name}`);
-        const { value: raw, consumed } = optionValue(argv, index, flag, known);
-        const value = typedValue(flag, raw);
-        index += consumed;
-        if (flag.type === 'list') {
-          values[name] = [...(values[name] ?? []), value];
-        } 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]);
-        }
+        index += applyOption(argv, index, token, { known, values, global, localArgs });
         continue;
       }
       if (token.startsWith('-')) throw new Error(`unknown option ${token}`);
@@ -89,41 +150,10 @@ export function validateArgs(argv, verb, globalFlags = []) {
       localArgs.push(token);
     }
 
-    for (const flag of locals.values()) {
-      if (flag.required && !Object.hasOwn(values, flag.name)) throw new Error(`missing required option --${flag.name}`);
-    }
-
-    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 (let index = 0; index < positionalSchema.length; index += 1) {
-      const schema = positionalSchema[index];
-      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}`);
-      const candidates = Array.isArray(supplied) ? supplied : supplied === undefined ? [] : [supplied];
-      for (const candidate of candidates) {
-        if (schema.enum && !schema.enum.includes(candidate)) {
-          throw new Error(`${schema.name} expects one of: ${schema.enum.join(', ')}`);
-        }
-      }
-    }
-
-    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');
-    }
-    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 { ok: true, values, args, global, localArgs, positionals };
+    requiredCheck(locals, values);
+    checkPositionals(verb, positionals, passthrough);
+    checkGlobals(verb, global);
+    return { ok: true, values, args: defaultArgs(locals, values), global, localArgs, positionals };
   } catch (error) {
     return { ok: false, code: 2, error: String(error?.message ?? error) };
   }