@usegraft/registry 0.1.0

package/registry/callout/editor/Callout.json

@@ -0,0 +1,15 @@
+{
+  "component": "Callout",
+  "label": "Callout",
+  "titleProp": "title",
+  "tone": {
+    "prop": "type",
+    "map": {
+      "info": "info",
+      "warning": "warn",
+      "tip": "success"
+    }
+  },
+  "hideProps": ["type"],
+  "snippet": "<Callout type=\"info\">\nSomething worth pulling out of the paragraph.\n</Callout>"
+}

package/registry/callout/registry.item.json

@@ -0,0 +1,13 @@
+{
+  "name": "callout",
+  "type": "block",
+  "description": "MDX Callout block — highlight info, warning, or tip callouts in authored content.",
+  "graftVersion": "*",
+  "dependencies": {},
+  "registryDependencies": [],
+  "files": [
+    { "source": "components/Callout.tsx", "target": "components/Callout.tsx", "role": "component" },
+    { "source": "editor/Callout.json", "target": "graft/editor/Callout.json", "role": "editor" }
+  ],
+  "llms": "components/callout.llms.txt"
+}

package/registry/comments/graft/comments.llms.txt

@@ -0,0 +1,14 @@
+## comments (primitive)
+
+Moderated comments backed by db-authoritative rows (`graft/comments.ts`).
+Functions are served at POST /api/fn/<name>:
+
+- `postComment` — public; `{ pageSlug, author, body }` → stores it unapproved. 5/min per caller.
+- `listComments` — public; `{ pageSlug, limit? }` → approved comments, newest first.
+- `moderateComment` — `{ id, approved }` → approve/hide. Needs the `content:moderate` scope.
+- `deleteComment` — `{ id }` → destructive: files an approval (`graft approve <id>`), then
+  retry with the approval id (MCP: the `approval` argument; HTTP: the
+  `x-graft-approval` header); also needs `content:moderate`.
+
+New comments are hidden until `moderateComment` approves them. Depends on the
+`scoped-access` primitive (`graft/scoped-access.ts`) for the moderation gate.

package/registry/comments/graft/comments.ts

@@ -0,0 +1,113 @@
+/**
+ * comments — a moderated-comments primitive (owned code; edit freely).
+ *
+ * A db-authoritative collection plus its functions: post (public), list
+ * (public; approved only), moderate (approve/hide; scope-gated), and delete
+ * (destructive; human-gated). Wired automatically via the graft/ barrel — live
+ * on the next `graft compile`. See graft/comments.llms.txt for the flow.
+ */
+import {
+  defineCollection,
+  defineFunction,
+  deleteRecord,
+  field,
+  insertRecord,
+  listRecords,
+  updateRecord,
+} from "@usegraft/core";
+import { requireModerator } from "./scoped-access";
+
+export const comments = defineCollection({
+  name: "comments",
+  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." }),
+    approved: field.boolean({ description: "Only approved comments list publicly." }),
+  },
+});
+
+/** Public: anyone may post; the comment is held unapproved until moderated. */
+export const postComment = defineFunction({
+  name: "postComment",
+  kind: "mutation",
+  public: true,
+  rateLimit: { limit: 5, windowSeconds: 60 },
+  description:
+    "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." }),
+  },
+  handler: async (ctx) => {
+    const record = await insertRecord(ctx, comments, { ...ctx.input, approved: false });
+    return { id: record.id, receivedAt: record.createdAt.toISOString() };
+  },
+});
+
+/** Public: only approved comments for the page, newest first. */
+export const listComments = defineFunction({
+  name: "listComments",
+  kind: "query",
+  description: "List approved comments for a page, newest first.",
+  returns: "{ comments: { id: string; author: string; body: string; receivedAt: string }[] }",
+  input: {
+    pageSlug: field.string({ description: "Page to list comments for." }),
+    limit: field.number({ optional: true, description: "Max rows scanned (default 100)." }),
+  },
+  handler: async (ctx) => {
+    const records = await listRecords(ctx, comments, { limit: ctx.input.limit ?? 100 });
+    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(),
+        })),
+    };
+  },
+});
+
+/** Scope-gated: approve or hide a comment. Needs the content:moderate scope. */
+export const moderateComment = defineFunction({
+  name: "moderateComment",
+  kind: "mutation",
+  description: "Approve or hide a comment. Requires the content:moderate scope.",
+  returns: "{ id: string; approved: boolean }",
+  input: {
+    id: field.string({ description: "The comment row id (uuid)." }),
+    approved: field.boolean({ description: "true to approve (publish), false to hide." }),
+  },
+  access: requireModerator,
+  handler: async (ctx) => {
+    const record = await updateRecord(ctx, comments, ctx.input.id, {
+      approved: ctx.input.approved,
+    });
+    return { id: record.id, approved: record.data.approved };
+  },
+});
+
+/** Destructive + scope-gated: permanently delete a comment (human-gated). */
+export const deleteComment = defineFunction({
+  name: "deleteComment",
+  kind: "mutation",
+  destructive: true,
+  description:
+    "Permanently delete a comment. Destructive: requires human approval (graft approve) and the content:moderate scope.",
+  returns: "{ deleted: { id: string } }",
+  input: { id: field.string({ description: "The comment row id (uuid)." }) },
+  access: requireModerator,
+  handler: async (ctx) => {
+    const removed = await deleteRecord(ctx, comments, ctx.input.id);
+    return { deleted: { id: removed.id } };
+  },
+});
+
+export const collections = { comments };
+export const functions = { postComment, listComments, moderateComment, deleteComment };

