anhedral 0.8.5 → 0.9.0

package/dist/provision.js

@@ -0,0 +1,197 @@
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { applyEdits, modify } from 'jsonc-parser';
+import { atomicJson, authenticate, defaultRunner, environment, readApplication, readConfig, targetDirectory, withApplicationLock, } from './project-state.js';
+import { cloudflareRequest, listCloudflare } from './cloudflare.js';
+const resourceTypes = {
+    d1: { endpoint: '/d1/database', nameField: 'name', idField: 'uuid' },
+    r2: { endpoint: '/r2/buckets', nameField: 'name', idField: 'name' },
+    kv: { endpoint: '/storage/kv/namespaces', nameField: 'title', idField: 'id' },
+    queue: { endpoint: '/queues', nameField: 'queue_name', idField: 'queue_id' },
+};
+async function listResources(request, kind) {
+    const { endpoint } = resourceTypes[kind];
+    if (kind !== 'r2')
+        return listCloudflare(request, endpoint);
+    const value = (await request('GET', endpoint)).result;
+    if (!Array.isArray(value?.buckets) || value.truncated)
+        throw new Error('Unsupported or truncated R2 bucket listing; select resources explicitly with provider tooling.');
+    return value.buckets;
+}
+/** Provisioning and recovery use the same independently verified private-storage policy. */
+async function assertPrivateBucket(request, name) {
+    const endpoint = `${resourceTypes.r2.endpoint}/${encodeURIComponent(name)}/domains`;
+    const managed = (await request('GET', `${endpoint}/managed`)).result;
+    const custom = (await request('GET', `${endpoint}/custom`)).result;
+    if (managed?.enabled !== false ||
+        !Array.isArray(custom?.domains) ||
+        custom.domains.some((domain) => domain.enabled !== false))
+        throw new Error('Selected R2 bucket has public or unknown domain access; resolve it before using private storage.');
+}
+function resourceName(value) {
+    if (typeof value !== 'string' || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(value))
+        throw new Error('Resources require explicit lowercase names of at most 63 characters.');
+    return value;
+}
+export function planProvisioning(root) {
+    const project = readApplication(root);
+    const resources = [];
+    for (const target of project.targets) {
+        const config = readConfig(targetDirectory(root, target));
+        if ((config.env && Object.keys(config.env).length) ||
+            (config.account_id && config.account_id !== project.accountId))
+            throw new Error('Reconcile target account/environment before provisioning.');
+        for (const [kind, field] of [
+            ['d1', 'd1_databases'],
+            ['r2', 'r2_buckets'],
+            ['kv', 'kv_namespaces'],
+        ]) {
+            const entries = config[field];
+            if (entries === undefined)
+                continue;
+            if (!Array.isArray(entries))
+                throw new Error(`Invalid ${field} configuration.`);
+            entries.forEach((entry, index) => {
+                if (!entry || typeof entry.binding !== 'string' || entry.jurisdiction)
+                    throw new Error('Use an explicit provider workflow for jurisdiction-specific resources.');
+                const name = resourceName(kind === 'd1'
+                    ? entry.database_name
+                    : kind === 'r2'
+                        ? entry.bucket_name
+                        : (entry.anhedral_name ?? `${project.name}-${entry.binding.toLowerCase()}`));
+                const id = kind === 'd1' ? entry.database_id : kind === 'kv' ? entry.id : undefined;
+                resources.push({
+                    kind,
+                    name,
+                    target: target.id,
+                    id: typeof id === 'string' && !id.startsWith('REPLACE_WITH_') ? id : undefined,
+                    field: kind === 'r2' ? undefined : [field, index, kind === 'd1' ? 'database_id' : 'id'],
+                });
+            });
+        }
+        const queues = config.queues;
+        for (const entry of [...(queues?.producers ?? []), ...(queues?.consumers ?? [])]) {
+            resources.push({ kind: 'queue', name: resourceName(entry.queue), target: target.id });
+            if ('dead_letter_queue' in entry && entry.dead_letter_queue)
+                resources.push({
+                    kind: 'queue',
+                    name: resourceName(entry.dead_letter_queue),
+                    target: target.id,
+                });
+        }
+    }
+    return {
+        projectId: project.id,
+        accountId: project.accountId,
+        resources,
+        externalIntegrations: ['hyperdrive', 'pipelines'].filter((key) => project.targets.some((target) => key in readConfig(targetDirectory(root, target)))),
+    };
+}
+export async function provisionApplication(root, dryRun = false, run = defaultRunner, suppliedRequest) {
+    root = realpathSync(root);
+    const plan = planProvisioning(root);
+    if (dryRun)
+        return { ...plan, mutation: false };
+    return withApplicationLock(root, async () => {
+        const project = readApplication(root);
+        const plan = planProvisioning(root);
+        const configured = new Map(project.targets.map((target) => {
+            const file = path.join(targetDirectory(root, target), 'wrangler.jsonc');
+            return [file, readFileSync(file, 'utf8')];
+        }));
+        const assertConfiguration = () => {
+            if (JSON.stringify(readApplication(root)) !== JSON.stringify(project) ||
+                [...configured].some(([file, content]) => readFileSync(file, 'utf8') !== content))
+                throw new Error('Configuration changed during provisioning; inspect resource receipts before retrying.');
+        };
+        await authenticate(root, project, run);
+        const request = suppliedRequest ??
+            (await cloudflareRequest(project, targetDirectory(root, project.targets[0]), run, environment(project)));
+        const receipts = [];
+        const resources = new Map();
+        for (const resource of plan.resources) {
+            assertConfiguration();
+            const key = `${resource.kind}:${resource.name}`;
+            let receipt = resources.get(key);
+            if (!receipt) {
+                const { endpoint, nameField, idField } = resourceTypes[resource.kind];
+                const existing = await listResources(request, resource.kind);
+                const matches = existing.filter((item) => item[nameField] === resource.name);
+                if (matches.length > 1)
+                    throw new Error('Ambiguous provider resource name.');
+                let value = matches[0];
+                const reused = !!value;
+                if (resource.id && (!value || value[idField] !== resource.id))
+                    throw new Error('Configured resource ID does not match its account/name; no replacement was created.');
+                assertConfiguration();
+                if (!value)
+                    value = (await request('POST', endpoint, { [nameField]: resource.name }))
+                        .result;
+                if (!value || typeof value[idField] !== 'string' || !value[idField])
+                    throw new Error('Provider did not return a resource identity; inspect provider state before retrying.');
+                receipt = {
+                    kind: resource.kind,
+                    name: resource.name,
+                    id: value[idField],
+                    reused,
+                };
+                resources.set(key, receipt);
+                receipts.push(receipt);
+                // Save identities immediately: a subsequent operation can fail without losing creation evidence.
+                atomicJson(path.join(root, '.anhedral/resources.json'), {
+                    schemaVersion: 1,
+                    projectId: project.id,
+                    accountId: project.accountId,
+                    checkedAt: new Date().toISOString(),
+                    resources: receipts,
+                    state: 'reconciling',
+                });
+                if (resource.kind === 'r2')
+                    await assertPrivateBucket(request, resource.name);
+            }
+            assertConfiguration();
+            if (resource.id && receipt.id !== resource.id)
+                throw new Error('Targets disagree about a shared resource ID.');
+            if (resource.field) {
+                const target = project.targets.find((item) => item.id === resource.target);
+                const file = path.join(targetDirectory(root, target), 'wrangler.jsonc');
+                const before = readFileSync(file, 'utf8');
+                const after = applyEdits(before, modify(before, resource.field, receipt.id, {
+                    formattingOptions: { insertSpaces: true, tabSize: 2 },
+                }));
+                writeFileSync(file, after);
+                configured.set(file, after);
+            }
+        }
+        const result = {
+            schemaVersion: 1,
+            projectId: project.id,
+            accountId: project.accountId,
+            checkedAt: new Date().toISOString(),
+            resources: receipts,
+            state: 'reconciled',
+            externalIntegrations: plan.externalIntegrations,
+        };
+        atomicJson(path.join(root, '.anhedral/resources.json'), result);
+        return result;
+    });
+}
+/** Reconcile committed identities against the customer account without creating resources or rewriting configuration. */
+export async function inspectApplicationResources(root, request) {
+    const plan = planProvisioning(root);
+    const receipts = [];
+    for (const resource of plan.resources) {
+        const { nameField, idField } = resourceTypes[resource.kind];
+        const existing = await listResources(request, resource.kind);
+        const matches = existing.filter((item) => item[nameField] === resource.name);
+        if (matches.length !== 1 || typeof matches[0][idField] !== 'string' || !matches[0][idField])
+            throw new Error('Committed resource is missing or ambiguous in the registered account.');
+        const id = matches[0][idField];
+        if ((resource.field && !resource.id) || (resource.id && resource.id !== id))
+            throw new Error('Committed resource identity differs from the registered account; recovery will not replace it.');
+        if (resource.kind === 'r2')
+            await assertPrivateBucket(request, resource.name);
+        receipts.push({ kind: resource.kind, name: resource.name, id, target: resource.target });
+    }
+    return { resources: receipts, externalIntegrations: plan.externalIntegrations };
+}

