@ratio-app/cli 0.1.1

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/dev-store-gate.ts","../src/lib/credentials/clock.ts","../src/lib/credentials/path.ts","../src/lib/errors.ts","../src/lib/credentials/refresher.ts","../src/lib/credentials/store.ts","../src/lib/credentials/schema.ts","../src/scaffold/render.ts","../src/index.ts"],"sourcesContent":["/**\n * Extension seam for future development-store gating.\n *\n * The Ratio platform has a forthcoming capability that will restrict certain\n * operations to development stores only. Today the CLI does not enforce any\n * such restriction — every operation is permitted regardless of store type.\n * When the platform gains that capability, one class swap in this module\n * (returning a different implementation from {@link getDevStoreGate}) will\n * activate enforcement without touching any consumer.\n *\n * Developers integrating with the CLI's internals do not need to interact\n * with this seam in v1.\n *\n * Rules:\n *   - No imports from node:fs, node:net, node:http, db, fetch, or any other\n *     I/O module. This module must remain pure/sync.\n *   - No Date.now() / new Date() / Math.random().\n *   - The only mutable module-level state is the singleton slot below.\n */\n\n// ---------------------------------------------------------------------------\n// Public interface\n// ---------------------------------------------------------------------------\n\n/**\n * Context passed by a caller invoking a would-be-gated operation.\n *\n * `command` is the only required field so that the seam is callable from\n * unauthenticated flows (e.g. login) as well as authenticated ones. `appId`\n * and `developerId` are optional because they are not yet known at every\n * potential call-site.\n */\nexport interface DevStoreGateContext {\n  /** The invoking oclif command id (e.g. \"app link\"). Required. */\n  readonly command: string;\n  /** The current app being operated on, if any. */\n  readonly appId?: string;\n  /** The current developer, if authenticated. */\n  readonly developerId?: string;\n}\n\n/** Extension point for future development-store gating enforcement. */\nexport interface DevStoreGate {\n  /**\n   * Assert the current context is allowed to invoke a gated operation.\n   *\n   * v1 implementations MAY be a no-op. Future implementations will throw\n   * when the operation is not permitted for the current context. Callers\n   * cannot silently ignore a denial: the method returns `void`, so the\n   * only signalling channel is an exception.\n   */\n  assertAllowed(context: DevStoreGateContext): void;\n}\n\n// ---------------------------------------------------------------------------\n// NoopDevStoreGate — v1 no-op implementation (shipping default)\n// ---------------------------------------------------------------------------\n\n/**\n * v1 no-op implementation. Permits every operation unconditionally by\n * simply returning. Replaced by a future implementation when the platform\n * capability lights up.\n */\nexport class NoopDevStoreGate implements DevStoreGate {\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  public assertAllowed(_context: DevStoreGateContext): void {\n    // No-op by design. See module JSDoc.\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Module-level singleton factory\n// ---------------------------------------------------------------------------\n\n// Stateless — a single instance is sound for the whole process lifetime.\nconst _defaultInstance: DevStoreGate = new NoopDevStoreGate();\n\n/**\n * Return the current {@link DevStoreGate} binding.\n *\n * v1 returns a singleton {@link NoopDevStoreGate}. When the platform\n * capability lights up, this factory is the single point that will\n * return a different implementation. No other code path is expected\n * to instantiate a {@link DevStoreGate}.\n */\nexport function getDevStoreGate(): DevStoreGate {\n  return _defaultInstance;\n}\n","/**\n * Injectable wall-clock seam for the credential store.\n *\n * This is the ONLY file in the credentials module allowed to sample the\n * real wall clock. Every other file receives a {@link Clock} instance so\n * tests can drive expiry-window logic deterministically with a fake.\n */\n\n/** Injectable time source. */\nexport interface Clock {\n  /** Milliseconds since Unix epoch. */\n  now(): number;\n}\n\n/** Production {@link Clock} backed by the system wall clock. */\nexport class SystemClock implements Clock {\n  now(): number {\n    return Date.now();\n  }\n}\n","/**\n * Pure path resolution for the credentials file.\n *\n * POSIX: `$XDG_CONFIG_HOME/ratio/credentials` when the override is a\n * non-empty string, otherwise `~/.config/ratio/credentials`.\n * Windows: `%APPDATA%\\ratio\\credentials`, falling back to\n * `<home>\\AppData\\Roaming\\ratio\\credentials` when APPDATA is unset.\n *\n * `path.win32.join` / `path.posix.join` are used explicitly (never bare\n * `path.join`) so the result is deterministic when a test running on a\n * POSIX host fakes `platform === 'win32'`.\n */\n\nimport os from 'node:os';\nimport path from 'node:path';\n\n/** The subset of environment variables the path algorithm consults. */\nexport interface PathEnv {\n  readonly XDG_CONFIG_HOME?: string;\n  readonly APPDATA?: string;\n}\n\n/** Snapshot the two relevant variables from the real process env. */\nfunction snapshotPathEnv(): PathEnv {\n  const snapshot: { XDG_CONFIG_HOME?: string; APPDATA?: string } = {};\n  const xdgConfigHome = process.env['XDG_CONFIG_HOME'];\n  if (xdgConfigHome !== undefined) {\n    snapshot.XDG_CONFIG_HOME = xdgConfigHome;\n  }\n  const appData = process.env['APPDATA'];\n  if (appData !== undefined) {\n    snapshot.APPDATA = appData;\n  }\n  return snapshot;\n}\n\n/**\n * Pure function. Returns the on-disk path for the credentials file.\n * platform defaults to process.platform, homedir defaults to os.homedir(),\n * env defaults to a snapshot of {XDG_CONFIG_HOME, APPDATA} from process.env.\n * All three are injectable so unit tests fake Windows without a Windows host.\n */\nexport function defaultCredentialsPath(\n  platform?: NodeJS.Platform,\n  homedir?: string,\n  env?: PathEnv,\n): string {\n  const resolvedPlatform = platform ?? process.platform;\n  const resolvedHome = homedir ?? os.homedir();\n  const resolvedEnv = env ?? snapshotPathEnv();\n\n  if (resolvedPlatform === 'win32') {\n    const appData = resolvedEnv.APPDATA;\n    const base =\n      appData !== undefined && appData !== ''\n        ? appData\n        : path.win32.join(resolvedHome, 'AppData', 'Roaming');\n    return path.win32.join(base, 'ratio', 'credentials');\n  }\n\n  const xdgConfigHome = resolvedEnv.XDG_CONFIG_HOME;\n  const base =\n    typeof xdgConfigHome === 'string' && xdgConfigHome !== ''\n      ? xdgConfigHome\n      : path.posix.join(resolvedHome, '.config');\n  return path.posix.join(base, 'ratio', 'credentials');\n}\n","/**\n * Error hierarchy for the Ratio CLI. Every error thrown from a command's\n * run() is expected to be an instance of RatioCLIError so the global\n * render-error handler can map it to a deterministic stderr line and exit\n * code. Uncaught Error subclasses render as \"INTERNAL: <msg>\" with exit 1.\n *\n * No import from @oclif/core — this file is dependency-free so tests\n * can import it without oclif overhead.\n */\n\nexport class RatioCLIError extends Error {\n  readonly code: string;\n  readonly exitCode: number;\n  readonly hint?: string;\n  readonly docsUrl?: string;\n\n  constructor(opts: {\n    code: string;\n    exitCode: number;\n    message: string;\n    hint?: string;\n    docsUrl?: string;\n  }) {\n    super(opts.message);\n    this.name = new.target.name;\n    this.code = opts.code;\n    this.exitCode = opts.exitCode;\n    if (opts.hint !== undefined) this.hint = opts.hint;\n    if (opts.docsUrl !== undefined) this.docsUrl = opts.docsUrl;\n  }\n}\n\n/** Coming-soon stub UX. Renders on stdout with exit 0. */\nexport class ComingSoonError extends RatioCLIError {\n  constructor(message: string) {\n    super({ code: 'COMING_SOON', exitCode: 0, message });\n  }\n}\n\n/** User has no credentials and command requires auth. */\nexport class NotLoggedInError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to sign in.\",\n  ) {\n    super({ code: 'NOT_LOGGED_IN', exitCode: 3, message, hint });\n  }\n}\n\nexport class TokenExpiredError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to refresh your session.\",\n  ) {\n    super({ code: 'TOKEN_EXPIRED', exitCode: 3, message, hint });\n  }\n}\n\nexport class ScopeDeniedError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'SCOPE_DENIED',\n      exitCode: 4,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class NetworkError extends RatioCLIError {\n  constructor(message: string, hint: string = 'Check your network and retry.') {\n    super({ code: 'NETWORK_ERROR', exitCode: 5, message, hint });\n  }\n}\n\nexport class RelayConnectError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Verify the tunnel URL and that the auth-server is reachable.',\n  ) {\n    super({ code: 'RELAY_CONNECT', exitCode: 6, message, hint });\n  }\n}\n\nexport class TemplateExistsError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Choose a different name or remove the existing directory.',\n  ) {\n    super({ code: 'TEMPLATE_EXISTS', exitCode: 7, message, hint });\n  }\n}\n\nexport class ValidationError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'VALIDATION_ERROR',\n      exitCode: 8,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class RelayResumeGapError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Reconnect from the current cursor; older events are outside the buffer window.',\n  ) {\n    super({ code: 'RELAY_RESUME_GAP', exitCode: 9, message, hint });\n  }\n}\n\nexport class OrchestratorSpawnError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Could not start your app's dev command — check that the command in ratio.config.jsonc runs from this directory.\",\n  ) {\n    super({ code: 'ORCHESTRATOR_SPAWN', exitCode: 10, message, hint });\n  }\n}\n\nexport class OrchestratorDrainTimeoutError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Your dev command did not exit cleanly within 5 seconds — it was forcibly terminated.',\n  ) {\n    super({ code: 'ORCHESTRATOR_DRAIN', exitCode: 11, message, hint });\n  }\n}\n\nexport function isRatioCLIError(err: unknown): err is RatioCLIError {\n  return err instanceof RatioCLIError;\n}\n","/**\n * Injectable token-refresh seam for the credential store.\n *\n * The store never performs network I/O itself: when a stored token is\n * close to expiry the store calls the injected {@link TokenRefresher}\n * and persists whatever it returns. The concrete HTTP implementation is\n * wired in by the auth commands; this module only defines the seam plus\n * a throw-if-called placeholder used before sign-in support is wired.\n */\n\nimport { NotLoggedInError } from '../errors.js';\nimport type { TokenSet } from './types.js';\n\n/** Injectable seam that exchanges a refresh token for a fresh token set. */\nexport interface TokenRefresher {\n  refresh(refreshToken: string): Promise<TokenSet>;\n}\n\n/**\n * v1 stub. Always rejects with a static-message NotLoggedInError; it\n * never inspects, echoes, or logs the token it was handed. The real\n * HTTP implementation is supplied by the auth commands.\n */\nexport class NotImplementedRefresher implements TokenRefresher {\n  async refresh(refreshToken: string): Promise<TokenSet> {\n    // Deliberately unused: this placeholder must never touch the token.\n    void refreshToken;\n    throw new NotLoggedInError(\n      'Token refresh is not available yet in this CLI version.',\n    );\n  }\n}\n","/**\n * File-backed credential store.\n *\n * Token resolution precedence (highest first):\n *   1. `RATIO_API_TOKEN` from the injected env reader — returned as-is\n *      with ZERO filesystem access and ZERO refresher involvement.\n *   2. The requested profile (default: \"default\") from the credentials\n *      file, silently refreshed via the injected TokenRefresher when it\n *      is within 5 minutes of expiry.\n *\n * Write contract: atomic tmp + rename in the SAME directory, tmp created\n * with mode 0600 at open time (POSIX), parent directory created 0700,\n * belt-and-braces chmod 0600 after rename. On Windows no chmod / mode\n * checks are ever performed. Concurrent writers are last-writer-wins by\n * design — the atomic rename guarantees no half-written file, which is\n * sufficient for a single-developer CLI.\n *\n * No secret (access token, refresh token, raw file contents) is ever\n * included in an error message or a log line.\n */\n\nimport crypto from 'node:crypto';\nimport fs from 'node:fs';\nimport { dirname } from 'node:path';\nimport {\n  NotLoggedInError,\n  TokenExpiredError,\n  ValidationError,\n} from '../errors.js';\nimport { SystemClock } from './clock.js';\nimport type { Clock } from './clock.js';\nimport { defaultCredentialsPath } from './path.js';\nimport { NotImplementedRefresher } from './refresher.js';\nimport type { TokenRefresher } from './refresher.js';\nimport { parseCredentials } from './schema.js';\nimport type { Credentials, DeveloperSession, Profile, TokenSet } from './types.js';\n\n/** Milliseconds before expiry at which a silent refresh is triggered. */\nconst REFRESH_WINDOW_MS = 300_000;\n\n/** Env var that short-circuits all file access when set to a non-empty string. */\nconst ENV_TOKEN_VAR = 'RATIO_API_TOKEN';\n\n/**\n * Env var that short-circuits developer-session file access when set to a\n * non-empty string. Strictly separate from RATIO_API_TOKEN: this one carries\n * the developer sign-in bearer used for app-management calls, never the\n * OAuth access token.\n */\nconst ENV_DEVELOPER_TOKEN_VAR = 'RATIO_DEVELOPER_TOKEN';\n\nexport interface CredentialStoreOptions {\n  /** Defaults to defaultCredentialsPath(). */\n  readonly filePath?: string;\n  /** Defaults to new SystemClock(). */\n  readonly clock?: Clock;\n  /** Defaults to new NotImplementedRefresher(). */\n  readonly refresher?: TokenRefresher;\n  /** Defaults to () => process.env — injected for env-precedence tests. */\n  readonly envReader?: () => Readonly<Record<string, string | undefined>>;\n  /** Defaults to process.platform. */\n  readonly platform?: NodeJS.Platform;\n}\n\nexport interface CredentialStore {\n  /** Reads the full credentials file. Throws NotLoggedInError if missing. */\n  load(): Promise<Credentials>;\n  /** Atomic write with 0600 on POSIX. tmp + rename in same dir. */\n  save(creds: Credentials): Promise<void>;\n  /** Deletes the credentials file. Idempotent. */\n  clear(): Promise<void>;\n  /**\n   * Env precedence: if envReader().RATIO_API_TOKEN is set, returns it\n   * WITHOUT reading the file, WITHOUT touching the refresher, WITHOUT\n   * any fs I/O. This is the auditable \"no disk access\" path.\n   *\n   * Otherwise: reads the file, validates, computes\n   *   msUntilExpiry = new Date(profile.expiresAt).getTime() - clock.now()\n   * If msUntilExpiry < 300_000 (5 min), calls refresher.refresh(...),\n   * persists the new TokenSet atomically, returns the new accessToken.\n   * Otherwise returns profile.accessToken.\n   */\n  getValidAccessToken(profileName?: string): Promise<string>;\n  /**\n   * Env precedence: RATIO_DEVELOPER_TOKEN if set (no fs I/O).\n   * Otherwise: load(); if creds.developer is absent or within 5 minutes of\n   * expiry, throws NotLoggedInError ('Developer signin required.').\n   * Otherwise returns creds.developer.jwt.\n   * NO refresh attempt — the caller drives the re-prompt UX.\n   */\n  getValidDeveloperToken(): Promise<string>;\n  /**\n   * Merge a DeveloperSession into the loaded credentials (creating the file\n   * if absent), atomic tmp+rename, 0600.\n   */\n  saveDeveloperSession(session: DeveloperSession): Promise<void>;\n}\n\n/** Narrow an unknown thrown value to a Node errno error with the given code. */\nfunction hasErrnoCode(err: unknown, code: string): boolean {\n  return (\n    err instanceof Error &&\n    (err as NodeJS.ErrnoException).code === code\n  );\n}\n\nexport class FileCredentialStore implements CredentialStore {\n  private readonly filePath: string;\n  private readonly clock: Clock;\n  private readonly refresher: TokenRefresher;\n  private readonly envReader: () => Readonly<\n    Record<string, string | undefined>\n  >;\n  private readonly platform: NodeJS.Platform;\n\n  constructor(opts?: CredentialStoreOptions) {\n    this.filePath = opts?.filePath ?? defaultCredentialsPath();\n    this.clock = opts?.clock ?? new SystemClock();\n    this.refresher = opts?.refresher ?? new NotImplementedRefresher();\n    this.envReader = opts?.envReader ?? (() => process.env);\n    this.platform = opts?.platform ?? process.platform;\n  }\n\n  async load(): Promise<Credentials> {\n    this.reapplyFileModeIfDrifted();\n\n    let raw: string;\n    try {\n      raw = fs.readFileSync(this.filePath, 'utf8');\n    } catch (err) {\n      if (hasErrnoCode(err, 'ENOENT')) {\n        throw new NotLoggedInError('You are not signed in.');\n      }\n      throw err;\n    }\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Never echo the raw contents — they may hold a truncated token.\n      throw new ValidationError(\n        'credentials file is not valid JSON — run \"ratio auth login\" to reset',\n      );\n    }\n\n    return parseCredentials(parsed);\n  }\n\n  async save(creds: Credentials): Promise<void> {\n    const dir = dirname(this.filePath);\n    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });\n    if (this.platform !== 'win32') {\n      // mkdirSync does not re-mode a pre-existing directory; re-apply.\n      fs.chmodSync(dir, 0o700);\n    }\n\n    const tmpPath = `${this.filePath}.${process.pid}.${crypto\n      .randomBytes(8)\n      .toString('hex')}.tmp`;\n    try {\n      // mode at open time closes the create-then-chmod race window.\n      fs.writeFileSync(tmpPath, JSON.stringify(creds, null, 2), {\n        mode: 0o600,\n      });\n      fs.renameSync(tmpPath, this.filePath);\n    } catch (err) {\n      try {\n        fs.unlinkSync(tmpPath);\n      } catch {\n        // Best-effort cleanup: the tmp file may never have been created.\n      }\n      throw err;\n    }\n\n    if (this.platform !== 'win32') {\n      // Belt-and-braces: rename may preserve a prior destination mode.\n      fs.chmodSync(this.filePath, 0o600);\n    }\n  }\n\n  async clear(): Promise<void> {\n    try {\n      fs.unlinkSync(this.filePath);\n    } catch (err) {\n      if (hasErrnoCode(err, 'ENOENT')) {\n        return; // Idempotent: already gone.\n      }\n      throw err;\n    }\n  }\n\n  async getValidAccessToken(profileName?: string): Promise<string> {\n    const envToken = this.envReader()[ENV_TOKEN_VAR];\n    if (typeof envToken === 'string' && envToken.length > 0) {\n      return envToken;\n    }\n\n    const creds = await this.load();\n    const name = profileName ?? 'default';\n    const profile = creds.profiles[name];\n    if (profile === undefined) {\n      throw new NotLoggedInError('You are not signed in.');\n    }\n\n    const msUntilExpiry =\n      new Date(profile.expiresAt).getTime() - this.clock.now();\n    if (msUntilExpiry < REFRESH_WINDOW_MS) {\n      return this.refreshAndPersist(creds, name, profile);\n    }\n\n    return profile.accessToken;\n  }\n\n  async getValidDeveloperToken(): Promise<string> {\n    const envToken = this.envReader()[ENV_DEVELOPER_TOKEN_VAR];\n    if (typeof envToken === 'string' && envToken.length > 0) {\n      return envToken;\n    }\n\n    let creds: Credentials;\n    try {\n      creds = await this.load();\n    } catch (err) {\n      if (err instanceof NotLoggedInError) {\n        throw new NotLoggedInError('Developer signin required.');\n      }\n      throw err;\n    }\n\n    const session = creds.developer;\n    if (session === undefined) {\n      throw new NotLoggedInError('Developer signin required.');\n    }\n\n    const msUntilExpiry =\n      new Date(session.expiresAt).getTime() - this.clock.now();\n    if (msUntilExpiry < REFRESH_WINDOW_MS) {\n      // No refresh endpoint exists for developer sessions — the caller\n      // drives a fresh interactive sign-in instead.\n      throw new NotLoggedInError('Developer signin required.');\n    }\n\n    return session.jwt;\n  }\n\n  async saveDeveloperSession(session: DeveloperSession): Promise<void> {\n    let creds: Credentials;\n    try {\n      creds = await this.load();\n    } catch (err) {\n      if (err instanceof NotLoggedInError) {\n        // Edge case: no prior credentials file. Create a fresh v1 shell so\n        // the merged write below still validates on the next load().\n        creds = { version: 1, server: '', clientId: '', profiles: {} };\n      } else {\n        throw err;\n      }\n    }\n\n    const updated: Credentials = {\n      ...creds,\n      developer: session,\n    };\n    await this.save(updated);\n  }\n\n  /**\n   * Exchange the profile's refresh token for a fresh token set, merge it\n   * into the loaded credentials (preserving every other profile), persist\n   * atomically, and return the new access token. A refresher failure is\n   * wrapped in TokenExpiredError; the underlying message is deliberately\n   * discarded so a secret can never leak through the error surface.\n   */\n  private async refreshAndPersist(\n    creds: Credentials,\n    name: string,\n    profile: Profile,\n  ): Promise<string> {\n    let refreshed: TokenSet;\n    try {\n      refreshed = await this.refresher.refresh(profile.refreshToken);\n    } catch {\n      throw new TokenExpiredError(\n        'Your session has expired and could not be refreshed.',\n      );\n    }\n\n    const updated: Credentials = {\n      ...creds,\n      profiles: {\n        ...creds.profiles,\n        [name]: {\n          ...profile,\n          accessToken: refreshed.accessToken,\n          refreshToken: refreshed.refreshToken,\n          expiresAt: refreshed.expiresAt,\n        },\n      },\n    };\n    await this.save(updated);\n    return refreshed.accessToken;\n  }\n\n  /**\n   * POSIX-only startup permission check: if the file exists with a mode\n   * other than 0600, re-apply 0600 and emit a warning to stderr. Never\n   * runs on Windows (stat modes there do not map to POSIX bits and chmod\n   * must not be called). Missing file is NOT an error here — load()\n   * reports it as NotLoggedInError.\n   */\n  private reapplyFileModeIfDrifted(): void {\n    if (this.platform === 'win32') {\n      return;\n    }\n\n    let stat: fs.Stats;\n    try {\n      stat = fs.statSync(this.filePath);\n    } catch (err) {\n      if (hasErrnoCode(err, 'ENOENT')) {\n        return; // load() turns the missing file into NotLoggedInError.\n      }\n      throw err;\n    }\n\n    const mode = stat.mode & 0o777;\n    if (mode !== 0o600) {\n      fs.chmodSync(this.filePath, 0o600);\n      process.stderr.write(\n        `[warn] credentials file permissions were 0o${mode.toString(8)}; corrected to 0600.\\n`,\n      );\n    }\n  }\n}\n","/**\n * Runtime validation for the on-disk credentials file.\n *\n * The parser is deliberately strict: unknown top-level keys, missing\n * fields, non-ISO timestamps, and any `version` other than `1` are all\n * rejected with a typed ValidationError. Error messages NEVER embed the\n * raw file contents — a malformed file may contain a truncated token.\n */\n\nimport { z } from 'zod';\nimport { ValidationError } from '../errors.js';\nimport type { Credentials } from './types.js';\n\nconst identitySchema = z\n  .object({\n    developerId: z.string(),\n    email: z.string(),\n    // Token-derived fields captured at login. Optional (additive) so files\n    // written before these fields existed still validate as version 1.\n    merchantId: z.string().optional(),\n    scopes: z.array(z.string()).optional(),\n  })\n  .strict();\n\nconst profileSchema = z\n  .object({\n    accessToken: z.string(),\n    refreshToken: z.string(),\n    expiresAt: z.string().datetime({ offset: true }),\n    identity: identitySchema,\n    obtainedAt: z.string().datetime({ offset: true }),\n  })\n  .strict();\n\nconst developerSessionSchema = z\n  .object({\n    jwt: z.string(),\n    developerId: z.string(),\n    email: z.string(),\n    expiresAt: z.string().datetime({ offset: true }),\n    obtainedAt: z.string().datetime({ offset: true }),\n  })\n  .strict();\n\n/** Strict zod schema for the version-1 credentials file. */\nexport const credentialsSchema = z\n  .object({\n    version: z.literal(1),\n    server: z.string(),\n    clientId: z.string(),\n    profiles: z.record(z.string(), profileSchema),\n    // Optional cached developer session. Additive so files written before\n    // this field existed still validate as version 1.\n    developer: developerSessionSchema.optional(),\n  })\n  .strict();\n\n/**\n * Validate an already-JSON-parsed value against the version-1 shape.\n *\n * Throws ValidationError on any mismatch. A recognisable-but-unsupported\n * `version` gets a dedicated upgrade message; the version label is only\n * echoed when it is a number so arbitrary file contents can never leak\n * into an error message.\n */\nexport function parseCredentials(input: unknown): Credentials {\n  if (typeof input === 'object' && input !== null && 'version' in input) {\n    const version = (input as { version: unknown }).version;\n    if (version !== 1) {\n      const label = typeof version === 'number' ? String(version) : 'unknown';\n      throw new ValidationError(\n        `credentials file version ${label} is unsupported by this CLI — upgrade the CLI or sign in again`,\n      );\n    }\n  }\n\n  const result = credentialsSchema.safeParse(input);\n  if (!result.success) {\n    throw new ValidationError(\n      'credentials file schema mismatch — expected v1 shape',\n    );\n  }\n  return result.data as Credentials;\n}\n","/**\n * Template scaffold engine for `ratio app create`.\n *\n * Renders a bundled app template into a destination directory:\n *\n * - Files ending in `.tmpl` are read as UTF-8 and every `{{key}}`\n *   placeholder is substituted from the provided substitution map,\n *   then written with the `.tmpl` suffix stripped\n *   (`package.json.tmpl` → `package.json`).\n * - All other files are copied byte-for-byte.\n *\n * The engine is intentionally minimal: a single-pass\n * `String.replace(/\\{\\{key\\}\\}/g, …)` with a replacer FUNCTION (so\n * `$&`, `$1`, `$$` in substitution values are never interpreted as\n * special replacement patterns). There is no template library and no\n * recursive substitution — if a substitution value itself contains\n * `{{...}}`, that literal text appears in the output untouched.\n *\n * Every template root carries a `manifest.json`:\n *\n * ```json\n * {\n *   \"name\": \"minimal\",\n *   \"description\": \"Express-based Ratio app (default).\",\n *   \"substitutionKeys\": [\"appName\", \"clientId\", \"sdkVersion\", \"templateName\"]\n * }\n * ```\n *\n * `substitutionKeys` is the closed set of placeholders the template's\n * `.tmpl` files may use. A `{{key}}` found in a `.tmpl` file that is\n * not declared in the manifest is a render-time error\n * (`unknown_substitution_key`). The `manifest.json` itself is copied\n * verbatim into the generated app so tooling can re-inspect which\n * template produced it.\n *\n * The canonical `ratio.config.jsonc` produced by every template has\n * this shape (the scaffolder writes it; `ratio app link` later fills\n * `clientId`):\n *\n * ```jsonc\n * {\n *   // Canonical Ratio app manifest. Committed to the app repo.\n *   // Written by scaffolder; `clientId` filled by `ratio app link`.\n *   \"$schema\": \"https://ratio.app/schema/app-manifest.v1.json\",\n *   \"appName\": \"{{appName}}\",\n *   \"clientId\": \"{{clientId}}\",\n *   \"sdkVersion\": \"{{sdkVersion}}\",\n *   \"template\": \"{{templateName}}\",\n *   \"webhooks\": {\n *     \"path\": \"/webhooks\",\n *     \"topics\": []\n *   },\n *   \"oauth\": {\n *     \"redirectPath\": \"/oauth/callback\",\n *     \"scopes\": []\n *   }\n * }\n * ```\n *\n * The engine does not hardcode that shape — it only substitutes keys —\n * but the block above documents the contract for template authors.\n */\n\nimport { copyFile, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';\nimport { dirname, join, resolve } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/** Per-template metadata, loaded from `<templateRoot>/manifest.json`. */\nexport interface TemplateManifest {\n  /** Template identifier, e.g. 'minimal' | 'with-admin-ui' | 'serverless'. */\n  readonly name: string;\n  readonly description: string;\n  /** Closed set of `{{key}}` placeholders the template's `.tmpl` files may use. */\n  readonly substitutionKeys: readonly string[];\n}\n\nexport interface RenderInput {\n  /** Must match one of the discovered templates. */\n  readonly templateName: string;\n  /** Absolute path to write into. Must be empty (or not yet exist). */\n  readonly destinationDir: string;\n  readonly substitutions: Readonly<Record<string, string>>;\n  /** Overrides template-root discovery (test injection). */\n  readonly sourceRootOverride?: string;\n  /** Called once per file AFTER a successful write. Bytes = per-file, NOT cumulative. */\n  readonly onFile?: (relativePath: string, bytesWritten: number) => void;\n}\n\nexport interface RenderResult {\n  /** Absolute paths, in write order. */\n  readonly filesWritten: readonly string[];\n  readonly bytesWritten: number;\n}\n\nexport type RatioTemplateErrorCode =\n  | 'template_not_found'\n  | 'unknown_substitution_key'\n  | 'missing_substitution_value'\n  | 'destination_not_empty'\n  | 'io_error';\n\n/** Error surface for the scaffold engine. All failures carry a stable `code`. */\nexport class RatioTemplateError extends Error {\n  readonly code: RatioTemplateErrorCode;\n  readonly templateName?: string;\n  readonly key?: string;\n\n  constructor(opts: {\n    readonly code: RatioTemplateErrorCode;\n    readonly message: string;\n    readonly templateName?: string;\n    readonly key?: string;\n    readonly cause?: unknown;\n  }) {\n    super(opts.message, opts.cause === undefined ? undefined : { cause: opts.cause });\n    this.name = 'RatioTemplateError';\n    this.code = opts.code;\n    if (opts.templateName !== undefined) {\n      this.templateName = opts.templateName;\n    }\n    if (opts.key !== undefined) {\n      this.key = opts.key;\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Private: placeholder syntax\n// ---------------------------------------------------------------------------\n\n/** `{{key}}` where key is a leading-alpha identifier. Single pass, global. */\nconst PLACEHOLDER_REGEX = /\\{\\{([a-zA-Z][a-zA-Z0-9_]*)\\}\\}/g;\n\nconst TMPL_SUFFIX = '.tmpl';\n\n// ---------------------------------------------------------------------------\n// Private: source-root discovery\n// ---------------------------------------------------------------------------\n\nasync function isDirectory(path: string): Promise<boolean> {\n  try {\n    return (await stat(path)).isDirectory();\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Locate the templates root. Order:\n *\n * 1. `sourceRootOverride` when provided (test injection).\n * 2. `templates/` next to the compiled module (production —\n *    `dist/templates/`, copied there at build time).\n * 3. `templates/` one level up from the module dir (dev — this file\n *    lives at `src/scaffold/`, templates at `src/templates/`).\n */\nasync function discoverSourceRoot(sourceRootOverride?: string): Promise<string> {\n  if (sourceRootOverride !== undefined) {\n    return sourceRootOverride;\n  }\n  const moduleDir = dirname(fileURLToPath(import.meta.url));\n  const candidates = [join(moduleDir, 'templates'), resolve(moduleDir, '..', 'templates')];\n  for (const candidate of candidates) {\n    if (await isDirectory(candidate)) {\n      return candidate;\n    }\n  }\n  throw new RatioTemplateError({\n    code: 'io_error',\n    message: `templates root not found (looked in: ${candidates.join(', ')})`,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Private: manifest loading\n// ---------------------------------------------------------------------------\n\nfunction assertManifestShape(raw: unknown, path: string): TemplateManifest {\n  if (\n    typeof raw !== 'object' ||\n    raw === null ||\n    typeof (raw as { name?: unknown }).name !== 'string' ||\n    typeof (raw as { description?: unknown }).description !== 'string' ||\n    !Array.isArray((raw as { substitutionKeys?: unknown }).substitutionKeys) ||\n    !(raw as { substitutionKeys: unknown[] }).substitutionKeys.every(\n      (k): k is string => typeof k === 'string',\n    )\n  ) {\n    throw new RatioTemplateError({\n      code: 'io_error',\n      message: `invalid template manifest at ${path}: expected { name, description, substitutionKeys[] }`,\n    });\n  }\n  const shaped = raw as { name: string; description: string; substitutionKeys: string[] };\n  return {\n    name: shaped.name,\n    description: shaped.description,\n    substitutionKeys: shaped.substitutionKeys,\n  };\n}\n\nasync function loadManifest(templateRoot: string): Promise<TemplateManifest> {\n  const manifestPath = join(templateRoot, 'manifest.json');\n  let content: string;\n  try {\n    content = await readFile(manifestPath, 'utf8');\n  } catch (err) {\n    throw new RatioTemplateError({\n      code: 'io_error',\n      message: `failed to read template manifest at ${manifestPath}`,\n      cause: err,\n    });\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(content);\n  } catch (err) {\n    throw new RatioTemplateError({\n      code: 'io_error',\n      message: `template manifest at ${manifestPath} is not valid JSON`,\n      cause: err,\n    });\n  }\n  return assertManifestShape(parsed, manifestPath);\n}\n\n// ---------------------------------------------------------------------------\n// Private: substitution (single pass, replacer function — never a string)\n// ---------------------------------------------------------------------------\n\nfunction substituteContent(\n  content: string,\n  substitutions: Readonly<Record<string, string>>,\n  allowedKeys: ReadonlySet<string>,\n  templateName: string,\n): string {\n  // Replacer FUNCTION: return values are inserted literally, so `$&`,\n  // `$1`, `$$` in a substitution value are never expanded. Output is\n  // NOT re-scanned — no recursive substitution.\n  return content.replace(PLACEHOLDER_REGEX, (_match, key: string) => {\n    if (!allowedKeys.has(key)) {\n      throw new RatioTemplateError({\n        code: 'unknown_substitution_key',\n        message: `placeholder {{${key}}} is not declared in the template manifest's substitutionKeys`,\n        templateName,\n        key,\n      });\n    }\n    const value = substitutions[key];\n    if (value === undefined) {\n      throw new RatioTemplateError({\n        code: 'missing_substitution_value',\n        message: `no substitution value provided for {{${key}}}`,\n        templateName,\n        key,\n      });\n    }\n    return value;\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Private: tree walk (stable, sorted order)\n// ---------------------------------------------------------------------------\n\ninterface TemplateFile {\n  /** Path relative to the template root, POSIX-joined by node:path. */\n  readonly relativePath: string;\n  readonly absolutePath: string;\n}\n\nasync function walkTemplateTree(root: string, relative = ''): Promise<TemplateFile[]> {\n  const entries = await readdir(join(root, relative), { withFileTypes: true });\n  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));\n  const files: TemplateFile[] = [];\n  for (const entry of entries) {\n    const rel = relative === '' ? entry.name : join(relative, entry.name);\n    if (entry.isDirectory()) {\n      files.push(...(await walkTemplateTree(root, rel)));\n    } else {\n      files.push({ relativePath: rel, absolutePath: join(root, rel) });\n    }\n  }\n  return files;\n}\n\n// ---------------------------------------------------------------------------\n// Public: listTemplates\n// ---------------------------------------------------------------------------\n\n/**\n * Discover all bundled templates and return their manifests, sorted by\n * template directory name for a stable order.\n */\nexport async function listTemplates(\n  sourceRootOverride?: string,\n): Promise<readonly TemplateManifest[]> {\n  const sourceRoot = await discoverSourceRoot(sourceRootOverride);\n  let entries;\n  try {\n    entries = await readdir(sourceRoot, { withFileTypes: true });\n  } catch (err) {\n    throw new RatioTemplateError({\n      code: 'io_error',\n      message: `failed to read templates root at ${sourceRoot}`,\n      cause: err,\n    });\n  }\n  const dirs = entries\n    .filter((e) => e.isDirectory())\n    .map((e) => e.name)\n    .sort();\n  const manifests: TemplateManifest[] = [];\n  for (const dir of dirs) {\n    manifests.push(await loadManifest(join(sourceRoot, dir)));\n  }\n  return manifests;\n}\n\n// ---------------------------------------------------------------------------\n// Public: renderTemplate\n// ---------------------------------------------------------------------------\n\n/**\n * Render the named template into `destinationDir`.\n *\n * Strict about its destination: if the directory already contains any\n * entry the render throws `destination_not_empty` — the caller owns\n * the \"directory already has content\" UX.\n */\nexport async function renderTemplate(input: RenderInput): Promise<RenderResult> {\n  const sourceRoot = await discoverSourceRoot(input.sourceRootOverride);\n  const templateRoot = join(sourceRoot, input.templateName);\n\n  if (!(await isDirectory(templateRoot))) {\n    throw new RatioTemplateError({\n      code: 'template_not_found',\n      message: `template '${input.templateName}' not found under ${sourceRoot}`,\n      templateName: input.templateName,\n    });\n  }\n\n  const manifest = await loadManifest(templateRoot);\n  const allowedKeys = new Set(manifest.substitutionKeys);\n\n  // Destination must be empty (or absent — created on demand).\n  try {\n    const existing = await readdir(input.destinationDir);\n    if (existing.length > 0) {\n      throw new RatioTemplateError({\n        code: 'destination_not_empty',\n        message: `destination directory ${input.destinationDir} is not empty`,\n        templateName: input.templateName,\n      });\n    }\n  } catch (err) {\n    if (err instanceof RatioTemplateError) {\n      throw err;\n    }\n    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {\n      throw new RatioTemplateError({\n        code: 'io_error',\n        message: `failed to inspect destination directory ${input.destinationDir}`,\n        templateName: input.templateName,\n        cause: err,\n      });\n    }\n  }\n\n  let files: TemplateFile[];\n  try {\n    files = await walkTemplateTree(templateRoot);\n  } catch (err) {\n    throw new RatioTemplateError({\n      code: 'io_error',\n      message: `failed to walk template tree at ${templateRoot}`,\n      templateName: input.templateName,\n      cause: err,\n    });\n  }\n\n  const filesWritten: string[] = [];\n  let bytesWritten = 0;\n\n  for (const file of files) {\n    const isTmpl = file.relativePath.endsWith(TMPL_SUFFIX);\n    const outRelative = isTmpl\n      ? file.relativePath.slice(0, -TMPL_SUFFIX.length)\n      : file.relativePath;\n    // npm-packlist strips `.gitignore` files from the published tarball, so\n    // templates ship the file as `gitignore` (template ROOT only — no `/` in\n    // the relative path) and the engine renames it back on render. This is a\n    // single explicit special case, not a general dot-strip convention.\n    const isTopLevelGitignore = file.relativePath === 'gitignore';\n    const effectiveOutRelative = isTopLevelGitignore ? '.gitignore' : outRelative;\n    const outPath = join(input.destinationDir, effectiveOutRelative);\n    let perFileBytes = 0;\n\n    if (isTmpl) {\n      let raw: string;\n      try {\n        raw = await readFile(file.absolutePath, 'utf8');\n      } catch (err) {\n        throw new RatioTemplateError({\n          code: 'io_error',\n          message: `failed to read template file ${file.absolutePath}`,\n          templateName: input.templateName,\n          cause: err,\n        });\n      }\n      // May throw unknown_substitution_key / missing_substitution_value —\n      // deliberately NOT wrapped as io_error.\n      const rendered = substituteContent(\n        raw,\n        input.substitutions,\n        allowedKeys,\n        input.templateName,\n      );\n      try {\n        await mkdir(dirname(outPath), { recursive: true });\n        await writeFile(outPath, rendered, 'utf8');\n      } catch (err) {\n        throw new RatioTemplateError({\n          code: 'io_error',\n          message: `failed to write rendered file ${outPath}`,\n          templateName: input.templateName,\n          cause: err,\n        });\n      }\n      perFileBytes = Buffer.byteLength(rendered, 'utf8');\n      bytesWritten += perFileBytes;\n    } else {\n      try {\n        await mkdir(dirname(outPath), { recursive: true });\n        await copyFile(file.absolutePath, outPath);\n        perFileBytes = (await stat(outPath)).size;\n        bytesWritten += perFileBytes;\n      } catch (err) {\n        throw new RatioTemplateError({\n          code: 'io_error',\n          message: `failed to copy file ${file.absolutePath} to ${outPath}`,\n          templateName: input.templateName,\n          cause: err,\n        });\n      }\n    }\n    filesWritten.push(outPath);\n    if (input.onFile !== undefined) {\n      try {\n        input.onFile(effectiveOutRelative, perFileBytes);\n      } catch (err) {\n        throw new RatioTemplateError({\n          code: 'io_error',\n          message: 'onFile callback threw',\n          templateName: input.templateName,\n          cause: err,\n        });\n      }\n    }\n  }\n\n  return { filesWritten, bytesWritten };\n}\n","/**\n * Official Ratio developer CLI.\n */\nexport const CLI_NAME = '@ratio-app/cli';\n\n// Dev-store gate — re-exported so external consumers can depend on the\n// interface and the singleton factory without importing the internal path.\nexport type { DevStoreGate, DevStoreGateContext } from './lib/dev-store-gate.js';\nexport { NoopDevStoreGate, getDevStoreGate } from './lib/dev-store-gate.js';\n\n// Credential store — re-exported so external consumers can depend on\n// the interface and the default implementation without importing the\n// internal path.\nexport type {\n  Credentials,\n  Profile,\n  Identity,\n  TokenSet,\n  Clock,\n  PathEnv,\n  TokenRefresher,\n  CredentialStore,\n  CredentialStoreOptions,\n} from './lib/credentials/index.js';\nexport {\n  SystemClock,\n  defaultCredentialsPath,\n  NotImplementedRefresher,\n  FileCredentialStore,\n} from './lib/credentials/index.js';\n\n// Scaffold engine — re-exported so the app-create scaffolder (and\n// external consumers) can render bundled templates without importing\n// the internal path.\nexport type { TemplateManifest, RenderInput, RenderResult } from './scaffold/index.js';\nexport { renderTemplate, listTemplates, RatioTemplateError } from './scaffold/index.js';\n"],"mappings":"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","names":["base","stat","dirname","path"]}

