@astrale-os/cli 1.0.0-beta.4 → 1.0.0-beta.6

package/src/lib/__tests__/instance-target.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from 'bun:test'
 import type { AstraleConfig } from '../config'
 import type { InstanceStore } from '../instance'
 
+import { AdminInstanceNotFoundError } from '../../admin/instance/model'
 import { AstraleError } from '../../errors'
 import { DEFAULT_CONFIG } from '../config'
 import {
@@ -124,9 +125,6 @@ describe('resolveInstanceTarget', () => {
   })
 
   test('unknown slugs surface the original instance-not-found error', async () => {
-    const notFound = new Error('Path not found: "/admin/instances/missing"')
-    notFound.name = 'NotFoundError'
-
     await expect(
       resolveInstanceTarget(
         { source: 'name', name: 'missing' },
@@ -134,7 +132,7 @@ describe('resolveInstanceTarget', () => {
           config: DEFAULT_CONFIG,
           instances: emptyStore,
           managed: async () => {
-            throw notFound
+            throw new AdminInstanceNotFoundError('missing')
           },
         },
       ),
@@ -168,14 +166,8 @@ describe('instance target helpers', () => {
     expect(couldBeConfiguredAdminInstance('bryan', directAdminConfig)).toBe(false)
   })
 
-  test('treats wrapped remote Instance.info misses as managed lookup not-found', () => {
-    const wrapped = new Error('Path not found: "/admin/instances/admin"') as Error & {
-      data?: unknown
-    }
-    wrapped.name = 'KernelError'
-    wrapped.data = { type: 'NotFoundError' }
-
-    expect(isManagedInstanceNotFound(wrapped)).toBe(true)
+  test('treats the owner-scoped Admin error as managed lookup not-found', () => {
+    expect(isManagedInstanceNotFound(new AdminInstanceNotFoundError('admin'))).toBe(true)
   })
 
   test('does not hide non-not-found managed lookup failures', () => {
@@ -194,37 +186,12 @@ describe('instance target helpers', () => {
   })
 })
 
-describe('isManagedInstanceNotFound: kernel InternalKernelError wrap', () => {
-  test('NOT_FOUND-prefixed InternalKernelError is an instance miss', () => {
-    const e = new Error('NOT_FOUND: no instance node for "knowledge"')
-    e.name = 'InternalKernelError'
-    expect(isManagedInstanceNotFound(e)).toBe(true)
-  })
-  test('other InternalKernelError messages are not swallowed', () => {
+describe('isManagedInstanceNotFound: unknown errors', () => {
+  test('does not infer a miss from an InternalKernelError message', () => {
     const e = new Error('DISPATCH_FAILED: handler crashed')
     e.name = 'InternalKernelError'
     expect(isManagedInstanceNotFound(e)).toBe(false)
   })
-  test('resolveNamedInstanceTarget maps the wrap to typed INSTANCE_NOT_FOUND', async () => {
-    const managed = async () => {
-      const e = new Error('NOT_FOUND: no instance node for "ghost"')
-      e.name = 'InternalKernelError'
-      throw e
-    }
-    const opts = {
-      config: DEFAULT_CONFIG,
-      instances: { instances: {} },
-      managed,
-    } as unknown as Parameters<typeof resolveInstanceTarget>[1]
-    let caught: unknown
-    try {
-      await resolveInstanceTarget({ source: 'name', name: 'ghost' }, opts)
-    } catch (e) {
-      caught = e
-    }
-    expect(caught).toBeInstanceOf(AstraleError)
-    expect((caught as AstraleError).code).toBe('INSTANCE_NOT_FOUND')
-  })
 
   test('maps Admin token-exchange failure to INSTANCE_NOT_FOUND', async () => {
     const managed = async () => {

package/src/lib/__tests__/log-errors.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+
+import { AstraleError } from '../../errors'
+import { failInput, fatal } from '../log'
+
+class ExitError extends Error {}
+
+let stderr = ''
+let exit: typeof process.exit
+let write: typeof process.stderr.write
+
+beforeEach(() => {
+  stderr = ''
+  exit = process.exit
+  write = process.stderr.write
+  process.exit = (() => {
+    throw new ExitError()
+  }) as typeof process.exit
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderr += String(chunk)
+    return true
+  }) as typeof process.stderr.write
+})
+
+afterEach(() => {
+  process.exit = exit
+  process.stderr.write = write
+})
+
+describe('terminal error safety', () => {
+  test('renders an empty aggregate as an honest non-blank unexpected failure', () => {
+    expect(() => fatal(new AggregateError([], ''), { json: true })).toThrow(ExitError)
+    expect(JSON.parse(stderr)).toEqual({
+      error: 'UNEXPECTED_ERROR',
+      message: 'The CLI encountered an unexpected internal failure.',
+    })
+  })
+
+  test('rejects blank admitted CLI diagnostics', () => {
+    expect(() => new AstraleError('INVALID_INPUT', '  ')).toThrow(TypeError)
+  })
+
+  test('labels only expected admission failures as invalid input', () => {
+    expect(() => failInput(new TypeError('Authored value is invalid.'), { json: true })).toThrow(
+      ExitError,
+    )
+    expect(JSON.parse(stderr)).toMatchObject({ error: 'INVALID_INPUT' })
+
+    stderr = ''
+    expect(() => failInput(new AggregateError([], ''), { json: true })).toThrow(ExitError)
+    expect(JSON.parse(stderr)).toMatchObject({ error: 'UNEXPECTED_ERROR' })
+  })
+})

package/src/lib/__tests__/studio-server-deps.test.ts

@@ -103,7 +103,7 @@ describe('studio server runtime deps', () => {
 describe('studio test gate', () => {
   test('the root and Studio suites include all client, server, and shared tests', () => {
     expect(cliPackage.scripts?.test).toBe(
-      'bun test src studio/client/src studio/server studio/shared && node --test scripts/*.test.mjs',
+      'node scripts/qualification/source-boundary.mjs --target && bun test src studio/client/src studio/server studio/shared && node --test scripts/*.test.mjs',
     )
     expect(cliPackage.scripts?.['test:studio']).toBe('pnpm --dir studio test')
     expect(studioPackage.scripts?.test).toBe('bun test client/src server shared')

package/src/lib/__tests__/update.test.ts

@@ -1,16 +1,20 @@
 import { describe, expect, test } from 'bun:test'
-import { chmod, mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises'
+import { chmod, mkdir, mkdtemp, readFile, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
 import {
+  admitScriptInstall,
+  classifyUpdateExecution,
   DEFAULT_UPDATE_CHANNEL,
   InstallMetadataSchema,
+  readInstallMetadata,
   releaseBase,
   shouldUpdate,
   updateAstrale,
   writeInstallMetadata,
   type InstallMetadata,
+  type UpdateExecution,
 } from '../update'
 
 async function makeFakeRelease(
@@ -65,7 +69,7 @@ async function makeFakeRelease(
 async function makeInstall(
   root: string,
   version: string,
-): Promise<{ meta: InstallMetadata; path: string }> {
+): Promise<{ meta: InstallMetadata; path: string; execution: UpdateExecution }> {
   const bin = join(root, 'bin', 'astrale')
   await mkdir(join(root, 'bin'), { recursive: true })
   await writeFile(
@@ -82,10 +86,33 @@ async function makeInstall(
     bin,
   }
   await writeInstallMetadata(meta, path)
-  return { meta, path }
+  return { meta, path, execution: { kind: 'standalone', executable: bin } }
 }
 
 describe('update helpers', () => {
+  test('classifies only a Bun-compiled executable as standalone', () => {
+    expect(
+      classifyUpdateExecution({
+        bunVersion: '1.3.14',
+        executable: '/tmp/astrale',
+        entry: '/$bunfs/root/astrale',
+      }),
+    ).toEqual({ kind: 'standalone', executable: '/tmp/astrale' })
+    expect(
+      classifyUpdateExecution({
+        bunVersion: '1.3.14',
+        executable: '/opt/homebrew/bin/bun',
+        entry: '/tmp/astrale.ts',
+      }),
+    ).toEqual({ kind: 'package-managed', executable: '/opt/homebrew/bin/bun' })
+    expect(
+      classifyUpdateExecution({
+        executable: '/opt/homebrew/bin/node',
+        entry: '/tmp/astrale.js',
+      }),
+    ).toEqual({ kind: 'package-managed', executable: '/opt/homebrew/bin/node' })
+  })
+
   test('defaults missing install metadata to the beta channel', () => {
     expect(DEFAULT_UPDATE_CHANNEL).toBe('beta')
     expect(
@@ -118,10 +145,70 @@ describe('update helpers', () => {
   })
 })
 
+describe('script install admission', () => {
+  test('rejects malformed JSON with the stable metadata error', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const path = join(root, 'install.json')
+    await writeFile(path, '{')
+
+    await expect(readInstallMetadata(path)).rejects.toMatchObject({
+      code: 'UPDATE_BAD_INSTALL_METADATA',
+    })
+  })
+
+  test('admits a symlink only when it resolves to the recorded binary', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { meta } = await makeInstall(root, '1.0.0')
+    const alias = join(root, 'astrale-alias')
+    await symlink(meta.bin, alias)
+
+    const admitted = await admitScriptInstall(meta, {
+      kind: 'standalone',
+      executable: alias,
+    })
+
+    expect(admitted.metadata).toEqual(meta)
+  })
+
+  test('rejects a standalone binary that does not own the recorded target', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { meta } = await makeInstall(root, '1.0.0')
+    const other = join(root, 'other-astrale')
+    await writeFile(other, '#!/bin/sh\n')
+
+    await expect(
+      admitScriptInstall(meta, { kind: 'standalone', executable: other }),
+    ).rejects.toMatchObject({ code: 'UPDATE_INSTALL_MISMATCH' })
+  })
+})
+
 describe('updateAstrale', () => {
+  test('a package-managed process never consults or mutates a coexisting script install', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { path, meta } = await makeInstall(root, '1.0.0')
+    const before = await readFile(meta.bin, 'utf8')
+    process.env.ASTRALE_UPDATE_BASE = 'file:///definitely-not-a-release'
+    try {
+      const result = await updateAstrale({
+        currentVersion: '2.0.0',
+        installPath: path,
+        execution: { kind: 'package-managed', executable: '/opt/homebrew/bin/node' },
+      })
+
+      expect(result).toEqual({
+        status: 'managed',
+        currentVersion: '2.0.0',
+        executable: '/opt/homebrew/bin/node',
+      })
+      expect(await readFile(meta.bin, 'utf8')).toBe(before)
+    } finally {
+      delete process.env.ASTRALE_UPDATE_BASE
+    }
+  })
+
   test('check compares the installed release identity from metadata', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path } = await makeInstall(root, 'main-abc123')
+    const { path, execution } = await makeInstall(root, 'main-abc123')
     const release = await makeFakeRelease(root, 'main-abc123', { binaryVersion: '1.0.0' })
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -130,6 +217,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -144,7 +232,7 @@ describe('updateAstrale', () => {
 
   test('check reports available update without replacing the binary', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path, meta } = await makeInstall(root, '1.0.0')
+    const { path, meta, execution } = await makeInstall(root, '1.0.0')
     const release = await makeFakeRelease(root, '1.1.0')
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -153,6 +241,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -168,7 +257,7 @@ describe('updateAstrale', () => {
 
   test('supports legacy string asset manifests', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path, meta } = await makeInstall(root, '1.0.0')
+    const { path, meta, execution } = await makeInstall(root, '1.0.0')
     const release = await makeFakeRelease(root, '1.1.0', { legacyManifest: true })
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -177,6 +266,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(check).toMatchObject({
@@ -188,6 +278,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -204,7 +295,7 @@ describe('updateAstrale', () => {
 
   test('updates the binary and install metadata', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path, meta } = await makeInstall(root, '1.0.0')
+    const { path, meta, execution } = await makeInstall(root, '1.0.0')
     const release = await makeFakeRelease(root, '1.1.0')
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -212,6 +303,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -231,7 +323,7 @@ describe('updateAstrale', () => {
 
   test('updates canary-style releases whose binary reports the package version', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path, meta } = await makeInstall(root, 'main-old123')
+    const { path, meta, execution } = await makeInstall(root, 'main-old123')
     const release = await makeFakeRelease(root, 'main-new456', { binaryVersion: '1.0.0' })
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -239,6 +331,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({

package/src/lib/__tests__/view-open-intent.test.ts

@@ -23,7 +23,6 @@ const profile: ResolvedView = {
         kind: 'definition',
         definitions: [{ origin: 'shell.test', kind: 'class', name: 'Person' }],
       },
-      auth: 'required',
     },
     href: 'https://shell.test/profile',
     handshake: 'shell',
@@ -41,7 +40,6 @@ const card: ResolvedView = {
         kind: 'definition',
         definitions: [{ origin: 'shell.test', kind: 'class', name: 'Person' }],
       },
-      auth: 'public',
     },
     href: 'https://shell.test/card',
     handshake: 'none',

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

@@ -29,7 +29,7 @@ describe('view session server credentials', () => {
           target: target('/:example.test'),
           route: {
             key: 'example.test:view.public',
-            declaration: { target: { kind: 'domain' }, auth: 'required' },
+            declaration: { target: { kind: 'domain' } },
             href: 'https://example.test/ui/public',
             handshake: 'none',
             issuer: issuer('https://example.test'),

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',

package/src/lib/command-dx.ts

@@ -41,12 +41,9 @@ export function renderCommanderError(
 
   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}`,

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>

package/src/lib/idp.ts

@@ -215,6 +215,7 @@ 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 {
@@ -281,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)
@@ -421,6 +432,23 @@ export function workosClientIdFromEnv(env: NodeJS.ProcessEnv = process.env): str
   )
 }
 
+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-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/log.ts

@@ -22,24 +22,29 @@ export function fatal(e: unknown, opts?: MachineOpts): 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)
   }
-  log.error(e instanceof AstraleError ? `${code}: ${msg}` : msg)
+  log.error(`${code}: ${msg}`)
   if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
   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,
   )
 }