@punk6529/playbook 0.2.4 → 0.2.8

package/README.md

@@ -24,7 +24,7 @@
   - `/playbook-advisor`：会话内主动顾问，自动按需查询知识库
   - `/playbook-query`：手动按标签检索经验
   - `/playbook-case`：引导式记录新 case，并更新索引
-- 一套稳定的 CLI 工作流（init / global init / update / query / promote / hit），便于持续演进而不破坏现有内容
+- 一套稳定的 CLI 工作流（init / global init / update / query / promote / show / hit / reindex），便于持续演进而不破坏现有内容
 
 ## 典型工作流
 
@@ -166,6 +166,16 @@ playbook query docker --json       # JSON 格式输出
 
 这个命令是 AI skill 的底层工具。`/playbook-advisor` 和 `/playbook-query` skill 在内部调用它来搜索知识库，节省 token 开销。
 
+### `playbook show`
+
+输出指定案例的完整内容。AI skill 用它查看案例详情（L2），无需知道文件路径。
+
+```bash
+playbook show case-001-docker-bind         # 输出案例文件内容
+```
+
+先查项目 INDEX，再查全局 INDEX，找到后输出对应文件内容到 stdout。
+
 ### `playbook hit`
 
 记录一次案例阅读命中，用于追踪案例的实际使用频率。
@@ -176,6 +186,17 @@ playbook hit case-001-docker-bind          # 记录一次命中
 
 AI advisor 每次阅读案例详情后自动调用。命中次数在 `playbook query` 输出中以 `hits:N` 显示，帮助识别高价值案例。
 
+### `playbook reindex`
+
+从文件 front matter 重建 INDEX.json。当 INDEX 被清空、损坏或需要同步时使用。
+
+```bash
+playbook reindex                   # 重建项目 INDEX
+playbook reindex --scope global    # 重建全局 INDEX
+```
+
+扫描 `cases/`、`patterns/`、`checklists/` 下的 `.md` 文件，解析 YAML front matter（title, tags, created），重建 INDEX.json。保留已有的 hits 统计。
+
 ## 错误处理
 
 - 未知命令或无效选项会给出可操作的提示信息

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punk6529/playbook",
-  "version": "0.2.4",
+  "version": "0.2.8",
   "description": "CLI for initializing and updating Playbook & Case workflows.",
   "main": "src/index.js",
   "bin": {

package/src/cli.js

@@ -1,11 +1,16 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
 const { CliError } = require("./errors");
-const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs } = require("./options");
+const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs, parseShowArgs, parseReindexArgs } = require("./options");
 const { initProject } = require("./commands/init-project");
 const { initGlobal } = require("./commands/global-init");
 const { updateProject } = require("./commands/update-project");
 const { queryIndex, aggregateTags, formatPlainText, formatJson, formatTagsOnly } = require("./commands/query");
 const { promoteEntries } = require("./commands/promote");
 const { hitEntry } = require("./commands/hit");
