@usegraft/contracts 0.0.0-canary-20260831153011

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/README.md

@@ -0,0 +1,36 @@
+# @usegraft/contracts
+
+> Shared error codes and introspection schemas. The vocabulary every other Graft package speaks.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+## Install
+
+```bash
+npm i @usegraft/contracts
+```
+
+You rarely install this directly. It arrives as a dependency of the packages that throw.
+
+## Errors an agent can act on
+
+```ts
+import { GraftError, ErrorCodes } from "@usegraft/contracts";
+
+throw new GraftError({
+  code: "INPUT_VALIDATION_FAILED",
+  message: 'Slug "My Page" is not URL-safe.',
+  fix: 'Slugs are kebab-case: lowercase letters, digits and single hyphens, e.g. "my-page".',
+  details: { slug: "My Page" },
+});
+```
+
+`fix` is not decoration. Every error carries the next action, because the primary reader is an agent deciding what to do rather than a human reading a stack trace. That is why `message` says what happened and `fix` says what to do about it.
+
+## Introspection
+
+`CollectionDescriptor`, `FieldDescriptor`, `FunctionDescriptor` and the registry descriptors are the shapes `describe_schema` and friends return over MCP. They are declared here so the CLI, the MCP server and the Studio cannot drift on what a collection looks like.
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/contracts/CHANGELOG.md)

package/dist/index.d.ts

