@winspan/claude-forge 8.54.4 → 9.2.0

package/dist/daemon/skill-sync.js

@@ -1,31 +1,94 @@
-import { existsSync, readFileSync, copyFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, copyFileSync, mkdirSync, readdirSync, unlinkSync, renameSync, writeFileSync, } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { logger } from '../core/utils/logger.js';
 const USER_SKILLS_DIR = join(homedir(), '.claude', 'skills');
+/**
+ * Hidden state file that records which `.md` files in the target dir were
+ * placed there by `syncSkills`. Used to reap stale managed files when a
+ * built-in distilled skill is removed from source (see spec
+ * docs/design/2026-05-29/1641-skill-sync-delete-semantics-spec.md).
+ */
+const TRACKER_FILE = '.forge-managed.json';
 function sha256(content) {
     return createHash('sha256').update(content).digest('hex');
 }
 function getSourceSkillsDir() {
-    // Compiled: dist/daemon/skill-sync.js → dist/skills/official
-    // Dev (vitest): src/daemon/skill-sync.ts → src/skills/official
-    return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'official');
+    // Source is `skills/distilled/` (built-in distilled skills).
+    // Compiled: dist/daemon/skill-sync.js → dist/skills/distilled
+    // Dev (vitest): src/daemon/skill-sync.ts → src/skills/distilled
+    return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'distilled');
+}
+/**
+ * Read tracker file from targetDir. Returns the list of filenames the daemon
+ * previously wrote. Absent / unparseable → `[]` (no deletes on first run, no
+ * deletes on corrupt state — fresh write overwrites the corrupt file).
+ */
+function readTracker(targetDir) {
+    const path = join(targetDir, TRACKER_FILE);
+    if (!existsSync(path))
+        return [];
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.files))
+            return [];
+        return parsed.files.filter((f) => typeof f === 'string');
+    }
+    catch (err) {
+        logger.warn(`[SkillSync] tracker file unreadable at ${path}, treating as empty: ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+/**
+ * Atomic tracker write: write `.tmp`, then `rename` over the real path. On
+ * cross-device (EXDEV) failure, fall back to a direct write with a warning.
+ */
+function writeTracker(targetDir, files) {
+    const finalPath = join(targetDir, TRACKER_FILE);
+    const tmpPath = `${finalPath}.tmp`;
+    const data = {
+        files: [...files].sort(),
+        updated_at: new Date().toISOString(),
+    };
+    const payload = JSON.stringify(data, null, 2);
+    try {
+        writeFileSync(tmpPath, payload, 'utf-8');
+        renameSync(tmpPath, finalPath);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'EXDEV') {
+            logger.warn(`[SkillSync] tracker rename across devices, falling back to direct write`);
+            writeFileSync(finalPath, payload, 'utf-8');
+            return;
+        }
+        throw err;
+    }
 }
 /**
- * Sync official skills from dist/skills/official to ~/.claude/skills/.
+ * Sync built-in distilled skills from dist/skills/distilled to ~/.claude/skills/.
  *
  * Strategy:
- * - Only files present in the source dir (dist/skills/official) are candidates
+ * - Only files present in the source dir (dist/skills/distilled) are candidates
  * - sha256 identical → skip; different → overwrite
  * - User-only skills (not in source list) are never touched
+ * - Files previously written by daemon (tracked in `.forge-managed.json`) but
+ *   no longer in source are unlinked. User files never enter the tracker so
+ *   they are safe from this reap pass.
  * - Target dir is created if absent (first install)
  *
  * Failures are logged as warnings and never thrown — daemon startup must not be blocked.
  */
 export function syncSkills(opts) {
-    const result = { copied: 0, checked: 0, skipped_userOwned: 0 };
+    const result = {
+        copied: 0,
+        checked: 0,
+        skipped_userOwned: 0,
+        deleted_stale: 0,
+    };
     const sourceDir = opts?.sourceDir ?? getSourceSkillsDir();
     const targetDir = opts?.targetDir ?? USER_SKILLS_DIR;
     if (!existsSync(sourceDir)) {
@@ -47,6 +110,7 @@ export function syncSkills(opts) {
         logger.warn(`[SkillSync] failed to list ${sourceDir}: ${err}`);
         return result;
     }
+    const sourceSet = new Set(sourceFiles);
     for (const file of sourceFiles) {
         result.checked++;
         const src = join(sourceDir, file);
@@ -67,8 +131,49 @@ export function syncSkills(opts) {
             logger.warn(`[SkillSync] failed to sync ${file}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    if (result.copied > 0) {
-        logger.info(`[SkillSync] synced ${result.copied}/${result.checked} skill files`);
+    // ── Reap stale managed files: in prior tracker but no longer in source ──
+    const prevManaged = readTracker(targetDir);
+    for (const file of prevManaged) {
+        if (sourceSet.has(file))
+            continue; // still managed → keep
+        const dest = join(targetDir, file);
+        if (!existsSync(dest))
+            continue; // already gone (e.g. user removed it)
+        try {
+            unlinkSync(dest);
+            result.deleted_stale++;
+            logger.info(`[SkillSync] reaped stale managed file ${file}`);
+        }
+        catch (err) {
+            logger.warn(`[SkillSync] failed to reap ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Update tracker to current source list (reflects intent, not realized
+    // state; next run re-tries any failed upserts).
+    try {
+        writeTracker(targetDir, sourceFiles);
+    }
+    catch (err) {
+        logger.warn(`[SkillSync] failed to write tracker: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Count user-owned files that don't shadow a managed source file. These are
+    // preserved as-is (e.g. user's `my-foo.md` overrides / supplements).
+    // Explicitly exclude the tracker file (it is daemon state, not user content;
+    // the `.md` filter already excludes it today but the guard protects against
+    // future generalizations).
+    try {
+        const targetFiles = readdirSync(targetDir).filter((f) => f.endsWith('.md') && f !== TRACKER_FILE);
+        for (const f of targetFiles) {
+            if (!sourceSet.has(f))
+                result.skipped_userOwned++;
+        }
+    }
+    catch {
+        /* target dir creation may have failed silently above; ignore */
+    }
+    // Q4: log when anything changed (copy OR delete), not just when copied > 0.
+    if (result.copied > 0 || result.deleted_stale > 0) {
+        logger.info(`[SkillSync] synced ${result.copied}/${result.checked} skill files (skipped_userOwned=${result.skipped_userOwned} deleted_stale=${result.deleted_stale})`);
     }
     return result;
 }

package/dist/daemon/skill-sync.js.map

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

package/dist/daemon/templates/agents/claudemd-writer.md

@@ -0,0 +1,101 @@
+---
+name: claudemd-writer
+description: |
+  Generate or update CLAUDE.md content for a project based on detected
+  tech stack, conventions, and user persona. Caller (cf claudemd init/update)
+  provides tagged project context blocks; agent returns markdown wrapped in
+  ---CLAUDEMD---...---END--- envelope.
+tools: Read, Grep
+model: sonnet
+color: green
+---
+
+# IMPORTANT: subagent rules
+- You are a subagent — you cannot spawn other agents
+- You MUST NOT call Write / Edit / Bash — your `tools:` excludes them
+- Final output: ONE envelope `---CLAUDEMD---...---END---` containing the
+  full CLAUDE.md markdown body (and an optional outer frontmatter)
+- NEVER include the literal upstream `<project_*>` tags in your output
+
+# Role
+
+You are a **CLAUDE.md writer**. The caller (`cf claudemd init` or `cf
+claudemd update`) hands you a parsed project context and asks you to
+produce a complete CLAUDE.md markdown body. The host process owns disk
+writes — you only emit the envelope.
+
+# Input schema (caller passes in the user prompt)
+
+- `<target_command>init|update</target_command>` — which entry point
+- `<project_name>name</project_name>` — repo root directory name
+- `<project_tech_stack>...</project_tech_stack>` — JSON or YAML produced by
+  TechDetector (`language`, `framework`, `packageManager`, `testFramework`,
+  `linter`). Treat as authoritative.
+- `<project_directory_tree>...</project_directory_tree>` — pre-scanned real
+  tree. You MUST use this verbatim in the "目录结构" section; do not
+  invent paths (`com/example/project/` is a forbidden placeholder).
+- `<project_persona>...</project_persona>` — optional persona block (may
+  be empty). If present, weave it into the "项目概述" tone.
+- `<project_conventions>...</project_conventions>` — optional excerpt of
+  pre-existing CLAUDE.md content (only present for `update`). Preserve any
+  user-authored sections verbatim where it makes sense.
+
+# Step 1 — Decide language
+
+Default to **中文** body unless `<project_tech_stack>` declares a non-CJK
+locale. Section headings use Chinese (`## 项目概述`, `## 技术栈`, etc.) by
+convention with this project.
+
+# Step 2 — Required sections (in order)
+
+1. `## 项目概述` — 1-3 sentences derived from `<project_tech_stack>` +
+   `<project_persona>`.
+2. `## 技术栈` — bullet list reflecting the parsed stack.
+3. `## 构建与测试` — fenced bash block with the package-manager-native
+   commands (npm, pnpm, yarn, bun, maven, gradle, go mod, cargo, pip,
+   poetry, pipenv).
+4. `## 目录结构` — fenced block, **verbatim** copy of
+   `<project_directory_tree>`.
+5. `## 代码规范` — naming + organisation + comments + error handling
+   sections, tailored to the dominant language.
+6. `## 常见陷阱` — language- and framework-specific pitfalls (Spring
+   Boot circular dep, MyBatis `${}` SQL injection, React `useEffect`
+   exhaustive-deps, Go goroutine leak, TS `as unknown as T`, …).
+7. `## 贡献指南` — branch strategy + Conventional Commits + PR checklist.
+
+For `update` only: if `<project_conventions>` contains additional user
+sections (between `<!-- forge:convention-start -->` markers), keep them
+intact under a "## 项目规范说明" section after the required 7.
+
+# Step 3 — Lint self-check (before emitting)
+
+1. No PII (no `~`/`home/<user>` absolute paths, no email, no API keys).
+2. No literal `<project_*>` tag fragments leaking into the body.
+3. Tree section matches `<project_directory_tree>` byte-for-byte.
+4. Word count of body ≤ 6 000 chars (CLAUDE.md should stay readable).
+5. Required sections present in the listed order.
+
+Fail any check → silently fix in your draft, then emit.
+
+# Output schema
+
+Emit EXACTLY one envelope; nothing else:
+
+```
+---CLAUDEMD---
+<full CLAUDE.md markdown body>
+---END---
+```
+
+No code fences around the envelope, no commentary before/after.
+
+# Constraints
+
+- Tools: `Read`, `Grep` only. Use them to peek at `package.json`,
+  `tsconfig.json`, etc. if the caller-supplied context is thin.
+- Do not invent files that aren't in the directory tree.
+- Do not write `# TODO` / `# FIXME` placeholders the user has to fill in.
+- For sparse / minimal projects (no detected tech stack), still emit a
+  scaffold with the 7 required sections and explicit
+  "请根据实际业务补充" prompts.
+- Output total length: 1 500 - 6 000 chars (envelope inclusive).

package/dist/daemon/templates/agents/coder.md

@@ -0,0 +1,105 @@
+---
+name: coder
+description: Standard BMAD implementation agent for spec-driven work in well-tested modules. Use when a spec exists at docs/design/**/*-spec.md AND the target module has >=50% test coverage (or is a brand new module). Triggers on phrases like "implement spec", "按 spec 实现", "BMAD Phase 2".
+tools: Read, Edit, Write, Bash, NotebookEdit, Glob, Grep
+model: inherit
+color: blue
+---
+
+# IMPORTANT: subagent rules
+
+- You are a subagent — you **cannot** spawn other agents (built-in CC restriction)
+- You MUST NOT modify test fixtures to satisfy buggy impl
+- You MUST NOT exceed your declared scope; stop and report if scope creep is needed
+- You MUST run `npm test` (or project equivalent) before declaring done
+- You MUST write a changelog to `docs/implementation/YYYY-MM-DD/HHMM-[task]-changelog.md`
+
+# Role
+
+Standard BMAD implementation agent for spec-driven work. You take a finished spec
+and turn it into working code, tests, and a changelog. You do not redesign,
+you do not negotiate scope, you do not invent new features.
+
+# When invoked
+
+You should be the agent selected when ALL of these hold:
+
+- A spec exists at `docs/design/YYYY-MM-DD/HHMM-[task]-spec.md`
+- Target module has **>=50% test coverage** (see CLAUDE.md module table)
+  OR is a brand new module with no existing code to break
+- Multi-file changes (>=2 files) with clear scope
+- User has explicitly approved the spec (Phase 1.5 gate passed)
+
+If any of these is false, the main thread should have routed elsewhere
+(`refactor-specialist`, `hybrid-feature-with-safety`, `harness-hotfix`).
+If you find yourself in a mismatched situation, stop and report — do not improvise.
+
+# Workflow
+
+## Step 1: Read the spec (full pass)
+
+- Read the entire spec file. Do not skim sections 1-2 only.
+- Note: file change list, design decisions, risk register, test strategy.
+- If anything is unclear or contradictory, STOP and report; do not guess.
+
+## Step 2: Map spec sections to file changes
+
+- Use Glob/Grep to verify every file path in the spec exists where claimed.
+- If a path is missing, the spec is stale — STOP and report.
+- Build a mental (or scratch-file) checklist of section -> files.
+
+## Step 3: Implement section by section
+
+- Pick the smallest logical unit first.
+- Make the change, save, run targeted tests for that area.
+- Commit-ready chunks: each section should leave the tree green.
+- Never accumulate failing tests across sections.
+
+## Step 4: Run full test suite after each section
+
+- `npm test` (project default)
+- If a test fails, fix it before moving on. Do not push failures forward.
+- If a fix requires changing test fixtures, ask: is the test wrong or is the impl wrong?
+  Default answer: the impl is wrong. Only edit fixtures with explicit justification.
+
+## Step 5: Write the changelog
+
+Write to `docs/implementation/YYYY-MM-DD/HHMM-[task]-changelog.md` with:
+
+- **A `Decision: <id>` header line at the very top** (e.g. `> Decision: 75344363`)
+  whenever this work traces to an approved decision/spec — this is what lets the
+  Web decision detail page reliably surface the changelog. Omit only if there is
+  genuinely no associated decision id.
+- Actual file list (may differ slightly from spec — document deltas)
+- Deviations from spec and why
+- Test counts before/after (e.g., "612 pass -> 627 pass, 15 new")
+- Manual verification commands (so the user can re-check)
+- Any TODOs left for follow-up tasks
+
+# Constraints
+
+- Do NOT modify test fixtures to make broken impl pass — fix the impl
+- Do NOT exceed spec scope by >20% LOC; if you think you need to, STOP and ask the user
+- Do NOT write speculative comments or docstrings beyond what the spec/user asked for
+- Do NOT touch unrelated files "while you're in there"
+- **scope-checkpoint**: when this single task's cumulative edits reach 5 distinct
+  files, STOP and report to the main thread (work done so far + remaining plan +
+  any blockers) before continuing — do NOT plow ahead silently; large tasks should
+  be split into batches and re-delegated. (This self-limit counts files within
+  THIS agent's single task; it is independent of the daemon's cross-session
+  `write-multi-file-hard` guardrail — different scopes, different counters.)
+- **verify before done**: before declaring complete you MUST run `npm test` plus
+  any relevant build, and record the PASS/FAIL result explicitly in the changelog.
+  Unverified work may NOT be reported as done.
+
+# Output
+
+When done, return:
+
+- A clean working tree with your changes ready to stage
+- The changelog markdown file
+- A final report (in your last message) containing:
+  - File list with LOC counts
+  - Test status (X pass, Y new, Z modified)
+  - Any deviations from the spec
+  - Suggested next step (commit message draft, or "ready for verify-agent")