package/dist/readiness.d.ts

@@ -1,4 +1,5 @@
-import { type StandardProduct } from './standard-products.js';
+import type { ResolvedStackRegistry } from './registry/resolve.js';
+import { type StandardProduct } from './stack-registry.js';
 export declare function inspectProject(root: string): {
     schemaVersion: number;
     root: string;
@@ -17,4 +18,6 @@ export declare function validateSetupPlan(plan: unknown): asserts plan is {
     registryVersion: 1;
     products: StandardProduct[];
     hosting: 'cloudflare' | 'vercel';
+    name?: string;
+    registry: ResolvedStackRegistry;
 };

package/dist/readiness.js

@@ -1,7 +1,11 @@
+import { assertSafeTarget } from './registry/receipt.js';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { CAPABILITY_REGISTRY, resolveStandardProducts } from './capabilities.js';
-import { STANDARD_PRODUCTS } from './standard-products.js';
+import { isDeepStrictEqual } from 'node:util';
+import { inspectWorkspaceGraph } from './workspace-graph.js';
+import { resolveStackRegistry, resolveStandardProducts } from './registry/resolve.js';
+import { CAPABILITY_REGISTRY } from './capabilities.js';
+import { STANDARD_PRODUCTS } from './stack-registry.js';
 export function inspectProject(root) {
     const checks = [];
     const record = (id, ok, detail) => checks.push({ id, ok, detail });
@@ -13,21 +17,77 @@ export function inspectProject(root) {
         validateSetupPlan(plan);
         const standard = read('anhedral.standard.json');
         record('setup-plan', true, `Requirements recorded by CLI ${plan.cliVersion}`);
+        try {
+            const installed = read('anhedral.registry.json');
+            const { status, workspaces: _workspaces, files: _files, remoteItems, resourcesProvisioned, ...snapshot } = installed;
+            if (status !== 'scaffolded' ||
+                resourcesProvisioned !== false ||
+                !isDeepStrictEqual(snapshot, plan.registry))
+                throw new Error('Registry provenance differs from the setup plan.');
+            for (const item of plan.registry.items)
+                for (const target of item.targets) {
+                    if (!existsSync(path.join(root, target)))
+                        throw new Error(`Registry target missing: ${item.name}.`);
+                }
+            if (remoteItems !== undefined) {
+                if (!Array.isArray(remoteItems))
+                    throw new Error('Invalid remote registry receipt.');
+                for (const item of remoteItems) {
+                    if (!item ||
+                        typeof item.source !== 'string' ||
+                        typeof item.integrity !== 'string' ||
+                        !Array.isArray(item.targets))
+                        throw new Error('Invalid remote registry provenance.');
+                    for (const target of item.targets) {
+                        assertSafeTarget(root, target);
+                        if (!existsSync(path.join(root, target)))
+                            throw new Error('Missing remote registry target.');
+                    }
+                }
+            }
+            record('stack-registry', true, 'Registry provenance and resolved targets match the setup plan');
+        }
+        catch {
+            record('stack-registry', false, 'Missing registry provenance or targets; inspect before regenerating');
+        }
+        try {
+            const workspaces = inspectWorkspaceGraph(root);
+            record('workspace-graph', workspaces.length > 0, 'Workspace names and dependencies resolve without cycles');
+        }
+        catch {
+            record('workspace-graph', false, 'Invalid workspace manifests, references or dependency cycles');
+        }
         record('cli-compatibility', plan.cliVersion === CAPABILITY_REGISTRY.cliVersion, 'Use the project CLI version or review upgrade differences');
-        record('selection', standard.schemaVersion === 1 && JSON.stringify(standard.products) === JSON.stringify(plan.products) && standard.hosting === (plan.products.includes('next') ? plan.hosting : null), 'Setup plan matches project selection');
+        record('selection', standard.schemaVersion === 1 &&
+            JSON.stringify(standard.products) === JSON.stringify(plan.products) &&
+            standard.hosting ===
+                (plan.products.includes('next') || plan.products.includes('vinext')
+                    ? plan.hosting
+                    : null), 'Setup plan matches project selection');
     }
     catch {
         record('setup-plan', false, 'Missing, invalid or unsupported setup plan; inspect the project before changing it');
     }
-    return { schemaVersion: 1, root, checks, localReady: checks.every((check) => check.ok), providerVerification: 'unverified', productionReady: false };
+    return {
+        schemaVersion: 1,
+        root,
+        checks,
+        localReady: checks.every((check) => check.ok),
+        providerVerification: 'unverified',
+        productionReady: false,
+    };
 }
 export function validateSetupPlan(plan) {
     if (!plan || typeof plan !== 'object')
         throw new Error('Invalid setup plan.');
     const value = plan;
-    if (value.schemaVersion !== 1 || value.registryVersion !== 1 || typeof value.cliVersion !== 'string')
+    if (value.schemaVersion !== 1 ||
+        value.registryVersion !== 1 ||
+        typeof value.cliVersion !== 'string')
         throw new Error('Unsupported setup plan version.');
-    if (!Array.isArray(value.products) || !value.products.length || !value.products.every((id) => STANDARD_PRODUCTS.includes(id)))
+    if (!Array.isArray(value.products) ||
+        !value.products.length ||
+        !value.products.every((id) => STANDARD_PRODUCTS.includes(id)))
         throw new Error('Unknown setup capabilities.');
     if (value.hosting !== 'cloudflare' && value.hosting !== 'vercel')
         throw new Error('Invalid hosting.');
@@ -36,12 +96,22 @@ export function validateSetupPlan(plan) {
     resolveStandardProducts(selected, value.hosting, false);
     if (selected.size !== value.products.length)
         throw new Error('Invalid or incomplete setup selection.');
+    if (value.name !== undefined && typeof value.name !== 'string')
+        throw new Error('Invalid setup project name.');
+    if (!isDeepStrictEqual(value.registry, resolveStackRegistry({
+        products: value.products,
+        hosting: value.hosting,
+        name: value.name,
+    })))
+        throw new Error('Invalid or inconsistent stack registry.');
 }
 function validateRequirements(setup, products) {
     if (!setup || typeof setup !== 'object')
         throw new Error('Missing setup requirements.');
     const value = setup;
-    if (value.resourcesProvisioned !== false || !Array.isArray(value.capabilities) || value.capabilities.length !== products.length)
+    if (value.resourcesProvisioned !== false ||
+        !Array.isArray(value.capabilities) ||
+        value.capabilities.length !== products.length)
         throw new Error('Invalid capability requirements.');
     const ids = value.capabilities.map((item) => validateCapability(item));
     if (new Set(ids).size !== products.length || !products.every((id) => ids.includes(id)))
@@ -51,7 +121,9 @@ function validateCapability(item) {
     if (!item || typeof item !== 'object')
         throw new Error('Invalid capability.');
     const value = item;
-    if (typeof value.id !== 'string' || typeof value.purpose !== 'string' || !['planned', 'starter'].includes(String(value.status)))
+    if (typeof value.id !== 'string' ||
+        typeof value.purpose !== 'string' ||
+        !['planned', 'starter'].includes(String(value.status)))
         throw new Error('Invalid capability metadata.');
     for (const key of ['tools', 'access', 'credentials', 'resources', 'verify']) {
         if (!Array.isArray(value[key]) || !value[key].every((entry) => typeof entry === 'string'))

package/dist/registry/add.d.ts

@@ -0,0 +1,22 @@
+import type { StandardRunner } from './types.js';
+export interface AddRequest {
+    items: string[];
+    registry?: string;
+    integrity?: string;
+    dryRun?: boolean;
+    skipInstall?: boolean;
+}
+/** Add recipes to an initialized workspace, refusing edits to customer-owned source. */
+export declare function addStackItems(root: string, request: AddRequest, run?: StandardRunner): Promise<{
+    files: string[];
+    conflicts: string[];
+    registry?: {
+        source: string;
+        integrity: string;
+    } | undefined;
+    schemaVersion: number;
+    root: string;
+    dryRun: boolean;
+    items: string[];
+    remoteItems: string[];
+}>;

package/dist/registry/add.js

@@ -0,0 +1,198 @@
+import { configureSecurityBackports } from '../security-backports.js';
+import { bootstrapWorkspace } from '../scaffold/bootstrap.js';
+import { registerApplication } from '../project-state.js';
+import { registerVercelApplication } from '../vercel.js';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { applyEdits, modify, parse } from 'jsonc-parser';
+import { STANDARD_PRODUCTS, installStackItem } from '../stack-registry.js';
+import { inspectProject, validateSetupPlan } from '../readiness.js';
+import { GENERATOR_VERSION } from '../version.js';
+import { runStagedTransaction } from '../transaction.js';
+import { inspectWorkspaceGraph } from '../workspace-graph.js';
+import { execFile } from '../util.js';
+import { json, put, readJson } from '../scaffold/files.js';
+import { writeStandardRoot } from '../scaffold/workspace.js';
+import { createRecipeContext } from './context.js';
+import { resolveStackRegistry, resolveStandardProducts } from './resolve.js';
+import { sourceFiles, assertSafeTarget } from './receipt.js';
+import { loadSourceRegistry, resolveSourceItems } from './remote.js';
+/** Add recipes to an initialized workspace, refusing edits to customer-owned source. */
+export async function addStackItems(root, request, run = execFile) {
+    root = realpathSync(root);
+    if (!request.items.length)
+        throw new Error('Select at least one registry item.');
+    const plan = readJson(root, 'anhedral.setup.json');
+    validateSetupPlan(plan);
+    if (plan.cliVersion !== GENERATOR_VERSION)
+        throw new Error('Use the project CLI version before adding recipes.');
+    if (!inspectProject(root).localReady)
+        throw new Error('Run doctor and resolve project provenance or workspace errors before add.');
+    const receipt = readJson(root, 'anhedral.registry.json');
+    if (!receipt.files || typeof receipt.files !== 'object' || Array.isArray(receipt.files))
+        throw new Error('This project has no scaffold fingerprints; migrate it deliberately before using add.');
+    const baseline = receipt.files;
+    const selected = new Set(plan.products);
+    let remote;
+    if (request.registry)
+        remote = await loadSourceRegistry(request.registry);
+    else
+        for (const id of request.items) {
+            if (!STANDARD_PRODUCTS.includes(id))
+                throw new Error(`Unknown stack product: ${id}.`);
+            selected.add(id);
+        }
+    if (request.integrity && (!remote || remote.integrity !== request.integrity))
+        throw new Error('Source registry integrity differs from the reviewed payload.');
+    resolveStandardProducts(selected, plan.hosting, false);
+    const options = {
+        root,
+        name: plan.name ?? path.basename(root),
+        products: [...selected].sort(),
+        hosting: plan.hosting,
+        skipInstall: !!request.skipInstall,
+        dryRun: false,
+        json: true,
+        initializeGit: false,
+    };
+    const registry = resolveStackRegistry(options);
+    const oldItems = new Map(plan.registry.items.map((item) => [item.name, item]));
+    const recipes = registry.items.filter((item) => item.installer === 'recipe' && !isDeepStrictEqual(oldItems.get(item.name), item));
+    // Relocating auth, database or service ownership requires a migration, not an additive scaffold.
+    for (const item of registry.items) {
+        const before = oldItems.get(item.name);
+        if (before && before.targets.some((target) => !item.targets.includes(target)))
+            throw new Error(`Adding this selection relocates ${item.name}; migrate its existing source explicitly.`);
+    }
+    const remoteItems = remote ? resolveSourceItems(remote.registry, request.items) : [];
+    if (remote) {
+        const previous = Array.isArray(receipt.remoteItems) ? receipt.remoteItems : [];
+        for (const item of remoteItems) {
+            const identity = `${remote.source}#${item.name}`;
+            const targets = item.files.map((file) => file.target);
+            for (const installed of previous) {
+                if (installed.identity === identity &&
+                    installed.targets.some((target) => !targets.includes(target)))
+                    throw new Error(`Remote update relocates ${item.name}; migrate its source explicitly.`);
+                if (installed.identity !== identity &&
+                    installed.targets.some((target) => targets.includes(target)))
+                    throw new Error(`Remote target is already owned by ${installed.name}.`);
+            }
+        }
+    }
+    const before = sourceFiles(root);
+    const receiptText = readFileSync(path.join(root, 'anhedral.registry.json'), 'utf8');
+    const commitPaths = [];
+    const conflicts = [];
+    const result = {
+        schemaVersion: 1,
+        root,
+        dryRun: !!request.dryRun,
+        items: registry.items
+            .filter((item) => !isDeepStrictEqual(oldItems.get(item.name), item))
+            .map((item) => item.name),
+        remoteItems: remoteItems.map((item) => item.name),
+        ...(remote ? { registry: { source: remote.source, integrity: remote.integrity } } : {}),
+        files: commitPaths,
+        conflicts,
+    };
+    await runStagedTransaction(root, {
+        dryRun: !!request.dryRun,
+        commitPaths,
+        seedPaths: [...before.keys(), 'anhedral.registry.json'],
+        build: async (stage) => {
+            const context = createRecipeContext(stage, options);
+            for (const item of registry.items)
+                Object.assign(context.bindings, item.bindings);
+            if (recipes.some((item) => ['vinext', 'next'].includes(item.name)) &&
+                !existsSync(path.join(stage, 'apps/web/package.json')))
+                bootstrapWorkspace(stage, options.name, run, true);
+            for (const item of recipes)
+                await installStackItem(item, context);
+            // Configuration items affect the existing runtime without regenerating its application source.
+            const configurationItems = registry.items.filter((item) => !isDeepStrictEqual(oldItems.get(item.name), item) && item.bindings);
+            if (configurationItems.length) {
+                const file = `apps/${context.runtimeApp}/wrangler.jsonc`;
+                let content = readFileSync(path.join(stage, file), 'utf8');
+                const config = parse(content);
+                for (const item of configurationItems)
+                    for (const [key, value] of Object.entries(item.bindings)) {
+                        if (config[key] !== undefined && !isDeepStrictEqual(config[key], value))
+                            throw new Error(`Existing ${key} configuration conflicts with ${item.name}; configure it explicitly.`);
+                        content = applyEdits(content, modify(content, [key], value, {
+                            formattingOptions: { insertSpaces: true, tabSize: 2 },
+                        }));
+                    }
+                put(stage, file, content);
+            }
+            for (const item of remoteItems)
+                for (const file of item.files) {
+                    assertSafeTarget(stage, file.target);
+                    put(stage, file.target, file.content);
+                }
+            writeStandardRoot(stage, options, registry, true);
+            if (options.products.includes('next') && options.hosting === 'vercel')
+                registerVercelApplication(stage);
+            if ([...sourceFiles(stage).keys()].some((file) => /^apps\/[^/]+\/wrangler\.jsonc$/.test(file)))
+                registerApplication(stage, true);
+            if (!request.dryRun)
+                run('pnpm', ['install', '--lockfile-only', '--no-frozen-lockfile', '--ignore-scripts'], stage);
+            if (!request.dryRun && configureSecurityBackports(stage))
+                run('pnpm', ['install', '--lockfile-only', '--no-frozen-lockfile', '--ignore-scripts'], stage);
+            const after = sourceFiles(stage);
+            const files = { ...baseline };
+            for (const [file, hash] of after) {
+                if (before.get(file) === hash)
+                    continue;
+                if (before.has(file) &&
+                    baseline[file] !== before.get(file) &&
+                    file !== 'anhedral.project.json')
+                    conflicts.push(file);
+                commitPaths.push(file);
+                files[file] = hash;
+            }
+            // Never delete preexisting source as a side effect of an addition.
+            for (const file of before.keys())
+                if (!after.has(file))
+                    conflicts.push(file);
+            if (conflicts.length && !request.dryRun)
+                throw new Error(`Addition conflicts with edited or untracked source: ${conflicts.join(', ')}. No files were installed.`);
+            const remoteReceipts = Array.isArray(receipt.remoteItems) ? [...receipt.remoteItems] : [];
+            for (const item of remoteItems) {
+                const identity = `${remote.source}#${item.name}`;
+                const previous = remoteReceipts.findIndex((entry) => entry.identity === identity);
+                const entry = {
+                    identity,
+                    name: item.name,
+                    version: item.version,
+                    source: remote.source,
+                    integrity: remote.integrity,
+                    targets: item.files.map((file) => file.target),
+                };
+                if (previous >= 0)
+                    remoteReceipts[previous] = entry;
+                else
+                    remoteReceipts.push(entry);
+            }
+            json(stage, 'anhedral.registry.json', {
+                ...registry,
+                status: 'scaffolded',
+                resourcesProvisioned: false,
+                workspaces: inspectWorkspaceGraph(stage),
+                files,
+                ...(remoteReceipts.length ? { remoteItems: remoteReceipts } : {}),
+            });
+            commitPaths.push('anhedral.registry.json');
+            // Detect concurrent changes even to source that this addition would otherwise preserve.
+            if (!isDeepStrictEqual(sourceFiles(root), before) ||
+                readFileSync(path.join(root, 'anhedral.registry.json'), 'utf8') !== receiptText)
+                throw new Error('Workspace changed during addition; retry after reviewing source.');
+        },
+        afterCommit: () => {
+            if (!request.skipInstall)
+                run('pnpm', ['install', '--frozen-lockfile', '--ignore-scripts'], root);
+        },
+    });
+    return result;
+}

package/dist/registry/bootstrap.d.ts

@@ -0,0 +1,2 @@
+export declare const BOOTSTRAP_COMMAND: readonly ["pnpm", "dlx", "shadcn@4.21.4", "init", "--monorepo", "--template", "next"];
+export declare function bootstrapArguments(name: string, cwd: string): string[];

package/dist/registry/bootstrap.js

@@ -0,0 +1,14 @@
+import { SHADCN_VERSION } from '../dependencies.js';
+const SHADCN_PACKAGE = `shadcn@${SHADCN_VERSION}`;
+export const BOOTSTRAP_COMMAND = [
+    'pnpm',
+    'dlx',
+    SHADCN_PACKAGE,
+    'init',
+    '--monorepo',
+    '--template',
+    'next',
+];
+export function bootstrapArguments(name, cwd) {
+    return [...BOOTSTRAP_COMMAND.slice(1), '--defaults', '--name', name, '--cwd', cwd];
+}

package/dist/registry/commands.d.ts

@@ -0,0 +1,2 @@
+export declare function runRegistry(args: string[], json: boolean): Promise<void>;
+export declare function runAdd(args: string[]): Promise<void>;