@superdoc/cli 0.35.0-next.23 → 0.35.0-next.25

package/dist/index.js

@@ -322018,6 +322018,35 @@ var init_context2 = __esm(() => {
   STATE_DIR_OVERRIDE_STORAGE = new AsyncLocalStorage;
 });
 
+// src/lib/text-input.ts
+import { readFile as readFile3 } from "node:fs/promises";
+async function resolveTextInput({ inlineValue, filePath, flag, doc }, context) {
+  if (filePath === undefined)
+    return inlineValue;
+  if (inlineValue !== undefined) {
+    throw new CliError("INVALID_ARGUMENT", `Use only one of --${flag} or --${flag}-file.`);
+  }
+  if (filePath.length === 0) {
+    throw new CliError("INVALID_ARGUMENT", `--${flag}-file requires a non-empty path or '-' for stdin.`);
+  }
+  if (filePath === "-" && doc === "-") {
+    throw new CliError("INVALID_ARGUMENT", `Cannot read both DOCX bytes and --${flag}-file content from stdin.`);
+  }
+  if (filePath === "-" && context.executionMode === "host") {
+    throw new CliError("INVALID_ARGUMENT", `--${flag}-file cannot read stdin in host mode. Use a file path or inline content.`);
+  }
+  try {
+    return filePath === "-" ? Buffer.from(await context.io.readStdinBytes()).toString("utf8") : await readFile3(filePath, "utf8");
+  } catch (error4) {
+    throw new CliError("FILE_READ_ERROR", `Could not read --${flag}-file ${filePath === "-" ? "from stdin" : filePath}.`, {
+      message: error4 instanceof Error ? error4.message : String(error4)
+    });
+  }
+}
+var init_text_input = __esm(() => {
+  init_errors();
+});
+
 // src/cli/operation-hints.ts
 function buildFormatInlineAliasRecord(value2) {
   return Object.fromEntries(FORMAT_INLINE_ALIAS_OPERATION_IDS.map((operationId) => [operationId, value2]));
@@ -324386,7 +324415,7 @@ function blankDocxCandidates({
 var init_blank_docx = () => {};
 
 // src/lib/document-source.ts
-import { readFile as readFile3, stat as stat3 } from "node:fs/promises";
+import { readFile as readFile4, stat as stat3 } from "node:fs/promises";
 import path3 from "node:path";
 import { fileURLToPath } from "node:url";
 async function fileExists(filePath) {
@@ -324397,7 +324426,7 @@ async function readBlankDocx() {
   const candidates = blankDocxCandidates({ moduleDir: MODULE_DIR });
   for (const candidate of candidates) {
     if (await fileExists(candidate)) {
-      const bytes = await readFile3(candidate);
+      const bytes = await readFile4(candidate);
       return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     }
   }
@@ -324424,7 +324453,7 @@ async function resolveDocumentSource(doc, io) {
     };
   }
   try {
-    const data = await readFile3(doc);
+    const data = await readFile4(doc);
     const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
     return {
       bytes,
@@ -324882,7 +324911,7 @@ var init_document_v2 = __esm(() => {
 
 // src/lib/document.ts
 import { createHash as createHash4 } from "node:crypto";
-import { readFile as readFile4 } from "node:fs/promises";
+import { readFile as readFile5 } from "node:fs/promises";
 async function openSessionDocument(doc, io, metadata, options = {}) {
   const { executionMode, sessionPool, sessionId } = options;
   const runtime = metadata.runtime ?? "v2";
@@ -324947,7 +324976,7 @@ function loadV2Runtime() {
 async function getFileChecksum(path5) {
   let bytes;
   try {
-    const data = await readFile4(path5);
+    const data = await readFile5(path5);
     bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
   } catch (error4) {
     const message = error4 instanceof Error ? error4.message : String(error4);
@@ -447340,6 +447369,8 @@ var init_command_examples = __esm(() => {
     htmlToFragment: ['superdoc html-to-fragment --html "<h2>Summary</h2><p><strong>Approved</strong></p>"'],
     markdownToFragment: ['superdoc markdown-to-fragment --markdown "## Summary\\n\\n**Approved**"'],
     insert: [
+      "superdoc insert --type html --value-file body.html",
+      "superdoc insert --type markdown --value-file -",
       'superdoc insert --value "Hello, world!"',
       'superdoc insert --block-id abc123 --value "Appended text"',
       'superdoc insert --type markdown --value "## New Section"',
@@ -447560,6 +447591,8 @@ var init_commands = __esm(() => {
       mutates: true,
       examples: [
         "superdoc open my-doc.docx",
+        "superdoc open --content-override-file body.md --override-type markdown",
+        "superdoc open --content-override-file - --override-type html",
         'superdoc open --content-override "# Title\\n\\nBody text" --override-type markdown',
         "superdoc open template.docx --content-override '<p>ALPHA01</p><p>BRAVO02</p>' --override-type html",
         `superdoc open my-doc.docx --collaboration-json '{"url":"wss://collab.example.com"}'`
@@ -448329,6 +448362,14 @@ var init_operation_params = __esm(() => {
     ],
     "doc.insert": [
       ...TEXT_TARGET_FLAT_PARAMS_AGENT_HIDDEN,
+      {
+        name: "valueFile",
+        kind: "flag",
+        flag: "value-file",
+        type: "string",
+        description: "Read content from a UTF-8 file, or '-' for stdin. Use instead of --value with --type text, html, or markdown.",
+        agentVisible: false
+      },
       {
         name: "offset",
         kind: "flag",
@@ -448790,12 +448831,20 @@ var init_operation_params = __esm(() => {
           type: "string",
           description: "Complete main-body content. Requires --override-type and cannot be combined with collaboration."
         },
+        {
+          name: "contentOverrideFile",
+          kind: "flag",
+          flag: "content-override-file",
+          type: "string",
+          description: "Read main-body content from a UTF-8 file, or '-' for stdin. Use instead of --content-override. Requires --override-type and cannot be combined with collaboration.",
+          agentVisible: false
+        },
         {
           name: "overrideType",
           kind: "flag",
           flag: "override-type",
           type: "string",
-          description: "Content format for --content-override: markdown, html, or text. Required when --content-override is present."
+          description: "Content format: markdown, html, or text. Required with --content-override or --content-override-file."
         },
         {
           name: "roomMode",
@@ -449236,6 +449285,7 @@ function buildOperationDetail(spec, metadata) {
       flag: p.flag,
       type: p.type,
       required: p.required,
+      description: p.description,
       schema: p.schema
     })),
     constraints: metadata.constraints
@@ -449427,7 +449477,9 @@ function buildDescribeCommandPretty(data) {
     const formatted = params4.map((param) => {
       const label = paramLabel(param);
       const detailParts = [];
-      if (param.kind === "doc" && param.name === "doc") {
+      if (param.description)
+        detailParts.push(param.description);
+      if (param.kind === "doc" && param.name === "doc" && !param.description) {
         detailParts.push("Document path or stdin");
       }
       const oneOfGroup = requiresOneOf?.find((group) => group.includes(param.name));
@@ -451041,7 +451093,7 @@ function resolvePassword(explicit, allowEnvFallback = true) {
 }
 
 // src/commands/open.ts
-import { open as openFile, readFile as readFile5, rm as rm4, writeFile as writeFile4 } from "node:fs/promises";
+import { open as openFile, readFile as readFile6, rm as rm4, writeFile as writeFile4 } from "node:fs/promises";
 function contextDocumentFromRuntime(opened) {
   return {
     meta: opened.meta,
@@ -451056,7 +451108,7 @@ async function applyContentOverride(invoke, content3, type, context) {
 }
 async function captureOpenContextFile(path5) {
   try {
-    return { path: path5, bytes: await readFile5(path5) };
+    return { path: path5, bytes: await readFile6(path5) };
   } catch (error4) {
     if (error4?.code === "ENOENT")
       return { path: path5 };
@@ -451132,20 +451184,26 @@ async function runOpen(tokens, context) {
         usage: [
           "superdoc open [doc] [--session <id>] [--password <password>]",
           "superdoc open [doc] --content-override <content> --override-type <markdown|html|text>",
+          "superdoc open [doc] --content-override-file <path> --override-type <markdown|html|text>",
+          "superdoc open --content-override-file - --override-type html",
           'superdoc open [doc] --collaboration-json "{...}" [--session <id>]',
           "",
           "Encrypted documents: use --password or set SUPERDOC_DOC_PASSWORD env var.",
-          "Content override replaces the main body while preserving the rest of a template DOCX."
+          "Content override replaces the main body while preserving the rest of a template DOCX.",
+          "Use --content-override-file for UTF-8 files; - reads stdin. Choose one content source."
         ]
       },
       pretty: [
         "Usage:",
         "  superdoc open [doc] [--session <id>] [--password <password>]",
         "  superdoc open [doc] --content-override <content> --override-type <markdown|html|text>",
+        "  superdoc open [doc] --content-override-file <path> --override-type <markdown|html|text>",
+        "  superdoc open --content-override-file - --override-type html",
         '  superdoc open [doc] --collaboration-json "{...}" [--session <id>]',
         "",
         "Encrypted documents: use --password or set SUPERDOC_DOC_PASSWORD env var.",
-        "Content override replaces the main body while preserving the rest of a template DOCX."
+        "Content override replaces the main body while preserving the rest of a template DOCX.",
+        "Use --content-override-file for UTF-8 files; - reads stdin. Choose one content source."
       ].join(`
 `)
     };
@@ -451155,7 +451213,9 @@ async function runOpen(tokens, context) {
   const collaborationPayload = await resolveJsonInput(parsed, "collaboration");
   const collabUrl = getStringOption(parsed, "collab-url");
   const collabDocumentId = getStringOption(parsed, "collab-document-id");
-  const contentOverride = getStringOption(parsed, "content-override");
+  const inlineContentOverride = getStringOption(parsed, "content-override");
+  const contentOverrideFile = getStringOption(parsed, "content-override-file");
+  const hasContentOverride = inlineContentOverride != null || contentOverrideFile != null;
   const overrideType = getStringOption(parsed, "override-type");
   const roomMode = getStringOption(parsed, "room-mode");
   const bootstrapSettlingMs = getNumberOption(parsed, "bootstrap-settling-ms");
@@ -451166,11 +451226,11 @@ async function runOpen(tokens, context) {
   const allowEnvFallback = context.executionMode !== "host";
   const password = resolvePassword(getStringOption(parsed, "password"), allowEnvFallback);
   const trackChanges = normalizeTrackChangesOpenConfig(args2.trackChanges);
-  if (contentOverride != null && !overrideType) {
-    throw new CliError("INVALID_ARGUMENT", "open: --content-override requires --override-type.");
+  if (hasContentOverride && !overrideType) {
+    throw new CliError("INVALID_ARGUMENT", "open: --content-override or --content-override-file requires --override-type.");
   }
-  if (overrideType && contentOverride == null) {
-    throw new CliError("INVALID_ARGUMENT", "open: --override-type requires --content-override.");
+  if (overrideType && !hasContentOverride) {
+    throw new CliError("INVALID_ARGUMENT", "open: --override-type requires --content-override or --content-override-file.");
   }
   if (overrideType && !VALID_OVERRIDE_TYPES.has(overrideType)) {
     throw new CliError("INVALID_ARGUMENT", `open: --override-type must be one of: markdown, html, text. Got "${overrideType}".`);
@@ -451181,7 +451241,7 @@ async function runOpen(tokens, context) {
   if (collaborationPayload != null && (collabUrl || collabDocumentId)) {
     throw new CliError("INVALID_ARGUMENT", "open: do not combine --collaboration-json with --collab-url / --collab-document-id.");
   }
-  if (contentOverride != null && (collaborationPayload != null || collabUrl)) {
+  if (hasContentOverride && (collaborationPayload != null || collabUrl)) {
     throw new CliError("INVALID_ARGUMENT", "open: --content-override is incompatible with collaboration mode. Content override is a template-initialization operation.");
   }
   let collaborationInput;
@@ -451232,6 +451292,7 @@ async function runOpen(tokens, context) {
     editorOpenOptions.trackChanges = trackChanges;
     editorOpenOptions.modules = { ...editorOpenOptions.modules, trackChanges };
   }
+  const contentOverride = await resolveTextInput({ inlineValue: inlineContentOverride, filePath: contentOverrideFile, flag: "content-override", doc }, context);
   return withContextLock(context.io, "open", async (paths) => {
     const existing = await readContextMetadata(paths);
     if (existing && existing.projectRoot !== getProjectRoot()) {
@@ -451267,7 +451328,7 @@ async function runOpen(tokens, context) {
       } else if (options.initializedBaseline) {
         contextRevision = await opened2.currentRevision();
         await opened2.exportToPath(paths.workingDocPath, true);
-        await writeBytesToPath(await readFile5(paths.workingDocPath), paths.originalDocPath, true);
+        await writeBytesToPath(await readFile6(paths.workingDocPath), paths.originalDocPath, true);
       } else {
         contextRevision = await opened2.currentRevision();
         await opened2.copySourceToPath(paths.originalDocPath, true);
@@ -451448,6 +451509,7 @@ var init_open = __esm(() => {
   init_document_source();
   init_file_output();
   init_mutation_orchestrator();
+  init_text_input();
   init_operation_args();
   init_session();
   init_types9();
@@ -454758,6 +454820,8 @@ var init_contract4 = __esm(() => {
             ],
             aliases: [],
             examples: [
+              "superdoc insert --type html --value-file body.html",
+              "superdoc insert --type markdown --value-file -",
               'superdoc insert --value "Hello, world!"',
               'superdoc insert --block-id abc123 --value "Appended text"',
               'superdoc insert --type markdown --value "## New Section"',
@@ -465146,6 +465210,8 @@ var init_contract4 = __esm(() => {
             aliases: [],
             examples: [
               "superdoc open my-doc.docx",
+              "superdoc open --content-override-file body.md --override-type markdown",
+              "superdoc open --content-override-file - --override-type html",
               'superdoc open --content-override "# Title\\n\\nBody text" --override-type markdown',
               "superdoc open template.docx --content-override '<p>ALPHA01</p><p>BRAVO02</p>' --override-type html",
               `superdoc open my-doc.docx --collaboration-json '{"url":"wss://collab.example.com"}'`
@@ -480260,6 +480326,14 @@ var init_contract4 = __esm(() => {
             description: "End offset within the block (character index).",
             agentVisible: false
           },
+          {
+            name: "valueFile",
+            kind: "flag",
+            type: "string",
+            flag: "value-file",
+            description: "Read content from a UTF-8 file, or '-' for stdin. Use instead of --value with --type text, html, or markdown.",
+            agentVisible: false
+          },
           {
             name: "offset",
             kind: "flag",
@@ -763127,12 +763201,20 @@ var init_contract4 = __esm(() => {
             flag: "content-override",
             description: "Complete main-body content. Requires --override-type and cannot be combined with collaboration."
           },
+          {
+            name: "contentOverrideFile",
+            kind: "flag",
+            type: "string",
+            flag: "content-override-file",
+            description: "Read main-body content from a UTF-8 file, or '-' for stdin. Use instead of --content-override. Requires --override-type and cannot be combined with collaboration.",
+            agentVisible: false
+          },
           {
             name: "overrideType",
             kind: "flag",
             type: "string",
             flag: "override-type",
-            description: "Content format for --content-override: markdown, html, or text. Required when --content-override is present."
+            description: "Content format: markdown, html, or text. Required with --content-override or --content-override-file."
           },
           {
             name: "roomMode",
@@ -763366,7 +763448,7 @@ var init_contract4 = __esm(() => {
             },
             overrideType: {
               type: "string",
-              description: "Content format for --content-override: markdown, html, or text. Required when --content-override is present."
+              description: "Content format: markdown, html, or text. Required with --content-override or --content-override-file."
             },
             roomMode: {
               type: "string",
@@ -767434,7 +767516,7 @@ var init_host2 = __esm(() => {
 });
 
 // ../../packages/sdk/langs/node/src/runtime/sdk-version.generated.ts
-var SDK_VERSION = "2.12.0-next.23";
+var SDK_VERSION = "2.12.0-next.25";
 
 // ../../packages/sdk/langs/node/src/runtime/embedded-platform.ts
 import { chmodSync, existsSync } from "node:fs";
@@ -767740,6 +767822,7 @@ function detailParam(param) {
     ...Object.prototype.hasOwnProperty.call(param, "flag") ? { flag: param.flag } : {},
     type: param.type,
     ...Object.prototype.hasOwnProperty.call(param, "required") ? { required: param.required } : {},
+    ...Object.prototype.hasOwnProperty.call(param, "description") ? { description: param.description } : {},
     ...Object.prototype.hasOwnProperty.call(param, "schema") ? { schema: param.schema } : {}
   };
 }
@@ -801397,7 +801480,7 @@ var init_embedded_tools_generated = __esm(() => {
 });
 
 // ../../packages/sdk/langs/node/src/presets/legacy.ts
-import { readFile as readFile6 } from "node:fs/promises";
+import { readFile as readFile7 } from "node:fs/promises";
 import path8 from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 function isRecord12(value2) {
@@ -801428,7 +801511,7 @@ async function readToolFile(fileName, message, candidateDirs = TOOLS_DIR_CANDIDA
     const filePath = path8.join(toolsDir, fileName);
     tried.push(filePath);
     try {
-      return { filePath, raw: await readFile6(filePath, "utf8") };
+      return { filePath, raw: await readFile7(filePath, "utf8") };
     } catch (error4) {
       lastError = error4;
     }
@@ -813850,7 +813933,7 @@ OPERATING RULES
 });
 
 // ../../packages/sdk/langs/node/src/presets/core.ts
-import { readFile as readFile7 } from "node:fs/promises";
+import { readFile as readFile8 } from "node:fs/promises";
 import path9 from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 async function readPromptFile(fileName, label, candidateDirs = PROMPT_DIR_CANDIDATES) {
@@ -813860,7 +813943,7 @@ async function readPromptFile(fileName, label, candidateDirs = PROMPT_DIR_CANDID
     const promptPath = path9.join(dir, fileName);
     tried.push(promptPath);
     try {
-      return await readFile7(promptPath, "utf8");
+      return await readFile8(promptPath, "utf8");
     } catch (err2) {
       const ioError = err2;
       if (ioError?.code !== "ENOENT") {
@@ -815825,6 +815908,18 @@ async function executeOperation(request) {
       maybeRemapInputValidationError(request, error4);
     }
   }
+  if (request.operationId === "doc.insert" && input.valueFile != null) {
+    const { valueFile, ...rest } = input;
+    input = {
+      ...rest,
+      value: await resolveTextInput({
+        inlineValue: input.value,
+        filePath: valueFile,
+        flag: "value",
+        doc: input.doc
+      }, baseContext)
+    };
+  }
   await preflightCallContext(request.operationId, input, baseContext);
   const effectiveContext = applySessionInputToContext(baseContext, input);
   const docApiId = toDocApiId(request.operationId);
@@ -815854,6 +815949,7 @@ var MANUAL_OPERATION_ALLOWLIST_SET, CALL_VALIDATION_COMMAND_FAILED_DOC_API_IDS,
 var init_operation_executor = __esm(() => {
   init_context2();
   init_errors();
+  init_text_input();
   init_input_readers();
   init_generic_dispatch();
   init_introspection_dispatch();
@@ -816217,7 +816313,7 @@ var init_document_runtime_session = __esm(() => {
 });
 
 // src/lib/local-document-runtime-sessions.ts
-import { readFile as readFile8 } from "node:fs/promises";
+import { readFile as readFile9 } from "node:fs/promises";
 function resolveAuthor2(user) {
   const name = user?.name?.trim() || "CLI";
   const email = user?.email?.trim();
@@ -816413,7 +816509,7 @@ function createCliLocalDocumentRuntimeSessions(manager = _0x51cc97()) {
         if (sourceBytes !== undefined) {
           bytes = new Uint8Array(sourceBytes);
         } else if (source.source === "path") {
-          bytes = await readFile8(source.path);
+          bytes = await readFile9(source.path);
         } else {
           throw new CliError("FILE_READ_ERROR", "The local document source bytes are unavailable.");
         }
@@ -816516,7 +816612,7 @@ var init_local_document_runtime_sessions = __esm(() => {
 
 // src/host/session-pool.ts
 import { createHash as createHash5 } from "node:crypto";
-import { readFile as readFile9 } from "node:fs/promises";
+import { readFile as readFile10 } from "node:fs/promises";
 function stableStringify2(value2) {
   if (value2 === null || typeof value2 !== "object")
     return JSON.stringify(value2);
@@ -816585,7 +816681,7 @@ class InMemorySessionPool {
       } : undefined;
       let byteLength2;
       let revision;
-      const replacementBytes = new Uint8Array(await readFile9(path10));
+      const replacementBytes = new Uint8Array(await readFile10(path10));
       if (session.sessionType === "local") {
         const initialRevision = Math.max(session.metadataRevision, publicRevisionForMetadata(session.opened)) + 1;
         const prepared = await this.localRuntimeSessions.prepare(sessionId, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/cli",
-  "version": "0.35.0-next.23",
+  "version": "0.35.0-next.25",
   "description": "Command-line interface for SuperDoc: inspect, convert, and edit .docx files from a terminal or a script.",
   "type": "module",
   "license": "AGPL-3.0",
@@ -35,7 +35,7 @@
   },
   "devDependencies": {
     "@hocuspocus/server": "^2.13.6",
-    "@superdoc/sdk": "2.12.0-next.23",
+    "@superdoc/sdk": "2.12.0-next.25",
     "@superdoc/document-api": "0.1.0-alpha.0",
     "@superdoc/docx-engine": "0.14.0-next.13",
     "@types/bun": "^1.3.8",
@@ -51,11 +51,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@superdoc/cli-darwin-arm64": "0.35.0-next.23",
-    "@superdoc/cli-darwin-x64": "0.35.0-next.23",
-    "@superdoc/cli-linux-x64": "0.35.0-next.23",
-    "@superdoc/cli-linux-arm64": "0.35.0-next.23",
-    "@superdoc/cli-windows-x64": "0.35.0-next.23"
+    "@superdoc/cli-darwin-arm64": "0.35.0-next.25",
+    "@superdoc/cli-darwin-x64": "0.35.0-next.25",
+    "@superdoc/cli-linux-x64": "0.35.0-next.25",
+    "@superdoc/cli-linux-arm64": "0.35.0-next.25",
+    "@superdoc/cli-windows-x64": "0.35.0-next.25"
   },
   "scripts": {
     "predev": "node scripts/ensure-superdoc-build.js",

package/skill/SKILL.md

@@ -58,7 +58,7 @@ superdoc close
 ```
 
 - `--content-override` is the fastest way to seed paragraphs, headings, lists, and `<br/>` line breaks.
-- Use `--override-type markdown|html|text` explicitly. `open` rejects `--content-override` without it.
+- Use `--override-type markdown|html|text` explicitly with either `--content-override` or `--content-override-file`.
 - For generation, do not start with `query match` unless you are modifying content that already exists.
 
 ### 3) Generate incrementally, then reuse the insert receipt target
@@ -167,6 +167,29 @@ superdoc insert tab --block-id p1 --offset 12
 
 - Direct invoke: `call <operationId> --input-json '{...}'` (JSON output only — `--pretty` is not supported)
 
+## Text, HTML, and Markdown Files
+
+For large content, use a UTF-8 file or pipe stdin with `-`. File content follows the same conversion and validation as inline content.
+
+```bash
+superdoc open --content-override-file ./body.md --override-type markdown
+superdoc insert --type html --value-file ./section.html
+superdoc save --out ./generated.docx
+superdoc close
+```
+
+```bash
+superdoc open --content-override-file - --override-type html < ./body.html
+superdoc insert --type text --value-file - < ./appendix.txt
+superdoc save --out ./generated.docx
+superdoc close
+```
+
+- Use `--value-file <path|->` for `insert --type text|html|markdown`.
+- Use `--content-override-file <path|->` for blank or template initialization with `open --override-type text|html|markdown`.
+- Choose one content source: inline or file/stdin. An empty file is an explicit empty payload.
+- Relative paths resolve from the current working directory. DOCX input and content input cannot both use stdin in the same command.
+
 ## JSON/File Payload Flags
 
 Not all `--*-file` variants are available on every command. Use `describe command <name>` to check.