okstra 0.21.1 → 0.23.0

package/src/config.mjs

@@ -0,0 +1,392 @@
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve, isAbsolute } from "node:path";
+import { spawn } from "node:child_process";
+import { resolvePaths } from "./paths.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>/.project-docs/okstra/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>.
+
+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;
+    },
+  },
+};
+
+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() {
+  const override = (process.env.OKSTRA_HOME || "").trim();
+  return override !== "" ? override : join(homedir(), ".okstra");
+}
+
+function globalConfigPath() {
+  return join(okstraHome(), "config.json");
+}
+
+function projectConfigPath(projectRoot) {
+  return join(projectRoot, ".project-docs", "okstra", "project.json");
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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);
+}
+
+function spawnCapture(cmd, args, env) {
+  return new Promise((resolveProc) => {
+    const child = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...env },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => (stdout += b.toString()));
+    child.stderr.on("data", (b) => (stderr += b.toString()));
+    child.on("error", (err) => resolveProc({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolveProc({ code, stdout, stderr }));
+  });
+}
+
+async function resolveProjectRoot(cwd) {
+  const paths = await resolvePaths();
+  const result = await spawnCapture(
+    "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: paths.pythonpath },
+  );
+  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 spawnCapture(
+    "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: paths.pythonpath },
+  );
+  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);
+
+  const targetPath =
+    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
+  if (scope === "project" && !projectRoot) {
+    throw new Error("cwd not inside an okstra project — cannot write project scope");
+  }
+  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)");
+  }
+  const targetPath =
+    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
+  if (scope === "project" && !projectRoot) {
+    throw new Error("cwd not inside an okstra project — cannot unset project scope");
+  }
+  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;
+  }
+}

package/src/render-bundle.mjs

@@ -17,7 +17,8 @@ Usage:
     [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \\
     [--gemini-model <m>] [--report-writer-model <m>] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
-    [--clarification-response <path>] [--work-category <cat>]
+    [--clarification-response <path>] [--work-category <cat>] \\
+    [--pr-template-path <path>]   # release-handoff only
 
 All flags pass through unchanged to \`python3 -m okstra_ctl.run\`. The
 shim auto-supplies \`--workspace-root\` (from \`okstra paths --field workspace\`)