okstra 0.36.2 → 0.38.0

package/src/migrate.mjs

@@ -0,0 +1,163 @@
+import { spawn } from "node:child_process";
+import { buildPythonpath, resolvePaths } from "./paths.mjs";
+import { LEGACY_OKSTRA_DIR, OKSTRA_DIR } from "./okstra-dirs.mjs";
+
+const USAGE = `okstra migrate — move project artifacts from ${LEGACY_OKSTRA_DIR}/ to ${OKSTRA_DIR}/
+
+Run this once per project that was set up before v0.37. The migrator moves
+the okstra-managed directory tree, rewrites the import line in your
+project's CLAUDE.md, updates .gitignore, and refreshes okstra-home
+registries (~/.okstra/{recent,active}.jsonl, ~/.okstra/worktrees/registry.json)
+so the existing run history keeps resolving to the new path.
+
+Usage:
+  okstra migrate                Dry-run by default. Prints the plan as JSON.
+  okstra migrate --apply        Execute the move and ancillary updates.
+  okstra migrate --cwd <dir>    Search starting point (default: cwd).
+  okstra migrate --quiet        Suppress stdout on success; exit code reports.
+  okstra migrate --json         Force JSON output (default for both modes).
+
+Exit codes:
+  0   plan prepared (dry-run) or migration applied successfully
+  1   pre-condition rejected (e.g. ${OKSTRA_DIR}/ already exists, or no
+      ${LEGACY_OKSTRA_DIR}/ to migrate); reason printed on stderr
+  2   internal error (python invocation failed, etc.)
+
+The command is idempotent in spirit: re-running after a successful apply
+exits 1 with "nothing to migrate". Safe to wire into CI as a one-shot
+post-upgrade step.
+`;
+
+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 = { cwd: process.cwd(), apply: false, quiet: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--apply") opts.apply = true;
+    else 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 paths = await resolvePaths();
+
+  // We resolve project root via the python resolver — the same one used by
+  // every other okstra command — to keep "what project this is" consistent
+  // across CLI surfaces. The resolver knows three lookup strategies; the
+  // migrator only needs whichever ancestor it returns.
+  const py = await runProcess(
+    "python3",
+    [
+      "-c",
+      [
+        "import json, sys",
+        "from pathlib import Path",
+        "from okstra_project.resolver import resolve_project_root, ResolverError",
+        "from okstra_ctl.migrate import (",
+        "    prepare_migration_plan, apply_migration_plan, MigrationRefused,",
+        ")",
+        "cwd, apply = sys.argv[1], sys.argv[2] == 'apply'",
+        "try:",
+        "    # Resolver requires .okstra/project.json by default; for migrate",
+        "    # we fall back to the cwd directly because the legacy layout has",
+        "    # no .okstra/project.json yet.",
+        "    try:",
+        "        pr = resolve_project_root(explicit_root='', cwd=cwd)",
+        "    except ResolverError:",
+        "        pr = Path(cwd).resolve()",
+        "    plan = prepare_migration_plan(pr)",
+        "    if apply:",
+        "        result = apply_migration_plan(plan, dry_run=False)",
+        "    else:",
+        "        result = apply_migration_plan(plan, dry_run=True)",
+        "    print('OK')",
+        "    print(json.dumps({'plan': plan.to_dict(), 'result': result.to_dict()}, ensure_ascii=False))",
+        "except MigrationRefused as e:",
+        "    print('REFUSED')",
+        "    print(str(e))",
+        "    sys.exit(1)",
+      ].join("\n"),
+      opts.cwd,
+      opts.apply ? "apply" : "dry",
+    ],
+    { PYTHONPATH: buildPythonpath(paths) },
+  );
+
+  if (py.code === 1) {
+    // Refused — pre-condition fail. Stderr message already on second line.
+    const reason = py.stdout.split("\n").slice(1).join("\n").trim() || py.stderr.trim();
+    if (!opts.quiet) process.stderr.write(`migrate refused: ${reason}\n`);
+    return 1;
+  }
+  if (py.code !== 0) {
+    process.stderr.write(`error: python invocation failed: ${py.stderr.trim() || py.stdout.trim()}\n`);
+    return 2;
+  }
+
+  const lines = py.stdout.split("\n");
+  if (lines[0]?.trim() !== "OK") {
+    process.stderr.write(`error: unexpected python output: ${py.stdout}\n`);
+    return 2;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(lines.slice(1).join("\n"));
+  } catch (err) {
+    process.stderr.write(`error: failed to parse python output: ${err.message}\n`);
+    return 2;
+  }
+
+  emit(opts, {
+    ok: true,
+    mode: opts.apply ? "apply" : "dry-run",
+    ...payload,
+  });
+  if (!opts.apply && !opts.quiet) {
+    process.stderr.write(
+      "\nNo changes written. Re-run with --apply to perform the migration.\n",
+    );
+  }
+  return 0;
+}

