@craft-ts/dev-tools 0.7.0-beta.13

package/src/scripts/create/create-project.ts

@@ -0,0 +1,849 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { runArchitectureMigration } from '../architecture/migrate-architecture.js';
+
+export const CRAFT_TS_STARTER_VERSION = '^0.7.0-beta.11';
+export const EFFECT_V4_VERSION = '^4.0.0-rc.110';
+
+export type CreateAgent = 'codex' | 'cursor' | 'claude-code' | 'cloud-code';
+export type CreateMode = 'effect' | 'plain';
+
+export type CreateProjectOptions = {
+  readonly directory: string;
+  readonly rootDir?: string;
+  readonly mode?: CreateMode;
+  readonly agents?: readonly CreateAgent[];
+  readonly force?: boolean;
+};
+
+export type CreateProjectResult = {
+  readonly directory: string;
+  readonly mode: CreateMode;
+  readonly agents: readonly CreateAgent[];
+  readonly changedFiles: readonly string[];
+};
+
+const DEFAULT_AGENTS: readonly CreateAgent[] = ['codex'];
+
+const BASE_AGENT_SKILL = `---
+name: craft-ts-project
+description: Build and evolve a framework-independent CraftTS application with typed reactivity, routing, API boundaries, lint and architecture contracts. Use when adding or reviewing CraftTS state, queries, mutations, components, routes, tests, or project structure.
+---
+
+# CraftTS project
+
+This project uses CraftTS without Angular. The renderer is @craft-ts/component,
+the reactive runtime is @craft-ts/core, and the application entry point is
+bootstrapCraft.
+
+## Workflow
+
+1. Read the existing component, route and API boundary before editing.
+2. Use query for server reads, mutation for writes, and CraftHttpClient
+   for transport. Yield every Craft reader.
+3. Use craftComponent, craftRoutes, componentDeps and the route DI proof;
+   do not introduce Angular decorators or inject().
+4. Run the focused test, then npm run lint, npm run typecheck,
+   npm run architecture, and npm run e2e when the browser flow changed.
+
+## Architecture tests
+
+The architecture/ suite is a graph-wide contract, not feature-level TDD. It
+checks invariants such as one owner per HTTP endpoint, no dependency cycles,
+declarative reactive code, named interactive elements and armed route DI.
+Run it after each structural change. Do not add an architecture it() merely
+because a new feature was added. Add a new rule only when a product invariant
+must prevent a recurring graph smell and no baseline helper covers it.
+
+The catalog is generated by architecture/load-graph.ts; never hand-edit
+architecture/catalog.ts.
+`;
+
+const EFFECT_AGENT_SKILL = `---
+name: craft-ts-effect-v4
+description: Build the Effect v4 integration of a framework-independent CraftTS project with typed services, Layers, queryEffect and Effect diagnostics. Use when editing an Effect-enabled starter or introducing Effect domain code.
+---
+
+# CraftTS + Effect v4
+
+This project deliberately uses Effect v4 (effect@${EFFECT_V4_VERSION}) and
+@craft-ts/effect. Keep the boundary explicit:
+
+- domain operations return Effect.Effect and depend on Context.Service;
+- production implementations are supplied by Layer;
+- UI data loading uses queryEffect, never a component-side runPromise;
+- installCraftEffectBridge() is installed once at bootstrap;
+- run npm run effect-check after changing an Effect generator, service or
+  Layer, then run the architecture suite.
+
+Do not silently replace Effect v4 APIs with v3 examples. Confirm a symbol in
+the installed package before using it.
+`;
+
+const AGENTS_MD = (mode: CreateMode): string => `# CraftTS project
+
+This project was created with \`craft create\` in **${mode === 'effect' ? 'Effect v4' : 'plain CraftTS'}** mode.
+
+Read \`.agents/skills/craft-ts-project/SKILL.md\` before changing application
+code. ${mode === 'effect' ? 'Effect-specific guidance is in `.agents/skills/craft-ts-effect-v4/SKILL.md`.' : ''}
+
+The architecture suite is a graph contract. Run \`npm run architecture\`;
+do not add a test per feature. Add a rule only for a recurring product-level
+dependency smell not already covered by the baseline helpers.
+`;
+
+type TemplateContext = {
+  readonly projectName: string;
+  readonly mode: CreateMode;
+};
+
+function json(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function packageJson(context: TemplateContext): string {
+  const effect = context.mode === 'effect';
+  return json({
+    name: context.projectName,
+    private: true,
+    type: 'module',
+    engines: { node: '>=20.19.0' },
+    scripts: {
+      dev: 'vite --host 127.0.0.1',
+      build: 'vite build',
+      lint: 'eslint .',
+      typecheck: 'tsc -p tsconfig.app.json --noEmit',
+      'typecheck-spec': 'tsc -p tsconfig.spec.json --noEmit',
+      test: 'vitest run --config vitest.config.ts',
+      e2e: 'playwright test',
+      ...(effect
+        ? {
+            'effect-check':
+              'node scripts/run-effect-tsgo.mjs diagnostics --project tsconfig.effect.json --severity error,warning',
+          }
+        : {}),
+      architecture: 'vitest run --config vitest.architecture.config.ts',
+      'typecheck-architecture':
+        'tsc -p tsconfig.architecture.json --noEmit',
+    },
+    dependencies: {
+      '@craft-ts/component': CRAFT_TS_STARTER_VERSION,
+      '@craft-ts/core': CRAFT_TS_STARTER_VERSION,
+      ...(effect ? { '@craft-ts/effect': CRAFT_TS_STARTER_VERSION, effect: EFFECT_V4_VERSION } : {}),
+    },
+    devDependencies: {
+      '@craft-ts/dev-tools': CRAFT_TS_STARTER_VERSION,
+      '@craft-ts/mcp': CRAFT_TS_STARTER_VERSION,
+      '@playwright/test': '^1.52.0',
+      '@types/node': '^22.0.0',
+      ...(effect
+        ? {
+            '@effect/tsgo': '^0.24.3',
+            '@typescript/native': 'npm:typescript@7.0.2',
+          }
+        : {}),
+      '@eslint/js': '^9.0.0',
+      'eslint': '^9.0.0',
+      'eslint-config-prettier': '^10.0.0',
+      'eslint-plugin-playwright': '^2.0.0',
+      'typescript': '^6.0.3',
+      'typescript-eslint': '^8.0.0',
+      'vite': '^8.0.0',
+      'vitest': '^4.0.0',
+    },
+  });
+}
+
+function tsconfig(context: TemplateContext): string {
+  return json({
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'preserve',
+      moduleResolution: 'bundler',
+      strict: true,
+      noEmit: true,
+      isolatedModules: true,
+      verbatimModuleSyntax: true,
+      erasableSyntaxOnly: false,
+      skipLibCheck: true,
+      types: ['node'],
+    },
+    references: [
+      { path: './tsconfig.app.json' },
+      { path: './tsconfig.spec.json' },
+      { path: './tsconfig.architecture.json' },
+      ...(context.mode === 'effect' ? [{ path: './tsconfig.effect.json' }] : []),
+    ],
+  });
+}
+
+const tsconfigApp = `{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "types": ["vite/client"] },
+  "files": ["src/main.ts"],
+  "include": ["src/**/*.d.ts"],
+  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
+}\n`;
+
+const tsconfigSpec = `{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "types": ["node", "vitest/globals", "vite/client"] },
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "e2e/**/*.ts"],
+  "exclude": ["src/main.ts"]
+}\n`;
+
+const tsconfigEffect = `{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "noEmit": true },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
+}\n`;
+
+const viteConfig = `import { defineConfig } from 'vite';
+
+export default defineConfig({
+  server: { host: '127.0.0.1', port: 4173 },
+  build: { target: 'es2022' },
+});
+`;
+
+const effectTsgoRunner = `import { chmodSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+const projectRoot = resolve(import.meta.dirname, '..');
+const effectTsgoPath = resolve(projectRoot, 'node_modules/.bin/effect-tsgo');
+if (process.platform !== 'win32') {
+  const nativeBinary = resolve(
+    projectRoot,
+    'node_modules',
+    '@effect',
+    'tsgo-' + process.platform + '-' + process.arch,
+    'lib',
+    'tsc',
+  );
+  if (existsSync(nativeBinary)) chmodSync(nativeBinary, 0o755);
+}
+const result = spawnSync(effectTsgoPath, process.argv.slice(2), {
+  cwd: projectRoot,
+  stdio: 'inherit',
+});
+if (result.error) throw result.error;
+process.exitCode = result.status ?? 1;
+`;
+
+const vitestConfig = `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    name: 'craft-ts-app',
+    globals: true,
+    environment: 'jsdom',
+    include: ['src/**/*.spec.ts'],
+  },
+});
+`;
+
+const eslintConfig = `import js from '@eslint/js';
+import prettier from 'eslint-config-prettier';
+import playwright from 'eslint-plugin-playwright';
+import tseslint from 'typescript-eslint';
+import craftRules from '@craft-ts/dev-tools/eslint-rules';
+
+export default tseslint.config(
+  { ignores: ['dist/**', 'node_modules/**', '**/architecture/catalog.ts'] },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['src/**/*.ts'],
+    plugins: { 'craft-ts': craftRules },
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.app.json', './tsconfig.spec.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      ...craftRules.configs.recommended.rules,
+      '@typescript-eslint/no-unused-vars': ['error', { varsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    files: ['src/**/*.spec.ts', 'src/**/*.test.ts'],
+    rules: {
+      'craft-ts/no-async-await': 'off',
+      'craft-ts/no-throw': 'off',
+      'craft-ts/prefer-browser-boundaries': 'off',
+      'craft-ts/prefer-craft-template-blocks': 'off',
+      'craft-ts/no-ephemeral-template-form-state': 'off',
+    },
+  },
+  {
+    files: ['e2e/**/*.ts'],
+    ...playwright.configs['flat/recommended'],
+  },
+  {
+    files: ['scripts/**/*.mjs'],
+    languageOptions: {
+      globals: { process: 'readonly' },
+    },
+  },
+  prettier,
+);
+`;
+
+const indexHtml = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>CraftTS starter</title>
+  </head>
+  <body>
+    <craft-root></craft-root>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+`;
+
+const styles = `:root { font-family: Inter, ui-sans-serif, system-ui, sans-serif; color: #172033; background: #f7f8fb; }
+* { box-sizing: border-box; }
+body { margin: 0; min-width: 320px; }
+a { color: #2457d6; }
+main { max-width: 860px; margin: 0 auto; padding: 3rem 1.25rem; }
+nav { display: flex; gap: 1rem; padding: 1rem 1.25rem; background: white; border-bottom: 1px solid #e3e7ef; }
+.card { padding: 1.5rem; background: white; border: 1px solid #e3e7ef; border-radius: .75rem; box-shadow: 0 8px 30px #1720330d; }
+.muted { color: #5c677d; }
+.error { color: #b42318; }
+button:focus-visible, a:focus-visible { outline: 3px solid #7aa2ff; outline-offset: 3px; }
+`;
+
+const mainTs = `import { bootstrapCraft } from '@craft-ts/component';
+import { appConfig } from './app/app.config';
+import './styles.css';
+
+bootstrapCraft({ config: appConfig });
+`;
+
+const appTs = `import {
+  a,
+  CraftRouterOutlet,
+  craftComponent,
+  div,
+  main,
+  nav,
+} from '@craft-ts/component';
+import { CraftRouterLink } from '@craft-ts/core';
+
+export const App = craftComponent(
+  'App',
+  {},
+  () => ({}),
+  () =>
+    div([
+      nav([
+        a('home', { craftRouterLink: { to: '' } }, 'Home').pipe(CraftRouterLink),
+        a('about', { craftRouterLink: { to: 'about' } }, 'About').pipe(CraftRouterLink),
+      ]),
+      main(CraftRouterOutlet()),
+    ]),
+);
+`;
+
+const routesTs = `import { loadCraftComponent } from '@craft-ts/component';
+import {
+  assertExhaustiveRouteExceptions,
+  craftRoutes,
+  type CanRun,
+  type CraftRouter,
+  type ValidateCascadeRoutesFile,
+} from '@craft-ts/core';
+
+export const { appRoutes } = craftRoutes('app', [
+  {
+    path: '',
+    ...loadCraftComponent(({ withRetry }) =>
+      withRetry(import('./home-page')).then(
+        (module: typeof import('./home-page')) => module.default,
+      ),
+    ),
+  },
+  {
+    path: 'about',
+    ...loadCraftComponent(({ withRetry }) =>
+      withRetry(import('./about-page')).then(
+        (module: typeof import('./about-page')) => module.default,
+      ),
+    ),
+  },
+]);
+
+assertExhaustiveRouteExceptions(appRoutes);
+
+type _CheckAppDI = ValidateCascadeRoutesFile<
+  never,
+  CraftRouter,
+  typeof appRoutes
+>;
+type _CanRunAppDI = CanRun<_CheckAppDI>;
+
+declare module '@craft-ts/core' {
+  interface CraftRouterRoutesRegistry {
+    App: typeof appRoutes.META_PATHS;
+  }
+}
+`;
+
+const appConfigTs = `import { provideCraftRootComponent } from '@craft-ts/component';
+import { craftAppConfig, provideCraftRouter } from '@craft-ts/core';
+import { App } from './app';
+import { appRoutes } from './app.routes';
+
+export const appConfig = craftAppConfig({
+  routingDeps: appRoutes.META_PATHS,
+  providers: [
+    provideCraftRootComponent(App),
+    provideCraftRouter(appRoutes.toRoutes()),
+  ],
+});
+`;
+
+const apiTs = `import { CraftHttpClient } from '@craft-ts/core';
+
+export type WelcomeResponse = {
+  readonly title: string;
+  readonly body: string;
+};
+
+export function* loadWelcome() {
+  return yield* CraftHttpClient.get(({ response }) => ({
+    url: '/api/welcome',
+    success: response<WelcomeResponse>(),
+  }));
+}
+`;
+
+const aboutPageTs = `import { craftComponent, div, heading, p } from '@craft-ts/component';
+
+export const AboutPage = craftComponent(
+  'AboutPage',
+  {},
+  () => ({}),
+  () =>
+    div({ class: 'card' }, [
+      heading('About this starter'),
+      p('This page proves that Craft routing and lazy component loading are wired.'),
+    ]),
+);
+
+export default AboutPage;
+`;
+
+const plainHomePageTs = `import {
+  craftComponent,
+  div,
+  heading,
+  ifBlock,
+  p,
+  span,
+} from '@craft-ts/component';
+import { craftComputed, query } from '@craft-ts/core';
+import { loadWelcome } from './api';
+
+export const HomePage = craftComponent(
+  'HomePage',
+  {},
+  function* () {
+    const welcomeQuery = yield* query(
+      'welcomeQuery',
+      {
+        params: () => true,
+        loader: function* () {
+          return yield* loadWelcome();
+        },
+      },
+      ({ resource }) => ({
+        hasWelcome: craftComputed('hasWelcome', () => resource.hasValue()),
+      }),
+    );
+    return { welcomeQuery };
+  },
+  ({ welcomeQuery }) =>
+    div({ class: 'card' }, [
+      heading('Welcome to CraftTS'),
+      p('A framework-independent starter with a typed API boundary.'),
+      ifBlock(welcomeQuery.isLoading, () => p({ class: 'muted' }, 'Loading API…')),
+      ifBlock(welcomeQuery.hasWelcome, () =>
+        div([
+          p(function* () {
+            return 'API title: ' + (yield* welcomeQuery.value()).title;
+          }),
+          p(function* () {
+            return 'API body: ' + (yield* welcomeQuery.value()).body;
+          }),
+        ]),
+      ),
+      ifBlock(welcomeQuery.hasException, () =>
+        p({ class: 'error' }, [span('The API request failed. Check the network tab.')]),
+      ),
+    ]),
+);
+
+export default HomePage;
+`;
+
+const effectDomainTs = `/* eslint-disable craft-ts/prefer-craft-http-transport, craft-ts/no-async-await, craft-ts/no-throw -- Effect owns this typed transport boundary. */
+import { Context, Data, Effect, Layer } from 'effect';
+
+export type WelcomeResponse = {
+  readonly title: string;
+  readonly body: string;
+};
+
+export class WelcomeApiError extends Data.TaggedError('WelcomeApiError')<{
+  readonly message: string;
+}> {}
+
+export type WelcomeRepository = {
+  readonly load: () => Effect.Effect<WelcomeResponse, WelcomeApiError>;
+};
+
+export class WelcomeRepositoryService extends Context.Service<
+  WelcomeRepositoryService,
+  WelcomeRepository
+>()('starter/WelcomeRepository') {}
+
+export const WelcomeRepositoryLive = Layer.succeed(WelcomeRepositoryService, {
+  load: () =>
+    Effect.tryPromise({
+      try: async () => {
+        const response = await fetch('/api/welcome');
+        if (!response.ok) throw new Error('HTTP ' + response.status);
+        return (await response.json()) as WelcomeResponse;
+      },
+      catch: (cause) => new WelcomeApiError({ message: String(cause) }),
+    }),
+});
+
+export const loadWelcome = (): Effect.Effect<
+  WelcomeResponse,
+  WelcomeApiError,
+  WelcomeRepositoryService
+> =>
+  Effect.gen(function* () {
+    const repository = yield* WelcomeRepositoryService;
+    return yield* repository.load();
+  });
+`;
+
+const effectHomePageTs = `import {
+  craftComponent,
+  div,
+  heading,
+  ifBlock,
+  p,
+  span,
+} from '@craft-ts/component';
+import { craftComputed } from '@craft-ts/core';
+import { queryEffect } from '@craft-ts/effect';
+import { loadWelcome, type WelcomeApiError } from './domain';
+
+export const HomePage = craftComponent(
+  'HomePage',
+  {},
+  function* () {
+    const welcomeQuery = yield* queryEffect(
+      'welcomeQuery',
+      {
+        method: (request: boolean) => request,
+        loader: () => loadWelcome(),
+      },
+      ({ resource, exceptions }) => ({
+        hasWelcome: craftComputed('hasWelcome', () => resource.hasValue()),
+        errorMessage: craftComputed('errorMessage', function* () {
+          return (yield* exceptions()).loader?.message ?? 'Unknown API error';
+        }),
+      }),
+    );
+    yield* welcomeQuery.call(true);
+    return { welcomeQuery };
+  },
+  ({ welcomeQuery }) =>
+    div({ class: 'card' }, [
+      heading('Welcome to CraftTS + Effect v4'),
+      p('The page uses queryEffect over a typed repository Layer.'),
+      ifBlock(welcomeQuery.isLoading, () => p({ class: 'muted' }, 'Loading API…')),
+      ifBlock(welcomeQuery.hasWelcome, () =>
+        div([
+          p(function* () {
+            return 'API title: ' + (yield* welcomeQuery.value()).title;
+          }),
+          p(function* () {
+            return 'API body: ' + (yield* welcomeQuery.value()).body;
+          }),
+        ]),
+      ),
+      ifBlock(welcomeQuery.hasException, () =>
+        p({ class: 'error' }, [
+          span(function* () {
+            return 'API error: ' + (yield* welcomeQuery.errorMessage());
+          }),
+        ]),
+      ),
+    ]),
+);
+
+export type HomePageError = WelcomeApiError;
+
+export default HomePage;
+`;
+
+const plainAppConfig = appConfigTs;
+const effectAppConfig = `import { provideCraftRootComponent } from '@craft-ts/component';
+import {
+  craftAppConfig,
+  provideAppInitializer,
+  provideCraftRouter,
+} from '@craft-ts/core';
+import {
+  installCraftEffectBridge,
+  provideLayer,
+} from '@craft-ts/effect';
+import { App } from './app';
+import { appRoutes } from './app.routes';
+import {
+  WelcomeRepositoryLive,
+} from './domain';
+
+const effectProviders = [provideLayer(WelcomeRepositoryLive)] as const;
+
+export const appConfig = craftAppConfig({
+  routingDeps: appRoutes.META_PATHS,
+  providers: [
+    provideCraftRootComponent(App),
+    provideCraftRouter(appRoutes.toRoutes()),
+    ...effectProviders,
+    provideAppInitializer(() => installCraftEffectBridge()),
+  ],
+});
+
+// effectProviders is a typed tuple: removing the Layer makes the app config
+// fail at the provider boundary before the application can boot.
+`;
+
+function unitTestTs(context: TemplateContext): string {
+  const effect = context.mode === 'effect';
+  return `// @vitest-environment jsdom
+import { mountCraftComponent } from '@craft-ts/component';
+import { TestBed, ɵInjector as Injector } from '@craft-ts/core';
+${effect ? "import { installCraftEffectBridge, provideLayer } from '@craft-ts/effect';\nimport { WelcomeRepositoryLive } from './domain';" : ''}
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { HomePage } from './home-page';
+
+describe('HomePage', () => {
+  ${effect ? 'let disposeBridge: () => void;' : ''}
+  beforeEach(() => {
+    TestBed.resetTestingModule();
+    document.body.replaceChildren();
+    ${effect ? 'disposeBridge = installCraftEffectBridge();' : ''}
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ title: 'Hello from the API', body: 'Typed transport works.' }), {
+        headers: { 'content-type': 'application/json' },
+      }),
+    ));
+  });
+
+  afterEach(() => {
+    ${effect ? 'disposeBridge();' : ''}
+    vi.unstubAllGlobals();
+    TestBed.resetTestingModule();
+  });
+
+  it('renders the API result', async () => {
+    const host = document.createElement('div');
+    document.body.append(host);
+    const injector = ${effect ? 'TestBed.rootInjector.createChild([provideLayer(WelcomeRepositoryLive)])' : 'TestBed.rootInjector'};
+    const mounted = mountCraftComponent(HomePage, host, injector as unknown as Injector);
+    TestBed.tick();
+    await vi.waitFor(() => expect(host.textContent).toContain('Hello from the API'));
+    mounted.destroy();
+  });
+});
+`;
+}
+
+const e2eTestTs = `import { expect, test } from '@playwright/test';
+
+test.beforeEach(async ({ page }) => {
+  await page.route('**/api/welcome', async (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ title: 'Hello from the API', body: 'E2E transport works.' }),
+    }),
+  );
+});
+
+test('loads the API page and navigates to About', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.getByRole('heading', { name: /Welcome to CraftTS/ })).toBeVisible();
+  await expect(page.getByText('Hello from the API')).toBeVisible();
+  await page.getByRole('link', { name: 'About' }).click();
+  await expect(page.getByRole('heading', { name: 'About this starter' })).toBeVisible();
+});
+`;
+
+const playwrightConfig = `import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  use: { baseURL: 'http://127.0.0.1:4173', ...devices['Desktop Chrome'] },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://127.0.0.1:4173',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+`;
+
+function readme(context: TemplateContext): string {
+  const effect = context.mode === 'effect';
+  return `# ${context.projectName}\n\nA framework-independent CraftTS starter generated by craft create.\n\nThis project includes:\n\n- a routed Craft component page;\n- a typed CraftHttpClient API boundary${effect ? ' behind an Effect v4 repository service and Layer' : ''};\n- flat-config ESLint with Craft rules;\n- unit tests, graph-wide architecture tests and a Playwright E2E flow.\n\n## Start\n\nnpm install\nnpm run dev\n\n## Verify\n\nnpm run lint\nnpm run typecheck\nnpm run typecheck-spec\n${effect ? 'npm run effect-check\n' : ''}npm test\nnpm run architecture\nnpm run e2e\nnpm run build\n\n### Architecture tests\n\narchitecture/ is the dependency-graph contract. It runs without booting the\nbrowser and catches duplicate HTTP ownership, dependency cycles, declarative\ngraph violations, unnamed interactive elements and missing route DI proofs.\nRun it after structural changes. Add a rule only for a recurring product\ninvariant that the baseline helpers do not cover; do not add one test per\nfeature.\n\nThe generated catalog is refreshed by architecture/load-graph.ts; do not edit\narchitecture/catalog.ts by hand.\n`;
+}
+
+function agentFiles(
+  mode: CreateMode,
+  agent: CreateAgent,
+): Record<string, string> {
+  const skill = `${BASE_AGENT_SKILL}${mode === 'effect' ? `\n${EFFECT_AGENT_SKILL}` : ''}`;
+  if (agent === 'codex') {
+    return {
+      'AGENTS.md': AGENTS_MD(mode),
+      '.agents/skills/craft-ts-project/SKILL.md': skill,
+      ...(mode === 'effect'
+        ? { '.agents/skills/craft-ts-effect-v4/SKILL.md': EFFECT_AGENT_SKILL }
+        : {}),
+    };
+  }
+  if (agent === 'cursor') {
+    return {
+      '.cursor/skills/craft-ts-project/SKILL.md': skill,
+      '.cursor/rules/craft-ts.mdc': `---\ndescription: CraftTS project rules\nglobs: **/*.ts\nalwaysApply: true\n---\n\nRead .cursor/skills/craft-ts-project/SKILL.md before editing CraftTS code.\n`,
+    };
+  }
+  if (agent === 'claude-code') {
+    return {
+      'CLAUDE.md': AGENTS_MD(mode),
+      '.claude/skills/craft-ts-project/SKILL.md': skill,
+      ...(mode === 'effect'
+        ? { '.claude/skills/craft-ts-effect-v4/SKILL.md': EFFECT_AGENT_SKILL }
+        : {}),
+    };
+  }
+  return {
+    'GEMINI.md': AGENTS_MD(mode),
+    '.gemini/skills/craft-ts-project/SKILL.md': skill,
+    ...(mode === 'effect'
+      ? { '.gemini/skills/craft-ts-effect-v4/SKILL.md': EFFECT_AGENT_SKILL }
+      : {}),
+  };
+}
+
+function templates(context: TemplateContext): Record<string, string> {
+  const effect = context.mode === 'effect';
+  return {
+    'package.json': packageJson(context),
+    'tsconfig.json': tsconfig(context),
+    'tsconfig.app.json': tsconfigApp,
+    'tsconfig.spec.json': tsconfigSpec,
+    ...(effect ? { 'tsconfig.effect.json': tsconfigEffect } : {}),
+    ...(effect ? { 'scripts/run-effect-tsgo.mjs': effectTsgoRunner } : {}),
+    'vite.config.ts': viteConfig,
+    'vitest.config.ts': vitestConfig,
+    'eslint.config.mjs': eslintConfig,
+    'playwright.config.ts': playwrightConfig,
+    'index.html': indexHtml,
+    'README.md': readme(context),
+    'src/main.ts': mainTs,
+    'src/styles.css': styles,
+    'src/types.d.ts': '/// <reference types="vite/client" />\n',
+    'src/app/app.ts': appTs,
+    'src/app/app.config.ts': effect ? effectAppConfig : plainAppConfig,
+    'src/app/app.routes.ts': routesTs,
+    ...(effect ? { 'src/app/api.ts': "export { loadWelcome } from './domain';\nexport type { WelcomeResponse } from './domain';\n" } : { 'src/app/api.ts': apiTs }),
+    ...(effect ? { 'src/app/domain.ts': effectDomainTs, 'src/app/home-page.ts': effectHomePageTs } : { 'src/app/home-page.ts': plainHomePageTs }),
+    'src/app/about-page.ts': aboutPageTs,
+    'src/app/home-page.spec.ts': unitTestTs(context),
+    'e2e/starter.spec.ts': e2eTestTs,
+  };
+}
+
+function normaliseAgent(agent: string): CreateAgent {
+  const value = agent.trim().toLowerCase();
+  if (value === 'codex') return 'codex';
+  if (value === 'cursor') return 'cursor';
+  if (value === 'claude' || value === 'claude-code') return 'claude-code';
+  if (value === 'cloud-code' || value === 'cloudcode' || value === 'gemini') return 'cloud-code';
+  throw new Error(`Unknown agent "${agent}". Use codex, cursor, claude-code, or cloud-code.`);
+}
+
+export function parseCreateAgents(value: string | undefined): readonly CreateAgent[] {
+  if (!value) return DEFAULT_AGENTS;
+  if (value.trim() === '' || value.trim().toLowerCase() === 'none') return [];
+  return [...new Set(value.split(',').map(normaliseAgent))];
+}
+
+export async function createCraftProject(
+  options: CreateProjectOptions,
+): Promise<CreateProjectResult> {
+  const rootDir = resolve(options.rootDir ?? process.cwd());
+  const directory = resolve(rootDir, options.directory);
+  const projectName = directory
+    .split(/[\\/]/)
+    .at(-1)
+    ?.replace(/[^a-zA-Z0-9._-]/g, '-') || 'craft-app';
+  const mode = options.mode ?? 'plain';
+  const agents = options.agents ?? DEFAULT_AGENTS;
+
+  if (existsSync(directory) && !options.force && (await readdir(directory)).length > 0) {
+    throw new Error(`Refusing to create in non-empty directory: ${directory}. Use --force to merge.`);
+  }
+
+  const files = {
+    ...templates({ projectName, mode }),
+    ...agents.reduce<Record<string, string>>(
+      (all, agent) => Object.assign(all, agentFiles(mode, agent)),
+      {},
+    ),
+  };
+  await Promise.all(
+    Object.entries(files).map(async ([file, contents]) => {
+      const target = join(directory, file);
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, contents, 'utf8');
+    }),
+  );
+
+  // Reuse the same deterministic scaffold as migration, but with a standalone
+  // project root. It also adds architecture/typecheck scripts to package.json.
+  await runArchitectureMigration({
+    rootDir: join(directory, 'src'),
+    tsConfigFilePath: join(directory, 'tsconfig.app.json'),
+    write: true,
+  });
+
+  return {
+    directory,
+    mode,
+    agents,
+    changedFiles: Object.keys(files).map((file) => relative(directory, join(directory, file))),
+  };
+}
+
+export function createModeFromFlag(value: string | undefined): CreateMode | undefined {
+  if (!value) return undefined;
+  if (value === 'v4' || value === 'effect' || value === 'true') return 'effect';
+  if (value === 'none' || value === 'plain' || value === 'false') return 'plain';
+  throw new Error(`Unknown --effect value "${value}". Use v4 or none.`);
+}