@astrale-os/cli 0.4.0-alpha.13

package/src/commands/identity/sync.ts

@@ -0,0 +1,32 @@
+import type { CommandDefinition } from '../../command'
+
+import { getIdentity, setIdentityMode } from '../../lib/identity'
+import { fatal, fatalNotImplemented, log } from '../../lib/log'
+
+export default {
+  name: 'sync',
+  description: 'Migrate an identity local → remote (astrale cloud)',
+  arguments: [{ name: 'name', description: 'Identity name', required: true }],
+  options: [
+    {
+      flags: '--force',
+      description: 'Tag as remote in the local registry even without cloud login',
+    },
+  ],
+  action: async (name: string, opts: { force?: boolean }) => {
+    try {
+      const identity = await getIdentity(name)
+      if (!opts.force) {
+        fatalNotImplemented(
+          'identity sync (remote)',
+          'Cloud adapter is stubbed in v1. Use --force to pre-tag the identity locally.',
+        )
+      }
+      await setIdentityMode(name, 'remote')
+      log.warn(`Tagged "${name}" as remote locally (cloud sync stubbed in v1)`)
+      log.dim(`  subject=${identity.subject}`)
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/identity/unsync.ts

@@ -0,0 +1,24 @@
+import type { CommandDefinition } from '../../command'
+
+import { getIdentity, setIdentityMode } from '../../lib/identity'
+import { fatal, log } from '../../lib/log'
+
+/** Metadata-only flip remote → local until cloud sync ships (§2.7). */
+export default {
+  name: 'unsync',
+  description: 'Migrate an identity remote → local',
+  arguments: [{ name: 'name', description: 'Identity name', required: true }],
+  action: async (name: string) => {
+    try {
+      const identity = await getIdentity(name)
+      if (identity.mode !== 'remote') {
+        log.warn(`Identity "${name}" is already ${identity.mode ?? 'local'}`)
+        return
+      }
+      await setIdentityMode(name, 'local')
+      log.success(`Identity "${name}" → local`)
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/identity/use.ts

@@ -0,0 +1,18 @@
+import type { CommandDefinition } from '../../command'
+
+import { setDefault } from '../../lib/identity'
+import { fatal, log } from '../../lib/log'
+
+export default {
+  name: 'use',
+  description: 'Set the active CLI identity',
+  arguments: [{ name: 'name', description: 'Identity name', required: true }],
+  action: async (name: string) => {
+    try {
+      await setDefault(name)
+      log.success(`Active identity set to "${name}"`)
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/identity/whoami.ts

@@ -0,0 +1,34 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+
+import { getDefault } from '../../lib/identity'
+import { fatal } from '../../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../../lib/output'
+
+type WhoamiResult = {
+  name: string
+  subject: string
+}
+
+export default {
+  name: 'whoami',
+  description: 'Show the current default identity',
+  options: [...RAW_OUTPUT_OPTIONS],
+  action: async (opts: RawOutputOpts) => {
+    try {
+      const identity = await getDefault()
+      const result: WhoamiResult = {
+        name: identity.name,
+        subject: identity.subject,
+      }
+      if (isMachine(opts)) {
+        output(result, opts)
+        return
+      }
+      console.log(`${chalk.bold(result.name)} (subject: ${result.subject})`)
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/idp/add.ts

@@ -0,0 +1,150 @@
+import { readFile } from 'node:fs/promises'
+
+import type { CommandDefinition } from '../../command'
+
+import {
+  fetchOidcMetadata,
+  fetchWorkosApplication,
+  OidcMetadataSchema,
+  type IdpClientConfig,
+  upsertIdpConfig,
+  workosAuthKitMetadata,
+} from '../../lib/idp'
+import { log } from '../../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+import { validateName, validateUrl } from '../../lib/validation'
+
+type AddOpts = {
+  issuer?: string
+  metadata?: string
+  clientId?: string
+  clientSecretEnv?: string
+  redirectUri?: string
+  scope?: string
+  public?: boolean
+  workosApiKeyEnv?: string
+  workosApp?: string
+  workosAuthkit?: boolean
+  workosApiHostname?: string
+  raw?: boolean
+  json?: boolean
+}
+
+export default {
+  name: 'add',
+  description: 'Add or update an OpenID Connect identity provider',
+  arguments: [{ name: 'name', description: 'Local IdP registry name' }],
+  options: [
+    { flags: '--issuer <url>', description: 'OIDC issuer URL' },
+    { flags: '--metadata <path>', description: 'Read discovery metadata from a local JSON file' },
+    { flags: '--client-id <id>', description: 'OAuth/OIDC client ID' },
+    { flags: '--client-secret-env <name>', description: 'Env var containing the client secret' },
+    { flags: '--redirect-uri <url>', description: 'Redirect URI for authorization-code login' },
+    { flags: '--scope <scope>', description: 'Default OAuth scope string' },
+    { flags: '--public', description: 'Mark the client as public/PKCE-capable' },
+    {
+      flags: '--workos-api-key-env <name>',
+      description: 'Env var containing the WorkOS API key',
+      default: 'WORKOS_API_KEY',
+    },
+    { flags: '--workos-app <id>', description: 'Fetch WorkOS Connect application metadata' },
+    {
+      flags: '--workos-authkit',
+      description: 'Configure WorkOS AuthKit CLI Auth using client_id only',
+    },
+    {
+      flags: '--workos-api-hostname <url>',
+      description: 'WorkOS API host for AuthKit CLI Auth',
+      default: 'https://api.workos.com',
+    },
+    ...RAW_OUTPUT_OPTIONS,
+  ],
+  afterHelpText: `
+Examples:
+  $ astrale idp add workos --workos-authkit --client-id client_...
+  $ astrale idp add workos-connect --issuer https://example.authkit.app \\
+      --client-id client_... --scope "openid profile email offline_access"
+  $ astrale idp add workos-connect --issuer https://example.authkit.app \\
+      --workos-app app_... --workos-api-key-env WORKOS_API_KEY
+
+Security:
+  Client secrets and WorkOS API keys are never stored by the CLI. Store only
+  the env var name with --client-secret-env / --workos-api-key-env.
+`,
+  action: async (name: string, opts: AddOpts) => {
+    validateName(name, 'IdP')
+    if (!opts.issuer && !opts.metadata && !opts.workosAuthkit) {
+      throw new Error('Either --issuer, --metadata, or --workos-authkit is required')
+    }
+
+    let metadata = opts.workosAuthkit
+      ? workosAuthKitMetadata(opts.workosApiHostname, opts.clientId)
+      : opts.metadata
+        ? OidcMetadataSchema.parse(JSON.parse(await readFile(opts.metadata, 'utf-8')))
+        : await fetchOidcMetadata(opts.issuer!)
+
+    if (opts.issuer) {
+      validateUrl(opts.issuer)
+      if (normalizeIssuer(metadata.issuer) !== normalizeIssuer(opts.issuer)) {
+        throw new Error(
+          `OIDC issuer mismatch: metadata has ${metadata.issuer}, expected ${opts.issuer}`,
+        )
+      }
+    }
+
+    let client: IdpClientConfig = {
+      client_id: opts.clientId,
+      client_secret_env: opts.clientSecretEnv,
+      redirect_uris: opts.redirectUri ? [opts.redirectUri] : undefined,
+      scope: opts.scope,
+      public: opts.public,
+      token_response: opts.workosAuthkit ? 'workos-authkit' : undefined,
+      token_request_format: opts.workosAuthkit ? 'json' : undefined,
+    }
+
+    if (opts.workosApp) {
+      const app = await fetchWorkosApplication({
+        app: opts.workosApp,
+        apiKeyEnv: opts.workosApiKeyEnv ?? 'WORKOS_API_KEY',
+      })
+      client = {
+        ...client,
+        client_id: client.client_id ?? app.client_id,
+        redirect_uris:
+          client.redirect_uris ?? app.redirect_uris?.map((uri) => uri.uri).filter(isString),
+        scope: client.scope ?? app.scopes?.join(' '),
+        public: client.public ?? app.uses_pkce,
+        workos_application_id: app.id,
+        workos_application_type: app.application_type,
+      }
+    }
+
+    if (opts.workosAuthkit && client.client_id) {
+      metadata = workosAuthKitMetadata(opts.workosApiHostname, client.client_id)
+    }
+
+    const idp = await upsertIdpConfig({ name, metadata, client })
+    if (isMachine(opts)) {
+      output(redact(idp), opts)
+      return
+    }
+
+    log.success(`IdP "${name}" saved`)
+    log.dim(`  issuer: ${idp.metadata.issuer}`)
+    if (idp.client.client_id) log.dim(`  client_id: ${idp.client.client_id}`)
+    if (idp.client.client_secret_env)
+      log.dim(`  client_secret_env: ${idp.client.client_secret_env}`)
+  },
+} satisfies CommandDefinition
+
+function isString(value: unknown): value is string {
+  return typeof value === 'string'
+}
+
+function redact<T extends { client: IdpClientConfig }>(value: T): T {
+  return value
+}
+
+function normalizeIssuer(value: string): string {
+  return value.replace(/\/+$/, '')
+}

package/src/commands/idp/list.ts

@@ -0,0 +1,57 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+import type { ListOpts, ListProjection } from '../../lib/output'
+
+import { listIdpConfigs } from '../../lib/idp'
+import { log } from '../../lib/log'
+import { isMachine, presentList, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+
+type IdpRow = {
+  name: string
+  issuer: string
+  clientId?: string
+  scope?: string
+  builtIn: boolean
+  updatedAt?: string
+}
+
+function projection(items: IdpRow[]): ListProjection {
+  return {
+    columns: [
+      { key: 'name', header: 'NAME', color: chalk.bold },
+      { key: 'type', header: 'TYPE', color: chalk.dim },
+      { key: 'issuer', header: 'ISSUER', color: chalk.dim },
+      { key: 'clientId', header: 'CLIENT_ID', color: chalk.dim },
+    ],
+    rows: items.map((i) => ({
+      name: i.name,
+      type: i.builtIn ? 'built-in' : 'custom',
+      issuer: i.issuer ?? '',
+      clientId: i.clientId ?? '',
+    })),
+    paths: items.map((i) => i.name),
+  }
+}
+
+export default {
+  name: 'list',
+  description: 'List configured identity providers',
+  options: [...RAW_OUTPUT_OPTIONS],
+  action: async (opts: ListOpts) => {
+    const items: IdpRow[] = (await listIdpConfigs()).map((config) => ({
+      name: config.name,
+      issuer: config.entry.issuer,
+      clientId: config.client.client_id,
+      scope: config.client.scope,
+      builtIn: !!config.entry.builtIn,
+      updatedAt: config.entry.updatedAt,
+    }))
+
+    if (items.length === 0 && !isMachine(opts)) {
+      log.dim('  No IdPs. Run: astrale idp add <name> --issuer <url>')
+      return
+    }
+    presentList(items, opts, projection)
+  },
+} satisfies CommandDefinition

package/src/commands/idp/refresh.ts

@@ -0,0 +1,38 @@
+import type { CommandDefinition } from '../../command'
+
+import {
+  fetchOidcMetadata,
+  readIdpConfigOrBuiltin,
+  upsertIdpConfig,
+  workosAuthKitMetadata,
+} from '../../lib/idp'
+import { log } from '../../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+
+export default {
+  name: 'refresh',
+  description: 'Refresh discovery metadata for an identity provider',
+  arguments: [{ name: 'name', description: 'Local IdP registry name' }],
+  options: [...RAW_OUTPUT_OPTIONS],
+  action: async (name: string, opts: { raw?: boolean; json?: boolean }) => {
+    const existing = await readIdpConfigOrBuiltin(name)
+    const metadata =
+      existing.client.token_response === 'workos-authkit'
+        ? workosAuthKitMetadata(existing.entry.issuer)
+        : await fetchOidcMetadata(existing.entry.issuer)
+    const idp = await upsertIdpConfig({
+      name,
+      metadata,
+      client: existing.client,
+      builtIn: existing.entry.builtIn,
+    })
+
+    if (isMachine(opts)) {
+      output(idp, opts)
+      return
+    }
+
+    log.success(`IdP "${name}" discovery metadata refreshed`)
+    log.dim(`  issuer: ${idp.metadata.issuer}`)
+  },
+} satisfies CommandDefinition

package/src/commands/idp/remove.ts

@@ -0,0 +1,36 @@
+import type { CommandDefinition } from '../../command'
+
+import { readIdentities } from '../../lib/identity'
+import { removeIdpConfig } from '../../lib/idp'
+import { log } from '../../lib/log'
+import { output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+
+export default {
+  name: 'remove',
+  aliases: ['rm'],
+  description: 'Remove an identity provider',
+  arguments: [{ name: 'name', description: 'Local IdP registry name' }],
+  options: [
+    { flags: '--force', description: 'Remove even when IdP-backed identities exist' },
+    ...RAW_OUTPUT_OPTIONS,
+  ],
+  action: async (name: string, opts: { force?: boolean; raw?: boolean; json?: boolean }) => {
+    const store = await readIdentities()
+    const dependents = Object.entries(store.identities)
+      .filter(([, identity]) => identity.source === 'idp' && identity.idp === name)
+      .map(([identityName]) => identityName)
+
+    if (dependents.length > 0 && !opts.force) {
+      throw new Error(
+        `IdP "${name}" is used by identities: ${dependents.join(', ')}. Re-run with --force or delete those identities first.`,
+      )
+    }
+
+    await removeIdpConfig(name)
+    if (opts.raw || opts.json) {
+      output({ removed: name, dependentIdentities: dependents }, opts)
+      return
+    }
+    log.success(`IdP "${name}" removed`)
+  },
+} satisfies CommandDefinition

package/src/commands/idp/show.ts

@@ -0,0 +1,29 @@
+import type { CommandDefinition } from '../../command'
+
+import { readIdpConfigOrBuiltin } from '../../lib/idp'
+import { output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+
+export default {
+  name: 'show',
+  description: 'Show an identity provider configuration',
+  arguments: [{ name: 'name', description: 'Local IdP registry name' }],
+  options: [
+    { flags: '--format <type>', description: 'Output format', choices: ['yaml', 'json'] },
+    ...RAW_OUTPUT_OPTIONS,
+  ],
+  action: async (
+    name: string,
+    opts: { raw?: boolean; json?: boolean; format?: 'yaml' | 'json' },
+  ) => {
+    const idp = await readIdpConfigOrBuiltin(name)
+    output(
+      {
+        name: idp.name,
+        entry: idp.entry,
+        metadata: idp.metadata,
+        client: idp.client,
+      },
+      opts,
+    )
+  },
+} satisfies CommandDefinition

package/src/commands/instance/active.ts

@@ -0,0 +1,64 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+
+import { withAdminKernelClient } from '../../kernel/client'
+import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { getActive, normalizeInstanceKernelUrl } from '../../lib/instance'
+import { log } from '../../lib/log'
+import { RAW_OUTPUT_OPTIONS, isMachine, output, type RawOutputOpts } from '../../lib/output'
+
+export default {
+  name: 'active',
+  description: 'Show the currently active instance',
+  options: [...RAW_OUTPUT_OPTIONS],
+  action: async (opts: RawOutputOpts) => {
+    try {
+      const isRaw = isMachine(opts)
+      const active = await resolveActiveForDisplay()
+      const { name } = active
+      const url = active.url ?? null
+      const createdAt = active.createdAt ?? null
+
+      if (isRaw) {
+        output({ name, url, createdAt }, opts)
+        return
+      }
+
+      console.log(`${chalk.bold(name)} (${url ?? 'local'})`)
+    } catch (e) {
+      log.error(e instanceof Error ? e.message : String(e))
+      process.exit(1)
+    }
+  },
+} satisfies CommandDefinition
+
+async function resolveActiveForDisplay(): Promise<{
+  name: string
+  url?: string
+  createdAt?: string
+}> {
+  const active = await getActive()
+  if (active.url) {
+    return {
+      name: active.name,
+      url: active.url,
+      createdAt: active.createdAt,
+    }
+  }
+
+  try {
+    const managed = await withAdminKernelClient(
+      {},
+      async (ctx) =>
+        (await ctx.client.call(`${ADMIN_INSTANCE}/info`, { id: active.name })) as InstanceInfo,
+    )
+    return {
+      name: managed.slug,
+      url: normalizeInstanceKernelUrl(managed.url),
+      createdAt: managed.createdAt,
+    }
+  } catch {
+    return { name: active.name }
+  }
+}

package/src/commands/instance/bookmark.ts

@@ -0,0 +1,72 @@
+import type { CommandDefinition } from '../../command'
+
+import { fetchWithCaFile } from '../../kernel/ca-fetch'
+import { normalizeInstanceKernelUrl, setActive, upsertInstance } from '../../lib/instance'
+import { fatal, log } from '../../lib/log'
+import { checkIssuerReachability } from '../../lib/meta'
+
+export default {
+  name: 'bookmark',
+  description: 'Register a reference to an existing remote instance',
+  arguments: [{ name: 'name', description: 'Bookmark name (free, required)', required: true }],
+  options: [
+    { flags: '--url <url>', description: 'URL of the remote instance (required)' },
+    { flags: '--issuer <url>', description: 'Kernel issuer/audience if different from URL' },
+    { flags: '--ca <path>', description: 'CA certificate file to trust for this bookmark' },
+    {
+      flags: '--as <identity>',
+      description: 'Default identity for this bookmark',
+    },
+    { flags: '--use', description: 'Set as active instance after bookmarking' },
+    { flags: '--skip-probe', description: 'Skip the OIDC + JWKS liveness probe (still recorded)' },
+  ],
+  action: async (
+    name: string,
+    opts: {
+      url?: string
+      issuer?: string
+      ca?: string
+      as?: string
+      use?: boolean
+      skipProbe?: boolean
+    },
+  ) => {
+    try {
+      if (!opts.url) fatal(new Error('Missing required flag: --url <url>'))
+      const url = normalizeInstanceKernelUrl(opts.url)
+      const expectedIssuer = opts.issuer ? normalizeInstanceKernelUrl(opts.issuer) : undefined
+
+      if (!opts.skipProbe) {
+        try {
+          const { issuer, keys } = await checkIssuerReachability(
+            url,
+            expectedIssuer,
+            opts.ca ? fetchWithCaFile(opts.ca) : undefined,
+          )
+          log.dim(`  iss=${issuer} keys=${keys.length}`)
+        } catch (e) {
+          log.dim('  (re-run with --skip-probe to bookmark anyway.)')
+          fatal(e)
+        }
+      }
+
+      const { entry, created } = await upsertInstance(name, {
+        url,
+        issuer: expectedIssuer,
+        caFile: opts.ca,
+        name,
+        kind: 'bookmark',
+        mode: 'remote',
+        defaultIdentity: opts.as,
+      })
+      log.success(`${created ? 'Bookmarked' : 'Updated bookmark'} "${name}" → ${entry.url}`)
+      if (opts.as) log.dim(`  default identity: ${opts.as}`)
+      if (opts.use) {
+        await setActive(name)
+        log.success(`Active instance: ${name}`)
+      }
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/instance/create.ts

@@ -0,0 +1,69 @@
+import type { CommandDefinition } from '../../command'
+
+import { ADMIN_TARGET_OPTIONS } from '../../lib/admin-target'
+import { fatal } from '../../lib/log'
+import { isMachine, output } from '../../lib/output'
+import { promptText } from '../../lib/prompt'
+import { provisionInstance, type ProvisionOpts } from '../../lib/provision-instance'
+import { validateSlug } from '../../lib/validation'
+
+// Re-exported for tests + `astrale setup`, which share the provisioning saga.
+export { assertAlphaCreateIdentity, parseEligibleHostIds } from '../../lib/provision-instance'
+
+/** inquirer `validate` for a slug: true when valid, else the human message. */
+function slugError(value: string): true | string {
+  try {
+    validateSlug(value)
+    return true
+  } catch (e) {
+    return e instanceof Error ? e.message : 'Invalid slug'
+  }
+}
+
+export default {
+  name: 'create',
+  description: 'Provision an alpha instance through the admin kernel (Instance.alphaCreate)',
+  afterHelpText: `
+Behavior:
+  Calls Instance.alphaCreate on the configured admin kernel. The caller must be
+  logged in with WorkOS. When --host-id is omitted, the admin kernel chooses the
+  caller's single eligible host. The new instance becomes the active instance.
+
+  Run with no slug in a terminal and it prompts for one (validated live). With
+  no TTY — or --ci / --no-prompt — the slug argument is required up front, so
+  piped / CI / agent runs fail fast instead of waiting on input.
+
+Examples:
+  $ astrale auth login
+  $ astrale instance create demo
+`,
+  arguments: [{ name: 'id', description: 'Instance slug', required: false }],
+  options: [
+    ...ADMIN_TARGET_OPTIONS,
+    {
+      flags: '--host-id <id>',
+      description: 'Advanced: host node id to provision on when multiple hosts are available',
+    },
+  ],
+  action: async (id: string | undefined, opts: ProvisionOpts) => {
+    try {
+      // Interactive (TTY only): prompt for the slug when omitted, with live
+      // validation. No TTY / --ci / --no-prompt / CI → the slug arg is required
+      // (fail fast, never hang a piped / agent / LLM run).
+      const interactive = !!process.stdin.isTTY && !(opts.ci || opts.noPrompt || process.env.CI)
+      if (!id && interactive) id = await promptText('Instance slug', { validate: slugError })
+      if (!id) {
+        throw new Error('`instance create` needs a slug, e.g. `astrale instance create demo`.')
+      }
+
+      const { created } = await provisionInstance(id, opts)
+
+      if (isMachine(opts)) {
+        output(created, opts)
+        return
+      }
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition