anhedral 0.8.6 → 0.9.0

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

package/dist/registry/commands.js

@@ -0,0 +1,99 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { addStackItems } from './add.js';
+import { buildSourceRegistry, loadSourceRegistry } from './remote.js';
+import { STACK_REGISTRY, getStackItem } from '../stack-registry.js';
+export async function runRegistry(args, json) {
+    if (args[0] === 'build') {
+        args = args.filter((arg) => arg !== '--json');
+        if (args.length !== 4 || args[2] !== '--output' || !args[1] || !args[3])
+            throw new Error('Use registry build <manifest> --output <registry.json>.');
+        const source = path.resolve(args[1]);
+        const output = path.resolve(args[3]);
+        if (source === output)
+            throw new Error('Registry output must differ from its authored manifest.');
+        const registry = buildSourceRegistry(source);
+        mkdirSync(path.dirname(output), { recursive: true });
+        writeFileSync(output, JSON.stringify(registry, null, 2) + '\n');
+        console.log(JSON.stringify({ output, items: registry.items.length }));
+        return;
+    }
+    const registryFlag = args.indexOf('--registry');
+    if (registryFlag >= 0) {
+        const source = args[registryFlag + 1];
+        if (!source || source.startsWith('-'))
+            throw new Error('Missing registry source.');
+        const positional = args.filter((arg, index) => index !== registryFlag && index !== registryFlag + 1 && arg !== '--json');
+        const registry = await loadSourceRegistry(source);
+        if (positional.length === 1 && positional[0] === 'list')
+            console.log(JSON.stringify(registry, null, 2));
+        else if (positional.length === 2 && positional[0] === 'view') {
+            const item = registry.registry.items.find((item) => item.name === positional[1]);
+            if (!item)
+                throw new Error('Unknown remote registry item.');
+            console.log(JSON.stringify({ source: registry.source, integrity: registry.integrity, item }, null, 2));
+        }
+        else
+            throw new Error('Use registry list|view [item] --registry <file|https-url>.');
+        return;
+    }
+    const positional = args.filter((arg) => arg !== '--json');
+    if (positional.includes('--help') || positional.includes('-h')) {
+        console.log('anhedral registry list|view [item] [--json]');
+        return;
+    }
+    if (positional.some((arg) => arg.startsWith('-')))
+        throw new Error('Unknown registry option.');
+    const [action = 'list', name, ...extra] = positional;
+    if (action === 'list' && !name && !extra.length) {
+        console.log(json
+            ? JSON.stringify(STACK_REGISTRY, null, 2)
+            : STACK_REGISTRY.items
+                .map((item) => `${item.name} (${item.type}) — ${item.description}`)
+                .join('\n'));
+        return;
+    }
+    if (action === 'view' && name && !extra.length) {
+        console.log(JSON.stringify(getStackItem(name), null, 2));
+        return;
+    }
+    throw new Error('Use registry list or registry view <item>.');
+}
+export async function runAdd(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log('anhedral add <directory> <items...> [--registry <file|https-url>] [--integrity sha256-...] [--dry-run] [--skip-install] [--json]');
+        return;
+    }
+    let source;
+    let integrity;
+    const positional = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (['--dry-run', '--skip-install', '--json'].includes(arg))
+            continue;
+        if (arg === '--integrity') {
+            if (integrity || !args[index + 1] || !/^sha256-[A-Za-z0-9+/]{43}=$/.test(args[index + 1]))
+                throw new Error('Specify one SHA-256 registry integrity.');
+            integrity = args[++index];
+        }
+        else if (arg === '--registry') {
+            if (source || !args[index + 1] || args[index + 1].startsWith('-'))
+                throw new Error('Specify one registry source.');
+            source = args[++index];
+        }
+        else if (arg.startsWith('-'))
+            throw new Error('Unknown add option.');
+        else
+            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), {
+        items,
+        registry: source,
+        integrity,
+        dryRun: args.includes('--dry-run'),
+        skipInstall: args.includes('--skip-install'),
+    }), null, 2));
+}

