contentbase 0.0.1

package/showcases/vinyl-collection/albums/kind-of-blue.mdx

@@ -0,0 +1,32 @@
+---
+artist: miles-davis
+year: 1959
+genre: Modal Jazz
+format: LP
+rating: 5
+condition: very-good
+---
+
+# Kind of Blue
+
+Recorded over two sessions in spring 1959, this album defined modal jazz. Miles handed his sextet sketches and scales instead of chord changes, and they improvised nearly everything on the first take.
+
+## Tracklist
+
+| # | Title | Duration |
+| --- | --- | --- |
+| 1 | So What | 9:22 |
+| 2 | Freddie Freeloader | 9:46 |
+| 3 | Blue in Green | 5:27 |
+| 4 | All Blues | 11:33 |
+| 5 | Flamenco Sketches | 9:26 |
+
+## Personnel
+
+- Miles Davis — trumpet
+- John Coltrane — tenor saxophone
+- Cannonball Adderley — alto saxophone
+- Bill Evans — piano (tracks 1, 3, 4, 5)
+- Wynton Kelly — piano (track 2)
+- Paul Chambers — bass
+- Jimmy Cobb — drums

package/showcases/vinyl-collection/albums/ok-computer.mdx

@@ -0,0 +1,37 @@
+---
+artist: radiohead
+year: 1997
+genre: Alternative Rock
+format: 2xLP
+rating: 5
+condition: near-mint
+---
+
+# OK Computer
+
+Radiohead's third album traded the angst of their earlier work for something bigger: a panoramic meditation on disconnection in the digital age. Dense, layered, and somehow more relevant with every passing year.
+
+## Tracklist
+
+| # | Title | Duration |
+| --- | --- | --- |
+| 1 | Airbag | 4:44 |
+| 2 | Paranoid Android | 6:23 |
+| 3 | Subterranean Homesick Alien | 4:27 |
+| 4 | Exit Music (For a Film) | 4:24 |
+| 5 | Let Down | 4:59 |
+| 6 | Karma Police | 4:21 |
+| 7 | Fitter Happier | 1:57 |
+| 8 | Electioneering | 3:50 |
+| 9 | Climbing Up the Walls | 4:45 |
+| 10 | No Surprises | 3:48 |
+| 11 | Lucky | 4:19 |
+| 12 | The Tourist | 5:24 |
+
+## Personnel
+
+- Thom Yorke — vocals, guitar, keyboards
+- Jonny Greenwood — guitar, keyboards, ondes Martenot
+- Ed O'Brien — guitar, vocals
+- Colin Greenwood — bass
+- Phil Selway — drums

package/showcases/vinyl-collection/albums/wild-is-the-wind.mdx

@@ -0,0 +1,35 @@
+---
+artist: nina-simone
+year: 1966
+genre: Jazz / Blues
+format: LP
+rating: 4
+condition: very-good
+---
+
+# Wild Is the Wind
+
+Stripped back compared to its predecessor, this album foregrounds Nina's piano and voice. The material ranges from tender ballads to biting social commentary, often within the same song.
+
+## Tracklist
+
+| # | Title | Duration |
+| --- | --- | --- |
+| 1 | I Love Your Lovin' Ways | 2:34 |
+| 2 | Four Women | 4:09 |
+| 3 | What More Can I Say | 3:11 |
+| 4 | Lilac Wine | 4:17 |
+| 5 | That's All I Ask | 3:01 |
+| 6 | Break Down and Let It All Out | 2:39 |
+| 7 | Why Keep On Breaking My Heart | 2:41 |
+| 8 | Wild Is the Wind | 6:49 |
+| 9 | Black Is the Color of My True Love's Hair | 3:07 |
+| 10 | If I Should Lose You | 2:22 |
+| 11 | Either Way I Lose | 4:38 |
+
+## Personnel
+
+- Nina Simone — vocals, piano
+- Rudy Stevenson — guitar, flute
+- Lisle Atkinson — bass
+- Bobby Hamilton — drums

package/showcases/vinyl-collection/artists/miles-davis.mdx