package/dist/lib/auth/authorize-code-exchange.d.ts

@@ -0,0 +1,50 @@
+import { TokenSet } from '../credentials/types.js';
+import { RATIO_CLI_CLIENT_ID } from './config.js';
+import { VerboseTracer } from './verbose-trace.js';
+
+/**
+ * OAuth authorization-code exchange step.
+ *
+ * Used by BOTH the browser flow (with redirectUri) and the manual flow
+ * (without redirectUri). Returns typed tokens + identity derived from
+ * the token response.
+ *
+ * A-29 adjudication: identity = token-derived {clientId, merchantId, scopes}.
+ * The backend token envelope does not expose developerId/email. This is a
+ * known ADR contradiction resolved pre-implementation; the schema tolerates
+ * absence and additive identity fields can be added when a backend endpoint
+ * for developer identity is available.
+ *
+ * Token response schema is pinned with zod for fast detection of envelope drift.
+ * Any schema mismatch throws a static-message ValidationError — the raw body
+ * is never included in any error message (secret-leak prevention).
+ */
+
+/** Token-derived identity (A-29 shape). */
+interface TokenDerivedIdentity {
+    readonly clientId: string;
+    readonly merchantId: string;
+    readonly scopes: readonly string[];
+}
+interface CodeExchangeInput {
+    readonly serverUrl: string;
+    readonly code: string;
+    readonly codeVerifier: string;
+    readonly redirectUri?: string;
+    readonly clientId: typeof RATIO_CLI_CLIENT_ID;
+    readonly fetchImpl?: typeof fetch;
+    /** Verbose diagnostic sink — never receives token/code/verifier/state. */
+    readonly trace?: VerboseTracer;
+}
+interface CodeExchangeOutput {
+    readonly tokens: TokenSet;
+    readonly identity: TokenDerivedIdentity;
+}
+/**
+ * Exchange an authorization code for tokens.
+ * POSTs to /oauth/token with grant_type=authorization_code.
+ * Never logs or includes token values in error messages.
+ */
+declare function exchangeCodeForTokens(i: CodeExchangeInput): Promise<CodeExchangeOutput>;
+
+export { type CodeExchangeInput, type CodeExchangeOutput, type TokenDerivedIdentity, exchangeCodeForTokens };