@@ -0,0 +1,394 @@
+import { z } from 'zod';
+
+/**
+ * Error codes + the GraftError shape.
+ *
+ * Every Graft error carries an agent-actionable `fix` — the next concrete step an
+ * agent (or human) can take to resolve it. This is part of the "self-teaching"
+ * pillar: failures explain how to recover, not just what went wrong.
+ */
+declare const ErrorCodes: {
+    readonly SCHEMA_VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED";
+    readonly COLLECTION_NOT_FOUND: "COLLECTION_NOT_FOUND";
+    readonly CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND";
+    readonly CONFIG_INVALID: "CONFIG_INVALID";
+    readonly ALREADY_INITIALIZED: "ALREADY_INITIALIZED";
+    readonly ENV_VAR_MISSING: "ENV_VAR_MISSING";
+    readonly CONTENT_DIR_NOT_FOUND: "CONTENT_DIR_NOT_FOUND";
+    readonly CONTENT_REFERENCE_NOT_FOUND: "CONTENT_REFERENCE_NOT_FOUND";
+    readonly DOCUMENT_NOT_FOUND: "DOCUMENT_NOT_FOUND";
+    readonly FUNCTION_NOT_FOUND: "FUNCTION_NOT_FOUND";
+    readonly INPUT_VALIDATION_FAILED: "INPUT_VALIDATION_FAILED";
+    readonly FUNCTION_EXECUTION_FAILED: "FUNCTION_EXECUTION_FAILED";
+    readonly METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED";
+    readonly ROUTE_NOT_FOUND: "ROUTE_NOT_FOUND";
+    readonly AUTHORITY_MISMATCH: "AUTHORITY_MISMATCH";
+    readonly INDEX_OWNERSHIP: "INDEX_OWNERSHIP";
+    readonly SLUG_NOT_UNIQUE: "SLUG_NOT_UNIQUE";
+    readonly INVALID_SLUG: "INVALID_SLUG";
+    readonly MIGRATION_REQUIRED: "MIGRATION_REQUIRED";
+    readonly MIGRATION_FAILED: "MIGRATION_FAILED";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly TOKEN_INVALID: "TOKEN_INVALID";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly DESTRUCTIVE_OP_REQUIRES_APPROVAL: "DESTRUCTIVE_OP_REQUIRES_APPROVAL";
+    readonly APPROVAL_INVALID: "APPROVAL_INVALID";
+    readonly APPROVAL_SELF_DECISION: "APPROVAL_SELF_DECISION";
+    readonly APPROVAL_UNATTRIBUTED: "APPROVAL_UNATTRIBUTED";
+    readonly BRANCH_NOT_FOUND: "BRANCH_NOT_FOUND";
+    readonly BRANCH_EXISTS: "BRANCH_EXISTS";
+    readonly BRANCH_INVALID: "BRANCH_INVALID";
+    readonly BRANCH_BACKEND_FAILED: "BRANCH_BACKEND_FAILED";
+    readonly REGISTRY_ITEM_NOT_FOUND: "REGISTRY_ITEM_NOT_FOUND";
+    readonly REGISTRY_ITEM_INVALID: "REGISTRY_ITEM_INVALID";
+    readonly REGISTRY_FILE_EXISTS: "REGISTRY_FILE_EXISTS";
+    readonly ASSET_EXISTS: "ASSET_EXISTS";
+    readonly NEEDS_DATABASE: "NEEDS_DATABASE";
+    readonly CONTENT_TREE_READ_ONLY: "CONTENT_TREE_READ_ONLY";
+    readonly GIT_UNAVAILABLE: "GIT_UNAVAILABLE";
+    readonly COMMIT_FAILED: "COMMIT_FAILED";
+    readonly STATIC_INDEX_NOT_FOUND: "STATIC_INDEX_NOT_FOUND";
+    readonly STATIC_INDEX_UNSUPPORTED: "STATIC_INDEX_UNSUPPORTED";
+    readonly NOT_IMPLEMENTED: "NOT_IMPLEMENTED";
+};
+type ErrorCode = keyof typeof ErrorCodes;
+interface GraftErrorJSON {
+    error: ErrorCode;
+    message: string;
+    fix?: string;
+    details?: Record<string, unknown>;
+}
+interface GraftErrorOptions {
+    code: ErrorCode;
+    message: string;
+    /** Agent-actionable next step, e.g. "create pages/about.mdx or fix the reference in nav.ts". */
+    fix?: string;
+    details?: Record<string, unknown>;
+}
+declare class GraftError extends Error {
+    readonly code: ErrorCode;
+    readonly fix?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(options: GraftErrorOptions);
+    toJSON(): GraftErrorJSON;
+}
+
+/**
+ * Introspection contracts — the single source of truth for what the MCP
+ * `describe_schema` tool returns, so the MCP server, CLI, and core all agree on
+ * shape. Zod gives us runtime validation and the inferred TypeScript types from
+ * one definition (the "one Zod layer" principle).
+ */
+
+declare const ContentAuthority: z.ZodEnum<{
+    "file-authoritative": "file-authoritative";
+    "db-authoritative": "db-authoritative";
+    "hybrid-with-drift-detection": "hybrid-with-drift-detection";
+}>;
+type ContentAuthority = z.infer<typeof ContentAuthority>;
+/**
+ * Field introspection — recursive so object/array fields expose their shape
+ * to agents (describe_schema), not opaque "json" blobs.
+ */
+type FieldDescriptor = {
+    name: string;
+    type: string;
+    optional: boolean;
+    description?: string;
+    /** Nested fields when type is `object`. */
+    fields?: FieldDescriptor[];
+    /** Item shape when type is `array` (name is conventionally `"item"`). */
+    items?: FieldDescriptor;
+};
+declare const FieldDescriptor: z.ZodType<FieldDescriptor>;
+declare const CollectionDescriptor: z.ZodObject<{
+    name: z.ZodString;
+    authority: z.ZodEnum<{
+        "file-authoritative": "file-authoritative";
+        "db-authoritative": "db-authoritative";
+        "hybrid-with-drift-detection": "hybrid-with-drift-detection";
+    }>;
+    fields: z.ZodArray<z.ZodType<FieldDescriptor, unknown, z.core.$ZodTypeInternals<FieldDescriptor, unknown>>>;
+    description: z.ZodOptional<z.ZodString>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type CollectionDescriptor = z.infer<typeof CollectionDescriptor>;
+declare const FunctionDescriptor: z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        query: "query";
+        mutation: "mutation";
+    }>;
+    args: z.ZodArray<z.ZodType<FieldDescriptor, unknown, z.core.$ZodTypeInternals<FieldDescriptor, unknown>>>;
+    returns: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    public: z.ZodOptional<z.ZodBoolean>;
+    destructive: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type FunctionDescriptor = z.infer<typeof FunctionDescriptor>;
+declare const SchemaDescription: z.ZodObject<{
+    collections: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        authority: z.ZodEnum<{
+            "file-authoritative": "file-authoritative";
+            "db-authoritative": "db-authoritative";
+            "hybrid-with-drift-detection": "hybrid-with-drift-detection";
+        }>;
+        fields: z.ZodArray<z.ZodType<FieldDescriptor, unknown, z.core.$ZodTypeInternals<FieldDescriptor, unknown>>>;
+        description: z.ZodOptional<z.ZodString>;
+        sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    functions: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            query: "query";
+            mutation: "mutation";
+        }>;
+        args: z.ZodArray<z.ZodType<FieldDescriptor, unknown, z.core.$ZodTypeInternals<FieldDescriptor, unknown>>>;
+        returns: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        public: z.ZodOptional<z.ZodBoolean>;
+        destructive: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type SchemaDescription = z.infer<typeof SchemaDescription>;
+/**
+ * Registry introspection — the shape the MCP `list_registry` / `describe_item`
+ * tools return so agents can browse owned primitives before `graft add`.
+ *
+ * The vocabulary here mirrors @usegraft/registry's authoring manifest (ITEM_TYPES /
+ * FILE_ROLES); a drift test in @usegraft/registry keeps the two in lockstep so this
+ * stays the single introspection source of truth without contracts depending on
+ * registry.
+ */
+declare const RegistryItemType: z.ZodEnum<{
+    block: "block";
+    field: "field";
+    access: "access";
+    bundle: "bundle";
+}>;
+type RegistryItemType = z.infer<typeof RegistryItemType>;
+declare const RegistryFileRole: z.ZodEnum<{
+    module: "module";
+    component: "component";
+    content: "content";
+    env: "env";
+    editor: "editor";
+}>;
+type RegistryFileRole = z.infer<typeof RegistryFileRole>;
+/**
+ * How a component presents in the Studio canvas — the editor's half of an
+ * owned primitive.
+ *
+ * Data, not code, and that is the load-bearing decision. The Studio ships as a
+ * prebuilt bundle with no bundler in the loop, so it cannot import a component
+ * from the project and render it; the only other way to let a third party
+ * control presentation would be to evaluate code they authored inside the
+ * editor, which is not a thing to ship. A declaration the editor interprets
+ * keeps the extension point open without that.
+ *
+ * It is copied into the project by `graft add`, exactly like the component it
+ * describes: owned, editable, no runtime dependency on the registry it came
+ * from. Renaming a prop means editing a file you already have.
+ *
+ * Everything is optional. A component with no declaration still renders — it
+ * gets the generic card, which is what every component got before this existed.
+ */
+declare const EditorComponentSpec: z.ZodObject<{
+    component: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    titleProp: z.ZodOptional<z.ZodString>;
+    linkProp: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodObject<{
+        prop: z.ZodString;
+        map: z.ZodRecord<z.ZodString, z.ZodEnum<{
+            success: "success";
+            info: "info";
+            warn: "warn";
+            danger: "danger";
+            neutral: "neutral";
+        }>>;
+    }, z.core.$strip>>;
+    hideProps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    children: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    snippet: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type EditorComponentSpec = z.infer<typeof EditorComponentSpec>;
+/** What `GET /api/studio/v1/editor-components` returns: the project's own declarations. */
+declare const EditorComponentList: z.ZodObject<{
+    components: z.ZodArray<z.ZodObject<{
+        component: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        titleProp: z.ZodOptional<z.ZodString>;
+        linkProp: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodObject<{
+            prop: z.ZodString;
+            map: z.ZodRecord<z.ZodString, z.ZodEnum<{
+                success: "success";
+                info: "info";
+                warn: "warn";
+                danger: "danger";
+                neutral: "neutral";
+            }>>;
+        }, z.core.$strip>>;
+        hideProps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        children: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        snippet: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type EditorComponentList = z.infer<typeof EditorComponentList>;
+/** One file an item writes — the target path (relative to project root) and its role. */
+declare const RegistryFileDescriptor: z.ZodObject<{
+    target: z.ZodString;
+    role: z.ZodEnum<{
+        module: "module";
+        component: "component";
+        content: "content";
+        env: "env";
+        editor: "editor";
+    }>;
+}, z.core.$strip>;
+type RegistryFileDescriptor = z.infer<typeof RegistryFileDescriptor>;
+/**
+ * Agent-facing description of one owned primitive. Deliberately omits the
+ * machine-specific absolute `dir` a loaded item carries — this is the wire shape.
+ */
+declare const RegistryItemDescriptor: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        block: "block";
+        field: "field";
+        access: "access";
+        bundle: "bundle";
+    }>;
+    description: z.ZodString;
+    graftVersion: z.ZodString;
+    dependencies: z.ZodRecord<z.ZodString, z.ZodString>;
+    registryDependencies: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        target: z.ZodString;
+        role: z.ZodEnum<{
+            module: "module";
+            component: "component";
+            content: "content";
+            env: "env";
+            editor: "editor";
+        }>;
+    }, z.core.$strip>>;
+    llms: z.ZodBoolean;
+}, z.core.$strip>;
+type RegistryItemDescriptor = z.infer<typeof RegistryItemDescriptor>;
+
+/**
+ * Well-known paths shared across packages.
+ */
+/**
+ * Where a static-tier project's compiled index lives, relative to the project
+ * root.
+ *
+ * Here rather than in @usegraft/db because the CLI resolves it while loading a
+ * config and deliberately lazy-loads the database package — a static import
+ * just to read one string would pull Postgres into every `graft` invocation.
+ */
+declare const STATIC_INDEX_DEFAULT_PATH = ".graft/index.db";
+
+/**
+ * Record the socket address a request came from. Called by an adapter that owns
+ * the connection — never from anything that merely receives a Request.
+ */
+declare function setRequestPeer(request: Request, address: string): void;
+/** The recorded peer address, or undefined when no adapter registered one. */
+declare function getRequestPeer(request: Request): string | undefined;
+/**
+ * The rate-limit identity for a caller with no verified actor.
+ *
+ * Lives here rather than beside one handler because more than one surface
+ * needs it — `createFunctionsHandler` for anonymous function calls, and
+ * `createContentApiHandler` for a read endpoint that never authenticates at
+ * all — and the rule it encodes is the kind that must not be reimplemented
+ * twice. `.greptile/rules.md` names it as a security invariant precisely
+ * because the obvious reading of `x-forwarded-for` is the wrong one.
+ *
+ * Never reads the header unless the deployment declares how many proxies it
+ * controls, and then counts from the RIGHT: entries are appended, so the
+ * rightmost were added by infrastructure closest to us. A client can prepend
+ * anything it likes and never reach that far.
+ */
+declare function rateIdentity(request: Request, trustedProxyHops: number): string;
+
+/**
+ * The content-index read contract.
+ *
+ * These types used to live in `@usegraft/db`, which made them unreachable
+ * without depending on the Postgres package — and `ContentRow` in particular
+ * was `typeof contentIndex.$inferSelect`, derived from a Drizzle table. So the
+ * shape every reader returns was defined by one implementation's storage
+ * schema, and any consumer that merely wanted to *describe* a row (the HTTP
+ * transport, the browser client) had to install a database driver to say so.
+ *
+ * They live here because this is the layer every package already shares.
+ * `@usegraft/db` now proves its table still matches this contract rather than
+ * defining it, which is the direction the dependency should have run in from
+ * the start: the seam owns the shape, the implementation conforms to it.
+ */
+/** One row of the authored-content index. */
+interface ContentRow {
+    branchId: string;
+    collection: string;
+    slug: string;
+    /** Validated frontmatter. */
+    data: Record<string, unknown>;
+    /** Authored MDX source, byte-for-byte as written. */
+    body: string;
+    contentHash: string;
+    sourcePath: string;
+    /** Soft-delete marker. Readers exclude these. */
+    deleted: boolean;
+    updatedAt: Date;
+    /** The FTS vector, when the implementation has one. */
+    search: string | null;
+}
+interface ReaderReadOptions {
+    collection: string;
+    /** When set, read a single document; otherwise the whole collection. */
+    slug?: string;
+    limit?: number;
+    offset?: number;
+    /** Branch to read; defaults to "main". Static readers serve their compiled branch regardless. */
+    branch?: string;
+}
+interface ReaderSearchOptions {
+    /** Websearch-syntax query: words, "quoted phrases", `or`, -exclusions. */
+    query: string;
+    /** Restrict to these collections; defaults to all. */
+    collections?: string[];
+    /** Max hits, best-ranked first. Defaults to 20. */
+    limit?: number;
+    branch?: string;
+}
+interface ContentSearchHit {
+    row: ContentRow;
+    /** Relevance rank: slug beats frontmatter beats body prose. */
+    rank: number;
+    /** Body fragment(s) with matches wrapped in `<b>…</b>`. */
+    snippet: string;
+}
+/**
+ * The seam between "who serves content reads" and "where the index lives".
+ * Implemented by the Postgres reader, the compiled SQLite artifact, and the
+ * HTTP reader in `@usegraft/content-api`.
+ */
+interface ContentIndexReader {
+    readContent(options: ReaderReadOptions): Promise<ContentRow[]>;
+    searchContent(options: ReaderSearchOptions): Promise<ContentSearchHit[]>;
+    close(): Promise<void>;
+}
+/** What one compile changed, by slug. */
+interface ChangeSet {
+    added: string[];
+    changed: string[];
+    removed: string[];
+    unchanged: number;
+}
+
+export { type ChangeSet, CollectionDescriptor, ContentAuthority, type ContentIndexReader, type ContentRow, type ContentSearchHit, EditorComponentList, EditorComponentSpec, type ErrorCode, ErrorCodes, FieldDescriptor, FunctionDescriptor, GraftError, type GraftErrorJSON, type GraftErrorOptions, type ReaderReadOptions, type ReaderSearchOptions, RegistryFileDescriptor, RegistryFileRole, RegistryItemDescriptor, RegistryItemType, STATIC_INDEX_DEFAULT_PATH, SchemaDescription, getRequestPeer, rateIdentity, setRequestPeer };

