anhedral 0.10.0 → 0.11.0

package/dist/scaffold/auth.js

@@ -1,34 +1,35 @@
+import { writeEnvironmentFile } from './environment.js';
 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';
 import { drizzleAdapter } from '@better-auth/drizzle-adapter';
 import type { createDatabase } from '@workspace/db';
 export function createAuth(db: ReturnType<typeof createDatabase>, secret: string, baseURL: string) {
-  return betterAuth({ database: drizzleAdapter(db, { provider: '${has('neon') ? 'pg' : 'sqlite'}', transaction: false }), secret, baseURL, emailAndPassword: { enabled: true } });
+  return betterAuth({
+    database: drizzleAdapter(db, { provider: '${has('neon') ? 'pg' : 'sqlite'}', transaction: false }),
+    secret,
+    baseURL,
+    emailAndPassword: { enabled: true },
+  });
 }
 `, {
-        'better-auth': '1.7.7',
-        '@better-auth/drizzle-adapter': '1.7.7',
+        'better-auth': STACK_DEPENDENCIES['better-auth'],
+        '@better-auth/drizzle-adapter': STACK_DEPENDENCIES['@better-auth/drizzle-adapter'],
         '@workspace/db': 'workspace:*',
     });
     patchPackage(root, `apps/${runtimeApp}/package.json`, {
-        dependencies: { '@workspace/auth': 'workspace:*' },
+        dependencies: { '@workspace/auth': 'workspace:*', '@workspace/db': 'workspace:*' },
     });
     const connection = has('neon') ? 'createDatabase(env.DATABASE_URL)' : 'createDatabase(env.DB)';
     if (has('hono')) {
         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' },
-        });
     }
     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';" : ''}
@@ -44,20 +45,19 @@ 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' },
-            });
+            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'] },
         });
     }
-    put(root, `apps/${runtimeApp}/${runtimeApp === 'web' && options.hosting === 'vercel' ? '.env.example' : '.dev.vars.example'}`, `${has('neon') ? 'DATABASE_URL=\n' : ''}BETTER_AUTH_SECRET=\nBETTER_AUTH_URL=http://localhost:${runtimeApp === 'web' && (options.hosting === 'vercel' || has('vinext')) ? '3000' : '8787'}\n`);
+    writeEnvironmentFile(root, `apps/${runtimeApp}/${runtimeApp === 'web' && options.hosting === 'vercel' ? '.env.example' : '.dev.vars.example'}`, {
+        ...(has('neon') ? { DATABASE_URL: '' } : {}),
+        BETTER_AUTH_SECRET: '',
+        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')) {
@@ -74,22 +74,62 @@ export function scaffoldClerk({ root, has }) {
                 put(root, 'apps/web/app/layout.tsx', 'import { ClerkProvider } from "@clerk/nextjs";\n' + wrapped);
             }
         }
-        put(root, 'apps/web/app/sign-in/[[...sign-in]]/page.tsx', 'import { SignIn } from "@clerk/nextjs";\nexport default function SignInPage() { return <SignIn />; }\n');
-        put(root, 'apps/web/app/sign-up/[[...sign-up]]/page.tsx', 'import { SignUp } from "@clerk/nextjs";\nexport default function SignUpPage() { return <SignUp />; }\n');
+        put(root, 'apps/web/app/sign-in/[[...sign-in]]/page.tsx', `import { Suspense } from 'react';
+import { SignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+  return (
+    <Suspense fallback={<p role="status">Loading sign in…</p>}>
+      <SignIn />
+    </Suspense>
+  );
+}
+`);
+        put(root, 'apps/web/app/sign-up/[[...sign-up]]/page.tsx', `import { Suspense } from 'react';
+import { SignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+  return (
+    <Suspense fallback={<p role="status">Loading sign up…</p>}>
+      <SignUp />
+    </Suspense>
+  );
+}
+`);
         put(root, 'apps/web/proxy.ts', `import { clerkMiddleware } from '@clerk/nextjs/server';
-export default clerkMiddleware();
+import type { NextMiddleware } from 'next/server';
+
+const proxy: NextMiddleware = clerkMiddleware();
+export default proxy;
 export const config = { matcher: ['/((?!_next|[^?]*\\\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico)).*)', '/(api|trpc)(.*)'] };
 `);
         // Middleware makes auth available; product routes must explicitly require identity and authorization.
     }
     if (has('hono')) {
-        patchPackage(root, 'apps/api/package.json', {
-            dependencies: { '@clerk/backend': STACK_DEPENDENCIES['@clerk/backend'] },
-        });
-        put(root, 'apps/api/src/identity.ts', `import { createClerkClient } from '@clerk/backend';
-export async function authenticate(request: Request, secretKey: string, authorizedParties: string[]) {
-  return createClerkClient({ secretKey }).authenticateRequest(request, { authorizedParties });
+        sharedPackage(root, 'auth', `import { createClerkClient } from '@clerk/backend';
+
+export async function authenticate(
+  request: Request,
+  secretKey: string,
+  publishableKey: string,
+  authorizedParties: string[],
+) {
+  if (!secretKey || !publishableKey || authorizedParties.length === 0) {
+    throw new Error('Configure Clerk keys and explicit authorized origins before authenticating.');
+  }
+  return createClerkClient({ secretKey, publishableKey }).authenticateRequest(request, {
+    authorizedParties,
+  });
 }
-`);
+`, { '@clerk/backend': STACK_DEPENDENCIES['@clerk/backend'] });
+        writeEnvironmentFile(root, 'apps/api/.dev.vars.example', {
+            CLERK_SECRET_KEY: '',
+            CLERK_PUBLISHABLE_KEY: '',
+        });
     }
