contentbit 0.1.0 → 0.1.1

package/dist/commands/init.js

@@ -1,32 +1,80 @@
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { loadRegistry } from '../load-registry.js';
 const TARGETS = ['react', 'html', 'markdown'];
-const REGISTRY_TEMPLATE = `// Custom blocks for this project. The CLI and your app share this module:
+/** Markdown library choices per target; the first entry is the default. */
+const MD_CHOICES = {
+    react: ['react-markdown', 'none'],
+    html: ['marked', 'markdown-it', 'none'],
+    markdown: ['none'],
+};
+const REGISTRY_TEMPLATE = `// Custom block definitions for this project. The CLI and your app share
+// this module — Node 22.18+ imports TypeScript directly:
 //
-//   contentbit validate "content/**/*.md" --registry ./blocks/registry.mjs
+//   contentbit validate "content/**/*.md" --registry ./blocks/registry.ts
 //
-// Define blocks with @contentbit/core and default-export them as an array.
+// Definitions stay framework-free (the CLI and every render target use
+// them); React components live next door in blocks/components.tsx.
 // Docs: https://contentbit.dev/docs/guides/custom-blocks
-//
-// import { defineBlock, pipeRows } from '@contentbit/core'
-// import { z } from 'zod'
-//
-// const pricingTable = defineBlock({
-//   name: 'pricing-table',
-//   description: 'Compares product plans.',
-//   props: z.object({ currency: z.enum(['usd', 'eur']).default('usd') }),
-//   content: pipeRows({ columns: ['plan', 'price'], minRows: 2 }),
-//   authoring: {
-//     useWhen: ['Comparing pricing plans'],
-//     example: ':::pricing-table\\n- Starter | $0\\n- Pro | $12/mo\\n:::',
-//   },
-// })
-
-export default []
+import { defineBlock, markdownBody, type BlockDefinition } from '@contentbit/core'
+import { z } from 'zod'
+
+export const quote = defineBlock({
+  name: 'quote',
+  description: 'A pull quote with an author.',
+  props: z.object({
+    author: z.string().min(1),
+    role: z.string().optional(),
+  }),
+  content: markdownBody({ minLength: 3 }),
+  authoring: {
+    useWhen: ['Quoting a person to support a point'],
+    avoidWhen: ['Highlighting your own remark, use callout instead'],
+    example: ':::quote{author="Ada Lovelace"}\\nThe Analytical Engine weaves algebraic patterns.\\n:::',
+  },
+})
+
+export default [quote] satisfies BlockDefinition<unknown>[]
+`;
+/** blocks/components.tsx — React components for custom blocks, next to their definitions. */
+function blockComponentsTemplate(styled) {
+    const body = styled
+        ? `  return (
+    <figure className="my-6 border-s-2 ps-4">
+      <blockquote className="text-lg italic">{ctx.renderMarkdown(data.markdown)}</blockquote>
+      <figcaption className="text-muted-foreground mt-2 text-sm">
+        — {String(node.props.author)}
+        {node.props.role ? \`, \${String(node.props.role)}\` : null}
+      </figcaption>
+    </figure>
+  )`
+        : `  return (
+    <figure style={{ margin: '1.5rem 0', borderLeft: '2px solid #d4d4d4', paddingLeft: '1rem' }}>
+      <blockquote style={{ fontStyle: 'italic' }}>{ctx.renderMarkdown(data.markdown)}</blockquote>
+      <figcaption style={{ marginTop: '0.5rem', fontSize: '0.875rem', opacity: 0.7 }}>
+        — {String(node.props.author)}
+        {node.props.role ? \`, \${String(node.props.role)}\` : null}
+      </figcaption>
+    </figure>
+  )`;
+    return `import type { BlockComponent, BlockComponentProps } from '@contentbit/react'
+
+// One React component per custom block, keyed by block name. Definitions
+// live in ./registry.ts — add a block there, add its component here, and
+// the rest of the app never changes.
+function QuoteBlock({ node, ctx }: BlockComponentProps) {
+  const data = node.data as { markdown: string }
+${body}
+}
+
+export const blockComponents: Record<string, BlockComponent> = {
+  quote: QuoteBlock,
+}
 `;
+}
 const EXAMPLE_CONTENT = `# Hello, Content Blocks
 
 Regular Markdown works everywhere. Blocks add validated structure:
@@ -40,26 +88,144 @@ Run the validate script and you will get file:line:col diagnostics.
 2. Run \`contentbit validate "content/**/*.md"\`.
 3. Render it with the target you picked at init.
 :::
+
+This one is a **custom block**, defined in \`blocks/registry.ts\` and rendered
+by the \`QuoteBlock\` component, in about twenty lines:
+
+:::quote{author="Ada Lovelace" role="Notes on the Analytical Engine, 1843"}
+The Analytical Engine weaves algebraic patterns just as the Jacquard loom
+weaves flowers and leaves.
+:::
 `;
-const REACT_COMPONENT = `import { genericBlocks } from '@contentbit/blocks'
+/** The wrapper component: styled pack or headless, with or without a Markdown lib. */
+function reactComponent(styled, mdWired, blocksImport) {
+    const mdImport = mdWired ? "import ReactMarkdown from 'react-markdown'\n" : '';
+    const mdProp = mdWired
+        ? '\n      renderMarkdown={(md) => <ReactMarkdown>{md}</ReactMarkdown>}'
+        : `\n      // TODO: plug your Markdown library in here, e.g. react-markdown.
+      // One function renders all prose: https://contentbit.dev/docs/guides/markdown
+      // renderMarkdown={(md) => <Markdown source={md} />}`;
+    const rendererImport = styled
+        ? `\n// The styled pack installed by shadcn. Yours to edit.
+import { ContentRenderer } from '@/components/content-blocks/content-renderer'`
+        : '';
+    const renderer = styled ? 'ContentRenderer' : 'ContentBlocks';
+    const reactImport = styled ? '' : "import { ContentBlocks } from '@contentbit/react'\n";
+    return `'use client'
+
+import { genericBlocks } from '@contentbit/blocks'
 import { createBlockRegistry, parseDocument, validateDocument } from '@contentbit/core'
-import { ContentBlocks } from '@contentbit/react'
+${reactImport}${mdImport}${rendererImport}
+// Everything block-related lives in the blocks/ folder: definitions in
+// registry.ts (shared with the validate CLI), components in components.tsx.
+import customBlocks from '${blocksImport}/registry'
+import { blockComponents } from '${blocksImport}/components'
 
-const registry = createBlockRegistry().use(genericBlocks())
+const registry = createBlockRegistry().use(genericBlocks()).use(customBlocks)
 
 export function Content({ source }: { source: string }) {
   const result = validateDocument(parseDocument(source), registry)
   return (
-    <ContentBlocks
+    <${renderer}
       document={result.document}
-      // TODO: plug your Markdown library in here, e.g. react-markdown.
-      // One function renders all prose: https://contentbit.dev/docs/guides/markdown
-      // renderMarkdown={(md) => <Markdown source={md} />}
+      components={blockComponents}${mdProp}
     />
   )
 }
 `;
-function detectPackageManager() {
+}
+function htmlRenderScript(md) {
+    const wiring = md === 'marked'
+        ? `import { marked } from 'marked'
+
+const renderMarkdown = (md) => marked.parse(md, { async: false })`
+        : md === 'markdown-it'
+            ? `import MarkdownIt from 'markdown-it'
+
+const mdIt = new MarkdownIt() // html: false by default — raw HTML stays escaped
+const renderMarkdown = (md) => mdIt.render(md)`
+            : `// TODO: plug a Markdown library in here (marked, markdown-it, remark).
+const renderMarkdown = undefined`;
+    return `// Render content/example.md to example.html. Run: node scripts/render-example.mjs
+import { genericBlocks } from '@contentbit/blocks'
+import { createBlockRegistry, parseDocument, validateDocument } from '@contentbit/core'
+import { renderToHtml } from '@contentbit/html'
+import { readFile, writeFile } from 'node:fs/promises'
+${wiring}
+
+const source = await readFile('content/example.md', 'utf8')
+const registry = createBlockRegistry().use(genericBlocks())
+const result = validateDocument(parseDocument(source), registry)
+const html = renderToHtml(result.document, { renderMarkdown })
+await writeFile('example.html', html, 'utf8')
+console.log('wrote example.html')
+`;
+}
+/** Where the component and example page belong for the detected framework. */
+function detectFramework(cwd, deps) {
+    if ((deps['@tanstack/react-start'] || deps['@tanstack/react-router']) &&
+        existsSync(join(cwd, 'src/routes'))) {
+        return {
+            framework: 'tanstack',
+            componentPath: 'src/components/content-blocks.tsx',
+            pagePath: 'src/routes/example.tsx',
+        };
+    }
+    if (deps.next) {
+        const appDir = existsSync(join(cwd, 'src/app')) ? 'src/app' : 'app';
+        if (existsSync(join(cwd, appDir))) {
+            return {
+                framework: 'next',
+                componentPath: 'components/content-blocks.tsx',
+                pagePath: `${appDir}/example/page.tsx`,
+            };
+        }
+    }
+    return { framework: null, componentPath: 'components/content-blocks.tsx', pagePath: null };
+}
+const TANSTACK_PAGE = `import { createFileRoute } from '@tanstack/react-router'
+
+import { Content } from '../components/content-blocks'
+// Vite's ?raw import inlines the Markdown as a string at build time.
+import source from '../../content/example.md?raw'
+
+export const Route = createFileRoute('/example')({ component: ExamplePage })
+
+function ExamplePage() {
+  return (
+    <main style={{ maxWidth: '42rem', margin: '0 auto', padding: '3rem 1.5rem' }}>
+      <Content source={source} />
+    </main>
+  )
+}
+`;
+const NEXT_PAGE = `import { readFile } from 'node:fs/promises'
+
+// If your project has no "@/" path alias, switch to a relative import.
+import { Content } from '@/components/content-blocks'
+
+export default async function ExamplePage() {
+  const source = await readFile('content/example.md', 'utf8')
+  return (
+    <main style={{ maxWidth: '42rem', margin: '0 auto', padding: '3rem 1.5rem' }}>
+      <Content source={source} />
+    </main>
+  )
+}
+`;
+function detectPackageManager(cwd) {
+    // The project's lockfile outranks however the CLI itself was launched.
+    const locks = [
+        ['pnpm-lock.yaml', 'pnpm'],
+        ['yarn.lock', 'yarn'],
+        ['bun.lock', 'bun'],
+        ['bun.lockb', 'bun'],
+        ['package-lock.json', 'npm'],
+    ];
+    for (const [file, pm] of locks) {
+        if (existsSync(join(cwd, file)))
+            return pm;
+    }
     const agent = process.env.npm_config_user_agent ?? '';
     for (const pm of ['pnpm', 'yarn', 'bun']) {
         if (agent.startsWith(pm))
@@ -71,6 +237,15 @@ function installArgs(pm, dev, pkgs) {
     const add = pm === 'npm' ? 'install' : 'add';
     return dev ? [add, '-D', ...pkgs] : [add, ...pkgs];
 }
+function dlxCommand(pm) {
+    if (pm === 'pnpm')
+        return ['pnpm', ['dlx']];
+    if (pm === 'yarn')
+        return ['yarn', ['dlx']];
+    if (pm === 'bun')
+        return ['bunx', []];
+    return ['npx', ['--yes']];
+}
 function runInstall(pm, args, cwd) {
     return new Promise((resolve) => {
         const child = spawn(pm, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
@@ -95,9 +270,12 @@ export async function initCommand(args, io) {
         args,
         options: {
             target: { type: 'string', short: 't' },
+            md: { type: 'string' },
             yes: { type: 'boolean', short: 'y', default: false },
             cwd: { type: 'string', default: process.cwd() },
             'no-install': { type: 'boolean', default: false },
+            'no-page': { type: 'boolean', default: false },
+            'no-styled': { type: 'boolean', default: false },
         },
     });
     const cwd = values.cwd;
@@ -140,17 +318,48 @@ export async function initCommand(args, io) {
     else {
         target = detected;
     }
+    // Resolve the Markdown library: flag > prompt (interactive) > target default.
+    // The default gives working prose rendering out of the box; 'none' opts out.
+    const choices = MD_CHOICES[target];
+    let md;
+    if (values.md) {
+        if (!choices.includes(values.md)) {
+            io.stderr(`Unknown markdown library "${values.md}". Use one of: ${choices.join(', ')}`);
+            return 2;
+        }
+        md = values.md;
+    }
+    else if (choices.length > 1 && !values.yes && process.stdin.isTTY && process.stdout.isTTY) {
+        const { isCancel, select } = await import('@clack/prompts');
+        const answer = await select({
+            message: 'Markdown library for prose rendering?',
+            initialValue: choices[0],
+            options: choices.map((c) => ({
+                value: c,
+                label: c,
+                hint: c === 'none' ? 'wire one yourself later' : 'installed and wired for you',
+            })),
+        });
+        if (isCancel(answer))
+            return 1;
+        md = answer;
+    }
+    else {
+        md = choices[0];
+    }
     // Install runtime packages plus the CLI as a dev dependency.
-    const runtime = ['@contentbit/core', '@contentbit/blocks'];
+    const runtime = ['@contentbit/core', '@contentbit/blocks', 'zod'];
     if (target === 'react')
         runtime.push('@contentbit/react');
     if (target === 'html')
         runtime.push('@contentbit/html');
+    if (md !== 'none')
+        runtime.push(md);
     if (values['no-install']) {
         io.stdout(`skipped install: ${runtime.join(' ')} + contentbit (dev)`);
     }
     else {
-        const pm = detectPackageManager();
+        const pm = detectPackageManager(cwd);
         io.stdout(`installing with ${pm}: ${runtime.join(' ')}`);
         if ((await runInstall(pm, installArgs(pm, false, runtime), cwd)) !== 0) {
             io.stderr('install failed');
@@ -163,11 +372,54 @@ export async function initCommand(args, io) {
     }
     // Scaffold project files; never overwrite.
     const files = [
-        ['blocks/registry.mjs', REGISTRY_TEMPLATE],
+        ['blocks/registry.ts', REGISTRY_TEMPLATE],
         ['content/example.md', EXAMPLE_CONTENT],
     ];
-    if (target === 'react')
-        files.push(['components/content-blocks.tsx', REACT_COMPONENT]);
+    const layout = detectFramework(cwd, { ...pkg.dependencies, ...pkg.devDependencies });
+    // shadcn project? Pull the styled component pack from the contentbit registry.
+    let styled = false;
+    const componentsJsonPath = join(cwd, 'components.json');
+    if (target === 'react' && !values['no-styled'] && existsSync(componentsJsonPath)) {
+        const componentsJson = JSON.parse(await readFile(componentsJsonPath, 'utf8'));
+        componentsJson.registries ??= {};
+        if (!componentsJson.registries['@contentbit']) {
+            componentsJson.registries['@contentbit'] = 'https://contentbit.dev/r/{name}.json';
+            await writeFile(componentsJsonPath, `${JSON.stringify(componentsJson, null, 2)}\n`, 'utf8');
+            io.stdout('added @contentbit registry to components.json');
+        }
+        if (values['no-install']) {
+            io.stdout('skipped: shadcn add @contentbit/generic-pack');
+            styled = true;
+        }
+        else {
+            const [bin, prefix] = dlxCommand(detectPackageManager(cwd));
+            io.stdout('installing the styled pack: shadcn add @contentbit/generic-pack');
+            const code = await runInstall(bin, [...prefix, 'shadcn@latest', 'add', '@contentbit/generic-pack', '--yes'], cwd);
+            if (code === 0)
+                styled = true;
+            else
+                io.stderr('styled pack install failed; falling back to headless defaults');
+        }
+    }
+    if (target === 'react') {
+        const depth = layout.componentPath.split('/').length - 1;
+        const blocksImport = `${'../'.repeat(depth)}blocks`;
+        files.push(['blocks/components.tsx', blockComponentsTemplate(styled)]);
+        files.push([
+            layout.componentPath,
+            reactComponent(styled, md === 'react-markdown', blocksImport),
+        ]);
+        // A visible page in the framework's own routing convention.
+        if (!values['no-page'] && layout.pagePath) {
+            files.push([layout.pagePath, layout.framework === 'tanstack' ? TANSTACK_PAGE : NEXT_PAGE]);
+        }
+    }
+    if (target === 'html') {
+        files.push([
+            'scripts/render-example.mjs',
+            htmlRenderScript(md),
+        ]);
+    }
     for (const [rel, content] of files) {
         const result = await scaffold(join(cwd, rel), content);
         io.stdout(`${result}: ${rel}`);
@@ -177,24 +429,37 @@ export async function initCommand(args, io) {
     fresh.scripts ??= {};
     if (!fresh.scripts['content:check']) {
         fresh.scripts['content:check'] =
-            'contentbit validate "content/**/*.md" --registry ./blocks/registry.mjs';
+            'contentbit validate "content/**/*.md" --registry ./blocks/registry.ts';
         await writeFile(pkgPath, `${JSON.stringify(fresh, null, 2)}\n`, 'utf8');
         io.stdout('added script: content:check');
     }
     // Generate the LLM authoring guide from the registry, ready to paste into a prompt.
-    const registry = await loadRegistry();
+    let registry;
+    try {
+        // Include the scaffolded custom blocks so the guide covers them too.
+        registry = await loadRegistry(join(cwd, 'blocks/registry.ts'));
+    }
+    catch {
+        registry = await loadRegistry(); // packages not installed yet (--no-install)
+    }
     const guide = registry.toAuthoringGuide({ audience: 'llm', includeExamples: true });
     await writeFile(join(cwd, 'contentbit-guide.md'), guide, 'utf8');
     io.stdout('created: contentbit-guide.md (LLM authoring instructions)');
     io.stdout('');
     io.stdout('Done. Next steps:');
-    io.stdout(`  1. Validate the starter content: ${detectPackageManager()} run content:check`);
+    io.stdout(`  1. Validate the starter content: ${detectPackageManager(cwd)} run content:check`);
     if (target === 'react') {
-        io.stdout('  2. Render it: import { Content } from "./components/content-blocks"');
+        if (!values['no-page'] && layout.pagePath) {
+            io.stdout('  2. Start the dev server and open /example to see the article rendered.');
+        }
+        else {
+            io.stdout('  2. Render it: import { Content } from "./components/content-blocks"');
+            io.stdout('     <Content source={...content/example.md as a string} />');
+        }
         io.stdout('  3. Styled components: pnpm dlx shadcn@latest add @contentbit/generic-pack');
     }
     else if (target === 'html') {
-        io.stdout('  2. Render it: contentbit render content/example.md --target html');
+        io.stdout('  2. Render it: node scripts/render-example.mjs && open example.html');
     }
     else {
         io.stdout('  2. Render it: contentbit render content/example.md --target markdown');

package/dist/load-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-registry.d.ts","sourceRoot":"","sources":["../src/load-registry.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAGhG,+EAA+E;AAC/E,wBAAsB,YAAY,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAchF"}
+{"version":3,"file":"load-registry.d.ts","sourceRoot":"","sources":["../src/load-registry.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAGhG,+EAA+E;AAC/E,wBAAsB,YAAY,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAsBhF"}

package/dist/load-registry.js

@@ -5,7 +5,16 @@ import { pathToFileURL } from 'node:url';
 export async function loadRegistry(registryPath) {
     const registry = createBlockRegistry().use(genericBlocks());
     if (registryPath) {
-        const mod = (await import(pathToFileURL(registryPath).href));
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(registryPath).href));
+        }
+        catch (err) {
+            if (err instanceof Error && 'code' in err && err.code === 'ERR_UNKNOWN_FILE_EXTENSION') {
+                throw new Error(`Importing a TypeScript registry needs Node 22.18+ (native type stripping): ${registryPath}`);
+            }
+            throw err;
+        }
         if (!Array.isArray(mod.default)) {
             throw new Error(`--registry module must default-export an array of block definitions: ${registryPath}`);
         }

package/dist/run.d.ts

@@ -3,6 +3,6 @@ export interface Io {
     stderr(line: string): void;
     writeFile(path: string, content: string): Promise<void>;
 }
-export declare const USAGE = "Usage: contentbit <init|validate|render|instructions|docs> [options]\n\n  init [-t react|html|markdown] [-y] [--no-install]\n\n  validate <globs...> [--registry <module.mjs>] [--strict-warnings]\n  render <file> --target html|markdown [--registry <module.mjs>] [--out <file>]\n  instructions [--audience llm|human] [--no-examples] [--registry <module.mjs>] [--out <file>]\n  docs [--registry <module.mjs>] [--out <file>]";
+export declare const USAGE = "Usage: contentbit <init|validate|render|instructions|docs> [options]\n\n  init [-t react|html|markdown] [--md ...] [-y] [--no-install] [--no-page]\n\n  validate <globs...> [--registry <module.mjs>] [--strict-warnings]\n  render <file> --target html|markdown [--registry <module.mjs>] [--out <file>]\n  instructions [--audience llm|human] [--no-examples] [--registry <module.mjs>] [--out <file>]\n  docs [--registry <module.mjs>] [--out <file>]";
 export declare function run(argv: string[], io: Io): Promise<number>;
 //# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,EAAE;IACjB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxD;AAED,eAAO,MAAM,KAAK,yaAO8B,CAAA;AAYhD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAcjE"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,EAAE;IACjB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxD;AAED,eAAO,MAAM,KAAK,gcAO8B,CAAA;AAYhD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAcjE"}