@usegraft/registry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,203 @@
+import { z } from 'zod';
+import { RegistryItemDescriptor } from '@usegraft/contracts';
+
+/**
+ * The registry item manifest — `registry.item.json` inside each bundled item.
+ *
+ * A registry item is a unit of owned, copy-in code (a shadcn-style primitive):
+ * some files, the npm/registry things it needs first, a semver range against
+ * @usegraft/core, and an optional llms.txt teaching fragment. Validated by this
+ * Zod schema on load, so a malformed item is a REGISTRY_ITEM_INVALID up front —
+ * never a half-written project. (See docs/design-notes/registry.md.)
+ */
+
+/** What kind of primitive this is — decides where its files conventionally land. */
+declare const ITEM_TYPES: readonly ["block", "field", "access", "bundle"];
+type ItemType = (typeof ITEM_TYPES)[number];
+/**
+ * A file the item ships. `role` decides how `graft add` treats it:
+ * - `module`  → a `graft/*.ts` primitive that the barrel aggregates
+ * - `component`→ a UI component (e.g. under components/)
+ * - `content` → an authored MDX file
+ * - `env`     → an env-var sample (printed, not merged, for now)
+ * - `editor`  → an `EditorComponentSpec` JSON saying how the component presents
+ *               in the Studio canvas. Owned like everything else an item ships:
+ *               it lands in `graft/editor/` and the Studio reads it from the
+ *               project, never from the registry it came from.
+ */
+declare const FILE_ROLES: readonly ["module", "component", "content", "env", "editor"];
+type FileRole = (typeof FILE_ROLES)[number];
+declare const registryFileSchema: z.ZodObject<{
+    source: z.ZodString;
+    target: z.ZodString;
+    role: z.ZodDefault<z.ZodEnum<{
+        module: "module";
+        component: "component";
+        content: "content";
+        env: "env";
+        editor: "editor";
+    }>>;
+}, z.core.$strip>;
+type RegistryFile = z.infer<typeof registryFileSchema>;
+declare const registryItemSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        block: "block";
+        field: "field";
+        access: "access";
+        bundle: "bundle";
+    }>;
+    description: z.ZodString;
+    graftVersion: z.ZodDefault<z.ZodString>;
+    dependencies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    registryDependencies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    files: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        target: z.ZodString;
+        role: z.ZodDefault<z.ZodEnum<{
+            module: "module";
+            component: "component";
+            content: "content";
+            env: "env";
+            editor: "editor";
+        }>>;
+    }, z.core.$strip>>;
+    llms: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type RegistryItemManifest = z.infer<typeof registryItemSchema>;
+/** A loaded item: its validated manifest plus the absolute directory it lives in. */
+interface RegistryItem extends RegistryItemManifest {
+    /** Absolute path to the item's directory in the bundled registry. */
+    dir: string;
+}
+
+/**
+ * A deliberately tiny semver check — enough to gate a registry item's
+ * `graftVersion` against the installed @usegraft/core, with no dependency.
+ *
+ * Supported:
+ * - "*" / "" / "x"        → any version
+ * - space-separated AND of comparators: `>=1.2.0 <2.0.0`, `>1.0.0`, `=1.2.3`, `1.2.3` (exact)
+ *
+ * Caret/tilde/prerelease ranges are out of scope until an item actually needs
+ * them (bundled Tier-1 items use "*" pre-1.0). Unparseable input fails closed.
+ */
+type Triple = [number, number, number];
+declare function parseVersion(v: string): Triple | null;
+declare function satisfies(version: string, range: string): boolean;
+
+/** A `graft/<basename>.ts` basename → a safe, camelCase JS identifier. */
+declare function moduleIdentifier(basename: string): string;
+/** Barrel source for the given primitive module basenames (deduped + sorted). */
+declare function barrelSource(basenames: readonly string[]): string;
+
+/** `Callout.tsx` / `callout.tsx` → export identifier `Callout` (PascalCase). */
+declare function componentExportName(filename: string): string;
+/**
+ * MDX map source for the given component basenames (no extension).
+ * Empty list → empty map object (valid; pages render markdown-only MDX).
+ */
+declare function mdxComponentsSource(basenames: readonly string[]): string;
+
+/**
+ * The bundled registry root — the sibling `registry/` dir (one level up from src
+ * or dist). Built from `import.meta.url` via path.join rather than
+ * `new URL("../registry", import.meta.url)` so bundlers (Turbopack in the Next
+ * example) don't try to statically resolve the directory as a module asset; it
+ * stays plain runtime code. The package is server-external where it runs bundled.
+ */
+declare function registryRoot(): string;
+/** Names of every bundled item (a subdirectory holding a manifest), sorted. */
+declare function listItemNames(root?: string): string[];
+/** Load + validate one item by name. Throws REGISTRY_ITEM_NOT_FOUND / _INVALID. */
+declare function loadItem(name: string, root?: string): RegistryItem;
+interface ResolveOptions {
+    /** Registry root override (tests point this at a fixture dir). */
+    root?: string;
+    /** Installed @usegraft/core version, to gate each item's graftVersion. Skipped if omitted. */
+    coreVersion?: string;
+}
+/**
+ * Resolve items plus their `registryDependencies` — transitively, deduped,
+ * dependency-first (post-order). Cycles are broken (an item already being
+ * visited is skipped). A version mismatch throws REGISTRY_ITEM_INVALID.
+ */
+declare function resolveItems(names: readonly string[], options?: ResolveOptions): RegistryItem[];
+/**
+ * The agent-facing description of one item (the `describe_item` MCP shape).
+ * Drops the machine-specific absolute `dir` and reduces files to what an agent
+ * needs: where they land and their role. `llms` becomes a boolean flag.
+ */
+declare function describeItem(item: RegistryItem): RegistryItemDescriptor;
+/**
+ * Every bundled item as a descriptor, sorted by name — the `list_registry`
+ * source. Loads + validates each manifest, so a malformed bundled item surfaces
+ * as REGISTRY_ITEM_INVALID here too.
+ */
+declare function listItems(root?: string): RegistryItemDescriptor[];
+
+interface PlannedFile {
+    /** Absolute path to write. */
+    targetPath: string;
+    /** Path relative to the project root — for display. */
+    relPath: string;
+    content: string;
+    role: string;
+    /** A file already exists at targetPath. */
+    exists: boolean;
+    /** The existing file is byte-identical to `content` (a no-op re-add). */
+    identical: boolean;
+}
+interface AddPlan {
+    items: RegistryItem[];
+    files: PlannedFile[];
+    /** The regenerated barrel — always written (generated infra, never a conflict). */
+    barrel: {
+        targetPath: string;
+        relPath: string;
+        content: string;
+    };
+    /**
+     * The regenerated MDX component map. Present when the project has (or this
+     * plan adds) any component-role files, or when components/ already exists.
+     */
+    mdxMap: {
+        targetPath: string;
+        relPath: string;
+        content: string;
+    } | null;
+    /** llms.txt fragments (one per item that ships one), appended if not already present. */
+    llms: {
+        targetPath: string;
+        fragments: string[];
+    };
+    /** npm packages to ensure installed (union across items) — printed, not run. */
+    npmDependencies: Record<string, string>;
+    /** Existing files that DIFFER and would be overwritten (guarded at apply time). */
+    conflicts: string[];
+}
+interface PlanAddOptions extends ResolveOptions {
+    /** Project root — the directory holding graft.config.ts. */
+    targetDir: string;
+}
+/**
+ * Component basenames under components/ for the MDX map.
+ * Convention: only PascalCase `*.tsx` files (Callout.tsx, Faq.tsx) — skips
+ * app helpers like page.tsx / contact-form.tsx and the generated map itself.
+ */
+declare function listMdxComponents(componentsDir: string): string[];
+declare function planAdd(names: readonly string[], options: PlanAddOptions): AddPlan;
+interface ApplyResult {
+    /** Files newly written or overwritten. */
+    written: string[];
+    /** Existing identical files left untouched. */
+    skipped: string[];
+    barrelPath: string;
+    mdxMapPath: string | null;
+    llmsAppended: boolean;
+}
+declare function applyPlan(plan: AddPlan, options?: {
+    overwrite?: boolean;
+}): ApplyResult;
+
+export { type AddPlan, type ApplyResult, FILE_ROLES, type FileRole, ITEM_TYPES, type ItemType, type PlanAddOptions, type PlannedFile, type RegistryFile, type RegistryItem, type RegistryItemManifest, type ResolveOptions, applyPlan, barrelSource, componentExportName, describeItem, listItemNames, listItems, listMdxComponents, loadItem, mdxComponentsSource, moduleIdentifier, parseVersion, planAdd, registryFileSchema, registryItemSchema, registryRoot, resolveItems, satisfies };

