@punk6529/playbook 0.0.0 → 0.2.0

package/README.md

@@ -1,5 +1,137 @@
 # @punk6529/playbook
 
-Placeholder release to reserve the package name.
+结构化工程知识库 CLI —— 初始化、更新和查询项目 Playbook 资产。
 
-The real implementation will be published in a later version.
+## 安装
+
+```bash
+npm install -g @punk6529/playbook
+```
+
+或免安装直接运行：
+
+```bash
+npx @punk6529/playbook --help
+```
+
+## 命令
+
+```bash
+playbook init [path] [--tools all|none|codex,claude] [--force]
+playbook global init [--force]
+playbook update [path] [--tools all|none|codex,claude] [--force]
+playbook query [tags...] [--limit N] [--scope project|global|both] [--json] [--tags-only]
+```
+
+## 作用范围
+
+- `playbook init` 项目级：
+  - 创建 `docs/playbook/{cases,patterns,checklists}` 和 `docs/playbook/INDEX.json`
+  - 根据 `--tools` 参数写入 AI skill 模板：
+    - Codex: `.codex/skills/{playbook-query,playbook-case,playbook-advisor}/SKILL.md`
+    - Claude: `.claude/skills/{playbook-query,playbook-case,playbook-advisor}/SKILL.md`
+- `playbook global init` 全局级：
+  - 创建 `~/.playbook/repo/{cases,patterns,checklists}`
+  - 创建 `~/.playbook/repo/INDEX.json` 和 `~/.playbook/repo/tags.yml`
+  - 不支持 `--tools`
+- `playbook update` 项目级：
+  - 仅更新托管模板文件
+  - 不修改用户业务内容（如 case markdown 文件）
+- V1 暂不支持 `playbook global update`
+
+## Skill 交付
+
+CLI 为支持的 AI 工具（`codex`、`claude`）安装以下 skill：
+
+| Skill | 用途 |
+|-------|------|
+| `playbook-query` | 手动查询知识库 |
+| `playbook-case` | 引导式 case 创建 |
+| `playbook-advisor` | 主动知识应用（自动感知 tag，AI 自主查询） |
+
+CLI 只负责文件交付（`init`/`update`），skill 的运行时执行由宿主 AI 工具处理。
+
+## 冲突策略
+
+- `playbook init` 和 `playbook global init` 默认非破坏性：
+  - 有冲突的托管文件会跳过并报告为 `conflict`
+- `playbook update` 采用分级策略：
+  - skill 模板：内容不同时自动刷新
+  - `docs/playbook/INDEX.json`：保护不覆盖，除非使用 `--force`
+- 使用 `--force` 可强制覆盖受保护的托管文件
+
+## 查询命令
+
+`playbook query` 按 tag 搜索 INDEX.json 条目（OR 逻辑），同时搜索项目和全局范围。
+
+```bash
+playbook query docker env          # 匹配 "docker" 或 "env" 的条目
+playbook query                     # 所有条目
+playbook query --tags-only         # 仅输出 tag 概览：docker(3) env(5) ci(2)
+playbook query --scope project     # 仅项目范围
+playbook query --limit 0           # 不限数量
+playbook query docker --json       # JSON 格式输出
+```
+
+## 在 AI 中使用
+
+`playbook init` 之后，AI 工具中有三个 skill 可用：
+
+### 1. `/playbook-advisor` —— 主动知识顾问
+
+在会话开始时调用一次，AI 会自动加载 tag 感知，后续遇到相关问题时自主查询。
+
+**典型使用流程：**
+
+```
+你：/playbook-advisor
+AI：（自动执行 playbook query --tags-only）
+AI：已加载知识库标签：docker(3) env(5) react(2) ci(1)
+
+...（正常工作中）...
+
+AI：（遇到 Docker 端口绑定问题，发现与 "docker" tag 相关）
+AI：（自动执行 playbook query docker）
+AI：（发现 "case-001-docker-bind" 标题相关，读取该 case）
+AI：根据之前的经验，这个问题是因为 Docker 默认绑定 0.0.0.0，需要改为 127.0.0.1...
+```
+
+特点：用户触发一次，之后 AI 自主判断何时查询，无需人工干预。
+
+### 2. `/playbook-query` —— 手动知识查询
+
+用户主动搜索知识库时使用。
+
+```
+你：/playbook-query
+AI：请提供要搜索的 tag
+你：docker
+AI：找到以下条目：
+    [project] case-001-docker-bind  Docker bind address issue  docker,env
+    (1 match: 1 project)
+```
+
+### 3. `/playbook-case` —— 记录新 case
+
+解决问题后，用来记录经验到知识库。
+
+```
+你：/playbook-case
+AI：请描述遇到的问题...
+你：Next.js 部署到 Vercel 后 API 路由 404
+AI：（引导你填写 问题/原因/解决/教训 四个部分）
+AI：（生成 case 文件，更新 INDEX.json）
+```
+
+## 错误处理
+
+- 未知命令或无效选项会给出可操作的提示信息
+- 托管文件读写失败会包含源路径和原因
+
+## 打包说明
+
+发布前确认包内容：
+
+```bash
+npm pack --dry-run
+```

