workos 0.13.4 → 0.14.0

package/dist/utils/interaction-mode.js

@@ -0,0 +1,102 @@
+const VALID_MODES = ['human', 'agent', 'ci'];
+let currentMode = { mode: 'human', source: 'default' };
+export class InvalidInteractionModeError extends Error {
+    value;
+    source;
+    constructor(value, source) {
+        const label = source === 'flag' ? '--mode' : 'WORKOS_MODE';
+        super(`${label} must be one of: ${VALID_MODES.join(', ')}`);
+        this.value = value;
+        this.source = source;
+        this.name = 'InvalidInteractionModeError';
+    }
+}
+function isTruthy(value) {
+    return value === '1' || value?.toLowerCase() === 'true';
+}
+function parseModeValue(value, source) {
+    const normalized = value?.toLowerCase();
+    if (normalized && VALID_MODES.includes(normalized)) {
+        return normalized;
+    }
+    throw new InvalidInteractionModeError(value, source);
+}
+function parseModeFromArgv(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--mode') {
+            const value = argv[i + 1];
+            if (!value || value.startsWith('-')) {
+                throw new InvalidInteractionModeError(value, 'flag');
+            }
+            return parseModeValue(value, 'flag');
+        }
+        if (arg.startsWith('--mode=')) {
+            return parseModeValue(arg.slice('--mode='.length), 'flag');
+        }
+    }
+    return undefined;
+}
+function hasCiMarker(env) {
+    return (isTruthy(env.CI) ||
+        isTruthy(env.GITHUB_ACTIONS) ||
+        isTruthy(env.GITLAB_CI) ||
+        isTruthy(env.CIRCLECI) ||
+        isTruthy(env.BUILDKITE) ||
+        isTruthy(env.TF_BUILD));
+}
+function hasAgentMarker(env) {
+    return (isTruthy(env.WORKOS_AGENT) ||
+        isTruthy(env.CLAUDECODE) ||
+        isTruthy(env.CLAUDE_CODE) ||
+        isTruthy(env.CURSOR_AGENT) ||
+        isTruthy(env.CODEX_SANDBOX) ||
+        env.CURSOR_TRACE_ID !== undefined);
+}
+export function resolveInteractionMode(options = {}) {
+    const argv = options.argv ?? [];
+    const env = options.env ?? process.env;
+    const flagMode = parseModeFromArgv(argv);
+    if (flagMode)
+        return { mode: flagMode, source: 'flag' };
+    if (env.WORKOS_MODE !== undefined) {
+        return { mode: parseModeValue(env.WORKOS_MODE, 'env'), source: 'env' };
+    }
+    if (isTruthy(env.WORKOS_NO_PROMPT)) {
+        return { mode: 'agent', source: 'workos_no_prompt' };
+    }
+    if (hasCiMarker(env)) {
+        return { mode: 'ci', source: 'ci_env' };
+    }
+    if (hasAgentMarker(env)) {
+        return { mode: 'agent', source: 'agent_env' };
+    }
+    const stdoutIsTTY = options.stdoutIsTTY ?? process.stdout.isTTY;
+    const stderrIsTTY = options.stderrIsTTY ?? process.stderr.isTTY;
+    if (!stdoutIsTTY || !stderrIsTTY) {
+        return { mode: 'agent', source: 'non_tty' };
+    }
+    return { mode: 'human', source: 'default' };
+}
+export function setInteractionMode(info) {
+    currentMode = info;
+}
+export function getInteractionMode() {
+    return currentMode;
+}
+export function isHumanMode() {
+    return currentMode.mode === 'human';
+}
+export function isAgentMode() {
+    return currentMode.mode === 'agent';
+}
+export function isCiMode() {
+    return currentMode.mode === 'ci';
+}
+export function isPromptAllowed() {
+    return isHumanMode();
+}
+export function resetInteractionModeForTests() {
+    currentMode = { mode: 'human', source: 'default' };
+}
+//# sourceMappingURL=interaction-mode.js.map

