@okf-harness/cli 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @okf-harness/cli
+
+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).
+
+Install:
+
+```bash
+npm install -g @okf-harness/cli
+okfh doctor --json
+```
+
+Try without a global install:
+
+```bash
+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).

package/dist/chunk-CU2XPEBG.js

@@ -0,0 +1,1028 @@
+// src/index.ts
+import { execFile as execFile2 } from "child_process";
+import path2 from "path";
+import { installAgentAdapters } from "@okf-harness/agent-pack";
+import {
+  addSource,
+  buildWorkspaceGraph,
+  createIngestPlan,
+  initWorkspace,
+  lintWorkspace,
+  listSources,
+  readWorkspaceDocument,
+  readWorkspaceStatus as readWorkspaceStatus2,
+  resolveWorkspaceRoot as resolveWorkspaceRoot2,
+  SourceManagementError,
+  searchWorkspace,
+  WorkspaceInitError as WorkspaceInitError2
+} from "@okf-harness/core";
+import { Command } from "commander";
+
+// src/doctor/index.ts
+import { execFile } from "child_process";
+import { access, readFile } from "fs/promises";
+import path from "path";
+import { promisify } from "util";
+import {
+  readWorkspaceStatus,
+  resolveWorkspaceRoot,
+  WorkspaceResolutionError
+} from "@okf-harness/core";
+var execFileAsync = promisify(execFile);
+var requiredSkills = [
+  "okf-harness-init",
+  "okf-harness-ingest",
+  "okf-harness-query",
+  "okf-harness-maintain"
+];
+async function runDoctor(options = {}) {
+  const checks = [
+    checkOkfh(),
+    checkNode(),
+    await checkExecutable("git", ["--version"], {
+      id: "git",
+      label: "git",
+      missingMessage: "git executable was not found."
+    }),
+    await checkExecutable("pnpm", ["--version"], {
+      id: "pnpm",
+      label: "pnpm",
+      missingMessage: "pnpm executable was not found.",
+      outputPrefix: "pnpm "
+    })
+  ];
+  const workspaceRoot = await resolveDoctorWorkspace(options, checks);
+  if (workspaceRoot === null) {
+    checks.push(skipCheck("workspace-status", "Workspace status", "No workspace was resolved."));
+    checks.push(skipCheck("claude-adapter", "Claude Code adapter", "No workspace was resolved."));
+    checks.push(skipCheck("codex-adapter", "Codex adapter", "No workspace was resolved."));
+  } else {
+    checks.push(await checkWorkspaceStatus(workspaceRoot));
+    checks.push(await checkAdapter(workspaceRoot, "claude"));
+    checks.push(await checkAdapter(workspaceRoot, "codex"));
+  }
+  const summary = summarizeChecks(checks);
+  return {
+    ok: summary.fail === 0,
+    workspace: workspaceRoot,
+    checks,
+    summary
+  };
+}
+function checkOkfh() {
+  return {
+    id: "okfh",
+    label: "okfh CLI",
+    status: "pass",
+    message: "The current okfh CLI entrypoint is running.",
+    details: {
+      argv0: process.argv[1] ?? null,
+      pid: process.pid
+    }
+  };
+}
+function checkNode() {
+  const version = process.versions.node;
+  const major = Number.parseInt(version.split(".")[0] ?? "", 10);
+  if (Number.isFinite(major) && major >= 22) {
+    return {
+      id: "node",
+      label: "Node.js",
+      status: "pass",
+      message: `Node.js ${version} satisfies the >=22 runtime requirement.`,
+      details: { version }
+    };
+  }
+  return {
+    id: "node",
+    label: "Node.js",
+    status: "fail",
+    message: `Node.js ${version} does not satisfy the >=22 runtime requirement.`,
+    details: { version, required: ">=22.0.0" }
+  };
+}
+async function checkExecutable(executable, args, options) {
+  try {
+    const { stdout, stderr } = await execFileAsync(executable, args);
+    const output = `${stdout}${stderr}`.trim();
+    return {
+      id: options.id,
+      label: options.label,
+      status: "pass",
+      message: output.length > 0 ? `${options.outputPrefix ?? ""}${output}` : `${executable} is available.`,
+      details: { executable }
+    };
+  } catch (error) {
+    const code = nodeErrorCode(error);
+    return {
+      id: options.id,
+      label: options.label,
+      status: "fail",
+      message: code === "ENOENT" ? options.missingMessage : `${executable} check failed.`,
+      details: {
+        executable,
+        error: error instanceof Error ? error.message : String(error)
+      }
+    };
+  }
+}
+async function resolveDoctorWorkspace(options, checks) {
+  try {
+    return await resolveWorkspaceRoot({
+      workspaceRoot: options.workspaceRoot,
+      startDir: options.startDir
+    });
+  } catch (error) {
+    if (error instanceof WorkspaceResolutionError) {
+      checks.push({
+        id: "workspace-resolution",
+        label: "Workspace resolution",
+        status: options.workspaceRoot === void 0 ? "warn" : "fail",
+        message: options.workspaceRoot === void 0 ? "No okfh.config.yaml was found from the current directory or its parents." : "The requested workspace could not be resolved.",
+        details: { startDir: error.startDir }
+      });
+      return null;
+    }
+    throw error;
+  }
+}
+async function checkWorkspaceStatus(workspaceRoot) {
+  const status = await readWorkspaceStatus(workspaceRoot);
+  if (!status.initialized) {
+    return {
+      id: "workspace-status",
+      label: "Workspace status",
+      status: "fail",
+      message: "Workspace is not initialized or okfh.config.yaml is invalid.",
+      details: {
+        workspace: status.workspaceRoot,
+        lintIssues: status.lint.issues.length
+      }
+    };
+  }
+  return {
+    id: "workspace-status",
+    label: "Workspace status",
+    status: status.lint.ok ? "pass" : "warn",
+    message: status.lint.ok ? `Workspace ${status.name ?? workspaceRoot} is initialized and lint passes.` : `Workspace ${status.name ?? workspaceRoot} is initialized but lint has issues.`,
+    details: {
+      workspace: status.workspaceRoot,
+      name: status.name ?? null,
+      wikiFiles: status.wikiFiles,
+      concepts: status.concepts,
+      lintOk: status.lint.ok,
+      lintIssues: status.lint.issues.length
+    }
+  };
+}
+async function checkAdapter(workspaceRoot, adapter) {
+  const rootGuidance = adapter === "claude" ? "CLAUDE.md" : "AGENTS.md";
+  const skillRoot = adapter === "claude" ? ".claude/skills" : ".agents/skills";
+  const missingFiles = [];
+  const rootPath = path.join(workspaceRoot, rootGuidance);
+  const rootContents = await readOptionalText(rootPath);
+  if (rootContents === void 0) {
+    missingFiles.push(rootGuidance);
+  }
+  for (const skill of requiredSkills) {
+    const skillPath = `${skillRoot}/${skill}/SKILL.md`;
+    if (!await fileExists(path.join(workspaceRoot, skillPath))) {
+      missingFiles.push(skillPath);
+    }
+  }
+  const hasManagedBlock = rootContents?.includes("<!-- OKF Harness: start -->") === true && rootContents.includes("<!-- OKF Harness: end -->");
+  if (missingFiles.length === 0 && hasManagedBlock) {
+    return {
+      id: `${adapter}-adapter`,
+      label: adapter === "claude" ? "Claude Code adapter" : "Codex adapter",
+      status: "pass",
+      message: `${adapter === "claude" ? "Claude Code" : "Codex"} adapter files are installed.`,
+      details: { rootGuidance, skillRoot }
+    };
+  }
+  return {
+    id: `${adapter}-adapter`,
+    label: adapter === "claude" ? "Claude Code adapter" : "Codex adapter",
+    status: "warn",
+    message: `${adapter === "claude" ? "Claude Code" : "Codex"} adapter support is incomplete.`,
+    details: {
+      rootGuidance,
+      skillRoot,
+      hasManagedBlock,
+      missingFiles,
+      repairCommand: `okfh agent install ${adapter} --workspace <workspace> --json`
+    }
+  };
+}
+function skipCheck(id, label, message) {
+  return {
+    id,
+    label,
+    status: "skip",
+    message
+  };
+}
+function summarizeChecks(checks) {
+  return checks.reduce(
+    (summary, check) => {
+      summary[check.status] += 1;
+      return summary;
+    },
+    { pass: 0, warn: 0, fail: 0, skip: 0 }
+  );
+}
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch (error) {
+    if (nodeErrorCode(error) === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function readOptionalText(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (nodeErrorCode(error) === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+function nodeErrorCode(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return void 0;
+  }
+  const code = error.code;
+  return typeof code === "string" ? code : void 0;
+}
+
+// src/errors/index.ts
+import {
+  GraphWorkspaceError,
+  ReadWorkspaceError,
+  WorkspaceInitError,
+  WorkspaceResolutionError as WorkspaceResolutionError2
+} from "@okf-harness/core";
+function handleCliError(error, io, options) {
+  if (error instanceof WorkspaceInitError) {
+    writeCliError(io, {
+      command: "init",
+      error,
+      json: options.json
+    });
+    return 1;
+  }
+  if (error instanceof WorkspaceResolutionError2) {
+    writeCliError(io, {
+      command: options.command,
+      error,
+      workspace: null,
+      next: ["Run from inside an OKF Harness workspace or pass --workspace <path>."],
+      json: options.json
+    });
+    return 1;
+  }
+  if (isCommanderError(error)) {
+    if (options.json) {
+      writeCliError(io, {
+        command: options.command,
+        error: {
+          code: error.code,
+          message: error.message
+        },
+        json: true
+      });
+    } else {
+      io.writeErr(options.capturedStderr);
+    }
+    return error.exitCode;
+  }
+  writeCliError(io, {
+    command: "unknown",
+    error: {
+      code: "UNKNOWN",
+      message: error instanceof Error ? error.message : "Unknown error."
+    },
+    json: options.json
+  });
+  return 5;
+}
+function writeCliError(io, options) {
+  const normalized = normalizeCliError(options.error);
+  if (normalized === void 0) {
+    return false;
+  }
+  const envelope = {
+    ok: false,
+    command: options.command,
+    data: {},
+    warnings: [],
+    error: normalized,
+    next: options.next ?? []
+  };
+  if (options.workspace !== void 0) {
+    envelope.workspace = options.workspace;
+  }
+  if (options.json === true) {
+    io.writeErr(`${JSON.stringify(envelope)}
+`);
+  } else {
+    io.writeErr(renderHumanError(normalized.message, options.next ?? []));
+  }
+  return true;
+}
+function writeValidationError(io, options) {
+  writeCliError(io, {
+    command: options.command,
+    error: options.details === void 0 ? {
+      code: options.code,
+      message: options.message
+    } : {
+      code: options.code,
+      message: options.message,
+      details: options.details
+    },
+    workspace: options.workspace,
+    next: options.next ?? [],
+    json: options.json
+  });
+}
+function renderHumanError(message, next) {
+  const nextStep = next[0];
+  return nextStep === void 0 ? `${message}
+` : `${message}
+Next: ${nextStep}
+`;
+}
+function normalizeCliError(error) {
+  if (isNormalizedCliError(error)) {
+    return normalizeObject(error);
+  }
+  if (error instanceof WorkspaceResolutionError2) {
+    return {
+      code: error.code,
+      message: error.message,
+      details: { startDir: error.startDir }
+    };
+  }
+  if (error instanceof ReadWorkspaceError) {
+    const normalized = {
+      code: error.code,
+      message: error.message
+    };
+    return Object.keys(error.details).length > 0 ? { ...normalized, details: error.details } : normalized;
+  }
+  if (error instanceof GraphWorkspaceError) {
+    return {
+      code: error.code,
+      message: error.message,
+      details: error.details
+    };
+  }
+  if (isErrorWithCode(error)) {
+    return {
+      code: error.code,
+      message: error.message
+    };
+  }
+  return void 0;
+}
+function normalizeObject(error) {
+  return error.details === void 0 ? {
+    code: error.code,
+    message: error.message
+  } : error;
+}
+function isCommanderError(error) {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const candidate = error;
+  return typeof candidate.code === "string" && typeof candidate.exitCode === "number" && typeof candidate.message === "string";
+}
+function isErrorWithCode(error) {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const candidate = error;
+  return typeof candidate.code === "string" && typeof candidate.message === "string";
+}
+function isNormalizedCliError(error) {
+  if (!isErrorWithCode(error)) {
+    return false;
+  }
+  const candidate = error;
+  return candidate.details === void 0 || isRecord(candidate.details);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/options/index.ts
+function parseIntegerOption(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Expected an integer option value, received: ${value}`);
+  }
+  return parsed;
+}
+function commandFromArgv(argv) {
+  const command = argv.slice(2).find((arg) => !arg.startsWith("-"));
+  return command ?? "unknown";
+}
+function parseAgentInstallTarget(input) {
+  if (input === "claude" || input === "codex" || input === "all") {
+    return input;
+  }
+  return void 0;
+}
+function parseInitAgentTarget(input) {
+  if (input === "none") {
+    return "none";
+  }
+  if (input === "claude,codex" || input === "codex,claude") {
+    return "all";
+  }
+  return parseAgentInstallTarget(input);
+}
+
+// src/render/result.ts
+function writeResult(io, envelope, json = false) {
+  if (json) {
+    io.writeOut(`${JSON.stringify(envelope)}
+`);
+    return;
+  }
+  io.writeOut(renderHumanResult(envelope));
+}
+function renderHumanResult(envelope) {
+  if (envelope.command === "search") {
+    const data = envelope.data;
+    const rows = (data.results ?? []).map((result, index) => {
+      const title = result.title ?? "(untitled)";
+      const pathValue = result.path ?? "(unknown path)";
+      const type = result.type ?? "Unknown";
+      const score = result.score === void 0 ? "" : ` score=${result.score}`;
+      return `${index + 1}. ${title} [${type}] ${pathValue}${score}`;
+    });
+    const summary = `Found ${data.totalMatches ?? rows.length}${data.truncated ? " (truncated)" : ""}`;
+    return `${summary}
+${rows.join("\n")}${rows.length > 0 ? "\n" : ""}`;
+  }
+  if (envelope.command === "read") {
+    const data = envelope.data;
+    const title = data.metadata?.title ?? "(untitled)";
+    const type = data.metadata?.type ?? "Unknown";
+    const pathValue = data.target?.path ?? "(unknown path)";
+    const truncated = data.content?.truncated ? " truncated" : "";
+    return `${title} [${type}] ${pathValue}${truncated}
+
+${data.content?.text ?? ""}
+`;
+  }
+  if (envelope.command === "graph") {
+    const data = envelope.data;
+    return `Graph report: ${data.report?.htmlPath ?? "(not written)"}
+Backlinks: ${data.report?.backlinksPath ?? "(not written)"}
+`;
+  }
+  if (envelope.command === "doctor") {
+    const data = envelope.data;
+    const summary = data.summary ?? {};
+    const rows = (data.checks ?? []).map((check) => {
+      const label = check.label ?? "Check";
+      const status = (check.status ?? "unknown").toUpperCase();
+      const message = check.message ?? "";
+      return `${status} ${label}: ${message}`;
+    });
+    return `Doctor: ${summary.pass ?? 0} pass, ${summary.warn ?? 0} warn, ${summary.fail ?? 0} fail, ${summary.skip ?? 0} skip
+${rows.join("\n")}${rows.length > 0 ? "\n" : ""}`;
+  }
+  if (!envelope.ok) {
+    return `FAILED ${envelope.command}
+`;
+  }
+  return `${envelope.ok ? "OK" : "FAILED"} ${envelope.command}
+`;
+}
+
+// src/index.ts
+var packageInfo = {
+  name: "@okf-harness/cli",
+  role: "cli"
+};
+async function runCli(argv = process.argv, io = {
+  writeOut: (chunk) => process.stdout.write(chunk),
+  writeErr: (chunk) => process.stderr.write(chunk)
+}) {
+  const program = new Command();
+  let exitCode = 0;
+  const jsonRequested = argv.includes("--json");
+  const capturedCommanderErrors = [];
+  program.name("okfh").description("OKF Harness command line interface.");
+  program.exitOverride();
+  program.command("init <workspace>").description("Initialize an OKF Harness workspace.").storeOptionsAsProperties(false).requiredOption("--name <name>", "workspace display name").option("--agents <agents>", "agent adapters to install: claude, codex, all, none", "all").option("--dry-run", "return the planned writes without creating files").option("--git", "initialize a git repository without committing").option("--json", "write machine-readable JSON").action(async (workspace, command) => {
+    const options = command.opts();
+    const agentTarget = parseInitAgentTarget(options.agents);
+    if (agentTarget === void 0) {
+      writeValidationError(io, {
+        command: "init",
+        code: "INVALID_AGENT_TARGET",
+        message: "Agents must be one of: claude, codex, all, none, claude,codex.",
+        workspace: path2.resolve(workspace),
+        next: ["Rerun okfh init with --agents all, claude, codex, none, or claude,codex."],
+        json: options.json === true
+      });
+      exitCode = 1;
+      return;
+    }
+    let result;
+    try {
+      result = await initWorkspace({
+        workspaceRoot: workspace,
+        name: options.name,
+        dryRun: options.dryRun === true,
+        git: options.git === true
+      });
+    } catch (error) {
+      if (error instanceof WorkspaceInitError2) {
+        writeCliError(io, {
+          command: "init",
+          error,
+          workspace: path2.resolve(workspace),
+          next: error.code === "INIT_NOT_EMPTY" ? ["Choose an empty directory, or run okfh doctor --workspace <path> --json."] : ["Fix the initialization input and rerun okfh init --json."],
+          json: options.json === true
+        });
+        exitCode = error.code === "DEPENDENCY_MISSING" ? 4 : 1;
+        return;
+      }
+      throw error;
+    }
+    const agentInstall = agentTarget === "none" ? void 0 : await installAgentAdapters({
+      workspaceRoot: result.workspaceRoot,
+      adapter: agentTarget,
+      dryRun: result.dryRun
+    });
+    const ok = result.lint.ok && (agentInstall?.conflicts.length ?? 0) === 0;
+    const plannedFiles = uniqueStrings(
+      result.dryRun ? [...result.files, ...agentInstall?.plannedFiles ?? []] : []
+    );
+    const files = uniqueStrings(
+      result.dryRun ? result.files : [
+        ...result.files,
+        ...agentInstall?.writtenFiles ?? [],
+        ...agentInstall?.replacedFiles ?? []
+      ]
+    );
+    const envelope = {
+      ok,
+      command: "init",
+      workspace: result.workspaceRoot,
+      data: {
+        name: result.name,
+        dryRun: result.dryRun,
+        git: result.git,
+        agents: renderInitAgentData(agentTarget, agentInstall),
+        files,
+        plannedFiles,
+        directories: result.directories,
+        lint: result.lint
+      },
+      warnings: filterAgentPackPendingWarnings(result.warnings),
+      next: [
+        "Use the generated OKF Harness skills from Claude Code or Codex.",
+        "Run okfh lint --workspace <path> --json after editing wiki files."
+      ]
+    };
+    writeResult(io, envelope, options.json);
+    exitCode = ok ? 0 : 1;
+  });
+  program.command("status").description("Report OKF Harness workspace status.").storeOptionsAsProperties(false).option("--workspace <path>", "workspace path").option("--json", "write machine-readable JSON").action(async (command) => {
+    const options = command.opts();
+    const workspaceRoot = await resolveWorkspaceRoot2({ workspaceRoot: options.workspace });
+    const result = await readWorkspaceStatus2(workspaceRoot);
+    const envelope = {
+      ok: result.initialized && result.lint.ok,
+      command: "status",
+      workspace: result.workspaceRoot,
+      data: {
+        initialized: result.initialized,
+        name: result.name,
+        wikiFiles: result.wikiFiles,
+        concepts: result.concepts,
+        lint: result.lint,
+        capabilities: {
+          search: "available",
+          read: "available",
+          graph: "available",
+          queryCommand: "not_available"
+        }
+      },
+      warnings: filterAgentPackPendingWarnings(result.warnings),
+      next: result.initialized ? ["Use okfh search and okfh read to answer from the synthesized wiki."] : []
+    };
+    writeResult(io, envelope, options.json);
+    exitCode = envelope.ok ? 0 : 1;
+  });
+  program.command("lint").description("Lint an OKF Harness workspace.").storeOptionsAsProperties(false).option("--workspace <path>", "workspace path").option("--json", "write machine-readable JSON").action(async (command) => {
+    const options = command.opts();
+    const workspaceRoot = await resolveWorkspaceRoot2({ workspaceRoot: options.workspace });
+    const lint = await lintWorkspace(workspaceRoot);
+    const envelope = {
+      ok: lint.ok,
+      command: "lint",
+      workspace: workspaceRoot,
+      data: lint,
+      warnings: [],
+      next: lint.ok ? [] : ["Fix lint errors and rerun okfh lint --workspace <path> --json."]
+    };
+    writeResult(io, envelope, options.json);
+    exitCode = lint.ok ? 0 : 1;
+  });
+  program.command("search <query>").description("Search synthesized OKF wiki concept documents.").storeOptionsAsProperties(false).option("--workspace <path>", "workspace path").option("--limit <number>", "maximum results to return", parseIntegerOption).option("--json", "write machine-readable JSON").action(async (query, command) => {
+    const options = command.opts();
+    let workspaceRoot = null;
+    try {
+      workspaceRoot = await resolveWorkspaceRoot2({ workspaceRoot: options.workspace });
+      const result = await searchWorkspace({
+        workspaceRoot,
+        query,
+        limit: options.limit
+      });
+      const { workspaceRoot: _workspaceRoot, warnings, ...data } = result;
+      const envelope = {
+        ok: true,
+        command: "search",
+        workspace: result.workspaceRoot,
+        data,
+        warnings,
+        next: result.totalMatches === 0 ? [
+          "Run okfh read index --json to inspect the wiki map.",
+          "Try broader keywords, or ingest sources first if the material is only registered raw source."
+        ] : ["Run okfh read <concept-id> --json for the most relevant candidate."]
+      };
+      writeResult(io, envelope, options.json);
+      exitCode = 0;
+    } catch (error) {
+      const handled = writeCliError(io, {
+        command: "search",
+        error,
+        workspace: workspaceRoot,
+        next: ["Check the workspace path and rerun okfh search --json."],
+        json: options.json === true
+      });
+      if (handled) {
+        exitCode = 1;
+        return;
+      }
+      throw error;
+    }
+  });
+  program.command("read <target>").description("Read a bounded OKF wiki document.").storeOptionsAsProperties(false).option("--workspace <path>", "workspace path").option("--section <heading>", "read a section by heading").option("--section-id <id>", "read a section by stable section id").option("--offset <number>", "read from a character offset", parseIntegerOption).option("--limit <number>", "maximum characters for range reads", parseIntegerOption).option("--full", "explicitly request a full bounded read").option("--json", "write machine-readable JSON").action(async (target, command) => {
+    const options = command.opts();
+    let workspaceRoot = null;
+    try {
+      workspaceRoot = await resolveWorkspaceRoot2({ workspaceRoot: options.workspace });
+      const result = await readWorkspaceDocument({
+        workspaceRoot,
+        target,
+        section: options.section,
+        sectionId: options.sectionId,
+        offset: options.offset,
+        limit: options.limit,
+        full: options.full === true
+      });
+      const { workspaceRoot: _workspaceRoot, warnings, ...data } = result;
+      const envelope = {
+        ok: true,
+        command: "read",
+        workspace: result.workspaceRoot,
+        data,
+        warnings,
+        next: result.content.truncated ? ["Use --section, --section-id, --offset/--limit, or --full to continue reading."] : []
+      };
+      writeResult(io, envelope, options.json);
+      exitCode = 0;
+    } catch (error) {
+      const handled = writeCliError(io, {
+        command: "read",
+        error,
+        workspace: workspaceRoot,
+        next: ["Run okfh search with broader keywords, then read one returned concept path."],
+        json: options.json === true
+      });
+      if (handled) {
+        exitCode = 1;
+        return;
+      }
+      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) => {
+    const options = command.opts();
+    let workspaceRoot = null;
+    try {
+      workspaceRoot = await resolveWorkspaceRoot2({ workspaceRoot: options.workspace });
+      const result = await buildWorkspaceGraph({ workspaceRoot });
+      if (options.open === true) {
+        await openGraphReport(result.report.htmlPath);
+      }
+      const { workspaceRoot: _workspaceRoot, ...data } = result;
+      const envelope = {
+        ok: true,
+        command: "graph",
+        workspace: result.workspaceRoot,
+        data,
+        warnings: [],
+        next: options.open === true ? [] : ["Open the graph HTML report in a browser if needed."]
+      };
+      writeResult(io, envelope, options.json);
+      exitCode = 0;
+    } catch (error) {
+      const handled = writeCliError(io, {
+        command: "graph",
+        error,
+        workspace: workspaceRoot,
+        next: ["Check write permissions under .okfh and rerun okfh graph --json."],
+        json: options.json === true
+      });
+      if (handled) {
+        exitCode = 1;
+        return;
+      }
+      throw error;
+    }
+  });
+  program.command("doctor").description("Check okfh, local shell dependencies, and workspace readiness.").storeOptionsAsProperties(false).option("--workspace <path>", "workspace path").option("--json", "write machine-readable JSON").action(async (command) => {
+    const options = command.opts();
+    const result = await runDoctor({ workspaceRoot: options.workspace });
+    const envelope = {
+      ok: result.ok,
+      command: "doctor",
+      workspace: result.workspace,
+      data: {
+        checks: result.checks,
+        summary: result.summary
+      },
+      warnings: result.checks.filter((check) => check.status === "warn").map((check) => ({
+        code: check.id.toUpperCase().replaceAll("-", "_"),
+        message: check.message
+      })),
+      next: result.ok ? ["Use okfh --json commands through the local shell for OKF Harness workflows."] : ["Fix failed checks, then rerun okfh doctor --json."]
+    };
+    writeResult(io, envelope, options.json);
+    exitCode = result.ok ? 0 : 1;
+  });
+  program.command("source <action> [input]").description("Register and list OKF Harness raw sources.").storeOptionsAsProperties(false).requiredOption("--workspace <path>", "workspace path").option("--dry-run", "return the planned source registration without writing files").option("--json", "write machine-readable JSON").action(async (actionInput, input, command) => {
+    const options = command.opts();
+    if (actionInput === "list") {
+      try {
+        const result = await listSources({ workspaceRoot: options.workspace });
+        const envelope = {
+          ok: true,
+          command: "source list",
+          workspace: result.workspaceRoot,
+          data: { sources: result.sources },
+          warnings: [],
+          next: []
+        };
+        writeResult(io, envelope, options.json);
+        exitCode = 0;
+      } catch (error) {
+        if (error instanceof SourceManagementError) {
+          writeCliError(io, {
+            command: "source list",
+            error,
+            workspace: path2.resolve(options.workspace),
+            next: ["Check the workspace path and rerun okfh source list --json."],
+            json: options.json === true
+          });
+          exitCode = 1;
+          return;
+        }
+        throw error;
+      }
+      return;
+    }
+    if (actionInput !== "add") {
+      writeValidationError(io, {
+        command: "source",
+        code: "INVALID_SOURCE_ACTION",
+        message: "Source action must be one of: add, list.",
+        workspace: path2.resolve(options.workspace),
+        next: ["Use okfh source add <path-or-url> --workspace <path> --json."],
+        json: options.json === true
+      });
+      exitCode = 1;
+      return;
+    }
+    if (input === void 0) {
+      writeValidationError(io, {
+        command: "source add",
+        code: "SOURCE_INPUT_REQUIRED",
+        message: "source add requires a file path or URL.",
+        workspace: path2.resolve(options.workspace),
+        next: ["Pass a local file path or URL to okfh source add."],
+        json: options.json === true
+      });
+      exitCode = 2;
+      return;
+    }
+    try {
+      const result = await addSource({
+        workspaceRoot: options.workspace,
+        input,
+        dryRun: options.dryRun === true
+      });
+      const envelope = {
+        ok: true,
+        command: "source add",
+        workspace: result.workspaceRoot,
+        data: {
+          action: result.action,
+          dryRun: result.dryRun,
+          source: result.source
+        },
+        warnings: [],
+        next: [`Run okfh ingest plan ${result.source.id} --workspace <path> --json.`]
+      };
+      writeResult(io, envelope, options.json);
+      exitCode = 0;
+    } catch (error) {
+      if (error instanceof SourceManagementError) {
+        writeCliError(io, {
+          command: "source add",
+          error,
+          workspace: path2.resolve(options.workspace),
+          next: ["Check the source input and workspace path, then rerun okfh source add --json."],
+          json: options.json === true
+        });
+        exitCode = error.code === "SOURCE_INPUT_UNSUPPORTED" ? 1 : 5;
+        return;
+      }
+      throw error;
+    }
+  });
+  program.command("ingest <action> <source>").description("Plan source ingestion into the OKF wiki.").storeOptionsAsProperties(false).requiredOption("--workspace <path>", "workspace path").option("--json", "write machine-readable JSON").action(async (actionInput, sourceInput, command) => {
+    const options = command.opts();
+    if (actionInput !== "plan") {
+      writeValidationError(io, {
+        command: "ingest",
+        code: "INVALID_INGEST_ACTION",
+        message: "Ingest action must be: plan.",
+        workspace: path2.resolve(options.workspace),
+        next: ["Use okfh ingest plan <source-id-or-path> --workspace <path> --json."],
+        json: options.json === true
+      });
+      exitCode = 1;
+      return;
+    }
+    try {
+      const result = await createIngestPlan({
+        workspaceRoot: options.workspace,
+        source: sourceInput
+      });
+      const envelope = {
+        ok: true,
+        command: "ingest plan",
+        workspace: result.workspaceRoot,
+        data: {
+          source: result.source,
+          recommendedReferencePath: result.recommendedReferencePath,
+          candidateConcepts: result.candidateConcepts,
+          checklist: result.checklist
+        },
+        warnings: [],
+        next: ["Use the ingest plan as the Agent checklist before editing wiki files."]
+      };
+      writeResult(io, envelope, options.json);
+      exitCode = 0;
+    } catch (error) {
+      if (error instanceof SourceManagementError) {
+        writeCliError(io, {
+          command: "ingest plan",
+          error,
+          workspace: path2.resolve(options.workspace),
+          next: ["Register the source first with okfh source add, then rerun okfh ingest plan."],
+          json: options.json === true
+        });
+        exitCode = error.code === "SOURCE_NOT_REGISTERED" ? 1 : 5;
+        return;
+      }
+      throw error;
+    }
+  });
+  program.command("agent <action> <adapter>").description("Install or repair Claude Code and Codex adapter files.").storeOptionsAsProperties(false).requiredOption("--workspace <path>", "workspace path").option("--dry-run", "return the planned writes without creating files").option("--force", "replace conflicting same-name adapter files").option("--json", "write machine-readable JSON").action(async (actionInput, adapterInput, command) => {
+    const options = command.opts();
+    if (actionInput !== "install") {
+      writeValidationError(io, {
+        command: "agent",
+        code: "INVALID_AGENT_ACTION",
+        message: "Agent action must be: install.",
+        workspace: path2.resolve(options.workspace),
+        next: ["Use okfh agent install claude|codex|all --workspace <path> --json."],
+        json: options.json === true
+      });
+      exitCode = 1;
+      return;
+    }
+    const adapter = parseAgentInstallTarget(adapterInput);
+    if (adapter === void 0) {
+      writeValidationError(io, {
+        command: "agent install",
+        code: "INVALID_AGENT_ADAPTER",
+        message: "Adapter must be one of: claude, codex, all.",
+        workspace: path2.resolve(options.workspace),
+        next: ["Rerun with adapter claude, codex, or all."],
+        json: options.json === true
+      });
+      exitCode = 1;
+      return;
+    }
+    const workspaceStatus = await readWorkspaceStatus2(options.workspace);
+    if (!workspaceStatus.initialized) {
+      writeValidationError(io, {
+        command: "agent install",
+        code: "WORKSPACE_NOT_INITIALIZED",
+        message: "Workspace is not initialized. Run okfh init first.",
+        workspace: workspaceStatus.workspaceRoot,
+        next: ["Run okfh init <workspace> --name <name> --agents all --json first."],
+        json: options.json === true
+      });
+      exitCode = 1;
+      return;
+    }
+    const result = await installAgentAdapters({
+      workspaceRoot: workspaceStatus.workspaceRoot,
+      adapter,
+      dryRun: options.dryRun === true,
+      force: options.force === true
+    });
+    const ok = result.conflicts.length === 0;
+    const envelope = {
+      ok,
+      command: "agent install",
+      workspace: workspaceStatus.workspaceRoot,
+      data: result,
+      warnings: [],
+      next: ok ? ["Run okfh status --workspace <path> --json to verify the workspace."] : ["Resolve conflicts or rerun with --force after reviewing the files."]
+    };
+    writeResult(io, envelope, options.json);
+    exitCode = ok ? 0 : 1;
+  });
+  const restoreConsoleError = captureCommanderConsoleError(capturedCommanderErrors);
+  try {
+    await program.parseAsync(argv);
+    return exitCode;
+  } catch (error) {
+    return handleCliError(error, io, {
+      command: commandFromArgv(argv),
+      json: jsonRequested,
+      capturedStderr: capturedCommanderErrors.join("")
+    });
+  } finally {
+    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) => {
+    capturedErrors.push(`${args.map((arg) => String(arg)).join(" ")}
+`);
+  };
+  return () => {
+    console.error = originalConsoleError;
+  };
+}
+function renderInitAgentData(requested, install) {
+  if (install === void 0) {
+    return { requested };
+  }
+  return { requested, install };
+}
+function filterAgentPackPendingWarnings(warnings) {
+  return warnings.filter((warning) => warning.code !== "AGENT_PACK_PENDING");
+}
+function uniqueStrings(values) {
+  return [...new Set(values)];
+}
+
+export {
+  packageInfo,
+  runCli
+};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+type CliIo = {
+    writeOut: (chunk: string) => void;
+    writeErr: (chunk: string) => void;
+};
+type JsonEnvelope = {
+    ok: boolean;
+    command: string;
+    workspace?: string | null;
+    data: unknown;
+    warnings: Array<{
+        code: string;
+        message: string;
+    }>;
+    next: string[];
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+};
+
+declare const packageInfo: {
+    readonly name: "@okf-harness/cli";
+    readonly role: "cli";
+};
+type PackageInfo = typeof packageInfo;
+declare function runCli(argv?: string[], io?: CliIo): Promise<number>;
+
+export { type CliIo, type JsonEnvelope, type PackageInfo, packageInfo, runCli };

package/dist/index.js

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

package/dist/main.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/main.js

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@okf-harness/cli",
+  "version": "0.1.0",
+  "description": "The okfh command-line package for local OKF Harness workspaces.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "author": "Eric Zhou",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "homepage": "https://github.com/pumblus/okf-harness#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pumblus/okf-harness.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/pumblus/okf-harness/issues"
+  },
+  "keywords": [
+    "okf",
+    "open-knowledge-format",
+    "llm-wiki",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "macos",
+    "knowledge-management"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "okfh": "dist/main.js",
+    "okf-harness": "dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "pnpm --dir ../.. --filter @okf-harness/core build && pnpm --dir ../.. --filter @okf-harness/agent-pack build && tsup src/index.ts src/main.ts --format esm --dts --clean",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@okf-harness/agent-pack": "0.1.0",
+    "@okf-harness/core": "0.1.0",
+    "commander": "4.1.1"
+  }
+}