npm - contentbase - Versions diffs - 0.0.1 → 0.0.4 - Mend

contentbase 0.0.1 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (97) hide show

package/.mcp.json +9 -0
package/CLI.md +593 -0
package/MCP-DESCRIPTIONS-REVIEW.md +122 -0
package/MCP-SERVER-SPEC.md +453 -0
package/PRIMER.md +540 -0
package/README.md +406 -13
package/bun.lock +45 -6
package/dist/cnotes +0 -0
package/docs/README.md +110 -0
package/docs/TABLE-OF-CONTENTS.md +7 -0
package/docs/models.ts +38 -0
package/models.ts +38 -0
package/package.json +14 -4
package/public/web-demo/index.html +813 -0
package/scripts/examples/01-collection-setup.ts +46 -0
package/scripts/examples/02-querying.ts +67 -0
package/scripts/examples/03-sections.ts +36 -0
package/scripts/examples/04-relationships.ts +54 -0
package/scripts/examples/05-document-api.ts +54 -0
package/scripts/examples/06-extract-sections.ts +55 -0
package/scripts/examples/07-validation.ts +46 -0
package/scripts/examples/08-serialization.ts +51 -0
package/scripts/examples/lib/format.ts +87 -0
package/scripts/examples/lib/setup.ts +21 -0
package/scripts/examples/run-all.ts +43 -0
package/showcases/node_modules/.cache/.repl_history +3 -0
package/showcases/vinyl-collection/artists/nina-simone.mdx +1 -1
package/src/__tests__/semantic-search.integration.test.ts +284 -0
package/src/api/endpoints/actions.ts +34 -0
package/src/api/endpoints/doc.ts +187 -0
package/src/api/endpoints/docs-index.ts +26 -0
package/src/api/endpoints/document.ts +171 -0
package/src/api/endpoints/documents.ts +71 -0
package/src/api/endpoints/inspect.ts +16 -0
package/src/api/endpoints/models.ts +10 -0
package/src/api/endpoints/query.ts +88 -0
package/src/api/endpoints/root.ts +7 -0
package/src/api/endpoints/search-reindex.ts +65 -0
package/src/api/endpoints/search-status.ts +55 -0
package/src/api/endpoints/search.ts +104 -0
package/src/api/endpoints/semantic-search.ts +120 -0
package/src/api/endpoints/text-search.ts +63 -0
package/src/api/endpoints/validate.ts +34 -0
package/src/api/helpers.ts +97 -0
package/src/base-model.ts +12 -0
package/src/cli/commands/action.ts +82 -44
package/src/cli/commands/console.ts +124 -0
package/src/cli/commands/create.ts +179 -53
package/src/cli/commands/embed.ts +323 -0
package/src/cli/commands/export.ts +58 -24
package/src/cli/commands/extract.ts +174 -0
package/src/cli/commands/help.ts +81 -0
package/src/cli/commands/index.ts +17 -0
package/src/cli/commands/init.ts +72 -48
package/src/cli/commands/inspect.ts +56 -46
package/src/cli/commands/mcp.ts +1219 -0
package/src/cli/commands/search.ts +285 -0
package/src/cli/commands/serve.ts +348 -0
package/src/cli/commands/summary.ts +60 -0
package/src/cli/commands/teach.ts +86 -0
package/src/cli/commands/text-search.ts +134 -0
package/src/cli/commands/validate.ts +126 -64
package/src/cli/index.ts +88 -19
package/src/cli/load-collection.ts +144 -17
package/src/cli/registry.ts +28 -0
package/src/collection.ts +455 -6
package/src/define-model.ts +104 -7
package/src/document.ts +47 -1
package/src/extract-sections.ts +222 -0
package/src/index.ts +20 -2
package/src/model-instance.ts +35 -5
package/src/node-shortcuts.ts +1 -1
package/src/query/collection-query.ts +96 -9
package/src/query/index.ts +7 -0
package/src/query/query-dsl.ts +259 -0
package/src/relationships/has-many.ts +39 -0
package/src/relationships/index.ts +7 -2
package/src/section.ts +2 -0
package/src/types.ts +24 -2
package/src/utils/index.ts +1 -0
package/src/utils/match-pattern.ts +65 -0
package/src/validator.ts +18 -1
package/test/collection.test.ts +118 -2
package/test/extract-sections.test.ts +356 -0
package/test/fixtures/sdlc/MODELS.md +106 -0
package/test/fixtures/sdlc/SKILL.md +404 -0
package/test/fixtures/sdlc/index.ts +9 -0
package/test/fixtures/sdlc/models.ts +8 -6
package/test/fixtures/sdlc/stories/authentication/a-user-should-be-able-to-login.mdx +20 -0
package/test/fixtures/sdlc/templates/epic.md +23 -0
package/test/fixtures/sdlc/templates/story.md +19 -0
package/test/pattern.test.ts +191 -0
package/test/query-dsl.test.ts +431 -0
package/test/query.test.ts +29 -0
package/test/relationships.test.ts +130 -0
package/test/section.test.ts +65 -4
package/test/table-of-contents.test.ts +135 -0