package/dist/utils/interaction-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-mode.js","sourceRoot":"","sources":["../../src/utils/interaction-mode.ts"],"names":[],"mappings":"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","sourcesContent":["export type InteractionMode = 'human' | 'agent' | 'ci';\n\nexport type InteractionModeSource =\n  | 'flag'\n  | 'env'\n  | 'workos_no_prompt'\n  | 'ci_env'\n  | 'agent_env'\n  | 'non_tty'\n  | 'default';\n\nexport interface InteractionModeInfo {\n  mode: InteractionMode;\n  source: InteractionModeSource;\n}\n\nexport interface ResolveInteractionModeOptions {\n  argv?: string[];\n  env?: NodeJS.ProcessEnv;\n  stdoutIsTTY?: boolean;\n  stderrIsTTY?: boolean;\n}\n\nconst VALID_MODES: InteractionMode[] = ['human', 'agent', 'ci'];\n\nlet currentMode: InteractionModeInfo = { mode: 'human', source: 'default' };\n\nexport class InvalidInteractionModeError extends Error {\n  constructor(\n    public readonly value: string | undefined,\n    public readonly source: 'flag' | 'env',\n  ) {\n    const label = source === 'flag' ? '--mode' : 'WORKOS_MODE';\n    super(`${label} must be one of: ${VALID_MODES.join(', ')}`);\n    this.name = 'InvalidInteractionModeError';\n  }\n}\n\nfunction isTruthy(value: string | undefined): boolean {\n  return value === '1' || value?.toLowerCase() === 'true';\n}\n\nfunction parseModeValue(value: string | undefined, source: 'flag' | 'env'): InteractionMode {\n  const normalized = value?.toLowerCase();\n  if (normalized && VALID_MODES.includes(normalized as InteractionMode)) {\n    return normalized as InteractionMode;\n  }\n  throw new InvalidInteractionModeError(value, source);\n}\n\nfunction parseModeFromArgv(argv: string[]): InteractionMode | undefined {\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n    if (arg === '--mode') {\n      const value = argv[i + 1];\n      if (!value || value.startsWith('-')) {\n        throw new InvalidInteractionModeError(value, 'flag');\n      }\n      return parseModeValue(value, 'flag');\n    }\n    if (arg.startsWith('--mode=')) {\n      return parseModeValue(arg.slice('--mode='.length), 'flag');\n    }\n  }\n\n  return undefined;\n}\n\nfunction hasCiMarker(env: NodeJS.ProcessEnv): boolean {\n  return (\n    isTruthy(env.CI) ||\n    isTruthy(env.GITHUB_ACTIONS) ||\n    isTruthy(env.GITLAB_CI) ||\n    isTruthy(env.CIRCLECI) ||\n    isTruthy(env.BUILDKITE) ||\n    isTruthy(env.TF_BUILD)\n  );\n}\n\nfunction hasAgentMarker(env: NodeJS.ProcessEnv): boolean {\n  return (\n    isTruthy(env.WORKOS_AGENT) ||\n    isTruthy(env.CLAUDECODE) ||\n    isTruthy(env.CLAUDE_CODE) ||\n    isTruthy(env.CURSOR_AGENT) ||\n    isTruthy(env.CODEX_SANDBOX) ||\n    env.CURSOR_TRACE_ID !== undefined\n  );\n}\n\nexport function resolveInteractionMode(options: ResolveInteractionModeOptions = {}): InteractionModeInfo {\n  const argv = options.argv ?? [];\n  const env = options.env ?? process.env;\n\n  const flagMode = parseModeFromArgv(argv);\n  if (flagMode) return { mode: flagMode, source: 'flag' };\n\n  if (env.WORKOS_MODE !== undefined) {\n    return { mode: parseModeValue(env.WORKOS_MODE, 'env'), source: 'env' };\n  }\n\n  if (isTruthy(env.WORKOS_NO_PROMPT)) {\n    return { mode: 'agent', source: 'workos_no_prompt' };\n  }\n\n  if (hasCiMarker(env)) {\n    return { mode: 'ci', source: 'ci_env' };\n  }\n\n  if (hasAgentMarker(env)) {\n    return { mode: 'agent', source: 'agent_env' };\n  }\n\n  const stdoutIsTTY = options.stdoutIsTTY ?? process.stdout.isTTY;\n  const stderrIsTTY = options.stderrIsTTY ?? process.stderr.isTTY;\n  if (!stdoutIsTTY || !stderrIsTTY) {\n    return { mode: 'agent', source: 'non_tty' };\n  }\n\n  return { mode: 'human', source: 'default' };\n}\n\nexport function setInteractionMode(info: InteractionModeInfo): void {\n  currentMode = info;\n}\n\nexport function getInteractionMode(): InteractionModeInfo {\n  return currentMode;\n}\n\nexport function isHumanMode(): boolean {\n  return currentMode.mode === 'human';\n}\n\nexport function isAgentMode(): boolean {\n  return currentMode.mode === 'agent';\n}\n\nexport function isCiMode(): boolean {\n  return currentMode.mode === 'ci';\n}\n\nexport function isPromptAllowed(): boolean {\n  return isHumanMode();\n}\n\nexport function resetInteractionModeForTests(): void {\n  currentMode = { mode: 'human', source: 'default' };\n}\n"]}

