okstra 0.174.0 → 0.175.1

package/src/commands/execute/plan-validate.mjs

@@ -1,68 +0,0 @@
-import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
-
-const USAGE = `okstra plan-validate — verify an approved-plan file has a recognised approval marker
-
-Usage:
-  okstra plan-validate <plan-path>
-
-Output: JSON { ok: true, planPath } on success.
-On failure: { ok: false, reason } with non-zero exit code.
-
-Replaces the \`from okstra_ctl.run import _validate_approved_plan\` heredoc
-pattern. Use this in flows that need to confirm a plan was approved
-without invoking the full prepare_task_bundle pipeline.
-`;
-
-function parseArgs(args) {
-  const positional = args.filter((a) => !a.startsWith("--"));
-  const unknown = args.filter((a) => a.startsWith("--"));
-  if (unknown.length) throw new Error(`unknown argument '${unknown[0]}'`);
-  if (positional.length !== 1) {
-    throw new Error("expected exactly one positional argument: <plan-path>");
-  }
-  return { planPath: positional[0] };
-}
-
-const SCRIPT = `
-import json, sys
-from okstra_ctl.run import _validate_approved_plan, PrepareError
-
-path = sys.argv[1]
-try:
-    _validate_approved_plan(path)
-except PrepareError as e:
-    print(json.dumps({"ok": False, "stage": "validation", "reason": str(e), "planPath": path}))
-    sys.exit(1)
-
-print(json.dumps({"ok": True, "planPath": path}))
-`;
-
-export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  let opts;
-  try {
-    opts = parseArgs(args);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
-    return 2;
-  }
-
-  const result = await runPythonSnippet({
-    script: SCRIPT,
-    args: [opts.planPath],
-  });
-
-  if (result.code !== 0 && !result.stdout.trim()) {
-    emitJsonError({
-      stage: "python",
-      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
-    });
-    return 1;
-  }
-
-  process.stdout.write(result.stdout);
-  return result.code === 0 ? 0 : result.code;
-}

package/src/commands/execute/run.mjs

