@okf-harness/cli 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,9 @@
 
 Command-line package for OKF Harness local workspaces. It provides the `okfh` command for initializing workspaces, registering sources, linting wiki content, searching and reading pages, generating graph reports, and installing Claude Code or Codex guidance.
 
-OKF Harness is an independent open-source project built on [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
+OKF Harness is an independent open-source project built on Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
+
+Most users install this package once, create one local workspace per knowledge domain, then ask Claude Code or Codex to maintain the workspace through `okfh --json`.
 
 Install:
 
@@ -17,4 +19,20 @@ Try without a global install:
 npx --package @okf-harness/cli okfh doctor --json
 ```
 
-For project overview, workflows, and security notes, see the [main repository README](https://github.com/pumblus/okf-harness#readme).
+Common commands:
+
+```bash
+okfh init "$HOME/Documents/OKF Harness/ai-research" --name "AI Research" --agents all --git --json
+okfh source add ~/Downloads/paper.pdf --workspace "$HOME/Documents/OKF Harness/ai-research" --json
+okfh ingest plan <source-id> --workspace "$HOME/Documents/OKF Harness/ai-research" --json
+okfh search "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --json
+okfh read topics/llm-wiki --workspace "$HOME/Documents/OKF Harness/ai-research" --json
+okfh lint --workspace "$HOME/Documents/OKF Harness/ai-research" --json
+okfh graph --workspace "$HOME/Documents/OKF Harness/ai-research" --json
+```
+
+On Windows PowerShell, use `$env:USERPROFILE\Documents\OKF Harness` for the workspace parent folder. On Command Prompt, use `%USERPROFILE%\Documents\OKF Harness`.
+
+OKF Harness keeps raw sources under `raw/sources/`, synthesized knowledge under `wiki/`, source records in `.okfh/manifest.jsonl`, and generated reports under `.okfh/reports/`.
+
+For project overview, workflows, security notes, and LLM-readable context, see the [main repository README](https://github.com/pumblus/okf-harness#readme) and [llms.txt](https://github.com/pumblus/okf-harness/blob/main/llms.txt).

package/dist/{chunk-CU2XPEBG.js → chunk-JFVFODXE.js}

@@ -1,5 +1,4 @@
 // src/index.ts
-import { execFile as execFile2 } from "child_process";
 import path2 from "path";
 import { installAgentAdapters } from "@okf-harness/agent-pack";
 import {
@@ -36,19 +35,26 @@ var requiredSkills = [
   "okf-harness-maintain"
 ];
 async function runDoctor(options = {}) {
+  const runtimePlatform = options.runtimePlatform ?? process.platform;
+  const runExecutable = options.runExecutable ?? runExecutableDefault;
   const checks = [
     checkOkfh(),
+    checkPlatform(runtimePlatform),
     checkNode(),
     await checkExecutable("git", ["--version"], {
       id: "git",
       label: "git",
-      missingMessage: "git executable was not found."
+      missingMessage: "git executable was not found.",
+      runtimePlatform,
+      runExecutable
     }),
     await checkExecutable("pnpm", ["--version"], {
       id: "pnpm",
       label: "pnpm",
       missingMessage: "pnpm executable was not found.",
-      outputPrefix: "pnpm "
+      outputPrefix: "pnpm ",
+      runtimePlatform,
+      runExecutable
     })
   ];
   const workspaceRoot = await resolveDoctorWorkspace(options, checks);
@@ -81,6 +87,33 @@ function checkOkfh() {
     }
   };
 }
+function checkPlatform(runtimePlatform) {
+  const platformLabel = platformLabelFor(runtimePlatform);
+  const supported = platformLabel !== null;
+  return {
+    id: "platform",
+    label: "Runtime platform",
+    status: supported ? "pass" : "fail",
+    message: supported ? `${platformLabel} is supported by OKF Harness.` : `Node platform ${runtimePlatform} is not supported by OKF Harness.`,
+    details: {
+      nodePlatform: runtimePlatform,
+      okfHarnessPlatform: platformLabel,
+      supported
+    }
+  };
+}
+function platformLabelFor(runtimePlatform) {
+  switch (runtimePlatform) {
+    case "darwin":
+      return "macOS";
+    case "win32":
+      return "Windows";
+    case "linux":
+      return "Linux";
+    default:
+      return null;
+  }
+}
 function checkNode() {
   const version = process.versions.node;
   const major = Number.parseInt(version.split(".")[0] ?? "", 10);
@@ -103,7 +136,9 @@ function checkNode() {
 }
 async function checkExecutable(executable, args, options) {
   try {
-    const { stdout, stderr } = await execFileAsync(executable, args);
+    const { stdout, stderr } = await options.runExecutable(executable, args, {
+      shell: shouldUseWindowsShell(options.runtimePlatform, executable)
+    });
     const output = `${stdout}${stderr}`.trim();
     return {
       id: options.id,
@@ -126,6 +161,16 @@ async function checkExecutable(executable, args, options) {
     };
   }
 }
+async function runExecutableDefault(executable, args, options) {
+  const { stdout, stderr } = await execFileAsync(executable, args, {
+    shell: options.shell === true,
+    windowsHide: true
+  });
+  return { stdout: String(stdout), stderr: String(stderr) };
+}
+function shouldUseWindowsShell(runtimePlatform, executable) {
+  return runtimePlatform === "win32" && ["npm", "pnpm"].includes(executable);
+}
 async function resolveDoctorWorkspace(options, checks) {
   try {
     return await resolveWorkspaceRoot({
@@ -422,6 +467,66 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// src/graph-open.ts
+import { execFile as execFile2 } from "child_process";
+var GRAPH_OPEN_FAILED = "GRAPH_OPEN_FAILED";
+var GraphOpenError = class extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.details = details;
+    this.name = "GraphOpenError";
+  }
+  details;
+  code = GRAPH_OPEN_FAILED;
+};
+async function openGraphReport(htmlPath, options = {}) {
+  const runtimePlatform = options.runtimePlatform ?? process.platform;
+  const runExecutable = options.runExecutable ?? runExecutableDefault2;
+  const command = graphOpenCommand(runtimePlatform, htmlPath);
+  if (command === null) {
+    throw new GraphOpenError(
+      `Node platform ${runtimePlatform} cannot automatically open graph reports.`,
+      { nodePlatform: runtimePlatform, htmlPath }
+    );
+  }
+  try {
+    await runExecutable(command.executable, command.args);
+  } catch (error) {
+    throw new GraphOpenError(
+      `Graph report was generated, but OKF Harness could not open it automatically: ${htmlPath}`,
+      {
+        nodePlatform: runtimePlatform,
+        htmlPath,
+        executable: command.executable,
+        error: error instanceof Error ? error.message : String(error)
+      }
+    );
+  }
+}
+function graphOpenCommand(runtimePlatform, htmlPath) {
+  switch (runtimePlatform) {
+    case "darwin":
+      return { executable: "open", args: [htmlPath] };
+    case "win32":
+      return { executable: "cmd.exe", args: ["/d", "/s", "/c", "start", "", htmlPath] };
+    case "linux":
+      return { executable: "xdg-open", args: [htmlPath] };
+    default:
+      return null;
+  }
+}
+async function runExecutableDefault2(executable, args) {
+  await new Promise((resolve, reject) => {
+    execFile2(executable, args, { windowsHide: true }, (error) => {
+      if (error !== null) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
 // src/options/index.ts
 function parseIntegerOption(value) {
   const parsed = Number.parseInt(value, 10);
@@ -722,7 +827,7 @@ async function runCli(argv = process.argv, io = {
       throw error;
     }
   });
-  program.command("graph").description("Generate OKF backlinks data and a self-contained graph report.").storeOptionsAsProperties(false).option("--workspace <path>", "workspace path").option("--open", "open the generated graph report in the default macOS browser").option("--json", "write machine-readable JSON").action(async (command) => {
+  program.command("graph").description("Generate OKF backlinks data and a self-contained graph report.").storeOptionsAsProperties(false).option("--workspace <path>", "workspace path").option("--open", "open the generated graph report in the system default browser").option("--json", "write machine-readable JSON").action(async (command) => {
     const options = command.opts();
     let workspaceRoot = null;
     try {
@@ -747,7 +852,9 @@ async function runCli(argv = process.argv, io = {
         command: "graph",
         error,
         workspace: workspaceRoot,
-        next: ["Check write permissions under .okfh and rerun okfh graph --json."],
+        next: error instanceof GraphOpenError ? [
+          "Open the generated graph HTML report manually, or rerun okfh graph --json without --open."
+        ] : ["Check write permissions under .okfh and rerun okfh graph --json."],
         json: options.json === true
       });
       if (handled) {
@@ -988,17 +1095,6 @@ async function runCli(argv = process.argv, io = {
     restoreConsoleError();
   }
 }
-async function openGraphReport(htmlPath) {
-  await new Promise((resolve, reject) => {
-    execFile2("open", [htmlPath], (error) => {
-      if (error !== null) {
-        reject(error);
-        return;
-      }
-      resolve();
-    });
-  });
-}
 function captureCommanderConsoleError(capturedErrors) {
   const originalConsoleError = console.error;
   console.error = (...args) => {

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   packageInfo,
   runCli
-} from "./chunk-CU2XPEBG.js";
+} from "./chunk-JFVFODXE.js";
 export {
   packageInfo,
   runCli

package/dist/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-CU2XPEBG.js";
+} from "./chunk-JFVFODXE.js";
 
 // src/main.ts
 process.exitCode = await runCli(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okf-harness/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The okfh command-line package for local OKF Harness workspaces.",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,6 +25,8 @@
     "claude-code",
     "codex",
     "macos",
+    "windows",
+    "linux",
     "knowledge-management"
   ],
   "publishConfig": {
@@ -50,8 +52,8 @@
     "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
-    "@okf-harness/agent-pack": "0.1.0",
-    "@okf-harness/core": "0.1.0",
+    "@okf-harness/agent-pack": "0.2.0",
+    "@okf-harness/core": "0.2.0",
     "commander": "4.1.1"
   }
 }