anhedral 0.10.0 → 0.11.0

package/dist/cloudflare.js

@@ -1,64 +1,194 @@
-/** Credentials stay in this closure, never in returned receipts, arguments or files. */
-export async function cloudflareRequest(project, directory, run, env) {
+const ORIGIN = 'https://api.cloudflare.com';
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+function object(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function cancelBody(response) {
+    try {
+        void response.body?.cancel().catch(() => undefined);
+    }
+    catch {
+        /* Best effort cancellation never exposes provider diagnostics. */
+    }
+}
+async function boundedJson(response, signal) {
+    if (signal.aborted) {
+        cancelBody(response);
+        throw new Error();
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error();
+    const cancel = () => {
+        void reader.cancel().catch(() => undefined);
+    };
+    signal.addEventListener('abort', cancel, { once: true });
+    const chunks = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            bytes += chunk.value.length;
+            if (bytes > MAX_RESPONSE_BYTES || signal.aborted)
+                throw new Error();
+            chunks.push(chunk.value);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        cancel();
+        throw new Error();
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+        reader.releaseLock();
+    }
+}
+function responseInfo(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!object(value))
+        throw new Error('Cloudflare returned unsupported pagination.');
+    const info = {};
+    for (const field of ['page', 'total_pages', 'count', 'per_page']) {
+        const entry = value[field];
+        if (entry !== undefined) {
+            if (typeof entry !== 'number' || !Number.isSafeInteger(entry) || entry < 0)
+                throw new Error('Cloudflare returned unsupported pagination.');
+            info[field] = entry;
+        }
+    }
+    return info;
+}
+/** Credentials stay in this closure. Fixed account paths, bounded response reads and
+ * a whole-request deadline apply to reads and mutations; mutations never retry. */
+export async function cloudflareRequest(project, directory, run, env, options = {}) {
+    const account = project.accountId;
+    if (typeof account !== 'string' || !/^[a-f0-9]{32}$/.test(account))
+        throw new Error('Select a valid Cloudflare account before provider requests.');
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000)
+        throw new Error('Invalid bounded Cloudflare request deadline.');
+    const send = options.send ?? fetch;
     let credentials;
     try {
-        credentials = JSON.parse(await run('pnpm', ['exec', 'wrangler', 'auth', 'token', '--json'], directory, env));
+        const raw = await run('pnpm', ['exec', 'wrangler', 'auth', 'token', '--json'], directory, env);
+        if (Buffer.byteLength(raw) > 64 * 1024)
+            throw new Error();
+        credentials = JSON.parse(raw);
     }
     catch {
         throw new Error('Cannot retrieve structured Wrangler credentials; update Wrangler and check authentication.');
     }
-    if (!['oauth', 'api_token'].includes(credentials.type) ||
+    if (!object(credentials) ||
+        typeof credentials.type !== 'string' ||
+        !['oauth', 'api_token'].includes(credentials.type) ||
         typeof credentials.token !== 'string' ||
-        !credentials.token)
+        !/^[\x21-\x7e]{1,16384}$/.test(credentials.token))
         throw new Error('Cloudflare operations require scoped API-token or Wrangler OAuth access.');
+    const token = credentials.token;
+    const prefix = `/client/v4/accounts/${account}`;
     return async (method, endpoint, body) => {
-        if (!project.accountId ||
-            !endpoint.startsWith('/') ||
-            endpoint.includes('..') ||
-            endpoint.includes('#'))
-            throw new Error('Invalid account-scoped provider request.');
-        let response;
+        let url;
         try {
-            response = await fetch(`https://api.cloudflare.com/client/v4/accounts/${project.accountId}${endpoint}`, {
-                method,
-                headers: {
-                    Authorization: `Bearer ${credentials.token}`,
-                    'Content-Type': 'application/json',
-                },
-                body: body === undefined ? undefined : JSON.stringify(body),
-                redirect: 'error',
-                signal: AbortSignal.timeout(30_000),
-            });
+            if (typeof endpoint !== 'string')
+                throw new Error();
+            const decodedPath = decodeURIComponent(endpoint.split('?')[0]);
+            if (!['GET', 'POST'].includes(method) ||
+                endpoint.length > 4096 ||
+                !endpoint.startsWith('/') ||
+                endpoint.startsWith('//') ||
+                /[\x00-\x20\x7f#\\]/.test(endpoint) ||
+                decodedPath.includes('..') ||
+                /[\x00-\x20\x7f#\\%]/.test(decodedPath))
+                throw new Error();
+            url = new URL(`${prefix}${endpoint}`, ORIGIN);
+            if (url.origin !== ORIGIN || !url.pathname.startsWith(`${prefix}/`))
+                throw new Error();
         }
         catch {
-            throw new Error('Cloudflare request failed; check connectivity and account permissions.');
+            throw new Error('Invalid account-scoped provider request.');
         }
-        let data;
+        const controller = new AbortController();
+        let timer;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                reject(new Error('Cloudflare request deadline exceeded; inspect remote status before retrying.'));
+            }, timeoutMs);
+        });
         try {
-            data = (await response.json());
+            return await Promise.race([
+                (async () => {
+                    let response;
+                    try {
+                        response = await send(url.href, {
+                            method,
+                            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+                            body: body === undefined ? undefined : JSON.stringify(body),
+                            redirect: 'error',
+                            signal: controller.signal,
+                        });
+                    }
+                    catch {
+                        throw new Error('Cloudflare request failed; check connectivity and account permissions.');
+                    }
+                    let data;
+                    try {
+                        data = await boundedJson(response, controller.signal);
+                    }
+                    catch {
+                        throw new Error(`Cloudflare returned unsupported output (HTTP ${response.status}).`);
+                    }
+                    if (!object(data))
+                        throw new Error(`Cloudflare returned unsupported output (HTTP ${response.status}).`);
+                    if (!response.ok || data.success !== true) {
+                        const codes = Array.isArray(data.errors)
+                            ? data.errors
+                                .slice(0, 20)
+                                .filter(object)
+                                .map((item) => item.code)
+                                .filter((code) => typeof code === 'number' &&
+                                Number.isSafeInteger(code) &&
+                                code >= 0 &&
+                                code <= 1_000_000)
+                                .join(',')
+                            : '';
+                        throw new Error(`Cloudflare operation failed (HTTP ${response.status}${codes ? `; codes ${codes}` : ''}). Check scoped permissions and service eligibility; no paid plan is activated automatically.`);
+                    }
+                    if (!Object.hasOwn(data, 'result'))
+                        throw new Error('Cloudflare returned no operation result.');
+                    return { result: data.result, result_info: responseInfo(data.result_info) };
+                })(),
+                timeout,
+            ]);
         }
-        catch {
-            throw new Error(`Cloudflare returned unsupported output (HTTP ${response.status}).`);
+        finally {
+            clearTimeout(timer);
         }
-        if (!response.ok || data.success !== true) {
-            const codes = (data.errors ?? [])
-                .map((item) => item.code)
-                .filter((code) => typeof code === 'number')
-                .join(',');
-            throw new Error(`Cloudflare operation failed (HTTP ${response.status}${codes ? `; codes ${codes}` : ''}). Check scoped permissions and service eligibility; no paid plan is activated automatically.`);
-        }
-        return { result: data.result, result_info: data.result_info };
     };
 }
 export async function listCloudflare(request, endpoint) {
     const result = [];
+    let bytes = 0;
     for (let page = 1; page <= 1000; page++) {
         const response = await request('GET', `${endpoint}${endpoint.includes('?') ? '&' : '?'}page=${page}&per_page=100`);
         if (!Array.isArray(response.result) ||
-            response.result.some((item) => !item || typeof item !== 'object'))
+            response.result.length > 100 ||
+            response.result.some((item) => !object(item)))
+            throw new Error('Unsupported provider resource list.');
+        try {
+            bytes += Buffer.byteLength(JSON.stringify(response.result));
+        }
+        catch {
             throw new Error('Unsupported provider resource list.');
+        }
+        if (result.length + response.result.length > 10_000 || bytes > 10 * 1024 * 1024)
+            throw new Error('Provider resource listing exceeded its collection limit.');
         result.push(...response.result);
-        const info = response.result_info;
+        const info = responseInfo(response.result_info);
         if (info?.total_pages !== undefined ? page >= info.total_pages : response.result.length < 100)
             return result;
     }

