contentbase 0.0.2 → 0.0.4

package/src/cli/commands/teach.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod'
+import fs from 'fs/promises'
+import path from 'path'
+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>) {
+  const collection = await loadCollection({
+    contentFolder: options.contentFolder,
+  })
+
+  const modelsSummary = collection.generateModelSummary()
+  const toc = collection.tableOfContents({ title: 'Table of Contents' })
+
+  // Read the bundled static docs from the contentbase package
+  const packageRoot = path.resolve(import.meta.dir, '../../..')
+  const primer = await fs.readFile(path.join(packageRoot, 'PRIMER.md'), 'utf8')
+  const cli = await fs.readFile(path.join(packageRoot, 'CLI.md'), 'utf8')
+
+  const output = [
+    modelsSummary.trimEnd(),
+    '',
+    '---',
+    '',
+    toc.trimEnd(),
+    '',
+    '---',
+    '',
+    cli.trimEnd(),
+    '',
+    '---',
+    '',
+    primer.trimEnd(),
+    '',
+  ].join('\n')
+
+  console.log(output)
+}
+
+commands.register('teach', {
+  description: 'Output combined documentation (README.md + TOC + CLI.md + PRIMER.md) for LLM context',
+  help: `# cnotes teach
+
+Output combined documentation suitable for feeding to an LLM as context. Concatenates the models summary, table of contents, CLI reference, and API primer into a single stream.
+
+## Usage
+
+\`\`\`
+cnotes teach [options]
+\`\`\`
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| \`--contentFolder\` | Path to content folder |
+
+## Output
+
+Writes to stdout in this order:
+
+1. **README.md** — Model definitions summary
+2. **TABLE-OF-CONTENTS.md** — Document listing
+3. **CLI.md** — CLI reference
+4. **PRIMER.md** — API primer
+
+## Examples
+
+\`\`\`bash
+# Print full documentation
+cnotes teach
+
+# Save to a file for LLM context
+cnotes teach > context.md
+
+# Teach from a specific content folder
+cnotes teach --contentFolder ./docs
+\`\`\`
+`,
+  argsSchema,
+  handler,
+})

package/src/cli/commands/text-search.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod'
+import { commands } from '../registry.js'
+import { loadCollection } from '../load-collection.js'
+
+const argsSchema = z.object({
+  include: z.string().optional(),
+  exclude: z.string().optional(),
+  ignoreCase: z.boolean().default(false),
+  expanded: z.boolean().default(false),
+  maxResults: z.number().optional(),
+  contentFolder: z.string().optional(),
+})
+
+async function handler(options: z.infer<typeof argsSchema>, { container }: { container: any }) {
+  const pattern = container.argv._[1] as string | undefined
+
+  if (!pattern) {
+    console.error('Usage: cnotes text-search <pattern> [options]')
+    console.error('  --expanded      Show line-level matches (default: files only)')
+    console.error('  --include       Glob filter (e.g. "*.md")')
+    console.error('  --exclude       Glob filter')
+    console.error('  --ignoreCase    Case insensitive search')
+    console.error('  --maxResults    Limit number of results')
+    process.exit(1)
+  }
+
+  const collection = await loadCollection({
+    contentFolder: options.contentFolder,
+  })
+
+  const grep = container.feature('grep')
+  const searchPath = collection.rootPath
+
+  const grepOptions: any = {
+    pattern,
+    path: searchPath,
+    ignoreCase: options.ignoreCase,
+    maxResults: options.maxResults,
+    include: options.include,
+    exclude: options.exclude,
+  }
+
+  if (!options.expanded) {
+    const files = await grep.filesContaining(pattern, {
+      path: searchPath,
+      ignoreCase: options.ignoreCase,
+      maxResults: options.maxResults,
+      include: options.include,
+      exclude: options.exclude,
+    })
+
+    if (files.length === 0) {
+      console.log('No matches found.')
+      return
+    }
+
+    console.log(`${files.length} file(s) match:\n`)
+    for (const file of files) {
+      console.log(`  ${file}`)
+    }
+  } else {
+    const results = await grep.search(grepOptions)
+
+    if (results.length === 0) {
+      console.log('No matches found.')
+      return
+    }
+
+    // Group by file
+    const grouped = new Map<string, typeof results>()
+    for (const match of results) {
+      if (!grouped.has(match.file)) grouped.set(match.file, [])
+      grouped.get(match.file)!.push(match)
+    }
+
+    console.log(`${grouped.size} file(s), ${results.length} match(es):\n`)
+    for (const [file, matches] of grouped) {
+      console.log(`  ${file}`)
+      for (const m of matches) {
+        console.log(`    ${m.line}: ${m.content}`)
+      }
+      console.log()
+    }
+  }
+}
+
+commands.register('text-search', {
+  description: 'Search file contents with pattern matching',
+  help: `# cnotes text-search
+
+Search file contents within the collection using ripgrep. Returns matching files by default, or line-level detail with \`--expanded\`.
+
+## Usage
+
+\`\`\`
+cnotes text-search <pattern> [options]
+\`\`\`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| \`pattern\` | Text or regex pattern to search for |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| \`--expanded\` | \`false\` | Show line-level matches instead of just file paths |
+| \`--include\` | | Glob filter for file types (e.g. \`"*.md"\`) |
+| \`--exclude\` | | Glob filter to exclude (e.g. \`"node_modules"\`) |
+| \`--ignoreCase\` | \`false\` | Case-insensitive matching |
+| \`--maxResults\` | | Limit number of results |
+| \`--contentFolder\` | | Path to content folder |
+
+## Examples
+
+\`\`\`bash
+# Find files containing "authentication"
+cnotes text-search authentication
+
+# Case-insensitive search with line details
+cnotes text-search "TODO" --ignoreCase --expanded
+
+# Search only markdown files
+cnotes text-search "status: draft" --include "*.md"
+
+# Limit results
+cnotes text-search "import" --maxResults 10 --expanded
+\`\`\`
+`,
+  argsSchema,
+  handler,
+})

