create-packkit 2.8.0 → 3.0.0

package/README.md

@@ -193,14 +193,32 @@ There's also an [`llms.txt`](llms.txt) (served at [danmat.github.io/create-packk
 { "mcpServers": { "packkit": { "command": "npx", "args": ["-y", "packkit-mcp"] } } }
 ```
 
+## Embed Packkit in your own app
+
+Packkit ships a typed, side-effect-free API so a Node application can use it as a
+project-generation engine — generate in memory, add your own deployment files,
+and write to disk when you're ready. No prompts, installs, git, or network.
+
+```js
+import { createProject, extendProject, writeGeneratedProject } from 'create-packkit/embedded';
+
+const project = createProject({ preset: 'react-app', name: 'weather-dashboard' });
+const extended = extendProject(project, { files: { '.github/workflows/deploy.yml': deployYaml } });
+await writeGeneratedProject({ project: extended, destination: '/tmp/weather-dashboard' });
+```
+
+Full guide, including diagnostics, reproducible definitions, digests, and the
+provider-neutral deployment contract: **[Embedding Packkit](docs/EMBEDDING.md)**.
+
 ## How it works
 
 Packkit is a pure `config → { files }` **core** that runs in both Node and the browser:
 
 - the **CLI** writes the files to disk, runs `git init`, and installs dependencies;
-- the **web configurator** zips the same files client-side (no server).
+- the **web configurator** zips the same files client-side (no server);
+- the **embedded API** ([`create-packkit/embedded`](docs/EMBEDDING.md)) hands the file map to a host application.
 
-Both drive from one options schema ([`src/core/options.js`](src/core/options.js)), so the CLI and the web page always stay in sync.
+All three drive from one options schema ([`src/core/options.js`](src/core/options.js)), so they always stay in sync.
 
 ## Staying fresh
 

package/package.json

@@ -1,20 +1,34 @@
 {
   "name": "create-packkit",
-  "version": "2.8.0",
+  "version": "3.0.0",
   "description": "Highly configurable scaffolder for modern npm packages and CLIs — pick your stack (TS/JS, bundler, tests, linter, CI, releases) from a CLI or a web configurator.",
   "type": "module",
   "bin": {
     "create-packkit": "bin/cli.js"
   },
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/core/index.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
     "./core": "./src/core/index.js",
+    "./embedded": {
+      "types": "./types/embedded.d.ts",
+      "default": "./src/embedded/index.js"
+    },
+    "./writer": {
+      "types": "./types/writer.d.ts",
+      "default": "./src/embedded/writer.js"
+    },
     "./cli": "./src/cli/index.js",
-    "./scaffold": "./src/cli/write.js"
+    "./scaffold": "./src/cli/write.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "bin",
     "src",
+    "types",
     "README.md",
     "LICENSE",
     "llms.txt"

package/src/cli/args.js

@@ -20,6 +20,7 @@ const OVERRIDE_FLAGS = {
   description: 'description',
   keywords: 'keywords',
   repo: 'repo',
+  'monorepo-layout': 'monorepoLayout',
 };
 
 // Boolean options that default ON — a --no-<flag> turns them off.

package/src/cli/index.js

@@ -41,7 +41,7 @@ defaults in one shot. Every option is documented (with why-you'd-use-it) at:
 
 Presets:
   ${PRESET_NAMES.join('  ')}
-  shortcuts: lib jslib rlib rapp vlib vapp slib sapp svc
+  shortcuts: lib jslib rlib rapp vlib vapp slib sapp svc fs
 
 Getting started:
   --preset <name>      Start from a preset (skips the wizard)
@@ -66,6 +66,7 @@ Stack:
   --server <hono|fastify|express>         HTTP service framework
   --pm <npm|pnpm|yarn|bun>
   --monorepo                              pnpm + Turborepo workspace
+  --monorepo-layout <libraries|fullstack> Linked packages, or web+server+shared
 
 Build & test:
   --bundler <tsup|tsdown|unbuild|rollup|none>
@@ -103,6 +104,7 @@ Examples:
   npx packkit ts-lib my-lib -y
   npx packkit react-app my-app --e2e
   npx packkit node-service api --server fastify --env
+  npx packkit fullstack acme --github        # web + API + shared, repo created
   npm create packkit@latest my-pkg -- --preset oss --pm pnpm
 `;
 
