create-packkit 0.1.1

package/src/core/features/vscode.js

@@ -0,0 +1,33 @@
+import { toJson } from '../render.js';
+
+export default {
+  id: 'vscode',
+  active: (cfg) => cfg.vscode,
+  apply(cfg) {
+    const biome = cfg.lint === 'biome';
+    const settings = {
+      'editor.formatOnSave': cfg.lint !== 'none',
+      'editor.defaultFormatter': biome ? 'biomejs.biome' : 'esbenp.prettier-vscode',
+      'editor.insertSpaces': false,
+    };
+    if (cfg.lint === 'eslint-prettier' || cfg.lint === 'oxlint') {
+      settings['editor.codeActionsOnSave'] = { 'source.fixAll': 'explicit' };
+    }
+
+    const recommendations = [];
+    if (biome) recommendations.push('biomejs.biome');
+    else {
+      if (cfg.lint === 'eslint-prettier') recommendations.push('dbaeumer.vscode-eslint');
+      if (cfg.lint !== 'none') recommendations.push('esbenp.prettier-vscode');
+    }
+    if (cfg.test === 'vitest') recommendations.push('vitest.explorer');
+
+    return {
+      files: {
+        '.vscode/settings.json': toJson(settings),
+        '.vscode/extensions.json': toJson({ recommendations }),
+      },
+      pkg: {},
+    };
+  },
+};

package/src/core/features/workflows.js

