create-packkit 2.7.2 → 2.9.0

package/README.md

@@ -31,6 +31,36 @@ npx create-packkit --preset full my-pkg --pm pnpm
 
 Then `cd`, and you already have a working project — `build`, `test`, and `lint` all pass out of the box.
 
+## Create the repo, not just the folder
+
+Packkit can create the remote and push the first commit, so you don't have to make an empty repo in a browser first:
+
+```sh
+# create it on GitHub (private) and push
+npx create-packkit ts-lib my-lib --github
+
+# public instead
+npx create-packkit ts-lib my-lib --github --public
+
+# any other host — GitLab, Bitbucket, Gitea, self-hosted
+npx create-packkit ts-lib my-lib --git-remote git@bitbucket.org:me/my-lib.git
+```
+
+`--github` shells out to the [GitHub CLI](https://cli.github.com), so **Packkit never asks for, reads, or stores a token** — `gh` already holds your credentials. Created repos are **private unless you pass `--public`**.
+
+This also fixes your links: the repository URL is baked into `package.json` and the README's CI badges when the files are generated, so letting Packkit resolve it up front means the badges point somewhere real from the first commit.
+
+### Scaffolding into a repo you already have
+
+Already cloned an empty repo, or started some work? `--merge` scaffolds around what's there:
+
+```sh
+git clone git@github.com:me/my-lib.git && cd my-lib
+npx create-packkit ts-lib my-lib --here --merge
+```
+
+**Existing files are never overwritten.** Anything that collides is left alone and reported, so you can diff at your leisure. (A directory containing only `.git` counts as empty — a fresh clone scaffolds without needing `--merge` at all.)
+
 ## Or configure it on the web
 
 No install needed: **[danmat.github.io/create-packkit](https://danmat.github.io/create-packkit/)** — tick the options, preview the file tree, and **download a zip** (or copy the equivalent `npx create-packkit` command). Everything runs in your browser.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-packkit",
-  "version": "2.7.2",
+  "version": "2.9.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": {
@@ -9,7 +9,8 @@
   "exports": {
     ".": "./src/core/index.js",
     "./core": "./src/core/index.js",
-    "./cli": "./src/cli/index.js"
+    "./cli": "./src/cli/index.js",
+    "./scaffold": "./src/cli/write.js"
   },
   "files": [
     "bin",
@@ -28,7 +29,8 @@
     "integration": "node scripts/integration.mjs",
     "build:web": "esbuild src/core/index.js --bundle --format=esm --outfile=docs/packkit-core.js",
     "update:node": "node scripts/update-node-versions.mjs",
-    "gen:reference": "node scripts/gen-reference.mjs"
+    "gen:reference": "node scripts/gen-reference.mjs",
+    "sync:mcp": "node scripts/sync-mcp-version.mjs"
   },
   "repository": {
     "type": "git",

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.
@@ -43,6 +44,10 @@ export function parseCliArgs(argv) {
       yes: { type: 'boolean', short: 'y' },
       recommended: { type: 'boolean' },
       here: { type: 'boolean' },
+      merge: { type: 'boolean' },
+      github: { type: 'boolean' },
+      'git-remote': { type: 'string' },
+      public: { type: 'boolean' },
       'no-install': { type: 'boolean' },
       'no-git': { type: 'boolean' },
       minify: { type: 'boolean' },
@@ -104,6 +109,12 @@ export function parseCliArgs(argv) {
     from: values.from,
     name,
     here: !!values.here,
+    merge: !!values.merge,
+    github: !!values.github,
+    gitRemote: values['git-remote'] || null,
+    // Publishing code outward is opt-in, and private is the safe default — a
+    // wrong guess here leaks source, so --public must be asked for explicitly.
+    private: !values.public,
     yes: !!values.yes || !!values.recommended,
     hasConfigFlags,
     install: !values['no-install'],

package/src/cli/index.js

@@ -6,7 +6,18 @@ import { generate, fromPreset, normalizeConfig, PRESET_NAMES, OPTIONS, OPTION_HE
 import { engineFloor, meetsNodeFloor } from '../core/node.js';
 import { parseCliArgs } from './args.js';
 import { runWizard } from './wizard.js';
-import { writeProject, dirIsEmptyOrMissing, gitInit, installDeps } from './write.js';
+import {
+  writeProject,
+  existingEntries,
+  gitInit,
+  installDeps,
+  hasCommand,
+  githubLogin,
+  createGithubRepo,
+  pushToRemote,
+  writeLockfile,
+  commitAll,
+} from './write.js';
 
 const pkgVersion = () => {
   try {
@@ -30,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)
@@ -38,9 +49,15 @@ Getting started:
   -y, --yes            Accept defaults / preset, no prompts (one-shot)
   --recommended        Alias for -y
   --here               Scaffold into the current directory
+  --merge              Scaffold into a non-empty directory (never overwrites)
   --no-install         Skip dependency install
   --no-git             Skip git init
 
+Create the repo:
+  --github             Create it on GitHub and push (uses the gh CLI)
+  --git-remote <url>   Push to an existing remote (GitLab, Bitbucket, self-hosted)
+  --public             Make the created repo public (default: private)
+
 Stack:
   --language <ts|js>
   --module <esm|cjs|dual>                 ESM-only is the default
@@ -49,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>
@@ -86,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
 `;
 
@@ -118,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,
@@ -144,14 +166,29 @@ export async function run(argv = process.argv.slice(2)) {
     console.error('A package name is required (pass one, or run interactively).');
     process.exit(1);
   }
-  if (!dirIsEmptyOrMissing(targetDir)) {
-    console.error(`Target directory "${basename(targetDir)}" is not empty. Aborting.`);
+  const occupied = existingEntries(targetDir);
+  if (occupied.length && !args.merge) {
+    const sample = occupied.slice(0, 4).join(', ') + (occupied.length > 4 ? ', …' : '');
+    console.error(
+      `Target directory "${basename(targetDir)}" is not empty (${sample}).\n` +
+        `Re-run with --merge to scaffold around what's there — existing files are never overwritten.`,
+    );
     process.exit(1);
   }
 
+  // Resolve the remote *before* generating: the repository URL is baked into
+  // package.json links and README badges at generate time, so creating the repo
+  // afterwards would ship a first commit pointing at nothing.
+  const remote = resolveRemote(args, config);
+  if (remote?.error) {
+    console.error(remote.error);
+    process.exit(1);
+  }
+  if (remote?.url && /^https?:/.test(remote.url)) config.repo = remote.url;
+
   // Generate + write.
   const { files, summary } = generate(config);
-  await writeProject(targetDir, files);
+  const { skipped } = await writeProject(targetDir, files, { merge: args.merge });
 
   // Post steps.
   if (config.gitInit) gitInit(targetDir);
@@ -162,6 +199,40 @@ export async function run(argv = process.argv.slice(2)) {
     s.stop(ok ? 'Dependencies installed' : 'Install skipped (run it manually)');
   }
 
+  // Create the remote last, so a failure here still leaves a complete local
+  // project behind — nothing to clean up, just a command to re-run.
+  let pushedTo = null;
+  if (remote) {
+    const s = p.spinner();
+    // A repo pushed without a lockfile fails CI immediately — actions/setup-node
+    // errors when its cache can't find one. Produce it without a full install.
+    if (!config.install) {
+      s.start('Writing a lockfile so CI passes on the first run');
+      const ok = writeLockfile(config.packageManager, targetDir);
+      s.stop(ok ? 'Lockfile written' : `No lockfile — run \`${config.packageManager} install\` and commit it, or CI will fail`);
+    }
+    commitAll(targetDir, 'Add lockfile');
+    s.start(remote.kind === 'github' ? `Creating ${remote.slug} on GitHub` : 'Pushing to origin');
+    const res =
+      remote.kind === 'github'
+        ? createGithubRepo({
+            slug: remote.slug,
+            description: config.description,
+            private: args.private,
+            cwd: targetDir,
+          })
+        : pushToRemote(remote.url, targetDir);
+    s.stop(res.ok ? `Pushed to ${remote.url}` : 'Could not create the remote');
+    if (res.ok) pushedTo = remote.url;
+    else {
+      const retry =
+        remote.kind === 'github'
+          ? `gh repo create ${remote.slug} --${args.private ? 'private' : 'public'} --source . --remote origin --push`
+          : `git remote add origin ${remote.url} && git push -u origin HEAD`;
+      console.error(`\n${res.error || 'The command failed.'}\n\nThe project is scaffolded. To retry:\n  cd ${basename(targetDir)} && ${retry}`);
+    }
+  }
+
   const rel = args.here ? '.' : config.name;
   const next = [
     args.here ? null : `cd ${rel}`,
@@ -178,9 +249,19 @@ export async function run(argv = process.argv.slice(2)) {
       ? `This is a ${config.framework} component library — \`${runWord(config)} dev\` rebuilds on change (there's no dev server). For a runnable app, scaffold the "${config.framework}-app" preset instead.`
       : null,
     `Requires Node >= ${floor}${nodeOk ? '' : ` — you're on ${process.version}, upgrade first`}.`,
+    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 = `Created ${summary.name} — ${summary.fileCount} files · ${summary.stack.join(' · ')}`;
+  const done =
+    `Created ${summary.name} — ${summary.fileCount - skipped.length} files · ${summary.stack.join(' · ')}` +
+    (pushedTo ? `\n${pushedTo}` : '');
   if (interactive) {
     p.note(next.join('\n') || 'You are all set.', 'Next steps');
     if (hints.length) p.log.info(hints.join('\n'));
@@ -199,6 +280,43 @@ function runWord(config) {
   return config.packageManager === 'npm' ? 'npm run' : config.packageManager;
 }
 
+// owner/name for the repo to create: an explicit --repo URL wins, otherwise the
+// authenticated gh account plus the project name.
+function githubSlug(repoUrl, login, name) {
+  const m = /github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/*$/.exec(repoUrl || '');
+  if (m) return `${m[1]}/${m[2]}`;
+  return login ? `${login}/${name}` : null;
+}
+
+/**
+ * Work out what remote to create, if any. Returns null (nothing to do),
+ * { error } to abort before writing anything, or the resolved target.
+ */
+function resolveRemote(args, config) {
+  if (!args.github && !args.gitRemote) return null;
+  if (!config.gitInit) {
+    return { error: 'Creating a repo needs a local git repo — drop --no-git.' };
+  }
+  if (args.gitRemote) return { kind: 'remote', url: args.gitRemote };
+
+  // Delegate to `gh` rather than calling the API: it already holds the user's
+  // credentials, so Packkit never reads, prompts for, or stores a token.
+  if (!hasCommand('gh')) {
+    return {
+      error:
+        '--github needs the GitHub CLI. Install it (https://cli.github.com), or use\n' +
+        '--git-remote <url> to push to a repo you have already created.',
+    };
+  }
+  const login = githubLogin();
+  if (!login) {
+    return { error: '--github needs an authenticated GitHub CLI. Run: gh auth login' };
+  }
+  const slug = githubSlug(config.repo, login, config.name);
+  if (!slug) return { error: 'Could not work out the repository name. Pass --repo <url>.' };
+  return { kind: 'github', slug, url: `https://github.com/${slug}` };
+}
+
 // Load a partial config from --from <file>, or a packkit.config.json in cwd.
 function loadProfile(args) {
   const path = args.from || (existsSync('packkit.config.json') ? 'packkit.config.json' : null);

package/src/cli/write.js

@@ -3,26 +3,48 @@ import { existsSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
-/** Write a { path: contents } map under `targetDir`. Returns the count. */
-export async function writeProject(targetDir, files) {
+/**
+ * Write a { path: contents } map under `targetDir`.
+ * In `merge` mode an existing file is never touched — it's reported as skipped,
+ * so scaffolding into a repo that already has files can't destroy work.
+ * Returns { written, skipped } as arrays of relative paths.
+ */
+export async function writeProject(targetDir, files, { merge = false } = {}) {
+  const written = [];
+  const skipped = [];
   for (const [rel, contents] of Object.entries(files)) {
     const full = join(targetDir, rel);
+    if (merge && existsSync(full)) {
+      skipped.push(rel);
+      continue;
+    }
     await mkdir(dirname(full), { recursive: true });
     await writeFile(full, contents);
+    written.push(rel);
   }
-  return Object.keys(files).length;
+  return { written, skipped };
 }
 
-/** True if the directory doesn't exist or contains no entries. */
-export function dirIsEmptyOrMissing(dir) {
-  if (!existsSync(dir)) return true;
+// Entries that don't make a directory "occupied": VCS metadata and OS noise.
+// `git clone` of a fresh empty repo leaves .git/ behind, and treating that as
+// non-empty broke the most common flow — create the repo, clone it, scaffold in.
+const IGNORED_ENTRIES = new Set(['.git', '.DS_Store', 'Thumbs.db', '.hg', '.svn']);
+
+/** Real (non-ignorable) entries in `dir`. Empty when the dir is missing. */
+export function existingEntries(dir) {
+  if (!existsSync(dir)) return [];
   try {
-    return readdirSync(dir).length === 0;
+    return readdirSync(dir).filter((e) => !IGNORED_ENTRIES.has(e));
   } catch {
-    return false;
+    return [];
   }
 }
 
+/** True if the directory doesn't exist or holds nothing that would be clobbered. */
+export function dirIsEmptyOrMissing(dir) {
+  return existingEntries(dir).length === 0;
+}
+
 /** Run a command in `cwd` (arg array — no shell parsing). Never throws. */
 export function run(cmd, args, cwd, { quiet = true } = {}) {
   const res = spawnSync(cmd, args, {
@@ -44,3 +66,76 @@ export function gitInit(cwd) {
 export function installDeps(pm, cwd) {
   return run(pm, ['install'], cwd, { quiet: false });
 }
+
+// Resolving the dependency graph without downloading it. Yarn has no equivalent
+// that works across its v1/v2+ split, so it's left out and reported instead.
+const LOCKFILE_ONLY = {
+  npm: ['install', '--package-lock-only', '--ignore-scripts'],
+  pnpm: ['install', '--lockfile-only', '--ignore-scripts'],
+  bun: ['install', '--lockfile-only'],
+};
+
+/**
+ * Write a lockfile without installing.
+ *
+ * A pushed repo with no lockfile fails CI on its very first run — `cache: npm`
+ * in actions/setup-node errors outright when it can't find one. So when we're
+ * about to create a remote but the install was skipped, produce the lockfile
+ * anyway. Returns false when the package manager has no such mode.
+ */
+export function writeLockfile(pm, cwd) {
+  const args = LOCKFILE_ONLY[pm];
+  return args ? run(pm, args, cwd) : false;
+}
+
+/** Run a command and capture its output. Never throws. */
+function capture(cmd, args, cwd) {
+  const res = spawnSync(cmd, args, { cwd, encoding: 'utf8', shell: process.platform === 'win32' });
+  return {
+    ok: res.status === 0,
+    stdout: (res.stdout || '').trim(),
+    stderr: (res.stderr || '').trim(),
+  };
+}
+
+/** True if `cmd` is on PATH. */
+export function hasCommand(cmd) {
+  return capture(process.platform === 'win32' ? 'where' : 'which', [cmd], process.cwd()).ok;
+}
+
+/** The authenticated GitHub login, or null if gh isn't installed or logged in. */
+export function githubLogin() {
+  const res = capture('gh', ['api', 'user', '-q', '.login'], process.cwd());
+  return res.ok && res.stdout ? res.stdout : null;
+}
+
+/**
+ * Create the GitHub repo and push to it, via the `gh` CLI.
+ *
+ * Deliberately shells out rather than calling the REST API: `gh` already owns
+ * the user's credentials, so Packkit never reads, prompts for, or stores a
+ * token. Returns { ok, error }.
+ */
+export function createGithubRepo({ slug, description, private: isPrivate = true, cwd }) {
+  const args = ['repo', 'create', slug, isPrivate ? '--private' : '--public',
+    '--source', '.', '--remote', 'origin', '--push'];
+  if (description) args.push('--description', description);
+  const res = capture('gh', args, cwd);
+  return { ok: res.ok, error: res.stderr || res.stdout };
+}
+
+/** Point `origin` at an existing remote URL and push the current branch. */
+export function pushToRemote(url, cwd) {
+  const added = capture('git', ['remote', 'add', 'origin', url], cwd);
+  if (!added.ok) return { ok: false, error: added.stderr };
+  const branch = capture('git', ['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+  const res = capture('git', ['push', '-u', 'origin', branch.ok ? branch.stdout : 'main'], cwd);
+  return { ok: res.ok, error: res.stderr };
+}
+
+/** Stage and commit everything if the tree is dirty. No-op on a clean tree. */
+export function commitAll(cwd, message) {
+  if (!capture('git', ['status', '--porcelain'], cwd).stdout) return false;
+  run('git', ['add', '-A'], cwd);
+  return run('git', ['commit', '-m', message, '--quiet'], cwd);
+}

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,7 +16,10 @@ 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. */
@@ -36,6 +40,7 @@ export function generate(input) {
   }
 
   files['package.json'] = toJson(finalizePackageJson(pkg));
+  files['packkit.json'] = provenance(cfg);
 
   return {
     config: cfg,

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,

package/src/core/node-versions.js

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by scripts/update-node-versions.mjs — do not edit by hand.
-// Source: nodejs.org/dist + nodejs/Release schedule, refreshed 2026-07-14.
+// Source: nodejs.org/dist + nodejs/Release schedule, refreshed 2026-07-20.
 // Offered lines track the Node release schedule; each version is that line's
 // newest published patch. Run `node scripts/update-node-versions.mjs` to refresh.
 

package/src/core/options.js

@@ -54,6 +54,14 @@ export const OPTIONS = {
   monorepo: {
     group: 'core', type: 'boolean', label: 'Monorepo (pnpm/Turborepo workspace)', default: false,
   },
+  monorepoLayout: {
+    group: 'core', type: 'select', label: 'Monorepo layout', default: 'libraries',
+    when: (cfg) => cfg.monorepo,
+    choices: [
+      { value: 'libraries', label: 'Libraries — linked packages you publish' },
+      { value: 'fullstack', label: 'Full-stack app — web + server + shared' },
+    ],
+  },
   framework: {
     group: 'core', type: 'select', label: 'Framework', default: 'none',
     choices: [
@@ -209,6 +217,7 @@ export const OPTION_HELP = {
   moduleFormat: 'How the package is consumed. ESM-only (default) is the modern, leanest choice — Node 20.19+/22.12+ can `require()` ESM. Pick dual only if you must support older CJS-only consumers; cjs-only is rarely needed.',
   target: 'What you are building — mix and match: a library (importable package), a CLI (ships a bin), an HTTP service, or an app (Vite SPA).',
   serviceFramework: 'For the service target: Hono (fast, web-standard, tiny — default), Fastify (batteries-included, plugins, schema validation), or Express (ubiquitous, huge ecosystem).',
+  monorepoLayout: 'What the workspace contains. "libraries" gives linked packages you publish (Changesets). "fullstack" gives apps/web (React+Vite) + apps/server (Hono) + packages/shared, wired together, with the server serving the web build in production.',
   monorepo: 'Generate a pnpm + Turborepo workspace with two linked example packages and Changesets. Only worth it when ≥2 packages share code.',
   framework: 'UI framework for component libraries and apps: React, Vue, or Svelte (or none for a plain package).',
   packageManager: 'Which package manager the scripts, lockfile, and CI target: npm, pnpm, yarn, or bun.',

package/src/core/presets.js

@@ -19,6 +19,10 @@ export const PRESETS = {
     release: 'none', workflows: ['ci'], deps: 'renovate', agents: true, vscode: true,
   },
   monorepo: { monorepo: true, language: 'ts', packageManager: 'pnpm' },
+  fullstack: {
+    monorepo: true, monorepoLayout: 'fullstack', language: 'ts', packageManager: 'pnpm',
+    framework: 'react', test: 'vitest', release: 'none', workflows: ['ci'],
+  },
   oss: {
     language: 'ts', target: ['library'], moduleFormat: 'esm', bundler: 'tsup',
     test: 'vitest', coverage: true, lint: 'eslint-prettier', gitHooks: 'simple-git-hooks',
@@ -53,6 +57,8 @@ export const PRESET_ALIASES = {
   slib: 'svelte-lib',
   sapp: 'svelte-app',
   svc: 'node-service',
+  fs: 'fullstack',
+  app: 'fullstack',
   service: 'node-service',
 };
 
@@ -78,6 +84,7 @@ export const PRESET_INFO = {
   'svelte-app': 'Svelte SPA — Vite dev server, build, Testing Library.',
   'node-service': 'Node HTTP service (Hono) — tsx dev, tsup build, Dockerfile.',
   monorepo: 'pnpm + Turborepo workspace — two example packages, Changesets, CI.',
+  fullstack: 'Full-stack monorepo — React+Vite web, Hono API, shared package; server serves the web build in production.',
   oss: 'Full open-source library — coverage, CodeQL, Codecov, Renovate, Changesets.',
   minimal: 'Bare TS library — tsup only, no tests/lint/CI.',
   full: 'Everything on — library + CLI, all workflows and extras.',

package/src/core/provenance.js

@@ -0,0 +1,35 @@
+// packkit.json — what this project was generated from.
+//
+// Packkit used to leave no trace, so a project couldn't answer "what did I
+// start from?", couldn't be diffed against a newer template, and had no upgrade
+// path. This records the answer next to the code.
+//
+// Only settings that differ from the defaults are stored, so the file reads as
+// the decisions someone actually made rather than a dump of every option. It is
+// deliberately free of timestamps and machine details: generation stays a pure
+// function of the config, so the same config always produces the same bytes.
+
+import { toJson } from './render.js';
+import { defaultConfig } from './options.js';
+
+// How this particular run was invoked, rather than what the project is.
+// Replaying a config shouldn't re-run someone else's `git init` or install.
+const TRANSIENT = new Set(['gitInit', 'install', 'generatorVersion', 'preset', 'name']);
+
+export function provenance(cfg) {
+  const defaults = defaultConfig();
+  const settings = {};
+  for (const [key, value] of Object.entries(cfg)) {
+    // Skip derived helpers (isTs, hasApp, ext…) — they aren't inputs.
+    if (!(key in defaults) || TRANSIENT.has(key)) continue;
+    if (JSON.stringify(value) !== JSON.stringify(defaults[key])) settings[key] = value;
+  }
+
+  return toJson({
+    $schema: 'https://danmat.github.io/create-packkit/packkit.schema.json',
+    generator: 'create-packkit',
+    ...(cfg.generatorVersion ? { version: cfg.generatorVersion } : {}),
+    ...(cfg.preset ? { preset: cfg.preset } : {}),
+    settings,
+  });
+}