voidforge-build 23.11.1 → 23.11.2

package/dist/CHANGELOG.md

@@ -6,6 +6,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ---
 
+## [23.11.2] - 2026-05-12
+
+### `voidforge init` mode prompt + methodology surfer-gate distribution
+
+Two threads of polish: the CLI now asks before launching, and the Silver Surfer gate finally ships in the methodology npm package.
+
+### Added
+
+- **`voidforge init` mode prompt.** With no flag, `init` now asks "Browser wizard or CLI (headless)?" instead of silently launching the browser server. Prompt appears only when stdin is a TTY.
+- **`--browser` flag on `voidforge init`.** Explicit opt-in to the wizard UI — skips the prompt for users (or scripts) that want the prior default behavior.
+- **Interactive headless init.** `voidforge init --headless` now prompts for project name (required), directory (defaulted to `~/Projects/<slug>`), and optional oneliner/domain/repo when `--name` is omitted in a TTY. Fully non-interactive when all flags are passed.
+- **`packages/methodology/scripts/surfer-gate/`** (8 files) — the Silver Surfer PreToolUse hook scripts (`check.sh`, `record-roster.sh`, `bypass.sh`, `_paths.sh`, `validate.sh`, `test.sh`, `README.md`, `settings-snippet.json`) now ship via the `voidforge-build-methodology` npm package, closing the ADR-051 distribution gap (#317). Previously the scripts lived only at the repo root and never reached downstream projects via `npx voidforge-build update`.
+- **9 pattern-table rows** in `packages/methodology/CLAUDE.md` — propagates the v23.11.0 pattern additions (adr-verification-gate, multi-tenant-property-test, multi-tenant-pool-bypass, rls-test-fixture, structural-sql-sentinel, audit-log, refactor-extraction, ai-prompt-safety, llm-state-dedup) into the methodology package copy so they reach downstream projects.
+
+### Changed
+
+- **Non-TTY `voidforge init` without a flag** now exits with a clear error directing the user to `--browser` or `--headless`. Previously it silently launched a wizard server into a context where no browser would ever open — a latent bug.
+- **Surfer Gate orchestrator-contract bash commands** in `packages/methodology/CLAUDE.md` are now wrapped in `[ -x ... ] && ... || true` existence guards with documented fallback ("if the script does not exist, your project predates v23.10.0; pull the gate or re-run `npx voidforge-build init`"). Lets the methodology cleanly cover both pre-#317 and post-#317 projects.
+
+### Why this exists
+
+The init server-launch was the loudest "this CLI doesn't ask before doing things" surface in onboarding — first-run users got a server URL with no opportunity to choose CLI mode. Two flags (`--browser`, `--headless`) now span the choice; the bare command asks. Separately, the surfer-gate scripts had been documented as shipping in the methodology package since v23.11.0 changelog #317, but the scripts themselves were never copied into `packages/methodology/`. This release actually ships them.
+
+---
+
 ## [23.11.1] - 2026-05-10
 
 ### `/git` release-discipline patch — close the silent-release gap

package/dist/VERSION.md

@@ -1,6 +1,6 @@
 # Version
 
-**Current:** 23.11.1
+**Current:** 23.11.2
 
 ## Versioning Scheme
 
@@ -14,6 +14,7 @@ This project uses [Semantic Versioning](https://semver.org/):
 
 | Version | Date | Summary |
 |---------|------|---------|
+| 23.11.2 | 2026-05-12 | `voidforge init` now prompts browser-vs-CLI when no mode flag is passed (TTY only) and `--browser` was added for explicit opt-in. Headless init prompts for name/dir/oneliner/domain/repo when `--name` is omitted in a TTY. Non-TTY no-flag now errors cleanly instead of silently launching a wizard server. Separately: `packages/methodology/scripts/surfer-gate/` (8 files) now ships in the npm methodology package — closes ADR-051 distribution gap (#317). 9 pattern-table rows + existence-guarded orchestrator-contract bash propagated into the methodology CLAUDE.md. |
 | 23.11.1 | 2026-05-10 | `/git` release-discipline patch — Step 4.5 (auto-tag, default-on) and Step 7 (`--npm` opt-in publish). Closes the silent-release gap that stranded v23.10.0 and v23.11.0 between GitHub and npm. Tag-push triggers the existing `publish.yml` workflow; `--npm` is a same-session fallback. Documents the `latest` dist-tag race when multiple tags are pushed simultaneously. RELEASE_MANAGER.md mirrored. |
 | 23.11.0 | 2026-05-10 | Field Report Triage — 18 reports closed (#313-#320, #322-#330). Two combined batches across multi-tenant retrofit campaigns (#313-#320) and autonomous-mode + AI-execution campaigns (#322-#330). 9 new patterns: adr-verification-gate.md, audit-log.ts, multi-tenant-{pool-bypass,property-test}.ts, rls-test-fixture.py, structural-sql-sentinel.py, refactor-extraction.md, ai-prompt-safety.ts, llm-state-dedup.ts. ai-eval.ts extended with Claude-prompt-eval template. middleware.ts extended with hot-path logging gate. 18 method-doc sections across CAMPAIGN, SYSTEMS_ARCHITECT, SECURITY_AUDITOR, QA_ENGINEER, SUB_AGENTS, BACKEND_ENGINEER, RELEASE_MANAGER, GAUNTLET, AI_INTELLIGENCE, DEVOPS_ENGINEER, FORGE_KEEPER, TESTING, TIME_VAULT. Surfer Gate now ships via npm methodology package + wizard project-init (closes ADR-051 distribution gap #317). Operational learnings added to Picard, Sisko, Coulson, Bashir, Loki, Irulan, Silver Surfer. |
 | 23.10.0 | 2026-04-20 | Field Report Triage — 6 reports closed (#303-#308). 33 approved fixes: SPEC_HANDOFF.md (new method doc), deploy-preflight.ts + post-deploy-probe.sh (new patterns), LEARNINGS LRN-5..10, Deploy Surface Boundary + Deployment Hygiene (field report #305 remediation), Step 2.5 pre-deploy secret scan + Step 4.5 post-deploy probe, TECH_DEBT SLA, npm-name pre-flight, ADR-050 Rename Verification Checklist, Silver Surfer HARD CONSTRAINT + 4 agent operational learnings. |

package/dist/scripts/voidforge.d.ts

@@ -3,8 +3,10 @@
  * VoidForge CLI — v21.0 The Extraction
  *
  * npx voidforge                       Launch wizard (browser UI at :3141)
- * npx voidforge init                  Create new project (Gandalf flow)
- * npx voidforge init --headless       Create project without browser
+ * npx voidforge init                  Create new project — prompts: browser or CLI
+ * npx voidforge init --browser        Skip the prompt, go straight to the browser wizard
+ * npx voidforge init --headless       Create project without browser (CLI prompts for name/dir)
+ * npx voidforge init --headless --name "X"   Fully non-interactive CLI init
  * npx voidforge init --core           Minimal methodology (no Holocron, no patterns)
  * npx voidforge update                Update project methodology (Bombadil)
  * npx voidforge update --self         Update the wizard itself

package/dist/scripts/voidforge.js

@@ -3,8 +3,10 @@
  * VoidForge CLI — v21.0 The Extraction
  *
  * npx voidforge                       Launch wizard (browser UI at :3141)
- * npx voidforge init                  Create new project (Gandalf flow)
- * npx voidforge init --headless       Create project without browser
+ * npx voidforge init                  Create new project — prompts: browser or CLI
+ * npx voidforge init --browser        Skip the prompt, go straight to the browser wizard
+ * npx voidforge init --headless       Create project without browser (CLI prompts for name/dir)
+ * npx voidforge init --headless --name "X"   Fully non-interactive CLI init
  * npx voidforge init --core           Minimal methodology (no Holocron, no patterns)
  * npx voidforge update                Update project methodology (Bombadil)
  * npx voidforge update --self         Update the wizard itself
@@ -167,6 +169,41 @@ async function launchWizard(mode = 'init') {
     if (!isRemote && !isLan)
         await openBrowser(url);
 }
+function slugifyName(name) {
+    return name.replace(/[^a-zA-Z0-9-_ ]/g, '').replace(/\s+/g, '-').toLowerCase();
+}
+function defaultProjectDir(name) {
+    return join(process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.', 'Projects', slugifyName(name));
+}
+async function prompt(question) {
+    const { createInterface } = await import('node:readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(question, (answer) => { rl.close(); res(answer.trim()); });
+    });
+}
+/**
+ * Asks the user to pick browser vs headless mode for `voidforge init`.
+ * Requires a TTY — caller must guard with process.stdin.isTTY.
+ */
+async function promptInitMode() {
+    console.log('');
+    console.log('  VoidForge — init');
+    console.log('');
+    console.log('  How would you like to set up this project?');
+    console.log('    1) Browser wizard (Gandalf) — interactive, guided UI');
+    console.log('    2) CLI (headless)            — prompts here in the terminal');
+    console.log('');
+    // Loop until we get a valid answer.
+    for (;;) {
+        const answer = (await prompt('  Choice [1]: ')).toLowerCase();
+        if (answer === '' || answer === '1' || answer === 'b' || answer === 'browser')
+            return 'browser';
+        if (answer === '2' || answer === 'c' || answer === 'cli' || answer === 'h' || answer === 'headless')
+            return 'headless';
+        console.log('  Please enter 1 (browser) or 2 (CLI).');
+    }
+}
 async function cmdInitHeadless() {
     const nameFlag = args.find((a, i) => args[i - 1] === '--name');
     const dirFlag = args.find((a, i) => args[i - 1] === '--dir');
@@ -174,25 +211,61 @@ async function cmdInitHeadless() {
     const domainFlag = args.find((a, i) => args[i - 1] === '--domain');
     const repoFlag = args.find((a, i) => args[i - 1] === '--repo');
     const isCore = args.includes('--core');
-    if (!nameFlag) {
-        console.error('Error: --name is required for headless init.');
-        console.error('Usage: npx voidforge init --headless --name "My Project" [--dir path] [--oneliner "..."]');
-        process.exit(1);
+    let name = nameFlag;
+    let directory = dirFlag;
+    let oneliner = onelinerFlag;
+    let domain = domainFlag;
+    let repoUrl = repoFlag;
+    // If --name is missing, prompt interactively (TTY only).
+    if (!name) {
+        if (!process.stdin.isTTY) {
+            console.error('Error: --name is required for headless init in non-interactive contexts.');
+            console.error('Usage: npx voidforge init --headless --name "My Project" [--dir path] [--oneliner "..."]');
+            process.exit(1);
+        }
+        console.log('');
+        console.log('  VoidForge — Headless Init');
+        console.log('  Press Enter to accept defaults shown in [brackets]. Optional fields can be left blank.');
+        console.log('');
+        while (!name) {
+            const answer = await prompt('  Project name: ');
+            if (answer)
+                name = answer;
+            else
+                console.log('  Project name is required.');
+        }
+        const defaultDir = defaultProjectDir(name);
+        if (!directory) {
+            const answer = await prompt(`  Directory [${defaultDir}]: `);
+            directory = answer || defaultDir;
+        }
+        if (!oneliner) {
+            const answer = await prompt('  One-line description (optional): ');
+            oneliner = answer || undefined;
+        }
+        if (!domain) {
+            const answer = await prompt('  Domain (optional): ');
+            domain = answer || undefined;
+        }
+        if (!repoUrl) {
+            const answer = await prompt('  Repo URL (optional): ');
+            repoUrl = answer || undefined;
+        }
     }
-    const defaultDir = join(process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.', 'Projects', nameFlag.replace(/[^a-zA-Z0-9-_ ]/g, '').replace(/\s+/g, '-').toLowerCase());
-    const directory = dirFlag ?? defaultDir;
+    if (!directory)
+        directory = defaultProjectDir(name);
     const { createProject } = await import('../wizard/lib/project-init.js');
     const result = await createProject({
-        name: nameFlag,
+        name,
         directory,
-        oneliner: onelinerFlag,
-        domain: domainFlag,
-        repoUrl: repoFlag,
+        oneliner,
+        domain,
+        repoUrl,
         core: isCore,
     });
     console.log('');
     console.log(`  VoidForge — Project Created`);
-    console.log(`  Name:      ${nameFlag}`);
+    console.log(`  Name:      ${name}`);
     console.log(`  Directory: ${result.projectDir}`);
     console.log(`  Files:     ${result.filesCreated} methodology files`);
     console.log(`  Marker:    ${result.markerId}`);
@@ -293,7 +366,8 @@ function showHelp() {
     console.log('  --help, -h         Show this help');
     console.log('  --remote           Launch in remote mode (0.0.0.0 + auth)');
     console.log('  --lan              Launch in LAN mode');
-    console.log('  --headless         CLI-only (no browser)');
+    console.log('  --browser          init: skip the mode prompt and launch the browser wizard');
+    console.log('  --headless         init: CLI-only flow (prompts for name/dir if not passed)');
     console.log('  --self             Deploy VoidForge itself');
     console.log('  --env-only         Write vault credentials to .env');
     console.log('');
@@ -536,14 +610,29 @@ async function main() {
                 console.log('  To rollback: restore from the backup directory.\n');
                 break;
             }
-            case 'init':
-                if (args.includes('--headless')) {
+            case 'init': {
+                const wantsHeadless = args.includes('--headless');
+                const wantsBrowser = args.includes('--browser');
+                if (wantsHeadless) {
                     await cmdInitHeadless();
                 }
-                else {
+                else if (wantsBrowser) {
                     await launchWizard('init');
                 }
+                else if (process.stdin.isTTY) {
+                    const mode = await promptInitMode();
+                    if (mode === 'headless')
+                        await cmdInitHeadless();
+                    else
+                        await launchWizard('init');
+                }
+                else {
+                    console.error('Error: `voidforge init` was run in a non-interactive context without a mode flag.');
+                    console.error('Pass --browser to launch the wizard UI, or --headless [--name "..."] for CLI init.');
+                    process.exit(1);
+                }
                 break;
+            }
             case 'heartbeat': {
                 const subCmd = args[1]; // start | stop | status
                 if (subCmd !== 'start') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voidforge-build",
-  "version": "23.11.1",
+  "version": "23.11.2",
   "description": "From nothing, everything. A methodology framework for building with Claude Code.",
   "type": "module",
   "engines": {