package/src/okstra-dirs.mjs

@@ -0,0 +1,37 @@
+// Single source of truth for the okstra-relative project directory name.
+//
+// okstra 가 한 프로젝트 안에 만드는 모든 산출물은 `<PROJECT_ROOT>/<OKSTRA_DIR>/`
+// 한 곳 아래에 모인다. 이 모듈은 그 이름과 자주 쓰이는 path 조합을 한 곳에서
+// export 한다. Python 쪽의 `okstra_project/dirs.py` 와 값이 정확히 일치해야
+// 한다 (두 언어를 함께 운영하는 마이그레이션 명령이 같은 path 를 가리켜야
+// 하므로). 디렉토리 이름을 바꾸려면 두 파일의 한 줄씩만 수정한다.
+//
+// 의존성은 `node:path` 만 — `src/install.mjs` / `src/setup.mjs` 등 무거운
+// 모듈에서 import 할 때 순환 위험을 피한다.
+
+import { join } from "node:path";
+
+export const OKSTRA_DIR = ".okstra";
+// Pre-v0.37 layout. `okstra migrate` reads this to find unmigrated projects.
+// 코드 path 빌드에는 절대 사용 금지 — `OKSTRA_DIR` 만. 오로지 migration
+// 탐지/안내 메시지 용도.
+export const LEGACY_OKSTRA_DIR = ".project-docs/okstra";
+export const CLAUDE_MD_IMPORT_LINE = `@${OKSTRA_DIR}/CLAUDE.md`;
+export const LEGACY_CLAUDE_MD_IMPORT_LINE = `@${LEGACY_OKSTRA_DIR}/CLAUDE.md`;
+
+export function okstraRoot(projectRoot) {
+  return join(projectRoot, OKSTRA_DIR);
+}
+
+export function projectJsonPath(projectRoot) {
+  return join(okstraRoot(projectRoot), "project.json");
+}
+
+export function claudeMdSymlinkPath(projectRoot) {
+  return join(okstraRoot(projectRoot), "CLAUDE.md");
+}
+
+export function claudeMdSymlinkRelative() {
+  // setup.mjs 의 기존 `CLAUDE_MD_SYMLINK_REL` 와 동일한 project-relative 값.
+  return join(OKSTRA_DIR, "CLAUDE.md");
+}

package/src/paths.mjs

@@ -68,6 +68,23 @@ export async function resolvePaths() {
   };
 }
 
