create-packkit 0.1.1

package/src/core/features/community.js

@@ -0,0 +1,175 @@
+export default {
+  id: 'community',
+  active: (cfg) => cfg.license !== 'none' || cfg.community,
+  apply(cfg) {
+    const files = {};
+    const year = new Date().getFullYear();
+    const holder = cfg.author || 'the authors';
+
+    if (cfg.license === 'MIT') files['LICENSE'] = mit(year, holder);
+    else if (cfg.license === 'ISC') files['LICENSE'] = isc(year, holder);
+    else if (cfg.license === 'Apache-2.0') files['LICENSE'] = apacheStub(year, holder);
+
+    if (cfg.community) {
+      files['CONTRIBUTING.md'] = contributing(cfg);
+      files['CODE_OF_CONDUCT.md'] = codeOfConduct(cfg);
+      files['SECURITY.md'] = security();
+      files['.github/ISSUE_TEMPLATE/bug_report.md'] = bugReport();
+      files['.github/ISSUE_TEMPLATE/feature_request.md'] = featureRequest();
+      files['.github/PULL_REQUEST_TEMPLATE.md'] = prTemplate();
+    }
+
+    return { files, pkg: {} };
+  },
+};
+
+function mit(year, holder) {
+  return `MIT License
+
+Copyright (c) ${year} ${holder}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+`;
+}
+
+function isc(year, holder) {
+  return `ISC License
+
+Copyright (c) ${year} ${holder}
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+`;
+}
+
+function apacheStub(year, holder) {
+  return `Copyright ${year} ${holder}
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Full text: https://www.apache.org/licenses/LICENSE-2.0.txt
+`;
+}
+
+function contributing(cfg) {
+  const pm = cfg.packageManager;
+  const install = pm === 'npm' ? 'npm install' : `${pm} install`;
+  return `# Contributing
+
+Thanks for your interest in contributing!
+
+## Development
+
+\`\`\`sh
+${install}
+${pm === 'npm' ? 'npm test' : pm + ' test'}
+\`\`\`
+
+## Pull requests
+
+- Create a branch, make your change, and open a PR against \`main\`.
+- Make sure lint, types and tests pass.
+${cfg.release === 'changesets' ? '- Run `npx changeset` to describe your change for the changelog.\n' : ''}
+`;
+}
+
+function codeOfConduct() {
+  return `# Code of Conduct
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+By participating, you are expected to uphold this code. Report unacceptable
+behavior to the maintainers.
+`;
+}
+
+function security() {
+  return `# Security Policy
+
+If you discover a security vulnerability, please **do not** open a public issue.
+Instead, report it privately to the maintainers (e.g. via GitHub Security
+Advisories). We will respond as quickly as possible.
+`;
+}
+
+function bugReport() {
+  return `---
+name: Bug report
+about: Report a problem
+labels: bug
+---
+
+**Describe the bug**
+
+**To reproduce**
+
+**Expected behavior**
+
+**Environment**
+- Version:
+- Node:
+- OS:
+`;
+}
+
+function featureRequest() {
+  return `---
+name: Feature request
+about: Suggest an idea
+labels: enhancement
+---
+
+**Problem**
+
+**Proposed solution**
+
+**Alternatives considered**
+`;
+}
+
+function prTemplate() {
+  return `## Summary
+
+<!-- What does this change and why? -->
+
+## Checklist
+
+- [ ] Tests pass
+- [ ] Lint & types pass
+- [ ] Docs updated if needed
+`;
+}

package/src/core/features/gitfiles.js

@@ -0,0 +1,50 @@
+// .gitignore, .editorconfig, .npmrc — always-on repo hygiene.
+
+const GITIGNORE = `# dependencies
+node_modules/
+.pnp.*
+.yarn/*
+
+# build output
+dist/
+coverage/
+*.tsbuildinfo
+
+# logs
+*.log
+npm-debug.log*
+
+# env & editor
+.env
+.env.*
+!.env.example
+.DS_Store
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+`;
+
+const EDITORCONFIG = `root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = tab
+
+[*.{json,yml,yaml,md}]
+indent_style = space
+indent_size = 2
+`;
+
+export default {
+  id: 'gitfiles',
+  active: () => true,
+  apply(cfg) {
+    const files = { '.gitignore': GITIGNORE };
+    if (cfg.editorconfig) files['.editorconfig'] = EDITORCONFIG;
+    return { files, pkg: {} };
+  },
+};

