@astrale-os/cli 0.8.1-alpha.6 → 0.8.1-alpha.7

package/src/commands/instance/list.ts

@@ -30,6 +30,7 @@ export type Bookmark = {
   issuer: string | null
   active: boolean
   defaultIdentity: string | null
+  caFile: string | null
   createdAt: string | null
 }
 
@@ -57,6 +58,7 @@ export default {
         issuer: entry.issuer ?? null,
         active: name === store.active,
         defaultIdentity: entry.defaultIdentity ?? null,
+        caFile: entry.caFile ?? null,
         createdAt: entry.createdAt ?? null,
       }))
 
@@ -111,13 +113,13 @@ export function buildInstanceRows(
   const rows: Array<Record<string, string>> = []
   const merged = new Set<string>()
 
-  const bookmarkByName = new Map<string, { url: string; active: boolean }>()
+  const bookmarkByName = new Map<string, Bookmark & { url: string }>()
   if (show.managed && show.bookmarks) {
     for (const bookmark of bookmarks) {
       if (bookmark.url === null) continue
       bookmarkByName.set(bookmark.name, {
+        ...bookmark,
         url: normalizeInstanceKernelUrl(bookmark.url),
-        active: bookmark.active,
       })
     }
   }
@@ -134,7 +136,9 @@ export function buildInstanceRows(
         name: twin?.active ? `${item.slug} ${chalk.green('*')}` : item.slug,
         kind: 'managed',
         url: item.url ?? '',
-        extra: formatInstanceLocation(item),
+        extra: [formatInstanceLocation(item), twin ? formatBookmarkConnection(twin) : '']
+          .filter(Boolean)
+          .join(' · '),
       })
     }
   }
@@ -146,7 +150,7 @@ export function buildInstanceRows(
         name: item.active ? `${item.name} ${chalk.green('*')}` : item.name,
         kind: 'bookmark',
         url: String(item.url ?? ''),
-        extra: '',
+        extra: formatBookmarkConnection(item),
       })
     }
   }
@@ -154,6 +158,16 @@ export function buildInstanceRows(
   return rows
 }
 