package/bin/playbook.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../src/cli");
+
+async function main() {
+  const exitCode = await runCli(process.argv.slice(2), process);
+  process.exitCode = exitCode;
+}
+
+main().catch((error) => {
+  process.stderr.write(`Unexpected error: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,18 +1,26 @@
 {
   "name": "@punk6529/playbook",
-  "version": "0.0.0",
-  "main": "index.js",
+  "version": "0.2.0",
+  "description": "CLI for initializing and updating Playbook & Case workflows.",
+  "main": "src/index.js",
+  "bin": {
+    "playbook": "bin/playbook.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test"
   },
-  "keywords": [],
+  "keywords": ["playbook", "knowledge-base", "cli", "ai-skills", "case-management"],
   "author": "",
   "license": "MIT",
-  "description": "Placeholder package. Real implementation coming soon.",
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    "index.js"
+    "bin",
+    "src",
+    "templates"
   ]
 }

package/src/cli.js

@@ -0,0 +1,171 @@
+const { CliError } = require("./errors");
+const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs } = 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 { printSummary } = require("./reporting");
+
+function usageText() {
+  return [
+    "Usage:",
+    "  playbook init [path] [--tools all|none|codex,claude] [--force]",
+    "  playbook global init [--force]",
+    "  playbook update [path] [--tools all|none|codex,claude] [--force]",
+    "  playbook query [tags...] [--limit N] [--scope project|global|both] [--json] [--tags-only]",
+    "",
+    "Notes:",
+    "  - `init` and `update` are project-scoped commands.",
+    "  - `global init` initializes ~/.playbook/repo and does not support --tools.",
+    "  - `query` searches INDEX.json by tags and returns matching entries.",
+    "  - V1 does not support `playbook global update`.",
+  ].join("\n");
+}
+
+function writeStdout(io, line) {
+  io.stdout.write(`${line}\n`);
+}
+
+function writeStderr(io, line) {
+  io.stderr.write(`${line}\n`);
+}
+
+function ensureNoHelpRequest(options, io) {
+  if (options.help) {
+    writeStdout(io, usageText());
+    return true;
+  }
+
+  return false;
+}
+
+function runInit(args, io) {
+  const options = parseProjectCommandArgs(args, "playbook init");
+  if (ensureNoHelpRequest(options, io)) {
+    return 0;
+  }
+
+  const result = initProject(options);
+  printSummary("playbook init completed", result.projectRoot, result.results, (line) =>
+    writeStdout(io, line)
+  );
+  return 0;
+}
+
+function runUpdate(args, io) {
+  const options = parseProjectCommandArgs(args, "playbook update");
+  if (ensureNoHelpRequest(options, io)) {
+    return 0;
+  }
+
+  const result = updateProject(options);
+  printSummary("playbook update completed", result.projectRoot, result.results, (line) =>
+    writeStdout(io, line)
+  );
+  return 0;
+}
+
+function queryHelpText() {
+  return [
+    "Usage: playbook query [tags...] [options]",
+    "",
+    "Search INDEX.json entries by tags (OR logic).",
+    "Without tags, returns all entries.",
+    "",
+    "Options:",
+    "  --limit N     Max results to return (default: 7, 0 = unlimited)",
+    "  --scope X     Search scope: project, global, or both (default: both)",
+    "  --json        Output results as JSON array",
+    "  --tags-only   Output only tag names with case counts",
+    "  -h, --help    Show this help",
+  ].join("\n");
+}
+
+function runQuery(args, io) {
+  const options = parseQueryArgs(args);
+  if (options.help) {
+    writeStdout(io, queryHelpText());
+    return 0;
+  }
+
+  if (options.tagsOnly) {
+    const result = aggregateTags(options);
+    writeStdout(io, formatTagsOnly(result));
+    return 0;
+  }
+
+  const result = queryIndex(options);
+  const output = options.json ? formatJson(result) : formatPlainText(result);
+  writeStdout(io, output);
+  return 0;
+}
+
+function runGlobal(args, io) {
+  const subcommand = args[0];
+  if (!subcommand) {
+    throw new CliError("Missing subcommand for `playbook global`. Supported: init");
+  }
+
+  if (subcommand === "update") {
+    throw new CliError(
+      "Unsupported command: `playbook global update` (V1). Use `playbook global init` or `playbook update`."
+    );
+  }
+
+  if (subcommand !== "init") {
+    throw new CliError(`Unknown command: playbook global ${subcommand}`);
+  }
+
+  const options = parseGlobalInitArgs(args.slice(1));
+  if (ensureNoHelpRequest(options, io)) {
+    return 0;
+  }
+
+  const result = initGlobal(options);
+  printSummary("playbook global init completed", result.globalRoot, result.results, (line) =>
+    writeStdout(io, line)
+  );
+  writeStdout(io, "Next: run `playbook init` inside a project to scaffold project assets.");
+  return 0;
+}
+
+async function runCli(argv, io = process) {
+  try {
+    if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+      writeStdout(io, usageText());
+      return 0;
+    }
+
+    const command = argv[0];
+    if (command === "init") {
+      return runInit(argv.slice(1), io);
+    }
+
+    if (command === "update") {
+      return runUpdate(argv.slice(1), io);
+    }
+
+    if (command === "query") {
+      return runQuery(argv.slice(1), io);
+    }
+
+    if (command === "global") {
+      return runGlobal(argv.slice(1), io);
+    }
+
+    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query`);
+  } catch (error) {
+    if (error instanceof CliError) {
+      writeStderr(io, `Error: ${error.message}`);
+      return error.exitCode;
+    }
+
+    writeStderr(io, `Unexpected error: ${error.message}`);
+    return 1;
+  }
+}
+
+module.exports = {
+  runCli,
+  usageText,
+};

