skillwiki 0.2.0-beta.3 → 0.2.0-beta.4

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { readFileSync } from "fs";
 import { Command } from "commander";
 
 // src/utils/output.ts
@@ -9,9 +10,14 @@ function printJson(r) {
 }
 function printHuman(r) {
   if (r.ok) {
-    process.stdout.write(`OK
+    if (typeof r.data === "object" && r.data !== null && "humanHint" in r.data) {
+      process.stdout.write(`${r.data.humanHint}
+`);
+    } else {
+      process.stdout.write(`OK
 ${formatData(r.data)}
 `);
+    }
   } else {
     process.stdout.write(`ERR ${r.error}
 ${r.detail !== void 0 ? formatData(r.detail) + "\n" : ""}`);
@@ -53,15 +59,19 @@ var ExitCode = {
   LINT_HAS_WARNINGS: 22,
   LINT_HAS_ERRORS: 23,
   ENV_WRITE_CONFLICT: 24,
-  NO_VAULT_CONFIGURED: 25
+  NO_VAULT_CONFIGURED: 25,
+  INVALID_CONFIG_KEY: 26,
+  CONFIG_WRITE_FAILED: 27,
+  DOCTOR_HAS_WARNINGS: 28,
+  DOCTOR_HAS_ERRORS: 29
 };
 
 // ../shared/src/json-output.ts
 function ok(data) {
   return { ok: true, data };
 }
-function err(error, detail) {
-  return detail === void 0 ? { ok: false, error } : { ok: false, error, detail };
+function err(error2, detail) {
+  return detail === void 0 ? { ok: false, error: error2 } : { ok: false, error: error2, detail };
 }
 
 // ../shared/src/schemas.ts
@@ -479,7 +489,8 @@ async function runOverlap(input) {
 import { join as join2 } from "path";
 
 // src/utils/dotenv.ts
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile4, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
+import { dirname as dirname2 } from "path";
 var WHITELIST = /* @__PURE__ */ new Set(["WIKI_PATH", "WIKI_LANG"]);
 async function parseDotenvFile(path) {
   let text;
@@ -502,6 +513,50 @@ async function parseDotenvFile(path) {
   }
   return out;
 }
+async function writeDotenv(filePath, entries, originalContent) {
+  const lines = originalContent !== void 0 ? updateLines(originalContent, entries) : freshLines(entries);
+  await mkdir2(dirname2(filePath), { recursive: true });
+  await writeFile2(filePath, lines.join("\n") + "\n", "utf8");
+}
+function freshLines(entries) {
+  const out = [];
+  for (const [key, value] of Object.entries(entries)) {
+    if (value !== void 0) out.push(`${key}=${value}`);
+  }
+  return out;
+}
+function updateLines(originalContent, entries) {
+  let rawLines = originalContent.split(/\r?\n/);
+  if (rawLines.length > 0 && rawLines[rawLines.length - 1] === "") {
+    rawLines = rawLines.slice(0, -1);
+  }
+  const keysToWrite = new Set(Object.keys(entries));
+  const out = [];
+  for (const line of rawLines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) {
+      out.push(line);
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+      out.push(line);
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    if (keysToWrite.has(key)) {
+      out.push(`${key}=${entries[key]}`);
+      keysToWrite.delete(key);
+    } else {
+      out.push(line);
+    }
+  }
+  for (const key of keysToWrite) {
+    const value = entries[key];
+    if (value !== void 0) out.push(`${key}=${value}`);
+  }
+  return out;
+}
 
 // src/utils/wiki-path.ts
 async function resolveInitTimePath(input) {
@@ -630,7 +685,7 @@ function simulateRemoval(adj, removed) {
 
 // src/commands/audit.ts
 import { readFile as readFile5, stat as stat2 } from "fs/promises";
-import { dirname as dirname2, resolve, join as join3 } from "path";
+import { dirname as dirname3, resolve, join as join3 } from "path";
 
 // src/parsers/citations.ts
 var FENCE2 = /```[\s\S]*?```/g;
@@ -657,7 +712,7 @@ async function runAudit(input) {
   if (!fm.ok) return { exitCode: ExitCode.INVALID_FRONTMATTER, result: fm };
   const split = splitFrontmatter(text);
   const body = split.ok ? split.data.body : text;
-  const vault = await findVaultRoot(dirname2(resolve(input.file)));
+  const vault = await findVaultRoot(dirname3(resolve(input.file)));
   if (!vault) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID") };
   const markers = extractCitationMarkers(body);
   const resolved = await Promise.all(markers.map(async (m) => {
@@ -688,7 +743,7 @@ async function findVaultRoot(start) {
       return cur;
     } catch {
     }
-    const parent = dirname2(cur);
+    const parent = dirname3(cur);
     if (parent === cur) return null;
     cur = parent;
   }
@@ -700,10 +755,10 @@ import { readdir as readdir2, stat as stat4 } from "fs/promises";
 import { join as join4 } from "path";
 
 // src/utils/install-fs.ts
-import { copyFile, mkdir as mkdir2, rename, writeFile as writeFile2, stat as stat3 } from "fs/promises";
-import { dirname as dirname3 } from "path";
+import { copyFile, mkdir as mkdir3, rename, writeFile as writeFile3, stat as stat3 } from "fs/promises";
+import { dirname as dirname4 } from "path";
 async function atomicCopyWithBackup(src, dst) {
-  await mkdir2(dirname3(dst), { recursive: true });
+  await mkdir3(dirname4(dst), { recursive: true });
   let backupPath = null;
   try {
     await stat3(dst);
@@ -721,9 +776,9 @@ async function atomicCopyWithBackup(src, dst) {
   return ok({ copied: true, backupPath });
 }
 async function writeManifest(path, m) {
-  await mkdir2(dirname3(path), { recursive: true });
+  await mkdir3(dirname4(path), { recursive: true });
   const enriched = { installed_at: (/* @__PURE__ */ new Date()).toISOString(), ...m };
-  await writeFile2(path, JSON.stringify(enriched, null, 2));
+  await writeFile3(path, JSON.stringify(enriched, null, 2));
 }
 
 // src/commands/install.ts
@@ -839,8 +894,8 @@ async function runLang(input) {
 }
 
 // src/commands/init.ts
-import { mkdir as mkdir3, readFile as readFile6, stat as stat5, writeFile as writeFile3 } from "fs/promises";
-import { join as join7, dirname as dirname4 } from "path";
+import { mkdir as mkdir4, readFile as readFile6, stat as stat5, writeFile as writeFile4 } from "fs/promises";
+import { join as join7, dirname as dirname5 } from "path";
 var DEFAULT_TAXONOMY = [
   "research",
   "comparison",
@@ -899,9 +954,9 @@ async function runInit(input) {
   }
   const created = [];
   try {
-    await mkdir3(target, { recursive: true });
+    await mkdir4(target, { recursive: true });
     for (const d of VAULT_DIRS) {
-      await mkdir3(join7(target, d), { recursive: true });
+      await mkdir4(join7(target, d), { recursive: true });
       created.push(d + "/");
     }
   } catch (e) {
@@ -913,7 +968,7 @@ async function runInit(input) {
   try {
     const schemaTpl = await readFile6(join7(input.templates, "SCHEMA.md"), "utf8");
     const schema = schemaTpl.replace("{{DOMAIN}}", input.domain).replace("{{WIKI_LANG}}", canonicalLang).replace("{{TAXONOMY_YAML}}", taxonomyYaml);
-    await writeFile3(join7(target, "SCHEMA.md"), schema, "utf8");
+    await writeFile4(join7(target, "SCHEMA.md"), schema, "utf8");
     created.push("SCHEMA.md");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "SCHEMA.md", message: String(e) }) };
@@ -921,7 +976,7 @@ async function runInit(input) {
   try {
     const idxTpl = await readFile6(join7(input.templates, "index.md"), "utf8");
     const idx = idxTpl.replace("{{INIT_DATE}}", today);
-    await writeFile3(join7(target, "index.md"), idx, "utf8");
+    await writeFile4(join7(target, "index.md"), idx, "utf8");
     created.push("index.md");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "index.md", message: String(e) }) };
@@ -929,17 +984,17 @@ async function runInit(input) {
   try {
     const logTpl = await readFile6(join7(input.templates, "log.md"), "utf8");
     const log = logTpl.replace(/\{\{INIT_DATE\}\}/g, today).replace("{{DOMAIN}}", input.domain).replace("{{WIKI_LANG}}", canonicalLang);
-    await writeFile3(join7(target, "log.md"), log, "utf8");
+    await writeFile4(join7(target, "log.md"), log, "utf8");
     created.push("log.md");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "log.md", message: String(e) }) };
   }
   try {
-    await mkdir3(dirname4(envPath), { recursive: true });
+    await mkdir4(dirname5(envPath), { recursive: true });
     const envBody = `WIKI_PATH=${target}
 WIKI_LANG=${canonicalLang}
 `;
-    await writeFile3(envPath, envBody, "utf8");
+    await writeFile4(envPath, envBody, "utf8");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: envPath, message: String(e) }) };
   }
@@ -1131,7 +1186,7 @@ async function runPagesize(input) {
 }
 
 // src/commands/log-rotate.ts
-import { readFile as readFile10, rename as rename2, writeFile as writeFile4, stat as stat6 } from "fs/promises";
+import { readFile as readFile10, rename as rename2, writeFile as writeFile5, stat as stat6 } from "fs/promises";
 import { join as join11 } from "path";
 var ENTRY_RE = /^## \[(\d{4})-\d{2}-\d{2}\]/gm;
 async function runLogRotate(input) {
@@ -1172,7 +1227,7 @@ Chronological action log. Newest entries last. Skill writes append entries; lint
 
 - Previous log moved to ${rotatedName}
 `;
-    await writeFile4(logPath, fresh, "utf8");
+    await writeFile5(logPath, fresh, "utf8");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { message: String(e) }) };
   }