package/src/core/features/githooks.js

@@ -0,0 +1,59 @@
+export default {
+  id: 'githooks',
+  active: (cfg) => cfg.gitHooks !== 'none',
+  apply(cfg) {
+    const files = {};
+    const pkg = { scripts: {}, devDependencies: {} };
+    const codeGlob = cfg.isTs ? '*.{js,ts}' : '*.js';
+
+    // What runs on staged files depends on the linter choice.
+    const staged =
+      cfg.lint === 'biome'
+        ? { [codeGlob]: 'biome check --write --no-errors-on-unmatched' }
+        : cfg.lint === 'eslint-prettier'
+          ? { [codeGlob]: ['prettier --write', 'eslint --fix'], '*.{json,md,yml}': 'prettier --write' }
+          : cfg.lint === 'oxlint'
+            ? { [codeGlob]: ['prettier --write', 'oxlint'], '*.{json,md,yml}': 'prettier --write' }
+            : null;
+
+    const needsLintStaged = cfg.gitHooks !== 'lefthook' && staged;
+
+    if (cfg.gitHooks === 'simple-git-hooks') {
+      pkg['simple-git-hooks'] = { 'pre-commit': needsLintStaged ? 'npx lint-staged' : 'npm test' };
+      pkg.scripts.prepare = 'simple-git-hooks';
+      pkg.devDependencies['simple-git-hooks'] = '^2.11.0';
+    } else if (cfg.gitHooks === 'husky') {
+      files['.husky/pre-commit'] = (needsLintStaged ? 'npx lint-staged\n' : 'npm test\n');
+      pkg.scripts.prepare = 'husky';
+      pkg.devDependencies.husky = '^9.1.0';
+    } else if (cfg.gitHooks === 'lefthook') {
+      files['lefthook.yml'] = lefthookYml(cfg, staged);
+      pkg.scripts.prepare = 'lefthook install';
+      pkg.devDependencies.lefthook = '^1.7.0';
+    }
+
+    if (needsLintStaged) {
+      pkg['lint-staged'] = staged;
+      pkg.devDependencies['lint-staged'] = '^15.2.0';
+    }
+
+    return { files, pkg };
+  },
+};
+
+function lefthookYml(cfg, staged) {
+  const cmd =
+    cfg.lint === 'biome'
+      ? 'biome check --write --no-errors-on-unmatched {staged_files}'
+      : cfg.lint === 'none'
+        ? 'npm test'
+        : 'prettier --write {staged_files}';
+  return [
+    'pre-commit:',
+    '  commands:',
+    '    format:',
+    `      glob: '*.{js,ts,json,md}'`,
+    `      run: ${cmd}`,
+    '',
+  ].join('\n');
+}

package/src/core/features/index.js

@@ -0,0 +1,32 @@
+// Feature registry. Order matters only for how package.json fragments merge
+// (later features deep-merge over earlier ones); files are keyed by path.
+
+import meta from './meta.js';
+import bundler from './bundler.js';
+import typescript from './typescript.js';
+import test from './test.js';
+import lint from './lint.js';
+import githooks from './githooks.js';
+import release from './release.js';
+import cli from './cli.js';
+import workflows from './workflows.js';
+import community from './community.js';
+import agents from './agents.js';
+import vscode from './vscode.js';
+import gitfiles from './gitfiles.js';
+
+export default [
+  meta,
+  bundler,
+  typescript,
+  test,
+  lint,
+  githooks,
+  release,
+  cli,
+  workflows,
+  community,
+  agents,
+  vscode,
+  gitfiles,
+];

package/src/core/features/lint.js

