@superdoc/cli 0.35.0-next.1 → 0.35.0-next.3

package/README.md

@@ -167,9 +167,14 @@ For full command help and examples, run:
 
 ```bash
 superdoc --help
+superdoc save --help
+superdoc create paragraph --help
 superdoc describe command <command-name>
+superdoc describe command doc.save
 ```
 
+Use `--help` or `-h` with a command to read its usage without opening a document or executing the command. Operation help includes `schemaCommand`, an executable command for retrieving the complete parameter schema. Add `--pretty` for terminal-readable output.
+
 ## v1 Breaking Changes
 
 This CLI replaces the previous `@superdoc-dev/cli` package surface with the v1 contract-driven command set.

package/dist/index.js

@@ -26288,12 +26288,6 @@ var init_input_readers = __esm(() => {
   init_errors();
 });
 
-// src/lib/collaboration/types.ts
-var ENV_VAR_NAME_PATTERN;
-var init_types3 = __esm(() => {
-  ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-});
-
 // src/lib/guards.ts
 import { constants } from "node:fs";
 import { access } from "node:fs/promises";
@@ -26315,6 +26309,12 @@ async function pathExists(path) {
 }
 var init_guards = () => {};
 
+// src/lib/collaboration/types.ts
+var ENV_VAR_NAME_PATTERN;
+var init_types3 = __esm(() => {
+  ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+});
+
 // src/lib/collaboration/parse.ts
 function expectNonEmptyString(value, path) {
   if (typeof value !== "string" || value.trim().length === 0) {
@@ -440169,6 +440169,11 @@ function buildAllSpecs() {
 }
 function buildHelpText() {
   const lines = ["Usage: superdoc <command> [options]", ""];
+  lines.push("Command help and schemas:");
+  lines.push("  superdoc <command> --help");
+  lines.push("  superdoc describe command <operationId>");
+  lines.push("  superdoc describe command doc.save");
+  lines.push("");
   lines.push("Common tasks:");
   lines.push("  Find mutation target    →  query match");
   lines.push("  Seed a synthetic doc    →  open --content-override ...");
@@ -440254,7 +440259,7 @@ var init_commands = __esm(() => {
       ]
     },
     status: { mutates: false, examples: ["superdoc status"] },
-    describe: { mutates: false, examples: ["superdoc describe"] },
+    describe: { mutates: false, examples: ["superdoc describe", "superdoc describe command doc.save"] },
     describeCommand: { mutates: false, examples: ["superdoc describe command find"] },
     "session.list": { mutates: false, examples: ["superdoc session list"] },
     "session.save": {
@@ -443661,11 +443666,27 @@ var init_legacy_compat = __esm(() => {
 });
 
 // src/commands/insert-inline-special.ts
-var runInsertTab, runInsertLineBreak;
+function unavailableHelp(command) {
+  const note = `${command} is not available in the v2-only CLI.`;
+  return {
+    command,
+    data: { usage: [`superdoc ${command}`], note },
+    pretty: `Usage: superdoc ${command}
+${note}`
+  };
+}
+async function runInsertTab(tokens, context) {
+  if (tokens.includes("--help") || tokens.includes("-h"))
+    return unavailableHelp("insert tab");
+  return runLegacyInsertTab(tokens, context);
+}
+async function runInsertLineBreak(tokens, context) {
+  if (tokens.includes("--help") || tokens.includes("-h"))
+    return unavailableHelp("insert line-break");
+  return runLegacyInsertLineBreak(tokens, context);
+}
 var init_insert_inline_special = __esm(() => {
   init_legacy_compat();
-  runInsertTab = runLegacyInsertTab;
-  runInsertLineBreak = runLegacyInsertLineBreak;
 });
 
 // src/lib/open-password.ts
@@ -457907,7 +457928,8 @@ var init_contract4 = __esm(() => {
             capabilities: [],
             aliases: [],
             examples: [
-              "superdoc describe"
+              "superdoc describe",
+              "superdoc describe command doc.save"
             ],
             errors: []
           },
@@ -759679,7 +759701,7 @@ var init_host2 = __esm(() => {
 });
 
 // ../../packages/sdk/langs/node/src/runtime/sdk-version.generated.ts
-var SDK_VERSION = "2.12.0-next.1";
+var SDK_VERSION = "2.12.0-next.3";
 
 // ../../packages/sdk/langs/node/src/runtime/embedded-platform.ts
 import { chmodSync, existsSync } from "node:fs";
@@ -807242,7 +807264,7 @@ async function runSessionList(tokens, _context) {
     return {
       command: "session list",
       data: {
-        usage: "superdoc session list"
+        usage: ["superdoc session list"]
       },
       pretty: "Usage: superdoc session list"
     };
@@ -809822,10 +809844,10 @@ function parseInvocation(argv) {
   return { globals, rest };
 }
 async function executeParsedInvocation(parsed, io, executionMode, sessionPool, ambientTimeoutMs, collaborationAuth) {
-  if (parsed.globals.help) {
+  if (parsed.globals.help && parsed.rest.length === 0) {
     return { helpText: HELP };
   }
-  if (parsed.globals.version) {
+  if (parsed.globals.version && !parsed.globals.help) {
     return {
       versionText: resolveCliPackageVersion()
     };
@@ -809833,7 +809855,17 @@ async function executeParsedInvocation(parsed, io, executionMode, sessionPool, a
   if (parsed.rest.length === 0) {
     return { helpText: HELP };
   }
-  const { key: key2, args: args2 } = parseCommand(parsed.rest);
+  let command;
+  try {
+    command = parseCommand(parsed.rest);
+  } catch (error4) {
+    if (parsed.globals.help && error4 instanceof CliError && error4.code === "UNKNOWN_COMMAND") {
+      return { helpText: HELP };
+    }
+    throw error4;
+  }
+  const { key: key2, args: args2 } = command;
+  const commandArgs = parsed.globals.help ? ["--help"] : args2;
   const context = {
     io,
     timeoutMs: parsed.globals.timeoutMs ?? ambientTimeoutMs,
@@ -809845,14 +809877,31 @@ async function executeParsedInvocation(parsed, io, executionMode, sessionPool, a
   const execution = await executeWithTimeout(async () => {
     if (MANUAL_COMMAND_KEY_SET.has(key2)) {
       const handler = MANUAL_COMMANDS[key2];
-      return handler(args2, context);
+      return handler(commandArgs, context);
     }
     if (CLI_COMMAND_KEY_SET.has(key2)) {
-      return runCommandWrapper(key2, args2, context);
+      return runCommandWrapper(key2, commandArgs, context);
     }
     throw new CliError("UNKNOWN_COMMAND", `Unknown command: ${key2}`);
   }, parsed.globals.timeoutMs);
   const operationId = COMMAND_OPERATION_ID_BY_KEY.get(key2);
+  if (parsed.globals.help) {
+    if (!operationId)
+      return { execution };
+    if (!isRecord4(execution.data)) {
+      throw new CliError("COMMAND_FAILED", `Invalid help response for ${key2}.`);
+    }
+    const schemaCommand = `superdoc describe command ${operationId}`;
+    return {
+      execution: {
+        ...execution,
+        data: { ...execution.data, schemaCommand },
+        pretty: `${execution.pretty}
+
+Schema: ${schemaCommand}`
+      }
+    };
+  }
   const shouldValidateResponse = operationId != null && !hasCommandHelpFlag(args2);
   if (!shouldValidateResponse) {
     return { execution };
@@ -809913,7 +809962,7 @@ async function run(argv, ioOverrides, options = {}) {
       if (parsed.rest[0] === "uninstall" && !parsed.globals.help) {
         return await runUninstall(parsed.rest.slice(1), io);
       }
-      if (parsed.rest[0] === "call" && outputMode !== "json") {
+      if (parsed.rest[0] === "call" && outputMode !== "json" && !parsed.globals.help) {
         throw new CliError("INVALID_ARGUMENT", "call: only --output json is supported.");
       }
       if (!parsed.globals.help) {
@@ -809952,6 +810001,7 @@ var init_src8 = __esm(async () => {
   init_envelope();
   init_errors();
   init_input_readers();
+  init_guards();
   init_call();
   init_close();
   init_execute_code2();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/cli",
-  "version": "0.35.0-next.1",
+  "version": "0.35.0-next.3",
   "description": "Command-line interface for SuperDoc: inspect, convert, and edit .docx files from a terminal or a script.",
   "type": "module",
   "license": "AGPL-3.0",
@@ -29,13 +29,13 @@
     "fast-glob": "^3.3.3",
     "happy-dom": "^20.3.4",
     "ws": "^8.18.0",
-    "superdoc": "2.15.0-next.2",
+    "superdoc": "2.15.0-next.3",
     "y-websocket": "^3.0.0",
     "yjs": "13.6.31"
   },
   "devDependencies": {
     "@hocuspocus/server": "^2.13.6",
-    "@superdoc/sdk": "2.12.0-next.1",
+    "@superdoc/sdk": "2.12.0-next.3",
     "@superdoc/document-api": "0.1.0-alpha.0",
     "@superdoc/docx-engine": "0.14.0-next.2",
     "@types/bun": "^1.3.8",
@@ -51,11 +51,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@superdoc/cli-darwin-arm64": "0.35.0-next.1",
-    "@superdoc/cli-darwin-x64": "0.35.0-next.1",
-    "@superdoc/cli-linux-x64": "0.35.0-next.1",
-    "@superdoc/cli-linux-arm64": "0.35.0-next.1",
-    "@superdoc/cli-windows-x64": "0.35.0-next.1"
+    "@superdoc/cli-darwin-arm64": "0.35.0-next.3",
+    "@superdoc/cli-darwin-x64": "0.35.0-next.3",
+    "@superdoc/cli-linux-x64": "0.35.0-next.3",
+    "@superdoc/cli-linux-arm64": "0.35.0-next.3",
+    "@superdoc/cli-windows-x64": "0.35.0-next.3"
   },
   "scripts": {
     "predev": "node scripts/ensure-superdoc-build.js",