@@ -1,208 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-
-import { runEnsureInstalled } from "../lifecycle/install.mjs";
-import { runPythonModule } from "../../lib/python-helper.mjs";
-import { resolvePaths } from "../../lib/paths.mjs";
-import { resolveRuntime } from "../../lib/host-registry-client.mjs";
-
-const USAGE = `okstra run — host-aware okstra execution front door
-
-Usage:
-  okstra run [<host-id-or-alias>] --project-root <dir> \\
-    --project-id <id> --task-group <tg> --task-id <tid> --task-type <type> \\
-    [--lead-runtime auto|<host-id-or-alias>] [--yes]
-
-The leading word selects the lead and is an alias for --lead-runtime, so
-'okstra run codex' starts a Codex lead. Naming a lead starts that CLI with the
-prepared prompt; 'external' instead orchestrates an all-CLI run through okstra
-team. Starting a lead whose CLI sandboxes itself asks for confirmation first,
-which --yes answers.
-`;
-
-function flagValue(args, flag) {
-  const equals = args.find((arg) => arg.startsWith(`${flag}=`));
-  if (equals) return equals.slice(flag.length + 1);
-  const index = args.indexOf(flag);
-  return index >= 0 ? args[index + 1] : "";
-}
-
-export function positionalRuntime(args) {
-  const first = args[0];
-  return !first || first.startsWith("-") ? "" : first;
-}
-
-export function requestedRuntimeFromArgs(args) {
-  return flagValue(args, "--lead-runtime") || positionalRuntime(args) || "auto";
-}
-
-export function withoutRuntimeSelection(args) {
-  const rest = positionalRuntime(args) ? args.slice(1) : args;
-  const out = [];
-  for (let i = 0; i < rest.length; i += 1) {
-    const arg = rest[i];
-    if (arg === "--lead-runtime") {
-      i += 1;
-      continue;
-    }
-    if (arg.startsWith("--lead-runtime=")) continue;
-    out.push(arg);
-  }
-  return out;
-}
-
-export function extractLabel(stdout, label) {
-  const prefix = `${label}:`;
-  const line = String(stdout || "").split("\n").find((item) => item.startsWith(prefix));
-  return line ? line.slice(prefix.length).trim() : "";
-}
-
-function projectRootFromArgs(args) {
-  return flagValue(args, "--project-root");
-}
-
-function renderArgs(args, resolution) {
-  return [
-    "--lead-runtime", resolution.resolvedRuntime,
-    "--lead-runtime-request", resolution.requestedRuntime,
-    "--runtime-resolution-json", JSON.stringify(resolution),
-    ...withoutRuntimeSelection(args),
-  ];
-}
-
-export function buildRunPlan({ args, paths, resolution, runManifestPath = "" }) {
-  void paths;
-  const projectRoot = projectRootFromArgs(args);
-  if (resolution.launchMode === "team") {
-    return {
-      ok: true,
-      kind: "team",
-      reason: resolution.reason,
-      commands: [
-        { name: "render-bundle", args: renderArgs(args, resolution), capture: true },
-        { name: "team dispatch", args: ["dispatch", "--project-root", projectRoot, "--run-manifest", runManifestPath], capture: false },
-        { name: "team await", args: ["await", "--project-root", projectRoot, "--run-manifest", runManifestPath], capture: false },
-      ],
-    };
-  }
-
-  if (resolution.launchMode === "lead") {
-    return {
-      ok: true,
-      kind: "launch-lead",
-      reason: resolution.reason,
-      // Handed to okstra.sh, which owns input collection and the launch. Only
-      // the runtime is decided here; everything else is passed through so the
-      // launcher can prompt for whatever is still missing.
-      // --launch-only: open the host and stop. Task inputs are collected by the
-      // okstra-run skill inside the session, which is how the Claude Code path
-      // has always worked — demanding a task id out here asks for it before the
-      // user has a session to pick one in.
-      commands: [
-        {
-          name: "launcher",
-          args: [
-            "--launch-only",
-            "--lead-runtime", resolution.resolvedRuntime,
-            ...withoutRuntimeSelection(args),
-          ],
-          capture: false,
-        },
-      ],
-    };
-  }
-
-  return { ok: false, reason: `unsupported launch mode: ${resolution.launchMode}`, commands: [] };
-}
-
-async function ensureRuntime(requestedRuntime) {
-  return await runEnsureInstalled(["--runtime", requestedRuntime, "-q"]);
-}
-
-async function runRenderCommand(command, paths) {
-  const result = await runPythonModule({
-    module: "okstra_ctl.run",
-    args: ["--workspace-root", paths.workspace, "--render-only", ...command.args],
-    stdio: "capture",
-  });
-  process.stdout.write(result.stdout);
-  if (result.stderr) process.stderr.write(result.stderr);
-  return result;
-}
-
-async function launchLead(command, paths) {
-  // okstra.sh already collects missing task inputs, prepares the bundle, asks
-  // about a sandbox waiver, and execs the lead. Reimplementing any of that here
-  // would give the two front doors separate answers to the same questions —
-  // most visibly, this one had no way to ask for a task id and simply forwarded
-  // the gap to python's argument parser.
-  const launcher = join(paths.bin, "okstra.sh");
-  if (!existsSync(launcher)) {
-    process.stderr.write(
-      `error: launcher not found at ${launcher} — run 'okstra install'\n`,
-    );
-    return 1;
-  }
-  const started = spawnSync(launcher, command.args, { stdio: "inherit" });
-  if (started.error) {
-    process.stderr.write(`error: could not start the launcher: ${started.error.message}\n`);
-    return 1;
-  }
-  return started.status ?? 1;
-}
-
-async function runTeam(args) {
-  const { run: runTeamCommand } = await import("./team.mjs");
-  return await runTeamCommand(args);
-}
-
-export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-
-  const paths = await resolvePaths();
-  const requestedRuntime = requestedRuntimeFromArgs(args);
-  const resolution = await resolveRuntime({
-    requestedRuntime,
-    command: "run",
-    env: process.env,
-    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
-  });
-  if (!resolution.ok) {
-    process.stderr.write(`error: ${resolution.reason}\n`);
-    return 2;
-  }
-
-  const firstPlan = buildRunPlan({ args, paths, resolution });
-  if (!firstPlan.ok) {
-    process.stderr.write(`error: ${firstPlan.reason}\n`);
-    return 2;
-  }
-
-  const ensureCode = await ensureRuntime(requestedRuntime);
-  if (ensureCode !== 0) return ensureCode;
-
-  if (firstPlan.kind === "launch-lead") {
-    return await launchLead(firstPlan.commands[0], paths);
-  }
-
-  const render = firstPlan.commands[0];
-  const prepared = await runRenderCommand(render, paths);
-  if (prepared.code !== 0) return prepared.code ?? 1;
-
-  const runManifestPath = extractLabel(prepared.stdout, "okstra run manifest");
-  if (!runManifestPath) {
-    process.stderr.write("error: render output did not include 'okstra run manifest:'\n");
-    return 1;
-  }
-
-  const plan = buildRunPlan({ args, paths, resolution, runManifestPath });
-  for (const command of plan.commands.slice(1)) {
-    const code = await runTeam(command.args);
-    if (code !== 0) return code;
-  }
-  return 0;
-}

