@controllerai/cli 0.2.0

package/dist/argv.js

@@ -0,0 +1,124 @@
+/**
+ * Ids are 12 characters from a URL-safe 64-symbol alphabet that includes `-`,
+ * so roughly one id in 64 begins with a hyphen — `-4xdQMkNx5I`, `-2h39vCLrwYj`.
+ * Passed as a positional, commander reads it as an option and fails with
+ * "unknown option", which looks like a caller mistake but is ours.
+ *
+ * Two defences, both applied before commander ever sees the arguments:
+ *
+ *   1. `--id <value>` works on every command that takes a positional id. The
+ *      pair is lifted out here and re-appended after a `--` terminator, so the
+ *      value reaches the action as the positional it always was and no command
+ *      has to be rewritten to accept it.
+ *   2. A bare single-dash token that is not a declared flag and has the shape of
+ *      an id is rescued the same way, so the obvious spelling just works.
+ *
+ * Double-dash tokens are deliberately NOT rescued: `--jsonn` is a typo, not an
+ * id, and silently turning it into an operand would trade a clear error for a
+ * confusing one. Those get a pointed message instead (see `unknownOptionHint`).
+ */
+/** `-` followed by at least six id characters — never a real short flag. */
+const ID_SHAPED = /^-[A-Za-z0-9_-]{6,}$/;
+/** Every long and short flag declared anywhere in the command tree. */
+export const collectFlags = (command, into = new Set()) => {
+    for (const option of command.options) {
+        if (option.long)
+            into.add(option.long);
+        if (option.short)
+            into.add(option.short);
+    }
+    for (const sub of command.commands)
+        collectFlags(sub, into);
+    return into;
+};
+export const normalizeArgv = (argv, knownFlags) => {
+    const kept = [];
+    const rescued = [];
+    let index = 0;
+    while (index < argv.length) {
+        const token = argv[index];
+        // Everything after an explicit `--` is already operands; leave it alone.
+        if (token === '--') {
+            kept.push(...argv.slice(index));
+            return kept;
+        }
+        if (token === '--id') {
+            const value = argv[index + 1];
+            if (value === undefined) {
+                // Let commander produce its own "argument missing" error.
+                kept.push(token);
+                index += 1;
+                continue;
+            }
+            rescued.push(value);
+            index += 2;
+            continue;
+        }
+        if (token.startsWith('--id=')) {
+            rescued.push(token.slice('--id='.length));
+            index += 1;
+            continue;
+        }
+        if (!token.startsWith('--') && ID_SHAPED.test(token) && !knownFlags.has(token)) {
+            rescued.push(token);
+            index += 1;
+            continue;
+        }
+        kept.push(token);
+        index += 1;
+    }
+    return rescued.length ? [...kept, '--', ...rescued] : kept;
+};
+export const unknownOptionHint = (flag) => `If "${flag}" is an id beginning with "-", pass it as \`--id ${flag.replace(/^-+/, '-')}\`.\n` +
+    'Every command that takes a positional id also accepts `--id <value>`, which is the ' +
+    'reliable spelling for hyphen-leading ids (they are common: the id alphabet includes "-").';
+/**
+ * Commander writes `error: unknown option '--x'` and then the whole help block,
+ * so a hint appended at exit time lands below the help and is easy to miss.
+ * Splice it onto the error line itself instead, on every command in the tree —
+ * `configureOutput` is per-command and is not inherited by subcommands that were
+ * created before it was set.
+ */
+export const explainUnknownOptions = (command) => {
+    const write = (chunk) => {
+        const match = /unknown option '(-[^']+)'/.exec(chunk);
+        // When commander already offers a near-miss suggestion the token is a typo,
+        // not an id; adding the id hint on top would be noise.
+        const isTypo = /Did you mean/.test(chunk);
+        process.stderr.write(match && !isTypo ? `${chunk}${unknownOptionHint(match[1])}\n\n` : chunk);
+    };
+    command.configureOutput({ writeErr: write });
+    for (const sub of command.commands)
+        explainUnknownOptions(sub);
+};
+/** `exitOverride` is only inherited by subcommands created after it is set. */
+export const applyExitOverride = (command, handler) => {
+    command.exitOverride(handler);
+    for (const sub of command.commands)
+        applyExitOverride(sub, handler);
+};
+/**
+ * `--json`, `--workflow` and `--api-url` are documented as global, and an agent
+ * reasonably writes them AFTER the subcommand (`cai flow list --json`).
+ * Commander only parses an option on the command that declares it, so they are
+ * declared on every command in the tree rather than the root alone.
+ *
+ * No defaults are attached: an absent flag must read as `undefined` so that
+ * `globalOpt()` keeps walking up to an ancestor that did set it. A `false`
+ * default on a leaf would shadow a `--json` given before the subcommand.
+ */
+export const addGlobalOptions = (command) => {
+    for (const sub of command.commands) {
+        const declared = new Set(sub.options.map(o => o.long));
+        if (!declared.has('--json'))
+            sub.option('--json', 'machine-readable output on stdout');
+        if (!declared.has('--workflow')) {
+            sub.option('--workflow <id>', 'workflow id (overrides `cai use` and CAI_WORKFLOW)');
+        }
+        if (!declared.has('--api-url')) {
+            sub.option('--api-url <url>', 'backend base URL (overrides CAI_API_URL)');
+        }
+        addGlobalOptions(sub);
+    }
+};
+//# sourceMappingURL=argv.js.map

package/dist/argv.js.map

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