okstra 0.174.0 → 0.176.0

package/src/commands/lifecycle/paths.mjs

@@ -1,104 +0,0 @@
-import { resolvePaths } from "../../lib/paths.mjs";
-
-const USAGE = `okstra paths — print runtime paths
-
-Usage:
-  okstra paths                Print all paths as JSON
-  okstra paths --json         Same as the default
-  okstra paths --field <key>  Print one field as a plain string
-  okstra paths --shell        Print shell 'export' statements for the
-                              standard OKSTRA_* env vars (sourced by skills)
-
-Fields:
-  agents       Absolute path to agents/. Default: <workspace>/agents.
-  workspace    Directory containing prompts/, templates/, validators/,
-               agents/. Equals the package's runtime/ directory in copy
-               mode, or the dev-link repo path in dev mode.
-  pythonpath   $HOME/.okstra/lib/python
-  bin          $HOME/.okstra/bin
-  home         $HOME/.okstra
-  version      Installed okstra version (from ~/.okstra/version stamp)
-  package      Currently invoked package version
-  dev-link     Repo path recorded by 'okstra install --link <repo>'
-               (empty string when not in dev mode).
-
-Shell mode exports (variable name -> field):
-  OKSTRA_WORKSPACE     workspace
-  OKSTRA_AGENTS_DIR    agents
-  OKSTRA_PYTHONPATH    pythonpath
-  OKSTRA_BIN           bin
-  OKSTRA_HOME          home
-`;
-
-const VALID_FIELDS = new Set([
-  "agents",
-  "workspace",
-  "pythonpath",
-  "bin",
-  "home",
-  "version",
-  "package",
-  "dev-link",
-]);
-
-const SHELL_EXPORTS = [
-  ["OKSTRA_WORKSPACE", "workspace"],
-  ["OKSTRA_AGENTS_DIR", "agents"],
-  ["OKSTRA_PYTHONPATH", "pythonpath"],
-  ["OKSTRA_BIN", "bin"],
-  ["OKSTRA_HOME", "home"],
-];
-
-export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-
-  let field = null;
-  let mode = "json";
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--json") {
-      mode = "json";
-    } else if (a === "--shell") {
-      mode = "shell";
-    } else if (a === "--field") {
-      field = args[i + 1];
-      i++;
-      if (!field) {
-        process.stderr.write("error: --field requires a name\n");
-        return 2;
-      }
-      if (!VALID_FIELDS.has(field)) {
-        process.stderr.write(`error: unknown field '${field}'. Valid: ${[...VALID_FIELDS].join(", ")}\n`);
-        return 2;
-      }
-      mode = "field";
-    } else {
-      process.stderr.write(`error: unknown argument '${a}'\n\n${USAGE}`);
-      return 2;
-    }
-  }
-
-  const paths = await resolvePaths();
-
-  if (mode === "field") {
-    process.stdout.write(`${paths[field]}\n`);
-    return 0;
-  }
-  if (mode === "shell") {
-    for (const [varName, key] of SHELL_EXPORTS) {
-      process.stdout.write(`export ${varName}=${shellQuote(paths[key])}\n`);
-    }
-    return 0;
-  }
-  process.stdout.write(`${JSON.stringify(paths, null, 2)}\n`);
-  return 0;
-}
-
-function shellQuote(value) {
-  if (value === "" || value == null) return "''";
-  if (/^[A-Za-z0-9_\/.\-+:@%=]+$/.test(value)) return value;
-  return `'${String(value).replace(/'/g, "'\\''")}'`;
-}

package/src/commands/lifecycle/preflight.mjs

