okstra 0.96.1 → 0.97.1

package/src/{paths.mjs → commands/lifecycle/paths.mjs}

@@ -1,7 +1,4 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { existsSync } from "node:fs";
-import { getPackageRoot, getPackageVersion } from "./version.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
 
 const USAGE = `okstra paths — print runtime paths
 
@@ -52,62 +49,6 @@ const SHELL_EXPORTS = [
   ["OKSTRA_HOME", "home"],
 ];
 
-export async function resolvePaths() {
-  const home = process.env.OKSTRA_HOME?.trim() || join(homedir(), ".okstra");
-  const pkgRoot = getPackageRoot();
-  const devLink = await readSimpleFile(join(home, "dev-link"));
-  const runtimeRoot = devLink || join(pkgRoot, "runtime");
-  return {
-    agents: join(runtimeRoot, "agents"),
-    workspace: runtimeRoot,
-    pythonpath: join(home, "lib", "python"),
-    bin: join(home, "bin"),
-    home,
-    package: await getPackageVersion(),
-    version: await readSimpleFile(join(home, "version")),
-    "dev-link": devLink || "",
-  };
-}
-
-function workspacePythonpath(paths) {
-  const candidates = [
-    join(paths.workspace, "python"),
-    join(paths.workspace, "scripts"),
-  ];
-  return candidates.find((candidate) => existsSync(candidate)) || "";
-}
-
-// 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 package/dev-link workspace runtime selected by `okstra paths`.
-//   3. 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,
-    workspacePythonpath(paths),
-    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");
-    return (await readFile(path, "utf8")).trim();
-  } catch {
-    return "";
-  }
-}
-
 export async function run(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);

package/src/{setup.mjs → commands/lifecycle/setup.mjs}

@@ -2,8 +2,8 @@ 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 { resolvePaths } from "./paths.mjs";
-import { fileExists, runProcess } from "./_proc.mjs";
+import { buildPythonpath, resolvePaths } from "../../lib/paths.mjs";
+import { fileExists, runProcess } from "../../lib/proc.mjs";
 
 const USAGE = `okstra setup — register the current project with okstra
 
@@ -95,7 +95,7 @@ async function resolveProjectRoot(paths, explicit) {
       explicit || "",
       process.cwd(),
     ],
