@nodii/dev 0.6.28 → 0.6.29

package/dist/starting.js

@@ -0,0 +1,406 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdir, readFile, rmdir, writeFile } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { CliError, configPath, devRequest, encode, query, readConfig, requireFlag } from "./core.js";
+import { nextCommand } from "./lanes.js";
+
+const execFile = promisify(execFileCallback);
+const via = { via: "nodii-dev" };
+const values = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
+
+function pairs(value, flag) {
+  const out = new Map();
+  for (const raw of values(value)) {
+    const at = String(raw).indexOf("=");
+    if (at < 1 || at === String(raw).length - 1)
+      throw new CliError("USAGE", `--${flag} must be NAME=VALUE and may be repeated.`, 2);
+    const key = String(raw).slice(0, at).trim();
+    const item = String(raw).slice(at + 1).trim();
+    if (out.has(key)) throw new CliError("USAGE", `--${flag} repeats ${key}.`, 2);
+    out.set(key, item);
+  }
+  return out;
+}
+
+function groupedPairs(value, flag) {
+  const out = new Map();
+  for (const raw of values(value)) {
+    const at = String(raw).indexOf("=");
+    if (at < 1 || at === String(raw).length - 1)
+      throw new CliError("USAGE", `--${flag} must be NAME=VALUE and may be repeated.`, 2);
+    const key = String(raw).slice(0, at).trim();
+    const item = String(raw).slice(at + 1).trim();
+    out.set(key, [...(out.get(key) ?? []), item]);
+  }
+  return out;
+}
+
+export function launchRepositories(key, flags) {
+  const sources = pairs(flags.repo, "repo");
+  const branches = pairs(flags.branch, "branch");
+  const bases = pairs(flags.base, "base");
+  const worktrees = pairs(flags.worktree, "worktree");
+  const owned = groupedPairs(flags["owned-path"], "owned-path");
+  if (!sources.size) throw new CliError("USAGE", "lane launch needs at least one --repo NAME=/absolute/source.", 2);
+  for (const collection of [branches, bases, worktrees, owned])
+    for (const name of collection.keys())
+      if (!sources.has(name)) throw new CliError("USAGE", `Repository options name unknown repo ${name}.`, 2);
+  return [...sources].map(([name, source]) => {
+    if (!isAbsolute(source)) throw new CliError("USAGE", `--repo ${name} needs an absolute source path.`, 2);
+    const branch = branches.get(name);
+    if (!branch) throw new CliError("USAGE", `Missing --branch ${name}=BRANCH.`, 2);
+    const worktree = worktrees.get(name) ?? join(source, ".claude", "worktrees", key);
+    if (!isAbsolute(worktree)) throw new CliError("USAGE", `--worktree ${name} needs an absolute path.`, 2);
+    return {
+      repo: name,
+      source: resolve(source),
+      branch,
+      worktree: resolve(worktree),
+      baseRef: bases.get(name) ?? "origin/main",
+      ownedPaths: owned.get(name) ?? [],
+    };
+  });
+}
+
+export function figmaScopes(value) {
+  return values(value).map((raw) => {
+    const scope = String(raw).trim();
+    const at = scope.indexOf("=");
+    const fileKey = (at < 0 ? scope : scope.slice(0, at)).trim();
+    const componentSets = at < 0 ? [] : scope.slice(at + 1).split(",").map((item) => item.trim()).filter(Boolean);
+    if (!fileKey || (at >= 0 && componentSets.length === 0))
+      throw new CliError("USAGE", "--figma must be FILE_KEY or FILE_KEY=COMPONENT_SET[,COMPONENT_SET] and may be repeated.", 2);
+    return {
+      fileKey,
+      componentSets,
+    };
+  });
+}
+
+const stateFile = (machine) => join(dirname(configPath()), `coordinator-${encodeURIComponent(machine)}.json`);
+export function laneConfigPath(key, current = configPath()) {
+  const configDir = dirname(current);
+  const agentsDir = basename(configDir) === "agents" ? configDir : join(configDir, "agents");
+  const lane = String(key).toLowerCase().replaceAll(/[^a-z0-9_-]/g, "-");
+  return join(agentsDir, `lane-${lane}.json`);
+}
+async function saveJson(file, value) {
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+async function loadJson(file) {
+  try { return JSON.parse(await readFile(file, "utf8")); }
+  catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function coordinatorRuntimePid(run = execFile) {
+  let pid = process.ppid;
+  for (let depth = 0; depth < 8 && Number.isInteger(pid) && pid > 1; depth += 1) {
+    const { stdout } = await run("ps", ["-p", String(pid), "-o", "ppid=", "-o", "comm="], { encoding: "utf8" });
+    const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(stdout);
+    if (!match) break;
+    if (/(?:^|\/)(?:codex|claude)(?:$|[-_.])/i.test(match[2])) return pid;
+    pid = Number(match[1]);
+  }
+  throw new CliError("COORDINATOR_PROCESS_NOT_FOUND", "Could not identify the parent Claude or Codex coordinator process.", 1);
+}
+
+async function watchCoordinator(runId) {
+  const { recordWatchedRun } = await import("./watchdog.js");
+  return recordWatchedRun({
+    runId,
+    pid: await coordinatorRuntimePid(),
+    configPath: configPath(),
+    worktree: process.cwd(),
+  });
+}
+
+export async function coordinatorCommand(action, flags, { request = devRequest, config = readConfig, save = saveJson, watch = watchCoordinator } = {}) {
+  if (action !== "start") throw new CliError("USAGE", `Unknown coordinator action: ${action}`, 2);
+  const machine = requireFlag(flags, "machine");
+  const payload = await request("POST", "/api/v1/coordinator-runs/start", {
+    machine,
+    expectedHeartbeatSeconds: flags["heartbeat-seconds"] ? Number(flags["heartbeat-seconds"]) : 60,
+    ...via,
+  });
+  const c = await config();
+  try {
+    await watch(payload.data.run.id);
+  } catch (error) {
+    try {
+      await request("POST", `/api/v1/runs/${encode(payload.data.run.id)}/process-exit`, {
+        reason: "coordinator watcher registration failed",
+        deathFingerprint: "coordinator-watch-registration",
+        logTail: String(error.message).slice(0, 50_000),
+      });
+    } catch {}
+    throw new CliError("COORDINATOR_WATCH_FAILED", `Coordinator run ${payload.data.run.id} was registered, but its session could not be watched: ${error.message}`, 1);
+  }
+  await save(stateFile(machine), {
+    machine,
+    machineId: payload.data.machine.id,
+    runId: payload.data.run.id,
+    agentId: c.agentId,
+    startedAt: payload.data.run.startedAt,
+  });
+  return {
+    payload,
+    human: (p) => [
+      `Coordinator ${p.data.run.id} is watching ${p.data.machine.name}.`,
+      `running lanes: ${p.data.runningLanes.length}`,
+      `orphans: ${p.data.orphanedRuns.length}`,
+      `unclaimed results: ${p.data.unclaimedResults.length}`,
+      ...(p.data.takeoverOfRunId ? [`takeover recorded from ${p.data.takeoverOfRunId}`] : []),
+    ].join("\n"),
+  };
+}
+
+async function createWorktrees(repositories, run = execFile) {
+  for (const repository of repositories) {
+    try {
+      const { stdout } = await run("git", ["-C", repository.worktree, "branch", "--show-current"], { encoding: "utf8" });
+      if (stdout.trim() !== repository.branch)
+        throw new CliError("WORKTREE_CONFLICT", `${repository.worktree} exists on ${stdout.trim() || "a detached HEAD"}, not ${repository.branch}.`, 1);
+      continue;
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+    }
+    await run("git", ["-C", repository.source, "fetch", "origin"]);
+    let branchExists = false;
+    try {
+      await run("git", ["-C", repository.source, "show-ref", "--verify", `refs/heads/${repository.branch}`]);
+      branchExists = true;
+    } catch {}
+    await run("git", ["-C", repository.source, "worktree", "add", repository.worktree, ...(branchExists ? [repository.branch] : ["-b", repository.branch, repository.baseRef])]);
+  }
+}
+
+async function writeLaneMarkers(repositories, marker, run = execFile, save = saveJson) {
+  for (const repository of repositories) {
+    const { stdout } = await run("git", ["-C", repository.worktree, "rev-parse", "--git-dir"], { encoding: "utf8" });
+    const gitDir = isAbsolute(stdout.trim()) ? stdout.trim() : resolve(repository.worktree, stdout.trim());
+    await save(join(gitDir, "nodii-lane.json"), marker);
+  }
+}
+
+async function primaryHead(repositories, run = execFile) {
+  const { stdout } = await run("git", ["-C", repositories[0].worktree, "rev-parse", "HEAD"], { encoding: "utf8" });
+  return stdout.trim();
+}
+
+async function defaultLaunchRuntime(options) {
+  const module = await import("./runtime-launcher.js");
+  return module.launchRuntime(options);
+}
+
+export async function verifyFigmaSeat({ env = process.env, fetchImpl = fetch, rateLimit = figmaRateLimit } = {}) {
+  const token = env.FIGMA_PAT || env.FIGMA_TOKEN;
+  if (!token) throw new CliError("FIGMA_TOKEN_REQUIRED", "--figma preflight needs FIGMA_PAT for the assigned Figma account.", 2);
+  let response;
+  try {
+    response = await rateLimit(() => fetchImpl("https://api.figma.com/v1/me", {
+      headers: { "X-Figma-Token": token },
+      signal: AbortSignal.timeout(10_000),
+    }));
+  } catch (error) {
+    throw new CliError("FIGMA_SEAT_UNAVAILABLE", `Figma seat preflight could not complete: ${error.message}`, 1);
+  }
+  if (!response.ok) throw new CliError("FIGMA_SEAT_UNAVAILABLE", `Figma seat preflight returned HTTP ${response.status}.`, 1);
+  const account = await response.json();
+  if (!account?.id) throw new CliError("FIGMA_SEAT_UNAVAILABLE", "Figma did not identify the assigned account.", 1);
+  return true;
+}
+
+/** Serialize the machine's shared Figma token and keep call starts 10s apart. */
+export async function figmaRateLimit(task, {
+  root = basename(dirname(configPath())) === "agents" ? dirname(dirname(configPath())) : dirname(configPath()),
+  sleep = delay,
+  now = Date.now,
+  fs = { mkdir, readFile, rmdir, writeFile },
+} = {}) {
+  const lock = join(root, "figma-rest.lock");
+  const stamp = join(root, "figma-rest-last-call");
+  await fs.mkdir(root, { recursive: true, mode: 0o700 });
+  const deadline = now() + 30_000;
+  for (;;) {
+    try {
+      await fs.mkdir(lock, { mode: 0o700 });
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      if (now() >= deadline) throw new CliError("FIGMA_RATE_LOCKED", "Another Figma REST call has held the machine lock for 30 seconds.", 1);
+      await sleep(100);
+    }
+  }
+  try {
+    let previous = 0;
+    try { previous = Number(await fs.readFile(stamp, "utf8")) || 0; }
+    catch (error) { if (error?.code !== "ENOENT") throw error; }
+    const wait = Math.max(0, 10_000 - (now() - previous));
+    if (wait) await sleep(wait);
+    await fs.writeFile(stamp, `${now()}\n`, { mode: 0o600 });
+    return await task();
+  } finally {
+    await fs.rmdir(lock);
+  }
+}
+
+export async function launchLaneCommand(key, flags, {
+  request = devRequest,
+  config = readConfig,
+  state = loadJson,
+  worktrees = createWorktrees,
+  markers = writeLaneMarkers,
+  head = primaryHead,
+  launcher = defaultLaunchRuntime,
+  figmaSeat = verifyFigmaSeat,
+  laneConfig = loadJson,
+  identityPath = laneConfigPath,
+} = {}) {
+  if (!key) throw new CliError("USAGE", "lane launch needs <key>.", 2);
+  const machine = requireFlag(flags, "machine");
+  const coordinator = flags["coordinator-run"]
+    ? { runId: flags["coordinator-run"], machineId: requireFlag(flags, "machine-id") }
+    : await state(stateFile(machine));
+  if (!coordinator) throw new CliError("COORDINATOR_NOT_STARTED", `Run nodii-dev coordinator start --machine ${machine} first.`, 1);
+  const repositories = launchRepositories(key, flags);
+  const runtime = requireFlag(flags, "runtime");
+  if (!["claude", "codex"].includes(runtime)) throw new CliError("USAGE", "--runtime must be claude or codex.", 2);
+  const issueRefs = values(requireFlag(flags, "issue")).flatMap((item) => String(item).split(",")).filter(Boolean);
+  const issueIds = await Promise.all(issueRefs.map(async (ref) => (await request("GET", `/api/v1/issues/${encode(ref)}`)).data.id));
+  const c = await config();
+  if (coordinator.agentId && coordinator.agentId !== c.agentId)
+    throw new CliError("COORDINATOR_IDENTITY_MISMATCH", `The saved ${machine} coordinator run belongs to another Dev agent.`, 1);
+  const devConfigPath = identityPath(key);
+  const identity = await laneConfig(devConfigPath);
+  if (!identity?.agentId)
+    throw new CliError("LANE_IDENTITY_REQUIRED", `Lane ${key} needs its provisioned Dev identity at ${devConfigPath}.`, 1);
+  const scopes = figmaScopes(flags.figma);
+  const figmaSeatVerified = scopes.length ? await figmaSeat() : false;
+  const profile = requireFlag(flags, "profile");
+  if (!isAbsolute(profile)) throw new CliError("USAGE", "--profile must be an absolute runtime profile path.", 2);
+  const body = {
+    key,
+    doneCheck: requireFlag(flags, "done-check"),
+    kind: requireFlag(flags, "kind"),
+    side: requireFlag(flags, "side"),
+    issueIds,
+    agentId: identity.agentId,
+    machineId: coordinator.machineId,
+    coordinatorRunId: coordinator.runId,
+    repositories: repositories.map(({ source: _source, ...repository }) => repository),
+    runtime,
+    profile,
+    devConfigPath,
+    model: requireFlag(flags, "model"),
+    subagentQuota: Number(requireFlag(flags, "subagents")),
+    ...(flags.notes ? { notes: flags.notes } : {}),
+    ...(flags["narrowing-note"] ? { narrowingNote: flags["narrowing-note"] } : {}),
+    ...(flags["narrowing-remainder"] ? { narrowingRemainder: flags["narrowing-remainder"] } : {}),
+    figmaScopes: scopes,
+    preflight: { ...(figmaSeatVerified ? { figmaSeatVerified: true } : {}) },
+    expectedHeartbeatSeconds: flags["heartbeat-seconds"] ? Number(flags["heartbeat-seconds"]) : 60,
+    ...via,
+  };
+  if (!Number.isInteger(body.subagentQuota) || body.subagentQuota < 0 || body.subagentQuota > 100)
+    throw new CliError("USAGE", "--subagents must be an integer from 0 to 100.", 2);
+  await request("POST", "/api/v1/lanes/launch", { phase: "preflight", ...body });
+  await worktrees(repositories);
+  const lastPushedCommit = await head(repositories);
+  let payload;
+  try {
+    payload = await request("POST", "/api/v1/lanes/launch", { phase: "register", ...body, lastPushedCommit });
+  } catch (error) {
+    throw new CliError(error?.code ?? "LANE_REGISTER_FAILED", `${error?.message ?? error}. Worktrees were created and were not removed; reconcile them before retrying.`, 1);
+  }
+  await markers(repositories, { laneKey: key, laneId: payload.data.lane.id, runId: payload.data.run.id });
+  try {
+    await launcher({
+      laneKey: key,
+      devConfigPath,
+      runtime,
+      model: body.model,
+      profileHome: body.profile,
+      cwd: repositories[0].worktree,
+      addDirs: repositories.slice(1).map(({ worktree }) => worktree),
+      prompt: payload.data.brief,
+      runId: payload.data.run.id,
+    });
+  } catch (error) {
+    try {
+      await request("POST", `/api/v1/lanes/${encode(payload.data.lane.id)}/resume/${encode(payload.data.run.id)}/launch-failed`, {
+        reason: error.message,
+        ...via,
+      });
+    } catch (reportError) {
+      throw new CliError("LANE_LAUNCH_FAILED", `Lane ${key} is registered but its runtime did not start (${error.message}), and Dev could not record the launch failure (${reportError.message}).`, 1);
+    }
+    throw new CliError("LANE_LAUNCH_FAILED", `Lane ${key} is registered but its runtime did not start: ${error.message}. Dev recorded it for lane resume.`, 1);
+  }
+  return { payload, human: `Launched ${key}: ${payload.data.brief}` };
+}
+
+export async function amendLaneCommand(key, flags, { request = devRequest } = {}) {
+  if (!key) throw new CliError("USAGE", "lane amend needs <key>.", 2);
+  const change = Object.fromEntries([["objective", flags.objective], ["scope", flags.scope], ["rules", flags.rules]].filter(([, value]) => value));
+  if (!Object.keys(change).length) throw new CliError("USAGE", "lane amend needs --objective, --scope, or --rules.", 2);
+  const payload = await request("POST", `/api/v1/lanes/${encode(key)}/amendments`, { change, reason: requireFlag(flags, "reason"), ...via });
+  return { payload, human: `Recorded amendment ${payload.data.version} for ${key}.` };
+}
+
+export async function currentMarker(run = execFile, load = loadJson, env = process.env) {
+  let stdout;
+  try {
+    ({ stdout } = await run("git", ["rev-parse", "--git-dir"], { encoding: "utf8" }));
+  } catch {
+    return null;
+  }
+  const gitDir = isAbsolute(stdout.trim()) ? stdout.trim() : resolve(process.cwd(), stdout.trim());
+  const marker = await load(join(gitDir, "nodii-lane.json"));
+  if (!marker) return null;
+  const runId = env.NODII_DEV_RUN_ID ?? marker.runId;
+  if (typeof marker.laneKey !== "string" || !marker.laneKey.trim() || typeof runId !== "string" || !runId.trim())
+    throw new CliError("LANE_MARKER_INVALID", "This worktree's Nodii lane marker is invalid; repair the launch record before running CLI commands.", 1);
+  return { ...marker, runId };
+}
+
+export async function amendmentGuard(argv, { request = devRequest, marker = currentMarker } = {}) {
+  const lane = await marker();
+  if (!lane) return null;
+  const [command, action] = argv.filter((token) => !token.startsWith("--"));
+  if ((command === "lane" && action === "gather" && argv.includes("--delta")) || (command === "lane" && action === "amend")) return lane;
+  const pending = await request("GET", `/api/v1/lanes/${encode(lane.laneKey)}/amendments${query({ runId: lane.runId })}`);
+  if (!pending.data.length) return lane;
+  const detail = pending.data.map((item) => `v${item.version} ${item.reason}: ${JSON.stringify(item.change)}`).join("\n");
+  throw new CliError("LANE_AMENDMENT_ACK_REQUIRED", `Lane ${lane.laneKey} changed:\n${detail}\nDelta gather required: run nodii-dev lane gather ${lane.laneKey} --delta.`, 1, { amendments: pending.data });
+}
+
+export async function gatherLaneCommand(key, flags, { request = devRequest, marker = currentMarker, gather = nextCommand } = {}) {
+  const lane = await marker();
+  key ??= lane?.laneKey;
+  if (!key) throw new CliError("USAGE", "lane gather needs <key> outside a launched lane worktree.", 2);
+  if (!flags.delta) return gather(key, flags, { request });
+  if (!lane || lane.laneKey !== key) throw new CliError("LANE_RUN_REQUIRED", "Delta gather must run inside this lane's registered worktree.", 1);
+  const pending = await request("GET", `/api/v1/lanes/${encode(key)}/amendments${query({ runId: lane.runId })}`);
+  if (!pending.data.length) {
+    const gathered = await gather(key, flags, { request });
+    return { ...gathered, human: `${typeof gathered.human === "string" ? gathered.human : "Gather complete."}\nNo pending amendments.` };
+  }
+  const version = Math.max(...pending.data.map((item) => item.version));
+  const gathered = await gather(key, {
+    ...flags,
+    deltaContext: { runId: lane.runId, amendmentVersion: version },
+  }, { request });
+  const acknowledgedVersion = gathered.payload?.rules?.amendmentAcknowledgement?.version;
+  if (acknowledgedVersion !== version)
+    throw new CliError("LANE_AMENDMENT_ACK_FAILED", `Delta gather did not acknowledge amendment version ${version}; the lane remains blocked.`, 1);
+  return {
+    payload: { ...gathered.payload, amendments: pending.data, acknowledgedVersion },
+    human: `${pending.data.map((item) => `v${item.version} ${item.reason}: ${JSON.stringify(item.change)}`).join("\n")}\n${typeof gathered.human === "string" ? gathered.human : "Gather complete."}\nAcknowledged amendment version ${version}.`,
+  };
+}