anhedral 0.10.1 → 0.11.0

package/dist/registry/commands.js

@@ -1,16 +1,28 @@
 import path from 'node:path';
+import { CAPABILITY_CONTRACT, formatCapabilityContract } from '../capability-contract.js';
 import { addStackItems } from './add.js';
-import { STACK_REGISTRY, getStackItem } from '../stack-registry.js';
-export async function runRegistry(args, json) {
+import { STACK_REGISTRY, STANDARD_PRODUCTS, getStackItem } from '../stack-registry.js';
+import { printResult } from '../cli-output.js';
+import { commandHelp } from './usage.js';
+import { CliArgumentError, suggest } from '../cli-arguments.js';
+export async function runRegistry(args, json, output = { json }) {
     const positional = args.filter((arg) => arg !== '--json');
     if (positional.includes('--help') || positional.includes('-h')) {
-        console.log('anhedral registry list|view [item] [--json]');
+        console.log(commandHelp('registry'));
         return;
     }
     if (positional.some((arg) => arg.startsWith('-')))
         throw new Error('Unknown registry option.');
     const [action = 'list', name, ...extra] = positional;
+    if (action === 'capabilities' && !name && !extra.length) {
+        if (output.quiet && !json)
+            return;
+        console.log(json ? JSON.stringify(CAPABILITY_CONTRACT, null, 2) : formatCapabilityContract());
+        return;
+    }
     if (action === 'list' && !name && !extra.length) {
+        if (output.quiet && !json)
+            return;
         console.log(json
             ? JSON.stringify(STACK_REGISTRY, null, 2)
             : STACK_REGISTRY.items
@@ -19,30 +31,57 @@ export async function runRegistry(args, json) {
         return;
     }
     if (action === 'view' && name && !extra.length) {
-        console.log(JSON.stringify(getStackItem(name), null, 2));
+        if (!STACK_REGISTRY.items.some((item) => item.name === name)) {
+            const correction = suggest(name, STACK_REGISTRY.items.map((item) => item.name));
+            throw new CliArgumentError(`Unknown bundled registry item.${correction ? ` Did you mean ${correction}?` : ''}`, 'Run anhedral registry list.');
+        }
+        printResult('registry', getStackItem(name), { ...output, json });
         return;
     }
-    throw new Error('Use registry list or registry view <item>.');
+    throw new Error('Use registry list, registry view <item>, or registry capabilities.');
 }
-export async function runAdd(args) {
+export async function runAdd(args, output = {}) {
     if (args.includes('--help') || args.includes('-h')) {
-        console.log('anhedral add <directory> <items...> [--dry-run] [--skip-install] [--json]');
+        console.log(commandHelp('add'));
         return;
     }
     const positional = [];
-    for (const arg of args) {
+    let preview;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--diff' || arg === '--view') {
+            if (preview)
+                throw new Error('Select one source preview: --diff or --view.');
+            preview = { mode: arg === '--diff' ? 'diff' : 'view' };
+            const next = args[index + 1];
+            if (next &&
+                !next.startsWith('-') &&
+                !STANDARD_PRODUCTS.includes(next)) {
+                preview.path = next;
+                index++;
+            }
+            continue;
+        }
         if (['--dry-run', '--skip-install', '--json'].includes(arg))
             continue;
         if (arg.startsWith('-'))
             throw new Error(`Unknown add option: ${arg}.`);
         positional.push(arg);
     }
-    const [directory, ...items] = positional;
-    if (!directory || !items.length)
-        throw new Error('Use add <directory> <items...>.');
-    console.log(JSON.stringify(await addStackItems(path.resolve(directory), {
+    const hasDirectory = positional[0] && !STANDARD_PRODUCTS.includes(positional[0]);
+    if (hasDirectory && positional.length === 1) {
+        const correction = suggest(positional[0], STANDARD_PRODUCTS);
+        if (correction)
+            throw new CliArgumentError(`Unknown stack part. Did you mean ${correction}?`, 'Run anhedral registry list.');
+    }
+    const directory = hasDirectory ? positional.shift() : process.cwd();
+    const items = positional;
+    if (!items.length)
+        throw new Error('Select bundled parts: anhedral add <items...> [--cwd <directory>].');
+    printResult('add', await addStackItems(path.resolve(directory), {
         items,
-        dryRun: args.includes('--dry-run'),
+        dryRun: args.includes('--dry-run') || Boolean(preview),
         skipInstall: args.includes('--skip-install'),
-    }), null, 2));
+        ...(preview ? { preview } : {}),
+    }), { ...output, json: args.includes('--json') });
 }

package/dist/registry/options.js

@@ -46,7 +46,8 @@ function parseStandardFlags(remaining) {
 }
 export function parseStandardOptions(command, args) {
     const remaining = [...args];
-    const directory = command === 'new' ? remaining.shift() : process.cwd();
+    const hasDirectory = remaining[0] && !remaining[0].startsWith('-');
+    const directory = command === 'new' || hasDirectory ? remaining.shift() : process.cwd();
     if (!directory || directory.startsWith('-'))
         throw new Error('new requires a destination directory.');
     const root = path.resolve(directory);
@@ -60,6 +61,6 @@ export function parseStandardOptions(command, args) {
         skipInstall: remaining.includes('--skip-install'),
         dryRun: remaining.includes('--dry-run'),
         json: remaining.includes('--json'),
-        initializeGit: gitSpecified ?? command === 'new',
+        initializeGit: gitSpecified ?? (command === 'new' || Boolean(hasDirectory)),
     };
 }

package/dist/registry/preview.d.ts

@@ -0,0 +1,11 @@
+export declare const MAX_PREVIEW_TOTAL_BYTES: number;
+export interface SourcePreview {
+    path: string;
+    content?: string;
+    diff?: string;
+    unavailable?: string;
+}
+export declare function validatePreviewPath(file: string): void;
+/** A single contextual hunk is linear in file size and remains an applicable unified patch. */
+export declare function sourceDiff(file: string, before: string | undefined, after: string): string;
+export declare function sourcePreview(root: string, stage: string, file: string, mode: 'diff' | 'view'): SourcePreview;

package/dist/registry/preview.js

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { readBoundedFile } from '../bounded-file.js';
+const MAX_PREVIEW_FILE_BYTES = 256 * 1024;
+export const MAX_PREVIEW_TOTAL_BYTES = 1024 * 1024;
+export function validatePreviewPath(file) {
+    if (!file ||
+        path.posix.isAbsolute(file) ||
+        file.includes('\\') ||
+        /[\x00-\x1f\x7f]/.test(file) ||
+        file
+            .split('/')
+            .some((part) => !part ||
+            ['.', '..', '.anhedral'].includes(part) ||
+            (/^(?:\.env|\.dev\.vars)(?:\.|$)/.test(part) && !part.endsWith('.example'))))
+        throw new Error('Select a relative generated source path; private environment and state files cannot be previewed.');
+}
+/** A single contextual hunk is linear in file size and remains an applicable unified patch. */
+export function sourceDiff(file, before, after) {
+    const lines = (content) => content === '' ? [] : content.split('\n').slice(0, content.endsWith('\n') ? -1 : undefined);
+    const oldLines = lines(before ?? '');
+    const newLines = lines(after);
+    if (before === after)
+        return '';
+    let prefix = 0;
+    while (prefix < oldLines.length &&
+        prefix < newLines.length &&
+        oldLines[prefix] === newLines[prefix])
+        prefix++;
+    // Newline-only changes must still include the final line in the patch.
+    if (prefix && oldLines.length === newLines.length && prefix === oldLines.length)
+        prefix--;
+    let suffix = 0;
+    while ((before ?? '').endsWith('\n') === after.endsWith('\n') &&
+        suffix < oldLines.length - prefix &&
+        suffix < newLines.length - prefix &&
+        oldLines.at(-suffix - 1) === newLines.at(-suffix - 1))
+        suffix++;
+    const start = Math.max(0, prefix - 3);
+    const oldEnd = Math.min(oldLines.length, oldLines.length - suffix + 3);
+    const newEnd = Math.min(newLines.length, newLines.length - suffix + 3);
+    const output = [
+        `diff --git a/${file} b/${file}`,
+        ...(before === undefined ? ['new file mode 100644'] : []),
+        `--- ${before === undefined ? '/dev/null' : `a/${file}`}`,
+        `+++ b/${file}`,
+        `@@ -${oldEnd - start ? start + 1 : start},${oldEnd - start} +${newEnd - start ? start + 1 : start},${newEnd - start} @@`,
+    ];
+    if (before === undefined && !after)
+        return output.slice(0, 2).join('\n') + '\n';
+    const append = (prefix, line, last, content) => {
+        output.push(`${prefix}${line}`);
+        if (last && !content.endsWith('\n'))
+            output.push('\');
+    };
+    for (let index = start; index < prefix; index++)
+        output.push(` ${oldLines[index]}`);
+    for (let index = prefix; index < oldLines.length - suffix; index++)
+        append('-', oldLines[index], index === oldLines.length - 1, before ?? '');
+    for (let index = prefix; index < newLines.length - suffix; index++)
+        append('+', newLines[index], index === newLines.length - 1, after);
+    for (let index = oldLines.length - suffix; index < oldEnd; index++)
+        append(' ', oldLines[index], index === oldLines.length - 1, after);
+    return output.join('\n') + '\n';
+}
+export function sourcePreview(root, stage, file, mode) {
+    validatePreviewPath(file);
+    const decode = (directory) => new TextDecoder('utf-8', { fatal: true }).decode(readBoundedFile(path.join(directory, file), MAX_PREVIEW_FILE_BYTES));
+    let after;
+    let before;
+    try {
+        after = decode(stage);
+        if (after.includes('\x00'))
+            throw new Error('Binary file');
+        if (mode === 'diff' && existsSync(path.join(root, file))) {
+            before = decode(root);
+            if (before.includes('\x00'))
+                throw new Error('Binary file');
+        }
+    }
+    catch {
+        return {
+            path: file,
+            unavailable: 'Binary, nonregular or oversized file; source preview is unavailable (256 KiB limit).',
+        };
+    }
+    return {
+        path: file,
+        ...(mode === 'view' ? { content: after } : { diff: sourceDiff(file, before, after) }),
+    };
+}

package/dist/registry/usage.d.ts

@@ -1 +1,11 @@
+export declare const COMMAND_HELP: {
+    [k: string]: {
+        options: string[];
+        description: string;
+        usage: string;
+        examples: readonly string[];
+        note?: string;
+    };
+};
+export declare function commandHelp(command: string): string | undefined;
 export declare const STANDARD_USAGE: string;

package/dist/registry/usage.js

@@ -1,37 +1,22 @@
-import { STANDARD_PRODUCTS } from '../stack-registry.js';
-export const STANDARD_USAGE = `Anhedral Application Stack & Delivery Standard
-
-anhedral new <directory> [products...] [--hosting cloudflare|vercel] [--skip-install] [--no-git] [--dry-run] [--json]
-anhedral add <directory> <items...> [--dry-run] [--skip-install] [--json]
-anhedral init [products...] [--hosting cloudflare|vercel] [--skip-install] [--git] [--dry-run] [--json]
-
-Default: Vinext on Cloudflare Workers, from the official shadcn pnpm/Turborepo monorepo.
-Web hosting: Vinext on Cloudflare by default; native Next.js on Vercel is an explicit option.
-Products: ${STANDARD_PRODUCTS.join(', ')}
-Examples:
-  anhedral new client-app
-  anhedral new mobile-app --expo
-  anhedral new product --next --expo --hono --neon --clerk --r2
-  anhedral new website --next --stripe --resend
-  anhedral init --wxt
-  anhedral cloud register|stage|save|deploy|status [directory] (managed service API required)
-  anhedral registry list|view [item] [--json]
-  anhedral doctor [directory] [--providers] --json
-  anhedral repository [directory] [--owner <github-account>] [--name <repo>] [--visibility private|public] [--create]
-  anhedral register [directory]
-  anhedral connect [directory] [--scope <team>] --audience public|private --use personal|commercial [--create] [--git]
-  anhedral connect [directory] --provider cloudflare [--account <id>] --audience public|private [--allow-email <email>]
-  anhedral provision [directory] [--dry-run] [--json]
-  anhedral ship [directory] [--dry-run] [--json]
-  anhedral adopt [directory] --provider vercel [--json]
-  anhedral recover [directory] [--provider vercel|cloudflare] [--json]
-  anhedral status [directory] [--refresh] [--json]
-  anhedral manage [directory] [--local] [--json]
-  anhedral verify [directory] [--json]
-  anhedral rollback [directory] --release <id> --data-compatible [--json]
-
---skip-install skips the final workspace install; the official shadcn bootstrap
-still requires network access and may install its own dependencies.
---all is intentionally unsupported: select only required capabilities.
-Vercel Hobby is personal/non-commercial with limits; commercial apps need a suitable existing plan.
-`;
+import { COMMANDS, GLOBAL_OPTIONS, optionHelp } from '../command-schema.js';
+// Preserve the presentation API for consumers; all option text comes from typed definitions.
+export const COMMAND_HELP = Object.fromEntries(Object.entries(COMMANDS).map(([name, entry]) => [
+    name,
+    { ...entry, options: entry.options.filter((option) => !option.hidden).map(optionHelp) },
+]));
+const primary = ['init', 'auth', 'ship', 'add', 'registry', 'inspect', 'doctor', 'connect'];
+const common = GLOBAL_OPTIONS.map(optionHelp);
+export function commandHelp(command) {
+    if (command === 'new')
+        return commandHelp('init')
+            ?.replace('Usage: anhedral init', 'Usage: anhedral new')
+            .concat('\nCompatibility alias: new requires a destination directory.\n');
+    const entry = COMMAND_HELP[command];
+    if (!entry)
+        return undefined;
+    return `${entry.description}\n\nUsage: anhedral ${entry.usage}\n\nOptions:\n${[...entry.options, ...common].map((option) => `  ${option}`).join('\n')}\n\nExamples:\n${entry.examples.map((example) => `  anhedral ${example}`).join('\n')}${entry.note ? `\n\n${entry.note}` : ''}\n`;
+}
+export const STANDARD_USAGE = `Anhedral\nScaffold source, authenticate your providers, and ship your selected stack.\n\nUsage: anhedral <command> [options]\n\nStart here:\n${primary.map((name) => `  ${name.padEnd(12)}${COMMAND_HELP[name].description}`).join('\n')}\n\nDelivery tools:\n${Object.entries(COMMAND_HELP)
+    .filter(([name]) => !primary.includes(name))
+    .map(([name, entry]) => `  ${name.padEnd(12)}${entry.description}`)
+    .join('\n')}\n\nDefault: Vinext on Cloudflare Workers, from the official shadcn pnpm/Turborepo monorepo.\nExamples:\n  anhedral init client-app\n  anhedral auth client-app\n  anhedral ship client-app --dry-run\n\nUse anhedral <command> --help for options and examples.\nUse anhedral help <command> for the same focused help.\nGlobal options:\n${common.map((option) => `  ${option}`).join('\n')}\n  -v, --version  Show the CLI version.\n\nnew remains a compatibility alias for init with an explicit destination.\n`;

package/dist/scaffold/auth.js

@@ -3,7 +3,7 @@ import { STACK_DEPENDENCIES } from '../dependencies.js';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { writeBetterAuthSchema } from '../auth-schema.js';
-import { json, put, readJson, patchPackage, sharedPackage } from './files.js';
+import { put, patchPackage, sharedPackage } from './files.js';
 export function scaffoldBetterAuth({ root, options, runtimeApp, has }) {
     writeBetterAuthSchema(root, has('neon'));
     sharedPackage(root, 'auth', `import { betterAuth } from 'better-auth';
@@ -30,14 +30,6 @@ export function createAuth(db: ReturnType<typeof createDatabase>, secret: string
         const source = readFileSync(path.join(root, 'apps/api/src/index.ts'), 'utf8');
         put(root, 'apps/api/src/index.ts', `import { createAuth } from '@workspace/auth';\nimport { createDatabase } from '@workspace/db';\n` +
             source.replace('export default app;', `app.on(['GET', 'POST'], '/api/auth/*', async (c) => {\n  const env = c.env;\n  const database = ${connection};\n  return await createAuth(database, env.BETTER_AUTH_SECRET, env.BETTER_AUTH_URL).handler(c.req.raw);\n});\nexport default app;`));
-        const config = readJson(root, 'apps/api/wrangler.jsonc');
-        json(root, 'apps/api/wrangler.jsonc', {
-            ...config,
-            vars: {
-                BETTER_AUTH_URL: 'http://localhost:8787',
-                ...(config.vars ?? {}),
-            },
-        });
     }
     else {
         put(root, 'apps/web/app/api/auth/[...all]/route.ts', `${has('vinext') ? "import { env } from 'cloudflare:workers';" : options.hosting === 'cloudflare' ? "import { getCloudflareContext } from '@opennextjs/cloudflare';" : ''}
@@ -53,15 +45,7 @@ export { handler as GET, handler as POST };
         if (options.hosting === 'cloudflare' && !has('vinext'))
             put(root, 'apps/web/cloudflare-env.d.ts', `interface CloudflareEnv { BETTER_AUTH_SECRET: string; BETTER_AUTH_URL: string; ${has('neon') ? 'DATABASE_URL: string;' : "DB: Parameters<typeof import('drizzle-orm/d1').drizzle>[0];"} }\n`);
         if (has('vinext')) {
-            put(root, 'apps/web/secrets.d.ts', 'declare namespace Cloudflare { interface Env { BETTER_AUTH_SECRET: string } }\n');
-            const config = readJson(root, 'apps/web/wrangler.jsonc');
-            json(root, 'apps/web/wrangler.jsonc', {
-                ...config,
-                vars: {
-                    BETTER_AUTH_URL: 'http://localhost:3000',
-                    ...(config.vars ?? {}),
-                },
-            });
+            put(root, 'apps/web/secrets.d.ts', 'declare namespace Cloudflare { interface Env { BETTER_AUTH_SECRET: string; BETTER_AUTH_URL: string } }\n');
         }
         patchPackage(root, 'apps/web/package.json', {
             dependencies: { 'drizzle-orm': STACK_DEPENDENCIES['drizzle-orm'] },
@@ -73,7 +57,7 @@ export { handler as GET, handler as POST };
         BETTER_AUTH_URL: `http://localhost:${runtimeApp === 'web' ? '3000' : '8787'}`,
     });
     if (has('hono'))
-        put(root, 'apps/api/src/secrets.d.ts', 'interface Env { BETTER_AUTH_SECRET: string }\n');
+        put(root, 'apps/api/src/secrets.d.ts', 'interface Env { BETTER_AUTH_SECRET: string; BETTER_AUTH_URL: string }\n');
 }
 export function scaffoldClerk({ root, has }) {
     if (has('next') || has('vinext')) {

package/dist/scaffold/workspace.js

@@ -9,6 +9,9 @@ import { json, put, readJson, patchPackage, } from './files.js';
 import { writeSetupDocumentation, workerBuildSuffix } from './documentation.js';
 import { writeStackDocumentation } from './stack-documentation.js';
 import { writeEnvironmentExample } from './environment.js';
+import { providerConfigurationTemplate } from '../providers/config.js';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 function securityOverrides(options) {
     const has = (value) => options.products.includes(value);
     return {
@@ -161,6 +164,14 @@ process.exitCode = result.status ?? 1;
         resourcesProvisioned: false,
     });
     json(root, 'anhedral.setup.json', createSetupPlan({ ...options, dryRun: false }, registry));
+    const providers = providerConfigurationTemplate(options.products, options.name);
+    const prior = updating && existsSync(path.join(root, 'anhedral.providers.json'))
+        ? readJson(root, 'anhedral.providers.json')
+        : undefined;
+    json(root, 'anhedral.providers.json', {
+        ...providers,
+        providers: { ...providers.providers, ...prior?.providers },
+    });
     if (!updating)
         writeSetupDocumentation(root, options);
 }