@usegraft/compiler 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,88 @@
+import { AnyCollection } from '@usegraft/core';
+import { Database, ChangeSet } from '@usegraft/db';
+
+/** One asset reference found in a document's frontmatter. */
+interface DocAsset {
+    /** The field the reference came from. */
+    field: string;
+    /** Key of the binary in the asset store. */
+    key: string;
+    alt?: string;
+}
+interface ProjectedDoc {
+    collection: string;
+    slug: string;
+    data: Record<string, unknown>;
+    body: string;
+    contentHash: string;
+    sourcePath: string;
+    /** Asset references indexed from `asset` fields (validated by the schema). */
+    assets: DocAsset[];
+}
+declare function parseDocument(raw: string, collection: AnyCollection, sourcePath: string): ProjectedDoc;
+
+interface CompileOptions {
+    contentDir: string;
+    collections: Record<string, AnyCollection>;
+    db: Database;
+    branchId?: string;
+    /**
+     * Git commit recorded with this compilation. Omit to auto-resolve from
+     * `contentDir` (tolerant: records null outside a git repo); pass null to skip.
+     */
+    gitSha?: string | null;
+    /**
+     * Also remove index rows in collections this schema doesn't know. Off by
+     * default: purging unknown collections is the signature of two projects
+     * sharing one DATABASE_URL, so projection aborts with INDEX_OWNERSHIP
+     * unless this is set (legitimate after a collection rename/delete).
+     */
+    pruneUnknown?: boolean;
+}
+interface CompileResult {
+    count: number;
+    docs: ProjectedDoc[];
+    /** What this run did to the index: added / changed / removed keys + unchanged count. */
+    changes: ChangeSet;
+    /** The commit the content tree was compiled from, when resolvable. */
+    gitSha: string | null;
+}
+/** Read + validate the content tree into normalized docs. Pure of the database. */
+declare function readDocs(contentDir: string, collections: Record<string, AnyCollection>): ProjectedDoc[];
+declare function compile(options: CompileOptions): Promise<CompileResult>;
+interface CompileStaticOptions {
+    contentDir: string;
+    collections: Record<string, AnyCollection>;
+    /** Artifact path, e.g. <project>/.graft/index.db. */
+    indexPath: string;
+    /** As in CompileOptions: omit to auto-resolve, null to skip. */
+    gitSha?: string | null;
+}
+/**
+ * The static-mode sibling of `compile`: same validate step (readDocs), but the
+ * projection target is the SQLite artifact — no database, no env. Branching is
+ * git's job here, so there is no branchId; the artifact records "main".
+ */
+declare function compileStatic(options: CompileStaticOptions): Promise<CompileResult>;
+/** HEAD commit of the repo containing `cwd`, or null (no git, no repo — never throws). */
+declare function resolveGitSha(cwd: string): string | null;
+
+/**
+ * Write a document's bytes, translating a read-only filesystem into an error
+ * that explains itself. Serverless platforms deploy an immutable filesystem, so
+ * a Studio or MCP write served from one fails deep inside fs with an opaque
+ * errno; authored content being files is the whole model, so the fix is to run
+ * the writing surface where the checkout is writable.
+ */
+declare function writeDocumentFile(fullPath: string, raw: string): void;
+/**
+ * The bytes to write for a document.
+ *
+ * @param existingRaw The file's current contents, or undefined for a new file.
+ * @returns the existing frontmatter with only genuinely changed keys rewritten,
+ * plus the new body. Falls back to a full `matter.stringify` when the block
+ * cannot be patched safely.
+ */
+declare function composeDocument(existingRaw: string | undefined, data: Record<string, unknown>, body: string): string;
+
+export { type CompileOptions, type CompileResult, type CompileStaticOptions, type DocAsset, type ProjectedDoc, compile, compileStatic, composeDocument, parseDocument, readDocs, resolveGitSha, writeDocumentFile };

package/dist/index.js