+function formatBookmarkConnection(bookmark: Bookmark): string {
+  return [
+    bookmark.issuer && bookmark.issuer !== bookmark.url ? `issuer=${bookmark.issuer}` : '',
+    bookmark.caFile ? `ca=${bookmark.caFile}` : '',
+    bookmark.defaultIdentity ? `identity=${bookmark.defaultIdentity}` : '',
+  ]
+    .filter(Boolean)
+    .join(' · ')
+}
+
 const ADMIN_INVENTORY_CODES = new Set([
   'TOKEN_EXCHANGE_SOURCE_INVALID',
   'TOKEN_EXCHANGE_SOURCE_EXPIRED',

package/src/commands/instance/use.ts

@@ -5,7 +5,9 @@ import { AstraleError } from '../../errors'
 import { getDefault, setDefault } from '../../identity/index'
 import { listOwnedInstances } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS } from '../../lib/admin-target'
+import { fetchWithCaFile } from '../../lib/ca-fetch'
 import {
+  findBookmarkTrustConflicts,
   getActive,
   readInstances,
   resolveInstance,
@@ -48,12 +50,8 @@ async function useInstance(name?: string, opts: UseOpts = {}): Promise<void> {
 
     const resolved = await resolveUseTarget(name, opts)
 
-    if (!opts.skipJwksCheck && resolved.issuer) {
-      try {
-        await checkIssuerReachability(resolved.url, resolved.issuer)
-      } catch (e) {
-        fatal(e)
-      }
+    if (!opts.skipJwksCheck) {
+      await probeBookmark(resolved)
     }
 
     await setActive(resolved.name)
@@ -94,6 +92,55 @@ async function useInstance(name?: string, opts: UseOpts = {}): Promise<void> {
   }
 }
 
+/** Probe with the exact TLS trust configuration stored on this bookmark. */
+export async function probeBookmark(
+  resolved: ResolvedInstance,
+  dependencies: Partial<BookmarkProbeDependencies> = {},
+): Promise<void> {
+  const probe = { ...defaultBookmarkProbeDependencies, ...dependencies }
+  const store = await probe.readInstances()
+  const conflicts = findBookmarkTrustConflicts(store, resolved.name, resolved.url, resolved.caFile)
+  try {
+    await probe.checkIssuerReachability(
+      resolved.url,
+      resolved.issuer,
+      resolved.caFile ? probe.fetchWithCaFile(resolved.caFile) : undefined,
+    )
+  } catch (cause) {
+    const original = cause instanceof AstraleError ? cause.hint : undefined
+    const trust = resolved.caFile
+      ? `Bookmark "${resolved.name}" trusts CA ${resolved.caFile}.`
+      : `Bookmark "${resolved.name}" uses the system trust store.`
+    const collision =
+      conflicts.length === 0
+        ? ''
+        : ` The same URL is bookmarked with different TLS trust as ${conflicts
+            .map((conflict) =>
+              conflict.caFile
+                ? `"${conflict.name}" (CA ${conflict.caFile})`
+                : `"${conflict.name}" (system trust)`,
+            )
+            .join(', ')}.`
+    throw new AstraleError(
+      cause instanceof AstraleError ? cause.code : 'ISSUER_UNREACHABLE',
+      `Issuer/JWKS probe failed for bookmark "${resolved.name}" at ${resolved.url}.`,
+      `${trust}${collision}${original ? ` ${original}` : ''} Inspect with \`astrale instance list --bookmarked --json\`.`,
+    )
+  }
+}
+
+interface BookmarkProbeDependencies {
+  readonly readInstances: typeof readInstances
+  readonly checkIssuerReachability: typeof checkIssuerReachability
+  readonly fetchWithCaFile: typeof fetchWithCaFile
+}
+
+const defaultBookmarkProbeDependencies: BookmarkProbeDependencies = Object.freeze({
+  readInstances,
+  checkIssuerReachability,
+  fetchWithCaFile,
+})
+
 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)
@@ -204,7 +251,7 @@ Examples:
       flags: '--adopt-default',
       description: 'Adopt instance default identity without prompt',
     },
-    { flags: '--skip-jwks-check', description: 'Skip the /meta ↔ JWKS match check' },
+    { flags: '--skip-jwks-check', description: 'Skip the OIDC discovery + JWKS liveness probe' },
   ],
   action: async (name: string | undefined, opts: UseOpts) => {
     await useInstance(name, opts)

package/src/commands/view.ts

@@ -172,22 +172,34 @@ async function findOnPath(name: string): Promise<string | null> {
 
 /** Dev checkout: (re)build the node-runnable CLI bundle when missing or stale. */
 async function ensureDevDist(entry: string, dist: string): Promise<void> {
-  const bun = (
-    globalThis as {
-      Bun?: { build: (o: object) => Promise<{ success: boolean; logs: unknown[] }> }
-    }
-  ).Bun
-  if (!bun) return
-  const srcDir = join(dirname(entry), '..', 'src')
-  if (existsSync(dist) && !(await newerThan(srcDir, statSync(dist).mtimeMs))) return
-  // stderr: --json consumers parse stdout.
-  console.error('(dev) building dist/astrale.js for the session server…')
-  await bun.build({
-    entrypoints: [entry],
-    outdir: dirname(dist),
-    target: 'node',
-    format: 'esm',
-  })
+  if (!(await devDistIsStale(entry, dist))) return
+  const projectDir = join(dirname(entry), '..')
+  const buildScript = join(projectDir, 'scripts', 'build.ts')
+  const bun = await findOnPath('bun')
+  if (!bun || !existsSync(buildScript)) return
+
+  // Build output goes to stderr so --json stdout remains valid.
+  console.error('(dev) dist/astrale.js is stale — running the official CLI build…')
+  const built = await run(bun, [buildScript], { cwd: projectDir })
+  if (built.stdout) process.stderr.write(built.stdout)
+  if (built.stderr) process.stderr.write(built.stderr)
+  if (built.code !== 0) throw new Error(`Official CLI build failed with exit code ${built.code}.`)
+}
+
+export async function devDistIsStale(entry: string, dist: string): Promise<boolean> {
+  if (!existsSync(dist)) return true
+  const projectDir = join(dirname(entry), '..')
+  const builtAt = statSync(dist).mtimeMs
+  const directories = [join(projectDir, 'src'), join(projectDir, 'bin'), join(projectDir, 'vendor')]
+  const files = [
+    join(projectDir, 'scripts', 'build.ts'),
+    join(projectDir, 'package.json'),
+    join(projectDir, 'pnpm-lock.yaml'),
+  ]
+  for (const directory of directories) {
+    if (existsSync(directory) && (await newerThan(directory, builtAt))) return true
+  }
+  return files.some((file) => existsSync(file) && statSync(file).mtimeMs > builtAt)
 }
 
 async function newerThan(dir: string, mtimeMs: number): Promise<boolean> {

package/src/connection/.spec/architecture.md

@@ -39,3 +39,8 @@ The target, timeout, and optional CA file are resolved before constructing the s
 customizes only the Fetch capability passed to Client. `withClientSession` and
 `withAdminClientSession` are terminal lifecycle boundaries: success, failure, and cancellation all
 close both the Client Session and its direct source-Auth client.
+
+The command boundary maps typed Client transport phase and delivery evidence without inspecting a
+private cause message. It preserves every admitted Kernel reason in machine output; human repair
+details are rendered only after the connection owner admits bounded public Function issues or one
+exact Query reason variant.

package/src/connection/.spec/laws/connection.ts

@@ -179,3 +179,23 @@ export const CLI_CONNECTION_PUBLIC_SEMANTIC_REASON = defineLaw({
     },
   ],
 })
+
+export const CLI_CONNECTION_TYPED_ERROR_PRESENTATION = defineLaw({
+  id: 'CLI-CONNECTION-TYPED-ERROR-PRESENTATION',
+  statement:
+    'The command boundary maps typed Client transport phase and delivery evidence without parsing a private cause, preserves the admitted Kernel reason in machine output, and renders only bounded public Function issues or one exact Query repair variant for humans.',
+  tests: [
+    {
+      file: '__tests__/errors.test.ts',
+      id: 'TEST-CLI-CONNECTION-MAPS-TYPED-TRANSPORT',
+    },
+    {
+      file: '__tests__/errors.test.ts',
+      id: 'TEST-CLI-CONNECTION-PRESENTS-BOUNDED-REPAIRS',
+    },
+    {
+      file: '__tests__/reasons.test.ts',
+      id: 'TEST-CLI-CONNECTION-ADMITS-BOUNDED-REASONS',
+    },
+  ],
+})

package/src/connection/.spec/layout.ts

@@ -10,6 +10,7 @@ export default defineLayout({
     'errors.ts',
     'exchange.ts',
     'index.ts',
+    'reasons.ts',
     'self.ts',
     'session.ts',
     'target.ts',

package/src/connection/__tests__/auth.test.ts

@@ -3,7 +3,9 @@ import { describe, expect, test } from 'bun:test'
 import type { Identity } from '../../identity/index'
 import type { AstraleConfig } from '../../lib/config'
 
-import { resolveKeyIdentityAuthOptions } from '../auth'
+import { IdpAudienceMismatchError } from '../../lib/idp'
+import { IdpSessionNoRefreshTokenError } from '../../lib/idp-session'
+import { classifyNoRefreshTokenError, resolveKeyIdentityAuthOptions } from '../auth'
 
 const config: AstraleConfig = {
   issuer: 'https://unregistered.invalid',
@@ -100,3 +102,27 @@ describe('resolveKeyIdentityAuthOptions', () => {
     })
   })
 })