@@ -0,0 +1,27 @@
+---
+genre: Jazz
+origin: Alton, Illinois
+active: "1944–1991"
+---
+
+# Miles Davis
+
+Trumpeter, bandleader, and relentless innovator. Miles didn't just play jazz — he bent it into new shapes every decade, from bebop to cool jazz to fusion and beyond.
+
+## Influences
+
+- Charlie Parker
+- Dizzy Gillespie
+- Duke Ellington
+- Ahmad Jamal
+- Jimi Hendrix
+
+## Discography
+
+### Kind of Blue
+
+The best-selling jazz album of all time. Modal jazz distilled to its essence.
+
+### Bitches Brew
+
+The album that invented jazz fusion. Chaotic, electric, and revolutionary.

package/showcases/vinyl-collection/artists/nina-simone.mdx

@@ -0,0 +1,26 @@
+---
+genre: Jazz / Soul
+origin: Tryon, North Carolina
+active: "1954–2003"
+---
+
+# Nina Simone
+
+Classically trained pianist who became one of the most powerful voices in American music. Her work fused jazz, blues, folk, and classical into something entirely her own — always political, always personal.
+
+## Influences
+
+- Johann Sebastian Bach
+- Billie Holiday
+- Langston Hughes
+- Lorraine Hansberry
+
+## Discography
+
+### I Put a Spell on You
+
+Lush orchestral arrangements meet Nina's incomparable voice. Sophisticated, powerful, and hauntingly intimate.
+
+### Wild Is the Wind
+
+A stripped-down collection that showcases her piano and voice at their most raw and emotive.

package/showcases/vinyl-collection/artists/radiohead.mdx

@@ -0,0 +1,27 @@
+---
+genre: Alternative Rock
+origin: Abingdon, Oxfordshire
+active: "1985–present"
+---
+
+# Radiohead
+
+Five musicians from Oxfordshire who spent three decades proving that popular music could be challenging, experimental, and emotionally devastating — all at the same time.
+
+## Influences
+
+- Talking Heads
+- R.E.M.
+- Can
+- Aphex Twin
+- Olivier Messiaen
+
+## Discography
+
+### OK Computer
+
+Anxiety about technology and modern alienation, wrapped in some of the most ambitious guitar rock ever committed to tape.
+
+### In Rainbows
+
+A warm, intimate counterpoint to the paranoia of their earlier work. Released via pay-what-you-want download.

package/showcases/vinyl-collection/models.ts

@@ -0,0 +1,73 @@
+import {
+  defineModel,
+  section,
+  hasMany,
+  belongsTo,
+  z,
+} from "../../src/index";
+import { toString } from "mdast-util-to-string";
+import { parseTable } from "../../src/utils/parse-table";
+
+// ─── Artist (parent) ───
+
+export const Artist = defineModel("Artist", {
+  prefix: "artists",
+  meta: z.object({
+    genre: z.string(),
+    origin: z.string(),
+    active: z.string(),
+  }),
+  sections: {
+    influences: section("Influences", {
+      extract: (q) => q.selectAll("listItem").map((n) => toString(n)),
+      schema: z.array(z.string()),
+    }),
+  },
+  relationships: {
+    albums: hasMany(() => Album, { heading: "Discography" }),
+  },
+});
+
+// ─── Album ───
+
+export const Album = defineModel("Album", {
+  prefix: "albums",
+  meta: z.object({
+    artist: z.string(),
+    year: z.number(),
+    genre: z.string(),
+    format: z.enum(["LP", "EP", "Single", "2xLP"]).default("LP"),
+    rating: z.number().min(1).max(5).optional(),
+    condition: z
+      .enum(["mint", "near-mint", "very-good", "good", "fair", "poor"])
+      .default("very-good"),
+  }),
+  sections: {
+    tracklist: section("Tracklist", {
+      extract: (q) => {
+        const tables = q.selectAll("table");
+        if (tables.length > 0) {
+          return parseTable(tables[0]);
+        }
+        return q.selectAll("listItem").map((n) => toString(n));
+      },
+      schema: z.union([
+        z.array(z.record(z.string(), z.string())),
+        z.array(z.string()),
+      ]),
+    }),
+    personnel: section("Personnel", {
+      extract: (q) => q.selectAll("listItem").map((n) => toString(n)),
+      schema: z.array(z.string()),
+    }),
+  },
+  relationships: {
+    artist: belongsTo(() => Artist, {
+      foreignKey: (doc) => doc.meta.artist as string,
+    }),
+  },
+  computed: {
+    isClassic: (self: any) => self.meta.year < 1980,
+    decade: (self: any) => `${Math.floor(self.meta.year / 10) * 10}s`,
+  },
+});

