@usegraft/content-migrations 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,56 @@
+import { AnyCollection, DocumentData } from '@usegraft/core';
+
+/** What the transform sees per document: the old, pre-migration shape. */
+interface ContentMigrationDoc {
+    slug: string;
+    /** `<collection>/<file>.mdx`, relative to the content root. */
+    sourcePath: string;
+    /** Raw frontmatter as authored (minus `slug`) — the OLD shape, so untyped. */
+    data: Record<string, unknown>;
+    /** The MDX body as authored. */
+    body: string;
+}
+/** What the transform returns: the new frontmatter (and optionally a new body). */
+interface ContentMigrationChange<TData> {
+    data: TData;
+    /** Omit to keep the body as-is. */
+    body?: string;
+}
+interface ContentMigrationOptions<TCollection extends AnyCollection> {
+    collection: TCollection;
+    /** One line for `graft migrate` listings: what this migration does and why. */
+    description: string;
+    transform: (doc: ContentMigrationDoc) => ContentMigrationChange<DocumentData<TCollection>> | Promise<ContentMigrationChange<DocumentData<TCollection>>>;
+}
+interface ContentMigration<TCollection extends AnyCollection = AnyCollection> {
+    readonly kind: "content";
+    readonly collection: TCollection;
+    readonly description: string;
+    readonly transform: ContentMigrationOptions<TCollection>["transform"];
+}
+type AnyContentMigration = ContentMigration<AnyCollection>;
+declare function defineContentMigration<TCollection extends AnyCollection>(options: ContentMigrationOptions<TCollection>): ContentMigration<TCollection>;
+
+interface RunContentMigrationOptions {
+    /** Absolute path to the content root (files live at <contentDir>/<collection>/…). */
+    contentDir: string;
+    migration: AnyContentMigration;
+    /** Write the transformed files. Defaults to false — report only. */
+    apply?: boolean;
+}
+interface ContentMigrationFileResult {
+    sourcePath: string;
+    slug: string;
+    changed: boolean;
+}
+interface ContentMigrationReport {
+    collection: string;
+    files: ContentMigrationFileResult[];
+    changed: number;
+    unchanged: number;
+    /** True when the changed files were written (apply mode). */
+    applied: boolean;
+}
+declare function runContentMigration(options: RunContentMigrationOptions): Promise<ContentMigrationReport>;
+
+export { type AnyContentMigration, type ContentMigration, type ContentMigrationChange, type ContentMigrationDoc, type ContentMigrationFileResult, type ContentMigrationOptions, type ContentMigrationReport, type RunContentMigrationOptions, defineContentMigration, runContentMigration };

package/dist/index.js

@@ -0,0 +1,119 @@
+// src/define.ts
+import { GraftError } from "@usegraft/contracts";
+function defineContentMigration(options) {
+  if (options.collection.authority === "db-authoritative") {
+    throw new GraftError({
+      code: "AUTHORITY_MISMATCH",
+      message: `Content migrations transform files, but collection "${options.collection.name}" is db-authoritative \u2014 its records are Postgres rows.`,
+      fix: `Use defineDataMigration from "@usegraft/core" for db-authoritative collections; defineContentMigration is only for collections whose documents are files.`,
+      details: { collection: options.collection.name, authority: options.collection.authority }
+    });
+  }
+  return {
+    kind: "content",
+    collection: options.collection,
+    description: options.description,
+    transform: options.transform
+  };
+}
+
+// src/run.ts
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import { basename, join, sep } from "path";
+import { GraftError as GraftError2 } from "@usegraft/contracts";
+import matter from "gray-matter";
+async function runContentMigration(options) {
+  const { contentDir, migration } = options;
+  const collection = migration.collection;
+  if (!existsSync(contentDir) || !statSync(contentDir).isDirectory()) {
+    throw new GraftError2({
+      code: "CONTENT_DIR_NOT_FOUND",
+      message: `Content directory not found: ${contentDir}`,
+      fix: `Run from the project root (contentDir comes from graft.config.ts), or create the directory.`,
+      details: { contentDir }
+    });
+  }
+  const dir = join(contentDir, collection.name);
+  const files = existsSync(dir) && statSync(dir).isDirectory() ? walk(dir).map((file) => ({
+    file,
+    sourcePath: `${collection.name}/${file.slice(dir.length + 1).split(sep).join("/")}`
+  })) : [];
+  const results = [];
+  const writes = [];
+  const failures = [];
+  for (const { file, sourcePath } of files) {
+    const raw = readFileSync(file, "utf8");
+    let parsed;
+    try {
+      parsed = matter(raw);
+    } catch (error) {
+      failures.push({
+        sourcePath,
+        reason: `frontmatter is not parseable YAML (${error instanceof Error ? error.message : String(error)}) \u2014 fix the file before migrating`
+      });
+      continue;
+    }
+    const frontmatter = parsed.data;
+    const explicitSlug = typeof frontmatter.slug === "string" && frontmatter.slug.length > 0 ? frontmatter.slug : void 0;
+    const slug = explicitSlug ?? basename(sourcePath).replace(/\.mdx?$/, "");
+    const { slug: _slug, ...data } = frontmatter;
+    let next;
+    try {
+      next = await migration.transform({ slug, sourcePath, data, body: parsed.content });
+    } catch (error) {
+      failures.push({
+        sourcePath,
+        reason: `transform threw: ${error instanceof Error ? error.message : String(error)}`
+      });
+      continue;
+    }
+    const validated = collection.schema.safeParse(next.data);
+    if (!validated.success) {
+      const issues = validated.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+      failures.push({ sourcePath, reason: `transformed data fails the schema \u2014 ${issues}` });
+      continue;
+    }
+    const nextBody = next.body ?? parsed.content;
+    const changed2 = JSON.stringify(next.data) !== JSON.stringify(data) || nextBody !== parsed.content;
+    results.push({ sourcePath, slug, changed: changed2 });
+    if (changed2) {
+      const nextFrontmatter = {
+        ...explicitSlug !== void 0 && { slug: explicitSlug },
+        ...next.data
+      };
+      writes.push({ file, raw: matter.stringify(nextBody, nextFrontmatter) });
+    }
+  }
+  if (failures.length > 0) {
+    throw new GraftError2({
+      code: "MIGRATION_FAILED",
+      message: `Content migration for "${collection.name}" failed on ${failures.length} of ${files.length} file(s); nothing was written.`,
+      fix: `Fix the transform (or the listed files) so every output satisfies the current "${collection.name}" schema, then re-run. Failures: ${failures.map((f) => `${f.sourcePath}: ${f.reason}`).join(" | ")}`,
+      details: { collection: collection.name, failures }
+    });
+  }
+  if (options.apply) {
+    for (const write of writes) writeFileSync(write.file, write.raw);
+  }
+  const changed = results.filter((r) => r.changed).length;
+  return {
+    collection: collection.name,
+    files: results,
+    changed,
+    unchanged: results.length - changed,
+    applied: options.apply === true
+  };
+}
+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();
+}
+export {
+  defineContentMigration,
+  runContentMigration
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@usegraft/content-migrations",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/content-migrations"
+  },
+  "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/core": "0.1.0",
+    "@usegraft/contracts": "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 ."
+  }
+}