package/dist/registry/context.d.ts

@@ -0,0 +1,3 @@
+import type { RecipeContext, StandardOptions } from './types.js';
+export declare function createRecipeContext(root: string, options: StandardOptions): RecipeContext;
+export declare function createResolutionContext(selection: Pick<StandardOptions, 'products' | 'hosting'> & Partial<Pick<StandardOptions, 'name'>>): RecipeContext;

package/dist/registry/context.js

@@ -0,0 +1,21 @@
+export function createRecipeContext(root, options) {
+    const selected = new Set(options.products);
+    return {
+        root,
+        options,
+        has: (product) => selected.has(product),
+        runtimeApp: selected.has('hono') ? 'api' : 'web',
+        bindings: {},
+    };
+}
+export function createResolutionContext(selection) {
+    return createRecipeContext('', {
+        root: '',
+        name: selection.name ?? 'app',
+        skipInstall: true,
+        dryRun: true,
+        json: false,
+        initializeGit: false,
+        ...selection,
+    });
+}

package/dist/registry/options.d.ts

@@ -0,0 +1,2 @@
+import type { StandardOptions } from './types.js';
+export declare function parseStandardOptions(command: 'new' | 'init', args: readonly string[]): StandardOptions;

package/dist/registry/options.js

@@ -0,0 +1,65 @@
+import { resolveStandardProducts } from './resolve.js';
+import path from 'node:path';
+import { packageNameFromText } from '../render.js';
+import { STANDARD_PRODUCTS } from '../stack-registry.js';
+function readGitFlag(token, previous) {
+    const value = token === '--git';
+    if (previous !== undefined && value !== previous)
+        throw new Error('Conflicting Git options.');
+    return value;
+}
+function readHostingFlag(value, previous, specified) {
+    if (value !== 'cloudflare' && value !== 'vercel')
+        throw new Error('hosting must be cloudflare or vercel.');
+    if (specified && previous !== value)
+        throw new Error('Conflicting hosting options.');
+    return value;
+}
+function parseStandardFlags(remaining) {
+    const products = new Set();
+    let hosting = 'cloudflare';
+    let hostingSpecified = false;
+    let gitSpecified;
+    for (let index = 0; index < remaining.length; index++) {
+        const token = remaining[index];
+        if (['--skip-install', '--dry-run', '--json', '--verbose'].includes(token))
+            continue;
+        if (token === '--git' || token === '--no-git') {
+            gitSpecified = readGitFlag(token, gitSpecified);
+            continue;
+        }
+        if (token === '--hosting' || token.startsWith('--hosting=')) {
+            const value = token === '--hosting' ? remaining[++index] : token.slice('--hosting='.length);
+            hosting = readHostingFlag(value, hosting, hostingSpecified);
+            hostingSpecified = true;
+            continue;
+        }
+        const value = token.replace(/^--/, '');
+        if (!STANDARD_PRODUCTS.includes(value)) {
+            throw new Error(`Unknown standard product: ${token}. Select only required products.`);
+        }
+        products.add(value);
+    }
+    if (!hostingSpecified && products.has('next'))
+        hosting = 'vercel';
+    return { products, hosting, hostingSpecified, gitSpecified };
+}
+export function parseStandardOptions(command, args) {
+    const remaining = [...args];
+    const directory = command === 'new' ? remaining.shift() : process.cwd();
+    if (!directory || directory.startsWith('-'))
+        throw new Error('new requires a destination directory.');
+    const root = path.resolve(directory);
+    const { products, hosting, hostingSpecified, gitSpecified } = parseStandardFlags(remaining);
+    resolveStandardProducts(products, hosting, hostingSpecified);
+    return {
+        root,
+        name: packageNameFromText(path.basename(root)),
+        products: [...products].sort(),
+        hosting,
+        skipInstall: remaining.includes('--skip-install'),
+        dryRun: remaining.includes('--dry-run'),
+        json: remaining.includes('--json'),
+        initializeGit: gitSpecified ?? command === 'new',
+    };
+}