package/dist/index.js

@@ -0,0 +1,217 @@
+// src/errors.ts
+var ErrorCodes = {
+  SCHEMA_VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED",
+  COLLECTION_NOT_FOUND: "COLLECTION_NOT_FOUND",
+  CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+  CONFIG_INVALID: "CONFIG_INVALID",
+  ALREADY_INITIALIZED: "ALREADY_INITIALIZED",
+  ENV_VAR_MISSING: "ENV_VAR_MISSING",
+  CONTENT_DIR_NOT_FOUND: "CONTENT_DIR_NOT_FOUND",
+  CONTENT_REFERENCE_NOT_FOUND: "CONTENT_REFERENCE_NOT_FOUND",
+  DOCUMENT_NOT_FOUND: "DOCUMENT_NOT_FOUND",
+  FUNCTION_NOT_FOUND: "FUNCTION_NOT_FOUND",
+  INPUT_VALIDATION_FAILED: "INPUT_VALIDATION_FAILED",
+  FUNCTION_EXECUTION_FAILED: "FUNCTION_EXECUTION_FAILED",
+  METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED",
+  ROUTE_NOT_FOUND: "ROUTE_NOT_FOUND",
+  AUTHORITY_MISMATCH: "AUTHORITY_MISMATCH",
+  INDEX_OWNERSHIP: "INDEX_OWNERSHIP",
+  SLUG_NOT_UNIQUE: "SLUG_NOT_UNIQUE",
+  INVALID_SLUG: "INVALID_SLUG",
+  MIGRATION_REQUIRED: "MIGRATION_REQUIRED",
+  MIGRATION_FAILED: "MIGRATION_FAILED",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  TOKEN_INVALID: "TOKEN_INVALID",
+  RATE_LIMITED: "RATE_LIMITED",
+  DESTRUCTIVE_OP_REQUIRES_APPROVAL: "DESTRUCTIVE_OP_REQUIRES_APPROVAL",
+  APPROVAL_INVALID: "APPROVAL_INVALID",
+  APPROVAL_SELF_DECISION: "APPROVAL_SELF_DECISION",
+  APPROVAL_UNATTRIBUTED: "APPROVAL_UNATTRIBUTED",
+  BRANCH_NOT_FOUND: "BRANCH_NOT_FOUND",
+  BRANCH_EXISTS: "BRANCH_EXISTS",
+  BRANCH_INVALID: "BRANCH_INVALID",
+  BRANCH_BACKEND_FAILED: "BRANCH_BACKEND_FAILED",
+  REGISTRY_ITEM_NOT_FOUND: "REGISTRY_ITEM_NOT_FOUND",
+  REGISTRY_ITEM_INVALID: "REGISTRY_ITEM_INVALID",
+  REGISTRY_FILE_EXISTS: "REGISTRY_FILE_EXISTS",
+  ASSET_EXISTS: "ASSET_EXISTS",
+  NEEDS_DATABASE: "NEEDS_DATABASE",
+  CONTENT_TREE_READ_ONLY: "CONTENT_TREE_READ_ONLY",
+  GIT_UNAVAILABLE: "GIT_UNAVAILABLE",
+  COMMIT_FAILED: "COMMIT_FAILED",
+  STATIC_INDEX_NOT_FOUND: "STATIC_INDEX_NOT_FOUND",
+  STATIC_INDEX_UNSUPPORTED: "STATIC_INDEX_UNSUPPORTED",
+  NOT_IMPLEMENTED: "NOT_IMPLEMENTED"
+};
+var GraftError = class extends Error {
+  code;
+  fix;
+  details;
+  constructor(options) {
+    super(options.message);
+    this.name = "GraftError";
+    this.code = options.code;
+    this.fix = options.fix;
+    this.details = options.details;
+  }
+  toJSON() {
+    return {
+      error: this.code,
+      message: this.message,
+      fix: this.fix,
+      details: this.details
+    };
+  }
+};
+
+// src/introspection.ts
+import { z } from "zod";
+var ContentAuthority = z.enum([
+  "file-authoritative",
+  "db-authoritative",
+  "hybrid-with-drift-detection"
+]);
+var FieldDescriptor = z.lazy(
+  () => z.object({
+    name: z.string(),
+    type: z.string(),
+    optional: z.boolean().default(false),
+    description: z.string().optional(),
+    fields: z.array(FieldDescriptor).optional(),
+    items: FieldDescriptor.optional()
+  })
+);
+var CollectionDescriptor = z.object({
+  name: z.string(),
+  authority: ContentAuthority,
+  fields: z.array(FieldDescriptor),
+  description: z.string().optional(),
+  /**
+   * Reading order for the collection's `section` values, when it groups.
+   *
+   * Section order is editorial — "Start here" before "Reference" — and there
+   * is nothing in the content to infer it from, since `order` restarts within
+   * each section. Declaring it on the collection means the site nav and any
+   * tool that lists content (Studio, agents) sort identically instead of each
+   * inventing an order. Sections not listed sort last, so new content never
+   * disappears from a sidebar.
+   */
+  sections: z.array(z.string()).optional()
+});
+var FunctionDescriptor = z.object({
+  name: z.string(),
+  kind: z.enum(["query", "mutation"]),
+  args: z.array(FieldDescriptor),
+  returns: z.string().optional(),
+  description: z.string().optional(),
+  /** Anonymous callers allowed. Mutations default to false; queries to true. */
+  public: z.boolean().optional(),
+  /** Always human-gated: invoking it requires an approved, one-shot, input-bound approval. */
+  destructive: z.boolean().optional()
+});
+var SchemaDescription = z.object({
+  collections: z.array(CollectionDescriptor),
+  functions: z.array(FunctionDescriptor)
+});
+var RegistryItemType = z.enum(["block", "field", "access", "bundle"]);
+var RegistryFileRole = z.enum(["module", "component", "content", "env", "editor"]);
+var EditorComponentSpec = z.object({
+  /** The JSX name this describes, e.g. "Callout". */
+  component: z.string().min(1),
+  /** Display name for the card's chip. Defaults to `component`. */
+  label: z.string().min(1).optional(),
+  /** Prop to show as the card's heading instead of guessing. */
+  titleProp: z.string().optional(),
+  /** Prop holding a destination, shown as a chip. */
+  linkProp: z.string().optional(),
+  /**
+   * Colour the card by one of its props — `type="warning"` on a Callout should
+   * look like a warning. Values map to the editor's own tone roles, so a
+   * third-party component cannot introduce a colour the theme does not have.
+   */
+  tone: z.object({
+    prop: z.string().min(1),
+    map: z.record(z.string(), z.enum(["info", "warn", "danger", "success", "neutral"]))
+  }).optional(),
+  /** Props already implied by the card's shape, not worth listing again. */
+  hideProps: z.array(z.string()).default([]),
+  /** Declarations for the children this component expects, e.g. DocCard inside DocCards. */
+  children: z.array(z.string()).default([]),
+  /**
+   * The exact MDX inserted when the operator picks this component from the
+   * palette. Authored by whoever wrote the component, because only they know
+   * which props are required and what a sensible starting body is — a guess
+   * assembled from the other fields would produce blocks that do not compile.
+   * Without one the component is still rendered, just not offered for insert.
+   *
+   * **Put the opening tag on a line of its own.** Markdown only treats JSX as
+   * one HTML *block* when nothing else shares the opening tag's line; write
+   * `<Callout>text</Callout>` on a single line and remark splits it into an
+   * open tag, a text node and a close tag, which renders as three pieces of
+   * raw source rather than one card. Every authored component in this repo is
+   * written the block way for exactly this reason.
+   */
+  snippet: z.string().min(1).optional()
+});
+var EditorComponentList = z.object({ components: z.array(EditorComponentSpec) });
+var RegistryFileDescriptor = z.object({
+  target: z.string(),
+  role: RegistryFileRole
+});
+var RegistryItemDescriptor = z.object({
+  name: z.string(),
+  type: RegistryItemType,
+  description: z.string(),
+  /** Semver range against @usegraft/core; "*" = any (pre-1.0 default). */
+  graftVersion: z.string(),
+  /** npm packages the target must install first (package → version range). */
+  dependencies: z.record(z.string(), z.string()),
+  /** Other registry items `graft add` pulls in first (transitive). */
+  registryDependencies: z.array(z.string()),
+  /** The files this item writes into the project. */
+  files: z.array(RegistryFileDescriptor),
+  /** Whether the item ships an llms.txt teaching fragment. */
+  llms: z.boolean()
+});
+
+// src/paths.ts
+var STATIC_INDEX_DEFAULT_PATH = ".graft/index.db";
+
+// src/peer.ts
+var peers = /* @__PURE__ */ new WeakMap();
+function setRequestPeer(request, address) {
+  peers.set(request, address);
+}
+function getRequestPeer(request) {
+  return peers.get(request);
+}
+function rateIdentity(request, trustedProxyHops) {
+  if (trustedProxyHops > 0) {
+    const forwarded = request.headers.get("x-forwarded-for");
+    if (forwarded) {
+      const hops = forwarded.split(",").map((entry) => entry.trim()).filter(Boolean);
+      const trusted = hops[hops.length - trustedProxyHops];
+      if (trusted) return trusted;
+    }
+  }
+  return getRequestPeer(request) ?? "unknown";
+}
+export {
+  CollectionDescriptor,
+  ContentAuthority,
+  EditorComponentList,
+  EditorComponentSpec,
+  ErrorCodes,
+  FieldDescriptor,
+  FunctionDescriptor,
+  GraftError,
+  RegistryFileDescriptor,
+  RegistryFileRole,
+  RegistryItemDescriptor,
+  RegistryItemType,
+  STATIC_INDEX_DEFAULT_PATH,
+  SchemaDescription,
+  getRequestPeer,
+  rateIdentity,
+  setRequestPeer
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@usegraft/contracts",
+  "version": "0.0.0-canary-20260831153011",
+  "description": "Shared error codes and introspection schemas: the vocabulary every Graft package speaks.",
+  "keywords": [
+    "agent",
+    "ai",
+    "cms",
+    "errors",
+    "graft",
+    "headless-cms",
+    "introspection",
+    "mcp",
+    "schemas",
+    "typescript"
+  ],
+  "homepage": "https://github.com/AndersonDesign1/graft#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/contracts"
+  },
+  "files": [
+    "dist"
+  ],
+  "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"
+  },
+  "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"
+  }
+}