skillwiki 0.2.0-beta.4 → 0.2.0-beta.6

package/dist/cli.js

@@ -70,8 +70,8 @@ var ExitCode = {
 function ok(data) {
   return { ok: true, data };
 }
-function err(error2, detail) {
-  return detail === void 0 ? { ok: false, error: error2 } : { ok: false, error: error2, detail };
+function err(error, detail) {
+  return detail === void 0 ? { ok: false, error } : { ok: false, error, detail };
 }
 
 // ../shared/src/schemas.ts
@@ -491,14 +491,9 @@ import { join as join2 } from "path";
 // src/utils/dotenv.ts
 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;
-  try {
-    text = await readFile4(path, "utf8");
-  } catch {
-    return {};
-  }
+var CONFIG_KEYS = ["WIKI_PATH", "WIKI_LANG"];
+var _whitelist = new Set(CONFIG_KEYS);
+function parseDotenvText(text) {
   const out = {};
   for (const rawLine of text.split(/\r?\n/)) {
     const line = rawLine.trim();
@@ -507,12 +502,21 @@ async function parseDotenvFile(path) {
     if (eq <= 0) continue;
     const key = line.slice(0, eq).trim();
     const value = line.slice(eq + 1).trim();
-    if (!WHITELIST.has(key)) continue;
+    if (!_whitelist.has(key)) continue;
     if (value.length === 0) continue;
     out[key] = value;
   }
   return out;
 }
+async function parseDotenvFile(path) {
+  let text;
+  try {
+    text = await readFile4(path, "utf8");
+  } catch {
+    return {};
+  }
+  return parseDotenvText(text);
+}
 async function writeDotenv(filePath, entries, originalContent) {
   const lines = originalContent !== void 0 ? updateLines(originalContent, entries) : freshLines(entries);
   await mkdir2(dirname2(filePath), { recursive: true });
@@ -1296,7 +1300,7 @@ 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";
+  return CONFIG_KEYS.includes(key);
 }
 function configPath(home) {
   return join12(home, ".skillwiki", ".env");
@@ -1320,7 +1324,7 @@ async function runConfigSet(input) {
       originalContent = await readFile11(filePath, "utf8");
     } catch {
     }
-    const existing = originalContent !== void 0 ? await parseDotenvFile(filePath) : {};
+    const existing = originalContent !== void 0 ? parseDotenvText(originalContent) : {};
     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}` }) };
@@ -1342,71 +1346,58 @@ async function runConfigPath(input) {
 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 check(status, id, label, detail) {
+  return { id, label, status, 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 check("pass", "node_version", "Node.js version", `v${major} >= 20`);
   }
-  return error("node_version", "Node.js version", `Node.js v${major} is below minimum v20`);
+  return check("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");
+    return check("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");
+    return check("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");
+    return check("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");
+    return check("warn", "cli_on_path", "skillwiki on PATH", "skillwiki not found on PATH");
   }
 }
 async function checkConfigFile(home) {
-  const cfgPath = join13(home, ".skillwiki", ".env");
+  const cfgPath = configPath(home);
   if (!existsSync2(cfgPath)) {
-    return warn("config_file", "Config file exists", `${cfgPath} not found`);
+    return check("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)"}`);
+    return check("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)}`);
+    return check("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");
+    return check("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 check("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`);
+  return check("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");
+    return check("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");
+    return check("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");
@@ -1414,20 +1405,20 @@ function checkVaultStructure(resolvedPath) {
     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 check("pass", "vault_structure", "Vault structure valid", "All required files and directories present");
   }
-  return error("vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")}`);
+  return check("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`);
+    return check("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 check("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/");
+  return check("warn", "skills_installed", "Skills installed", "No SKILL.md files found in ~/.claude/skills/");
 }
 function findSkillMd(dir) {
   const results = [];
@@ -1451,9 +1442,12 @@ async function runDoctor(input) {
   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 });
+  if (resolved.ok) {
+    checks.push(check("pass", "wiki_path_set", "WIKI_PATH configured", `Resolved via ${resolved.data.source}: ${resolved.data.path}`));
+  } else {
+    checks.push(check("error", "wiki_path_set", "WIKI_PATH configured", "No vault configured. Run `skillwiki init` or pass --vault."));
+  }
   const resolvedPath = resolved.ok ? resolved.data.path : void 0;
   checks.push(checkWikiPathExists(resolvedPath));
   checks.push(checkVaultStructure(resolvedPath));
@@ -1593,7 +1587,6 @@ configCmd.command("path").description("print the config file path").action(async
 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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.6",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,7 +1,8 @@
 {
   "name": "skillwiki",
-  "version": "0.1.0",
-  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 10 prompt-only skills (wiki-* + proj-*) backed by the deterministic `skillwiki` CLI (8 subcommands, JSON-by-default).",
+  "version": "0.2.0-beta.6",
+  "skills": "./",
+  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 11 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI (8 subcommands, JSON-by-default).",
   "author": {
     "name": "karlorz",
     "url": "https://github.com/karlorz"

package/skills/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/hooks/run-hook.cmd

@@ -0,0 +1,43 @@
+: << 'CMDBLOCK'
+@echo off
+REM Cross-platform polyglot wrapper for hook scripts.
+REM On Windows: cmd.exe runs the batch portion, which finds and calls bash.
+REM On Unix: the shell interprets this as a script (: is a no-op in bash).
+REM
+REM Hook scripts use extensionless filenames (e.g. "session-start" not
+REM "session-start.sh") so Claude Code's Windows auto-detection -- which
+REM prepends "bash" to any command containing .sh -- doesn't interfere.
+
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+
+set "HOOK_DIR=%~dp0"
+
+REM Try Git for Windows bash in standard locations
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM Try bash on PATH
+where bash >nul 2>nul
+if %ERRORLEVEL% equ 0 (
+    bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM No bash found - exit silently
+exit /b 0
+CMDBLOCK
+
+# Unix: run the named script directly
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

package/skills/hooks/session-start

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# SessionStart hook for skillwiki plugin
+# Injects using-skillwiki SKILL.md content into every conversation.
+
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+skill_content=$(cat "${PLUGIN_ROOT}/using-skillwiki/SKILL.md" 2>/dev/null || echo "Error reading using-skillwiki skill")
+
+# Escape string for JSON embedding using bash parameter substitution.
+# Each ${s//old/new} is a single C-level pass.
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+skill_escaped=$(escape_for_json "$skill_content")
+session_context="<EXTREMELY_IMPORTANT>\nYou have skillwiki.\n\n**Below is the full content of your 'skillwiki:using-skillwiki' skill - your introduction to the skillwiki skills. For all other skills, use the 'Skill' tool:**\n\n${skill_escaped}\n</EXTREMELY_IMPORTANT>"
+
+# Uses printf instead of heredoc to work around bash 5.3+ heredoc hang.
+printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
+
+exit 0

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.6",
   "private": true,
-  "files": ["wiki-*", "proj-*", ".claude-plugin", "README.md"]
+  "files": ["wiki-*", "proj-*", "using-skillwiki", ".claude-plugin", "hooks", "README.md"]
 }

package/skills/using-skillwiki/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: using-skillwiki
+description: Invoke at session start or when knowledge-base tasks arise — maps all wiki-*/proj-* skills and teaches the skillwiki CLI workflow
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+</SUBAGENT-STOP>
+
+# using-skillwiki
+
+You have skillwiki — a project-aware Karpathy-style knowledge base for Claude Code.
+
+## When to Use These Skills
+
+Invoke a skillwiki skill when the user:
+- Wants to create, build, or start a vault/wiki/knowledge base
+- Mentions ingesting sources, reading URLs into notes, converting content
+- Asks to search, query, or find information in their vault
+- Wants a health check or lint on their vault
+- Mentions crystallizing a session into a note
+- Talks about project workspaces, ADRs, or distillation
+- Asks about their skillwiki configuration or setup health
+
+## Skill Map
+
+| Skill | When to Invoke |
+|-------|----------------|
+| `wiki-init` | Bootstrap a new vault — SCHEMA.md, index.md, log.md, ~/.skillwiki/.env |
+| `wiki-ingest` | Convert URLs, files, or pasted text into typed-knowledge pages |
+| `wiki-query` | Search the vault and synthesize an answer with ranked results |
+| `wiki-lint` | Vault health check (stale pages, oversized pages, log rotation) |
+| `wiki-crystallize` | Distill the current working session into a typed-knowledge page |
+| `wiki-audit` | Verify raw provenance references and source frontmatter integrity |
+| `proj-init` | Bootstrap a project workspace (README, requirements, architecture) |
+| `proj-work` | Open or run a work item under a project's work/ directory |
+| `proj-distill` | Distill project compound entries into vault concept pages |
+| `proj-decide` | Write an Architectural Decision Record (ADR) |
+
+## CLI Backbone
+
+All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
+
+Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`.
+
+Run `skillwiki doctor` to diagnose setup issues. Run `skillwiki config list` to see current configuration.
+
+## Typical Workflow
+
+1. **Init** (`wiki-init`) — create vault, set domain and taxonomy
+2. **Ingest** (`wiki-ingest`) — add sources, build pages
+3. **Query** (`wiki-query`) — search and synthesize answers
+4. **Lint** (`wiki-lint`) — periodic health checks
+5. **Crystallize** (`wiki-crystallize`) — save session insights as pages
+6. **Audit** (`wiki-audit`) — verify source integrity
+
+For longer-running project work, use `proj-init` → `proj-work` → `proj-distill` / `proj-decide`.