skillwiki 0.10.36 → 0.10.37

package/dist/cli.js

@@ -181,11 +181,19 @@ import { Command } from "commander";
 function printJson(r) {
   process.stdout.write(JSON.stringify(r) + "\n");
 }
-function printHuman(r) {
+function printHuman(r, opts = {}) {
   if (r.ok) {
     if (typeof r.data === "object" && r.data !== null && "humanHint" in r.data) {
-      process.stdout.write(`${r.data.humanHint}
+      const humanHint = r.data.humanHint;
+      if (!opts.detailHints?.length) {
+        process.stdout.write(`${humanHint}
 `);
+      } else {
+        const existingLines = new Set(humanHint.split("\n"));
+        const detailLines2 = opts.detailHints.filter((line) => !existingLines.has(line));
+        process.stdout.write(`${[humanHint, ...detailLines2].join("\n")}
+`);
+      }
     } else {
       process.stdout.write(`OK
 ${formatData(r.data)}
@@ -202,6 +210,45 @@ function formatData(d) {
   return JSON.stringify(d, null, 2);
 }
 
+// src/utils/lint-detail-hints.ts
+function lintDetailHints(data) {
+  const record = asRecord(data);
+  if (!record) return [];
+  const bySeverity = asRecord(record.by_severity);
+  if (bySeverity && Array.isArray(bySeverity.error)) {
+    return detailLines(bySeverity.error, false);
+  }
+  return Array.isArray(record.buckets) ? detailLines(record.buckets, true) : [];
+}
+function healthLintDetailHints(data) {
+  const record = asRecord(data);
+  const components = asRecord(record?.components);
+  const lint = asRecord(components?.lint);
+  return Array.isArray(lint?.buckets) ? detailLines(lint.buckets, true) : [];
+}
+function detailLines(buckets, requireErrorSeverity) {
+  const seen = /* @__PURE__ */ new Set();
+  const lines = [];
+  for (const bucket of buckets) {
+    const record = asRecord(bucket);
+    if (!record || requireErrorSeverity && record.severity !== "error") continue;
+    const name = nonEmptyBucketName(record);
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    lines.push(`detail: skillwiki lint --only ${name} --examples 3`);
+  }
+  return lines;
+}
+function nonEmptyBucketName(bucket) {
+  if (typeof bucket.kind !== "string" || !/^[a-z0-9_]+$/.test(bucket.kind)) return null;
+  if (typeof bucket.count === "number") return bucket.count > 0 ? bucket.kind : null;
+  if (Array.isArray(bucket.items)) return bucket.items.length > 0 ? bucket.kind : null;
+  return null;
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : null;
+}
+
 // src/utils/deprecation.ts
 import { readFileSync } from "fs";
 import { join } from "path";
@@ -9354,9 +9401,16 @@ var program = new Command();
 program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");
 async function emit(r, vault, opts) {
-  if (program.opts().human) printHuman(r.result);
-  else printJson(r.result);
+  if (program.opts().human) {
+    const detailHints = r.result.ok ? opts?.humanDetailHints?.(r.result.data) : void 0;
+    printHuman(r.result, { detailHints });
+  } else {
+    printJson(r.result);
+  }
   if (vault && opts?.postCommit !== false) await postCommit(vault, r.exitCode);
+  await new Promise((resolve6, reject) => {
+    process.stdout.write("", (error) => error ? reject(error) : resolve6());
+  });
   process.exit(r.exitCode);
 }
 function dirtyVolumeBlock(vault, command) {
@@ -9835,6 +9889,7 @@ projectionsCmd.command("repair-legacy [vault]").description("repair one supporte
 });
 program.command("lint [vault]").description("run all vault health checks").option("--days <n>", "stale threshold", (s) => parseInt(s, 10), 90).option("--lines <n>", "pagesize threshold", (s) => parseInt(s, 10), 200).option("--log-threshold <n>", "log rotation threshold", (s) => parseInt(s, 10), 500).option("--fix", "auto-fix supported lint violations").option("--only <bucket>", "run only the specified lint bucket").option("--summary", "emit bounded bucket counts instead of full item arrays", false).option("--examples <n>", "example count per bucket in summary mode", (s) => parseInt(s, 10), 3).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
+  const humanDetailHints = opts.only ? void 0 : lintDetailHints;
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else if (opts.fix && opts.summary) return emitGuardedVaultWrite(
     v.vault,
@@ -9849,7 +9904,8 @@ program.command("lint [vault]").description("run all vault health checks").optio
       only: opts.only,
       summary: true,
       examplesLimit: opts.examples
-    })
+    }),
+    { humanDetailHints }
   );
   else if (opts.fix) return emitGuardedVaultWrite(
     v.vault,
@@ -9863,7 +9919,8 @@ program.command("lint [vault]").description("run all vault health checks").optio
       fix: true,
       only: opts.only,
       summary: false
-    })
+    }),
+    { humanDetailHints }
   );
   else if (opts.summary) emit(await runLint({
     vault: v.vault,
@@ -9875,7 +9932,7 @@ program.command("lint [vault]").description("run all vault health checks").optio
     only: opts.only,
     summary: true,
     examplesLimit: opts.examples
-  }), v.vault);
+  }), v.vault, { humanDetailHints });
   else emit(await runLint({
     vault: v.vault,
     source: vault ? "flag" : void 0,
@@ -9884,7 +9941,7 @@ program.command("lint [vault]").description("run all vault health checks").optio
     logThreshold: opts.logThreshold,
     fix: false,
     only: opts.only
-  }), v.vault);
+  }), v.vault, { humanDetailHints });
 });
 program.command("health [vault]").description("bounded whole-system wiki health report").option("--wiki <name>", "wiki profile name").option("--sync <mode>", "vault-sync policy: optional|required|off", "optional").option("--no-fail", "always exit 0 while reporting status in JSON").option("--out <path>", "write JSON result envelope to this path").option("--examples <n>", "example count per lint bucket", (s) => parseInt(s, 10), 3).action(async (vault, opts) => {
   const sync = String(opts.sync ?? "optional");
@@ -9905,7 +9962,7 @@ program.command("health [vault]").description("bounded whole-system wiki health
     noFail: opts.fail === false,
     out: opts.out,
     examplesLimit: opts.examples
-  }), void 0, { postCommit: false });
+  }), void 0, { postCommit: false, humanDetailHints: healthLintDetailHints });
 });
 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 ?? "" })));

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.36",
+  "version": "0.10.37",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 19 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.36",
+  "version": "0.10.37",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 19 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.10.36",
+  "version": "0.10.37",
   "private": true,
   "files": [
     "wiki-*",