package/src/commands/global-init.js

@@ -0,0 +1,31 @@
+const path = require("path");
+const { resolveGlobalRoot } = require("../core/context");
+const { GLOBAL_SKELETON_DIRS, GLOBAL_MANAGED_FILES } = require("../manifest");
+const { readTemplate } = require("../template-store");
+const { ensureDirectory, writeManagedFile } = require("../file-ops");
+
+function initGlobal(options) {
+  const globalRoot = resolveGlobalRoot();
+  const results = [];
+
+  for (const relativeDirectory of GLOBAL_SKELETON_DIRS) {
+    const directoryPath = path.join(globalRoot, relativeDirectory);
+    results.push(ensureDirectory(directoryPath));
+  }
+
+  for (const managedFile of GLOBAL_MANAGED_FILES) {
+    const targetPath = path.join(globalRoot, managedFile.relativePath);
+    const content = readTemplate(managedFile.templatePath);
+    results.push(writeManagedFile(targetPath, content, options.force));
+  }
+
+  return {
+    globalRoot,
+    results,
+  };
+}
+
+module.exports = {
+  initGlobal,
+  resolveGlobalRoot,
+};

package/src/commands/init-project.js

@@ -0,0 +1,30 @@
+const path = require("path");
+const { PROJECT_SKELETON_DIRS, getProjectManagedFiles } = require("../manifest");
+const { readTemplate } = require("../template-store");
+const { ensureDirectory, writeManagedFile } = require("../file-ops");
+
+function initProject(options) {
+  const projectRoot = path.resolve(options.targetPath);
+  const results = [];
+
+  for (const relativeDirectory of PROJECT_SKELETON_DIRS) {
+    const directoryPath = path.join(projectRoot, relativeDirectory);
+    results.push(ensureDirectory(directoryPath));
+  }
+
+  const managedFiles = getProjectManagedFiles(options.tools);
+  for (const managedFile of managedFiles) {
+    const targetPath = path.join(projectRoot, managedFile.relativePath);
+    const content = readTemplate(managedFile.templatePath);
+    results.push(writeManagedFile(targetPath, content, options.force));
+  }
+
+  return {
+    projectRoot,
+    results,
+  };
+}
+
+module.exports = {
+  initProject,
+};

