@amedia/create-kragl 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @amedia/create-kragl
+
+## 1.0.0
+
+### Major Changes
+
+- 94884aa: Add `@amedia/create-kragl`, which sets up kragl in a project with `npm init @amedia/kragl@latest`: it installs the packages, writes the config files and adds the lint and format scripts.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @amedia/create-kragl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sets up [kragl](../kragl) in a project:
+
+```sh
+npm init @amedia/kragl@latest
+```
+
+In the current directory it:
+
+1. Creates a `package.json` if there is none, as an ES module package.
+2. Installs `@amedia/kragl` and `@amedia/kragl-lockfile-lint` as exact
+   dev dependencies.
+3. Writes `eslint.config.js` and `prettier.config.js` with `kragl install`.
+4. Adds the `format`, `lint` and `lint:fix` scripts.
+
+Running it again only adds what is missing. It never changes an existing
+script or dependency, and keeps existing config files unless `--force` is
+given. Only npm projects are supported: it stops if it finds a Yarn, pnpm or
+Bun lockfile.
+
+`@latest` makes npm fetch the newest version instead of a copy installed
+earlier.
+
+## Options
+
+npm passes options after `--` on to `create-kragl`:
+
+```sh
+npm init @amedia/kragl@latest -- --biome --ls-lint
+```
+
+| Option               | Effect                                                                                       |
+| -------------------- | -------------------------------------------------------------------------------------------- |
+| `--biome`            | Use [Biome](../kragl-biome): installs `@amedia/kragl-cli` and `@amedia/kragl-biome` instead. |
+| `--no-lockfile-lint` | Leave out [lockfile-lint](../kragl-lockfile-lint).                                           |
+| `--ls-lint`          | Add [ls-lint](../kragl-ls-lint).                                                             |
+| `--browserslist`     | Add [Browserslist](../kragl-browserslist).                                                   |
+| `-f, --force`        | Overwrite existing config files.                                                             |
+
+A project that already has `@amedia/kragl-biome` stays on Biome without
+`--biome`.
+
+## Notes
+
+Requires Node 22+.

package/bin/create-kragl.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@amedia/create-kragl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Set up kragl in a project with `npm init @amedia/kragl`",
+  "bin": {
+    "create-kragl": "bin/create-kragl.js"
+  },
+  "type": "module",
+  "files": [
+    "*"
+  ],
+  "scripts": {
+    "test": "node --test 'src/*-test.js'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amedia/eslint-config-amedia.git"
+  },
+  "keywords": [
+    "kragl"
+  ],
+  "author": "Amedia",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/amedia/eslint-config-amedia/issues"
+  },
+  "homepage": "https://github.com/amedia/eslint-config-amedia#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/cli.js

