@geminix/gxpm 0.1.0

package/scripts/commands/upgrade.ts

@@ -0,0 +1,243 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { readGxpmVersion } from "../version";
+
+interface UpgradeOptions {
+  dryRun?: boolean;
+  skipPull?: boolean;
+  skipInstall?: boolean;
+}
+
+function getGxpmRoot(): string {
+  const envRoot = process.env.GXPM_DIR;
+  if (envRoot) return resolve(envRoot);
+  // Heuristic: find gxpm repo by locating the bin/gxpm binary on PATH
+  try {
+    const binPath = execSync("command -v gxpm", { encoding: "utf-8" }).trim();
+    if (binPath) {
+      // Resolve symlinks
+      const realBin = execSync(`readlink -f "${binPath}" 2>/dev/null || echo "${binPath}"`, { encoding: "utf-8" }).trim();
+      return resolve(realBin, "..", "..");
+    }
+  } catch {
+    // fallthrough
+  }
+  // Fallback: assume cwd is gxpm repo
+  return resolve(import.meta.dir, "../..");
+}
+
+function getCurrentBranch(root: string): string {
+  return execSync("git branch --show-current", { cwd: root, encoding: "utf-8" }).trim();
+}
+
+function getLastLocalVersion(root: string): string | null {
+  try {
+    const prior = execSync("git show HEAD@{1}:VERSION", { cwd: root, encoding: "utf-8" }).trim();
+    return prior;
+  } catch {
+    return null;
+  }
+}
+
+function filesChangedSince(root: string, ref: string): string[] {
+  try {
+    const out = execSync(`git diff --name-only ${ref}..HEAD`, { cwd: root, encoding: "utf-8" }).trim();
+    return out ? out.split("\n") : [];
+  } catch {
+    return [];
+  }
+}
+
+function listMigrationGuides(root: string, fromVersion: string, toVersion: string): string[] {
+  const migrationsDir = join(root, "docs", "migrations");
+  if (!existsSync(migrationsDir)) return [];
+
+  const guides: string[] = [];
+  for (const file of readdirSync(migrationsDir)) {
+    if (!file.endsWith(".md")) continue;
+    const match = file.match(/^v([0-9.]+)\.md$/);
+    if (!match) continue;
+    const v = match[1];
+    // Simple semver-ish comparison: assume versions are like 0.1.0, 0.2.0
+    if (compareSemver(v, fromVersion) > 0 && compareSemver(v, toVersion) <= 0) {
+      guides.push(join(migrationsDir, file));
+    }
+  }
+  return guides.sort((a, b) => compareSemver(parseVersionFromPath(a), parseVersionFromPath(b)));
+}
+
+function parseVersionFromPath(path: string): string {
+  const base = path.split("/").pop() ?? "";
+  const m = base.match(/^v([0-9.]+)\.md$/);
+  return m?.[1] ?? "0.0.0";
+}
+
+function compareSemver(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const na = pa[i] ?? 0;
+    const nb = pb[i] ?? 0;
+    if (na !== nb) return na - nb;
+  }
+  return 0;
+}
+
+function logUpgradeError(root: string, phase: string, from: string, to: string, hint: string) {
+  const auditDir = join(homedir(), ".gxpm", "audit");
+  mkdirSync(auditDir, { recursive: true });
+  const line = JSON.stringify({ ts: new Date().toISOString(), phase, from_version: from, to_version: to, hint }) + "\n";
+  const errPath = join(auditDir, "upgrade-errors.jsonl");
+  const { writeFileSync } = require("node:fs");
+  writeFileSync(errPath, line, { flag: "a" });
+}
+
+import { mkdirSync } from "node:fs";
+
+export function runUpgradeCommand(argv: string[]) {
+  const opts: UpgradeOptions = {
+    dryRun: argv.includes("--dry-run"),
+    skipPull: argv.includes("--skip-pull"),
+    skipInstall: argv.includes("--skip-install"),
+  };
+
+  const root = getGxpmRoot();
+  const currentVersion = readGxpmVersion({ root });
+  const priorVersion = getLastLocalVersion(root);
+  const branch = getCurrentBranch(root);
+
+  if (branch !== "main" && branch !== "master") {
+    console.warn(`Warning: current branch is '${branch}', not main/master. Upgrade may be unsafe.`);
+  }
+
+  const steps: string[] = [];
+
+  // Step 1: git pull
+  if (!opts.skipPull) {
+    steps.push("git pull origin main");
+    if (!opts.dryRun) {
+      try {
+        execSync("git pull origin main", { cwd: root, stdio: "inherit" });
+      } catch (e) {
+        const hint = "Resolve git conflicts manually, then rerun `gxpm upgrade`";
+        logUpgradeError(root, "git_pull", priorVersion ?? "unknown", currentVersion, hint);
+        throw new Error(`git pull failed. ${hint}`);
+      }
+    }
+  }
+
+  // Step 2: bun install
+  if (!opts.skipInstall) {
+    steps.push("bun install");
+    if (!opts.dryRun) {
+      try {
+        execSync("bun install", { cwd: root, stdio: "inherit" });
+      } catch (e) {
+        const hint = "Check bun.lock conflicts and run `bun install` manually";
+        logUpgradeError(root, "bun_install", priorVersion ?? "unknown", currentVersion, hint);
+        throw new Error(`bun install failed. ${hint}`);
+      }
+    }
+  }
+
+  // Step 3: Detect template changes and regenerate skill docs
+  const changed = opts.dryRun ? [] : filesChangedSince(root, "HEAD@{1}");
+  const tmplChanged = changed.some((f) => f.endsWith(".tmpl"));
+  const hooksChanged = changed.some((f) => f.startsWith("templates/hooks/"));
+
+  if (tmplChanged) {
+    steps.push("bun run gen:skill-docs (skill templates changed)");
+    if (!opts.dryRun) {
+      try {
+        execSync("bun run gen:skill-docs", { cwd: root, stdio: "inherit" });
+      } catch (e) {
+        const hint = "Run `bun run gen:skill-docs` manually after fixing errors";
+        logUpgradeError(root, "gen_skill_docs", priorVersion ?? "unknown", currentVersion, hint);
+        throw new Error(`gen:skill-docs failed. ${hint}`);
+      }
+    }
+  }
+
+  if (hooksChanged) {
+    steps.push("gxpm init --install-hooks (hook templates changed) — run manually");
+  }
+
+  // Step 4: post-upgrade notes
+  const newVersion = readGxpmVersion({ root });
+  const guides = listMigrationGuides(root, priorVersion ?? "0.0.0", newVersion);
+
+  if (opts.dryRun) {
+    console.log("DRY RUN — would execute:");
+    for (const s of steps) console.log(`  ${s}`);
+    if (guides.length > 0) {
+      console.log("");
+      console.log("Migration guides to read:");
+      for (const g of guides) console.log(`  ${g}`);
+    }
+    return;
+  }
+
+  console.log(`Upgrade complete: ${priorVersion ?? "unknown"} -> ${newVersion}`);
+  console.log("");
+  if (guides.length > 0) {
+    console.log("Migration guides for versions you skipped:");
+    for (const g of guides) {
+      console.log(`  ${g}`);
+    }
+    console.log("");
+    console.log("Read each guide and run any backfill steps listed before continuing.");
+  }
+  if (hooksChanged) {
+    console.log("");
+    console.log("Hook templates changed. Run `gxpm init --install-hooks --target <repo>` to update.");
+  }
+}
+
+export function runPostUpgradeCommand(argv: string[]) {
+  const root = getGxpmRoot();
+  const currentVersion = readGxpmVersion({ root });
+
+  // Find all migration guides <= current version
+  const migrationsDir = join(root, "docs", "migrations");
+  if (!existsSync(migrationsDir)) {
+    console.log("No migrations directory found.");
+    return;
+  }
+
+  const guides: string[] = [];
+  for (const file of readdirSync(migrationsDir)) {
+    if (!file.endsWith(".md")) continue;
+    const v = parseVersionFromPath(file);
+    if (compareSemver(v, currentVersion) <= 0) {
+      guides.push(join(migrationsDir, file));
+    }
+  }
+  guides.sort((a, b) => compareSemver(parseVersionFromPath(a), parseVersionFromPath(b)));
+
+  console.log(`gxpm ${currentVersion} — post-upgrade notes`);
+  console.log("");
+
+  if (guides.length === 0) {
+    console.log("No migration guides found.");
+    return;
+  }
+
+  for (const g of guides) {
+    const name = g.split("/").pop() ?? g;
+    console.log(`--- ${name} ---`);
+    try {
+      const content = readFileSync(g, "utf-8");
+      // Print only the first 30 lines to avoid flooding
+      const lines = content.split("\n").slice(0, 30);
+      console.log(lines.join("\n"));
+      if (content.split("\n").length > 30) {
+        console.log("... (truncated, read full file for details)");
+      }
+      console.log("");
+    } catch {
+      console.log("(could not read)");
+    }
+  }
+}

