thevoidforge 21.0.0

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

@@ -0,0 +1,359 @@
+/**
+ * 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().
+ */
+import { readFile, rename, mkdir, open, copyFile, chmod } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+const VOIDFORGE_DIR = join(homedir(), '.voidforge');
+const REGISTRY_PATH = join(VOIDFORGE_DIR, 'projects.json');
+// ── Write serialization (from vault.ts) ────────────
+let writeQueue = Promise.resolve();
+function serialized(fn) {
+    const result = writeQueue.then(fn, () => fn());
+    writeQueue = result.then(() => { }, () => { });
+    return result;
+}
+// ── Validation ─────────────────────────────────────
+const VALID_HEALTH_STATUSES = new Set(['healthy', 'degraded', 'down', 'unchecked']);
+function isValidProject(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const p = obj;
+    const valid = (typeof p.id === 'string' &&
+        typeof p.name === 'string' &&
+        typeof p.directory === 'string' &&
+        typeof p.deployTarget === 'string' &&
+        typeof p.deployUrl === 'string' &&
+        typeof p.sshHost === 'string' &&
+        typeof p.framework === 'string' &&
+        typeof p.database === 'string' &&
+        typeof p.createdAt === 'string' &&
+        typeof p.lastBuildPhase === 'number' &&
+        typeof p.lastDeployAt === 'string' &&
+        typeof p.healthCheckUrl === 'string' &&
+        typeof p.monthlyCost === 'number' &&
+        typeof p.healthStatus === 'string' &&
+        VALID_HEALTH_STATUSES.has(p.healthStatus) &&
+        typeof p.healthCheckedAt === 'string');
+    if (!valid)
+        return false;
+    // Migrate legacy projects without owner/access/linkedProjects fields
+    if (typeof p.owner !== 'string')
+        p.owner = '';
+    if (!Array.isArray(p.access))
+        p.access = [];
+    if (!Array.isArray(p.linkedProjects))
+        p.linkedProjects = [];
+    return true;
+}
+// ── Path normalization ─────────────────────────────
+function normalizePath(dir) {
+    return resolve(dir);
+}
+// ── File I/O (atomic writes, following vault.ts) ───
+/** Read the full registry. Returns empty array if file doesn't exist. */
+export async function readRegistry() {
+    try {
+        const raw = await readFile(REGISTRY_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        // Validate each entry, filter out invalid ones
+        return parsed.filter(isValidProject);
+    }
+    catch (err) {
+        // File not found is expected — return empty registry
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return [];
+        }
+        // JSON parse error or permission denied — throw so callers don't overwrite data
+        throw new Error(`Registry corrupted or unreadable: ${err instanceof Error ? err.message : 'Unknown error'}`);
+    }
+}
+/** Atomic write: backup → temp file → fsync → rename (from vault.ts). */
+async function writeRegistry(projects) {
+    await mkdir(VOIDFORGE_DIR, { recursive: true });
+    // Backup current file before overwriting (data loss prevention)
+    try {
+        await copyFile(REGISTRY_PATH, REGISTRY_PATH + '.bak');
+        await chmod(REGISTRY_PATH + '.bak', 0o600);
+    }
+    catch (err) {
+        // ENOENT = no file to back up (expected on first write)
+        // Other errors (disk full, permissions) = log but don't block the write
+        if (!(err instanceof Error && 'code' in err && err.code === 'ENOENT')) {
+            console.error('Registry backup failed:', err instanceof Error ? err.message : 'Unknown error');
+        }
+    }
+    const data = JSON.stringify(projects, null, 2);
+    const tmpPath = REGISTRY_PATH + '.tmp';
+    const fh = await open(tmpPath, 'w', 0o600);
+    try {
+        await fh.writeFile(data);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, REGISTRY_PATH);
+}
+// ── Public API (all mutating ops are serialized) ───
+/**
+ * Add a new project to the registry.
+ * @throws Error if a project with the same directory is already registered.
+ */
+export function addProject(input) {
+    return serialized(async () => {
+        const projects = await readRegistry();
+        const normalized = normalizePath(input.directory);
+        const exists = projects.some((p) => normalizePath(p.directory) === normalized);
+        if (exists) {
+            throw new Error(`Project already registered at ${input.directory}`);
+        }
+        const project = {
+            ...input,
+            directory: normalized,
+            id: randomUUID(),
+            healthStatus: 'unchecked',
+            healthCheckedAt: '',
+            owner: input.owner ?? '',
+            access: input.access ?? [],
+            linkedProjects: input.linkedProjects ?? [],
+        };
+        projects.push(project);
+        await writeRegistry(projects);
+        return project;
+    });
+}
+/** Get a project by ID. Returns null if not found. */
+export async function getProject(id) {
+    const projects = await readRegistry();
+    return projects.find((p) => p.id === id) ?? null;
+}
+/** Find a project by directory path. Returns null if not found. */
+export async function findByDirectory(directory) {
+    const projects = await readRegistry();
+    const normalized = normalizePath(directory);
+    return projects.find((p) => normalizePath(p.directory) === normalized) ?? null;
+}
+/** Mutable fields — prevents callers from injecting arbitrary keys via spread. */
+const MUTABLE_FIELDS = new Set([
+    'name', 'deployTarget', 'deployUrl', 'sshHost', 'framework', 'database',
+    'lastBuildPhase', 'lastDeployAt', 'healthCheckUrl', 'monthlyCost',
+    'healthStatus', 'healthCheckedAt',
+]);
+/** Update a project by ID. Merges only known mutable fields. Returns null if not found. */
+export function updateProject(id, updates) {
+    return serialized(async () => {
+        const projects = await readRegistry();
+        const idx = projects.findIndex((p) => p.id === id);
+        if (idx === -1)
+            return null;
+        // Pick only known mutable fields from updates, validate enum fields
+        const safe = {};
+        for (const [key, value] of Object.entries(updates)) {
+            if (!MUTABLE_FIELDS.has(key))
+                continue;
+            // Validate healthStatus against allowed values
+            if (key === 'healthStatus' && !VALID_HEALTH_STATUSES.has(value))
+                continue;
+            safe[key] = value;
+        }
+        projects[idx] = { ...projects[idx], ...safe };
+        await writeRegistry(projects);
+        return projects[idx];
+    });
+}
+/** Remove a project by ID. Cleans up linked references in other projects. */
+export function removeProject(id) {
+    return serialized(async () => {
+        const projects = await readRegistry();
+        const idx = projects.findIndex((p) => p.id === id);
+        if (idx === -1)
+            return false;
+        projects.splice(idx, 1);
+        // Clean up linked references in remaining projects
+        for (const project of projects) {
+            project.linkedProjects = project.linkedProjects.filter((lid) => lid !== id);
+        }
+        await writeRegistry(projects);
+        return true;
+    });
+}
+/** Update health status for a project. */
+export function updateHealthStatus(id, status) {
+    return serialized(async () => {
+        const projects = await readRegistry();
+        const idx = projects.findIndex((p) => p.id === id);
+        if (idx === -1)
+            return;
+        projects[idx] = {
+            ...projects[idx],
+            healthStatus: status,
+            healthCheckedAt: new Date().toISOString(),
+        };
+        await writeRegistry(projects);
+    });
+}
+/** LOKI-004: Batch update health status — single read-write cycle for N projects. */
+export function batchUpdateHealthStatus(updates) {
+    return serialized(async () => {
+        const projects = await readRegistry();
+        const now = new Date().toISOString();
+        for (const { id, status } of updates) {
+            const idx = projects.findIndex((p) => p.id === id);
+            if (idx === -1)
+                continue;
+            projects[idx] = { ...projects[idx], healthStatus: status, healthCheckedAt: now };
+        }
+        await writeRegistry(projects);
+    });
+}
+// ── Per-project access control ──────────────────────
+/**
+ * Get projects visible to a user.
+ * Admins see all. Others see owned + explicitly shared.
+ */
+export async function getProjectsForUser(username, globalRole) {
+    const projects = await readRegistry();
+    if (globalRole === 'admin')
+        return projects;
+    return projects.filter((p) => p.owner === username || p.access.some((a) => a.username === username));
+}
+/**
+ * Check if a user can access a project at the given role level.
+ * Returns the effective role or null if no access.
+ */
+export async function checkProjectAccess(projectId, username, globalRole) {
+    const project = await getProject(projectId);
+    if (!project)
+        return null;
+    // Global admins have full access
+    if (globalRole === 'admin')
+        return 'admin';
+    // Project owner has full access
+    if (project.owner === username)
+        return 'admin';
+    // Check access list
+    const entry = project.access.find((a) => a.username === username);
+    return entry?.role ?? null;
+}
+/** Grant access to a project for a user. Overwrites existing entry for that user. */
+export function grantAccess(projectId, username, role) {
+    return serialized(async () => {
+        const projects = await readRegistry();
+        const idx = projects.findIndex((p) => p.id === projectId);
+        if (idx === -1)
+            throw new Error('Project not found');
+        const project = projects[idx];
+        // Remove existing entry for this user (if any)
+        project.access = project.access.filter((a) => a.username !== username);
+        project.access.push({ username, role });
+        await writeRegistry(projects);
+    });
+}
+/** Revoke access from a project for a user. */
+export function revokeAccess(projectId, username) {
+    return serialized(async () => {
+        const projects = await readRegistry();
+        const idx = projects.findIndex((p) => p.id === projectId);
+        if (idx === -1)
+            throw new Error('Project not found');
+        const project = projects[idx];
+        const before = project.access.length;
+        project.access = project.access.filter((a) => a.username !== username);
+        if (project.access.length === before)
+            throw new Error('User has no access to revoke');
+        await writeRegistry(projects);
+    });
+}
+/** Remove a user from all project access lists and clear ownership (cleanup on user deletion). */
+export function removeUserFromAllProjects(username) {
+    return serialized(async () => {
+        const projects = await readRegistry();
+        let changedCount = 0;
+        for (const project of projects) {
+            const before = project.access.length;
+            project.access = project.access.filter((a) => a.username !== username);
+            if (project.access.length < before)
+                changedCount++;
+            // Clear ownership to prevent privilege escalation via username reuse
+            if (project.owner === username) {
+                project.owner = '';
+                changedCount++;
+            }
+        }
+        if (changedCount > 0)
+            await writeRegistry(projects);
+        return changedCount;
+    });
+}
+/** Get access list for a project. */
+export async function getProjectAccess(projectId) {
+    const project = await getProject(projectId);
+    if (!project)
+        return null;
+    return { owner: project.owner, access: project.access };
+}
+// ── Linked services ─────────────────────────────────
+/** Link two projects bidirectionally. */
+export function linkProjects(projectIdA, projectIdB) {
+    return serialized(async () => {
+        if (projectIdA === projectIdB)
+            throw new Error('Cannot link a project to itself');
+        const projects = await readRegistry();
+        const a = projects.find((p) => p.id === projectIdA);
+        const b = projects.find((p) => p.id === projectIdB);
+        if (!a || !b)
+            throw new Error('Project not found');
+        if (!a.linkedProjects.includes(projectIdB))
+            a.linkedProjects.push(projectIdB);
+        if (!b.linkedProjects.includes(projectIdA))
+            b.linkedProjects.push(projectIdA);
+        await writeRegistry(projects);
+    });
+}
+/** Unlink two projects bidirectionally. */
+export function unlinkProjects(projectIdA, projectIdB) {
+    return serialized(async () => {
+        const projects = await readRegistry();
+        const a = projects.find((p) => p.id === projectIdA);
+        const b = projects.find((p) => p.id === projectIdB);
+        if (!a || !b)
+            throw new Error('Project not found');
+        a.linkedProjects = a.linkedProjects.filter((id) => id !== projectIdB);
+        b.linkedProjects = b.linkedProjects.filter((id) => id !== projectIdA);
+        await writeRegistry(projects);
+    });
+}
+/** Get all projects in the linked group (BFS traversal with cycle detection). */
+export async function getLinkedGroup(projectId) {
+    const projects = await readRegistry();
+    const start = projects.find((p) => p.id === projectId);
+    if (!start)
+        return [];
+    // BFS to resolve transitive links: A→B→C means all three are in the group
+    const visited = new Set();
+    const queue = [start];
+    const group = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (visited.has(current.id))
+            continue;
+        visited.add(current.id);
+        group.push(current);
+        for (const linkedId of current.linkedProjects) {
+            if (!visited.has(linkedId)) {
+                const linked = projects.find((p) => p.id === linkedId);
+                if (linked)
+                    queue.push(linked);
+            }
+        }
+    }
+    return group;
+}