package/src/cli/commands/validate.ts

@@ -1,75 +1,137 @@
-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];
+import { z } from 'zod'
+import { commands } from '../registry.js'
+import { loadCollection } from '../load-collection.js'
+import { validateDocument } from '../../validator.js'
+
+const argsSchema = z.object({
+  contentFolder: z.string().optional(),
+  setDefaultMeta: z.boolean().default(false),
+})
+
+async function handler(options: z.infer<typeof argsSchema>, context: { container: any }) {
+  const collection = await loadCollection({
+    contentFolder: options.contentFolder,
+  })
+
+  const setDefaultMeta = options.setDefaultMeta
+  const target = (context.container.argv._[1] as string) || 'all'
+  let pathIds: string[]
+
+  if (target === 'all') {
+    pathIds = collection.available
+  } else if (collection.items.has(target)) {
+    pathIds = [target]
+  } else {
+    const def = collection.getModelDefinition(target)
+    if (def) {
+      pathIds = collection.available.filter((id) =>
+        id.startsWith(def.prefix)
+      )
     } 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);
-      }
+      console.error(`Not found: "${target}"`)
+      process.exit(1)
     }
+  }
 
-    let valid = 0;
-    let invalid = 0;
+  let valid = 0
+  let invalid = 0
+  let updated = 0
 