@@ -1236,9 +1291,195 @@ async function runLint(input) {
   };
 }
 
+// src/commands/config.ts
+import { readFile as readFile11 } from "fs/promises";
+import { existsSync } from "fs";
+import { join as join12 } from "path";
+function validateKey(key) {
+  return key === "WIKI_PATH" || key === "WIKI_LANG";
+}
+function configPath(home) {
+  return join12(home, ".skillwiki", ".env");
+}
+async function runConfigGet(input) {
+  if (!validateKey(input.key)) {
+    return { exitCode: ExitCode.INVALID_CONFIG_KEY, result: err("INVALID_CONFIG_KEY", { key: input.key }) };
+  }
+  const map = await parseDotenvFile(configPath(input.home));
+  const value = map[input.key] ?? "";
+  return { exitCode: ExitCode.OK, result: ok({ key: input.key, value, humanHint: value }) };
+}
+async function runConfigSet(input) {
+  if (!validateKey(input.key)) {
+    return { exitCode: ExitCode.INVALID_CONFIG_KEY, result: err("INVALID_CONFIG_KEY", { key: input.key }) };
+  }
+  const filePath = configPath(input.home);
+  try {
+    let originalContent;
+    try {
+      originalContent = await readFile11(filePath, "utf8");
+    } catch {
+    }
+    const existing = originalContent !== void 0 ? await parseDotenvFile(filePath) : {};
+    const merged = { ...existing, [input.key]: input.value };
+    await writeDotenv(filePath, merged, originalContent);
+    return { exitCode: ExitCode.OK, result: ok({ key: input.key, value: input.value, written: true, humanHint: `${input.key}=${input.value}` }) };
+  } catch (e) {
+    return { exitCode: ExitCode.CONFIG_WRITE_FAILED, result: err("CONFIG_WRITE_FAILED", { key: input.key, error: String(e) }) };
+  }
+}
+async function runConfigList(input) {
+  const map = await parseDotenvFile(configPath(input.home));
+  const entries = Object.entries(map).map(([key, value]) => ({ key, value: value ?? "" }));
+  return { exitCode: ExitCode.OK, result: ok({ entries, humanHint: entries.map((e) => `${e.key}=${e.value}`).join("\n") }) };
+}
+async function runConfigPath(input) {
+  const filePath = configPath(input.home);
+  return { exitCode: ExitCode.OK, result: ok({ path: filePath, exists: existsSync(filePath), humanHint: filePath }) };
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync2, readdirSync, statSync } from "fs";
+import { join as join13 } from "path";
+import { execSync } from "child_process";
+function pass(id, label, detail) {
+  return { id, label, status: "pass", detail };
+}
+function warn(id, label, detail) {
+  return { id, label, status: "warn", detail };
+}
+function error(id, label, detail) {
+  return { id, label, status: "error", detail };
+}
+function checkNodeVersion() {
+  const major = parseInt(process.version.slice(1).split(".")[0], 10);
+  if (major >= 20) {
+    return pass("node_version", "Node.js version", `v${major} >= 20`);
+  }
+  return error("node_version", "Node.js version", `Node.js v${major} is below minimum v20`);
+}
+function checkCliOnPath(argv) {
+  if (argv.length >= 2 && argv[1].endsWith("cli.js")) {
+    return warn("cli_on_path", "skillwiki on PATH", "Running via node cli.js (dev mode) \u2014 PATH check skipped");
+  }
+  if (argv.length >= 2 && argv[1] === "skillwiki") {
+    return pass("cli_on_path", "skillwiki on PATH", "Running as skillwiki \u2014 already on PATH");
+  }
+  try {
+    execSync("which skillwiki 2>/dev/null", { encoding: "utf8" }).trim();
+    return pass("cli_on_path", "skillwiki on PATH", "skillwiki found on PATH");
+  } catch {
+    return warn("cli_on_path", "skillwiki on PATH", "skillwiki not found on PATH");
+  }
+}
+async function checkConfigFile(home) {
+  const cfgPath = join13(home, ".skillwiki", ".env");
+  if (!existsSync2(cfgPath)) {
+    return warn("config_file", "Config file exists", `${cfgPath} not found`);
+  }
+  try {
+    const map = await parseDotenvFile(cfgPath);
+    const keys = Object.keys(map);
+    return pass("config_file", "Config file exists", `Found with keys: ${keys.length > 0 ? keys.join(", ") : "(none set)"}`);
+  } catch (e) {
+    return warn("config_file", "Config file exists", `Failed to parse ${cfgPath}: ${String(e)}`);
+  }
+}
+async function checkWikiPathSet(input) {
+  const r = await resolveRuntimePath({ flag: void 0, envValue: input.envValue, home: input.home });
+  if (r.ok) {
+    return pass("wiki_path_set", "WIKI_PATH configured", `Resolved via ${r.data.source}: ${r.data.path}`);
+  }
+  return error("wiki_path_set", "WIKI_PATH configured", "No vault configured. Run `skillwiki init` or pass --vault.");
+}
+function checkWikiPathExists(resolvedPath) {
+  if (resolvedPath === void 0) {
+    return error("wiki_path_exists", "Vault directory exists", "Cannot check \u2014 WIKI_PATH not resolved");
+  }
+  if (existsSync2(resolvedPath) && statSync(resolvedPath).isDirectory()) {
+    return pass("wiki_path_exists", "Vault directory exists", resolvedPath);
+  }
+  return error("wiki_path_exists", "Vault directory exists", `${resolvedPath} does not exist or is not a directory`);
+}
+function checkVaultStructure(resolvedPath) {
+  if (resolvedPath === void 0) {
+    return error("vault_structure", "Vault structure valid", "Cannot check \u2014 WIKI_PATH not resolved");
+  }
+  if (!existsSync2(resolvedPath)) {
+    return error("vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
+  }
+  const missing = [];
+  if (!existsSync2(join13(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  for (const dir of ["raw", "entities", "concepts", "meta"]) {
+    if (!existsSync2(join13(resolvedPath, dir))) missing.push(dir + "/");
+  }
+  if (missing.length === 0) {
+    return pass("vault_structure", "Vault structure valid", "All required files and directories present");
+  }
+  return error("vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")}`);
+}
+function checkSkillsInstalled(home) {
+  const skillsDir = join13(home, ".claude", "skills");
+  if (!existsSync2(skillsDir)) {
+    return warn("skills_installed", "Skills installed", `${skillsDir} not found`);
+  }
+  const found = findSkillMd(skillsDir);
+  if (found.length > 0) {
+    return pass("skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found`);
+  }
+  return warn("skills_installed", "Skills installed", "No SKILL.md files found in ~/.claude/skills/");
+}
+function findSkillMd(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name === "SKILL.md") {
+      results.push(join13(dir, entry.name));
+    } else if (entry.isDirectory()) {
+      results.push(...findSkillMd(join13(dir, entry.name)));
+    }
+  }
+  return results;
+}
+async function runDoctor(input) {
+  const checks = [];
+  checks.push(checkNodeVersion());
+  checks.push(checkCliOnPath(input.argv));
+  checks.push(await checkConfigFile(input.home));
+  const wikiPathCheck = await checkWikiPathSet(input);
+  checks.push(wikiPathCheck);
+  const resolved = await resolveRuntimePath({ flag: void 0, envValue: input.envValue, home: input.home });
+  const resolvedPath = resolved.ok ? resolved.data.path : void 0;
+  checks.push(checkWikiPathExists(resolvedPath));
+  checks.push(checkVaultStructure(resolvedPath));
+  checks.push(checkSkillsInstalled(input.home));
+  const summary = {
+    pass: checks.filter((c) => c.status === "pass").length,
+    warn: checks.filter((c) => c.status === "warn").length,
+    error: checks.filter((c) => c.status === "error").length
+  };
+  const exitCode = summary.error > 0 ? ExitCode.DOCTOR_HAS_ERRORS : summary.warn > 0 ? ExitCode.DOCTOR_HAS_WARNINGS : ExitCode.OK;
+  const statusIcon = { pass: "\u2713", warn: "\u26A0", error: "\u2717" };
+  const lines = checks.map((c) => {
+    const icon = statusIcon[c.status];
+    const padded = c.label.padEnd(24);
+    return `  ${icon} ${padded} ${c.detail}`;
+  });
+  lines.push("");
+  lines.push(`${summary.pass} pass \xB7 ${summary.warn} warn \xB7 ${summary.error} error`);
+  const humanHint = lines.join("\n");
+  return { exitCode, result: ok({ checks, summary, humanHint }) };
+}
+
 // src/cli.ts
