@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

package/src/commands/__tests__/read-commands.test.ts

@@ -6,6 +6,12 @@ type GraphContext = {
     getOrThrow: typeof getOrThrowMock
     mutate: typeof mutateMock
   }
+  session: {
+    schema: {
+      inspect: typeof inspectMock
+      bundle: typeof bundleMock
+    }
+  }
 }
 
 type RunOpts = {
@@ -36,6 +42,10 @@ let mutations: unknown[] = []
 let queryResult: unknown
 let getResult: unknown
 let mutationResult: unknown
+let inspectResult: unknown
+let bundleResult: unknown
+let selfFailure: unknown
+let selfContexts: unknown[] = []
 
 const queryMock = mock(async (ast: unknown, options?: unknown) => {
   queryCalls.push({ ast, options })
@@ -49,7 +59,11 @@ const mutateMock = mock(async (mutation: unknown) => {
   mutations.push(mutation)
   return mutationResult
 })
-const expandSelfInPathMock = mock(async (path: string) => {
+const inspectMock = mock(async (_origin: string) => inspectResult)
+const bundleMock = mock(async (_origin: string) => bundleResult)
+const expandSelfInPathMock = mock(async (path: string, context: unknown) => {
+  selfContexts.push(context)
+  if (selfFailure !== undefined) throw selfFailure
   if (path === '@self') {
     return {
       path: '@expanded-self',
@@ -59,10 +73,12 @@ const expandSelfInPathMock = mock(async (path: string) => {
   return { path, meta: undefined }
 })
 const withSelfHintMock = mock(async (action: () => Promise<unknown>) => action())
+const commandContext = {
+  graph: { query: queryMock, getOrThrow: getOrThrowMock, mutate: mutateMock },
+  session: { schema: { inspect: inspectMock, bundle: bundleMock } },
+}
 const runKernelCommandMock = mock(async (run: RunOpts) => {
-  const result = await run.fn({
-    graph: { query: queryMock, getOrThrow: getOrThrowMock, mutate: mutateMock },
-  })
+  const result = await run.fn(commandContext)
   await run.format?.(result, run.opts, true)
 })
 
@@ -88,9 +104,22 @@ beforeEach(() => {
   }
   getResult = undefined
   mutationResult = { createdNodes: {} }
+  inspectResult = {
+    origin: 'notes.example.dev',
+    revision: 'notes-v1',
+    generation: 'sha256:generation',
+  }
+  bundleResult = {
+    domain: inspectResult,
+    bundle: { origin: 'notes.example.dev', revision: 'notes-v1' },
+  }
+  selfFailure = undefined
+  selfContexts = []
   queryMock.mockClear()
   getOrThrowMock.mockClear()
   mutateMock.mockClear()
+  inspectMock.mockClear()
+  bundleMock.mockClear()
   expandSelfInPathMock.mockClear()
   withSelfHintMock.mockClear()
   runKernelCommandMock.mockClear()
@@ -161,12 +190,12 @@ describe('query command', () => {
     ])
   })
 
-  test('authors a Definition source through the same canonical Query V6 call', async () => {
+  test('authors a Class source through the same canonical Query V6 call', async () => {
     const { queryCommand } = await import('../query')
 
     await queryCommand([], {
       json: true,
-      definition: '/:issues.astrale.ai:class.Issue',
+      class: '/:issues.astrale.ai:class.Issue',
       limit: '20',
     })
 
@@ -179,8 +208,8 @@ describe('query command', () => {
             kind: 'node',
             terms: [
               {
-                kind: 'definition',
-                definition: { origin: 'issues.astrale.ai', kind: 'class', name: 'Issue' },
+                kind: 'class',
+                class: { origin: 'issues.astrale.ai', kind: 'class', name: 'Issue' },
               },
             ],
             binding: 'n0',
@@ -193,6 +222,44 @@ describe('query command', () => {
     ])
   })
 
+  test('retains the opaque continuation in machine output without wrapping the graph result', async () => {
+    const { queryCommand } = await import('../query')
+    const result = {
+      kind: 'graph' as const,
+      graph: {
+        nodes: [{ id: 'issue-1', class: 'issues.astrale.ai:class.Issue', props: {} }],
+        edges: [],
+      },
+      selection: { kind: 'node' as const, ids: ['issue-1'] },
+    }
+    queryResult = {
+      result,
+      page: { next: 'opaque-next-page' },
+    }
+
+    await queryCommand([], {
+      json: true,
+      class: '/:issues.astrale.ai:class.Issue',
+      limit: '1',
+    })
+
+    expect(JSON.parse(stdout)).toEqual({
+      ...result,
+      page: { next: 'opaque-next-page' },
+    })
+  })
+
+  test('resolves @self inside the command session and never relabels transport failure as input', async () => {
+    const { queryCommand } = await import('../query')
+    await queryCommand(['@self'], { json: true, limit: '2' })
+    expect(selfContexts).toEqual([commandContext])
+
+    const aggregate = new AggregateError([], '')
+    selfFailure = aggregate
+    await expect(queryCommand(['@self'], { json: true, limit: '2' })).rejects.toBe(aggregate)
+    expect(errors.join('\n')).not.toContain('INVALID_INPUT')
+  })
+
   /** @evidence TEST-CLI-QUERY-REJECTS-V1-BEFORE-CONNECTION */
   test('rejects a legacy AST before opening the command connection', async () => {
     const { queryCommand } = await import('../query')
@@ -215,7 +282,7 @@ describe('get command', () => {
     const { getCommand } = await import('../get')
     getResult = {
       id: 'note-1',
-      class: '/:notes.example.dev:class.Note',
+      class: 'notes.example.dev:class.Note',
       props: { 'notes.example.dev:class.Note.property.title': 'Hello' },
     }
 
@@ -226,6 +293,47 @@ describe('get command', () => {
     expect(stdout).not.toContain('__labels')
     expect(stdout).not.toContain('classId')
   })
+
+  test('resolves @self through the same point-read command context', async () => {
+    const { getCommand } = await import('../get')
+    await getCommand('@self', { json: true })
+    expect(selfContexts).toEqual([commandContext])
+    expect(getTargets).toEqual(['@expanded-self'])
+  })
+})
+
+describe('introspect command', () => {
+  test('uses the split SDK Schema API without recreating the retired introspection request', async () => {
+    const { introspectCommand } = await import('../introspect')
+
+    await introspectCommand(
+      'notes.example.dev',
+      { json: true },
+      {
+        runKernelCommand: runKernelCommandMock as never,
+      },
+    )
+
+    expect(inspectMock).toHaveBeenCalledWith('notes.example.dev')
+    expect(bundleMock).not.toHaveBeenCalled()
+    expect(JSON.parse(stdout)).toEqual(inspectResult)
+  })
+
+  test('requests the immutable bundle only when explicitly selected', async () => {
+    const { introspectCommand } = await import('../introspect')
+
+    await introspectCommand(
+      'notes.example.dev',
+      { json: true, bundle: true },
+      {
+        runKernelCommand: runKernelCommandMock as never,
+      },
+    )
+
+    expect(bundleMock).toHaveBeenCalledWith('notes.example.dev')
+    expect(inspectMock).not.toHaveBeenCalled()
+    expect(JSON.parse(stdout)).toEqual(bundleResult)
+  })
 })
 
 describe('mutate command', () => {
@@ -242,7 +350,7 @@ describe('mutate command', () => {
           {
             op: 'node.create',
             as: 'note',
-            class: '/:notes.example.dev:class.Note',
+            class: 'notes.example.dev:class.Note',
             props: {},
           },
         ],
@@ -258,7 +366,7 @@ describe('mutate command', () => {
           {
             op: 'node.create',
             as: 'note',
-            class: '/:notes.example.dev:class.Note',
+            class: 'notes.example.dev:class.Note',
             props: {},
           },
         ],

package/src/commands/__tests__/token-ttl.test.ts

@@ -1,11 +1,13 @@
-import { describe, expect, test } from 'bun:test'
+import type { AuthApi, Identity, IssuerId, MintedCredential } from '@astrale-os/sdk/auth'
+
+import { describe, expect, mock, test } from 'bun:test'
 
 import { AstraleError } from '../../errors'
-import { parseTtl } from '../token'
+import { issueToken, parseTtl } from '../token'
 
 describe('parseTtl', () => {
-  test('defaults to 3600 seconds', () => {
-    expect(parseTtl(undefined)).toBe(3600)
+  test('defaults below the five-minute local source-credential lifetime', () => {
+    expect(parseTtl(undefined)).toBe(240)
   })
 
   test('rejects non-positive and non-integer values', () => {
@@ -19,3 +21,46 @@ describe('parseTtl', () => {
     expect(parseTtl('90')).toBe(90)
   })
 })
+
+describe('issueToken', () => {
+  const kernel = 'https://kernel.test' as IssuerId
+  const identity = {
+    id: 'caller' as Identity['id'],
+    issuer: 'https://issuer.test' as Identity['issuer'],
+    subject: 'caller' as Identity['subject'],
+    frozen: false,
+    requiredClaims: [],
+  } satisfies Identity
+
+  test('mints a reusable top-level credential for the Kernel audience', async () => {
+    const mint = mock(async () => 'kernel-token' as MintedCredential)
+    const delegate = mock(async () => 'delegated-token' as MintedCredential)
+    const whoami = mock(async () => identity)
+    const auth = { mint, delegate, whoami } satisfies Pick<AuthApi, 'delegate' | 'mint' | 'whoami'>
+
+    await expect(issueToken(auth, kernel, kernel, 90)).resolves.toBe(
+      'kernel-token' as MintedCredential,
+    )
+    expect(mint).toHaveBeenCalledWith({ ttlSeconds: 90 })
+    expect(whoami).not.toHaveBeenCalled()
+    expect(delegate).not.toHaveBeenCalled()
+  })
+
+  test('delegates the selected identity only for an external audience', async () => {
+    const mint = mock(async () => 'kernel-token' as MintedCredential)
+    const delegate = mock(async () => 'delegated-token' as MintedCredential)
+    const whoami = mock(async () => identity)
+    const auth = { mint, delegate, whoami } satisfies Pick<AuthApi, 'delegate' | 'mint' | 'whoami'>
+
+    await expect(issueToken(auth, kernel, 'https://service.test' as IssuerId, 120)).resolves.toBe(
+      'delegated-token' as MintedCredential,
+    )
+    expect(mint).not.toHaveBeenCalled()
+    expect(whoami).toHaveBeenCalledTimes(1)
+    expect(delegate).toHaveBeenCalledWith(identity.id, {
+      audience: 'https://service.test',
+      ttlSeconds: 120,
+      attenuation: { kind: 'identity', self: true },
+    })
+  })
+})

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

@@ -35,9 +35,11 @@ describe('CLI update staleness', () => {
     const result = await cliStale(
       { channel: 'canary' },
       {
-        update: async () => {
-          throw new Error('package managed')
-        },
+        update: async () => ({
+          status: 'managed',
+          currentVersion: '1.0.0-beta.0',
+          executable: '/opt/homebrew/bin/node',
+        }),
         fetchPackageVersion: async ({ channel }) => {
           expect(channel).toBe('canary')
           return '1.0.0-canary.0'
@@ -52,6 +54,26 @@ describe('CLI update staleness', () => {
     })
   })
 
+  test('does not misclassify a script update failure as package-managed', async () => {
+    const fetchPackageVersion = mock(async () => '9.9.9')
+    const result = await cliStale(
+      {},
+      {
+        update: async () => {
+          throw new Error('release endpoint unavailable')
+        },
+        fetchPackageVersion,
+      },
+    )
+
+    expect(result).toMatchObject({
+      stale: false,
+      managed: false,
+      error: 'release endpoint unavailable',
+    })
+    expect(fetchPackageVersion).not.toHaveBeenCalled()
+  })
+
   test('maps the default to beta and the stable channel to npm latest', async () => {
     const originalFetch = globalThis.fetch
     const fetchMock = mock(async (input: RequestInfo | URL) => {

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

@@ -52,7 +52,6 @@ const resolved = [
         kind: 'definition' as const,
         definitions: [{ origin: 'ai-gateway.astrale.ai', kind: 'class' as const, name: 'Model' }],
       },
-      auth: 'required' as const,
     },
   }),
   route({
@@ -62,7 +61,7 @@ const resolved = [
     issuer: 'https://ai-gateway.astrale.ai',
     etag: `sha256:${'c'.repeat(64)}`,
     revision: `sha256:${'d'.repeat(64)}`,
-    declaration: { target: { kind: 'domain' as const }, auth: 'public' as const },
+    declaration: { target: { kind: 'domain' as const } },
   }),
 ]
 
@@ -147,3 +146,52 @@ describe('view capture timing', () => {
     expect(commands.length).toBeGreaterThan(2)
   })
 })
+
+describe('view session runtime', () => {
+  test('builds one serve config with the admitted operator origin grant', async () => {
+    const { createViewServeConfig } = await import('../view')
+    const record = {
+      id: 'v-proof',
+      pid: 0,
+      port: 4419,
+      nonce: 'proof',
+      pageUrl: 'http://127.0.0.1:4419/s/proof/',
+      view: { target: Path.parse('/:ai-gateway.astrale.ai').raw, route: resolved[0] },
+      createdAt: '2026-08-26T00:00:00.000Z',
+    }
+
+    const config = createViewServeConfig(
+      record,
+      { allowExternalOrigin: ['https://connect.nango.dev/'] },
+      { url: 'https://kernel.test', kernelIssuer: 'https://kernel.test' },
+    )
+
+    expect(config.session).toBe(record)
+    expect(config.externalOrigins).toEqual(['https://connect.nango.dev'])
+    expect(config.proxy).toEqual({
+      kernelUrl: 'https://kernel.test',
+      issuer: 'https://kernel.test',
+      caFile: undefined,
+      direct: true,
+    })
+  })
+
+  test('spawns the detached server from a compiled executable without its virtual Bun entry', async () => {
+    const { resolveServeRuntime, viewServeInvocation } = await import('../view')
+
+    const runtime = await resolveServeRuntime({
+      executable: '/opt/astrale/bin/astrale',
+      entry: '/$bunfs/root/astrale',
+      exists: () => true,
+      find: async () => '/usr/bin/node',
+    })
+    expect(runtime).toEqual({
+      file: '/opt/astrale/bin/astrale',
+      args: [],
+    })
+    expect(viewServeInvocation(runtime, '/tmp/view.config.json')).toEqual({
+      file: '/opt/astrale/bin/astrale',
+      args: ['__view-serve', '--config', '/tmp/view.config.json'],
+    })
+  })
+})

package/src/commands/auth/logout.ts

@@ -4,7 +4,7 @@ import { getDefault, readIdentities } from '../../identity/index'
 import { deleteIdpSession, listIdpSessions } from '../../lib/idp'
 import { log } from '../../lib/log'
 import { output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
-import { ExchangeCredentialCache } from '../../state/index'
+import { ExchangeCredentialCache, SESSION_ROUTE_STORE } from '../../state/index'
 
 export default {
   name: 'logout',
@@ -30,6 +30,7 @@ export default {
 
     for (const name of names) await deleteIdpSession(name)
     await new ExchangeCredentialCache().clear()
+    SESSION_ROUTE_STORE.clear()
 
     if (opts.raw || opts.json) {
       output({ cleared: names }, opts)

package/src/commands/browser.ts

@@ -13,6 +13,7 @@ import {
   profileDirFor,
   saveSession,
 } from '../lib/browser'
+import { sweepBrowserProfiles } from '../lib/browser-retention'
 import { readLocalStatus } from '../lib/local-status'
 import { fatal, log } from '../lib/log'
 import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../lib/output'
@@ -25,6 +26,29 @@ type BrowserOpts = RawOutputOpts & {
   check?: boolean
 }
 
+/**
+ * Opportunistic profile retention, the same `git gc --auto` shape the session
+ * store uses: no daemon, no cron, it just rides on the command that created the
+ * mess. Silent when there is nothing to do, and never fatal — losing a sweep is
+ * strictly better than losing the browser command.
+ */
+async function reportSweep(machine: boolean): Promise<void> {
+  try {
+    const swept = await sweepBrowserProfiles()
+    if (machine || swept.bytesFreed === 0) return
+    const freed = `${(swept.bytesFreed / 1024 / 1024).toFixed(0)} MB`
+    const what = [
+      swept.removed.length > 0 ? `${swept.removed.length} dormant profile(s) removed` : null,
+      swept.purged.length > 0 ? `${swept.purged.length} cache(s) trimmed` : null,
+    ]
+      .filter(Boolean)
+      .join(', ')
+    log.dim(`retention: ${what} — ${freed} freed`)
+  } catch {
+    /* retention must never break the browser command */
+  }
+}
+
 const LOGIN_TIMEOUT_MS = 180_000
 const POLL_INTERVAL_MS = 2500
 
@@ -125,6 +149,11 @@ Examples:
     const host = new URL(gui).host
     await requireAgentBrowser(machine, opts)
 
+    // Retention runs BEFORE anything launches, so no profile we touch can be in
+    // use by a browser this command started. Profiles held by someone else's
+    // live browser are skipped by the sweep itself.
+    await reportSweep(machine)
+
     const usingCdp = !!opts.cdp
     const profile = usingCdp ? null : (opts.profile ?? profileDirFor(host))
     const target = usingCdp ? { cdp: opts.cdp } : { profile: profile! }

package/src/commands/call-describe.ts

@@ -1,8 +1,9 @@
 import type { Path } from '@astrale-os/sdk/graph/path'
+import type { ResolvedFunction, ResolvedMethod } from '@astrale-os/sdk/schema'
 
-import { AstraleError } from '../errors'
+import { bundle, schema } from '@astrale-os/sdk/schema'
 
-type JsonRecord = Record<string, unknown>
+import { AstraleError } from '../errors'
 
 export interface CallableDescription {
   readonly path: string
@@ -18,40 +19,40 @@ export interface CallableDescription {
   readonly candidates?: readonly CallableDescription[]
 }
 
-/** Resolve one callable's input/output from an installed Domain schema document. */
-export function describeCallableFromSchema(
+/** Resolve one callable from an admitted installed Domain bundle. */
+export function describeCallableFromBundle(
   path: Path,
-  schema: unknown,
+  input: unknown,
 ): CallableDescription | undefined {
   if (path.ast.anchor.kind !== 'domain') return undefined
   const origin = path.ast.anchor.origin
   const last = path.ast.steps.at(-1)
-  const document = asRecord(schema)
-  if (document === undefined || last === undefined) return undefined
+  if (last === undefined) return undefined
+  const domain = schema.resolve(bundle.accept(input).root)
+  if (domain.origin !== origin) return undefined
 
   if (last.kind === 'method') {
-    const owner = path.ast.steps.at(-2)
-    if (
-      owner?.kind === 'projection' &&
-      (owner.projection.kind === 'class' || owner.projection.kind === 'interface')
-    ) {
-      const bag = asRecord(
-        owner.projection.kind === 'class' ? document.classes : document.interfaces,
+    const ownerStep = path.ast.steps.at(-2)
+    if (ownerStep?.kind === 'projection' && ownerStep.projection.kind === 'class') {
+      const owner = domain.classes[ownerStep.projection.name]
+      if (owner?.kind !== 'node') return undefined
+      const method = namedMethod(
+        last.dispatch === 'static' ? owner.static.methods : owner.methods,
+        last.name,
+        last.dispatch,
       )
-      const definition = asRecord(bag?.[owner.projection.name])
-      const method = asRecord(asRecord(definition?.methods)?.[last.name])
-      if (method !== undefined) {
-        return Object.freeze({
-          path: path.raw,
-          origin,
-          class: owner.projection.name,
-          method: last.name,
-          dispatch: last.dispatch,
-          ...callableFields(method),
-        })
-      }
+      return method === undefined
+        ? undefined
+        : description(path, origin, owner.ref.name, method, last.dispatch)
     }
-    const matches = findNamedMethods(document, origin, path.raw, last.name, last.dispatch)
+
+    const matches = Object.values(domain.classes).flatMap((owner) => {
+      if (owner.kind !== 'node') return []
+      const method = namedMethod(owner.methods, last.name, last.dispatch)
+      return method === undefined
+        ? []
+        : [description(path, origin, owner.ref.name, method, last.dispatch)]
+    })
     if (matches.length === 1) return matches[0]
     if (matches.length > 1) {
       return Object.freeze({
@@ -66,13 +67,13 @@ export function describeCallableFromSchema(
   }
 
   if (last.kind === 'projection' && last.projection.kind === 'function') {
-    const fn = asRecord(asRecord(document.functions)?.[last.projection.name])
-    if (fn === undefined) return undefined
+    const callable = domain.functions[last.projection.name]
+    if (callable === undefined) return undefined
     return Object.freeze({
       path: path.raw,
       origin,
-      function: last.projection.name,
-      ...callableFields(fn),
+      function: callable.ref.name,
+      ...callableFields(callable),
     })
   }
   return undefined
@@ -82,50 +83,41 @@ export function missingCallableDescription(path: string): AstraleError {
   return new AstraleError(
     'CALL_DESCRIBE_UNAVAILABLE',
     `No callable schema is installed for ${path}.`,
-    'Use a Domain-rooted Path such as /:host.astrale.ai:class.Manager:createInstance. Method Paths are not Function nodes.',
+    'Use a Domain-rooted Path such as /:kernel.astrale.ai:class.Identity:whois. Method Paths are not Function nodes.',
   )
 }
 
-function findNamedMethods(
-  schema: JsonRecord,
+function namedMethod(
+  methods: Iterable<ResolvedMethod>,
+  name: string,
+  dispatch: 'static' | 'instance',
+): ResolvedMethod | undefined {
+  const expectedStatic = dispatch === 'static'
+  return [...methods].find((method) => method.name === name && method.static === expectedStatic)
+}
+
+function description(
+  path: Path,
   origin: string,
-  path: string,
-  method: string,
+  className: string,
+  callable: ResolvedMethod,
   dispatch: 'static' | 'instance',
-): CallableDescription[] {
-  const matches: CallableDescription[] = []
-  for (const bag of [schema.classes, schema.interfaces]) {
-    const definitions = asRecord(bag)
-    if (definitions === undefined) continue
-    for (const [className, definition] of Object.entries(definitions)) {
-      const methodDef = asRecord(asRecord(asRecord(definition)?.methods)?.[method])
-      if (methodDef === undefined) continue
-      matches.push(
-        Object.freeze({
-          path,
-          origin,
-          class: className,
-          method,
-          dispatch,
-          ...callableFields(methodDef),
-        }),
-      )
-    }
-  }
-  return matches
+): CallableDescription {
+  return Object.freeze({
+    path: path.raw,
+    origin,
+    class: className,
+    method: callable.name,
+    dispatch,
+    ...callableFields(callable),
+  })
 }
 
-function callableFields(value: JsonRecord): Partial<CallableDescription> {
+function callableFields(callable: ResolvedFunction | ResolvedMethod): Partial<CallableDescription> {
   return {
-    ...(typeof value.description === 'string' ? { description: value.description } : {}),
-    ...(value.auth === undefined ? {} : { auth: value.auth }),
-    ...(value.input === undefined ? {} : { input: value.input }),
-    ...(value.output === undefined ? {} : { output: value.output }),
+    ...(callable.description === undefined ? {} : { description: callable.description }),
+    auth: callable.auth,
+    input: callable.input,
+    output: callable.output,
   }
 }
-
-function asRecord(input: unknown): JsonRecord | undefined {
-  return input !== null && typeof input === 'object' && !Array.isArray(input)
-    ? (input as JsonRecord)
-    : undefined
-}