package/dist/utils/output.d.ts

@@ -1,22 +1,26 @@
 /**
  * Output mode system for non-TTY / JSON support.
  *
- * Resolves once at startup, drives all output formatting.
+ * Resolves once at startup, drives output formatting only.
  * In JSON mode: structured JSON to stdout, structured errors to stderr.
  * In human mode: chalk-formatted output (existing behavior).
  */
 import { type TableColumn } from './table.js';
+import type { RecoveryHints } from './recovery-hints.js';
+import type { InteractionModeInfo } from './interaction-mode.js';
 export type OutputMode = 'human' | 'json';
 /**
  * Resolve the output mode based on flags and environment.
  *
  * Priority:
  * 1. Explicit --json flag
- * 2. WORKOS_FORCE_TTY env var → human
- * 3. Non-TTY auto-detection → json
- * 4. Default → human
+ * 2. WORKOS_FORCE_TTY env var → human output compatibility
+ * 3. WORKOS_NO_PROMPT legacy compatibility → json
+ * 4. Non-TTY auto-detection → json
+ * 5. Default → human
  */
 export declare function resolveOutputMode(jsonFlag?: boolean): OutputMode;
+export declare function resolveEffectiveOutputMode(mode: OutputMode, interaction: InteractionModeInfo): OutputMode;
 export declare function setOutputMode(mode: OutputMode): void;
 export declare function getOutputMode(): OutputMode;
 export declare function isJsonMode(): boolean;
@@ -29,17 +33,21 @@ export declare function outputSuccess(message: string, data?: object, options?:
         message: string;
     }>;
 }): void;
-/** Write a structured error to stderr. */
-export declare function outputError(error: {
+export interface StructuredError {
     code: string;
     message: string;
     details?: unknown;
-}): void;
+    /**
+     * Optional structured recovery metadata for agents.
+     *
+     * Only include for deterministic recovery paths. Human output prints the
+     * first hint as a follow-up line; JSON output serializes the full structure.
+     */
+    recovery?: RecoveryHints;
+}
+/** Write a structured error to stderr. */
+export declare function outputError(error: StructuredError): void;
 /** Write tabular data — chalk table in human mode, JSON array in json mode. */
 export declare function outputTable(columns: TableColumn[], rows: string[][], rawData?: unknown[]): void;
 /** Exit with a structured error. Writes error then exits with code 1. */
-export declare function exitWithError(error: {
-    code: string;
-    message: string;
-    details?: unknown;
-}): never;
+export declare function exitWithError(error: StructuredError): never;

package/dist/utils/output.js

