@astrale-os/cli 1.0.0-beta.32 → 1.0.0-beta.43

package/src/lib/invocation.ts

@@ -1,11 +0,0 @@
-/** Process-wide machine mode from argv (`--json` / `--raw` / `--ci`). */
-
-let argvMachine = false
-
-export function configureInvocation(argv: readonly string[]): void {
-  argvMachine = argv.some((token) => token === '--json' || token === '--raw' || token === '--ci')
-}
-
-export function invocationWantsMachine(): boolean {
-  return argvMachine
-}

package/src/lib/local-status.ts

@@ -1,152 +0,0 @@
-import { decodeJwt } from 'jose'
-
-import type { AstraleConfig } from './config'
-
-import { readIdentities, type IdentityStore } from '../identity/index'
-import { resolveAdminTargetFromStore } from './admin-target'
-import { DEFAULT_CONFIG, readConfig } from './config'
-import { isSessionExpired, readIdpSession, type IdpSession } from './idp'
-import { readInstances, type InstanceStore } from './instance'
-
-export type LocalInstanceStatus = {
-  active: string
-  url: string
-  issuer: string | null
-  defaultIdentity: string | null
-} | null
-
-export type LocalAdminStatus =
-  | {
-      name: string
-      url: string
-      issuer: string
-      source: string
-      configured: boolean
-    }
-  | {
-      error: string
-    }
-
-export type LocalIdentityStatus = {
-  name: string
-  subject: string
-  source: 'key' | 'idp'
-  idp: string | null
-  session: {
-    cached: boolean
-    requiresLogin?: boolean
-    hasRefreshToken?: boolean
-  } | null
-} | null
-
-export type LocalStatus = {
-  admin: LocalAdminStatus
-  instance: LocalInstanceStatus
-  identity: LocalIdentityStatus
-}
-
-export type JwtExpiration = {
-  expiresAt: string
-  expired: boolean
-}
-
-export async function readLocalStatus(): Promise<LocalStatus> {
-  const [instances, identities, config] = await Promise.all([
-    // Read-only: status / `setup --plan` must never trigger a sanitize-writeback.
-    readInstances(undefined, { persist: false }),
-    readIdentities(),
-    readConfig(),
-  ])
-  return buildLocalStatus(instances, identities, async (name) => readIdpSession(name), config)
-}
-
-export async function buildLocalStatus(
-  instances: InstanceStore,
-  identities: IdentityStore,
-  readSession: (identityName: string) => Promise<IdpSession | null>,
-  config: AstraleConfig = DEFAULT_CONFIG,
-): Promise<LocalStatus> {
-  const activeEntry = instances.active ? instances.instances[instances.active] : undefined
-  const instance = instances.active
-    ? {
-        active: instances.active,
-        url: activeEntry?.url ?? '',
-        issuer: activeEntry?.issuer ?? null,
-        defaultIdentity: activeEntry?.defaultIdentity ?? null,
-      }
-    : null
-
-  const identityEntry = identities.identities[identities.default]
-  const admin = buildAdminStatus(config, instances)
-  if (!identityEntry) {
-    return { admin, instance, identity: null }
-  }
-
-  const source = identityEntry.source ?? 'key'
-  const session =
-    source === 'idp'
-      ? await readSession(identities.default)
-          .then((value) => {
-            if (!value) return { cached: false }
-            const expiresAt =
-              value.expires_at ??
-              expClaimToIso(value.claims?.exp) ??
-              expClaimToIso(identityEntry.claims?.exp)
-            const hasRefreshToken = !!value.refresh_token
-            return {
-              cached: true,
-              requiresLogin:
-                !hasRefreshToken &&
-                isSessionExpired({ expires_at: expiresAt, access_token: value.access_token }),
-              hasRefreshToken,
-            }
-          })
-          .catch(() => ({ cached: false }))
-      : null
-
-  return {
-    admin,
-    instance,
-    identity: {
-      name: identities.default,
-      subject: identityEntry.subject,
-      source,
-      idp: identityEntry.idp ?? null,
-      session,
-    },
-  }
-}
-
-function buildAdminStatus(config: AstraleConfig, instances: InstanceStore): LocalAdminStatus {
-  try {
-    const target = resolveAdminTargetFromStore({}, config, instances)
-    return {
-      name: target.name,
-      url: target.url,
-      issuer: target.kernelIssuer,
-      source: target.source,
-      configured: target.configured,
-    }
-  } catch (err) {
-    return { error: err instanceof Error ? err.message : String(err) }
-  }
-}
-
-function expClaimToIso(value: unknown): string | undefined {
-  if (typeof value !== 'number') return undefined
-  return new Date(value * 1000).toISOString()
-}
-
-export function decodeJwtExpiration(token: string, nowMs = Date.now()): JwtExpiration | null {
-  try {
-    const payload = decodeJwt(token)
-    if (typeof payload.exp !== 'number') return null
-    const expiresMs = payload.exp * 1000
-    return {
-      expiresAt: new Date(expiresMs).toISOString(),
-      expired: expiresMs <= nowMs,
-    }
-  } catch {
-    return null
-  }
-}