+
+describe('classifyNoRefreshTokenError', () => {
+  test('preserves expiry when the non-refreshable session already targets the required audience', () => {
+    const expired = new IdpSessionNoRefreshTokenError('alice')
+
+    expect(
+      classifyNoRefreshTokenError('https://kernel.example', 'https://kernel.example', expired),
+    ).toBe(expired)
+  })
+
+  test('reports a real audience mismatch when the source audience differs', () => {
+    const result = classifyNoRefreshTokenError(
+      'https://child.example',
+      'https://manager.example',
+      new IdpSessionNoRefreshTokenError('alice'),
+    )
+
+    expect(result).toBeInstanceOf(IdpAudienceMismatchError)
+    expect(result).toMatchObject({
+      requested: 'https://child.example',
+      actual: 'https://manager.example',
+    })
+  })
+})

package/src/connection/__tests__/ca-fetch.test.ts

@@ -29,7 +29,10 @@ describe('connection CA fetch', () => {
       hostname: '127.0.0.1',
       port: 0,
       tls: { cert: certificate, key },
-      fetch: () => new Response('trusted'),
+      fetch: (request) =>
+        new URL(request.url).pathname === '/cached'
+          ? new Response(null, { status: 304, headers: { etag: 'retained' } })
+          : new Response('trusted'),
     })
 
     const requests: Array<{ input: RequestInfo | URL; init?: RequestInit }> = []
@@ -45,6 +48,10 @@ describe('connection CA fetch', () => {
     expect(await httpsResponse.text()).toBe('trusted')
     expect(httpsResponse.url).toBe(httpsUrl)
     expect(httpsResponse.redirected).toBe(false)
+    const cachedResponse = await scoped(`https://127.0.0.1:${server.port}/cached`)
+    expect(cachedResponse.status).toBe(304)
+    expect(cachedResponse.body).toBeNull()
+    expect(cachedResponse.headers.get('etag')).toBe('retained')
     await expect(
       scoped('http://localhost:8080/invoke', init).then((value) => value.text()),
     ).resolves.toBe('fallback')