contentbase 0.0.1

package/examples/sdlc-queries.ts

@@ -0,0 +1,161 @@
+/**
+ * Contentbase Example: Querying an SDLC Content Collection
+ *
+ * This script demonstrates loading a collection of Epics and Stories
+ * from markdown files and querying them using the Contentbase API.
+ *
+ * Run with: bun run examples/sdlc-queries.ts
+ */
+import path from "path";
+import { fileURLToPath } from "url";
+import { Collection, type InferModelInstance } from "../src/index";
+import { Epic, Story, type StoryDef } from "../test/fixtures/sdlc/models";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const basePath = path.resolve(__dirname, "../test/fixtures/sdlc");
+
+async function main() {
+  // 1. Create and load the collection
+  const collection = new Collection({
+    rootPath: basePath,
+    name: "sdlc",
+  });
+
+  collection.register(Epic);
+  collection.register(Story);
+  await collection.load();
+
+  console.log("Available documents:", collection.available);
+
+  // -------------------------------------------------------
+  // 2. Get a single model instance by path ID
+  // -------------------------------------------------------
+  const authEpic = collection.getModel("epics/authentication", Epic);
+
+  console.log("\n--- Epic: Authentication ---");
+  console.log("Title:", authEpic.title);
+  console.log("Slug:", authEpic.slug);
+  console.log("Status:", authEpic.meta.status);
+  console.log("Priority:", authEpic.meta.priority);
+  console.log("Is complete?", authEpic.computed.isComplete);
+
+  // -------------------------------------------------------
+  // 3. Query all epics
+  // -------------------------------------------------------
+  const allEpics = await collection.query(Epic).fetchAll();
+
+  console.log("\n--- All Epics ---");
+  for (const epic of allEpics) {
+    console.log(`  ${epic.title} (${epic.meta.status})`);
+  }
+
+  // -------------------------------------------------------
+  // 4. Filter with where clauses
+  // -------------------------------------------------------
+  const highPriority = await collection
+    .query(Epic)
+    .where("meta.priority", "high")
+    .fetchAll();
+
+  console.log("\n--- High Priority Epics ---");
+  for (const epic of highPriority) {
+    console.log(`  ${epic.title} — priority: ${epic.meta.priority}`);
+  }
+
+  // -------------------------------------------------------
+  // 5. Query helpers: first, last, count
+  // -------------------------------------------------------
+  const firstEpic = await collection.query(Epic).first();
+  const lastEpic = await collection.query(Epic).last();
+  const epicCount = await collection.query(Epic).count();
+
+  console.log("\n--- Query Helpers ---");
+  console.log("First epic:", firstEpic?.title);
+  console.log("Last epic:", lastEpic?.title);
+  console.log("Total epics:", epicCount);
+
+  // -------------------------------------------------------
+  // 6. Chained where clauses (AND logic)
+  // -------------------------------------------------------
+  const filtered = await collection
+    .query(Epic)
+    .where("meta.status", "created")
+    .whereExists("meta.priority")
+    .fetchAll();
+
+  console.log("\n--- Created Epics with Priority Set ---");
+  for (const epic of filtered) {
+    console.log(`  ${epic.title} — ${epic.meta.priority}`);
+  }
+
+  // -------------------------------------------------------
+  // 7. HasMany relationships — Epic -> Stories
+  // -------------------------------------------------------
+  const stories = authEpic.relationships.stories.fetchAll();
+
+  console.log("\n--- Stories under Authentication Epic ---");
+  for (const story of stories) {
+    console.log(`  ${story.title}`);
+  }
+
+  console.log("First story:", authEpic.relationships.stories.first()?.title);
+  console.log("Last story:", authEpic.relationships.stories.last()?.title);
+
+  // -------------------------------------------------------
+  // 8. BelongsTo relationships — Story -> Epic
+  // -------------------------------------------------------
+  const registerStory: InferModelInstance<StoryDef> = collection.getModel(
+    "stories/authentication/a-user-should-be-able-to-register",
+    Story
+  );
+
+  const parentEpic = registerStory.relationships.epic.fetch();
+
+  console.log("\n--- Story -> Epic (belongsTo) ---");
+  console.log(`"${registerStory.title}" belongs to "${parentEpic.title}"`);
+
+  // -------------------------------------------------------
+  // 9. Sections — structured data extracted from headings
+  // -------------------------------------------------------
+  console.log("\n--- Sections: Acceptance Criteria ---");
+  for (const criterion of registerStory.sections.acceptanceCriteria) {
+    console.log(`  • ${criterion}`);
+  }
+
+  console.log("\n--- Sections: Mockups ---");
+  for (const [label, url] of Object.entries(registerStory.sections.mockups)) {
+    console.log(`  ${label}: ${url}`);
+  }
+
+  // -------------------------------------------------------
+  // 10. Validation
+  // -------------------------------------------------------
+  const result = await registerStory.validate();
+
+  console.log("\n--- Validation ---");
+  console.log("Valid?", result.valid);
+  console.log("Error count:", result.errors.length);
+
+  // -------------------------------------------------------
+  // 11. Serialization
+  // -------------------------------------------------------
+  const json = authEpic.toJSON({
+    computed: ["isComplete"],
+    related: ["stories"],
+  });
+
+  console.log("\n--- toJSON ---");
+  console.log(JSON.stringify(json, null, 2));
+
+  // -------------------------------------------------------
+  // 12. Working with the raw Document
+  // -------------------------------------------------------
+  const doc = authEpic.document;
+
+  console.log("\n--- Raw Document ---");
+  console.log("Headings:", doc.nodes.headings.length);
+  console.log("Links:", doc.nodes.links.length);
+  console.log("Lists:", doc.nodes.lists.length);
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "contentbase",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "contentbase": "./src/cli/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "citty": "^0.1.6",
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.0",
+    "mdast-util-mdxjs-esm": "^2.0.1",
+    "mdast-util-to-markdown": "^2.1.2",
+    "mdast-util-to-string": "^4.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "unified": "^11.0.5",
+    "unist-util-find-after": "^5.0.0",
+    "unist-util-find-all-after": "^5.0.0",
+    "unist-util-find-all-before": "^5.0.0",
+    "unist-util-find-before": "^4.0.0",
+    "unist-util-select": "^5.1.0",
+    "unist-util-visit": "^5.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/mdast": "^4.0.4",
+    "bun-types": "^1.1.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}

package/showcases/national-parks/models.ts

@@ -0,0 +1,74 @@
+import {
+  defineModel,
+  section,
+  hasMany,
+  belongsTo,
+  z,
+} from "../../src/index";
+import { toString } from "mdast-util-to-string";
+import { parseTable } from "../../src/utils/parse-table";
+
+// ─── Park (parent) ───
+
+export const Park = defineModel("Park", {
+  prefix: "parks",
+  meta: z.object({
+    state: z.string(),
+    region: z.enum(["west", "southwest", "southeast", "northeast", "midwest"]),
+    established: z.number(),
+    area: z.string(),
+    visitors: z.number(),
+    fee: z.number(),
+  }),
+  sections: {
+    wildlife: section("Wildlife", {
+      extract: (q) => q.selectAll("listItem").map((n) => toString(n)),
+      schema: z.array(z.string()),
+    }),
+    seasons: section("Best Seasons", {
+      extract: (q) => {
+        const tables = q.selectAll("table");
+        if (tables.length > 0) {
+          return parseTable(tables[0]);
+        }
+        return [];
+      },
+      schema: z.array(z.record(z.string(), z.string())),
+    }),
+  },
+  relationships: {
+    trails: hasMany(() => Trail, { heading: "Trails" }),
+  },
+  computed: {
+    isPopular: (self: any) => self.meta.visitors > 3_000_000,
+    ageYears: (self: any) => new Date().getFullYear() - self.meta.established,
+  },
+});
+
+// ─── Trail ───
+
+export const Trail = defineModel("Trail", {
+  prefix: "trails",
+  meta: z.object({
+    park: z.string(),
+    distance: z.string(),
+    elevationGain: z.string(),
+    difficulty: z.enum(["easy", "moderate", "strenuous"]),
+    type: z.enum(["out-and-back", "loop", "point-to-point"]),
+    dogs: z.boolean().default(false),
+  }),
+  sections: {
+    highlights: section("Highlights", {
+      extract: (q) => q.selectAll("listItem").map((n) => toString(n)),
+      schema: z.array(z.string()),
+    }),
+  },
+  relationships: {
+    park: belongsTo(() => Park, {
+      foreignKey: (doc) => doc.meta.park as string,
+    }),
+  },
+  computed: {
+    isLong: (self: any) => parseFloat(self.meta.distance) > 10,
+  },
+});

package/showcases/national-parks/parks/acadia.mdx

@@ -0,0 +1,40 @@
+---
+state: Maine
+region: northeast
+established: 1919
+area: "49,071 acres"
+visitors: 4069000
+fee: 30
+---
+
+# Acadia
+
+The only national park in the northeastern United States. Rocky coastline, granite peaks, and boreal forest crammed onto an island off the coast of Maine. Small in acreage but staggering in density of beauty.
+
+## Wildlife
+
+- Moose
+- Harbor seal
+- Bald eagle
+- Puffin (offshore)
+- Snowshoe hare
+- Peregrine falcon
+
+## Best Seasons
+
+| Season | Conditions | Crowds |
+| --- | --- | --- |
+| Spring | Mud season, wildflowers begin | Light |
+| Summer | Warm, long days, all carriage roads open | Heavy |
+| Fall | Peak foliage, crisp air, perfect hiking | Heavy |
+| Winter | Snow, cross-country skiing, solitude | Very light |
+
+## Trails
+
+### Precipice Trail
+
+Iron rungs and ladders bolted into a cliff face. More climb than hike. Seasonal closures for nesting peregrines.
+
+### Jordan Pond Path
+
+A flat, easy loop around the clearest lake in the park. End with popovers at Jordan Pond House.

package/showcases/national-parks/parks/yosemite.mdx

@@ -0,0 +1,44 @@
+---
+state: California
+region: west
+established: 1890
+area: "748,436 acres"
+visitors: 3690000
+fee: 35
+---
+
+# Yosemite
+
+Granite cliffs, ancient sequoias, and waterfalls that drop thousands of feet. Yosemite Valley alone is worth the trip, but the backcountry — Tuolumne Meadows, the high Sierra — is where the park reveals its full scale.
+
+## Wildlife
+
+- Black bear
+- Mule deer
+- Peregrine falcon
+- Sierra Nevada bighorn sheep
+- Great gray owl
+- Pacific fisher
+
+## Best Seasons
+
+| Season | Conditions | Crowds |
+| --- | --- | --- |
+| Spring | Waterfalls at peak flow, some roads closed | Moderate |
+| Summer | Warm, all facilities open | Heavy |
+| Fall | Cool, fewer crowds, fall color | Light |
+| Winter | Snow, Tioga Road closed, skiing | Very light |
+
+## Trails
+
+### Mist Trail
+
+The park's most iconic hike — steep granite stairs through the spray of Vernal Fall and on to Nevada Fall.
+
+### Half Dome
+
+The bucket-list summit. Cables, permits, and 14+ miles of exertion for a view you'll never forget.
+
+### Cathedral Lakes
+
+A high-country gem in Tuolumne Meadows — alpine lakes ringed by granite peaks.

package/showcases/national-parks/parks/zion.mdx

@@ -0,0 +1,44 @@
+---
+state: Utah
+region: southwest
+established: 1919
+area: "147,242 acres"
+visitors: 4692000
+fee: 35
+---
+
+# Zion
+
+Massive sandstone walls in shades of red, pink, and cream tower above the Virgin River. The canyon is narrow enough to feel intimate and vast enough to feel humbling. Zion manages to be both.
+
+## Wildlife
+
+- Desert bighorn sheep
+- California condor
+- Ringtail cat
+- Collared lizard
+- Mexican spotted owl
+- Canyon tree frog
+
+## Best Seasons
+
+| Season | Conditions | Crowds |
+| --- | --- | --- |
+| Spring | Wildflowers, moderate temps, some flash flood risk | Moderate |
+| Summer | Hot (100°F+), best for The Narrows | Very heavy |
+| Fall | Perfect temps, fall color in the canyon | Moderate |
+| Winter | Cool, snow on rims, peaceful | Light |
+
+## Trails
+
+### Angels Landing
+
+A chain-assisted climb along a narrow ridge with 1,500-foot dropoffs on either side. Not for the faint-hearted.
+
+### The Narrows
+
+Wade upstream through the Virgin River between thousand-foot canyon walls. The ultimate slot canyon experience.
+
+### Observation Point
+
+The highest viewpoint in the main canyon — looks down on Angels Landing from above.

package/showcases/national-parks/queries.ts

@@ -0,0 +1,103 @@
+/**
+ * Example queries for the National Parks showcase.
+ *
+ * Run with: bun showcases/national-parks/queries.ts
+ */
+import { Collection } from "../../src/index";
+import { Park, Trail } from "./models";
+
+const collection = new Collection({
+  rootPath: new URL(".", import.meta.url).pathname,
+});
+
+collection.register(Park);
+collection.register(Trail);
+await collection.load();
+
+// ── All parks ──
+const allParks = await collection.query(Park).fetchAll();
+console.log(`Total parks: ${allParks.length}`);
+for (const park of allParks) {
+  console.log(
+    `  ${park.title} (${park.meta.state}) — ${park.meta.area}, est. ${park.meta.established}`
+  );
+}
+
+// ── Filter by region ──
+const western = await collection
+  .query(Park)
+  .whereIn("meta.region", ["west", "southwest"])
+  .fetchAll();
+console.log(
+  `\nWestern parks: ${western.map((p) => p.title).join(", ")}`
+);
+
+// ── Popular parks (>3M visitors) ──
+console.log(`\nPopular parks (>3M visitors):`);
+for (const park of allParks) {
+  if (park.computed.isPopular) {
+    console.log(
+      `  ${park.title} — ${park.meta.visitors.toLocaleString()} visitors`
+    );
+  }
+}
+
+// ── Park age ──
+console.log(`\nPark ages:`);
+for (const park of allParks) {
+  console.log(`  ${park.title}: ${park.computed.ageYears} years old`);
+}
+
+// ── All trails ──
+const allTrails = await collection.query(Trail).fetchAll();
+console.log(`\nTotal trails: ${allTrails.length}`);
+
+// ── Filter by difficulty ──
+const strenuous = await collection
+  .query(Trail)
+  .where("meta.difficulty", "strenuous")
+  .fetchAll();
+console.log(
+  `\nStrenuous trails: ${strenuous.map((t) => t.title).join(", ")}`
+);
+
+const easy = await collection
+  .query(Trail)
+  .where("meta.difficulty", "easy")
+  .fetchAll();
+console.log(`Easy trails: ${easy.map((t) => t.title).join(", ")}`);
+
+// ── Dog-friendly trails ──
+const dogFriendly = await collection
+  .query(Trail)
+  .where("meta.dogs", true)
+  .fetchAll();
+console.log(
+  `\nDog-friendly trails: ${dogFriendly.map((t) => t.title).join(", ")}`
+);
+
+// ── Sections as structured data ──
+const yosemite = collection.getModel("parks/yosemite", Park);
+console.log(`\n--- ${yosemite.title} ---`);
+console.log("Wildlife:", yosemite.sections.wildlife);
+console.log("Best seasons:", yosemite.sections.seasons);
+
+// ── Park → Trails relationship (hasMany) ──
+const zion = collection.getModel("parks/zion", Park);
+const zionTrails = zion.relationships.trails.fetchAll();
+console.log(
+  `\n${zion.title} trails: ${zionTrails.map((t) => t.title).join(", ")}`
+);
+
+// ── Trail → Park relationship (belongsTo) ──
+const narrows = collection.getModel("trails/the-narrows", Trail);
+const parentPark = narrows.relationships.park.fetch();
+console.log(`\n${narrows.title} is in ${parentPark.title} (${parentPark.meta.state})`);
+console.log("Highlights:", narrows.sections.highlights);
+
+// ── Serialize ──
+const json = yosemite.toJSON({
+  sections: ["wildlife", "seasons"],
+  computed: ["isPopular", "ageYears"],
+});
+console.log(`\nYosemite as JSON:`, JSON.stringify(json, null, 2));

package/showcases/national-parks/trails/angels-landing.mdx

@@ -0,0 +1,19 @@
+---
+park: zion
+distance: "5.4 mi"
+elevationGain: "1,488 ft"
+difficulty: strenuous
+type: out-and-back
+dogs: false
+---
+
+# Angels Landing
+
+Zion's most famous trail — and one of the most exposed hikes in any national park. The final half-mile follows a knife-edge ridge with chains for handholds and sheer dropoffs on both sides. Permit required.
+
+## Highlights
+
+- Walter's Wiggles — 21 tight switchbacks carved into the cliff
+- Scout Lookout — a wide saddle with stunning views even if you turn back here
+- Chain section along the narrow ridge
+- Panoramic views of Zion Canyon from the 5,790 ft summit

package/showcases/national-parks/trails/cathedral-lakes.mdx

@@ -0,0 +1,19 @@
+---
+park: yosemite
+distance: "7.0 mi"
+elevationGain: "1,000 ft"
+difficulty: moderate
+type: out-and-back
+dogs: false
+---
+
+# Cathedral Lakes
+
+A high-country classic in Tuolumne Meadows. Two pristine alpine lakes sit in granite bowls below Cathedral Peak. The trail winds through subalpine meadows dotted with wildflowers in midsummer.
+
+## Highlights
+
+- Lower Cathedral Lake — wide and open with Cathedral Peak reflected in the water
+- Upper Cathedral Lake — smaller, more secluded, tucked under the peak
+- Wildflower meadows in July and August
+- Views of Cathedral Peak and Eichorn Pinnacle

package/showcases/national-parks/trails/half-dome.mdx

@@ -0,0 +1,19 @@
+---
+park: yosemite
+distance: "14.2 mi"
+elevationGain: "4,800 ft"
+difficulty: strenuous
+type: out-and-back
+dogs: false
+---
+
+# Half Dome
+
+The defining Yosemite summit. A full-day endurance test that follows the Mist Trail, then climbs through the sub-dome before ascending the final 400 feet on steel cables bolted into granite. Permits required.
+
+## Highlights
+
+- Cable section on the final ascent — thrilling and exposed
+- Summit views of Tenaya Canyon, Clouds Rest, and the entire valley
+- Passes both Vernal and Nevada Falls on the way up
+- Sub-dome scramble over smooth granite slabs

package/showcases/national-parks/trails/jordan-pond-path.mdx

@@ -0,0 +1,19 @@
+---
+park: acadia
+distance: "3.3 mi"
+elevationGain: "105 ft"
+difficulty: easy
+type: loop
+dogs: true
+---
+
+# Jordan Pond Path
+
+A flat, family-friendly loop around the clearest lake in Acadia. The path hugs the shoreline through mixed forest, with iconic views of the Bubbles — two rounded granite peaks — reflected in the water.
+
+## Highlights
+
+- Mirror-like reflections of the Bubbles on calm mornings
+- Boardwalk sections over the boggy north shore
+- Jordan Pond House for tea and popovers after the hike
+- Accessible for all skill levels and ages

package/showcases/national-parks/trails/mist-trail.mdx

@@ -0,0 +1,19 @@
+---
+park: yosemite
+distance: "5.4 mi"
+elevationGain: "1,000 ft"
+difficulty: strenuous
+type: out-and-back
+dogs: false
+---
+
+# Mist Trail
+
+Yosemite's most iconic day hike. Steep granite stairs climb through the spray of Vernal Fall, then continue along the Merced River to the top of Nevada Fall. You will get wet.
+
+## Highlights
+
+- Vernal Fall (317 ft) — close enough to feel the mist
+- Nevada Fall (594 ft) — a massive cascade visible from the bridge above
+- Emerald Pool between the two falls
+- Granite staircase carved into the cliff face

package/showcases/national-parks/trails/observation-point.mdx

@@ -0,0 +1,19 @@
+---
+park: zion
+distance: "8.0 mi"
+elevationGain: "2,148 ft"
+difficulty: strenuous
+type: out-and-back
+dogs: false
+---
+
+# Observation Point
+
+The highest viewpoint accessible by trail in Zion Canyon. From the top, you look directly down on Angels Landing — a perspective that makes you appreciate how exposed that ridge really is.
+
+## Highlights
+
+- Echo Canyon section — narrow side canyon with weeping rock walls
+- Views down onto Angels Landing and the Great White Throne
+- Cable Mountain and the historic cable works ruins nearby
+- Slickrock terrain near the summit

package/showcases/national-parks/trails/precipice-trail.mdx

@@ -0,0 +1,19 @@
+---
+park: acadia
+distance: "1.6 mi"
+elevationGain: "1,058 ft"
+difficulty: strenuous
+type: out-and-back
+dogs: false
+---
+
+# Precipice Trail
+
+Acadia's most thrilling route — iron rungs, ladders, and narrow ledges bolted into the cliff face of Champlain Mountain. More via ferrata than hiking trail. Closed spring through midsummer for peregrine falcon nesting.
+
+## Highlights
+
+- Iron rung ladders on near-vertical rock faces
+- Exposed traverses with ocean views
+- Summit views of Frenchman Bay and the Porcupine Islands
+- Peregrine falcons nesting on the cliff (visible from below during closures)

package/showcases/national-parks/trails/the-narrows.mdx

@@ -0,0 +1,19 @@
+---
+park: zion
+distance: "9.4 mi"
+elevationGain: "334 ft"
+difficulty: strenuous
+type: out-and-back
+dogs: false
+---
+
+# The Narrows
+
+A river hike through the narrowest section of Zion Canyon. You wade — and occasionally swim — upstream through the Virgin River between sandstone walls up to 1,000 feet high. Entirely unlike any other trail in the park system.
+
+## Highlights
+
+- Wall Street section — walls narrow to 20 feet with the river filling the entire canyon floor
+- Orderville Canyon junction — a side canyon worth exploring
+- Hanging gardens of ferns and columbine on the canyon walls
+- The interplay of light and shadow in the narrow slot