@@ -0,0 +1,154 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+
+import { plan } from './plan.js';
+
+const HELP = `Usage: npm init @amedia/kragl@latest -- [options]
+
+Installs kragl in the project in the current directory, writes its config
+files and adds the lint and format scripts. Running it again only adds what
+is missing.
+
+Options:
+  --biome              use Biome instead of ESLint and Prettier
+  --no-lockfile-lint   leave out the lockfile-lint runner
+  --ls-lint            add the ls-lint runner
+  --browserslist       add the Browserslist runner
+  -f, --force          overwrite existing config files
+  -h, --help           print this help text`;
+
+// Lockfiles of the package managers kragl does not support.
+const FOREIGN_LOCKFILES = [
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'bun.lock',
+  'bun.lockb',
+];
+
+const fail = (message) => {
+  console.error(`create-kragl: ${message}`);
+  process.exit(1);
+};
+
+const npm = (args) =>
+  spawnSync('npm', args, {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  }).status === 0;
+
+const readPackageJson = () => JSON.parse(readFileSync('package.json', 'utf8'));
+
+// Keeps the file's own indentation, the way npm does when it writes it.
+const addScripts = (scripts) => {
+  const text = readFileSync('package.json', 'utf8');
+  const indent = text.match(/^[ \t]+/m)?.[0] ?? 2;
+  const packageJson = JSON.parse(text);
+
+  packageJson.scripts = { ...packageJson.scripts, ...scripts };
+  writeFileSync(
+    'package.json',
+    `${JSON.stringify(packageJson, null, indent)}\n`
+  );
+};
+
+let values;
+
+try {
+  ({ values } = parseArgs({
+    options: {
+      biome: { type: 'boolean', default: false },
+      'no-lockfile-lint': { type: 'boolean', default: false },
+      'ls-lint': { type: 'boolean', default: false },
+      browserslist: { type: 'boolean', default: false },
+      force: { type: 'boolean', short: 'f', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  }));
+} catch (error) {
+  fail(`${error.message}\n\n${HELP}`);
+}
+
+if (values.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const foreign = FOREIGN_LOCKFILES.find((file) => existsSync(file));
+
+if (foreign) {
+  fail(`found ${foreign}; kragl supports npm projects only.`);
+}
+
+// The config files kragl writes are ES modules, and npm 11 makes new packages
+// CommonJS unless told otherwise.
+if (
+  !existsSync('package.json') &&
+  !npm(['init', '--yes', '--init-type=module'])
+) {
+  fail('npm init failed.');
+}
+
+const { packages, configs, scripts } = plan(readPackageJson(), {
+  biome: values.biome,
+  'lockfile-lint': !values['no-lockfile-lint'],
+  'ls-lint': values['ls-lint'],
+  browserslist: values.browserslist,
+});
+
+if (
+  packages.length > 0 &&
+  !npm(['install', '--save-dev', '--save-exact', ...packages])
+) {
+  fail('npm install failed.');
+}
+
+// Existing config files are kept unless --force. `--no` makes npm use the
+// kragl just installed and never fetch one from the registry.
+const kept = values.force
+  ? []
+  : configs.filter(({ filename }) => existsSync(filename));
+const failed = configs
+  .filter((config) => !kept.includes(config))
+  .filter(
+    ({ tool }) =>
+      !npm([
+        'exec',
+        '--no',
+        '--',
+        'kragl',
+        'install',
+        `--${tool}`,
+        ...(values.force ? ['--force'] : []),
+      ])
+  );
+
+const scriptNames = Object.keys(scripts);
+
+if (scriptNames.length > 0) {
+  addScripts(scripts);
+}
+
+console.log('');
+console.log(
+  packages.length > 0
+    ? `Installed ${packages.join(', ')}.`
+    : 'All kragl packages were already installed.'
+);
+
+if (scriptNames.length > 0) {
+  console.log(`Added scripts: ${scriptNames.join(', ')}.`);
+}
+
+if (kept.length > 0) {
+  const filenames = kept.map(({ filename }) => filename).join(', ');
+  console.log(`Kept ${filenames}; re-run with --force to replace.`);
+}
+
+if (failed.length > 0) {
+  const tools = failed.map(({ tool }) => tool).join(', ');
+  fail(`kragl install failed for ${tools}, see above.`);
+}
+
+console.log('Run `npm run lint` to lint the project.');

package/src/plan-test.js

@@ -0,0 +1,76 @@
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { plan, SCRIPTS } from './plan.js';
+
+const defaults = { 'lockfile-lint': true };
+
+describe('plan', () => {
+  test('sets up ESLint, Prettier and lockfile-lint in an empty project', () => {
+    assert.deepEqual(plan({}, defaults), {
+      packages: ['@amedia/kragl', '@amedia/kragl-lockfile-lint'],
+      configs: [
+        { tool: 'eslint', filename: 'eslint.config.js' },
+        { tool: 'prettier', filename: 'prettier.config.js' },
+      ],
+      scripts: SCRIPTS,
+    });
+  });
+
+  test('sets up Biome without ESLint and Prettier', () => {
+    const { packages, configs } = plan({}, { ...defaults, biome: true });
+
+    assert.deepEqual(packages, [
+      '@amedia/kragl-cli',
+      '@amedia/kragl-biome',
+      '@amedia/kragl-lockfile-lint',
+    ]);
+    assert.deepEqual(configs, [{ tool: 'biome', filename: 'biome.json' }]);
+  });
+
+  test('stays on Biome when kragl-biome is installed', () => {
+    const packageJson = {
+      devDependencies: {
+        '@amedia/kragl-cli': '1.0.1',
+        '@amedia/kragl-biome': '1.3.1',
+      },
+    };
+
+    assert.deepEqual(plan(packageJson, defaults), {
+      packages: ['@amedia/kragl-lockfile-lint'],
+      configs: [{ tool: 'biome', filename: 'biome.json' }],
+      scripts: SCRIPTS,
+    });
+  });
+
+  test('adds the opt-in runners and leaves out lockfile-lint', () => {
+    const { packages } = plan(
+      {},
+      { 'lockfile-lint': false, 'ls-lint': true, browserslist: true }
+    );
+
+    assert.deepEqual(packages, [
+      '@amedia/kragl',
+      '@amedia/kragl-ls-lint',
+      '@amedia/kragl-browserslist',
+    ]);
+  });
+
+  test('skips packages in dependencies or devDependencies', () => {
+    const packageJson = {
+      dependencies: { '@amedia/kragl': '6.4.0' },
+      devDependencies: { '@amedia/kragl-lockfile-lint': '1.0.0' },
+    };
+
+    assert.deepEqual(plan(packageJson, defaults).packages, []);
+  });
+
+  test('keeps existing scripts', () => {
+    const packageJson = { scripts: { lint: 'eslint .' } };
+
+    assert.deepEqual(plan(packageJson, defaults).scripts, {
+      format: 'kragl format',
+      'lint:fix': 'kragl lint --fix',
+    });
+  });
+});

package/src/plan.js

@@ -0,0 +1,65 @@
+// Runners a project can opt into on top of the base setup, by flag name.
+export const RUNNERS = {
+  'lockfile-lint': '@amedia/kragl-lockfile-lint',
+  'ls-lint': '@amedia/kragl-ls-lint',
+  browserslist: '@amedia/kragl-browserslist',
+};
+
+// The base setups, and the config file `kragl install --<tool>` writes for
+// each of their tools.
+const BASES = {
+  kragl: {
+    packages: ['@amedia/kragl'],
+    configs: [
+      { tool: 'eslint', filename: 'eslint.config.js' },
+      { tool: 'prettier', filename: 'prettier.config.js' },
+    ],
+  },
+  biome: {
+    packages: ['@amedia/kragl-cli', '@amedia/kragl-biome'],
+    configs: [{ tool: 'biome', filename: 'biome.json' }],
+  },
+};
+
+export const SCRIPTS = {
+  format: 'kragl format',
+  lint: 'kragl lint',
+  'lint:fix': 'kragl lint --fix',
+};
+
+/**
+ * Works out what `create-kragl` has to do in a project, leaving out what is
+ * already there, so running it again only fills in what is missing.
+ *
+ * @param {Object} packageJson - The project's package.json.
+ * @param {Object} options - The parsed flags: `biome` and one per runner.
+ * @returns {{ packages: string[], configs: Object[], scripts: Object }}
+ */
+export function plan(packageJson, options) {
+  const installed = new Set(
+    Object.keys({
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies,
+    })
+  );
+
+  // A project already on Biome stays on Biome without passing --biome again.
+  const base =
+    options.biome || installed.has('@amedia/kragl-biome')
+      ? BASES.biome
+      : BASES.kragl;
+
+  const runners = Object.keys(RUNNERS)
+    .filter((name) => options[name])
+    .map((name) => RUNNERS[name]);
+
+  const packages = [...base.packages, ...runners].filter(
+    (name) => !installed.has(name)
+  );
+
+  const scripts = Object.fromEntries(
+    Object.entries(SCRIPTS).filter(([name]) => !packageJson.scripts?.[name])
+  );
+
+  return { packages, configs: base.configs, scripts };
+}