anhedral 0.10.1 → 0.11.0

package/dist/providers/schema.js

@@ -0,0 +1,49 @@
+import { PROVIDER_DEFINITIONS, PROVIDER_EVENT_PATTERN, PROVIDER_IDENTITY_PATTERN, PROVIDER_TEXT_PATTERN, PROVIDER_WEBHOOK_PATTERN, } from './definitions.js';
+function fieldSchema(field) {
+    if (field.kind === 'events')
+        return {
+            type: 'array',
+            minItems: 1,
+            maxItems: 100,
+            uniqueItems: true,
+            items: { type: 'string', pattern: PROVIDER_EVENT_PATTERN },
+        };
+    return {
+        type: 'string',
+        maxLength: 255,
+        ...(field.choices
+            ? { enum: field.choices }
+            : {
+                pattern: field.kind === 'identity'
+                    ? PROVIDER_IDENTITY_PATTERN
+                    : field.kind === 'https-url'
+                        ? PROVIDER_WEBHOOK_PATTERN
+                        : PROVIDER_TEXT_PATTERN,
+            }),
+    };
+}
+/** Editor schema validates syntax; selected-stack and provisioning readiness checks
+ * remain application rules, since templates deliberately contain empty choices. */
+export const PROVIDER_CONFIGURATION_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'Anhedral provider configuration',
+    description: 'Nonsecret resource choices. Supply credentials through the environment.',
+    type: 'object',
+    additionalProperties: false,
+    required: ['schemaVersion', 'providers'],
+    properties: {
+        schemaVersion: { const: 1 },
+        providers: {
+            type: 'object',
+            additionalProperties: false,
+            properties: Object.fromEntries(Object.entries(PROVIDER_DEFINITIONS).map(([id, definition]) => [
+                id,
+                {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: Object.fromEntries(Object.entries(definition.fields).map(([key, field]) => [key, fieldSchema(field)])),
+                },
+            ])),
+        },
+    },
+};

package/dist/providers/state.d.ts

@@ -0,0 +1,56 @@
+import { atomicJson, type DeliveryRunner } from '../project-state.js';
+import { type ApiObject, type ApiRequest } from './api.js';
+import { type MinimalReceipt } from './receipts.js';
+import { type IntegrationProvider, type ProviderSettings } from './config.js';
+export interface OperationDescriptor {
+    key: string;
+    route: string;
+}
+export declare function privateStateDirectory(root: string, run: DeliveryRunner): Promise<string>;
+export declare function readProviderStateStatus(directory: string): {
+    schemaVersion: number;
+    providers: {
+        provider: string;
+        operations: {
+            recovery: string;
+            descriptor?: OperationDescriptor | undefined;
+            resources?: MinimalReceipt | undefined;
+            operation: string;
+            status: "pending" | "complete";
+        }[];
+    }[];
+};
+/** Store credentials before completing a minimal receipt. A crash leaves a pending
+ * operation, never permission to replay a provider mutation with an unknown outcome. */
+export declare class ProvisioningState {
+    private readonly write;
+    private readonly file;
+    private readonly credentialsFile;
+    private readonly state;
+    private readonly credentials;
+    constructor(directory: string, write?: typeof atomicJson);
+    private assertCredentials;
+    private retainCredentials;
+    private migrate;
+    /** No configurations, credentials, provider payloads or mutation bodies in status. */
+    status(): {
+        schemaVersion: number;
+        providers: {
+            provider: string;
+            operations: {
+                operation: string;
+                status: "pending" | "complete";
+                resources: MinimalReceipt;
+            }[];
+        }[];
+    };
+    context(id: IntegrationProvider, settings: ProviderSettings): void;
+    recoverResource(id: IntegrationProvider, operation: string, resource: string, settings: ProviderSettings, api: ApiRequest, beforeCommit?: () => void): Promise<{
+        provider: keyof import("./definitions.js").ProviderSettingsById;
+        operation: string;
+        status: string;
+        resources: MinimalReceipt;
+        mutation: string;
+    }>;
+    create(id: IntegrationProvider, key: string, api: ApiRequest, route: string, body: ApiObject): Promise<ApiObject>;
+}

