okstra 0.2.0 → 0.4.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

@@ -1,8 +1,12 @@
 import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
+const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
+
 const USAGE = `okstra doctor — diagnose the installed runtime
 
 Usage:
@@ -15,6 +19,7 @@ Checks:
   - okstra_ctl module importable
   - bash entrypoints present and executable in $HOME/.okstra/bin
   - agents/ directory exists inside the okstra package
+  - canonical skills present at $HOME/.claude/skills/<name>/SKILL.md
   - version stamp matches package version
 `;
 
@@ -104,6 +109,16 @@ export async function run(args) {
     await check("bin: okstra-codex-exec.sh", () => checkBashEntry(paths.bin, "okstra-codex-exec.sh")),
     await check("bin: okstra-gemini-exec.sh", () => checkBashEntry(paths.bin, "okstra-gemini-exec.sh")),
     await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
+    ...(await Promise.all(
+      REQUIRED_SKILLS.map((name) =>
+        check(`skill: ${name}`, async () => {
+          const p = join(CLAUDE_SKILLS_DIR, name, "SKILL.md");
+          return (await pathExists(p))
+            ? { ok: true, detail: p }
+            : { ok: false, detail: `not found: ${p}` };
+        }),
+      ),
+    )),
     await check("version stamp", async () =>
       paths.version === paths.package
         ? { ok: true, detail: paths.version }

package/src/install.mjs

@@ -1,9 +1,13 @@
 import { promises as fs } from "node:fs";
 import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { join, relative, resolve as resolveAbs } from "node:path";
 import { getPackageRoot } from "./version.mjs";
 import { resolvePaths } from "./paths.mjs";
 
+const SKILLS_MANIFEST_REL = "installed-skills.json";
+const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+
 const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "lib"];
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
@@ -25,13 +29,16 @@ Usage:
   okstra install --refresh    Re-copy even files that match by hash
 
 Effect (copy mode):
-  ${"$HOME"}/.okstra/lib/python   <- packages/okstra/runtime/python
-  ${"$HOME"}/.okstra/bin           <- packages/okstra/runtime/bin
+  ${"$HOME"}/.okstra/lib/python   <- runtime/python
+  ${"$HOME"}/.okstra/bin           <- runtime/bin
+  ${"$HOME"}/.claude/skills/<name> <- runtime/skills/<name>   (per skill)
+  ${"$HOME"}/.okstra/installed-skills.json   <- manifest of installed skills
   ${"$HOME"}/.okstra/version       <- installed package version stamp
 
 Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
+  ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name>   (symlink dir)
   ${"$HOME"}/.okstra/dev-link         <- <repo> path stamp
   ${"$HOME"}/.okstra/version          <- installed package version stamp
 
@@ -208,6 +215,9 @@ async function installLinkMode(repoPath, paths, opts) {
     if (!quiet) process.stdout.write(`  bin/${name}: ${action}\n`);
   }
 
+  const skillResult = await installSkillsLink(repoAbs, { dryRun, quiet });
+  await writeSkillsManifest(paths.home, skillResult.installed, { dryRun });
+
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
@@ -229,6 +239,79 @@ async function fileExists(p) {
   }
 }
 
