thevoidforge 21.0.0

package/dist/wizard/lib/prd-validator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * PRD Structural Validator — Troi's compliance checks.
+ *
+ * Validates that a PRD document has the expected sections and
+ * cross-references based on its frontmatter configuration.
+ * Produces warnings (not errors) — the user can proceed with gaps.
+ *
+ * PRD Reference: RFC-blueprint-path.md
+ */
+import type { PrdFrontmatter } from './frontmatter.js';
+export interface ValidationResult {
+    errors: string[];
+    warnings: string[];
+    sections: string[];
+    valid: boolean;
+}
+/**
+ * Extract all markdown heading sections from PRD content.
+ * Returns lowercase heading text for case-insensitive matching.
+ */
+export declare function extractSections(content: string): string[];
+/**
+ * Validate PRD structure against frontmatter configuration.
+ *
+ * Rules (warnings, not blockers):
+ * - PRD must have an OVERVIEW or SUMMARY section
+ * - PRD must have at least one feature section
+ * - If database is configured, should have DATA MODELS section
+ * - If deploy target is set, should have DEPLOYMENT section
+ * - If auth is enabled, should mention authentication
+ * - If workers are enabled, should define background workers
+ * - If payments are configured, should have a payments/billing section
+ */
+export declare function validatePrdStructure(content: string, frontmatter: PrdFrontmatter): ValidationResult;
+/**
+ * Run conflict scan between frontmatter fields.
+ * Checks for contradictions that cost hours if caught late.
+ */
+export declare function scanConflicts(frontmatter: PrdFrontmatter): string[];

package/dist/wizard/lib/prd-validator.js