package/dist/wizard/lib/provision-manifest.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Provision manifest — persists resource state to disk for crash recovery.
+ *
+ * Before each AWS resource creation, the intended action is recorded.
+ * After creation, the resource ID is written. On cleanup, the manifest
+ * is read and resources deleted in reverse. On wizard startup, incomplete
+ * manifests can be detected and cleaned up.
+ *
+ * Stored at ~/.voidforge/runs/<runId>.json
+ */
+import type { CreatedResource } from './provisioners/types.js';
+export interface ManifestResource {
+    type: string;
+    id: string;
+    region: string;
+    status: 'pending' | 'created' | 'cleaned' | 'failed';
+}
+export interface ProvisionManifest {
+    runId: string;
+    startedAt: string;
+    target: string;
+    region: string;
+    projectName: string;
+    status: 'in-progress' | 'complete' | 'failed' | 'cleaned';
+    resources: ManifestResource[];
+}
+/** Create a new manifest for a provisioning run. */
+export declare function createManifest(runId: string, target: string, region: string, projectName: string): Promise<ProvisionManifest>;
+/** Record that a resource is about to be created (write-ahead). */
+export declare function recordResourcePending(runId: string, type: string, id: string, region: string): Promise<void>;
+/** Record that a resource was successfully created. */
+export declare function recordResourceCreated(runId: string, type: string, id: string, region: string): Promise<void>;
+/** Mark the overall run status. */
+export declare function updateManifestStatus(runId: string, status: ProvisionManifest['status']): Promise<void>;
+/** Mark a resource as cleaned up. */
+export declare function recordResourceCleaned(runId: string, type: string, id: string): Promise<void>;
+/** Read a manifest by run ID. Returns null if not found. */
+export declare function readManifest(runId: string): Promise<ProvisionManifest | null>;
+/** Delete a manifest file (after successful cleanup). */
+export declare function deleteManifest(runId: string): Promise<void>;
+/** List all incomplete manifests (for recovery on startup). */
+export declare function listIncompleteRuns(): Promise<ProvisionManifest[]>;
+/** Convert manifest resources to the CreatedResource[] format used by provisioners. */
+export declare function manifestToCreatedResources(manifest: ProvisionManifest): CreatedResource[];

