@usegraft/contracts 0.1.1 → 1.0.0-beta.0

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

@@ -34,6 +34,7 @@ declare const ErrorCodes: {
     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";
@@ -278,4 +279,116 @@ declare const RegistryItemDescriptor: z.ZodObject<{
 }, z.core.$strip>;
 type RegistryItemDescriptor = z.infer<typeof RegistryItemDescriptor>;
 
-export { CollectionDescriptor, ContentAuthority, EditorComponentList, EditorComponentSpec, type ErrorCode, ErrorCodes, FieldDescriptor, FunctionDescriptor, GraftError, type GraftErrorJSON, type GraftErrorOptions, RegistryFileDescriptor, RegistryFileRole, RegistryItemDescriptor, RegistryItemType, SchemaDescription };
+/**
+ * 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

@@ -26,6 +26,7 @@ var ErrorCodes = {
   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",
@@ -172,6 +173,29 @@ var RegistryItemDescriptor = z.object({
   /** 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,
@@ -185,5 +209,9 @@ export {
   RegistryFileRole,
   RegistryItemDescriptor,
   RegistryItemType,
-  SchemaDescription
+  STATIC_INDEX_DEFAULT_PATH,
+  SchemaDescription,
+  getRequestPeer,
+  rateIdentity,
+  setRequestPeer
 };

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "@usegraft/contracts",
-  "version": "0.1.1",
+  "version": "1.0.0-beta.0",
+  "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",
@@ -33,7 +47,6 @@
     "build": "tsup src/index.ts --format esm --dts --clean",
     "dev": "tsup src/index.ts --format esm --watch",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "lint": "oxlint ."
+    "test": "vitest run"
   }
 }