package/dist/index.js

@@ -0,0 +1,365 @@
+// src/manifest.ts
+import { z } from "zod";
+var ITEM_TYPES = ["block", "field", "access", "bundle"];
+var FILE_ROLES = ["module", "component", "content", "env", "editor"];
+var registryFileSchema = z.object({
+  /** Path to the file inside the item directory. */
+  source: z.string().min(1),
+  /** Path to write, relative to the target project root. */
+  target: z.string().min(1),
+  role: z.enum(FILE_ROLES).default("module")
+});
+var registryItemSchema = z.object({
+  /** Item id — must equal its directory name. */
+  name: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "must be lowercase kebab-case"),
+  type: z.enum(ITEM_TYPES),
+  description: z.string().min(1),
+  /** Semver range against the installed @usegraft/core. "*" = any (pre-1.0 default). */
+  graftVersion: z.string().default("*"),
+  /** npm packages the target needs; printed for the operator to install (not run). */
+  dependencies: z.record(z.string(), z.string()).default({}),
+  /** Other registry items to add first (transitive, deduped, deps-first). */
+  registryDependencies: z.array(z.string()).default([]),
+  files: z.array(registryFileSchema).min(1),
+  /** Path (inside the item dir) to an llms.txt fragment appended on add. */
+  llms: z.string().min(1).optional()
+});
+
+// src/version.ts
+function parseVersion(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function compare(a, b) {
+  if (a[0] !== b[0]) return a[0] < b[0] ? -1 : 1;
+  if (a[1] !== b[1]) return a[1] < b[1] ? -1 : 1;
+  if (a[2] !== b[2]) return a[2] < b[2] ? -1 : 1;
+  return 0;
+}
+function satisfies(version, range) {
+  const trimmed = range.trim();
+  if (trimmed === "" || trimmed === "*" || trimmed === "x") return true;
+  const v = parseVersion(version);
+  if (!v) return false;
+  for (const comparator of trimmed.split(/\s+/)) {
+    const m = /^(>=|<=|>|<|=)?(.+)$/.exec(comparator);
+    const target = m ? parseVersion(m[2] ?? "") : null;
+    if (!m || !target) return false;
+    const cmp = compare(v, target);
+    const op = m[1] ?? "=";
+    const ok = op === ">=" ? cmp >= 0 : op === "<=" ? cmp <= 0 : op === ">" ? cmp > 0 : op === "<" ? cmp < 0 : cmp === 0;
+    if (!ok) return false;
+  }
+  return true;
+}
+
+// src/barrel.ts
+var HEADER = [
+  "// Generated by `graft add` \u2014 do not edit.",
+  "// Aggregates the owned primitives under graft/ into merged collections/functions.",
+  "// Safe to delete: `graft add` regenerates it from whatever modules live in graft/."
+];
+function moduleIdentifier(basename2) {
+  const camel = basename2.replace(
+    /[^a-zA-Z0-9]+(.)?/g,
+    (_all, next) => next ? next.toUpperCase() : ""
+  );
+  return /^[a-zA-Z_$]/.test(camel) ? camel : `_${camel}`;
+}
+function barrelSource(basenames) {
+  const entries = [...new Set(basenames)].sort().map((base) => ({ base, id: moduleIdentifier(base) }));
+  const imports = entries.map((e) => `import * as ${e.id} from "./${e.base}";`);
+  const list = entries.map((e) => e.id).join(", ");
+  return [
+    ...HEADER,
+    'import { mergePrimitives } from "@usegraft/core";',
+    ...imports,
+    "",
+    `export const { collections, functions } = mergePrimitives([${list}]);`,
+    ""
+  ].join("\n");
+}
+
+// src/mdx-map.ts
+var HEADER2 = [
+  "// Generated by `graft add` \u2014 do not edit.",
+  "// MDX component map for @usegraft/sdk-next MdxBody. Safe to delete: `graft add`",
+  "// regenerates it from whatever PascalCase *.tsx files live in components/."
+];
+function componentExportName(filename) {
+  const base = filename.replace(/\.tsx?$/, "");
+  if (!base) return "Component";
+  return base.charAt(0).toUpperCase() + base.slice(1);
+}
+function mdxComponentsSource(basenames) {
+  const entries = [...new Set(basenames)].map((base) => {
+    const fileBase = base.replace(/\.tsx?$/, "");
+    return { fileBase, exportName: componentExportName(fileBase) };
+  }).sort((a, b) => a.exportName.localeCompare(b.exportName));
+  if (entries.length === 0) {
+    return [
+      ...HEADER2,
+      'import type { MdxComponents } from "@usegraft/sdk-next";',
+      "",
+      "export const mdxComponents: MdxComponents = {};",
+      ""
+    ].join("\n");
+  }
+  const imports = entries.map((e) => `import { ${e.exportName} } from "./${e.fileBase}";`);
+  const props = entries.map((e) => `  ${e.exportName},`).join("\n");
+  return [
+    ...HEADER2,
+    'import type { MdxComponents } from "@usegraft/sdk-next";',
+    ...imports,
+    "",
+    "export const mdxComponents: MdxComponents = {",
+    props,
+    "};",
+    ""
+  ].join("\n");
+}
+
+// src/registry.ts
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { GraftError } from "@usegraft/contracts";
+var MANIFEST_FILE = "registry.item.json";
+function registryRoot() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "registry");
+}
+function listItemNames(root = registryRoot()) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && existsSync(join(root, entry.name, MANIFEST_FILE))).map((entry) => entry.name).sort();
+}
+function loadItem(name, root = registryRoot()) {
+  const dir = join(root, name);
+  const manifestPath = join(dir, MANIFEST_FILE);
+  if (!existsSync(manifestPath)) {
+    const available = listItemNames(root);
+    throw new GraftError({
+      code: "REGISTRY_ITEM_NOT_FOUND",
+      message: `No registry item named "${name}".`,
+      fix: `Add one of the available items instead: ${available.join(", ") || "(none bundled)"}.`,
+      details: { name, available }
+    });
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    throw new GraftError({
+      code: "REGISTRY_ITEM_INVALID",
+      message: `Item "${name}" has an unparseable ${MANIFEST_FILE}: ${error instanceof Error ? error.message : String(error)}`,
+      fix: "This is a registry bug \u2014 the manifest must be valid JSON. Fix the item or report it.",
+      details: { name }
+    });
+  }
+  const parsed = registryItemSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => ({
+      path: i.path.join("."),
+      message: i.message
+    }));
+    throw new GraftError({
+      code: "REGISTRY_ITEM_INVALID",
+      message: `Item "${name}" has an invalid ${MANIFEST_FILE}.`,
+      fix: "This is a registry bug \u2014 the manifest does not match the item schema (see details.issues). Fix the item or report it.",
+      details: { name, issues }
+    });
+  }
+  if (parsed.data.name !== name) {
+    throw new GraftError({
+      code: "REGISTRY_ITEM_INVALID",
+      message: `Item in "${name}/" declares name "${parsed.data.name}" \u2014 it must match its directory.`,
+      fix: "Rename the directory or the manifest `name` so they agree.",
+      details: { name, declared: parsed.data.name }
+    });
+  }
+  return { ...parsed.data, dir };
+}
+function resolveItems(names, options = {}) {
+  const root = options.root ?? registryRoot();
+  const resolved = [];
+  const done = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const visit = (name) => {
+    if (done.has(name) || visiting.has(name)) return;
+    visiting.add(name);
+    const item = loadItem(name, root);
+    if (options.coreVersion && !satisfies(options.coreVersion, item.graftVersion)) {
+      throw new GraftError({
+        code: "REGISTRY_ITEM_INVALID",
+        message: `Item "${name}" needs @usegraft/core ${item.graftVersion}, but ${options.coreVersion} is installed.`,
+        fix: `Move @usegraft/core into ${item.graftVersion}, or use a version of "${name}" compatible with ${options.coreVersion}.`,
+        details: { name, needs: item.graftVersion, installed: options.coreVersion }
+      });
+    }
+    for (const dep of item.registryDependencies) visit(dep);
+    visiting.delete(name);
+    done.add(name);
+    resolved.push(item);
+  };
+  for (const name of names) visit(name);
+  return resolved;
+}
+function describeItem(item) {
+  return {
+    name: item.name,
+    type: item.type,
+    description: item.description,
+    graftVersion: item.graftVersion,
+    dependencies: item.dependencies,
+    registryDependencies: item.registryDependencies,
+    files: item.files.map((file) => ({ target: file.target, role: file.role })),
+    llms: item.llms !== void 0
+  };
+}
+function listItems(root = registryRoot()) {
+  return listItemNames(root).map((name) => describeItem(loadItem(name, root)));
+}
+
+// src/add.ts
+import { existsSync as existsSync2, mkdirSync, readdirSync as readdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { basename, dirname as dirname2, join as join2 } from "path";
+import { GraftError as GraftError2 } from "@usegraft/contracts";
+var GRAFT_DIR = "graft";
+var COMPONENTS_DIR = "components";
+var MDX_MAP_FILE = "mdx-components.ts";
+function listGraftModules(graftDir) {
+  if (!existsSync2(graftDir)) return [];
+  return readdirSync2(graftDir).filter((f) => f.endsWith(".ts") && f !== "index.ts").map((f) => f.slice(0, -".ts".length));
+}
+function listMdxComponents(componentsDir) {
+  if (!existsSync2(componentsDir)) return [];
+  return readdirSync2(componentsDir).filter((f) => f.endsWith(".tsx") && /^[A-Z]/.test(f)).map((f) => f.replace(/\.tsx$/, ""));
+}
+function planAdd(names, options) {
+  const { targetDir } = options;
+  const items = resolveItems(names, options);
+  const files = [];
+  const npmDependencies = {};
+  const fragments = [];
+  const newModules = [];
+  const newComponents = [];
+  for (const item of items) {
+    Object.assign(npmDependencies, item.dependencies);
+    for (const file of item.files) {
+      const content = readFileSync2(join2(item.dir, file.source), "utf8");
+      const targetPath = join2(targetDir, file.target);
+      const exists = existsSync2(targetPath);
+      const identical = exists && readFileSync2(targetPath, "utf8") === content;
+      files.push({ targetPath, relPath: file.target, content, role: file.role, exists, identical });
+      if (file.role === "module") {
+        const parts = file.target.replace(/\\/g, "/").split("/");
+        if (parts.length === 2 && parts[0] === GRAFT_DIR && parts[1]?.endsWith(".ts")) {
+          newModules.push(basename(file.target).replace(/\.ts$/, ""));
+        }
+      }
+      if (file.role === "component" && file.target.replace(/\\/g, "/").startsWith(`${COMPONENTS_DIR}/`)) {
+        const base = basename(file.target).replace(/\.tsx$/, "");
+        if (base !== "mdx-components") newComponents.push(base);
+      }
+    }
+    if (item.llms) fragments.push(readFileSync2(join2(item.dir, item.llms), "utf8").trimEnd());
+  }
+  const graftDir = join2(targetDir, GRAFT_DIR);
+  const modules = [.../* @__PURE__ */ new Set([...listGraftModules(graftDir), ...newModules])];
+  const componentsDir = join2(targetDir, COMPONENTS_DIR);
+  const componentNames = [.../* @__PURE__ */ new Set([...listMdxComponents(componentsDir), ...newComponents])];
+  const touchesComponents = newComponents.length > 0 || existsSync2(componentsDir) || existsSync2(join2(componentsDir, MDX_MAP_FILE));
+  return {
+    items,
+    files,
+    barrel: {
+      targetPath: join2(graftDir, "index.ts"),
+      relPath: join2(GRAFT_DIR, "index.ts"),
+      content: barrelSource(modules)
+    },
+    mdxMap: touchesComponents ? {
+      targetPath: join2(componentsDir, MDX_MAP_FILE),
+      relPath: join2(COMPONENTS_DIR, MDX_MAP_FILE),
+      content: mdxComponentsSource(componentNames)
+    } : null,
+    llms: { targetPath: join2(targetDir, "llms.txt"), fragments },
+    npmDependencies,
+    conflicts: files.filter((f) => f.exists && !f.identical).map((f) => f.relPath)
+  };
+}
+function fragmentHeading(fragment) {
+  const lines = fragment.split("\n");
+  return lines.find((l) => l.startsWith("## ")) ?? lines[0] ?? fragment.slice(0, 24);
+}
+function applyPlan(plan, options = {}) {
+  if (!options.overwrite && plan.conflicts.length > 0) {
+    throw new GraftError2({
+      code: "REGISTRY_FILE_EXISTS",
+      message: `Adding ${plan.items.map((i) => i.name).join(", ")} would overwrite ${plan.conflicts.length} existing file(s) that differ: ${plan.conflicts.join(", ")}.`,
+      fix: "Re-run with --overwrite to replace them, or move/rename those files first. `graft add --dry-run <item>` previews every path an item writes.",
+      details: { conflicts: plan.conflicts }
+    });
+  }
+  const written = [];
+  const skipped = [];
+  for (const file of plan.files) {
+    if (file.identical) {
+      skipped.push(file.relPath);
+      continue;
+    }
+    mkdirSync(dirname2(file.targetPath), { recursive: true });
+    writeFileSync(file.targetPath, file.content, "utf8");
+    written.push(file.relPath);
+  }
+  const graftDir = dirname2(plan.barrel.targetPath);
+  mkdirSync(graftDir, { recursive: true });
+  writeFileSync(plan.barrel.targetPath, barrelSource(listGraftModules(graftDir)), "utf8");
+  let mdxMapPath = null;
+  if (plan.mdxMap) {
+    const componentsDir = dirname2(plan.mdxMap.targetPath);
+    mkdirSync(componentsDir, { recursive: true });
+    writeFileSync(
+      plan.mdxMap.targetPath,
+      mdxComponentsSource(listMdxComponents(componentsDir)),
+      "utf8"
+    );
+    mdxMapPath = plan.mdxMap.relPath;
+  }
+  let llmsAppended = false;
+  const existing = existsSync2(plan.llms.targetPath) ? readFileSync2(plan.llms.targetPath, "utf8") : "";
+  const fresh = plan.llms.fragments.filter(
+    (f) => f.trim().length > 0 && !existing.includes(fragmentHeading(f))
+  );
+  if (fresh.length > 0) {
+    const separator = existing.trim().length > 0 ? "\n\n" : "";
+    writeFileSync(
+      plan.llms.targetPath,
+      `${existing.trimEnd()}${separator}${fresh.join("\n\n")}
+`,
+      "utf8"
+    );
+    llmsAppended = true;
+  }
+  return { written, skipped, barrelPath: plan.barrel.relPath, mdxMapPath, llmsAppended };
+}
+export {
+  FILE_ROLES,
+  ITEM_TYPES,
+  applyPlan,
+  barrelSource,
+  componentExportName,
+  describeItem,
+  listItemNames,
+  listItems,
+  listMdxComponents,
+  loadItem,
+  mdxComponentsSource,
+  moduleIdentifier,
+  parseVersion,
+  planAdd,
+  registryFileSchema,
+  registryItemSchema,
+  registryRoot,
+  resolveItems,
+  satisfies
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@usegraft/registry",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/registry"
+  },
+  "files": [
+    "dist",
+    "registry"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.1.0",
+    "@usegraft/contracts": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "oxlint ."
+  }
+}