package/dist/command-schema.d.ts

@@ -0,0 +1,21 @@
+/** Machine-readable option semantics; help is presentation, never parser input. */
+export interface CommandOption {
+    flag: string;
+    aliases?: readonly string[];
+    description: string;
+    value?: string;
+    arity?: 'required' | 'optional';
+    repeatable?: boolean;
+    hidden?: boolean;
+}
+export interface CommandDefinition {
+    description: string;
+    usage: string;
+    options: readonly CommandOption[];
+    examples: readonly string[];
+    note?: string;
+}
+export declare const GLOBAL_OPTIONS: readonly CommandOption[];
+export declare function optionHelp(option: CommandOption): string;
+export declare function commandDefinition(command: string | undefined): CommandDefinition | undefined;
+export declare const COMMANDS: Readonly<Record<string, CommandDefinition>>;

package/dist/command-schema.js

@@ -0,0 +1,374 @@
+import { STANDARD_PRODUCTS } from './stack-registry.js';
+export const GLOBAL_OPTIONS = [
+    {
+        flag: '--cwd',
+        aliases: ['-c'],
+        value: 'directory',
+        arity: 'required',
+        description: 'Run from a selected working directory.',
+    },
+    { flag: '--json', description: 'Return machine-readable output.' },
+    {
+        flag: '--quiet',
+        aliases: ['-q'],
+        description: 'Suppress human output; retain JSON and errors.',
+    },
+    { flag: '--verbose', description: 'Show local scaffolding tool output (human mode only).' },
+    { flag: '--help', aliases: ['-h'], description: 'Show command help.' },
+];
+export function optionHelp(option) {
+    const flags = [...(option.aliases ?? []), option.flag].join(', ');
+    const argument = option.arity === 'required'
+        ? ` <${option.value}>`
+        : option.arity === 'optional'
+            ? ` [${option.value}]`
+            : '';
+    return `${flags}${argument}  ${option.description}`;
+}
+export function commandDefinition(command) {
+    return COMMANDS[command === 'new' ? 'init' : (command ?? '')];
+}
+export const COMMANDS = {
+    inspect: {
+        description: 'Inspect local stack, setup requirements and recorded delivery evidence.',
+        usage: 'inspect [directory] [options]',
+        options: [],
+        examples: ['inspect', 'inspect --json'],
+        note: 'Read-only and offline. Recorded results do not establish live provider status or permissions.',
+    },
+    integrations: {
+        description: 'Inspect private integration receipts or reconcile a verified pending resource.',
+        usage: 'integrations status | recover [directory] [options]',
+        options: [
+            {
+                flag: '--provider',
+                value: 'name',
+                arity: 'required',
+                description: 'Select a bundled integration provider for recovery.',
+            },
+            {
+                flag: '--operation',
+                value: 'hash',
+                arity: 'required',
+                description: 'Select the exact pending operation from status.',
+            },
+            {
+                flag: '--resource',
+                value: 'id',
+                arity: 'required',
+                description: 'Verify and adopt this existing resource; never recreate it.',
+            },
+        ],
+        examples: [
+            'integrations status --json',
+            'integrations recover --provider neon --operation recorded-hash --resource existing-id',
+        ],
+        note: 'Status is read-only. Recovery verifies provider identity before updating a local receipt. Legacy unknown operations and unrecoverable one-time credentials remain blocked.',
+    },
+    init: {
+        description: 'Scaffold a project from the bundled stack registry.',
+        usage: 'init [directory] [products...] [options]',
+        options: [
+            ...STANDARD_PRODUCTS.map((name) => ({
+                flag: `--${name}`,
+                description: `Include ${name}.`,
+                hidden: true,
+            })),
+            {
+                flag: '--hosting',
+                description: 'Select web hosting.',
+                value: 'cloudflare|vercel',
+                arity: 'required',
+            },
+            {
+                flag: '--skip-install',
+                description: 'Skip the final install (bootstrap still needs network).',
+            },
+            { flag: '--git', description: 'Initialize a project repository or skip it.' },
+            { flag: '--no-git', description: 'Initialize a project repository or skip it.' },
+            { flag: '--dry-run', description: 'Preview the selected stack without writes or network.' },
+        ],
+        examples: [
+            'init client-app',
+            'init mobile-app --expo',
+            'init product --next --hono --neon --clerk --dry-run',
+        ],
+        note: `Default: Vinext on Cloudflare Workers, using the official shadcn pnpm/Turborepo monorepo.\nProducts: ${STANDARD_PRODUCTS.join(', ')}\nOnly bundled options are supported. --all is intentionally unsupported.`,
+    },
+    auth: {
+        description: 'Check or guide authentication for the selected providers.',
+        usage: 'auth [directory] [options]',
+        options: [
+            {
+                flag: '--provider',
+                description: 'Check one provider required by this project.',
+                value: 'name',
+                arity: 'required',
+            },
+            { flag: '--status', description: 'Check existing access without opening login.' },
+            { flag: '--non-interactive', description: 'Never open an interactive login.' },
+        ],
+        examples: ['auth', 'auth --status --json', 'auth --provider neon'],
+        note: 'Management keys come from the environment. Login does not establish all write permissions or complete provider setup. Complete anhedral.providers.json before shipping.',
+    },
+    ship: {
+        description: 'Provision, configure and deploy the supported selected stack.',
+        usage: 'ship [directory] [options]',
+        options: [
+            { flag: '--dry-run', description: 'Preview provisioning and deployment without mutations.' },
+            {
+                flag: '--provider',
+                description: 'Select hosting in a mixed project.',
+                value: 'cloudflare|vercel',
+                arity: 'required',
+            },
+            {
+                flag: '--platform',
+                description: 'Build a selected mobile platform.',
+                value: 'ios|android',
+                arity: 'required',
+            },
+            {
+                flag: '--profile',
+                description: 'Select the configured EAS build profile.',
+                value: 'name',
+                arity: 'required',
+            },
+        ],
+        examples: ['ship --dry-run', 'ship --json', 'ship --platform android --profile preview'],
+        note: 'Connect the intended hosting account and audience first. Commit source before shipping; resolved tracked bindings require review and another commit. Mobile builds return links and never submit to stores.',
+    },
+    add: {
+        description: 'Add bundled stack parts while preserving edited source.',
+        usage: 'add [directory] <items...> [options]',
+        options: [
+            { flag: '--dry-run', description: 'Preview changed paths without installing them.' },
+            {
+                flag: '--diff',
+                description: 'Preview source changes; implies --dry-run.',
+                value: 'path',
+                arity: 'optional',
+            },
+            {
+                flag: '--view',
+                description: 'Preview generated source; implies --dry-run.',
+                value: 'path',
+                arity: 'optional',
+            },
+            { flag: '--skip-install', description: 'Skip the final dependency install.' },
+        ],
+        examples: [
+            'add resend',
+            'add client-app resend --dry-run',
+            'add resend --diff --cwd client-app',
+        ],
+        note: 'Source previews are local and bounded. A new web bootstrap cannot be previewed offline; the plan reports that limitation. Edited-source conflicts require review; there is no force overwrite.',
+    },
+    registry: {
+        description: 'Inspect the bundled stack catalog and setup requirements.',
+        usage: 'registry list | view <item> | capabilities [options]',
+        options: [],
+        examples: [
+            'registry list',
+            'registry view neon',
+            'registry capabilities',
+            'registry capabilities --json',
+        ],
+    },
+    doctor: {
+        description: 'Check project provenance and local readiness without writes.',
+        usage: 'doctor [directory] [options]',
+        options: [
+            { flag: '--providers', description: 'Also check tools and existing provider context.' },
+        ],
+        examples: ['doctor', 'doctor client-app --providers --json'],
+    },
+    connect: {
+        description: 'Select the intended hosting account, project and audience.',
+        usage: 'connect [directory] [options]',
+        options: [
+            {
+                flag: '--provider',
+                description: 'Select the hosting provider.',
+                value: 'cloudflare|vercel',
+                arity: 'required',
+            },
+            {
+                flag: '--account',
+                description: 'Select the Cloudflare account.',
+                value: 'id',
+                arity: 'required',
+            },
+            {
+                flag: '--audience',
+                description: 'Set the explicit hosting audience.',
+                value: 'public|private',
+                arity: 'required',
+            },
+            {
+                flag: '--allow-email',
+                description: 'Allow a private Cloudflare member (repeatable).',
+                value: 'email',
+                arity: 'required',
+                repeatable: true,
+            },
+            { flag: '--scope', description: 'Select the Vercel team.', value: 'team', arity: 'required' },
+            {
+                flag: '--use',
+                description: 'Declare Vercel usage.',
+                value: 'personal|commercial',
+                arity: 'required',
+            },
+            { flag: '--create', description: 'Create the selected Vercel project.' },
+            { flag: '--git', description: 'Connect the verified GitHub repository.' },
+        ],
+        examples: [
+            'connect --provider cloudflare --audience public',
+            'connect --scope customer --audience private --use commercial --create',
+        ],
+        note: 'Vercel Hobby is personal/non-commercial. Commercial applications need an eligible existing plan; no paid plan is activated automatically.',
+    },
+    repository: {
+        description: 'Connect or create the application owner’s GitHub repository.',
+        usage: 'repository [directory] [--owner <account>] [options]',
+        options: [
+            {
+                flag: '--owner',
+                description: 'Select the GitHub owner.',
+                value: 'account',
+                arity: 'required',
+            },
+            { flag: '--name', description: 'Set the repository name.', value: 'name', arity: 'required' },
+            {
+                flag: '--visibility',
+                description: 'Set visibility (default: private).',
+                value: 'private|public',
+                arity: 'required',
+            },
+            { flag: '--create', description: 'Create the repository when needed.' },
+        ],
+        examples: ['repository --owner customer --create'],
+    },
+    register: {
+        description: 'Record application identity and delivery targets.',
+        usage: 'register [directory] [--provider cloudflare|vercel]',
+        options: [
+            {
+                flag: '--provider',
+                description: 'Select the provider.',
+                value: 'cloudflare|vercel',
+                arity: 'required',
+            },
+        ],
+        examples: ['register'],
+    },
+    provision: {
+        description: 'Reconcile Cloudflare resources without deploying code.',
+        usage: 'provision [directory] [options]',
+        options: [
+            {
+                flag: '--provider',
+                description: 'Select Cloudflare in a mixed project.',
+                value: 'cloudflare',
+                arity: 'required',
+            },
+            { flag: '--dry-run', description: 'Preview resources without mutations.' },
+        ],
+        examples: ['provision --dry-run'],
+        note: 'Use ship for the full selected-integration and hosting flow.',
+    },
+    status: {
+        description: 'Inspect recorded release and provider evidence.',
+        usage: 'status [directory] [options]',
+        options: [
+            {
+                flag: '--provider',
+                description: 'Select hosting.',
+                value: 'cloudflare|vercel',
+                arity: 'required',
+            },
+            { flag: '--refresh', description: 'Refresh provider evidence.' },
+        ],
+        examples: ['status --refresh'],
+    },
+    manage: {
+        description: 'Write a local overview of recorded delivery evidence.',
+        usage: 'manage [directory] [options]',
+        options: [
+            {
+                flag: '--provider',
+                description: 'Select hosting.',
+                value: 'cloudflare|vercel',
+                arity: 'required',
+            },
+            { flag: '--local', description: 'Use local evidence without provider refresh.' },
+            { flag: '--refresh', description: 'Refresh provider evidence.' },
+        ],
+        examples: ['manage --local'],
+    },
+    verify: {
+        description: 'Exercise the application’s configured live acceptance checks.',
+        usage: 'verify [directory] [options]',
+        options: [
+            {
+                flag: '--provider',
+                description: 'Select hosting.',
+                value: 'cloudflare|vercel',
+                arity: 'required',
+            },
+            { flag: '--refresh', description: 'Refresh provider evidence.' },
+        ],
+        examples: ['verify'],
+    },
+    adopt: {
+        description: 'Record a verified existing Vercel Git deployment.',
+        usage: 'adopt [directory] [--provider vercel]',
+        options: [
+            { flag: '--provider', description: 'Select Vercel.', value: 'vercel', arity: 'required' },
+            { flag: '--refresh', description: 'Refresh provider evidence.' },
+        ],
+        examples: ['adopt --provider vercel'],
+        note: 'Does not push or deploy.',
+    },
+    recover: {
+        description: 'Recover verified hosting state or a proven interrupted local lock.',
+        usage: 'recover [directory] [options]',
+        options: [
+            {
+                flag: '--lock',
+                description: 'Release only a proven dead local delivery lock; never replay provider operations.',
+            },
+            {
+                flag: '--provider',
+                description: 'Select hosting.',
+                value: 'cloudflare|vercel',
+                arity: 'required',
+            },
+            { flag: '--refresh', description: 'Refresh provider evidence.' },
+        ],
+        examples: ['recover'],
+        note: 'Does not recreate missing integration credentials or historical product checks.',
+    },
+    rollback: {
+        description: 'Restore a recorded code release after compatibility review.',
+        usage: 'rollback [directory] --release <id> --data-compatible [options]',
+        options: [
+            {
+                flag: '--provider',
+                description: 'Select hosting.',
+                value: 'cloudflare|vercel',
+                arity: 'required',
+            },
+            {
+                flag: '--release',
+                description: 'Select a recorded release.',
+                value: 'id',
+                arity: 'required',
+            },
+            { flag: '--data-compatible', description: 'Confirm data/schema compatibility.' },
+            { flag: '--refresh', description: 'Refresh provider evidence.' },
+        ],
+        examples: ['rollback --release recorded-id --data-compatible'],
+        note: 'Code rollback does not restore data.',
+    },
+};

package/dist/delivery.d.ts

@@ -9,7 +9,7 @@ interface TargetRelease {
     urls: string[];
     providerConfirmed: boolean;
 }
-interface Release {
+export interface Release {
     id: string;
     commit: string;
     startedAt: string;
@@ -26,7 +26,7 @@ interface Release {
     };
 }
 export declare function connectApplication(root: string, accountId: string | undefined, audience: 'public' | 'private' | undefined, run?: import("./project-state.js").DeliveryRunner, emails?: string[]): Promise<ApplicationProject>;
-export declare function planDelivery(root: string): {
+export declare function planDelivery(root: string, allowResourcePlaceholders?: boolean): {
     project: ApplicationProject;
     checks: string[][];
     deployments: {