okstra 0.3.0 → 0.5.0

package/src/check-project.mjs

@@ -0,0 +1,188 @@
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { resolvePaths } from "./paths.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
+                                    .project-docs/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 runProcess(cmd, args, env) {
+  return new Promise((resolve) => {
+    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) => resolve({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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;
+  }
+
+  const opts = parseArgs(args);
+  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"),
+      opts.cwd,
+    ],
+    { PYTHONPATH: paths.pythonpath },
+  );
+
+  if (probe.code !== 0) {
+    emit(opts, {
+      ok: false,
+      stage: "python",
+      reason: `python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`,
+    });
+    return 1;
+  }
+
+  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) {
+    emit(opts, {
+      ok: false,
+      stage: "resolve",
+      reason: resolverError,
+      cwd: opts.cwd,
+    });
+    return 2;
+  }
+
+  const projectRoot = tagOf("PROJECT_ROOT");
+  const projectJsonPath = tagOf("PROJECT_JSON");
+  if (!projectRoot || !projectJsonPath) {
+    emit(opts, {
+      ok: false,
+      stage: "parse",
+      reason: "could not parse python output",
+      raw: probe.stdout,
+    });
+    return 1;
+  }
+
+  if (!(await fileExists(projectJsonPath))) {
+    emit(opts, {
+      ok: false,
+      stage: "project_json_missing",
+      reason: `${projectJsonPath} not found — run /okstra-setup in this project first`,
+      projectRoot,
+      projectJsonPath,
+    });
+    return 1;
+  }
+
+  let projectId = null;
+  try {
+    const data = JSON.parse(await fs.readFile(projectJsonPath, "utf8"));
+    projectId = typeof data?.projectId === "string" ? data.projectId : null;
+  } catch (err) {
+    emit(opts, {
+      ok: false,
+      stage: "project_json_invalid",
+      reason: `failed to parse ${projectJsonPath}: ${err.message}`,
+      projectRoot,
+      projectJsonPath,
+    });
+    return 1;
+  }
+
+  if (!projectId) {
+    emit(opts, {
+      ok: false,
+      stage: "project_json_invalid",
+      reason: `${projectJsonPath} missing projectId field`,
+      projectRoot,
+      projectJsonPath,
+    });
+    return 1;
+  }
+
+  emit(opts, {
+    ok: true,
+    projectRoot,
+    projectJsonPath,
+    projectId,
+  });
+  return 0;
+}

package/src/doctor.mjs

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
-const REQUIRED_SKILLS = ["setup-okstra", "okstra-run"];
+const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
 
 const USAGE = `okstra doctor — diagnose the installed runtime
 

package/src/install.mjs

@@ -226,6 +226,13 @@ async function installLinkMode(repoPath, paths, opts) {
     process.stdout.write(`  dev-link stamp: ${repoAbs}\n`);
     process.stdout.write(`  version stamp: ${paths.package}\n`);
     process.stdout.write("done.\n");
+    process.stdout.write(
+      "\nNext step: register the current project.\n" +
+        "  cd <your project> && npx -y okstra@latest setup --project-id <id>\n" +
+        "  (or run /okstra-setup inside a Claude Code session)\n" +
+        "\nTip: to use a bare 'okstra' command instead of npx, run:\n" +
+        "  npm i -g okstra\n",
+    );
   }
   return 0;
 }
@@ -401,6 +408,13 @@ export async function runInstall(args) {
   if (!opts.quiet) {
     process.stdout.write(`  version stamp: ${paths.package}\n`);
     process.stdout.write("done.\n");
+    process.stdout.write(
+      "\nNext step: register the current project.\n" +
+        "  cd <your project> && npx -y okstra@latest setup --project-id <id>\n" +
+        "  (or run /okstra-setup inside a Claude Code session)\n" +
+        "\nTip: to use a bare 'okstra' command instead of npx, run:\n" +
+        "  npm i -g okstra\n",
+    );
   }
   return 0;
 }
@@ -430,8 +444,8 @@ export async function runEnsureInstalled(args) {
   }
   if (!(await dirExists(paths.pythonpath))) reasons.push(`missing ${paths.pythonpath}`);
   if (!(await dirExists(paths.agents))) reasons.push(`missing agents dir ${paths.agents}`);
-  if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "setup-okstra", "SKILL.md")))) {
-    reasons.push(`missing ${CLAUDE_SKILLS_DIR}/setup-okstra/SKILL.md`);
+  if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
+    reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
   }
 
   if (reasons.length === 0) {

package/src/setup.mjs

@@ -0,0 +1,243 @@
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra setup — register the current project with okstra
+
+Writes <PROJECT_ROOT>/.project-docs/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 runProcess(cmd, args, env) {
+  return new Promise((resolve) => {
+    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) => resolve({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+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;
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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: paths.pythonpath },
+  );
+  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: paths.pythonpath },
+  );
+  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) {
+    process.stderr.write(`error: could not resolve PROJECT_ROOT: ${err.message}\n`);
+    return err.code === "RESOLVER" ? 2 : 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, fontsninja): ");
+    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;
+  }
+
+  process.stdout.write(JSON.stringify({ ok: true, ...result, projectJsonPath }, null, 2) + "\n");
+  return 0;
+}

package/src/uninstall.mjs

@@ -13,7 +13,7 @@ const BIN_ENTRYPOINTS = [
 ];
 
 const FALLBACK_SKILL_NAMES = [
-  "setup-okstra",
+  "okstra-setup",
   "okstra-run",
   "okstra-status",
   "okstra-history",
@@ -103,7 +103,7 @@ export async function runUninstall(args) {
   if (opts.purge) {
     if (!opts.yes && !opts.dryRun) {
       const ok = await promptConfirm(
-        `purge entire ${paths.home} AND ~/.claude/skills/{okstra-*,setup-okstra}? user data will be lost.`,
+        `purge entire ${paths.home} AND ~/.claude/skills/{okstra-*,okstra-setup}? user data will be lost.`,
       );
       if (!ok) {
         process.stdout.write("aborted.\n");