outrank-cli 0.5.0 → 0.6.0

package/src/commands/auth.js

@@ -1,127 +1,245 @@
-import { getOption, hasFlag, parseArgs } from '../core/args.js';
-import { requestAgentApi } from '../core/api.js';
+import { PROFILE_ENV } from '../core/constants.js';
 import {
-  clearStoredAuth,
+  API_KEY_FIELD,
+  BASE_URL_FIELD,
+  clearProfileAuth,
   getConfigPath,
-  getDefaultBaseUrl,
-  resolveRuntimeConfig,
-  storeAuthConfig,
+  loadProfiles,
+  redactApiKey,
+  storeProfileAuth,
 } from '../core/config.js';
-import { cliSuccess } from '../core/errors.js';
+import { ContextSource, Surface, normalizeBaseUrl } from '../core/context.js';
+import { cliSuccess, usageError } from '../core/errors.js';
+import { assertHeaderSafeApiKey, requestAgentApi } from '../core/http.js';
+import { profileSelectedByEnvHint } from '../core/profileSelection.js';
+import { bool, string } from '../core/schema.js';
+import { CommandKind, Toolset, defineCommand, defineGroup } from './registry.js';
 
 export const AUTH_HELP = `Usage:
-  outrank-cli auth login <api-key> [--base-url <url>] [--no-verify]
+  outrank-cli auth login <api-key> [--profile <name>] [--default] [--base-url <url>] [--no-verify]
   outrank-cli auth whoami
   outrank-cli auth status
-  outrank-cli auth logout
+  outrank-cli auth profiles
+  outrank-cli auth logout [--profile <name>]
 
 Commands:
-  login     Store an API key locally and optionally verify it immediately.
+  login     Store an API key in a profile (the default profile unless --profile is given) and optionally verify it.
   whoami    Verify auth and return the current user and organization details.
-  status    Show the currently resolved auth and base-url configuration.
-  logout    Remove the stored API key from local config.
+  status    Show the resolved profile, where its key and base URL came from, and the config path.
+  profiles  List stored profiles with redacted keys and mark the default one.
+  logout    Remove the stored API key from a profile.
 
 Notes:
-  Environment variables override local config: OUTRANK_API_KEY, OUTRANK_BASE_URL.
+  Precedence: --api-key and --base-url win; then a profile selected with --profile or OUTRANK_PROFILE
+  (a selected profile ignores OUTRANK_API_KEY and OUTRANK_BASE_URL); then OUTRANK_API_KEY and
+  OUTRANK_BASE_URL; then the default profile from local config.
+  login verifies against and stores the resolved base URL: --base-url, else OUTRANK_BASE_URL (ignored when
+  a profile is selected), else the profile's stored value, else the default.
   Optional config-dir override: OUTRANK_CONFIG_DIR
   Local config path: ~/.outrank/config.json
 `;
 