package/src/lib/log.ts

@@ -1,143 +0,0 @@
-import chalk from 'chalk'
-import ora, { type Ora } from 'ora'
-
-import { AstraleError, NotImplementedError } from '../errors'
-import { printFailureDebug } from './failure-debug'
-import { formatElapsed } from './format'
-import { isMachine, type MachineOpts } from './output'
-
-export const log = {
-  info: (msg: string) => console.log(chalk.blue('ℹ'), msg),
-  success: (msg: string) => console.log(chalk.green('✔'), msg),
-  // Diagnostics never share stdout with command results. In particular,
-  // --json/--raw consumers must receive exactly one parseable value there.
-  warn: (msg: string) => console.error(chalk.yellow('⚠'), msg),
-  error: (msg: string) => console.error(chalk.red('✖'), msg),
-  step: (msg: string) => console.log(chalk.cyan('→'), msg),
-  dim: (msg: string) => console.log(chalk.dim(msg)),
-}
-
-/** Report an error with hint (when present) and exit. `--json` / `--ci` / a
- *  non-TTY stdout always get one structured JSON line on stderr. */
-export function fatal(e: unknown, opts?: MachineOpts & { readonly debug?: boolean }): never {
-  // Ctrl-C at an interactive (@inquirer/prompts) prompt — exit quietly with the
-  // SIGINT convention, not a red error line.
-  if (e instanceof Error && e.name === 'ExitPromptError') process.exit(130)
-  const msg =
-    e instanceof AstraleError ? e.message : 'The CLI encountered an unexpected internal failure.'
-  const code = e instanceof AstraleError ? e.code : 'UNEXPECTED_ERROR'
-  if (isMachine(opts)) {
-    const payload: Record<string, unknown> = { error: code, message: msg }
-    if (e instanceof AstraleError && e.hint) payload.hint = e.hint
-    process.stderr.write(JSON.stringify(payload) + '\n')
-  } else {
-    log.error(`${code}: ${msg}`)
-    if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
-  }
-  if (opts?.debug) printFailureDebug(e, '')
-  process.exit(1)
-}
-
-/** Project only a caller-authored admission failure into the CLI input family. */
-export function failInput(error: unknown, opts?: MachineOpts): never {
-  if (error instanceof AstraleError) fatal(error, opts)
-  if (!(error instanceof TypeError)) fatal(error, opts)
-  fatal(
-    new AstraleError(
-      'INVALID_INPUT',
-      error.message.trim() ? error.message : 'CLI input is invalid.',
-    ),
-    opts,
-  )
-}
-
-/** Shortcut for stub commands that aren't wired in v1 (§15). */
-export function fatalNotImplemented(feature: string, hint?: string): never {
-  fatal(new NotImplementedError(feature, hint))
-}
-
-/** Maximum time a spinner may run before being forcefully stopped. */
-const SPINNER_SAFETY_MS = 60_000
-
-const IS_CI = !!(process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.NO_SPINNER)
-
-/**
- * Run an async operation behind a spinner. Pass `enabled: false` for
- * machine-readable output modes. Errors are rethrown after the spinner is
- * stopped (✖ label failed).
- *
- * On success the spinner line is cleared — commands print their own result.
- * Pass `opts.success` to instead persist a single final line
- * (✔ <success text> <elapsed>) so a command ends on one line, not a
- * spinner line + result line pair.
- */
-export async function withSpinner<T>(
-  label: string,
-  enabled: boolean,
-  fn: () => Promise<T>,
-  opts: { success?: (result: T) => string } = {},
-): Promise<T> {
-  if (!enabled) return await fn()
-  const spin = spinner(`${label}...`)
-  const start = performance.now()
-  try {
-    const result = await fn()
-    if (opts.success) {
-      spin.succeed(`${opts.success(result)} ${chalk.dim(formatElapsed(performance.now() - start))}`)
-    } else {
-      spin.stop()
-    }
-    return result
-  } catch (error) {
-    spin.fail(`${label} failed`)
-    throw error
-  }
-}
-
-export function spinner(text: string): Ora {
-  const target = process.stderr
-
-  if (!target.writable || IS_CI) {
-    return ora({ text, isEnabled: false })
-  }
-
-  // Hand ora the bare stream: ora 9 hooks `stream.write` by assignment to
-  // interleave external writes, so any wrapper here must survive that
-  // mutation (a get-only Proxy recurses infinitely and kills the spinner).
-  // Backpressure is ora's job now — it pauses rendering until 'drain'.
-  const spin = ora({ text, color: 'cyan', stream: target }).start()
-
-  const safety = setTimeout(() => {
-    if (spin.isSpinning) spin.stop()
-  }, SPINNER_SAFETY_MS)
-  safety.unref()
-
-  const onTargetError = () => {
-    if (spin.isSpinning) spin.stop()
-  }
-  target.once('error', onTargetError)
-
-  const cleanup = () => {
-    clearTimeout(safety)
-    target.removeListener('error', onTargetError)
-  }
-
-  const origSucceed = spin.succeed.bind(spin)
-  const origFail = spin.fail.bind(spin)
-  const origStop = spin.stop.bind(spin)
-
-  spin.succeed = (text?: string) => {
-    cleanup()
-    return origSucceed(text)
-  }
-  spin.fail = (text?: string) => {
-    cleanup()
-    return origFail(text)
-  }
-  spin.stop = () => {
-    cleanup()
-    return origStop()
-  }
-
-  return spin
-}

