@bendyline/docblocks-cli 2.2.0 → 2.2.1

package/dist/bin.js

@@ -1872,6 +1872,66 @@ async function validatePreparedDocument(_documents, prepared, targetFormat, sign
     diagnostics: unique
   };
 }
+function annotationSyntaxDiagnostics(markdown, stage, format) {
+  const diagnostics = [];
+  const lines = markdown.split(/\r?\n/);
+  let inFence = false;
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    if (diagnostics.length >= MCP_WIRE_LIMITS5.arrayEntries) break;
+    const rawLine = lines[lineIndex];
+    if (/^\s*(?:```|~~~)/u.test(rawLine)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const line = rawLine.replace(/`[^`]*`/gu, "``");
+    let search = 0;
+    while (search < line.length) {
+      const open6 = line.indexOf("{[", search);
+      if (open6 === -1) break;
+      const close = line.indexOf("]}", open6 + 2);
+      if (close === -1) {
+        diagnostics.push(
+          malformedAnnotationDiagnostic(
+            stage,
+            format,
+            lineIndex + 1,
+            open6 + 1,
+            'An annotation opened with "{[" has no matching "]}" on the same line.'
+          )
+        );
+        break;
+      }
+      const inner = line.slice(open6 + 2, close).replace(/"[^"]*"/gu, '""');
+      if (/[{}[\]]/u.test(inner)) {
+        diagnostics.push(
+          malformedAnnotationDiagnostic(
+            stage,
+            format,
+            lineIndex + 1,
+            open6 + 1,
+            "An annotation contains a stray brace or bracket outside quoted values."
+          )
+        );
+      }
+      search = close + 2;
+    }
+  }
+  return diagnostics;
+}
+function malformedAnnotationDiagnostic(stage, format, line, column, message) {
+  return {
+    code: "malformed-template-annotation",
+    severity: "warning",
+    stage,
+    format,
+    count: 1,
+    message,
+    remediation: 'Repair the annotation so it reads exactly `{[templateId key="value"]}` with no extra braces or brackets, then validate again.',
+    retryable: false,
+    location: { kind: "source", line, column }
+  };
+}
 async function authoringDiagnostics(prepared, stage, format, signal) {
   throwIfAborted5(signal);
   const {
@@ -1885,7 +1945,11 @@ async function authoringDiagnostics(prepared, stage, format, signal) {
   const blocks = flattenBlocks(prepared.doc.blocks);
   const analyzedBlocks = blocks.slice(0, MCP_WIRE_LIMITS5.arrayEntries);
   const theme = resolveThemeForDoc(prepared.doc);
-  const diagnostics = [];
+  const diagnostics = annotationSyntaxDiagnostics(
+    prepared.markdown,
+    stage,
+    format
+  );
   for (let index = 0; index < analyzedBlocks.length; index += 1) {
     const checkpoint = cancellationCheckpoint(signal, index);
     if (checkpoint) await checkpoint;
@@ -4639,11 +4703,13 @@ function registerTemplateTools(server, context) {
               throw new Error(`Format "${normalizedTarget}" is not export-capable`);
             }
           }
-          const [templates, schemaModule, transformModule] = await Promise.all([
+          const [fullTemplates, schemaModule, transformModule] = await Promise.all([
             authoringTemplateCatalog(),
             import("@bendyline/squisq/schemas"),
             import("@bendyline/squisq/transform")
           ]);
+          const annotationHandling = normalizedTarget ? await targetTemplateAnnotationHandling(normalizedTarget) : null;
+          const templates = annotationHandling === "ignored" ? fullTemplates.filter((template) => template.safeForContentFirst) : fullTemplates;
           let recommendations = [];
           let totalBlocks = null;
           let truncated = false;
@@ -4688,19 +4754,19 @@ function registerTemplateTools(server, context) {
             defaultFidelity: authoringDefaultFidelity(normalizedTarget, goal),
             workflow: [
               "Treat supplied facts as a closed evidence set. Use temporal or correlational wording unless causality is supplied. Label calculations, assumptions, hypotheses, recommendations, and illustrative examples. Do not infer end-to-end feasibility from one supplied phase duration.",
-              "Audit claims before conversion: causal links, rhetorical labels such as compounding, engine, healthy, strong, or constraint, superlatives, sole-cause claims, targets, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed as a hypothesis, recommendation, example, or proposal. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Do not call choices a sequence or capacity allocation unless order, timing, or resource constraints were supplied.",
-              "Complete every requested element without presenting invented policy as established fact. When a requested policy, playbook, or training guide needs unsupplied roles, gates, timelines, channels, or procedures, add one explicit proposed operating model scope note placed before the first such detail so it governs all of them.",
+              "Audit claims before conversion: causal links, rhetorical labels such as compounding, engine, healthy, strong, or constraint, superlatives, sole-cause claims, targets, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied.",
+              "Complete every requested element without presenting invented policy as established fact. When a requested policy, playbook, or training guide needs unsupplied roles, gates, timelines, channels, or procedures, add one explicit proposed operating model scope note placed before the first such detail so it governs all of them. Prefix each unsupplied operational rule with Proposed: on its slide or section.",
               "Generic option traits\u2014control, flexibility, vendor support, freed capacity, switching costs\u2014are capability claims: state one only when supplied or labeled Assumption or Judgment, even in table cells and tradeoffs.",
               "Author complete Squisq-compatible content with heading-bound annotations; ordinary headings default to the loss-averse content template.",
               normalizedTarget === "pptx" ? "Match every explicitly requested slide count exactly. Use exactly one level-one Markdown heading (#) per slide and no level-two through level-six headings because every heading becomes a slide by default. Target at most 80 words per slide, and use lists, tables, or bold labels for within-slide structure." : "Honor the requested word range and document genre. Prefer connected memo prose for executive decisions and native headings, tables, and checklists for operational documents.",
-              normalizedTarget === "pptx" ? "Make slide one a supported point-of-view thesis, not a generic title or unsupported flourish. For requested choices, state a concrete opportunity cost grounded in the supplied alternatives and name one clearly labeled proposed accountable role per choice. If a tradeoff requires an unsupplied capacity or outcome assumption, label it Assumption or Potential tradeoff rather than stating it as fact." : "Tie each decision implication or comparative judgment to a supplied fact or calculation, or label it Judgment. When accountability is requested but not supplied, name one clearly labeled proposed accountable role per decision or workstream.",
-              "Add decision value without inventing causes: interpret supplied comparisons to baselines, goals, targets, and rankings; use transparent calculations; label any new review cadence or measurement procedure as proposed.",
+              normalizedTarget === "pptx" ? "Make slide one a supported point-of-view thesis, not a generic title. For requested choices, state a concrete opportunity cost from supplied alternatives and one proposed accountable role per choice. Label any unsupplied capacity or outcome assumption Assumption or Potential tradeoff." : "Tie each decision implication or comparative judgment to a supplied fact or calculation, or label it Judgment. When accountability is requested but not supplied, name one clearly labeled proposed accountable role per decision or workstream.",
+              "Add decision value without inventing causes: interpret supplied comparisons to baselines, goals, and targets; use transparent calculations; label new review cadences or measurement procedures as proposed.",
               "Before validation and conversion, run a content preflight: count slide sections or document words, verify every requested element, and rewrite or label every unsupported claim.",
-              "Use the complete Markdown as the authoritative source. Pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document, and revise by editing the complete Markdown and converting again.",
-              "Use create_document_bundle only when reusing a large Markdown-and-asset bundle across several review or conversion operations would materially reduce retransmission.",
+              "Use the complete Markdown as the authoritative source. Pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document; revise by editing it and converting again.",
+              "When a draft will feed two or more validate, preview, or convert calls, stage it once with create_document_bundle and pass the returned artifact URI as each source; after edits, stage the revised draft again.",
               "Use inspect_document or validate_document when semantic structure, content retention, accessibility, or target diagnostics need review; repair actionable findings in the authoritative Markdown.",
               "Use preview_document when visual evidence is needed, inspect previewBasis, and repair overflow or layout problems in the authoritative Markdown.",
-              normalizedTarget === "pptx" ? "For visual polish, replace selected content blocks with compatible recommended templates; use patterns such as definitionCard for a definition, dataTable for a true table, comparisonBar for supported numeric comparisons, and list for concise steps when the returned catalog supports them. Preserve all required content and preview again." : "For visual polish, use native headings, tables, and checklists where they improve scanning; keep complete-body content when a visual template would discard detail, then preview again.",
+              normalizedTarget === "pptx" ? "For visual polish, replace selected content blocks with compatible recommended templates; use patterns such as definitionCard for a definition, dataTable for a true table, comparisonBar for supported numeric comparisons, and list for concise steps when the returned catalog supports them. Preserve all required content and preview again." : annotationHandling === "ignored" ? "This target flattens template annotations to semantic content, so visual templates have no effect on the exported file: rely on native headings, tables, and checklists for structure and scanning." : "For visual polish, use native headings, tables, and checklists where they improve scanning; keep complete-body content when a visual template would discard detail, then preview again.",
               "Convert to immutable artifacts, inspect conversion reports, and save only final durable outputs."
             ],
             syntax: {
@@ -5153,7 +5219,7 @@ function compactAuthoringContextText(context) {
     `Warning: ${context.syntax.standaloneWarning}`,
     `Templates (${context.templates.length}): ${context.templates.map(({ id }) => id).join(", ")}`,
     `Themes (${context.themes.length}): ${context.themes.map(({ id }) => id).join(", ")}`,
-    `Transform styles (${context.transformStyles.length}): ${context.transformStyles.map(({ id }) => id).join(", ")}`
+    `Transform styles (${context.transformStyles.length}): ${context.transformStyles.map(({ id }) => id).join(", ")} \u2014 transforms re-compose blocks and can change section count; avoid on exact-count briefs.`
   ];
   if (context.recommendations.length > 0) {
     lines.push(
@@ -5232,6 +5298,15 @@ async function authoringTemplateCatalog() {
     };
   });
 }
+async function targetTemplateAnnotationHandling(targetFormat) {
+  const { createCliRegistry: createCliRegistry2 } = await import("@bendyline/squisq-cli/api");
+  const definition = createCliRegistry2().get(targetFormat);
+  if (definition && typeof definition === "object" && "templateAnnotationHandling" in definition) {
+    const value = definition.templateAnnotationHandling;
+    if (value === "rendered" || value === "preserved" || value === "ignored") return value;
+  }
+  return null;
+}
 function authoringDefaultFidelity(targetFormat, goal) {
   if (!targetFormat) return null;
   if (targetFormat === "mp4" || targetFormat === "gif") return "rendered-fidelity";
@@ -5702,7 +5777,7 @@ function createMcpServer(options = {}) {
   const server = new McpServer(
     { name: "docblocks", version: getPackageVersion() },
     {
-      instructions: "Treat provided facts as a closed evidence set: preserve them exactly; use temporal or correlational wording unless causality is supplied; label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, rhetorical performance labels, superlatives, sole causes, targets, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Add decision value through supplied baselines, goals, targets, rankings, and transparent calculations. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied. When a requested policy, playbook, or training guide needs unsupplied operating details, add one proposed operating model scope note, then complete every requested element. Match explicit slide/page counts and word ranges exactly; target at most 80 words per presentation section. Make slide one a supported point-of-view thesis. For requested choices, state concrete opportunity costs grounded in supplied alternatives and one proposed accountable role per choice; label unsupplied capacity, outcome, or review-cadence assumptions. Before conversion, count sections or words, verify required elements, and audit unsupported claims. Start with get_authoring_context for the compact linked-Squisq contract and structured catalog. Author complete Squisq-compatible Markdown with template annotations on headings, for example `# Heading {[content]}`; standalone `{[template]}` creates an extra heading-less block. Ordinary headings default to the loss-averse `content` template. The canonical path is complete Markdown\u2014or a bundle source when assets are needed\u2014directly into convert_document; revise by editing the complete Markdown and converting again. create_document_bundle is optional for materially large, reusable Markdown-and-asset bundles. Use inspect_document, validate_document, and preview_document when their evidence is useful rather than as required phases. Save only the final durable artifact. Never invent root ids: call list_roots and use an id exactly as returned."
+      instructions: "Treat provided facts as a closed evidence set: preserve them exactly; use temporal or correlational wording unless causality is supplied; label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, rhetorical performance labels, superlatives, sole causes, targets, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Add decision value through supplied baselines, goals, targets, rankings, and transparent calculations. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied. When a requested policy, playbook, or training guide needs unsupplied operating details, add one proposed operating model scope note, then complete every requested element. Match explicit slide/page counts and word ranges exactly; target at most 80 words per presentation section. Make slide one a supported point-of-view thesis. For requested choices, state concrete opportunity costs grounded in supplied alternatives and one proposed accountable role per choice; label unsupplied capacity, outcome, or review-cadence assumptions. Before conversion, count sections or words, verify required elements, and audit unsupported claims. Start with get_authoring_context for the compact linked-Squisq contract and structured catalog. Author complete Squisq-compatible Markdown with template annotations on headings, for example `# Heading {[content]}`; standalone `{[template]}` creates an extra heading-less block. Ordinary headings default to the loss-averse `content` template. The canonical path is complete Markdown\u2014or a bundle source when assets are needed\u2014directly into convert_document; revise by editing the complete Markdown and converting again. When one draft will feed two or more validate, preview, or convert calls, stage it once with create_document_bundle and pass the returned artifact URI as each source instead of re-sending the Markdown. Use inspect_document, validate_document, and preview_document when their evidence is useful rather than as required phases. Save only the final durable artifact. Never invent root ids: call list_roots and use an id exactly as returned."
     }
   );
   registerAgenticTools(server, {

package/dist/eval/cli.js

@@ -704,7 +704,8 @@ function missingArtifact(caught) {
 }
 
 // src/eval/codex-host.ts
-import { readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { mkdtemp, readFile as readFile3, rm, writeFile as writeFile2 } from "fs/promises";
+import { tmpdir } from "os";
 import path3 from "path";
 import { z } from "zod";
 
@@ -908,17 +909,30 @@ async function runGeneration(options, testCase, caseDirectory) {
   const prompt = generationPrompt(testCase, options.profile);
   await writeFile2(path3.join(caseDirectory, "generation-prompt.txt"), prompt);
   const resolved = await resolveCodexCommand(options.codexCommand);
+  const agentCwd = await mkdtemp(path3.join(tmpdir(), "docblocks-eval-agent-"));
   const args = [
     ...resolved.prefixArgs,
-    ...buildCodexGenerationArgs(options, testCase, caseDirectory, outputSchemaPath, finalPath)
+    ...buildCodexGenerationArgs(
+      options,
+      testCase,
+      caseDirectory,
+      agentCwd,
+      outputSchemaPath,
+      finalPath
+    )
   ];
-  const capture = await runCapturedProcess({
-    command: resolved.command,
-    args,
-    cwd: options.repoRoot,
-    stdin: prompt,
-    timeoutMs: 15 * 60 * 1e3
-  });
+  let capture;
+  try {
+    capture = await runCapturedProcess({
+      command: resolved.command,
+      args,
+      cwd: agentCwd,
+      stdin: prompt,
+      timeoutMs: 15 * 60 * 1e3
+    });
+  } finally {
+    await rm(agentCwd, { recursive: true, force: true }).catch(() => void 0);
+  }
   await Promise.all([
     writeFile2(path3.join(caseDirectory, "generation-trace.jsonl"), capture.stdout),
     writeFile2(path3.join(caseDirectory, "generation-stderr.log"), capture.stderr)
@@ -951,6 +965,7 @@ async function runLlmJudge(options, testCase, markdown, caseDirectory) {
   const prompt = judgePrompt(testCase, markdown);
   await writeFile2(path3.join(caseDirectory, "judge-prompt.txt"), prompt);
   const resolved = await resolveCodexCommand(options.codexCommand);
+  const judgeCwd = await mkdtemp(path3.join(tmpdir(), "docblocks-eval-judge-"));
   const args = [
     ...resolved.prefixArgs,
     "exec",
@@ -964,7 +979,7 @@ async function runLlmJudge(options, testCase, markdown, caseDirectory) {
     "--color",
     "never",
     "--cd",
-    caseDirectory,
+    judgeCwd,
     "--output-schema",
     outputSchemaPath,
     "--output-last-message",
@@ -972,13 +987,18 @@ async function runLlmJudge(options, testCase, markdown, caseDirectory) {
     ...options.model ? ["--model", options.model] : [],
     "-"
   ];
-  const capture = await runCapturedProcess({
-    command: resolved.command,
-    args,
-    cwd: options.repoRoot,
-    stdin: prompt,
-    timeoutMs: 10 * 60 * 1e3
-  });
+  let capture;
+  try {
+    capture = await runCapturedProcess({
+      command: resolved.command,
+      args,
+      cwd: judgeCwd,
+      stdin: prompt,
+      timeoutMs: 10 * 60 * 1e3
+    });
+  } finally {
+    await rm(judgeCwd, { recursive: true, force: true }).catch(() => void 0);
+  }
   await Promise.all([
     writeFile2(path3.join(caseDirectory, "judge-trace.jsonl"), capture.stdout),
     writeFile2(path3.join(caseDirectory, "judge-stderr.log"), capture.stderr)
@@ -990,7 +1010,7 @@ async function runLlmJudge(options, testCase, markdown, caseDirectory) {
     usage: extractTokenUsage(capture.stdout)
   };
 }
-function buildCodexGenerationArgs(options, testCase, caseDirectory, outputSchemaPath, finalPath) {
+function buildCodexGenerationArgs(options, testCase, caseDirectory, agentCwd, outputSchemaPath, finalPath) {
   const mcpArgs = [
     options.cliEntry,
     "mcp",
@@ -1013,7 +1033,7 @@ function buildCodexGenerationArgs(options, testCase, caseDirectory, outputSchema
     "--color",
     "never",
     "--cd",
-    caseDirectory,
+    agentCwd,
     "-c",
     `mcp_servers.docblocks.command=${tomlString(process.execPath)}`,
     "-c",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/docblocks-cli",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Build, preview, convert, render, inspect, and automate documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -46,17 +46,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/docblocks": "2.2.0",
-    "@bendyline/squisq": "2.3.2",
-    "@bendyline/squisq-cli": "2.3.2",
-    "@bendyline/squisq-formats": "2.3.2",
-    "@bendyline/squisq-react": "2.3.2",
-    "@bendyline/squisq-video": "2.2.2",
+    "@bendyline/docblocks": "2.2.1",
+    "@bendyline/squisq": "2.3.3",
+    "@bendyline/squisq-cli": "2.3.3",
+    "@bendyline/squisq-formats": "2.3.3",
+    "@bendyline/squisq-react": "2.3.3",
+    "@bendyline/squisq-video": "2.2.3",
     "@modelcontextprotocol/sdk": "1.29.0",
     "commander": "13.1.0",
     "jszip": "3.10.1",
-    "playwright-core": "1.58.2",
     "pdf-lib": "1.17.1",
+    "playwright-core": "1.58.2",
     "zod": "3.25.76"
   }
 }