okstra 0.174.0 → 0.175.1

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

@@ -1,100 +0,0 @@
-import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
-
-const USAGE = `okstra task-show — summarize a task's manifest and workflow state
-
-Usage:
-  okstra task-show <task-key>                  task-key is project-id:task-group:task-id
-  okstra task-show <task-key> --cwd <dir>      Resolve PROJECT_ROOT from <dir>
-  okstra task-show <task-key> --project <dir>  Use <dir> directly as PROJECT_ROOT
-
-Output: JSON with taskKey, taskType, taskRoot, brief path, workflow phases,
-artifacts, modelAssignments, latestRunPath. Replaces the
-\`cat task-manifest.json | python3 -c ...\` summarization pattern.
-`;
-
-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.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, task_read_side_snapshot,
-    ResolverError, StateError,
-)
-
-explicit = sys.argv[1]
-cwd = sys.argv[2]
-task_key = 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)
-
-pr_path = Path(pr)
-try:
-    snapshot = task_read_side_snapshot(pr_path, task_key)
-except StateError as e:
-    print(json.dumps({
-        "ok": False,
-        "stage": getattr(e, "stage", None) or "task_snapshot",
-        "reason": str(e),
-    }))
-    sys.exit(1)
-
-out = {"ok": True, **snapshot}
-print(json.dumps(out, ensure_ascii=False, default=str, 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/lifecycle/check-project.mjs

@@ -1,187 +0,0 @@
-import { promises as fs } from "node:fs";
-import { join } from "node:path";
-import { buildPythonpath, resolvePaths } from "../../lib/paths.mjs";
-import { fileExists, runProcess } from "../../lib/proc.mjs";
-
-const USAGE = `okstra check-project — verify that the current project has okstra setup
-
-Usage:
-  okstra check-project              Resolve PROJECT_ROOT from cwd, look for
-                                    .okstra/project.json,
-                                    print JSON status to stdout.
-  okstra check-project --cwd <dir>  Use <dir> as the search starting point
-                                    instead of process cwd.
-  okstra check-project --json       Same as default (kept for symmetry with
-                                    'paths --json').
-  okstra check-project --quiet      Suppress stdout on success; exit code
-                                    alone reports state.
-
-Exit codes:
-  0   project.json found, projectId present
-  1   project.json missing or unreadable (project setup not done)
-  2   PROJECT_ROOT could not be resolved from cwd (no project marker
-      ancestor; user should pass --cwd or run from within a project)
-
-User-facing skills should call this after 'ensure-installed' and refuse
-to proceed if the exit code is non-zero, directing the user to
-'/okstra-setup' first.
-`;
-
-function parseArgs(args) {
-  const opts = { cwd: process.cwd(), quiet: false, json: true };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--quiet" || a === "-q") opts.quiet = true;
-    else if (a === "--json") opts.json = true;
-    else if (a === "--cwd") {
-      const next = args[i + 1];
-      if (!next || next.startsWith("--")) throw new Error("--cwd requires a path");
-      opts.cwd = next;
-      i++;
-    } else {
-      throw new Error(`unknown argument '${a}'`);
-    }
-  }
-  return opts;
-}
-
-function emit(opts, payload) {
-  if (opts.quiet) return;
-  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-}
-
-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 { code, payload } = await checkProject({ cwd: opts.cwd });
-  emit(opts, payload);
-  return code;
-}
-
-// Core check shared with 'okstra preflight' — resolves PROJECT_ROOT from cwd
-// and validates .okstra/project.json without writing to stdout.
-export async function checkProject({ cwd = process.cwd() } = {}) {
-  const paths = await resolvePaths();
-
-  const probe = await runProcess(
-    "python3",
-    [
-      "-c",
-      [
-        "import json, sys",
-        "from okstra_project import resolve_project_root, project_json_path, ResolverError",
-        "try:",
-        "    pr = resolve_project_root(explicit_root='', cwd=sys.argv[1])",
-        "    print('PROJECT_ROOT', pr)",
-        "    print('PROJECT_JSON', project_json_path(pr))",
-        "except ResolverError as e:",
-        "    print('RESOLVER_ERROR', e)",
-      ].join("\n"),
-      cwd,
-    ],
-    { PYTHONPATH: buildPythonpath(paths) },
-  );
-
-  if (probe.code !== 0) {
-    const raw = probe.stderr.trim() || probe.stdout.trim();
-    return {
-      code: 1,
-      payload: {
-        ok: false,
-        stage: "python",
-        reason:
-          `python invocation failed: ${raw}. ` +
-          "This usually means the okstra runtime is stale or missing — " +
-          "run 'okstra doctor' to diagnose, then 'okstra ensure-installed' " +
-          "to repair.",
-      },
-    };
-  }
-
-  const lines = probe.stdout.trim().split("\n");
-  const tagOf = (key) =>
-    lines
-      .find((l) => l.startsWith(key + " "))
-      ?.slice(key.length + 1)
-      .trim() ?? null;
-
-  const resolverError = tagOf("RESOLVER_ERROR");
-  if (resolverError) {
-    return {
-      code: 2,
-      payload: { ok: false, stage: "resolve", reason: resolverError, cwd },
-    };
-  }
-
-  const projectRoot = tagOf("PROJECT_ROOT");
-  const projectJsonPath = tagOf("PROJECT_JSON");
-  if (!projectRoot || !projectJsonPath) {
-    return {
-      code: 1,
-      payload: {
-        ok: false,
-        stage: "parse",
-        reason: "could not parse python output",
-        raw: probe.stdout,
-      },
-    };
-  }
-
-  if (!(await fileExists(projectJsonPath))) {
-    return {
-      code: 1,
-      payload: {
-        ok: false,
-        stage: "project_json_missing",
-        reason: `${projectJsonPath} not found — run /okstra-setup in this project first`,
-        projectRoot,
-        projectJsonPath,
-      },
-    };
-  }
-
-  let projectId = null;
-  try {
-    const data = JSON.parse(await fs.readFile(projectJsonPath, "utf8"));
-    projectId = typeof data?.projectId === "string" ? data.projectId : null;
-  } catch (err) {
-    return {
-      code: 1,
-      payload: {
-        ok: false,
-        stage: "project_json_invalid",
-        reason: `failed to parse ${projectJsonPath}: ${err.message}`,
-        projectRoot,
-        projectJsonPath,
-      },
-    };
-  }
-
-  if (!projectId) {
-    return {
-      code: 1,
-      payload: {
-        ok: false,
-        stage: "project_json_invalid",
-        reason: `${projectJsonPath} missing projectId field`,
-        projectRoot,
-        projectJsonPath,
-      },
-    };
-  }
-
-  return {
-    code: 0,
-    payload: { ok: true, projectRoot, projectJsonPath, projectId },
-  };
-}