package/src/api/helpers.ts ADDED Viewed

@@ -0,0 +1,97 @@
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkGfm from 'remark-gfm'
+import remarkRehype from 'remark-rehype'
+import rehypeStringify from 'rehype-stringify'
+import type { Collection } from '../collection.js'
+import { introspectMetaSchema } from '../collection.js'
+export async function renderMarkdownToHtml(markdown: string): Promise<string> {
+  const result = await unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .process(markdown)
+  return String(result)
+}
+export function rewriteDocLinks(html: string): string {
+  return html.replace(/href="([^"]*\.(?:md|mdx))"/g, (match, href) => {
+    if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//')) {
+      return match
+    }
+    return `href="${href.replace(/\.mdx?$/, '')}"`
+  })
+}
+export const tocPageStyle = `<style>
+  *, *::before, *::after { box-sizing: border-box; }
+  body {
+    font-family: 'Inter', system-ui, -apple-system, sans-serif;
+    max-width: 52rem;
+    margin: 0 auto;
+    padding: 2rem 1.5rem;
+    line-height: 1.7;
+    color: #1a1a2e;
+    background: #fafafa;
+  }
+  h1 { font-size: 2rem; font-weight: 600; margin: 2rem 0 1rem; color: #0f0f23; }
+  h2 { font-size: 1.5rem; font-weight: 600; margin: 2.5rem 0 0.75rem; color: #16163a; border-bottom: 1px solid #e2e2e8; padding-bottom: 0.4rem; }
+  a { color: #2563eb; text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  ul { padding-left: 1.5rem; margin: 0.5rem 0 1rem; }
+  li { margin: 0.3rem 0; }
+</style>`
+export async function renderTocPage(collection: Collection): Promise<string> {
+  const tocMarkdown = collection.tableOfContents({ title: 'Table of Contents', basePath: '.' })
+  const tocHtml = rewriteDocLinks(await renderMarkdownToHtml(tocMarkdown))
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Table of Contents</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
+${tocPageStyle}
+</head>
+<body>
+${tocHtml}
+</body></html>`
+}
+export function resolveModelDef(collection: Collection, name: string) {
+  const lower = name.toLowerCase()
+  return collection.modelDefinitions.find(
+    (d: any) => d.name.toLowerCase() === lower || d.prefix.toLowerCase() === lower,
+  )
+}
+export function buildSchemaJSON(collection: Collection) {
+  const models: Record<string, any> = {}
+  for (const def of collection.modelDefinitions as any[]) {
+    const fields = introspectMetaSchema(def.meta)
+    const sections = Object.entries(def.sections || {}).map(([key, sec]: [string, any]) => ({
+      key,
+      heading: sec.heading,
+      alternatives: sec.alternatives || [],
+      hasSchema: !!sec.schema,
+    }))
+    const relationships = Object.entries(def.relationships || {}).map(([key, rel]: [string, any]) => ({
+      key,
+      type: rel.type,
+      model: rel.model,
+    }))
+    models[def.name] = {
+      name: def.name,
+      prefix: def.prefix,
+      description: def.description,
+      fields,
+      sections,
+      relationships,
+      computed: Object.keys(def.computed || {}),
+      scopes: Object.keys(def.scopes || {}),
+    }
+  }
+  return models
+}

package/src/base-model.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { defineModel } from "./define-model";
+/**
+ * Built-in Base model that serves as a catch-all for documents
+ * that don't match any other registered model.
+ * Auto-registered by Collection.load() unless overridden.
+ */
+export const Base = defineModel("Base", {
+  prefix: "",
+  meta: z.looseObject({}),
+});

package/src/cli/commands/action.ts CHANGED Viewed

@@ -1,44 +1,82 @@
-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)
-      );
-    }
-  },
-});
+import { z } from 'zod'
+import { commands } from '../registry.js'
+import { loadCollection } from '../load-collection.js'
+const argsSchema = z.object({
+  contentFolder: z.string().optional(),
+})
+async function handler(options: z.infer<typeof argsSchema>, context: { container: any }) {
+  const collection = await loadCollection({
+    contentFolder: options.contentFolder,
+  })
+  const actionName = context.container.argv._[1] as string | undefined
+  if (!actionName) {
+    console.error('Usage: cnotes action <name>')
+    console.error(`Available: ${collection.availableActions.join(', ') || '(none)'}`)
+    process.exit(1)
+  }
+  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)
+    )
+  }
+}
+commands.register('action', {
+  description: 'Run a named action on the collection',
+  help: `# cnotes action
+Run a named action registered on the collection. Actions are custom functions defined in your collection's entry point.
+## Usage
+\`\`\`
+cnotes action <name> [options]
+\`\`\`
+## Arguments
+| Argument | Description |
+|----------|-------------|
+| \`name\` | The registered action name |
+## Options
+| Option | Description |
+|--------|-------------|
+| \`--contentFolder\` | Path to content folder |
+## Output
+If the action returns a value, it is printed to stdout (strings directly, objects as JSON).
+## Examples
+\`\`\`bash
+# Run an action
+cnotes action generate-report
+# Run an action on a specific content folder
+cnotes action sync --contentFolder ./docs
+# List available actions (shows error with available names)
+cnotes action
+\`\`\`
+`,
+  argsSchema,
+  handler,
+})