@@ -0,0 +1,137 @@
+/**
+ * PRD Structural Validator — Troi's compliance checks.
+ *
+ * Validates that a PRD document has the expected sections and
+ * cross-references based on its frontmatter configuration.
+ * Produces warnings (not errors) — the user can proceed with gaps.
+ *
+ * PRD Reference: RFC-blueprint-path.md
+ */
+// ── Section Detection ───────────────────────────────
+/**
+ * Extract all markdown heading sections from PRD content.
+ * Returns lowercase heading text for case-insensitive matching.
+ */
+export function extractSections(content) {
+    const headingPattern = /^#{1,3}\s+(.+)$/gm;
+    const sections = [];
+    let match;
+    while ((match = headingPattern.exec(content)) !== null) {
+        sections.push(match[1].trim().toLowerCase());
+    }
+    return sections;
+}
+/**
+ * Check if any section heading contains a given keyword.
+ */
+function hasSection(sections, keyword) {
+    const lower = keyword.toLowerCase();
+    return sections.some(s => s.includes(lower));
+}
+// ── Structural Validation ───────────────────────────
+/**
+ * Validate PRD structure against frontmatter configuration.
+ *
+ * Rules (warnings, not blockers):
+ * - PRD must have an OVERVIEW or SUMMARY section
+ * - PRD must have at least one feature section
+ * - If database is configured, should have DATA MODELS section
+ * - If deploy target is set, should have DEPLOYMENT section
+ * - If auth is enabled, should mention authentication
+ * - If workers are enabled, should define background workers
+ * - If payments are configured, should have a payments/billing section
+ */
+export function validatePrdStructure(content, frontmatter) {
+    const sections = extractSections(content);
+    const errors = [];
+    const warnings = [];
+    const contentLower = content.toLowerCase();
+    // Required: Overview or Summary section
+    if (!hasSection(sections, 'overview') && !hasSection(sections, 'summary') && !hasSection(sections, 'introduction')) {
+        warnings.push('Missing OVERVIEW or SUMMARY section — add a high-level description of the product');
+    }
+    // Required: At least one feature section
+    if (!hasSection(sections, 'feature') && !hasSection(sections, 'core') && !hasSection(sections, 'functionality')) {
+        warnings.push('No feature sections found — add sections describing what the product does');
+    }
+    // Conditional: Database → Data Models
+    if (frontmatter.database && frontmatter.database !== 'no' && frontmatter.database !== 'none') {
+        if (!hasSection(sections, 'data model') && !hasSection(sections, 'schema') && !hasSection(sections, 'database')) {
+            warnings.push(`Database "${frontmatter.database}" configured but no DATA MODELS or SCHEMA section found`);
+        }
+    }
+    // Conditional: Deploy → Deployment section
+    if (frontmatter.deploy && frontmatter.deploy !== 'no' && frontmatter.deploy !== 'none') {
+        if (!hasSection(sections, 'deploy') && !hasSection(sections, 'infrastructure') && !hasSection(sections, 'hosting')) {
+            warnings.push(`Deploy target "${frontmatter.deploy}" configured but no DEPLOYMENT section found`);
+        }
+    }
+    // Conditional: Auth → Authentication mentioned
+    if (frontmatter.auth && frontmatter.auth !== 'no' && frontmatter.auth !== 'none' && frontmatter.auth !== 'false') {
+        if (!contentLower.includes('auth') && !contentLower.includes('login') && !contentLower.includes('sign in')) {
+            warnings.push('Auth is enabled but PRD does not mention authentication, login, or sign-in');
+        }
+    }
+    // Conditional: Workers → Background jobs defined
+    if (frontmatter.workers && frontmatter.workers !== 'no' && frontmatter.workers !== 'none' && frontmatter.workers !== 'false') {
+        if (!contentLower.includes('worker') && !contentLower.includes('background') && !contentLower.includes('queue') && !contentLower.includes('cron')) {
+            warnings.push('Workers enabled but PRD does not mention workers, background jobs, queues, or cron');
+        }
+    }
+    // Conditional: Payments → Billing section
+    if (frontmatter.payments && frontmatter.payments !== 'no' && frontmatter.payments !== 'none' && frontmatter.payments !== 'false') {
+        if (!contentLower.includes('payment') && !contentLower.includes('billing') && !contentLower.includes('subscription') && !contentLower.includes('pricing')) {
+            warnings.push(`Payments "${frontmatter.payments}" configured but PRD does not mention payments, billing, or pricing`);
+        }
+    }
+    // Conditional: Email → Email section or mentions
+    if (frontmatter.email && frontmatter.email !== 'no' && frontmatter.email !== 'none' && frontmatter.email !== 'false') {
+        if (!contentLower.includes('email') && !contentLower.includes('notification') && !contentLower.includes('mail')) {
+            warnings.push(`Email "${frontmatter.email}" configured but PRD does not mention email or notifications`);
+        }
+    }
+    return {
+        errors,
+        warnings,
+        sections,
+        valid: errors.length === 0,
+    };
+}
+/**
+ * Run conflict scan between frontmatter fields.
+ * Checks for contradictions that cost hours if caught late.
+ */
+export function scanConflicts(frontmatter) {
+    const conflicts = [];
+    // Auth + Database: auth usually needs a database
+    if (frontmatter.auth && frontmatter.auth !== 'no' && frontmatter.auth !== 'none') {
+        if (!frontmatter.database || frontmatter.database === 'none') {
+            conflicts.push('Auth is enabled but no database configured — auth needs persistent storage for users/sessions');
+        }
+    }
+    // Payments + Auth: payments need auth
+    if (frontmatter.payments && frontmatter.payments !== 'no' && frontmatter.payments !== 'none') {
+        if (!frontmatter.auth || frontmatter.auth === 'no' || frontmatter.auth === 'none') {
+            conflicts.push('Payments configured but auth is disabled — payments require authenticated users');
+        }
+    }
+    // Workers + Deploy: workers need persistent hosting
+    if (frontmatter.workers && frontmatter.workers !== 'no' && frontmatter.workers !== 'none' && frontmatter.workers !== 'false') {
+        if (frontmatter.deploy === 'static' || frontmatter.deploy === 'cloudflare') {
+            conflicts.push(`Workers enabled but deploy target "${frontmatter.deploy}" does not support background processes`);
+        }
+    }
+    // Cache + Deploy: Redis needs a host
+    if (frontmatter.cache && frontmatter.cache !== 'none' && frontmatter.cache !== 'no') {
+        if (frontmatter.deploy === 'static' || frontmatter.deploy === 'cloudflare') {
+            conflicts.push(`Cache "${frontmatter.cache}" configured but deploy target "${frontmatter.deploy}" does not support cache services`);
+        }
+    }
+    // Admin + Auth: admin panel needs auth
+    if (frontmatter.admin && frontmatter.admin !== 'no' && frontmatter.admin !== 'none' && frontmatter.admin !== 'false') {
+        if (!frontmatter.auth || frontmatter.auth === 'no' || frontmatter.auth === 'none') {
+            conflicts.push('Admin panel enabled but auth is disabled — admin requires authenticated access');
+        }
+    }
+    return conflicts;
+}