-    for (const pathId of pathIds) {
-      const def = collection.findModelDefinition(pathId);
-      if (!def) continue;
+  for (const pathId of pathIds) {
+    const def = collection.findModelDefinition(pathId)
+    if (!def) continue
 
-      const doc = collection.document(pathId);
-      const result = validateDocument(doc, def);
+    const doc = collection.document(pathId)
 
-      if (result.valid) {
-        valid++;
-      } else {
-        invalid++;
-        console.log(`INVALID: ${pathId}`);
-        for (const error of result.errors) {
-          console.log(`  ${error.path.join(".")}: ${error.message}`);
+    if (setDefaultMeta && Object.keys(doc.meta).length === 0) {
+      const defaults = def.meta.parse({})
+      if (Object.keys(defaults).length > 0) {
+        const cleanDefaults: Record<string, unknown> = {}
+        for (const [k, v] of Object.entries(defaults)) {
+          if (v !== undefined) cleanDefaults[k] = v
+        }
+        if (Object.keys(cleanDefaults).length > 0) {
+          Object.assign(doc.meta, cleanDefaults)
+          await doc.save({ normalize: false })
+          updated++
+          console.log(`SET DEFAULTS: ${pathId}`)
         }
       }
     }
 
-    console.log();
-    console.log(
-      `Validated ${valid + invalid} documents: ${valid} valid, ${invalid} invalid`
-    );
+    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()
+  if (updated > 0) {
+    console.log(`Updated ${updated} document(s) with default meta.`)
+  }
+  console.log(
+    `Validated ${valid + invalid} documents: ${valid} valid, ${invalid} invalid`
+  )
+
+  if (invalid > 0) process.exit(1)
+}
+
+commands.register('validate', {
+  description: 'Validate documents against their model schemas',
+  help: `# cnotes validate
+
+Validate documents against their model schemas. Check frontmatter types, required fields, and optionally fill in missing defaults.
+
+## Usage
+
+\`\`\`
+cnotes validate [target] [options]
+\`\`\`
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| \`target\` | A path ID, model name, or \`all\` | \`all\` |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| \`--setDefaultMeta\` | Write Zod schema defaults to documents with empty frontmatter |
+| \`--contentFolder\` | Path to content folder |
+
+## Exit Codes
+
+- \`0\` — All documents valid
+- \`1\` — One or more validation errors
+
+## Examples
+
+\`\`\`bash
+# Validate everything
+cnotes validate
+
+# Validate a single document
+cnotes validate epics/auth-system
+
+# Validate all documents of a model
+cnotes validate Epic
+
+# Fill in missing defaults and validate
+cnotes validate all --setDefaultMeta
 
-    if (invalid > 0) process.exit(1);
-  },
-});
+# Validate a different content folder
+cnotes validate --contentFolder ./docs
+\`\`\`
+`,
+  argsSchema,
+  handler,
+})

package/src/cli/index.ts

@@ -1,20 +1,89 @@
 #!/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);
+import { commands } from './registry.js'
+
+// Side-effect imports register all commands
+import './commands/index.js'
+
+async function renderMarkdown(container: any, text: string) {
+  const ui = container.feature('ui')
+  console.log(ui.markdown(text))
+}
+
+async function main() {
+  // Dynamic import so the library stays luca-free; only the CLI pulls it in
+  const luca = await import('@soederpop/luca/node')
+  const container = luca.default
+
+  const commandName = container.argv._[0] as string | undefined
+  const wantsHelp = container.argv.help || container.argv.h
+
+  // Bare invocation or explicit "help" with no subcommand
+  if (!commandName || (commandName === 'help' && !container.argv._[1])) {
+    const help = commands.get('help')!
+    await help.handler({}, { container })
+    return
+  }
+
+  // `cnotes help <command>` — show that command's help
+  if (commandName === 'help' && container.argv._[1]) {
+    const target = container.argv._[1] as string
+    if (!commands.has(target)) {
+      console.error(`Unknown command: ${target}`)
+      console.error(`Run "cnotes help" to see available commands.\n`)
+      process.exit(1)
+    }
+    const def = commands.get(target)!
+    if (def.help) {
+      await renderMarkdown(container, def.help)
+    } else {
+      console.log(`${target} — ${def.description}\n`)
+      console.log(`No detailed help available for this command.`)
+    }
+    return
+  }
+
+  if (!commands.has(commandName)) {
+    console.error(`Unknown command: ${commandName}`)
+    console.error(`Run "cnotes help" to see available commands.\n`)
+    process.exit(1)
+  }
+
+  const def = commands.get(commandName)!
+
+  // `cnotes <command> --help` — show that command's help
+  if (wantsHelp) {
+    if (def.help) {
+      await renderMarkdown(container, def.help)
+    } else {
+      console.log(`${commandName} — ${def.description}\n`)
+      console.log(`No detailed help available for this command.`)
+    }
+    return
+  }
+
+  // Parse args from container.argv (minimist-parsed)
+  const { _: _positional, ...flags } = container.argv
+  let options = flags
+
+  if (def.argsSchema) {
+    const result = def.argsSchema.safeParse(flags)
+    if (!result.success) {
+      console.error(`Invalid options for "${commandName}":`)
+      for (const issue of result.error.issues) {
+        console.error(`  ${issue.path.join('.')}: ${issue.message}`)
+      }
+      if (def.help) {
+        console.error(`\nRun "cnotes ${commandName} --help" for usage information.`)
+      }
+      process.exit(1)
+    }
+    options = result.data
+  }
+
+  await def.handler(options, { container })
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})