package/dist/providers/state.js

@@ -0,0 +1,329 @@
+import path from 'node:path';
+import { existsSync, lstatSync, mkdirSync, realpathSync } from 'node:fs';
+import { readBoundedFile, MAX_PROJECT_JSON_BYTES } from '../bounded-file.js';
+import { atomicJson } from '../project-state.js';
+import { digest, object, ProviderRequestError } from './api.js';
+import { verifyRecoveredResource } from './recovery-verification.js';
+import { splitReceipt, validReceipt, validCredentials, restoreReceipt, } from './receipts.js';
+import { INTEGRATION_PROVIDERS, } from './config.js';
+function validDescriptor(value) {
+    return (record(value) &&
+        Object.keys(value).every((key) => ['key', 'route'].includes(key)) &&
+        typeof value.key === 'string' &&
+        /^(project|application|domain|web-app|ios-app|android-app|sending-key|webhook|service-account|client-key)$/.test(value.key) &&
+        typeof value.route === 'string' &&
+        value.route.length <= 1024 &&
+        /^\/[a-zA-Z0-9_/-]+$/.test(value.route) &&
+        !value.route.includes('//'));
+}
+function record(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/** Validate saved operations before trusting their replay protection or resource values. */
+function validState(value) {
+    if (!record(value) ||
+        !(value.schemaVersion === 1 || value.schemaVersion === 2) ||
+        Object.keys(value).some((key) => !['schemaVersion', 'providers'].includes(key)) ||
+        !record(value.providers))
+        return false;
+    return Object.entries(value.providers).every(([id, provider]) => {
+        if (!INTEGRATION_PROVIDERS.includes(id) ||
+            !record(provider) ||
+            Object.keys(provider).some((key) => !['config', 'operations'].includes(key)) ||
+            typeof provider.config !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(provider.config) ||
+            !record(provider.operations))
+            return false;
+        return Object.entries(provider.operations).every(([key, operation]) => {
+            if (!/^[a-f0-9]{64}$/.test(key) ||
+                !record(operation) ||
+                Object.keys(operation).some((field) => !(value.schemaVersion === 1
+                    ? ['status', 'value']
+                    : ['status', 'value', 'credentialFields', 'descriptor']).includes(field)))
+                return false;
+            if (operation.descriptor !== undefined && !validDescriptor(operation.descriptor))
+                return false;
+            if (operation.status === 'pending')
+                return !Object.hasOwn(operation, 'value') && !Object.hasOwn(operation, 'credentialFields');
+            if (operation.status !== 'complete' || !record(operation.value))
+                return false;
+            if (value.schemaVersion === 1)
+                return true;
+            return (validReceipt(id, operation.value) &&
+                (operation.credentialFields === undefined ||
+                    (Array.isArray(operation.credentialFields) &&
+                        new Set(operation.credentialFields).size === operation.credentialFields.length &&
+                        operation.credentialFields.every((field) => typeof field === 'string' &&
+                            validCredentials(id, { [field]: 'validation-placeholder' })))));
+        });
+    });
+}
+export async function privateStateDirectory(root, run) {
+    root = realpathSync(root);
+    const directory = path.join(root, '.anhedral');
+    if (existsSync(directory) &&
+        (lstatSync(directory).isSymbolicLink() || !lstatSync(directory).isDirectory()))
+        throw new Error('Provider state directory must be a regular directory.');
+    const environment = { ...process.env, CI: '1', NO_COLOR: '1' };
+    if (realpathSync((await run('git', ['rev-parse', '--show-toplevel'], root, environment)).trim()) !==
+        root)
+        throw new Error('Provider configuration requires its own application repository.');
+    for (const file of [
+        '.anhedral/providers.json',
+        '.anhedral/provider-credentials.json',
+        '.anhedral/runtime.json',
+    ]) {
+        if ((await run('git', ['ls-files', '--', file], root, environment)).trim())
+            throw new Error('Provider state must not be tracked.');
+        if ((await run('git', ['check-ignore', '--no-index', '--', file], root, environment)).trim() !==
+            file)
+            throw new Error('Ignore .anhedral/ before provisioning providers.');
+    }
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (realpathSync(directory) !== directory)
+        throw new Error('Provider state directory escapes the project.');
+    return directory;
+}
+function validCredentialsState(value) {
+    return (record(value) &&
+        value.schemaVersion === 1 &&
+        !Object.keys(value).some((key) => !['schemaVersion', 'providers'].includes(key)) &&
+        record(value.providers) &&
+        Object.entries(value.providers).every(([id, operations]) => INTEGRATION_PROVIDERS.includes(id) &&
+            record(operations) &&
+            Object.entries(operations).every(([key, entries]) => /^[a-f0-9]{64}$/.test(key) && validCredentials(id, entries))));
+}
+function privateJson(file) {
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error('Provider state must be a regular private file.');
+    if (process.platform !== 'win32' && stat.mode & 0o077)
+        throw new Error('Provider state contains credentials; restrict its permissions to 0600.');
+    try {
+        return JSON.parse(readBoundedFile(file, MAX_PROJECT_JSON_BYTES).toString('utf8'));
+    }
+    catch {
+        throw new Error('Invalid provider state.');
+    }
+}
+export function readProviderStateStatus(directory) {
+    const file = path.join(directory, 'providers.json');
+    if (!existsSync(file))
+        return { schemaVersion: 2, providers: [] };
+    if (lstatSync(directory).isSymbolicLink() || !lstatSync(directory).isDirectory())
+        throw new Error('Provider state directory must be a regular private directory.');
+    const state = privateJson(file);
+    if (!validState(state))
+        throw new Error('Invalid provider state.');
+    return {
+        schemaVersion: 2,
+        providers: Object.entries(state.providers).map(([id, provider]) => ({
+            provider: id,
+            operations: Object.entries(provider.operations).map(([operation, saved]) => ({
+                operation,
+                status: saved.status,
+                ...(saved.value
+                    ? { resources: splitReceipt(id, saved.value).receipt }
+                    : {}),
+                ...(saved.descriptor ? { descriptor: saved.descriptor } : {}),
+                recovery: !saved.descriptor
+                    ? 'unknown-descriptor'
+                    : ['sending-key', 'webhook', 'service-account'].includes(saved.descriptor.key)
+                        ? 'requires-one-time-credential'
+                        : ['project', 'application', 'domain', 'web-app', 'ios-app', 'android-app'].includes(saved.descriptor.key)
+                            ? 'verified-resource'
+                            : 'unsupported-operation',
+            })),
+        })),
+    };
+}
+/** Store credentials before completing a minimal receipt. A crash leaves a pending
+ * operation, never permission to replay a provider mutation with an unknown outcome. */
+export class ProvisioningState {
+    write;
+    file;
+    credentialsFile;
+    state;
+    credentials;
+    constructor(directory, write = atomicJson) {
+        this.write = write;
+        if (lstatSync(directory).isSymbolicLink() || !lstatSync(directory).isDirectory())
+            throw new Error('Provider state directory must be a regular private directory.');
+        directory = realpathSync(directory);
+        this.file = path.join(directory, 'providers.json');
+        this.credentialsFile = path.join(directory, 'provider-credentials.json');
+        const credentials = existsSync(this.credentialsFile)
+            ? privateJson(this.credentialsFile)
+            : { schemaVersion: 1, providers: {} };
+        if (!validCredentialsState(credentials))
+            throw new Error('Invalid provider credential state.');
+        this.credentials = credentials;
+        const state = existsSync(this.file)
+            ? privateJson(this.file)
+            : { schemaVersion: 2, providers: {} };
+        if (!validState(state))
+            throw new Error('Invalid provider state.');
+        this.state = state;
+        if (state.schemaVersion === 1)
+            this.migrate();
+        this.assertCredentials();
+    }
+    assertCredentials() {
+        for (const [id, provider] of Object.entries(this.state.providers)) {
+            for (const [operation, saved] of Object.entries(provider.operations)) {
+                const credentials = this.credentials.providers[id]?.[operation] ?? {};
+                if (saved.credentialFields?.some((field) => !credentials[field]))
+                    throw new Error('Provider creation credentials are missing. Restore private state before retrying.');
+            }
+        }
+    }
+    retainCredentials(id, operation, entries) {
+        if (!Object.keys(entries).length)
+            return;
+        const provider = (this.credentials.providers[id] ??= {});
+        const previous = provider[operation];
+        if (previous && digest(previous) !== digest(entries))
+            throw new Error('Provider credential state conflicts with the saved creation result.');
+        provider[operation] = entries;
+    }
+    migrate() {
+        const migrated = { schemaVersion: 2, providers: {} };
+        for (const id of INTEGRATION_PROVIDERS) {
+            const provider = this.state.providers[id];
+            if (!provider)
+                continue;
+            const operations = {};
+            for (const [key, saved] of Object.entries(provider.operations)) {
+                if (saved.status === 'pending')
+                    operations[key] = { status: 'pending' };
+                else {
+                    const { receipt, credentials } = splitReceipt(id, saved.value);
+                    this.retainCredentials(id, key, credentials);
+                    operations[key] = {
+                        status: 'complete',
+                        value: receipt,
+                        ...(Object.keys(credentials).length
+                            ? { credentialFields: Object.keys(credentials) }
+                            : {}),
+                    };
+                }
+            }
+            migrated.providers[id] = { config: provider.config, operations };
+        }
+        // Credentials first: if the receipt write fails, the original schema 1 response
+        // remains intact and a retry can safely repeat this local migration.
+        this.write(this.credentialsFile, this.credentials);
+        this.write(this.file, migrated);
+        this.state.schemaVersion = 2;
+        this.state.providers = migrated.providers;
+    }
+    /** No configurations, credentials, provider payloads or mutation bodies in status. */
+    status() {
+        return {
+            schemaVersion: 2,
+            providers: Object.entries(this.state.providers).map(([id, provider]) => ({
+                provider: id,
+                operations: Object.entries(provider.operations).map(([operation, saved]) => ({
+                    operation,
+                    status: saved.status,
+                    resources: saved.value ?? {},
+                })),
+            })),
+        };
+    }
+    context(id, settings) {
+        const hash = digest(settings);
+        const saved = this.state.providers[id];
+        if (saved && saved.config !== hash)
+            throw new Error(`${id}: desired configuration changed. Reconcile saved resource IDs before changing provider state.`);
+        if (!saved)
+            this.state.providers[id] = { config: hash, operations: {} };
+    }
+    async recoverResource(id, operation, resource, settings, api, beforeCommit = () => { }) {
+        this.context(id, settings);
+        const provider = this.state.providers[id];
+        const saved = provider.operations[operation];
+        if (!saved || saved.status !== 'pending')
+            throw new Error('Only an explicitly identified pending provider operation can be reconciled.');
+        if (!saved.descriptor)
+            throw new Error('This legacy pending operation has no trusted descriptor. Inspect the provider and retain its journal; automatic recovery is unavailable.');
+        const receipt = await verifyRecoveredResource(id, saved.descriptor, resource, settings, api);
+        beforeCommit();
+        const complete = {
+            status: 'complete',
+            descriptor: saved.descriptor,
+            value: receipt,
+        };
+        provider.operations[operation] = complete;
+        try {
+            this.write(this.file, this.state);
+        }
+        catch (error) {
+            provider.operations[operation] = saved;
+            throw error;
+        }
+        return {
+            provider: id,
+            operation,
+            status: 'complete',
+            resources: receipt,
+            mutation: 'local-receipt-only',
+        };
+    }
+    async create(id, key, api, route, body) {
+        const state = this.state.providers[id];
+        if (!state)
+            throw new Error('Select a provider configuration before creating resources.');
+        const operation = digest({ key, route, body });
+        const saved = state.operations[operation];
+        if (saved?.status === 'complete')
+            return restoreReceipt(saved.value, this.credentials.providers[id]?.[operation] ?? {});
+        if (saved)
+            throw new Error(`${id}: interrupted ${key} creation has an unknown outcome. Inspect the provider and reconcile the saved operation before retrying.`);
+        const descriptor = { key, route };
+        if (!validDescriptor(descriptor))
+            throw new Error('Unsupported provider operation descriptor.');
+        state.operations[operation] = { status: 'pending', descriptor };
+        this.write(this.file, this.state);
+        let value;
+        try {
+            value = object(await api(route, 'POST', body, operation));
+        }
+        catch (error) {
+            if (error instanceof ProviderRequestError && error.rejected) {
+                delete state.operations[operation];
+                this.write(this.file, this.state);
+            }
+            throw error;
+        }
+        const { receipt, credentials } = splitReceipt(id, value);
+        const expected = id === 'resend' && key === 'sending-key'
+            ? 'token'
+            : id === 'stripe' && key === 'webhook'
+                ? 'secret'
+                : id === 'openai' && key === 'service-account'
+                    ? 'api_key'
+                    : undefined;
+        if (expected && !credentials[expected])
+            throw new Error('Provider omitted the one-time creation credential. Inspect the pending operation before retrying.');
+        this.retainCredentials(id, operation, credentials);
+        if (Object.keys(credentials).length)
+            this.write(this.credentialsFile, this.credentials);
+        state.operations[operation] = {
+            status: 'complete',
+            descriptor,
+            value: receipt,
+            ...(Object.keys(credentials).length
+                ? { credentialFields: Object.keys(credentials) }
+                : {}),
+        };
+        try {
+            this.write(this.file, this.state);
+        }
+        catch (error) {
+            state.operations[operation] = { status: 'pending', descriptor };
+            throw error;
+        }
+        return restoreReceipt(receipt, credentials);
+    }
+}

package/dist/provision.d.ts

@@ -1,7 +1,7 @@
 import { type DeliveryRunner } from './project-state.js';
 import { type CloudflareRequest } from './cloudflare.js';
 interface Resource {
-    kind: 'd1' | 'r2' | 'kv' | 'queue';
+    kind: 'd1' | 'r2' | 'kv' | 'queue' | 'stream';
     name: string;
     id?: string;
     target: string;

package/dist/provision.js

@@ -8,9 +8,28 @@ const resourceTypes = {
     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' },
+    stream: { endpoint: '/pipelines/v1/streams', nameField: 'name', idField: 'id' },
 };
 async function listResources(request, kind) {
     const { endpoint } = resourceTypes[kind];
+    if (kind === 'stream') {
+        const streams = [];
+        let bytes = 0;
+        for (let page = 0; page < 1000; page++) {
+            const response = await request('GET', `${endpoint}?page=${page}&per_page=100`);
+            if (!Array.isArray(response.result))
+                throw new Error('Unsupported stream listing.');
+            if (response.result.some((item) => !item || typeof item !== 'object' || Array.isArray(item)))
+                throw new Error('Unsupported stream resource.');
+            streams.push(...response.result);
+            bytes += Buffer.byteLength(JSON.stringify(response.result));
+            if (streams.length > 10_000 || bytes > 10 * 1024 * 1024)
+                throw new Error('Stream listing exceeded collection limit; select resource IDs explicitly.');
+            if (response.result.length < 100)
+                return streams;
+        }
+        throw new Error('Stream listing exceeded pagination limit.');
+    }
     if (kind !== 'r2')
         return listCloudflare(request, endpoint);
     const value = (await request('GET', endpoint)).result;
@@ -18,6 +37,15 @@ async function listResources(request, kind) {
         throw new Error('Unsupported or truncated R2 bucket listing; select resources explicitly with provider tooling.');
     return value.buckets;
 }
+async function assertPrivateStream(request, id) {
+    if (!/^[a-f0-9]{32}$/i.test(id))
+        throw new Error('Invalid Basin stream ID.');
+    const stream = (await request('GET', `${resourceTypes.stream.endpoint}/${id}`)).result;
+    if (stream?.http?.enabled !== false ||
+        stream.worker_binding?.enabled !== true ||
+        stream.format?.type !== 'json')
+        throw new Error('Basin stream must use a private Worker binding with JSON events and HTTP ingestion disabled.');
+}
 /** Provisioning and recovery use the same independently verified private-storage policy. */
 async function assertPrivateBucket(request, name) {
     const endpoint = `${resourceTypes.r2.endpoint}/${encodeURIComponent(name)}/domains`;
@@ -79,12 +107,30 @@ export function planProvisioning(root) {
                     target: target.id,
                 });
         }
+        if (config.pipelines !== undefined) {
+            if (!Array.isArray(config.pipelines))
+                throw new Error('Invalid Basin stream bindings.');
+            config.pipelines.forEach((entry, index) => {
+                if (!entry ||
+                    typeof entry.binding !== 'string' ||
+                    typeof entry.stream !== 'string' ||
+                    entry.pipeline)
+                    throw new Error('Use explicit Basin stream bindings.');
+                resources.push({
+                    kind: 'stream',
+                    name: resourceName(`${project.name}-${entry.binding.toLowerCase()}`),
+                    target: target.id,
+                    id: entry.stream.startsWith('REPLACE_WITH_') ? undefined : entry.stream,
+                    field: ['pipelines', index, 'stream'],
+                });
+            });
+        }
     }
     return {
         projectId: project.id,
         accountId: project.accountId,
         resources,
-        externalIntegrations: ['hyperdrive', 'pipelines'].filter((key) => project.targets.some((target) => key in readConfig(targetDirectory(root, target)))),
+        externalIntegrations: ['hyperdrive'].filter((key) => project.targets.some((target) => key in readConfig(targetDirectory(root, target)))),
     };
 }
 export async function provisionApplication(root, dryRun = false, run = defaultRunner, suppliedRequest) {
@@ -125,8 +171,16 @@ export async function provisionApplication(root, dryRun = false, run = defaultRu
                     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;
+                    value = (await request('POST', endpoint, {
+                        [nameField]: resource.name,
+                        ...(resource.kind === 'stream'
+                            ? {
+                                http: { enabled: false, authentication: true },
+                                worker_binding: { enabled: true },
+                                format: { type: 'json', unstructured: true },
+                            }
+                            : {}),
+                    })).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 = {
@@ -148,6 +202,8 @@ export async function provisionApplication(root, dryRun = false, run = defaultRu
                 });
                 if (resource.kind === 'r2')
                     await assertPrivateBucket(request, resource.name);
+                if (resource.kind === 'stream')
+                    await assertPrivateStream(request, receipt.id);
             }
             assertConfiguration();
             if (resource.id && receipt.id !== resource.id)
@@ -191,6 +247,8 @@ export async function inspectApplicationResources(root, request) {
             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);
+        if (resource.kind === 'stream')
+            await assertPrivateStream(request, id);
         receipts.push({ kind: resource.kind, name: resource.name, id, target: resource.target });
     }
     return { resources: receipts, externalIntegrations: plan.externalIntegrations };

