cronus-ui 0.6.0

package/dist/compose/templates.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bundled app-template I/O. Lives here (not in commands/compose.ts) so
+ * `reloadManifest` can load a template without a circular import through the
+ * compose command module.
+ */
+import { type AppManifest } from "./manifest.js";
+/** Canonical `-y` / non-TTY compose target — never lexicographic first. */
+export declare const DEFAULT_COMPOSE_TEMPLATE = "saas";
+/** True when `name` is a safe templates/apps basename (no path traversal). */
+export declare function isTemplateSlug(name: string): boolean;
+/** List the bundled template names (basename without .json), sorted. */
+export declare function listTemplates(): Promise<string[]>;
+/**
+ * Template used when the user passes `--yes` or stdin is not a TTY.
+ * Prefers SaaS; falls back to the first bundled name if SaaS is missing.
+ */
+export declare function defaultComposeTemplate(available: string[]): string;
+/** Load + strictly parse a bundled template manifest by name. Throws on missing/invalid. */
+export declare function loadTemplate(name: string): Promise<AppManifest>;
+/** Load + strictly parse a manifest from an explicit file path. */
+export declare function loadManifestFile(path: string): Promise<AppManifest>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/compose/templates.js

@@ -0,0 +1,76 @@
+/**
+ * Bundled app-template I/O. Lives here (not in commands/compose.ts) so
+ * `reloadManifest` can load a template without a circular import through the
+ * compose command module.
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { closestName } from "../utils.js";
+import { parseManifest } from "./manifest.js";
+/** Directory holding the bundled app-template manifests (dist/ or src/ layout). */
+function appsTemplatesDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // compiled: dist/compose/templates.js → dist/../templates ; source: src/compose → ../templates
+    const compiled = join(here, "..", "..", "templates", "apps");
+    const fromSource = join(here, "..", "templates", "apps");
+    return [compiled, fromSource].find((p) => existsSync(p)) ?? compiled;
+}
+/** Canonical `-y` / non-TTY compose target — never lexicographic first. */
+export const DEFAULT_COMPOSE_TEMPLATE = "saas";
+const TEMPLATE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** True when `name` is a safe templates/apps basename (no path traversal). */
+export function isTemplateSlug(name) {
+    return TEMPLATE_SLUG.test(name);
+}
+/** List the bundled template names (basename without .json), sorted. */
+export async function listTemplates() {
+    try {
+        return (await readdir(appsTemplatesDir()))
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => f.slice(0, -".json".length))
+            .filter(isTemplateSlug)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Template used when the user passes `--yes` or stdin is not a TTY.
+ * Prefers SaaS; falls back to the first bundled name if SaaS is missing.
+ */
+export function defaultComposeTemplate(available) {
+    if (available.includes(DEFAULT_COMPOSE_TEMPLATE))
+        return DEFAULT_COMPOSE_TEMPLATE;
+    const first = available[0];
+    if (first === undefined)
+        throw new Error("no app templates are bundled with this CLI");
+    return first;
+}
+/** Load + strictly parse a bundled template manifest by name. Throws on missing/invalid. */
+export async function loadTemplate(name) {
+    if (!isTemplateSlug(name)) {
+        throw new Error(`Unknown template "${name}".`);
+    }
+    const file = join(appsTemplatesDir(), `${name}.json`);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch {
+        const available = await listTemplates();
+        const suggestion = closestName(name, available);
+        throw new Error(suggestion
+            ? `Unknown template "${name}". Did you mean "${suggestion}"? (available: ${available.join(", ")})`
+            : `Unknown template "${name}" (available: ${available.join(", ") || "none"}).`);
+    }
+    return parseManifest(JSON.parse(raw));
+}
+/** Load + strictly parse a manifest from an explicit file path. */
+export async function loadManifestFile(path) {
+    const raw = await readFile(path, "utf8");
+    return parseManifest(JSON.parse(raw));
+}
+//# sourceMappingURL=templates.js.map

package/dist/compose.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public library entry for programmatic composition (consumed by
+ * `create-cronus-app`'s post-scaffold step). Re-exports the pure apply core so a
+ * scaffolder can generate an app template into a freshly-created project without
+ * shelling out to the CLI.
+ */
+export { type ComposeAppOptions, type ComposeAppResult, composeApp, listTemplates, loadTemplate, } from "./commands/compose.js";
+export type { AppManifest } from "./compose/manifest.js";
+export type { ComposeChoiceInput } from "./compose/plan.js";
+//# sourceMappingURL=compose.d.ts.map

package/dist/compose.js

@@ -0,0 +1,8 @@
+/**
+ * Public library entry for programmatic composition (consumed by
+ * `create-cronus-app`'s post-scaffold step). Re-exports the pure apply core so a
+ * scaffolder can generate an app template into a freshly-created project without
+ * shelling out to the CLI.
+ */
+export { composeApp, listTemplates, loadTemplate, } from "./commands/compose.js";
+//# sourceMappingURL=compose.js.map

package/dist/config.d.ts

@@ -0,0 +1,94 @@
+export declare const CONFIG_FILE = "cronus-ui.json";
+export declare const CLI_VERSION = "0.6.0";
+export declare const DEFAULT_REGISTRY = "https://raw.githubusercontent.com/pedrogbraz/cronus-ui/v0.6.0/registry";
+/** Manifest entry `add`/`upgrade` record per installed registry item. */
+export interface InstalledRecord {
+    /** Registry release the files came from (git tag without the leading "v"). */
+    version: string;
+    /** Project-relative paths the item wrote (e.g. "components/ui/button.tsx"). */
+    files: string[];
+}
+/**
+ * The normalized `choices` an app was composed with. Persisted with sorted keys
+ * (deterministic) so `compose --plan <dir>` clones reproduce the same plan and
+ * the 3-way page upgrade (F4) has a stable comparison base. Phase 1 fills `brand`
+ * (and, when passed, `seed`); `variants`/`pages` stay empty until F2.
+ */
+export interface ComposedChoices {
+    /** Selected block variant per family slug (F2; `{}` in F1). */
+    variants: Record<string, string>;
+    /** The routes actually generated, in manifest order. */
+    pages: string[];
+    /** The `--brand` value baked into chrome/hero copy. */
+    brand: string;
+    /** Aesthetic PRNG seed (only present when the caller passed `--seed`). */
+    seed?: number;
+}
+/**
+ * Per-composed-app record written by `compose` (mirrors {@link InstalledRecord}
+ * for `installed`). `files` are the generated page/layout/chrome paths (NOT the
+ * installed blocks — those live in `installed`). The `.cronus-ui/base/<composed-key>/`
+ * snapshot (template name; legacy compose used the package.json name and F4
+ * falls back to that dir) holds the exact bytes for the F4 page-upgrade merge
+ * base.
+ */
+export interface ComposedRecord {
+    /** Registry release the app was composed from (git tag without the leading "v"). */
+    version: string;
+    /** Manifest plan schema version the app was generated against. */
+    planVersion: number;
+    /** The normalized choices (sorted keys) the app was generated with. */
+    choices: ComposedChoices;
+    /** Project-relative paths the composer generated (pages, layouts, chrome wrappers). */
+    files: string[];
+    /**
+     * Content fingerprint of the manifest this app was composed from (compose
+     * provenance). `add-page` reloads a bundled template only when it matches this
+     * hash — so a `--manifest`-composed app whose `name` collides with a bundled
+     * template (store/landing/saas) is NOT silently reloaded from the wrong bundled
+     * manifest. Absent for apps composed before this field existed (legacy): the
+     * verification is then skipped (nothing to compare against).
+     */
+    manifestHash?: string;
+}
+export interface CronusUIConfig {
+    /** Import aliases used when rewriting component sources. */
+    aliases: {
+        ui: string;
+        lib: string;
+        blocks: string;
+    };
+    /** Filesystem paths (relative to cwd) where files are written. */
+    paths: {
+        ui: string;
+        lib: string;
+        blocks: string;
+    };
+    /** Registry source (http base URL or local directory). */
+    registry: string;
+    /** The app's theme preset + color mode (written by the scaffolder / `theme set`). */
+    theme?: {
+        name: string;
+        mode: string;
+    };
+    /**
+     * Install manifest: which items are installed, from which registry release,
+     * and which files they own. `upgrade` uses the recorded version as the merge
+     * base for its 3-way merge. Absent for installs made before this field
+     * existed ("legacy") — `upgrade` then falls back to a 2-way diff.
+     */
+    installed?: Record<string, InstalledRecord>;
+    /**
+     * Compose manifest: which app templates were generated into this project, the
+     * plan version + normalized choices, and the generated files each owns. Mirrors
+     * `installed` (round-tripped verbatim); the F4 page-upgrade reads it to know
+     * which pages to re-render against their `.cronus-ui/base/` snapshot.
+     */
+    composed?: Record<string, ComposedRecord>;
+}
+export declare const DEFAULT_CONFIG: CronusUIConfig;
+export declare function configPath(cwd: string): string;
+export declare function hasConfig(cwd: string): boolean;
+export declare function readConfig(cwd: string): Promise<CronusUIConfig>;
+export declare function writeConfig(cwd: string, config: CronusUIConfig): Promise<void>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,38 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const CONFIG_FILE = "cronus-ui.json";
+export const CLI_VERSION = "0.6.0";
+export const DEFAULT_REGISTRY = `https://raw.githubusercontent.com/pedrogbraz/cronus-ui/v${CLI_VERSION}/registry`;
+export const DEFAULT_CONFIG = {
+    aliases: { ui: "@/components/ui", lib: "@/lib", blocks: "@/components/blocks" },
+    paths: { ui: "components/ui", lib: "lib", blocks: "components/blocks" },
+    registry: DEFAULT_REGISTRY,
+};
+export function configPath(cwd) {
+    return join(cwd, CONFIG_FILE);
+}
+export function hasConfig(cwd) {
+    return existsSync(configPath(cwd));
+}
+export async function readConfig(cwd) {
+    const raw = await readFile(configPath(cwd), "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+        aliases: { ...DEFAULT_CONFIG.aliases, ...parsed.aliases },
+        paths: { ...DEFAULT_CONFIG.paths, ...parsed.paths },
+        registry: parsed.registry ?? DEFAULT_CONFIG.registry,
+        // Preserve the theme block when present so `add`/`init` round-trips never drop it.
+        ...(parsed.theme ? { theme: parsed.theme } : {}),
+        // Same for the install manifest — dropping it would silently downgrade every
+        // component to the legacy (2-way) upgrade path.
+        ...(parsed.installed ? { installed: parsed.installed } : {}),
+        // And for the compose manifest — dropping it would orphan generated pages
+        // from their base snapshot, breaking the composed-page 3-way upgrade (F4).
+        ...(parsed.composed ? { composed: parsed.composed } : {}),
+    };
+}
+export async function writeConfig(cwd, config) {
+    await writeFile(configPath(cwd), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+//# sourceMappingURL=config.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { add } from "./commands/add.js";
+import { addPageCommand } from "./commands/add-page.js";
+import { aiAdd } from "./commands/ai.js";
+import { compose } from "./commands/compose.js";
+import { diff } from "./commands/diff.js";
+import { init } from "./commands/init.js";
+import { list } from "./commands/list.js";
+import { themeAdd, themeSet } from "./commands/theme.js";
+import { upgrade } from "./commands/upgrade.js";
+import { CLI_VERSION } from "./config.js";
+const program = new Command();
+program
+    .name("cronus-ui")
+    .description("Add Cronus UI components to your project, shadcn-style.")
+    .version(CLI_VERSION);
+program
+    .command("init")
+    .description("Set up cronus-ui.json, the cn() helper, and base dependencies.")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .option("-r, --registry <source>", "registry URL or local directory")
+    .option("-y, --yes", "overwrite an existing cronus-ui.json")
+    .option("--skip-install", "do not install base dependencies")
+    .action((opts) => init({
+    cwd: opts.cwd,
+    registry: opts.registry,
+    yes: opts.yes,
+    skipInstall: opts.skipInstall,
+}));
+program
+    .command("add")
+    .description("Add one or more components (resolves dependencies).")
+    .argument("[components...]", "component names")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .option("-r, --registry <source>", "registry URL or local directory")
+    .option("-o, --overwrite", "overwrite existing files")
+    .option("--skip-install", "do not install npm dependencies")
+    .action((components, opts) => add(components, {
+    cwd: opts.cwd,
+    registry: opts.registry,
+    overwrite: opts.overwrite,
+    skipInstall: opts.skipInstall,
+}));
+program
+    .command("compose")
+    .description("Generate a full app from a validated template (pages + chrome from installed blocks).")
+    .argument("[template]", "app template name (default with -y: saas)")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .option("-r, --registry <source>", "registry URL or local directory")
+    .option("-m, --manifest <file>", "compose from an explicit manifest file instead of a bundled template")
+    .option("--pages <list>", "comma-separated route subset (e.g. /,products,login)")
+    .option("--variant <pair...>", "block variant selection, e.g. --variant login=split (F2)")
+    .option("-b, --brand <name>", "brand wordmark baked into chrome/hero")
+    .option("-s, --seed <n>", "aesthetic PRNG seed (recorded for reproducibility)")
+    .option("-o, --overwrite", "overwrite existing files")
+    .option("--skip-install", "do not install npm dependencies")
+    .option("--dry-run", "print the validated plan + per-file preview, write nothing")
+    .option("-y, --yes", "non-interactive: pick saas if no template is given")
+    .action((template, opts) => compose(template, {
+    cwd: opts.cwd,
+    registry: opts.registry,
+    manifest: opts.manifest,
+    pages: opts.pages,
+    variant: opts.variant,
+    brand: opts.brand,
+    seed: opts.seed,
+    overwrite: opts.overwrite,
+    skipInstall: opts.skipInstall,
+    dryRun: opts.dryRun,
+    yes: opts.yes,
+}));
+program
+    .command("add-page")
+    .description("Add one page to an already-composed app (installs new blocks, updates the nav + composed record).")
+    .requiredOption("--route <route>", "route to add, e.g. /faq")
+    .requiredOption("--blocks <list>", "comma-separated blocks, e.g. faq,cta (or login=split)")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .option("-r, --registry <source>", "registry URL or local directory")
+    .option("--chrome <group>", "chrome group for the page (default: the app's first group)")
+    .option("--title <title>", "page <title> (default: Title-Cased route)")
+    .option("--nav <label>", "nav label; adds the page to the chrome nav")
+    .option("--app <name>", "which composed app to extend (required if the project has >1)")
+    .option("-m, --manifest <file>", "reload the manifest from a file (for --manifest-composed apps)")
+    .option("-o, --overwrite", "replace the page if the route already exists")
+    .option("--skip-install", "do not install npm dependencies")
+    .option("--dry-run", "print the plan + files that would be written, write nothing")
+    .action((opts) => addPageCommand({
+    cwd: opts.cwd,
+    route: opts.route,
+    blocks: opts.blocks,
+    chrome: opts.chrome,
+    title: opts.title,
+    nav: opts.nav,
+    app: opts.app,
+    manifest: opts.manifest,
+    overwrite: opts.overwrite,
+    skipInstall: opts.skipInstall,
+    dryRun: opts.dryRun,
+    registry: opts.registry,
+}));
+program
+    .command("list")
+    .alias("ls")
+    .description("List all components available in the registry.")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .option("-r, --registry <source>", "registry URL or local directory")
+    .action((opts) => list({ cwd: opts.cwd, registry: opts.registry }));
+program
+    .command("diff")
+    .description("Show which installed components have drifted from the registry (run `cronus-ui upgrade` to merge updates without losing local edits).")
+    .argument("[components...]", "component names (default: all)")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .option("-r, --registry <source>", "registry URL or local directory")
+    .action((components, opts) => diff(components, { cwd: opts.cwd, registry: opts.registry }));
+program
+    .command("upgrade")
+    .description("Upgrade installed components and composed pages/layouts to the current release, keeping your local edits.")
+    .argument("[components...]", "component names (or use --all)")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .option("-r, --registry <source>", "registry URL or local directory")
+    .option("-a, --all", "upgrade every component recorded in cronus-ui.json")
+    .option("--dry-run", "print the per-file plan (fast-forward / merge / conflict), write nothing")
+    .option("-y, --yes", "assume yes: write conflict markers and confirmed overwrites without asking")
+    .option("-o, --overwrite", "components installed before the manifest existed: replace local files with upstream")
+    .option("-m, --manifest <file>", "reload composed apps from this manifest file (for --manifest-composed apps)")
+    .addHelpText("after", `
+How it works:
+  Each component's installed release is recorded in cronus-ui.json ("installed").
+  upgrade 3-way merges base (that release), local (your file) and upstream (the
+  current release) with \`git merge-file --diff3\`, so upstream fixes land WITHOUT
+  losing your edits. Clean merges are written; conflicts are written with markers
+  only if you confirm (or --yes). Unresolved files get a ready-to-paste coding
+  agent prompt in CRONUS-UPGRADE.md.
+
+  \`upgrade --all\` also 3-way-merges composed pages and layouts against their
+  \`.cronus-ui/base/<template>/\` snapshot (same decision matrix). Named
+  \`upgrade button\` does not touch composed pages. Custom --manifest apps must
+  re-supply --manifest.
+
+Examples:
+  cronus-ui upgrade --all --dry-run    preview the plan for everything installed
+  cronus-ui upgrade button card        upgrade two components
+  cronus-ui upgrade --all --yes        upgrade all, accept conflict markers`)
+    .action((components, opts) => upgrade(components, {
+    cwd: opts.cwd,
+    registry: opts.registry,
+    all: opts.all,
+    dryRun: opts.dryRun,
+    yes: opts.yes,
+    overwrite: opts.overwrite,
+    manifestPath: opts.manifest,
+}));
+const theme = program.command("theme").description("Manage the app's Cronus UI theme preset.");
+theme
+    .command("set")
+    .description("Switch the theme preset (and optionally the color mode).")
+    .argument("<name>", "theme preset (aurora, neutral, midnight, sunset, emerald)")
+    .option("-m, --mode <mode>", "color mode (dark or light)")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .action((name, opts) => themeSet({ name, mode: opts.mode, cwd: opts.cwd }));
+theme
+    .command("add")
+    .description("Apply a theme built in the Create Studio (permalink URL, bare c= payload, or exported theme JSON file).")
+    .argument("<source>", "Create Studio permalink, c= payload, or path to a theme JSON export")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .option("--css <file>", "globals CSS file for the overrides block (default: auto-detect)")
+    .option("--dry-run", "print what would be applied, write nothing")
+    .action((source, opts) => themeAdd({ source, cwd: opts.cwd, css: opts.css, dryRun: opts.dryRun }));
+program
+    .command("ai")
+    .description("Add the AI Kit (AGENTS.md doctrine + Claude Code / Cursor / Copilot / Windsurf / Gemini config).")
+    .option("-c, --cwd <dir>", "working directory", process.cwd())
+    .option("-a, --assistants <list>", "comma-separated: claude, cursor, copilot, windsurf, gemini (or 'all'/'none')")
+    .option("-p, --preset <name>", "doctrine preset: standard, fintech, saas, oss, agency, or none", "standard")
+    .option("-s, --skills <list>", "comma-separated Claude Code skills (or 'all'/'none')")
+    .action((opts) => aiAdd({
+    cwd: opts.cwd,
+    assistants: opts.assistants,
+    preset: opts.preset,
+    skills: opts.skills,
+}));
+program.parseAsync(process.argv);
+//# sourceMappingURL=index.js.map

package/dist/registry.d.ts

@@ -0,0 +1,59 @@
+/** A single file that ships with a registry item. */
+export interface RegistryFile {
+    /** Path relative to the item kind (e.g. "button.tsx" or "cn.ts"). */
+    path: string;
+    /** Raw source, with canonical `../lib/cn.js` / `./x.js` specifiers. */
+    content: string;
+    /** Where it is written in the consumer. */
+    target: "ui" | "lib" | "block";
+}
+export type RegistryItemType = "registry:ui" | "registry:lib" | "registry:block";
+export interface RegistryItem {
+    name: string;
+    type: RegistryItemType;
+    /** npm packages (with version ranges) this item imports. */
+    dependencies: string[];
+    /** other registry items this item imports (by name). */
+    registryDependencies: string[];
+    files: RegistryFile[];
+}
+export interface RegistryIndexEntry {
+    name: string;
+    type: RegistryItemType;
+    dependencies: string[];
+    registryDependencies: string[];
+}
+export type RegistryIndex = RegistryIndexEntry[];
+/** Extract the release version a registry source is pinned to, if any. */
+export declare function registrySourceVersion(source: string): string | undefined;
+/**
+ * Re-pin a versioned registry source to a different release tag. Because the
+ * default registry lives at `raw.githubusercontent.com/.../v<version>/registry`,
+ * every published release's registry stays addressable forever — `upgrade`
+ * uses this to fetch the exact merge base a component was installed from.
+ * Returns undefined when the source carries no version segment (an unversioned
+ * URL or plain local directory), in which case past releases are unreachable.
+ */
+export declare function registrySourceAtVersion(source: string, version: string): string | undefined;
+/** A registry source: either a local directory or an http(s) base URL. */
+export declare class Registry {
+    private readonly base;
+    private readonly isUrl;
+    private cache;
+    constructor(base: string);
+    private readJson;
+    index(): Promise<RegistryIndex>;
+    /**
+     * The `registry/meta.json` sidecar, or `null` when the registry does not ship
+     * one (older releases / custom registries). Mirrors the MCP client's graceful
+     * degradation so `compose` can fail with a clear message rather than a raw 404.
+     */
+    meta<T = unknown>(): Promise<T | null>;
+    item(name: string): Promise<RegistryItem>;
+    /**
+     * Resolve the full transitive closure of registry items needed for `names`,
+     * returned in dependency-first order (so files write cleanly).
+     */
+    resolve(names: string[]): Promise<RegistryItem[]>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.js

@@ -0,0 +1,96 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+/**
+ * Matches a release-pinned "/vX.Y.Z/" path segment in a registry source, e.g.
+ * ".../cronus-ui/v0.5.0/registry" (the default raw.githubusercontent.com layout)
+ * or a local ".../v0.5.0/registry" mirror. The trailing separator is a
+ * lookahead so replacements never eat it.
+ */
+const VERSION_SEGMENT_RE = /([/\\])v(\d+\.\d+\.\d+(?:-[\w.]+)?)(?=[/\\])/;
+/** Extract the release version a registry source is pinned to, if any. */
+export function registrySourceVersion(source) {
+    return VERSION_SEGMENT_RE.exec(source)?.[2];
+}
+/**
+ * Re-pin a versioned registry source to a different release tag. Because the
+ * default registry lives at `raw.githubusercontent.com/.../v<version>/registry`,
+ * every published release's registry stays addressable forever — `upgrade`
+ * uses this to fetch the exact merge base a component was installed from.
+ * Returns undefined when the source carries no version segment (an unversioned
+ * URL or plain local directory), in which case past releases are unreachable.
+ */
+export function registrySourceAtVersion(source, version) {
+    if (!VERSION_SEGMENT_RE.test(source))
+        return undefined;
+    return source.replace(VERSION_SEGMENT_RE, `$1v${version}`);
+}
+/** A registry source: either a local directory or an http(s) base URL. */
+export class Registry {
+    base;
+    isUrl;
+    cache = new Map();
+    constructor(base) {
+        this.isUrl = /^https?:\/\//.test(base);
+        this.base = this.isUrl ? base.replace(/\/$/, "") : isAbsolute(base) ? base : resolve(base);
+    }
+    async readJson(file) {
+        if (this.isUrl) {
+            const res = await fetch(`${this.base}/${file}`);
+            if (!res.ok)
+                throw new Error(`registry fetch failed (${res.status}): ${this.base}/${file}`);
+            return (await res.json());
+        }
+        const raw = await readFile(join(this.base, file), "utf8");
+        return JSON.parse(raw);
+    }
+    async index() {
+        return this.readJson("index.json");
+    }
+    /**
+     * The `registry/meta.json` sidecar, or `null` when the registry does not ship
+     * one (older releases / custom registries). Mirrors the MCP client's graceful
+     * degradation so `compose` can fail with a clear message rather than a raw 404.
+     */
+    async meta() {
+        try {
+            return await this.readJson("meta.json");
+        }
+        catch {
+            return null;
+        }
+    }
+    async item(name) {
+        const cached = this.cache.get(name);
+        if (cached)
+            return cached;
+        const item = await this.readJson(`${name}.json`);
+        this.cache.set(name, item);
+        return item;
+    }
+    /**
+     * Resolve the full transitive closure of registry items needed for `names`,
+     * returned in dependency-first order (so files write cleanly).
+     */
+    async resolve(names) {
+        const ordered = [];
+        const seen = new Set();
+        const visiting = new Set();
+        const visit = async (name) => {
+            if (seen.has(name))
+                return;
+            if (visiting.has(name))
+                return; // guard against cycles
+            visiting.add(name);
+            const item = await this.item(name);
+            for (const dep of item.registryDependencies)
+                await visit(dep);
+            visiting.delete(name);
+            seen.add(name);
+            ordered.push(item);
+        };
+        for (const name of names)
+            await visit(name);
+        return ordered;
+    }
+}
+//# sourceMappingURL=registry.js.map