@@ -1,125 +0,0 @@
-import { checkProject } from "./check-project.mjs";
-import { runEnsureInstalled } from "./install.mjs";
-import { missingHelperScripts } from "../../lib/helper-scripts.mjs";
-import { resolveInstalledScript } from "../../lib/python-helper.mjs";
-import { resolvePaths } from "../../lib/paths.mjs";
-import { checkRuntimeReadiness } from "../../lib/host-registry-client.mjs";
-
-const USAGE = `okstra preflight — one-call skill preflight (ensure-installed + check-project)
-
-Usage:
-  okstra preflight [--runtime <name>] [--cwd <dir>] [--json]
-
-Runs the runtime freshness check (quietly reinstalling when stale), then
-verifies the target project has .okstra/project.json. Prints one JSON object:
-
-  ok: true   {ok, projectRoot, projectJsonPath, projectId, runtimeReadiness}
-  ok: false  {ok, stage, reason, ...}
-             stage: install | helper_scripts_missing | resolve |
-                    project_json_missing | project_json_invalid |
-                    runtime_readiness | python | parse
-
-Options:
-  --runtime <name>   Runtime whose assets must be present (e.g. claude-code);
-                     forwarded to ensure-installed.
-  --cwd <dir>        Resolve PROJECT_ROOT from <dir> instead of process cwd.
-  --json             Default output format (kept for symmetry).
-
-Exit codes:
-  0   runtime fresh, project registered, and current host ready
-  1   runtime install failed, project setup missing/invalid, or host not ready
-  2   PROJECT_ROOT could not be resolved from cwd (pass --cwd), or bad flags
-`;
-
-function parseArgs(args) {
-  const opts = { cwd: process.cwd(), runtime: null };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--json") continue;
-    if (a === "--cwd" || a === "--runtime") {
-      const next = args[i + 1];
-      if (!next || next.startsWith("--")) throw new Error(`${a} requires a value`);
-      if (a === "--cwd") opts.cwd = next;
-      else opts.runtime = next;
-      i++;
-    } else {
-      throw new Error(`unknown argument '${a}'`);
-    }
-  }
-  return opts;
-}
-
-function emit(payload) {
-  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-}
-
-// A BLOCKING lead step calls these mid-run; resolving them here turns a stale
-// install into an up-front failure instead of a dead end hours into a run.
-async function findMissingHelperScripts() {
-  return missingHelperScripts(await resolvePaths(), resolveInstalledScript);
-}
-
-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 ensureArgs = ["--quiet"];
-  if (opts.runtime) ensureArgs.push("--runtime", opts.runtime);
-  const installCode = await runEnsureInstalled(ensureArgs);
-  if (installCode !== 0) {
-    emit({
-      ok: false,
-      stage: "install",
-      reason:
-        "okstra runtime install failed — run 'okstra doctor' to diagnose, " +
-        "then 'okstra install' to repair.",
-    });
-    return installCode === 2 ? 2 : 1;
-  }
-
-  const missingHelpers = await findMissingHelperScripts();
-  if (missingHelpers.length > 0) {
-    emit({
-      ok: false,
-      stage: "helper_scripts_missing",
-      missingHelpers,
-      reason:
-        `${missingHelpers.length} helper script(s) a lead prompt can call are not ` +
-        "installed — run 'okstra install' to repair before starting a run.",
-    });
-    return 1;
-  }
-
-  const { code, payload } = await checkProject({ cwd: opts.cwd });
-  if (code !== 0) {
-    emit(payload);
-    return code;
-  }
-
-  const runtimeReadiness = await checkRuntimeReadiness({
-    runtime: opts.runtime,
-    projectRoot: payload.projectRoot,
-  });
-  if (["blocked", "unknown"].includes(runtimeReadiness.status)) {
-    emit({
-      ...payload,
-      ok: false,
-      stage: "runtime_readiness",
-      reason: `current host readiness is ${runtimeReadiness.status}`,
-      runtimeReadiness,
-    });
-    return 1;
-  }
-  emit({ ...payload, runtimeReadiness });
-  return code;
-}

package/src/commands/lifecycle/setup.mjs

