@punk6529/playbook 0.2.3 → 0.2.5

package/README.md

@@ -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`
 
 记录一次案例阅读命中，用于追踪案例的实际使用频率。

package/package.json

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

package/src/cli.js

@@ -1,11 +1,12 @@
 const { CliError } = require("./errors");
-const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs } = require("./options");
+const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs, parseShowArgs } = 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 { printSummary } = require("./reporting");
 
 function usageText() {
@@ -18,6 +19,7 @@ function usageText() {
     "  playbook promote <entry-id...> [--force]",
     "  playbook promote --all [--force]",
     "  playbook hit <entry-id>",
+    "  playbook show <entry-id>",
     "",
     "Notes:",
     "  - `init` and `update` are project-scoped commands.",
@@ -178,6 +180,30 @@ 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 runGlobal(args, io) {
   const subcommand = args[0];
   if (!subcommand) {
@@ -235,11 +261,15 @@ async function runCli(argv, io = process) {
       return runHit(argv.slice(1), io);
     }
 
+    if (command === "show") {
+      return runShow(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`);
   } catch (error) {
     if (error instanceof CliError) {
       writeStderr(io, `Error: ${error.message}`);

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/manifest.js

@@ -9,18 +9,6 @@ const PROJECT_MANAGED_FILES = [
     relativePath: "docs/playbook/INDEX.json",
     templatePath: "project/docs/playbook/INDEX.json",
   },
-  {
-    relativePath: "docs/playbook/cases/_example-001-delete-me.md",
-    templatePath: "project/docs/playbook/cases/_example-001-delete-me.md",
-  },
-  {
-    relativePath: "docs/playbook/patterns/_example-001-delete-me.md",
-    templatePath: "project/docs/playbook/patterns/_example-001-delete-me.md",
-  },
-  {
-    relativePath: "docs/playbook/checklists/_example-001-delete-me.md",
-    templatePath: "project/docs/playbook/checklists/_example-001-delete-me.md",
-  },
   {
     relativePath: ".codex/skills/playbook-query/SKILL.md",
     templatePath: "project/skills/playbook-query/SKILL.md",

package/src/options.js

@@ -240,11 +240,31 @@ 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 };
+}
+
 module.exports = {
   parseProjectCommandArgs,
   parseGlobalInitArgs,
   parseQueryArgs,
   parsePromoteArgs,
   parseHitArgs,
+  parseShowArgs,
   parseToolsValue,
 };

package/templates/global/INDEX.json

@@ -1,9 +1 @@
-{
-  "_example-001-delete-me": {
-    "type": "case",
-    "title": "Example entry — delete this and add real entries via playbook-case skill",
-    "tags": ["workflow"],
-    "path": "cases/_example-001-delete-me.md",
-    "created": "2026-01-01"
-  }
-}
+{}

package/templates/project/docs/playbook/INDEX.json

@@ -1,23 +1 @@
-{
-  "case-001-example-node-version-mismatch": {
-    "type": "case",
-    "title": "Deployment failed due to Node.js version mismatch",
-    "tags": ["env", "ci"],
-    "path": "cases/_example-001-delete-me.md",
-    "created": "2026-01-01"
-  },
-  "pattern-001-example-pin-runtime-versions": {
-    "type": "pattern",
-    "title": "Pin runtime versions before upgrading dependencies",
-    "tags": ["env", "workflow"],
-    "path": "patterns/_example-001-delete-me.md",
-    "created": "2026-01-01"
-  },
-  "checklist-001-example-pre-publish": {
-    "type": "checklist",
-    "title": "Pre-publish checklist",
-    "tags": ["workflow", "ci"],
-    "path": "checklists/_example-001-delete-me.md",
-    "created": "2026-01-01"
-  }
-}
+{}

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-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
 

package/templates/project/docs/playbook/cases/_example-001-delete-me.md

@@ -1,24 +0,0 @@
-# Deployment failed due to Node.js version mismatch
-
-> Delete this example file and create real cases using the playbook-case skill.
-
-## Problem
-
-Production deployment failed silently. The build succeeded locally but crashed on startup in CI with `SyntaxError: Unexpected token ??=`.
-
-## Context
-
-- Local dev environment: Node 20
-- CI runner: Node 16 (inherited from base image, not pinned)
-- The `??=` operator (logical nullish assignment) requires Node 15+
-- No `engines` field in package.json to catch this earlier
-
-## Solution
-
-1. Added `"engines": { "node": ">=20" }` to package.json
-2. Updated CI base image to `node:20-slim`
-3. Added `engine-strict=true` to `.npmrc` so mismatches fail fast on `npm install`
-
-## Takeaway
-
-Always pin the Node.js version in `engines` and enforce it. Silent version mismatches cause the worst kind of debugging — everything works locally.

package/templates/project/docs/playbook/checklists/_example-001-delete-me.md

@@ -1,10 +0,0 @@
-# Pre-publish checklist
-
-> Delete this example file and create real checklists using the playbook-case skill.
-
-- [ ] Run `npm pack --dry-run` and verify included files
-- [ ] Check `files` field in package.json matches intended contents
-- [ ] Verify version number is correct and not already published
-- [ ] Run full test suite: `npm test`
-- [ ] Check for accidentally included secrets or credentials
-- [ ] Confirm README is up to date with current API/usage

package/templates/project/docs/playbook/patterns/_example-001-delete-me.md

@@ -1,15 +0,0 @@
-# Pin runtime versions before upgrading dependencies
-
-> Delete this example file and create real patterns using the playbook-case skill.
-
-## When to Use
-
-Apply this pattern whenever you upgrade a major runtime (Node.js, Python, Ruby) or a core dependency that has runtime version requirements.
-
-## Pattern
-
-1. **Pin the current version first** — add `engines` field (Node), `python_requires` (Python), or equivalent before making any changes
-2. **Upgrade in CI first** — update the CI base image/config before changing local dev setup
-3. **Run full test suite against new version** — don't rely on local smoke tests
-4. **Update lockfile** — regenerate `package-lock.json` / `yarn.lock` under the new runtime
-5. **Communicate** — update README and onboarding docs with new version requirement