@@ -1,7 +1,7 @@
 /**
  * Output mode system for non-TTY / JSON support.
  *
- * Resolves once at startup, drives all output formatting.
+ * Resolves once at startup, drives output formatting only.
  * In JSON mode: structured JSON to stdout, structured errors to stderr.
  * In human mode: chalk-formatted output (existing behavior).
  */
@@ -13,9 +13,10 @@ let currentMode = 'human';
  *
  * Priority:
  * 1. Explicit --json flag
- * 2. WORKOS_FORCE_TTY env var → human
- * 3. Non-TTY auto-detection → json
- * 4. Default → human
+ * 2. WORKOS_FORCE_TTY env var → human output compatibility
+ * 3. WORKOS_NO_PROMPT legacy compatibility → json
+ * 4. Non-TTY auto-detection → json
+ * 5. Default → human
  */
 export function resolveOutputMode(jsonFlag) {
     if (jsonFlag)
@@ -28,6 +29,12 @@ export function resolveOutputMode(jsonFlag) {
         return 'json';
     return 'human';
 }
+export function resolveEffectiveOutputMode(mode, interaction) {
+    if (interaction.mode === 'human' || interaction.source === 'non_tty') {
+        return mode;
+    }
+    return 'json';
+}
 export function setOutputMode(mode) {
     currentMode = mode;
     if (mode === 'json') {
@@ -73,6 +80,11 @@ export function outputError(error) {
     }
     else {
         console.error(chalk.red(error.message));
+        const firstHint = error.recovery?.hints[0];
+        if (firstHint) {
+            const suffix = firstHint.command ? ` Run: ${firstHint.command}` : '';
+            console.error(chalk.dim(`→ ${firstHint.description}${suffix}`));
+        }
     }
 }
 /** Write tabular data — chalk table in human mode, JSON array in json mode. */

package/dist/utils/output.js.map

@@ -1 +1 @@
-{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Output mode system for non-TTY / JSON support.\n *\n * Resolves once at startup, drives all output formatting.\n * In JSON mode: structured JSON to stdout, structured errors to stderr.\n * In human mode: chalk-formatted output (existing behavior).\n */\n\nimport chalk from 'chalk';\nimport { formatTable, type TableColumn } from './table.js';\n\nexport type OutputMode = 'human' | 'json';\n\nlet currentMode: OutputMode = 'human';\n\n/**\n * Resolve the output mode based on flags and environment.\n *\n * Priority:\n * 1. Explicit --json flag\n * 2. WORKOS_FORCE_TTY env var → human\n * 3. Non-TTY auto-detection → json\n * 4. Default → human\n */\nexport function resolveOutputMode(jsonFlag?: boolean): OutputMode {\n  if (jsonFlag) return 'json';\n  if (process.env.WORKOS_FORCE_TTY === '1' || process.env.WORKOS_FORCE_TTY === 'true') return 'human';\n  if (process.env.WORKOS_NO_PROMPT === '1' || process.env.WORKOS_NO_PROMPT === 'true') return 'json';\n  if (!process.stdout.isTTY) return 'json';\n  return 'human';\n}\n\nexport function setOutputMode(mode: OutputMode): void {\n  currentMode = mode;\n  if (mode === 'json') {\n    chalk.level = 0;\n  }\n}\n\nexport function getOutputMode(): OutputMode {\n  return currentMode;\n}\n\nexport function isJsonMode(): boolean {\n  return currentMode === 'json';\n}\n\n/** Write structured JSON to stdout (one line, no pretty-print). */\nexport function outputJson(data: unknown): void {\n  console.log(JSON.stringify(data));\n}\n\n/** Write a success result — chalk in human mode, JSON in json mode. */\nexport function outputSuccess(\n  message: string,\n  data?: object,\n  options?: { warnings?: Array<{ code: string; message: string }> },\n): void {\n  if (currentMode === 'json') {\n    const result: Record<string, unknown> = { status: 'ok', message };\n    if (data) result.data = data;\n    if (options?.warnings?.length) result.warnings = options.warnings;\n    console.log(JSON.stringify(result));\n  } else {\n    console.log(chalk.green(message));\n    if (data) {\n      console.log(JSON.stringify(data, null, 2));\n    }\n    if (options?.warnings?.length) {\n      for (const w of options.warnings) {\n        console.error(chalk.yellow(w.message));\n      }\n    }\n  }\n}\n\n/** Write a structured error to stderr. */\nexport function outputError(error: { code: string; message: string; details?: unknown }): void {\n  if (currentMode === 'json') {\n    console.error(JSON.stringify({ error }));\n  } else {\n    console.error(chalk.red(error.message));\n  }\n}\n\n/** Write tabular data — chalk table in human mode, JSON array in json mode. */\nexport function outputTable(columns: TableColumn[], rows: string[][], rawData?: unknown[]): void {\n  if (currentMode === 'json') {\n    if (rawData) {\n      console.log(JSON.stringify(rawData));\n    } else {\n      const headers = columns.map((c) => c.header);\n      const jsonRows = rows.map((row) => {\n        const obj: Record<string, string> = {};\n        headers.forEach((h, i) => {\n          obj[h] = row[i] ?? '';\n        });\n        return obj;\n      });\n      console.log(JSON.stringify(jsonRows));\n    }\n  } else {\n    console.log(formatTable(columns, rows));\n  }\n}\n\n/** Exit with a structured error. Writes error then exits with code 1. */\nexport function exitWithError(error: { code: string; message: string; details?: unknown }): never {\n  outputError(error);\n  process.exit(1);\n}\n"]}
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Output mode system for non-TTY / JSON support.\n *\n * Resolves once at startup, drives output formatting only.\n * In JSON mode: structured JSON to stdout, structured errors to stderr.\n * In human mode: chalk-formatted output (existing behavior).\n */\n\nimport chalk from 'chalk';\nimport { formatTable, type TableColumn } from './table.js';\nimport type { RecoveryHints } from './recovery-hints.js';\nimport type { InteractionModeInfo } from './interaction-mode.js';\n\nexport type OutputMode = 'human' | 'json';\n\nlet currentMode: OutputMode = 'human';\n\n/**\n * Resolve the output mode based on flags and environment.\n *\n * Priority:\n * 1. Explicit --json flag\n * 2. WORKOS_FORCE_TTY env var → human output compatibility\n * 3. WORKOS_NO_PROMPT legacy compatibility → json\n * 4. Non-TTY auto-detection → json\n * 5. Default → human\n */\nexport function resolveOutputMode(jsonFlag?: boolean): OutputMode {\n  if (jsonFlag) return 'json';\n  if (process.env.WORKOS_FORCE_TTY === '1' || process.env.WORKOS_FORCE_TTY === 'true') return 'human';\n  if (process.env.WORKOS_NO_PROMPT === '1' || process.env.WORKOS_NO_PROMPT === 'true') return 'json';\n  if (!process.stdout.isTTY) return 'json';\n  return 'human';\n}\n\nexport function resolveEffectiveOutputMode(mode: OutputMode, interaction: InteractionModeInfo): OutputMode {\n  if (interaction.mode === 'human' || interaction.source === 'non_tty') {\n    return mode;\n  }\n  return 'json';\n}\n\nexport function setOutputMode(mode: OutputMode): void {\n  currentMode = mode;\n  if (mode === 'json') {\n    chalk.level = 0;\n  }\n}\n\nexport function getOutputMode(): OutputMode {\n  return currentMode;\n}\n\nexport function isJsonMode(): boolean {\n  return currentMode === 'json';\n}\n\n/** Write structured JSON to stdout (one line, no pretty-print). */\nexport function outputJson(data: unknown): void {\n  console.log(JSON.stringify(data));\n}\n\n/** Write a success result — chalk in human mode, JSON in json mode. */\nexport function outputSuccess(\n  message: string,\n  data?: object,\n  options?: { warnings?: Array<{ code: string; message: string }> },\n): void {\n  if (currentMode === 'json') {\n    const result: Record<string, unknown> = { status: 'ok', message };\n    if (data) result.data = data;\n    if (options?.warnings?.length) result.warnings = options.warnings;\n    console.log(JSON.stringify(result));\n  } else {\n    console.log(chalk.green(message));\n    if (data) {\n      console.log(JSON.stringify(data, null, 2));\n    }\n    if (options?.warnings?.length) {\n      for (const w of options.warnings) {\n        console.error(chalk.yellow(w.message));\n      }\n    }\n  }\n}\n\nexport interface StructuredError {\n  code: string;\n  message: string;\n  details?: unknown;\n  /**\n   * Optional structured recovery metadata for agents.\n   *\n   * Only include for deterministic recovery paths. Human output prints the\n   * first hint as a follow-up line; JSON output serializes the full structure.\n   */\n  recovery?: RecoveryHints;\n}\n\n/** Write a structured error to stderr. */\nexport function outputError(error: StructuredError): void {\n  if (currentMode === 'json') {\n    console.error(JSON.stringify({ error }));\n  } else {\n    console.error(chalk.red(error.message));\n    const firstHint = error.recovery?.hints[0];\n    if (firstHint) {\n      const suffix = firstHint.command ? ` Run: ${firstHint.command}` : '';\n      console.error(chalk.dim(`→ ${firstHint.description}${suffix}`));\n    }\n  }\n}\n\n/** Write tabular data — chalk table in human mode, JSON array in json mode. */\nexport function outputTable(columns: TableColumn[], rows: string[][], rawData?: unknown[]): void {\n  if (currentMode === 'json') {\n    if (rawData) {\n      console.log(JSON.stringify(rawData));\n    } else {\n      const headers = columns.map((c) => c.header);\n      const jsonRows = rows.map((row) => {\n        const obj: Record<string, string> = {};\n        headers.forEach((h, i) => {\n          obj[h] = row[i] ?? '';\n        });\n        return obj;\n      });\n      console.log(JSON.stringify(jsonRows));\n    }\n  } else {\n    console.log(formatTable(columns, rows));\n  }\n}\n\n/** Exit with a structured error. Writes error then exits with code 1. */\nexport function exitWithError(error: StructuredError): never {\n  outputError(error);\n  process.exit(1);\n}\n"]}

package/dist/utils/recovery-hints.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Recovery hints for structured CLI errors.
+ *
+ * Recovery metadata is consumed by coding agents through JSON stderr output.
+ * Hints describe the deterministic next step the caller can take to fix the
+ * failure: the exact command to run, whether host shell access is required,
+ * and (optionally) related docs links.
+ *
+ * Keep hints conservative: only include `command` when the next action is
+ * unambiguous and safe. When the correct next step depends on user intent,
+ * provide `description` only.
+ */
+import type { InteractionMode } from './interaction-mode.js';
+export interface RecoveryHint {
+    /** Human-readable next step for both humans and agents. */
+    description: string;
+    /** Exact command to run, when deterministic. */
+    command?: string;
+    /** True when the command must run on the user's host shell, not in the current sandbox. */
+    hostShellRequired?: boolean;
+    /** Optional documentation URL. */
+    docsUrl?: string;
+    /** Optional markdown-capable documentation URL. Only set when route support is verified. */
+    docsMarkdownUrl?: string;
+}
+export interface RecoveryHints {
+    hints: RecoveryHint[];
+}
+/** Build mode-aware recovery hints for `auth_required` errors. */
+export declare function authLoginRecovery(options: {
+    mode: InteractionMode;
+    env?: NodeJS.ProcessEnv;
+}): RecoveryHints;
+/** Build a `confirmation_required` recovery hint, attaching a command only when the exact rerun is known. */
+export declare function confirmationRecovery(command?: string): RecoveryHints;
+/** Build a `missing_args` recovery hint, attaching a command only when it is directly runnable. */
+export declare function missingArgsRecovery(command: string | undefined, description: string): RecoveryHints;

package/dist/utils/recovery-hints.js

@@ -0,0 +1,80 @@
+/**
+ * Recovery hints for structured CLI errors.
+ *
+ * Recovery metadata is consumed by coding agents through JSON stderr output.
+ * Hints describe the deterministic next step the caller can take to fix the
+ * failure: the exact command to run, whether host shell access is required,
+ * and (optionally) related docs links.
+ *
+ * Keep hints conservative: only include `command` when the next action is
+ * unambiguous and safe. When the correct next step depends on user intent,
+ * provide `description` only.
+ */
+import { formatWorkOSCommand } from './command-invocation.js';
+/** Build mode-aware recovery hints for `auth_required` errors. */
+export function authLoginRecovery(options) {
+    const env = options.env ?? process.env;
+    const loginCommand = formatWorkOSCommand('auth login', env);
+    if (options.mode === 'ci') {
+        return {
+            hints: [
+                {
+                    description: 'Set WORKOS_API_KEY in the CI environment.',
+                },
+                {
+                    description: 'Or refresh stored credentials before the CI run.',
+                    command: loginCommand,
+                    hostShellRequired: true,
+                },
+            ],
+        };
+    }
+    if (options.mode === 'agent') {
+        return {
+            hints: [
+                {
+                    description: "Authenticate on the user's host shell.",
+                    command: loginCommand,
+                    hostShellRequired: true,
+                },
+                {
+                    description: 'Or set WORKOS_API_KEY before invoking the CLI.',
+                },
+            ],
+        };
+    }
+    return {
+        hints: [
+            {
+                description: 'Authenticate via browser-based device login.',
+                command: loginCommand,
+            },
+            {
+                description: 'Or set WORKOS_API_KEY.',
+            },
+        ],
+    };
+}
+/** Build a `confirmation_required` recovery hint, attaching a command only when the exact rerun is known. */
+export function confirmationRecovery(command) {
+    return {
+        hints: [
+            {
+                description: 'Re-run with explicit confirmation.',
+                ...(command && { command }),
+            },
+        ],
+    };
+}
+/** Build a `missing_args` recovery hint, attaching a command only when it is directly runnable. */
+export function missingArgsRecovery(command, description) {
+    return {
+        hints: [
+            {
+                description,
+                ...(command && { command }),
+            },
+        ],
+    };
+}
+//# sourceMappingURL=recovery-hints.js.map

package/dist/utils/recovery-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-hints.js","sourceRoot":"","sources":["../../src/utils/recovery-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAmB9D,kEAAkE;AAClE,MAAM,UAAU,iBAAiB,CAAC,OAA2D;IAC3F,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,YAAY,GAAG,mBAAmB,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAE5D,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO;YACL,KAAK,EAAE;gBACL;oBACE,WAAW,EAAE,2CAA2C;iBACzD;gBACD;oBACE,WAAW,EAAE,kDAAkD;oBAC/D,OAAO,EAAE,YAAY;oBACrB,iBAAiB,EAAE,IAAI;iBACxB;aACF;SACF,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO;YACL,KAAK,EAAE;gBACL;oBACE,WAAW,EAAE,wCAAwC;oBACrD,OAAO,EAAE,YAAY;oBACrB,iBAAiB,EAAE,IAAI;iBACxB;gBACD;oBACE,WAAW,EAAE,gDAAgD;iBAC9D;aACF;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,EAAE;YACL;gBACE,WAAW,EAAE,8CAA8C;gBAC3D,OAAO,EAAE,YAAY;aACtB;YACD;gBACE,WAAW,EAAE,wBAAwB;aACtC;SACF;KACF,CAAC;AACJ,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,OAAO;QACL,KAAK,EAAE;YACL;gBACE,WAAW,EAAE,oCAAoC;gBACjD,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;aAC5B;SACF;KACF,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,mBAAmB,CAAC,OAA2B,EAAE,WAAmB;IAClF,OAAO;QACL,KAAK,EAAE;YACL;gBACE,WAAW;gBACX,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;aAC5B;SACF;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Recovery hints for structured CLI errors.\n *\n * Recovery metadata is consumed by coding agents through JSON stderr output.\n * Hints describe the deterministic next step the caller can take to fix the\n * failure: the exact command to run, whether host shell access is required,\n * and (optionally) related docs links.\n *\n * Keep hints conservative: only include `command` when the next action is\n * unambiguous and safe. When the correct next step depends on user intent,\n * provide `description` only.\n */\n\nimport type { InteractionMode } from './interaction-mode.js';\nimport { formatWorkOSCommand } from './command-invocation.js';\n\nexport interface RecoveryHint {\n  /** Human-readable next step for both humans and agents. */\n  description: string;\n  /** Exact command to run, when deterministic. */\n  command?: string;\n  /** True when the command must run on the user's host shell, not in the current sandbox. */\n  hostShellRequired?: boolean;\n  /** Optional documentation URL. */\n  docsUrl?: string;\n  /** Optional markdown-capable documentation URL. Only set when route support is verified. */\n  docsMarkdownUrl?: string;\n}\n\nexport interface RecoveryHints {\n  hints: RecoveryHint[];\n}\n\n/** Build mode-aware recovery hints for `auth_required` errors. */\nexport function authLoginRecovery(options: { mode: InteractionMode; env?: NodeJS.ProcessEnv }): RecoveryHints {\n  const env = options.env ?? process.env;\n  const loginCommand = formatWorkOSCommand('auth login', env);\n\n  if (options.mode === 'ci') {\n    return {\n      hints: [\n        {\n          description: 'Set WORKOS_API_KEY in the CI environment.',\n        },\n        {\n          description: 'Or refresh stored credentials before the CI run.',\n          command: loginCommand,\n          hostShellRequired: true,\n        },\n      ],\n    };\n  }\n\n  if (options.mode === 'agent') {\n    return {\n      hints: [\n        {\n          description: \"Authenticate on the user's host shell.\",\n          command: loginCommand,\n          hostShellRequired: true,\n        },\n        {\n          description: 'Or set WORKOS_API_KEY before invoking the CLI.',\n        },\n      ],\n    };\n  }\n\n  return {\n    hints: [\n      {\n        description: 'Authenticate via browser-based device login.',\n        command: loginCommand,\n      },\n      {\n        description: 'Or set WORKOS_API_KEY.',\n      },\n    ],\n  };\n}\n\n/** Build a `confirmation_required` recovery hint, attaching a command only when the exact rerun is known. */\nexport function confirmationRecovery(command?: string): RecoveryHints {\n  return {\n    hints: [\n      {\n        description: 'Re-run with explicit confirmation.',\n        ...(command && { command }),\n      },\n    ],\n  };\n}\n\n/** Build a `missing_args` recovery hint, attaching a command only when it is directly runnable. */\nexport function missingArgsRecovery(command: string | undefined, description: string): RecoveryHints {\n  return {\n    hints: [\n      {\n        description,\n        ...(command && { command }),\n      },\n    ],\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workos",
-  "version": "0.13.4",
+  "version": "0.14.0",
   "type": "module",
   "description": "The Official Workos CLI",
   "repository": {
@@ -49,20 +49,21 @@
     "@anthropic-ai/sdk": "^0.78.0",
     "@clack/core": "^1.0.1",
     "@clack/prompts": "1.0.1",
+    "@hono/node-server": "^1",
     "@napi-rs/keyring": "^1.2.0",
     "@workos-inc/node": "^8.7.0",
+    "@workos/openapi-spec": "^0.1.0",
     "@workos/skills": "0.5.0",
     "chalk": "^5.6.2",
     "diff": "^8.0.3",
     "fast-glob": "^3.3.3",
+    "hono": "^4",
     "ink": "^6.8.0",
     "opn": "^5.4.0",
     "react": "^19.2.4",
     "semver": "^7.7.4",
     "uuid": "^13.0.0",
     "xstate": "^5.28.0",
-    "hono": "^4",
-    "@hono/node-server": "^1",
     "yaml": "^2.8.2",
     "yargs": "^18.0.0",
     "zod": "^4.3.6"