package/registry/comments/registry.item.json

@@ -0,0 +1,10 @@
+{
+  "name": "comments",
+  "type": "bundle",
+  "description": "Moderated comments: a db-authoritative collection + post/list/moderate/delete functions.",
+  "graftVersion": "*",
+  "dependencies": {},
+  "registryDependencies": ["scoped-access"],
+  "files": [{ "source": "graft/comments.ts", "target": "graft/comments.ts", "role": "module" }],
+  "llms": "graft/comments.llms.txt"
+}

package/registry/commerce/graft/commerce.llms.txt

@@ -0,0 +1,35 @@
+## commerce (primitive)
+
+Catalog + orders foundation in `graft/commerce.ts`.
+
+### Catalog (files)
+
+Author products under `content/products/<slug>.mdx`:
+
+    ---
+    title: Widget
+    description: A fine widget.
+    priceCents: 2900
+    currency: USD
+    active: true
+    ---
+
+    Longer product body (MDX)…
+
+Then `graft compile`. List via sdk `listContent("products")` or MCP `list_content`.
+
+### Orders (Postgres)
+
+Functions at POST /api/fn/<name>:
+
+- `placeOrder` — public; `{ email, items: [{ productSlug, qty }] }` → creates a
+  `pending` order with snapshotted unit prices. Unknown/inactive products 400.
+- `listOrders` — needs `commerce:orders:read`; `{ limit? }`.
+- `updateOrderStatus` — needs `commerce:orders:write`; `{ id, status }` where
+  status is pending|paid|cancelled|fulfilled.
+- `cancelOrder` — destructive hard-delete; needs write scope + `graft approve`
+  then retry with the approval id (MCP: the `approval` argument; HTTP: the
+  `x-graft-approval` header). Prefer `updateOrderStatus` → cancelled for
+  soft cancel.
+
+Mint scopes on your issuer (example: GRAFT_DEV_TOKEN or Better Auth payload).

package/registry/commerce/graft/commerce.ts