+var pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
-program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version("0.2.0-beta.3");
+program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");
 function emit(r) {
   if (program.opts().human) printHuman(r.result);
@@ -1344,6 +1585,17 @@ program.command("lint [vault]").option("--days <n>", "stale threshold", (s) => p
     logThreshold: opts.logThreshold
   }));
 });
+var configCmd = program.command("config").description("manage skillwiki configuration");
+configCmd.command("get <key>").description("print the value of a config key").action(async (key) => emit(await runConfigGet({ key, home: process.env.HOME ?? "" })));
+configCmd.command("set <key> <value>").description("set a config key value").action(async (key, value) => emit(await runConfigSet({ key, value, home: process.env.HOME ?? "" })));
+configCmd.command("list").description("list all config key=value pairs").action(async () => emit(await runConfigList({ home: process.env.HOME ?? "" })));
+configCmd.command("path").description("print the config file path").action(async () => emit(await runConfigPath({ home: process.env.HOME ?? "" })));
+program.command("doctor").description("diagnose skillwiki setup issues").action(async () => emit(await runDoctor({
+  home: process.env.HOME ?? "",
+  envValue: process.env.WIKI_PATH,
+  envLang: process.env.WIKI_LANG,
+  argv: process.argv
+})));
 program.parseAsync(process.argv).catch((e) => {
   process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");
   process.exit(1);

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.4",
   "type": "module",
-  "bin": { "skillwiki": "dist/cli.js" },
-  "files": ["dist", "templates", "skills", "README.md"],
+  "bin": {
+    "skillwiki": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "skills",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsup && rm -rf ./skills && cp -r ../skills ./skills",
     "test": "vitest run",
@@ -23,5 +30,7 @@
     "typescript": "^5.7.0",
     "vitest": "^2.1.0"
   },
-  "engines": { "node": ">=20" }
+  "engines": {
+    "node": ">=20"
+  }
 }