@@ -0,0 +1,76 @@
+import { toJson } from '../render.js';
+
+export default {
+  id: 'lint',
+  active: (cfg) => cfg.lint !== 'none',
+  apply(cfg) {
+    const files = {};
+    const pkg = { scripts: {}, devDependencies: {} };
+
+    if (cfg.lint === 'eslint-prettier' || cfg.lint === 'oxlint') {
+      // Prettier is shared by both.
+      files['.prettierrc.json'] = toJson({
+        useTabs: true,
+        singleQuote: true,
+        semi: true,
+        printWidth: 100,
+        trailingComma: 'all',
+      });
+      files['.prettierignore'] = 'dist\ncoverage\n';
+      pkg.scripts.format = 'prettier --write .';
+      pkg.scripts['format:check'] = 'prettier --check .';
+      pkg.devDependencies.prettier = '^3.3.0';
+    }
+
+    if (cfg.lint === 'eslint-prettier') {
+      files['eslint.config.js'] = eslintFlatConfig(cfg);
+      pkg.scripts.lint = 'eslint .';
+      pkg.scripts['lint:fix'] = 'eslint . --fix';
+      pkg.devDependencies.eslint = '^9.0.0';
+      pkg.devDependencies['@eslint/js'] = '^9.0.0';
+      if (cfg.isTs) pkg.devDependencies['typescript-eslint'] = '^8.0.0';
+    } else if (cfg.lint === 'oxlint') {
+      pkg.scripts.lint = 'oxlint';
+      pkg.devDependencies.oxlint = '^0.9.0';
+    } else if (cfg.lint === 'biome') {
+      files['biome.json'] = toJson({
+        $schema: 'https://biomejs.dev/schemas/1.8.0/schema.json',
+        formatter: { enabled: true, indentStyle: 'tab', lineWidth: 100 },
+        linter: { enabled: true, rules: { recommended: true } },
+        javascript: { formatter: { quoteStyle: 'single', trailingCommas: 'all' } },
+      });
+      pkg.scripts.lint = 'biome check .';
+      pkg.scripts['lint:fix'] = 'biome check --write .';
+      pkg.scripts.format = 'biome format --write .';
+      pkg.devDependencies['@biomejs/biome'] = '^1.8.0';
+    }
+
+    return { files, pkg };
+  },
+};
+
+function eslintFlatConfig(cfg) {
+  if (cfg.isTs) {
+    return [
+      `import js from '@eslint/js';`,
+      `import tseslint from 'typescript-eslint';`,
+      ``,
+      `export default tseslint.config(`,
+      `\tjs.configs.recommended,`,
+      `\t...tseslint.configs.recommended,`,
+      `\t{ ignores: ['dist', 'coverage'] },`,
+      `);`,
+      ``,
+    ].join('\n');
+  }
+  return [
+    `import js from '@eslint/js';`,
+    ``,
+    `export default [`,
+    `\tjs.configs.recommended,`,
+    `\t{ languageOptions: { ecmaVersion: 'latest', sourceType: 'module' } },`,
+    `\t{ ignores: ['dist', 'coverage'] },`,
+    `];`,
+    ``,
+  ].join('\n');
+}

package/src/core/features/meta.js

@@ -0,0 +1,99 @@
+// Always-on: base package.json descriptive fields + the source entry + README.
+
+export default {
+  id: 'meta',
+  active: () => true,
+  apply(cfg) {
+    const files = {};
+    const pkg = {
+      name: cfg.name,
+      version: '0.0.0',
+      description: cfg.description || '',
+      type: cfg.moduleFormat === 'cjs' ? 'commonjs' : 'module',
+      engines: { node: `>=${cfg.nodeVersion}` },
+      scripts: {},
+    };
+
+    const kw = String(cfg.keywords || '').split(',').map((s) => s.trim()).filter(Boolean);
+    if (kw.length) pkg.keywords = kw;
+    if (cfg.author) pkg.author = cfg.author;
+    if (cfg.repo) {
+      pkg.repository = { type: 'git', url: `git+${cfg.repo.replace(/\.git$/, '')}.git` };
+      pkg.bugs = { url: `${cfg.repo.replace(/\.git$/, '')}/issues` };
+      pkg.homepage = `${cfg.repo.replace(/\.git$/, '')}#readme`;
+    }
+
+    // Source entry point.
+    const ext = cfg.ext;
+    files[`src/index.${ext}`] = cfg.hasLibrary
+      ? libraryEntry(cfg)
+      : `// ${cfg.name}\n`;
+
+    // README
+    files['README.md'] = readme(cfg);
+
+    // Node version pin
+    files['.nvmrc'] = `${cfg.nodeVersion}\n`;
+
+    // A typecheck script for TS projects regardless of bundler.
+    if (cfg.isTs) pkg.scripts.typecheck = 'tsc --noEmit';
+
+    return { files, pkg };
+  },
+};
+
+function libraryEntry(cfg) {
+  if (cfg.isTs) {
+    return [
+      `/** Greet someone by name. */`,
+      `export function greet(name: string): string {`,
+      `\treturn \`Hello, \${name}!\`;`,
+      `}`,
+      ``,
+    ].join('\n');
+  }
+  return [
+    `/**`,
+    ` * Greet someone by name.`,
+    ` * @param {string} name`,
+    ` * @returns {string}`,
+    ` */`,
+    `export function greet(name) {`,
+    `\treturn \`Hello, \${name}!\`;`,
+    `}`,
+    ``,
+  ].join('\n');
+}
+
+function readme(cfg) {
+  const install = {
+    npm: `npm install ${cfg.name}`,
+    pnpm: `pnpm add ${cfg.name}`,
+    yarn: `yarn add ${cfg.name}`,
+    bun: `bun add ${cfg.name}`,
+  }[cfg.packageManager];
+
+  const lines = [
+    `# ${cfg.name}`,
+    '',
+    cfg.description || '_A modern package scaffolded with [Packkit](https://danmat.github.io/create-packkit/)._',
+    '',
+    '## Install',
+    '',
+    '```sh',
+    install,
+    '```',
+    '',
+  ];
+
+  if (cfg.hasLibrary) {
+    const imp = cfg.isTs || cfg.hasEsm ? `import { greet } from '${cfg.name}';` : `const { greet } = require('${cfg.name}');`;
+    lines.push('## Usage', '', '```' + (cfg.isTs ? 'ts' : 'js'), imp, '', `greet('world'); // "Hello, world!"`, '```', '');
+  }
+  if (cfg.hasCli) {
+    lines.push('## CLI', '', '```sh', `npx ${cfg.name} --help`, '```', '');
+  }
+
+  lines.push('## License', '', cfg.license === 'none' ? 'Unlicensed.' : `${cfg.license}${cfg.author ? ' © ' + cfg.author : ''}`, '');
+  return lines.join('\n');
+}

