contentbase 0.0.1

package/src/cli/commands/inspect.ts

@@ -0,0 +1,46 @@
+import { defineCommand } from "citty";
+import { loadCollection } from "../load-collection";
+
+export default defineCommand({
+  meta: {
+    name: "inspect",
+    description: "Display collection info and registered models",
+  },
+  args: {
+    rootPath: {
+      type: "string",
+      description: "Root path for the collection",
+      alias: "r",
+    },
+  },
+  async run({ args }) {
+    const collection = await loadCollection({
+      rootPath: args.rootPath as string | undefined,
+    });
+
+    console.log(`Collection: ${collection.name}`);
+    console.log(`Root: ${collection.rootPath}`);
+    console.log(`Items: ${collection.available.length}`);
+    console.log();
+
+    for (const def of collection.modelDefinitions) {
+      const matchingItems = collection.available.filter((id) =>
+        id.startsWith(def.prefix)
+      );
+      console.log(`  Model: ${def.name}`);
+      console.log(`    Prefix: ${def.prefix}`);
+      console.log(
+        `    Sections: ${Object.keys(def.sections).join(", ") || "(none)"}`
+      );
+      console.log(
+        `    Relationships: ${Object.keys(def.relationships).join(", ") || "(none)"}`
+      );
+      console.log(`    Documents: ${matchingItems.length}`);
+      console.log();
+    }
+
+    if (collection.availableActions.length > 0) {
+      console.log(`Actions: ${collection.availableActions.join(", ")}`);
+    }
+  },
+});

package/src/cli/commands/validate.ts

@@ -0,0 +1,75 @@
+import { defineCommand } from "citty";
+import { loadCollection } from "../load-collection";
+import { validateDocument } from "../../validator";
+
+export default defineCommand({
+  meta: {
+    name: "validate",
+    description: "Validate documents against their model schemas",
+  },
+  args: {
+    target: {
+      type: "positional",
+      description: "Path ID, model name, or 'all'",
+      required: false,
+    },
+    rootPath: {
+      type: "string",
+      description: "Root path for the collection",
+      alias: "r",
+    },
+  },
+  async run({ args }) {
+    const collection = await loadCollection({
+      rootPath: args.rootPath as string | undefined,
+    });
+
+    const target = (args.target as string) || "all";
+    let pathIds: string[];
+
+    if (target === "all") {
+      pathIds = collection.available;
+    } else if (collection.items.has(target)) {
+      pathIds = [target];
+    } else {
+      // Try to match as model name
+      const def = collection.getModelDefinition(target);
+      if (def) {
+        pathIds = collection.available.filter((id) =>
+          id.startsWith(def.prefix)
+        );
+      } else {
+        console.error(`Not found: "${target}"`);
+        process.exit(1);
+      }
+    }
+
+    let valid = 0;
+    let invalid = 0;
+
+    for (const pathId of pathIds) {
+      const def = collection.findModelDefinition(pathId);
+      if (!def) continue;
+
+      const doc = collection.document(pathId);
+      const result = validateDocument(doc, def);
+
+      if (result.valid) {
+        valid++;
+      } else {
+        invalid++;
+        console.log(`INVALID: ${pathId}`);
+        for (const error of result.errors) {
+          console.log(`  ${error.path.join(".")}: ${error.message}`);
+        }
+      }
+    }
+
+    console.log();
+    console.log(
+      `Validated ${valid + invalid} documents: ${valid} valid, ${invalid} invalid`
+    );
+
+    if (invalid > 0) process.exit(1);
+  },
+});

package/src/cli/index.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+import { defineCommand, runMain } from "citty";
+
+const main = defineCommand({
+  meta: {
+    name: "contentbase",
+    version: "0.1.0",
+    description: "An ORM for Markdown/MDX files",
+  },
+  subCommands: {
+    init: () => import("./commands/init.js").then((m) => m.default),
+    create: () => import("./commands/create.js").then((m) => m.default),
+    inspect: () => import("./commands/inspect.js").then((m) => m.default),
+    validate: () => import("./commands/validate.js").then((m) => m.default),
+    export: () => import("./commands/export.js").then((m) => m.default),
+    action: () => import("./commands/action.js").then((m) => m.default),
+  },
+});
+
+runMain(main);

package/src/cli/load-collection.ts