@@ -1,333 +0,0 @@
-import { promises as fs } from "node:fs";
-import { createInterface } from "node:readline";
-import { homedir } from "node:os";
-import { join, resolve as resolvePath } from "node:path";
-import { buildPythonpath, resolvePaths } from "../../lib/paths.mjs";
-import { fileExists, runProcess } from "../../lib/proc.mjs";
-
-const USAGE = `okstra setup — register the current project with okstra
-
-Writes <PROJECT_ROOT>/.okstra/project.json. This is the
-project-level companion to 'okstra install' (which is machine-level).
-Inside a Claude Code session this is also exposed as the /okstra-setup
-slash command.
-
-Usage:
-  okstra setup --project-id <id>          Register with explicit projectId
-  okstra setup                            Use existing project.json or
-                                          prompt for projectId (TTY only)
-  okstra setup --project-root <path>      Override PROJECT_ROOT resolution
-  okstra setup --yes                      Skip prompts; require all inputs
-                                          on the command line
-
-Behavior:
-  - If project.json already exists, the projectId must match (okstra refuses
-    to silently rename a project). Delete the file manually if you really
-    want to change projectId.
-  - If --project-id is omitted and stdin is a TTY, you are prompted.
-  - If --project-id is omitted and stdin is not a TTY, the command exits
-    with an error (use --project-id for CI / scripts).
-
-Exit codes:
-  0   project.json present and valid after the run
-  1   I/O / python failure or projectId mismatch
-  2   PROJECT_ROOT could not be resolved
-`;
-
-function parseArgs(args) {
-  const opts = {
-    projectId: null,
-    projectRoot: null,
-    yes: false,
-  };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--yes" || a === "-y") opts.yes = true;
-    else if (a === "--project-id") {
-      const next = args[i + 1];
-      if (!next || next.startsWith("--")) throw new Error("--project-id requires a value");
-      opts.projectId = next;
-      i++;
-    } else if (a === "--project-root") {
-      const next = args[i + 1];
-      if (!next || next.startsWith("--")) throw new Error("--project-root requires a path");
-      opts.projectRoot = next;
-      i++;
-    } else {
-      throw new Error(`unknown argument '${a}'`);
-    }
-  }
-  return opts;
-}
-
-
-function prompt(question) {
-  return new Promise((resolve) => {
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
-}
-
-function validateProjectId(id) {
-  if (!id) return "project-id is empty";
-  if (!/[A-Za-z0-9]/.test(id)) return "project-id must contain at least one alphanumeric character";
-  return null;
-}
-
-async function resolveProjectRoot(paths, explicit) {
-  const probe = await runProcess(
-    "python3",
-    [
-      "-c",
-      [
-        "import sys",
-        "from okstra_project import resolve_project_root, project_json_path, ResolverError",
-        "try:",
-        "    pr = resolve_project_root(explicit_root=sys.argv[1], cwd=sys.argv[2])",
-        "    print('PROJECT_ROOT', pr)",
-        "    print('PROJECT_JSON', project_json_path(pr))",
-        "except ResolverError as e:",
-        "    print('RESOLVER_ERROR', e)",
-      ].join("\n"),
-      explicit || "",
-      process.cwd(),
-    ],
-    { PYTHONPATH: buildPythonpath(paths) },
-  );
-  if (probe.code !== 0) {
-    throw new Error(`python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`);
-  }
-  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) {
-    const err = new Error(resolverError);
-    err.code = "RESOLVER";
-    throw err;
-  }
-  return {
-    projectRoot: tagOf("PROJECT_ROOT"),
-    projectJsonPath: tagOf("PROJECT_JSON"),
-  };
-}
-
-async function upsert(paths, projectRoot, projectId) {
-  const probe = await runProcess(
-    "python3",
-    [
-      "-c",
-      [
-        "import json, sys",
-        "from pathlib import Path",
-        "from okstra_project import upsert_project_json, ResolverError",
-        "try:",
-        "    result = upsert_project_json(Path(sys.argv[1]), sys.argv[2])",
-        "    print('OK', json.dumps(result))",
-        "except ResolverError as e:",
-        "    print('ERROR', e)",
-      ].join("\n"),
-      projectRoot,
-      projectId,
-    ],
-    { PYTHONPATH: buildPythonpath(paths) },
-  );
-  if (probe.code !== 0) {
-    throw new Error(`python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`);
-  }
-  const out = probe.stdout.trim();
-  if (out.startsWith("OK ")) {
-    return JSON.parse(out.slice(3));
-  }
-  if (out.startsWith("ERROR ")) {
-    throw new Error(out.slice(6));
-  }
-  throw new Error(`unexpected upsert output: ${out}`);
-}
-
-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 1;
-  }
-
-  const paths = await resolvePaths();
-
-  let resolved;
-  try {
-    resolved = await resolveProjectRoot(paths, opts.projectRoot);
-  } catch (err) {
-    if (err.code === "RESOLVER") {
-      const cwd = resolvePath(process.cwd());
-      const home = resolvePath(homedir());
-      const inHome = cwd === home;
-      process.stderr.write(
-        "error: 'okstra setup' registers the CURRENT directory as an okstra project,\n" +
-          "       but no project root could be resolved from here.\n" +
-          `       cwd: ${cwd}\n` +
-          (inHome
-            ? "       (this looks like your home directory — setup is project-level, not machine-level;\n" +
-              "        machine-level install is 'okstra install', which you've likely already done.)\n"
-            : "") +
-          "\nFix one of:\n" +
-          "  1. cd into the project you want to register, then re-run:\n" +
-          "       cd <your project> && okstra setup --project-id <id>\n" +
-          "  2. pass an explicit path:\n" +
-          "       okstra setup --project-root <abs-path> --project-id <id>\n" +
-          "  3. run from inside any git working tree (the toplevel becomes PROJECT_ROOT).\n" +
-          `\n(underlying error: ${err.message})\n`,
-      );
-      return 2;
-    }
-    // Non-RESOLVER path: typically python invocation failure (PYTHONPATH wrong,
-    // ~/.okstra missing, python3 not on PATH, okstra_project module missing).
-    // The user can't fix this by adjusting setup arguments — it's a runtime
-    // health issue, not a PROJECT_ROOT issue. Reword accordingly.
-    const looksLikePythonFailure = /python invocation failed|ModuleNotFoundError|No module named/.test(
-      err.message,
-    );
-    if (looksLikePythonFailure) {
-      process.stderr.write(
-        "error: 'okstra setup' could not start because the okstra runtime is not\n" +
-          "       reachable from this process. This is almost always a stale or\n" +
-          "       incomplete install, not a problem with your setup arguments.\n" +
-          "\nFix:\n" +
-          "  1. run 'okstra doctor' to see exactly what is missing\n" +
-          "  2. run 'okstra ensure-installed' (or 'npx -y okstra@latest install')\n" +
-          "     to repair the runtime\n" +
-          "  3. retry: okstra setup --project-id <id>\n" +
-          `\n(underlying error: ${err.message})\n`,
-      );
-      return 1;
-    }
-    process.stderr.write(`error: could not resolve PROJECT_ROOT: ${err.message}\n`);
-    return 1;
-  }
-  const { projectRoot, projectJsonPath } = resolved;
-
-  let existing = null;
-  if (await fileExists(projectJsonPath)) {
-    try {
-      existing = JSON.parse(await fs.readFile(projectJsonPath, "utf8"));
-    } catch (err) {
-      process.stderr.write(`error: failed to parse ${projectJsonPath}: ${err.message}\n`);
-      return 1;
-    }
-  }
-
-  let projectId = opts.projectId;
-  if (!projectId && existing?.projectId) {
-    projectId = existing.projectId;
-  }
-
-  if (!projectId) {
-    if (opts.yes || !process.stdin.isTTY) {
-      process.stderr.write(
-        `error: --project-id is required (no existing project.json, not a TTY)\n`,
-      );
-      return 1;
-    }
-    process.stderr.write(`PROJECT_ROOT: ${projectRoot}\n`);
-    const answer = await prompt("project-id (e.g. INV-1234, my-app): ");
-    projectId = answer;
-  }
-
-  const invalid = validateProjectId(projectId);
-  if (invalid) {
-    process.stderr.write(`error: ${invalid}\n`);
-    return 1;
-  }
-
-  let result;
-  try {
-    result = await upsert(paths, projectRoot, projectId);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n`);
-    return 1;
-  }
-
-  let settingsSymlink = null;
-  try {
-    settingsSymlink = await ensureProjectSettingsSymlink(projectRoot);
-  } catch (err) {
-    process.stderr.write(
-      `warning: failed to provision .claude/settings.local.json symlink — ` +
-        `host Claude Code sessions in this project may need to add wrapper permissions manually. (${err.message})\n`,
-    );
-  }
-
-  process.stdout.write(
-    JSON.stringify(
-      {
-        ok: true,
-        ...result,
-        projectJsonPath,
-        settingsLocalJson: settingsSymlink,
-      },
-      null,
-      2,
-    ) + "\n",
-  );
-  return 0;
-}
-
-async function ensureProjectSettingsSymlink(projectRoot) {
-  const template = join(homedir(), ".okstra", "templates", "settings.local.json");
-  try {
-    await fs.access(template);
-  } catch {
-    return null; // install hasn't provisioned the template yet (pre-0.14 install)
-  }
-
-  const claudeDir = join(projectRoot, ".claude");
-  const target = join(claudeDir, "settings.local.json");
-  await fs.mkdir(claudeDir, { recursive: true });
-
-  let existingStat;
-  try {
-    existingStat = await fs.lstat(target);
-  } catch {
-    existingStat = null;
-  }
-
-  if (existingStat?.isSymbolicLink()) {
-    const current = await fs.readlink(target);
-    const resolved = current.startsWith("/") ? current : join(claudeDir, current);
-    if (resolved === template) return target;
-    await backupAndReplace(target, template);
-    return target;
-  }
-  if (existingStat) {
-    await backupAndReplace(target, template);
-    return target;
-  }
-
-  await fs.symlink(template, target);
-  return target;
-}
-
-async function backupAndReplace(target, template) {
-  const stamp = new Date()
-    .toISOString()
-    .replace(/[-:]/g, "")
-    .replace(/\..*/, "")
-    .replace("T", "-");
-  const backup = `${target}.bak.${stamp}`;
-  await fs.rename(target, backup);
-  await fs.symlink(template, target);
-}
-