@bendyline/docblocks-cli 1.1.2 → 2.0.0

package/README.md

@@ -1,121 +1,93 @@
 # @bendyline/docblocks-cli
 
-DocBlocks CLI — build, serve, convert, and manage markdown document projects from the command line.
+The DocBlocks command-line surface for document build and preview, linked-Squisq
+format conversion, MP4 rendering, document parsing, and a local MCP server for
+agents.
 
 ## Installation
 
-```bash
-npm install -g @bendyline/docblocks-cli
-```
-
-## Commands
-
-### `docblocks init [dir]`
-
-Initialize a new DocBlocks workspace. Creates a `.docblocks` directory with configuration.
-
-### `docblocks build`
-
-Build markdown files into HTML output.
+Node.js 22.14 or newer is required.
 
 ```bash
-docblocks build -i ./docs -o ./dist
+npm install -g @bendyline/docblocks-cli
+docblocks --help
 ```
 
-**Options:**
-
-- `-i, --input <dir>` — Input directory (default: `.`)
-- `-o, --output <dir>` — Output directory (default: `dist`)
-- `-t, --theme <id>` — Visual theme to apply
+## Documentation
 
-### `docblocks serve`
+- [Authoritative CLI reference](https://github.com/bendyline/docblocks/blob/main/docs/cli.md)
+- [MCP architecture and protocol guide](https://github.com/bendyline/docblocks/blob/main/docs/mcp.md)
 
-Start a local development server for previewing documents.
+Those guides describe current input support, linked Squisq ownership, format
+directions, overwrite behavior, MCP authority, artifact lifecycle, and assurance.
 
-**Options:**
+## Commands
 
-- `-p, --port <port>` — Port to listen on (default: `3000`)
-- `-d, --dir <dir>` — Directory to serve (default: `.`)
-- `-t, --theme <id>` — Visual theme to apply
+| Command                            | Purpose                                               |
+| ---------------------------------- | ----------------------------------------------------- |
+| `docblocks init [dir]`             | Create minimal `.docblocks/config.json` metadata.     |
+| `docblocks build`                  | Recursively build Markdown into standalone HTML.      |
+| `docblocks serve`                  | Run a constrained local preview server.               |
+| `docblocks convert <input>`        | Convert through the linked Squisq registry.           |
+| `docblocks video <input> [output]` | Render a configurable MP4.                            |
+| `docblocks mcp`                    | Start the artifact-first MCP server over local stdio. |
+| `docblocks themes`                 | List linked Squisq theme IDs.                         |
+| `docblocks transforms`             | List linked Squisq transform IDs.                     |
+| `docblocks parse <input>`          | Parse UTF-8 Markdown into Squisq Markdown AST JSON.   |
 
-### `docblocks convert <input>`
+Use `docblocks help <command>` for the installed option summary.
 
-Convert a markdown document to DOCX, PPTX, PDF, HTML, or DBK container format. `<input>` can be a `.md` file, a `.zip`/`.dbk` container, or a folder.
+## Examples
 
 ```bash
-# Convert to all formats
-docblocks convert story.md
-
-# Convert to specific formats with a theme
-docblocks convert story.md -f docx,pdf -t cinematic
-
-# Apply a transform style before exporting
-docblocks convert story.md --transform documentary -o ./output
-```
-
-**Options:**
+# Build and preview Markdown
+docblocks build --input ./docs --output ./dist
+docblocks serve --dir ./docs
 
-- `-o, --output-dir <dir>` — Output directory
-- `-f, --formats <list>` — Comma-separated formats: docx, pptx, pdf, html, dbk
-- `-t, --theme <id>` — Visual theme (use `docblocks themes` to list)
-- `--transform <style>` — Transform style (use `docblocks transforms` to list)
-
-### `docblocks video <input> [output]`
+# The no-flag conversion set is exactly DOCX, PPTX, PDF, HTML, and DBK
+docblocks convert story.md
 
-Render a document to MP4 video with synced animations. Requires ffmpeg and Playwright. `<input>` can be a `.md` file, a `.zip`/`.dbk` container, or a folder.
+# Select any export-capable linked-registry formats
+docblocks convert report.docx --formats md,pdf,pptx --output-dir ./exports
 
-```bash
+# Render MP4 with explicit media controls
 docblocks video story.md --quality high --orientation portrait
-```
 
-**Options:**
+# Discover authoring vocabulary from linked Squisq
+docblocks themes
+docblocks transforms
 
-- `-o, --output <path>` — Output MP4 path
-- `--fps <number>` — Frames per second (1-120, default: 30)
-- `--quality <level>` — draft, normal, or high
-- `--orientation <orient>` — landscape or portrait
-- `--captions <style>` — off, standard, or social
-- `--width <pixels>` / `--height <pixels>` — Override dimensions
-
-### `docblocks mcp`
-
-Start an MCP (Model Context Protocol) server over stdio for AI-assisted document operations.
-
-```bash
+# Start MCP with no filesystem authority
 docblocks mcp
-```
-
-**MCP Tools exposed:**
-
-- `export_markdown_to_docx` / `_pdf` / `_pptx` / `_html` / `_video` — Export markdown to polished output formats
-- `analyze_markdown` — Extract content structure (stats, quotes, facts, dates)
-- `restyle_markdown` — Apply a transform style and return restyled markdown
-- `list_themes` / `list_transform_styles` / `list_export_formats` — Discovery tools
-
-All export tools accept raw markdown text directly — AI agents can write content and immediately export without temp files.
 
-**Claude Desktop / Copilot integration:**
-
-```json
-{
-  "mcpServers": {
-    "docblocks": { "command": "npx", "args": ["docblocks", "mcp"] }
-  }
-}
+# Grant independent roots when an agent needs files or durable output
+docblocks mcp --allow-read ./documents --allow-write ./exports
 ```
 
-### `docblocks themes`
-
-List all available visual themes.
+`convert` and `video` accept Markdown, Squisq JSON Doc, DBK/ZIP, folders, and
+import-capable linked-registry formats. Direct `build`, `convert`, and `video`
+outputs replace existing destination files. MCP conversions instead return
+immutable session artifacts; only explicit `save_artifact` materializes one, using
+no-replace or hash-conditional replacement semantics.
 
-### `docblocks transforms`
+The live linked registry currently covers Markdown, DOCX, PDF, PPTX, XLSX, CSV,
+HTML, HTML ZIP, EPUB, DBK, MP4, and GIF. Direction varies by format, so use the
+CLI reference or MCP `list_formats` rather than assuming every format imports.
 
-List all available transform styles.
+MP4/GIF rendering requires Chromium and FFmpeg. Install Chromium with
+`npx playwright install chromium`; Squisq resolves FFmpeg from `SQUISQ_FFMPEG`,
+`PATH`, or `ffmpeg-static`, in that order.
 
-### `docblocks parse <input>`
+## Development with linked Squisq
 
-Parse a markdown file and print its structure as JSON.
+From the DocBlocks repository root:
 
-## License
+```bash
+npm run link:squisq
+npm run check:squisq-linked
+npm run test:mcp:linked
+npm run all
+```
 
-MIT
+The linked assurance commands use the sibling `..\squisq` source checkout, not the
+npm package copy.

package/dist/commands/convert.d.ts

@@ -1,8 +1,10 @@
 /**
  * convert command
  *
- * Reads a markdown file, ZIP/DBK container, or folder and exports to
- * supported formats: DOCX, PPTX, PDF, HTML, and container ZIP (.dbk).
+ * Reads any input supported by the linked Squisq CLI and exports through its
+ * canonical format registry. The historical default set remains DOCX, PPTX,
+ * PDF, HTML, and DBK; callers may explicitly request any export-capable
+ * registry format.
  *
  * Wraps the same logic as squisq-cli's convert command, reusing the
  * underlying squisq libraries directly.
@@ -10,17 +12,25 @@
 import { Command } from 'commander';
 import type { MarkdownDocument } from '@bendyline/squisq/markdown';
 import type { ContentContainer } from '@bendyline/squisq/storage';
+import type { FormatRegistry } from '@bendyline/squisq-cli/api';
 export interface ConvertOptions {
     outputDir?: string;
     formats?: string;
     theme?: string;
     transform?: string;
+    /** Cancel reading, transformation, conversion, or publication at a bounded boundary. */
+    signal?: AbortSignal;
+    /** Programmatic registry override; the CLI defaults to the linked Squisq registry. */
+    registry?: FormatRegistry;
 }
 export interface ConvertResult {
     outputFiles: {
         path: string;
         format: string;
         size: number;
+        mimeType: string;
+        suggestedFilename: string;
+        warnings: string[];
     }[];
 }
 export declare function runConvert(inputPath: string, opts: ConvertOptions): Promise<ConvertResult>;

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

@@ -1 +1 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../src/commands/convert.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAqBlE,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/D;AAED,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmEhG;AA8DD;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,gBAAgB,EAC7B,SAAS,EAAE,gBAAgB,EAC3B,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CAQ3B;AAkBD,eAAO,MAAM,cAAc,SAqBvB,CAAC"}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../src/commands/convert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAA2B,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIzF,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,EAAE,CAAC;CACL;AAED,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAiHhG;AAUD;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,gBAAgB,EAC7B,SAAS,EAAE,gBAAgB,EAC3B,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AA6LD,eAAO,MAAM,cAAc,SAyBvB,CAAC"}