contentbase 0.0.2 → 0.0.4

package/src/cli/commands/extract.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod'
+import picomatch from 'picomatch'
+import yaml from 'js-yaml'
+import { commands } from '../registry.js'
+import { loadCollection } from '../load-collection.js'
+import { stringifyAst } from '../../utils/stringify-ast.js'
+import type { Root, RootContent, Heading } from 'mdast'
+
+const argsSchema = z.object({
+  sections: z.string().optional(),
+  s: z.string().optional(),
+  title: z.string().optional(),
+  t: z.string().optional(),
+  frontmatter: z.boolean().default(false),
+  noNormalizeHeadings: z.boolean().default(false),
+  contentFolder: z.string().optional(),
+})
+
+async function handler(options: z.infer<typeof argsSchema>, context: { container: any }) {
+  const collection = await loadCollection({
+    contentFolder: options.contentFolder,
+  })
+
+  const target = context.container.argv._[1] as string | undefined
+  if (!target) {
+    console.error('Usage: cnotes extract <target> --sections "Section1,Section2"')
+    process.exit(1)
+  }
+
+  const sectionsArg = options.sections || options.s
+  if (!sectionsArg) {
+    console.error('--sections is required')
+    process.exit(1)
+  }
+
+  const sectionNames = sectionsArg
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  const includeFrontmatter = options.frontmatter
+  const noNormalize = options.noNormalizeHeadings
+  const title = options.title || options.t
+
+  const isMatch = picomatch(target)
+  const matchingIds = collection.available.filter((id) => isMatch(id))
+
+  if (matchingIds.length === 0) {
+    console.error(`No documents matched: ${target}`)
+    process.exit(1)
+  }
+
+  const allNodes: RootContent[] = []
+
+  if (title) {
+    allNodes.push({
+      type: 'heading',
+      depth: 1,
+      children: [{ type: 'text', value: title }],
+    } as Heading)
+  }
+
+  for (const id of matchingIds) {
+    const doc = collection.document(id)
+
+    if (includeFrontmatter && Object.keys(doc.meta).length > 0) {
+      allNodes.push({
+        type: 'yaml',
+        value: yaml.dump(doc.meta).trim(),
+      } as any)
+    }
+
+    const docNodes: RootContent[] = []
+
+    const titleNode = doc.nodes.firstHeading
+    if (titleNode) {
+      docNodes.push(titleNode as RootContent)
+    }
+
+    const leading = doc.nodes.leadingElementsAfterTitle
+    if (leading.length > 0) {
+      docNodes.push(...(leading as RootContent[]))
+    }
+
+    for (const name of sectionNames) {
+      try {
+        const sectionNodes = doc.extractSection(name)
+        if (sectionNodes.length > 0) {
+          docNodes.push(...(sectionNodes as RootContent[]))
+        }
+      } catch {
+        // Section not found — skip
+      }
+    }
+
+    if (!noNormalize && docNodes.length > 0) {
+      const headings = docNodes.filter(
+        (n): n is Heading => n.type === 'heading'
+      )
+      if (headings.length > 0) {
+        const minDepth = Math.min(...headings.map((h) => h.depth))
+        const targetDepth = title ? 2 : 1
+        const shift = targetDepth - minDepth
+        if (shift !== 0) {
+          for (const h of headings) {
+            h.depth = Math.max(1, Math.min(6, h.depth + shift)) as
+              | 1
+              | 2
+              | 3
+              | 4
+              | 5
+              | 6
+          }
+        }
+      }
+    }
+
+    allNodes.push(...docNodes)
+  }
+
+  const combinedAst: Root = { type: 'root', children: allNodes }
+  console.log(stringifyAst(combinedAst).trim())
+}
+
+commands.register('extract', {
+  description: 'Extract specific sections from documents',
+  help: `# cnotes extract
+
+Extract specific sections from one or more documents. Supports glob patterns for matching multiple documents and outputs clean markdown with normalized headings.
+
+## Usage
+
+\`\`\`
+cnotes extract <target> --sections "Section1,Section2" [options]
+\`\`\`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| \`target\` | Path ID or glob pattern (e.g. \`epics/*\`, \`tasks/auth-*\`) |
+
+## Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| \`--sections\` | \`-s\` | **Required.** Comma-separated section headings to extract |
+| \`--title\` | \`-t\` | Add a top-level H1 title to the output |
+| \`--frontmatter\` | | Include YAML frontmatter in the output |
+| \`--noNormalizeHeadings\` | | Skip heading depth normalization |
+| \`--contentFolder\` | | Path to content folder |
+
+## Heading Normalization
+
+By default, extracted headings are re-leveled so the output starts at H1 (or H2 when \`--title\` is used). Use \`--noNormalizeHeadings\` to preserve original depths.
+
+## Examples
+
+\`\`\`bash
+# Extract Overview from a single document
+cnotes extract epics/auth-system --sections "Overview"
+
+# Extract multiple sections
+cnotes extract tasks/login-bug -s "Overview,Requirements,Acceptance Criteria"
+
+# Extract from all epics with a title wrapper
+cnotes extract "epics/*" -s "Overview" -t "Epic Summaries"
+
+# Include frontmatter in output
+cnotes extract epics/auth-system -s "Overview" --frontmatter
+\`\`\`
+`,
+  argsSchema,
+  handler,
+})

package/src/cli/commands/help.ts

