create-pkgbld 1.8.2 → 2.0.1

package/README.md

@@ -1,22 +1,97 @@
 # create-pkgbld
 
-Minimalistic scaffolding utility for [pkgbld](https://github.com/kshutkin/package-build/tree/main/pkgbld).
-
-*Disclaimer:* Despite the version being 1.0.0+ it is still very raw, use only if it fits your needs.
-
-[Changelog](./CHANGELOG.md)
+Scaffold packages built with [PKG BLD](https://github.com/kshutkin/package-build/tree/main/pkgbld) and manage their build plugins and project setup extensions.
 
 ## Usage
 
-```
+```sh
 npm init pkgbld
+npm init pkgbld <directory>
 ```
 
-or
+For a new package, `create-pkgbld` generates the initial package metadata and
+README. In an existing package, it opens the interactive package manager for
+adding, removing, or adopting integrations. Pending changes are shown before
+they are written.
+
+Use `--quiet` (`-q`) to suppress informational output and the interactive
+package manager. Use `--install` to run the detected package manager after
+dependency changes.
+
+## Package management
+
+| Command | Behavior |
+|---|---|
+| `create-pkgbld list` | List official integrations, locked integrations, and modern plugins declared by the project. Listing is offline and does not change the project. |
+| `create-pkgbld add <package>` | Apply an official integration, restore a locked one, or adopt an installed unmanaged plugin. |
+| `create-pkgbld remove <package>` | Remove an integration and its project-lock entry. Unregistered plugins are removed from every dependency field. |
+| `create-pkgbld update <package>` | Update one managed official integration to the newest stable version allowed by its registry range. |
+
+Package names may be registry names such as `biome` and
+`pkgbld-dts-buddy`, or the full name of a discovered plugin.
+
+### Flags
+
+| Flag | Description |
+|---|---|
+| `--yes`, `-y` | Use extension prompt defaults. It does not approve update conflicts. |
+| `--dry-run` | Resolve and display changes without writing the project or installing dependencies. |
+| `--quiet`, `-q` | Suppress informational output. |
+| `--install` | Run the detected package manager after add, remove, or extension-update dependency changes. |
+| `--accept-conflicts` | Update only: accept proposed replacements for resources customized since the locked version. |
 
+Build plugin updates always install and verify the exact target version before
+advancing the project lock, regardless of `--install`.
+
+```sh
+create-pkgbld add biome --yes --dry-run
+create-pkgbld add biome --yes --install
+create-pkgbld remove biome --yes
+create-pkgbld update biome --dry-run
+create-pkgbld update biome --yes --accept-conflicts
 ```
-npm init pkgbld <folder name>
+
+## Official integrations
+
+| Name | Purpose |
+|---|---|
+| `biome` | Biome linting and formatting |
+| `pkgbld-swc` | TypeScript stripping through `pkgbld-plugin-swc` |
+| `dts-buddy` | Standalone declaration bundling |
+| `pkgbld-dts-buddy` | Declaration bundling through `pkgbld-plugin-dts-buddy` |
+
+The bundled registry contains metadata only. Selected extension versions are
+downloaded into a version-isolated shared cache located with
+`find-cache-directory`; set `CREATE_PKGBLD_CACHE_DIR` to override its location.
+Extension packages are not added to the target project. Build plugins and tools
+configured by an extension are normal project dependencies.
+
+Applied or adopted integrations are recorded by canonical package name and
+exact version in the committed `.pkgbld-lock.json`:
+
+```json
+{
+  "$schema": "https://unpkg.com/create-pkgbld/lock-schema-v1.json",
+  "packages": {
+    "create-pkgbld-extension-biome": "0.1.1",
+    "@author/pkgbld-plugin-example": "2.1.0"
+  }
+}
 ```
-# License
 
-[MIT](https://github.com/kshutkin/package-build/blob/main/LICENSE)
+Plugins named `pkgbld-plugin-*` or `@scope/pkgbld-plugin-*` are discovered in
+`dependencies`, `devDependencies`, and `peerDependencies` without executing
+their code. A manageable plugin must declare a `pkgbld` range in
+`peerDependencies`. The range is validated before add and update; legacy or
+unresolved plugins are excluded with an actionable warning.
+
+Updates compare the locked extension contract, the current project, and the
+target contract. Unchanged resources update automatically. Customized
+resources are displayed as conflicts and require interactive approval or
+`--accept-conflicts`.
+
+See the [PKG BLD plugin interface](https://github.com/kshutkin/package-build/blob/main/pkgbld/README.md#build-plugin-interface) for build plugin authoring,
+[EXTENSIONS.md](./EXTENSIONS.md) for optional project setup behavior, and
+[DESIGN.md](./DESIGN.md) for package-management semantics.
+
+[Changelog](./CHANGELOG.md) · [License](https://github.com/kshutkin/package-build/blob/main/LICENSE)

package/extensions-schema.json

@@ -0,0 +1,53 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "create-pkgbld extension registry",
+    "description": "Registry file describing extensions available to create-pkgbld.",
+    "type": "object",
+    "required": ["extensions"],
+    "additionalProperties": false,
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "description": "Optional schema reference."
+        },
+        "extensions": {
+            "type": "array",
+            "description": "List of extensions exposed by this registry.",
+            "items": { "$ref": "#/definitions/extensionEntry" }
+        }
+    },
+    "definitions": {
+        "extensionEntry": {
+            "type": "object",
+            "required": ["name", "package", "description"],
+            "additionalProperties": false,
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Unique extension name as referenced from CLI (e.g. `create-pkgbld add <name>`)."
+                },
+                "package": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "^(?:@[a-z0-9][a-z0-9._~-]*/)?(?:create-pkgbld-extension-|pkgbld-plugin-)[a-z0-9][a-z0-9._~-]*(?:/extension)?$",
+                    "description": "Canonical create-pkgbld extension package or PKG BLD plugin, optionally with /extension."
+                },
+                "version": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Version range installed in the shared extension cache. Defaults to latest."
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Short human description shown in the list / TUI."
+                },
+                "tags": {
+                    "type": "array",
+                    "description": "Optional tags for grouping/filtering.",
+                    "items": { "type": "string", "minLength": 1 }
+                }
+            }
+        }
+    }
+}

package/extensions.json

@@ -0,0 +1,33 @@
+{
+    "$schema": "./extensions-schema.json",
+    "extensions": [
+        {
+            "name": "biome",
+            "package": "create-pkgbld-extension-biome",
+            "version": "^0.1.0",
+            "description": "Biome linter and formatter",
+            "tags": ["linter", "formatter"]
+        },
+        {
+            "name": "pkgbld-swc",
+            "package": "pkgbld-plugin-swc/extension",
+            "version": "^1.0.0",
+            "description": "SWC TypeScript stripping via pkgbld",
+            "tags": ["plugin", "typescript", "pkgbld"]
+        },
+        {
+            "name": "pkgbld-dts-buddy",
+            "package": "pkgbld-plugin-dts-buddy/extension",
+            "version": "^1.0.0",
+            "description": "Generate d.ts files using dts-buddy",
+            "tags": ["plugin", "types", "pkgbld"]
+        },
+        {
+            "name": "dts-buddy",
+            "package": "create-pkgbld-extension-dts-buddy",
+            "version": "^0.1.0",
+            "description": "Standalone d.ts bundling using dts-buddy",
+            "tags": ["types"]
+        }
+    ]
+}

package/index.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-'use strict';
-import('./dist/index.mjs');
+
+import('./src/index.js');

package/lock-schema-v1.json

@@ -0,0 +1,26 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://unpkg.com/create-pkgbld/lock-schema-v1.json",
+    "title": "create-pkgbld lock file, version 1",
+    "description": "Records PKG BLD integrations acknowledged as applied to a project.",
+    "type": "object",
+    "required": ["$schema", "packages"],
+    "additionalProperties": false,
+    "properties": {
+        "$schema": {
+            "const": "https://unpkg.com/create-pkgbld/lock-schema-v1.json"
+        },
+        "packages": {
+            "type": "object",
+            "description": "Canonical npm package names mapped to exact applied versions.",
+            "propertyNames": {
+                "type": "string",
+                "pattern": "^(?:@[a-z0-9][a-z0-9._~-]*/)?(?:create-pkgbld-extension-|pkgbld-plugin-)[a-z0-9][a-z0-9._~-]*$"
+            },
+            "additionalProperties": {
+                "type": "string",
+                "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+            }
+        }
+    }
+}

package/package.json

@@ -1,11 +1,18 @@
 {
-  "version": "1.8.2",
+  "version": "2.0.1",
   "name": "create-pkgbld",
   "license": "MIT",
   "author": "Konstantin Shutkin",
   "bin": "./index.js",
-  "main": "./dist/index.mjs",
+  "main": "./src/index.js",
   "type": "module",
+  "files": [
+    "src",
+    "index.js",
+    "extensions.json",
+    "extensions-schema.json",
+    "lock-schema-v1.json"
+  ],
   "engines": {
     "node": ">=20"
   },
@@ -23,12 +30,20 @@
     "init"
   ],
   "dependencies": {
-    "string-argv": "0.3.2",
-    "git-user-name": "2.0.0",
-    "cleye": "1.3.4",
-    "parse-git-config": "3.0.0",
+    "@niceties/ansi": "^1.1.2",
+    "@niceties/node-parseargs-plus": "^0.6.0",
+    "find-cache-directory": "^6.0.0",
     "prompts": "2.4.2",
-    "kleur": "4.1.5",
-    "lodash": "4.17.21"
+    "semver": "7.8.5",
+    "pkgbld": "2.1.0"
+  },
+  "devDependencies": {
+    "@types/prompts": "2.4.9",
+    "@types/semver": "7.8.0",
+    "dts-buddy": "^0.8.3"
+  },
+  "scripts": {
+    "build": "echo 'no build needed'",
+    "test": "node --test 'test/*.test.js'"
   }
 }

package/src/conflicts.js

@@ -0,0 +1,21 @@
+/**
+ * Format conflicts for printing. Returns lines with a leading marker.
+ * @param {readonly import('./project-changes.js').Conflict[]} conflicts
+ * @returns {string[]}
+ */
+export function formatConflicts(conflicts) {
+    return conflicts.map(conflict => {
+        const source = `(from: ${[...new Set(conflict.sources)].join(', ')})`;
+        if (conflict.kind !== 'migration-conflict') return `  ⚠ ${conflict.message} ${source}`;
+        return `  ⚠ ${conflict.message}; expected ${formatValue(conflict.expected)}, found ${formatValue(
+            conflict.current
+        )}, proposed ${formatValue(conflict.proposed)} ${source}`;
+    });
+}
+
+/** @param {unknown} value */
+function formatValue(value) {
+    if (value === undefined) return '<absent>';
+    const json = JSON.stringify(value);
+    return json && json.length > 120 ? `${json.slice(0, 117)}...` : (json ?? String(value));
+}

package/src/diff.js

@@ -0,0 +1,83 @@
+import { blue, gray, green, red, white, yellow } from '@niceties/ansi';
+
+/**
+ * @typedef {import('./tree.js').FileChange} FileChange
+ */
+
+/**
+ * Render an accumulated set of FileChanges as a colored, file-by-file diff
+ * suitable for printing before commit (or for --dry-run output).
+ *
+ * Pure: returns a string with no trailing newline; the caller decides
+ * whether to wrap with headers or pipe through console.log.
+ *
+ * @param {readonly FileChange[]} changes
+ * @param {{ projectRoot?: string, readDiskJson?: (path: string) => any | null }} [opts]
+ * @returns {string}
+ */
+export function renderChanges(changes, opts = {}) {
+    if (changes.length === 0) return gray('  (no changes)');
+    const lines = [];
+    for (const c of changes) {
+        const tag = c.type === 'CREATE' ? green('CREATE') : c.type === 'UPDATE' ? yellow('UPDATE') : red('DELETE');
+        lines.push(`  ${tag}  ${white(c.path)}`);
+        if (c.type === 'UPDATE' && c.path.endsWith('package.json') && typeof c.content === 'string') {
+            const before = opts.readDiskJson?.(c.path) ?? null;
+            const after = safeParseJson(c.content);
+            if (before && after) {
+                const keyLines = describePackageJsonDiff(before, after);
+                for (const kl of keyLines) lines.push(`         ${kl}`);
+            }
+        } else if (c.type === 'DELETE') {
+            lines.push(`         ${gray('(file removed)')}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+/**
+ * @param {string} text
+ */
+function safeParseJson(text) {
+    try {
+        return JSON.parse(text);
+    } catch {
+        return null;
+    }
+}
+
+const PKG_GROUPS = ['dependencies', 'devDependencies', 'peerDependencies', 'scripts'];
+
+/**
+ * @param {Record<string, any>} before
+ * @param {Record<string, any>} after
+ * @returns {string[]}
+ */
+function describePackageJsonDiff(before, after) {
+    /** @type {string[]} */
+    const out = [];
+    for (const group of PKG_GROUPS) {
+        const b = before[group] ?? {};
+        const a = after[group] ?? {};
+        const keys = new Set([...Object.keys(b), ...Object.keys(a)]);
+        for (const k of keys) {
+            if (b[k] === a[k]) continue;
+            if (!(k in b)) {
+                out.push(`${green('+')} ${gray(group)}.${white(k)} ${gray('=')} ${green(String(a[k]))}`);
+            } else if (!(k in a)) {
+                out.push(`${red('-')} ${gray(group)}.${white(k)}`);
+            } else {
+                out.push(`${blue('~')} ${gray(group)}.${white(k)} ${gray(String(b[k]))} ${gray('→')} ${white(String(a[k]))}`);
+            }
+        }
+    }
+    const topKeys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const k of topKeys) {
+        if (PKG_GROUPS.includes(k)) continue;
+        if (JSON.stringify(before[k]) === JSON.stringify(after[k])) continue;
+        if (!(k in before)) out.push(`${green('+')} ${white(k)}`);
+        else if (!(k in after)) out.push(`${red('-')} ${white(k)}`);
+        else out.push(`${blue('~')} ${white(k)}`);
+    }
+    return out;
+}

package/src/engine.js

@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * @typedef {import('./tree.js').Tree} Tree
+ * @typedef {import('./registry.js').Extension} Extension
+ * @typedef {import('./registry.js').SetupDeclarative} SetupDeclarative
+ * @typedef {import('./registry.js').RemoveDeclarative} RemoveDeclarative
+ * @typedef {import('./types.js').OptionsValue} OptionsValue
+ */
+
+/**
+ * Run an extension's setup against the given tree.
+ *
+ * @param {Extension} extension
+ * @param {Tree} tree
+ * @param {OptionsValue} [options]
+ */
+export async function runSetup(extension, tree, options = {}) {
+    if (!extension.setup) return;
+    tree.setExtensionBase(extension.__baseDir ?? null);
+    try {
+        if (typeof extension.setup === 'function') {
+            await extension.setup(tree, options);
+        } else {
+            applyDeclarativeSetup(extension.setup, tree);
+        }
+    } finally {
+        tree.setExtensionBase(null);
+    }
+}
+
+/**
+ * Run an extension's remove against the given tree.
+ *
+ * @param {Extension} extension
+ * @param {Tree} tree
+ * @param {OptionsValue} [options]
+ */
+export async function runRemove(extension, tree, options = {}) {
+    if (!extension.remove) return;
+    tree.setExtensionBase(extension.__baseDir ?? null);
+    try {
+        if (typeof extension.remove === 'function') {
+            await extension.remove(tree, options);
+        } else {
+            applyDeclarativeRemove(extension.remove, tree);
+        }
+    } finally {
+        tree.setExtensionBase(null);
+    }
+}
+
+/**
+ * @param {Extension} extension
+ * @param {Tree} tree
+ */
+export function detectExtension(extension, tree) {
+    if (typeof extension.detect !== 'function') return false;
+    return Boolean(extension.detect(tree));
+}
+
+/**
+ * @param {SetupDeclarative} setup
+ * @param {Tree} tree
+ */
+function applyDeclarativeSetup(setup, tree) {
+    if (setup.dependencies) {
+        for (const [name, version] of Object.entries(setup.dependencies)) {
+            tree.addDependency(name, version, 'dependencies');
+        }
+    }
+    if (setup.devDependencies) {
+        for (const [name, version] of Object.entries(setup.devDependencies)) {
+            tree.addDependency(name, version, 'devDependencies');
+        }
+    }
+    if (setup.scripts) {
+        for (const [name, command] of Object.entries(setup.scripts)) {
+            tree.addScript(name, command);
+        }
+    }
+    if (setup.files) {
+        for (const [target, source] of Object.entries(setup.files)) {
+            if (source.startsWith('inline:')) {
+                tree.write(target, source.slice('inline:'.length));
+            } else {
+                const abs = tree.resolveExtensionFile(source);
+                tree.write(target, readFileSync(abs, 'utf8'));
+            }
+        }
+    }
+    if (setup.packageJson) {
+        const extra = setup.packageJson;
+        tree.updateJson('package.json', pkg => {
+            for (const [key, value] of Object.entries(extra)) {
+                pkg[key] = value;
+            }
+            return pkg;
+        });
+    }
+}
+
+/**
+ * @param {RemoveDeclarative} remove
+ * @param {Tree} tree
+ */
+function applyDeclarativeRemove(remove, tree) {
+    if (remove.dependencies) {
+        for (const name of remove.dependencies) tree.removeDependency(name, 'dependencies');
+    }
+    if (remove.devDependencies) {
+        for (const name of remove.devDependencies) tree.removeDependency(name, 'devDependencies');
+    }
+    if (remove.scripts) {
+        for (const name of remove.scripts) tree.removeScript(name);
+    }
+    if (remove.files) {
+        for (const file of remove.files) tree.delete(file);
+    }
+}

package/src/extension-cache.js

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import findCacheDirectory from 'find-cache-directory';
+import semver from 'semver';
+
+import { resolvePublishedVersion } from './package-version.js';
+
+/** @returns {string} */
+export function getExtensionCacheDir() {
+    if (process.env.CREATE_PKGBLD_CACHE_DIR) return path.resolve(process.env.CREATE_PKGBLD_CACHE_DIR);
+    const cacheDir = findCacheDirectory({ name: 'create-pkgbld', cwd: import.meta.dirname });
+    if (!cacheDir) throw new Error('Cannot locate a shared cache directory for create-pkgbld');
+    return path.join(cacheDir, 'extensions');
+}
+
+/**
+ * Return the installable package name from a package or package/subpath specifier.
+ * Relative and absolute paths are intentionally not installable.
+ * @param {string} specifier
+ */
+export function getPackageName(specifier) {
+    if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('file:')) return null;
+    const parts = specifier.split('/');
+    if (specifier.startsWith('@')) return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null;
+    return parts[0] || null;
+}
+
+/** @param {string} packageName @param {string} version @param {string} [cacheRoot] */
+export function getExtensionCacheSlot(packageName, version, cacheRoot = getExtensionCacheDir()) {
+    return path.join(cacheRoot, encodeURIComponent(packageName), version);
+}
+
+/**
+ * Return cached exact-version roots newest first.
+ * @param {string} packageName
+ * @param {string | undefined} selector
+ * @param {string} [cacheRoot]
+ */
+export async function listCachedExtensionSlots(packageName, selector, cacheRoot = getExtensionCacheDir()) {
+    const packageRoot = path.join(cacheRoot, encodeURIComponent(packageName));
+    let versions;
+    try {
+        versions = await readdir(packageRoot);
+    } catch {
+        return [];
+    }
+    return semver
+        .rsort(versions.filter(version => semver.valid(version) && (!selector || semver.satisfies(version, selector))))
+        .map(version => ({ version, cacheDir: getExtensionCacheSlot(packageName, version, cacheRoot) }));
+}
+
+/**
+ * Install one exact extension version in an immutable shared-cache slot.
+ * A range is resolved before the slot is selected.
+ * @param {{ package: string, version?: string }} entry
+ * @param {string} [cacheRoot]
+ * @param {(command: string, args: string[], cwd: string) => Promise<number>} [runner]
+ * @param {(packageName: string, selector: string) => Promise<string>} [versionResolver]
+ */
+export async function installCachedExtension(
+    entry,
+    cacheRoot = getExtensionCacheDir(),
+    runner = runCommand,
+    versionResolver = resolvePublishedVersion
+) {
+    const packageName = getPackageName(entry.package);
+    if (!packageName) throw new Error(`Extension package "${entry.package}" cannot be installed in the shared cache`);
+
+    const selector = entry.version ?? 'latest';
+    const exactVersion = semver.valid(selector) ?? (await versionResolver(packageName, selector));
+    const cacheDir = getExtensionCacheSlot(packageName, exactVersion, cacheRoot);
+    const manifestPath = path.join(cacheDir, 'package.json');
+    const packageManifest = path.join(cacheDir, 'node_modules', packageName, 'package.json');
+    if (await hasCachedPackage(packageManifest, exactVersion)) return { cacheDir, version: exactVersion };
+
+    await mkdir(cacheDir, { recursive: true });
+    const manifest = { private: true, dependencies: { [packageName]: exactVersion } };
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+    const code = await runner('npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund'], cacheDir);
+    if (code !== 0) {
+        await writeFile(manifestPath, `${JSON.stringify({ private: true, dependencies: {} }, null, 2)}\n`);
+        throw new Error(`Failed to cache extension package "${packageName}@${exactVersion}" (npm install exited with code ${code})`);
+    }
+    if (!(await hasCachedPackage(packageManifest, exactVersion))) {
+        throw new Error(`npm install completed without caching extension package "${packageName}@${exactVersion}"`);
+    }
+    return { cacheDir, version: exactVersion };
+}
+
+/** @param {string} manifestPath @param {string} exactVersion */
+async function hasCachedPackage(manifestPath, exactVersion) {
+    try {
+        const installed = JSON.parse(await readFile(manifestPath, 'utf8'));
+        return installed.version === exactVersion;
+    } catch {
+        return false;
+    }
+}
+
+/** @param {string} command @param {string[]} args @param {string} cwd */
+function runCommand(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
+        child.on('error', reject);
+        child.on('close', code => resolve(code ?? 1));
+    });
+}

package/src/{get-git-root.ts → get-git-root.js}

@@ -5,4 +5,4 @@ export default async function getGitRoot() {
     const exec = util.promisify(childProcess.exec);
     const { stdout } = await exec('git rev-parse --show-toplevel');
     return stdout.trim();
-}
+}