package/src/commands/execute/wizard.mjs

@@ -1,167 +0,0 @@
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { runPythonModule } from "../../lib/python-helper.mjs";
-import { resolvePaths } from "../../lib/paths.mjs";
-
-const USAGE = `okstra wizard — interactive okstra-run input collector
-
-Used by the okstra-run skill to drive the per-step prompt loop. Each
-subcommand round-trips a JSON state file held by the skill.
-
-Subcommands:
-  new-state-file  print a fresh absolute state-file path on stdout (no I/O on the file itself)
-  init            seed a fresh wizard state and emit the first prompt
-  step            submit an answer (or fetch the current prompt) and emit next
-  render-args     emit the final --flag/value map for 'okstra render-bundle'
-  confirmation    emit the multi-line confirmation echo block
-  outcome         emit render args, persistence actions, and confirmation text
-
-Usage:
-  okstra wizard new-state-file
-  okstra wizard init --state-file <path> --project-root <p> --project-id <id> --host-runtime <runtime> \\
-    --entry-mode current-session --available-function <semantic-name>
-  okstra wizard step --state-file <path> (--answer <value> | --no-submit)
-  okstra wizard render-args --state-file <path>
-  okstra wizard confirmation --state-file <path>
-  okstra wizard outcome --state-file <path>
-
-'init' auto-fills --workspace-root from 'okstra paths --field workspace',
-so callers do not pass it.
-
-All subcommands emit a single JSON object on stdout. On validation failure
-'step' returns {ok:false, error, current} so the skill can re-prompt.
-`;
-
-// Only the flags listed here are boolean; every other wizard flag takes a
-// value, so the token after it is always its value — even free-text answers
-// that begin with "--". A heuristic that rejects "--"-prefixed values would
-// make legitimate directive/base-ref answers unsubmittable. The inline
-// "--key=value" form lets callers pass any value (including empty)
-// unambiguously.
-const BOOLEAN_FLAGS = new Set(["no-submit"]);
-
-export function parseFlags(args) {
-  const out = {};
-  const setFlag = (key, value) => {
-    if (key === "available-function") {
-      out[key] = [...(out[key] ?? []), value];
-      return;
-    }
-    out[key] = value;
-  };
-  for (let i = 0; i < args.length; i += 1) {
-    const a = args[i];
-    if (!a.startsWith("--")) {
-      throw new Error(`unexpected positional argument: ${a}`);
-    }
-    const eq = a.indexOf("=");
-    if (eq !== -1) {
-      setFlag(a.slice(2, eq), a.slice(eq + 1));
-      continue;
-    }
-    const key = a.slice(2);
-    if (BOOLEAN_FLAGS.has(key)) {
-      out[key] = true;
-      continue;
-    }
-    if (i + 1 >= args.length) {
-      throw new Error(`flag --${key} requires a value`);
-    }
-    setFlag(key, args[i + 1]);
-    i += 1;
-  }
-  return out;
-}
-
-export function buildPythonArgs(sub, flags, workspaceRoot = "") {
-  const pyArgs = [sub, "--state-file", flags["state-file"]];
-  if (sub === "init") {
-    pyArgs.push("--workspace-root", workspaceRoot);
-    pyArgs.push("--project-root", flags["project-root"]);
-    pyArgs.push("--project-id", flags["project-id"]);
-    if (flags["host-runtime"]) {
-      pyArgs.push("--host-runtime", flags["host-runtime"]);
-    }
-    for (const value of flags["available-function"] ?? []) {
-      pyArgs.push("--available-function", value);
-    }
-    pyArgs.push("--entry-mode", flags["entry-mode"] ?? "current-session");
-  } else if (sub === "step") {
-    if (flags["no-submit"]) {
-      pyArgs.push("--no-submit");
-    }
-    if (flags.answer !== undefined) {
-      pyArgs.push("--answer", flags.answer);
-    }
-  }
-  return pyArgs;
-}
-
-export async function run(args) {
-  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return args.length === 0 ? 2 : 0;
-  }
-
-  const [sub, ...rest] = args;
-  if (!["new-state-file", "init", "step", "render-args", "confirmation", "outcome"].includes(sub)) {
-    process.stderr.write(`error: unknown wizard subcommand '${sub}'\n\n${USAGE}`);
-    return 2;
-  }
-
-  if (sub === "new-state-file") {
-    if (rest.length > 0) {
-      process.stderr.write("error: new-state-file takes no arguments\n");
-      return 2;
-    }
-    const dir = mkdtempSync(join(tmpdir(), "okstra-wizard-"));
-    process.stdout.write(join(dir, "state.json") + "\n");
-    return 0;
-  }
-
-  let flags;
-  try {
-    flags = parseFlags(rest);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
-    return 2;
-  }
-
-  if (!flags["state-file"]) {
-    process.stderr.write("error: --state-file is required\n");
-    return 2;
-  }
-
-  let workspaceRoot = "";
-  if (sub === "init") {
-    if (!flags["project-root"] || !flags["project-id"]) {
-      process.stderr.write("error: init requires --project-root and --project-id\n");
-      return 2;
-    }
-    const paths = await resolvePaths();
-    workspaceRoot = paths.workspace;
-  }
-  const pyArgs = buildPythonArgs(sub, flags, workspaceRoot);
-
-  const result = await runPythonModule({
-    module: "okstra_ctl.wizard",
-    args: pyArgs,
-    stdio: "capture",
-  });
-
-  if (result.code !== 0 && !result.stdout.trim()) {
-    process.stdout.write(
-      JSON.stringify(
-        { ok: false, stage: "python", reason: result.stderr.trim() || "no output" },
-        null,
-        2,
-      ) + "\n",
-    );
-    return 1;
-  }
-
-  process.stdout.write(result.stdout);
-  return result.code === 0 ? 0 : result.code;
-}

