okstra 0.1.0

package/src/paths.mjs

@@ -0,0 +1,132 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getPackageRoot, getPackageVersion } from "./version.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 packages/okstra/runtime 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 resolvePaths() {
+  const home = 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 || "",
+  };
+}
+
+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);
+    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/uninstall.mjs

@@ -0,0 +1,122 @@
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { resolvePaths } from "./paths.mjs";
+
+const BIN_ENTRYPOINTS = [
+  "okstra.sh",
+  "okstra-codex-exec.sh",
+  "okstra-gemini-exec.sh",
+  "okstra-central.sh",
+  "okstra-token-usage.py",
+  "okstra-error-log.py",
+];
+
+const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra
+
+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)
+                                Requires -y or an interactive confirmation
+  okstra uninstall --dry-run    Print the plan without touching disk
+  okstra uninstall -y           Skip confirmation prompt for --purge
+`;
+
+async function pathExists(p) {
+  try {
+    await fs.lstat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function removePath(p, opts) {
+  const { dryRun = false, quiet = false } = opts ?? {};
+  if (!(await pathExists(p))) {
+    if (!quiet) process.stdout.write(`  not present: ${p}\n`);
+    return false;
+  }
+  if (dryRun) {
+    process.stdout.write(`[dry-run] rm ${p}\n`);
+    return true;
+  }
+  await fs.rm(p, { recursive: true, force: true });
+  if (!quiet) process.stdout.write(`  removed: ${p}\n`);
+  return true;
+}
+
+async function promptConfirm(question) {
+  if (!process.stdin.isTTY) return false;
+  process.stdout.write(`${question} [y/N] `);
+  return await new Promise((resolveP) => {
+    process.stdin.setEncoding("utf8");
+    process.stdin.once("data", (chunk) => {
+      const answer = chunk.toString().trim().toLowerCase();
+      resolveP(answer === "y" || answer === "yes");
+    });
+  });
+}
+
+export async function runUninstall(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const opts = {
+    dryRun: args.includes("--dry-run"),
+    quiet: args.includes("-q") || args.includes("--quiet"),
+    purge: args.includes("--purge"),
+    yes: args.includes("-y") || args.includes("--yes"),
+  };
+  const paths = await resolvePaths();
+
+  if (!(await pathExists(paths.home))) {
+    if (!opts.quiet) process.stdout.write(`okstra not installed (no ${paths.home})\n`);
+    return 0;
+  }
+
+  if (opts.purge) {
+    if (!opts.yes && !opts.dryRun) {
+      const ok = await promptConfirm(`purge entire ${paths.home}? user data will be lost.`);
+      if (!ok) {
+        process.stdout.write("aborted.\n");
+        return 1;
+      }
+    }
+    if (!opts.quiet) process.stdout.write(`purging ${paths.home}\n`);
+    await removePath(paths.home, opts);
+    return 0;
+  }
+
+  if (!opts.quiet) {
+    process.stdout.write(`uninstalling okstra runtime\n`);
+    process.stdout.write(`  home: ${paths.home}\n`);
+  }
+  await removePath(paths.pythonpath, 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 */
+      }
+    }
+  }
+  await removePath(join(paths.home, "version"), opts);
+  await removePath(join(paths.home, "dev-link"), opts);
+
+  if (!opts.quiet) {
+    process.stdout.write("done. user data preserved (recent.jsonl, projects/, archive/, ...).\n");
+  }
+  return 0;
+}

package/src/version.mjs

@@ -0,0 +1,20 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(here, "..", "package.json");
+
+let cachedVersion = null;
+
+export async function getPackageVersion() {
+  if (cachedVersion) return cachedVersion;
+  const raw = await readFile(packageJsonPath, "utf8");
+  const { version } = JSON.parse(raw);
+  cachedVersion = version;
+  return version;
+}
+
+export function getPackageRoot() {
+  return join(here, "..");
+}