@@ -135,6 +137,9 @@ export async function run(argv = process.argv.slice(2)) {
 
   config.gitInit = args.git;
   config.install = args.install;
+  // Core is version-agnostic (it also runs in the browser), so the surface
+  // that knows the version supplies it for packkit.json.
+  config.generatorVersion = pkgVersion();
 
   // Node preflight: the generated project's tools (eslint, vite, vitest) hard-
   // require this floor. npm only *warns* on engines, so catch it here — clearly,
@@ -247,6 +252,11 @@ export async function run(argv = process.argv.slice(2)) {
     skipped.length
       ? `Kept ${skipped.length} existing file${skipped.length > 1 ? 's' : ''} — Packkit's version was not written: ${skipped.join(', ')}`
       : null,
+    // Said here too, not just in the README: this is the moment a red X appears
+    // on a repo that is ten seconds old, and the cause is not obvious.
+    pushedTo && config.workflows?.includes('npm-publish') && config.release === 'changesets'
+      ? `The Release workflow will fail until npm credentials exist — set up npm Trusted Publishing, or add an NPM_TOKEN secret. See "Releasing" in the README.`
+      : null,
   ].filter(Boolean);
 
   const done =

package/src/core/features/meta.js

@@ -144,6 +144,31 @@ function readme(cfg) {
     lines.push('## CLI', '', '```sh', `npx ${cfg.name} --help`, '```', '');
   }
 
+  // Publishing needs a credential the repo doesn't have yet. The changesets
+  // workflow runs on every push, so without this note the first thing a new
+  // repo does is fail a job for a reason that's only explained in a YAML
+  // comment. Say it where someone will actually read it.
+  if (cfg.workflows?.includes('npm-publish')) {
+    const changesets = cfg.release === 'changesets';
+    lines.push(
+      '## Releasing',
+      '',
+      changesets
+        ? 'Releases are handled by the `Release` workflow: push a changeset (`npx changeset`) and it opens a version PR, then publishes when that PR merges.'
+        : 'Pushing a `v*` tag triggers the `Publish` workflow, which publishes to npm with provenance.',
+      '',
+      '**Publishing needs npm credentials, which a new repository does not have.** Either:',
+      '',
+      '- Set up [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) — no secret to store or rotate, and the recommended option; or',
+      '- Add an [npm automation token](https://docs.npmjs.com/creating-and-viewing-access-tokens) as an `NPM_TOKEN` repository secret.',
+      '',
+      changesets
+        ? 'Until one of those is in place the `Release` workflow will fail with `ENEEDAUTH` on every push. That is expected on a brand-new repo.'
+        : 'Until one of those is in place, tag pushes will fail with `ENEEDAUTH`.',
+      '',
+    );
+  }
+
   lines.push('## License', '', cfg.license === 'none' ? 'Unlicensed.' : `${cfg.license}${cfg.author ? ' © ' + cfg.author : ''}`, '');
   return lines.join('\n');
 }

package/src/core/index.js

@@ -7,6 +7,7 @@ import { deepMerge, toJson } from './render.js';
 import { finalizePackageJson } from './pkg.js';
 import features from './features/index.js';
 import { buildMonorepo } from './monorepo.js';
+import { provenance } from './provenance.js';
 import { PRESETS, PRESET_NAMES, PRESET_INFO, PRESET_ALIASES, resolvePreset } from './presets.js';
 
 export { OPTIONS, GROUPS, OPTION_HELP, defaultConfig, normalizeConfig, PRESETS, PRESET_NAMES, PRESET_INFO, PRESET_ALIASES, resolvePreset };