package/src/core/features/release.js

@@ -0,0 +1,44 @@
+import { toJson } from '../render.js';
+
+export default {
+  id: 'release',
+  active: (cfg) => cfg.release !== 'none',
+  apply(cfg) {
+    const files = {};
+    const pkg = { scripts: {}, devDependencies: {} };
+
+    if (cfg.release === 'changesets') {
+      files['.changeset/config.json'] = toJson({
+        $schema: 'https://unpkg.com/@changesets/config@3.0.0/schema.json',
+        changelog: '@changesets/cli/changelog',
+        commit: false,
+        access: 'public',
+        baseBranch: 'main',
+        updateInternalDependencies: 'patch',
+      });
+      files['.changeset/README.md'] =
+        '# Changesets\n\nRun `npx changeset` to record a version bump for your next release.\n';
+      pkg.scripts.changeset = 'changeset';
+      pkg.scripts.version = 'changeset version';
+      pkg.scripts.release = `${buildThen(cfg)}changeset publish`;
+      pkg.devDependencies['@changesets/cli'] = '^2.27.0';
+    } else if (cfg.release === 'release-it') {
+      files['.release-it.json'] = toJson({
+        git: { commitMessage: 'chore: release v${version}' },
+        github: { release: true },
+        npm: { publish: true },
+      });
+      pkg.scripts.release = 'release-it';
+      pkg.devDependencies['release-it'] = '^17.0.0';
+    } else if (cfg.release === 'np') {
+      pkg.scripts.release = 'np';
+      pkg.devDependencies.np = '^10.0.0';
+    }
+
+    return { files, pkg };
+  },
+};
+
+function buildThen(cfg) {
+  return cfg.bundler !== 'none' || cfg.isTs ? 'npm run build && ' : '';
+}

package/src/core/features/test.js

