@usegraft/registry 0.1.1 → 1.0.0-beta.0

package/README.md

@@ -0,0 +1,45 @@
+# @usegraft/registry
+
+> The shadcn-style registry behind `graft add`. Primitives are copied into your repository, not imported from ours.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+## The model
+
+`graft add faq` writes real files into `graft/` in your project and regenerates the barrel. You own them from that moment: edit them, delete them, or diverge entirely. There is no version of ours you are pinned to and no upgrade that overwrites your changes.
+
+That is the whole extensibility story. A plugin you cannot read is a plugin an agent cannot edit.
+
+## Install
+
+```bash
+npm i @usegraft/registry
+```
+
+Most people use `graft add` rather than this package directly.
+
+## Browse
+
+```ts
+import { listItems, describeItem, loadItem } from "@usegraft/registry";
+
+const items = listItems();
+const detail = describeItem("faq");
+```
+
+Agents reach the same surface over MCP as `list_registry` and `describe_item`.
+
+## Apply
+
+```ts
+import { loadItem, applyPlan } from "@usegraft/registry";
+
+const item = loadItem("faq");
+await applyPlan(plan);
+```
+
+`applyPlan` resolves transitive dependencies, writes the files, and regenerates the `graft/` barrel and the MDX component map.
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/registry/CHANGELOG.md)

package/dist/index.d.ts

@@ -109,7 +109,6 @@ declare function mdxComponentsSource(basenames: readonly string[]): string;
 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). */

package/dist/index.js

@@ -55,6 +55,7 @@ function satisfies(version, range) {
 }
 
 // src/barrel.ts
