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

package/src/connection/session.ts

@@ -1,11 +1,15 @@
-import type { AuthApi } from '@astrale-os/kernel-client/auth'
-import type { GraphApi } from '@astrale-os/kernel-client/graph'
-import type { ClientSessionOptions, SessionAuth } from '@astrale-os/kernel-client/session'
-
-import { call } from '@astrale-os/kernel-client'
-import { createAuth } from '@astrale-os/kernel-client/auth'
-import { createGraph } from '@astrale-os/kernel-client/graph'
-import { ClientSession } from '@astrale-os/kernel-client/session'
+import type { AuthApi } from '@astrale-os/sdk/auth'
+import type { GraphApi } from '@astrale-os/sdk/client'
+import type {
+  ClientSessionOptions,
+  SessionAuth,
+  SessionRouteStore,
+} from '@astrale-os/sdk/client/session'
+
+import { createAuth } from '@astrale-os/sdk/auth'
+import { call } from '@astrale-os/sdk/client'
+import { createGraph } from '@astrale-os/sdk/client'
+import { ClientSession } from '@astrale-os/sdk/client/session'
 
 import type { AstraleConfig } from '../lib/config'
 import type { AdminConnectionOptions, ConnectionOptions, ConnectionTarget } from './target'
@@ -21,6 +25,8 @@ import { fetchWithCaFile } from '../lib/ca-fetch'
 import { readConfig } from '../lib/config'
 import { log } from '../lib/log'
 import { isMachine } from '../lib/output'
+import { SESSION_ROUTE_STORE } from '../state/session-routes'
+import { bindCredentialIdentity } from './auth'
 import { createCliCredential, validateCredentialSelection } from './credential'
 import { resolveAdminConnectionTarget, resolveConnectionTarget } from './target'
 
