@starci/cli 1.0.1 → 1.2.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,8 @@ 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 { retargetNotice, targetOf, treeTargetRefusal } from './runtime-target.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 +64,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 +72,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 +169,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 +181,39 @@ 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, command }) => {
   const skipped = [];
-  const located = (io.locateRuntime ?? locateRuntime)({ cwd, env, skipped, ...(home ? { home } : {}) });
-  if (!located) return noRuntime(stderr, split.group, skipped);
+  const record = (io.locateRuntime ?? locateRuntime)({ cwd, env, skipped, ...(home ? { home } : {}) });
+  if (!record) return noRuntime(stderr, split.group, skipped);
+  const own = (io.ownRuntimeRoot ?? ownRuntimeRoot)();
+  const { located, retargeted } = targetOf({ command, args, located: record, own });
+  if (retargeted) writeTo(stderr, retargetNotice(retargeted, own));
+  const refused = treeTargetRefusal({ command, args, located, own });
+  if (refused) return fail(stderr, refused.message, 2);
+  const notice = foreignRuntimeNotice(located, own);
+  if (notice) writeTo(stderr, notice);
   const spawn = io.spawn ?? spawnSync;
   let result;
   try {
@@ -262,4 +232,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, command });
 }

package/src/runtime-install.generated.mjs

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

package/src/runtime-install.mjs

@@ -20,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)];
 };
 

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/runtime-target.mjs

@@ -0,0 +1,41 @@
+import path from 'node:path';
+
+/** The code a verb that writes the runtime tree is refused with when it would write a tree other than the CLI's own. */
+export const RUNTIME_TREE_FOREIGN = 'RUNTIME_TREE_TARGET_FOREIGN';
+
+const sameRoot = (a, b) => (process.platform === 'win32' ? path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase() : path.resolve(a) === path.resolve(b));
+
+/** Whether this invocation of `command` writes the runtime tree: its `writesRuntimeTree` is true (always), a flag name that makes it write, or `!flag` (writes unless that flag is given). */
+function writesTree(command, args) {
+  const mark = command?.writesRuntimeTree;
+  if (mark === true) return true;
+  if (typeof mark !== 'string') return false;
+  return mark.startsWith('!') ? !args.includes(`--${mark.slice(1)}`) : args.includes(`--${mark}`);
+}
+
+/**
+ * The refusal of a verb that writes the runtime tree while the located runtime is not the tree that owns the running CLI and nothing chose it
+ * explicitly (STARCI_RUNTIME, or the verb's own --root). The per-user record outranks the checkout for reading, so a clone's bin would otherwise
+ * write the live tree. Null when the verb does not write the tree, the CLI is not in a runtime, or the target is explicit or the CLI's own. Pure.
+ */
+export function treeTargetRefusal({ command, args, located, own }) {
+  if (!located || !own || !writesTree(command, args)) return null;
+  if (located.source === 'STARCI_RUNTIME' || args.includes('--root') || sameRoot(located.root, own)) return null;
+  return { code: RUNTIME_TREE_FOREIGN, message: `${RUNTIME_TREE_FOREIGN}: this verb writes the runtime tree, and the located runtime ${located.root} (${located.source}) is not the tree ${own} that owns this CLI; set STARCI_RUNTIME=${own} (or pass --root) to say which tree to write` };
+}
+
+/** The explicit runtime choices that outrank a verb's side: STARCI_RUNTIME, or the verb's own --root. */
+const chosenExplicitly = (located, args) => located.source === 'STARCI_RUNTIME' || args.includes('--root');
+
+/**
+ * The runtime a verb runs: a tree-side verb (one whose result is about the runtime tree that owns the running bin: a check, a test selection, a receipt, a catalog
+ * regeneration) runs THIS checkout unless a tree was chosen explicitly, so its verdict is about the tree it ran in; a host-side verb runs the located runtime (the
+ * per-user record included). {located, retargeted}: `retargeted` carries the runtime the record pointed at when this checkout replaced it. Pure.
+ */
+export function targetOf({ command, args, located, own }) {
+  if (!located || !own || command?.runtimeSide !== 'tree' || chosenExplicitly(located, args) || sameRoot(located.root, own)) return { located, retargeted: null };
+  return { located: { root: own, source: 'own-checkout' }, retargeted: located };
+}
+
+/** The one stderr line saying a tree-side verb ran this checkout although the located runtime is another tree. */
+export const retargetNotice = (retargeted, own) => `starci: this verb is about the runtime tree that owns this CLI, so it ran ${own}, not ${retargeted.root} (${retargeted.source}); set STARCI_RUNTIME to judge another tree\n`;

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));