@starci/cli 1.1.0 → 1.2.0

package/src/main.mjs

@@ -3,6 +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 { retargetNotice, targetOf, treeTargetRefusal } from './runtime-target.mjs';
 import { foreignRuntimeNotice, locateRuntime, ownRuntimeRoot, runtimeEntryOf } from './runtime-locate.mjs';
 import { runtimeEnv } from './shim.mjs';
 
@@ -202,11 +203,16 @@ const hfsDispatch = async (split, group, args, { io, cwd, stdout, stderr }) => {
 };
 
 /** 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 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 notice = foreignRuntimeNotice(located, (io.ownRuntimeRoot ?? ownRuntimeRoot)());
+  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;
@@ -268,5 +274,5 @@ export async function main(argv = process.argv.slice(2), io = {}) {
   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 });
+  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.7";
+export const RUNTIME_VERSION = "1.0.0-alpha.9";

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/validate-args.mjs

@@ -31,15 +31,24 @@ const typedValue = (flag, raw) => {
   return raw;
 };
 
+/** The values a list flag takes after its first one when the verb has no positional slot: every following token that is no option (`--knowledge a b c`), as the contracts write it. */
+const listTail = (argv, index, flag, verb) => {
+  if (flag.type !== 'list' || (verb.positional ?? []).length > 0) return [];
+  const tail = [];
+  while (index + 2 + tail.length < argv.length && !argv[index + 2 + tail.length].startsWith('-')) tail.push(argv[index + 2 + tail.length]);
+  return tail;
+};
+
 /** 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 applyOption = (argv, index, token, { known, internal, values, global, localArgs, verb }) => {
   const name = optionName(token);
   const flag = known.get(name);
-  if (!flag) throw new Error(`unknown option --${name}`);
+  if (!flag) throw new Error(internal.has(name) ? `unknown option --${name}: it is a call of the runtime itself, not a CLI option; ${internal.get(name)}` : `unknown option --${name}`);
   const { value: raw, consumed } = optionValue(argv, index, flag, known);
   const value = typedValue(flag, raw);
+  const tail = consumed ? listTail(argv, index, flag, verb) : [];
   if (flag.type === 'list') {
-    values[name] = [...(values[name] ?? []), value];
+    values[name] = [...(values[name] ?? []), value, ...tail];
   } else if (Object.hasOwn(values, name)) {
     throw new Error(`--${name} may be given only once`);
   } else {
@@ -49,8 +58,10 @@ const applyOption = (argv, index, token, { known, values, global, localArgs }) =
   else {
     localArgs.push(token);
     if (consumed) localArgs.push(argv[index + consumed]);
+    // each further value of a list flag reaches the handler as a repeated option, the form every list-flag handler parses
+    for (const extra of tail) localArgs.push(token, extra);
   }
-  return consumed;
+  return consumed + tail.length;
 };
 
 /** Every required local option must have been given. */
@@ -121,6 +132,8 @@ export function validateArgs(argv, verb, globalFlags = []) {
   const globals = new Map(globalFlags.map((flag) => [flag.name, { ...flag, global: true }]));
   const locals = new Map((verb.flags ?? []).map((flag) => [flag.name, flag]));
   const known = new Map([...globals, ...locals]);
+  // Flags the runtime's own scripts take and the CLI refuses, each with the pointer a person is given instead.
+  const internal = new Map((verb.internalFlags ?? []).map((entry) => [entry.name, entry.pointer]));
   const values = {};
   const global = {};
   const localArgs = [];
@@ -142,7 +155,7 @@ export function validateArgs(argv, verb, globalFlags = []) {
         continue;
       }
       if (token.startsWith('--')) {
-        index += applyOption(argv, index, token, { known, values, global, localArgs });
+        index += applyOption(argv, index, token, { known, internal, values, global, localArgs, verb });
         continue;
       }
       if (token.startsWith('-')) throw new Error(`unknown option ${token}`);