@@ -0,0 +1,290 @@
+// src/parse.ts
+import { createHash } from "crypto";
+import { basename } from "path";
+import { GraftError } from "@usegraft/contracts";
+import matter from "gray-matter";
+var SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function parseDocument(raw, collection, sourcePath) {
+  const { data: frontmatter, content } = matter(raw);
+  const result = collection.schema.safeParse(frontmatter);
+  if (!result.success) {
+    const issues = result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+    throw new GraftError({
+      code: "SCHEMA_VALIDATION_FAILED",
+      message: `${sourcePath} does not match collection "${collection.name}"`,
+      fix: `Update the frontmatter to satisfy the "${collection.name}" schema \u2014 ${issues}`,
+      details: { sourcePath, issues: result.error.issues }
+    });
+  }
+  const slugValue = frontmatter.slug;
+  const slug = typeof slugValue === "string" && slugValue.length > 0 ? slugValue : basename(sourcePath).replace(/\.mdx?$/, "");
+  if (!SLUG_RE.test(slug)) {
+    throw new GraftError({
+      code: "INVALID_SLUG",
+      message: `Slug "${slug}" (${sourcePath}) is not URL-safe`,
+      fix: `Slugs must be kebab-case: lowercase letters, digits, and single hyphens (e.g. "getting-started"). Set a valid \`slug\` in frontmatter or rename the file.`,
+      details: { slug, sourcePath, pattern: SLUG_RE.source }
+    });
+  }
+  const data = result.data;
+  return {
+    collection: collection.name,
+    slug,
+    data,
+    body: content.trim(),
+    contentHash: createHash("sha256").update(raw).digest("hex"),
+    sourcePath,
+    assets: collectAssets(collection, data)
+  };
+}
+function collectAssets(collection, data) {
+  const assets = [];
+  for (const [name, definition] of Object.entries(collection.fields)) {
+    if (definition.type !== "asset") continue;
+    const value = data[name];
+    if (value === void 0 || value === null) continue;
+    const ref = value;
+    assets.push({ field: name, key: ref.key, ...ref.alt !== void 0 && { alt: ref.alt } });
+  }
+  return assets;
+}
+
+// src/compile.ts
+import { execFileSync } from "child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join, relative, sep } from "path";
+import { GraftError as GraftError2 } from "@usegraft/contracts";
+import {
+  projectBranchContent,
+  projectStaticContent
+} from "@usegraft/db";
+function readDocs(contentDir, collections) {
+  if (!existsSync(contentDir) || !statSync(contentDir).isDirectory()) {
+    throw new GraftError2({
+      code: "CONTENT_DIR_NOT_FOUND",
+      message: `Content directory not found: ${contentDir}`,
+      fix: `Create it (documents live at <contentDir>/<collection>/<slug>.mdx, e.g. content/pages/home.mdx) or pass the correct \`contentDir\` to compile().`,
+      details: { contentDir, collections: Object.keys(collections) }
+    });
+  }
+  const docs = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const file of walk(contentDir)) {
+    const sourcePath = relative(contentDir, file).split(sep).join("/");
+    const segments = sourcePath.split("/");
+    const collectionName = segments.length > 1 ? segments[0] ?? "" : "";
+    const collection = collections[collectionName];
+    if (!collection) {
+      const known = Object.keys(collections).join(", ") || "(none registered)";
+      throw new GraftError2({
+        code: "COLLECTION_NOT_FOUND",
+        message: segments.length > 1 ? `No collection registered for "${collectionName}" (${sourcePath})` : `${sourcePath} sits at the content root; documents must live in a collection folder`,
+        fix: segments.length > 1 ? `Register it \u2014 defineCollection({ name: "${collectionName}", fields: { \u2026 } }) and pass it to compile() \u2014 or move the file into one of: ${known}.` : `Move it to <contentDir>/<collection>/${sourcePath}. Registered collections: ${known}.`,
+        details: { sourcePath, collection: collectionName, registered: Object.keys(collections) }
+      });
+    }
+    if (collection.authority === "db-authoritative") {
+      throw new GraftError2({
+        code: "AUTHORITY_MISMATCH",
+        message: `${sourcePath} is a file, but collection "${collectionName}" is db-authoritative \u2014 its records live in Postgres, not in the content tree.`,
+        fix: `Remove the file and write the data through the collection's functions instead (insertRecord via a defineFunction mutation). Files are only for file-authoritative collections.`,
+        details: { sourcePath, collection: collectionName, authority: collection.authority }
+      });
+    }
+    const doc = parseDocument(readFileSync(file, "utf8"), collection, sourcePath);
+    const key = `${doc.collection}/${doc.slug}`;
+    const existing = seen.get(key);
+    if (existing) {
+      throw new GraftError2({
+        code: "SLUG_NOT_UNIQUE",
+        message: `Slug "${doc.slug}" in collection "${doc.collection}" is used by both ${existing} and ${sourcePath}`,
+        fix: `Give one a unique \`slug\` in frontmatter, or rename the file.`,
+        details: { slug: doc.slug, collection: doc.collection, files: [existing, sourcePath] }
+      });
+    }
+    seen.set(key, sourcePath);
+    docs.push(doc);
+  }
+  return docs.sort(
+    (a, b) => a.collection === b.collection ? a.slug.localeCompare(b.slug) : a.collection.localeCompare(b.collection)
+  );
+}
+async function compile(options) {
+  const docs = readDocs(options.contentDir, options.collections);
+  const gitSha = options.gitSha === void 0 ? resolveGitSha(options.contentDir) : options.gitSha;
+  const changes = await projectBranchContent(
+    options.db,
+    docs.map((doc) => ({
+      collection: doc.collection,
+      slug: doc.slug,
+      data: doc.data,
+      body: doc.body,
+      contentHash: doc.contentHash,
+      sourcePath: doc.sourcePath
+    })),
+    {
+      branchId: options.branchId ?? "main",
+      gitSha,
+      knownCollections: Object.keys(options.collections),
+      pruneUnknown: options.pruneUnknown
+    }
+  );
+  return { count: docs.length, docs, changes, gitSha };
+}
+async function compileStatic(options) {
+  const docs = readDocs(options.contentDir, options.collections);
+  const gitSha = options.gitSha === void 0 ? resolveGitSha(options.contentDir) : options.gitSha;
+  const changes = await projectStaticContent(
+    docs.map((doc) => ({
+      collection: doc.collection,
+      slug: doc.slug,
+      data: doc.data,
+      body: doc.body,
+      contentHash: doc.contentHash,
+      sourcePath: doc.sourcePath
+    })),
+    { path: options.indexPath, gitSha }
+  );
+  return { count: docs.length, docs, changes, gitSha };
+}
+function resolveGitSha(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function walk(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) out.push(...walk(full));
+    else if (/\.mdx?$/.test(name)) out.push(full);
+  }
+  return out.sort();
+}
+
+// src/serialize.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname } from "path";
+import { GraftError as GraftError3 } from "@usegraft/contracts";
+import matter2 from "gray-matter";
+var READ_ONLY_CODES = /* @__PURE__ */ new Set(["EROFS", "EACCES", "EPERM"]);
+function writeDocumentFile(fullPath, raw) {
+  try {
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, raw);
+  } catch (error) {
+    const code = error.code ?? "";
+    if (!READ_ONLY_CODES.has(code)) throw error;
+    throw new GraftError3({
+      code: "CONTENT_TREE_READ_ONLY",
+      message: `Cannot write ${fullPath}: the filesystem refused it (${code}).`,
+      fix: "Authored content lives in files, so writing needs a writable checkout. Run this surface locally (`graft studio` / `graft mcp`) or in a container with the project mounted read-write; a serverless deployment's filesystem is read-only and should serve reads only.",
+      details: { path: fullPath, errno: code }
+    });
+  }
+}
+var FRONTMATTER_BLOCK = /^(?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n)([\s\S]*)$/;
+function sameData(a, b) {
+  if (a === b) return true;
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => sameData(item, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object" && a !== null && b !== null) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every(
+      (key) => Object.hasOwn(b, key) && sameData(a[key], b[key])
+    );
+  }
+  return false;
+}
+var BLOCK_PARTS = /^(?---[ \t]*\r?\n)([\s\S]*?)(\r?\n---[ \t]*\r?\n)$/;
+var TOP_LEVEL_KEY = /^([A-Za-z0-9_$-]+|"(?:[^"\\]|\\.)*"|'(?:[^']|'')*'):(?:\s|$)/;
+function unquoteKey(key) {
+  if (key.startsWith('"') && key.endsWith('"')) return JSON.parse(key);
+  if (key.startsWith("'") && key.endsWith("'")) return key.slice(1, -1).replace(/''/g, "'");
+  return key;
+}
+function scanKeys(yaml) {
+  const lines = yaml.split(/\r?\n/);
+  const out = [];
+  for (const line of lines) {
+    const match = TOP_LEVEL_KEY.exec(line);
+    if (match?.[1]) {
+      out.push({ key: unquoteKey(match[1]), lines: [line] });
+      continue;
+    }
+    if (out.length === 0) {
+      if (line.trim() === "") continue;
+      return null;
+    }
+    out[out.length - 1]?.lines.push(line);
+  }
+  return out.length > 0 ? out : null;
+}
+function renderKey(key, value) {
+  const dumped = matter2.stringify("", { [key]: value });
+  const block = FRONTMATTER_BLOCK.exec(dumped)?.[1];
+  if (!block) return null;
+  const inner = BLOCK_PARTS.exec(block)?.[2];
+  if (inner === void 0) return null;
+  return inner.split(/\r?\n/);
+}
+function patchFrontmatter(block, original, data, newline) {
+  const parts = BLOCK_PARTS.exec(block);
+  if (!parts) return null;
+  const [, open = "", yaml = "", close = ""] = parts;
+  const scanned = scanKeys(yaml);
+  if (!scanned) return null;
+  const out = [];
+  const kept = /* @__PURE__ */ new Set();
+  for (const entry of scanned) {
+    if (!Object.hasOwn(data, entry.key)) continue;
+    kept.add(entry.key);
+    if (Object.hasOwn(original, entry.key) && sameData(original[entry.key], data[entry.key])) {
+      out.push(...entry.lines);
+      continue;
+    }
+    const rendered = renderKey(entry.key, data[entry.key]);
+    if (!rendered) return null;
+    out.push(...rendered);
+  }
+  for (const key of Object.keys(data)) {
+    if (kept.has(key)) continue;
+    const rendered = renderKey(key, data[key]);
+    if (!rendered) return null;
+    out.push(...rendered);
+  }
+  if (out.length === 0) return null;
+  return open + out.join(newline) + close;
+}
+function composeDocument(existingRaw, data, body) {
+  if (existingRaw === void 0) return matter2.stringify(body, data);
+  const match = FRONTMATTER_BLOCK.exec(existingRaw);
+  if (!match) return matter2.stringify(body, data);
+  const [, block = "", rest = ""] = match;
+  const newline = /\r\n/.test(block) ? "\r\n" : "\n";
+  const original = matter2(existingRaw).data;
+  const frontmatter = sameData(original, data) ? block : patchFrontmatter(block, original, data, newline);
+  if (frontmatter === null) return matter2.stringify(body, data);
+  const separator = /^\r?\n/.exec(rest)?.[0] ?? "";
+  const needsNewline = !body.endsWith("\n") && existingRaw.endsWith("\n");
+  return frontmatter + separator + body + (needsNewline ? newline : "");
+}
+export {
+  compile,
+  compileStatic,
+  composeDocument,
+  parseDocument,
+  readDocs,
+  resolveGitSha,
+  writeDocumentFile
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@usegraft/compiler",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/compiler"
+  },
+  "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": {
+    "gray-matter": "^4.0.3",
+    "@usegraft/contracts": "0.1.0",
+    "@usegraft/core": "0.1.0",
+    "@usegraft/db": "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 ."
+  }
+}