package/scripts/commands/verify.ts

@@ -0,0 +1,183 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { getConfigValue } from "../../core/config";
+import { runDoctor } from "../doctor";
+
+interface VerifyCheck {
+  name: string;
+  status: "ok" | "warn" | "fail";
+  message: string;
+}
+
+interface VerifyResult {
+  status: "passed" | "warnings" | "failed";
+  checks: VerifyCheck[];
+}
+
+function isGitRepo(dir: string): boolean {
+  return existsSync(join(dir, ".git"));
+}
+
+function checkGitHooksFire(target: string): VerifyCheck {
+  try {
+    // Create a temp file to verify pre-commit fires
+    const testFile = join(target, ".gxpm", ".verify-hook-test");
+    writeFileSync(testFile, "hook test\n");
+    execSync("git add -f .gxpm/.verify-hook-test", { cwd: target });
+    // Run pre-commit hook manually to see if it exits 0
+    const hooksPath = execSync("git config core.hooksPath", { cwd: target, encoding: "utf-8" }).trim();
+    const preCommit = join(hooksPath, "pre-commit");
+    if (existsSync(preCommit)) {
+      execSync(preCommit, { cwd: target, stdio: "ignore" });
+    }
+    execSync("git reset HEAD .gxpm/.verify-hook-test", { cwd: target, stdio: "ignore" });
+    rmSync(testFile);
+    return { name: "git_hooks_fire", status: "ok", message: "pre-commit hook executes without error" };
+  } catch (e) {
+    return { name: "git_hooks_fire", status: "warn", message: `Could not verify hook execution: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+function checkWorktreeAvailable(target: string): VerifyCheck {
+  try {
+    execSync("git worktree list", { cwd: target, stdio: "ignore" });
+    return { name: "worktree_available", status: "ok", message: "git worktree is available" };
+  } catch {
+    return { name: "worktree_available", status: "warn", message: "git worktree not available or failed" };
+  }
+}
+
+function checkSkillHostDiscovery(): VerifyCheck {
+  const hosts = ["claude", "codex", "cursor"];
+  const found: string[] = [];
+  const home = homedir();
+  for (const h of hosts) {
+    const skillPath = join(home, "." + h, "skills", "gxpm", "SKILL.md");
+    if (existsSync(skillPath)) found.push(h);
+  }
+  if (found.length > 0) {
+    return { name: "skill_host_discovery", status: "ok", message: `gxpm skill installed on: ${found.join(", ")}` };
+  }
+  return { name: "skill_host_discovery", status: "fail", message: "gxpm skill not found on any host. Run: gxpm init --install-skill --host all" };
+}
+
+function checkLinearConnectivity(): VerifyCheck {
+  const provider = getConfigValue({ key: "sync.provider" });
+  if (provider.value !== "linear") {
+    return { name: "linear_connectivity", status: "ok", message: "sync.provider is not linear; skipped" };
+  }
+  try {
+    const token = process.env.LINEAR_API_KEY || process.env.LINEAR_API_TOKEN;
+    if (!token) {
+      return { name: "linear_connectivity", status: "warn", message: "sync.provider=linear but no LINEAR_API_KEY env var set" };
+    }
+    // Minimal GraphQL health check
+    const result = execSync(
+      `curl -sf -H "Authorization: ${token}" -H "Content-Type: application/json" -X POST -d '{"query":"{ viewer { id } }"}' https://api.linear.app/graphql`,
+      { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }
+    );
+    const parsed = JSON.parse(result);
+    if (parsed.errors) {
+      return { name: "linear_connectivity", status: "fail", message: `Linear API error: ${parsed.errors[0]?.message}` };
+    }
+    return { name: "linear_connectivity", status: "ok", message: "Linear API reachable" };
+  } catch (e) {
+    return { name: "linear_connectivity", status: "warn", message: `Could not verify Linear connectivity: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+function checkIssueLifecycle(target: string, dryRun: boolean): VerifyCheck {
+  try {
+    if (dryRun) {
+      return { name: "issue_lifecycle", status: "ok", message: "dry-run: skipped actual issue creation" };
+    }
+    // Create a test issue
+    const out = execSync("bin/gxpm issue create --auto-id", { cwd: target, encoding: "utf-8" }).trim();
+    const match = out.match(/created (GXPM-\d+)/i);
+    if (!match) {
+      return { name: "issue_lifecycle", status: "fail", message: "Could not parse issue creation output" };
+    }
+    const id = match[1];
+    // Initialize required artifact for triage → plan transition
+    execSync(`bin/gxpm triage init ${id}`, { cwd: target, stdio: "ignore" });
+    // Transition to plan
+    execSync(`bin/gxpm issue transition ${id} plan`, { cwd: target, stdio: "ignore" });
+    return { name: "issue_lifecycle", status: "ok", message: `Created and transitioned ${id} successfully` };
+  } catch (e) {
+    return { name: "issue_lifecycle", status: "fail", message: `Issue lifecycle test failed: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+export function runVerifyCommand(argv: string[]) {
+  const dryRun = argv.includes("--dry-run");
+  const json = argv.includes("--json");
+  const target = resolve(process.cwd());
+
+  if (!isGitRepo(target)) {
+    throw new Error(`Not a git repository: ${target}`);
+  }
+
+  const checks: VerifyCheck[] = [];
+
+  // 1. Doctor baseline
+  try {
+    const doctorReport = runDoctor({ cwd: target });
+    const hasFail = (doctorReport as any).checks?.some((c: any) => c.status === "fail");
+    const hasWarn = (doctorReport as any).checks?.some((c: any) => c.status === "warn");
+    if (hasFail) {
+      checks.push({ name: "doctor_baseline", status: "fail", message: "gxpm doctor has failing checks" });
+    } else if (hasWarn) {
+      checks.push({ name: "doctor_baseline", status: "warn", message: "gxpm doctor has warnings" });
+    } else {
+      checks.push({ name: "doctor_baseline", status: "ok", message: "gxpm doctor all clear" });
+    }
+  } catch (e) {
+    checks.push({ name: "doctor_baseline", status: "fail", message: `doctor failed: ${e instanceof Error ? e.message : String(e)}` });
+  }
+
+  // 2. Git hooks
+  checks.push(checkGitHooksFire(target));
+
+  // 3. Worktree
+  checks.push(checkWorktreeAvailable(target));
+
+  // 4. Skill hosts
+  checks.push(checkSkillHostDiscovery());
+
+  // 5. Linear (if configured)
+  checks.push(checkLinearConnectivity());
+
+  // 6. Issue lifecycle (optional, can be skipped with --no-issue-test)
+  if (!argv.includes("--no-issue-test")) {
+    checks.push(checkIssueLifecycle(target, dryRun));
+  }
+
+  const hasFail = checks.some((c) => c.status === "fail");
+  const hasWarn = checks.some((c) => c.status === "warn");
+  const status: VerifyResult["status"] = hasFail ? "failed" : hasWarn ? "warnings" : "passed";
+
+  const result: VerifyResult = { status, checks };
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(hasFail ? 1 : 0);
+  }
+
+  console.log("gxpm verify");
+  console.log("===========");
+  console.log("");
+  for (const c of checks) {
+    const icon = c.status === "ok" ? "✓" : c.status === "warn" ? "⚠" : "✗";
+    console.log(`  ${icon} ${c.name}: ${c.message}`);
+  }
+  console.log("");
+  console.log(`Result: ${status}`);
+
+  if (hasFail) {
+    console.log("");
+    console.log("Fix failing checks, then rerun `gxpm verify`.");
+    process.exit(1);
+  }
+}

package/scripts/commands/wiki.ts

@@ -0,0 +1,242 @@
+import { writeArtifact } from "../../core/artifacts";
+import {
+  ensureNativeWikiCurrent,
+  evaluateNativeWiki,
+  getNativeWikiContextForIssue,
+  getNativeWikiStatus,
+  initializeNativeWiki,
+  queryNativeWiki,
+  updateNativeWiki,
+  type NativeWikiBuildResult,
+  type NativeWikiEvalReport,
+  type NativeWikiIssueContext,
+  type NativeWikiQueryResult,
+  type NativeWikiStatus,
+} from "../../core/wiki";
+import { optionRequiredValue, parsePositiveIntegerOption } from "./helpers";
+
+const WIKI_CONTEXT_USAGE = "Usage: gxpm wiki context <issue-id> [--phase <phase>] [--limit <n>] [--write-artifact] [--json] [--no-auto-update]";
+
+export function runWikiCommand(argv: string[], subcommand: string | undefined) {
+  if (!subcommand || subcommand === "status") {
+    const native = getNativeWikiStatus();
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify({ native }, null, 2));
+    } else {
+      console.log(formatNativeWikiStatus(native));
+    }
+    return;
+  }
+
+  if (subcommand === "init" || subcommand === "index") {
+    const result = initializeNativeWiki();
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatNativeWikiBuildResult(result));
+    }
+    return;
+  }
+
+  if (subcommand === "update") {
+    const result = updateNativeWiki();
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatNativeWikiBuildResult(result));
+    }
+    return;
+  }
+
+  if (subcommand === "eval") {
+    const report = evaluateNativeWiki();
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(formatNativeWikiEvalReport(report));
+    }
+    return;
+  }
+
+  if (subcommand === "query") {
+    const query = wikiQueryText(argv);
+    if (!query) {
+      throw new Error("Usage: gxpm wiki query <text> [--limit <n>] [--json] [--no-auto-update]");
+    }
+    const result = queryNativeWiki({
+      query,
+      limit: parsePositiveIntegerOption(argv, "--limit"),
+      autoUpdate: !argv.includes("--no-auto-update"),
+    });
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatNativeWikiQueryResult(result));
+    }
+    return;
+  }
+
+  if (subcommand === "context") {
+    const contextIssueId = argv[2];
+    if (!contextIssueId || contextIssueId.startsWith("--")) {
+      throw new Error(WIKI_CONTEXT_USAGE);
+    }
+    assertNoUnexpectedWikiContextPositionals(argv);
+    const result = getNativeWikiContextForIssue({
+      issueId: contextIssueId,
+      phase: argv.includes("--phase") ? optionRequiredValue(argv, "--phase") : undefined,
+      limit: parsePositiveIntegerOption(argv, "--limit"),
+      autoUpdate: !argv.includes("--no-auto-update"),
+    });
+    const artifactWritten = argv.includes("--write-artifact");
+    if (artifactWritten) {
+      writeArtifact({ issueId: contextIssueId, type: "wiki-context", payload: result });
+    }
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(artifactWritten ? { ...result, artifactWritten: "wiki-context" } : result, null, 2));
+    } else {
+      console.log(formatNativeWikiIssueContext(result, artifactWritten));
+    }
+    return;
+  }
+
+  throw new Error(`Usage: gxpm wiki status [--json] | gxpm wiki init [--json] | gxpm wiki index [--json] | gxpm wiki update [--json] | gxpm wiki eval [--json] | gxpm wiki query <text> [--limit <n>] [--json] | ${WIKI_CONTEXT_USAGE.replace(/^Usage: /, "")}`);
+}
+
+function formatNativeWikiStatus(status: NativeWikiStatus) {
+  const lines = [`Optional human wiki: ${status.state}`];
+  if (!status.detected) {
+    lines.push(`state: ${status.paths.state} not initialized`);
+    lines.push(`Reason: ${status.reason}`);
+    lines.push(`Run when humans want local project docs: ${status.commands.init}`);
+    return lines.join("\n");
+  }
+  lines.push(`generatedAt: ${status.generatedAt ?? "unknown"}`);
+  lines.push(`baseCommit: ${status.baseCommit ?? "unknown"}`);
+  lines.push(`currentCommit: ${status.currentCommit ?? "unknown"}`);
+  lines.push(`files: ${status.indexedFiles}`);
+  lines.push(`edges: ${status.graphEdges}`);
+  lines.push(`dimensions: ${status.dimensionedFiles}`);
+  lines.push(`docs: ${status.docs.join(", ") || "none"}`);
+  lines.push(`stale: ${status.stale ? "yes" : "no"}`);
+  lines.push(`Reason: ${status.reason}`);
+  if (status.changedFiles.length > 0) {
+    lines.push("Changed files:");
+    for (const file of status.changedFiles.slice(0, 10)) lines.push(`- ${file}`);
+  }
+  if (status.stale) lines.push(`Manual refresh: ${status.commands.update}`);
+  return lines.join("\n");
+}
+
+function formatNativeWikiBuildResult(result: NativeWikiBuildResult) {
+  return [
+    `Optional human wiki: ${result.mode}`,
+    `state: ${result.state.status}`,
+    `baseCommit: ${result.state.baseCommit ?? "unknown"}`,
+    `files: ${result.index.files.length}`,
+    `edges: ${result.graph.edges.length}`,
+    `dimensions: ${result.dimensions.files.length}`,
+    `docs: ${result.docs.join(", ")}`,
+  ].join("\n");
+}
+
+function formatNativeWikiEvalReport(report: NativeWikiEvalReport) {
+  const lines = [
+    `Optional human wiki eval: ${report.native.status.state}`,
+    `generated docs: ${report.native.generatedDocs.count}`,
+    `project topic clusters: ${report.native.projectTopics.clusterCount}`,
+    `indexed files: ${report.native.sourceCoverage.indexedFiles}`,
+    `source-anchored files: ${report.native.sourceCoverage.anchoredFiles}`,
+    `orphan indexed files: ${report.native.sourceCoverage.orphanIndexedFiles}`,
+  ];
+  if (report.native.queryScenarios.length > 0) {
+    lines.push("");
+    lines.push("Query scenarios:");
+    for (const scenario of report.native.queryScenarios) {
+      lines.push(`- ${scenario.query}: ${scenario.topFiles.slice(0, 3).join(", ") || "no matches"}`);
+    }
+  }
+  lines.push("");
+  lines.push("Recommendations:");
+  for (const recommendation of report.recommendations) lines.push(`- ${recommendation}`);
+  return lines.join("\n");
+}
+
+function formatNativeWikiQueryResult(result: NativeWikiQueryResult) {
+  const lines = [`Optional human wiki query: ${result.query}`];
+  if (result.results.length === 0) {
+    lines.push("No matches. Try `gxpm wiki init` if the index is stale.");
+    return lines.join("\n");
+  }
+  lines.push("Source files:");
+  for (const r of result.results) {
+    lines.push(`- ${r.path}${r.line ? ` #L${r.line}` : ""}`);
+  }
+  if (result.suggestedDocs.length > 0) {
+    lines.push("Suggested human docs:");
+    for (const doc of result.suggestedDocs) lines.push(`- ${doc}`);
+  }
+  return lines.join("\n");
+}
+
+function formatNativeWikiIssueContext(result: NativeWikiIssueContext, artifactWritten: boolean) {
+  const lines = [
+    `Optional human wiki context: ${result.issueId}`,
+    `phase: ${result.phase} (current: ${result.currentPhase})`,
+    `query: ${result.query}`,
+  ];
+  if (result.artifactsUsed.length > 0) {
+    lines.push("Artifacts used:");
+    for (const artifact of result.artifactsUsed) lines.push(`- ${artifact.type}`);
+  }
+  if (result.results.length === 0) {
+    lines.push("No source files matched. Try `gxpm wiki update` if humans need refreshed docs.");
+  } else {
+    lines.push("Source files:");
+    for (const r of result.results) {
+      lines.push(`- ${r.path}${r.line ? ` #L${r.line}` : ""}`);
+    }
+  }
+  if (result.suggestedDocs.length > 0) {
+    lines.push("Suggested human docs:");
+    for (const doc of result.suggestedDocs) lines.push(`- ${doc}`);
+  }
+  if (artifactWritten) lines.push("Artifact written: wiki-context");
+  return lines.join("\n");
+}
+
+function wikiQueryText(argv: string[]) {
+  const values: string[] = [];
+  for (let index = 2; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "--json") continue;
+    if (arg === "--limit") {
+      index++;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const next = argv[index + 1];
+      if (next && !next.startsWith("--")) index++;
+      continue;
+    }
+    values.push(arg);
+  }
+  return values.join(" ").trim();
+}
+
+function assertNoUnexpectedWikiContextPositionals(argv: string[]) {
+  const optionsWithValues = new Set(["--phase", "--limit"]);
+  const flagOptions = new Set(["--json", "--write-artifact"]);
+  for (let index = 3; index < argv.length; index++) {
+    const arg = argv[index];
+    if (optionsWithValues.has(arg)) {
+      index++;
+      continue;
+    }
+    if (flagOptions.has(arg)) continue;
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown option for gxpm wiki context: ${arg}`);
+    }
+    throw new Error(WIKI_CONTEXT_USAGE);
+  }
+}