@@ -0,0 +1,216 @@
+import { toJson } from '../render.js';
+
+// package-manager helpers ----------------------------------------------------
+function pmInstall(cfg) {
+  return {
+    npm: 'npm ci',
+    pnpm: 'pnpm install --frozen-lockfile',
+    yarn: 'yarn install --immutable',
+    bun: 'bun install --frozen-lockfile',
+  }[cfg.packageManager];
+}
+function pmRun(cfg, script) {
+  return cfg.packageManager === 'npm' ? `npm run ${script}` : `${cfg.packageManager} ${script}`;
+}
+function setupSteps(cfg) {
+  const steps = ['      - uses: actions/checkout@v4'];
+  if (cfg.packageManager === 'pnpm') steps.push('      - uses: pnpm/action-setup@v4');
+  if (cfg.packageManager === 'bun') {
+    steps.push('      - uses: oven-sh/setup-bun@v2');
+  } else {
+    steps.push(
+      '      - uses: actions/setup-node@v4',
+      '        with:',
+      `          node-version: '${cfg.nodeVersion}'`,
+      `          cache: '${cfg.packageManager === 'yarn' ? 'yarn' : cfg.packageManager === 'pnpm' ? 'pnpm' : 'npm'}'`,
+    );
+  }
+  steps.push(`      - run: ${pmInstall(cfg)}`);
+  return steps.join('\n');
+}
+
+export default {
+  id: 'workflows',
+  active: (cfg) => (cfg.workflows && cfg.workflows.length) || cfg.deps !== 'none',
+  apply(cfg) {
+    const files = {};
+    const wf = cfg.workflows || [];
+
+    if (wf.includes('ci')) files['.github/workflows/ci.yml'] = ciWorkflow(cfg, wf.includes('codecov'));
+    if (wf.includes('npm-publish')) files['.github/workflows/release.yml'] = releaseWorkflow(cfg);
+    if (wf.includes('pages')) files['.github/workflows/pages.yml'] = pagesWorkflow(cfg);
+    if (wf.includes('codeql')) files['.github/workflows/codeql.yml'] = codeqlWorkflow();
+    if (wf.includes('stale')) files['.github/workflows/stale.yml'] = staleWorkflow();
+
+    if (cfg.deps === 'renovate') {
+      files['.github/renovate.json'] = toJson({
+        $schema: 'https://docs.renovatebot.com/renovate-schema.json',
+        extends: ['config:recommended', ':semanticCommits'],
+      });
+    } else if (cfg.deps === 'dependabot') {
+      files['.github/dependabot.yml'] = [
+        'version: 2',
+        'updates:',
+        '  - package-ecosystem: npm',
+        '    directory: "/"',
+        '    schedule:',
+        '      interval: weekly',
+        '  - package-ecosystem: github-actions',
+        '    directory: "/"',
+        '    schedule:',
+        '      interval: weekly',
+        '',
+      ].join('\n');
+    }
+
+    return { files, pkg: {} };
+  },
+};
+
+function ciWorkflow(cfg, codecov) {
+  const jobs = [];
+  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.bundler !== 'none' || cfg.isTs) jobs.push(`      - run: ${pmRun(cfg, 'build')}`);
+  const cov = codecov
+    ? '\n      - uses: codecov/codecov-action@v4\n        with:\n          token: ${{ secrets.CODECOV_TOKEN }}'
+    : '';
+  return [
+    'name: CI',
+    'on:',
+    '  push:',
+    '    branches: [main]',
+    '  pull_request:',
+    'jobs:',
+    '  ci:',
+    '    runs-on: ubuntu-latest',
+    setupSteps(cfg),
+    jobs.join('\n') + cov,
+    '',
+  ].join('\n');
+}
+
+function releaseWorkflow(cfg) {
+  if (cfg.release === 'changesets') {
+    return [
+      'name: Release',
+      'on:',
+      '  push:',
+      '    branches: [main]',
+      'concurrency: ${{ github.workflow }}-${{ github.ref }}',
+      'permissions:',
+      '  contents: write',
+      '  pull-requests: write',
+      '  id-token: write',
+      'jobs:',
+      '  release:',
+      '    runs-on: ubuntu-latest',
+      setupSteps(cfg),
+      '      - uses: changesets/action@v1',
+      '        with:',
+      `          publish: ${pmRun(cfg, 'release')}`,
+      '          version: ' + pmRun(cfg, 'version'),
+      '        env:',
+      '          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}',
+      '          NPM_CONFIG_PROVENANCE: "true"',
+      '        # add NPM_TOKEN as a repo secret, or use npm Trusted Publishing (OIDC)',
+      '',
+    ].join('\n');
+  }
+  // tag-triggered publish with provenance
+  return [
+    'name: Publish',
+    'on:',
+    '  push:',
+    '    tags: ["v*"]',
+    'permissions:',
+    '  contents: read',
+    '  id-token: write',
+    'jobs:',
+    '  publish:',
+    '    runs-on: ubuntu-latest',
+    setupSteps(cfg),
+    cfg.bundler !== 'none' || cfg.isTs ? `      - run: ${pmRun(cfg, 'build')}` : null,
+    '      - run: npm publish --provenance --access public',
+    '        env:',
+    '          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}',
+    '',
+  ].filter((l) => l !== null).join('\n');
+}
+
+function pagesWorkflow(cfg) {
+  return [
+    'name: Deploy Pages',
+    'on:',
+    '  push:',
+    '    branches: [main]',
+    'permissions:',
+    '  contents: read',
+    '  pages: write',
+    '  id-token: write',
+    'concurrency:',
+    '  group: pages',
+    '  cancel-in-progress: true',
+    'jobs:',
+    '  deploy:',
+    '    environment:',
+    '      name: github-pages',
+    '      url: ${{ steps.deployment.outputs.page_url }}',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@v4',
+    '      - uses: actions/configure-pages@v5',
+    '      - uses: actions/upload-pages-artifact@v3',
+    '        with:',
+    '          path: ./docs',
+    '      - id: deployment',
+    '        uses: actions/deploy-pages@v4',
+    '',
+  ].join('\n');
+}
+
+function codeqlWorkflow() {
+  return [
+    'name: CodeQL',
+    'on:',
+    '  push:',
+    '    branches: [main]',
+    '  pull_request:',
+    '  schedule:',
+    '    - cron: "0 6 * * 1"',
+    'jobs:',
+    '  analyze:',
+    '    runs-on: ubuntu-latest',
+    '    permissions:',
+    '      security-events: write',
+    '    steps:',
+    '      - uses: actions/checkout@v4',
+    '      - uses: github/codeql-action/init@v3',
+    '        with:',
+    '          languages: javascript-typescript',
+    '      - uses: github/codeql-action/analyze@v3',
+    '',
+  ].join('\n');
+}
+
+function staleWorkflow() {
+  return [
+    'name: Stale',
+    'on:',
+    '  schedule:',
+    '    - cron: "0 0 * * *"',
+    'jobs:',
+    '  stale:',
+    '    runs-on: ubuntu-latest',
+    '    permissions:',
+    '      issues: write',
+    '      pull-requests: write',
+    '    steps:',
+    '      - uses: actions/stale@v9',
+    '        with:',
+    '          days-before-stale: 60',
+    '          days-before-close: 7',
+    '',
+  ].join('\n');
+}

