create-pkgbld 1.8.2 → 2.0.0

package/src/index.js

@@ -0,0 +1,257 @@
+import { execFileSync } from 'node:child_process';
+import fsSync from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { isPackageJson, processPackageJson, toFormattedJson } from 'pkgbld/options';
+import prompts from 'prompts';
+
+import { gray, green, red, white, yellow } from '@niceties/ansi';
+import { parseArgsPlus } from '@niceties/node-parseargs-plus';
+import { help } from '@niceties/node-parseargs-plus/help';
+import { parameters } from '@niceties/node-parseargs-plus/parameters';
+
+import { formatConflicts } from './conflicts.js';
+import { renderChanges } from './diff.js';
+import getGitRoot from './get-git-root.js';
+import { changesAffectDependencies, detectPackageManager, runInstall } from './install.js';
+import { openPackageOperations } from './package-operations.js';
+import { ProjectChanges } from './project-changes.js';
+import { loadRegistry } from './registry.js';
+import { runAdd, runList, runRemoveCmd, runUpdate } from './subcommands.js';
+import { pad16plus, runInteractiveLoop } from './tui.js';
+
+const SUBCOMMANDS = new Set(['add', 'remove', 'update', 'list']);
+
+/**
+ * @typedef {import('pkgbld/options').PackageJson} PackageJson
+ * @typedef {import('./types.js').PkgInfo} PkgInfo
+ */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const builtinRegistryPath = path.resolve(__dirname, '..', 'extensions.json');
+
+async function execute() {
+    const version = await reportVersion();
+
+    const sub = process.argv[2];
+    if (sub && SUBCOMMANDS.has(sub)) {
+        const rest = process.argv.slice(3);
+        if (sub === 'list') return runList(version, rest);
+        if (sub === 'add') return runAdd(version, rest);
+        if (sub === 'remove') return runRemoveCmd(version, rest);
+        if (sub === 'update') return runUpdate(version, rest);
+    }
+
+    const args = parseArgsPlus(
+        {
+            name: 'create-pkgbld',
+            version,
+            parameters: ['[package name]'],
+            options: {
+                quiet: {
+                    type: /** @type {'boolean'} */ ('boolean'),
+                    description: 'Quiet mode',
+                    default: false,
+                },
+                install: {
+                    type: /** @type {'boolean'} */ ('boolean'),
+                    description: 'Run package manager install after commit if deps changed',
+                    default: false,
+                },
+            },
+        },
+        [help, parameters]
+    );
+
+    const quiet = Boolean(args.values.quiet);
+    const installFlag = Boolean(args.values.install);
+
+    if (!quiet) console.log(`create-pkgbld v${version}\n`);
+
+    const targetDir = path.join(process.cwd(), args.parameters.packageName ?? '.');
+
+    if (!quiet) console.log(gray(pad16plus('Target Directory', 0)) + white(targetDir));
+
+    const pkg = await readPackage(targetDir);
+    if (pkg.mode === 'create') await initializePackage(pkg, targetDir);
+
+    /** @type {import('./tui.js').PendingPackageOperation[]} */
+    let pendingPackageOperations = [];
+
+    if (!quiet && pkg.mode === 'update') {
+        const registry = await loadRegistry(builtinRegistryPath);
+        const packageOperations = await openPackageOperations({ projectRoot: targetDir, registry });
+        for (const warning of packageOperations.warnings) console.warn(yellow(`Warning: ${warning}`));
+        try {
+            pendingPackageOperations = await runInteractiveLoop({ packageOperations });
+        } catch (/** @type {any} */ err) {
+            if (err && err.message === 'cancelled') process.exit(-1);
+            throw err;
+        }
+    }
+
+    await fs.mkdir(targetDir, { recursive: true });
+    const project = new ProjectChanges(targetDir);
+    if (pkg.mode === 'create') {
+        project.edit(tree => {
+            tree.write('package.json', toFormattedJson(pkg.pkg, tree.read('package.json')));
+            tree.write('README.md', pkg.readme);
+        });
+    }
+
+    for (const pending of pendingPackageOperations) {
+        await pending.operation.stage(project, pending.answers);
+    }
+
+    const { changes, conflicts } = project.review();
+
+    if (!quiet) {
+        console.log(`\n${gray('Pending changes:')}`);
+        console.log(renderChanges(changes, { readDiskJson: p => readDiskJsonFromDir(targetDir, p) }));
+        if (conflicts.length > 0) {
+            console.log(yellow('\nConflicts detected:'));
+            for (const line of formatConflicts(conflicts)) console.log(yellow(line));
+        }
+    }
+
+    const beforePkg = readDiskJsonFromDir(targetDir, 'package.json');
+    try {
+        await project.commit();
+    } catch (e) {
+        console.error(e);
+        process.exit(-1);
+    }
+
+    if (!quiet) {
+        for (const pending of pendingPackageOperations) {
+            const { effect, package: item } = pending.operation;
+            const verb = effect === 'adopt' ? green('adopted') : effect === 'remove' ? red('removed') : green('installed');
+            console.log(`${gray('Package')} ${white(item.name)} ${verb}`);
+        }
+    }
+
+    if (changesAffectDependencies(changes, beforePkg)) {
+        const pm = detectPackageManager(targetDir);
+        let shouldInstall = installFlag;
+        if (!shouldInstall && !quiet) {
+            const ans = await prompts({ type: 'confirm', name: 'go', message: `Run ${pm} install now?`, initial: false });
+            shouldInstall = Boolean(ans.go);
+        }
+        if (shouldInstall) {
+            if (!quiet) console.log(gray(`\nRunning ${pm} install...`));
+            const code = await runInstall(pm, targetDir);
+            if (code !== 0) {
+                console.error(red(`${pm} install exited with code ${code}`));
+                process.exitCode = code;
+            }
+        } else if (!quiet) {
+            console.log(gray(`\nDependencies changed. Run "${pm} install" to apply (or pass --install).`));
+        }
+    }
+}
+
+/**
+ * @param {string} dir
+ * @param {string} relPath
+ */
+function readDiskJsonFromDir(dir, relPath) {
+    try {
+        return JSON.parse(fsSync.readFileSync(path.join(dir, relPath), 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+execute();
+
+async function reportVersion() {
+    const createPkgBldPackage = await readPackage(path.resolve(__dirname, '..'));
+
+    const version = createPkgBldPackage.pkg.version ?? '<unknown>';
+
+    return version;
+}
+
+/**
+ * @param {PkgInfo} pkg
+ * @param {string} targetDir
+ * @returns {Promise<void>}
+ */
+async function initializePackage(pkg, targetDir) {
+    /** @type {PackageJson} */
+    const defaults = {
+        version: '0.0.1',
+        name: path.basename(targetDir),
+        description: '',
+        license: 'MIT',
+        author: getGitConfigValue('user.name'),
+        readme: 'README.md',
+    };
+
+    try {
+        const url = getGitConfigValue('remote.origin.url');
+        if (url) {
+            const root = await getGitRoot();
+            const directory = path.relative(root, targetDir);
+            defaults.homepage = url.replace('.git', `/blob/main${directory ? `/${directory}` : ''}/README.md`);
+            defaults.repository = /** @type {any} */ ({ type: 'git', url: `git+${url}`, directory: directory || undefined });
+            defaults.bugs = url.replace('.git', '/issues');
+        }
+    } catch (_) {
+        /* ignore */
+    }
+    pkg.pkg = processPackageJson(
+        defaults,
+        key => key in defaults,
+        key => /** @type {Record<string, unknown>} */ (defaults)[key]
+    );
+    pkg.readme = `# ${defaults.name}`;
+}
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+function getGitConfigValue(key) {
+    try {
+        return execFileSync('git', ['config', '--get', key], { encoding: 'utf8' }).trim();
+    } catch (_) {
+        return '';
+    }
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<PkgInfo>}
+ */
+async function readPackage(dir) {
+    const packageFileName = path.resolve(dir, 'package.json');
+    const readmeFileName = path.resolve(dir, 'README.md');
+    /** @type {PackageJson} */
+    const defaultPkg = {};
+    try {
+        const pkgFile = await fs.readFile(packageFileName);
+        const readmeFile = await fs.readFile(readmeFileName);
+        const pkg = JSON.parse(pkgFile.toString());
+        const isValidPackageJson = isPackageJson(pkg);
+        if (!isValidPackageJson) {
+            console.error('Invalid package.json');
+            throw new Error('Invalid package.json');
+        }
+        return {
+            pkg,
+            readme: readmeFile.toString(),
+            mode: /** @type {const} */ ('update'),
+        };
+    } catch (_) {
+        /**/
+    }
+
+    return {
+        pkg: defaultPkg,
+        readme: '',
+        mode: /** @type {const} */ ('create'),
+    };
+}

package/src/install.js

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Detect the package manager for the given project root, based on lockfile
+ * presence. Defaults to `npm`.
+ *
+ * @param {string} projectRoot
+ * @returns {'pnpm' | 'yarn' | 'npm'}
+ */
+export function detectPackageManager(projectRoot) {
+    if (existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
+    return 'npm';
+}
+
+/**
+ * Return true if any of the given FileChanges touch dependency-related
+ * fields in package.json. Compares against a snapshot taken before commit.
+ *
+ * @param {readonly import('./tree.js').FileChange[]} changes
+ * @param {any} beforePackageJson
+ */
+export function changesAffectDependencies(changes, beforePackageJson) {
+    for (const c of changes) {
+        if (!c.path.endsWith('package.json') || c.type === 'DELETE' || typeof c.content !== 'string') continue;
+        let after;
+        try {
+            after = JSON.parse(c.content);
+        } catch {
+            continue;
+        }
+        const before = beforePackageJson ?? {};
+        for (const group of ['dependencies', 'devDependencies', 'peerDependencies']) {
+            if (JSON.stringify(/** @type {any} */ (before)[group] ?? {}) !== JSON.stringify(after[group] ?? {})) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+/**
+ * Spawn `<pm> install` in the project root. Inherits stdio so the user sees
+ * live progress. Never invoked automatically — only when the caller has
+ * confirmed (e.g. via `--install` flag or interactive prompt).
+ *
+ * @param {'pnpm' | 'yarn' | 'npm'} pm
+ * @param {string} projectRoot
+ * @returns {Promise<number>}
+ */
+export function runInstall(pm, projectRoot) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(pm, ['install'], { cwd: projectRoot, stdio: 'inherit', shell: process.platform === 'win32' });
+        child.on('error', reject);
+        child.on('close', code => resolve(code ?? 0));
+    });
+}

package/src/inventory.js

@@ -0,0 +1,161 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { detectExtension } from './engine.js';
+import { getPackageName } from './extension-cache.js';
+import { getPackageKind, isPluginPackageName } from './package-names.js';
+import { resolveInstalledPackage } from './package-resolution.js';
+import { getPkgbldPeerRange, inspectInstalledPlugin } from './plugin-compatibility.js';
+import { readProjectLock } from './project-lock.js';
+import { resolveExtension } from './registry.js';
+import { Tree } from './tree.js';
+
+/**
+ * @typedef {'available' | 'applied' | 'installed-managed' | 'installed-unmanaged' | 'unavailable'} PackageState
+ * @typedef {{
+ *   entry: import('./registry.js').ExtensionEntry,
+ *   packageName: string,
+ *   kind: 'plugin' | 'extension',
+ *   state: PackageState,
+ *   lockedVersion: string | null,
+ *   resolvedVersion: string | null,
+ *   dependencyFields: string[],
+ *   hasExtensionContract: boolean,
+ *   ext: import('./registry.js').Extension | null,
+ *   error: string | null,
+ *   installed: boolean,
+ *   managed: boolean
+ * }} PackageItem
+ */
+
+/**
+ * Build the package inventory without downloading or executing missing packages.
+ * @param {import('./registry.js').ExtensionEntry[]} registry
+ * @param {string} projectRoot
+ * @returns {Promise<{ items: PackageItem[], warnings: string[] }>}
+ */
+export async function buildPackageInventory(registry, projectRoot) {
+    const lock = await readProjectLock(projectRoot);
+    const pkg = await readPackageJson(projectRoot);
+    /** @type {Map<string, { entry: import('./registry.js').ExtensionEntry, packageName: string, kind: 'plugin' | 'extension', lockedVersion: string | null, dependencyFields: string[], hasExtensionContract: boolean }>} */
+    const records = new Map();
+
+    for (const entry of registry) {
+        const packageName = getPackageName(entry.package);
+        const kind = packageName && getPackageKind(packageName);
+        if (!packageName || !kind) throw new Error(`Registry package "${entry.package}" does not use a supported package name`);
+        records.set(packageName, {
+            entry,
+            packageName,
+            kind,
+            lockedVersion: lock?.packages[packageName] ?? null,
+            dependencyFields: getDependencyFields(pkg, packageName),
+            hasExtensionContract: true,
+        });
+    }
+
+    for (const [packageName, version] of Object.entries(lock?.packages ?? {})) {
+        if (records.has(packageName)) continue;
+        const kind = /** @type {'plugin' | 'extension'} */ (getPackageKind(packageName));
+        records.set(packageName, {
+            entry: {
+                name: packageName,
+                package: packageName,
+                version,
+                description: kind === 'plugin' ? 'Third-party PKG BLD plugin' : 'PKG BLD extension',
+                tags: kind === 'plugin' ? ['plugin', 'pkgbld', 'third-party'] : ['extension', 'third-party'],
+                official: false,
+            },
+            packageName,
+            kind,
+            lockedVersion: version,
+            dependencyFields: getDependencyFields(pkg, packageName),
+            hasExtensionContract: kind === 'extension',
+        });
+    }
+
+    for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
+        for (const packageName of Object.keys(pkg[field] ?? {})) {
+            if (!isPluginPackageName(packageName) || records.has(packageName)) continue;
+            records.set(packageName, {
+                entry: {
+                    name: packageName,
+                    package: packageName,
+                    description: 'Third-party PKG BLD plugin',
+                    tags: ['plugin', 'pkgbld', 'third-party'],
+                    official: false,
+                },
+                packageName,
+                kind: 'plugin',
+                lockedVersion: null,
+                dependencyFields: getDependencyFields(pkg, packageName),
+                hasExtensionContract: false,
+            });
+        }
+    }
+
+    const tree = new Tree(projectRoot);
+    /** @type {PackageItem[]} */
+    const items = [];
+    /** @type {string[]} */
+    const warnings = [];
+    for (const record of records.values()) {
+        let installedPackage = resolveInstalledPackage(record.packageName, projectRoot);
+        if (record.kind === 'plugin' && record.dependencyFields.length > 0) {
+            const inspection = inspectInstalledPlugin(record.packageName, projectRoot);
+            if (!inspection.eligible) {
+                warnings.push(/** @type {string} */ (inspection.warning));
+                continue;
+            }
+            installedPackage = inspection.resolved;
+        } else if (record.kind === 'plugin' && record.lockedVersion && !record.entry.official) {
+            warnings.push(
+                `Ignoring ${record.packageName}: its plugin metadata cannot be verified from the project. Install and adopt a modern version before managing it with create-pkgbld.`
+            );
+            continue;
+        }
+        let ext = null;
+        let error = null;
+        let detected = false;
+        let resolvedVersion = installedPackage?.version ?? null;
+        if (record.hasExtensionContract && record.entry.official) {
+            try {
+                ext = await resolveExtension(record.entry, projectRoot, { exactVersion: record.lockedVersion ?? undefined });
+                if (record.kind === 'plugin' && !getPkgbldPeerRange(ext.__packageManifest)) {
+                    warnings.push(
+                        `Ignoring ${record.packageName}: the resolved package does not declare pkgbld in peerDependencies. Upgrade the plugin before managing it with create-pkgbld.`
+                    );
+                    continue;
+                }
+                detected = detectExtension(ext, tree);
+                resolvedVersion = ext.__packageVersion ?? resolvedVersion;
+            } catch (/** @type {any} */ cause) {
+                error = cause.message ?? String(cause);
+            }
+        }
+        const installed = record.kind === 'plugin' ? record.dependencyFields.length > 0 : detected;
+        const managed = record.lockedVersion !== null;
+        /** @type {PackageState} */
+        let state;
+        if (managed) state = installed ? 'installed-managed' : 'applied';
+        else if (installed) state = 'installed-unmanaged';
+        else if (record.entry.official) state = 'available';
+        else state = 'unavailable';
+        items.push({ ...record, state, resolvedVersion, ext, error, installed, managed });
+    }
+    return { items: items.sort((a, b) => a.entry.name.localeCompare(b.entry.name)), warnings };
+}
+
+/** @param {Record<string, any>} pkg @param {string} packageName */
+function getDependencyFields(pkg, packageName) {
+    return ['dependencies', 'devDependencies', 'peerDependencies'].filter(field => pkg[field]?.[packageName] !== undefined);
+}
+
+/** @param {string} projectRoot */
+async function readPackageJson(projectRoot) {
+    try {
+        return JSON.parse(await readFile(path.join(projectRoot, 'package.json'), 'utf8'));
+    } catch {
+        return {};
+    }
+}

package/src/package-names.js

@@ -0,0 +1,25 @@
+const PLUGIN_PACKAGE_RE = /^(?:@[^/]+\/)?pkgbld-plugin-/;
+const EXTENSION_PACKAGE_RE = /^(?:@[^/]+\/)?create-pkgbld-extension-/;
+const LOCK_PACKAGE_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?(?:create-pkgbld-extension-|pkgbld-plugin-)[a-z0-9][a-z0-9._~-]*$/;
+
+/** @param {string} packageName */
+export function isPluginPackageName(packageName) {
+    return PLUGIN_PACKAGE_RE.test(packageName);
+}
+
+/** @param {string} packageName */
+export function isExtensionPackageName(packageName) {
+    return EXTENSION_PACKAGE_RE.test(packageName);
+}
+
+/** @param {string} packageName @returns {'plugin' | 'extension' | null} */
+export function getPackageKind(packageName) {
+    if (isPluginPackageName(packageName)) return 'plugin';
+    if (isExtensionPackageName(packageName)) return 'extension';
+    return null;
+}
+
+/** @param {string} packageName */
+export function isLockPackageName(packageName) {
+    return LOCK_PACKAGE_RE.test(packageName);
+}