package/src/cli/commands/console.ts ADDED Viewed

@@ -0,0 +1,124 @@
+import { z } from 'zod'
+import { commands } from '../registry.js'
+import { loadCollection } from '../load-collection.js'
+const argsSchema = z.object({
+  contentFolder: z.string().optional(),
+})
+async function handler(options: z.infer<typeof argsSchema>, context: { container: any }) {
+  const container = context.container
+  const ui = container.feature('ui')
+  const collection = await loadCollection({
+    contentFolder: options.contentFolder,
+  })
+  const featureContext: Record<string, any> = {
+    collection,
+  }
+  // Expose all container features
+  for (const name of container.features.available) {
+    try {
+      featureContext[name] = container.feature(name)
+    } catch {}
+  }
+  // Load user console module if present
+  const consoleModulePath = container.paths.resolve('cnotes.console.ts')
+  let consoleModuleLoaded = false
+  let consoleModuleError: Error | null = null
+  if (container.fs.exists(consoleModulePath)) {
+    try {
+      const vmFeature = container.feature('vm')
+      const userExports = vmFeature.loadModule(consoleModulePath, { container, console, collection })
+      Object.assign(featureContext, userExports)
+      consoleModuleLoaded = true
+    } catch (err: any) {
+      consoleModuleError = err
+    }
+  }
+  const prompt = ui.colors.cyan('cnotes') + ui.colors.dim(' > ')
+  console.log()
+  console.log(ui.colors.dim('  Contentbase REPL — collection and container features in scope. Tab to autocomplete.'))
+  if (consoleModuleLoaded) {
+    console.log(ui.colors.dim('  Loaded cnotes.console.ts exports into scope.'))
+  } else if (consoleModuleError) {
+    console.log(ui.colors.yellow('  Warning: Failed to load cnotes.console.ts:'))
+    console.log(ui.colors.yellow(`    ${consoleModuleError.message}`))
+    console.log(ui.colors.dim('  The REPL will start without your custom exports.'))
+  }
+  console.log(ui.colors.dim('  Type .exit to quit.'))
+  console.log()
+  const repl = container.feature('repl', { prompt })
+  await repl.start({
+    context: {
+      ...featureContext,
+      console,
+      setTimeout,
+      setInterval,
+      clearTimeout,
+      clearInterval,
+      fetch,
+      Bun,
+    },
+  })
+}
+commands.register('console', {
+  description: 'Start an interactive REPL with collection and container features in scope',
+  help: `# cnotes console
+Start an interactive REPL with the loaded collection, all container features, and optional user-defined exports in scope. Useful for exploring and debugging your content.
+## Usage
+\`\`\`
+cnotes console [options]
+\`\`\`
+## Options
+| Option | Description |
+|--------|-------------|
+| \`--contentFolder\` | Path to content folder |
+## Scope
+The REPL has these variables available:
+- \`collection\` — The loaded Collection instance
+- All luca container features (fs, ui, grep, etc.)
+- Exports from \`cnotes.console.ts\` if present in the project root
+## Custom Console Module
+Create a \`cnotes.console.ts\` file in your project root to add custom helpers to the REPL scope:
+\`\`\`typescript
+export const myHelper = () => "hello from console"
+\`\`\`
+## Examples
+\`\`\`bash
+# Start the REPL
+cnotes console
+# Start with a specific content folder
+cnotes console --contentFolder ./docs
+# Once inside the REPL:
+#   collection.available           — list all document IDs
+#   collection.document('posts/hello')  — load a document
+#   .exit                          — quit
+\`\`\`
+`,
+  argsSchema,
+  handler,
+})