package/src/core/index.js

@@ -0,0 +1,73 @@
+// Packkit core — pure, dependency-free, runs in Node AND the browser.
+// generate(config) -> { config, files: { path: contents }, postCommands, summary }
+// The CLI writes `files` to disk; the web configurator zips them.
+
+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 } from './presets.js';
+
+export { OPTIONS, GROUPS, defaultConfig, normalizeConfig, PRESETS, PRESET_NAMES };
+
+/** Apply a named preset 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 });
+}
+
+/** Turn a config into a complete set of files. */
+export function generate(input) {
+  const cfg = normalizeConfig(input);
+  const files = {};
+  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;
+    }
+    if (out.pkg) pkg = deepMerge(pkg, out.pkg);
+  }
+
+  files['package.json'] = toJson(finalizePackageJson(pkg));
+
+  return {
+    config: cfg,
+    files,
+    postCommands: postCommands(cfg),
+    summary: summarize(cfg, files),
+  };
+}
+
+function postCommands(cfg) {
+  const install = {
+    npm: 'npm install',
+    pnpm: 'pnpm install',
+    yarn: 'yarn install',
+    bun: 'bun install',
+  }[cfg.packageManager];
+  const cmds = [];
+  if (cfg.gitInit) cmds.push('git init', 'git add -A', 'git commit -m "Initial commit from Packkit"');
+  if (cfg.install) cmds.push(install);
+  return cmds;
+}
+
+function summarize(cfg, files) {
+  return {
+    name: cfg.name,
+    fileCount: Object.keys(files).length,
+    stack: [
+      cfg.isTs ? 'TypeScript' : 'JavaScript',
+      cfg.moduleFormat.toUpperCase(),
+      cfg.target.join('+'),
+      cfg.bundler !== 'none' ? cfg.bundler : (cfg.isTs ? 'tsc' : 'no-build'),
+      cfg.test !== 'none' ? cfg.test : null,
+      cfg.lint !== 'none' ? cfg.lint : null,
+      cfg.release !== 'none' ? cfg.release : null,
+    ].filter(Boolean),
+    workflows: cfg.workflows,
+  };
+}

package/src/core/options.js