package/src/commands/inspect/stage-map.mjs

@@ -1,98 +0,0 @@
-import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
-
-const USAGE = `okstra stage-map — dump a task's implementation-planning Stage Map + done stages
-
-Usage:
-  okstra stage-map <task-key>                  task-key is project-id:task-group:task-id
-  okstra stage-map <task-key> --cwd <dir>      Resolve PROJECT_ROOT from <dir>
-  okstra stage-map <task-key> --project <dir>  Use <dir> directly as PROJECT_ROOT
-
-Output: JSON { ok, taskKey, taskRoot, state, sourcePlanPath, stages:[…], doneStages:[int], planning:{…} }.
-Each stage row carries stage_number, title, depends_on, step_count and exit_contract_summary; a
-schema-v2 report adds that stage's sliceValue, acceptance and exitContract.
-planning carries the report's task-level rows — rollbackStrategy, validationChecklist,
-crossProjectDependencies, dependencyMigrationRisk, recommendedOption — so a consumer renders the
-plan instead of re-summarising the report body. Both are absent for a schema-v1 report.
-stages is [] when no implementation-planning Stage Map exists.
-`;
-
-function parseArgs(args) {
-  const opts = { cwd: process.cwd(), projectRoot: "", taskKey: "" };
-  const positional = [];
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--cwd") {
-      opts.cwd = args[++i];
-      if (!opts.cwd) throw new Error("--cwd requires a path");
-    } else if (a === "--project") {
-      opts.projectRoot = args[++i];
-      if (!opts.projectRoot) throw new Error("--project requires a path");
-    } else if (a === "--json") {
-      // JSON is always emitted; accept the flag for parity with sibling commands.
-    } else if (a.startsWith("--")) {
-      throw new Error(`unknown argument '${a}'`);
-    } else {
-      positional.push(a);
-    }
-  }
-  if (positional.length !== 1) {
-    throw new Error("expected exactly one positional argument: <task-key>");
-  }
-  opts.taskKey = positional[0];
-  return opts;
-}
-
-const SCRIPT = `
-import json, sys
-from pathlib import Path
-from okstra_project import (
-    resolve_project_root, stage_map_read_side_snapshot, ResolverError, StateError,
-)
-
-explicit, cwd, task_key = sys.argv[1], sys.argv[2], sys.argv[3]
-
-try:
-    pr = resolve_project_root(explicit_root=explicit, cwd=cwd)
-except ResolverError as e:
-    print(json.dumps({"ok": False, "stage": "resolve", "reason": str(e)}))
-    sys.exit(2)
-
-try:
-    snapshot = stage_map_read_side_snapshot(Path(pr), task_key)
-except StateError as e:
-    print(json.dumps({
-        "ok": False,
-        "stage": getattr(e, "stage", None) or "stage_map",
-        "reason": str(e),
-    }))
-    sys.exit(1)
-
-print(json.dumps({"ok": True, **snapshot}, ensure_ascii=False, indent=2))
-`;
-
-export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  let opts;
-  try {
-    opts = parseArgs(args);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
-    return 2;
-  }
-  const result = await runPythonSnippet({
-    script: SCRIPT,
-    args: [opts.projectRoot, opts.cwd, opts.taskKey],
-  });
-  if (result.code !== 0 && !result.stdout.trim()) {
-    emitJsonError({
-      stage: "python",
-      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
-    });
-    return 1;
-  }
-  process.stdout.write(result.stdout);
-  return result.code === 0 ? 0 : result.code;
-}

