@swmansion/argent 0.15.0 → 0.15.1-next.0

package/dist/cli.js

@@ -30,6 +30,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { BUNDLED_RUNTIME_PATHS } from "./bundled-paths.js";
 import { installFatalHandlers } from "./fatal-handlers.js";
+import { INSTALLER_COMMAND_META, installerHelpRequested, printInstallerHelp, } from "./installer-help.js";
 const PACKAGE_NAME = "@swmansion/argent";
 function getInstalledVersion() {
     try {
@@ -46,6 +47,16 @@ function getInstalledVersion() {
 const [, , command, ...rest] = process.argv;
 const isMcpServer = command === "mcp";
 installFatalHandlers({ isMcpServer });
+// One installer row of the command table: the command's one-line summary plus
+// its indented detail lines, both from INSTALLER_COMMAND_META. The summary is
+// shared with the per-command `--help`, so the two can't drift; the details
+// are table-only prose kept in the meta so each command's help text lives in
+// one place.
+function installerHelpEntry(command) {
+    const meta = INSTALLER_COMMAND_META[command];
+    const details = (meta.details ?? []).map((line) => `\n              ${line}`).join("");
+    return `${meta.summary}${details}`;
+}
 function printHelp() {
     const version = getInstalledVersion() ?? "unknown";
     console.log(`
@@ -55,19 +66,14 @@ Usage: argent <command> [options]
 
 Commands:
   mcp         Start the MCP stdio server (used by editors)
-  init        Initialize argent in the current workspace (MCP server + skills)
-              (--global [default] installs on PATH; --local commits a
-              devDependency setup the whole team gets on \`npm install\`)
-  install     Alias for init
-  update      Check for updates and refresh configuration
-              (acts on the present install — both when a global install and a
-              project devDependency coexist; --global/--local select explicitly)
-  uninstall   Remove argent configuration from the workspace
-              (--global/--local choose which install — package and its
-              configs — is removed)
-  remove      Alias for uninstall
+  init        ${installerHelpEntry("init")}
+  install     ${installerHelpEntry("install")}
+  update      ${installerHelpEntry("update")}
+  uninstall   ${installerHelpEntry("uninstall")}
+  remove      ${installerHelpEntry("remove")}
   tools       List tools exposed by the tool-server
   run         Invoke a tool by name (use \`argent run <tool> --help\` for flags)
+  flow        Run a saved flow (use \`argent flow --help\` for options)
   server      Manage the shared tool-server (start / status / stop / logs)
   lens        Open Argent Lens bound to a fresh coding-agent session (macOS)
   link        Route client requests to a remote tool-server
@@ -99,6 +105,16 @@ async function loadCli() {
     return (await import("./cli-cmds.mjs"));
 }
 async function main() {
+    // The installer subcommands (init / install / update / uninstall / remove)
+    // forward their argv straight to the side-effecting installer functions,
+    // which do not short-circuit on `--help` — so `argent uninstall --help`
+    // would run the real (destructive) command. Intercept help for exactly that
+    // set before dispatching. All other subcommands handle `--help` themselves.
+    if (installerHelpRequested(command, rest)) {
+        // installerHelpRequested only returns true for an InstallerCommand.
+        printInstallerHelp(command);
+        return;
+    }
     switch (command) {
         case "mcp":
             return (await loadMcp()).startMcpServer({ paths: BUNDLED_RUNTIME_PATHS });
@@ -114,6 +130,8 @@ async function main() {
             return (await loadCli()).tools(rest, { paths: BUNDLED_RUNTIME_PATHS });
         case "run":
             return (await loadCli()).run(rest, { paths: BUNDLED_RUNTIME_PATHS });
+        case "flow":
+            return (await loadCli()).flow(rest, { paths: BUNDLED_RUNTIME_PATHS });
         case "server":
             return (await loadCli()).server(rest, { paths: BUNDLED_RUNTIME_PATHS });
         case "lens":

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAIlC,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAEzC,SAAS,mBAAmB;IAC1B,IAAI,CAAC;QACH,uEAAuE;QACvE,oDAAoD;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACxE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAyB,CAAC;QACjF,OAAO,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,EAAE,AAAD,EAAG,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;AAC5C,MAAM,WAAW,GAAG,OAAO,KAAK,KAAK,CAAC;AAEtC,oBAAoB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;AAEtC,SAAS,SAAS;IAChB,MAAM,OAAO,GAAG,mBAAmB,EAAE,IAAI,SAAS,CAAC;IACnD,OAAO,CAAC,GAAG,CAAC;UACJ,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAkCN,YAAY;CACtB,CAAC,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,2EAA2E;AAC3E,mEAAmE;AACnE,KAAK,UAAU,aAAa;IAC1B,OAAO,CAAC,MAAM,MAAM,CAAC,iBAAwB,CAAC,CAAqB,CAAC;AACtE,CAAC;AACD,KAAK,UAAU,OAAO;IACpB,OAAO,CAAC,MAAM,MAAM,CAAC,kBAAyB,CAAC,CAAe,CAAC;AACjE,CAAC;AACD,KAAK,UAAU,OAAO;IACpB,OAAO,CAAC,MAAM,MAAM,CAAC,gBAAuB,CAAC,CAAe,CAAC;AAC/D,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,KAAK;YACR,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,cAAc,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC;QAC5E,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS;YACZ,OAAO,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,KAAK,QAAQ;YACX,OAAO,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9C,KAAK,WAAW,CAAC;QACjB,KAAK,QAAQ;YACX,OAAO,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACjD,KAAK,OAAO;YACV,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC;QACzE,KAAK,KAAK;YACR,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC;QACvE,KAAK,QAAQ;YACX,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC;QAC1E,KAAK,MAAM;YACT,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC;QACxE,KAAK,MAAM;YACT,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtC,KAAK,QAAQ;YACX,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxC,KAAK,QAAQ;YACX,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxC,KAAK,SAAS;YACZ,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzC,KAAK,OAAO;YACV,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvC,KAAK,WAAW;YACd,OAAO,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3C,KAAK,WAAW,CAAC;QACjB,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,SAAS,CAAC,CAAC;YAChD,OAAO;QACT,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI,CAAC;QACV;YACE,SAAS,EAAE,CAAC;YACZ,IAAI,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;IACL,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/installer-help.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Help handling for the installer subcommands (init / install / update /
+ * uninstall / remove).
+ *
+ * These commands forward their argv straight to the side-effecting installer
+ * functions, which do not themselves short-circuit on `--help`. Without an
+ * explicit guard `argent uninstall --help` runs the real uninstall — it even
+ * opens the destructive "Remove argent configuration from this workspace?"
+ * prompt. The dispatcher checks `installerHelpRequested` before dispatching so
+ * a help request prints usage and returns without loading or invoking any
+ * installer code.
+ *
+ * The other subcommands (run / tools / server / link / flags / …) handle
+ * `--help` themselves, so they are deliberately excluded here — intercepting
+ * them would swallow their own command-specific help.
+ *
+ * This module is also the single source of truth for each installer command's
+ * help text: the top-level `argent --help` table in cli.ts reads the summary
+ * and detail lines from `INSTALLER_COMMAND_META` so the two can't drift.
+ */
+/** Installer subcommands that lack their own `--help` handling. */
+export declare const INSTALLER_COMMANDS: readonly ["init", "install", "update", "uninstall", "remove"];
+export type InstallerCommand = (typeof INSTALLER_COMMANDS)[number];
+export declare function isInstallerCommand(command: string | undefined): command is InstallerCommand;
+/**
+ * Flags that consume the next argv token, mirroring the real parsers
+ * (`extractFlag` in init-args.ts, the lookahead loops in update.ts). A
+ * bareword `help` immediately after one of these is that flag's value, not a
+ * help request. `--project-root` (update) is agent-internal — parsed but
+ * deliberately absent from the help text. Kept in sync with the parsers by
+ * test/installer-flags-sync.test.ts.
+ */
+export declare const VALUE_TAKING_FLAGS: Record<InstallerCommand, readonly string[]>;
+/**
+ * True when `command` is an installer subcommand and `rest` requests help. Pure
+ * — the dispatcher uses it to short-circuit before running any side-effecting
+ * installer code.
+ *
+ * Help is recognised from a help flag anywhere in `rest` (see `isHelpFlag`) or
+ * the bareword `help` (case-insensitive) in any position — EXCEPT directly
+ * after a value-taking flag, where it is that flag's value: `argent init
+ * --from help` names a package literally called `help` and must reach the
+ * installer. The bareword matters on the destructive path: `argent uninstall
+ * --yes help` would otherwise run a prompt-free uninstall (`--yes` skips the
+ * confirmation).
+ */
+export declare function installerHelpRequested(command: string | undefined, rest: string[]): boolean;
+interface InstallerOption {
+    /** Flag spelling as shown to the user, e.g. `--from <path>` or `--yes, -y`. */
+    flag: string;
+    description: string;
+}
+interface InstallerCommandMeta {
+    /**
+     * One-line summary shared with the top-level `argent --help` table. No
+     * trailing period — cli.ts renders it inline in a command list, and
+     * `printInstallerHelp` appends its own.
+     */
+    summary: string;
+    /**
+     * Extra lines rendered indented under the summary in the top-level command
+     * table (cli.ts). Per-command `--help` conveys the same information through
+     * the option descriptions instead.
+     */
+    details?: string[];
+    /** Usage line, e.g. `argent init [options]`. */
+    usage: string;
+    /** Real flags this command parses. Empty for aliases (see `aliasOf`). */
+    options: InstallerOption[];
+    /** When set, this command is an alias; its help defers to the target's. */
+    aliasOf?: InstallerCommand;
+}
+/**
+ * How each installer subcommand is described in help — its summary and detail
+ * lines (the sole copy, also rendered by the top-level table in cli.ts), usage,
+ * and options. The option lists mirror the flags each installer actually parses
+ * (init-args.ts, update.ts, uninstall.ts, install-targets.ts in
+ * packages/argent-installer); test/installer-flags-sync.test.ts fails when they
+ * drift from the parsers.
+ */
+export declare const INSTALLER_COMMAND_META: Record<InstallerCommand, InstallerCommandMeta>;
+/**
+ * Print the usage block for an installer subcommand — usage line, summary, the
+ * command's options (or a pointer to the aliased command), and a footer.
+ * Read-only: no network, no wizard, no prompt.
+ */
+export declare function printInstallerHelp(command: InstallerCommand): void;
+export {};

package/dist/installer-help.js

@@ -0,0 +1,191 @@
+/**
+ * Help handling for the installer subcommands (init / install / update /
+ * uninstall / remove).
+ *
+ * These commands forward their argv straight to the side-effecting installer
+ * functions, which do not themselves short-circuit on `--help`. Without an
+ * explicit guard `argent uninstall --help` runs the real uninstall — it even
+ * opens the destructive "Remove argent configuration from this workspace?"
+ * prompt. The dispatcher checks `installerHelpRequested` before dispatching so
+ * a help request prints usage and returns without loading or invoking any
+ * installer code.
+ *
+ * The other subcommands (run / tools / server / link / flags / …) handle
+ * `--help` themselves, so they are deliberately excluded here — intercepting
+ * them would swallow their own command-specific help.
+ *
+ * This module is also the single source of truth for each installer command's
+ * help text: the top-level `argent --help` table in cli.ts reads the summary
+ * and detail lines from `INSTALLER_COMMAND_META` so the two can't drift.
+ */
+/** Installer subcommands that lack their own `--help` handling. */
+export const INSTALLER_COMMANDS = ["init", "install", "update", "uninstall", "remove"];
+export function isInstallerCommand(command) {
+    return INSTALLER_COMMANDS.includes(command);
+}
+/**
+ * True when `arg` is a help flag. Accepted spellings, all case-insensitive:
+ * `--help`, `-h`, `--help=<anything>`, single-dash `-help`, and an em/en-dash
+ * `—help` (smart-dash editors rewrite a pasted `--` into one). Anything else —
+ * e.g. `/help` or `--helpme` — is NOT treated as help and falls through to the
+ * real command, where uninstall's interactive confirmation still guards the
+ * destructive path (unless `--yes` was also passed).
+ */
+function isHelpFlag(arg) {
+    // Smart-dash normalization: a leading em/en dash stands for the `--` it was
+    // rewritten from.
+    const lower = arg.toLowerCase().replace(/^[—–]/, "--");
+    return lower === "--help" || lower === "-h" || lower === "-help" || lower.startsWith("--help=");
+}
+/**
+ * Flags that consume the next argv token, mirroring the real parsers
+ * (`extractFlag` in init-args.ts, the lookahead loops in update.ts). A
+ * bareword `help` immediately after one of these is that flag's value, not a
+ * help request. `--project-root` (update) is agent-internal — parsed but
+ * deliberately absent from the help text. Kept in sync with the parsers by
+ * test/installer-flags-sync.test.ts.
+ */
+export const VALUE_TAKING_FLAGS = {
+    init: ["--from"],
+    install: ["--from"],
+    update: ["--version", "--project-root"],
+    uninstall: [],
+    remove: [],
+};
+/**
+ * True when `command` is an installer subcommand and `rest` requests help. Pure
+ * — the dispatcher uses it to short-circuit before running any side-effecting
+ * installer code.
+ *
+ * Help is recognised from a help flag anywhere in `rest` (see `isHelpFlag`) or
+ * the bareword `help` (case-insensitive) in any position — EXCEPT directly
+ * after a value-taking flag, where it is that flag's value: `argent init
+ * --from help` names a package literally called `help` and must reach the
+ * installer. The bareword matters on the destructive path: `argent uninstall
+ * --yes help` would otherwise run a prompt-free uninstall (`--yes` skips the
+ * confirmation).
+ */
+export function installerHelpRequested(command, rest) {
+    if (!isInstallerCommand(command))
+        return false;
+    if (rest.some(isHelpFlag))
+        return true;
+    const valueFlags = VALUE_TAKING_FLAGS[command];
+    return rest.some((arg, i) => arg.toLowerCase() === "help" && (i === 0 || !valueFlags.includes(rest[i - 1])));
+}
+const NON_INTERACTIVE_OPTION = {
+    flag: "--yes, -y",
+    description: "Run without prompts, accepting defaults.",
+};
+const NO_TELEMETRY_OPTION = {
+    flag: "--no-telemetry",
+    description: "Opt out of anonymous telemetry for this run.",
+};
+/**
+ * How each installer subcommand is described in help — its summary and detail
+ * lines (the sole copy, also rendered by the top-level table in cli.ts), usage,
+ * and options. The option lists mirror the flags each installer actually parses
+ * (init-args.ts, update.ts, uninstall.ts, install-targets.ts in
+ * packages/argent-installer); test/installer-flags-sync.test.ts fails when they
+ * drift from the parsers.
+ */
+export const INSTALLER_COMMAND_META = {
+    init: {
+        summary: "Initialize argent in the current workspace (MCP server + skills + rules)",
+        details: [
+            "(--global [default] installs on PATH; --local commits a",
+            "devDependency setup the whole team gets on `npm install`)",
+        ],
+        usage: "argent init [options]",
+        options: [
+            NON_INTERACTIVE_OPTION,
+            NO_TELEMETRY_OPTION,
+            {
+                flag: "--from <path>",
+                description: "Install from a local tarball or package spec instead of the npm release.",
+            },
+            {
+                flag: "--global",
+                description: "Install on PATH for this machine (the default).",
+            },
+            {
+                flag: "--local",
+                description: "Commit a devDependency setup the whole team gets on `npm install`.",
+            },
+        ],
+    },
+    install: {
+        summary: "Alias for init",
+        usage: "argent install [options]",
+        options: [],
+        aliasOf: "init",
+    },
+    update: {
+        summary: "Check for updates and refresh configuration",
+        details: [
+            "(acts on the present install — both when a global install and a",
+            "project devDependency coexist; --global/--local select explicitly)",
+        ],
+        usage: "argent update [options]",
+        options: [
+            NON_INTERACTIVE_OPTION,
+            NO_TELEMETRY_OPTION,
+            {
+                flag: "--version <version>",
+                description: "Update to a specific version instead of the latest.",
+            },
+            {
+                flag: "--global",
+                description: "Act on the global (PATH) install when both kinds coexist.",
+            },
+            {
+                flag: "--local",
+                description: "Act on the project-local (devDependency) install when both kinds coexist.",
+            },
+        ],
+    },
+    uninstall: {
+        summary: "Remove argent configuration from the current workspace",
+        details: ["(--global/--local choose which install — package and its", "configs — is removed)"],
+        usage: "argent uninstall [options]",
+        options: [
+            { flag: "--yes, -y", description: "Skip the confirmation prompt." },
+            {
+                flag: "--global",
+                description: "Remove the global (PATH) install — the package and its configs.",
+            },
+            {
+                flag: "--local",
+                description: "Remove the project-local (devDependency) install — the package and its configs.",
+            },
+        ],
+    },
+    remove: {
+        summary: "Alias for uninstall",
+        usage: "argent remove [options]",
+        options: [],
+        aliasOf: "uninstall",
+    },
+};
+/**
+ * Print the usage block for an installer subcommand — usage line, summary, the
+ * command's options (or a pointer to the aliased command), and a footer.
+ * Read-only: no network, no wizard, no prompt.
+ */
+export function printInstallerHelp(command) {
+    const meta = INSTALLER_COMMAND_META[command];
+    const lines = ["", `Usage: ${meta.usage}`, "", `${meta.summary}.`];
+    if (meta.aliasOf) {
+        lines.push("", `Run \`argent ${meta.aliasOf} --help\` to see its options.`);
+    }
+    else if (meta.options.length > 0) {
+        const width = Math.max(...meta.options.map((o) => o.flag.length));
+        lines.push("", "Options:");
+        for (const option of meta.options) {
+            lines.push(`  ${option.flag.padEnd(width)}  ${option.description}`);
+        }
+    }
+    lines.push("", "Run `argent --help` for the full list of commands.", "");
+    console.log(lines.join("\n"));
+}
+//# sourceMappingURL=installer-help.js.map

package/dist/installer-help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer-help.js","sourceRoot":"","sources":["../src/installer-help.ts"],"names":[],"mappings":"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"}