voidforge-build 23.9.1

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

@@ -0,0 +1,228 @@
+/**
+ * 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-build-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-build-methodology
+    try {
+        const { createRequire } = await import('node:module');
+        const require_ = createRequire(import.meta.url);
+        const methodologyPkg = require_.resolve('voidforge-build-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-build-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'));
+    }
+    // Agent definitions (ADR-044)
+    const agentsSrc = join(methodologyRoot, '.claude', 'agents');
+    if (existsSync(agentsSrc)) {
+        count += await copyDir(agentsSrc, join(projectDir, '.claude', 'agents'));
+    }
+    // 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');
+    // Two paths per ADR-058:
+    //   (a) Legacy monorepo template: contains `[PROJECT_NAME]` placeholder → replace.
+    //   (b) Published methodology package: `<!-- REMOVE-FOR-NPM-PUBLISH -->` strips
+    //       the Project section in prepack.sh, so the downstream CLAUDE.md has no
+    //       Project section at all. Insert one after the first `# CLAUDE.md` heading.
+    if (content.includes('[PROJECT_NAME]')) {
+        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 ?? '');
+    }
+    else if (!content.includes('## Project')) {
+        // Published-package case: Project section was stripped. Insert a fresh one.
+        const projectBlock = [
+            '',
+            '## Project',
+            '',
+            `- **Name:** ${config.name}`,
+            `- **One-liner:** ${config.oneliner ?? ''}`,
+            `- **Domain:** ${config.domain ?? ''}`,
+            `- **Repo:** ${config.repoUrl ?? ''}`,
+            '',
+        ].join('\n');
+        // Insert after the first "# CLAUDE.md" heading, or prepend if no heading.
+        const headingMatch = content.match(/^# CLAUDE\.md\s*\n/m);
+        if (headingMatch && headingMatch.index !== undefined) {
+            const insertAt = headingMatch.index + headingMatch[0].length;
+            content = content.slice(0, insertAt) + projectBlock + content.slice(insertAt);
+        }
+        else {
+            content = `# CLAUDE.md\n${projectBlock}${content}`;
+        }
+    }
+    // If the Project section already exists and has no placeholders, leave it alone.
+    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[]>;

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;
+}