package/src/commands/lifecycle/config.mjs

@@ -1,385 +0,0 @@
-import { promises as fs } from "node:fs";
-import { dirname, join, resolve, isAbsolute } from "node:path";
-import { buildPythonpath, resolvePaths, resolveOkstraHome } from "../../lib/paths.mjs";
-import { OKSTRA_DIR, projectJsonPath } from "../../lib/okstra-dirs.mjs";
-import { fileExists, runProcess } from "../../lib/proc.mjs";
-
-const USAGE = `okstra config — read / write okstra settings (project + global scopes)
-
-Settings are persisted as JSON keys in one of two files:
-  project: <project-root>/${OKSTRA_DIR}/project.json
-  global:  ~/.okstra/config.json
-
-Supported keys (CLI alias -> JSON field):
-  pr-template-path   -> prTemplatePath
-                       PR body template used by the release-handoff phase.
-                       Path may be absolute, ~/-prefixed, or (project scope
-                       only) relative to <project-root>.
-
-  report-language    -> reportLanguage
-                       Final-report language. One of: en, ko, auto.
-                       'auto' is resolved by the report-writer lead from
-                       the task brief at run time.
-
-Usage:
-  okstra config get <key> [--scope project|global|all]
-      Print the value at the requested scope.
-      'all' prints every scope, plus the effective resolved value where
-      available (for pr-template-path the resolver may fall back to the
-      bundled skill default).
-
-  okstra config set <key> <value> [--scope project|global]
-      Write the value. Scope is required unless cwd is inside an okstra
-      project (then defaults to 'project'). Global scope only accepts
-      absolute or ~/-prefixed paths.
-
-  okstra config unset <key> [--scope project|global]
-      Remove the key from the chosen scope.
-
-  okstra config show [--scope project|global|all]
-      Dump every okstra-managed key from the chosen scope as JSON.
-
-Common options:
-  --cwd <dir>           Search starting point for project root (default: pwd)
-  --json                Force JSON output for get/show (default for show)
-  --quiet               Suppress informational stdout on set/unset; exit
-                        code alone reports success
-`;
-
-// CLI-key -> { jsonField, scopes, validate }
-// validate(value, ctx) returns null on success or an error string.
-const KEYS = {
-  "pr-template-path": {
-    jsonField: "prTemplatePath",
-    scopes: ["project", "global"],
-    validate(value, ctx) {
-      if (typeof value !== "string" || value.trim() === "") {
-        return "value must be a non-empty path";
-      }
-      const v = value.trim();
-      if (ctx.scope === "global") {
-        if (!v.startsWith("~/") && !v.startsWith("~\\") && !isAbsolute(v)) {
-          return (
-            "global scope requires an absolute path or '~/'-prefixed path " +
-            `(got ${JSON.stringify(v)}). Use --scope project for project-root-relative paths.`
-          );
-        }
-      }
-      return null;
-    },
-  },
-  "report-language": {
-    jsonField: "reportLanguage",
-    scopes: ["project", "global"],
-    validate(value) {
-      const allowed = new Set(["en", "ko", "auto"]);
-      if (typeof value !== "string" || !allowed.has(value)) {
-        return (
-          `value must be one of: en, ko, auto (got ${JSON.stringify(value)})`
-        );
-      }
-      return null;
-    },
-  },
-};
-
-function parseArgs(args) {
-  const opts = {
-    op: null,
-    key: null,
-    value: null,
-    scope: null,
-    cwd: process.cwd(),
-    json: false,
-    quiet: false,
-  };
-  const positional = [];
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--scope") {
-      const next = args[i + 1];
-      if (!next) throw new Error("--scope requires a value (project|global|all)");
-      opts.scope = next;
-      i++;
-    } else if (a === "--cwd") {
-      const next = args[i + 1];
-      if (!next) throw new Error("--cwd requires a path");
-      opts.cwd = next;
-      i++;
-    } else if (a === "--json") {
-      opts.json = true;
-    } else if (a === "--quiet" || a === "-q") {
-      opts.quiet = true;
-    } else if (a.startsWith("--")) {
-      throw new Error(`unknown flag ${a}`);
-    } else {
-      positional.push(a);
-    }
-  }
-  opts.op = positional[0] ?? null;
-  opts.key = positional[1] ?? null;
-  opts.value = positional[2] ?? null;
-  return opts;
-}
-
-function okstraHome() {
-  return resolveOkstraHome();
-}
-
-function globalConfigPath() {
-  return join(okstraHome(), "config.json");
-}
-
-function projectConfigPath(projectRoot) {
-  return projectJsonPath(projectRoot);
-}
-
-async function readJson(p) {
-  if (!(await fileExists(p))) return null;
-  const text = await fs.readFile(p, "utf8");
-  try {
-    const data = JSON.parse(text);
-    return typeof data === "object" && data !== null ? data : {};
-  } catch (err) {
-    throw new Error(`failed to parse ${p}: ${err.message}`);
-  }
-}
-
-async function writeJsonAtomic(p, data) {
-  await fs.mkdir(dirname(p), { recursive: true });
-  const tmp = `${p}.tmp.${process.pid}`;
-  await fs.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf8");
-  await fs.rename(tmp, p);
-}
-
-async function resolveProjectRoot(cwd) {
-  const paths = await resolvePaths();
-  const result = await runProcess(
-    "python3",
-    [
-      "-c",
-      [
-        "import sys",
-        "from okstra_project import resolve_project_root, ResolverError",
-        "try:",
-        "    print(resolve_project_root(explicit_root='', cwd=sys.argv[1]))",
-        "except ResolverError as e:",
-        "    sys.stderr.write(str(e)+'\\n'); sys.exit(2)",
-      ].join("\n"),
-      cwd,
-    ],
-    { PYTHONPATH: buildPythonpath(paths) },
-  );
-  if (result.code === 0) return result.stdout.trim();
-  return null;
-}
-
-function emit(opts, payload) {
-  if (opts.quiet) return;
-  if (opts.json || typeof payload !== "string") {
-    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-  } else {
-    process.stdout.write(`${payload}\n`);
-  }
-}
-
-async function effectivePrTemplatePath(projectRoot) {
-  // Mirror the python resolver order without depending on it for the simple
-  // case where we just want to surface the chain in 'config get --scope all'.
-  // Python remains the source of truth at run time; this is informational.
-  const paths = await resolvePaths();
-  const result = await runProcess(
-    "python3",
-    [
-      "-c",
-      [
-        "import json, sys",
-        "from pathlib import Path",
-        "from okstra_ctl.pr_template import resolve_pr_template_path, PrTemplateError",
-        "try:",
-        "    r = resolve_pr_template_path(Path(sys.argv[1]))",
-        "    print(json.dumps({'ok': True, 'path': str(r.path), 'source': r.source}))",
-        "except PrTemplateError as e:",
-        "    print(json.dumps({'ok': False, 'reason': str(e)}))",
-      ].join("\n"),
-      projectRoot ?? process.cwd(),
-    ],
-    { PYTHONPATH: buildPythonpath(paths) },
-  );
-  if (result.code !== 0) return null;
-  try {
-    return JSON.parse(result.stdout.trim());
-  } catch {
-    return null;
-  }
-}
-
-async function opGet(opts) {
-  const spec = KEYS[opts.key];
-  const scope = opts.scope ?? "all";
-  const projectRoot = await resolveProjectRoot(opts.cwd);
-
-  const out = {};
-  if (scope === "project" || scope === "all") {
-    if (!projectRoot) {
-      out.project = { available: false, reason: "cwd not inside an okstra project" };
-    } else {
-      const cfg = (await readJson(projectConfigPath(projectRoot))) ?? {};
-      out.project = {
-        available: true,
-        path: projectConfigPath(projectRoot),
-        value: cfg[spec.jsonField] ?? null,
-      };
-    }
-  }
-  if (scope === "global" || scope === "all") {
-    const cfg = (await readJson(globalConfigPath())) ?? {};
-    out.global = {
-      available: true,
-      path: globalConfigPath(),
-      value: cfg[spec.jsonField] ?? null,
-    };
-  }
-
-  if (scope === "all" && opts.key === "pr-template-path") {
-    const effective = await effectivePrTemplatePath(projectRoot);
-    if (effective) out.effective = effective;
-  }
-
-  if (scope !== "all" && !opts.json) {
-    const entry = out[scope];
-    if (entry?.available && entry.value !== null) {
-      emit(opts, entry.value);
-    } else {
-      emit(opts, "");
-    }
-    return 0;
-  }
-  emit(opts, out);
-  return 0;
-}
-
-async function opSet(opts) {
-  const spec = KEYS[opts.key];
-  if (opts.value === null) throw new Error(`'config set ${opts.key}' requires a value argument`);
-  let scope = opts.scope;
-  const projectRoot = await resolveProjectRoot(opts.cwd);
-  if (!scope) {
-    scope = projectRoot ? "project" : null;
-    if (!scope) {
-      throw new Error(
-        "--scope is required when cwd is not inside an okstra project. " +
-          "Pass --scope project or --scope global.",
-      );
-    }
-  }
-  if (!spec.scopes.includes(scope)) {
-    throw new Error(`key '${opts.key}' does not support scope '${scope}'`);
-  }
-  const ctx = { scope, projectRoot };
-  const err = spec.validate(opts.value, ctx);
-  if (err) throw new Error(err);
-
-  if (scope === "project" && !projectRoot) {
-    throw new Error("cwd not inside an okstra project — cannot write project scope");
-  }
-  const targetPath =
-    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
-  const existing = (await readJson(targetPath)) ?? {};
-  existing[spec.jsonField] = opts.value;
-  await writeJsonAtomic(targetPath, existing);
-  emit(opts, { ok: true, scope, path: targetPath, key: opts.key, value: opts.value });
-  return 0;
-}
-
-async function opUnset(opts) {
-  const spec = KEYS[opts.key];
-  let scope = opts.scope;
-  const projectRoot = await resolveProjectRoot(opts.cwd);
-  if (!scope) {
-    scope = projectRoot ? "project" : null;
-    if (!scope) throw new Error("--scope is required (project|global)");
-  }
-  if (scope === "project" && !projectRoot) {
-    throw new Error("cwd not inside an okstra project — cannot unset project scope");
-  }
-  const targetPath =
-    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
-  const existing = (await readJson(targetPath)) ?? {};
-  if (!(spec.jsonField in existing)) {
-    emit(opts, { ok: true, scope, path: targetPath, key: opts.key, removed: false });
-    return 0;
-  }
-  delete existing[spec.jsonField];
-  await writeJsonAtomic(targetPath, existing);
-  emit(opts, { ok: true, scope, path: targetPath, key: opts.key, removed: true });
-  return 0;
-}
-
-async function opShow(opts) {
-  const scope = opts.scope ?? "all";
-  const projectRoot = await resolveProjectRoot(opts.cwd);
-  const out = {};
-  if (scope === "project" || scope === "all") {
-    out.project = projectRoot
-      ? {
-          path: projectConfigPath(projectRoot),
-          data: (await readJson(projectConfigPath(projectRoot))) ?? {},
-        }
-      : { available: false, reason: "cwd not inside an okstra project" };
-  }
-  if (scope === "global" || scope === "all") {
-    out.global = {
-      path: globalConfigPath(),
-      data: (await readJson(globalConfigPath())) ?? {},
-    };
-  }
-  emit({ ...opts, json: true }, out);
-  return 0;
-}
-
-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 opts = parseArgs(args);
-  if (!opts.op) {
-    process.stderr.write("missing subcommand (get|set|unset|show)\n");
-    return 2;
-  }
-  if (opts.scope !== null && !["project", "global", "all"].includes(opts.scope)) {
-    process.stderr.write(`invalid --scope: ${opts.scope}\n`);
-    return 2;
-  }
-  if (["get", "set", "unset"].includes(opts.op)) {
-    if (!opts.key) {
-      process.stderr.write(`'config ${opts.op}' requires a key argument\n`);
-      return 2;
-    }
-    if (!KEYS[opts.key]) {
-      process.stderr.write(
-        `unknown key '${opts.key}'. Supported: ${Object.keys(KEYS).join(", ")}\n`,
-      );
-      return 2;
-    }
-  }
-  try {
-    switch (opts.op) {
-      case "get":
-        return await opGet(opts);
-      case "set":
-        return await opSet(opts);
-      case "unset":
-        return await opUnset(opts);
-      case "show":
-        return await opShow(opts);
-      default:
-        process.stderr.write(`unknown subcommand '${opts.op}'\n`);
-        return 2;
-    }
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n`);
-    return 1;
-  }
-}