package/src/commands/query.js

@@ -0,0 +1,172 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const DEFAULT_LIMIT = 7;
+
+function readIndex(indexPath) {
+  try {
+    const content = fs.readFileSync(indexPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function filterByTags(index, tags) {
+  const entries = [];
+  for (const [id, entry] of Object.entries(index)) {
+    if (tags.length === 0 || entry.tags.some((t) => tags.includes(t))) {
+      entries.push({ id, ...entry });
+    }
+  }
+  return entries;
+}
+
+function queryIndex(options) {
+  const { tags = [], limit = DEFAULT_LIMIT, scope = "both", targetPath = "." } = options;
+
+  const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
+  const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
+
+  let projectEntries = [];
+  let globalEntries = [];
+  let anyIndexFound = false;
+
+  if (scope === "both" || scope === "project") {
+    const projectIndex = readIndex(projectIndexPath);
+    if (projectIndex) {
+      anyIndexFound = true;
+      projectEntries = filterByTags(projectIndex, tags).map((e) => ({ ...e, scope: "project" }));
+    }
+  }
+
+  if (scope === "both" || scope === "global") {
+    const globalIndex = readIndex(globalIndexPath);
+    if (globalIndex) {
+      anyIndexFound = true;
+      globalEntries = filterByTags(globalIndex, tags).map((e) => ({ ...e, scope: "global" }));
+    }
+  }
+
+  const all = [...projectEntries, ...globalEntries];
+
+  if (!anyIndexFound) {
+    return { entries: [], found: false };
+  }
+
+  const limited = limit > 0 ? all.slice(0, limit) : all;
+
+  return { entries: limited, total: all.length, found: true };
+}
+
+function formatPlainText(result) {
+  if (!result.found) {
+    return "No playbook INDEX found.";
+  }
+
+  if (result.entries.length === 0) {
+    return "No matching entries.";
+  }
+
+  const lines = result.entries.map(
+    (e) => `[${e.scope}]\t${e.id}\t${e.title}\t${e.tags.join(",")}`
+  );
+
+  const displayed = result.entries.length;
+  const total = result.total;
+  const projectCount = result.entries.filter((e) => e.scope === "project").length;
+  const globalCount = result.entries.filter((e) => e.scope === "global").length;
+
+  const parts = [];
+  if (projectCount > 0) parts.push(`${projectCount} project`);
+  if (globalCount > 0) parts.push(`${globalCount} global`);
+
+  let summary = `(${total} match${total === 1 ? "" : "es"}`;
+  if (displayed < total) {
+    summary += `, showing ${displayed}`;
+  }
+  summary += `: ${parts.join(", ")})`;
+
+  lines.push(summary);
+  return lines.join("\n");
+}
+
+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 tagCounts = {};
+  let anyIndexFound = false;
+
+  function countTags(index) {
+    for (const entry of Object.values(index)) {
+      for (const tag of entry.tags) {
+        tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+      }
+    }
+  }
+
+  if (scope === "both" || scope === "project") {
+    const projectIndex = readIndex(projectIndexPath);
+    if (projectIndex) {
+      anyIndexFound = true;
+      countTags(projectIndex);
+    }
+  }
+
+  if (scope === "both" || scope === "global") {
+    const globalIndex = readIndex(globalIndexPath);
+    if (globalIndex) {
+      anyIndexFound = true;
+      countTags(globalIndex);
+    }
+  }
+
+  if (!anyIndexFound) {
+    return { tags: {}, found: false };
+  }
+
+  return { tags: tagCounts, found: true };
+}
+
+function formatTagsOnly(result) {
+  if (!result.found) {
+    return "No playbook INDEX found.";
+  }
+
+  const entries = Object.entries(result.tags);
+  if (entries.length === 0) {
+    return "No tags found.";
+  }
+
+  return entries.map(([tag, count]) => `${tag}(${count})`).join(" ");
+}
+
+function formatJson(result) {
+  if (!result.found) {
+    return JSON.stringify([]);
+  }
+
+  const output = result.entries.map((e) => ({
+    id: e.id,
+    scope: e.scope,
+    type: e.type,
+    title: e.title,
+    tags: e.tags,
+    path: e.path,
+  }));
+
+  return JSON.stringify(output, null, 2);
+}
+
+module.exports = {
+  queryIndex,
+  aggregateTags,
+  formatPlainText,
+  formatJson,
+  formatTagsOnly,
+  DEFAULT_LIMIT,
+};

package/src/commands/update-project.js

@@ -0,0 +1,30 @@
+const path = require("path");
+const { getProjectManagedFiles } = require("../manifest");
+const { readTemplate } = require("../template-store");
+const { writeManagedFile } = require("../file-ops");
+
+function updateProject(options) {
+  const projectRoot = path.resolve(options.targetPath);
+  const results = [];
+
+  const managedFiles = getProjectManagedFiles(options.tools);
+  for (const managedFile of managedFiles) {
+    const targetPath = path.join(projectRoot, managedFile.relativePath);
+    const content = readTemplate(managedFile.templatePath);
+    const defaultOverwrite = managedFile.overwriteOnUpdate === true;
+    const effectiveForce = options.force || defaultOverwrite;
+    const overwriteReason = !options.force && defaultOverwrite
+      ? "overwritten by default managed skill refresh"
+      : undefined;
+    results.push(writeManagedFile(targetPath, content, effectiveForce, overwriteReason));
+  }
+
+  return {
+    projectRoot,
+    results,
+  };
+}
+
+module.exports = {
+  updateProject,
+};

package/src/constants.js

@@ -0,0 +1,5 @@
+const SUPPORTED_TOOLS = ["codex", "claude"];
+
+module.exports = {
+  SUPPORTED_TOOLS,
+};

package/src/core/context.js

@@ -0,0 +1,24 @@
+const os = require("os");
+const path = require("path");
+const { CliError } = require("../errors");
+
+function resolveGlobalRoot() {
+  const home = os.homedir();
+  if (!home) {
+    throw new CliError("Cannot resolve home directory for global playbook path");
+  }
+
+  return path.join(home, ".playbook", "repo");
+}
+
+function resolveRuntimeContext(projectRoot = ".") {
+  return {
+    projectRoot: path.resolve(projectRoot),
+    globalRoot: resolveGlobalRoot(),
+  };
+}
+
+module.exports = {
+  resolveRuntimeContext,
+  resolveGlobalRoot,
+};

package/src/errors.js

@@ -0,0 +1,11 @@
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+module.exports = {
+  CliError,
+};