@starci/cli 1.0.0

package/src/runtime-locate.mjs

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const runtimeEntry = (root) => path.join(root, 'scripts', 'cli', 'main.mjs');
+const embeddedRuntimeRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+const usableRoot = (candidate, exists) => {
+  if (!candidate || typeof candidate !== 'string') return null;
+  const root = path.resolve(candidate);
+  return exists(runtimeEntry(root)) ? root : null;
+};
+
+/**
+ * Locate the runtime in the binding order: env, per-user record, upward .claude, embedded checkout.
+ * A source that is set but unusable (a stale record, a bad env root) never throws: it falls through to the next source
+ * and is described in `skipped` (when given) so the caller can say why the lookup came up empty.
+ */
+export function locateRuntime({ cwd = process.cwd(), env = process.env, home = os.homedir(), exists = existsSync, read = readFileSync,
+  embeddedRoot = embeddedRuntimeRoot, skipped = [] } = {}) {
+  const fromEnv = usableRoot(env.STARCI_RUNTIME, exists);
+  if (fromEnv) return { root: fromEnv, source: 'STARCI_RUNTIME' };
+  if (env.STARCI_RUNTIME) skipped.push(`STARCI_RUNTIME "${env.STARCI_RUNTIME}" has no scripts/cli/main.mjs`);
+
+  const record = path.join(home, '.starci', 'runtime.json');
+  if (exists(record)) {
+    let recorded;
+    let readable = true;
+    try {
+      recorded = JSON.parse(read(record, 'utf8'))?.root;
+    } catch {
+      readable = false;
+      skipped.push(`${record} is not valid JSON`);
+    }
+    const root = usableRoot(recorded, exists);
+    if (root) return { root, source: record };
+    if (readable) skipped.push(`${record} points at ${JSON.stringify(recorded ?? null)}, which has no scripts/cli/main.mjs (stale record)`);
+  }
+
+  let directory = path.resolve(cwd);
+  for (;;) {
+    const root = usableRoot(path.join(directory, '.claude'), exists);
+    if (root) return { root, source: 'upward' };
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  const embedded = usableRoot(embeddedRoot, exists);
+  if (embedded) return { root: embedded, source: 'embedded' };
+  return null;
+}
+
+export const runtimeEntryOf = runtimeEntry;

package/src/shim.mjs

@@ -0,0 +1,82 @@
+import { mkdirSync, writeFileSync, chmodSync, unlinkSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+/** Programs whose PATH entries enforce the shared command policy before reaching the host tool. */
+const TOOL_WRAPPERS = Object.freeze(['git', 'npm', 'npx', 'node', 'docker', 'supabase', 'gh', 'schtasks']);
+
+const wrapperName = (program, platform) => platform === 'win32' ? `${program}.cmd` : program;
+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`;
+
+/** 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 = {}) {
+  const mkdir = deps.mkdir ?? ((directory) => mkdirSync(directory, { recursive: true }));
+  const write = deps.write ?? writeFileSync;
+  const chmod = deps.chmod ?? chmodSync;
+  const platform = deps.platform ?? process.platform;
+  const node = deps.node ?? process.execPath;
+  const runtimeRoot = path.resolve(root);
+  const starciHome = path.join(home, '.starci');
+  const shimDir = path.join(starciHome, 'bin');
+  const runtimeJson = path.join(starciHome, 'runtime.json');
+  const cli = launcher == null ? path.join(runtimeRoot, 'packages', 'cli', 'bin', 'starci.mjs') : path.resolve(launcher);
+
+  mkdir(shimDir);
+  write(runtimeJson, `${JSON.stringify({ root: runtimeRoot }, null, 2)}\n`);
+  if (platform === 'win32') {
+    const shim = path.join(shimDir, 'starci.cmd');
+    write(shim, `@echo off\r\n"${node}" "${cli}" %*\r\n`);
+    for (const program of TOOL_WRAPPERS) {
+      write(path.join(shimDir, wrapperName(program, platform)), wrapperText({ program, platform, node, cli }));
+    }
+    return { root: runtimeRoot, runtimeJson, shim };
+  }
+
+  const shim = path.join(shimDir, 'starci');
+  write(shim, `#!/bin/sh\nexec "${node}" "${cli}" "$@"\n`);
+  chmod(shim, 0o755);
+  for (const program of TOOL_WRAPPERS) {
+    const wrapper = path.join(shimDir, wrapperName(program, platform));
+    write(wrapper, wrapperText({ program, platform, node, cli }));
+    chmod(wrapper, 0o755);
+  }
+  return { root: runtimeRoot, runtimeJson, shim };
+}
+
+/** Remove only the guarded tool wrappers; a missing wrapper is already unlinked. */
+export function removeToolWrappers({ home = os.homedir() } = {}, deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const unlink = deps.unlink ?? unlinkSync;
+  const shimDir = path.join(home, '.starci', 'bin');
+  const removed = [];
+  for (const program of TOOL_WRAPPERS) {
+    const wrapper = path.join(shimDir, wrapperName(program, platform));
+    try {
+      unlink(wrapper);
+      removed.push(wrapper);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+  return removed;
+}
+
+/**
+ * The environment a runtime process runs in: the same as the caller's, without the guarded wrapper directory on PATH.
+ * An agent's own `git` or `npm` meets the wrappers; the runtime verbs that agent started act with the real tools, so a
+ * verb can do what its role allows. Nothing the agent can set changes this: the launcher always strips it.
+ */
+export function runtimeEnv(env = process.env, { home = os.homedir(), platform = process.platform } = {}) {
+  const key = Object.keys(env).find((name) => name.toLowerCase() === 'path');
+  if (!key) return env;
+  const same = (entry) => {
+    const left = path.resolve(String(entry).replace(/^"(.*)"$/, '$1'));
+    const right = path.resolve(home, '.starci', 'bin');
+    return platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+  };
+  const separator = platform === 'win32' ? ';' : ':';
+  return { ...env, [key]: String(env[key]).split(separator).filter((entry) => entry && !same(entry)).join(separator) };
+}

package/src/validate-args.mjs

@@ -0,0 +1,170 @@
+const optionName = (token) => token.slice(2).split('=', 1)[0];
+
+// A value may start with a single dash; one that is `--` or names a known flag is a missing value (use --flag=value).
+const looksLikeFlag = (token, known) => token === '--' || (token.startsWith('--') && known.has(optionName(token)));
+
+const optionValue = (argv, index, flag, known) => {
+  const token = argv[index];
+  const equals = token.indexOf('=');
+  if (equals >= 0) return { value: token.slice(equals + 1), consumed: 0 };
+  if (flag.type === 'boolean') return { value: true, consumed: 0 };
+  if (index + 1 >= argv.length || looksLikeFlag(argv[index + 1], known)) {
+    throw new Error(`--${flag.name} needs a value (use --${flag.name}=<value> for a value that looks like an option)`);
+  }
+  return { value: argv[index + 1], consumed: 1 };
+};
+
+const typedValue = (flag, raw) => {
+  if (flag.type === 'boolean') {
+    if (raw === true || raw === 'true') return true;
+    if (raw === 'false') return false;
+    throw new Error(`--${flag.name} expects true or false`);
+  }
+  if (flag.type === 'number') {
+    const value = String(raw).trim() === '' ? Number.NaN : Number(raw);
+    if (!Number.isFinite(value)) throw new Error(`--${flag.name} expects a number`);
+    return value;
+  }
+  if (flag.type === 'enum' && !flag.enum?.includes(raw)) {
+    throw new Error(`--${flag.name} expects one of: ${(flag.enum ?? []).join(', ')}`);
+  }
+  return raw;
+};
+
+/**
+ * Validate the arguments after a catalog group and verb.
+ *
+ * Global options are returned separately so dispatchers can implement them once;
+ * localArgs contains only the verb's positionals and local options, in input order.
+ * Everything after a bare `--` is passed through unchanged: it is never parsed as an option and
+ * only fills positional slots the verb declares.
+ */
+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]);
+  const values = {};
+  const global = {};
+  const localArgs = [];
+  const positionals = [];
+  const passthrough = [];
+  let positionalOnly = false;
+
+  try {
+    for (let index = 0; index < argv.length; index += 1) {
+      const token = argv[index];
+      if (positionalOnly) {
+        passthrough.push(token);
+        localArgs.push(token);
+        continue;
+      }
+      if (token === '--') {
+        positionalOnly = true;
+        localArgs.push(token);
+        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]);
+        }
+        continue;
+      }
+      if (token.startsWith('-')) throw new Error(`unknown option ${token}`);
+      positionals.push(token);
+      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 };
+  } catch (error) {
+    return { ok: false, code: 2, error: String(error?.message ?? error) };
+  }
+}
+
+/** Insert dispatcher-owned flags before a pass-through `--`, where handlers still parse them as options. */
+export function withFlagsBeforeDashes(args, extra) {
+  const at = args.indexOf('--');
+  return at < 0 ? [...args, ...extra] : [...args.slice(0, at), ...extra, ...args.slice(at)];
+}
+
+const isHelpToken = (token) => token === '--help' || token === '-h' || token === '--help=true';
+
+/**
+ * Find the group and verb while allowing catalog global options before them.
+ * `help` is true when --help or -h appears before any bare `--`; everything after `--` is pass-through.
+ */
+export function splitCommand(argv, globalFlags = []) {
+  const globals = new Map(globalFlags.map((flag) => [flag.name, flag]));
+  const command = [];
+  const args = [];
+  let help = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--') {
+      args.push(...argv.slice(index));
+      break;
+    }
+    if (isHelpToken(token)) {
+      help = true;
+      continue;
+    }
+    if (token.startsWith('--')) {
+      const flag = globals.get(optionName(token));
+      args.push(token);
+      const next = argv[index + 1];
+      if (flag && flag.type !== 'boolean' && !token.includes('=') && next !== undefined && !looksLikeFlag(next, globals)) args.push(argv[++index]);
+    } else if (token.startsWith('-') && token.length > 1) {
+      args.push(token);
+    } else if (command.length < 2) command.push(token);
+    else args.push(token);
+  }
+  return { group: command[0] ?? null, verb: command[1] ?? null, args, help };
+}