@@ -0,0 +1,193 @@
+// The single source of truth for every choice Packkit offers.
+// Both the CLI wizard and the web configurator render from this schema, and
+// `normalizeConfig` turns partial/user input into a complete, valid config.
+
+/** @typedef {'select'|'multiselect'|'boolean'|'text'} OptionType */
+
+export const OPTIONS = {
+  // ---- package metadata ----
+  name: { group: 'meta', type: 'text', label: 'Package name', default: 'my-package' },
+  description: { group: 'meta', type: 'text', label: 'Description', default: '' },
+  author: { group: 'meta', type: 'text', label: 'Author', default: '' },
+  keywords: { group: 'meta', type: 'text', label: 'Keywords (comma-separated)', default: '' },
+  repo: { group: 'meta', type: 'text', label: 'Repository URL', default: '' },
+
+  // ---- core shape ----
+  language: {
+    group: 'core', type: 'select', label: 'Language', default: 'ts',
+    choices: [
+      { value: 'ts', label: 'TypeScript (strict)' },
+      { value: 'js', label: 'JavaScript (ESM)' },
+    ],
+  },
+  moduleFormat: {
+    group: 'core', type: 'select', label: 'Module format', default: 'dual',
+    choices: [
+      { value: 'esm', label: 'ESM only' },
+      { value: 'cjs', label: 'CommonJS only' },
+      { value: 'dual', label: 'Dual (ESM + CJS)' },
+    ],
+  },
+  target: {
+    group: 'core', type: 'multiselect', label: 'What are you building?', default: ['library'],
+    choices: [
+      { value: 'library', label: 'Library (importable package)' },
+      { value: 'cli', label: 'CLI tool (ships a bin)' },
+    ],
+  },
+  packageManager: {
+    group: 'core', type: 'select', label: 'Package manager', default: 'npm',
+    choices: [
+      { value: 'npm', label: 'npm' },
+      { value: 'pnpm', label: 'pnpm' },
+      { value: 'yarn', label: 'yarn' },
+      { value: 'bun', label: 'bun' },
+    ],
+  },
+  nodeVersion: {
+    group: 'core', type: 'select', label: 'Node version', default: '20',
+    choices: [
+      { value: '18', label: '18 (LTS)' },
+      { value: '20', label: '20 (LTS)' },
+      { value: '22', label: '22 (LTS)' },
+    ],
+  },
+
+  // ---- build ----
+  bundler: {
+    group: 'build', type: 'select', label: 'Bundler / build', default: 'tsup',
+    choices: [
+      { value: 'tsup', label: 'tsup (esbuild — recommended)' },
+      { value: 'tsdown', label: 'tsdown (Rolldown — fast successor)' },
+      { value: 'unbuild', label: 'unbuild (UnJS)' },
+      { value: 'rollup', label: 'Rollup' },
+      { value: 'none', label: 'None (tsc / no build)' },
+    ],
+  },
+
+  // ---- testing ----
+  test: {
+    group: 'quality', type: 'select', label: 'Test runner', default: 'vitest',
+    choices: [
+      { value: 'vitest', label: 'Vitest (recommended)' },
+      { value: 'jest', label: 'Jest' },
+      { value: 'node', label: 'node:test (built-in)' },
+      { value: 'none', label: 'None' },
+    ],
+  },
+  coverage: { group: 'quality', type: 'boolean', label: 'Coverage reporting', default: true },
+
+  // ---- lint / format ----
+  lint: {
+    group: 'quality', type: 'select', label: 'Lint / format', default: 'eslint-prettier',
+    choices: [
+      { value: 'eslint-prettier', label: 'ESLint + Prettier (recommended)' },
+      { value: 'biome', label: 'Biome (all-in-one)' },
+      { value: 'oxlint', label: 'oxlint + Prettier (fast)' },
+      { value: 'none', label: 'None' },
+    ],
+  },
+
+  // ---- git hooks ----
+  gitHooks: {
+    group: 'quality', type: 'select', label: 'Git hooks', default: 'simple-git-hooks',
+    choices: [
+      { value: 'simple-git-hooks', label: 'simple-git-hooks (light)' },
+      { value: 'husky', label: 'husky + lint-staged' },
+      { value: 'lefthook', label: 'lefthook' },
+      { value: 'none', label: 'None' },
+    ],
+  },
+
+  // ---- release ----
+  release: {
+    group: 'release', type: 'select', label: 'Release / versioning', default: 'changesets',
+    choices: [
+      { value: 'changesets', label: 'Changesets (recommended)' },
+      { value: 'release-it', label: 'release-it' },
+      { value: 'np', label: 'np' },
+      { value: 'none', label: 'None' },
+    ],
+  },
+
+  // ---- github actions (configurable workflows) ----
+  workflows: {
+    group: 'ci', type: 'multiselect', label: 'GitHub Actions',
+    default: ['ci', 'npm-publish'],
+    choices: [
+      { value: 'ci', label: 'CI (typecheck + lint + test + build)' },
+      { value: 'npm-publish', label: 'Publish to npm (provenance / OIDC)' },
+      { value: 'pages', label: 'Deploy GitHub Pages' },
+      { value: 'codeql', label: 'CodeQL security scan' },
+      { value: 'codecov', label: 'Upload coverage to Codecov' },
+      { value: 'stale', label: 'Stale issue/PR bot' },
+    ],
+  },
+  deps: {
+    group: 'ci', type: 'select', label: 'Dependency updates', default: 'renovate',
+    choices: [
+      { value: 'renovate', label: 'Renovate' },
+      { value: 'dependabot', label: 'Dependabot' },
+      { value: 'none', label: 'None' },
+    ],
+  },
+
+  // ---- repo hygiene ----
+  license: {
+    group: 'repo', type: 'select', label: 'License', default: 'MIT',
+    choices: [
+      { value: 'MIT', label: 'MIT' },
+      { value: 'Apache-2.0', label: 'Apache-2.0' },
+      { value: 'ISC', label: 'ISC' },
+      { value: 'none', label: 'None' },
+    ],
+  },
+  community: { group: 'repo', type: 'boolean', label: 'Community files (CONTRIBUTING, CoC, SECURITY, templates)', default: true },
+  agents: { group: 'repo', type: 'boolean', label: 'AI agent instructions (AGENTS.md + CLAUDE.md)', default: true },
+  vscode: { group: 'repo', type: 'boolean', label: 'VS Code settings + extensions', default: true },
+  editorconfig: { group: 'repo', type: 'boolean', label: '.editorconfig', default: true },
+  gitInit: { group: 'repo', type: 'boolean', label: 'git init + initial commit', default: true },
+  install: { group: 'repo', type: 'boolean', label: 'Install dependencies', default: true },
+};
+
+export const GROUPS = [
+  { id: 'meta', label: 'Package' },
+  { id: 'core', label: 'Core' },
+  { id: 'build', label: 'Build' },
+  { id: 'quality', label: 'Quality' },
+  { id: 'release', label: 'Release' },
+  { id: 'ci', label: 'CI / CD' },
+  { id: 'repo', label: 'Repository' },
+];
+
+/** Build a default config from the schema. */
+export function defaultConfig() {
+  const cfg = {};
+  for (const [key, opt] of Object.entries(OPTIONS)) {
+    cfg[key] = Array.isArray(opt.default) ? [...opt.default] : opt.default;
+  }
+  return cfg;
+}
+
+/** Merge partial input over the defaults and coerce a few fields. */
+export function normalizeConfig(input = {}) {
+  const cfg = { ...defaultConfig(), ...input };
+
+  // A CLI target needs an executable build; JS `strict` isn't a thing, etc.
+  if (!Array.isArray(cfg.target) || cfg.target.length === 0) cfg.target = ['library'];
+  if (!Array.isArray(cfg.workflows)) cfg.workflows = [];
+
+  // Coverage only makes sense with a test runner that supports it.
+  if (cfg.test === 'none' || cfg.test === 'node') cfg.coverage = false;
+  // Codecov workflow implies coverage.
+  if (cfg.workflows.includes('codecov')) cfg.coverage = true;
+  // npm-publish + changesets are complementary; nothing to coerce, just noted.
+
+  cfg.isTs = cfg.language === 'ts';
+  cfg.ext = cfg.isTs ? 'ts' : 'js';
+  cfg.hasLibrary = cfg.target.includes('library');
+  cfg.hasCli = cfg.target.includes('cli');
+  cfg.hasEsm = cfg.moduleFormat === 'esm' || cfg.moduleFormat === 'dual';
+  cfg.hasCjs = cfg.moduleFormat === 'cjs' || cfg.moduleFormat === 'dual';
+  return cfg;
+}