@@ -0,0 +1,53 @@
+import fs from "fs/promises";
+import path from "path";
+import { Collection } from "../collection";
+
+export async function loadCollection(options: {
+  rootPath?: string;
+  modulePath?: string;
+}): Promise<Collection> {
+  let { rootPath, modulePath } = options;
+
+  if (!rootPath) {
+    const cwd = process.cwd();
+    const pkgPath = path.resolve(cwd, "package.json");
+    try {
+      const manifest = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+      if (manifest.contentbase?.rootPath) {
+        rootPath = path.resolve(cwd, manifest.contentbase.rootPath);
+      }
+    } catch {
+      // No package.json found
+    }
+    rootPath = rootPath ?? cwd;
+  }
+
+  if (!modulePath) {
+    for (const ext of ["ts", "js", "mjs"]) {
+      const candidate = path.resolve(rootPath, `index.${ext}`);
+      try {
+        await fs.stat(candidate);
+        modulePath = candidate;
+        break;
+      } catch {
+        // Not found, try next
+      }
+    }
+  }
+
+  if (modulePath) {
+    const mod = await import(modulePath);
+    const collection = mod.collection ?? mod.default;
+    if (!(collection instanceof Collection)) {
+      throw new Error(
+        "Module must export a Collection as 'collection' or default export."
+      );
+    }
+    await collection.load();
+    return collection;
+  }
+
+  const collection = new Collection({ rootPath });
+  await collection.load();
+  return collection;
+}

package/src/collection.ts