@@ -15,36 +16,74 @@ export { OPTIONS, GROUPS, OPTION_HELP, defaultConfig, normalizeConfig, PRESETS,
 export function fromPreset(name, overrides = {}) {
   const canonical = resolvePreset(name);
   if (!canonical) throw new Error(`Unknown preset "${name}". Known: ${PRESET_NAMES.join(', ')}`);
-  return normalizeConfig({ ...PRESETS[canonical], ...overrides });
+  const cfg = normalizeConfig({ ...PRESETS[canonical], ...overrides });
+  // Recorded in packkit.json so a project knows which preset it came from.
+  cfg.preset = canonical;
+  return cfg;
 }
 
-/** Turn a config into a complete set of files. */
-export function generate(input) {
-  const cfg = normalizeConfig(input);
-  if (cfg.monorepo) return buildMonorepo(cfg);
-
+/**
+ * Run every active feature, collecting its files and package.json fragment.
+ * Returns the raw material — file map, the fragments in contribution order,
+ * and which feature produced each file — so callers that need provenance (the
+ * embedded API's collision detection) get it without a second pass, while
+ * `generate` folds it into the same output as before.
+ */
+export function assemble(cfg) {
   const files = {};
+  const fileSources = {};
+  const fragments = [];
   let pkg = {};
 
   for (const feat of features) {
     if (!feat.active(cfg)) continue;
     const out = feat.apply(cfg) || {};
     if (out.files) {
-      for (const [path, contents] of Object.entries(out.files)) files[path] = contents;
+      for (const [path, contents] of Object.entries(out.files)) {
+        (fileSources[path] ||= []).push(feat.id);
+        files[path] = contents;
+      }
+    }
+    if (out.pkg) {
+      fragments.push({ source: feat.id, pkg: out.pkg });
+      pkg = deepMerge(pkg, out.pkg);
     }
-    if (out.pkg) pkg = deepMerge(pkg, out.pkg);
   }
+  return { files, fileSources, fragments, pkg };
+}
 
+/**
+ * Generate, keeping the provenance assemble() produced. One assembly pass feeds
+ * both the public files and the embedded API's conflict diagnostics, so the
+ * bytes callers get and the provenance they inspect come from the same run.
+ */
+export function generateTracked(input, diagnostics = null) {
+  const cfg = normalizeConfig(input, diagnostics);
+  if (cfg.monorepo) {
+    // The monorepo generator is a separate path with no per-feature fragments.
+    return { ...buildMonorepo(cfg), fileSources: {}, fragments: [] };
+  }
+
+  const { files, fileSources, fragments, pkg } = assemble(cfg);
   files['package.json'] = toJson(finalizePackageJson(pkg));
+  files['packkit.json'] = provenance(cfg);
 
   return {
     config: cfg,
     files,
     postCommands: postCommands(cfg),
     summary: summarize(cfg, files),
+    fileSources,
+    fragments,
   };
 }
 
+/** Turn a config into a complete set of files. */
+export function generate(input) {
+  const { config, files, postCommands, summary } = generateTracked(input);
+  return { config, files, postCommands, summary };
+}
+
 function postCommands(cfg) {
   const install = {
     npm: 'npm install',

package/src/core/monorepo.js

@@ -6,8 +6,15 @@ import { toJson } from './render.js';
 import community from './features/community.js';
 import agents from './features/agents.js';
 import gitfiles from './features/gitfiles.js';
+import { provenance } from './provenance.js';
 
 export function buildMonorepo(cfg) {
+  // Two genuinely different shapes: a set of publishable libraries, or a
+  // deployable app (web + server + shared code). They differ in workspace
+  // globs, whether anything publishes, and what `dev` means, so they don't
+  // usefully share a code path.
+  if (cfg.monorepoLayout === 'fullstack') return buildFullstack(cfg);
+
   const files = {};
   const pm = cfg.packageManager;
   const scope = cfg.name.replace(/^@/, '').split('/')[0];
@@ -104,6 +111,7 @@ export function buildMonorepo(cfg) {
   files['.prettierrc.json'] = toJson({ useTabs: true, singleQuote: true, semi: true, printWidth: 100, trailingComma: 'all' });
 
   files['README.md'] = rootReadme(cfg, pm, core, utils);
+  files['packkit.json'] = provenance(cfg);
   files['.github/workflows/ci.yml'] = ciWorkflow(cfg, pm);
 
   // ---- packages ----
@@ -151,6 +159,362 @@ export function buildMonorepo(cfg) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Full-stack layout: apps/web + apps/server + packages/shared.
+//
+// The pieces already existed as standalone presets (react-app, node-service);
+// what was missing was the composition — workspace wiring, one shared package
+// both sides import, and a production story where the server serves the built
+// web assets instead of needing a second host.
+// ---------------------------------------------------------------------------
+function buildFullstack(cfg) {
+  const files = {};
+  const pm = cfg.packageManager;
+  const scope = cfg.name.replace(/^@/, '').split('/')[0];
+  const shared = `@${scope}/shared`;
+  const wsProto = pm === 'pnpm' ? 'workspace:*' : '*';
+  const run = (s) => (pm === 'npm' ? `npm run ${s}` : `${pm} ${s}`);
+
+  for (const feat of [community, agents, gitfiles]) {
+    if (feat.active(cfg)) Object.assign(files, feat.apply(cfg).files);
+  }
+
+  files['package.json'] = toJson({
+    name: cfg.name,
+    version: '0.0.0',
+    private: true,
+    type: 'module',
+    ...(cfg.license !== 'none' ? { license: cfg.license } : {}),
+    ...(pm === 'pnpm'
+      ? { packageManager: 'pnpm@9.10.0' }
+      : { workspaces: ['apps/*', 'packages/*'] }),
+    scripts: {
+      dev: 'turbo dev',
+      build: 'turbo build',
+      // Production runs the built server, which also serves the web build.
+      start: `${pm === 'npm' ? 'npm --prefix apps/server run' : `${pm} --filter ./apps/server`} start`,
+      test: 'turbo test',
+      lint: 'turbo lint',
+      typecheck: 'turbo typecheck',
+    },
+    devDependencies: {
+      turbo: '^2.0.0',
+      typescript: '^5.9.3',
+      vitest: '^4.0.0',
+      eslint: '^10.0.0',
+      '@eslint/js': '^10.0.0',
+      'typescript-eslint': '^8.0.0',
+      prettier: '^3.3.0',
+      '@types/node': `^${cfg.nodeVersion}.0.0`,
+    },
+  });
+
+  if (pm === 'pnpm') {
+    files['pnpm-workspace.yaml'] = 'packages:\n  - "apps/*"\n  - "packages/*"\n';
+  }
+
+  files['turbo.json'] = toJson({
+    $schema: 'https://turbo.build/schema.json',
+    tasks: {
+      build: { dependsOn: ['^build'], outputs: ['dist/**'] },
+      // Shared is built before the apps start, so both sides always import a
+      // current copy without a separate watch process.
+      dev: { dependsOn: ['^build'], cache: false, persistent: true },
+      test: { dependsOn: ['^build'] },
+      typecheck: { dependsOn: ['^build'] },
+      lint: {},
+    },
+  });
+
+  files['tsconfig.base.json'] = toJson({
+    $schema: 'https://json.schemastore.org/tsconfig',
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'ESNext',
+      moduleResolution: 'Bundler',
+      lib: ['ES2022', 'DOM'],
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      declaration: true,
+      noEmit: true,
+    },
+  });
+
+  files['eslint.config.js'] = [
+    `import js from '@eslint/js';`,
+    `import tseslint from 'typescript-eslint';`,
+    ``,
+    `export default tseslint.config(`,
+    `\tjs.configs.recommended,`,
+    `\t...tseslint.configs.recommended,`,
+    `\t{ ignores: ['**/dist'] },`,
+    `);`,
+    ``,
+  ].join('\n');
+  files['.prettierrc.json'] = toJson({ useTabs: true, singleQuote: true, semi: true, printWidth: 100, trailingComma: 'all' });
+  files['.github/workflows/ci.yml'] = ciWorkflow(cfg, pm);
+  files['README.md'] = fullstackReadme(cfg, pm, shared);
+  files['packkit.json'] = provenance(cfg);
+
+  // ---- packages/shared: the contract both sides compile against ----
+  files['packages/shared/package.json'] = toJson({
+    name: shared,
+    version: '0.0.0',
+    private: true,
+    type: 'module',
+    main: './dist/index.js',
+    types: './dist/index.d.ts',
+    exports: { '.': { types: './dist/index.d.ts', default: './dist/index.js' } },
+    scripts: {
+      build: 'tsup src/index.ts --format esm --dts --clean',
+      test: 'vitest run',
+      typecheck: 'tsc --noEmit',
+      lint: 'eslint .',
+    },
+    devDependencies: { tsup: '^8.0.0' },
+  });
+  files['packages/shared/tsconfig.json'] = toJson({ extends: '../../tsconfig.base.json', include: ['src'] });
+  files['packages/shared/src/index.ts'] = [
+    `/** The shape the server returns and the web app renders. Change it once. */`,
+    `export interface Health {`,
+    `\tok: boolean;`,
+    `\tservice: string;`,
+    `\tuptime: number;`,
+    `}`,
+    ``,
+    `export function describeHealth(h: Health): string {`,
+    `\treturn h.ok ? \`\${h.service} is up (\${Math.round(h.uptime)}s)\` : \`\${h.service} is down\`;`,
+    `}`,
+    ``,
+  ].join('\n');
+  files['packages/shared/src/index.test.ts'] = exampleTest(
+    `import { describeHealth } from './index.js';`,
+    `expect(describeHealth({ ok: true, service: 'api', uptime: 12 })).toBe('api is up (12s)')`,
+  );
+
+  // ---- apps/server ----
+  files['apps/server/package.json'] = toJson({
+    name: `@${scope}/server`,
+    version: '0.0.0',
+    private: true,
+    type: 'module',
+    scripts: {
+      dev: 'tsx watch src/index.ts',
+      build: 'tsup src/index.ts --format esm --clean',
+      start: 'node dist/index.js',
+      test: 'vitest run',
+      typecheck: 'tsc --noEmit',
+      lint: 'eslint .',
+    },
+    dependencies: { hono: '^4.5.0', '@hono/node-server': '^2.0.0', [shared]: wsProto },
+    devDependencies: { tsx: '^4.0.0', tsup: '^8.0.0' },
+  });
+  files['apps/server/tsconfig.json'] = toJson({ extends: '../../tsconfig.base.json', include: ['src'] });
+  files['apps/server/src/app.ts'] = [
+    `import { Hono } from 'hono';`,
+    `import { serveStatic } from '@hono/node-server/serve-static';`,
+    `import type { Health } from '${shared}';`,
+    ``,
+    `export const app = new Hono();`,
+    ``,
+    `app.get('/api/health', (c) => {`,
+    `\tconst body: Health = { ok: true, service: '${cfg.name}', uptime: process.uptime() };`,
+    `\treturn c.json(body);`,
+    `});`,
+    ``,
+    `// In production the API also serves the built web app, so one process and`,
+    `// one port covers the whole thing. In dev, Vite serves the app and proxies`,
+    `// /api here instead (see apps/web/vite.config.ts).`,
+    `if (process.env.NODE_ENV === 'production') {`,
+    `\tapp.use('/*', serveStatic({ root: '../web/dist' }));`,
+    `}`,
+    ``,
+  ].join('\n');
+  files['apps/server/src/index.ts'] = [
+    `import { serve } from '@hono/node-server';`,
+    `import { app } from './app.js';`,
+    ``,
+    `const port = Number(process.env.PORT ?? 3000);`,
+    `serve({ fetch: app.fetch, port });`,
+    `console.log(\`Listening on http://localhost:\${port}\`);`,
+    ``,
+  ].join('\n');
+  files['apps/server/src/app.test.ts'] = [
+    `import { describe, it, expect } from 'vitest';`,
+    `import { app } from './app.js';`,
+    ``,
+    `describe('api', () => {`,
+    `\tit('reports health', async () => {`,
+    `\t\tconst res = await app.request('/api/health');`,
+    `\t\texpect(res.status).toBe(200);`,
+    `\t\texpect(await res.json()).toMatchObject({ ok: true });`,
+    `\t});`,
+    `});`,
+    ``,
+  ].join('\n');
+
+  // ---- apps/web ----
+  files['apps/web/package.json'] = toJson({
+    name: `@${scope}/web`,
+    version: '0.0.0',
+    private: true,
+    type: 'module',
+    scripts: {
+      dev: 'vite',
+      build: 'vite build',
+      preview: 'vite preview',
+      test: 'vitest run',
+      typecheck: 'tsc --noEmit',
+      lint: 'eslint .',
+    },
+    dependencies: { react: '^19.0.0', 'react-dom': '^19.0.0', [shared]: wsProto },
+    devDependencies: {
+      vite: '^8.0.0',
+      '@vitejs/plugin-react': '^6.0.0',
+      // Without the React types, `turbo typecheck` fails on the very first run
+      // with TS7016/TS7026 on every JSX element.
+      '@types/react': '^19.0.0',
+      '@types/react-dom': '^19.0.0',
+      '@testing-library/react': '^16.0.0',
+      '@testing-library/dom': '^10.0.0',
+      jsdom: '^29.0.0',
+    },
+  });
+  files['apps/web/tsconfig.json'] = toJson({
+    extends: '../../tsconfig.base.json',
+    compilerOptions: { jsx: 'react-jsx' },
+    include: ['src'],
+  });
+  files['apps/web/vite.config.ts'] = [
+    `/// <reference types="vitest" />`,
+    `import { defineConfig } from 'vite';`,
+    `import react from '@vitejs/plugin-react';`,
+    ``,
+    `export default defineConfig({`,
+    `\tplugins: [react()],`,
+    `\t// Same-origin /api in dev as in production, so no CORS and no base URL`,
+    `\t// juggling between environments.`,
+    `\tserver: { proxy: { '/api': 'http://localhost:3000' } },`,
+    `\ttest: { environment: 'jsdom' },`,
+    `});`,
+    ``,
+  ].join('\n');
+  files['apps/web/src/App.test.tsx'] = [
+    `import { describe, it, expect } from 'vitest';`,
+    `import { render, screen } from '@testing-library/react';`,
+    `import { App } from './App.js';`,
+    ``,
+    `describe('App', () => {`,
+    `\tit('renders the service name', () => {`,
+    `\t\trender(<App />);`,
+    `\t\texpect(screen.getByRole('heading', { name: '${cfg.name}' })).toBeDefined();`,
+    `\t});`,
+    `});`,
+    ``,
+  ].join('\n');
+  files['apps/web/index.html'] = [
+    `<!doctype html>`,
+    `<html lang="en">`,
+    `\t<head>`,
+    `\t\t<meta charset="UTF-8" />`,
+    `\t\t<meta name="viewport" content="width=device-width, initial-scale=1.0" />`,
+    `\t\t<title>${cfg.name}</title>`,
+    `\t</head>`,
+    `\t<body>`,
+    `\t\t<div id="root"></div>`,
+    `\t\t<script type="module" src="/src/main.tsx"></script>`,
+    `\t</body>`,
+    `</html>`,
+    ``,
+  ].join('\n');
+  files['apps/web/src/main.tsx'] = [
+    `import { StrictMode } from 'react';`,
+    `import { createRoot } from 'react-dom/client';`,
+    `import { App } from './App.js';`,
+    ``,
+    `createRoot(document.getElementById('root')!).render(`,
+    `\t<StrictMode>`,
+    `\t\t<App />`,
+    `\t</StrictMode>,`,
+    `);`,
+    ``,
+  ].join('\n');
+  files['apps/web/src/App.tsx'] = [
+    `import { useEffect, useState } from 'react';`,
+    `import { describeHealth, type Health } from '${shared}';`,
+    ``,
+    `export function App() {`,
+    `\tconst [health, setHealth] = useState<Health | null>(null);`,
+    ``,
+    `\tuseEffect(() => {`,
+    `\t\tfetch('/api/health')`,
+    `\t\t\t.then((r) => r.json() as Promise<Health>)`,
+    `\t\t\t.then(setHealth)`,
+    `\t\t\t.catch(() => setHealth({ ok: false, service: '${cfg.name}', uptime: 0 }));`,
+    `\t}, []);`,
+    ``,
+    `\treturn (`,
+    `\t\t<main>`,
+    `\t\t\t<h1>${cfg.name}</h1>`,
+    `\t\t\t<p>{health ? describeHealth(health) : 'Checking…'}</p>`,
+    `\t\t</main>`,
+    `\t);`,
+    `}`,
+    ``,
+  ].join('\n');
+
+  return {
+    config: cfg,
+    files,
+    postCommands: cfg.gitInit ? ['git init', 'git add -A', 'git commit -m "Initial commit from Packkit"'] : [],
+    summary: {
+      name: cfg.name,
+      fileCount: Object.keys(files).length,
+      stack: ['monorepo', 'full-stack', `${pm}+turbo`, 'React+Vite', 'Hono', 'TypeScript', 'vitest'],
+      workflows: ['ci'],
+    },
+  };
+}
+
+function fullstackReadme(cfg, pm, shared) {
+  const install = pm === 'npm' ? 'npm install' : `${pm} install`;
+  const run = (s) => (pm === 'npm' ? `npm run ${s}` : `${pm} ${s}`);
+  return [
+    `# ${cfg.name}`,
+    '',
+    cfg.description || '_A full-stack monorepo scaffolded with [Packkit](https://danmat.github.io/create-packkit/)._',
+    '',
+    '## Layout',
+    '',
+    '```',
+    'apps/web       React + Vite front end',
+    'apps/server    Hono API (also serves the web build in production)',
+    'packages/shared  types and helpers both sides import',
+    '```',
+    '',
+    '## Develop',
+    '',
+    '```sh',
+    install,
+    run('dev') + '     # web on :5173, api on :3000',
+    '```',
+    '',
+    `Vite proxies \`/api\` to the server, so requests are same-origin in development exactly as they are in production — no CORS, no environment-specific base URL.`,
+    '',
+    '## Production',
+    '',
+    '```sh',
+    run('build'),
+    run('start') + '   # one process serving the API and the built web app',
+    '```',
+    '',
+    `\`${shared}\` is built before either app starts, so a change to a shared type surfaces as a type error on both sides rather than at runtime.`,
+    '',
+    cfg.license !== 'none' ? `## License\n\n${cfg.license}${cfg.author ? ' © ' + cfg.author : ''}\n` : '',
+  ].join('\n');
+}
+
 function addPackage(files, { name, dir, src, test, deps }) {
   const pkg = {
     name,