@dench.com/cli 3.8.1-staging.390 → 3.8.2-staging.392

package/lib/command-help.ts

@@ -1,16 +1,23 @@
-import { COMMAND_ARGUMENTS } from "./command-args";
+import { COMMAND_ARGUMENTS, normalizeCommandAlias } from "./command-args";
 import { apiOperations } from "./command-registry";
+import {
+  FILE_COMMAND_ARGUMENTS,
+  FILE_COMMAND_NOTES,
+} from "./file-command-contract";
 
-/** Literal command words only; never interpret a data value as a command. */
+/** Literal command words only; placeholders and quoted data are not commands. */
 function words(usage: string): string[] {
   const parts = usage
     .replace(/^dench\s+/, "")
     .split(/\s+/)
     .filter(Boolean);
-  const end = parts.findIndex((part) => /^[<[(-]/.test(part));
+  const end = parts.findIndex((part) => /^[<[('"|-]/.test(part));
   return end < 0 ? parts : parts.slice(0, end);
 }
-
+/** Resolve only actual CLI aliases, while callers retain the requested spelling. */
+export function normalizeHelpCommand(argv: readonly string[]): string[] {
+  return normalizeCommandAlias(argv.filter((arg) => arg !== "help"));
+}
 function matches(
   prefix: readonly string[],
   candidate: readonly string[],
@@ -19,28 +26,127 @@ function matches(
     candidate[index]?.split("|").includes(word),
   );
 }
+type Entry = {
+  usage: string;
+  description: string;
+  rank: number;
+  examples?: string[];
+  notes?: string[];
+};
+
+/** Even a dispatcher with no richer usage must disclose required arguments. */
+export function argumentUsage(
+  entry: (typeof COMMAND_ARGUMENTS)[number],
+): string {
+  if (entry.usage) return entry.usage;
+  const [min, max] = entry.positionals;
+  const count = max ?? min;
+  const positional = Array.from({ length: count }, (_, i) => {
+    const name = count === 1 ? "argument" : `argument${i + 1}`;
+    return i < min ? `<${name}>` : `[<${name}>]`;
+  });
+  if (max === null) positional.push("[arguments...]");
+  return [
+    `dench ${entry.command}`,
+    ...positional,
+    ...entry.values.map((flag) => `[${flag} <value>]`),
+    ...entry.switches.map((flag) => `[${flag}]`),
+  ].join(" ");
+}
+
+function nativeFileUsage(usage: string): boolean {
+  const path = words(usage);
+  return (
+    path[0] !== "files" ||
+    path.length < 2 ||
+    FILE_COMMAND_ARGUMENTS.some((entry) =>
+      matches(path.slice(0, 2), entry.command.split(" ")),
+    )
+  );
+}
+
+/** Prefer richer syntax PER command, never suppress uncovered sibling commands. */
+function preferredEntries(entries: Entry[]): Entry[] {
+  const groups = new Map<string, Entry[]>();
+  for (const entry of entries) {
+    const key = words(entry.usage).join(" ");
+    if (!key || !nativeFileUsage(entry.usage)) continue;
+    const existing = groups.get(key) ?? [];
+    const rank = existing[0]?.rank ?? -1;
+    if (entry.rank > rank) groups.set(key, [entry]);
+    else if (
+      entry.rank === rank &&
+      !existing.some((item) => item.usage === entry.usage)
+    ) {
+      groups.set(key, [...existing, entry]);
+    }
+  }
+  return [...groups.values()].flat();
+}
+
+function stripUsageComment(line: string): string {
+  let quote = "";
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === "\\" && quote !== "'") {
+      i++;
+      continue;
+    }
+    if (char === quote) quote = "";
+    else if (!quote && (char === "'" || char === '"')) quote = char;
+    else if (!quote && char === "#" && /\s/.test(line[i - 1] ?? ""))
+      return line.slice(0, i).trim();
+  }
+  return line.trim();
+}
+
+/** Preserve immediately following option lines without turning prose into syntax. */
+function usageEntries(text: string): Entry[] {
+  const entries: Entry[] = [];
+  let current: Entry | undefined;
+  let indent = 0;
+  for (const line of text.split("\n")) {
+    const value = line.trim();
+    const depth = line.length - line.trimStart().length;
+    if (value.startsWith("dench ")) {
+      current = {
+        usage: stripUsageComment(value).replace(/\\$/, "").trim(),
+        description: "",
+        rank: 3,
+      };
+      entries.push(current);
+      indent = depth;
+    } else if (current && depth > indent && /^(?:\[?-{1,2}|<)/.test(value)) {
+      current.usage += ` ${stripUsageComment(value).replace(/\\$/, "").trim()}`;
+    } else {
+      current = undefined;
+    }
+  }
+  return entries;
+}
 
 /** Registry metadata supplies discovery, never invokes command implementations. */
 export function commandHelp(argv: readonly string[], usageText = ""): string {
   const args = [...argv];
   if (args[0] === "help") args.shift();
-  const input = words(args.filter((arg) => arg !== "help").join(" "));
-  const usageLines = usageText
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line.startsWith("dench "));
-  const candidates = [
-    ...usageLines.map((usage) => ({ usage, description: "" })),
+  const requested = words(args.filter((arg) => arg !== "help").join(" "));
+  const input = normalizeHelpCommand(requested);
+  const aliased = input.join(" ") !== requested.join(" ");
+  if (input[0] === "files" && input[1] === "mkdir") {
+    return "dench files mkdir is not a native CLI command. Directory creation is available as files.mkdir through the API/SDK. Run dench files --help for supported file commands.";
+  }
+  const candidates: Entry[] = [
+    ...usageEntries(usageText),
     ...COMMAND_ARGUMENTS.map((entry) => ({
-      usage:
-        `dench ${entry.command} ${[...entry.values.map((flag) => `[${flag} <value>]`), ...entry.switches.map((flag) => `[${flag}]`)].join(" ")}`.trim(),
-      description: "",
+      usage: argumentUsage(entry),
+      description: entry.description ?? "",
+      rank: entry.usage ? 4 : 2,
+      examples: entry.examples,
+      notes: entry.notes,
     })),
     ...apiOperations
       .filter((op) => {
         if (!op.deprecated) return true;
-        // Keep exact legacy leaf help available without adding those commands
-        // back to the broad index or a parent family's discovery.
         const command = words(op.cli);
         return (
           command.length > 1 &&
@@ -53,41 +159,88 @@ export function commandHelp(argv: readonly string[], usageText = ""): string {
         description: op.deprecated
           ? `Compatibility command. ${op.summary}`
           : op.summary,
+        rank: 1,
       })),
   ];
+  const preferred = preferredEntries(candidates);
+  if (!input.length) {
+    const families = new Map<string, Set<string>>();
+    for (const entry of preferred) {
+      const path = words(entry.usage);
+      if (!path.length) continue;
+      const set = families.get(path[0]) ?? new Set<string>();
+      set.add(path.join(" "));
+      families.set(path[0], set);
+    }
+    return [
+      "Dench CLI",
+      "Usage: dench <command> [arguments] [options]",
+      "",
+      "Commands:",
+      ...[...families]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(
+          ([name, paths]) =>
+            `  ${name}${paths.size > 1 ? ` (${paths.size} commands)` : ""}`,
+        ),
+      "",
+      "Run dench <command> --help or dench <command> <subcommand> --help for syntax and examples.",
+      "Connect: dench signin. Inspect the workspace: dench context --json.",
+      "--json selects structured results. --help and -h run locally without authentication.",
+      "Backend overrides: --prod, --staging, --backend <name>, --host <url>.",
+      "Versioned references: dench reference --list --json.",
+    ].join("\n");
+  }
   let prefix = input;
   while (
     prefix.length &&
-    !candidates.some((item) => matches(prefix, words(item.usage)))
-  ) {
+    !preferred.some((item) => matches(prefix, words(item.usage)))
+  )
     prefix = prefix.slice(0, -1);
-  }
-  const selected = candidates.filter((item) =>
+  const selected = preferred.filter((item) =>
     matches(prefix, words(item.usage)),
   );
-  // Domain usage has real flag spellings; a backend schema is not a CLI parser.
-  const exactUsage = selected.filter((item) => !item.description);
-  const entries = exactUsage.length ? exactUsage : selected;
-  const seen = new Set<string>();
-  const lines = entries.filter((item) => {
-    if (seen.has(item.usage)) return false;
-    seen.add(item.usage);
-    return true;
-  });
-  const heading = `Usage: dench ${prefix.join(" ")}${prefix.length ? "" : "<command>"}`;
+  const lines = selected.slice(0, 12);
+  const exact = lines.filter(
+    (item) => words(item.usage).length === prefix.length,
+  );
+  const contract = COMMAND_ARGUMENTS.find(
+    (entry) => entry.command === prefix.join(" "),
+  );
+  const printedUsage = lines.map((item) => item.usage).join(" ");
+  const missingFlags = contract
+    ? [
+        ...contract.values
+          .filter((flag) => !printedUsage.includes(flag))
+          .map((flag) => `${flag} <value>`),
+        ...contract.switches.filter((flag) => !printedUsage.includes(flag)),
+      ]
+    : [];
+  const displayPath = aliased
+    ? requested.slice(0, prefix.length + requested.length - input.length)
+    : prefix;
   return [
-    heading,
-    ...lines
-      .slice(0, 12)
-      .map(
-        (item) =>
-          `  ${item.usage}${item.description ? `\n    ${item.description}` : ""}`,
-      ),
-    ...(lines.length > 12
+    `Usage: dench ${displayPath.join(" ")}${displayPath.length ? "" : "<command>"}`,
+    ...(aliased ? [`Alias of dench ${prefix.join(" ")}.`] : []),
+    ...lines.map(
+      (item) =>
+        `  ${item.usage}${item.description ? `\n    ${item.description}` : ""}`,
+    ),
+    ...(selected.length > 12
       ? [
-          `  ${lines.length - 12} more commands; add a subcommand before --help.`,
+          `  ${selected.length - 12} more commands; add a subcommand before --help.`,
         ]
       : []),
+    ...(missingFlags.length
+      ? [`Additional options: ${missingFlags.join(", ")}`]
+      : []),
+    ...exact.flatMap((item) => item.notes ?? []),
+    ...(prefix.length === 1 && prefix[0] === "files" ? FILE_COMMAND_NOTES : []),
+    ...exact.flatMap((item) =>
+      item.examples?.length
+        ? ["Examples:", ...item.examples.map((value) => `  ${value}`)]
+        : [],
+    ),
     "Options: --help, -h (local help); --json (structured command results).",
   ].join("\n");
 }

package/lib/file-command-contract.ts

@@ -0,0 +1,106 @@
+/** Native file commands implemented by cli/dench.ts. API operations are not
+ * necessarily CLI commands: files.mkdir is available only through the API/SDK. */
+type FileCommandArguments = {
+  command: string;
+  positionals: readonly [number, number];
+  values: string[];
+  switches: string[];
+  flagPositionals: Record<string, readonly [number, number | null]>;
+  usage: string;
+  description: string;
+  examples: string[];
+  notes: string[];
+};
+
+export const FILE_COMMAND_ARGUMENTS: FileCommandArguments[] = [
+  {
+    command: "files ls",
+    positionals: [0, 1] as const,
+    values: [],
+    switches: ["--recursive", "-r"],
+    flagPositionals: {},
+    usage: "dench files ls [<path>] [--recursive|-r] [--json]",
+    description: "List workspace files; the default path is /.",
+    examples: ["dench files ls /reports --recursive --json"],
+    notes: ["--recursive (or -r) includes descendants."],
+  },
+  {
+    command: "files cat",
+    positionals: [1, 1] as const,
+    values: [],
+    switches: [],
+    flagPositionals: {},
+    usage: "dench files cat <path> [--json]",
+    description: "Read a workspace file's inline text.",
+    examples: ["dench files cat /reports/summary.md"],
+    notes: [
+      "Use cat for virtual files such as IDENTITY.md and ORGANISATION.md, which have no download blob.",
+      "For binary files or files without inline text, use files download.",
+    ],
+  },
+  {
+    command: "files write",
+    positionals: [1, 1] as const,
+    values: [],
+    switches: [],
+    flagPositionals: {},
+    usage: "dench files write <path> [--json]",
+    description: "Write a workspace file's text from stdin.",
+    examples: [
+      "dench files write /reports/summary.md --json < ./summary.md",
+      "printf '%s\\n' 'Report ready.' | dench files write /reports/summary.md --json",
+    ],
+    notes: [
+      "The destination path is required. Pipe or redirect the raw UTF-8 file text into stdin.",
+      "--json controls the result format; stdin is file content, not an API JSON envelope. No --stdin, --content or --file flag is supported.",
+      "Writing replaces the complete text; empty stdin writes an empty file.",
+    ],
+  },
+  {
+    command: "files mv",
+    positionals: [2, 2] as const,
+    values: [],
+    switches: [],
+    flagPositionals: {},
+    usage: "dench files mv <src> <dst> [--json]",
+    description: "Move or rename a workspace file or directory.",
+    examples: ["dench files mv /reports/draft.md /reports/summary.md --json"],
+    notes: ["Both paths refer to workspace storage, not local disk."],
+  },
+  {
+    command: "files rm",
+    positionals: [1, 1] as const,
+    values: [],
+    switches: ["--recursive", "-r"],
+    flagPositionals: {},
+    usage: "dench files rm <path> [--recursive|-r] [--json]",
+    description: "Remove a workspace file or directory.",
+    examples: ["dench files rm /reports/old --recursive --json"],
+    notes: [
+      "Directories require --recursive (or -r). An absent path is already removed.",
+    ],
+  },
+  {
+    command: "files download",
+    positionals: [1, 2] as const,
+    values: [],
+    switches: ["--url"],
+    flagPositionals: {},
+    usage: "dench files download <path> [<local-dest>] [--url] [--json]",
+    description:
+      "Download workspace bytes to local disk, or print a signed URL.",
+    examples: [
+      "dench files download /reports/summary.pdf ./summary.pdf --json",
+      "dench files download /reports/summary.pdf --url --json",
+    ],
+    notes: [
+      "Without --url, downloads directories recursively and defaults the local destination to the path's basename (/ becomes workspace).",
+      "--url prints a short-lived signed URL for one stored file instead of saving locally; local-dest is unused in this mode.",
+    ],
+  },
+];
+
+export const FILE_COMMAND_NOTES = [
+  "Workspace paths are POSIX paths under /workspace; /reports/a.md and /workspace/reports/a.md address the same file.",
+  "These commands read or update workspace storage. Use dench stage to upload local files or directories.",
+];