@@ -0,0 +1,81 @@
+import { commands } from '../registry.js'
+
+async function handler(_options: any, context: { container: any }) {
+  const ui = context.container.feature('ui')
+
+  const lines: string[] = [
+    '# cnotes',
+    '',
+    'An ORM for structured Markdown/MDX files.',
+    '',
+    '## Usage',
+    '',
+    '```',
+    'cnotes <command> [options]',
+    '```',
+    '',
+    '## Commands',
+    '',
+    '| Command | Description |',
+    '|---------|-------------|',
+  ]
+
+  for (const name of commands.available) {
+    const def = commands.get(name)!
+    lines.push(`| \`${name}\` | ${def.description} |`)
+  }
+
+  lines.push(
+    '',
+    '## Global Options',
+    '',
+    '| Option | Description |',
+    '|--------|-------------|',
+    '| `--help`, `-h` | Show help for a command |',
+    '| `--contentFolder` | Path to content folder (most commands) |',
+    '',
+    '## Getting Help',
+    '',
+    '```bash',
+    '# Show this overview',
+    'cnotes help',
+    '',
+    '# Show detailed help for a command',
+    'cnotes help serve',
+    'cnotes serve --help',
+    '```',
+  )
+
+  console.log(ui.markdown(lines.join('\n')))
+}
+
+commands.register('help', {
+  description: 'Show available commands',
+  help: `# cnotes help
+
+Show available commands and usage information.
+
+## Usage
+
+\`\`\`
+cnotes help [command]
+\`\`\`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| \`command\` | Show detailed help for a specific command |
+
+## Examples
+
+\`\`\`bash
+# Show all commands
+cnotes help
+
+# Show help for the serve command
+cnotes help serve
+\`\`\`
+`,
+  handler,
+})

package/src/cli/commands/index.ts

@@ -0,0 +1,17 @@
+// Side-effect imports register each command
+import './init.js'
+import './create.js'
+import './inspect.js'
+import './validate.js'
+import './export.js'
+import './action.js'
+import './summary.js'
+import './teach.js'
+import './extract.js'
+import './mcp.js'
+import './serve.js'
+import './console.js'
+import './help.js'
+import './text-search.js'
+import './search.js'
+import './embed.js'

package/src/cli/commands/init.ts

@@ -1,30 +1,17 @@
-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";
+import fs from 'fs/promises'
+import path from 'path'
+import { commands } from '../registry.js'
+
+async function handler(_options: any, context: { container: any }) {
+  const name = (context.container.argv._[1] 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 })
+
+  await fs.writeFile(
+    path.join(dir, 'models.ts'),
+    `import { defineModel, z } from "contentbase";
 
 export const Post = defineModel("Post", {
   prefix: "posts",
@@ -34,13 +21,12 @@ export const Post = defineModel("Post", {
   }),
 });
 `,
-      "utf8"
-    );
+    'utf8'
+  )
 
-    // Create a sample post
-    await fs.writeFile(
-      path.join(dir, "posts", "hello-world.mdx"),
-      `---
+  await fs.writeFile(
+    path.join(dir, 'posts', 'hello-world.md'),
+    `---
 status: draft
 author: me
 ---
@@ -49,13 +35,12 @@ author: me
 
 Welcome to your contentbase project!
 `,
-      "utf8"
-    );
+    'utf8'
+  )
 
-    // Create index.ts
-    await fs.writeFile(
-      path.join(dir, "index.ts"),
-      `import { Collection } from "contentbase";
+  await fs.writeFile(
+    path.join(dir, 'index.ts'),
+    `import { Collection } from "contentbase";
 import { Post } from "./models";
 
 export const collection = new Collection({
@@ -64,12 +49,51 @@ export const collection = new Collection({
 
 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`);
-  },
-});
+    'utf8'
+  )
+
+  console.log(`Created contentbase project at ${dir}`)
+  console.log(`  ${name}/models.ts`)
+  console.log(`  ${name}/index.ts`)
+  console.log(`  ${name}/posts/hello-world.md`)
+}
+
+commands.register('init', {
+  description: 'Initialize a new contentbase project',
+  help: `# cnotes init
+
+Scaffold a new contentbase project with a sample model and document.
+
+## Usage
+
+\`\`\`
+cnotes init [name]
+\`\`\`
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| \`name\` | Directory name for the project | \`my-content\` |
+
+## What It Creates
+
+- \`<name>/models.ts\` — Model definitions with a sample Post model
+- \`<name>/index.ts\` — Collection entry point
+- \`<name>/posts/hello-world.md\` — Sample document
+
+## Examples
+
+\`\`\`bash
+# Create with default name
+cnotes init
+
+# Create with custom name
+cnotes init docs
+
+# Create in a subdirectory
+cnotes init content/blog
+\`\`\`
+`,
+  handler,
+})

package/src/cli/commands/inspect.ts

@@ -1,46 +1,56 @@
-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(", ")}`);
-    }
-  },
-});
+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>) {
+  const collection = await loadCollection({
+    contentFolder: options.contentFolder,
+  })
+
+  console.log(collection.generateModelSummary())
+}
+
+commands.register('inspect', {
+  description: 'Display collection info and registered models',
+  help: `# cnotes inspect
+
+Display a summary of the collection: registered models, their fields, sections, relationships, and document counts.
+
+## Usage
+
+\`\`\`
+cnotes inspect [options]
+\`\`\`
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| \`--contentFolder\` | Path to content folder |
+
+## Output
+
+Shows for each model:
+- Prefix and document count
+- Meta field definitions (name, type, required, default)
+- Section headings
+- Relationships (belongsTo, hasMany)
+- Computed properties and named scopes
+
+## Examples
+
+\`\`\`bash
+# Inspect current directory's collection
+cnotes inspect
+
+# Inspect a specific content folder
+cnotes inspect --contentFolder test/fixtures/sdlc
+\`\`\`
+`,
+  argsSchema,
+  handler,
+})