@@ -0,0 +1,399 @@
+import fs from "fs/promises";
+import path from "path";
+import matter from "gray-matter";
+import { Document } from "./document";
+import { CollectionQuery } from "./query/collection-query";
+import { createModelInstance } from "./model-instance";
+import { readDirectory } from "./utils/read-directory";
+import type {
+  ModelDefinition,
+  CollectionItem,
+  CollectionOptions,
+  InferModelInstance,
+} from "./types";
+
+export class Collection {
+  readonly rootPath: string;
+  readonly name: string;
+  readonly extensions: string[];
+
+  #items: Map<string, CollectionItem> = new Map();
+  #documents: Map<string, Document> = new Map();
+  #models: Map<string, ModelDefinition<any, any, any, any, any>> = new Map();
+  #actions: Map<string, (collection: Collection, ...args: any[]) => any> =
+    new Map();
+  #loaded = false;
+
+  constructor(options: CollectionOptions) {
+    this.rootPath = path.resolve(options.rootPath);
+    this.name = options.name ?? options.rootPath;
+    this.extensions = options.extensions ?? ["mdx", "md"];
+  }
+
+  // ─── Model registration ───
+
+  /**
+   * Register a model definition with this collection.
+   * Accepts the output of defineModel().
+   */
+  register<TDef extends ModelDefinition<any, any, any, any, any>>(
+    definition: TDef
+  ): this {
+    this.#models.set(definition.name, definition);
+    return this;
+  }
+
+  /** Get a model definition by name */
+  getModelDefinition(
+    name: string
+  ): ModelDefinition<any, any, any, any, any> | undefined {
+    return this.#models.get(name);
+  }
+
+  get modelDefinitions(): ModelDefinition<any, any, any, any, any>[] {
+    return Array.from(this.#models.values());
+  }
+
+  // ─── Loading ───
+
+  get loaded(): boolean {
+    return this.#loaded;
+  }
+
+  get items(): Map<string, CollectionItem> {
+    return this.#items;
+  }
+
+  get documents(): Map<string, Document> {
+    return this.#documents;
+  }
+
+  get available(): string[] {
+    return Array.from(this.#items.keys());
+  }
+
+  /**
+   * Recursively load all markdown files from rootPath.
+   * Parses frontmatter with gray-matter, stores content and metadata.
+   */
+  async load(options: { refresh?: boolean } = {}): Promise<this> {
+    const refresh = options.refresh ?? false;
+
+    if (this.#loaded && !refresh) {
+      return this;
+    }
+
+    if (this.#loaded && refresh) {
+      this.#items.clear();
+    }
+
+    const extensionPattern = new RegExp(
+      `\\.(${this.extensions.join("|")})$`,
+      "i"
+    );
+    const paths = await readDirectory(this.rootPath, extensionPattern);
+
+    await Promise.all(
+      paths.map(async (filePath) => {
+        const pathId = this.getPathId(filePath);
+        const raw = await fs.readFile(filePath, "utf8");
+        const stat = await fs.stat(filePath);
+        const { data, content } = matter(raw);
+
+        this.#items.set(pathId, {
+          raw,
+          content,
+          meta: data,
+          path: filePath,
+          createdAt: stat.ctime,
+          updatedAt: stat.mtime,
+        });
+      })
+    );
+
+    // Refresh any already-created documents
+    if (this.#loaded && refresh) {
+      await Promise.all(
+        Array.from(this.#documents.values()).map((doc) => doc.reload())
+      );
+    }
+
+    this.#loaded = true;
+    return this;
+  }
+
+  // ─── Document access (lazy creation) ───
+
+  /**
+   * Get or create a Document for the given pathId.
+   * Documents are cached: calling document("foo") twice returns the same instance.
+   */
+  document(pathId: string): Document {
+    if (!this.#loaded) {
+      throw new Error(
+        "Collection has not been loaded. Call load() first."
+      );
+    }
+
+    let doc = this.#documents.get(pathId);
+    if (doc) return doc;
+
+    const item = this.#items.get(pathId);
+    if (!item) {
+      throw new Error(`Could not find document "${pathId}"`);
+    }
+
+    doc = new Document({
+      id: pathId,
+      content: item.content,
+      meta: item.meta,
+      collection: this,
+    });
+
+    this.#documents.set(pathId, doc);
+    return doc;
+  }
+
+  /**
+   * Creates a new Document tied to this collection without it
+   * existing in the items map. Used for in-memory documents
+   * (e.g., extracted from hasMany relationships).
+   */
+  createDocument(attrs: {
+    id: string;
+    content?: string;
+    meta?: Record<string, unknown>;
+    ast?: import("mdast").Root;
+  }): Document {
+    return new Document({
+      id: attrs.id,
+      content: attrs.content ?? "",
+      meta: attrs.meta ?? {},
+      collection: this,
+      ast: attrs.ast,
+    });
+  }
+
+  // ─── Model access ───
+
+  /**
+   * Get a typed model instance for a document.
+   * The definition parameter carries the type information.
+   */
+  getModel<TDef extends ModelDefinition<any, any, any, any, any>>(
+    pathId: string,
+    definition: TDef
+  ): InferModelInstance<TDef> {
+    const doc = this.document(pathId);
+    return createModelInstance(doc, definition, this);
+  }
+
+  /**
+   * Determine which model definition matches a document,
+   * using match functions or prefix matching.
+   */
+  findModelDefinition(
+    pathId: string
+  ): ModelDefinition<any, any, any, any, any> | undefined {
+    const item = this.#items.get(pathId);
+    if (!item) return undefined;
+
+    for (const def of this.#models.values()) {
+      if (def.match) {
+        if (def.match({ id: pathId, meta: item.meta })) return def;
+      } else {
+        if (pathId.startsWith(def.prefix)) return def;
+      }
+    }
+    return undefined;
+  }
+
+  // ─── Querying ───
+
+  /**
+   * Create a typed query for model instances.
+   */
+  query<TDef extends ModelDefinition<any, any, any, any, any>>(
+    definition: TDef
+  ): CollectionQuery<TDef> {
+    return new CollectionQuery<TDef>(this, definition);
+  }
+
+  // ─── Persistence ───
+
+  async saveItem(
+    pathId: string,
+    options: { content: string; extension?: string }
+  ): Promise<CollectionItem> {
+    const extension = options.extension ?? ".mdx";
+    const { data, content } = matter(options.content);
+
+    if (!this.#items.has(pathId)) {
+      const filePath = this.resolve(`${pathId}${extension}`);
+      this.#items.set(pathId, {
+        raw: options.content,
+        content,
+        meta: data,
+        path: filePath,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      });
+    }
+
+    const item = this.#items.get(pathId)!;
+    const filePath = item.path;
+
+    await fs.mkdir(path.parse(filePath).dir, { recursive: true });
+    await fs.writeFile(filePath, options.content, "utf8");
+
+    // Update the stored item
+    item.raw = options.content;
+    item.content = content;
+    item.meta = data;
+    item.updatedAt = new Date();
+
+    return item;
+  }
+
+  async deleteItem(pathId: string): Promise<this> {
+    const item = this.#items.get(pathId);
+    if (!item) return this;
+
+    try {
+      await fs.rm(item.path);
+    } catch {
+      // File might not exist
+    }
+    this.#items.delete(pathId);
+    this.#documents.delete(pathId);
+    return this;
+  }
+
+  async readItem(
+    pathId: string,
+    extension: string = "mdx"
+  ): Promise<CollectionItem> {
+    let filePath: string;
+
+    if (this.#items.has(pathId)) {
+      filePath = this.#items.get(pathId)!.path;
+    } else {
+      filePath = this.resolve(`${pathId}.${extension}`);
+    }
+
+    const raw = await fs.readFile(filePath, "utf8");
+    const stat = await fs.stat(filePath);
+    const { data, content } = matter(raw);
+
+    const item: CollectionItem = {
+      raw,
+      content,
+      meta: data,
+      path: filePath,
+      createdAt: stat.ctime,
+      updatedAt: stat.mtime,
+    };
+
+    this.#items.set(pathId, item);
+    return item;
+  }
+
+  // ─── Actions ───
+
+  action(
+    name: string,
+    fn: (collection: Collection, ...args: any[]) => any
+  ): this {
+    if (typeof fn !== "function") {
+      throw new Error("Expected a function for collection action");
+    }
+    this.#actions.set(name, fn);
+    return this;
+  }
+
+  get actions(): Map<string, Function> {
+    return this.#actions;
+  }
+
+  get availableActions(): string[] {
+    return Array.from(this.#actions.keys());
+  }
+
+  async runAction(name: string, ...args: any[]): Promise<any> {
+    const fn = this.#actions.get(name);
+    if (!fn) {
+      throw new Error(`Action "${name}" does not exist on this collection.`);
+    }
+    return fn(this, ...args);
+  }
+
+  // ─── Plugin system ───
+
+  use(
+    plugin: (collection: Collection, options?: any) => void,
+    options?: any
+  ): this {
+    plugin(this, options);
+    return this;
+  }
+
+  // ─── Utilities ───
+
+  resolve(...args: string[]): string {
+    return path.resolve(this.rootPath, ...args);
+  }
+
+  getPathId(absolutePath: string): string {
+    const relativePath = path.relative(this.rootPath, absolutePath);
+    return relativePath.replace(/\.[a-z]+$/i, "");
+  }
+
+  // ─── Serialization ───
+
+  toJSON(options: { content?: boolean } = {}): Record<string, unknown> {
+    const models = this.modelDefinitions.map((def) => ({
+      name: def.name,
+      prefix: def.prefix,
+      matchingPaths: this.available.filter((id) =>
+        id.startsWith(def.prefix)
+      ),
+    }));
+
+    const result: Record<string, unknown> = {
+      models,
+      itemIds: Array.from(this.#items.keys()),
+    };
+
+    if (options.content) {
+      const items: Record<string, CollectionItem> = {};
+      for (const [id, item] of this.#items.entries()) {
+        items[id] = item;
+      }
+      result.items = items;
+    }
+
+    return result;
+  }
+
+  async export(
+    options: Record<string, unknown> = {}
+  ): Promise<Record<string, unknown>> {
+    if (!this.#loaded) await this.load();
+
+    const json = this.toJSON(options);
+    const modelData: Record<string, unknown[]> = {};
+
+    for (const def of this.modelDefinitions) {
+      const query = new CollectionQuery(this, def);
+      const instances = await query.fetchAll();
+      modelData[def.name] = instances.map((inst: any) => inst.toJSON());
+    }
+
+    return {
+      ...json,
+      modelData,
+      rootPath: this.rootPath,
+      name: this.name,
+    };
+  }
+}

package/src/define-model.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { pluralize } from "./utils/inflect";
+import type {
+  ModelDefinition,
+  SectionDefinition,
+  RelationshipDefinition,
+  DocumentRef,
+} from "./types";
+
+/**
+ * Configuration input for defineModel. This is what the user writes.
+ */
+export interface DefineModelConfig<
+  TMeta extends z.ZodTypeAny,
+  TSections extends Record<string, SectionDefinition<any>>,
+  TRelationships extends Record<string, RelationshipDefinition<any>>,
+  TComputed extends Record<string, (self: any) => any>,
+> {
+  prefix?: string;
+  meta?: TMeta;
+  sections?: TSections;
+  relationships?: TRelationships;
+  computed?: TComputed;
+  match?: (doc: DocumentRef) => boolean;
+  defaults?: Partial<z.input<TMeta>>;
+}
+
+/**
+ * defineModel creates a ModelDefinition with full type inference.
+ *
+ * Usage:
+ *   const Story = defineModel("Story", {
+ *     prefix: "stories",
+ *     meta: z.object({ status: z.enum(["created","complete"]) }),
+ *     sections: { ... },
+ *     relationships: { ... },
+ *     computed: { ... },
+ *   });
+ *
+ * The returned object is both a runtime config AND carries all type info.
+ * typeof Story is ModelDefinition<"Story", typeof metaSchema, ...>.
+ */
+export function defineModel<
+  TName extends string,
+  TMeta extends z.ZodTypeAny = z.ZodObject<{}, "passthrough">,
+  TSections extends Record<string, SectionDefinition<any>> = Record<
+    string,
+    never
+  >,
+  TRelationships extends Record<string, RelationshipDefinition<any>> = Record<
+    string,
+    never
+  >,
+  TComputed extends Record<string, (self: any) => any> = Record<
+    string,
+    never
+  >,
+>(
+  name: TName,
+  config: DefineModelConfig<
+    TMeta,
+    TSections,
+    TRelationships,
+    TComputed
+  > = {} as any
+): ModelDefinition<TName, TMeta, TSections, TRelationships, TComputed> {
+  const meta = (config.meta ?? z.object({}).passthrough()) as TMeta;
+
+  return {
+    name,
+    prefix: config.prefix ?? pluralize(name.toLowerCase()),
+    meta,
+    schema: meta,
+    sections: (config.sections ?? ({} as any)) as TSections,
+    relationships: (config.relationships ?? ({} as any)) as TRelationships,
+    computed: (config.computed ?? ({} as any)) as TComputed,
+    match: config.match,
+    defaults: config.defaults,
+  };
+}