voidforge-build 23.19.0 → 23.20.0

package/dist/wizard/lib/project-init.js

@@ -141,6 +141,16 @@ async function copyMethodology(methodologyRoot, projectDir, core) {
         await chmodShellScripts(join(projectDir, 'scripts', 'surfer-gate'));
         await mergeSettingsHook(projectDir);
     }
+    // Context-meter status line (/contextmeter) — default-on. Ship the scripts AND wire
+    // the statusLine + UserPromptSubmit awareness hook into settings.json, the same way the
+    // surfer-gate hook is wired. Defaults: warn 80% / crit 92% (baked into the scripts).
+    // Opt out per project with `/contextmeter --uninstall`.
+    const statuslineSrc = join(methodologyRoot, 'scripts', 'statusline');
+    if (existsSync(statuslineSrc)) {
+        count += await copyDir(statuslineSrc, join(projectDir, 'scripts', 'statusline'));
+        await chmodShellScripts(join(projectDir, 'scripts', 'statusline'));
+        await mergeStatuslineSettings(projectDir);
+    }
     return count;
 }
 async function chmodShellScripts(dir) {
@@ -190,6 +200,55 @@ async function mergeSettingsHook(projectDir) {
     };
     await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
 }
+/**
+ * Wire the /contextmeter status line + awareness hook into settings.json (default-on).
+ * Mirrors mergeSettingsHook: set `statusLine` only when the project doesn't already have
+ * one (never clobber a user's), and append the UserPromptSubmit awareness hook unless an
+ * equivalent is already present (idempotent). Defaults (warn 80 / crit 92) live in the
+ * scripts, so the wired commands carry no env prefix.
+ */
+async function mergeStatuslineSettings(projectDir) {
+    const snippetPath = join(projectDir, 'scripts', 'statusline', 'settings-snippet.json');
+    const settingsPath = join(projectDir, '.claude', 'settings.json');
+    if (!existsSync(snippetPath))
+        return;
+    const snippet = JSON.parse(await readFile(snippetPath, 'utf-8'));
+    const snippetStatusLine = snippet?.statusLine;
+    const snippetUserPrompt = (snippet?.hooks?.UserPromptSubmit ?? []);
+    if (!snippetStatusLine && snippetUserPrompt.length === 0)
+        return;
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+        }
+        catch {
+            // Existing settings.json is unreadable — leave it alone.
+            return;
+        }
+    }
+    else {
+        await mkdir(join(projectDir, '.claude'), { recursive: true });
+    }
+    // statusLine: never clobber a project's existing one.
+    if (snippetStatusLine && !settings.statusLine) {
+        settings.statusLine = snippetStatusLine;
+    }
+    // UserPromptSubmit: append the awareness hook unless an equivalent is already present.
+    const existingHooks = (settings.hooks ?? {});
+    const existingUserPrompt = (existingHooks.UserPromptSubmit ?? []);
+    const alreadyHasMeter = existingUserPrompt.some((entry) => {
+        const hooks = (entry?.hooks ?? []);
+        return hooks.some((h) => typeof h?.command === 'string' && h.command.includes('context-awareness-hook'));
+    });
+    if (!alreadyHasMeter && snippetUserPrompt.length > 0) {
+        settings.hooks = {
+            ...existingHooks,
+            UserPromptSubmit: [...existingUserPrompt, ...snippetUserPrompt],
+        };
+    }
+    await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
 // ── Identity Injection ───────────────────────────────────
 async function injectIdentity(projectDir, config) {
     const claudePath = join(projectDir, 'CLAUDE.md');

package/dist/wizard/lib/updater.d.ts

@@ -2,17 +2,36 @@
  * Update mechanisms — methodology update (replaces /void git-fetch),
  * self-update, and extension update.
  */
+import type { ClaudeMdAction } from './claude-md-strategy.js';
 export interface UpdatePlan {
     added: string[];
     modified: string[];
     removed: string[];
     unchanged: number;
+    /** Non-destructive CLAUDE.md handling (issue #368). */
+    claudeMd?: {
+        action: ClaudeMdAction;
+        droppedSections: string[];
+        warnings: string[];
+        /** Side file written instead of CLAUDE.md, relative to project root. */
+        sideFile?: string;
+    };
 }
 export interface UpdateResult {
     applied: boolean;
     plan: UpdatePlan;
     newVersion: string;
 }
+export type UpdateMode = 'help' | 'self' | 'extensions' | 'methodology';
+/**
+ * Decide which `update` mode the given argv selects. Pure — no I/O, no exit.
+ *
+ * Help MUST win over every action flag (issue #368): `update --help` printed
+ * usage but the OLD router fell through and EXECUTED the (destructive) update.
+ * Centralizing the precedence here makes that ordering testable and keeps the
+ * CLI from re-introducing the bug.
+ */
+export declare function resolveUpdateMode(args: string[]): UpdateMode;
 /**
  * Diff methodology source against project files.
  * Returns a plan showing what would change.

package/dist/wizard/lib/updater.js

@@ -2,11 +2,29 @@
  * Update mechanisms — methodology update (replaces /void git-fetch),
  * self-update, and extension update.
  */
-import { readFile, readdir, cp } from 'node:fs/promises';
+import { readFile, readdir, cp, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
-import { readMarker, writeMarker } from './marker.js';
+import { readMarker, writeMarker, DEFAULT_CLAUDE_MD_STRATEGY } from './marker.js';
+import { planClaudeMdUpdate, UPSTREAM_SUFFIX } from './claude-md-strategy.js';
+/**
+ * Decide which `update` mode the given argv selects. Pure — no I/O, no exit.
+ *
+ * Help MUST win over every action flag (issue #368): `update --help` printed
+ * usage but the OLD router fell through and EXECUTED the (destructive) update.
+ * Centralizing the precedence here makes that ordering testable and keeps the
+ * CLI from re-introducing the bug.
+ */
+export function resolveUpdateMode(args) {
+    if (args.includes('--help') || args.includes('-h'))
+        return 'help';
+    if (args.includes('--self'))
+        return 'self';
+    if (args.includes('--extensions'))
+        return 'extensions';
+    return 'methodology';
+}
 // ── Methodology Source Resolution ────────────────────────
 async function resolveMethodologySource() {
     const dir = import.meta.dirname ?? new URL('.', import.meta.url).pathname;
@@ -47,6 +65,23 @@ async function collectFiles(dir, base = '') {
     }
     return files;
 }
+/**
+ * Compute the non-destructive CLAUDE.md plan for a project (issue #368).
+ * Reads the marker's `claudeMd` strategy (default 'preserve') and delegates the
+ * decision to the pure planner. Returns null only when there is no upstream
+ * CLAUDE.md to apply.
+ */
+async function planClaudeMd(sourceRoot, projectDir) {
+    const srcPath = join(sourceRoot, 'CLAUDE.md');
+    if (!existsSync(srcPath))
+        return null;
+    const upstream = await readFile(srcPath, 'utf-8');
+    const destPath = join(projectDir, 'CLAUDE.md');
+    const current = existsSync(destPath) ? await readFile(destPath, 'utf-8') : null;
+    const marker = await readMarker(projectDir);
+    const strategy = marker?.claudeMd ?? DEFAULT_CLAUDE_MD_STRATEGY;
+    return planClaudeMdUpdate(current, upstream, strategy);
+}
 /**
  * Diff methodology source against project files.
  * Returns a plan showing what would change.
@@ -68,9 +103,33 @@ export async function diffMethodology(projectDir) {
         { src: 'docs/patterns', dest: 'docs/patterns' },
         { src: 'scripts/thumper', dest: 'scripts/thumper' },
         { src: 'scripts/surfer-gate', dest: 'scripts/surfer-gate' },
+        // Context-meter status line + awareness hook (/contextmeter). Scripts propagate on
+        // update; activation (statusLine + UserPromptSubmit hook in settings.json) stays opt-in.
+        { src: 'scripts/statusline', dest: 'scripts/statusline' },
     ];
-    // Single files to compare
-    const singleFiles = ['CLAUDE.md', 'HOLOCRON.md', 'VERSION.md'];
+    // CLAUDE.md is handled via the non-destructive strategy mechanism (issue #368)
+    // — never the old "preserve first 10 lines, overwrite the rest" clobber.
+    const claudeMdPlan = await planClaudeMd(sourceRoot, projectDir);
+    if (claudeMdPlan) {
+        plan.claudeMd = {
+            action: claudeMdPlan.action,
+            droppedSections: claudeMdPlan.droppedSections,
+            warnings: claudeMdPlan.warnings,
+            sideFile: claudeMdPlan.sideFileContent !== null ? `CLAUDE.md${UPSTREAM_SUFFIX}` : undefined,
+        };
+        if (claudeMdPlan.action === 'unchanged' || claudeMdPlan.action === 'skip') {
+            plan.unchanged++;
+        }
+        else if (claudeMdPlan.action === 'side-file') {
+            // The side file is the only thing that changes; CLAUDE.md itself is untouched.
+            plan.modified.push(`CLAUDE.md${UPSTREAM_SUFFIX}`);
+        }
+        else {
+            plan.modified.push('CLAUDE.md');
+        }
+    }
+    // Other single files compare/copy verbatim (no special preservation needed).
+    const singleFiles = ['HOLOCRON.md', 'VERSION.md'];
     // Check single files
     for (const file of singleFiles) {
         const srcPath = join(sourceRoot, file);
@@ -83,21 +142,10 @@ export async function diffMethodology(projectDir) {
         else {
             const srcContent = await readFile(srcPath, 'utf-8');
             const destContent = await readFile(destPath, 'utf-8');
-            // Skip CLAUDE.md first 10 lines (project identity) when comparing
-            if (file === 'CLAUDE.md') {
-                const srcLines = srcContent.split('\n').slice(10).join('\n');
-                const destLines = destContent.split('\n').slice(10).join('\n');
-                if (srcLines !== destLines)
-                    plan.modified.push(file);
-                else
-                    plan.unchanged++;
-            }
-            else {
-                if (srcContent !== destContent)
-                    plan.modified.push(file);
-                else
-                    plan.unchanged++;
-            }
+            if (srcContent !== destContent)
+                plan.modified.push(file);
+            else
+                plan.unchanged++;
         }
     }
     // Check directories
@@ -153,24 +201,27 @@ export async function applyUpdate(projectDir) {
     if (plan.added.length === 0 && plan.modified.length === 0) {
         return { applied: false, plan, newVersion };
     }
+    // CLAUDE.md: apply the non-destructive strategy decision (issue #368).
+    // Never overwrite a customized CLAUDE.md in place. `preserve` writes a side
+    // file; `merge` replaces only the fenced block; `skip` does nothing.
+    const claudeMdPlan = await planClaudeMd(sourceRoot, projectDir);
+    const claudeMdDestPath = join(projectDir, 'CLAUDE.md');
+    if (claudeMdPlan) {
+        if (claudeMdPlan.claudeMdContent !== null) {
+            await writeFile(claudeMdDestPath, claudeMdPlan.claudeMdContent, 'utf-8');
+        }
+        if (claudeMdPlan.sideFileContent !== null) {
+            await writeFile(`${claudeMdDestPath}${UPSTREAM_SUFFIX}`, claudeMdPlan.sideFileContent, 'utf-8');
+        }
+    }
+    // The CLAUDE.md plan entries are handled above — exclude them from the
+    // generic verbatim copy loop so we don't double-write or clobber.
+    const claudeMdEntries = new Set(['CLAUDE.md', `CLAUDE.md${UPSTREAM_SUFFIX}`]);
     // Copy added + modified files
     const { mkdir } = await import('node:fs/promises');
     for (const file of [...plan.added, ...plan.modified]) {
-        // Special handling for CLAUDE.md: preserve project identity (first 10 lines)
-        if (file === 'CLAUDE.md') {
-            const srcContent = await readFile(join(sourceRoot, file), 'utf-8');
-            const destPath = join(projectDir, file);
-            if (existsSync(destPath)) {
-                const destContent = await readFile(destPath, 'utf-8');
-                const destIdentity = destContent.split('\n').slice(0, 10).join('\n');
-                const srcBody = srcContent.split('\n').slice(10).join('\n');
-                await import('node:fs/promises').then(fs => fs.writeFile(destPath, destIdentity + '\n' + srcBody, 'utf-8'));
-            }
-            else {
-                await cp(join(sourceRoot, file), destPath);
-            }
+        if (claudeMdEntries.has(file))
             continue;
-        }
         const srcPath = join(sourceRoot, file);
         const destPath = join(projectDir, file);
         const destDir = join(destPath, '..');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voidforge-build",
-  "version": "23.19.0",
+  "version": "23.20.0",
   "description": "From nothing, everything. A methodology framework for building with Claude Code.",
   "type": "module",
   "engines": {
@@ -45,7 +45,7 @@
     "@aws-sdk/client-rds": "^3.700.0",
     "@aws-sdk/client-s3": "^3.700.0",
     "@aws-sdk/client-sts": "^3.700.0",
-    "voidforge-build-methodology": "^23.19.0",
+    "voidforge-build-methodology": "^23.20.0",
     "node-pty": "^1.2.0-beta.12",
     "ws": "^8.19.0"
   },