@astrale-os/cli 1.0.0-beta.2 → 1.0.0-beta.20

package/src/lib/__tests__/view-session.test.ts

@@ -58,7 +58,7 @@ describe('view session private state', () => {
             issuer: issuer('https://example.test'),
             etag: `sha256:${'a'.repeat(64)}`,
             revision: revision('b'),
-            declaration: { target: { kind: 'domain' }, auth: 'required' },
+            declaration: { target: { kind: 'domain' } },
           },
         },
         createdAt: '2026-08-12T00:00:00.000Z',
@@ -69,6 +69,7 @@ describe('view session private state', () => {
         issuer: 'https://kernel.test',
         direct: true,
       },
+      externalOrigins: [],
       idleMs: 60_000,
     } satisfies ViewServeConfig
 

package/src/lib/admin-instance.ts

@@ -6,7 +6,7 @@ import { withAdminClientSession } from '../connection'
 export {
   AdminInstanceNotFoundError,
   findOwnedInstance,
-  formatInstanceLocation,
+  formatInstanceState,
   type InstanceInfo,
   type InstanceState,
   type OwnedInstanceInfo,
@@ -19,19 +19,25 @@ export function listOwnedInstances(options: AdminConnectionOptions) {
   )
 }
 
+/** Read caller-visible inventory together with the exact local identity used for the Admin call. */
+export function listOwnedInstancesWithIdentity(options: AdminConnectionOptions) {
+  return withAdminClientSession(options, async (context) =>
+    Object.freeze({
+      instances: await (await connectAdminInstances(context)).list(),
+      ...(context.identity === undefined ? {} : { identity: context.identity }),
+    }),
+  )
+}
+
 /** Reuse an already-open Admin session for a caller-visible Instance inventory. */
 export async function listOwnedInstancesInContext(context: ConnectionContext) {
   return (await connectAdminInstances(context)).list()
 }
 