package/src/core/pkg.js

@@ -0,0 +1,31 @@
+// Finalize the accumulated package.json: order top-level keys sensibly and
+// sort dependency maps alphabetically (matches what `npm`/formatters produce).
+
+const KEY_ORDER = [
+  'name', 'version', 'description', 'keywords', 'homepage', 'bugs', 'repository',
+  'license', 'author', 'type', 'exports', 'main', 'module', 'types', 'bin',
+  'files', 'engines', 'packageManager', 'scripts', 'simple-git-hooks', 'lint-staged',
+  'dependencies', 'peerDependencies', 'devDependencies', 'publishConfig',
+];
+
+export function finalizePackageJson(pkg) {
+  const out = {};
+  for (const key of KEY_ORDER) {
+    if (pkg[key] === undefined) continue;
+    out[key] = isDepMap(key) ? sortKeys(pkg[key]) : pkg[key];
+  }
+  // Carry through anything not in the canonical order (future-proofing).
+  for (const key of Object.keys(pkg)) {
+    if (!(key in out)) out[key] = pkg[key];
+  }
+  return out;
+}
+
+function isDepMap(key) {
+  return key === 'dependencies' || key === 'devDependencies' || key === 'peerDependencies';
+}
+
+function sortKeys(obj) {
+  if (!obj || typeof obj !== 'object') return obj;
+  return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, obj[k]]));
+}