@@ -0,0 +1,294 @@
+/**
+ * commerce — catalog + orders foundation (owned code; edit freely).
+ *
+ * products  — file-authoritative: author MDX under content/products/*.mdx
+ * orders    — db-authoritative: rows in Postgres via the functions below
+ *
+ * Wired via the graft/ barrel — live on the next `graft compile`.
+ * See graft/commerce.llms.txt for the agent flow.
+ */
+import { requireScopes } from "@usegraft/auth";
+import { GraftError } from "@usegraft/contracts";
+import {
+  defineCollection,
+  defineFunction,
+  deleteRecord,
+  field,
+  insertRecord,
+  listRecords,
+  updateRecord,
+  type FunctionContext,
+} from "@usegraft/core";
+
+/** Scopes this vertical checks — point them at whatever your issuer emits. */
+export const COMMERCE_SCOPES = {
+  ordersRead: "commerce:orders:read",
+  ordersWrite: "commerce:orders:write",
+} as const;
+
+const requireOrdersRead = requireScopes(COMMERCE_SCOPES.ordersRead);
+const requireOrdersWrite = requireScopes(COMMERCE_SCOPES.ordersWrite);
+
+export const ORDER_STATUSES = ["pending", "paid", "cancelled", "fulfilled"] as const;
+export type OrderStatus = (typeof ORDER_STATUSES)[number];
+
+/**
+ * products — catalog as files. Agents author content/products/<slug>.mdx;
+ * git is the version history. Compile projects into content_index.
+ */
+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)." }),
+    currency: field.string({
+      optional: true,
+      description: 'ISO currency code (default "USD").',
+    }),
+    image: field.asset({ optional: true, description: "Product image." }),
+    active: field.boolean({
+      optional: true,
+      description: "When false, placeOrder rejects this product. Default true when omitted.",
+    }),
+  },
+});
+
+/**
+ * orders — operational data. Written only through placeOrder / updateOrderStatus /
+ * cancelOrder. No content/orders/ folder (AUTHORITY_MISMATCH if files appear).
+ */
+export const orders = defineCollection({
+  name: "orders",
+  authority: "db-authoritative",
+  description: "Customer orders. Place via placeOrder; admin via list/update/cancel.",
+  fields: {
+    email: field.string({ 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." }),
+        },
+      }),
+    }),
+    status: field.string({
+      description: "pending | paid | cancelled | fulfilled",
+    }),
+    totalCents: field.number({ description: "Sum of qty * unitPriceCents." }),
+  },
+});
+
+type ProductRow = {
+  slug: string;
+  title: string;
+  priceCents: number;
+  active: boolean;
+};
+
+/** Load product frontmatter from content_index for the current branch. */
+async function loadProducts(
+  ctx: Pick<FunctionContext, "db" | "branch">,
+  slugs: string[],
+): 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;
+    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,
+      title: data.title,
+      priceCents: data.priceCents,
+      active: data.active !== false,
+    });
+  }
+  return out;
+}
+
+/** Public: place an order against the live catalog (prices snapshotted). */
+export const placeOrder = defineFunction({
+  name: "placeOrder",
+  kind: "mutation",
+  public: true,
+  rateLimit: { limit: 10, windowSeconds: 60 },
+  description:
+    "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." }),
+    items: field.array({
+      description: "What to buy.",
+      of: field.object({
+        fields: {
+          productSlug: field.string({ description: "Product slug from content/products/." }),
+          qty: field.number({ description: "Quantity (>= 1)." }),
+        },
+      }),
+    }),
+  },
+  handler: async (ctx) => {
+    const { email, items } = ctx.input;
+    if (items.length === 0) {
+      throw new GraftError({
+        code: "INPUT_VALIDATION_FAILED",
+        message: "placeOrder requires at least one line item.",
+        fix: 'Send items: [{ "productSlug": "widget", "qty": 1 }]. List catalog slugs via listContent("products") or content/products/.',
+        details: { issues: [{ path: "items", message: "must be non-empty" }] },
+      });
+    }
+    for (const [i, line] of items.entries()) {
+      if (!Number.isFinite(line.qty) || line.qty < 1 || !Number.isInteger(line.qty)) {
+        throw new GraftError({
+          code: "INPUT_VALIDATION_FAILED",
+          message: `items[${i}].qty must be an integer >= 1.`,
+          fix: "Use whole quantities of at least 1 per line.",
+          details: { issues: [{ path: `items.${i}.qty`, message: "integer >= 1 required" }] },
+        });
+      }
+    }
+
+    const catalog = await loadProducts(
+      ctx,
+      items.map((l) => l.productSlug),
+    );
+    const snapshotted: { productSlug: string; qty: number; unitPriceCents: number }[] = [];
+    let totalCents = 0;
+
+    for (const [i, line] of items.entries()) {
+      const product = catalog.get(line.productSlug);
+      if (!product) {
+        throw new GraftError({
+          code: "INPUT_VALIDATION_FAILED",
+          message: `Unknown product slug "${line.productSlug}".`,
+          fix: `Author content/products/${line.productSlug}.mdx (or fix the slug), run graft compile, then retry.`,
+          details: {
+            issues: [{ path: `items.${i}.productSlug`, message: "product not found" }],
+          },
+        });
+      }
+      if (!product.active) {
+        throw new GraftError({
+          code: "INPUT_VALIDATION_FAILED",
+          message: `Product "${line.productSlug}" is not active.`,
+          fix: "Set active: true on that product (or omit active) and recompile.",
+          details: {
+            issues: [{ path: `items.${i}.productSlug`, message: "product inactive" }],
+          },
+        });
+      }
+      snapshotted.push({
+        productSlug: line.productSlug,
+        qty: line.qty,
+        unitPriceCents: product.priceCents,
+      });
+      totalCents += product.priceCents * line.qty;
+    }
+
+    const record = await insertRecord(ctx, orders, {
+      email,
+      items: snapshotted,
+      status: "pending",
+      totalCents,
+    });
+    return {
+      id: record.id,
+      totalCents: record.data.totalCents,
+      status: record.data.status,
+      receivedAt: record.createdAt.toISOString(),
+    };
+  },
+});
+
+/** Scope-gated: list recent orders, newest first. */
+export const listOrders = defineFunction({
+  name: "listOrders",
+  kind: "query",
+  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)." }),
+  },
+  access: requireOrdersRead,
+  handler: async (ctx) => {
+    const records = await listRecords(ctx, orders, { limit: ctx.input.limit });
+    return {
+      orders: records.map((r) => ({
+        id: r.id,
+        email: r.data.email,
+        status: r.data.status,
+        totalCents: r.data.totalCents,
+        items: r.data.items,
+        receivedAt: r.createdAt.toISOString(),
+      })),
+    };
+  },
+});
+
+/** Scope-gated: update order status (no payment provider — status only). */
+export const updateOrderStatus = defineFunction({
+  name: "updateOrderStatus",
+  kind: "mutation",
+  description:
+    "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" }),
+  },
+  access: requireOrdersWrite,
+  handler: async (ctx) => {
+    const status = ctx.input.status as OrderStatus;
+    if (!ORDER_STATUSES.includes(status)) {
+      throw new GraftError({
+        code: "INPUT_VALIDATION_FAILED",
+        message: `Invalid status "${ctx.input.status}".`,
+        fix: `Use one of: ${ORDER_STATUSES.join(", ")}.`,
+        details: {
+          issues: [{ path: "status", message: `expected one of ${ORDER_STATUSES.join("|")}` }],
+        },
+      });
+    }
+    const record = await updateRecord(ctx, orders, ctx.input.id, { status });
+    return { id: record.id, status: record.data.status };
+  },
+});
+
+/**
+ * Destructive + scope-gated: permanently delete an order (human-gated).
+ * Soft-cancel = updateOrderStatus → cancelled; this is the hard-delete gate demo.
+ */
+export const cancelOrder = defineFunction({
+  name: "cancelOrder",
+  kind: "mutation",
+  destructive: true,
+  description:
+    "Permanently delete an order. Destructive: requires human approval (graft approve) and commerce:orders:write.",
+  returns: "{ deleted: { id: string; email: string } }",
+  input: { id: field.string({ description: "Order row id (uuid)." }) },
+  access: requireOrdersWrite,
+  handler: async (ctx) => {
+    const removed = await deleteRecord(ctx, orders, ctx.input.id);
+    return { deleted: { id: removed.id, email: removed.data.email } };
+  },
+});
+
+export const collections = { products, orders };
+export const functions = { placeOrder, listOrders, updateOrderStatus, cancelOrder };