-/** Provision through Fleet placement or one explicitly resolved Host receiver. */
-export function createOwnedInstance(
-  options: AdminConnectionOptions,
-  slug: string,
-  hostId?: string,
-) {
+/** Request one managed Instance; Admin owns infrastructure placement. */
+export function createOwnedInstance(options: AdminConnectionOptions, slug: string) {
   return withAdminClientSession(options, async (context) =>
-    (await connectAdminInstances(context)).create(slug, hostId),
+    (await connectAdminInstances(context)).create(slug),
   )
 }
 

package/src/lib/admin-target.ts

@@ -5,11 +5,30 @@ import type { InstanceStore } from './instance'
 
 import { AstraleError } from '../errors'
 import { readInstances, resolveInstanceKey } from './instance'
+import { DEFAULT_UPDATE_CHANNEL } from './update'
 import { isHttpUrl } from './validation'
 
 export const DEFAULT_ADMIN_TARGET_NAME = 'admin'
-export const DEFAULT_ADMIN_TARGET_URL = 'https://admin.eu.astrale.ai/api'
-export const DEFAULT_ADMIN_DOMAIN_ISSUER = 'https://admin.beta.astrale.ai'
+
+export function defaultAdminTargetForChannel(channel: string): {
+  readonly url: string
+  readonly domainIssuer: string
+} {
+  return channel === 'stable'
+    ? {
+        url: 'https://admin.eu.astrale.ai/api',
+        domainIssuer: 'https://admin.astrale.ai',
+      }
+    : {
+        url: 'https://admin.eu.beta.astrale.ai/api',
+        domainIssuer: 'https://admin.beta.astrale.ai',
+      }
+}
+
+const DEFAULT_ADMIN_TARGET = defaultAdminTargetForChannel(DEFAULT_UPDATE_CHANNEL)
+
+export const DEFAULT_ADMIN_TARGET_URL = DEFAULT_ADMIN_TARGET.url
+export const DEFAULT_ADMIN_DOMAIN_ISSUER = DEFAULT_ADMIN_TARGET.domainIssuer
 
 export const DEFAULT_ADMIN_TARGET_CONFIG = {
   name: DEFAULT_ADMIN_TARGET_NAME,

package/src/lib/binary.ts

@@ -7,14 +7,31 @@ import { output } from './output'
 
 /** A binary kernel result: bytes (or a stream of them) plus its content-type. */
 export type BinaryLike = {
-  readonly body: Uint8Array
+  readonly body: Uint8Array | AsyncIterable<Uint8Array>
   readonly mediaType: string
+  readonly status?: number
   readonly headers?: Readonly<Record<string, string>>
 }
 
 /** Collapse a (possibly streamed) binary body into a single byte array. */
-export async function readBinaryBody(body: Uint8Array): Promise<Uint8Array> {
-  return body
+export async function readBinaryBody(
+  body: Uint8Array | AsyncIterable<Uint8Array>,
+): Promise<Uint8Array> {
+  if (body instanceof Uint8Array) return new Uint8Array(body)
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for await (const chunk of body) {
+    const detached = new Uint8Array(chunk)
+    chunks.push(detached)
+    size += detached.byteLength
+  }
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
 }
 
 function isTextLike(contentType: string): boolean {
@@ -43,13 +60,13 @@ function humanSize(bytes: number): string {
 function jsonEnvelope(resp: BinaryLike, bytes: Uint8Array): Record<string, unknown> {
   if (isTextLike(resp.mediaType)) {
     return {
-      status: 200,
+      status: resp.status ?? 200,
       contentType: resp.mediaType,
       body: new TextDecoder().decode(bytes),
     }
   }
   return {
-    status: 200,
+    status: resp.status ?? 200,
     contentType: resp.mediaType,
     bodyBase64: Buffer.from(bytes).toString('base64'),
   }

package/src/lib/command-dx.ts

@@ -2,8 +2,6 @@ import type { Command, CommanderError } from 'commander'
 
 import chalk from 'chalk'
 
-import { isMachine } from './output'
-
 export type CommandCatalogEntry = {
   path: string[]
   usage: string
@@ -30,27 +28,27 @@ export function renderCommanderError(
   program: Command,
   error: CommanderError,
   argv = process.argv.slice(2),
+  machine = argv.some((token) => token === '--ci' || token === '--json' || token === '--raw') ||
+    !(process.stdout.isTTY ?? false),
 ): string {
   const tokens = stripOptions(argv)
   const catalog = collectCommandCatalog(program)
   const matched = matchRegisteredPrefix(program, tokens)
 
   if (matched.path.length === 0 && tokens.length > 0) {
-    return maybeMachine(renderUnknownCommand(tokens, catalog))
+    return maybeMachine(renderUnknownCommand(tokens, catalog), machine)
   }
 
   if (error.code === 'commander.missingArgument') {
     const usage = usageFor(matched.path, matched.command)
-    const argName = error.message.match(/'([^']+)'/)?.[1]
     return maybeMachine(
       [
-        `Missing required argument${argName ? ` ${chalk.bold(`<${argName}>`)}` : ''} for ${chalk.bold(
-          `astrale ${matched.path.join(' ')}`,
-        )}`,
+        `Missing required argument for ${chalk.bold(`astrale ${matched.path.join(' ')}`)}`,
         '',
         'Usage:',
         `  astrale ${usage}`,
       ].join('\n'),
+      machine,
     )
   }
 
@@ -66,6 +64,7 @@ export function renderCommanderError(
         'Usage:',
         `  astrale ${usage}`,
       ].join('\n'),
+      machine,
     )
   }
 
@@ -77,6 +76,7 @@ export function renderCommanderError(
         ? ['', 'Did you mean:', ...suggestions.map((s) => `  astrale ${s}`)]
         : []),
     ].join('\n'),
+    machine,
   )
 }
 
@@ -143,8 +143,8 @@ function usageFor(path: string[], command: Command): string {
 
 const ANSI_RE = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g')
 
-function maybeMachine(text: string): string {
-  if (!isMachine()) return text
+function maybeMachine(text: string, machine: boolean): string {
+  if (!machine) return text
   const plain = text.replace(ANSI_RE, '')
   const first = plain.split('\n').find((line) => line.trim().length > 0) ?? plain
   return JSON.stringify({ error: 'USAGE_ERROR', message: first, detail: plain })

package/src/lib/domain-publication.ts

@@ -1,4 +1,4 @@
-import { publication } from '@astrale-os/kernel-protocol'
+import { publication } from '@astrale-os/sdk/publication'
 
 const MAXIMUM_PUBLICATION_BYTES = 1024 * 1024
 type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
@@ -9,8 +9,7 @@ export async function fetchDomainPublication(
   signal?: AbortSignal,
   fetchImpl: FetchLike = globalThis.fetch,
 ): Promise<publication.Publication> {
-  const root = deploymentRoot(input)
-  const url = new URL(publication.PATH, root)
+  const url = domainPublicationUrl(input)
   const response = await fetchImpl(url, {
     redirect: 'error',
     ...(signal === undefined ? {} : { signal }),
@@ -81,7 +80,8 @@ async function cancel(body: ReadableStream<Uint8Array> | null): Promise<void> {
   if (body !== null) await body.cancel().catch(() => undefined)
 }
 
-function deploymentRoot(input: string): URL {
+/** Canonical discovery document for a Domain origin or exact Publication URL. */
+export function domainPublicationUrl(input: string): URL {
   let url: URL
   try {
     url = new URL(input)
@@ -94,9 +94,11 @@ function deploymentRoot(input: string): URL {
     url.password !== '' ||
     url.search !== '' ||
     url.hash !== '' ||
-    !['', '/'].includes(url.pathname)
+    !['', '/', publication.PATH].includes(url.pathname)
   ) {
-    throw new TypeError(`Domain deployment URL must be an HTTP(S) origin: ${input}`)
+    throw new TypeError(
+      `Domain deployment URL must be an HTTP(S) origin or canonical Publication URL: ${input}`,
+    )
   }
-  return new URL(url.origin)
+  return new URL(publication.PATH, url.origin)
 }

package/src/lib/failure-debug.ts

@@ -0,0 +1,26 @@
+import chalk from 'chalk'
+
+const MAXIMUM_DEBUG_FAILURES = 32
+
+export function printFailureDebug(error: unknown, url: string): void {
+  process.stderr.write(`\n${chalk.dim('── debug ─────────────────')}\n`)
+  if (url) process.stderr.write(`${chalk.dim(`url:   ${url}`)}\n`)
+  const seen = new Set<unknown>()
+  const pending: Array<{ value: unknown; relation: string }> = [{ value: error, relation: 'error' }]
+  while (pending.length > 0 && seen.size < MAXIMUM_DEBUG_FAILURES) {
+    const { value, relation } = pending.shift()!
+    if (seen.has(value)) continue
+    seen.add(value)
+    if (!(value instanceof Error)) {
+      process.stderr.write(`${chalk.dim(`${relation}: ${String(value)}`)}\n`)
+      continue
+    }
+    process.stderr.write(
+      `${chalk.dim(`${relation}: ${value.constructor.name}: ${value.message}`)}\n`,
+    )
+    if (value.stack) process.stderr.write(`${chalk.dim(value.stack)}\n`)
+    if (value.cause !== undefined) pending.push({ value: value.cause, relation: 'caused by' })
+    if (value instanceof AggregateError)
+      for (const child of value.errors) pending.push({ value: child, relation: 'aggregate' })
+  }
+}

package/src/lib/idp.ts

@@ -214,6 +214,8 @@ export type IdpConfig = {
 
 export const BUILTIN_WORKOS_IDP_NAME = 'workos'
 const DEFAULT_WORKOS_API_HOST = 'https://api.workos.com'
+const DEFAULT_WORKOS_CLIENT_ID = 'client_01KC29HET5F3QAQ8GNTPZ7F320'
+const LEGACY_WORKOS_CLIENT_ID = 'client_01KC29HEGD7B40TV2C4QZ436BG'
 const WORKOS_CLIENT_ID_ENV_NAMES = ['WORKOS_CLIENT_ID', 'VITE_WORKOS_CLIENT_ID'] as const
 
 export function idpDir(name: string): string {
@@ -280,7 +282,17 @@ export async function readIdpConfigOrBuiltin(
   validateName(name, 'IdP')
   const store = await readIdpStore()
   if (store.idps[name]) {
-    return await readIdpConfig(name)
+    const existing = await readIdpConfig(name)
+    const replacement = opts.persist
+      ? legacyBuiltinWorkosReplacement(existing, opts.clientId)
+      : undefined
+    if (!replacement) return existing
+    return upsertIdpConfig({
+      name: replacement.name,
+      metadata: replacement.metadata,
+      client: replacement.client,
+      builtIn: true,
+    })
   }
 
   const builtin = builtinIdpConfig(name, opts.clientId)
@@ -413,11 +425,30 @@ export function builtinIdpConfig(
 }
 
 export function workosClientIdFromEnv(env: NodeJS.ProcessEnv = process.env): string | undefined {
-  return WORKOS_CLIENT_ID_ENV_NAMES.map((name) => env[name]?.trim()).find(
-    (value): value is string => typeof value === 'string' && value.length > 0,
+  return (
+    WORKOS_CLIENT_ID_ENV_NAMES.map((name) => env[name]?.trim()).find(
+      (value): value is string => typeof value === 'string' && value.length > 0,
+    ) ?? DEFAULT_WORKOS_CLIENT_ID
   )
 }
 
+export function legacyBuiltinWorkosReplacement(
+  existing: IdpConfig,
+  clientIdOverride?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): IdpConfig | undefined {
+  if (
+    existing.name !== BUILTIN_WORKOS_IDP_NAME ||
+    !existing.entry.builtIn ||
+    existing.client.client_id !== LEGACY_WORKOS_CLIENT_ID
+  ) {
+    return undefined
+  }
+  const replacement = builtinIdpConfig(existing.name, clientIdOverride, env)
+  if (!replacement || replacement.client.client_id === LEGACY_WORKOS_CLIENT_ID) return undefined
+  return replacement
+}
+
 async function fetchOAuthAuthorizationServerMetadata(
   issuer: string,
 ): Promise<Partial<OidcMetadata> | undefined> {

package/src/lib/instance-candidates.ts

@@ -1,6 +1,6 @@
 import type { InstanceEntry, InstanceStore } from './instance'
 
-import { formatInstanceLocation, type OwnedInstanceInfo } from './admin-instance'
+import { formatInstanceState, type OwnedInstanceInfo } from './admin-instance'
 import { normalizeInstanceKernelUrl, resolveInstanceKey } from './instance'
 
 export type InstanceCandidate =
@@ -44,6 +44,6 @@ export function describeInstanceCandidate(candidate: InstanceCandidate): string
   if (candidate.source === 'bookmark') {
     return `${candidate.key} (bookmark) ${candidate.url}`
   }
-  const extra = formatInstanceLocation(candidate.info)
+  const extra = formatInstanceState(candidate.info)
   return `${candidate.key} (managed) ${candidate.url}${extra ? ` — ${extra}` : ''}`
 }

package/src/lib/instance-target.ts

@@ -1,6 +1,6 @@
-import type { InstanceInfo } from '../admin/instance/model'
 import type { AstraleConfig } from './config'
 
+import { AdminInstanceNotFoundError, type InstanceInfo } from '../admin/instance/model'
 import { AstraleError } from '../errors'
 import {
   DEFAULT_ADMIN_TARGET_NAME,
@@ -190,19 +190,8 @@ export function isAdminDiscoveryFailure(error: unknown): boolean {
 }
 
 export function isManagedInstanceNotFound(error: unknown): boolean {
-  if (error instanceof AstraleError && error.code === 'INSTANCE_NOT_FOUND') return true
-  if (!(error instanceof Error)) return false
-  if (error.name === 'NotFoundError') return true
-  // The admin kernel reports a missing instance node as InternalKernelError
-  // with a NOT_FOUND-prefixed message. In this lookup that's an instance
-  // miss (config problem), not a kernel fault — map it so callers get the
-  // typed INSTANCE_NOT_FOUND with remediation instead of a raw kernel error.
-  if (error.name === 'InternalKernelError' && /^NOT_FOUND\b/.test(error.message)) return true
-  const data = (error as Error & { data?: unknown }).data
   return (
-    error.name === 'KernelError' &&
-    !!data &&
-    typeof data === 'object' &&
-    (data as { type?: unknown }).type === 'NotFoundError'
+    error instanceof AdminInstanceNotFoundError ||
+    (error instanceof AstraleError && error.code === 'INSTANCE_NOT_FOUND')
   )
 }

package/src/lib/instance.ts

@@ -297,22 +297,26 @@ export async function upsertInstance(
  * bookmark was repointed to a different kernel so callers can warn.
  */
 export async function upsertManagedBookmark(
-  key: string,
-  slug: string,
-  rawUrl: string,
-  organizationId?: string,
+  input: Readonly<{
+    key: string
+    slug: string
+    url: string
+    organizationId?: string
+    defaultIdentity?: 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, {
+  const previousUrl = store.instances[input.key]?.url
+  const url = normalizeInstanceKernelUrl(input.url)
+  const { entry } = await upsertInstance(input.key, {
     url,
     issuer: url,
-    slug,
-    name: slug,
+    slug: input.slug,
+    name: input.slug,
     kind: 'bookmark',
     mode: 'remote',
-    ...(organizationId ? { organizationId } : {}),
+    ...(input.organizationId ? { organizationId: input.organizationId } : {}),
+    ...(input.defaultIdentity ? { defaultIdentity: input.defaultIdentity } : {}),
   })
   return {
     entry,
@@ -362,8 +366,9 @@ export async function getActive(config?: AstraleConfig): Promise<InstanceEntry &
 export async function resolveInstance(
   identifier: string,
   config?: AstraleConfig,
+  opts: { persist?: boolean } = {},
 ): Promise<ResolvedInstance> {
-  const store = await readInstances(config)
+  const store = await readInstances(config, opts)
   const key = resolveInstanceKey(store, identifier)
   const entry = key ? store.instances[key] : undefined
   if (!key || !entry?.url) {

package/src/lib/log.ts

@@ -2,6 +2,7 @@ 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'
 
@@ -18,28 +19,34 @@ export const log = {
 
 /** 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): never {
+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 Error ? e.message : String(e)
-  const code = e instanceof AstraleError ? e.code : e instanceof Error ? e.name : 'Error'
+  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')
-    process.exit(1)
+  } else {
+    log.error(`${code}: ${msg}`)
+    if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
   }
-  log.error(e instanceof AstraleError ? `${code}: ${msg}` : msg)
-  if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
+  if (opts?.debug) printFailureDebug(e, '')
   process.exit(1)
 }
 
-/** Admit expected invalid input and exit through {@link fatal}. */
-export function failClosed(error: unknown, opts?: MachineOpts): never {
+/** 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 instanceof Error ? error.message : String(error)),
+    new AstraleError(
+      'INVALID_INPUT',
+      error.message.trim() ? error.message : 'CLI input is invalid.',
+    ),
     opts,
   )
 }

package/src/lib/output.ts

@@ -17,7 +17,7 @@ export type RawOutputOpts = Pick<OutputOpts, 'raw' | 'json'>
 export type MachineOpts = RawOutputOpts & { readonly ci?: boolean }
 
 export const RAW_OUTPUT_OPTIONS = [
-  { flags: '--json', description: 'Always-valid JSON (for jq)' },
+  { flags: '--json', description: 'JSON; streaming commands emit one JSON value per line' },
   { flags: '--raw', description: 'Unwrapped: bare scalar / raw bytes / JSON for objects' },
 ] as const
 

package/src/lib/proc.ts

@@ -22,7 +22,11 @@ export function run(
   opts: { cwd?: string } = {},
 ): Promise<RunResult> {
   return new Promise((resolve, reject) => {
-    const child = spawn(file, args, { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    const child = spawn(file, args, {
+      cwd: opts.cwd,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
     let stdout = ''
     let stderr = ''
     child.stdout?.setEncoding('utf8')
@@ -50,7 +54,7 @@ export function runInherit(
   opts: { cwd?: string } = {},
 ): Promise<number> {
   return new Promise((resolve, reject) => {
-    const child = spawn(file, args, { cwd: opts.cwd, stdio: 'inherit' })
+    const child = spawn(file, args, { cwd: opts.cwd, shell: false, stdio: 'inherit' })
     child.on('error', reject)
     child.on('close', (code) => resolve(code ?? -1))
   })
@@ -73,6 +77,7 @@ export function spawnHandle(
   return spawn(file, args, {
     cwd: opts.cwd,
     env: opts.env,
+    shell: false,
     // `detached` makes the child its own process-group leader so the caller can
     // tear down the whole tree (the child AND its grandchildren) with a single
     // group signal — `process.kill(-child.pid, …)`.