package/src/core/presets.js

@@ -0,0 +1,23 @@
+// Named presets = partial configs applied over the defaults, so devs can skip
+// the wizard: `npx packkit ts-lib my-project`.
+
+export const PRESETS = {
+  'ts-lib': { language: 'ts', target: ['library'], moduleFormat: 'dual' },
+  'js-lib': { language: 'js', target: ['library'], moduleFormat: 'dual', bundler: 'tsup' },
+  'ts-cli': { language: 'ts', target: ['cli', 'library'], moduleFormat: 'esm' },
+  cli: { language: 'ts', target: ['cli', 'library'], moduleFormat: 'esm' },
+  minimal: {
+    language: 'ts', target: ['library'], moduleFormat: 'dual', bundler: 'tsup',
+    test: 'none', lint: 'none', gitHooks: 'none', release: 'none',
+    workflows: ['ci'], deps: 'none', community: false, agents: false, vscode: false,
+  },
+  full: {
+    language: 'ts', target: ['library', 'cli'], moduleFormat: 'dual', bundler: 'tsup',
+    test: 'vitest', coverage: true, lint: 'eslint-prettier', gitHooks: 'simple-git-hooks',
+    release: 'changesets',
+    workflows: ['ci', 'npm-publish', 'pages', 'codeql', 'codecov', 'stale'],
+    deps: 'renovate', community: true, agents: true, vscode: true,
+  },
+};
+
+export const PRESET_NAMES = Object.keys(PRESETS);

package/src/core/render.js

@@ -0,0 +1,35 @@
+// Minimal {{var}} template rendering — feature modules mostly use template
+// literals directly; this is for the few multi-line string templates.
+
+/** Replace {{ key }} / {{ a.b }} tokens from `vars`. Missing keys render empty. */
+export function render(template, vars = {}) {
+  return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) => {
+    const val = key.split('.').reduce((o, k) => (o == null ? o : o[k]), vars);
+    return val == null ? '' : String(val);
+  });
+}
+
+/** Deep-merge plain objects (arrays are concatenated + de-duped). Used to fold
+ *  each feature's package.json fragment into the accumulator. */
+export function deepMerge(target, source) {
+  if (Array.isArray(target) && Array.isArray(source)) {
+    return [...new Set([...target, ...source])];
+  }
+  if (isPlainObject(target) && isPlainObject(source)) {
+    const out = { ...target };
+    for (const [k, v] of Object.entries(source)) {
+      out[k] = k in target ? deepMerge(target[k], v) : v;
+    }
+    return out;
+  }
+  return source;
+}
+
+function isPlainObject(v) {
+  return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** Stable, human-friendly stringify with 2-space indent and trailing newline. */
+export function toJson(obj) {
+  return JSON.stringify(obj, null, 2) + '\n';
+}