uipkge-ng 0.1.0

package/dist/layout.js

@@ -0,0 +1,114 @@
+// Where components go and how they import each other, derived from the
+// components.json aliases and the project's tsconfig `paths`.
+import { existsSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { parse } from 'jsonc-parser';
+import { DEFAULT_ALIASES } from './config.js';
+import { UipkgeError } from './errors.js';
+/** Folders the registry targets and the aliases its sources import. */
+export const REGISTRY_DIRS = { ui: 'src/app/components/ui', lib: 'src/lib', blocks: 'src/app/components/blocks' };
+const REGISTRY_IMPORTS = { ui: '@/ui', lib: '@/lib' };
+const posix = (p) => p.replace(/\\/g, '/');
+/** The tsconfig an app's sources compile with: tsconfig.json, else (multi-project workspaces) tsconfig.app.json. */
+export function appTsconfig(root) {
+    return !existsSync(path.join(root, 'tsconfig.json')) && existsSync(path.join(root, 'tsconfig.app.json')) ? 'tsconfig.app.json' : 'tsconfig.json';
+}
+/** compilerOptions the way TypeScript sees them, following relative `extends`. */
+export function readTsChain(file, seen = new Set()) {
+    if (!existsSync(file) || seen.has(file))
+        return { ownPaths: false };
+    seen.add(file);
+    const doc = (parse(readFileSync(file, 'utf8'), [], { allowTrailingComma: true }) ?? {});
+    const dir = path.dirname(file);
+    const own = doc.compilerOptions ?? {};
+    const ext = typeof doc.extends === 'string' && doc.extends.startsWith('.') ? doc.extends : undefined;
+    const parent = ext ? readTsChain(path.resolve(dir, ext.endsWith('.json') ? ext : `${ext}.json`), seen) : { ownPaths: false };
+    return {
+        baseUrl: own.baseUrl ? path.resolve(dir, own.baseUrl) : parent.baseUrl,
+        paths: own.paths ?? parent.paths,
+        pathsDir: own.paths ? dir : parent.pathsDir,
+        ownPaths: Boolean(own.paths),
+    };
+}
+export function readTsPaths(root, file = appTsconfig(root)) {
+    const chain = readTsChain(path.join(root, file));
+    return { base: chain.baseUrl ?? chain.pathsDir ?? root, paths: chain.paths ?? {} };
+}
+/**
+ * Resolves an import alias to a project-relative folder the way TypeScript
+ * does: exact keys first, then the wildcard key with the longest prefix.
+ * Returns null when no mapping covers it.
+ */
+export function aliasToDir(alias, ts, root) {
+    const exact = ts.paths[alias]?.[0];
+    let target = exact;
+    if (!target) {
+        let best = -1;
+        for (const [pattern, targets] of Object.entries(ts.paths)) {
+            const star = pattern.indexOf('*');
+            if (star === -1 || !targets[0])
+                continue;
+            const prefix = pattern.slice(0, star);
+            const suffix = pattern.slice(star + 1);
+            const probe = `${alias}/`;
+            if (probe.startsWith(prefix) && prefix.length > best && (suffix === '' || suffix === '/')) {
+                best = prefix.length;
+                const rest = probe.slice(prefix.length).replace(/\/$/, '');
+                target = targets[0].replace('*', rest);
+            }
+        }
+    }
+    if (!target)
+        return null;
+    const abs = path.resolve(ts.base, target.replace(/\/\*$/, '').replace(/\/$/, ''));
+    const rel = posix(path.relative(root, abs));
+    return rel.startsWith('..') ? null : rel || '.';
+}
+export function resolveLayout(root, aliases = DEFAULT_ALIASES, ts = readTsPaths(root)) {
+    const dirs = {};
+    for (const key of ['ui', 'lib', 'blocks']) {
+        const dir = aliasToDir(aliases[key], ts, root);
+        if (!dir) {
+            throw new UipkgeError(`The "${key}" alias "${aliases[key]}" in components.json is not mapped in ${appTsconfig(root)} "paths".`, `Add a mapping such as "${aliases[key]}/*": ["./src/…/*"], or run \`uipkge-ng init\` for the defaults.`);
+        }
+        dirs[key] = dir;
+    }
+    return { dirs, aliases };
+}
+const CODE_FILE = /\.(m?[jt]sx?|html)$/;
+/** Rewrites `'@/ui/…'` / `'@/lib/…'` specifiers to the project's aliases. */
+export function rewriteImports(content, aliases) {
+    let out = content;
+    for (const key of ['ui', 'lib']) {
+        const from = REGISTRY_IMPORTS[key];
+        const to = aliases[key].replace(/\/+$/, '');
+        if (to === from)
+            continue;
+        out = out.replace(new RegExp(`(['"\`])${from.replace(/[/@]/g, '\\$&')}/`, 'g'), `$1${to}/`);
+    }
+    return out;
+}
+/**
+ * The item as it should land in this project: targets moved from the
+ * registry's folders to the project's, imports rewritten to its aliases.
+ * `diff` compares against this too, so alias changes never read as edits.
+ */
+export function adaptItem(item, layout) {
+    const moves = ['ui', 'blocks', 'lib']
+        .filter(k => layout.dirs[k] !== REGISTRY_DIRS[k])
+        .map(k => ({ from: `~/${REGISTRY_DIRS[k]}/`, to: `~/${layout.dirs[k] === '.' ? '' : `${layout.dirs[k]}/`}` }));
+    const rewrite = layout.aliases.ui !== REGISTRY_IMPORTS.ui || layout.aliases.lib !== REGISTRY_IMPORTS.lib;
+    if (!moves.length && !rewrite)
+        return item;
+    return {
+        ...item,
+        files: item.files.map(f => {
+            let target = f.target;
+            const move = target && moves.find(m => target.startsWith(m.from));
+            if (target && move)
+                target = move.to + target.slice(move.from.length);
+            const content = rewrite && typeof f.content === 'string' && CODE_FILE.test(target ?? f.path ?? '') ? rewriteImports(f.content, layout.aliases) : f.content;
+            return { ...f, target, content };
+        }),
+    };
+}

package/dist/output.js

@@ -0,0 +1,26 @@
+// Line output. Colours only on a real terminal, never with NO_COLOR or TERM=dumb.
+const useColor = (stream) => Boolean(stream.isTTY) && !('NO_COLOR' in process.env) && process.env.TERM !== 'dumb';
+const wrap = (open, close) => (text) => useColor(process.stdout) ? `\u001b[${open}m${text}\u001b[${close}m` : text;
+export const color = {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    red: wrap(31, 39),
+    cyan: wrap(36, 39),
+};
+let silent = false;
+/** `--silent`: everything but errors is muted. */
+export const setSilent = (value) => void (silent = value);
+export const isSilent = () => silent;
+const out = (text) => void (silent || process.stdout.write(text));
+export const log = {
+    info: (message) => out(`${message}\n`),
+    step: (message) => out(`${color.dim('›')} ${message}\n`),
+    success: (message) => out(`${color.green('✔')} ${message}\n`),
+    warn: (message) => out(`${color.yellow('⚠')} ${message}\n`),
+    error: (message) => process.stderr.write(`${useColor(process.stderr) ? '\u001b[31m✖\u001b[39m' : '✖'} ${message}\n`),
+    blank: () => out('\n'),
+};
+/** Human wording for a count: "1 component", "3 components". */
+export const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;

package/dist/packages.js

@@ -0,0 +1,68 @@
+import { spawn } from 'node:child_process';
+import { UipkgeError } from './errors.js';
+import { isSilent } from './output.js';
+/** `@scope/name@^1.2` → { name: '@scope/name', version: '^1.2' }; `clsx` → { name: 'clsx' }. */
+export function parseSpec(spec) {
+    const at = spec.lastIndexOf('@');
+    if (at > 0)
+        return { name: spec.slice(0, at), version: spec.slice(at + 1) || undefined };
+    return { name: spec };
+}
+/**
+ * Registry items list `@angular/forms` etc. without a version. Installing
+ * "latest" into an Angular 21 app would pull a mismatched major, so unversioned
+ * `@angular/*` packages are pinned to the project's own `@angular/core` range.
+ */
+export function pinAngular(specs, angularCoreRange) {
+    return specs.map(spec => {
+        const { name, version } = parseSpec(spec);
+        return name.startsWith('@angular/') && !version ? `${name}@${angularCoreRange}` : spec;
+    });
+}
+/** Drops packages the project already declares (any version). */
+export function missingPackages(specs, declared) {
+    const seen = new Set();
+    const out = [];
+    for (const spec of specs) {
+        const { name } = parseSpec(spec);
+        if (declared[name] || seen.has(name))
+            continue;
+        seen.add(name);
+        out.push(spec);
+    }
+    return out;
+}
+export function installArgs(pm, packages, dev) {
+    const add = pm === 'npm' ? 'install' : 'add';
+    const devFlag = dev ? [pm === 'bun' ? '--dev' : '-D'] : [];
+    return [add, ...devFlag, ...packages];
+}
+/**
+ * Runs the package manager in the project root. Its output is shown as-is,
+ * except under --silent, where it is buffered and only printed if it fails.
+ */
+export function installPackages(pm, root, packages, dev = false) {
+    if (!packages.length)
+        return Promise.resolve();
+    const args = installArgs(pm, packages, dev);
+    const quiet = isSilent();
+    return new Promise((resolve, reject) => {
+        const child = spawn(pm, args, {
+            cwd: root,
+            stdio: quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+            // npm/pnpm/yarn are .cmd shims on Windows.
+            shell: process.platform === 'win32',
+        });
+        const captured = [];
+        child.stdout?.on('data', (chunk) => captured.push(chunk));
+        child.stderr?.on('data', (chunk) => captured.push(chunk));
+        child.on('error', error => reject(new UipkgeError(`Could not run ${pm}: ${error.message}`, `Is ${pm} installed and on your PATH?`)));
+        child.on('exit', code => {
+            if (code === 0)
+                return resolve();
+            if (quiet && captured.length)
+                process.stderr.write(Buffer.concat(captured));
+            reject(new UipkgeError(`\`${pm} ${args.join(' ')}\` failed (exit ${code}).`));
+        });
+    });
+}

package/dist/project.js

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { parse } from 'jsonc-parser';
+import { UipkgeError } from './errors.js';
+export function declaredDependencies(pkg) {
+    return { ...pkg.dependencies, ...pkg.devDependencies };
+}
+/** Nearest directory at or above `start` that holds a package.json. */
+export function findProjectRoot(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        if (existsSync(path.join(dir, 'package.json')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+const LOCKFILES = [
+    ['bun.lock', 'bun'],
+    ['bun.lockb', 'bun'],
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['package-lock.json', 'npm'],
+];
+/** Lockfile at `root` or above (a workspace member's lockfile lives at the workspace root), else `packageManager`. */
+export function detectPackageManager(root, pkg) {
+    for (let dir = path.resolve(root);; dir = path.dirname(dir)) {
+        for (const [file, pm] of LOCKFILES)
+            if (existsSync(path.join(dir, file)))
+                return pm;
+        if (path.dirname(dir) === dir)
+            break;
+    }
+    const declared = pkg.packageManager?.split('@')[0];
+    if (declared === 'pnpm' || declared === 'yarn' || declared === 'bun' || declared === 'npm')
+        return declared;
+    return 'npm';
+}
+export async function readPackageJson(root) {
+    const file = path.join(root, 'package.json');
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw new UipkgeError(`Could not read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+const isInside = (child, parent) => {
+    const rel = path.relative(parent, child);
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+/** Application projects in angular.json (libraries have no global styles to theme). */
+export function angularApps(packageRoot) {
+    const file = path.join(packageRoot, 'angular.json');
+    if (!existsSync(file))
+        return [];
+    const doc = (parse(readFileSync(file, 'utf8')) ?? {});
+    return Object.entries(doc.projects ?? {})
+        .filter(([, p]) => (p.projectType ?? 'application') === 'application')
+        .map(([name, p]) => {
+        const root = path.resolve(packageRoot, p.root ?? '');
+        const styles = ((p.architect ?? p.targets)?.build?.options?.styles ?? [])
+            .map(s => (typeof s === 'string' ? s : s.input))
+            .filter((s) => Boolean(s))
+            .map(s => path.relative(root, path.resolve(packageRoot, s)).replace(/\\/g, '/'));
+        return { name, root, styles };
+    });
+}
+/**
+ * Which Angular app `cwd` belongs to. An existing components.json between cwd
+ * and the package root wins; otherwise the angular.json project containing
+ * cwd, the only app, or the only initialized app. Null outside a package.
+ */
+export function findApp(cwd) {
+    const packageRoot = findProjectRoot(cwd);
+    if (!packageRoot)
+        return null;
+    const apps = angularApps(packageRoot);
+    for (let dir = path.resolve(cwd); isInside(dir, packageRoot); dir = path.dirname(dir)) {
+        if (existsSync(path.join(dir, 'components.json')))
+            return { root: dir, packageRoot, app: apps.find(a => a.root === dir) };
+        if (dir === packageRoot)
+            break;
+    }
+    const containing = apps.filter(a => a.root !== packageRoot && isInside(path.resolve(cwd), a.root)).sort((a, b) => b.root.length - a.root.length)[0];
+    const initialized = apps.filter(a => existsSync(path.join(a.root, 'components.json')));
+    const app = containing ?? (apps.length === 1 ? apps[0] : apps.find(a => a.root === packageRoot) ?? (initialized.length === 1 ? initialized[0] : undefined));
+    if (app)
+        return { root: app.root, packageRoot, app };
+    return { root: packageRoot, packageRoot, ambiguous: apps.length > 1 ? apps : undefined };
+}
+/** The folder uipkge reads components.json from for `cwd`, or null outside a package. */
+export const findAppRoot = (cwd) => findApp(cwd)?.root ?? null;
+/** Loads the Angular project containing `cwd`, or explains why it can't be used. */
+export async function loadProject(cwd) {
+    if (!existsSync(cwd))
+        throw new UipkgeError(`The directory ${cwd} does not exist.`);
+    const location = findApp(cwd);
+    if (!location)
+        throw new UipkgeError('No package.json found.', 'Run this inside your Angular project.');
+    const { root, packageRoot } = location;
+    if (location.ambiguous) {
+        const first = path.relative(cwd, location.ambiguous[0].root) || '.';
+        throw new UipkgeError(`This workspace has ${location.ambiguous.length} apps: ${location.ambiguous.map(a => a.name).join(', ')}.`, `Run uipkge-ng inside the app's folder, or pass it with \`-c ${first}\`.`);
+    }
+    const packageJson = await readPackageJson(packageRoot);
+    const deps = declaredDependencies(packageJson);
+    const angularCore = deps['@angular/core'];
+    if (!angularCore) {
+        throw new UipkgeError(`${root} is not an Angular project (no @angular/core in package.json).`);
+    }
+    if (deps['nx'] || existsSync(path.join(packageRoot, 'nx.json'))) {
+        throw new UipkgeError('Nx workspaces are not supported yet.', 'Run uipkge-ng inside a standalone Angular CLI app.');
+    }
+    return {
+        root,
+        packageRoot,
+        app: location.app,
+        packageJson,
+        angularCore,
+        isAnalog: Boolean(deps['@analogjs/platform'] || deps['@analogjs/vite-plugin-angular']),
+        hasTailwind: Boolean(deps['tailwindcss']),
+        packageManager: detectPackageManager(packageRoot, packageJson),
+    };
+}
+/**
+ * Resolves a registry `target` (`~/src/app/…`) to an absolute path inside the
+ * project. Targets come from the network, so anything that would escape the
+ * project root (absolute paths, `..`) is refused rather than written.
+ */
+export function resolveTarget(root, target) {
+    const relative = target.replace(/^~\//, '');
+    if (path.isAbsolute(relative) || /^[a-zA-Z]:/.test(relative)) {
+        throw new UipkgeError(`Refusing to write outside the project: ${target}`);
+    }
+    const absolute = path.resolve(root, relative);
+    const rel = path.relative(root, absolute);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new UipkgeError(`Refusing to write outside the project: ${target}`);
+    }
+    return absolute;
+}

package/dist/prompts.js

@@ -0,0 +1,27 @@
+import * as p from '@clack/prompts';
+import { UipkgeError } from './errors.js';
+/** Prompts only when a person is at a real terminal — never in CI or pipes. */
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.CI;
+}
+export class CancelledError extends UipkgeError {
+    constructor() {
+        super('Cancelled. Nothing was changed.');
+    }
+}
+export async function confirm(message, initialValue = true) {
+    const answer = await p.confirm({ message, initialValue });
+    if (p.isCancel(answer))
+        throw new CancelledError();
+    return answer;
+}
+export async function pickComponents(options) {
+    const answer = await p.autocompleteMultiselect({
+        message: 'Which components do you want to add? (type to search, space to select)',
+        options,
+        required: true,
+    });
+    if (p.isCancel(answer))
+        throw new CancelledError();
+    return answer;
+}

package/dist/registry.js

@@ -0,0 +1,187 @@
+import { readFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { UipkgeError } from './errors.js';
+export const DEFAULT_REGISTRY_URL = 'https://uipkge.dev/r/angular';
+/** Items only `init` installs; never listed or added by name. */
+export const FOUNDATION_ITEMS = new Set(['init', 'tailwind', 'utils']);
+export function resolveRegistryUrl(configured) {
+    const url = process.env.UIPKGE_REGISTRY_URL || configured || DEFAULT_REGISTRY_URL;
+    return url.replace(/\/+$/, '');
+}
+/** A registry answered 404: the item isn't there (as opposed to unreachable or refused). */
+export class NotFoundError extends UipkgeError {
+    url;
+    constructor(url) {
+        super(`Not found in the registry: ${url}`);
+        this.url = url;
+    }
+}
+const NAMESPACED = /^(@[a-z0-9][\w-]*)\/([^/\s]+)$/i;
+/** A name from the default registry, `@ns/name` from a named registry, an absolute item URL, or a local item file. */
+export function refKind(ref) {
+    if (/^https?:\/\//.test(ref))
+        return 'url';
+    if (NAMESPACED.test(ref) && !ref.endsWith('.json'))
+        return 'namespaced';
+    if (/^(\.{1,2}[\\/]|[\\/]|~[\\/]|[a-zA-Z]:[\\/])/.test(ref) || ref.endsWith('.json'))
+        return 'file';
+    return 'name';
+}
+/** `https://…/r/angular/popper.json` → `popper`; `@acme/button` → `button`; plain names pass through. */
+export function itemNameFromRef(ref) {
+    const namespaced = ref.match(NAMESPACED);
+    if (namespaced)
+        return namespaced[2];
+    const last = ref.split(/[?#]/)[0].split('/').pop() ?? ref;
+    return last.replace(/\.json$/, '');
+}
+/**
+ * Expands `${VAR}` from `env`. A missing variable is an error (a request with
+ * "Bearer " and no token would just fail later with a confusing 401).
+ */
+export function expandEnv(value, env, where) {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+        const found = env[name];
+        if (found === undefined || found === '') {
+            throw new UipkgeError(`${where} needs the environment variable ${name}, which is not set.`, `Set ${name} in your shell or in .env / .env.local.`);
+        }
+        return found;
+    });
+}
+export function namedRegistryFrom(ns, config, env) {
+    const raw = typeof config === 'string' ? { url: config } : config;
+    if (!raw.url || !raw.url.includes('{name}')) {
+        throw new UipkgeError(`Registry "${ns}" needs a url containing {name}, e.g. "https://example.com/r/{name}.json".`);
+    }
+    const where = `Registry "${ns}"`;
+    const expand = (obj) => Object.fromEntries(Object.entries(obj ?? {}).map(([k, v]) => [k, expandEnv(v, env, where)]));
+    return { url: expandEnv(raw.url, env, where), headers: expand(raw.headers), params: expand(raw.params) };
+}
+/** `{name}` substituted, `params` appended as a query string. */
+export function namedItemUrl(reg, name) {
+    const url = new URL(reg.url.replace('{name}', encodeURIComponent(name)));
+    for (const [k, v] of Object.entries(reg.params))
+        url.searchParams.set(k, v);
+    return url.toString();
+}
+export function createRegistry(baseUrl, fetchOrOptions, cwdArg) {
+    // Back-compat signature: createRegistry(url, fetch?, cwd?).
+    const options = typeof fetchOrOptions === 'function' ? { fetch: fetchOrOptions, cwd: cwdArg } : { ...fetchOrOptions, cwd: fetchOrOptions?.cwd ?? cwdArg };
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const rawRegistries = options.registries ?? {};
+    const named = new Map();
+    const indexes = new Map();
+    const items = new Map();
+    function namespace(ns) {
+        let reg = named.get(ns);
+        if (!reg) {
+            const raw = rawRegistries[ns];
+            if (!raw) {
+                const known = Object.keys(rawRegistries);
+                throw new UipkgeError(`Unknown registry "${ns}".`, known.length ? `Configured registries: ${known.join(', ')}.` : 'Add it under "registries" in components.json.');
+            }
+            reg = namedRegistryFrom(ns, raw, env);
+            named.set(ns, reg);
+        }
+        return reg;
+    }
+    async function getJson(url, headers) {
+        let res;
+        try {
+            res = await fetchImpl(url, headers && Object.keys(headers).length ? { headers } : undefined);
+        }
+        catch (error) {
+            throw new UipkgeError(`Could not reach ${url}: ${error instanceof Error ? error.message : String(error)}`, 'Check your connection, or set UIPKGE_REGISTRY_URL if you use a mirror.');
+        }
+        if (res.status === 404)
+            throw new NotFoundError(url);
+        if (res.status === 401 || res.status === 403) {
+            throw new UipkgeError(`The registry refused access (${res.status}): ${url}`, 'Check the token/headers configured for this registry.');
+        }
+        if (!res.ok)
+            throw new UipkgeError(`Registry request failed (${res.status}): ${url}`);
+        try {
+            return await res.json();
+        }
+        catch {
+            throw new UipkgeError(`The registry returned invalid JSON: ${url}`);
+        }
+    }
+    function asIndex(data, url) {
+        const index = data;
+        if (!index || !Array.isArray(index.items))
+            throw new UipkgeError(`Unexpected registry index format: ${url}`);
+        return index;
+    }
+    function asItem(data, where) {
+        const item = data;
+        if (!item || typeof item.name !== 'string' || !Array.isArray(item.files)) {
+            throw new UipkgeError(`Unexpected registry item format: ${where}`);
+        }
+        return item;
+    }
+    return {
+        baseUrl,
+        namespaces: Object.keys(rawRegistries),
+        async index(ns) {
+            const key = ns ?? '';
+            let pending = indexes.get(key);
+            if (!pending) {
+                if (ns) {
+                    const reg = namespace(ns);
+                    const url = namedItemUrl(reg, 'registry');
+                    pending = getJson(url, reg.headers).then(d => asIndex(d, url));
+                }
+                else {
+                    const url = `${baseUrl}/registry.json`;
+                    pending = getJson(url).then(d => asIndex(d, url));
+                }
+                indexes.set(key, pending);
+            }
+            return pending;
+        },
+        async item(ref) {
+            const kind = refKind(ref);
+            let key;
+            let load;
+            if (kind === 'file') {
+                key = path.resolve(cwd, ref.replace(/^~(?=[\\/])/, process.env.HOME ?? '~'));
+                load = () => readLocal(key);
+            }
+            else if (kind === 'namespaced') {
+                const [, ns, name] = ref.match(NAMESPACED);
+                const reg = namespace(ns);
+                key = namedItemUrl(reg, name);
+                // Headers go only to this registry's own URLs.
+                load = () => getJson(key, reg.headers);
+            }
+            else {
+                key = kind === 'url' ? ref : `${baseUrl}/${ref}.json`;
+                load = () => getJson(key);
+            }
+            let pending = items.get(key);
+            if (!pending) {
+                pending = load().then(d => asItem(d, key));
+                items.set(key, pending);
+            }
+            return pending;
+        },
+    };
+}
+async function readLocal(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        throw new UipkgeError(`Could not read the item file ${file}.`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UipkgeError(`${file} is not valid JSON.`);
+    }
+}

package/dist/resolve.js

@@ -0,0 +1,60 @@
+import { UipkgeError } from './errors.js';
+import { FOUNDATION_ITEMS, itemNameFromRef, refKind } from './registry.js';
+/** Throws one error listing every name the index does not know. Nothing is installed. */
+export function assertKnownNames(names, known, consequence = '') {
+    const unknown = names.filter(n => !known.has(n));
+    if (!unknown.length)
+        return;
+    const list = unknown.map(n => `\`${n}\``).join(', ');
+    throw new UipkgeError(`${unknown.length === 1 ? 'Component' : 'Components'} not found in the registry: ${list}.${consequence ? ` ${consequence}` : ''}`, 'See what is available with `uipkge-ng list`.');
+}
+/**
+ * Walks `registryDependencies` depth-first so every dependency is written before
+ * its dependents. Each item is visited once (shared deps, cycles). An installed
+ * item is skipped — unless `overwrite` — but its dependencies are still walked,
+ * so a partially installed tree gets completed.
+ */
+export async function planInstall(registry, names, isInstalled, overwrite, 
+/** Applied to each fetched item before anything else (e.g. `--path` relocation of requested items). */
+transform = item => item) {
+    // Only bare names are looked up in the index; URLs and local files stand alone.
+    const bare = names.filter(n => refKind(n) === 'name');
+    if (bare.length) {
+        const index = await registry.index();
+        assertKnownNames(bare, new Set(index.items.map(i => i.name)), 'Nothing was installed.');
+    }
+    const visited = new Set();
+    const install = [];
+    const skipped = [];
+    const dependencies = new Set();
+    const devDependencies = new Set();
+    async function visit(ref, direct) {
+        // The default registry's foundation is init's job; a component depending on
+        // `utils` must not reinstall it. `@acme/utils` is someone else's item.
+        const kind = refKind(ref);
+        const ownRegistry = kind === 'name' || (kind === 'url' && ref.startsWith(`${registry.baseUrl}/`));
+        if (ownRegistry && FOUNDATION_ITEMS.has(itemNameFromRef(ref)))
+            return undefined;
+        const item = transform(await registry.item(ref), direct);
+        if (visited.has(item.name))
+            return item.name;
+        visited.add(item.name);
+        for (const dep of item.registryDependencies ?? [])
+            await visit(dep, false);
+        if (isInstalled(item) && !overwrite) {
+            skipped.push(item.name);
+            return item.name;
+        }
+        install.push(item);
+        item.dependencies?.forEach(d => dependencies.add(d));
+        item.devDependencies?.forEach(d => devDependencies.add(d));
+        return item.name;
+    }
+    const requested = [];
+    for (const name of names) {
+        const resolved = await visit(name, true);
+        if (resolved && !requested.includes(resolved))
+            requested.push(resolved);
+    }
+    return { install, skipped, requested, dependencies: [...dependencies], devDependencies: [...devDependencies] };
+}