+import { GraftError } from "@usegraft/contracts";
 var HEADER = [
   "// Generated by `graft add` \u2014 do not edit.",
   "// Aggregates the owned primitives under graft/ into merged collections/functions.",
@@ -69,6 +70,20 @@ function moduleIdentifier(basename2) {
 }
 function barrelSource(basenames) {
   const entries = [...new Set(basenames)].sort().map((base) => ({ base, id: moduleIdentifier(base) }));
+  const byId = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    byId.set(entry.id, [...byId.get(entry.id) ?? [], entry.base]);
+  }
+  const collisions = [...byId.entries()].filter(([, files]) => files.length > 1);
+  if (collisions.length > 0) {
+    const described = collisions.map(([id, files]) => `${files.map((f) => `${f}.ts`).join(" and ")} both become "${id}"`).join("; ");
+    throw new GraftError({
+      code: "REGISTRY_ITEM_INVALID",
+      message: `Modules under graft/ collide when converted to identifiers: ${described}.`,
+      fix: "Rename one of each colliding pair so their camelCase forms differ \u2014 graft/index.ts imports each module under that name, and two imports cannot share one binding.",
+      details: { collisions: Object.fromEntries(collisions) }
+    });
+  }
   const imports = entries.map((e) => `import * as ${e.id} from "./${e.base}";`);
   const list = entries.map((e) => e.id).join(", ");
   return [
@@ -124,7 +139,7 @@ function mdxComponentsSource(basenames) {
 import { existsSync, readdirSync, readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { GraftError } from "@usegraft/contracts";
+import { GraftError as GraftError2 } from "@usegraft/contracts";
 var MANIFEST_FILE = "registry.item.json";
 function registryRoot() {
   return join(dirname(fileURLToPath(import.meta.url)), "..", "registry");
@@ -133,12 +148,21 @@ 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();
 }
+var ITEM_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function loadItem(name, root = registryRoot()) {
+  if (!ITEM_NAME_RE.test(name)) {
+    throw new GraftError2({
+      code: "REGISTRY_ITEM_INVALID",
+      message: `"${name}" is not a registry item name.`,
+      fix: 'Item names are kebab-case: lowercase letters, digits and single hyphens, e.g. "comments". Call list_registry to see what is available.',
+      details: { name, pattern: ITEM_NAME_RE.source }
+    });
+  }
   const dir = join(root, name);
   const manifestPath = join(dir, MANIFEST_FILE);
   if (!existsSync(manifestPath)) {
     const available = listItemNames(root);
-    throw new GraftError({
+    throw new GraftError2({
       code: "REGISTRY_ITEM_NOT_FOUND",
       message: `No registry item named "${name}".`,
       fix: `Add one of the available items instead: ${available.join(", ") || "(none bundled)"}.`,
@@ -149,7 +173,7 @@ function loadItem(name, root = registryRoot()) {
   try {
     raw = JSON.parse(readFileSync(manifestPath, "utf8"));
   } catch (error) {
-    throw new GraftError({
+    throw new GraftError2({
       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.",
@@ -162,7 +186,7 @@ function loadItem(name, root = registryRoot()) {
       path: i.path.join("."),
       message: i.message
     }));
-    throw new GraftError({
+    throw new GraftError2({
       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.",
@@ -170,7 +194,7 @@ function loadItem(name, root = registryRoot()) {
     });
   }
   if (parsed.data.name !== name) {
-    throw new GraftError({
+    throw new GraftError2({
       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.",
@@ -189,7 +213,7 @@ function resolveItems(names, options = {}) {
     visiting.add(name);
     const item = loadItem(name, root);
     if (options.coreVersion && !satisfies(options.coreVersion, item.graftVersion)) {
-      throw new GraftError({
+      throw new GraftError2({
         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}.`,
@@ -223,7 +247,7 @@ function listItems(root = registryRoot()) {
 // 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";
+import { GraftError as GraftError3 } from "@usegraft/contracts";
 var GRAFT_DIR = "graft";
 var COMPONENTS_DIR = "components";
 var MDX_MAP_FILE = "mdx-components.ts";
@@ -293,7 +317,7 @@ function fragmentHeading(fragment) {
 }
 function applyPlan(plan, options = {}) {
   if (!options.overwrite && plan.conflicts.length > 0) {
-    throw new GraftError2({
+    throw new GraftError3({
       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.",
@@ -303,10 +327,19 @@ function applyPlan(plan, options = {}) {
   const written = [];
   const skipped = [];
   for (const file of plan.files) {
-    if (file.identical) {
+    const current = existsSync2(file.targetPath) ? readFileSync2(file.targetPath, "utf8") : void 0;
+    if (current === file.content) {
       skipped.push(file.relPath);
       continue;
     }
+    if (current !== void 0 && !options.overwrite) {
+      throw new GraftError3({
+        code: "REGISTRY_FILE_EXISTS",
+        message: `"${file.relPath}" changed on disk after the plan was made, and adding would overwrite it.`,
+        fix: "Re-run `graft add` to plan against the current tree, or pass --overwrite if replacing that file is the intent.",
+        details: { path: file.relPath }
+      });
+    }
     mkdirSync(dirname2(file.targetPath), { recursive: true });
     writeFileSync(file.targetPath, file.content, "utf8");
     written.push(file.relPath);

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@usegraft/registry",
-  "version": "0.1.1",
+  "version": "1.0.0-beta.0",
+  "description": "The shadcn-style registry behind `graft add`. Primitives are copied into your repository, not imported from ours.",
+  "keywords": [
+    "agent",
+    "ai",
+    "cms",
+    "codegen",
+    "graft",
+    "headless-cms",
+    "mcp",
+    "primitives",
+    "registry",
+    "shadcn",
+    "typescript"
+  ],
+  "homepage": "https://github.com/AndersonDesign1/graft#readme",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@usegraft/contracts": "0.1.1",
+    "@usegraft/contracts": "1.0.0-beta.0",
     "zod": "^4.1.0"
   },
   "engines": {
@@ -35,7 +50,6 @@
     "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 ."
+    "test": "vitest run --passWithNoTests"
   }
 }

package/registry/comments/graft/comments.ts

@@ -22,9 +22,12 @@ export const comments = defineCollection({
   authority: "db-authoritative",
   description: "Visitor comments, held for moderation until approved.",
   fields: {
-    pageSlug: field.string({ description: "Slug of the page the comment belongs to." }),
-    author: field.string({ description: "Commenter's display name." }),
-    body: field.text({ description: "The comment text." }),
+    pageSlug: field.string({
+      maxLength: 200,
+      description: "Slug of the page the comment belongs to.",
+    }),
+    author: field.string({ maxLength: 80, description: "Commenter's display name." }),
+    body: field.text({ maxLength: 4000, description: "The comment text." }),
     approved: field.boolean({ description: "Only approved comments list publicly." }),
   },
 });
@@ -39,9 +42,9 @@ export const postComment = defineFunction({
     "Post a comment (public; held unapproved until a moderator approves it). 5/min per caller.",
   returns: "{ id: string; receivedAt: string }",
   input: {
-    pageSlug: field.string({ description: "Page the comment is on." }),
-    author: field.string({ description: "Display name." }),
-    body: field.text({ description: "The comment text." }),
+    pageSlug: field.string({ maxLength: 200, description: "Page the comment is on." }),
+    author: field.string({ maxLength: 80, description: "Display name." }),
+    body: field.text({ maxLength: 4000, description: "The comment text." }),
   },
   handler: async (ctx) => {
     const record = await insertRecord(ctx, comments, { ...ctx.input, approved: false });
@@ -55,21 +58,32 @@ export const listComments = defineFunction({
   kind: "query",
   description: "List approved comments for a page, newest first.",
   returns: "{ comments: { id: string; author: string; body: string; receivedAt: string }[] }",
+  rateLimit: { limit: 60, windowSeconds: 60 },
   input: {
-    pageSlug: field.string({ description: "Page to list comments for." }),
-    limit: field.number({ optional: true, description: "Max rows scanned (default 100)." }),
+    pageSlug: field.string({ maxLength: 200, description: "Page to list comments for." }),
+    limit: field.number({
+      optional: true,
+      int: true,
+      min: 1,
+      max: 100,
+      description: "Max comments to return (default 100).",
+    }),
   },
   handler: async (ctx) => {
-    const records = await listRecords(ctx, comments, { limit: ctx.input.limit ?? 100 });
+    // Both predicates run in SQL. Filtering after the row cap meant unapproved
+    // comments consumed the window, so posting enough of them hid every
+    // approved comment on every page — silently, with no error.
+    const records = await listRecords(ctx, comments, {
+      limit: ctx.input.limit ?? 100,
+      match: { approved: true, pageSlug: ctx.input.pageSlug },
+    });
     return {
-      comments: records
-        .filter((r) => r.data.approved && r.data.pageSlug === ctx.input.pageSlug)
-        .map((r) => ({
-          id: r.id,
-          author: r.data.author,
-          body: r.data.body,
-          receivedAt: r.createdAt.toISOString(),
-        })),
+      comments: records.map((r) => ({
+        id: r.id,
+        author: r.data.author,
+        body: r.data.body,
+        receivedAt: r.createdAt.toISOString(),
+      })),
     };
   },
 });

package/registry/commerce/graft/commerce.ts

@@ -40,11 +40,20 @@ export const products = defineCollection({
   name: "products",
   description: "Sellable catalog items (file-authoritative). Author under content/products/.",
   fields: {
-    title: field.string({ description: "Product name." }),
-    description: field.text({ description: "Short product description." }),
-    priceCents: field.number({ description: "Price in the smallest currency unit (e.g. cents)." }),
+    title: field.string({ maxLength: 200, description: "Product name." }),
+    description: field.text({ maxLength: 2000, description: "Short product description." }),
+    priceCents: field.number({
+      int: true,
+      min: 0,
+      max: 100_000_000,
+      description: "Price in the smallest currency unit (e.g. cents).",
+    }),
     currency: field.string({
       optional: true,
+      // Exactly three letters: Intl.NumberFormat throws a RangeError on
+      // anything else, and one malformed product used to break the whole
+      // catalog page at render time.
+      pattern: /^[A-Za-z]{3}$/,
       description: 'ISO currency code (default "USD").',
     }),
     image: field.asset({ optional: true, description: "Product image." }),
@@ -64,21 +73,25 @@ export const orders = defineCollection({
   authority: "db-authoritative",
   description: "Customer orders. Place via placeOrder; admin via list/update/cancel.",
   fields: {
-    email: field.string({ description: "Buyer email." }),
+    email: field.string({ maxLength: 320, description: "Buyer email." }),
     items: field.array({
       description: "Line items snapshotted at order time (price locked).",
       of: field.object({
         fields: {
-          productSlug: field.string({ description: "Catalog product slug." }),
-          qty: field.number({ description: "Quantity (>= 1)." }),
-          unitPriceCents: field.number({ description: "Unit price at order time." }),
+          productSlug: field.string({ maxLength: 200, description: "Catalog product slug." }),
+          qty: field.number({ int: true, min: 1, max: 10_000, description: "Quantity (1-10000)." }),
+          unitPriceCents: field.number({
+            int: true,
+            min: 0,
+            description: "Unit price at order time.",
+          }),
         },
       }),
     }),
     status: field.string({
       description: "pending | paid | cancelled | fulfilled",
     }),
-    totalCents: field.number({ description: "Sum of qty * unitPriceCents." }),
+    totalCents: field.number({ int: true, min: 0, description: "Sum of qty * unitPriceCents." }),
   },
 });
 
@@ -96,25 +109,31 @@ async function loadProducts(
 ): Promise<Map<string, ProductRow>> {
   const unique = [...new Set(slugs)];
   const out = new Map<string, ProductRow>();
-  for (const slug of unique) {
-    const row = await ctx.db.query.contentIndex.findFirst({
-      where: (t, ops) =>
-        ops.and(
-          ops.eq(t.branchId, ctx.branch),
-          ops.eq(t.collection, "products"),
-          ops.eq(t.slug, slug),
-          ops.eq(t.deleted, false),
-        ),
-    });
-    if (!row) continue;
+  if (unique.length === 0) return out;
+
+  // One query, not one per slug. The loop this replaces ran before unknown
+  // slugs were rejected, so a request carrying thousands of bogus slugs held a
+  // pooled connection for that many serial round-trips and only then failed
+  // validation — starving every other function sharing the pool.
+  const rows = await ctx.db.query.contentIndex.findMany({
+    where: (t, ops) =>
+      ops.and(
+        ops.eq(t.branchId, ctx.branch),
+        ops.eq(t.collection, "products"),
+        ops.inArray(t.slug, unique),
+        ops.eq(t.deleted, false),
+      ),
+  });
+
+  for (const row of rows) {
     const data = row.data as {
       title?: string;
       priceCents?: number;
       active?: boolean;
     };
     if (typeof data.priceCents !== "number" || typeof data.title !== "string") continue;
-    out.set(slug, {
-      slug,
+    out.set(row.slug, {
+      slug: row.slug,
       title: data.title,
       priceCents: data.priceCents,
       active: data.active !== false,
@@ -133,13 +152,21 @@ export const placeOrder = defineFunction({
     "Place an order for active products. Snapshots unit prices; status starts as pending. 10/min per caller.",
   returns: "{ id: string; totalCents: number; status: string; receivedAt: string }",
   input: {
-    email: field.string({ description: "Buyer email." }),
+    email: field.string({ maxLength: 320, description: "Buyer email." }),
     items: field.array({
       description: "What to buy.",
+      // Capped: each entry drives catalog work, so an uncapped array is a
+      // per-request amplifier.
+      maxItems: 100,
       of: field.object({
         fields: {
-          productSlug: field.string({ description: "Product slug from content/products/." }),
-          qty: field.number({ description: "Quantity (>= 1)." }),
+          productSlug: field.string({
+            maxLength: 200,
+            description: "Product slug from content/products/.",
+          }),
+          // Bounded so price x qty cannot exceed Number.MAX_SAFE_INTEGER and
+          // silently store a wrong total.
+          qty: field.number({ int: true, min: 1, max: 10_000, description: "Quantity (1-10000)." }),
         },
       }),
     }),
@@ -224,7 +251,13 @@ export const listOrders = defineFunction({
   description: "List recent orders, newest first. Requires commerce:orders:read.",
   returns: "{ orders: { id, email, status, totalCents, items, receivedAt }[] }",
   input: {
-    limit: field.number({ optional: true, description: "Max rows (default 50)." }),
+    limit: field.number({
+      optional: true,
+      int: true,
+      min: 1,
+      max: 200,
+      description: "Max rows (default 50).",
+    }),
   },
   access: requireOrdersRead,
   handler: async (ctx) => {
@@ -250,8 +283,8 @@ export const updateOrderStatus = defineFunction({
     "Set an order's status (pending|paid|cancelled|fulfilled). Requires commerce:orders:write.",
   returns: "{ id: string; status: string }",
   input: {
-    id: field.string({ description: "Order row id (uuid)." }),
-    status: field.string({ description: "pending | paid | cancelled | fulfilled" }),
+    id: field.string({ maxLength: 64, description: "Order row id (uuid)." }),
+    status: field.string({ maxLength: 32, description: "pending | paid | cancelled | fulfilled" }),
   },
   access: requireOrdersWrite,
   handler: async (ctx) => {