@astrale-os/cli 0.4.0-alpha.13

package/src/commands/instance/delete.ts

@@ -0,0 +1,72 @@
+import type { CommandDefinition } from '../../command'
+import type { KernelCommandOpts } from '../../kernel'
+
+import { withAdminKernelClient } from '../../kernel/client'
+import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
+import { clearActive, readInstances, removeInstance, resolveInstanceKey } from '../../lib/instance'
+import { fatal, log, withSpinner } from '../../lib/log'
+import { isMachine, output } from '../../lib/output'
+
+type DeleteOpts = KernelCommandOpts &
+  AdminTargetCommandOpts & {
+    keepBookmark?: boolean
+  }
+
+export default {
+  name: 'delete',
+  description: 'Delete an admin-managed instance through the admin kernel',
+  afterHelpText: `
+Behavior:
+  Calls Instance.delete on the configured admin kernel: best-effort decommission
+  of the instance's routing-registry entry + WorkOS org (frees the slug), then
+  removes the Instance record. The host kernel itself is NOT deregistered (the
+  deprovisioning saga is a follow-up). A same-name local bookmark is removed
+  after the delete succeeds unless --keep-bookmark is passed.
+`,
+  arguments: [{ name: 'id', description: 'Instance slug', required: true }],
+  options: [
+    ...ADMIN_TARGET_OPTIONS,
+    { flags: '--keep-bookmark', description: 'Do not remove a same-name local bookmark' },
+  ],
+  action: async (id: string, opts: DeleteOpts) => {
+    // Teardown walks services + deprovisions — same saga-sized budget as create.
+    opts = { ...opts, timeout: opts.timeout ?? '240000' }
+    try {
+      const result = await withSpinner(
+        `Deleting instance ${id}`,
+        !isMachine(opts),
+        () =>
+          withAdminKernelClient(
+            opts,
+            async (ctx) =>
+              (await ctx.client.call(`${ADMIN_INSTANCE}/delete`, { id })) as InstanceInfo,
+          ),
+        { success: (deleted) => `Deleted instance: ${deleted.slug}` },
+      )
+
+      if (!opts.keepBookmark) {
+        const store = await readInstances()
+        const key = resolveInstanceKey(store, id)
+        if (key) await removeInstance(key)
+      }
+      await clearActive(id)
+
+      if (isMachine(opts)) {
+        output(result, opts)
+        return
+      }
+    } catch (e) {
+      // Bookmark-only id → no admin Instance → kernel NOT_FOUND. Point to
+      // `forget` (local drop) instead of surfacing the raw path error.
+      const notManaged =
+        e instanceof Error && (e.name === 'NotFoundError' || e.message.startsWith('Path not found'))
+      if (notManaged && resolveInstanceKey(await readInstances(), id)) {
+        log.error(`No admin-managed instance "${id}".`)
+        log.dim(`  hint: it's a local bookmark — drop it with: astrale instance forget ${id}`)
+        process.exit(1)
+      }
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/instance/forget.ts

@@ -0,0 +1,26 @@
+import type { CommandDefinition } from '../../command'
+
+import { readInstances, removeInstance, resolveInstanceKey } from '../../lib/instance'
+import { fatal, log } from '../../lib/log'
+
+export default {
+  name: 'forget',
+  description: 'Drop a bookmark reference (never destructive kernel-side)',
+  afterHelpText: `
+Behavior:
+  Drops a bookmark reference only — never touches the remote kernel.
+  To destructively remove an admin-managed instance use \`astrale instance delete\`.
+`,
+  arguments: [{ name: 'name', description: 'Bookmark name (slug or name)', required: true }],
+  action: async (name: string) => {
+    try {
+      const store = await readInstances()
+      const key = resolveInstanceKey(store, name)
+      if (!key) fatal(new Error(`Instance "${name}" not found`))
+      await removeInstance(key!)
+      log.success(`Forgot bookmark "${name}" (no kernel-side change)`)
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/instance/list.ts

@@ -0,0 +1,149 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+import type { KernelCommandOpts } from '../../kernel'
+import type { Column } from '../../lib/output'
+
+import { withAdminKernelClient } from '../../kernel/client'
+import { ADMIN_INSTANCE, formatInstanceLocation, type InstanceInfo } from '../../lib/admin-instance'
+import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
+import { normalizeInstanceKernelUrl, readInstances } from '../../lib/instance'
+import { fatal, log, withSpinner } from '../../lib/log'
+import { isMachine, output, type RawOutputOpts } from '../../lib/output'
+import { renderTable } from '../../lib/table'
+
+type ListOpts = KernelCommandOpts &
+  AdminTargetCommandOpts &
+  RawOutputOpts & {
+    bookmarked?: boolean
+    adminOnly?: boolean
+  }
+
+export type Bookmark = {
+  name: string
+  url: string | null
+  issuer: string | null
+  active: boolean
+  defaultIdentity: string | null
+  createdAt: string | null
+}
+
+const COLUMNS: Column[] = [
+  { key: 'name', header: 'NAME', color: chalk.bold },
+  { key: 'kind', header: 'KIND', color: chalk.dim },
+  { key: 'url', header: 'URL', color: chalk.dim },
+  { key: 'extra', header: '', color: chalk.dim },
+]
+
+export default {
+  name: 'list',
+  description: 'List admin-managed instances and local bookmarks',
+  options: [
+    ...ADMIN_TARGET_OPTIONS,
+    { flags: '--bookmarked', description: 'Only show locally bookmarked kernel connections' },
+    { flags: '--admin-only', description: 'Only show instances returned by the admin kernel' },
+  ],
+  action: async (opts: ListOpts) => {
+    try {
+      const store = await readInstances()
+      const bookmarks: Bookmark[] = Object.entries(store.instances).map(([name, entry]) => ({
+        name,
+        url: entry.url ?? null,
+        issuer: entry.issuer ?? null,
+        active: name === store.active,
+        defaultIdentity: entry.defaultIdentity ?? null,
+        createdAt: entry.createdAt ?? null,
+      }))
+
+      let managed: InstanceInfo[] = []
+      if (!opts.bookmarked) {
+        managed = await withSpinner('Fetching instances', !isMachine(opts), () =>
+          withAdminKernelClient(
+            opts,
+            async (ctx) => (await ctx.client.call(`${ADMIN_INSTANCE}/list`, {})) as InstanceInfo[],
+          ),
+        )
+      }
+      if (isMachine(opts)) {
+        output(
+          {
+            active: store.active || null,
+            ...(opts.adminOnly ? {} : { bookmarks }),
+            ...(opts.bookmarked ? {} : { instances: managed }),
+          },
+          opts,
+        )
+        return
+      }
+
+      const rows = buildInstanceRows(managed, bookmarks, {
+        managed: !opts.bookmarked,
+        bookmarks: !opts.adminOnly,
+      })
+
+      if (rows.length === 0) {
+        log.dim('  No instances. Run: astrale instance bookmark <name> --url <url>')
+        return
+      }
+      process.stdout.write(renderTable(rows, { columns: COLUMNS }) + '\n')
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition
+
+/**
+ * One row per instance. A bookmark that points at a managed instance (same
+ * name and same kernel URL) merges into the managed row — carrying the active
+ * marker — instead of listing the instance twice.
+ */
+export function buildInstanceRows(
+  managed: InstanceInfo[],
+  bookmarks: Bookmark[],
+  show: { managed: boolean; bookmarks: boolean },
+): Array<Record<string, string>> {
+  const rows: Array<Record<string, string>> = []
+  const merged = new Set<string>()
+
+  const bookmarkByName = new Map<string, { url: string; active: boolean }>()
+  if (show.managed && show.bookmarks) {
+    for (const bookmark of bookmarks) {
+      if (bookmark.url === null) continue
+      bookmarkByName.set(bookmark.name, {
+        url: normalizeInstanceKernelUrl(bookmark.url),
+        active: bookmark.active,
+      })
+    }
+  }
+
+  if (show.managed) {
+    for (const item of managed) {
+      const candidate = item.url ? bookmarkByName.get(item.slug) : undefined
+      const twin =
+        candidate && item.url && candidate.url === normalizeInstanceKernelUrl(item.url)
+          ? candidate
+          : undefined
+      if (twin) merged.add(item.slug)
+      rows.push({
+        name: twin?.active ? `${item.slug} ${chalk.green('*')}` : item.slug,
+        kind: 'managed',
+        url: item.url ?? '',
+        extra: formatInstanceLocation(item),
+      })
+    }
+  }
+
+  if (show.bookmarks) {
+    for (const item of bookmarks) {
+      if (merged.has(item.name)) continue
+      rows.push({
+        name: item.active ? `${item.name} ${chalk.green('*')}` : item.name,
+        kind: 'bookmark',
+        url: String(item.url ?? ''),
+        extra: '',
+      })
+    }
+  }
+
+  return rows
+}

package/src/commands/instance/status.ts

@@ -0,0 +1,42 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+import type { KernelCommandOpts } from '../../kernel'
+
+import { withAdminKernelClient } from '../../kernel/client'
+import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
+import { fatal, log, withSpinner } from '../../lib/log'
+import { isMachine, output, type RawOutputOpts } from '../../lib/output'
+
+type StatusOpts = KernelCommandOpts & AdminTargetCommandOpts & RawOutputOpts
+
+export default {
+  name: 'status',
+  description: 'Show admin instance status',
+  arguments: [{ name: 'id', description: 'Instance slug', required: true }],
+  options: [...ADMIN_TARGET_OPTIONS],
+  action: async (id: string, opts: StatusOpts) => {
+    try {
+      const result = await withSpinner(`Fetching instance ${id}`, !isMachine(opts), () =>
+        withAdminKernelClient(
+          opts,
+          async (ctx) => (await ctx.client.call(`${ADMIN_INSTANCE}/info`, { id })) as InstanceInfo,
+        ),
+      )
+      if (isMachine(opts)) {
+        output(result, opts)
+        return
+      }
+      console.log(`${chalk.bold(result.slug)} ${chalk.dim(result.url)}`)
+      if (result.state)
+        log.dim(`  state: ${result.state}${result.phase ? ` (${result.phase})` : ''}`)
+      if (result.error) log.dim(`  error: ${result.error}`)
+      if (result.region) log.dim(`  region: ${result.region}`)
+      if (result.hostId) log.dim(`  host: ${result.hostId}`)
+      if (result.createdAt) log.dim(`  created: ${result.createdAt}`)
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/instance/use.ts

@@ -0,0 +1,210 @@
+import type { CommandDefinition } from '../../command'
+
+import { AstraleError } from '../../errors'
+import { withAdminKernelClient } from '../../kernel/client'
+import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { ADMIN_TARGET_OPTIONS } from '../../lib/admin-target'
+import { getDefault, setDefault } from '../../lib/identity'
+import {
+  getActive,
+  readInstances,
+  resolveInstance,
+  resolveInstanceKey,
+  setActive,
+  upsertManagedBookmark,
+  type ResolvedInstance,
+} from '../../lib/instance'
+import {
+  collectInstanceCandidates,
+  describeInstanceCandidate,
+  type InstanceCandidate,
+} from '../../lib/instance-candidates'
+import { fatal, log } from '../../lib/log'
+import { checkIssuerReachability } from '../../lib/meta'
+import { confirmDefaultYes, selectFrom } from '../../lib/prompt'
+import { validateSlug } from '../../lib/validation'
+
+type UseOpts = {
+  admin?: string
+  adminUrl?: string
+  url?: string
+  timeout?: string
+  as?: string
+  creds?: string
+  debug?: boolean
+  ci?: boolean
+  noPrompt?: boolean
+  adoptDefault?: boolean
+  skipJwksCheck?: boolean
+}
+
+async function useInstance(name?: string, opts: UseOpts = {}): Promise<void> {
+  try {
+    if (!name) {
+      const active = await getActive()
+      console.log(`${active.name} (${active.url})`)
+      return
+    }
+
+    const resolved = await resolveUseTarget(name, opts)
+
+    if (!opts.skipJwksCheck && resolved.issuer) {
+      try {
+        await checkIssuerReachability(resolved.url, resolved.issuer)
+      } catch (e) {
+        fatal(e)
+      }
+    }
+
+    await setActive(resolved.name)
+    log.success(`Active instance: ${resolved.name} (${resolved.url})`)
+
+    // §7.1 identity-adoption prompt (DX). Orthogonality preserved — we
+    // only switch on explicit user consent (or --adopt-default in CI).
+    const store = await readInstances()
+    const key = resolveInstanceKey(store, resolved.name)
+    const identityCandidate =
+      resolved.defaultIdentity ?? (key ? store.instances[key]?.defaultIdentity : undefined)
+    if (!identityCandidate) return
+    const active = await getDefault().catch(() => null)
+    if (active?.name === identityCandidate) return
+
+    const inCi = opts.ci || opts.noPrompt || !!process.env.CI
+    if (inCi) {
+      if (opts.adoptDefault) {
+        await setDefault(identityCandidate)
+        log.success(`Identity switched to "${identityCandidate}" (--adopt-default)`)
+      } else {
+        log.dim(
+          `  (instance default identity "${identityCandidate}" — keep active ${active?.name ?? 'none'})`,
+        )
+      }
+      return
+    }
+
+    const msg = `Instance "${resolved.name}" has default identity "${identityCandidate}". Active: "${active?.name ?? 'none'}". Switch identity too?`
+    if (await confirmDefaultYes(msg)) {
+      await setDefault(identityCandidate)
+      log.success(`Identity switched to "${identityCandidate}"`)
+    } else {
+      log.dim('  kept active identity (orthogonal)')
+    }
+  } catch (e) {
+    fatal(e)
+  }
+}
+
+async function resolveUseTarget(name: string, opts: UseOpts): Promise<ResolvedInstance> {
+  const [store, managed] = await Promise.all([readInstances(), fetchManagedInstances(name, opts)])
+  const candidates = collectInstanceCandidates(name, store, managed)
+
+  if (candidates.length === 0) {
+    throw new AstraleError(
+      'INSTANCE_NOT_FOUND',
+      `Instance "${name}" is not bookmarked and not admin-managed.\n` +
+        `  Bookmark: astrale instance bookmark ${name} --url <url>\n` +
+        `  Or check: astrale instance list`,
+    )
+  }
+
+  const interactive = !(opts.ci || opts.noPrompt || process.env.CI)
+  const chosen =
+    candidates.length === 1
+      ? candidates[0]
+      : interactive
+        ? await pickCandidate(name, candidates)
+        : null
+  if (!chosen) throw ambiguousError(name, candidates)
+
+  if (chosen.source === 'bookmark') {
+    return await resolveInstance(chosen.key)
+  }
+
+  assertManagedReady(chosen.info)
+  const { repointedFrom } = await upsertManagedBookmark(chosen.key, chosen.info.slug, chosen.url)
+  if (repointedFrom) {
+    log.warn(`Bookmark "${chosen.key}" repointed: ${repointedFrom} → ${chosen.url}`)
+  }
+  return await resolveInstance(chosen.key)
+}
+
+/**
+ * All admin-managed instances (collectInstanceCandidates filters by name).
+ * Best-effort: an unreachable or unauthenticated admin kernel degrades to
+ * bookmark-only resolution.
+ */
+async function fetchManagedInstances(name: string, opts: UseOpts): Promise<InstanceInfo[]> {
+  try {
+    validateSlug(name)
+  } catch {
+    return []
+  }
+  try {
+    return await withAdminKernelClient(
+      opts,
+      async (ctx) => (await ctx.client.call(`${ADMIN_INSTANCE}/list`, {})) as InstanceInfo[],
+    )
+  } catch {
+    return []
+  }
+}
+
+function assertManagedReady(info: InstanceInfo): void {
+  if (!info.state || info.state === 'ready') return
+  const detail = info.phase && info.phase !== info.state ? ` (${info.phase})` : ''
+  throw new AstraleError(
+    'INSTANCE_NOT_READY',
+    `Instance "${info.slug}" is ${info.state}${detail}; it cannot be selected yet.`,
+    info.error ?? undefined,
+  )
+}
+
+async function pickCandidate(
+  name: string,
+  candidates: InstanceCandidate[],
+): Promise<InstanceCandidate | null> {
+  return selectFrom(
+    `Multiple instances match "${name}":`,
+    candidates.map((candidate) => ({
+      label: describeInstanceCandidate(candidate),
+      value: candidate,
+    })),
+  )
+}
+
+function ambiguousError(name: string, candidates: InstanceCandidate[]): AstraleError {
+  const lines = candidates.map((candidate) => `  - ${describeInstanceCandidate(candidate)}`)
+  return new AstraleError(
+    'INSTANCE_AMBIGUOUS',
+    `Multiple instances match "${name}":\n${lines.join('\n')}`,
+    'Run interactively to pick one, or `astrale instance forget <name>` to drop the stale bookmark.',
+  )
+}
+
+export default {
+  name: 'use',
+  description: 'Set the active kernel instance (no args: show current)',
+  afterHelpText: `
+Behavior:
+  The active instance lives in ~/.astrale/instances.json (a
+  process-global file). Concurrent instance:prepare or parallel test
+  runs can rewrite it under you — in scripted/parallel flows pass
+  -i <instance> on every command instead of relying on \`use\`.
+
+Examples:
+  $ astrale instance use staging
+  $ astrale instance use staging --adopt-default
+`,
+  arguments: [{ name: 'name', description: 'Registered instance name', required: false }],
+  options: [
+    ...ADMIN_TARGET_OPTIONS,
+    {
+      flags: '--adopt-default',
+      description: 'Adopt instance default identity without prompt',
+    },
+    { flags: '--skip-jwks-check', description: 'Skip the /meta ↔ JWKS match check' },
+  ],
+  action: async (name: string | undefined, opts: UseOpts) => {
+    await useInstance(name, opts)
+  },
+} satisfies CommandDefinition