-export const handleAuthCommand = async (argv) => {
-  const subcommand = argv[0];
-  const parsed = parseArgs(argv.slice(1));
-  const wantsHelp =
-    !subcommand || subcommand === '--help' || subcommand === '-h' || subcommand === 'help' || hasFlag(parsed, 'help');
+const WHOAMI_PATH = '/auth/whoami';
+const CONFIG_PATH_FIELD = 'config_path';
+const ENV_IGNORED_SUFFIX = ' (env ignored)';
+const LOGIN_MISSING_KEY_GUIDANCE = 'Run `outrank-cli auth login <api-key>` or pass `--api-key <api-key>`, then retry.';
+const LOGIN_SAVED_GUIDANCE =
+  'Credentials saved. Run `outrank-cli auth whoami` to confirm the active workspace at any time.';
+const loginSavedToProfileGuidance = (profile) =>
+  `Credentials saved to profile ${profile}, which is not the default. Pass --profile ${profile} or set ` +
+  `${PROFILE_ENV}=${profile} to use it, or re-run login with --default to make it the default.`;
+const STATUS_GUIDANCE =
+  'Confirm this target before running live commands. If you use a non-default Outrank deployment, set ' +
+  '`OUTRANK_BASE_URL` first.';
+const STATUS_UNKNOWN_PROFILE_GUIDANCE =
+  'The selected profile is not stored. Run `outrank-cli auth profiles` to see the stored profiles, or ' +
+  '`outrank-cli auth login <api-key> --profile <name>` to create it.';
+const STATUS_UNKNOWN_PROFILE_WITH_KEY_GUIDANCE =
+  'The selected profile is not stored; the key in use comes from --api-key, not from a profile. Run ' +
+  '`outrank-cli auth login <api-key> --profile <name>` to store it.';
+const statusInvalidStoredBaseUrlGuidance = (profile) =>
+  `The base URL stored in profile ${profile} is not a valid URL, so authenticated commands will fail. Edit it in ` +
+  `the config file, or run \`outrank-cli auth login <api-key> --profile ${profile} --base-url <url>\` to replace it.`;
+const LOGIN_BASE_URL_FROM_ENV_NOTE =
+  ' The base URL came from OUTRANK_BASE_URL and is now stored in the profile; unset the variable if that was not ' +
+  'intended and run login again with --base-url.';
 
-  if (wantsHelp) {
-    return cliSuccess(
-      {
-        usage: AUTH_HELP.trim(),
-      },
-      'Choose one of: login, whoami, status, logout.',
-    );
+const statusGuidance = (ctx) => {
+  if (ctx.profile.explicit && !ctx.profile.known) {
+    const base = ctx.apiKey ? STATUS_UNKNOWN_PROFILE_WITH_KEY_GUIDANCE : STATUS_UNKNOWN_PROFILE_GUIDANCE;
+    return base + profileSelectedByEnvHint(ctx.profile.source);
+  }
+  if (ctx.baseUrl === null) {
+    return statusInvalidStoredBaseUrlGuidance(ctx.profile.name) + profileSelectedByEnvHint(ctx.profile.source);
+  }
+  return STATUS_GUIDANCE;
+};
+
+const describeStoredBaseUrl = (value) => {
+  if (value === undefined) return { base_url: null, base_url_valid: true };
+  try {
+    return { base_url: normalizeBaseUrl(value), base_url_valid: true };
+  } catch {
+    return { base_url: null, base_url_valid: false };
   }
+};
+const LOGOUT_GUIDANCE =
+  'Stored API key removed. Any future authenticated call now requires OUTRANK_API_KEY or a fresh `auth login`.';
+const logoutProfileGuidance = (profile) =>
+  `Stored API key removed from profile ${profile}. Other profiles are untouched; run ` +
+  `\`outrank-cli auth login <api-key> --profile ${profile}\` to store a new key.`;
+const logoutNothingStoredGuidance = (profile) =>
+  `Profile ${profile} had no stored API key, so nothing changed. Run \`outrank-cli auth profiles\` to see ` +
+  'which profiles hold keys.';
+const PROFILES_EMPTY_GUIDANCE =
+  'No profiles are stored. Run `outrank-cli auth login <api-key>` (optionally with --profile <name>) to create one.';
+const PROFILES_GUIDANCE =
+  'Select a profile per call with --profile <name> or per shell with OUTRANK_PROFILE. A selected profile ignores ' +
+  'OUTRANK_API_KEY and OUTRANK_BASE_URL; --api-key and --base-url still win.';
 
-  if (subcommand === 'login') {
-    const apiKey = parsed.positionals[0] ?? getOption(parsed, 'api-key');
-    if (!apiKey) {
-      throw Object.assign(new Error('Missing API key.'), {
-        cliCode: 'CLI_INVALID_USAGE',
-        guidance:
-          'Run `outrank-cli auth login <api-key>` or pass `--api-key <api-key>`, then retry.',
-      });
-    }
+const configPathField = (ctx) => (ctx.surface === Surface.MCP ? {} : { [CONFIG_PATH_FIELD]: getConfigPath() });
 
-    const baseUrl = getOption(parsed, 'base-url') ?? getDefaultBaseUrl();
-    if (!hasFlag(parsed, 'no-verify')) {
-      const verifyParsed = parseArgs(['--api-key', apiKey, '--base-url', baseUrl]);
-      const response = await requestAgentApi(verifyParsed, {
-        method: 'GET',
-        path: '/auth/whoami',
-      });
-      if (!response.ok) {
-        return response.payload;
-      }
-    }
+const renderSource = (source, envIgnored) => (envIgnored ? `${source}${ENV_IGNORED_SUFFIX}` : source);
 
-    const saved = await storeAuthConfig({ apiKey, baseUrl });
+const login = defineCommand({
+  id: 'auth.login',
+  summary: 'Store an API key in a profile and optionally verify it immediately.',
+  kind: CommandKind.LOCAL,
+  toolsets: [Toolset.CORE],
+  mcp: false,
+  allowUnknownProfile: true,
+  input: { apiKey: string(), noVerify: bool(), makeDefault: bool() },
+  cli: {
+    positionals: ['apiKey'],
+    placeholders: { apiKey: '<api-key>' },
+    options: { 'no-verify': 'noVerify', default: 'makeDefault' },
+  },
+  run: async (input, ctx) => {
+    const apiKey = input.apiKey ?? (ctx.source.apiKey === ContextSource.FLAG ? ctx.apiKey : undefined);
+    if (!apiKey) throw usageError('Missing API key.', LOGIN_MISSING_KEY_GUIDANCE);
+    assertHeaderSafeApiKey(apiKey);
+    if (!input.noVerify) {
+      const { result } = await requestAgentApi({ ...ctx, apiKey }, { method: 'GET', path: WHOAMI_PATH });
+      if (!result.ok) return result;
+    }
+    const saved = await storeProfileAuth({
+      profile: ctx.profile.name,
+      apiKey,
+      baseUrl: ctx.baseUrl,
+      makeDefault: input.makeDefault,
+    });
+    const envNote = ctx.source.baseUrl === ContextSource.ENV ? LOGIN_BASE_URL_FROM_ENV_NOTE : '';
     return cliSuccess(
       {
         stored: {
+          profile: saved.profile,
+          is_default: saved.isDefault,
           api_key: true,
-          base_url: saved.baseUrl,
-          config_path: getConfigPath(),
+          base_url: saved.stored[BASE_URL_FIELD],
+          base_url_source: ctx.source.baseUrl,
+          [CONFIG_PATH_FIELD]: getConfigPath(),
         },
       },
-      'Credentials saved. Run `outrank-cli auth whoami` to confirm the active workspace at any time.',
+      (saved.isDefault ? LOGIN_SAVED_GUIDANCE : loginSavedToProfileGuidance(saved.profile)) + envNote,
     );
-  }
+  },
+});
 
-  if (subcommand === 'whoami') {
-    const response = await requestAgentApi(parsed, {
-      method: 'GET',
-      path: '/auth/whoami',
-    });
-    return response.payload;
-  }
+const whoami = defineCommand({
+  id: 'auth.whoami',
+  summary: 'Verify auth and return the current user and organization details.',
+  kind: CommandKind.READ,
+  toolsets: [Toolset.CORE],
+  run: (_input, ctx) => ctx.http({ method: 'GET', path: WHOAMI_PATH }),
+});
+
+const status = defineCommand({
+  id: 'auth.status',
+  summary: 'Show the resolved profile, auth source and base-url configuration (the key itself is never shown).',
+  kind: CommandKind.LOCAL,
+  toolsets: [Toolset.CORE],
+  mcp: { redact: [CONFIG_PATH_FIELD] },
+  offline: true,
+  allowUnknownProfile: true,
+  run: (_input, ctx) =>
+    cliSuccess(
+      {
+        profile: ctx.profile.name,
+        profile_source: ctx.profile.source,
+        profile_stored: ctx.profile.known,
+        base_url: ctx.baseUrl,
+        base_url_valid: ctx.baseUrl !== null,
+        api_key_present: Boolean(ctx.apiKey),
+        api_key_source: renderSource(ctx.source.apiKey, ctx.source.envIgnored),
+        base_url_source: renderSource(ctx.source.baseUrl, ctx.source.baseUrlEnvIgnored),
+        ...configPathField(ctx),
+      },
+      statusGuidance(ctx),
+    ),
+});
 
-  if (subcommand === 'status') {
-    const runtime = await resolveRuntimeConfig(parsed);
+const profiles = defineCommand({
+  id: 'auth.profiles',
+  summary: 'List stored profiles with redacted keys and mark the default one.',
+  kind: CommandKind.LOCAL,
+  toolsets: [Toolset.CORE],
+  mcp: false,
+  offline: true,
+  allowUnknownProfile: true,
+  run: async (_input, ctx) => {
+    const state = await loadProfiles();
+    const names = Object.keys(state.profiles).sort();
     return cliSuccess(
       {
-        base_url: runtime.baseUrl,
-        api_key_present: Boolean(runtime.apiKey),
-        api_key_source: process.env.OUTRANK_API_KEY
-          ? 'env'
-          : runtime.config.apiKey
-            ? 'config'
-            : 'missing',
-        base_url_source: process.env.OUTRANK_BASE_URL
-          ? 'env'
-          : runtime.config.baseUrl
-            ? 'config'
-            : 'default',
-        config_path: getConfigPath(),
+        default_profile: state.defaultProfile,
+        active_profile: ctx.profile.name,
+        active_profile_stored: ctx.profile.known,
+        profiles: names.map((name) => ({
+          name,
+          is_default: name === state.defaultProfile,
+          api_key_present: Boolean(state.profiles[name][API_KEY_FIELD]),
+          api_key_suffix: redactApiKey(state.profiles[name][API_KEY_FIELD]),
+          ...describeStoredBaseUrl(state.profiles[name][BASE_URL_FIELD]),
+        })),
+        [CONFIG_PATH_FIELD]: getConfigPath(),
       },
-      'Confirm this target before running live commands. If you use a non-default Outrank deployment, set `OUTRANK_BASE_URL` first.',
+      names.length === 0 ? PROFILES_EMPTY_GUIDANCE : PROFILES_GUIDANCE,
     );
-  }
+  },
+});
+
+const logoutGuidance = (ctx, removed) => {
+  if (!removed) return logoutNothingStoredGuidance(ctx.profile.name);
+  return ctx.profile.explicit ? logoutProfileGuidance(ctx.profile.name) : LOGOUT_GUIDANCE;
+};
 
-  if (subcommand === 'logout') {
-    const runtime = await resolveRuntimeConfig(parsed);
-    await clearStoredAuth();
+const logout = defineCommand({
+  id: 'auth.logout',
+  summary: 'Remove the stored API key from a profile.',
+  kind: CommandKind.LOCAL,
+  toolsets: [Toolset.CORE],
+  mcp: false,
+  offline: true,
+  run: async (_input, ctx) => {
+    const { removed } = await clearProfileAuth({ profile: ctx.profile.name });
     return cliSuccess(
       {
-        cleared: ['apiKey'],
-        config_path: getConfigPath(),
-        base_url_still_configured: Boolean(runtime.config.baseUrl),
+        cleared: removed ? [API_KEY_FIELD] : [],
+        profile: ctx.profile.name,
+        [CONFIG_PATH_FIELD]: getConfigPath(),
+        base_url_still_configured: Boolean(ctx.storedBaseUrl),
       },
-      'Stored API key removed. Any future authenticated call now requires OUTRANK_API_KEY or a fresh `auth login`.',
+      logoutGuidance(ctx, removed),
     );
-  }
+  },
+});
 
-  throw Object.assign(new Error(`Unknown auth subcommand: ${subcommand}.`), {
-    cliCode: 'CLI_INVALID_USAGE',
+export const authGroup = defineGroup({
+  id: 'auth',
+  help: { usage: AUTH_HELP, guidance: 'Choose one of: login, whoami, status, profiles, logout.' },
+  unknown: (word) => ({
+    message: `Unknown auth subcommand: ${word}.`,
     guidance: 'Run `outrank-cli auth --help` to see available auth commands.',
-  });
-};
+  }),
+  children: [login, whoami, status, profiles, logout],
+});

package/src/commands/billing.js

@@ -1,8 +1,14 @@
 import { randomUUID } from 'node:crypto';
 
-import { parseArgs, hasFlag, parseIntegerOption, getOption } from '../core/args.js';
-import { requestAgentApi } from '../core/api.js';
+import {
+  BILLING_MAX_ADDITIONAL_PRODUCTS,
+  BILLING_MIN_ADDITIONAL_PRODUCTS,
+  BILLING_MIN_CONFIRM_CHARGE_CENTS,
+  HTTP_STATUS_CONFLICT,
+} from '../core/constants.js';
 import { cliSuccess } from '../core/errors.js';
+import { int, string } from '../core/schema.js';
+import { CommandKind, Toolset, defineCommand, defineGroup } from './registry.js';
 
 export const BILLING_HELP = `Usage:
   outrank-cli billing portal-url
@@ -16,114 +22,106 @@ Notes:
   buy requires the server-quoted recurring total in cents and an explicit idempotency key.
 `;
 
-const handlePurchaseProducts = async (argv) => {
-  const subcommand = argv[0];
-  const parsed = parseArgs(argv.slice(1));
-  const wantsHelp =
-    !subcommand || subcommand === '--help' || subcommand === '-h' || subcommand === 'help' || hasFlag(parsed, 'help');
-
-  if (wantsHelp) {
-    return cliSuccess(
-      {
-        usage:
-          'Usage:\n  outrank-cli billing purchase-products quote --additional-products <n> [--idempotency-key <key>]\n  outrank-cli billing purchase-products buy --additional-products <n> --confirm-charge-cents <n> --idempotency-key <key>',
-      },
-      'Use `quote` first, then `buy` with the quoted recurring total and a stable idempotency key.',
-    );
-  }
-
-  const additionalProducts = parseIntegerOption(parsed, 'additional-products', {
-    required: true,
-    min: 1,
-    max: 30,
-  });
-
-  if (subcommand === 'quote') {
-    const idempotencyKey = getOption(parsed, 'idempotency-key') || randomUUID();
-    const response = await requestAgentApi(parsed, {
+const PURCHASE_PRODUCTS_HELP =
+  'Usage:\n' +
+  '  outrank-cli billing purchase-products quote --additional-products <n> [--idempotency-key <key>]\n' +
+  '  outrank-cli billing purchase-products buy --additional-products <n> --confirm-charge-cents <n> ' +
+  '--idempotency-key <key>';
+
+const PURCHASE_PRODUCTS_PATH = '/billing/purchase-products';
+const QUOTE_GUIDANCE =
+  'Quote received. Review the recurring total and, if the human approves, run the matching `buy` command with ' +
+  '--confirm-charge-cents set to the quoted amount.';
+const buyKeyGuidance = () =>
+  `Generate a stable unique key for this purchase, for example ${randomUUID()}, then retry with ` +
+  '--idempotency-key <value>.';
+
+const additionalProducts = () =>
+  int({ min: BILLING_MIN_ADDITIONAL_PRODUCTS, max: BILLING_MAX_ADDITIONAL_PRODUCTS }).required();
+
+const isQuote = (status, result) =>
+  status === HTTP_STATUS_CONFLICT &&
+  result.ok === false &&
+  Number.isInteger(result.error?.details?.expected_recurring_total_cents);
+
+const portalUrl = defineCommand({
+  id: 'billing.portal-url',
+  summary: 'Return a Stripe customer-portal link for the human to open in a browser.',
+  kind: CommandKind.READ,
+  toolsets: [Toolset.BILLING],
+  entryPoint: true,
+  run: (_input, ctx) => ctx.http({ method: 'GET', path: '/billing/portal-url' }),
+});
+
+const quote = defineCommand({
+  id: 'billing.purchase-products.quote',
+  summary: 'Request pricing for additional product slots without authorizing the charge.',
+  kind: CommandKind.READ,
+  toolsets: [Toolset.BILLING],
+  entryPoint: true,
+  input: { additionalProducts: additionalProducts(), idempotencyKey: string() },
+  run: async (input, ctx) => {
+    const idempotencyKey = input.idempotencyKey ?? randomUUID();
+    const { result, status } = await ctx.request({
       method: 'POST',
-      path: '/billing/purchase-products',
-      body: {
-        additional_products: additionalProducts,
-      },
+      path: PURCHASE_PRODUCTS_PATH,
+      body: { additional_products: input.additionalProducts },
       idempotencyKey,
     });
-
-    if (!response.ok && response.status === 409) {
+    if (isQuote(status, result)) {
       return cliSuccess(
-        {
-          quote: response.payload.error?.details ?? null,
-          api_response: response.payload,
-          idempotency_key: idempotencyKey,
-        },
-        'Quote received. Review the recurring total and, if the human approves, run the matching `buy` command with --confirm-charge-cents set to the quoted amount.',
+        { quote: result.error.details, api_response: result, idempotency_key: idempotencyKey },
+        QUOTE_GUIDANCE,
       );
     }
-
-    return response.payload;
-  }
-
-  if (subcommand === 'buy') {
-    const confirmChargeCents = parseIntegerOption(parsed, 'confirm-charge-cents', {
-      required: true,
-      min: 0,
-    });
-    const idempotencyKey = getOption(parsed, 'idempotency-key');
-    if (!idempotencyKey) {
-      throw Object.assign(new Error('Missing required option: --idempotency-key.'), {
-        cliCode: 'CLI_INVALID_USAGE',
-        guidance:
-          `Generate a stable unique key for this purchase, for example ${randomUUID()}, then retry with --idempotency-key <value>.`,
-      });
+    if (result.ok && result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
+      return { ...result, data: { ...result.data, idempotency_key: idempotencyKey } };
     }
-
-    const response = await requestAgentApi(parsed, {
+    return result;
+  },
+});
+
+const buy = defineCommand({
+  id: 'billing.purchase-products.buy',
+  summary: 'Buy additional product slots at the quoted recurring total.',
+  kind: CommandKind.MONEY,
+  toolsets: [Toolset.BILLING],
+  input: {
+    additionalProducts: additionalProducts(),
+    confirmChargeCents: int({ min: BILLING_MIN_CONFIRM_CHARGE_CENTS }).required(),
+    idempotencyKey: string().required({ guidance: buyKeyGuidance() }),
+  },
+  run: (input, ctx) =>
+    ctx.http({
       method: 'POST',
-      path: '/billing/purchase-products',
-      body: {
-        additional_products: additionalProducts,
-        confirm_charge_cents: confirmChargeCents,
-      },
-      idempotencyKey,
-    });
-    return response.payload;
-  }
-
-  throw Object.assign(new Error(`Unknown billing purchase-products subcommand: ${subcommand}.`), {
-    cliCode: 'CLI_INVALID_USAGE',
-    guidance:
-      'Run `outrank-cli billing purchase-products --help` to see the available purchase-products commands.',
-  });
-};
-
-export const handleBillingCommand = async (argv) => {
-  const subcommand = argv[0];
-  const parsed = parseArgs(argv.slice(1));
-  const wantsHelp = !subcommand || subcommand === '--help' || subcommand === '-h' || subcommand === 'help';
-
-  if (wantsHelp) {
-    return cliSuccess(
-      {
-        usage: BILLING_HELP.trim(),
-      },
-      'Choose one of the currently available billing groups: `portal-url` or `purchase-products`.',
-    );
-  }
-
-  if (subcommand === 'portal-url') {
-    const response = await requestAgentApi(parsed, {
-      method: 'GET',
-      path: '/billing/portal-url',
-    });
-    return response.payload;
-  }
-
-  if (subcommand === 'purchase-products') {
-    return handlePurchaseProducts(argv.slice(1));
-  }
-
-  throw Object.assign(new Error(`Unknown billing subcommand: ${subcommand}.`), {
-    cliCode: 'CLI_INVALID_USAGE',
+      path: PURCHASE_PRODUCTS_PATH,
+      body: { additional_products: input.additionalProducts, confirm_charge_cents: input.confirmChargeCents },
+      idempotencyKey: input.idempotencyKey,
+    }),
+});
+
+const purchaseProducts = defineGroup({
+  id: 'billing.purchase-products',
+  help: {
+    usage: PURCHASE_PRODUCTS_HELP,
+    guidance: 'Use `quote` first, then `buy` with the quoted recurring total and a stable idempotency key.',
+  },
+  unknown: (word) => ({
+    message: `Unknown billing purchase-products subcommand: ${word}.`,
+    guidance: 'Run `outrank-cli billing purchase-products --help` to see the available purchase-products commands.',
+  }),
+  children: [quote, buy],
+});
+
+export const billingGroup = defineGroup({
+  id: 'billing',
+  help: {
+    usage: BILLING_HELP,
+    guidance: 'Choose one of the currently available billing groups: `portal-url` or `purchase-products`.',
+  },
+  unknown: (word) => ({
+    message: `Unknown billing subcommand: ${word}.`,
     guidance: 'Run `outrank-cli billing --help` to see available billing commands.',
-  });
-};
+  }),
+  children: [portalUrl, purchaseProducts],
+});