package/src/lib/login-flow.ts

@@ -1,201 +0,0 @@
-import { upsertIdpIdentity } from '../identity/registry'
-import {
-  decodeTokenClaims,
-  exchangeAuthorizationCode,
-  identityNameFromClaims,
-  issuerFromToken,
-  normalizeTokenResponse,
-  pollDeviceToken,
-  readIdpConfigOrBuiltin,
-  readIdpSession,
-  readIdpStore,
-  requireClientId,
-  requestClientCredentials,
-  requestDeviceAuthorization,
-  saveIdpSession,
-  subjectFromToken,
-  tokenAudienceMatches,
-  tokenExpiresAt,
-  withCachedToken,
-  workosClientIdFromEnv,
-  type IdpSession,
-  type TokenResponse,
-} from './idp'
-import { log } from './log'
-
-/**
- * The IdP login flow, lifted out of the `auth login` command so it can be
- * driven from anywhere (the command renders the result; `astrale setup` runs it
- * as one hand-held step). The side effects — saving the session cache and
- * upserting the IdP-backed identity — live here so every caller gets identical
- * behavior; presentation (the device URL is logged here; success lines are the
- * caller's) does not.
- */
-export type LoginFlowOpts = {
-  idp?: string
-  name?: string
-  scope?: string
-  audience?: string
-  clientId?: string
-  clientSecretEnv?: string
-  clientCredentials?: boolean
-  code?: string
-  redirectUri?: string
-  codeVerifier?: string
-  /** Switch the default identity to the one we just logged in (default true). */
-  use?: boolean
-  /**
-   * Optional device-flow presentation boundary. When supplied, the caller
-   * receives the verification coordinates instead of terminal log output.
-   */
-  onVerification?: (event: DeviceVerification) => void
-}
-
-export type DeviceVerification = {
-  verificationUri: string
-  verificationUriComplete?: string
-  userCode?: string
-  expiresIn?: number
-  message?: string
-}
-
-export type LoginResult = {
-  session: IdpSession
-  identityName: string
-  idpName: string
-}
-
-/**
- * Authenticate against an IdP and persist the result. Throws on any failure
- * (no session is written) — notably BEFORE saving when an explicit `--audience`
- * does not match the minted access token, so a wrong-audience login never
- * leaves a half-written cache.
- */
-export async function loginViaIdp(opts: LoginFlowOpts): Promise<LoginResult> {
-  const idpName = await resolveIdpName(opts.idp)
-  const previous = opts.name && !opts.clientId ? await readIdpSession(opts.name) : null
-  const savedClientId = previous?.idp === idpName ? previous.clientId : undefined
-  const requestedClientId = opts.clientId ?? savedClientId
-  const idp = await readIdpConfigOrBuiltin(idpName, {
-    clientId: requestedClientId,
-    persist: true,
-  })
-  const clientId = requireClientId(idp, requestedClientId)
-  const scope = opts.scope ?? idp.client.scope ?? 'openid profile email offline_access'
-
-  const token = normalizeTokenResponse(await obtainToken(idp, { ...opts, clientId }, scope))
-  if (!token.access_token) throw new Error('IdP response did not include access_token')
-  if (opts.audience && !tokenAudienceMatches(token.access_token, opts.audience)) {
-    throw new Error(
-      `IdP response access_token was not minted for requested audience ${opts.audience}`,
-    )
-  }
-
-  const claims = decodeTokenClaims(token.id_token ?? token.access_token)
-  const subject = subjectFromToken(token, clientId)
-  const issuer = issuerFromToken(token, idp.metadata.issuer)
-  const identityName = opts.name ?? identityNameFromClaims(claims, idpName)
-  const session: IdpSession = {
-    identity: identityName,
-    idp: idpName,
-    issuer,
-    subject,
-    clientId,
-    audience: opts.audience,
-    access_token: token.access_token,
-    id_token: token.id_token,
-    refresh_token: token.refresh_token,
-    token_type: token.token_type,
-    scope: token.scope ?? scope,
-    expires_at: tokenExpiresAt(token),
-    tokens: withCachedToken(undefined, token.access_token, tokenExpiresAt(token)),
-    claims: claims ? (claims as Record<string, unknown>) : undefined,
-    updatedAt: new Date().toISOString(),
-  }
-
-  await saveIdpSession(session)
-  await upsertIdpIdentity(identityName, {
-    subject,
-    idp: idpName,
-    issuer,
-    audience: opts.audience,
-    claims: session.claims,
-    use: opts.use,
-  })
-
-  return { session, identityName, idpName }
-}
-
-/** Resolve which IdP to use: explicit name, the sole configured one, or WorkOS. */
-export async function resolveIdpName(name: string | undefined): Promise<string> {
-  if (name) return name
-  const store = await readIdpStore()
-  const names = Object.keys(store.idps)
-  if (names.length === 1) return names[0]
-  if (names.length === 0 && workosClientIdFromEnv()) return 'workos'
-  if (names.length === 0)
-    throw new Error('No IdPs configured. Run: astrale idp add <name> --issuer <url>')
-  throw new Error(`Multiple IdPs configured. Choose one with --idp: ${names.join(', ')}`)
-}
-
-async function obtainToken(
-  idp: Awaited<ReturnType<typeof readIdpConfigOrBuiltin>>,
-  opts: LoginFlowOpts,
-  scope: string,
-): Promise<TokenResponse> {
-  if (opts.clientCredentials) {
-    return requestClientCredentials({
-      idp,
-      clientId: opts.clientId,
-      clientSecretEnv: opts.clientSecretEnv,
-      scope,
-      audience: opts.audience,
-    })
-  }
-
-  if (opts.code) {
-    if (!opts.redirectUri) throw new Error('--redirect-uri is required with --code')
-    return exchangeAuthorizationCode({
-      idp,
-      code: opts.code,
-      redirectUri: opts.redirectUri,
-      codeVerifier: opts.codeVerifier,
-      clientId: opts.clientId,
-      clientSecretEnv: opts.clientSecretEnv,
-    })
-  }
-
-  const device = await requestDeviceAuthorization({
-    idp,
-    clientId: opts.clientId,
-    scope,
-    audience: opts.audience,
-  })
-  const verificationUri = device.verification_uri ?? device.verification_uri_complete
-  if (!verificationUri) {
-    throw new Error('IdP device authorization response did not include a verification URL')
-  }
-  const verification: DeviceVerification = {
-    verificationUri,
-    verificationUriComplete: device.verification_uri_complete,
-    userCode: device.user_code,
-    expiresIn: device.expires_in,
-    message: device.message,
-  }
-  if (opts.onVerification) opts.onVerification(verification)
-  else {
-    if (device.verification_uri_complete) log.info(`Open: ${device.verification_uri_complete}`)
-    else if (device.verification_uri) log.info(`Open: ${device.verification_uri}`)
-    if (device.user_code) log.info(`Code: ${device.user_code}`)
-    if (device.message) log.dim(`  ${device.message}`)
-  }
-
-  return pollDeviceToken({
-    idp,
-    deviceCode: device.device_code,
-    clientId: opts.clientId,
-    clientSecretEnv: opts.clientSecretEnv,
-    intervalSec: device.interval,
-    expiresInSec: device.expires_in,
-  })
-}