package/dist/wizard/lib/provision-manifest.js

@@ -0,0 +1,164 @@
+/**
+ * Provision manifest — persists resource state to disk for crash recovery.
+ *
+ * Before each AWS resource creation, the intended action is recorded.
+ * After creation, the resource ID is written. On cleanup, the manifest
+ * is read and resources deleted in reverse. On wizard startup, incomplete
+ * manifests can be detected and cleaned up.
+ *
+ * Stored at ~/.voidforge/runs/<runId>.json
+ */
+import { readFile, readdir, unlink, mkdir, open, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+const RUNS_DIR = join(homedir(), '.voidforge', 'runs');
+/** QA-R2-004: Write queue to serialize manifest mutations and prevent race conditions */
+let writeQueue = Promise.resolve();
+function serialized(fn) {
+    const result = writeQueue.then(fn, () => fn());
+    writeQueue = result.then(() => { }, () => { });
+    return result;
+}
+// IG-R4 LOKI-003: Atomic write with fsync — crash-recovery manifests must survive crashes
+async function atomicWriteManifest(runId, manifest) {
+    const filePath = manifestPath(runId);
+    const tmpPath = filePath + '.tmp';
+    const fh = await open(tmpPath, 'w', 0o600);
+    try {
+        await fh.writeFile(JSON.stringify(manifest, null, 2));
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, filePath);
+}
+async function ensureDir() {
+    await mkdir(RUNS_DIR, { recursive: true });
+}
+// SEC-R3-013: Validate runId is a UUID to prevent path traversal
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function manifestPath(runId) {
+    if (!UUID_RE.test(runId))
+        throw new Error('Invalid runId format');
+    return join(RUNS_DIR, `${runId}.json`);
+}
+/** Create a new manifest for a provisioning run. */
+export function createManifest(runId, target, region, projectName) {
+    // QA-R3-004: Wrap in serialized() for consistency with other mutation functions
+    return serialized(async () => {
+        await ensureDir();
+        const manifest = {
+            runId,
+            startedAt: new Date().toISOString(),
+            target,
+            region,
+            projectName,
+            status: 'in-progress',
+            resources: [],
+        };
+        await atomicWriteManifest(runId, manifest);
+        return manifest;
+    });
+}
+/** Record that a resource is about to be created (write-ahead). */
+export function recordResourcePending(runId, type, id, region) {
+    return serialized(async () => {
+        const manifest = await readManifest(runId);
+        if (!manifest)
+            return;
+        manifest.resources.push({ type, id, region, status: 'pending' });
+        await atomicWriteManifest(runId, manifest);
+    });
+}
+/** Record that a resource was successfully created. */
+export function recordResourceCreated(runId, type, id, region) {
+    return serialized(async () => {
+        const manifest = await readManifest(runId);
+        if (!manifest)
+            return;
+        const existing = manifest.resources.find((r) => r.type === type && r.id === id);
+        if (existing) {
+            existing.status = 'created';
+        }
+        else {
+            manifest.resources.push({ type, id, region, status: 'created' });
+        }
+        await atomicWriteManifest(runId, manifest);
+    });
+}
+/** Mark the overall run status. */
+export function updateManifestStatus(runId, status) {
+    return serialized(async () => {
+        const manifest = await readManifest(runId);
+        if (!manifest)
+            return;
+        manifest.status = status;
+        await atomicWriteManifest(runId, manifest);
+    });
+}
+/** Mark a resource as cleaned up. */
+export function recordResourceCleaned(runId, type, id) {
+    return serialized(async () => {
+        const manifest = await readManifest(runId);
+        if (!manifest)
+            return;
+        const resource = manifest.resources.find((r) => r.type === type && r.id === id);
+        if (resource)
+            resource.status = 'cleaned';
+        await atomicWriteManifest(runId, manifest);
+    });
+}
+/** Read a manifest by run ID. Returns null if not found. */
+export async function readManifest(runId) {
+    const path = manifestPath(runId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = await readFile(path, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Delete a manifest file (after successful cleanup). */
+export async function deleteManifest(runId) {
+    const path = manifestPath(runId);
+    try {
+        await unlink(path);
+    }
+    catch { /* already gone */ }
+}
+/** List all incomplete manifests (for recovery on startup). */
+export async function listIncompleteRuns() {
+    await ensureDir();
+    const incomplete = [];
+    try {
+        const files = await readdir(RUNS_DIR);
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const raw = await readFile(join(RUNS_DIR, file), 'utf-8');
+                const manifest = JSON.parse(raw);
+                if (manifest.status === 'in-progress' || manifest.status === 'failed') {
+                    const hasCreatedResources = manifest.resources.some((r) => r.status === 'created');
+                    if (hasCreatedResources) {
+                        incomplete.push(manifest);
+                    }
+                }
+            }
+            catch { /* skip corrupt files */ }
+        }
+    }
+    catch { /* directory might not exist */ }
+    return incomplete;
+}
+/** Convert manifest resources to the CreatedResource[] format used by provisioners. */
+export function manifestToCreatedResources(manifest) {
+    return manifest.resources
+        .filter((r) => r.status === 'created')
+        .map((r) => ({ type: r.type, id: r.id, region: r.region }));
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Provisioner Registry — single source of truth for provisioner map,
+ * credential scoping, and GitHub-linked target constants.
+ *
+ * ARCH-R2-002: Extracted from provision.ts + headless-deploy.ts to prevent drift.
+ */
+import type { Provisioner } from './provisioners/types.js';
+/** All available provisioners keyed by deploy target name. */
+export declare const provisioners: Record<string, Provisioner>;
+/** Credential scoping — each provisioner only receives vault keys it needs (ADR-020). */
+export declare const provisionKeys: Record<string, string[]>;
+/** Deploy targets that benefit from GitHub repo linking (ADR-015). */
+export declare const GITHUB_LINKED_TARGETS: string[];
+/** Deploy targets where GitHub push is optional (deploy via SSH/SDK instead). */
+export declare const GITHUB_OPTIONAL_TARGETS: string[];

package/dist/wizard/lib/provisioner-registry.js

@@ -0,0 +1,34 @@
+/**
+ * Provisioner Registry — single source of truth for provisioner map,
+ * credential scoping, and GitHub-linked target constants.
+ *
+ * ARCH-R2-002: Extracted from provision.ts + headless-deploy.ts to prevent drift.
+ */
+import { dockerProvisioner } from './provisioners/docker.js';
+import { awsVpsProvisioner } from './provisioners/aws-vps.js';
+import { vercelProvisioner } from './provisioners/vercel.js';
+import { railwayProvisioner } from './provisioners/railway.js';
+import { cloudflareProvisioner } from './provisioners/cloudflare.js';
+import { staticS3Provisioner } from './provisioners/static-s3.js';
+/** All available provisioners keyed by deploy target name. */
+export const provisioners = {
+    docker: dockerProvisioner,
+    vps: awsVpsProvisioner,
+    vercel: vercelProvisioner,
+    railway: railwayProvisioner,
+    cloudflare: cloudflareProvisioner,
+    static: staticS3Provisioner,
+};
+/** Credential scoping — each provisioner only receives vault keys it needs (ADR-020). */
+export const provisionKeys = {
+    vps: ['aws-access-key-id', 'aws-secret-access-key', 'aws-region'],
+    static: ['aws-access-key-id', 'aws-secret-access-key', 'aws-region'],
+    vercel: ['vercel-token'],
+    railway: ['railway-token'],
+    cloudflare: ['cloudflare-api-token', 'cloudflare-account-id'],
+    docker: [],
+};
+/** Deploy targets that benefit from GitHub repo linking (ADR-015). */
+export const GITHUB_LINKED_TARGETS = ['vercel', 'cloudflare', 'railway'];
+/** Deploy targets where GitHub push is optional (deploy via SSH/SDK instead). */
+export const GITHUB_OPTIONAL_TARGETS = ['vps', 'static'];

package/dist/wizard/lib/provisioners/aws-vps.d.ts

@@ -0,0 +1,6 @@
+/**
+ * AWS VPS provisioner — EC2 + SG + optional RDS/ElastiCache.
+ * Uses @aws-sdk for all AWS API calls.
+ */
+import type { Provisioner } from './types.js';
+export declare const awsVpsProvisioner: Provisioner;