package/showcases/vinyl-collection/queries.ts

@@ -0,0 +1,87 @@
+/**
+ * Example queries for the Vinyl Collection showcase.
+ *
+ * Run with: bun showcases/vinyl-collection/queries.ts
+ */
+import { Collection } from "../../src/index";
+import { Artist, Album } from "./models";
+
+const collection = new Collection({
+  rootPath: new URL(".", import.meta.url).pathname,
+});
+
+collection.register(Artist);
+collection.register(Album);
+await collection.load();
+
+// ── Full collection ──
+const allAlbums = await collection.query(Album).fetchAll();
+console.log(`Total albums in collection: ${allAlbums.length}`);
+
+// ── Filter by genre ──
+const jazzAlbums = await collection
+  .query(Album)
+  .where("meta.genre", "contains", "Jazz")
+  .fetchAll();
+console.log(
+  `\nJazz albums: ${jazzAlbums.map((a) => `${a.title} (${a.meta.year})`).join(", ")}`
+);
+
+// ── Filter by decade (computed) ──
+console.log(`\nAlbums by decade:`);
+for (const album of allAlbums) {
+  console.log(`  ${album.title} — ${album.computed.decade}`);
+}
+
+// ── 5-star records ──
+const topRated = await collection
+  .query(Album)
+  .where("meta.rating", 5)
+  .fetchAll();
+console.log(
+  `\n5-star albums: ${topRated.map((a) => a.title).join(", ")}`
+);
+
+// ── Classics (pre-1980) ──
+console.log(`\nClassics (pre-1980):`);
+for (const album of allAlbums) {
+  if (album.computed.isClassic) {
+    console.log(`  ${album.title} (${album.meta.year})`);
+  }
+}
+
+// ── Condition report ──
+const mint = await collection
+  .query(Album)
+  .whereIn("meta.condition", ["mint", "near-mint"])
+  .fetchAll();
+console.log(
+  `\nMint / near-mint condition: ${mint.map((a) => a.title).join(", ")}`
+);
+
+// ── Tracklist as structured data ──
+const kob = collection.getModel("albums/kind-of-blue", Album);
+console.log(`\n--- ${kob.title} ---`);
+console.log("Tracklist:", kob.sections.tracklist);
+console.log("Personnel:", kob.sections.personnel);
+
+// ── Artist → Albums relationship ──
+const miles = collection.getModel("artists/miles-davis", Artist);
+console.log(`\n--- ${miles.title} ---`);
+console.log("Influences:", miles.sections.influences);
+const milesAlbums = miles.relationships.albums.fetchAll();
+console.log(
+  `Albums in discography: ${milesAlbums.map((a) => a.title).join(", ")}`
+);
+
+// ── Album → Artist relationship ──
+const okc = collection.getModel("albums/ok-computer", Album);
+const artist = okc.relationships.artist.fetch();
+console.log(`\n${okc.title} by ${artist.title} (${artist.meta.origin})`);
+
+// ── Serialize ──
+const json = kob.toJSON({
+  sections: ["tracklist", "personnel"],
+  computed: ["isClassic", "decade"],
+});
+console.log(`\nKind of Blue as JSON:`, JSON.stringify(json, null, 2));

package/src/ast-query.ts