+// Compose the PYTHONPATH spawned python3 subprocesses should see.
+//
+// Precedence (first wins):
+//   1. process.env.PYTHONPATH (user override — e.g. in-repo `PYTHONPATH=scripts`
+//      for dev work without re-running `okstra install`).
+//   2. The installed user-runtime path (~/.okstra/lib/python).
+//
+// This is a colon-joined string suitable for direct assignment into the child
+// process env. Empty segments are dropped so a missing env var does not produce
+// a leading ':' (which Python treats as 'current directory').
+export function buildPythonpath(paths) {
+  const fragments = [process.env.PYTHONPATH, paths.pythonpath].filter(
+    (s) => typeof s === "string" && s.length > 0,
+  );
+  return fragments.join(":");
+}
+
 async function readSimpleFile(path) {
   try {
     const { readFile } = await import("node:fs/promises");

package/src/setup.mjs

@@ -4,10 +4,14 @@ import { createInterface } from "node:readline";
 import { homedir } from "node:os";
 import { join, resolve as resolvePath } from "node:path";
 import { resolvePaths } from "./paths.mjs";
+import {
+  CLAUDE_MD_IMPORT_LINE as DIRS_CLAUDE_MD_IMPORT_LINE,
+  claudeMdSymlinkRelative,
+} from "./okstra-dirs.mjs";
 
 const USAGE = `okstra setup — register the current project with okstra
 
-Writes <PROJECT_ROOT>/.project-docs/okstra/project.json. This is the
+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.
@@ -298,7 +302,7 @@ export async function run(args) {
     claudeMd = await ensureProjectClaudeMd(projectRoot);
   } catch (err) {
     process.stderr.write(
-      `warning: failed to wire <PROJECT>/CLAUDE.md @ .project-docs/okstra/CLAUDE.md import — ` +
+      `warning: failed to wire <PROJECT>/CLAUDE.md @ .okstra/CLAUDE.md import — ` +
         `Claude Code sessions in this project will not auto-load okstra guidance. (${err.message})\n`,
     );
   }
@@ -378,8 +382,8 @@ async function backupAndReplace(target, template) {
 }
 
 const CLAUDE_MD_TEMPLATE_PATH = join(homedir(), ".okstra", "templates", "okstra.CLAUDE.md");
-const CLAUDE_MD_SYMLINK_REL = join(".project-docs", "okstra", "CLAUDE.md");
-const CLAUDE_MD_IMPORT_LINE = "@.project-docs/okstra/CLAUDE.md";
+const CLAUDE_MD_SYMLINK_REL = claudeMdSymlinkRelative();
+const CLAUDE_MD_IMPORT_LINE = DIRS_CLAUDE_MD_IMPORT_LINE;
 const CLAUDE_MD_MARKER_BEGIN = "<!-- okstra:claude-md:begin (managed by okstra setup — do not edit) -->";
 const CLAUDE_MD_MARKER_END = "<!-- okstra:claude-md:end -->";
 

package/src/uninstall.mjs

@@ -64,7 +64,7 @@ Usage:
                                 active.jsonl, projects/, archive/,
                                 state.json, .locks/
                                 Per-project artifacts created by 'okstra setup'
-                                (<PROJECT>/.project-docs/okstra/CLAUDE.md symlink,
+                                (<PROJECT>/.okstra/CLAUDE.md symlink,
                                 <PROJECT>/CLAUDE.md import block,
                                 <PROJECT>/AGENTS.md symlink,
                                 <PROJECT>/.claude/settings.local.json symlink)
@@ -200,8 +200,8 @@ export async function runUninstall(args) {
 
   await removePath(join(paths.home, "templates", "settings.local.json"), opts);
   await removePath(join(paths.home, "templates", "okstra.CLAUDE.md"), opts);
-  // Per-project artifacts (<PROJECT>/.project-docs/okstra/CLAUDE.md symlink,
-  // <PROJECT>/AGENTS.md symlink, and the @.project-docs/okstra/CLAUDE.md import
+  // Per-project artifacts (<PROJECT>/.okstra/CLAUDE.md symlink,
+  // <PROJECT>/AGENTS.md symlink, and the @.okstra/CLAUDE.md import
   // block inside <PROJECT>/CLAUDE.md) are NOT removed here — uninstall is
   // machine-level and does not know which projects opted in. Symlinks will
   // dangle until the user removes them manually or re-runs okstra install +