create-packkit 2.7.2 → 2.8.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.8.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

@@ -43,6 +43,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 +108,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 {
@@ -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
@@ -144,14 +161,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 +194,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 +244,14 @@ 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,
   ].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 +270,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/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.