@@ -0,0 +1,132 @@
+import { findBefore } from "unist-util-find-before";
+import { findAfter } from "unist-util-find-after";
+import { findAllBefore } from "unist-util-find-all-before";
+import { findAllAfter } from "unist-util-find-all-after";
+import { visit } from "unist-util-visit";
+import { selectAll, select } from "unist-util-select";
+import { toString } from "mdast-util-to-string";
+import type { Root, Content, Heading, RootContent } from "mdast";
+
+export class AstQuery {
+  readonly ast: Root;
+
+  constructor(ast: Root) {
+    this.ast = ast;
+  }
+
+  /** Find the first node matching a unist-util-select selector. */
+  select(selector: string): Content | null {
+    return select(selector, this.ast) as Content | null;
+  }
+
+  /** Find all nodes matching a unist-util-select selector. */
+  selectAll(selector: string): Content[] {
+    return selectAll(selector, this.ast) as Content[];
+  }
+
+  /** Walk the tree, calling visitor for each node. */
+  visit(visitor: (node: Content) => void): void {
+    visit(this.ast, (node) => {
+      visitor(node as Content);
+    });
+  }
+
+  /** Find all nodes before the given node. */
+  findAllBefore(
+    node: Content,
+    test?: string | ((node: Content) => boolean)
+  ): Content[] {
+    return findAllBefore(this.ast, node as RootContent, test as any) as Content[];
+  }
+
+  /** Find all nodes after the given node. */
+  findAllAfter(
+    node: Content,
+    test?: string | ((node: Content) => boolean)
+  ): Content[] {
+    return findAllAfter(this.ast, node as RootContent, test as any) as Content[];
+  }
+
+  /** Find the first node before the given node matching the test. */
+  findBefore(
+    node: Content,
+    test?: string | ((node: Content) => boolean)
+  ): Content | null {
+    return findBefore(this.ast, node as RootContent, test as any) as Content | null;
+  }
+
+  /** Find the first node after the given node matching the test. */
+  findAfter(
+    node: Content,
+    test?: string | ((node: Content) => boolean)
+  ): Content | null {
+    return findAfter(this.ast, node as RootContent, test as any) as Content | null;
+  }
+
+  /**
+   * Find all nodes between two nodes (exclusive on both ends),
+   * based on line position.
+   */
+  findBetween(nodeOne: Content, nodeTwo: Content): Content[] {
+    const startLine = nodeOne.position?.end?.line ?? 0;
+    const endLine = nodeTwo.position?.start?.line ?? Infinity;
+    return this.ast.children.filter(
+      (child) =>
+        (child.position?.start?.line ?? 0) > startLine &&
+        (child.position?.end?.line ?? 0) < endLine
+    ) as Content[];
+  }
+
+  /** Get the node at a given line number. */
+  atLine(lineNumber: number): Content | undefined {
+    return this.ast.children.find(
+      (child) => child.position?.start?.line === lineNumber
+    ) as Content | undefined;
+  }
+
+  /**
+   * Get all headings at a given depth (1-6).
+   * Fixed: original had a bug calling this.astQuery.selectAll instead of this.selectAll
+   */
+  headingsAtDepth(depth: number): Heading[] {
+    return (this.selectAll("heading") as Heading[]).filter(
+      (h) => h.depth === depth
+    );
+  }
+
+  /** Find the next heading node with the same depth as the given heading. */
+  findNextSiblingHeadingTo(headingNode: Heading): Heading | undefined {
+    const startLine = headingNode.position?.end?.line ?? 0;
+    return (this.selectAll("heading") as Heading[]).find(
+      (h) =>
+        h.depth === headingNode.depth &&
+        (h.position?.start?.line ?? 0) > startLine
+    );
+  }
+
+  /**
+   * Find a heading by its text content. Case insensitive.
+   * Pass exact=false for substring matching.
+   */
+  findHeadingByText(text: string, exact = true): Heading | undefined {
+    return (this.selectAll("heading") as Heading[]).find((heading) => {
+      const headingText = toString(heading).toLowerCase();
+      return exact
+        ? headingText.trim() === text.toLowerCase()
+        : headingText.includes(text.toLowerCase());
+    });
+  }
+
+  /**
+   * Find all headings matching the text. Case insensitive.
+   * Pass exact=false for substring matching.
+   */
+  findAllHeadingsByText(text: string, exact = true): Heading[] {
+    return (this.selectAll("heading") as Heading[]).filter((heading) => {
+      const headingText = toString(heading).toLowerCase();
+      return exact
+        ? headingText.trim() === text.toLowerCase()
+        : headingText.includes(text.toLowerCase());
+    });
+  }
+}

package/src/cli/commands/action.ts