package/src/lib/meta.ts

@@ -1,90 +0,0 @@
-/**
- * Issuer reachability helpers — OIDC discovery + JWKS.
- *
- * Kernels don't expose `/meta`. They expose OIDC discovery at
- * `/.well-known/openid-configuration` (standard, returns `issuer` and
- * `jwks_uri`) and JWKS at `/.well-known/jwks.json`. These helpers probe
- * both to verify the issuer is alive and publishes at least one key.
- *
- * Domain deployment readiness uses the canonical Domain Publication; that is
- * outside this issuer-connectivity helper.
- */
-
-import { IssuerUnreachableError } from '../errors'
-
-type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
-
-export type DiscoveryDocument = {
-  /** OIDC issuer URL. */
-  issuer: string
-  /** JWKS URI (defaults to `<issuer>/.well-known/jwks.json`). */
-  jwksUri: string
-}
-
-export async function fetchDiscovery(
-  url: string,
-  timeoutMs = 5_000,
-  fetchImpl: FetchLike = globalThis.fetch,
-): Promise<DiscoveryDocument> {
-  const discoveryUrl = url.replace(/\/+$/, '') + '/.well-known/openid-configuration'
-  try {
-    const r = await fetchImpl(discoveryUrl, { signal: AbortSignal.timeout(timeoutMs) })
-    if (!r.ok) throw new Error(`HTTP ${r.status}`)
-    const body = (await r.json()) as { issuer?: string; jwks_uri?: string }
-    if (!body.issuer) throw new Error('discovery missing "issuer"')
-    const issuer = body.issuer
-    const jwksUri = body.jwks_uri ?? `${issuer.replace(/\/+$/, '')}/.well-known/jwks.json`
-    return { issuer, jwksUri }
-  } catch (e) {
-    throw new IssuerUnreachableError(discoveryUrl, (e as Error).message)
-  }
-}
-
-export async function fetchJwks(
-  jwksUri: string,
-  timeoutMs = 5_000,
-  fetchImpl: FetchLike = globalThis.fetch,
-): Promise<{ keys: Array<{ kid?: string }> }> {
-  try {
-    const r = await fetchImpl(jwksUri, { signal: AbortSignal.timeout(timeoutMs) })
-    if (!r.ok) throw new Error(`HTTP ${r.status}`)
-    return (await r.json()) as { keys: Array<{ kid?: string }> }
-  } catch (e) {
-    throw new IssuerUnreachableError(jwksUri, (e as Error).message)
-  }
-}
-
-/**
- * Discover the WorkOS organization an instance host pins
- */
-export async function fetchOrgHint(url: string, timeoutMs = 5_000): Promise<string | undefined> {
-  try {
-    const origin = new URL(url).origin
-    const r = await fetch(`${origin}/auth/org`, { signal: AbortSignal.timeout(timeoutMs) })
-    if (!r.ok) return undefined
-    const body = (await r.json()) as { organizationId?: unknown }
-    return typeof body.organizationId === 'string' ? body.organizationId : undefined
-  } catch {
-    return undefined
-  }
-}
-
-/** Verify the pinned issuer publishes self-consistent OIDC discovery and a non-empty JWKS. */
-export async function checkIssuerReachability(
-  url: string,
-  issuerOverride?: string,
-  fetchImpl?: FetchLike,
-): Promise<{ issuer: string; keys: Array<{ kid?: string }> }> {
-  const discoveryBase = issuerOverride ?? url
-  const discovery = await fetchDiscovery(discoveryBase, 5_000, fetchImpl)
-  if (issuerOverride !== undefined && discovery.issuer !== issuerOverride) {
-    throw new IssuerUnreachableError(
-      `${discoveryBase.replace(/\/+$/, '')}/.well-known/openid-configuration`,
-      `discovery declared issuer "${discovery.issuer}" instead of "${issuerOverride}"`,
-    )
-  }
-  const jwks = await fetchJwks(discovery.jwksUri, 5_000, fetchImpl)
-  if (jwks.keys.length === 0)
-    throw new IssuerUnreachableError(discovery.jwksUri, 'no keys published')
-  return { issuer: discovery.issuer, keys: jwks.keys }
-}