@astrale-os/cli 0.4.0-alpha.13

package/src/lib/instance-candidates.ts

@@ -0,0 +1,49 @@
+import type { InstanceEntry, InstanceStore } from './instance'
+
+import { formatInstanceLocation, type InstanceInfo } from './admin-instance'
+import { normalizeInstanceKernelUrl, resolveInstanceKey } from './instance'
+
+export type InstanceCandidate =
+  | { source: 'bookmark'; key: string; url: string; entry: InstanceEntry }
+  | { source: 'managed'; key: string; url: string; info: InstanceInfo }
+
+/**
+ * Gather every instance a bare name can refer to — the local bookmark
+ * (collision-guarded, so at most one) plus admin-managed instances matching
+ * the slug. A managed instance already bookmarked at the same kernel URL
+ * collapses into the bookmark candidate instead of appearing twice.
+ */
+export function collectInstanceCandidates(
+  name: string,
+  store: InstanceStore,
+  managed: InstanceInfo[],
+): InstanceCandidate[] {
+  const out: InstanceCandidate[] = []
+
+  const key = resolveInstanceKey(store, name)
+  const entry = key ? store.instances[key] : undefined
+  const bookmarkUrl = entry?.url ? normalizeInstanceKernelUrl(entry.url) : null
+  if (key && entry && bookmarkUrl) {
+    out.push({ source: 'bookmark', key, url: bookmarkUrl, entry })
+  }
+
+  for (const info of managed) {
+    if (info.slug !== name && info.id !== name) continue
+    // The type says url is set, but a still-provisioning instance can
+    // come back without one — not a usable target.
+    if (!info.url) continue
+    const url = normalizeInstanceKernelUrl(info.url)
+    if (bookmarkUrl && url === bookmarkUrl) continue
+    out.push({ source: 'managed', key: info.slug, url, info })
+  }
+
+  return out
+}
+
+export function describeInstanceCandidate(candidate: InstanceCandidate): string {
+  if (candidate.source === 'bookmark') {
+    return `${candidate.key} (bookmark) ${candidate.url}`
+  }
+  const extra = formatInstanceLocation(candidate.info)
+  return `${candidate.key} (managed) ${candidate.url}${extra ? ` — ${extra}` : ''}`
+}

package/src/lib/instance-target.ts

@@ -0,0 +1,182 @@
+import type { InstanceInfo } from './admin-instance'
+import type { AstraleConfig } from './config'
+
+import { AstraleError } from '../errors'
+import {
+  DEFAULT_ADMIN_TARGET_NAME,
+  resolveAdminTarget,
+  type AdminTargetCommandOpts,
+  type ResolvedAdminTarget,
+} from './admin-target'
+import {
+  getActive,
+  normalizeInstanceKernelUrl,
+  resolveInstance,
+  resolveInstanceKey,
+  type InstanceStore,
+} from './instance'
+import { validateSlug } from './validation'
+
+export type InstanceTargetRequest =
+  | { source: 'active' }
+  | { source: 'name'; name: string }
+  | { source: 'admin' }
+  | { source: 'url'; url: string; name?: string; issuer?: string }
+
+export type ResolvedInstanceTarget = {
+  name?: string
+  source: 'bookmark' | 'managed' | 'admin' | 'url'
+  url: string
+  issuer: string
+  defaultIdentity?: string
+  caFile?: string
+}
+
+export type ResolveInstanceTargetOpts = {
+  config: AstraleConfig
+  instances?: InstanceStore
+  admin?: AdminTargetCommandOpts
+  managed?: (slug: string) => Promise<InstanceInfo>
+}
+
+export async function resolveInstanceTarget(
+  request: InstanceTargetRequest,
+  opts: ResolveInstanceTargetOpts,
+): Promise<ResolvedInstanceTarget> {
+  switch (request.source) {
+    case 'active': {
+      const active = opts.instances ? activeFromStore(opts.instances) : await getActive(opts.config)
+      return resolveNamedInstanceTarget(active.name, opts)
+    }
+    case 'name':
+      return resolveNamedInstanceTarget(request.name, opts)
+    case 'admin':
+      return adminTargetToInstance(
+        await resolveAdminTarget(opts.admin ?? {}, opts.config, opts.instances),
+      )
+    case 'url':
+      return {
+        name: request.name,
+        source: 'url',
+        url: request.url,
+        issuer: request.issuer ?? request.url,
+      }
+  }
+}
+
+async function resolveNamedInstanceTarget(
+  identifier: string,
+  opts: ResolveInstanceTargetOpts,
+): Promise<ResolvedInstanceTarget> {
+  let notFound: AstraleError
+  try {
+    return await resolveBookmarkedInstanceTarget(identifier, opts)
+  } catch (e) {
+    if (!(e instanceof AstraleError) || e.code !== 'INSTANCE_NOT_FOUND') throw e
+    notFound = e
+  }
+
+  if (couldBeConfiguredAdminInstance(identifier, opts.config)) {
+    const admin = await resolveAdminTarget(opts.admin ?? {}, opts.config, opts.instances)
+    const target = adminTargetToInstance(admin)
+    if (identifier === target.name) return target
+  }
+
+  try {
+    validateSlug(identifier)
+  } catch {
+    throw notFound
+  }
+  if (!opts.managed) throw notFound
+
+  let managed: InstanceInfo
+  try {
+    managed = await opts.managed(identifier)
+  } catch (e) {
+    if (!isManagedInstanceNotFound(e)) throw e
+    throw notFound
+  }
+
+  const url = normalizeInstanceKernelUrl(managed.url)
+  return {
+    name: managed.slug,
+    source: 'managed',
+    url,
+    issuer: url,
+  }
+}
+
+async function resolveBookmarkedInstanceTarget(
+  identifier: string,
+  opts: ResolveInstanceTargetOpts,
+): Promise<ResolvedInstanceTarget> {
+  if (opts.instances) {
+    const key = resolveInstanceKey(opts.instances, identifier)
+    const entry = key ? opts.instances.instances[key] : undefined
+    if (!key || !entry?.url) throw instanceNotFound(identifier)
+    const url = normalizeInstanceKernelUrl(entry.url)
+    return {
+      name: key,
+      source: 'bookmark',
+      url,
+      issuer: entry.issuer ? normalizeInstanceKernelUrl(entry.issuer) : url,
+      defaultIdentity: entry.defaultIdentity,
+      caFile: entry.caFile,
+    }
+  }
+
+  const resolved = await resolveInstance(identifier, opts.config)
+  return {
+    name: resolved.name,
+    source: 'bookmark',
+    url: resolved.url,
+    issuer: resolved.issuer ?? resolved.url,
+    defaultIdentity: resolved.defaultIdentity,
+    caFile: resolved.caFile,
+  }
+}
+
+function activeFromStore(store: InstanceStore): { name: string } {
+  if (!store.active) {
+    throw new Error('No active instance. Run: astrale instance bookmark <name> --url <url> --use')
+  }
+  return { name: store.active }
+}
+
+function instanceNotFound(identifier: string): AstraleError {
+  return new AstraleError(
+    'INSTANCE_NOT_FOUND',
+    `Instance "${identifier}" is not bookmarked.\n` +
+      `  Bookmark: astrale instance bookmark ${identifier} --url <url>\n` +
+      `  Or pass --url <kernel-url> directly.`,
+  )
+}
+
+export function couldBeConfiguredAdminInstance(identifier: string, config: AstraleConfig): boolean {
+  const admin = config.admin
+  if (admin.instance) return identifier === admin.instance
+  return identifier === (admin.name ?? DEFAULT_ADMIN_TARGET_NAME)
+}
+
+export function adminTargetToInstance(target: ResolvedAdminTarget): ResolvedInstanceTarget {
+  return {
+    name: target.registrationSlug,
+    source: 'admin',
+    url: target.url,
+    issuer: target.issuer,
+    defaultIdentity: target.defaultIdentity,
+    ...(target.caFile ? { caFile: target.caFile } : {}),
+  }
+}
+
+export function isManagedInstanceNotFound(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+  if (error.name === 'NotFoundError') return true
+  const data = (error as Error & { data?: unknown }).data
+  return (
+    error.name === 'KernelError' &&
+    !!data &&
+    typeof data === 'object' &&
+    (data as { type?: unknown }).type === 'NotFoundError'
+  )
+}

package/src/lib/instance.ts

@@ -0,0 +1,395 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { z } from 'zod'
+
+import type { AstraleConfig } from './config'
+
+import { AstraleError, IdentifierCollisionError, ReservedSlugError } from '../errors'
+import { log } from './log'
+import { INSTANCES_PATH } from './paths'
+import {
+  RESERVED_SLUGS,
+  RegistryModeSchema,
+  validateName,
+  validateUrl,
+  type RegistryMode,
+} from './validation'
+
+export const InstanceKindSchema = z.enum(['bookmark'])
+export type InstanceKind = z.infer<typeof InstanceKindSchema>
+
+export const InstanceEntrySchema = z.object({
+  url: z.string().optional(),
+  issuer: z.string().optional(),
+  createdAt: z.string().optional(),
+  slug: z.string().optional(),
+  name: z.string().optional(),
+  kind: InstanceKindSchema.optional(),
+  mode: RegistryModeSchema.optional(),
+  defaultIdentity: z.string().optional(),
+  caFile: z.string().optional(),
+  // WorkOS org captured from `instance create` — authoritative for token
+  // scoping (the router's /auth/org lookup is eventually consistent).
+  organizationId: z.string().optional(),
+})
+
+export const InstanceStoreSchema = z.object({
+  active: z.string(),
+  instances: z.record(z.string(), InstanceEntrySchema),
+})
+
+export type InstanceEntry = z.infer<typeof InstanceEntrySchema>
+export type InstanceStore = z.infer<typeof InstanceStoreSchema>
+
+export type AddInstanceOpts = {
+  url?: string
+  slug?: string
+  name?: string
+  kind?: InstanceKind
+  mode?: RegistryMode
+  issuer?: string
+  defaultIdentity?: string
+  caFile?: string
+  organizationId?: string
+}
+
+export type ResolvedInstance = {
+  name: string
+  kind: InstanceKind | 'managed'
+  url: string
+  issuer?: string
+  createdAt?: string
+  defaultIdentity?: string
+  caFile?: string
+  mode?: RegistryMode
+  status?: string
+}
+
+function seed(): InstanceStore {
+  return { active: '', instances: {} }
+}
+
+export function sanitizeStore(store: InstanceStore): { store: InstanceStore; changed: boolean } {
+  let changed = false
+  const instances: Record<string, InstanceEntry> = {}
+
+  for (const [key, entry] of Object.entries(store.instances)) {
+    if (key === 'manager') {
+      changed = true
+      continue
+    }
+    if (!entry.url) {
+      changed = true
+      continue
+    }
+    const normalizedUrl = normalizeInstanceKernelUrl(entry.url)
+    const normalizedIssuer = entry.issuer ? normalizeInstanceKernelUrl(entry.issuer) : entry.issuer
+    const next: InstanceEntry = {
+      ...entry,
+      url: normalizedUrl,
+      issuer: normalizedIssuer,
+      kind: 'bookmark',
+    }
+    // VALUE comparison only. The old `next !== entry` (object identity) was
+    // ALWAYS true, so every read rewrote instances.json fire-and-forget —
+    // concurrent astrale processes clobbered each other's `active` from
+    // stale snapshots (observed: `instance create` setting the active
+    // target, then a parallel command silently reverting it — every call
+    // after that wrote to the WRONG instance).
+    if (
+      entry.kind !== 'bookmark' ||
+      normalizedUrl !== entry.url ||
+      normalizedIssuer !== entry.issuer
+    ) {
+      changed = true
+    }
+    instances[key] = next
+  }
+
+  const active = store.active || Object.keys(instances)[0] || ''
+  if (active !== store.active) changed = true
+  return { store: { active, instances }, changed }
+}
+
+let instancesMemo: InstanceStore | null = null
+
+export async function readInstances(
+  _config?: AstraleConfig,
+  opts: { persist?: boolean } = {},
+): Promise<InstanceStore> {
+  if (instancesMemo) return instancesMemo
+  let raw: string
+  try {
+    raw = await readFile(INSTANCES_PATH, 'utf-8')
+  } catch {
+    instancesMemo = seed()
+    return instancesMemo
+  }
+
+  let parsed: InstanceStore
+  try {
+    parsed = InstanceStoreSchema.parse(JSON.parse(raw))
+  } catch (e) {
+    const reason = e instanceof z.ZodError ? 'invalid schema' : 'corrupt JSON'
+    log.warn(`Could not read instances at ${INSTANCES_PATH} (${reason}) — using empty registry`)
+    instancesMemo = seed()
+    return instancesMemo
+  }
+
+  const { store, changed } = sanitizeStore(parsed)
+  instancesMemo = store
+  // Self-heal a stale/unnormalized store on read — but never from a read-only
+  // caller (`opts.persist: false`, e.g. status / `setup --plan`). Any mutating
+  // path reads with the default and rewrites, so healing still happens there.
+  if (changed && opts.persist !== false) writeInstances(store).catch(() => undefined)
+  return store
+}
+
+export async function writeInstances(store: InstanceStore): Promise<void> {
+  await mkdir(dirname(INSTANCES_PATH), { recursive: true })
+  await writeFile(INSTANCES_PATH, JSON.stringify(store, null, 2) + '\n')
+  instancesMemo = store
+}
+
+function collectIdentifiers(store: InstanceStore, skipKey?: string): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const [key, entry] of Object.entries(store.instances)) {
+    if (key === skipKey) continue
+    out.set(key, `instance key "${key}"`)
+    if (entry.slug && !out.has(entry.slug)) out.set(entry.slug, `slug of instance "${key}"`)
+    if (entry.name && !out.has(entry.name)) out.set(entry.name, `name of instance "${key}"`)
+  }
+  return out
+}
+
+export function assertNoCollision(
+  store: InstanceStore,
+  identifiers: string[],
+  ignoreKey?: string,
+): void {
+  // Skip the ignored entry at collection time (never delete by identifier
+  // string: another entry may own the same slug/name alias).
+  const existing = collectIdentifiers(store, ignoreKey)
+  for (const id of identifiers) {
+    if (!id) continue
+    const owner = existing.get(id)
+    if (owner) throw new IdentifierCollisionError(id, owner)
+  }
+}
+
+export function resolveInstanceKey(store: InstanceStore, identifier: string): string | null {
+  if (store.instances[identifier]) return identifier
+  for (const [key, entry] of Object.entries(store.instances)) {
+    if (entry.slug === identifier || entry.name === identifier) return key
+  }
+  return null
+}
+
+export async function addInstance(key: string, opts: AddInstanceOpts = {}): Promise<InstanceEntry> {
+  validateName(key, 'Instance')
+  if (RESERVED_SLUGS.has(key)) throw new ReservedSlugError(key)
+  if (!opts.url) throw new Error('Instance bookmarks require --url <url>')
+  const normalizedUrl = normalizeInstanceKernelUrl(opts.url)
+  validateUrl(normalizedUrl)
+
+  const store = await readInstances()
+  if (store.instances[key]) {
+    throw new Error(
+      `Instance "${key}" already exists. Remove it first with: astrale instance forget ${key}`,
+    )
+  }
+  assertNoCollision(store, [key, opts.slug, opts.name].filter(Boolean) as string[])
+
+  const entry: InstanceEntry = {
+    ...opts,
+    url: normalizedUrl,
+    issuer: opts.issuer ? normalizeInstanceKernelUrl(opts.issuer) : opts.issuer,
+    kind: 'bookmark',
+    createdAt: new Date().toISOString(),
+  }
+  store.instances[key] = entry
+  if (!store.active) store.active = key
+  await writeInstances(store)
+  return entry
+}
+
+export async function upsertInstance(
+  key: string,
+  opts: AddInstanceOpts = {},
+): Promise<{ entry: InstanceEntry; created: boolean }> {
+  validateName(key, 'Instance')
+  if (RESERVED_SLUGS.has(key)) throw new ReservedSlugError(key)
+  if (!opts.url) throw new Error('Instance bookmarks require --url <url>')
+  const normalizedUrl = normalizeInstanceKernelUrl(opts.url)
+  validateUrl(normalizedUrl)
+
+  const store = await readInstances()
+  assertNoCollision(store, [key, opts.slug, opts.name].filter(Boolean) as string[], key)
+
+  const existing = store.instances[key]
+  const normalizedIssuer = opts.issuer ? normalizeInstanceKernelUrl(opts.issuer) : undefined
+  const entry: InstanceEntry = {
+    ...existing,
+    ...definedEntry(opts),
+    url: normalizedUrl,
+    ...(normalizedIssuer ? { issuer: normalizedIssuer } : {}),
+    kind: 'bookmark',
+    createdAt: existing?.createdAt ?? new Date().toISOString(),
+  }
+  store.instances[key] = entry
+  if (!store.active) store.active = key
+  await writeInstances(store)
+  return { entry, created: !existing }
+}
+
+/**
+ * Bookmark an admin-managed instance under `key` (url = issuer = the
+ * normalized kernel URL). Reports the previous URL when an existing
+ * bookmark was repointed to a different kernel so callers can warn.
+ */
+export async function upsertManagedBookmark(
+  key: string,
+  slug: string,
+  rawUrl: string,
+  organizationId?: string,
+): Promise<{ entry: InstanceEntry; repointedFrom?: string }> {
+  const store = await readInstances()
+  const previousUrl = store.instances[key]?.url
+  const url = normalizeInstanceKernelUrl(rawUrl)
+  const { entry } = await upsertInstance(key, {
+    url,
+    issuer: url,
+    slug,
+    name: slug,
+    kind: 'bookmark',
+    mode: 'remote',
+    ...(organizationId ? { organizationId } : {}),
+  })
+  return {
+    entry,
+    ...(previousUrl && previousUrl !== entry.url ? { repointedFrom: previousUrl } : {}),
+  }
+}
+
+export async function removeInstance(key: string): Promise<void> {
+  const store = await readInstances()
+  if (!store.instances[key]) throw new Error(`Instance "${key}" not found`)
+  delete store.instances[key]
+  if (store.active === key) store.active = Object.keys(store.instances)[0] ?? ''
+  await writeInstances(store)
+}
+
+export async function setActive(identifier: string): Promise<string> {
+  const store = await readInstances()
+  const key = resolveInstanceKey(store, identifier)
+  if (!key) {
+    throw new Error(
+      `Instance "${identifier}" is not bookmarked. Run: astrale instance bookmark ${identifier} --url <url>`,
+    )
+  }
+  store.active = key
+  await writeInstances(store)
+  return key
+}
+
+export async function clearActive(identifier: string): Promise<void> {
+  const store = await readInstances()
+  if (store.active !== identifier) return
+  store.active = Object.keys(store.instances)[0] ?? ''
+  await writeInstances(store)
+}
+
+export async function getActive(config?: AstraleConfig): Promise<InstanceEntry & { name: string }> {
+  const store = await readInstances(config)
+  if (!store.active) {
+    throw new Error('No active instance. Run: astrale instance bookmark <name> --url <url> --use')
+  }
+  const entry = store.instances[store.active]
+  return { ...entry, name: store.active }
+}
+
+export async function resolveInstance(
+  identifier: string,
+  config?: AstraleConfig,
+): Promise<ResolvedInstance> {
+  const store = await readInstances(config)
+  const key = resolveInstanceKey(store, identifier)
+  const entry = key ? store.instances[key] : undefined
+  if (!key || !entry?.url) {
+    throw new AstraleError(
+      'INSTANCE_NOT_FOUND',
+      `Instance "${identifier}" is not bookmarked.\n` +
+        `  Bookmark: astrale instance bookmark ${identifier} --url <url>\n` +
+        `  Or pass --url <kernel-url> directly.`,
+    )
+  }
+  return {
+    name: key,
+    kind: 'bookmark',
+    url: normalizeInstanceKernelUrl(entry.url),
+    issuer: entry.issuer ? normalizeInstanceKernelUrl(entry.issuer) : entry.issuer,
+    createdAt: entry.createdAt,
+    defaultIdentity: entry.defaultIdentity,
+    caFile: entry.caFile,
+    mode: entry.mode,
+  }
+}
+
+export async function resolveKernelUrl(
+  opts: { url?: string; instance?: string },
+  config: AstraleConfig,
+): Promise<string> {
+  if (opts.url) return opts.url
+  const identifier = opts.instance ?? (await getActive(config)).name
+  return (await resolveInstance(identifier, config)).url
+}
+
+/**
+ * The bookmarked org id for the instance matching `audience`'s origin —
+ * consulted before the router's eventually-consistent `/auth/org`.
+ */
+export async function orgIdForAudience(audience: string): Promise<string | undefined> {
+  let origin: string
+  try {
+    origin = new URL(audience).origin
+  } catch {
+    return undefined
+  }
+  const store = await readInstances()
+  for (const entry of Object.values(store.instances)) {
+    if (!entry.organizationId || !entry.url) continue
+    try {
+      if (new URL(entry.url).origin === origin) return entry.organizationId
+    } catch {
+      // unparsable bookmark URL — skip
+    }
+  }
+  return undefined
+}
+
+export function normalizeInstanceKernelUrl(url: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return url
+  }
+  if (!isRegionRoutedInstanceRoot(parsed)) return url.replace(/\/$/, '')
+
+  parsed.pathname = '/api'
+  return parsed.toString().replace(/\/$/, '')
+}
+
+function isRegionRoutedInstanceRoot(url: URL): boolean {
+  if (url.pathname !== '' && url.pathname !== '/') return false
+  if (url.search || url.hash) return false
+
+  const labels = url.hostname.toLowerCase().split('.')
+  return labels.length === 4 && labels[2] === 'astrale' && labels[3] === 'ai'
+}
+
+function definedEntry(entry: AddInstanceOpts): AddInstanceOpts {
+  return Object.fromEntries(
+    Object.entries(entry).filter(([, value]) => value !== undefined),
+  ) as AddInstanceOpts
+}