package/dist/lib/auth/authorize-code-exchange.js

@@ -0,0 +1,114 @@
+// src/lib/auth/authorize-code-exchange.ts
+import { z } from "zod";
+
+// src/lib/errors.ts
+var RatioCLIError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  docsUrl;
+  constructor(opts) {
+    super(opts.message);
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    if (opts.hint !== void 0) this.hint = opts.hint;
+    if (opts.docsUrl !== void 0) this.docsUrl = opts.docsUrl;
+  }
+};
+var NetworkError = class extends RatioCLIError {
+  constructor(message, hint = "Check your network and retry.") {
+    super({ code: "NETWORK_ERROR", exitCode: 5, message, hint });
+  }
+};
+var ValidationError = class extends RatioCLIError {
+  constructor(message, hint) {
+    const opts = {
+      code: "VALIDATION_ERROR",
+      exitCode: 8,
+      message
+    };
+    if (hint !== void 0) opts.hint = hint;
+    super(opts);
+  }
+};
+
+// src/lib/auth/verbose-trace.ts
+var noopTracer = () => {
+};
+
+// src/lib/auth/authorize-code-exchange.ts
+var TokenResponseSchema = z.object({
+  access_token: z.string().min(1),
+  refresh_token: z.string().min(1),
+  expires_in: z.number().int().positive(),
+  token_type: z.string().optional(),
+  scope: z.string().optional(),
+  merchant_id: z.string().optional()
+});
+function exchangeCodeForTokens(i) {
+  return _exchangeCodeForTokensImpl(i);
+}
+async function _exchangeCodeForTokensImpl(i) {
+  const fetchFn = i.fetchImpl ?? fetch;
+  const body = {
+    grant_type: "authorization_code",
+    code: i.code,
+    clientId: i.clientId,
+    codeVerifier: i.codeVerifier
+  };
+  if (i.redirectUri !== void 0) {
+    body["redirectUri"] = i.redirectUri;
+  }
+  const trace = i.trace ?? noopTracer;
+  const startedAt = Date.now();
+  let response;
+  try {
+    response = await fetchFn(`${i.serverUrl}/oauth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+  } catch {
+    trace(`POST /oauth/token \u2192 network error (${Date.now() - startedAt}ms)`);
+    throw new NetworkError("Failed to reach the Ratio server during token exchange.");
+  }
+  trace(`POST /oauth/token \u2192 ${response.status} (${Date.now() - startedAt}ms)`);
+  if (response.status >= 400 && response.status < 500) {
+    throw new ValidationError(
+      "The authorization code was rejected. Run 'ratio auth login' again."
+    );
+  }
+  if (response.status >= 500 || !response.ok) {
+    throw new NetworkError("The Ratio server returned an error during token exchange.");
+  }
+  let raw;
+  try {
+    raw = await response.json();
+  } catch {
+    throw new ValidationError("Token response was not valid JSON.");
+  }
+  const parsed = TokenResponseSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new ValidationError("Token response shape was unexpected. Run ratio auth login again.");
+  }
+  const data = parsed.data;
+  const expiresAt = new Date(Date.now() + data.expires_in * 1e3).toISOString();
+  const tokens = {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresAt
+  };
+  const scopeStr = data.scope ?? "";
+  const scopes = scopeStr.length > 0 ? scopeStr.split(/[\s,]+/).filter(Boolean) : [];
+  const identity = {
+    clientId: i.clientId,
+    merchantId: data.merchant_id ?? "ratio-cli-dev",
+    scopes
+  };
+  return { tokens, identity };
+}
+export {
+  exchangeCodeForTokens
+};
+//# sourceMappingURL=authorize-code-exchange.js.map

package/dist/lib/auth/authorize-code-exchange.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/auth/authorize-code-exchange.ts","../../../src/lib/errors.ts","../../../src/lib/auth/verbose-trace.ts"],"sourcesContent":["/**\n * OAuth authorization-code exchange step.\n *\n * Used by BOTH the browser flow (with redirectUri) and the manual flow\n * (without redirectUri). Returns typed tokens + identity derived from\n * the token response.\n *\n * A-29 adjudication: identity = token-derived {clientId, merchantId, scopes}.\n * The backend token envelope does not expose developerId/email. This is a\n * known ADR contradiction resolved pre-implementation; the schema tolerates\n * absence and additive identity fields can be added when a backend endpoint\n * for developer identity is available.\n *\n * Token response schema is pinned with zod for fast detection of envelope drift.\n * Any schema mismatch throws a static-message ValidationError — the raw body\n * is never included in any error message (secret-leak prevention).\n */\n\nimport { z } from 'zod';\nimport { NetworkError, ValidationError } from '../errors.js';\nimport type { TokenSet } from '../credentials/index.js';\nimport { RATIO_CLI_CLIENT_ID } from './config.js';\nimport { noopTracer } from './verbose-trace.js';\nimport type { VerboseTracer } from './verbose-trace.js';\n\n/** Token response envelope from POST /oauth/token (authorization_code grant). */\nconst TokenResponseSchema = z.object({\n  access_token: z.string().min(1),\n  refresh_token: z.string().min(1),\n  expires_in: z.number().int().positive(),\n  token_type: z.string().optional(),\n  scope: z.string().optional(),\n  merchant_id: z.string().optional(),\n});\n\n/** Token-derived identity (A-29 shape). */\nexport interface TokenDerivedIdentity {\n  readonly clientId: string;\n  readonly merchantId: string;\n  readonly scopes: readonly string[];\n}\n\nexport interface CodeExchangeInput {\n  readonly serverUrl: string;\n  readonly code: string;\n  readonly codeVerifier: string;\n  readonly redirectUri?: string;          // undefined for --manual\n  readonly clientId: typeof RATIO_CLI_CLIENT_ID;\n  readonly fetchImpl?: typeof fetch;      // injectable for tests\n  /** Verbose diagnostic sink — never receives token/code/verifier/state. */\n  readonly trace?: VerboseTracer;\n}\n\nexport interface CodeExchangeOutput {\n  readonly tokens: TokenSet;\n  readonly identity: TokenDerivedIdentity;\n}\n\n/**\n * Exchange an authorization code for tokens.\n * POSTs to /oauth/token with grant_type=authorization_code.\n * Never logs or includes token values in error messages.\n */\nexport function exchangeCodeForTokens(i: CodeExchangeInput): Promise<CodeExchangeOutput> {\n  return _exchangeCodeForTokensImpl(i);\n}\n\nasync function _exchangeCodeForTokensImpl(i: CodeExchangeInput): Promise<CodeExchangeOutput> {\n  const fetchFn = i.fetchImpl ?? fetch;\n\n  const body: Record<string, string> = {\n    grant_type: 'authorization_code',\n    code: i.code,\n    clientId: i.clientId,\n    codeVerifier: i.codeVerifier,\n  };\n  if (i.redirectUri !== undefined) {\n    body['redirectUri'] = i.redirectUri;\n  }\n\n  const trace = i.trace ?? noopTracer;\n  const startedAt = Date.now();\n\n  let response: Response;\n  try {\n    response = await fetchFn(`${i.serverUrl}/oauth/token`, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(body),\n    });\n  } catch {\n    trace(`POST /oauth/token → network error (${Date.now() - startedAt}ms)`);\n    throw new NetworkError('Failed to reach the Ratio server during token exchange.');\n  }\n\n  trace(`POST /oauth/token → ${response.status} (${Date.now() - startedAt}ms)`);\n\n  if (response.status >= 400 && response.status < 500) {\n    throw new ValidationError(\n      \"The authorization code was rejected. Run 'ratio auth login' again.\",\n    );\n  }\n\n  if (response.status >= 500 || !response.ok) {\n    throw new NetworkError('The Ratio server returned an error during token exchange.');\n  }\n\n  let raw: unknown;\n  try {\n    raw = await response.json();\n  } catch {\n    throw new ValidationError('Token response was not valid JSON.');\n  }\n\n  const parsed = TokenResponseSchema.safeParse(raw);\n  if (!parsed.success) {\n    throw new ValidationError('Token response shape was unexpected. Run ratio auth login again.');\n  }\n\n  const data = parsed.data;\n  const expiresAt = new Date(Date.now() + data.expires_in * 1000).toISOString();\n\n  const tokens: TokenSet = {\n    accessToken: data.access_token,\n    refreshToken: data.refresh_token,\n    expiresAt,\n  };\n\n  const scopeStr = data.scope ?? '';\n  const scopes = scopeStr.length > 0 ? scopeStr.split(/[\\s,]+/).filter(Boolean) : [];\n\n  const identity: TokenDerivedIdentity = {\n    clientId: i.clientId,\n    merchantId: data.merchant_id ?? 'ratio-cli-dev',\n    scopes,\n  };\n\n  return { tokens, identity };\n}\n","/**\n * Error hierarchy for the Ratio CLI. Every error thrown from a command's\n * run() is expected to be an instance of RatioCLIError so the global\n * render-error handler can map it to a deterministic stderr line and exit\n * code. Uncaught Error subclasses render as \"INTERNAL: <msg>\" with exit 1.\n *\n * No import from @oclif/core — this file is dependency-free so tests\n * can import it without oclif overhead.\n */\n\nexport class RatioCLIError extends Error {\n  readonly code: string;\n  readonly exitCode: number;\n  readonly hint?: string;\n  readonly docsUrl?: string;\n\n  constructor(opts: {\n    code: string;\n    exitCode: number;\n    message: string;\n    hint?: string;\n    docsUrl?: string;\n  }) {\n    super(opts.message);\n    this.name = new.target.name;\n    this.code = opts.code;\n    this.exitCode = opts.exitCode;\n    if (opts.hint !== undefined) this.hint = opts.hint;\n    if (opts.docsUrl !== undefined) this.docsUrl = opts.docsUrl;\n  }\n}\n\n/** Coming-soon stub UX. Renders on stdout with exit 0. */\nexport class ComingSoonError extends RatioCLIError {\n  constructor(message: string) {\n    super({ code: 'COMING_SOON', exitCode: 0, message });\n  }\n}\n\n/** User has no credentials and command requires auth. */\nexport class NotLoggedInError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to sign in.\",\n  ) {\n    super({ code: 'NOT_LOGGED_IN', exitCode: 3, message, hint });\n  }\n}\n\nexport class TokenExpiredError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to refresh your session.\",\n  ) {\n    super({ code: 'TOKEN_EXPIRED', exitCode: 3, message, hint });\n  }\n}\n\nexport class ScopeDeniedError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'SCOPE_DENIED',\n      exitCode: 4,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class NetworkError extends RatioCLIError {\n  constructor(message: string, hint: string = 'Check your network and retry.') {\n    super({ code: 'NETWORK_ERROR', exitCode: 5, message, hint });\n  }\n}\n\nexport class RelayConnectError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Verify the tunnel URL and that the auth-server is reachable.',\n  ) {\n    super({ code: 'RELAY_CONNECT', exitCode: 6, message, hint });\n  }\n}\n\nexport class TemplateExistsError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Choose a different name or remove the existing directory.',\n  ) {\n    super({ code: 'TEMPLATE_EXISTS', exitCode: 7, message, hint });\n  }\n}\n\nexport class ValidationError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'VALIDATION_ERROR',\n      exitCode: 8,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class RelayResumeGapError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Reconnect from the current cursor; older events are outside the buffer window.',\n  ) {\n    super({ code: 'RELAY_RESUME_GAP', exitCode: 9, message, hint });\n  }\n}\n\nexport class OrchestratorSpawnError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Could not start your app's dev command — check that the command in ratio.config.jsonc runs from this directory.\",\n  ) {\n    super({ code: 'ORCHESTRATOR_SPAWN', exitCode: 10, message, hint });\n  }\n}\n\nexport class OrchestratorDrainTimeoutError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Your dev command did not exit cleanly within 5 seconds — it was forcibly terminated.',\n  ) {\n    super({ code: 'ORCHESTRATOR_DRAIN', exitCode: 11, message, hint });\n  }\n}\n\nexport function isRatioCLIError(err: unknown): err is RatioCLIError {\n  return err instanceof RatioCLIError;\n}\n","/**\n * Minimal verbose diagnostic seam for the auth flow.\n *\n * When `--verbose` is on, the auth HTTP/loopback boundaries emit ONE line\n * per boundary crossing (method, path, status, timing, flow events) so a\n * failing login/refresh can be diagnosed from the CLI transcript alone.\n *\n * Safety contract (enforced by tests):\n *  - Lines go to STDERR only — never stdout — so `--json` consumers and\n *    shell pipelines are never corrupted.\n *  - NO secret material is ever passed to a tracer: no access/refresh\n *    token, no authorization code, no code_verifier, no state value.\n *    Only method, path, HTTP status, port numbers, and durations.\n */\n\n/** A tracer receives one pre-formatted diagnostic message per event. */\nexport type VerboseTracer = (msg: string) => void;\n\n/** Shared no-op used when `--verbose` is off (default everywhere). */\nexport const noopTracer: VerboseTracer = () => {};\n\n/**\n * Build a tracer. Returns the shared no-op unless `verbose` is true.\n * Output sink is injectable for tests; defaults to process.stderr.\n */\nexport function createVerboseTracer(\n  verbose: boolean,\n  write: (line: string) => void = (line) => {\n    process.stderr.write(line);\n  },\n): VerboseTracer {\n  if (!verbose) return noopTracer;\n  return (msg: string) => {\n    write(`[verbose] ${msg}\\n`);\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/lib/auth/authorize-url.d.ts

@@ -0,0 +1,42 @@
+import { RATIO_CLI_CLIENT_ID } from './config.js';
+
+/**
+ * Pure URL builders for the OAuth authorization step.
+ *
+ * The browser flow uses a redirectUri (loopback callback) so the portal
+ * redirects back to the CLI. The manual flow uses ?display_code=1 so
+ * the portal renders a copyable code for the user to paste.
+ *
+ * Zero network I/O in this module — pure string construction only.
+ */
+
+interface AuthorizeUrlBrowserOptions {
+    readonly serverUrl: string;
+    readonly clientId: typeof RATIO_CLI_CLIENT_ID;
+    readonly codeChallenge: string;
+    readonly state: string;
+    readonly redirectUri: string;
+    readonly scopes?: readonly string[];
+    readonly merchantId?: string;
+}
+interface AuthorizeUrlManualOptions {
+    readonly serverUrl: string;
+    readonly clientId: typeof RATIO_CLI_CLIENT_ID;
+    readonly codeChallenge: string;
+    readonly state: string;
+    readonly scopes?: readonly string[];
+    readonly merchantId?: string;
+}
+/**
+ * Build the authorize URL for the browser flow.
+ * Includes redirect_uri for the loopback callback; does NOT include display_code.
+ */
+declare function buildBrowserAuthorizeUrl(o: AuthorizeUrlBrowserOptions): string;
+/**
+ * Build the authorize URL for the manual copy-paste flow.
+ * Includes display_code=1 so the portal renders a copyable code.
+ * Does NOT include redirect_uri.
+ */
+declare function buildManualAuthorizeUrl(o: AuthorizeUrlManualOptions): string;
+
+export { type AuthorizeUrlBrowserOptions, type AuthorizeUrlManualOptions, buildBrowserAuthorizeUrl, buildManualAuthorizeUrl };

package/dist/lib/auth/authorize-url.js

@@ -0,0 +1,35 @@
+// src/lib/auth/config.ts
+var RATIO_CLI_MERCHANT_ID = "ratio-cli-dev";
+
+// src/lib/auth/authorize-url.ts
+function buildBrowserAuthorizeUrl(o) {
+  const params = new URLSearchParams();
+  params.set("client_id", o.clientId);
+  params.set("merchant_id", o.merchantId ?? RATIO_CLI_MERCHANT_ID);
+  params.set("code_challenge", o.codeChallenge);
+  params.set("code_challenge_method", "S256");
+  params.set("state", o.state);
+  params.set("redirect_uri", o.redirectUri);
+  if (o.scopes && o.scopes.length > 0) {
+    params.set("scope", o.scopes.join(","));
+  }
+  return `${o.serverUrl}/oauth/authorize?${params.toString()}`;
+}
+function buildManualAuthorizeUrl(o) {
+  const params = new URLSearchParams();
+  params.set("client_id", o.clientId);
+  params.set("merchant_id", o.merchantId ?? RATIO_CLI_MERCHANT_ID);
+  params.set("code_challenge", o.codeChallenge);
+  params.set("code_challenge_method", "S256");
+  params.set("state", o.state);
+  params.set("display_code", "1");
+  if (o.scopes && o.scopes.length > 0) {
+    params.set("scope", o.scopes.join(","));
+  }
+  return `${o.serverUrl}/oauth/authorize?${params.toString()}`;
+}
+export {
+  buildBrowserAuthorizeUrl,
+  buildManualAuthorizeUrl
+};
+//# sourceMappingURL=authorize-url.js.map

package/dist/lib/auth/authorize-url.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/auth/config.ts","../../../src/lib/auth/authorize-url.ts"],"sourcesContent":["/**\n * Server-URL resolution for the Ratio CLI auth flow.\n *\n * Resolution order (highest priority first):\n *   1. RATIO_SERVER_URL environment variable\n *   2. Credentials.server from the stored credential file (passed in as opts.credentials.server)\n *   3. The compiled-in default: https://gkx.ratio.win\n *\n * The default is the ONLY place this URL appears in non-config source files.\n * All other auth-library modules call resolveServerUrl() — never hardcode.\n *\n * A-28: the merchantId constant lives here so it appears in exactly ONE\n * production file and is grep-able.\n */\n\n/** Compiled-in default server URL. */\nexport const DEFAULT_SERVER_URL = 'https://gkx.ratio.win';\n\n/**\n * Synthetic merchantId sent in the authorize URL.\n * A-28 adjudication: backend auto-creates missing merchants via\n * ensureMerchantExists(); 'ratio-cli-dev' is the designated synthetic value.\n * Appears in exactly ONE production file (this one).\n */\nexport const RATIO_CLI_MERCHANT_ID = 'ratio-cli-dev';\n\n/** The fixed clientId for the ratio-cli public OAuth client. */\nexport const RATIO_CLI_CLIENT_ID = 'ratio-cli' as const;\n\nexport interface ServerConfig {\n  readonly url: string;\n}\n\nexport interface ResolveServerUrlOptions {\n  readonly credentials?: { readonly server?: string };\n  readonly env?: Readonly<Record<string, string | undefined>>;\n}\n\n/**\n * Resolve the backend server URL using the three-level precedence chain.\n * Injectable for tests: pass `env` to avoid reading `process.env` directly.\n */\nexport function resolveServerUrl(opts?: ResolveServerUrlOptions): string {\n  const env = opts?.env ?? process.env;\n  if (typeof env['RATIO_SERVER_URL'] === 'string' && env['RATIO_SERVER_URL'].length > 0) {\n    return env['RATIO_SERVER_URL'];\n  }\n  if (typeof opts?.credentials?.server === 'string' && opts.credentials.server.length > 0) {\n    return opts.credentials.server;\n  }\n  return DEFAULT_SERVER_URL;\n}\n","/**\n * Pure URL builders for the OAuth authorization step.\n *\n * The browser flow uses a redirectUri (loopback callback) so the portal\n * redirects back to the CLI. The manual flow uses ?display_code=1 so\n * the portal renders a copyable code for the user to paste.\n *\n * Zero network I/O in this module — pure string construction only.\n */\n\nimport { RATIO_CLI_CLIENT_ID, RATIO_CLI_MERCHANT_ID } from './config.js';\n\nexport interface AuthorizeUrlBrowserOptions {\n  readonly serverUrl: string;\n  readonly clientId: typeof RATIO_CLI_CLIENT_ID;\n  readonly codeChallenge: string;\n  readonly state: string;\n  readonly redirectUri: string;    // http://127.0.0.1:<port>/callback\n  readonly scopes?: readonly string[];\n  readonly merchantId?: string;\n}\n\nexport interface AuthorizeUrlManualOptions {\n  readonly serverUrl: string;\n  readonly clientId: typeof RATIO_CLI_CLIENT_ID;\n  readonly codeChallenge: string;\n  readonly state: string;\n  readonly scopes?: readonly string[];\n  readonly merchantId?: string;\n}\n\n/**\n * Build the authorize URL for the browser flow.\n * Includes redirect_uri for the loopback callback; does NOT include display_code.\n */\nexport function buildBrowserAuthorizeUrl(o: AuthorizeUrlBrowserOptions): string {\n  const params = new URLSearchParams();\n  params.set('client_id', o.clientId);\n  params.set('merchant_id', o.merchantId ?? RATIO_CLI_MERCHANT_ID);\n  params.set('code_challenge', o.codeChallenge);\n  params.set('code_challenge_method', 'S256');\n  params.set('state', o.state);\n  params.set('redirect_uri', o.redirectUri);\n  if (o.scopes && o.scopes.length > 0) {\n    params.set('scope', o.scopes.join(','));\n  }\n  return `${o.serverUrl}/oauth/authorize?${params.toString()}`;\n}\n\n/**\n * Build the authorize URL for the manual copy-paste flow.\n * Includes display_code=1 so the portal renders a copyable code.\n * Does NOT include redirect_uri.\n */\nexport function buildManualAuthorizeUrl(o: AuthorizeUrlManualOptions): string {\n  const params = new URLSearchParams();\n  params.set('client_id', o.clientId);\n  params.set('merchant_id', o.merchantId ?? RATIO_CLI_MERCHANT_ID);\n  params.set('code_challenge', o.codeChallenge);\n  params.set('code_challenge_method', 'S256');\n  params.set('state', o.state);\n  params.set('display_code', '1');\n  if (o.scopes && o.scopes.length > 0) {\n    params.set('scope', o.scopes.join(','));\n  }\n  return `${o.serverUrl}/oauth/authorize?${params.toString()}`;\n}\n"],"mappings":";AAwBO,IAAM,wBAAwB;;;ACW9B,SAAS,yBAAyB,GAAuC;AAC9E,QAAM,SAAS,IAAI,gBAAgB;AACnC,SAAO,IAAI,aAAa,EAAE,QAAQ;AAClC,SAAO,IAAI,eAAe,EAAE,cAAc,qBAAqB;AAC/D,SAAO,IAAI,kBAAkB,EAAE,aAAa;AAC5C,SAAO,IAAI,yBAAyB,MAAM;AAC1C,SAAO,IAAI,SAAS,EAAE,KAAK;AAC3B,SAAO,IAAI,gBAAgB,EAAE,WAAW;AACxC,MAAI,EAAE,UAAU,EAAE,OAAO,SAAS,GAAG;AACnC,WAAO,IAAI,SAAS,EAAE,OAAO,KAAK,GAAG,CAAC;AAAA,EACxC;AACA,SAAO,GAAG,EAAE,SAAS,oBAAoB,OAAO,SAAS,CAAC;AAC5D;AAOO,SAAS,wBAAwB,GAAsC;AAC5E,QAAM,SAAS,IAAI,gBAAgB;AACnC,SAAO,IAAI,aAAa,EAAE,QAAQ;AAClC,SAAO,IAAI,eAAe,EAAE,cAAc,qBAAqB;AAC/D,SAAO,IAAI,kBAAkB,EAAE,aAAa;AAC5C,SAAO,IAAI,yBAAyB,MAAM;AAC1C,SAAO,IAAI,SAAS,EAAE,KAAK;AAC3B,SAAO,IAAI,gBAAgB,GAAG;AAC9B,MAAI,EAAE,UAAU,EAAE,OAAO,SAAS,GAAG;AACnC,WAAO,IAAI,SAAS,EAAE,OAAO,KAAK,GAAG,CAAC;AAAA,EACxC;AACA,SAAO,GAAG,EAAE,SAAS,oBAAoB,OAAO,SAAS,CAAC;AAC5D;","names":[]}

package/dist/lib/auth/browser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Browser-launch wrapper for the OAuth browser flow.
+ *
+ * This is the SOLE file that imports from the 'open' npm package.
+ * Injectable via the BrowserOpener interface for unit tests.
+ */
+interface BrowserOpener {
+    open(url: string): Promise<void>;
+}
+/**
+ * Create the default browser opener backed by the 'open' package.
+ * Throws NotLoggedInError on failure with the --manual fallback hint.
+ */
+declare function defaultBrowserOpener(): BrowserOpener;
+
+export { type BrowserOpener, defaultBrowserOpener };

package/dist/lib/auth/browser.js

@@ -0,0 +1,48 @@
+// src/lib/errors.ts
+var RatioCLIError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  docsUrl;
+  constructor(opts) {
+    super(opts.message);
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    if (opts.hint !== void 0) this.hint = opts.hint;
+    if (opts.docsUrl !== void 0) this.docsUrl = opts.docsUrl;
+  }
+};
+var NotLoggedInError = class extends RatioCLIError {
+  constructor(message, hint = "Run 'ratio auth login' to sign in.") {
+    super({ code: "NOT_LOGGED_IN", exitCode: 3, message, hint });
+  }
+};
+
+// src/lib/auth/browser.ts
+function defaultBrowserOpener() {
+  return {
+    async open(url) {
+      let openFn;
+      try {
+        const mod = await import("open");
+        openFn = mod.default;
+      } catch {
+        throw new NotLoggedInError(
+          "Could not open a browser. Run 'ratio auth login --manual' to complete without a browser."
+        );
+      }
+      try {
+        await openFn(url);
+      } catch {
+        throw new NotLoggedInError(
+          "Could not open a browser. Run 'ratio auth login --manual' to complete without a browser."
+        );
+      }
+    }
+  };
+}
+export {
+  defaultBrowserOpener
+};
+//# sourceMappingURL=browser.js.map

package/dist/lib/auth/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/errors.ts","../../../src/lib/auth/browser.ts"],"sourcesContent":["/**\n * Error hierarchy for the Ratio CLI. Every error thrown from a command's\n * run() is expected to be an instance of RatioCLIError so the global\n * render-error handler can map it to a deterministic stderr line and exit\n * code. Uncaught Error subclasses render as \"INTERNAL: <msg>\" with exit 1.\n *\n * No import from @oclif/core — this file is dependency-free so tests\n * can import it without oclif overhead.\n */\n\nexport class RatioCLIError extends Error {\n  readonly code: string;\n  readonly exitCode: number;\n  readonly hint?: string;\n  readonly docsUrl?: string;\n\n  constructor(opts: {\n    code: string;\n    exitCode: number;\n    message: string;\n    hint?: string;\n    docsUrl?: string;\n  }) {\n    super(opts.message);\n    this.name = new.target.name;\n    this.code = opts.code;\n    this.exitCode = opts.exitCode;\n    if (opts.hint !== undefined) this.hint = opts.hint;\n    if (opts.docsUrl !== undefined) this.docsUrl = opts.docsUrl;\n  }\n}\n\n/** Coming-soon stub UX. Renders on stdout with exit 0. */\nexport class ComingSoonError extends RatioCLIError {\n  constructor(message: string) {\n    super({ code: 'COMING_SOON', exitCode: 0, message });\n  }\n}\n\n/** User has no credentials and command requires auth. */\nexport class NotLoggedInError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to sign in.\",\n  ) {\n    super({ code: 'NOT_LOGGED_IN', exitCode: 3, message, hint });\n  }\n}\n\nexport class TokenExpiredError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Run 'ratio auth login' to refresh your session.\",\n  ) {\n    super({ code: 'TOKEN_EXPIRED', exitCode: 3, message, hint });\n  }\n}\n\nexport class ScopeDeniedError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'SCOPE_DENIED',\n      exitCode: 4,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class NetworkError extends RatioCLIError {\n  constructor(message: string, hint: string = 'Check your network and retry.') {\n    super({ code: 'NETWORK_ERROR', exitCode: 5, message, hint });\n  }\n}\n\nexport class RelayConnectError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Verify the tunnel URL and that the auth-server is reachable.',\n  ) {\n    super({ code: 'RELAY_CONNECT', exitCode: 6, message, hint });\n  }\n}\n\nexport class TemplateExistsError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Choose a different name or remove the existing directory.',\n  ) {\n    super({ code: 'TEMPLATE_EXISTS', exitCode: 7, message, hint });\n  }\n}\n\nexport class ValidationError extends RatioCLIError {\n  constructor(message: string, hint?: string) {\n    const opts: { code: string; exitCode: number; message: string; hint?: string } = {\n      code: 'VALIDATION_ERROR',\n      exitCode: 8,\n      message,\n    };\n    if (hint !== undefined) opts.hint = hint;\n    super(opts);\n  }\n}\n\nexport class RelayResumeGapError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Reconnect from the current cursor; older events are outside the buffer window.',\n  ) {\n    super({ code: 'RELAY_RESUME_GAP', exitCode: 9, message, hint });\n  }\n}\n\nexport class OrchestratorSpawnError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = \"Could not start your app's dev command — check that the command in ratio.config.jsonc runs from this directory.\",\n  ) {\n    super({ code: 'ORCHESTRATOR_SPAWN', exitCode: 10, message, hint });\n  }\n}\n\nexport class OrchestratorDrainTimeoutError extends RatioCLIError {\n  constructor(\n    message: string,\n    hint: string = 'Your dev command did not exit cleanly within 5 seconds — it was forcibly terminated.',\n  ) {\n    super({ code: 'ORCHESTRATOR_DRAIN', exitCode: 11, message, hint });\n  }\n}\n\nexport function isRatioCLIError(err: unknown): err is RatioCLIError {\n  return err instanceof RatioCLIError;\n}\n","/**\n * Browser-launch wrapper for the OAuth browser flow.\n *\n * This is the SOLE file that imports from the 'open' npm package.\n * Injectable via the BrowserOpener interface for unit tests.\n */\n\nimport { NotLoggedInError } from '../errors.js';\n\nexport interface BrowserOpener {\n  open(url: string): Promise<void>;\n}\n\n/**\n * Create the default browser opener backed by the 'open' package.\n * Throws NotLoggedInError on failure with the --manual fallback hint.\n */\nexport function defaultBrowserOpener(): BrowserOpener {\n  return {\n    async open(url: string): Promise<void> {\n      // Dynamic import is used so the module is loadable in test environments\n      // that do not have a display (CI / SSH). The real 'open' call only fires\n      // in production use when this opener is not replaced by a test double.\n      let openFn: (url: string) => Promise<unknown>;\n      try {\n        const mod = await import('open');\n        openFn = mod.default as (url: string) => Promise<unknown>;\n      } catch {\n        throw new NotLoggedInError(\n          \"Could not open a browser. Run 'ratio auth login --manual' to complete without a browser.\",\n        );\n      }\n      try {\n        await openFn(url);\n      } catch {\n        throw new NotLoggedInError(\n          \"Could not open a browser. Run 'ratio auth login --manual' to complete without a browser.\",\n        );\n      }\n    },\n  };\n}\n"],"mappings":";AAUO,IAAM,gBAAN,cAA4B,MAAM;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAMT;AACD,UAAM,KAAK,OAAO;AAClB,SAAK,OAAO,WAAW;AACvB,SAAK,OAAO,KAAK;AACjB,SAAK,WAAW,KAAK;AACrB,QAAI,KAAK,SAAS,OAAW,MAAK,OAAO,KAAK;AAC9C,QAAI,KAAK,YAAY,OAAW,MAAK,UAAU,KAAK;AAAA,EACtD;AACF;AAUO,IAAM,mBAAN,cAA+B,cAAc;AAAA,EAClD,YACE,SACA,OAAe,sCACf;AACA,UAAM,EAAE,MAAM,iBAAiB,UAAU,GAAG,SAAS,KAAK,CAAC;AAAA,EAC7D;AACF;;;AC9BO,SAAS,uBAAsC;AACpD,SAAO;AAAA,IACL,MAAM,KAAK,KAA4B;AAIrC,UAAI;AACJ,UAAI;AACF,cAAM,MAAM,MAAM,OAAO,MAAM;AAC/B,iBAAS,IAAI;AAAA,MACf,QAAQ;AACN,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MACF;AACA,UAAI;AACF,cAAM,OAAO,GAAG;AAAA,MAClB,QAAQ;AACN,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/lib/auth/config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Server-URL resolution for the Ratio CLI auth flow.
+ *
+ * Resolution order (highest priority first):
+ *   1. RATIO_SERVER_URL environment variable
+ *   2. Credentials.server from the stored credential file (passed in as opts.credentials.server)
+ *   3. The compiled-in default: https://gkx.ratio.win
+ *
+ * The default is the ONLY place this URL appears in non-config source files.
+ * All other auth-library modules call resolveServerUrl() — never hardcode.
+ *
+ * A-28: the merchantId constant lives here so it appears in exactly ONE
+ * production file and is grep-able.
+ */
+/** Compiled-in default server URL. */
+declare const DEFAULT_SERVER_URL = "https://gkx.ratio.win";
+/**
+ * Synthetic merchantId sent in the authorize URL.
+ * A-28 adjudication: backend auto-creates missing merchants via
+ * ensureMerchantExists(); 'ratio-cli-dev' is the designated synthetic value.
+ * Appears in exactly ONE production file (this one).
+ */
+declare const RATIO_CLI_MERCHANT_ID = "ratio-cli-dev";
+/** The fixed clientId for the ratio-cli public OAuth client. */
+declare const RATIO_CLI_CLIENT_ID: "ratio-cli";
+interface ServerConfig {
+    readonly url: string;
+}
+interface ResolveServerUrlOptions {
+    readonly credentials?: {
+        readonly server?: string;
+    };
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Resolve the backend server URL using the three-level precedence chain.
+ * Injectable for tests: pass `env` to avoid reading `process.env` directly.
+ */
+declare function resolveServerUrl(opts?: ResolveServerUrlOptions): string;
+
+export { DEFAULT_SERVER_URL, RATIO_CLI_CLIENT_ID, RATIO_CLI_MERCHANT_ID, type ResolveServerUrlOptions, type ServerConfig, resolveServerUrl };

package/dist/lib/auth/config.js

@@ -0,0 +1,21 @@
+// src/lib/auth/config.ts
+var DEFAULT_SERVER_URL = "https://gkx.ratio.win";
+var RATIO_CLI_MERCHANT_ID = "ratio-cli-dev";
+var RATIO_CLI_CLIENT_ID = "ratio-cli";
+function resolveServerUrl(opts) {
+  const env = opts?.env ?? process.env;
+  if (typeof env["RATIO_SERVER_URL"] === "string" && env["RATIO_SERVER_URL"].length > 0) {
+    return env["RATIO_SERVER_URL"];
+  }
+  if (typeof opts?.credentials?.server === "string" && opts.credentials.server.length > 0) {
+    return opts.credentials.server;
+  }
+  return DEFAULT_SERVER_URL;
+}
+export {
+  DEFAULT_SERVER_URL,
+  RATIO_CLI_CLIENT_ID,
+  RATIO_CLI_MERCHANT_ID,
+  resolveServerUrl
+};
+//# sourceMappingURL=config.js.map

package/dist/lib/auth/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/auth/config.ts"],"sourcesContent":["/**\n * Server-URL resolution for the Ratio CLI auth flow.\n *\n * Resolution order (highest priority first):\n *   1. RATIO_SERVER_URL environment variable\n *   2. Credentials.server from the stored credential file (passed in as opts.credentials.server)\n *   3. The compiled-in default: https://gkx.ratio.win\n *\n * The default is the ONLY place this URL appears in non-config source files.\n * All other auth-library modules call resolveServerUrl() — never hardcode.\n *\n * A-28: the merchantId constant lives here so it appears in exactly ONE\n * production file and is grep-able.\n */\n\n/** Compiled-in default server URL. */\nexport const DEFAULT_SERVER_URL = 'https://gkx.ratio.win';\n\n/**\n * Synthetic merchantId sent in the authorize URL.\n * A-28 adjudication: backend auto-creates missing merchants via\n * ensureMerchantExists(); 'ratio-cli-dev' is the designated synthetic value.\n * Appears in exactly ONE production file (this one).\n */\nexport const RATIO_CLI_MERCHANT_ID = 'ratio-cli-dev';\n\n/** The fixed clientId for the ratio-cli public OAuth client. */\nexport const RATIO_CLI_CLIENT_ID = 'ratio-cli' as const;\n\nexport interface ServerConfig {\n  readonly url: string;\n}\n\nexport interface ResolveServerUrlOptions {\n  readonly credentials?: { readonly server?: string };\n  readonly env?: Readonly<Record<string, string | undefined>>;\n}\n\n/**\n * Resolve the backend server URL using the three-level precedence chain.\n * Injectable for tests: pass `env` to avoid reading `process.env` directly.\n */\nexport function resolveServerUrl(opts?: ResolveServerUrlOptions): string {\n  const env = opts?.env ?? process.env;\n  if (typeof env['RATIO_SERVER_URL'] === 'string' && env['RATIO_SERVER_URL'].length > 0) {\n    return env['RATIO_SERVER_URL'];\n  }\n  if (typeof opts?.credentials?.server === 'string' && opts.credentials.server.length > 0) {\n    return opts.credentials.server;\n  }\n  return DEFAULT_SERVER_URL;\n}\n"],"mappings":";AAgBO,IAAM,qBAAqB;AAQ3B,IAAM,wBAAwB;AAG9B,IAAM,sBAAsB;AAe5B,SAAS,iBAAiB,MAAwC;AACvE,QAAM,MAAM,MAAM,OAAO,QAAQ;AACjC,MAAI,OAAO,IAAI,kBAAkB,MAAM,YAAY,IAAI,kBAAkB,EAAE,SAAS,GAAG;AACrF,WAAO,IAAI,kBAAkB;AAAA,EAC/B;AACA,MAAI,OAAO,MAAM,aAAa,WAAW,YAAY,KAAK,YAAY,OAAO,SAAS,GAAG;AACvF,WAAO,KAAK,YAAY;AAAA,EAC1B;AACA,SAAO;AACT;","names":[]}

package/dist/lib/auth/http-refresher.d.ts

@@ -0,0 +1,30 @@
+import { TokenSet } from '../credentials/types.js';
+import { TokenRefresher } from '../credentials/refresher.js';
+import { RATIO_CLI_CLIENT_ID } from './config.js';
+import { VerboseTracer } from './verbose-trace.js';
+
+/**
+ * HTTP implementation of the TokenRefresher interface.
+ *
+ * POSTs to /oauth/token with grant_type=refresh_token.
+ * Maps 4xx → TokenExpiredError, 5xx/network → NetworkError.
+ * Never logs or echoes the token value in any error message.
+ */
+
+interface HttpTokenRefresherOptions {
+    readonly serverUrl: string;
+    readonly clientId: typeof RATIO_CLI_CLIENT_ID;
+    readonly fetchImpl?: typeof fetch;
+    /** Verbose diagnostic sink — never receives the refresh token value. */
+    readonly trace?: VerboseTracer;
+}
+declare class HttpTokenRefresher implements TokenRefresher {
+    private readonly serverUrl;
+    private readonly clientId;
+    private readonly fetchImpl;
+    private readonly trace;
+    constructor(opts: HttpTokenRefresherOptions);
+    refresh(refreshToken: string): Promise<TokenSet>;
+}
+
+export { HttpTokenRefresher, type HttpTokenRefresherOptions };