package/dist/registry/add.d.ts

@@ -1,11 +1,17 @@
 import type { StandardRunner } from './types.js';
+import { type SourcePreview } from './preview.js';
 export interface AddRequest {
     items: string[];
     dryRun?: boolean;
     skipInstall?: boolean;
+    preview?: {
+        mode: 'diff' | 'view';
+        path?: string;
+    };
 }
 /** Add recipes to an initialized workspace, refusing edits to customer-owned source. */
 export declare function addStackItems(root: string, request: AddRequest, run?: StandardRunner): Promise<{
+    previews?: SourcePreview[] | undefined;
     schemaVersion: number;
     root: string;
     dryRun: boolean;

package/dist/registry/add.js

@@ -18,11 +18,20 @@ import { writeStandardRoot } from '../scaffold/workspace.js';
 import { createRecipeContext } from './context.js';
 import { resolveStackRegistry, resolveStandardProducts } from './resolve.js';
 import { sourceFiles } from './receipt.js';
+import { sourcePreview, validatePreviewPath, MAX_PREVIEW_TOTAL_BYTES, } from './preview.js';
 /** Add recipes to an initialized workspace, refusing edits to customer-owned source. */
 export async function addStackItems(root, request, run = execFile) {
     for (const key of Object.keys(request))
-        if (!['items', 'dryRun', 'skipInstall'].includes(key))
+        if (!['items', 'dryRun', 'skipInstall', 'preview'].includes(key))
             throw new Error(`Unknown add option: ${key}. Only bundled registry items are supported.`);
+    if (request.preview) {
+        if (!request.dryRun ||
+            !['diff', 'view'].includes(request.preview.mode) ||
+            Object.keys(request.preview).some((key) => !['mode', 'path'].includes(key)))
+            throw new Error('Source previews require dry-run and one mode: diff or view.');
+        if (request.preview.path !== undefined)
+            validatePreviewPath(request.preview.path);
+    }
     if (!request.dryRun)
         assertWorkspaceRuntime(run);
     root = realpathSync(root);
@@ -81,11 +90,14 @@ export async function addStackItems(root, request, run = execFile) {
         targets: recipes.flatMap((item) => item.targets),
         files: commitPaths,
         conflicts,
+        ...(request.preview ? { previews: [] } : {}),
     };
     // The upstream web generator requires network access and executes package scripts.
     // A preview reports the resolved selection without invoking that generator.
     if (request.dryRun && result.bootstrapRequired) {
         result.filesChecked = false;
+        if (request.preview)
+            throw new Error('Source preview requires a new web bootstrap and cannot run offline. Use add --dry-run for the selection plan.');
         return result;
     }
     await runStagedTransaction(root, {
@@ -152,6 +164,22 @@ export async function addStackItems(root, request, run = execFile) {
                 files,
             });
             commitPaths.push('anhedral.registry.json');
+            if (request.preview && result.previews) {
+                const preview = request.preview;
+                const selected = [...commitPaths]
+                    .filter((file) => !preview.path || preview.path === file)
+                    .sort();
+                if (preview.path && !selected.length)
+                    throw new Error('Requested path is not a changed generated source file.');
+                let total = 0;
+                for (const file of selected) {
+                    const content = sourcePreview(root, stage, file, preview.mode);
+                    total += Buffer.byteLength(JSON.stringify(content));
+                    if (total > MAX_PREVIEW_TOTAL_BYTES)
+                        throw new Error('Source preview exceeds 1 MiB. Select a single file with --diff <path> or --view <path>.');
+                    result.previews.push(content);
+                }
+            }
             // Detect concurrent changes even to source that this addition would otherwise preserve.
             if (!isDeepStrictEqual(sourceFiles(root), before) ||
                 readBoundedFile(path.join(root, 'anhedral.registry.json'), MAX_PROJECT_JSON_BYTES).toString('utf8') !== receiptText)

package/dist/registry/commands.d.ts

@@ -1,2 +1,3 @@
-export declare function runRegistry(args: string[], json: boolean): Promise<void>;
-export declare function runAdd(args: string[]): Promise<void>;
+import { type OutputOptions } from '../cli-output.js';
+export declare function runRegistry(args: string[], json: boolean, output?: OutputOptions): Promise<void>;
+export declare function runAdd(args: string[], output?: OutputOptions): Promise<void>;