+    if (has('next') || has('vinext'))
+        writeEnvironmentFile(root, 'apps/web/.env.example', {
+            NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: '',
+            CLERK_SECRET_KEY: '',
+        });
 }

package/dist/scaffold/bootstrap.d.ts

@@ -1,3 +1,5 @@
 import type { StandardRunner } from '../registry/types.js';
 export declare function assertBootstrapPlatform(run: StandardRunner, platform?: NodeJS.Platform): void;
+/** Planning and diagnostics support older Node releases; generated dependencies do not. */
+export declare function assertWorkspaceRuntime(run: StandardRunner, version?: string): void;
 export declare function bootstrapWorkspace(root: string, name: string, run: StandardRunner, webOnly?: boolean): void;

package/dist/scaffold/bootstrap.js

@@ -6,8 +6,17 @@ export function assertBootstrapPlatform(run, platform = process.platform) {
     if (platform === 'win32' && run === execFile)
         throw new Error('Native Windows initialization is blocked because the upstream shadcn monorepo bootstrap writes component files outside the project. Run Anhedral inside WSL. Planning and doctor remain available on Windows.');
 }
+/** Planning and diagnostics support older Node releases; generated dependencies do not. */
+export function assertWorkspaceRuntime(run, version = process.versions.node) {
+    if (run !== execFile)
+        return;
+    const [major, minor] = version.split('.').map(Number);
+    if (!((major === 22 && minor >= 13) || major >= 24))
+        throw new Error('Generated workspaces require Node.js 22.13+ on the 22.x line or Node.js 24+. Planning and doctor remain available on older CLI-supported versions.');
+}
 export function bootstrapWorkspace(root, name, run, webOnly = false) {
     assertBootstrapPlatform(run);
+    assertWorkspaceRuntime(run);
     const temporary = path.join(root, '.bootstrap');
     mkdirSync(temporary);
     try {

package/dist/scaffold/database.js

@@ -1,3 +1,4 @@
+import { writeEnvironmentFile } from './environment.js';
 import { STACK_DEPENDENCIES } from '../dependencies.js';
 import { put, patchPackage, sharedPackage } from './files.js';
 export function scaffoldDatabase({ root, options, runtimeApp, has }) {
@@ -15,11 +16,14 @@ import * as schema from './schema';
 export function createDatabase(binding: Parameters<typeof drizzle>[0]) { return drizzle(binding, { schema }); }
 `, {
         'drizzle-orm': STACK_DEPENDENCIES['drizzle-orm'],
-        ...(has('neon') ? { '@neondatabase/serverless': '1.2.0' } : {}),
+        ...(has('neon')
+            ? { '@neondatabase/serverless': STACK_DEPENDENCIES['@neondatabase/serverless'] }
+            : {}),
     });
     if (has('neon')) {
         const native = runtimeApp === 'web' && options.hosting === 'vercel';
-        put(root, `apps/${runtimeApp}/${native ? '.env.example' : '.dev.vars.example'}`, 'DATABASE_URL=\n');
+        writeEnvironmentFile(root, `apps/${runtimeApp}/${native ? '.env.example' : '.dev.vars.example'}`, { DATABASE_URL: '' });
+        writeEnvironmentFile(root, 'packages/db/.env.example', { DATABASE_URL: '' });
         if (!native)
             put(root, `apps/${runtimeApp}/${runtimeApp === 'api' ? 'src/' : ''}database-secrets.d.ts`, runtimeApp === 'api'
                 ? 'interface Env { DATABASE_URL: string }\n'
@@ -27,7 +31,12 @@ export function createDatabase(binding: Parameters<typeof drizzle>[0]) { return
     }
     put(root, 'packages/db/src/schema.ts', '// Define product tables here; generate and review SQL before migration.\nexport {};\n');
     put(root, 'packages/db/drizzle.config.ts', has('neon')
-        ? `import { defineConfig } from 'drizzle-kit';
+        ? `import { existsSync } from 'node:fs';
+import { loadEnvFile } from 'node:process';
+import { defineConfig } from 'drizzle-kit';
+
+if (existsSync('.env')) loadEnvFile('.env');
+
 export default defineConfig({ dialect: 'postgresql', schema: './src/schema.ts', out: './migrations', dbCredentials: { url: process.env.DATABASE_URL! } });
 `
         : `import { defineConfig } from 'drizzle-kit';
@@ -37,7 +46,4 @@ export default defineConfig({ dialect: 'sqlite', schema: './src/schema.ts', out:
         devDependencies: { 'drizzle-kit': STACK_DEPENDENCIES['drizzle-kit'] },
         scripts: { 'db:generate': 'drizzle-kit generate' },
     });
-    patchPackage(root, `apps/${runtimeApp}/package.json`, {
-        dependencies: { '@workspace/db': 'workspace:*' },
-    });
 }

package/dist/scaffold/documentation.js

@@ -1,3 +1,4 @@
+import { markdownHeading } from '../render.js';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { put } from './files.js';
@@ -9,13 +10,15 @@ export function workerBuildSuffix(options) {
 export function writeSetupDocumentation(root, options) {
     const has = (product) => options.products.includes(product);
     const agentsFile = path.join(root, 'AGENTS.md');
+    const workerSelected = options.products.some((product) => ['vinext', 'hono', 'realtime', 'queues', 'cron', 'workflows'].includes(product)) ||
+        (has('next') && options.hosting === 'cloudflare');
     const existingAgents = existsSync(agentsFile) && (has('next') || has('vinext'))
         ? readFileSync(agentsFile, 'utf8') + '\n'
         : '';
     put(root, 'AGENTS.md', existingAgents +
         `# Anhedral delivery standard
 
-Keep accounts, source, infrastructure, billing, and recovery client-owned. Use macOS, OpenAI/Codex, Computer Use and Control Chrome during implementation and verification. Use provider plugins, APIs/MCP and CLIs for operations; Cloudflare plugin + cf where available, Wrangler for project commands.
+Keep accounts, source, infrastructure, billing, and recovery client-owned. Use the available developer tools and the selected platforms’ native toolchains for implementation and verification. Use provider plugins, APIs/MCP and CLIs for operations; Wrangler handles Cloudflare project commands.
 
 Vinext on Cloudflare Workers by default; native Next.js on Vercel is an explicit option. Free-to-start where suitable, within provider eligibility and limits. Respect the existing account, budget, audience and release authorization. Request only missing approval for paid activation, material spending, architecture changes or release. Do not deploy or activate providers as part of initialization.
 
@@ -27,33 +30,33 @@ Developer tooling includes Cloudflare’s security-audit skill (https://github.c
 
 For new projects, guide GitHub sign-in and the user's Git identity. Review files and secret ignores, commit the initial source, then use anhedral repository --create for a private repository under the authenticated user. Preserve existing origins and visibility; use an explicitly selected organization when requested. Connect Vercel with --git and verify actual GitHub installation access. For Git delivery, commit and push reviewed changes, wait for production, then use anhedral adopt and anhedral verify. Adoption checks exact repository, production branch and commit without uploading again. Use anhedral ship only for an explicit CLI delivery. Recover a fresh clone with anhedral recover; rerun product verification because prior test evidence is not recovered. Use anhedral doctor --providers to inspect installed tools and recorded provider context.
 
-Maintain docs/architecture.md with selected components, rationale, alternatives, data/access boundaries, and a diagram of actual connections. Maintain docs/verification.md with product acceptance criteria, exercised flows, evidence, and blockers. Generated setup is a starter, not implemented product behavior.
+Consult docs/stack.md for the current generated options, targets and setup requirements. Maintain docs/architecture.md with selected components, rationale, alternatives, data/access boundaries, and a diagram of actual connections. Maintain docs/verification.md with product acceptance criteria, exercised flows, evidence, and blockers. Generated setup is a starter, not implemented product behavior.
 
 Run pnpm check. Use pnpm exec fallow during development and pnpm exec fallow audit for changes. Fix legitimate findings; use narrow documented exceptions. Verify real UI flows with Computer Use and Control Chrome, plus relevant integrations, native apps/simulators, and deployed previews. Carry an authorized build-and-ship request through deployment and live verification; ask only for authorization that is still missing.
 `);
-    put(root, 'README.md', `# ${options.name}
+    put(root, 'README.md', `# ${markdownHeading(options.name)}
 
 Initialized from the official shadcn pnpm/Turborepo monorepo, with the Anhedral Application Stack & Delivery Standard.
 
-Initial selection: ${options.products.join(', ')}. Current selections and additions are recorded in anhedral.setup.json and anhedral.registry.json. ${has('vinext') ? 'Vinext App Router on Cloudflare Workers.' : has('next') ? `Next.js hosting: ${options.hosting === 'cloudflare' ? 'Cloudflare Workers + OpenNext' : 'Vercel (native Next.js default)'}.` : ''}
+Initial selection: ${options.products.join(', ')}. Current selections and additions are recorded in anhedral.setup.json, anhedral.registry.json and [docs/stack.md](docs/stack.md). ${has('vinext') ? 'Vinext App Router on Cloudflare Workers.' : has('next') ? `Next.js hosting: ${options.hosting === 'cloudflare' ? 'Cloudflare Workers + OpenNext' : 'Vercel (native Next.js default)'}.` : ''}
 
 Run pnpm install, commit pnpm-lock.yaml, then pnpm dev. Run pnpm check for lint, types, Fallow audit, tests and build. Without a Git comparison base, audit runs the full Fallow gate. Add meaningful product tests and integration checks as behavior is implemented. The tests task runs only workspaces that define tests; init does not claim product verification.
 
-${has('next') && options.hosting === 'vercel' ? 'Native Next.js uses customer-owned Vercel. Connect with the intended scope and personal/commercial use before shipping. Default to private all-deployment protection unless public access was requested; verify protection before linking Git or uploading code. Run anhedral doctor --providers for prerequisites and recorded provider context. Configure server secrets in that project; use cache components, partial prefetching, Link navigation and Suspense deliberately. ' : ''}${options.hosting === 'cloudflare' || has('hono') ? 'Cloudflare bindings contain REPLACE_WITH_* IDs. Reconcile resources in the client account and generate Worker types before development. Workers expose local dev and explicit deploy scripts. ' : ''}${has('vinext') ? 'Build with pnpm build, then pnpm --dir apps/web preview to exercise the production Worker. Vinext provides a Next-compatible API surface; native Next.js is an explicit framework option. ' : ''}${has('next') && options.hosting === 'cloudflare' ? 'Use the web preview script to exercise the actual OpenNext Worker runtime. ' : ''}Initialization does not provision infrastructure or deploy.
+${has('next') && options.hosting === 'vercel' ? 'Native Next.js uses customer-owned Vercel. Connect with the intended scope and personal/commercial use before shipping. Default to private all-deployment protection unless public access was requested; verify protection before linking Git or uploading code. Run anhedral doctor --providers for prerequisites and recorded provider context. Configure server secrets in that project; use cache components, partial prefetching, Link navigation and Suspense deliberately. ' : ''}${workerSelected ? 'Cloudflare bindings contain REPLACE_WITH_* IDs. Reconcile resources in the client account and generate Worker types before development. Workers expose local dev and explicit deploy scripts. ' : ''}${has('vinext') ? 'Build with pnpm build, then pnpm --dir apps/web preview to exercise the production Worker. Vinext provides a Next-compatible API surface; native Next.js is an explicit framework option. ' : ''}${has('next') && options.hosting === 'cloudflare' ? 'Use the web preview script to exercise the actual OpenNext Worker runtime. ' : ''}Initialization does not provision infrastructure or deploy.
 
-Security gate: pnpm audit:deps audits all dependencies. Reviewed backports in scripts/security are accepted only after patch hashes, installed package hashes and regression checks match. Unknown advisories and modified patches remain blocking.
+Security gate: pnpm audit:deps audits all dependencies and retains the original report. Reviewed backports in scripts/security are accepted only after patch hashes, installed package hashes and regression checks match. Unremediated high/critical advisories, incomplete reports and modified patches remain blocking; lower-severity findings remain visible in the report.
 
 ${has('next') && options.hosting === 'cloudflare' ? 'OpenNext is configured without a provisioned incremental-cache bucket. Choose and configure a cache adapter before using ISR or cache features that require shared persistence.\n' : ''}
 ${has('neon') ? 'Configure server-only DATABASE_URL for the intended Neon branch and role. Direct HTTP needs no Hyperdrive or connection cleanup. Review migrations and authorization; interactive transactions require a reviewed WebSocket or PostgreSQL adapter.\n' : ''}
 ${has('better-auth') ? 'Core Better Auth tables are included in the Drizzle schema. Review and apply migrations before using /api/auth. Configure BETTER_AUTH_SECRET, BETTER_AUTH_URL and trusted origins for the correct environment.\n' : ''}
-${has('clerk') ? 'Clerk middleware exposes server identity; protect selected routes explicitly. The web starter includes ClerkProvider and sign-in/sign-up pages. Configure the selected native SDKs when implementing account flows.\n' : ''}
+${has('clerk') ? `${has('next') || has('vinext') ? 'The web starter includes ClerkProvider, middleware and sign-in/sign-up pages. Configure NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and server-only CLERK_SECRET_KEY. ' : ''}${has('hono') ? 'packages/auth exports a Clerk request authentication helper. Configure its server secret and publishable key, supply explicit authorized origins, and wire it into product routes; the API health route remains public. ' : ''}Authentication does not establish resource authorization.\n` : ''}
 ${has('r2') ? 'FILES is a private R2 binding. Implement authentication and file-level authorization before exposing file routes. Clients never receive R2 credentials.\n' : ''}
 ${has('realtime') ? 'Durable Object rooms support hibernating WebSockets; the public entrypoint remains disabled until room authorization and short-lived tickets are implemented.\n' : ''}
 ${has('queues') ? 'Queue processing retries unimplemented jobs and uses a dead-letter queue. Add product processing and transactional idempotency before acknowledging messages.\n' : ''}
 ${has('basin') ? 'Basin uses a Pipelines stream binding. Configure its stream, sink, R2/catalog and SQL in client-owned infrastructure; it is distinct from operational logs.\n' : ''}
 Provider packages are SDK factories or integration boundaries, not finished business features. Connect only needed packages to server entrypoints. Billing needs verified webhooks and idempotent consumption; RevenueCat adds cross-store entitlement configuration. Local data needs a platform-specific SQLite/filesystem adapter. Sentry needs a platform SDK and runtime initialization. Native auth and subscriptions need platform-specific setup.
 
-Purchase the domain in the client's GoDaddy account, then add its zone to the client's Cloudflare account and configure Cloudflare nameservers. The client retains registration, renewal, billing and recovery ownership. Verify DNS records and zone activation before connecting application domains and mail. Inbound mail uses Cloudflare Email Routing. Outbound business and application mail defaults to Cloudflare Email Sending; Resend is an alternative when selected. Configure the selected mail provider before use; init does not provision domains or mail services. GitHub Actions runs PR checks and never deploys automatically. Respect existing authorization; request only missing approval for paid activation, material spending, architecture changes or release.
+When the product needs a domain, purchase it in the client's GoDaddy account, then add its zone to the client's Cloudflare account and configure Cloudflare nameservers. The client retains registration, renewal, billing and recovery ownership. Verify DNS records and zone activation before connecting application domains and mail. Inbound mail uses Cloudflare Email Routing. Outbound business and application mail defaults to Cloudflare Email Sending; Resend is an alternative when selected. Configure the selected mail provider before use; init does not provision domains or mail services. GitHub Actions runs PR checks and never deploys automatically. Respect existing authorization; request only missing approval for paid activation, material spending, architecture changes or release.
 `);
     put(root, '.github/workflows/check.yml', `name: Check
 on:

package/dist/scaffold/environment.d.ts

@@ -1,2 +1,4 @@
 import type { ResolvedStackRegistry } from '../registry/resolve.js';
+/** Extend examples without discarding earlier recipe defaults or customer comments. */
+export declare function writeEnvironmentFile(root: string, file: string, variables: Record<string, string>): void;
 export declare function writeEnvironmentExample(root: string, registry: ResolvedStackRegistry): void;

package/dist/scaffold/environment.js

@@ -1,5 +1,22 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
 import { put } from './files.js';
+/** Extend examples without discarding earlier recipe defaults or customer comments. */
+export function writeEnvironmentFile(root, file, variables) {
+    const destination = path.join(root, file);
+    let content = existsSync(destination) ? readFileSync(destination, 'utf8') : '';
+    const keys = new Set([...content.matchAll(/^[ \t]*(?:export[ \t]+)?([A-Z][A-Z0-9_]*)[ \t]*=/gm)].map((match) => match[1]));
+    const additions = Object.entries(variables)
+        .filter(([key]) => !keys.has(key))
+        .map(([key, value]) => `${key}=${value}`);
+    if (additions.length) {
+        if (content && !content.endsWith('\n'))
+            content += '\n';
+        content += additions.join('\n') + '\n';
+    }
+    put(root, file, content || '\n');
+}
 export function writeEnvironmentExample(root, registry) {
     const names = [...new Set(registry.items.flatMap((item) => item.environment))].sort();
-    put(root, '.env.example', names.map((name) => `${name}=`).join('\n') + '\n');
+    writeEnvironmentFile(root, '.env.example', Object.fromEntries(names.map((name) => [name, ''])));
 }

package/dist/scaffold/files.d.ts

@@ -10,6 +10,7 @@ export interface PackageManifest extends Json {
     };
 }
 export interface TurboConfig extends Json {
+    globalEnv?: string[];
     tasks: Record<string, {
         dependsOn?: string[];
         outputs?: string[];

package/dist/scaffold/files.js

@@ -1,9 +1,17 @@
-import { STACK_DEPENDENCIES } from '../dependencies.js';
-import { readFileSync } from 'node:fs';
+import { STACK_DEPENDENCIES, WORKER_DEV_PORTS } from '../dependencies.js';
+import { readBoundedFile, MAX_PROJECT_JSON_BYTES } from '../bounded-file.js';
 import path from 'node:path';
 import { writeFile } from '../util.js';
 export function readJson(root, file) {
-    const value = JSON.parse(readFileSync(path.join(root, file), 'utf8'));
+    let value;
+    try {
+        value = JSON.parse(readBoundedFile(path.join(root, file), MAX_PROJECT_JSON_BYTES).toString('utf8'));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new Error(`Invalid JSON in ${file}.`);
+        throw error;
+    }
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error(`Expected a JSON object: ${file}.`);
     return value;
@@ -34,12 +42,15 @@ export function workerConfig(name) {
     };
 }
 export function worker(root, app, config, source, dependencies = {}) {
+    const ports = WORKER_DEV_PORTS[app];
+    if (!ports)
+        throw new Error(`Unknown Worker application: ${app}.`);
     json(root, `apps/${app}/package.json`, {
         name: `@workspace/${app}`,
         private: true,
         type: 'module',
         scripts: {
-            dev: 'wrangler dev',
+            dev: `wrangler dev --port ${ports.http} --inspector-port ${ports.inspector}`,
             build: 'wrangler deploy --dry-run --outdir dist',
             deploy: 'wrangler deploy',
             typecheck: 'wrangler types && tsc --noEmit',

package/dist/scaffold/services.js

@@ -1,20 +1,35 @@
+import { resourceName } from '../render.js';
 import { workerConfig, worker } from './files.js';
 export function scaffoldRealtime({ root, options }) {
     worker(root, 'realtime', {
-        ...workerConfig(`${options.name}-realtime`),
+        ...workerConfig(resourceName(options.name, 'realtime')),
         durable_objects: { bindings: [{ name: 'ROOMS', class_name: 'Room' }] },
         migrations: [{ tag: 'v1', new_sqlite_classes: ['Room'] }],
     }, `import { DurableObject } from 'cloudflare:workers';
 export class Room extends DurableObject<Env> {
   async fetch(request: Request): Promise<Response> {
-    if (request.headers.get('Upgrade') !== 'websocket') return new Response('WebSocket required', { status: 426 });
+    if (request.headers.get('Upgrade')?.toLowerCase() !== 'websocket') {
+      return new Response('WebSocket required', { status: 426 });
+    }
     const pair = new WebSocketPair();
     this.ctx.acceptWebSocket(pair[1]);
     return new Response(null, { status: 101, webSocket: pair[0] });
   }
   webSocketMessage(sender: WebSocket, message: string | ArrayBuffer) {
-    if ((typeof message === 'string' ? new TextEncoder().encode(message).byteLength : message.byteLength) > 16384) { sender.close(1009, 'Message too large'); return; }
-    this.ctx.getWebSockets().filter((socket) => socket !== sender).forEach((socket) => socket.send(message));
+    const size = typeof message === 'string'
+      ? new TextEncoder().encode(message).byteLength
+      : message.byteLength;
+    if (size > 16384) {
+      sender.close(1009, 'Message too large');
+      return;
+    }
+    this.#broadcastToPeers(sender, message);
+  }
+
+  #broadcastToPeers(sender: WebSocket, message: string | ArrayBuffer) {
+    for (const socket of this.ctx.getWebSockets()) {
+      if (socket !== sender) socket.send(message);
+    }
   }
 }
 export default {
@@ -28,15 +43,15 @@ export default {
 }
 export function scaffoldQueues({ root, options }) {
     worker(root, 'jobs', {
-        ...workerConfig(`${options.name}-jobs`),
+        ...workerConfig(resourceName(options.name, 'jobs')),
         queues: {
-            producers: [{ binding: 'JOBS', queue: `${options.name}-jobs` }],
+            producers: [{ binding: 'JOBS', queue: resourceName(options.name, 'jobs') }],
             consumers: [
                 {
-                    queue: `${options.name}-jobs`,
+                    queue: resourceName(options.name, 'jobs'),
                     max_batch_size: 10,
                     max_retries: 3,
-                    dead_letter_queue: `${options.name}-jobs-dlq`,
+                    dead_letter_queue: resourceName(options.name, 'jobs-dlq'),
                 },
             ],
         },
@@ -52,7 +67,10 @@ export function scaffoldQueues({ root, options }) {
 `);
 }
 export function scaffoldCron({ root, options }) {
-    worker(root, 'scheduled', { ...workerConfig(`${options.name}-scheduled`), triggers: { crons: ['0 * * * *'] } }, `export default {
+    worker(root, 'scheduled', {
+        ...workerConfig(resourceName(options.name, 'scheduled')),
+        triggers: { crons: ['0 * * * *'] },
+    }, `export default {
   async scheduled(controller: ScheduledController): Promise<void> {
     // Define a product schedule, idempotency key, overlap policy, and failure alerts before release.
     console.log('Scheduled trigger', controller.scheduledTime);
@@ -62,10 +80,10 @@ export function scaffoldCron({ root, options }) {
 }
 export function scaffoldWorkflows({ root, options }) {
     worker(root, 'workflows', {
-        ...workerConfig(`${options.name}-workflows`),
+        ...workerConfig(resourceName(options.name, 'workflows')),
         workflows: [
             {
-                name: `${options.name}-workflow`,
+                name: resourceName(options.name, 'workflow'),
                 binding: 'WORKFLOW',
                 class_name: 'ApplicationWorkflow',
             },
@@ -74,11 +92,17 @@ export function scaffoldWorkflows({ root, options }) {
 export class ApplicationWorkflow extends WorkflowEntrypoint<Env, { operationId: string }> {
   async run(event: WorkflowEvent<{ operationId: string }>, step: WorkflowStep) {
     return step.do('validate', { retries: { limit: 3, delay: '10 seconds', backoff: 'exponential' } }, async () => {
-      if (!event.payload.operationId) throw new Error('operationId required');
+      if (typeof event.payload.operationId !== 'string' || !event.payload.operationId) {
+        throw new Error('operationId required');
+      }
       return { operationId: event.payload.operationId };
     });
   }
 }
-export default { async fetch() { return new Response('Use an authorized server binding to create workflows', { status: 403 }); } };
+export default {
+  async fetch() {
+    return new Response('Use an authorized server binding to create workflows', { status: 403 });
+  },
+};
 `);
 }

package/dist/scaffold/stack-documentation.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedStackRegistry } from '../registry/resolve.js';
+/** Human-readable companion to the current resolved registry, refreshed by add. */
+export declare function writeStackDocumentation(root: string, registry: ResolvedStackRegistry): void;

package/dist/scaffold/stack-documentation.js

@@ -0,0 +1,52 @@
+import { WORKER_DEV_PORTS } from '../dependencies.js';
+import { put } from './files.js';
+/** Human-readable companion to the current resolved registry, refreshed by add. */
+export function writeStackDocumentation(root, registry) {
+    const sections = registry.items.map((item) => {
+        const lines = [
+            `## ${item.name}`,
+            '',
+            item.description + '.',
+            '',
+            `Targets: ${item.targets.map((target) => `\`${target}\``).join(', ')}.`,
+        ];
+        if (item.environment.length)
+            lines.push(`Environment: ${item.environment.map((key) => `\`${key}\``).join(', ')}.`);
+        if (item.bindings)
+            lines.push('', 'Worker configuration:', '', '```json', JSON.stringify(item.bindings, null, 2), '```');
+        if (item.setup) {
+            for (const [label, entries] of [
+                ['Required setup', item.setup.resources],
+                ['Credentials', item.setup.credentials],
+                ['Verify before delivery', item.setup.verify],
+            ]) {
+                if (!entries.length)
+                    continue;
+                lines.push('', `${label}:`, '', ...entries.map((entry) => `- ${entry}`));
+            }
+        }
+        return lines.join('\n');
+    });
+    const ports = Object.entries(WORKER_DEV_PORTS)
+        .filter(([app]) => registry.items.some((item) => item.targets.includes(`apps/${app}`)))
+        .map(([app, port]) => `| ${app} | ${port.http} | ${port.inspector} |`);
+    put(root, 'docs/stack.md', [
+        '# Selected stack',
+        '',
+        `Generated from the bundled Anhedral ${registry.cliVersion} registry. This file is refreshed by add. Keep product decisions in docs/architecture.md and acceptance evidence in docs/verification.md.`,
+        '',
+        'These are scaffolds and integration boundaries. Provider access, migrations, authorization and live behavior require the setup and checks listed below.',
+        ...(ports.length
+            ? [
+                '',
+                '## Local Worker ports',
+                '',
+                '| Application | HTTP | Inspector |',
+                '| --- | --- | --- |',
+                ...ports,
+            ]
+            : []),
+        '',
+        ...sections.flatMap((section) => [section, '']),
+    ].join('\n'));
+}

package/dist/scaffold/styling.d.ts

@@ -0,0 +1,3 @@
+import type { RecipeContext } from '../registry/types.js';
+/** Shared data and a Tailwind v3 preset for Expo/NativeWind and WXT. */
+export declare function scaffoldStyling({ root }: RecipeContext): void;

package/dist/scaffold/styling.js

@@ -0,0 +1,84 @@
+import { json, patchPackage, put, readJson } from './files.js';
+/** Shared data and a Tailwind v3 preset for Expo/NativeWind and WXT. */
+export function scaffoldStyling({ root }) {
+    put(root, 'packages/styling/src/tokens.cjs', `exports.light = {
+  '--background': '0 0% 100%',
+  '--foreground': '0 0% 9%',
+  '--card': '0 0% 100%',
+  '--card-foreground': '0 0% 9%',
+  '--popover': '0 0% 100%',
+  '--popover-foreground': '0 0% 9%',
+  '--primary': '0 0% 9%',
+  '--primary-foreground': '0 0% 98%',
+  '--secondary': '0 0% 96.1%',
+  '--secondary-foreground': '0 0% 9%',
+  '--muted': '0 0% 96.1%',
+  '--muted-foreground': '0 0% 45.1%',
+  '--accent': '0 0% 96.1%',
+  '--accent-foreground': '0 0% 9%',
+  '--destructive': '0 84.2% 60.2%',
+  '--destructive-foreground': '0 0% 98%',
+  '--border': '0 0% 89.8%',
+  '--input': '0 0% 89.8%',
+  '--ring': '0 0% 63.9%',
+  '--radius': '0.5rem',
+};
+
+exports.dark = {
+  ...exports.light,
+  '--background': '0 0% 9%',
+  '--foreground': '0 0% 98%',
+  '--card': '0 0% 9%',
+  '--card-foreground': '0 0% 98%',
+  '--popover': '0 0% 9%',
+  '--popover-foreground': '0 0% 98%',
+  '--primary': '0 0% 98%',
+  '--primary-foreground': '0 0% 9%',
+  '--secondary': '0 0% 14.9%',
+  '--secondary-foreground': '0 0% 98%',
+  '--muted': '0 0% 14.9%',
+  '--muted-foreground': '0 0% 63.9%',
+  '--accent': '0 0% 14.9%',
+  '--accent-foreground': '0 0% 98%',
+  '--destructive': '0 70.9% 59.4%',
+  '--border': '0 0% 14.9%',
+  '--input': '0 0% 14.9%',
+};
+
+exports.spacing = { small: 4, medium: 8, large: 16 };
+`);
+    put(root, 'packages/styling/tailwind.cjs', `const { light, dark } = require('./src/tokens.cjs');
+const color = (name) => 'hsl(var(--' + name + '))';
+const surface = (name) => ({ DEFAULT: color(name), foreground: color(name + '-foreground') });
+
+module.exports = {
+  darkMode: 'class',
+  theme: {
+    extend: {
+      colors: {
+        border: color('border'), input: color('input'), ring: color('ring'),
+        background: color('background'), foreground: color('foreground'),
+        primary: surface('primary'), secondary: surface('secondary'),
+        destructive: surface('destructive'), muted: surface('muted'),
+        accent: surface('accent'), popover: surface('popover'), card: surface('card'),
+      },
+      borderRadius: {
+        lg: 'var(--radius)', md: 'calc(var(--radius) - 2px)', sm: 'calc(var(--radius) - 4px)',
+      },
+    },
+  },
+  plugins: [function themeVariables({ addBase }) {
+    addBase({ ':root': light, '.dark:root': dark });
+  }],
+};
+`);
+    patchPackage(root, 'packages/styling/package.json', {
+        exports: { '.': './src/index.ts', './tailwind': './tailwind.cjs' },
+    });
+    const config = readJson(root, 'packages/styling/tsconfig.json');
+    json(root, 'packages/styling/tsconfig.json', {
+        ...config,
+        compilerOptions: { ...config.compilerOptions, allowJs: true },
+        include: ['src/**/*.ts', 'src/**/*.cjs', 'tailwind.cjs'],
+    });
+}