voidforge-build 23.19.0 → 23.21.0

package/dist/wizard/lib/marker.js

@@ -5,10 +5,12 @@
  * The CLI walks up from cwd to find it, determining the project root.
  */
 import { readFile, writeFile } from 'node:fs/promises';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, readFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
+/** Safe default when a marker omits `claudeMd`. Never silently clobber. */
+export const DEFAULT_CLAUDE_MD_STRATEGY = 'preserve';
 // ── Constants ────────────────────────────────────────────
 export const MARKER_FILE = '.voidforge';
 // ── Read / Write ─────────────────────────────────────────
@@ -31,13 +33,14 @@ export async function writeMarker(dir, marker) {
     const markerPath = join(dir, MARKER_FILE);
     await writeFile(markerPath, JSON.stringify(marker, null, 2) + '\n', 'utf-8');
 }
-export function createMarker(version, tier = 'full', extensions = []) {
+export function createMarker(version, tier = 'full', extensions = [], claudeMd = DEFAULT_CLAUDE_MD_STRATEGY) {
     return {
         id: randomUUID(),
         version,
         created: new Date().toISOString(),
         tier,
         extensions,
+        claudeMd,
     };
 }
 // ── Project Detection ────────────────────────────────────
@@ -89,6 +92,59 @@ export function requireProjectRoot(startDir = process.cwd()) {
     }
     return root;
 }
+/**
+ * Detect a legacy methodology consumer that predates the `.voidforge` marker.
+ *
+ * Such projects originally consumed methodology via git (before the marker
+ * convention) and so `update` hard-errors them toward `init` — which is the
+ * wrong remedy on an existing project (issue #369). The signature of a real
+ * consumer is the methodology footprint: `VERSION.md` + `.claude/commands/` +
+ * `docs/methods/` all present. When that holds and NO marker exists, the CLI
+ * should OFFER to create the marker rather than send the user to `init`.
+ *
+ * Tier is inferred from `wizard/` presence (full-tier projects embed/embedded
+ * the wizard), mirroring the workaround in the field report.
+ *
+ * Returns null when the dir already has a marker (not legacy) or does not look
+ * like a methodology consumer (genuinely not a VoidForge project).
+ */
+export function detectLegacyConsumer(dir = process.cwd()) {
+    const root = resolve(dir);
+    // If a valid marker is already present anywhere up the tree, it is not legacy.
+    if (findProjectRoot(root) !== null)
+        return null;
+    const hasVersion = existsSync(join(root, 'VERSION.md'));
+    const hasCommands = isDir(join(root, '.claude', 'commands'));
+    const hasMethods = isDir(join(root, 'docs', 'methods'));
+    if (!(hasVersion && hasCommands && hasMethods))
+        return null;
+    const inferredTier = isDir(join(root, 'wizard'))
+        ? 'full'
+        : 'methodology';
+    return { dir: root, inferredTier };
+}
+/** Read the methodology version from a project's VERSION.md, or 'unknown'. */
+export function readVersionFile(dir) {
+    const versionPath = join(resolve(dir), 'VERSION.md');
+    if (!existsSync(versionPath))
+        return 'unknown';
+    try {
+        const raw = readFileSync(versionPath, 'utf-8');
+        const match = raw.match(/(\d+\.\d+\.\d+)/);
+        return match ? match[1] : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function isDir(p) {
+    try {
+        return existsSync(p) && statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 // ── Global Config ────────────────────────────────────────
 export function getGlobalDir() {
     const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? homedir();

package/dist/wizard/lib/patterns/oauth-token-lifecycle.d.ts

@@ -8,6 +8,20 @@
  * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
  * - Token stored as encrypted blob in vault, keyed by platform name
  * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ * - VERIFY EXPIRY + REFRESH-GRANT BEHAVIOR AGAINST THE PROVIDER'S LIVE DOCS AT
+ *   INTEGRATION TIME. The PLATFORM_CONFIGS TTLs below are STARTING ASSUMPTIONS,
+ *   not ground truth — providers change them and "no refresh token / never
+ *   expires" is a common false assumption. Field report #373: a Todoist
+ *   integration shipped on "tokens don't expire," but the modern API issues
+ *   ~1h access tokens WITH a refresh token; the code discarded the refresh
+ *   token + expiry and registered no refresher, so it died ~1h after every
+ *   connect across four sessions — looking exactly like intermittent
+ *   revocation. At integration time: (1) read the provider's OAuth docs and
+ *   quote the verified access-token TTL + whether a refresh_token is issued;
+ *   (2) if a refresh_token exists, PERSIST it and register a refresher — never
+ *   discard it; (3) distinguish "expired" from "revoked" via the API's OWN
+ *   error body, not by inference (an expired token that mimics revocation will
+ *   send you reauth-hunting instead of refreshing).
  *
  * Agents: Breeze (platform relations), Dockson (vault)
  *

package/dist/wizard/lib/patterns/oauth-token-lifecycle.js

@@ -8,11 +8,32 @@
  * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
  * - Token stored as encrypted blob in vault, keyed by platform name
  * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ * - VERIFY EXPIRY + REFRESH-GRANT BEHAVIOR AGAINST THE PROVIDER'S LIVE DOCS AT
+ *   INTEGRATION TIME. The PLATFORM_CONFIGS TTLs below are STARTING ASSUMPTIONS,
+ *   not ground truth — providers change them and "no refresh token / never
+ *   expires" is a common false assumption. Field report #373: a Todoist
+ *   integration shipped on "tokens don't expire," but the modern API issues
+ *   ~1h access tokens WITH a refresh token; the code discarded the refresh
+ *   token + expiry and registered no refresher, so it died ~1h after every
+ *   connect across four sessions — looking exactly like intermittent
+ *   revocation. At integration time: (1) read the provider's OAuth docs and
+ *   quote the verified access-token TTL + whether a refresh_token is issued;
+ *   (2) if a refresh_token exists, PERSIST it and register a refresher — never
+ *   discard it; (3) distinguish "expired" from "revoked" via the API's OWN
+ *   error body, not by inference (an expired token that mimics revocation will
+ *   send you reauth-hunting instead of refreshing).
  *
  * Agents: Breeze (platform relations), Dockson (vault)
  *
  * PRD Reference: §9.5 (token refresh strategy), §9.18 (vault session), §9.19.15
  */
+// ASSUMPTIONS, NOT GROUND TRUTH (field report #373). These TTLs and the
+// "refreshTokenTtlDays: 0 = never expires" entries are starting points. At
+// integration time, VERIFY each value against the provider's current OAuth
+// docs and the live token response (`expires_in`, presence of `refresh_token`)
+// — a provider that "doesn't expire" today may issue ~1h tokens tomorrow, and
+// a missing refresher then surfaces as recurring prod token-death that mimics
+// revocation. Treat any new platform here the same way before shipping.
 const PLATFORM_CONFIGS = [
     { platform: 'meta', accessTokenTtlHours: 1440, refreshTokenTtlDays: 0, refreshEndpoint: 'https://graph.facebook.com/v19.0/oauth/access_token' },
     { platform: 'google', accessTokenTtlHours: 1, refreshTokenTtlDays: 0, refreshEndpoint: 'https://oauth2.googleapis.com/token' },

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.21.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.21.0",
     "node-pty": "^1.2.0-beta.12",
     "ws": "^8.19.0"
   },