package/src/cli/commands/create.ts CHANGED Viewed

@@ -1,59 +1,185 @@
-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);
+import { z } from 'zod'
+import fs from 'fs/promises'
+import path from 'path'
+import matter from 'gray-matter'
+import { commands } from '../registry.js'
+import { loadCollection } from '../load-collection.js'
+import { kebabCase } from '../../utils/inflect.js'
+import { introspectMetaSchema } from '../../collection.js'
+const argsSchema = z.object({
+  title: z.string().optional(),
+  contentFolder: z.string().optional(),
+})
+async function handler(options: z.infer<typeof argsSchema>, context: { container: any }) {
+  const collection = await loadCollection({
+    contentFolder: options.contentFolder,
+  })
+  const modelName = context.container.argv._[1] as string | undefined
+  if (!modelName) {
+    console.error('Usage: cnotes create <model> --title "Document Title"')
+    process.exit(1)
+  }
+  const title = options.title
+  if (!title) {
+    console.error('--title is required')
+    process.exit(1)
+  }
+  const def =
+    collection.getModelDefinition(modelName) ??
+    collection.modelDefinitions.find(
+      (d) => d.name.toLowerCase() === modelName.toLowerCase()
+    )
+  if (!def) {
+    console.error(
+      `Model "${modelName}" not found. Available: ${collection.modelDefinitions.map((d) => d.name).join(', ')}`
+    )
+    process.exit(1)
+  }
+  // Parse --meta.* flags from raw argv
+  const metaOverrides: Record<string, unknown> = {}
+  const rawArgs = context.container.argv
+  for (const key of Object.keys(rawArgs)) {
+    if (key.startsWith('meta.')) {
+      metaOverrides[key.slice(5)] = rawArgs[key]
     }
+  }
+  // Build meta from priority layers: zod defaults < definition.defaults < template frontmatter < CLI overrides
+  const zodDefaults: Record<string, unknown> = {}
+  for (const field of introspectMetaSchema(def.meta)) {
+    if (field.defaultValue !== undefined) {
+      zodDefaults[field.name] = field.defaultValue
+    }
+  }
+  const definitionDefaults: Record<string, unknown> = def.defaults ?? {}
-    const slug = kebabCase(title.toLowerCase());
-    const pathId = `${def.prefix}/${slug}`;
-    const filePath = path.resolve(
+  // Template lookup
+  const templateExtensions = ['md', 'mdx']
+  let templateContent: string | null = null
+  for (const ext of templateExtensions) {
+    const templatePath = path.resolve(
       collection.rootPath,
-      `${pathId}.mdx`
-    );
+      'templates',
+      `${modelName.toLowerCase()}.${ext}`
+    )
+    try {
+      templateContent = await fs.readFile(templatePath, 'utf8')
+      break
+    } catch {
+      // template not found, try next extension
+    }
+  }
+  let content: string
+  if (templateContent) {
+    const parsed = matter(templateContent)
+    const mergedMeta = {
+      ...zodDefaults,
+      ...definitionDefaults,
+      ...parsed.data,
+      ...metaOverrides,
+    }
+    const body = parsed.content.replace(/^# .+$/m, `# ${title}`)
+    content = matter.stringify(body, mergedMeta)
+  } else {
+    const mergedMeta = {
+      ...zodDefaults,
+      ...definitionDefaults,
+      ...metaOverrides,
+    }
+    const lines: string[] = []
+    lines.push(`# ${title}`)
+    lines.push('')
+    const sections = def.sections ?? {}
+    for (const [, sec] of Object.entries(sections)) {
+      const s = sec as any
+      lines.push(`## ${s.heading}`)
+      lines.push('')
+      if (s.schema?.description) {
+        lines.push(s.schema.description)
+        lines.push('')
+      }
+    }
+    content = matter.stringify(lines.join('\n'), mergedMeta)
+  }
+  const slug = kebabCase(title.toLowerCase())
+  const pathId = `${def.prefix}/${slug}`
+  const filePath = path.resolve(collection.rootPath, `${pathId}.md`)
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  await fs.writeFile(filePath, content, 'utf8')
+  console.log(`Created ${filePath}`)
+}
+commands.register('create', {
+  description: 'Create a new document for a model type',
+  help: `# cnotes create
+Create a new document for a registered model, with proper frontmatter defaults and section scaffolding.
+## Usage
+\`\`\`
+cnotes create <model> --title "Document Title" [options]
+\`\`\`
+## Arguments
+| Argument | Description |
+|----------|-------------|
+| \`model\` | Model name (e.g. \`Post\`, \`Epic\`, \`Task\`) |
+## Options
+| Option | Description |
+|--------|-------------|
+| \`--title\` | **Required.** Title for the new document (used as H1 and slug) |
+| \`--meta.*\` | Set frontmatter fields (e.g. \`--meta.status active\`) |
+| \`--contentFolder\` | Path to content folder |
+## Template Lookup
+If \`templates/<model>.md\` (or \`.mdx\`) exists in the content root, it will be used as the document scaffold. Template frontmatter is merged with schema defaults and CLI overrides.
+## Meta Priority
+Frontmatter values are merged in this order (last wins):
+1. Zod schema defaults
+2. Model definition defaults
+3. Template frontmatter
+4. CLI \`--meta.*\` overrides
+## Examples
-    const content = `---\n---\n\n# ${title}\n`;
+\`\`\`bash
+# Create a new post
+cnotes create Post --title "My First Post"
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, content, "utf8");
+# Create with meta overrides
+cnotes create Task --title "Fix login bug" --meta.status active --meta.priority high
-    console.log(`Created ${filePath}`);
-  },
-});
+# Create from a different content folder
+cnotes create Epic --title "Auth System" --contentFolder ./docs
+\`\`\`
+`,
+  argsSchema,
+  handler,
+})