package/dist/wizard/lib/project-init.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Project creation — headless and browser init flows.
+ *
+ * Creates a new VoidForge project by copying methodology files,
+ * injecting project identity, writing the marker, and registering.
+ */
+import { type VoidForgeMarker } from './marker.js';
+export interface ProjectConfig {
+    name: string;
+    directory: string;
+    oneliner?: string;
+    domain?: string;
+    repoUrl?: string;
+    tier?: VoidForgeMarker['tier'];
+    extensions?: string[];
+    core?: boolean;
+    skipGit?: boolean;
+}
+export interface ProjectResult {
+    projectDir: string;
+    markerId: string;
+    filesCreated: number;
+}
+export declare function createProject(config: ProjectConfig): Promise<ProjectResult>;

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

@@ -0,0 +1,193 @@
+/**
+ * Project creation — headless and browser init flows.
+ *
+ * Creates a new VoidForge project by copying methodology files,
+ * injecting project identity, writing the marker, and registering.
+ */
+import { mkdir, readFile, writeFile, readdir, cp } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { createMarker, writeMarker, } from './marker.js';
+import { addProject } from './project-registry.js';
+// ── Methodology Source ───────────────────────────────────
+/**
+ * Resolves the methodology source directory.
+ * In development: monorepo root (where CLAUDE.md lives).
+ * In production: the installed @voidforge/methodology package.
+ */
+async function resolveMethodologyRoot() {
+    // Development: walk up from this file to find CLAUDE.md at monorepo root
+    const dir = import.meta.dirname ?? new URL('.', import.meta.url).pathname;
+    let current = dir;
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(join(current, 'CLAUDE.md')) && existsSync(join(current, '.claude', 'commands'))) {
+            return current;
+        }
+        current = resolve(current, '..');
+    }
+    // Production: try to resolve from @voidforge/methodology
+    try {
+        const { createRequire } = await import('node:module');
+        const require_ = createRequire(import.meta.url);
+        const methodologyPkg = require_.resolve('@voidforge/methodology/package.json');
+        return resolve(methodologyPkg, '..');
+    }
+    catch {
+        // Package not installed — expected in development
+    }
+    throw new Error('Cannot find methodology source. Checked: CLAUDE.md walkup (development), ' +
+        '@voidforge/methodology package (production). Ensure VoidForge is installed correctly.');
+}
+// ── Copy Methodology ─────────────────────────────────────
+async function copyDir(src, dest) {
+    if (!existsSync(src))
+        return 0;
+    await mkdir(dest, { recursive: true });
+    let count = 0;
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        if (entry.isDirectory()) {
+            count += await copyDir(srcPath, destPath);
+        }
+        else {
+            await cp(srcPath, destPath);
+            count++;
+        }
+    }
+    return count;
+}
+async function copyMethodology(methodologyRoot, projectDir, core) {
+    let count = 0;
+    // Always copy: CLAUDE.md, VERSION.md
+    for (const file of ['CLAUDE.md', 'VERSION.md']) {
+        const src = join(methodologyRoot, file);
+        if (existsSync(src)) {
+            await cp(src, join(projectDir, file));
+            count++;
+        }
+    }
+    // Full tier: also copy HOLOCRON.md, CHANGELOG.md
+    if (!core) {
+        for (const file of ['HOLOCRON.md', 'CHANGELOG.md']) {
+            const src = join(methodologyRoot, file);
+            if (existsSync(src)) {
+                await cp(src, join(projectDir, file));
+                count++;
+            }
+        }
+    }
+    // Commands
+    const commandsSrc = join(methodologyRoot, '.claude', 'commands');
+    if (existsSync(commandsSrc)) {
+        count += await copyDir(commandsSrc, join(projectDir, '.claude', 'commands'));
+    }
+    // Methods
+    const methodsSrc = join(methodologyRoot, 'docs', 'methods');
+    if (existsSync(methodsSrc)) {
+        count += await copyDir(methodsSrc, join(projectDir, 'docs', 'methods'));
+    }
+    // Patterns (full tier only)
+    if (!core) {
+        const patternsSrc = join(methodologyRoot, 'docs', 'patterns');
+        if (existsSync(patternsSrc)) {
+            count += await copyDir(patternsSrc, join(projectDir, 'docs', 'patterns'));
+        }
+    }
+    // Naming registry
+    const registrySrc = join(methodologyRoot, 'docs', 'NAMING_REGISTRY.md');
+    if (existsSync(registrySrc)) {
+        await mkdir(join(projectDir, 'docs'), { recursive: true });
+        await cp(registrySrc, join(projectDir, 'docs', 'NAMING_REGISTRY.md'));
+        count++;
+    }
+    // Thumper scripts
+    const thumperSrc = join(methodologyRoot, 'scripts', 'thumper');
+    if (existsSync(thumperSrc)) {
+        count += await copyDir(thumperSrc, join(projectDir, 'scripts', 'thumper'));
+    }
+    return count;
+}
+// ── Identity Injection ───────────────────────────────────
+async function injectIdentity(projectDir, config) {
+    const claudePath = join(projectDir, 'CLAUDE.md');
+    if (!existsSync(claudePath))
+        return;
+    let content = await readFile(claudePath, 'utf-8');
+    content = content.replace('[PROJECT_NAME]', config.name);
+    content = content.replace('[ONE_LINE_DESCRIPTION]', config.oneliner ?? '');
+    content = content.replace('[DOMAIN]', config.domain ?? '');
+    content = content.replace('[REPO_URL]', config.repoUrl ?? '');
+    await writeFile(claudePath, content, 'utf-8');
+}
+// ── Git Init ─────────────────────────────────────────────
+function gitInit(projectDir) {
+    try {
+        execSync('git init', { cwd: projectDir, stdio: 'pipe' });
+        execSync('git add -A', { cwd: projectDir, stdio: 'pipe' });
+        execSync('git commit -m "Initial commit — created with VoidForge"', {
+            cwd: projectDir,
+            stdio: 'pipe',
+            env: { ...process.env },
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Main Entry ───────────────────────────────────────────
+export async function createProject(config) {
+    const projectDir = resolve(config.directory);
+    // 1. Create directory
+    await mkdir(projectDir, { recursive: true });
+    // 2. Copy methodology
+    const methodologyRoot = await resolveMethodologyRoot();
+    const filesCreated = await copyMethodology(methodologyRoot, projectDir, config.core ?? false);
+    // 3. Inject project identity
+    await injectIdentity(projectDir, config);
+    // 4. Write .voidforge marker
+    const marker = createMarker('21.0.0', config.core ? 'methodology' : 'full', config.extensions ?? []);
+    await writeMarker(projectDir, marker);
+    // 5. Register in project registry
+    try {
+        await addProject({
+            name: config.name,
+            directory: projectDir,
+            deployTarget: '',
+            deployUrl: '',
+            sshHost: '',
+            framework: 'unknown',
+            database: 'none',
+            createdAt: marker.created,
+            lastBuildPhase: 0,
+            lastDeployAt: '',
+            healthCheckUrl: '',
+            monthlyCost: 0,
+            owner: '',
+            access: [],
+            linkedProjects: [],
+        });
+    }
+    catch {
+        // Registry write is best-effort — don't fail project creation
+    }
+    // 6. Validate critical files were copied
+    if (!existsSync(join(projectDir, 'CLAUDE.md'))) {
+        throw new Error('Failed to copy CLAUDE.md — methodology source may be corrupted.');
+    }
+    // 7. Git init + initial commit
+    if (!config.skipGit) {
+        const gitOk = gitInit(projectDir);
+        if (!gitOk) {
+            console.warn('Warning: git init failed. Project created but not version-controlled.');
+        }
+    }
+    return {
+        projectDir,
+        markerId: marker.id,
+        filesCreated: filesCreated + 1, // +1 for .voidforge marker
+    };
+}

package/dist/wizard/lib/project-registry.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Project Registry — CRUD for ~/.voidforge/projects.json.
+ * Zero-dep JSON file storage for multi-project Avengers Tower.
+ * File permissions: 0600 (owner read/write only).
+ *
+ * Follows vault.ts patterns: serialized writes, atomic file ops, homedir().
+ */
+export type HealthStatus = 'healthy' | 'degraded' | 'down' | 'unchecked';
+export interface ProjectAccessEntry {
+    username: string;
+    role: 'deployer' | 'viewer';
+}
+export interface Project {
+    id: string;
+    name: string;
+    directory: string;
+    deployTarget: string;
+    deployUrl: string;
+    sshHost: string;
+    framework: string;
+    database: string;
+    createdAt: string;
+    lastBuildPhase: number;
+    lastDeployAt: string;
+    healthCheckUrl: string;
+    monthlyCost: number;
+    healthStatus: HealthStatus;
+    healthCheckedAt: string;
+    owner: string;
+    access: ProjectAccessEntry[];
+    linkedProjects: string[];
+}
+export type ProjectInput = Omit<Project, 'id' | 'healthStatus' | 'healthCheckedAt'> & {
+    owner?: string;
+    access?: ProjectAccessEntry[];
+    linkedProjects?: string[];
+};
+/** Read the full registry. Returns empty array if file doesn't exist. */
+export declare function readRegistry(): Promise<Project[]>;
+/**
+ * Add a new project to the registry.
+ * @throws Error if a project with the same directory is already registered.
+ */
+export declare function addProject(input: ProjectInput): Promise<Project>;
+/** Get a project by ID. Returns null if not found. */
+export declare function getProject(id: string): Promise<Project | null>;
+/** Find a project by directory path. Returns null if not found. */
+export declare function findByDirectory(directory: string): Promise<Project | null>;
+/** Update a project by ID. Merges only known mutable fields. Returns null if not found. */
+export declare function updateProject(id: string, updates: Partial<Omit<Project, 'id' | 'createdAt' | 'directory'>>): Promise<Project | null>;
+/** Remove a project by ID. Cleans up linked references in other projects. */
+export declare function removeProject(id: string): Promise<boolean>;
+/** Update health status for a project. */
+export declare function updateHealthStatus(id: string, status: HealthStatus): Promise<void>;
+/** LOKI-004: Batch update health status — single read-write cycle for N projects. */
+export declare function batchUpdateHealthStatus(updates: Array<{
+    id: string;
+    status: HealthStatus;
+}>): Promise<void>;
+/**
+ * Get projects visible to a user.
+ * Admins see all. Others see owned + explicitly shared.
+ */
+export declare function getProjectsForUser(username: string, globalRole: string): Promise<Project[]>;
+/**
+ * Check if a user can access a project at the given role level.
+ * Returns the effective role or null if no access.
+ */
+export declare function checkProjectAccess(projectId: string, username: string, globalRole: string): Promise<'admin' | 'deployer' | 'viewer' | null>;
+/** Grant access to a project for a user. Overwrites existing entry for that user. */
+export declare function grantAccess(projectId: string, username: string, role: 'deployer' | 'viewer'): Promise<void>;
+/** Revoke access from a project for a user. */
+export declare function revokeAccess(projectId: string, username: string): Promise<void>;
+/** Remove a user from all project access lists and clear ownership (cleanup on user deletion). */
+export declare function removeUserFromAllProjects(username: string): Promise<number>;
+/** Get access list for a project. */
+export declare function getProjectAccess(projectId: string): Promise<{
+    owner: string;
+    access: ProjectAccessEntry[];
+} | null>;
+/** Link two projects bidirectionally. */
+export declare function linkProjects(projectIdA: string, projectIdB: string): Promise<void>;
+/** Unlink two projects bidirectionally. */
+export declare function unlinkProjects(projectIdA: string, projectIdB: string): Promise<void>;
+/** Get all projects in the linked group (BFS traversal with cycle detection). */
+export declare function getLinkedGroup(projectId: string): Promise<Project[]>;