+async function listSkillDirs(skillsRoot) {
+  try {
+    const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+async function writeSkillsManifest(home, names, opts) {
+  const { dryRun = false } = opts ?? {};
+  const data = {
+    version: 1,
+    installedAt: new Date().toISOString(),
+    skills: Array.from(new Set(names)).sort(),
+  };
+  if (dryRun) {
+    process.stdout.write(`[dry-run] write skills manifest: ${data.skills.length} entries\n`);
+    return;
+  }
+  await writeFileAtomic(
+    join(home, SKILLS_MANIFEST_REL),
+    JSON.stringify(data, null, 2) + "\n",
+    0o644,
+  );
+}
+
+async function installSkillsCopy(runtimeRoot, opts) {
+  const { refresh, dryRun, quiet } = opts;
+  const srcRoot = join(runtimeRoot, "skills");
+  const names = await listSkillDirs(srcRoot);
+  if (names.length === 0) {
+    if (!quiet) process.stdout.write("  skills: runtime/skills empty — skipped\n");
+    return { installed: [] };
+  }
+  let copied = 0;
+  let skipped = 0;
+  for (const name of names) {
+    const r = await copyTreeIfChanged(
+      join(srcRoot, name),
+      join(CLAUDE_SKILLS_DIR, name),
+      { refresh, dryRun, mode: 0o644 },
+    );
+    copied += r.copied;
+    skipped += r.skipped;
+  }
+  if (!quiet) {
+    process.stdout.write(
+      `  skills: copied=${copied} skipped=${skipped} -> ${CLAUDE_SKILLS_DIR}/ (${names.length} skills)\n`,
+    );
+  }
+  return { installed: names };
+}
+
+async function installSkillsLink(repoAbs, opts) {
+  const { dryRun, quiet } = opts;
+  const srcRoot = join(repoAbs, "skills");
+  const names = await listSkillDirs(srcRoot);
+  if (names.length === 0) {
+    if (!quiet) process.stdout.write("  skills: <repo>/skills missing — skipped\n");
+    return { installed: [] };
+  }
+  if (!dryRun) await fs.mkdir(CLAUDE_SKILLS_DIR, { recursive: true });
+  for (const name of names) {
+    const src = join(srcRoot, name);
+    const dst = join(CLAUDE_SKILLS_DIR, name);
+    const action = await ensureSymlink(src, dst, { dryRun });
+    if (!quiet) process.stdout.write(`  skills/${name}: ${action}\n`);
+  }
+  return { installed: names };
+}
+
 function parseInstallArgs(args) {
   const result = {
     dryRun: false,
@@ -309,6 +392,9 @@ export async function runInstall(args) {
     );
   }
 
+  const skillResult = await installSkillsCopy(runtimeRoot, opts);
+  await writeSkillsManifest(paths.home, skillResult.installed, { dryRun: opts.dryRun });
+
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
   }
@@ -344,6 +430,9 @@ 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, "okstra-setup", "SKILL.md")))) {
+    reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
+  }
 
   if (reasons.length === 0) {
     if (!quiet) process.stdout.write(`okstra runtime OK (package ${paths.package})\n`);

package/src/paths.mjs

@@ -14,8 +14,8 @@ Usage:
 Fields:
   agents       Absolute path to agents/. Default: <workspace>/agents.
   workspace    Directory containing prompts/, templates/, validators/,
-               agents/. Equals packages/okstra/runtime in copy mode,
-               or the dev-link repo path in dev mode.
+               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

package/src/uninstall.mjs

@@ -1,4 +1,5 @@
 import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
@@ -11,13 +12,35 @@ const BIN_ENTRYPOINTS = [
   "okstra-error-log.py",
 ];
 
-const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra
+const FALLBACK_SKILL_NAMES = [
+  "okstra-setup",
+  "okstra-run",
+  "okstra-status",
+  "okstra-history",
+  "okstra-schedule",
+  "okstra-context-loader",
+  "okstra-team-contract",
+  "okstra-convergence",
+  "okstra-report-writer",
+  "okstra-report-finder",
+  "okstra-time-summary",
+];
+
+const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+const SKILLS_MANIFEST_REL = "installed-skills.json";
+
+const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra and ~/.claude/skills
 
 Usage:
-  okstra uninstall              Remove lib/, bin/{known entries}, version, dev-link
-                                Preserves user data: recent.jsonl, active.jsonl,
-                                projects/, archive/, state.json, .locks/
-  okstra uninstall --purge      Remove the entire ~/.okstra directory (DESTRUCTIVE)
+  okstra uninstall              Remove ~/.okstra/{lib, bin/<known>, version,
+                                dev-link, installed-skills.json} AND
+                                ~/.claude/skills/<name> for every entry in
+                                the install manifest (fallback: hard-coded
+                                okstra-* names). Preserves user data:
+                                recent.jsonl, active.jsonl, projects/,
+                                archive/, state.json, .locks/
+  okstra uninstall --purge      Remove the entire ~/.okstra directory AND
+                                ~/.claude/skills/<okstra-*> (DESTRUCTIVE).
                                 Requires -y or an interactive confirmation
   okstra uninstall --dry-run    Print the plan without touching disk
   okstra uninstall -y           Skip confirmation prompt for --purge
@@ -79,7 +102,9 @@ export async function runUninstall(args) {
 
   if (opts.purge) {
     if (!opts.yes && !opts.dryRun) {
-      const ok = await promptConfirm(`purge entire ${paths.home}? user data will be lost.`);
+      const ok = await promptConfirm(
+        `purge entire ${paths.home} AND ~/.claude/skills/{okstra-*,okstra-setup}? user data will be lost.`,
+      );
       if (!ok) {
         process.stdout.write("aborted.\n");
         return 1;
@@ -87,6 +112,10 @@ export async function runUninstall(args) {
     }
     if (!opts.quiet) process.stdout.write(`purging ${paths.home}\n`);
     await removePath(paths.home, opts);
+    // Skills live outside ~/.okstra — purge those too with the fallback list.
+    for (const name of FALLBACK_SKILL_NAMES) {
+      await removePath(join(CLAUDE_SKILLS_DIR, name), opts);
+    }
     return 0;
   }
 
@@ -112,6 +141,19 @@ export async function runUninstall(args) {
       }
     }
   }
+
+  // Remove the skills we own. Manifest is authoritative; fall back to the
+  // hard-coded okstra-* names if it is missing (e.g. an install from an old
+  // version that did not write the manifest).
+  const skillNames = await readSkillsManifest(paths.home);
+  if (!opts.quiet) {
+    process.stdout.write(`  skills: removing ${skillNames.length} entries from ${CLAUDE_SKILLS_DIR}\n`);
+  }
+  for (const name of skillNames) {
+    await removePath(join(CLAUDE_SKILLS_DIR, name), opts);
+  }
+  await removePath(join(paths.home, SKILLS_MANIFEST_REL), opts);
+
   await removePath(join(paths.home, "version"), opts);
   await removePath(join(paths.home, "dev-link"), opts);
 
@@ -120,3 +162,14 @@ export async function runUninstall(args) {
   }
   return 0;
 }
+
+async function readSkillsManifest(home) {
+  try {
+    const raw = await fs.readFile(join(home, SKILLS_MANIFEST_REL), "utf8");
+    const data = JSON.parse(raw);
+    if (Array.isArray(data?.skills)) return data.skills;
+  } catch {
+    /* fall through */
+  }
+  return FALLBACK_SKILL_NAMES;
+}