package/src/commands/inspect/task-list.mjs

@@ -1,97 +0,0 @@
-import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
-
-const USAGE = `okstra task-list — list okstra tasks registered in this project
-
-Usage:
-  okstra task-list                            Resolve PROJECT_ROOT from cwd, list tasks
-  okstra task-list --cwd <dir>                Start resolution from <dir> instead of cwd
-  okstra task-list --project <dir>            Use <dir> directly as PROJECT_ROOT
-  okstra task-list --task-type <type>         Filter by taskType
-  okstra task-list --latest-run-status <s>    Filter by latestRunStatus
-  okstra task-list --task-group <group>       Filter by taskGroup
-  okstra task-list --limit <N>                Keep the first N (catalog is updatedAt desc)
-
-Output: JSON { ok, projectRoot, tasks: [...], latest: {...}|null }.
-Filters are AND-combined and all optional.
-
-Replaces the common pattern of loading okstra_project and calling
-list_project_tasks + read_latest_task from a python heredoc.
-`;
-
-function parseArgs(args) {
-  const opts = { cwd: process.cwd(), projectRoot: "", taskType: "", latestRunStatus: "", taskGroup: "", limit: "" };
-  const valued = {
-    "--cwd": "cwd", "--project": "projectRoot", "--task-type": "taskType",
-    "--latest-run-status": "latestRunStatus", "--task-group": "taskGroup", "--limit": "limit",
-  };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    const key = valued[a];
-    if (!key) throw new Error(`unknown argument '${a}'`);
-    const v = args[++i];
-    if (v === undefined || v === "") throw new Error(`${a} requires a value`);
-    opts[key] = v;
-  }
-  return opts;
-}
-
-const SCRIPT = `
-import json, sys
-from pathlib import Path
-from okstra_project import (
-    list_project_tasks, read_latest_task,
-    resolve_project_root, ResolverError,
-)
-
-explicit = sys.argv[1]
-cwd = sys.argv[2]
-task_type = sys.argv[3] or None
-latest_run_status = sys.argv[4] or None
-task_group = sys.argv[5] or None
-limit = int(sys.argv[6]) if sys.argv[6] else None
-try:
-    pr = resolve_project_root(explicit_root=explicit, cwd=cwd)
-except ResolverError as e:
-    print(json.dumps({"ok": False, "stage": "resolve", "reason": str(e)}))
-    sys.exit(2)
-
-pr_path = Path(pr)
-print(json.dumps({
-    "ok": True,
-    "projectRoot": str(pr_path),
-    "tasks": list_project_tasks(
-        pr_path, task_type=task_type, latest_run_status=latest_run_status,
-        task_group=task_group, limit=limit),
-    "latest": read_latest_task(pr_path),
-}, default=str))
-`;
-
-export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  let opts;
-  try {
-    opts = parseArgs(args);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
-    return 2;
-  }
-
-  const result = await runPythonSnippet({
-    script: SCRIPT,
-    args: [opts.projectRoot, opts.cwd, opts.taskType, opts.latestRunStatus, opts.taskGroup, opts.limit],
-  });
-
-  if (result.code !== 0 && !result.stdout.trim()) {
-    emitJsonError({
-      stage: "python",
-      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
-    });
-    return 1;
-  }
-
-  process.stdout.write(result.stdout);
-  return result.code === 0 ? 0 : result.code;
-}