contentbit 0.1.0 → 0.2.0

package/dist/commands/agents.d.ts

@@ -0,0 +1,11 @@
+import type { Io } from '../run.js';
+export interface AgentOptions {
+    /** Install Claude Code skills; defaults to detecting a .claude/ directory. */
+    claude?: boolean;
+    /** Manage the AGENTS.md block; defaults to true. */
+    agentsMd?: boolean;
+}
+/** Install or refresh the agent integration. Shared by `agents` and `init`. */
+export declare function installAgentIntegration(cwd: string, options: AgentOptions, io: Io): Promise<void>;
+export declare function agentsCommand(args: string[], io: Io): Promise<number>;
+//# sourceMappingURL=agents.d.ts.map

package/dist/commands/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AA2JnC,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,+EAA+E;AAC/E,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,EAAE,GACL,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB3E"}

package/dist/commands/agents.js

@@ -0,0 +1,197 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+// Everything here is static and project-independent by design: skills fetch
+// live data (authoring guide, stats, diagnostics) by running the CLI, so the
+// registry stays the single source of truth and nothing can drift. Bump the
+// frontmatter version when a template changes; `contentbit agents` re-runs
+// overwrite in place.
+const TEMPLATE_VERSION = 1;
+const AUTHOR_SKILL = `---
+name: contentbit-author
+description: |
+  Write or edit contentbit Markdown content (directive blocks like :::callout).
+  Use when asked to create or modify content documents in a project that uses
+  contentbit — blog posts, docs pages, changelogs, any Markdown covered by
+  \`contentbit validate\`.
+version: ${TEMPLATE_VERSION}
+---
+
+# Writing contentbit content
+
+contentbit documents are plain Markdown plus directive blocks
+(\`:::name{props} ... :::\`). Every block has a schema. Never guess block names,
+props, or body shapes — fetch the live guide from the project's registry first.
+
+## Find the project conventions
+
+Check \`package.json\` for a \`content:check\` script. It holds the canonical
+validate invocation for this project: the content glob and, if present, the
+\`--registry <path>\` flag pointing at custom block definitions. Reuse both
+below. No script? Default to \`content/**/*.md\` with no \`--registry\` flag.
+
+## The loop
+
+1. **Fetch the authoring guide** (always — it covers this project's custom blocks):
+
+   \`\`\`sh
+   contentbit instructions --audience llm [--registry <path from content:check>]
+   \`\`\`
+
+   Read it before writing. It documents every available block: props, body
+   shape, and when to use or avoid it.
+
+2. **Write the document.** Plain Markdown everywhere; blocks only where the
+   guide's use-when guidance fits. Keep frontmatter consistent with sibling
+   documents in the same folder.
+
+3. **Validate and fix until clean:**
+
+   \`\`\`sh
+   contentbit validate <file> [--registry <path>]
+   \`\`\`
+
+   Diagnostics print to stderr as \`file:line:col severity CODE message\`, often
+   with a \`hint:\` line suggesting the fix. Exit 0 means clean; exit 1 means
+   errors remain. Fix every diagnostic and re-run. Never finish with a failing
+   validate.
+
+## Failure modes
+
+- \`contentbit\` not found or no registry resolvable: the project is not set up.
+  Say so and suggest \`npx contentbit@latest init\` — do not invent block syntax.
+- A block you want does not exist: use plain Markdown, or ask whether to define
+  a custom block in the registry. Never emit an unregistered block name.
+`;
+const AUDIT_SKILL = `---
+name: contentbit-audit
+description: |
+  Audit contentbit Markdown content health using document stats. Use when asked
+  to audit, review, or find improvements across content — thin pages, missing
+  structure, validation issues — in a project that uses contentbit.
+version: ${TEMPLATE_VERSION}
+---
+
+# Auditing contentbit content
+
+\`contentbit stats\` analyzes documents and prints JSON to stdout. It is a read
+tool: it always exits 0, even when documents have validation errors.
+
+## Gather
+
+Check \`package.json\` for the \`content:check\` script to find this project's
+content glob and \`--registry\` flag, then:
+
+\`\`\`sh
+contentbit stats "content/**/*.md" [--registry <path>]
+\`\`\`
+
+One matched file prints a single stats object; multiple files print an array.
+Each entry includes the file path, frontmatter data, a heading \`outline\` with
+per-section word counts, \`blocks.byName\` usage counts, \`links.domains\`, and
+a \`validation\` summary (\`errors\`/\`warnings\`).
+
+## Interpret
+
+Prioritize findings in this order:
+
+1. **Validation errors and warnings** — broken content ships broken pages.
+2. **Thin documents** — outline sections with very low word counts.
+3. **Block-less documents** — \`blocks.byName\` empty where sibling documents
+   use blocks; structure (steps, callouts, comparisons, faq) may be missing.
+4. **Missing or inconsistent frontmatter** compared to sibling documents.
+5. **Structural imbalance** — skipped heading levels, single-section walls of text.
+
+## Report
+
+Report findings per file with concrete suggestions, ordered by priority. Do not
+edit files during the audit. To fix a finding, follow the contentbit-author
+skill (fetch the guide, edit, validate until clean) — offer that as a follow-up.
+`;
+const AGENTS_MD_BLOCK = `<!-- contentbit:start -->
+
+## contentbit content (generated — edits inside this block are overwritten)
+
+This project validates Markdown content with contentbit. Documents are plain
+Markdown plus directive blocks (\`:::name{props} ... :::\`), each with a schema.
+The \`content:check\` script in package.json holds the canonical validate
+command — the content glob and the \`--registry\` flag — reuse its arguments.
+
+When writing or editing content:
+
+1. Fetch the live authoring guide first — never guess block syntax:
+   \`contentbit instructions --audience llm [--registry <path>]\`
+2. Write plain Markdown; use blocks where the guide's use-when guidance fits.
+3. Validate until clean (exit 0): \`contentbit validate <file> [--registry <path>]\`.
+   Diagnostics print as \`file:line:col severity CODE message\` with fix hints.
+
+When auditing content health:
+
+- \`contentbit stats "content/**/*.md" [--registry <path>]\` prints JSON stats
+  and always exits 0: outline word counts, block usage, link domains, and
+  validation error/warning counts. Flag validation issues, thin documents, and
+  block-less pages first.
+
+If \`contentbit\` is unavailable, suggest \`npx contentbit@latest init\` instead
+of inventing block syntax.
+
+<!-- contentbit:end -->`;
+const START = '<!-- contentbit:start -->';
+const END = '<!-- contentbit:end -->';
+/** Insert or replace the fenced contentbit block, leaving the rest untouched. */
+function upsertBlock(existing) {
+    const start = existing.indexOf(START);
+    const end = existing.indexOf(END);
+    if (start !== -1 && end !== -1) {
+        return existing.slice(0, start) + AGENTS_MD_BLOCK + existing.slice(end + END.length);
+    }
+    if (existing.trim() === '')
+        return `${AGENTS_MD_BLOCK}\n`;
+    return `${existing.replace(/\n*$/, '\n\n')}${AGENTS_MD_BLOCK}\n`;
+}
+/** Install or refresh the agent integration. Shared by `agents` and `init`. */
+export async function installAgentIntegration(cwd, options, io) {
+    const claude = options.claude ?? existsSync(join(cwd, '.claude'));
+    const agentsMd = options.agentsMd ?? true;
+    if (agentsMd) {
+        const path = join(cwd, 'AGENTS.md');
+        let existing = '';
+        try {
+            existing = await readFile(path, 'utf8');
+        }
+        catch {
+            /* not there yet */
+        }
+        const created = existing === '';
+        await writeFile(path, upsertBlock(existing), 'utf8');
+        io.stdout(`${created ? 'created' : 'updated'}: AGENTS.md (contentbit block)`);
+    }
+    if (claude) {
+        const skills = [
+            ['contentbit-author', AUTHOR_SKILL],
+            ['contentbit-audit', AUDIT_SKILL],
+        ];
+        for (const [name, content] of skills) {
+            const dir = join(cwd, '.claude/skills', name);
+            await mkdir(dir, { recursive: true });
+            await writeFile(join(dir, 'SKILL.md'), content, 'utf8');
+            io.stdout(`installed: .claude/skills/${name}/SKILL.md`);
+        }
+    }
+}
+export async function agentsCommand(args, io) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            claude: { type: 'boolean', default: false },
+            'no-agents-md': { type: 'boolean', default: false },
+            cwd: { type: 'string', default: process.cwd() },
+        },
+    });
+    await installAgentIntegration(values.cwd, {
+        claude: values.claude || undefined, // false means "detect", not "skip"
+        agentsMd: !values['no-agents-md'],
+    }, io);
+    return 0;
+}

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAmGnC,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8GzE"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAgYnC,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAyNzE"}