@@ -38,6 +44,8 @@ export interface ConnectionContext {
   readonly graph: GraphApi
   readonly auth: AuthApi
   readonly target: ConnectionTarget
+  /** Local identity label selected for this session; absent for raw credentials or anonymous use. */
+  readonly identity?: string
 }
 
 interface OwnedConnection {
@@ -63,6 +71,7 @@ export async function withClientSession<Value>(
   const target = await resolveConnectionTarget(options, config, {
     managed: (slug) => lookupManagedInstance(slug, options),
   })
+  options = await bindCredentialIdentity(options, target)
   warnMissingExplicitTarget(options, target)
   return runResolvedClientSession(target, timeoutMs, options, config, action, openConnection)
 }
@@ -76,6 +85,7 @@ export async function withAdminClientSession<Value>(
   const timeoutMs = resolveTimeoutMs(options.timeout)
   const config = await readConfig()
   const target = await resolveAdminConnectionTarget(options, config)
+  options = await bindCredentialIdentity(options, target)
   return runResolvedClientSession(target, timeoutMs, options, config, action, openConnection)
 }
 
@@ -141,7 +151,13 @@ function openConnection(
   const graph = createGraph((call, request) => session.call(call, request))
   const authApi = createAuth((path, input, request) => session.call(call(path, input), request))
   return {
-    context: Object.freeze({ session, graph, auth: authApi, target }),
+    context: Object.freeze({
+      session,
+      graph,
+      auth: authApi,
+      target,
+      ...(options.as === undefined ? {} : { identity: options.as }),
+    }),
     close() {
       session.close()
     },
@@ -154,11 +170,13 @@ export function createClientSessionOptions(
   fetch: NonNullable<ClientSessionOptions['fetch']>,
   auth: SessionAuth | undefined,
   timeoutMs: number,
+  routeStore: SessionRouteStore = SESSION_ROUTE_STORE,
 ): ClientSessionOptions {
   return {
     kernel: target.kernelIssuer,
     fetch,
     ...(auth === undefined ? {} : { auth }),
+    routeStore,
     policy: {
       maximumRouteAgeMs: MAXIMUM_ROUTE_AGE_MS,
       ...(new URL(target.url).protocol === 'http:' ? { allowInsecureHttp: true } : {}),

package/src/errors.ts

@@ -2,8 +2,9 @@ export class AstraleError extends Error {
   code: string
   hint?: string
 
-  constructor(code: string, message: string, hint?: string) {
-    super(message)
+  constructor(code: string, message: string, hint?: string, options?: ErrorOptions) {
+    if (message.trim() === '') throw new TypeError('CLI error message must be non-blank.')
+    super(message, options)
     this.name = 'AstraleError'
     this.code = code
     this.hint = hint

package/src/graph/.spec/api.d.ts

@@ -1,7 +1,14 @@
+import type { ClassKey, ClassRef } from '@astrale-os/sdk/graph/class'
 import type { MutationAST } from '@astrale-os/sdk/mutation'
 import type { QueryAST, QueryDirection } from '@astrale-os/sdk/query'
 
-/** Untrusted CLI fields used to author or admit one exact Query V5 request. */
+/** Admit one canonical Domain-rooted Class Path into its DSL coordinate. */
+export function classReference(input: string, label: string): ClassRef
+
+/** Admit one canonical Domain-rooted Class Path into its exact string identity. */
+export function classKey(input: string, label: string): ClassKey
+
+/** Untrusted CLI fields used to author or admit one exact Query V6 request. */
 export interface QueryCommandInput {
   readonly sources: readonly string[]
   readonly definition?: string
@@ -12,16 +19,16 @@ export interface QueryCommandInput {
   readonly cursor?: string
 }
 
-/** Canonical query plus the caller-bound continuation token kept outside the AST. */
+/** Canonical query plus caller-bound pagination kept outside the AST. */
 export interface PreparedQuery {
   readonly ast: QueryAST
-  readonly cursor?: string
+  readonly page: Readonly<{ readonly size: number; readonly after?: string }>
 }
 
-/** Admit canonical Query V5 or author its supported Path/Definition/one-edge CLI subset. */
+/** Admit canonical Query V6 or author its supported Path/Class/one-edge CLI subset. */
 export function prepareQuery(input: QueryCommandInput): PreparedQuery
 
-/** Admit canonical Mutation V2 or its exact authoring input; legacy PatchData is rejected. */
+/** Admit canonical Mutation V3 or its exact authoring input; legacy PatchData is rejected. */
 export function prepareMutation(input: unknown): MutationAST
 
 /** Return the user-facing leaf of one exact qualified Property key. */

package/src/graph/.spec/layout.ts

@@ -1,6 +1,14 @@
 import { defineLayout } from '@astrale-os/spec/authoring'
 
 export default defineLayout({
-  entries: ['__tests__/', 'index.ts', 'mutation.ts', 'projection.ts', 'query.ts', 'tsconfig.json'],
+  entries: [
+    '__tests__/',
+    'class.ts',
+    'index.ts',
+    'mutation.ts',
+    'projection.ts',
+    'query.ts',
+    'tsconfig.json',
+  ],
   exact: true,
 })

package/src/graph/__tests__/mutation.test.ts

@@ -14,7 +14,7 @@ describe('prepareMutation', () => {
               {
                 op: 'node.create',
                 as: 'note',
-                class: '/:notes.example.dev:class.Note',
+                class: 'notes.example.dev:class.Note',
                 props: {},
               },
             ],
@@ -29,7 +29,7 @@ describe('prepareMutation', () => {
         {
           op: 'node.create',
           as: 'note',
-          class: '/:notes.example.dev:class.Note',
+          class: 'notes.example.dev:class.Note',
           props: {},
         },
       ],

package/src/graph/__tests__/query.test.ts

@@ -38,7 +38,7 @@ describe('prepareQuery', () => {
   })
 
   /** @evidence TEST-CLI-GRAPH-AUTHORS-DEFINITION-QUERY */
-  test('authors an exact Definition source without backend query text', () => {
+  test('authors an exact Class source without backend query text', () => {
     const prepared = prepareQuery({
       sources: [],
       definition: '/:issues.astrale.ai:class.Issue',
@@ -52,8 +52,8 @@ describe('prepareQuery', () => {
         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',
@@ -64,6 +64,25 @@ describe('prepareQuery', () => {
     expect(prepared.page).toEqual({ size: 201 })
   })
 
+  test('unions positional Paths and one Class source in authored order', () => {
+    const prepared = prepareQuery({
+      sources: ['@note'],
+      definition: '/:issues.astrale.ai:class.Issue',
+    })
+
+    expect(JSON.parse(JSON.stringify(prepared.ast.source))).toEqual({
+      kind: 'node',
+      terms: [
+        { kind: 'path', path: '@note' },
+        {
+          kind: 'class',
+          class: { origin: 'issues.astrale.ai', kind: 'class', name: 'Issue' },
+        },
+      ],
+      binding: 'n0',
+    })
+  })
+
   /** @evidence TEST-CLI-GRAPH-ADMITS-QUERY-V6-ORDERING */
   test('admits one exact Property-ordered Query V6 document', () => {
     const ast = {
@@ -73,8 +92,8 @@ describe('prepareQuery', () => {
         kind: 'node',
         terms: [
           {
-            kind: 'definition',
-            definition: { origin: 'notes.example.dev', kind: 'class', name: 'Note' },
+            kind: 'class',
+            class: { origin: 'notes.example.dev', kind: 'class', name: 'Note' },
           },
         ],
         binding: 'n0',
@@ -149,6 +168,6 @@ describe('prepareQuery', () => {
     ).toThrow('--limit must be a positive integer')
     expect(() =>
       prepareQuery({ sources: [], definition: '/:notes.example.dev:view.note' }),
-    ).toThrow('--definition must be one canonical Class or Interface Path')
+    ).toThrow('--definition must be one canonical Class Path')
   })
 })

package/src/graph/class.ts

@@ -0,0 +1,30 @@
+import type { ClassKey as ClassKeyValue, ClassRef } from '@astrale-os/sdk/graph/class'
+
+import { ClassKey } from '@astrale-os/sdk/graph/class'
+import { Path } from '@astrale-os/sdk/graph/path'
+
+/** Admit one canonical Domain-rooted Class Path into its DSL coordinate. */
+export function classReference(input: string, label: string): ClassRef {
+  const path = Path.parse(input)
+  const step = path.ast.steps[0]
+  if (
+    path.ast.anchor.kind !== 'domain' ||
+    path.ast.steps.length !== 1 ||
+    step?.kind !== 'projection' ||
+    step.projection.kind !== 'class'
+  ) {
+    throw new TypeError(`${label} must be one canonical Class Path`)
+  }
+  return ClassKey.ref(
+    ClassKey.of({
+      origin: path.ast.anchor.origin,
+      kind: 'class',
+      name: step.projection.name,
+    }),
+  )
+}
+
+/** Admit one canonical Domain-rooted Class Path into its exact string identity. */
+export function classKey(input: string, label: string): ClassKeyValue {
+  return ClassKey.of(classReference(input, label))
+}

package/src/graph/index.ts

@@ -1,3 +1,4 @@
+export { classKey, classReference } from './class'
 export { prepareMutation } from './mutation'
 export { nodeProperty, unqualifyProperty } from './projection'
 export { prepareQuery, type PreparedQuery, type QueryCommandInput } from './query'

package/src/graph/query.ts

@@ -1,12 +1,15 @@
 import type {
+  NodeQueryBuilder,
   QueryAST as QueryASTValue,
-  QueryDefinitionRef,
   QueryDirection,
+  QueryNodeInput,
 } from '@astrale-os/sdk/query'
 
 import { Path } from '@astrale-os/sdk/graph/path'
 import { Query, QueryAST } from '@astrale-os/sdk/query'
 
+import { classReference } from './class'
+
 export interface QueryCommandInput {
   readonly sources: readonly string[]
   readonly definition?: string
@@ -51,43 +54,29 @@ export function prepareQuery(input: QueryCommandInput): PreparedQuery {
   }
 
   const paths = input.sources.map((source) => Path.parse(source))
-  const definition = input.definition === undefined ? undefined : definitionRef(input.definition)
-  const query =
-    paths.length > 0
-      ? Query.from({
-          kind: 'node',
-          paths: paths as [Path, ...Path[]],
-          ...(definition === undefined ? {} : { definitions: [definition] }),
-        })
-      : Query.from({ kind: 'node', definitions: [definition!] })
+  const definition =
+    input.definition === undefined ? undefined : classReference(input.definition, '--definition')
+  const nodes = definition === undefined ? paths : [...paths, definition]
+  const query: NodeQueryBuilder<unknown> = Query.from({
+    nodes: nodes as [QueryNodeInput, ...QueryNodeInput[]],
+  })
   const ast =
     input.edge === undefined
-      ? query.select({ kind: 'graph' })
-      : query
-          .expand({
-            via: [definitionRef(input.edge)],
-            direction: input.direction ?? 'outgoing',
-          })
-          .select({ kind: 'graph' })
+      ? query.select({ kind: 'graph', binding: query.node })
+      : expanded(query, input.edge, input.direction)
   return withPage(ast, limit, input.cursor)
 }
 
-function definitionRef(input: string): QueryDefinitionRef {
-  const path = Path.parse(input)
-  const step = path.ast.steps[0]
-  if (
-    path.ast.anchor.kind !== 'domain' ||
-    path.ast.steps.length !== 1 ||
-    step?.kind !== 'projection' ||
-    (step.projection.kind !== 'class' && step.projection.kind !== 'interface')
-  ) {
-    throw new TypeError('--definition must be one canonical Class or Interface Path')
-  }
-  return Object.freeze({
-    origin: path.ast.anchor.origin,
-    kind: step.projection.kind,
-    name: step.projection.name,
+function expanded(
+  query: NodeQueryBuilder<unknown>,
+  edge: string,
+  direction: QueryDirection | undefined,
+): QueryASTValue {
+  const result = query.expand({
+    via: [classReference(edge, '--edge')],
+    direction: direction ?? 'outgoing',
   })
+  return result.select({ kind: 'graph', binding: result.node })
 }
 
 function positiveInteger(raw: string | undefined, name: string, fallback: number): number {

package/src/identity/.spec/api.d.ts

@@ -1,6 +1,6 @@
-import type { Call } from '@astrale-os/kernel-client'
 import type { ProvisionRequest } from '@astrale-os/sdk/auth'
-import type { LocalBinding } from '@astrale-os/sdk/graph/model'
+import type { Call } from '@astrale-os/sdk/client'
+import type { LocalBinding } from '@astrale-os/sdk/graph'
 import type { JWK } from 'jose'
 
 import type {

package/src/identity/__tests__/fixtures/registry-journey.ts

@@ -1,5 +1,8 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
 import { fileExists, keypairPaths } from '../../../keys/index'
-import { KEYS_DIR } from '../../../state/index'
+import { EXCHANGE_CREDENTIALS_PATH, KEYS_DIR, SESSION_ROUTES_PATH } from '../../../state/index'
 import {
   createIdentity,
   exportIdentity,
@@ -30,6 +33,13 @@ try {
 } catch (error) {
   selectedDeletion = error instanceof Error ? error.message : String(error)
 }
+await mkdir(dirname(SESSION_ROUTES_PATH), { recursive: true })
+await mkdir(dirname(EXCHANGE_CREDENTIALS_PATH), { recursive: true })
+await writeFile(SESSION_ROUTES_PATH, '{"version":1,"entries":{"confidential":{}}}\n')
+await writeFile(
+  EXCHANGE_CREDENTIALS_PATH,
+  '{"version":2,"entries":{"confidential":{"credential":"bearer"}}}\n',
+)
 await deleteIdentity('bob')
 await deleteIdentity('alice-alias')
 await upsertIdpIdentity('workos', {
@@ -49,5 +59,7 @@ console.log(
     selectedDeletion,
     aliceKey: await fileExists(keypairPaths('alice', KEYS_DIR).privatePath),
     bobKey: await fileExists(keypairPaths('bob', KEYS_DIR).privatePath),
+    routeCache: await fileExists(SESSION_ROUTES_PATH),
+    exchangeCache: JSON.parse(await readFile(EXCHANGE_CREDENTIALS_PATH, 'utf8')),
   }),
 )

package/src/identity/__tests__/registration.test.ts

@@ -1,6 +1,6 @@
 import type { ProvisionRequest } from '@astrale-os/sdk/auth'
 
-import { LocalBinding } from '@astrale-os/sdk/graph/model'
+import { LocalBinding } from '@astrale-os/sdk/graph'
 import { expect, test } from 'bun:test'
 
 import { submitIdentityProvision } from '../registration'

package/src/identity/__tests__/registry.test.ts

@@ -47,6 +47,8 @@ describe('identity registry journey', () => {
       selectedDeletion: string
       aliceKey: boolean
       bobKey: boolean
+      routeCache: boolean
+      exchangeCache: unknown
     }
     expect(result.store.default).toBe('alice')
     expect(Object.keys(result.store.identities).sort()).toEqual(['alice', 'workos'])
@@ -60,6 +62,8 @@ describe('identity registry journey', () => {
     expect(result.selectedDeletion).toContain('Cannot delete the default identity')
     expect(result.aliceKey).toBe(true)
     expect(result.bobKey).toBe(false)
+    expect(result.routeCache).toBe(false)
+    expect(result.exchangeCache).toEqual({ version: 2, entries: {} })
 
     const persisted = JSON.parse(await readFile(join(root, 'identities.json'), 'utf-8')) as {
       version?: unknown

package/src/identity/registration.ts

@@ -1,9 +1,9 @@
-import type { Call } from '@astrale-os/kernel-client'
 import type { ProvisionRequest } from '@astrale-os/sdk/auth'
-import type { LocalBinding } from '@astrale-os/sdk/graph/model'
+import type { Call } from '@astrale-os/sdk/client'
+import type { LocalBinding } from '@astrale-os/sdk/graph'
 
-import { call } from '@astrale-os/kernel-client'
 import { issuer } from '@astrale-os/sdk/auth'
+import { call } from '@astrale-os/sdk/client'
 import { NodeId } from '@astrale-os/sdk/graph/node'
 import { Path } from '@astrale-os/sdk/graph/path'
 

package/src/identity/registry.ts

@@ -10,6 +10,7 @@ import {
   type IdentityStore,
   type Registration,
   ExchangeCredentialCache,
+  SESSION_ROUTE_STORE,
 } from '../state/index'
 
 export type { Identity, IdentityStore, Registration } from '../state/index'
@@ -68,6 +69,7 @@ export async function deleteIdentity(name: string): Promise<void> {
     return { next: { ...store, identities }, value: undefined }
   })
   await new ExchangeCredentialCache().clear()
+  SESSION_ROUTE_STORE.clear()
 }
 
 function hasAnotherKeyIdentity(store: IdentityStore, name: string, subject: string): boolean {

package/src/keys/__tests__/keys.test.ts

@@ -62,6 +62,10 @@ describe('DESIGN — per-identity keys', () => {
     await persistKeypair('alice', { keysDir: tmp })
     const jwt = await signAs('alice', tmp)
     expect(jwt.split('.').length).toBe(3)
+    const claims = decodeJwt(jwt)
+    expect(claims.iat).toBeUndefined()
+    expect(claims.exp).toBeNumber()
+    expect((claims.exp as number) * 1_000).toBeGreaterThan(Date.now() + 299_000)
   })
 
   /** @evidence TEST-CLI-KEYS-DISTINGUISHES-KERNEL-ROOT-GRANT */

package/src/keys/credential.ts

@@ -47,6 +47,7 @@ async function signIdentityCredential(options: {
     .setIssuer(options.issuer)
     .setSubject(options.subject)
     .setAudience(options.audience)
+    .setExpirationTime('5m')
     .sign(privateKey)
 }
 

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

@@ -6,6 +6,7 @@ import {
   DEFAULT_ADMIN_TARGET_NAME,
   DEFAULT_ADMIN_DOMAIN_ISSUER,
   DEFAULT_ADMIN_TARGET_URL,
+  defaultAdminTargetForChannel,
   resolveAdminTargetFromStore,
 } from '../admin-target'
 import { DEFAULT_CONFIG, type AstraleConfig } from '../config'
@@ -32,6 +33,17 @@ const instances: InstanceStore = {
 }
 
 describe('resolveAdminTargetFromStore', () => {
+  test('derives hosted Admin defaults from the release channel', () => {
+    expect(defaultAdminTargetForChannel('beta')).toEqual({
+      url: 'https://admin.eu.beta.astrale.ai/api',
+      domainIssuer: 'https://admin.beta.astrale.ai',
+    })
+    expect(defaultAdminTargetForChannel('stable')).toEqual({
+      url: 'https://admin.eu.astrale.ai/api',
+      domainIssuer: 'https://admin.astrale.ai',
+    })
+  })
+
   test('uses hosted admin default without active instance coupling', () => {
     expect(resolveAdminTargetFromStore({}, DEFAULT_CONFIG, instances)).toEqual({
       name: DEFAULT_ADMIN_TARGET_NAME,

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

@@ -39,11 +39,26 @@ describe('presentBinary', () => {
 
   test('--json inlines text for text-like content types', async () => {
     await presentBinary(
-      { mediaType: 'text/plain', body: new TextEncoder().encode('hi') },
+      { mediaType: 'text/plain', status: 202, body: new TextEncoder().encode('hi') },
       { json: true },
     )
     const obj = JSON.parse(Buffer.concat(chunks).toString())
     expect(obj.body).toBe('hi')
+    expect(obj.status).toBe(202)
+  })
+
+  test('--raw drains streaming binary chunks in exact order', async () => {
+    await presentBinary(
+      {
+        mediaType: 'application/octet-stream',
+        body: (async function* () {
+          yield new Uint8Array([1, 2])
+          yield new Uint8Array([3, 4])
+        })(),
+      },
+      { raw: true },
+    )
+    expect(Array.from(Buffer.concat(chunks))).toEqual([1, 2, 3, 4])
   })
 
   test('-o writes raw bytes to a file', async () => {