package/registry/commerce/registry.item.json

@@ -0,0 +1,13 @@
+{
+  "name": "commerce",
+  "type": "bundle",
+  "description": "Commerce foundation: file-authoritative product catalog + db-authoritative orders with place/list/update/cancel functions.",
+  "graftVersion": "*",
+  "dependencies": {
+    "@usegraft/auth": "workspace:*",
+    "@usegraft/contracts": "workspace:*"
+  },
+  "registryDependencies": [],
+  "files": [{ "source": "graft/commerce.ts", "target": "graft/commerce.ts", "role": "module" }],
+  "llms": "graft/commerce.llms.txt"
+}

package/registry/faq/components/Faq.tsx

@@ -0,0 +1,38 @@
+/**
+ * Faq — MDX block (owned code; edit freely).
+ *
+ * Use in authored MDX bodies with an items prop:
+ *
+ *   <Faq items={[
+ *     { question: "Is content in git?", answer: "Yes — git is authoritative." },
+ *     { question: "Who is the primary operator?", answer: "An AI agent." },
+ *   ]} />
+ *
+ * Or spread a frontmatter `faqs` array from a collection that uses `faqFields`.
+ */
+export interface FaqItem {
+  question: string;
+  answer: string;
+}
+
+export interface FaqProps {
+  items?: FaqItem[];
+  title?: string;
+}
+
+export function Faq({ items = [], title }: FaqProps) {
+  if (items.length === 0) return null;
+  return (
+    <section className="faq" aria-label={title ?? "Frequently asked questions"}>
+      {title ? <h2 className="faq-title">{title}</h2> : null}
+      <dl className="faq-list">
+        {items.map((item) => (
+          <div key={item.question} className="faq-item">
+            <dt className="faq-question">{item.question}</dt>
+            <dd className="faq-answer">{item.answer}</dd>
+          </div>
+        ))}
+      </dl>
+    </section>
+  );
+}

package/registry/faq/components/faq.llms.txt