@@ -0,0 +1,104 @@
+import { toJson } from '../render.js';
+
+export default {
+  id: 'test',
+  active: (cfg) => cfg.test !== 'none',
+  apply(cfg) {
+    const files = {};
+    const pkg = { scripts: {}, devDependencies: {} };
+    const ext = cfg.ext;
+
+    if (cfg.test === 'vitest') {
+      files[`vitest.config.${ext}`] = [
+        `import { defineConfig } from 'vitest/config';`,
+        ``,
+        `export default defineConfig({`,
+        `\ttest: {`,
+        cfg.coverage ? `\t\tcoverage: { provider: 'v8', reporter: ['text', 'lcov'] },` : null,
+        `\t},`,
+        `});`,
+        ``,
+      ].filter((l) => l !== null).join('\n');
+      pkg.scripts.test = 'vitest run';
+      pkg.scripts['test:watch'] = 'vitest';
+      pkg.devDependencies.vitest = '^2.0.0';
+      if (cfg.coverage) {
+        pkg.scripts.coverage = 'vitest run --coverage';
+        pkg.devDependencies['@vitest/coverage-v8'] = '^2.0.0';
+      }
+      files[`src/index.test.${ext}`] = exampleTest('vitest', cfg);
+    } else if (cfg.test === 'jest') {
+      files['jest.config.js'] = jestConfig(cfg);
+      pkg.scripts.test = 'jest';
+      pkg.scripts['test:watch'] = 'jest --watch';
+      pkg.devDependencies.jest = '^29.0.0';
+      if (cfg.isTs) {
+        pkg.devDependencies['ts-jest'] = '^29.0.0';
+        pkg.devDependencies['@types/jest'] = '^29.0.0';
+      }
+      if (cfg.coverage) pkg.scripts.coverage = 'jest --coverage';
+      files[`src/index.test.${ext}`] = exampleTest('jest', cfg);
+    } else if (cfg.test === 'node') {
+      pkg.scripts.test = cfg.isTs ? 'node --import tsx --test "src/**/*.test.ts"' : 'node --test';
+      if (cfg.isTs) pkg.devDependencies.tsx = '^4.0.0';
+      files[`src/index.test.${ext}`] = exampleTest('node', cfg);
+    }
+
+    return { files, pkg };
+  },
+};
+
+function importPath(runner, cfg) {
+  if (!cfg.isTs) return './index.js';
+  if (runner === 'node') return './index.ts';
+  return './index.js';
+}
+
+function exampleTest(runner, cfg) {
+  const imp = importPath(runner, cfg);
+  if (runner === 'node') {
+    return [
+      `import { test } from 'node:test';`,
+      `import assert from 'node:assert/strict';`,
+      `import { greet } from '${imp}';`,
+      ``,
+      `test('greet', () => {`,
+      `\tassert.equal(greet('world'), 'Hello, world!');`,
+      `});`,
+      ``,
+    ].join('\n');
+  }
+  const api = runner === 'jest' ? `` : `import { describe, it, expect } from 'vitest';\n`;
+  const expectApi = runner === 'jest' ? '' : '';
+  return [
+    api + `import { greet } from '${imp}';`,
+    ``,
+    `describe('greet', () => {`,
+    `\tit('greets by name', () => {`,
+    `\t\texpect(greet('world')).toBe('Hello, world!');`,
+    `\t});`,
+    `});`,
+    ``,
+  ].join('\n');
+}
+
+function jestConfig(cfg) {
+  if (cfg.isTs) {
+    return [
+      `/** @type {import('jest').Config} */`,
+      `export default {`,
+      `\tpreset: 'ts-jest/presets/default-esm',`,
+      `\ttestEnvironment: 'node',`,
+      `\textensionsToTreatAsEsm: ['.ts'],`,
+      `};`,
+      ``,
+    ].join('\n');
+  }
+  return [
+    `/** @type {import('jest').Config} */`,
+    `export default {`,
+    `\ttestEnvironment: 'node',`,
+    `};`,
+    ``,
+  ].join('\n');
+}

package/src/core/features/typescript.js

@@ -0,0 +1,48 @@
+import { toJson } from '../render.js';
+
+export default {
+  id: 'typescript',
+  active: (cfg) => cfg.isTs,
+  apply(cfg) {
+    const noBuild = cfg.bundler === 'none';
+    const compilerOptions = {
+      target: 'ES2022',
+      module: 'ESNext',
+      moduleResolution: 'Bundler',
+      lib: ['ES2022'],
+      strict: true,
+      noUncheckedIndexedAccess: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      forceConsistentCasingInFileNames: true,
+      verbatimModuleSyntax: cfg.bundler !== 'none',
+      declaration: true,
+    };
+    if (noBuild) {
+      // tsc is the build: emit to dist.
+      compilerOptions.moduleResolution = 'NodeNext';
+      compilerOptions.module = 'NodeNext';
+      compilerOptions.outDir = 'dist';
+      compilerOptions.rootDir = 'src';
+    } else {
+      compilerOptions.noEmit = true;
+    }
+
+    return {
+      files: {
+        'tsconfig.json': toJson({
+          $schema: 'https://json.schemastore.org/tsconfig',
+          compilerOptions,
+          include: ['src'],
+          exclude: ['dist', 'node_modules'],
+        }),
+      },
+      pkg: {
+        devDependencies: {
+          typescript: '^5.5.0',
+          '@types/node': `^${cfg.nodeVersion}.0.0`,
+        },
+      },
+    };
+  },
+};