package/registry/callout/components/Callout.tsx

@@ -0,0 +1,34 @@
+/**
+ * Callout — MDX block (owned code; edit freely).
+ *
+ * Use in authored MDX bodies:
+ *
+ *   <Callout type="info">Agents edit this file; git is the version history.</Callout>
+ *
+ * Wired into the generated `components/mdx-components.ts` map by `graft add`.
+ */
+import type { ReactNode } from "react";
+
+export type CalloutType = "info" | "warning" | "tip";
+
+export interface CalloutProps {
+  type?: CalloutType;
+  title?: string;
+  children?: ReactNode;
+}
+
+const LABELS: Record<CalloutType, string> = {
+  info: "Note",
+  warning: "Warning",
+  tip: "Tip",
+};
+
+export function Callout({ type = "info", title, children }: CalloutProps) {
+  const label = title ?? LABELS[type];
+  return (
+    <aside className={`callout callout-${type}`} data-callout={type} role="note">
+      <strong className="callout-label">{label}</strong>
+      <div className="callout-body">{children}</div>
+    </aside>
+  );
+}

package/registry/callout/components/callout.llms.txt

@@ -0,0 +1,19 @@
+## callout (primitive)
+
+MDX block at `components/Callout.tsx`, registered in the generated
+`components/mdx-components.ts` map. Use inside any page body:
+
+    <Callout type="info">
+      Agents edit MDX; git is the version history.
+    </Callout>
+
+    <Callout type="warning" title="Breaking">
+      Pre-1.0 APIs may change for the better long-run design.
+    </Callout>
+
+    <Callout type="tip">
+      Run `graft compile` after editing content.
+    </Callout>
+
+`type` is `info` | `warning` | `tip` (default `info`). Optional `title`
+overrides the default label. Style via `.callout`, `.callout-info`, etc.