@@ -0,0 +1,22 @@
+## faq (primitive)
+
+MDX block at `components/Faq.tsx` plus optional `graft/fields/faq.ts` field group.
+
+In MDX body (items inline):
+
+    <Faq title="Common questions" items={[
+      { question: "Is content in git?", answer: "Yes — git is authoritative." },
+      { question: "Who operates Graft?", answer: "An AI agent; humans are optional." },
+    ]} />
+
+Or store FAQs in frontmatter via the field helper:
+
+    import { faqFields } from "./graft/fields/faq";
+    // fields: { title: field.string(), ...faqFields }
+
+    # frontmatter
+    faqs:
+      - question: "…"
+        answer: "…"
+
+Then in the page component: `<Faq items={doc.data.faqs ?? []} />`.

package/registry/faq/editor/Faq.json

@@ -0,0 +1,5 @@
+{
+  "component": "Faq",
+  "label": "FAQ",
+  "titleProp": "title"
+}

package/registry/faq/graft/fields/faq.ts

@@ -0,0 +1,21 @@
+/**
+ * faqFields — optional structured FAQ list for a collection (owned code).
+ *
+ * Spread into a collection: `fields: { title: field.string(), ...faqFields }`.
+ * Then in MDX: `<Faq items={/* from frontmatter faqs *\/} />` or pass
+ * `doc.data.faqs` from the page component.
+ */
+import { field } from "@usegraft/core";
+
+export const faqFields = {
+  faqs: field.array({
+    optional: true,
+    description: "FAQ entries shown on the page (question + answer).",
+    of: field.object({
+      fields: {
+        question: field.string({ description: "The question." }),
+        answer: field.text({ description: "The answer (plain text or short prose)." }),
+      },
+    }),
+  }),
+};

package/registry/faq/registry.item.json

@@ -0,0 +1,14 @@
+{
+  "name": "faq",
+  "type": "block",
+  "description": "MDX Faq block — render a list of question/answer pairs in authored content.",
+  "graftVersion": "*",
+  "dependencies": {},
+  "registryDependencies": [],
+  "files": [
+    { "source": "components/Faq.tsx", "target": "components/Faq.tsx", "role": "component" },
+    { "source": "graft/fields/faq.ts", "target": "graft/fields/faq.ts", "role": "module" },
+    { "source": "editor/Faq.json", "target": "graft/editor/Faq.json", "role": "editor" }
+  ],
+  "llms": "components/faq.llms.txt"
+}

package/registry/scoped-access/graft/scoped-access.llms.txt

@@ -0,0 +1,9 @@
+## scoped-access (primitive)
+
+`graft/scoped-access.ts` names your token scopes and exposes access rules.
+
+- `requireModerator` gates a function so only callers whose token carries the
+  `content:moderate` scope may run it (anonymous/unscoped → 401 UNAUTHORIZED).
+- Edit the `SCOPES` map to match what your token issuer emits, then reuse the
+  rules on any function's `access:`.
+- Requires `@usegraft/auth` in the project (mint/verify tokens there).

package/registry/scoped-access/graft/scoped-access.ts

@@ -0,0 +1,19 @@
+/**
+ * scoped-access — owned access helpers (edit freely).
+ *
+ * Name the token scopes your functions check in one place, then gate a function
+ * with the matching rule. `requireScopes` (from @usegraft/auth) verifies the
+ * caller's token carries the scope; anonymous or unscoped callers are rejected
+ * with UNAUTHORIZED. Point the scope strings at whatever your token issuer
+ * actually emits.
+ */
+import { requireScopes } from "@usegraft/auth";
+
+/** The scopes this project's functions check. Rename or extend to match your issuer. */
+export const SCOPES = {
+  /** Approve/hide user-generated content (comments, reviews, …). */
+  moderate: "content:moderate",
+} as const;
+
+/** Access rule: the caller's token must carry the moderation scope. */
+export const requireModerator = requireScopes(SCOPES.moderate);

package/registry/scoped-access/registry.item.json

@@ -0,0 +1,14 @@
+{
+  "name": "scoped-access",
+  "type": "access",
+  "description": "Name your token scopes once and gate functions with them (a requireScopes preset).",
+  "graftVersion": "*",
+  "dependencies": {
+    "@usegraft/auth": "workspace:*"
+  },
+  "registryDependencies": [],
+  "files": [
+    { "source": "graft/scoped-access.ts", "target": "graft/scoped-access.ts", "role": "module" }
+  ],
+  "llms": "graft/scoped-access.llms.txt"
+}