@dench.com/cli 3.8.0-staging.389 → 3.8.2-staging.391

package/lib/campaign-timeline.ts

@@ -8,6 +8,8 @@ export type TimelineRun = {
   startedAt?: number;
   waitUntil?: number;
   retryAt?: number;
+  /** A wait for acceptance: when it stops waiting either way. */
+  timeoutAt?: number;
   completedAt?: number;
   emailMessageId?: string;
   lastError?: string;
@@ -49,6 +51,8 @@ export type TimelineResult = {
     type: string;
     order: number;
     waitHours?: number;
+    /** If / else and Wait until they accept steps: what they check. */
+    label?: string;
   }>;
   runs: TimelineRun[];
   emailMessages: TimelineEmail[];
@@ -63,6 +67,10 @@ export type TimelineStep = {
   outcome: string;
   at: number | null;
   detail: string[];
+  /** An If / else or a wait for acceptance: the path it took. */
+  branch?: "yes" | "no";
+  /** Still waiting for them to accept: when it stops waiting. */
+  acceptanceDeadline?: number;
   subject?: string;
   text?: string;
   error?: string;
@@ -101,16 +109,66 @@ const EMAIL_STATUS: Record<string, string> = {
   failed: "could not send",
 };
 
+function resultField(result: unknown, key: string): unknown {
+  return result && typeof result === "object"
+    ? (result as Record<string, unknown>)[key]
+    : undefined;
+}
+
 function skipReason(result: unknown): string {
-  const reason =
-    result && typeof result === "object"
-      ? (result as { reason?: unknown }).reason
-      : undefined;
+  const reason = resultField(result, "reason");
   return (typeof reason === "string" && SKIP_REASONS[reason]) || "Skipped";
 }
 
+/** Why an If / else or a wait for acceptance took its No path. */
+const NO_REASONS: Record<string, string> = {
+  missing_linkedin_identity: "no LinkedIn profile",
+  missing_email_identity: "no email address",
+  linkedin_connection_timeout: "they did not accept in time",
+  linkedin_invite_withdrawn: "the connection request was withdrawn",
+  linkedin_invite_not_sent: "no connection request went out",
+};
+
+const LOGIC_TYPES = new Set(["condition", "wait_for_connection"]);
+
+export function branchOf(run: TimelineRun): "yes" | "no" | undefined {
+  if (!LOGIC_TYPES.has(run.type) || run.status !== "sent") return undefined;
+  const branch = resultField(run.result, "branch");
+  return branch === "yes" || branch === "no" ? branch : undefined;
+}
+
+/** What the editor calls each exit: Yes / No, or Accepted / Not accepted. */
+export function branchExitLabel(type: string, branch: "yes" | "no"): string {
+  if (type === "wait_for_connection")
+    return branch === "yes" ? "Accepted" : "Not accepted";
+  return branch === "yes" ? "Yes" : "No";
+}
+
+function logicOutcome(run: TimelineRun): string | undefined {
+  if (!LOGIC_TYPES.has(run.type)) return undefined;
+  const branch = branchOf(run);
+  if (branch) {
+    const reason = resultField(run.result, "reason");
+    const why =
+      branch === "no" && typeof reason === "string" ? NO_REASONS[reason] : "";
+    return `${branchExitLabel(run.type, branch)}${why ? ` (${why})` : ""}`;
+  }
+  if (run.status === "sent") return "Done";
+  if (run.type === "wait_for_connection")
+    return run.status === "waiting"
+      ? "Waiting for them to accept"
+      : run.status === "queued" || run.status === "running"
+        ? "Checking whether they accepted"
+        : undefined;
+  return ["queued", "running", "waiting"].includes(run.status)
+    ? "Checking"
+    : undefined;
+}
+
 function outcomeOf(run: TimelineRun): string {
   if (run.status === "skipped") return skipReason(run.result);
+  const logic = logicOutcome(run);
+  if (logic) return logic;
   if (run.status === "sent") {
     if (run.type === "wait") return "Waited";
     if (run.type === "linkedin_visit") return "Visited";
@@ -153,6 +211,11 @@ export function timelineSteps(result: TimelineResult): TimelineStep[] {
         run.status === "sent" || run.status === "skipped"
           ? undefined
           : (run.lastError ?? email?.lastError)?.trim();
+      const branch = branchOf(run);
+      const waitingForAccept =
+        run.type === "wait_for_connection" &&
+        run.status === "waiting" &&
+        typeof run.timeoutAt === "number";
       return {
         step: (step?.order ?? run.stepIndex) + 1,
         stepId: String(run.stepId),
@@ -167,6 +230,8 @@ export function timelineSteps(result: TimelineResult): TimelineStep[] {
           run.scheduledAt ??
           null,
         detail,
+        ...(branch ? { branch } : {}),
+        ...(waitingForAccept ? { acceptanceDeadline: run.timeoutAt } : {}),
         ...(email?.subject ? { subject: email.subject } : {}),
         ...(text ? { text } : {}),
         ...(problem ? { error: problem } : {}),

package/lib/command-args.ts

@@ -1,4 +1,5 @@
 import { CliArgError, missingFlagValue } from "./cli-args";
+import { FILE_COMMAND_ARGUMENTS } from "./file-command-contract";
 
 type PositionalArity = readonly [min: number, max: number | null];
 
@@ -8,6 +9,10 @@ type CommandArguments = {
   switches: string[];
   positionals: PositionalArity;
   flagPositionals: Record<string, PositionalArity>;
+  usage?: string;
+  description?: string;
+  examples?: string[];
+  notes?: string[];
 };
 const spec = (
   command: string,
@@ -138,9 +143,7 @@ export const COMMAND_ARGUMENTS = [
   ...["delete", "enable", "disable"].map((verb) =>
     spec(`cron ${verb}`, [1, 1]),
   ),
-  spec("files rm", [1, 1], "", "--recursive -r"),
-  spec("files mv", [2, 2]),
-  spec("files write", [1, 1]),
+  ...FILE_COMMAND_ARGUMENTS,
   spec("stage", [1, 2], "", "--clean"),
   ...["identity", "organisation", "user", "tools", "mem"].flatMap((group) =>
     ["edit", "set"].map((verb) =>
@@ -200,16 +203,30 @@ export const COMMAND_ARGUMENTS = [
   browserSpec("stop", [0, 0]),
 ];
 
-export function assertDeclaredCommandFlags(argv: readonly string[]): void {
-  const boundary = argv.indexOf("--");
-  const args = argv
-    .slice(0, boundary < 0 ? undefined : boundary)
-    .filter((arg) => arg !== "--json");
+/** Keep compatibility aliases identical in validation and local discovery. */
+export function normalizeCommandAlias(argv: readonly string[]): string[] {
+  const args = [...argv];
   if (["routine", "routines"].includes(args[0])) args[0] = "cron";
   if (["ad", "adline"].includes(args[0])) args[0] = "ads";
-  if (args[0] === "agent" && ["new", "send"].includes(args[1]))
+  if (args[0] === "agent" && ["new", "send", "follow"].includes(args[1]))
     args[0] = "chat";
   if (args[0] === "crm" && args[1] === "members") args.shift();
+  if (args[0] === "campaigns") args[0] = "campaign";
+  return args;
+}
+
+export function assertDeclaredCommandFlags(argv: readonly string[]): void {
+  const boundary = argv.indexOf("--");
+  const args = normalizeCommandAlias(
+    argv
+      .slice(0, boundary < 0 ? undefined : boundary)
+      .filter((arg) => arg !== "--json"),
+  );
+  if (args[0] === "files" && boundary >= 0) {
+    throw new CliArgError(
+      "dench files does not accept a child-command separator (--). Run `dench files --help` for usage.",
+    );
+  }
   const contract = COMMAND_ARGUMENTS.find(({ command }) =>
     command.split(" ").every((part, index) => args[index] === part),
   );

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/command-registry.ts

@@ -4183,7 +4183,7 @@ const rawApiOperations = [
     id: "campaigns.analytics",
     group: "campaigns",
     summary:
-      "Campaign funnel: enrolled, contacted, invited, accepted, messaged, replied, opens and clicks.",
+      "Campaign funnel: enrolled, contacted, invited, accepted, messaged, replied, opens and clicks, and for a workflow how many people took each If / else and Wait for them to accept path (branchStats).",
     cli: "dench campaign get",
     method: "GET",
     path: "/campaigns/{sequenceId}/analytics",
@@ -4237,7 +4237,7 @@ const rawApiOperations = [
     id: "campaigns.steps.replace",
     group: "campaigns",
     summary:
-      "Replace every step of a draft campaign (email, wait, LinkedIn visit, connection request, message, post reaction, InMail). Steps are checked first: a field the step type would drop, missing text or {TOKEN} single braces are rejected, not saved. Configure sender pools on the campaign; step sender ids are legacy-only.",
+      "Replace every step of a draft campaign (email, wait, LinkedIn visit, connection request, message, post reaction, InMail, If / else, Wait for them to accept). A workflow (stepModel workflow, or steps with key, next, yesNext or noNext) branches: condition and wait_for_connection steps continue on yesNext or noNext, other steps on next; each points at another step's key or end. Steps are checked first: a field the step type would drop, missing text, {TOKEN} single braces or paths that don't hold together are rejected, not saved. Configure sender pools on the campaign; step sender ids are legacy-only.",
     cli: "dench campaign steps set",
     method: "PUT",
     path: "/campaigns/{sequenceId}/steps",
@@ -4249,7 +4249,7 @@ const rawApiOperations = [
     id: "campaigns.steps.update",
     group: "campaigns",
     summary:
-      "Edit the text, waits and conditions of a launched (or paused) campaign's steps in place. Each step keeps its id, type and place; pass the stepId and the updatedAt you read, and only the fields you change. Messages already sent or being prepared keep their text; drafts use campaigns.steps.replace.",
+      "Edit the text, waits and conditions of a launched (or paused) campaign's steps in place. Each step keeps its id, type and place; pass the stepId and the updatedAt you read, and only the fields you change. A workflow keeps its paths and what each If / else checks (key, next, yesNext, noNext, check, conditionField, conditionOperator); conditionValue and acceptance waits stay editable. Messages already sent or being prepared keep their text; drafts use campaigns.steps.replace.",
     cli: "dench campaign steps edit",
     method: "PATCH",
     path: "/campaigns/{sequenceId}/steps",

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.",
+];