create-packkit 1.0.0 → 1.1.0

package/README.md

@@ -53,6 +53,17 @@ No install needed: **[danmat.github.io/create-packkit](https://danmat.github.io/
 
 **Team profiles:** save a partial config as `packkit.config.json` (or any file) and reuse it with `npx create-packkit my-lib --from ./packkit.config.json` — flags still override the file.
 
+## For AI agents & automation
+
+Packkit is safe to drive non-interactively — every option is a flag, so no prompts are needed. Agents can introspect the whole interface as JSON:
+
+```sh
+npx create-packkit --schema      # all options, presets, and aliases as JSON
+npx create-packkit my-lib ts-lib --no-install --no-git   # deterministic scaffold
+```
+
+There's also an [`llms.txt`](llms.txt) (served at [danmat.github.io/create-packkit/llms.txt](https://danmat.github.io/create-packkit/llms.txt)) describing the commands for LLMs.
+
 ## How it works
 
 Packkit is a pure `config → { files }` **core** that runs in both Node and the browser:

package/llms.txt

@@ -0,0 +1,43 @@
+# Packkit (create-packkit)
+
+> A highly configurable, non-interactive scaffolder for modern npm packages, CLIs, HTTP services, and front-end apps (React/Vue/Svelte). Designed to be driven by humans OR automation/agents.
+
+Packkit generates a complete, ready-to-ship project from a single deterministic command. It is safe for agents to call because every option is a flag — no prompts are required when a name and flags (or a preset) are given.
+
+## For agents: how to use it
+
+Introspect the full interface (all options, presets, aliases) as JSON:
+
+```sh
+npx create-packkit --schema
+```
+
+Generate non-interactively (no prompts; `--no-install`/`--no-git` for a pure file scaffold):
+
+```sh
+npx create-packkit <name> [preset] [--flags...]
+```
+
+Examples:
+
+```sh
+npx create-packkit my-lib ts-lib
+npx create-packkit my-cli cli --pm pnpm
+npx create-packkit ui react-lib --storybook
+npx create-packkit api node-service
+npx create-packkit web react-app
+npx create-packkit lib my-lib --no-install --no-git
+```
+
+## Presets (and short aliases)
+
+`ts-lib` (`lib`) · `js-lib` (`jslib`) · `ts-cli` / `cli` · `react-lib` (`rlib`) · `react-app` (`rapp`) · `vue-lib` (`vlib`) · `vue-app` (`vapp`) · `svelte-lib` (`slib`) · `svelte-app` (`sapp`) · `node-service` (`svc`) · `oss` · `minimal` · `full`
+
+## Key flags
+
+`--language ts|js` · `--framework none|react|vue|svelte` · `--target library|cli|service|app` (repeatable) · `--module esm|cjs|dual` · `--bundler tsup|tsdown|unbuild|rollup|none` · `--minify` · `--test vitest|jest|node|none` · `--lint eslint-prettier|biome|oxlint|none` · `--hooks ...` · `--release changesets|release-it|np|none` · `--workflows ci|npm-publish|pages|codeql|codecov|stale` (repeatable) · `--pkg-checks` (publint + are-the-types-wrong) · `--knip` · `--jsr` · `--deps renovate|dependabot|none` · `--license MIT|Apache-2.0|ISC|none` · `--pm npm|pnpm|yarn|bun` · `--from <file>` (load a JSON profile) · `--no-install` · `--no-git`
+
+## Links
+- Web configurator: https://danmat.github.io/create-packkit/
+- Repo: https://github.com/DanMat/create-packkit
+- npm: https://www.npmjs.com/package/create-packkit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-packkit",
-  "version": "1.0.0",
+  "version": "1.1.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": {
@@ -15,7 +15,8 @@
     "bin",
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "llms.txt"
   ],
   "engines": {
     "node": ">=18"

package/src/cli/args.js

@@ -1,5 +1,5 @@
 import { parseArgs } from 'node:util';
-import { PRESET_NAMES } from '../core/presets.js';
+import { resolvePreset } from '../core/presets.js';
 
 // Map friendly flag names to config keys for non-interactive use.
 const OVERRIDE_FLAGS = {
@@ -17,6 +17,7 @@ const OVERRIDE_FLAGS = {
   node: 'nodeVersion',
   author: 'author',
   description: 'description',
+  repo: 'repo',
 };
 
 // Boolean options that default ON — a --no-<flag> turns them off.
@@ -45,8 +46,12 @@ export function parseCliArgs(argv) {
       workflows: { type: 'string', multiple: true },
       minify: { type: 'boolean' },
       storybook: { type: 'boolean' },
+      'pkg-checks': { type: 'boolean' },
+      knip: { type: 'boolean' },
+      jsr: { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
       version: { type: 'boolean', short: 'v' },
+      schema: { type: 'boolean' },
       ...Object.fromEntries(Object.keys(OVERRIDE_FLAGS).map((k) => [k, { type: 'string' }])),
       ...Object.fromEntries(Object.keys(NEGATABLE).map((k) => [k, { type: 'boolean' }])),
     },
@@ -55,7 +60,7 @@ export function parseCliArgs(argv) {
   // First positional may be a known preset; otherwise it's the project name.
   let preset = values.preset;
   const pos = [...positionals];
-  if (!preset && pos.length && PRESET_NAMES.includes(pos[0])) preset = pos.shift();
+  if (!preset && pos.length && resolvePreset(pos[0])) preset = pos.shift();
   const name = values.name || pos[0];
 
   const overrides = {};
@@ -66,6 +71,9 @@ export function parseCliArgs(argv) {
   if (values.workflows) overrides.workflows = values.workflows;
   if (values.minify) overrides.minify = true;
   if (values.storybook) overrides.storybook = true;
+  if (values['pkg-checks']) overrides.pkgChecks = true;
+  if (values.knip) overrides.knip = true;
+  if (values.jsr) overrides.jsr = true;
   for (const [flag, key] of Object.entries(NEGATABLE)) {
     if (values[flag]) overrides[key] = false;
   }
@@ -81,6 +89,7 @@ export function parseCliArgs(argv) {
     git: !values['no-git'],
     help: !!values.help,
     version: !!values.version,
+    schema: !!values.schema,
     overrides,
   };
 }

package/src/cli/index.js

@@ -2,7 +2,7 @@ import { resolve, basename } from 'node:path';
 import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
-import { generate, fromPreset, normalizeConfig, PRESET_NAMES } from '../core/index.js';
+import { generate, fromPreset, normalizeConfig, PRESET_NAMES, OPTIONS, PRESET_INFO, PRESET_ALIASES } from '../core/index.js';
 import { parseCliArgs } from './args.js';
 import { runWizard } from './wizard.js';
 import { writeProject, dirIsEmptyOrMissing, gitInit, installDeps } from './write.js';
@@ -41,10 +41,14 @@ Options:
   --hooks <simple-git-hooks|husky|lefthook|none>  --release <changesets|release-it|np|none>
   --workflows <ci|npm-publish|pages|codeql|codecov|stale>   (repeatable)
   --deps <renovate|dependabot|none>  --license <MIT|Apache-2.0|ISC|none>
+  --pkg-checks (publint + are-the-types-wrong)   --knip   --jsr
   --no-coverage  --no-community  --no-agents  --no-vscode  --no-editorconfig
+  --schema            Print the full option/preset schema as JSON (for tools/agents)
   -h, --help          Show this help
   -v, --version       Show version
 
+Preset shortcuts: lib, jslib, rlib, rapp, vlib, vapp, slib, sapp, svc
+
 Examples:
   npx packkit ts-lib my-lib
   npm create packkit@latest my-cli -- --preset cli
@@ -55,6 +59,10 @@ export async function run(argv = process.argv.slice(2)) {
   const args = parseCliArgs(argv);
   if (args.help) return void console.log(HELP);
   if (args.version) return void console.log(pkgVersion());
+  if (args.schema) {
+    // Machine-readable interface for tools/agents: every option, preset, and alias.
+    return void console.log(JSON.stringify({ version: pkgVersion(), options: OPTIONS, presets: PRESET_INFO, aliases: PRESET_ALIASES }, null, 2));
+  }
 
   const interactive = !args.preset && !args.yes && !args.from && process.stdout.isTTY;
 

package/src/core/features/bundler.js

@@ -20,16 +20,19 @@ export default {
       pkg.files = ['dist'];
       const esm = './dist/index.js';
       const cjs = './dist/index.cjs';
-      const dts = './dist/index.d.ts';
+      const dtsEsm = './dist/index.d.ts';
+      // Dual builds emit a separate .d.cts so CJS consumers resolve the right
+      // types under the "require" condition (publint / are-the-types-wrong).
+      const dtsCjs = cfg.moduleFormat === 'dual' ? './dist/index.d.cts' : dtsEsm;
+
       const exp = {};
-      if (cfg.isTs) exp.types = dts;
-      if (cfg.hasEsm) exp.import = esm;
-      if (cfg.hasCjs) exp.require = build ? cjs : './dist/index.cjs';
+      if (cfg.hasEsm) exp.import = cfg.isTs ? { types: dtsEsm, default: esm } : esm;
+      if (cfg.hasCjs) exp.require = cfg.isTs ? { types: dtsCjs, default: cjs } : cjs;
       pkg.exports = { '.': exp };
-      if (cfg.hasCjs) pkg.main = exp.require;
-      else pkg.main = esm;
+
+      pkg.main = cfg.hasCjs ? cjs : esm;
       if (cfg.hasEsm) pkg.module = esm;
-      if (cfg.isTs) pkg.types = dts;
+      if (cfg.isTs) pkg.types = cfg.hasEsm ? dtsEsm : dtsCjs;
     }
 
     // ---- build tooling ----

package/src/core/features/checks.js

@@ -0,0 +1,24 @@
+// Package-correctness + hygiene checks (opt-in):
+//  - publint            validates package.json shape (exports/main/module)
+//  - are-the-types-wrong verifies TS consumers resolve your .d.ts correctly
+//  - knip               finds unused files, dependencies, and exports
+
+export default {
+  id: 'checks',
+  active: (cfg) => cfg.pkgChecks || cfg.knip,
+  apply(cfg) {
+    const pkg = { scripts: {}, devDependencies: {} };
+
+    if (cfg.pkgChecks) {
+      pkg.scripts['check:pkg'] = 'publint && attw --pack';
+      pkg.devDependencies.publint = '^0.3.0';
+      pkg.devDependencies['@arethetypeswrong/cli'] = '^0.18.0';
+    }
+    if (cfg.knip) {
+      pkg.scripts.knip = 'knip';
+      pkg.devDependencies.knip = '^5.0.0';
+    }
+
+    return { files: {}, pkg };
+  },
+};

package/src/core/features/index.js

@@ -12,6 +12,8 @@ import lint from './lint.js';
 import githooks from './githooks.js';
 import release from './release.js';
 import cli from './cli.js';
+import checks from './checks.js';
+import jsr from './jsr.js';
 import workflows from './workflows.js';
 import storybook from './storybook.js';
 import community from './community.js';
@@ -31,6 +33,8 @@ export default [
   githooks,
   release,
   cli,
+  checks,
+  jsr,
   workflows,
   storybook,
   community,

package/src/core/features/jsr.js

@@ -0,0 +1,42 @@
+import { toJson } from '../render.js';
+
+// JSR publishing (TypeScript-first, ESM-only registry with automatic provenance).
+// Publishes source directly — no build step required. JSR names are scoped, so
+// a non-scoped package gets an @scope placeholder to fill in.
+
+export default {
+  id: 'jsr',
+  active: (cfg) => cfg.jsr,
+  apply(cfg) {
+    const name = cfg.name.startsWith('@') ? cfg.name : `@scope/${cfg.name}`;
+    return {
+      files: {
+        'jsr.json': toJson({
+          name,
+          version: '0.0.0',
+          exports: `./src/index.${cfg.ext}`,
+        }),
+        '.github/workflows/jsr.yml': [
+          'name: Publish to JSR',
+          'on:',
+          '  push:',
+          '    tags: ["v*"]',
+          'permissions:',
+          '  contents: read',
+          '  id-token: write',
+          'jobs:',
+          '  publish:',
+          '    runs-on: ubuntu-latest',
+          '    steps:',
+          '      - uses: actions/checkout@v4',
+          '      - uses: actions/setup-node@v4',
+          "        with:",
+          "          node-version: '20'",
+          '      - run: npx jsr publish',
+          '',
+        ].join('\n'),
+      },
+      pkg: {},
+    };
+  },
+};

package/src/core/features/meta.js

@@ -16,6 +16,7 @@ export default {
 
     const kw = String(cfg.keywords || '').split(',').map((s) => s.trim()).filter(Boolean);
     if (kw.length) pkg.keywords = kw;
+    if (cfg.license !== 'none') pkg.license = cfg.license;
     if (cfg.author) pkg.author = cfg.author;
     if (cfg.repo) {
       pkg.repository = { type: 'git', url: `git+${cfg.repo.replace(/\.git$/, '')}.git` };

package/src/core/features/workflows.js

@@ -72,7 +72,9 @@ function ciWorkflow(cfg, codecov) {
   if (cfg.isTs) jobs.push(`      - run: ${pmRun(cfg, 'typecheck')}`);
   if (cfg.lint !== 'none') jobs.push(`      - run: ${pmRun(cfg, 'lint')}`);
   if (cfg.test !== 'none') jobs.push(`      - run: ${pmRun(cfg, codecov ? 'coverage' : 'test')}`);
+  if (cfg.knip) jobs.push(`      - run: ${pmRun(cfg, 'knip')}`);
   if (cfg.hasBuild) jobs.push(`      - run: ${pmRun(cfg, 'build')}`);
+  if (cfg.pkgChecks) jobs.push(`      - run: ${pmRun(cfg, 'check:pkg')}`); // after build (attw packs dist)
   const cov = codecov
     ? '\n      - uses: codecov/codecov-action@v4\n        with:\n          token: ${{ secrets.CODECOV_TOKEN }}'
     : '';
@@ -85,6 +87,7 @@ function ciWorkflow(cfg, codecov) {
     'jobs:',
     '  ci:',
     '    runs-on: ubuntu-latest',
+    '    steps:',
     setupSteps(cfg),
     jobs.join('\n') + cov,
     '',
@@ -106,6 +109,7 @@ function releaseWorkflow(cfg) {
       'jobs:',
       '  release:',
       '    runs-on: ubuntu-latest',
+      '    steps:',
       setupSteps(cfg),
       '      - uses: changesets/action@v1',
       '        with:',
@@ -130,6 +134,7 @@ function releaseWorkflow(cfg) {
     'jobs:',
     '  publish:',
     '    runs-on: ubuntu-latest',
+    '    steps:',
     setupSteps(cfg),
     cfg.hasBuild ? `      - run: ${pmRun(cfg, 'build')}` : null,
     '      - run: npm publish --provenance --access public',

package/src/core/index.js

@@ -6,15 +6,15 @@ import { normalizeConfig, OPTIONS, GROUPS, defaultConfig } from './options.js';
 import { deepMerge, toJson } from './render.js';
 import { finalizePackageJson } from './pkg.js';
 import features from './features/index.js';
-import { PRESETS, PRESET_NAMES, PRESET_INFO } from './presets.js';
+import { PRESETS, PRESET_NAMES, PRESET_INFO, PRESET_ALIASES, resolvePreset } from './presets.js';
 
-export { OPTIONS, GROUPS, defaultConfig, normalizeConfig, PRESETS, PRESET_NAMES, PRESET_INFO };
+export { OPTIONS, GROUPS, defaultConfig, normalizeConfig, PRESETS, PRESET_NAMES, PRESET_INFO, PRESET_ALIASES, resolvePreset };
 
-/** Apply a named preset over the defaults, returning a full config. */
+/** Apply a named preset (or alias) over the defaults, returning a full config. */
 export function fromPreset(name, overrides = {}) {
-  const preset = PRESETS[name];
-  if (!preset) throw new Error(`Unknown preset "${name}". Known: ${PRESET_NAMES.join(', ')}`);
-  return normalizeConfig({ ...preset, ...overrides });
+  const canonical = resolvePreset(name);
+  if (!canonical) throw new Error(`Unknown preset "${name}". Known: ${PRESET_NAMES.join(', ')}`);
+  return normalizeConfig({ ...PRESETS[canonical], ...overrides });
 }
 
 /** Turn a config into a complete set of files. */

package/src/core/options.js

@@ -91,6 +91,8 @@ export const OPTIONS = {
   },
   coverage: { group: 'quality', type: 'boolean', label: 'Coverage reporting', default: true },
   storybook: { group: 'quality', type: 'boolean', label: 'Storybook (component libraries)', default: false },
+  pkgChecks: { group: 'quality', type: 'boolean', label: 'Package checks (publint + are-the-types-wrong)', default: false },
+  knip: { group: 'quality', type: 'boolean', label: 'Knip (unused files / deps / exports)', default: false },
 
   // ---- lint / format ----
   lint: {
@@ -124,6 +126,7 @@ export const OPTIONS = {
       { value: 'none', label: 'None' },
     ],
   },
+  jsr: { group: 'release', type: 'boolean', label: 'Publish to JSR (TS-first registry)', default: false },
 
   // ---- github actions (configurable workflows) ----
   workflows: {
@@ -236,5 +239,11 @@ export function normalizeConfig(input = {}) {
 
   // Storybook only applies to component libraries.
   if (!cfg.hasFramework || cfg.hasApp || !cfg.hasLibrary) cfg.storybook = false;
+
+  cfg.publishable = (cfg.hasLibrary || cfg.hasCli) && !cfg.hasApp && !cfg.hasService;
+  // Package-correctness checks only make sense for a publishable package.
+  if (!cfg.publishable) cfg.pkgChecks = false;
+  // JSR is TypeScript-first, ESM, and for plain (non-framework) libraries.
+  if (!(cfg.isTs && cfg.hasLibrary && !cfg.hasFramework && !cfg.hasApp)) cfg.jsr = false;
   return cfg;
 }

package/src/core/presets.js

@@ -23,6 +23,7 @@ export const PRESETS = {
     test: 'vitest', coverage: true, lint: 'eslint-prettier', gitHooks: 'simple-git-hooks',
     release: 'changesets', workflows: ['ci', 'npm-publish', 'codeql', 'codecov'],
     deps: 'renovate', community: true, agents: true, vscode: true,
+    pkgChecks: true, knip: true,
   },
   minimal: {
     language: 'ts', target: ['library'], moduleFormat: 'dual', bundler: 'tsup',
@@ -40,6 +41,27 @@ export const PRESETS = {
 
 export const PRESET_NAMES = Object.keys(PRESETS);
 
+// Short shortcuts, e.g. `npx create-packkit lib my-lib`.
+export const PRESET_ALIASES = {
+  lib: 'ts-lib',
+  jslib: 'js-lib',
+  rlib: 'react-lib',
+  rapp: 'react-app',
+  vlib: 'vue-lib',
+  vapp: 'vue-app',
+  slib: 'svelte-lib',
+  sapp: 'svelte-app',
+  svc: 'node-service',
+  service: 'node-service',
+};
+
+/** Resolve a preset name or alias to its canonical preset id (or undefined). */
+export function resolvePreset(name) {
+  if (PRESETS[name]) return name;
+  if (PRESET_ALIASES[name]) return PRESET_ALIASES[name];
+  return undefined;
+}
+
 // Short gists for the CLI help and the web configurator (tooltips + description).
 export const PRESET_INFO = {
   'ts-lib': 'TypeScript library — dual ESM/CJS, tsup, Vitest, ESLint.',