@astrale-os/cli 0.8.1-alpha.6 → 1.0.0-beta.0

package/dist/types/connection/auth.d.ts

@@ -1,5 +1,7 @@
 import type { AstraleConfig } from '../lib/config';
 import { type Identity } from '../identity/registry';
+import { IdpAudienceMismatchError } from '../lib/idp';
+import { IdpSessionNoRefreshTokenError } from '../lib/idp-session';
 export type KeyIdentityAuthOptions = {
     issuer: string;
     subject?: string;
@@ -23,6 +25,7 @@ export declare function resolveCredential(opts: {
     defaultIdentity?: string;
 }, config: AstraleConfig, audience?: string, registrationKey?: string): Promise<string>;
 export declare function resolveKeyIdentityAuthOptions(identity: Identity, config: AstraleConfig, audience?: string, registrationKey?: string): KeyIdentityAuthOptions;
+export declare function classifyNoRefreshTokenError(requestedAudience: string, sourceAudience: string | undefined, error: IdpSessionNoRefreshTokenError): IdpSessionNoRefreshTokenError | IdpAudienceMismatchError;
 /** A refresh attempt failed for a reason that re-login will NOT fix. */
 export declare class IdpRefreshTransientError extends Error {
     constructor(message: string);

package/dist/types/lib/instance.d.ts

@@ -136,6 +136,10 @@ export type ResolvedInstance = {
     mode?: RegistryMode;
     status?: string;
 };
+export type BookmarkTrustConflict = {
+    readonly name: string;
+    readonly caFile: string | null;
+};
 export declare function sanitizeStore(store: InstanceStore): {
     store: InstanceStore;
     changed: boolean;
@@ -152,6 +156,12 @@ export declare function readInstances(_config?: AstraleConfig, opts?: {
 export declare function writeInstances(store: InstanceStore): Promise<void>;
 export declare function assertNoCollision(store: InstanceStore, identifiers: string[], ignoreKey?: string): void;
 export declare function resolveInstanceKey(store: InstanceStore, identifier: string): string | null;
+/**
+ * Find other bookmarks for the same normalized Kernel URL whose TLS trust
+ * configuration differs. System trust (`undefined`) is a configuration too:
+ * mixing it with a custom CA is exactly as significant as mixing two CA files.
+ */
+export declare function findBookmarkTrustConflicts(store: InstanceStore, name: string, url: string, caFile?: string): BookmarkTrustConflict[];
 export declare function addInstance(key: string, opts?: AddInstanceOpts): Promise<InstanceEntry>;
 export declare function upsertInstance(key: string, opts?: AddInstanceOpts): Promise<{
     entry: InstanceEntry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.8.1-alpha.6",
+  "version": "1.0.0-beta.0",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -62,10 +62,10 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
-    "@astrale-os/kernel-client": "0.6.0-beta.1",
+    "@astrale-os/kernel-client": ">=0.6.0-beta.3 <1.0.0",
     "@astrale-os/ox": ">=0.1.0 <1.0.0",
-    "@astrale-os/sdk": "0.5.0-beta.1",
-    "@astrale-os/shell": "0.3.8-beta.1",
+    "@astrale-os/sdk": ">=0.5.0-beta.3 <1.0.0",
+    "@astrale-os/shell": ">=0.3.8-beta.2 <1.0.0",
     "@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.1",
     "@commitlint/cli": "~20.3.1",
     "@commitlint/config-conventional": "~20.3.1",
@@ -82,16 +82,16 @@
   "lint-staged": {
     "*.{js,cjs,mjs,ts,tsx}": [
       "oxlint --fix --no-error-on-unmatched-pattern",
-      "oxfmt --write"
+      "oxfmt --write --no-error-on-unmatched-pattern"
     ],
     "*.{json,yml,yaml}": [
-      "oxfmt --write"
+      "oxfmt --write --no-error-on-unmatched-pattern"
     ]
   },
   "devEngines": {
     "runtime": {
       "name": "node",
-      "version": ">=24 <25",
+      "version": ">=24 <25 || >=26 <27",
       "onFail": "error"
     }
   },
@@ -101,13 +101,13 @@
   "scripts": {
     "preinstall": "node .check-workspace.cjs",
     "build": "bun scripts/build.ts",
-    "package:check": "pnpm run typecheck && pnpm run test && pnpm run build && node scripts/verify-public-exports.mjs",
+    "package:check": "pnpm run typecheck && pnpm run test && pnpm run build && node scripts/verify-public-exports.mjs && node scripts/verify-private-ports-boundary.mjs",
     "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.tests.json && tsgo --noEmit -p viewer && tsgo --noEmit -p studio",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "format": "pnpm exec oxfmt --write .",
     "format:check": "pnpm exec oxfmt --check .",
-    "test": "bun test src",
+    "test": "bun test src && node --test scripts/*.test.mjs",
     "test:watch": "bun test --watch src"
   }
 }

package/src/commands/__tests__/domain-install-operation.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test'
+
+import { installDirect } from '../domain/install'
+
+const GENERATED = '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8'
+const RETRY = '139137b5-af47-47ce-92b2-b64a2b0c63d7'
+
+const originalFetch = globalThis.fetch
+
+class ExitError extends Error {}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+describe('direct domain install operation identity', () => {
+  test('generates one operation before transport and exposes it for recovery', async () => {
+    globalThis.fetch = mock(async () =>
+      Response.json({ domainName: 'crm.test' }),
+    ) as unknown as typeof fetch
+    const create = mock(() => GENERATED)
+    const requests: unknown[] = []
+    let recovery: unknown
+
+    await installDirect(
+      'https://crm.test',
+      { direct: true, json: true },
+      {
+        createOperationId: create,
+        runKernelCommand: async (input) => {
+          recovery = input.recovery
+          requests.push(
+            await input.fn({
+              session: {
+                call: async (call: { input: unknown }) => call.input,
+              },
+            } as never),
+          )
+        },
+      },
+    )
+
+    expect(create).toHaveBeenCalledTimes(1)
+    expect(requests).toEqual([
+      {
+        operation: GENERATED,
+        domains: [{ source: { kind: 'remote', url: 'https://crm.test' } }],
+      },
+    ])
+    expect(recovery).toEqual({
+      operation: GENERATED,
+      retry: `astrale domain install https://crm.test --direct --operation ${GENERATED}`,
+    })
+  })
+
+  test('accepts an explicit operation only as the exact retry identity', async () => {
+    globalThis.fetch = mock(async () =>
+      Response.json({ domainName: 'crm.test' }),
+    ) as unknown as typeof fetch
+    const create = mock(() => GENERATED)
+    const accepted: string[] = []
+    const requests: unknown[] = []
+
+    await installDirect(
+      'https://crm.test',
+      { direct: true, operation: RETRY, json: true },
+      {
+        createOperationId: create,
+        acceptOperationId: (input) => {
+          accepted.push(String(input))
+          return RETRY
+        },
+        runKernelCommand: async (input) => {
+          requests.push(
+            await input.fn({
+              session: {
+                call: async (call: { input: unknown }) => call.input,
+              },
+            } as never),
+          )
+        },
+      },
+    )
+
+    expect(create).not.toHaveBeenCalled()
+    expect(accepted).toEqual([RETRY])
+    expect(requests).toEqual([
+      {
+        operation: RETRY,
+        domains: [{ source: { kind: 'remote', url: 'https://crm.test' } }],
+      },
+    ])
+  })
+
+  test('rejects a non-UUID operation before metadata or Kernel transport', async () => {
+    const originalExit = process.exit
+    const originalWrite = process.stderr.write
+    const fetch = mock(async () => Response.json({ domainName: 'crm.test' }))
+    const run = mock(async () => undefined)
+    globalThis.fetch = fetch as unknown as typeof globalThis.fetch
+    process.exit = (() => {
+      throw new ExitError('exit')
+    }) as typeof process.exit
+    process.stderr.write = (() => true) as typeof process.stderr.write
+    try {
+      await expect(
+        installDirect(
+          'https://crm.test',
+          { direct: true, operation: 'guessable-operation', json: true },
+          { runKernelCommand: run },
+        ),
+      ).rejects.toBeInstanceOf(ExitError)
+    } finally {
+      process.exit = originalExit
+      process.stderr.write = originalWrite
+    }
+
+    expect(fetch).not.toHaveBeenCalled()
+    expect(run).not.toHaveBeenCalled()
+  })
+})

package/src/commands/__tests__/domain-install-owned.test.ts

@@ -1,3 +1,4 @@
+import { ResponseError } from '@astrale-os/kernel-client'
 import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
 
 import type { OwnedInstanceInfo } from '../../lib/admin-instance'
@@ -118,4 +119,69 @@ describe('admin domain install owner boundary', () => {
     expect(calls).toEqual([])
     expect(calls).toEqual([])
   })
+
+  test('preserves an incompatible issuer reason returned through Admin', async () => {
+    inventory = [
+      {
+        id: 'owned-id',
+        slug: 'owned',
+        url: 'https://owned.eu.astrale.ai',
+        state: 'ready',
+      },
+    ]
+    const domain = {
+      id: 'crm-id',
+      origin: 'crm.acme.dev',
+      name: 'CRM',
+      url: 'https://crm.acme.dev',
+      createdAt: '2026-08-20T00:00:00.000Z',
+      updatedAt: '2026-08-20T00:00:00.000Z',
+    }
+    const failure = new ResponseError(5001, 'Schema operation is not supported.', {
+      code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+      details: {
+        phase: 'upgrade',
+        origin: domain.origin,
+        issue: 'issuer-changed',
+        installedIssuer: 'https://old.example',
+        replacementIssuer: 'https://new.example',
+      },
+    })
+    const { installViaAdmin } = await import('../domain/install')
+
+    await expect(
+      installViaAdmin(
+        domain.origin,
+        {
+          instance: 'owned',
+          json: true,
+          noPrompt: true,
+        },
+        {
+          listInstances: async () => inventory,
+          listDomains: async () => [domain],
+          install: async () => {
+            throw failure
+          },
+        },
+      ),
+    ).rejects.toEqual(new ExitError(1))
+
+    expect(JSON.parse(stderr)).toEqual({
+      error: 'RESPONSE_ERROR',
+      code: 5001,
+      message: 'Schema operation is not supported.',
+      reason: {
+        code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+        details: {
+          phase: 'upgrade',
+          origin: 'crm.acme.dev',
+          issue: 'issuer-changed',
+          installedIssuer: 'https://old.example',
+          replacementIssuer: 'https://new.example',
+        },
+      },
+      hint: expect.stringContaining('astrale domain uninstall crm.acme.dev'),
+    })
+  })
 })

package/src/commands/__tests__/domain-uninstall.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test'
+import { join } from 'node:path'
+
+import { uninstallCallInput } from '../domain/uninstall'
+
+const cliRoot = join(import.meta.dir, '../../..')
+
+describe('domain uninstall', () => {
+  test('sends the public Kernel uninstall request', () => {
+    expect(uninstallCallInput('grc.example', 'op-1')).toEqual({
+      operation: 'op-1',
+      origin: 'grc.example',
+    })
+  })
+
+  test('requires --yes outside a TTY before connecting to a Kernel', async () => {
+    const proc = Bun.spawn({
+      cmd: ['bun', join(cliRoot, 'bin/astrale.ts'), 'domain', 'uninstall', 'grc.example', '--json'],
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+
+    expect(exitCode).toBe(1)
+    expect(stdout).toBe('')
+    expect(JSON.parse(stderr)).toMatchObject({
+      error: 'CONFIRMATION_REQUIRED',
+      message: 'Uninstalling Domain "grc.example" requires explicit confirmation.',
+    })
+  })
+
+  test('states that uninstall never deletes business data', async () => {
+    const proc = Bun.spawn({
+      cmd: ['bun', join(cliRoot, 'bin/astrale.ts'), 'domain', 'uninstall', '--help'],
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+
+    expect(exitCode).toBe(0)
+    expect(stderr).toBe('')
+    expect(stdout).toContain('Uninstall never deletes business data.')
+    expect(stdout).toContain('business data still uses its schema')
+  })
+})

package/src/commands/__tests__/install-direct.test.ts

@@ -4,8 +4,9 @@ import { directInstallCallInput } from '../domain/install'
 
 describe('directInstallCallInput', () => {
   test('sends the current remote install syscall, not a legacy url list', () => {
-    expect(directInstallCallInput('https://tasks.example.test', 'secret', 'op-1')).toEqual({
-      operation: 'op-1',
+    const operation = '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8'
+    expect(directInstallCallInput('https://tasks.example.test', operation, 'secret')).toEqual({
+      operation,
       domains: [
         {
           source: {

package/src/commands/__tests__/install-identity-override.test.ts

@@ -41,16 +41,27 @@ describe('declared-origin probe (/meta)', () => {
     return `http://localhost:${server.port}`
   }
 
-  test('reads domainName from a well-formed /meta', async () => {
+  test('reads origin from a well-formed /meta', async () => {
+    // The exact shape SDK workers serve (adapter-cloudflare worker `/meta`).
     const url = serveMeta((req) =>
       new URL(req.url).pathname === '/meta'
-        ? Response.json({ iss: 'https://x', domainName: 'crm.acme.dev' })
+        ? Response.json({
+            origin: 'crm.acme.dev',
+            issuer: 'https://crm.acme.dev',
+            schemaRevision: 'sha256:abc',
+            deploymentVersion: 'v1',
+          })
         : new Response('nope', { status: 404 }),
     )
     expect(await probeDeclaredOrigin(url)).toBe('crm.acme.dev')
   })
 
-  test('degrades to undefined on missing domainName, non-200, bad JSON, or dead host', async () => {
+  test('falls back to the pre-Kernel-V2 domainName field', async () => {
+    const legacy = serveMeta(() => Response.json({ iss: 'https://x', domainName: 'crm.acme.dev' }))
+    expect(await probeDeclaredOrigin(legacy)).toBe('crm.acme.dev')
+  })
+
+  test('degrades to undefined on missing origin, non-200, bad JSON, or dead host', async () => {
     const noName = serveMeta(() => Response.json({ iss: 'https://x' }))
     expect(await probeDeclaredOrigin(noName)).toBeUndefined()
 

package/src/commands/__tests__/instance-bookmark.test.ts

@@ -72,6 +72,63 @@ describe('instance bookmark command', () => {
     expect(store.instances.testmarc.caFile).toBe('/tmp/ca.pem')
     expect(store.instances.testmarc.createdAt).toBe('2026-06-10T00:00:00.000Z')
   })
+
+  test('warns when another bookmark uses different TLS trust for the same URL', async () => {
+    await writeFile(
+      join(tmp, 'instances.json'),
+      JSON.stringify({
+        active: 'stable',
+        instances: {
+          stable: {
+            url: 'https://local.example/kernel',
+            caFile: '/certs/stable.pem',
+          },
+        },
+      }),
+    )
+
+    const result = await runBookmark(
+      'stale',
+      '--url',
+      'https://local.example/kernel/',
+      '--ca',
+      '/certs/old.pem',
+      '--skip-probe',
+    )
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stderr).toContain('TLS trust differs for the same Kernel URL')
+    expect(result.stderr).toContain('"stable" uses CA /certs/stable.pem')
+  })
+
+  test('active --json exposes the TLS and identity configuration', async () => {
+    await writeFile(
+      join(tmp, 'instances.json'),
+      JSON.stringify({
+        active: 'stable',
+        instances: {
+          stable: {
+            url: 'https://local.example/kernel',
+            issuer: 'https://issuer.example',
+            defaultIdentity: 'marc',
+            caFile: '/certs/stable.pem',
+            createdAt: '2026-08-20T00:00:00.000Z',
+          },
+        },
+      }),
+    )
+
+    const result = await runCli('instance', 'active', '--json')
+    expect(result.exitCode).toBe(0)
+    expect(JSON.parse(result.stdout)).toEqual({
+      name: 'stable',
+      url: 'https://local.example/kernel',
+      issuer: 'https://issuer.example',
+      defaultIdentity: 'marc',
+      caFile: '/certs/stable.pem',
+      createdAt: '2026-08-20T00:00:00.000Z',
+    })
+  })
 })
 
 async function readInstances(): Promise<{
@@ -85,9 +142,17 @@ async function runBookmark(...args: string[]): Promise<{
   exitCode: number
   stdout: string
   stderr: string
+}> {
+  return runCli('instance', 'bookmark', ...args)
+}
+
+async function runCli(...args: string[]): Promise<{
+  exitCode: number
+  stdout: string
+  stderr: string
 }> {
   const proc = Bun.spawn({
-    cmd: ['bun', join(cliRoot, 'bin/astrale.ts'), 'instance', 'bookmark', ...args],
+    cmd: ['bun', join(cliRoot, 'bin/astrale.ts'), ...args],
     env: { ...process.env, ASTRALE_HOME: tmp },
     stdout: 'pipe',
     stderr: 'pipe',

package/src/commands/__tests__/instance-list-rows.test.ts

@@ -15,6 +15,7 @@ function bookmark(overrides: Partial<Bookmark> = {}): Bookmark {
     issuer: null,
     active: false,
     defaultIdentity: null,
+    caFile: null,
     createdAt: null,
     ...overrides,
   }

package/src/commands/__tests__/instance-use.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from 'bun:test'
+
+import { IssuerUnreachableError } from '../../errors'
+import { InstanceStoreSchema, type ResolvedInstance } from '../../lib/instance'
+import { probeBookmark } from '../instance/use'
+
+const resolved: ResolvedInstance = {
+  name: 'stable',
+  kind: 'bookmark',
+  url: 'https://local.example/kernel',
+  issuer: 'https://issuer.example',
+  caFile: '/certs/stable.pem',
+}
+
+describe('instance use bookmark probe', () => {
+  test('uses the CA stored on the selected bookmark', async () => {
+    const scopedFetch = globalThis.fetch
+
+    await expect(
+      probeBookmark(resolved, {
+        readInstances: async () =>
+          InstanceStoreSchema.parse({
+            active: 'stable',
+            instances: {
+              stable: { url: resolved.url, caFile: resolved.caFile },
+            },
+          }),
+        fetchWithCaFile: (path) => {
+          expect(path).toBe('/certs/stable.pem')
+          return scopedFetch
+        },
+        checkIssuerReachability: async (url, issuer, fetchImpl) => {
+          expect(url).toBe(resolved.url)
+          expect(issuer).toBe(resolved.issuer)
+          expect(fetchImpl).toBe(scopedFetch)
+          return { issuer: resolved.issuer!, keys: [{ kid: 'key-1' }] }
+        },
+      }),
+    ).resolves.toBeUndefined()
+  })
+
+  test('names conflicting bookmark CAs in a failed TLS probe', async () => {
+    const failure = probeBookmark(resolved, {
+      readInstances: async () =>
+        InstanceStoreSchema.parse({
+          active: 'stable',
+          instances: {
+            stable: { url: resolved.url, caFile: resolved.caFile },
+            stale: { url: resolved.url, caFile: '/certs/old.pem' },
+          },
+        }),
+      fetchWithCaFile: () => fetch,
+      checkIssuerReachability: async () => {
+        throw new IssuerUnreachableError(resolved.url, 'certificate verify failed')
+      },
+    })
+
+    await expect(failure).rejects.toMatchObject({
+      code: 'ISSUER_UNREACHABLE',
+      message: `Issuer/JWKS probe failed for bookmark "stable" at ${resolved.url}.`,
+    })
+    await expect(failure).rejects.toHaveProperty(
+      'hint',
+      expect.stringContaining('"stale" (CA /certs/old.pem)'),
+    )
+  })
+})

package/src/commands/__tests__/view-build.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdir, mkdtemp, rm, utimes, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { devDistIsStale } from '../view'
+
+const temporaryDirectories: string[] = []
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true })),
+  )
+})
+
+describe('view development runtime build', () => {
+  test('reuses a current official build and detects every runtime build input', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-view-build-'))
+    temporaryDirectories.push(root)
+    const entry = join(root, 'bin', 'astrale.ts')
+    const source = join(root, 'src', 'command.ts')
+    const vendor = join(root, 'vendor', 'dependency.tgz')
+    const buildScript = join(root, 'scripts', 'build.ts')
+    const packageJson = join(root, 'package.json')
+    const lockfile = join(root, 'pnpm-lock.yaml')
+    const dist = join(root, 'dist', 'astrale.js')
+
+    await Promise.all(
+      ['bin', 'src', 'vendor', 'scripts', 'dist'].map((directory) =>
+        mkdir(join(root, directory), { recursive: true }),
+      ),
+    )
+    const inputs = [entry, source, vendor, buildScript, packageJson, lockfile]
+    await Promise.all(inputs.map((file) => writeFile(file, 'input')))
+    await writeFile(dist, 'built')
+    const past = new Date(Date.now() - 2_000)
+    const present = new Date()
+    await Promise.all(inputs.map((file) => utimes(file, past, past)))
+    await utimes(dist, present, present)
+
+    expect(await devDistIsStale(entry, dist)).toBe(false)
+
+    for (const input of inputs) {
+      await utimes(input, new Date(Date.now() + 2_000), new Date(Date.now() + 2_000))
+      expect(await devDistIsStale(entry, dist)).toBe(true)
+      await utimes(input, past, past)
+    }
+  })
+
+  test('requires a build when dist/astrale.js is missing', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-view-build-missing-'))
+    temporaryDirectories.push(root)
+
+    expect(
+      await devDistIsStale(join(root, 'bin', 'astrale.ts'), join(root, 'dist', 'astrale.js')),
+    ).toBe(true)
+  })
+})