package/dist/registry/receipt.d.ts

@@ -0,0 +1,3 @@
+export declare function sourceFiles(root: string): Map<string, string>;
+export declare function recordScaffoldFiles(root: string): void;
+export declare function assertSafeTarget(root: string, relative: string): void;

package/dist/registry/receipt.js

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { json, readJson } from '../scaffold/files.js';
+const excluded = new Set([
+    '.pnpm-store',
+    '.artifacts',
+    '.git',
+    'node_modules',
+    '.next',
+    '.open-next',
+    '.wrangler',
+    '.turbo',
+    'dist',
+    '.output',
+    '.expo',
+    '.fallow',
+    '.anhedral',
+    '.anhedral.lock',
+    '.anhedral-txn',
+    'anhedral.registry.json',
+]);
+export function sourceFiles(root) {
+    const files = new Map();
+    const visit = (directory) => {
+        for (const entry of readdirSync(path.join(root, directory), { withFileTypes: true })) {
+            if (excluded.has(entry.name))
+                continue;
+            const relative = directory ? `${directory}/${entry.name}` : entry.name;
+            // Local credentials are never seeded into an addition transaction or fingerprint receipt.
+            if (/^(?:\.env|\.dev\.vars)(?:\.|$)/.test(entry.name) && !entry.name.endsWith('.example'))
+                continue;
+            if (entry.isSymbolicLink())
+                throw new Error(`Source symlinks are unsupported: ${relative}.`);
+            if (entry.isDirectory())
+                visit(relative);
+            else if (entry.isFile())
+                files.set(relative, createHash('sha256')
+                    .update(readFileSync(path.join(root, relative)))
+                    .digest('hex'));
+        }
+    };
+    visit('');
+    return files;
+}
+export function recordScaffoldFiles(root) {
+    const receipt = readJson(root, 'anhedral.registry.json');
+    json(root, 'anhedral.registry.json', {
+        ...receipt,
+        files: Object.fromEntries(sourceFiles(root)),
+    });
+}
+export function assertSafeTarget(root, relative) {
+    if (!relative ||
+        path.isAbsolute(relative) ||
+        relative.includes('\\') ||
+        relative
+            .split('/')
+            .some((part) => !part ||
+            part === '.' ||
+            part === '..' ||
+            part.includes(':') ||
+            /[\x00-\x1f]/.test(part) ||
+            /[. ]$/.test(part) ||
+            /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i.test(part)))
+        throw new Error(`Unsafe registry target: ${relative}.`);
+    let current = root;
+    for (const part of relative.split('/')) {
+        current = path.join(current, part);
+        if (existsSync(current) && lstatSync(current).isSymbolicLink())
+            throw new Error(`Registry target traverses a symlink: ${relative}.`);
+    }
+}

package/dist/registry/remote.d.ts

@@ -0,0 +1,25 @@
+export interface SourceItem {
+    name: string;
+    version: string;
+    registryDependencies: string[];
+    files: {
+        target: string;
+        content: string;
+    }[];
+}
+export interface SourceRegistry {
+    schemaVersion: 1;
+    name: string;
+    items: SourceItem[];
+}
+export interface RemoteRegistry {
+    source: string;
+    integrity: string;
+    registry: SourceRegistry;
+}
+/** Declarative source only: no executable recipe callbacks, hooks or destination templates. */
+export declare function validateSourceRegistry(value: unknown): SourceRegistry;
+export declare function loadSourceRegistry(source: string, fetcher?: typeof fetch): Promise<RemoteRegistry>;
+export declare function resolveSourceItems(registry: SourceRegistry, selected: readonly string[]): SourceItem[];
+/** Compile repository-relative source paths into a distributable JSON payload. */
+export declare function buildSourceRegistry(manifestFile: string): SourceRegistry;