+const { showEntry } = require("./commands/show");
+const { reindexPlaybook } = require("./commands/reindex");
 const { printSummary } = require("./reporting");
 
 function usageText() {
@@ -18,6 +23,9 @@ function usageText() {
     "  playbook promote <entry-id...> [--force]",
     "  playbook promote --all [--force]",
     "  playbook hit <entry-id>",
+    "  playbook show <entry-id>",
+    "  playbook reindex [--scope project|global]",
+    "  playbook root [--scope project|global]",
     "",
     "Notes:",
     "  - `init` and `update` are project-scoped commands.",
@@ -178,6 +186,83 @@ function runHit(args, io) {
   return 0;
 }
 
+function showHelpText() {
+  return [
+    "Usage: playbook show <entry-id>",
+    "",
+    "Display the full content of a playbook entry.",
+    "Searches project INDEX first, then global INDEX.",
+    "",
+    "Options:",
+    "  -h, --help    Show this help",
+  ].join("\n");
+}
+
+function runShow(args, io) {
+  const options = parseShowArgs(args);
+  if (options.help) {
+    writeStdout(io, showHelpText());
+    return 0;
+  }
+
+  const result = showEntry(options);
+  writeStdout(io, result.content);
+  return 0;
+}
+
+function reindexHelpText() {
+  return [
+    "Usage: playbook reindex [options]",
+    "",
+    "Rebuild INDEX.json by scanning playbook files and reading front matter.",
+    "",
+    "Options:",
+    "  --scope X     Scope: project or global (default: project)",
+    "  -h, --help    Show this help",
+  ].join("\n");
+}
+
+function runReindex(args, io) {
+  const options = parseReindexArgs(args);
+  if (options.help) {
+    writeStdout(io, reindexHelpText());
+    return 0;
+  }
+
+  const result = reindexPlaybook(options);
+  writeStdout(io, `Reindexed ${result.scope}: ${result.count} ${result.count === 1 ? "entry" : "entries"} found.`);
+  return 0;
+}
+
+function runRoot(args, io) {
+  let scope = "project";
+  for (const arg of args) {
+    if (arg === "-h" || arg === "--help") {
+      writeStdout(io, "Usage: playbook root [--scope project|global]\n\nOutput the absolute path of the playbook directory.");
+      return 0;
+    }
+    if (arg === "--scope" || arg.startsWith("--scope=")) {
+      const value = arg === "--scope" ? args[args.indexOf(arg) + 1] : arg.slice("--scope=".length);
+      if (value === "global" || value === "project") scope = value;
+    }
+  }
+
+  if (scope === "global") {
+    const globalRoot = path.join(os.homedir(), ".playbook/repo");
+    if (!fs.existsSync(globalRoot)) {
+      throw new CliError("Global playbook not found. Run 'playbook global init' first.");
+    }
+    writeStdout(io, globalRoot);
+  } else {
+    const projectRoot = path.resolve("docs/playbook");
+    if (!fs.existsSync(projectRoot)) {
+      throw new CliError("Project playbook not found. Run 'playbook init' first.");
+    }
+    writeStdout(io, projectRoot);
+  }
+  return 0;
+}
+
 function runGlobal(args, io) {
   const subcommand = args[0];
   if (!subcommand) {
@@ -235,11 +320,23 @@ async function runCli(argv, io = process) {
       return runHit(argv.slice(1), io);
     }
 
+    if (command === "show") {
+      return runShow(argv.slice(1), io);
+    }
+
+    if (command === "reindex") {
+      return runReindex(argv.slice(1), io);
+    }
+
+    if (command === "root") {
+      return runRoot(argv.slice(1), io);
+    }
+
     if (command === "global") {
       return runGlobal(argv.slice(1), io);
     }
 
-    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query, promote, hit`);
+    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query, promote, hit, show, reindex, root`);
   } catch (error) {
     if (error instanceof CliError) {
       writeStderr(io, `Error: ${error.message}`);

package/src/commands/query.js

@@ -92,11 +92,28 @@ function formatPlainText(result) {
   return lines.join("\n");
 }
 
+function readTagsRegistry(tagsYmlPath) {
+  try {
+    const content = fs.readFileSync(tagsYmlPath, "utf8");
+    const ids = [];
+    for (const line of content.split("\n")) {
+      const match = line.match(/^\s*-\s*id:\s*(.+)/);
+      if (match) {
+        ids.push(match[1].trim());
+      }
+    }
+    return ids;
+  } catch {
+    return null;
+  }
+}
+
 function aggregateTags(options) {
   const { scope = "both", targetPath = "." } = options;
 
   const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
   const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
+  const tagsYmlPath = path.join(os.homedir(), ".playbook/repo/tags.yml");
 
   const tagCounts = {};
   let anyIndexFound = false;
@@ -125,6 +142,17 @@ function aggregateTags(options) {
     }
   }
 
+  // Merge tags.yml registry — ensures registered tags appear even with count 0
+  const registryTags = readTagsRegistry(tagsYmlPath);
+  if (registryTags) {
+    anyIndexFound = true;
+    for (const tag of registryTags) {
+      if (!(tag in tagCounts)) {
+        tagCounts[tag] = 0;
+      }
+    }
+  }
+
   if (!anyIndexFound) {
     return { tags: {}, found: false };
   }

package/src/commands/reindex.js

@@ -0,0 +1,98 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { CliError } = require("../errors");
+const { parseFrontMatter } = require("../frontmatter");
+
+const TYPE_DIRS = {
+  cases: "case",
+  patterns: "pattern",
+  checklists: "checklist",
+};
+
+function readIndex(indexPath) {
+  try {
+    const content = fs.readFileSync(indexPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function scanDir(baseDir) {
+  const entries = {};
+
+  for (const [dirName, type] of Object.entries(TYPE_DIRS)) {
+    const dirPath = path.join(baseDir, dirName);
+    if (!fs.existsSync(dirPath)) continue;
+
+    const files = fs.readdirSync(dirPath).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      const filePath = path.join(dirPath, file);
+      const content = fs.readFileSync(filePath, "utf8");
+      const fm = parseFrontMatter(content);
+
+      if (!fm.title) continue; // skip files without valid front matter
+
+      const id = file.replace(/\.md$/, "");
+      const relativePath = `${dirName}/${file}`;
+
+      entries[id] = {
+        type,
+        title: fm.title,
+        tags: fm.tags || [],
+        path: relativePath,
+        created: fm.created || new Date().toISOString().slice(0, 10),
+      };
+    }
+  }
+
+  return entries;
+}
+
+function reindexPlaybook(options) {
+  const { scope = "project", targetPath = "." } = options;
+
+  let baseDir;
+  let indexPath;
+
+  if (scope === "global") {
+    baseDir = path.join(os.homedir(), ".playbook/repo");
+    indexPath = path.join(baseDir, "INDEX.json");
+  } else {
+    baseDir = path.resolve(targetPath, "docs/playbook");
+    indexPath = path.join(baseDir, "INDEX.json");
+  }
+
+  if (!fs.existsSync(baseDir)) {
+    throw new CliError(
+      scope === "global"
+        ? "Global playbook not found. Run 'playbook global init' first."
+        : "Project playbook not found. Run 'playbook init' first."
+    );
+  }
+
+  // Read existing index to preserve hits
+  const oldIndex = readIndex(indexPath) || {};
+
+  // Scan files and build new index
+  const newEntries = scanDir(baseDir);
+
+  // Preserve hits from old index
+  for (const [id, entry] of Object.entries(newEntries)) {
+    if (oldIndex[id] && oldIndex[id].hits) {
+      entry.hits = oldIndex[id].hits;
+    }
+  }
+
+  // Write new index
+  fs.writeFileSync(indexPath, JSON.stringify(newEntries, null, 2) + "\n", "utf8");
+
+  return {
+    scope,
+    count: Object.keys(newEntries).length,
+    entries: newEntries,
+  };
+}
+
+module.exports = { reindexPlaybook, scanDir };

package/src/commands/show.js

@@ -0,0 +1,57 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { CliError } = require("../errors");
+
+function readIndex(indexPath) {
+  try {
+    const content = fs.readFileSync(indexPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function showEntry(options) {
+  const { entryId, targetPath = "." } = options;
+
+  const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
+  const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
+
+  // Try project first
+  const projectIndex = readIndex(projectIndexPath);
+  if (projectIndex && projectIndex[entryId]) {
+    const entryPath = projectIndex[entryId].path;
+    const fullPath = path.resolve(targetPath, "docs/playbook", entryPath);
+    const content = readFile(fullPath, entryId);
+    return { entryId, scope: "project", content };
+  }
+
+  // Fall back to global
+  const globalIndex = readIndex(globalIndexPath);
+  if (globalIndex && globalIndex[entryId]) {
+    const entryPath = globalIndex[entryId].path;
+    const fullPath = path.join(os.homedir(), ".playbook/repo", entryPath);
+    const content = readFile(fullPath, entryId);
+    return { entryId, scope: "global", content };
+  }
+
+  // Not found
+  if (!projectIndex && !globalIndex) {
+    throw new CliError("No INDEX.json found. Run 'playbook init' or 'playbook global init' first.");
+  }
+
+  throw new CliError(`Entry '${entryId}' not found in project or global INDEX.`);
+}
+
+function readFile(fullPath, entryId) {
+  try {
+    return fs.readFileSync(fullPath, "utf8");
+  } catch {
+    throw new CliError(`File not found for entry '${entryId}': ${fullPath}`);
+  }
+}
+
+module.exports = {
+  showEntry,
+};

package/src/frontmatter.js

@@ -0,0 +1,66 @@
+/**
+ * Parse YAML front matter from markdown content.
+ * Expects format:
+ * ---
+ * title: Some title
+ * tags: [tag1, tag2]
+ * created: 2026-02-01
+ * ---
+ * body content here
+ */
+function parseFrontMatter(content) {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith("---")) {
+    return { title: null, tags: null, created: null, body: content };
+  }
+
+  const endIndex = trimmed.indexOf("\n---", 3);
+  if (endIndex === -1) {
+    return { title: null, tags: null, created: null, body: content };
+  }
+
+  const fmBlock = trimmed.slice(4, endIndex);
+  const body = trimmed.slice(endIndex + 4).replace(/^\n/, "");
+
+  let title = null;
+  let tags = null;
+  let created = null;
+
+  for (const line of fmBlock.split("\n")) {
+    const stripped = line.trim();
+    if (!stripped || stripped.startsWith("#")) continue;
+
+    const colonIndex = stripped.indexOf(":");
+    if (colonIndex === -1) continue;
+
+    const key = stripped.slice(0, colonIndex).trim();
+    const value = stripped.slice(colonIndex + 1).trim();
+
+    if (key === "title") {
+      title = value;
+    } else if (key === "tags") {
+      tags = parseTagsValue(value);
+    } else if (key === "created") {
+      created = value;
+    }
+  }
+
+  return { title, tags, created, body };
+}
+
+function parseTagsValue(value) {
+  // Handle [tag1, tag2] format
+  const match = value.match(/^\[(.*)?\]$/);
+  if (match) {
+    if (!match[1] || !match[1].trim()) return [];
+    return match[1]
+      .split(",")
+      .map((t) => t.trim())
+      .filter(Boolean);
+  }
+  // Handle bare value as single tag
+  if (value) return [value];
+  return [];
+}
+
+module.exports = { parseFrontMatter };

package/src/options.js

@@ -240,11 +240,69 @@ function parseHitArgs(args) {
   return { help: false, entryId };
 }
 
+function parseShowArgs(args) {
+  for (const arg of args) {
+    if (arg === "-h" || arg === "--help") {
+      return { help: true };
+    }
+  }
+
+  const entryId = args[0];
+  if (!entryId || entryId.startsWith("-")) {
+    throw new CliError("playbook show requires an entry ID");
+  }
+
+  if (args.length > 1) {
+    throw new CliError("playbook show accepts exactly one entry ID");
+  }
+
+  return { help: false, entryId };
+}
+
+function parseReindexArgs(args) {
+  let scope = "project";
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === "-h" || arg === "--help") {
+      return { help: true };
+    }
+
+    if (arg === "--scope") {
+      const next = args[i + 1];
+      if (!next || !["project", "global"].includes(next)) {
+        throw new CliError("--scope must be one of: project, global");
+      }
+      scope = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--scope=")) {
+      const value = arg.slice("--scope=".length);
+      if (!["project", "global"].includes(value)) {
+        throw new CliError("--scope must be one of: project, global");
+      }
+      scope = value;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new CliError(`Unknown option for playbook reindex: ${arg}`);
+    }
+  }
+
+  return { help: false, scope };
+}
+
 module.exports = {
   parseProjectCommandArgs,
   parseGlobalInitArgs,
   parseQueryArgs,
   parsePromoteArgs,
   parseHitArgs,
+  parseShowArgs,
+  parseReindexArgs,
   parseToolsValue,
 };

package/templates/project/skills/playbook-advisor/SKILL.md

@@ -43,11 +43,12 @@ Review the titles in the output. Only proceed to Step 2 for entries whose titles
 
 ### Step 2 — Read specific cases (L2)
 
-For relevant entries only:
-- Project entries: read `docs/playbook/<path>`
-- Global entries: read `~/.playbook/repo/<path>`
+For relevant entries only, run:
+```bash
+playbook show <entry-id>
+```
 
-Do NOT read all matched entries. Only read the ones that look relevant based on title.
+This outputs the full content of the case file. Do NOT read all matched entries. Only show the ones that look relevant based on title.
 
 When multiple entries have similar titles, prefer entries with higher `hits` count — they have been used more often and are likely more effective.
 

package/templates/project/skills/playbook-case/SKILL.md

@@ -13,10 +13,11 @@ Use this skill when the user asks to create, review, or inspect case entries.
 - For new cases, enforce this guided flow:
   1. If the user has not provided a concrete problem statement, ask first:
      "你想把之前遇到的哪个问题沉淀为 case？请一句话描述。"
-  2. After problem statement is available, suggest tags from registry/index context first:
-     - Prefer project index: `docs/playbook/INDEX.json`
-     - Use global index only when relevant: `~/.playbook/repo/INDEX.json`
-     - Ask user to choose existing tags or explicitly confirm a new tag
+  2. After problem statement is available, get available tags by running:
+     ```bash
+     playbook query --tags-only
+     ```
+     Suggest relevant existing tags from the output. Ask user to choose existing tags or explicitly confirm a new tag.
   3. If scope is not confirmed, ask for scope confirmation:
      - default is `project`
      - use `global` only when user explicitly confirms
@@ -65,9 +66,51 @@ Format: `{type}-{NNN}-{slug}`
 - `NNN`: zero-padded 3-digit sequence number (check existing entries to determine next number)
 - `slug`: lowercase hyphenated descriptor derived from the title
 
+### Case File Format
+
+Case files MUST include YAML front matter with title, tags, and created:
+
+```markdown
+---
+title: OAuth token refresh race condition under concurrency
+tags: [auth, api]
+created: 2026-02-10
+---
+
+## Problem
+...
+
+## Context
+...
+
+## Solution
+...
+
+## Takeaway
+...
+```
+
+The front matter is the source of truth for metadata. INDEX.json is rebuilt from front matter via `playbook reindex`.
+
+### File Paths
+
+Write files to the correct location based on scope:
+
+- **Project scope:** case file → `<project-root>/docs/playbook/<path>`, INDEX → `<project-root>/docs/playbook/INDEX.json`
+- **Global scope:** case file → `~/.playbook/repo/<path>`, INDEX → `~/.playbook/repo/INDEX.json`
+
+**IMPORTANT:** Always use absolute paths when writing files. Do NOT use relative paths — the current working directory may not be the project root.
+
+Get the playbook directory first:
+```bash
+playbook root                   # project scope
+playbook root --scope global    # global scope
+```
+Then use the output to construct absolute paths, e.g. `<root>/cases/case-001-xxx.md` and `<root>/INDEX.json`.
+
 ### Draft Package Output
 
-When producing the draft package, output the INDEX entry as a ready-to-merge JSON snippet:
+When producing the draft package, output:
 
 ```
 **Entry ID:** case-001-oauth-token-race
@@ -84,3 +127,11 @@ Add this entry to INDEX.json:
   }
 }
 ```
+
+### Write Procedure
+
+After user confirms the draft:
+
+1. Write the case file to the scope-specific path
+2. Read the current INDEX.json, merge the new entry, write back
+3. Run `playbook hit <entry-id>` is NOT needed — hit is only for reads

package/templates/project/skills/playbook-query/SKILL.md

@@ -30,14 +30,15 @@ Output format (one line per match):
 (N matches: X project, Y global)
 ```
 
-### Expansion (L2): Read individual case files
+### Expansion (L2): Show entry content
 
 When the user asks to see details of a specific entry, or when you need full context for a task:
 
-- For project entries: read `docs/playbook/<path>` where `<path>` is from the query result
-- For global entries: read `~/.playbook/repo/<path>`
+```bash
+playbook show <entry-id>
+```
 
-Only expand entries that are actually needed. Do not read all matched entries at once.
+This outputs the full content of the entry file. Only expand entries that are actually needed. Do not show all matched entries at once.
 
 ### Edge Cases