@@ -0,0 +1,44 @@
+import { defineCommand } from "citty";
+import { loadCollection } from "../load-collection";
+
+export default defineCommand({
+  meta: {
+    name: "action",
+    description: "Run a named action on the collection",
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Action name",
+      required: true,
+    },
+    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 actionName = args.name as string;
+
+    if (!collection.actions.has(actionName)) {
+      console.error(
+        `Action "${actionName}" not found. Available: ${collection.availableActions.join(", ") || "(none)"}`
+      );
+      process.exit(1);
+    }
+
+    const result = await collection.runAction(actionName);
+    if (result !== undefined) {
+      console.log(
+        typeof result === "string"
+          ? result
+          : JSON.stringify(result, null, 2)
+      );
+    }
+  },
+});

package/src/cli/commands/create.ts

@@ -0,0 +1,59 @@
+import { defineCommand } from "citty";
+import fs from "fs/promises";
+import path from "path";
+import { loadCollection } from "../load-collection";
+import { kebabCase } from "../../utils/inflect";
+
+export default defineCommand({
+  meta: {
+    name: "create",
+    description: "Create a new document for a model type",
+  },
+  args: {
+    model: {
+      type: "positional",
+      description: "Model name",
+      required: true,
+    },
+    title: {
+      type: "string",
+      description: "Document title",
+      required: true,
+    },
+    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 modelName = args.model as string;
+    const title = args.title as string;
+    const def = collection.getModelDefinition(modelName);
+
+    if (!def) {
+      console.error(
+        `Model "${modelName}" not found. Available: ${collection.modelDefinitions.map((d) => d.name).join(", ")}`
+      );
+      process.exit(1);
+    }
+
+    const slug = kebabCase(title.toLowerCase());
+    const pathId = `${def.prefix}/${slug}`;
+    const filePath = path.resolve(
+      collection.rootPath,
+      `${pathId}.mdx`
+    );
+
+    const content = `---\n---\n\n# ${title}\n`;
+
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, "utf8");
+
+    console.log(`Created ${filePath}`);
+  },
+});

package/src/cli/commands/export.ts

@@ -0,0 +1,24 @@
+import { defineCommand } from "citty";
+import { loadCollection } from "../load-collection";
+
+export default defineCommand({
+  meta: {
+    name: "export",
+    description: "Export collection as JSON",
+  },
+  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,
+    });
+
+    const data = await collection.export();
+    console.log(JSON.stringify(data, null, 2));
+  },
+});

package/src/cli/commands/init.ts

@@ -0,0 +1,75 @@
+import { defineCommand } from "citty";
+import fs from "fs/promises";
+import path from "path";
+
+export default defineCommand({
+  meta: {
+    name: "init",
+    description: "Initialize a new contentbase project",
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Project name",
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const name = (args.name as string) || "my-content";
+    const dir = path.resolve(process.cwd(), name);
+
+    await fs.mkdir(dir, { recursive: true });
+    await fs.mkdir(path.join(dir, "posts"), { recursive: true });
+
+    // Create a sample model file
+    await fs.writeFile(
+      path.join(dir, "models.ts"),
+      `import { defineModel, z } from "contentbase";
+
+export const Post = defineModel("Post", {
+  prefix: "posts",
+  meta: z.object({
+    status: z.enum(["draft", "published"]).default("draft"),
+    author: z.string().optional(),
+  }),
+});
+`,
+      "utf8"
+    );
+
+    // Create a sample post
+    await fs.writeFile(
+      path.join(dir, "posts", "hello-world.mdx"),
+      `---
+status: draft
+author: me
+---
+
+# Hello World
+
+Welcome to your contentbase project!
+`,
+      "utf8"
+    );
+
+    // Create index.ts
+    await fs.writeFile(
+      path.join(dir, "index.ts"),
+      `import { Collection } from "contentbase";
+import { Post } from "./models";
+
+export const collection = new Collection({
+  rootPath: import.meta.dir,
+});
+
+collection.register(Post);
+`,
+      "utf8"
+    );
+
+    console.log(`Created contentbase project at ${dir}`);
+    console.log(`  ${name}/models.ts`);
+    console.log(`  ${name}/index.ts`);
+    console.log(`  ${name}/posts/hello-world.mdx`);
+  },
+});