@zentao-hub/cli 0.1.0

package/dist/registry.js

@@ -0,0 +1,42 @@
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+import { resolveWorkspace } from "./paths.js";
+export function registryPath(profile, workspace) {
+    return path.join(resolveWorkspace(profile, workspace), "repos.yaml");
+}
+export async function loadRegistry(profile, workspace) {
+    const file = registryPath(profile, workspace);
+    if (!existsSync(file))
+        return { products: {} };
+    const text = await fs.readFile(file, "utf8");
+    const parsed = (yaml.load(text) ?? {});
+    return { products: parsed.products ?? {} };
+}
+export async function saveRegistry(reg, profile, workspace) {
+    const file = registryPath(profile, workspace);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const text = yaml.dump(reg, { sortKeys: false, lineWidth: 120 });
+    await fs.writeFile(file, text, "utf8");
+}
+export function listEntries(reg, productId) {
+    return reg.products[String(productId)] ?? [];
+}
+export function addEntry(reg, productId, entry) {
+    const key = String(productId);
+    const entries = reg.products[key] ?? [];
+    const normalized = {
+        path: path.resolve(entry.path),
+        ...(entry.name ? { name: entry.name } : {}),
+        ...(entry.tags && entry.tags.length ? { tags: entry.tags } : {}),
+    };
+    if (entries.some((e) => path.resolve(e.path) === normalized.path)) {
+        reg.products[key] = entries;
+        return { added: false, entries };
+    }
+    const next = [...entries, normalized];
+    reg.products[key] = next;
+    return { added: true, entries: next };
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/util.d.ts

@@ -0,0 +1,27 @@
+export declare function copyFile(src: string, dest: string, opts?: {
+    overwrite?: boolean;
+}): Promise<"copied" | "skipped">;
+/**
+ * Delete a file if it exists. Returns "removed" / "missing" so callers can
+ * print symmetric output to install-style commands.
+ */
+export declare function removeFile(filePath: string): Promise<"removed" | "missing">;
+/**
+ * Remove a directory if it exists and is empty. Used by uninstall-* commands
+ * to tidy up empty `.githooks/` once the last hook is gone, without ever
+ * touching directories that still hold user files.
+ */
+export declare function removeIfEmpty(dirPath: string): Promise<boolean>;
+export declare function ensureExecutable(filePath: string): Promise<void>;
+export declare function isGitRepo(repoPath: string): boolean;
+export declare function git(repoPath: string, args: string[]): {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare function info(msg: string): void;
+export declare function warn(msg: string): void;

package/dist/util.js

@@ -0,0 +1,70 @@
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+export async function copyFile(src, dest, opts = {}) {
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    if (existsSync(dest) && !opts.overwrite)
+        return "skipped";
+    await fs.copyFile(src, dest);
+    return "copied";
+}
+/**
+ * Delete a file if it exists. Returns "removed" / "missing" so callers can
+ * print symmetric output to install-style commands.
+ */
+export async function removeFile(filePath) {
+    if (!existsSync(filePath))
+        return "missing";
+    await fs.unlink(filePath);
+    return "removed";
+}
+/**
+ * Remove a directory if it exists and is empty. Used by uninstall-* commands
+ * to tidy up empty `.githooks/` once the last hook is gone, without ever
+ * touching directories that still hold user files.
+ */
+export async function removeIfEmpty(dirPath) {
+    if (!existsSync(dirPath))
+        return false;
+    try {
+        await fs.rmdir(dirPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureExecutable(filePath) {
+    try {
+        await fs.chmod(filePath, 0o755);
+    }
+    catch {
+        // best-effort; on Windows chmod is a no-op
+    }
+}
+export function isGitRepo(repoPath) {
+    const r = spawnSync("git", ["-C", repoPath, "rev-parse", "--git-dir"], {
+        encoding: "utf8",
+    });
+    return r.status === 0;
+}
+export function git(repoPath, args) {
+    const r = spawnSync("git", ["-C", repoPath, ...args], { encoding: "utf8" });
+    return { status: r.status ?? -1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "CliError";
+    }
+}
+export function info(msg) {
+    process.stdout.write(`${msg}\n`);
+}
+export function warn(msg) {
+    process.stderr.write(`[warn] ${msg}\n`);
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@zentao-hub/cli",
+  "version": "0.1.0",
+  "description": "Helper CLI for @zentao-hub/mcp — registers the MCP server, installs slash commands / prompts (Claude Code, GitHub Copilot, Codex CLI), installs a commit-msg hook, and manages the bug hub + repos.yaml registry.",
+  "license": "MIT",
+  "author": "Deven Liu <iliudonghui@gmail.com>",
+  "keywords": [
+    "zentao",
+    "禅道",
+    "mcp",
+    "claude",
+    "claude-code",
+    "github-copilot",
+    "copilot-cli",
+    "codex",
+    "cli",
+    "slash-command",
+    "commit-msg-hook"
+  ],
+  "homepage": "https://github.com/devenliu/zentao-hub/tree/main/packages/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devenliu/zentao-hub.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/devenliu/zentao-hub/issues"
+  },
+  "type": "module",
+  "bin": {
+    "zentao-hub": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "@zentao-hub/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.14.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "clean": "tsc -b --clean && rm -rf dist tsconfig.tsbuildinfo"
+  }
+}

package/templates/.claude/commands/bug-analyze.md

@@ -0,0 +1,46 @@
+---
+description: Pull and analyze the context of a single ZenTao bug (no worktree, no changes to any repo). Useful for sizing / scheduling / reading screenshots.
+argument-hint: <bugId>
+---
+
+# ZenTao bug analysis (read-only)
+
+Runs only Phase 1 of /fix-bug.
+
+## Variables
+
+- `$WS`     = `zentao-hub workspace ${ZENTAO_PROFILE:+--profile "$ZENTAO_PROFILE"} --print-path` — the CLI handles the per-profile layout. **Only pass `--profile` when `$ZENTAO_PROFILE` is set**; when it's unset we deliberately omit the flag so the CLI falls back to the `"default"` field of `~/.zentao-hub/credentials.json` (otherwise the literal string `default` would override whatever profile the user configured as default).
+  Fallback when `zentao-hub` isn't on `$PATH`: `${ZENTAO_HUB:-$HOME/.zentao-hub}/<profile>`, where `<profile>` is `$ZENTAO_PROFILE` if set, else the `"default"` field of `credentials.json` (`python3 -c 'import json,os; print(json.load(open(os.path.expanduser("~/.zentao-hub/credentials.json")))["default"])' 2>/dev/null`), else literal `default`.
+- `$BUG_ID`  = `$1` (required)
+- `$BUG_DIR` = `$WS/bugs/$BUG_ID`
+
+## Steps
+
+### 1. Prep
+- `mkdir -p $WS/bugs`
+
+### 2. Pull context into `$BUG_DIR`
+- `mkdir -p $BUG_DIR/attachments`
+- `mcp__zentao__get_bug(bugId=$BUG_ID)` → write `$BUG_DIR/raw.json`, and produce a `description.md` summary (title / priority / severity / reporter / assignedTo / reproduction steps). For HTML→markdown rules, see [section 1.3 in fix-bug.md](fix-bug.md#bugsteps-html--markdown-conversion-rules).
+- `mcp__zentao__get_bug_history(bugId=$BUG_ID)` → write `history.md`
+- `mcp__zentao__download_bug_attachments(bugId=$BUG_ID, destDir="$BUG_DIR/attachments", includeInline=true)`. If `errors[]` is non-empty, tell the user.
+
+### 3. Analyze
+Read every local file (use Read directly on screenshots as images). Produce:
+
+- **Symptom**: what the user sees / repro conditions / blast radius
+- **Likely root cause** (at the business-logic level)
+- **Code leads**: keywords / file names / function names that future-you should grep for when actually fixing
+- **Unknowns / things to clarify**: list them explicitly
+- **Difficulty estimate**: a rough S / M / L plus a guess at which repos / modules will need to change
+
+Write the analysis to `$BUG_DIR/analysis.md` and print a summary to the user.
+
+### 4. Wrap up
+- No worktree creation, no repository changes
+- Do NOT call `mcp__zentao__resolve_bug`
+- Keep `$BUG_DIR` around — when you later run `/fix-bug $productId $BUG_ID` it will be reused (avoids re-downloading)
+
+## When to upgrade to /fix-bug
+
+If you decide to fix it: run `/fix-bug <productId> $BUG_ID`. Phase 1 detects that `$BUG_DIR` already exists, skips the download, and continues from the analysis step.

package/templates/.claude/commands/fix-bug.md

@@ -0,0 +1,193 @@
+---
+description: Pull a ZenTao bug, analyze in the workspace, confirm with the user, pick repositories, then open a worktree per repo to fix and squash-merge.
+argument-hint: [productId] [bugId?]
+---
+
+# ZenTao bug-fix flow (workspace + multi-repo + worktree)
+
+Run in the three phases below. At every ⏸ point **stop and wait for user confirmation**. Announce every git / file write command before running it.
+
+## Variables
+
+Resolve before running:
+
+- `$WS`         = `zentao-hub workspace ${ZENTAO_PROFILE:+--profile "$ZENTAO_PROFILE"} --print-path` — the CLI handles the per-profile layout. **Only pass `--profile` when `$ZENTAO_PROFILE` is set** (check with `printenv ZENTAO_PROFILE`); when it's unset we deliberately omit the flag so the CLI falls back to the `"default"` field of `~/.zentao-hub/credentials.json` (otherwise the literal string `default` would override whatever profile the user configured as default).
+  Fallback when `zentao-hub` isn't on `$PATH`: `${ZENTAO_HUB:-$HOME/.zentao-hub}/<profile>`, where `<profile>` is `$ZENTAO_PROFILE` if set, else the `"default"` field of `credentials.json` (`python3 -c 'import json,os; print(json.load(open(os.path.expanduser("~/.zentao-hub/credentials.json")))["default"])' 2>/dev/null`), else literal `default`.
+- `$BUG_ID`     = chosen bug id
+- `$BUG_DIR`    = `$WS/bugs/$BUG_ID`
+- `$REGISTRY`   = `$WS/repos.yaml`
+- For each chosen repository:
+  - `$REPO`     = repository root (absolute path)
+  - `$WORKTREE` = `$(dirname $REPO)/$(basename $REPO)-bug-$BUG_ID`
+  - `$BRANCH`   = `fix/bug-$BUG_ID`
+  - `$MAIN`     = main branch of that repo (detect via `git -C $REPO symbolic-ref --short refs/remotes/origin/HEAD`; fall back to `main` / `master` / `trunk`)
+
+Always pass `-C <repo|worktree>` to git so the non-persistent Bash cwd never causes confusion.
+
+---
+
+## Phase 1 — Bug context (does not depend on any repository)
+
+### 1.1 Prepare the workspace
+- `mkdir -p $WS/bugs`
+- Make sure `$WS` exists; create if missing.
+
+### 1.2 Pick a bug
+- If `$2` is not provided: `mcp__zentao__list_my_bugs(productId=$1, status=active, limit=20)`, display the top 10 sorted by `pri` ascending, and let the user pick.
+- If `$2` is provided: `$BUG_ID = $2`.
+
+### 1.3 Pull context into `$BUG_DIR` (idempotent)
+
+If `$BUG_DIR/raw.json` already exists (e.g. a previous `/bug-analyze` ran), tell the user and ask ⏸: reuse, or re-download? Default: reuse and skip to 1.4.
+
+Otherwise:
+- `mkdir -p $BUG_DIR/attachments`
+- `mcp__zentao__get_bug(bugId=$BUG_ID)` → write `$BUG_DIR/raw.json`; also produce `$BUG_DIR/description.md` containing: title, priority, severity, reporter, assignedTo, plus a "Reproduction steps" section converted from `bug.steps` HTML using the rules below.
+- `mcp__zentao__get_bug_history(bugId=$BUG_ID)` → write `$BUG_DIR/history.md` (comments and status changes ordered by time).
+- `mcp__zentao__download_bug_attachments(bugId=$BUG_ID, destDir="$BUG_DIR/attachments", includeInline=true)`. Report any failed files honestly to the user.
+
+#### `bug.steps` HTML → markdown conversion rules
+
+Apply these rules so the result is reliably readable:
+
+- `<img src=".../file-read-{id}.{ext}" ...>` → `![](attachments/inline/inline-N-<basename>)` (path aligned with how download_bug_attachments persists files; N follows in-text order)
+- `<br>` / `<br/>` → newline `\n`
+- `</p>`, `</div>`, `</li>` → newline `\n`
+- `<li ...>` → start-of-line `- ` (unordered list item)
+- `<li>` inside `<ol>` → start-of-line `1. `, etc. (ordered list item)
+- All other HTML tags → strip
+- HTML entities → decoded: `&nbsp;` → space, `&amp;` → `&`, `&lt;` → `<`, `&gt;` → `>`, `&quot;` → `"`
+- 3+ consecutive newlines → collapse to 2
+- Trim leading / trailing whitespace
+
+After this, the result should read as clean markdown with no residual tags.
+
+### 1.4 Analyze ⏸
+Read `description.md` + `history.md` + every attachment (Read screenshots directly as images). **Note: at this point you may not know yet which repository to change.** Focus the analysis on the bug itself:
+
+- **Symptom**: what the user sees / repro conditions / blast radius
+- **Likely root cause** (code-agnostic): business-logic step, data / config / API
+- **Code leads**: keywords / function names / file-name hints, to help match repositories in Phase 2
+- **Unknowns**: list them explicitly
+
+Write the analysis to `$BUG_DIR/analysis.md`.
+
+⏸ **Ask the user**: does the analysis look right? Anything to add?
+
+---
+
+## Phase 2 — Pick repositories
+
+### 2.1 Look up the registry
+- If `$REGISTRY` doesn't exist: either `cp $WS/repos.yaml.example $REGISTRY`, or create a minimal skeleton `{products: {}}` (the user may not have copied the example — be tolerant).
+- Parse the yaml with `python3 -c` (no extra deps):
+  ```bash
+  python3 -c "
+  import yaml, sys
+  with open('$REGISTRY') as f: data = yaml.safe_load(f) or {}
+  entries = (data.get('products') or {}).get($1) or []
+  for e in entries: print(e.get('name', ''), e.get('path', ''), ','.join(e.get('tags', [])))
+  "
+  ```
+- List the candidate repositories for this productId (name / path / tags).
+
+### 2.2 Let the user pick ⏸
+- If the registry has candidates → list them and let the user pick (**multi-select** — cross-repo bugs are common, e.g. frontend + backend).
+- No candidates / wants to add a new one → prompt for an absolute path.
+- For each selected path:
+  - Verify it's a git repo: `git -C <path> rev-parse --git-dir`
+  - Verify the working tree is clean: `git -C <path> status --porcelain` should be empty
+  - If either fails, stop and let the user clean up.
+- Write any newly-entered repos back to `$REGISTRY`:
+  ```bash
+  python3 << 'PYEOF'
+  import yaml
+  with open('$REGISTRY') as f: data = yaml.safe_load(f) or {}
+  data.setdefault('products', {}).setdefault($1, [])
+  # Append entries, dedup by path
+  existing = {e['path'] for e in data['products'][$1]}
+  for new_path in [...]:  # user-supplied
+      if new_path not in existing:
+          data['products'][$1].append({'path': new_path})
+  with open('$REGISTRY', 'w') as f: yaml.safe_dump(data, f, allow_unicode=True, sort_keys=False)
+  PYEOF
+  ```
+
+⏸ **Confirm the repository list** before moving to Phase 3.
+
+---
+
+## Phase 3 — Worktree + fix (loop per repository)
+
+For **each** chosen `$REPO`:
+
+### 3.1 Create the worktree
+- `git -C $REPO fetch origin` (skip if there is no origin)
+- Detect `$MAIN` and tell the user. If `$MAIN` is behind origin, suggest fast-forwarding first.
+- Check whether `$BRANCH` already exists; if so, stop and ask: reuse, delete and recreate, or rename.
+- `git -C $REPO worktree add -b $BRANCH $WORKTREE $MAIN`
+
+### 3.2 Fix plan ⏸
+Based on `$BUG_DIR/analysis.md` + the code in this repo (use Grep / Read), produce a plan specific to **this repository**:
+
+- File list to change + the approach
+- Blast radius / test coverage / risk
+- Cross-repo dependencies (e.g. frontend depends on a backend release first)
+
+⏸ **Ask the user**: does the plan look right?
+
+### 3.3 Apply changes (cwd = `$WORKTREE`)
+- Edit / Write the changes
+- Run tests and type checks (use the project's own commands)
+- After tests pass: `git -C $WORKTREE add -A && git -C $WORKTREE commit -m "<wip msg>"`. Multiple commits are fine.
+
+### 3.4 Squash merge ⏸
+- `git -C $REPO checkout $MAIN`
+- `git -C $REPO merge --squash $BRANCH`
+- On conflict, stop and let the user resolve manually; **do not auto-reset**.
+- Draft a commit message, **show it to the user, and only after confirmation submit via heredoc**:
+
+  ```
+  fix: #$BUG_ID <original bug title>
+
+  <one-line root cause>
+  <one-line fix>
+
+  Closes ZenTao bug $BUG_ID
+  ```
+
+- After committing, record the commit hash and repo name for wrap-up.
+
+---
+
+## Phase 4 — Wrap-up suggestions (**suggest only, do not auto-run**)
+
+Summarize the commit hash for every repository:
+
+```
+- venus-frontend: abc1234
+- venus-backend:  def5678
+```
+
+Based on user preference, optionally:
+
+- Push each repo: `git -C $REPO push origin $MAIN`
+- Mark the bug resolved in ZenTao:
+  ```
+  mcp__zentao__resolve_bug(
+    bugId=$BUG_ID,
+    resolution="fixed",
+    comment="Multi-repo fix:\n- venus-frontend: abc1234\n- venus-backend: def5678",
+    resolvedBuild="...",
+  )
+  ```
+- Remove each worktree: `git -C $REPO worktree remove $WORKTREE`
+- Delete the fix branch: `git -C $REPO branch -D $BRANCH`
+- Leave the bug context in `$BUG_DIR` (kept by default for future traceability); remove with `rm -rf $BUG_DIR` if desired.
+
+## Failure / cancel paths
+
+- Phase 1/2, user decides not to fix: optionally clean up an empty `$BUG_DIR`; touch no repositories.
+- Phase 3, tests cannot be made to pass in one repo: stop at that worktree, hand it back to the user; do not roll back the other repos already completed.
+- pre-commit hook fails: fix the underlying problem per the hook's message, then commit again; **do not** `--amend`, do not `--no-verify`.
+- squash merge conflict: stop, ask the user to resolve in the main checkout manually; once they say "continue", proceed with the commit step.

package/templates/.githooks/commit-msg

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Block AI signatures and validate the Conventional Commits header.
+# Enable with: git config core.hooksPath .githooks
+# (zentao install-hooks does this automatically)
+
+msg_file="$1"
+msg=$(cat "$msg_file")
+
+# 1) Block AI signatures / auto-generated markers
+if echo "$msg" | grep -qiE "(generated with claude|co-authored-by:[[:space:]]*claude|co-authored-by:[[:space:]]*.*noreply@anthropic|🤖|generated by ai|claude assisted|ai assisted)"; then
+  echo "ERROR: commit message contains an AI signature, blocked."
+  echo
+  echo "Matched fragment:"
+  echo "$msg" | grep -iE "(generated with claude|co-authored-by|🤖|AI|claude)" | head -3
+  echo
+  echo "Remove it and re-commit."
+  exit 1
+fi
+
+# 2) Conventional Commits header: <type>(<scope>)?: <subject>
+first_line=$(echo "$msg" | head -n 1)
+
+# Let Merge / Revert pass through
+if echo "$first_line" | grep -qE "^(Merge|Revert)"; then
+  exit 0
+fi
+
+if ! echo "$first_line" | grep -qE "^(feat|fix|docs|style|refactor|test|chore|perf|build|ci)(\([a-z0-9_-]+\))?!?: .+"; then
+  echo "ERROR: commit header does not match Conventional Commits."
+  echo
+  echo "Current: $first_line"
+  echo
+  echo "Expected: <type>(<scope>): <subject>"
+  echo "Allowed types: feat, fix, docs, style, refactor, test, chore, perf, build, ci"
+  echo "Example:       fix(auth): handle expired login token"
+  exit 1
+fi
+
+# 3) Optional: require every commit to carry a ZenTao bug reference [ZT#<id>].
+#    Disabled by default; uncomment to enforce.
+# if ! echo "$msg" | grep -qE "\[ZT#[0-9]+\]"; then
+#   echo "ERROR: commit message is missing the ZenTao bug reference [ZT#<id>]"
+#   echo "       Suggested placement: end of subject or in the body, e.g. fix(auth): handle expired login token [ZT#12345]"
+#   exit 1
+# fi
+
+exit 0

package/templates/CLAUDE.md

@@ -0,0 +1,86 @@
+# Project AI collaboration rules
+
+> Copied here by `zentao-hub install claude-md`, sitting next to `package.json` / `pyproject.toml` / etc.
+> Claude Code reads this file on startup as the collaboration contract for this repository.
+> Before relying on it, please fill in the "Code style" section with the conventions specific to this repo.
+
+## Bug-fixing workflow
+
+This project fixes ZenTao bugs through the slash commands from [zentao-hub](https://github.com/devenliu/zentao-hub) (installed globally, or via a local path). **Do not commit / push manually on the main branch.**
+
+Entry points:
+
+- `/bug-analyze <bugId>` — analyze only, no fix. Bug context lands in `<workspace>/bugs/<id>/`, where the workspace is the per-profile dir under `$ZENTAO_HUB` (or `~/.zentao-hub`).
+- `/fix-bug <productId> [bugId]` — full flow. **Automatically creates a worktree**, edits inside the worktree, then squash-merges back to the main branch.
+
+See the [@zentao-hub/cli README](https://github.com/devenliu/zentao-hub/blob/main/packages/cli/README.md) for the full design.
+
+## Commit conventions (enforced by `.githooks/commit-msg`)
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <subject>
+```
+
+- **type**: `feat` / `fix` / `docs` / `style` / `refactor` / `test` / `chore` / `perf` / `build` / `ci`
+- **scope**: module name (optional)
+- **subject**: imperative mood, no trailing period, kept short
+
+When fixing a bug, append a ZenTao reference in the body so it stays traceable:
+
+```
+fix(auth): handle expired login token
+
+Root cause: the interceptor did not handle 401.
+Fix: add refresh + retry in the response interceptor.
+
+Closes ZenTao bug 12345
+```
+
+> If the team wants every commit to carry a `[ZT#<id>]` marker, uncomment section 3 of `.githooks/commit-msg`.
+
+## Hard prohibitions (the hook will block these)
+
+- Do NOT add AI signatures to commit messages — `Co-Authored-By: Claude`, `🤖 Generated with`, or any equivalent.
+- Do NOT append phrases like "Generated by AI", "Claude-assisted", "AI-assisted".
+- Do NOT use `--no-verify` to bypass the hook (unless explicitly authorized with a clear reason).
+- Do NOT use `--amend` on commits that have already been pushed.
+
+## Test and commit cadence
+
+- Code changes must pass this repository's standard test / type-check commands (see "Test commands" below) before commit.
+- One commit, one clear goal — split into multiple commits if multiple goals are in play.
+- If a pre-commit hook fails: **fix the underlying problem and re-commit**, do not use `--no-verify` and do not `--amend`.
+
+## Test commands
+
+> Fill in based on this repository. Examples:
+
+```bash
+# Node.js
+npm test
+npm run typecheck
+
+# Python
+pytest
+mypy .
+
+# Go
+go test ./...
+
+# Rust
+cargo test
+```
+
+## Code style
+
+> Fill in based on this repository. Typical contents:
+>
+> - Location and conventions for ESLint / Prettier (or equivalent)
+> - Naming conventions (camelCase / snake_case / package structure)
+> - Test requirements (coverage thresholds, required test types)
+> - Module boundaries and dependency-injection conventions
+> - i18n and error-handling style
+
+(Delete the `>` quote block and replace with the real rules for this repo.)

package/templates/repos.yaml.example

@@ -0,0 +1,26 @@
+# zentao-hub repository registry — example
+#
+# Real file path: <HUB>/repos.yaml (gitignored).
+# Auto-created on the first /fix-bug run if missing, then appended as the user adds entries.
+# You can also edit it by hand — the structure is intentionally simple.
+#
+# Top level is productId (numeric) → list of repositories backing that product.
+# Per-entry fields:
+#   path  (required)  — absolute path to the repository root
+#   name  (optional)  — friendly name for the list UI; defaults to basename(path)
+#   tags  (optional)  — array of tags for matching bug content (frontend / backend / db / ...)
+
+products:
+  # Example: Venus2.0 (productId comes from list_products)
+  2:
+    - name: venus-frontend
+      path: /Users/you/projects/venus-fe
+      tags: [frontend, ui, electron]
+    - name: venus-backend
+      path: /Users/you/projects/venus-be
+      tags: [backend, api, python]
+
+  # Example: Guochuang
+  20:
+    - path: /Users/you/projects/guochuang
+      tags: [fullstack]