-    { PYTHONPATH: paths.pythonpath },
+    { PYTHONPATH: buildPythonpath(paths) },
   );
   if (probe.code !== 0) {
     throw new Error(`python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`);
@@ -136,7 +136,7 @@ async function upsert(paths, projectRoot, projectId) {
       projectRoot,
       projectId,
     ],
-    { PYTHONPATH: paths.pythonpath },
+    { PYTHONPATH: buildPythonpath(paths) },
   );
   if (probe.code !== 0) {
     throw new Error(`python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`);

package/src/{uninstall.mjs → commands/lifecycle/uninstall.mjs}

@@ -1,26 +1,11 @@
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { resolvePaths } from "./paths.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
 import {
   RUNTIMES_MANIFEST_REL,
   runtimeManifestIncludesClaudeAssets,
-} from "./runtime-manifest.mjs";
-
-const BIN_ENTRYPOINTS = [
-  "okstra.sh",
-  "okstra-codex-exec.sh",
-  "okstra-claude-exec.sh",
-  "okstra-antigravity-exec.sh",
-  "okstra-trace-cleanup.sh",
-  "okstra-team-reconcile.sh",
-  "okstra-central.sh",
-  "okstra-token-usage.py",
-  "okstra-error-log.py",
-  "okstra-render-report-views.py",
-  "okstra-render-final-report.py",
-  "okstra-wrapper-status.py",
-];
+} from "../../lib/runtime-manifest.mjs";
 
 const FALLBACK_SKILL_NAMES = [
   "okstra",
@@ -71,7 +56,7 @@ const USAGE = `okstra uninstall — remove installed runtime and okstra skills
 
 Usage:
   okstra uninstall              Remove ~/.okstra/{lib (python + validators),
-                                bin/<known>, schemas, templates, version,
+                                bin, schemas, templates, version,
                                 dev-link, installed-runtimes.json,
                                 installed-skills.json, installed-agents.json} AND
                                 every skill target recorded in
@@ -184,21 +169,24 @@ export async function runUninstall(args) {
   // template's section schema (observed: a pre-renumber `## 4.5 Stage Map`
   // validator outliving every later install).
   await removePath(join(paths.home, "lib", "validators"), opts);
-  for (const name of BIN_ENTRYPOINTS) {
-    await removePath(join(paths.bin, name), opts);
-  }
-  // Clean now-empty parents (best-effort).
-  for (const dir of [join(paths.home, "lib"), paths.bin]) {
-    if (await pathExists(dir)) {
-      try {
-        const entries = await fs.readdir(dir);
-        if (entries.length === 0) {
-          if (!opts.dryRun) await fs.rmdir(dir);
-          if (!opts.quiet) process.stdout.write(`  removed empty: ${dir}\n`);
-        }
-      } catch {
-        /* ignore */
+  // bin/ tree — install copies the whole runtime/bin payload (entrypoints +
+  // bin/lib helpers) in copy mode, so a per-name list always drifts behind
+  // additions (e.g. okstra-inject-report-index.py, okstra-spawn-followups.sh).
+  // Remove the directory wholesale, matching how install populates it; nothing
+  // under ~/.okstra/bin is user data.
+  await removePath(paths.bin, opts);
+  // Clean now-empty lib parent (best-effort) — pythonpath + validators were the
+  // only okstra-owned children.
+  const libDir = join(paths.home, "lib");
+  if (await pathExists(libDir)) {
+    try {
+      const entries = await fs.readdir(libDir);
+      if (entries.length === 0) {
+        if (!opts.dryRun) await fs.rmdir(libDir);
+        if (!opts.quiet) process.stdout.write(`  removed empty: ${libDir}\n`);
       }
+    } catch {
+      /* ignore */
     }
   }
 

package/src/{memory.mjs → commands/memory/memory.mjs}

@@ -1,5 +1,6 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { randomBytes } from "node:crypto";
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
@@ -227,12 +228,15 @@ function buildEntry(opts, content, now) {
   const title = inferTitle(content, opts.title, opts.file);
   const compact = now.toISOString().replace(/\D/g, "").slice(0, 17);
   const slug = slugify(title);
-  const id = `mem_${compact}_${slug}`;
+  // Random suffix disambiguates two same-title adds within one millisecond,
+  // which would otherwise collide on both id and on-disk path (silent overwrite).
+  const nonce = randomBytes(3).toString("hex");
+  const id = `mem_${compact}_${slug}_${nonce}`;
   const relativePath = join(
     "entries",
     String(now.getUTCFullYear()),
     String(now.getUTCMonth() + 1).padStart(2, "0"),
-    `${now.toISOString().replace(/[:.]/g, "")}-${slug}.md`,
+    `${now.toISOString().replace(/[:.]/g, "")}-${slug}-${nonce}.md`,
   );
   return {
     id,
@@ -298,10 +302,19 @@ async function readIndex() {
     if (err.code === "ENOENT") return [];
     throw err;
   }
-  return text
-    .split(/\r?\n/)
-    .filter(Boolean)
-    .map((line) => JSON.parse(line));
+  // Skip lines that fail to parse so one truncated row (e.g. an interrupted
+  // appendIndex) cannot make the whole Memory Book unreadable; other JSONL
+  // readers in okstra tolerate corruption the same way.
+  const entries = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (!line) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // Drop the unparseable row; intact entries remain visible.
+    }
+  }
+  return entries;
 }
 
 async function writeIndex(entries) {
@@ -447,7 +460,19 @@ async function opArchive(args) {
   const updated = entries.map((candidate) =>
     candidate.id === entry.id ? archivedEntry : candidate,
   );
-  await writeIndex(updated);
+  try {
+    await writeIndex(updated);
+  } catch (err) {
+    // Index rewrite failed after the file was already moved — move it back so
+    // the index keeps pointing at the file's real location (mirrors opAdd).
+    if (archivedEntry.path !== entry.path) {
+      await fs.rename(
+        join(memoryRoot(), archivedEntry.path),
+        join(memoryRoot(), entry.path),
+      );
+    }
+    throw err;
+  }
   if (json) emitJson({ ok: true, entry: archivedEntry });
   else process.stdout.write(`archived ${entry.id}\n`);
   return 0;

package/src/{inject-report-index.mjs → commands/report/inject-report-index.mjs}

@@ -1,4 +1,4 @@
-import { runInstalledScript } from "./_python-helper.mjs";
+import { runInstalledScript } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra inject-report-index — add the top-of-report Index + scroll anchors to a report
 

package/src/{render-final-report.mjs → commands/report/render-final-report.mjs}

@@ -1,4 +1,4 @@
-import { runInstalledScript } from "./_python-helper.mjs";
+import { runInstalledScript } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra render-final-report — render the markdown sibling of a final-report data.json
 

package/src/{render-views.mjs → commands/report/render-views.mjs}

@@ -1,4 +1,4 @@
-import { runInstalledScript } from "./_python-helper.mjs";
+import { runInstalledScript } from "../../lib/python-helper.mjs";
 
 const USAGE = `okstra render-views — render the self-contained HTML view of a final-report
 

package/src/lib/paths.mjs

@@ -0,0 +1,60 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { getPackageRoot, getPackageVersion } from "./version.mjs";
+
+export async function resolvePaths() {
+  const home = process.env.OKSTRA_HOME?.trim() || join(homedir(), ".okstra");
+  const pkgRoot = getPackageRoot();
+  const devLink = await readSimpleFile(join(home, "dev-link"));
+  const runtimeRoot = devLink || join(pkgRoot, "runtime");
+  return {
+    agents: join(runtimeRoot, "agents"),
+    workspace: runtimeRoot,
+    pythonpath: join(home, "lib", "python"),
+    bin: join(home, "bin"),
+    home,
+    package: await getPackageVersion(),
+    version: await readSimpleFile(join(home, "version")),
+    "dev-link": devLink || "",
+  };
+}
+
+function workspacePythonpath(paths) {
+  const candidates = [
+    join(paths.workspace, "python"),
+    join(paths.workspace, "scripts"),
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) || "";
+}
+
+// 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 package/dev-link workspace runtime selected by `okstra paths`.
+//   3. 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,
+    workspacePythonpath(paths),
+    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");
+    return (await readFile(path, "utf8")).trim();
+  } catch {
+    return "";
+  }
+}

package/src/{_python-helper.mjs → lib/python-helper.mjs}

@@ -10,7 +10,7 @@ function resolveInstalledScript(paths, scriptName) {
   // been installed (dev / CI).
   const installed = join(paths.bin, scriptName);
   if (existsSync(installed)) return installed;
-  const repoRoot = fileURLToPath(new URL("..", import.meta.url));
+  const repoRoot = fileURLToPath(new URL("../..", import.meta.url));
   const dev = resolvePath(repoRoot, "scripts", scriptName);
   return existsSync(dev) ? dev : null;
 }
@@ -60,12 +60,22 @@ export async function runPythonSnippet({ script, args = [], extraEnv = {} }) {
       stdio: ["ignore", "pipe", "pipe"],
       env: { ...process.env, PYTHONPATH: buildPythonpath(paths), ...extraEnv },
     });
-    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 }));
+    // Collect chunks and join once: repeated `s += chunk` is O(n^2) for the
+    // large rendered prompts some capture-mode callers stream through here.
+    const outChunks = [];
+    const errChunks = [];
+    child.stdout.on("data", (b) => outChunks.push(b));
+    child.stderr.on("data", (b) => errChunks.push(b));
+    child.on("error", (err) =>
+      resolve({ code: -1, stdout: Buffer.concat(outChunks).toString(), stderr: err.message }),
+    );
+    child.on("close", (code) =>
+      resolve({
+        code,
+        stdout: Buffer.concat(outChunks).toString(),
+        stderr: Buffer.concat(errChunks).toString(),
+      }),
+    );
   });
 }
 
@@ -76,14 +86,26 @@ export async function runPythonModule({ module, args = [], extraEnv = {}, stdio
       stdio: stdio === "capture" ? ["ignore", "pipe", "pipe"] : ["ignore", "inherit", "inherit"],
       env: { ...process.env, PYTHONPATH: buildPythonpath(paths), ...extraEnv },
     });
-    let stdout = "";
-    let stderr = "";
+    // Collect chunks and join once: repeated `s += chunk` is O(n^2) for the
+    // large rendered prompts some capture-mode callers stream through here.
+    const outChunks = [];
+    const errChunks = [];
     if (stdio === "capture") {
-      child.stdout.on("data", (b) => (stdout += b.toString()));
-      child.stderr.on("data", (b) => (stderr += b.toString()));
+      child.stdout.on("data", (b) => outChunks.push(b));
+      child.stderr.on("data", (b) => errChunks.push(b));
     }
-    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
-    child.on("close", (code) => resolve({ code, stdout, stderr }));
+    child.on("error", (err) =>
+      resolve({ code: -1, stdout: Buffer.concat(outChunks).toString(), stderr: err.message }),
+    );
+    // A signal-killed child reports code === null; normalize to a non-zero exit
+    // here so every consumer inherits correct failure semantics from one place.
+    child.on("close", (code) =>
+      resolve({
+        code: typeof code === "number" ? code : 1,
+        stdout: Buffer.concat(outChunks).toString(),
+        stderr: Buffer.concat(errChunks).toString(),
+      }),
+    );
   });
 }
 

package/src/{version.mjs → lib/version.mjs}

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
 const here = dirname(fileURLToPath(import.meta.url));
-const packageJsonPath = join(here, "..", "package.json");
+const packageJsonPath = join(here, "..", "..", "package.json");
 
 let cachedVersion = null;
 
@@ -16,5 +16,5 @@ export async function getPackageVersion() {
 }
 
 export function getPackageRoot() {
-  return join(here, "..");
+  return join(here, "..", "..");
 }