@scp-dev/cli 0.0.0-stage → 0.1.2

package/dist/chunk-DA3EB2YF.js

@@ -0,0 +1,359 @@
+// src/term.ts
+import { spawnSync } from "child_process";
+import { CLI_NAME } from "@scp-dev/core";
+var FAILED = 125;
+var SELF = [process.execPath, ...process.versions.bun ? ["--no-env-file", "--config=/dev/null"] : [], process.argv[1]];
+function capture(argv, env) {
+  const result = spawnSync(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], ...env ? { env } : {} });
+  return result.status === 0 ? result.stdout : void 0;
+}
+function note(message) {
+  process.stderr.write(`${message.startsWith(`${CLI_NAME} `) ? "" : `${CLI_NAME}: `}${message}
+`);
+}
+async function exitFlushed(code, waitMs = 1e4) {
+  const ended = (stream) => new Promise((resolve2) => {
+    try {
+      stream.end(() => resolve2());
+    } catch {
+      resolve2();
+    }
+  });
+  let timer;
+  await Promise.race([Promise.all([ended(process.stdout), ended(process.stderr)]), new Promise((resolve2) => timer = setTimeout(resolve2, waitMs))]);
+  clearTimeout(timer);
+  process.exit(code);
+}
+function printTable(rows) {
+  const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+  for (const row of rows)
+    console.log(
+      row.map((cell, column) => cell.padEnd(widths[column])).join("  ").trimEnd()
+    );
+}
+var DURATION_PART = /(\d+(?:\.\d+)?)(ms|s|m|h|d)/g;
+var DURATION_UNITS = { ms: 1e-3, s: 1, m: 60, h: 3600, d: 86400 };
+function parseSeconds(text, flag) {
+  const trimmed = text.trim();
+  let seconds;
+  if (/^\d+(?:\.\d+)?$/.test(trimmed)) seconds = Number(trimmed);
+  else {
+    seconds = 0;
+    let consumed = "";
+    for (const match of trimmed.matchAll(DURATION_PART)) {
+      seconds += Number(match[1]) * DURATION_UNITS[match[2]];
+      consumed += match[0];
+    }
+    if (consumed !== trimmed || consumed === "") {
+      throw new Error(`${flag} ${JSON.stringify(text)} is not a duration like 90s, 30m or 1h30m`);
+    }
+  }
+  if (!(seconds > 0)) throw new Error(`${flag} must be more than zero`);
+  return Math.max(1, Math.ceil(seconds));
+}
+
+// src/identity.ts
+import { existsSync, realpathSync } from "fs";
+import { tmpdir } from "os";
+import { basename, dirname, isAbsolute, join, resolve } from "path";
+import { shortHostname } from "@scp-dev/broker";
+import { LIMITS, validHandle, validHarness } from "@scp-dev/core";
+var SHORT = { "claude-code": "claude" };
+var SHELLS = /* @__PURE__ */ new Set(["sh", "bash", "zsh", "dash", "fish"]);
+var LABEL_KEY = /^[a-z0-9][a-z0-9._-]{0,31}$/;
+function detectHarness(env) {
+  if (env.GROK_SESSION_ID || env.GROK_HOOK_EVENT) return "grok";
+  if (env.MUSE_SESSION_ID) return "muse";
+  if (env.OPENCODE === "1") return "opencode";
+  if (env.ANTIGRAVITY_AGENT === "1" || env.ANTIGRAVITY_CONVERSATION_ID) return "agy";
+  if (env.CLAUDECODE === "1") return "claude-code";
+  if (env.CODEX_THREAD_ID) return "codex";
+  return void 0;
+}
+function normalizeHarness(raw, fallback) {
+  const name = (raw ?? "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+/, "").slice(0, 32).replace(/-+$/, "");
+  if (name === "claude") return "claude-code";
+  return validHarness(name) ? name : fallback;
+}
+function hookHarness(argument, env) {
+  if (!argument) return detectHarness(env) ?? "hook";
+  const named = normalizeHarness(argument, "hook");
+  return named === "claude-code" && (env.GROK_SESSION_ID || env.GROK_HOOK_EVENT) ? "grok" : named;
+}
+function resolveHarness(explicit, env, fallback) {
+  const named = explicit ?? env.SCP_HARNESS;
+  return named ? normalizeHarness(named, fallback) : detectHarness(env) ?? normalizeHarness(fallback, "mcp");
+}
+function gitToplevel(cwd) {
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    if (dirname(dir) === dir) return void 0;
+  }
+}
+function toHandle(raw) {
+  let handle = raw.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[^a-z0-9]+/, "").slice(0, 63).replace(/[-.]+$/, "");
+  if (!handle) handle = "agent";
+  if (!validHandle(handle)) handle = `${handle.slice(0, 56)}-agent`;
+  return handle;
+}
+function deriveHandle(harness, cwd) {
+  const top = gitToplevel(cwd) ?? resolve(cwd);
+  return toHandle(`${SHORT[harness] ?? harness}-${basename(top) || "root"}`);
+}
+function parseLabels(value) {
+  const labels = {};
+  for (const pair of (value ?? "").split(",")) {
+    const eq = pair.indexOf("=");
+    const key = pair.slice(0, eq).trim();
+    if (eq > 0 && LABEL_KEY.test(key)) labels[key] = pair.slice(eq + 1).trim();
+  }
+  return labels;
+}
+function labelsFor(env, host = shortHostname()) {
+  const labels = parseLabels(env.SCP_LABELS);
+  labels.machine ??= host;
+  return labels;
+}
+function processKey(harnessPid2, startOf = psStart) {
+  const started = startOf(harnessPid2);
+  return started ? `pid:${harnessPid2}:${started}` : `pid:${harnessPid2}`;
+}
+function sessionKey(env, harnessProcess) {
+  return env.SCP_SESSION ? `env:${env.SCP_SESSION}` : harnessProcess;
+}
+function psStart(pid) {
+  try {
+    const started = (capture(["ps", "-o", "lstart=", "-p", String(pid)], { PATH: process.env.PATH ?? "/usr/bin:/bin", LC_ALL: "C" }) ?? "").trim().replace(/\s+/g, "-");
+    return /^[A-Za-z0-9:-]{1,64}$/.test(started) ? started : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function parsePsCommTable(text) {
+  const table = /* @__PURE__ */ new Map();
+  for (const line of text.split("\n")) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+(\S.*?)\s*$/.exec(line);
+    if (match) table.set(Number(match[1]), { ppid: Number(match[2]), start: match[3].replace(/\s+/g, "-"), args: match[4] });
+  }
+  return table;
+}
+function readPsTable() {
+  try {
+    const table = capture(["ps", "-ww", "-axo", "pid=,ppid=,lstart=,args="], { PATH: process.env.PATH ?? "/usr/bin:/bin", LC_ALL: "C" });
+    return table === void 0 ? void 0 : parsePsCommTable(table);
+  } catch {
+    return void 0;
+  }
+}
+var PASS_THROUGH = /* @__PURE__ */ new Set([
+  ...SHELLS,
+  "ash",
+  "ksh",
+  "env",
+  "timeout",
+  "nohup",
+  "nice",
+  "time",
+  "stdbuf",
+  "xargs",
+  "script",
+  "caffeinate",
+  "flock",
+  "sandbox-exec",
+  "bwrap",
+  "codex-linux-sandbox",
+  "codex-linux-san"
+]);
+var INTERPRETERS = /* @__PURE__ */ new Set(["node", "nodejs", "bun", "deno", "ruby", "perl"]);
+var RUNNERS = /* @__PURE__ */ new Set(["npm", "pnpm", "yarn"]);
+var FETCHERS = /* @__PURE__ */ new Set(["npx", "bunx", "pnpx", "uvx"]);
+var SCRIPT_RUNNERS = /* @__PURE__ */ new Set(["tsx", "ts-node", "vite-node", "esno"]);
+var INLINE = /* @__PURE__ */ new Set(["-c", "-e", "--eval", "-p", "--print", "-"]);
+var VALUED = /* @__PURE__ */ new Set(["-r", "--require", "--import", "--loader", "--experimental-loader", "-I", "-M", "-W", "-X", "-C", "--conditions", "--preload"]);
+var HARNESSES = /* @__PURE__ */ new Set([
+  "claude",
+  "claude-code",
+  "codex",
+  "opencode",
+  "opencode-ai",
+  "grok",
+  "grok-cli",
+  "muse",
+  "agy",
+  "antigravity",
+  "gemini",
+  "gemini-cli"
+]);
+var INSTALLED = /(^|\/)(node_modules|site-packages|dist-packages|\.npm|\.bun|\.cache|\.local|\.cargo|\.volta|\.nvm|\.pyenv|\.rbenv|Cellar|Applications)(\/|$)|^\/(opt|usr|Library|nix)\//;
+function command(args) {
+  return basename(args.split(/\s+/)[0].replace(/^-/, "")).toLowerCase();
+}
+var namesHarness = (words) => words.some((word) => !word.startsWith("-") && word.split("/").some((part) => HARNESSES.has(part.toLowerCase().replace(/\..*$/, ""))));
+var roots;
+function workspaceRoots() {
+  if (roots) return roots;
+  const real = (path) => {
+    try {
+      return realpathSync(path);
+    } catch {
+      return path;
+    }
+  };
+  const found = [process.cwd(), tmpdir(), "/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
+  try {
+    const top = capture(["git", "rev-parse", "--show-toplevel"]);
+    if (top !== void 0) found.push(top.trim());
+  } catch {
+  }
+  roots = [...new Set(found.filter(Boolean).map(real))];
+  return roots;
+}
+function ownScript(operand) {
+  if (operand === void 0 || operand === "-") return true;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(operand) || operand.startsWith("~") || INSTALLED.test(operand)) return false;
+  if (!isAbsolute(operand)) return !operand.split("/").includes("..");
+  let path = operand;
+  try {
+    path = realpathSync(operand);
+  } catch {
+  }
+  if (INSTALLED.test(path)) return false;
+  return workspaceRoots().some((root) => path === root || path.startsWith(`${root}/`));
+}
+function helper(args) {
+  const words = args.split(/\s+/);
+  if (namesHarness(words.slice(1))) return false;
+  const name = command(args);
+  let rest = words.slice(1);
+  if (FETCHERS.has(name)) {
+    while (rest[0]?.startsWith("-")) rest = rest.slice(1);
+    return SCRIPT_RUNNERS.has(rest[0] ?? "") && rest.slice(1).every((word) => word.startsWith("-") || ownScript(word));
+  }
+  if (name === "uv" || RUNNERS.has(name)) {
+    if (rest[0] !== "run") return false;
+    if (name === "uv") {
+      rest = rest.slice(1);
+      while (rest[0]?.startsWith("-")) rest = rest.slice(1);
+      if (rest[0] === void 0) return true;
+      const inner = rest.join(" ");
+      return /^python[0-9.]*$/.test(command(inner)) || INTERPRETERS.has(command(inner)) ? helper(inner) : ownScript(rest[0]);
+    }
+    return true;
+  }
+  if (!INTERPRETERS.has(name) && !/^python[0-9.]*$/.test(name)) return false;
+  if (name === "bun" && rest[0] === "x") return false;
+  if ((name === "bun" || name === "deno") && rest[0] === "run") {
+    rest = rest.slice(1);
+    if (name === "deno") while (rest[0]?.startsWith("-")) rest = rest.slice(1);
+    const target = rest.find((word) => !word.startsWith("-"));
+    if (target !== void 0 && !/[/.]/.test(target)) return false;
+  }
+  for (let i = 0; i < rest.length; i++) {
+    const word = rest[i];
+    if (word === "-m") return false;
+    if (INLINE.has(word)) return true;
+    if (VALUED.has(word)) {
+      if (!ownScript(rest[++i])) return false;
+      continue;
+    }
+    if (!word.startsWith("-")) return ownScript(word);
+  }
+  return true;
+}
+function harnessLineage(pid, table = readPsTable()) {
+  const keys = lineage(pid, table);
+  let first = -1;
+  for (let i = 0, at = pid; i < keys.length; i++, at = table.get(at).ppid) {
+    const args = table.get(at).args;
+    if (PASS_THROUGH.has(command(args))) continue;
+    if (!helper(args)) return keys.slice(0, i + 1);
+    if (first < 0) first = i;
+  }
+  return first < 0 ? [] : keys;
+}
+var INITS = /* @__PURE__ */ new Set(["init", "systemd", "launchd"]);
+function hiddenHarness(pid, table = readPsTable()) {
+  if (!table || harnessLineage(pid, table).length) return false;
+  const seen = /* @__PURE__ */ new Set();
+  let at = pid;
+  while (at > 1 && !seen.has(at)) {
+    seen.add(at);
+    const entry = table.get(at);
+    if (!entry) return false;
+    at = entry.ppid;
+  }
+  const init = table.get(1);
+  return at === 1 && init !== void 0 && !INITS.has(command(init.args));
+}
+function lineage(harnessPid2, table = readPsTable()) {
+  const keys = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (let pid = harnessPid2; pid > 1 && keys.length < LIMITS.lineageMax && !seen.has(pid); ) {
+    const entry = table?.get(pid);
+    if (!entry) break;
+    seen.add(pid);
+    keys.push(/^[A-Za-z0-9:-]{1,64}$/.test(entry.start) ? `pid:${pid}:${entry.start}` : `pid:${pid}`);
+    pid = entry.ppid;
+  }
+  return keys;
+}
+function spawnerKey(pid = process.pid, table = readPsTable()) {
+  const key = lineage(pid, table)[0];
+  return key?.startsWith(`pid:${pid}:`) ? key : void 0;
+}
+function psParent(pid) {
+  const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(capture(["ps", "-o", "ppid=,comm=", "-p", String(pid)], { PATH: process.env.PATH ?? "/usr/bin:/bin" }) ?? "");
+  return match ? { ppid: Number(match[1]), comm: match[2] } : void 0;
+}
+function harnessPid(ppid = process.ppid, parentOf = psParent) {
+  const parent = parentOf(ppid);
+  if (parent && parent.ppid > 1 && SHELLS.has(basename(parent.comm.replace(/^-/, "")))) return parent.ppid;
+  return ppid;
+}
+function hookHarnessPid(env, harness, ppid = process.ppid, parentOf = psParent) {
+  const named = harness === "claude-code" ? env.CLAUDE_PID : harness === "opencode" ? env.OPENCODE_PID : void 0;
+  const pid = Number(named);
+  if (Number.isInteger(pid) && pid > 1) return pid;
+  return harnessPid(ppid, parentOf);
+}
+function relayIdentity(input) {
+  const harness = resolveHarness(input.harness, input.env, input.fallbackHarness);
+  const cwd = isAbsolute(input.cwd) ? input.cwd : resolve(input.cwd);
+  const handle = input.as ?? input.env.SCP_NAME ?? deriveHandle(harness, cwd);
+  const pid = input.harnessPid(harness);
+  const harnessProcess = processKey(pid, input.startOf);
+  const keys = input.lineageOf ? input.lineageOf(pid) : lineage(pid);
+  return {
+    handle,
+    harness,
+    cwd,
+    session: sessionKey(input.env, harnessProcess),
+    process: harnessProcess,
+    labels: labelsFor(input.env),
+    ...input.env.SCP_PARENT ? { parent: input.env.SCP_PARENT } : {},
+    ...keys.length ? { lineage: keys } : {},
+    ...input.env.SCP_GRANT ? { grant: input.env.SCP_GRANT } : {}
+  };
+}
+
+export {
+  FAILED,
+  SELF,
+  note,
+  exitFlushed,
+  printTable,
+  parseSeconds,
+  shortHostname,
+  detectHarness,
+  hookHarness,
+  gitToplevel,
+  labelsFor,
+  readPsTable,
+  harnessLineage,
+  hiddenHarness,
+  lineage,
+  spawnerKey,
+  harnessPid,
+  hookHarnessPid,
+  relayIdentity
+};

package/dist/chunk-KN7WEIE4.js

@@ -0,0 +1,41 @@
+// src/help-spawn.ts
+import { CLI_NAME, LIMITS } from "@scp-dev/core";
+var SPAWN_HELP = `${CLI_NAME} spawn [flags] [--] <harness cmd...>: run a worker agent under you with a relay grant (never printed)
+
+  e.g. ${CLI_NAME} spawn --name rev codex exec "review src/judge.ts, end with your findings"
+       ${CLI_NAME} spawn claude -p "list the open TODOs in packages/cli"
+
+  --name N              its address (default <harness>-<5 random characters>)
+  --title T             its title until it sets its own (default the prompt's first line)
+  --no-push             your stop does not wait on it; its messages and handback still reach you after your tool
+                        calls or with another worker's push
+  --bg | --fg           --bg (the default in an agent's shell or without a terminal on stdout) returns at once;
+                        --fg (the default at a human's terminal) runs it in the foreground, passing on its output
+                        and exit code: scripts that need the exit code pass --fg
+  --handback-bytes N    hand back only the last N bytes of its final output (1 to ${LIMITS.handbackBytes})
+  --peek local          peekable from its start
+  --scope P --rules S --in S --out S --allow S --group G --under EP --ttl S --labels K=V,...
+                        its scope and grant, as for ${CLI_NAME} spawn-env (default scope: parent)
+The command starts after -- or at the first word that is not one of these flags.
+
+It returns at once, printing the worker's name and its runner's pid: do not background it (no &, no
+run_in_background). A failure before the harness starts (bad flags, a refused grant, no such harness) fails the
+spawn itself. Your stop waits for the worker's messages (hooks install --push-wait, default 600 s).
+Handback: when the harness exits you get its exit code and its reply, cleaned and redacted (a claude -p worker:
+all its replies since its prompt, from its transcript; other harnesses: their final output), and each of your
+messages it never applied as steer not applied: <text>. A worker that never joined or exited non-zero also hands
+back its last ${LIMITS.stderrBytes / 1024} KB of stderr.
+Steer: ${CLI_NAME} send <name> <text>; a claude -p or codex exec prompt gets a note naming you and your steer key.
+A codex exec worker that exited before a late steer is resumed with it (codex exec resume, at most twice).
+Harnesses: codex gets -c overrides that hand it the grant (also behind env, timeout, nohup or nice); a ${CLI_NAME}
+command from its workspace-write sandbox needs -c sandbox_workspace_write.network_access=true. codex exec
+gets --skip-git-repo-check outside a git repo, and with its prompt in argv piped stdin only under --fg. Workers
+message with the relay MCP tools (relay_send, relay_inbox, relay_reply). claude -p and grok -p get those tools allowed
+unless you pass a permission flag. muse runs with --contributor-mode off unless you pass on. agy needs the allow rules ${CLI_NAME}
+setup writes.
+
+Full reference: ${CLI_NAME} help --all.`;
+
+export {
+  SPAWN_HELP
+};