@astrale-os/cli 1.0.0-beta.2 → 1.0.0-beta.20

package/src/admin/catalog/model.ts

@@ -33,10 +33,9 @@ export interface InstallDomainResult {
   readonly error?: string | null
 }
 
-export class AdminDomainNotFoundError extends Error {
-  readonly name = 'NotFoundError'
-
+export class AdminDomainNotFoundError extends AstraleError {
   constructor(readonly identifier: string) {
-    super(`No visible Admin Domain matches ${JSON.stringify(identifier)}.`)
+    super('DOMAIN_NOT_FOUND', `No visible Admin Domain matches ${JSON.stringify(identifier)}.`)
   }
 }
+import { AstraleError } from '../../errors'

package/src/admin/contract.ts

@@ -0,0 +1,46 @@
+import type { Input } from '@astrale-os/sdk/client'
+import type { ClientSession } from '@astrale-os/sdk/client/session'
+import type { ClassRef } from '@astrale-os/sdk/schema'
+
+import { call } from '@astrale-os/sdk/client'
+import { Path } from '@astrale-os/sdk/graph/path'
+import { K, PropertyKey } from '@astrale-os/sdk/schema'
+
+const origin = 'admin.astrale.ai'
+
+function classRef(name: string): ClassRef {
+  return Object.freeze({ origin, kind: 'class', name }) as ClassRef
+}
+
+const Domain = classRef('Domain')
+
+export const AdminContract = Object.freeze({
+  origin,
+  fleet: Path.parse('/:admin.astrale.ai:core.fleet'),
+  classes: Object.freeze({
+    Domain,
+  }),
+  edges: Object.freeze({
+    fleetInstallsDomainByDefault: classRef('fleet_installs_domain_by_default'),
+  }),
+  properties: Object.freeze({
+    domain: Object.freeze({
+      origin: PropertyKey.of(Domain, 'origin'),
+      name: K.classes.Named.properties.name.key,
+      discoveryUrl: PropertyKey.of(Domain, 'discoveryUrl'),
+      description: K.classes.Descriptable.properties.description.key,
+      createdAt: K.classes.Timestamped.properties.createdAt.key,
+      updatedAt: K.classes.Timestamped.properties.updatedAt.key,
+    }),
+  }),
+})
+
+/** Invoke one stable Admin instance Method without schema discovery or reflection. */
+export function callAdminMethod(
+  session: ClientSession,
+  receiver: Path,
+  method: string,
+  input: Input,
+): Promise<unknown> {
+  return session.call(call(Path.instanceMethod(receiver, method), input))
+}

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

@@ -1,18 +1,12 @@
-import type { GraphQueryOptions, NeighborsOptions, NodePage } from '@astrale-os/kernel-client/graph'
-import type { ClassPath } from '@astrale-os/sdk/graph/class'
+import type { GraphApi } from '@astrale-os/sdk/client'
 import type { Node } from '@astrale-os/sdk/graph/node'
-import type { PathLike } from '@astrale-os/sdk/graph/path'
-import type { QueryAST, QueryResult } from '@astrale-os/sdk/query'
+import type { QueryAST } from '@astrale-os/sdk/query'
 
 /** Smallest Kernel graph capability needed by bounded Admin graph reads. */
-export interface AdminGraphQueryApi {
-  query(ast: QueryAST, options?: GraphQueryOptions): Promise<QueryResult>
-}
+export type AdminGraphQueryApi = Pick<GraphApi, 'query'>
 
 /** Caller-scoped graph reads shared by the Admin catalog and Instance journeys. */
-export interface AdminGraphApi extends AdminGraphQueryApi {
-  neighbors(source: PathLike, edge: ClassPath, options: NeighborsOptions): Promise<NodePage>
-}
+export type AdminGraphApi = Pick<GraphApi, 'query' | 'neighbors'>
 
 export interface ReadAllNodesOptions {
   readonly label: string

package/src/admin/graph/nodes.ts

@@ -1,4 +1,4 @@
-import type { GraphApi } from '@astrale-os/kernel-client/graph'
+import type { GraphApi } from '@astrale-os/sdk/client'
 import type { Node } from '@astrale-os/sdk/graph/node'
 import type { QueryAST } from '@astrale-os/sdk/query'
 

package/src/admin/instance/.spec/api.d.ts

@@ -1,7 +1,4 @@
-import type { DomainBinding } from '@astrale-os/kernel-client/domain'
-import type { ClientSession } from '@astrale-os/kernel-client/session'
-
-import type { AdminGraphApi } from '../../graph/.spec/api.js'
+import type { ClientSession } from '@astrale-os/sdk/client/session'
 
 export type InstanceState = 'provisioning' | 'ready' | 'deleting' | 'failed' | 'deleted'
 
@@ -11,10 +8,11 @@ export interface InstanceInfo {
   readonly url: string
   readonly hostId?: string
   readonly region?: string
-  readonly state?: InstanceState
+  readonly state: InstanceState
   readonly phase?: string
   readonly error?: string | null
   readonly createdAt?: string
+  readonly updatedAt?: string
   readonly organizationId?: string
 }
 
@@ -33,12 +31,11 @@ export interface DomainInstallReceipt {
 
 export interface AdminInstanceContext {
   readonly session: ClientSession
-  readonly graph: AdminGraphApi
 }
 
 export interface AdminInstanceApi {
   list(): Promise<OwnedInstanceInfo[]>
-  create(slug: string, hostId?: string): Promise<InstanceInfo>
+  create(slug: string): Promise<InstanceInfo>
   status(identifier: string): Promise<InstanceInfo>
   delete(identifier: string): Promise<InstanceInfo>
   installDomain(identifier: string, domain: string): Promise<DomainInstallReceipt>
@@ -51,7 +48,6 @@ export class AdminInstanceNotFoundError extends Error {
 }
 
 export interface AdminInstanceDependencies {
-  readonly bind?: (session: ClientSession) => Promise<DomainBinding>
   readonly operationId?: (kind: 'create' | 'status' | 'delete' | 'install-domain') => string
 }
 
@@ -63,4 +59,4 @@ export function findOwnedInstance(
   instances: readonly OwnedInstanceInfo[],
   identifier: string,
 ): OwnedInstanceInfo | undefined
-export function formatInstanceLocation(info: InstanceInfo): string
+export function formatInstanceState(info: InstanceInfo): string

package/src/admin/instance/.spec/architecture.md

@@ -1,10 +1,10 @@
 # CLI Admin Instance adapter
 
-The adapter discovers and binds the configured Admin Domain, proves its origin, and resolves the
-singleton Fleet receiver. Policy-visible `Instance` and `Host` Nodes come from bounded Graph queries;
-Host location is joined through `instance_runs_on_host`.
+The adapter calls the stable singleton Fleet receiver directly. Listing and automatic creation are
+one Admin Method call each; connection performs no schema discovery, introspection, or graph read.
+Every returned summary is decoded locally before it reaches a command.
 
-Automatic creation invokes `Fleet.createInstance`; explicit `--host-id` resolves one visible,
-non-reserved Host and invokes `Host.createInstance`. Status, deletion, and Domain installation
-invoke the exact Instance receiver. The adapter creates internal operation IDs but preserves the
-existing CLI projection and selection-required experience.
+Automatic creation invokes `Fleet.createInstance`. Status, deletion, and Domain installation first
+resolve a caller-visible Instance through Fleet and then invoke that exact Instance receiver. The
+adapter creates internal operation IDs but preserves the existing CLI projection and
+selection-required experience.

package/src/admin/instance/__tests__/client.test.ts

@@ -1,135 +1,46 @@
-import type { Node } from '@astrale-os/sdk/graph/node'
-import type { QueryAST } from '@astrale-os/sdk/query'
-
-import { ClassPath } from '@astrale-os/sdk/graph/class'
-import { NodeId } from '@astrale-os/sdk/graph/node'
-import { Path } from '@astrale-os/sdk/graph/path'
-import { describe, expect, mock, test } from 'bun:test'
-
-import type { AdminBinding } from '../../binding'
-import type { AdminGraphApi } from '../../graph'
+import { describe, expect, test } from 'bun:test'
 
+import { adminSession } from '../../__tests__/fixture'
 import { connectAdminInstances } from '../client'
 
-const methods: Array<{ owner: string; name: string }> = []
-
-function definition(name: string) {
-  return {
-    name,
-    $: {
-      method(method: string) {
-        const value = { owner: name, name: method }
-        methods.push(value)
-        return value
-      },
-      property(property: string) {
-        return { key: property }
-      },
-    },
-  }
-}
-
-function node(id: string, props: Record<string, unknown>): Node {
-  return {
-    id: NodeId(id),
-    class: ClassPath.from('admin.astrale.ai', 'Instance'),
-    props: props as never,
-  }
-}
-
-function graphResult(nodes: readonly Node[], cursor?: string) {
-  return {
-    result: {
-      kind: 'nodes' as const,
-      nodes: nodes.map((value) => ({ kind: 'value' as const, value })),
-    },
-    page: cursor === undefined ? {} : { next: cursor },
-  }
-}
-
-function sourceName(ast: QueryAST): string | undefined {
-  const term = ast.source.terms[0]
-  return term?.kind === 'definition' ? term.definition.name : undefined
-}
-
-function fixture(input: {
-  instances?: readonly Node[]
-  hosts?: readonly Node[]
-  reserved?: Node | null
-  invoke?: (method: { owner: string; name: string }, receiver: unknown, input: unknown) => unknown
-}) {
-  methods.length = 0
-  const Instance = definition('Instance')
-  const Host = definition('Host')
-  const Fleet = definition('Fleet')
-  const invoke = mock(async (method: unknown, receiver: unknown, value: unknown) =>
-    input.invoke?.(method as { owner: string; name: string }, receiver, value),
-  )
-  const binding = {
-    $: {
-      publication: { origin: 'admin.astrale.ai' },
-      origin: 'admin.astrale.ai',
-      class(name: string) {
-        if (name === 'Instance') return Instance
-        if (name === 'Host') return Host
-        if (name === 'Fleet') return Fleet
-        throw new Error(`Unexpected class ${name}`)
-      },
-      core: { nodes: { fleet: { path: Path.id(NodeId('fleet')) } } },
-      invoke,
-    },
-  } as unknown as AdminBinding
-  const query = mock(async (ast: QueryAST) => {
-    const name = sourceName(ast)
-    if (name === 'Instance') return graphResult(input.instances ?? [])
-    if (name === 'Host') return graphResult(input.hosts ?? [])
-    throw new Error(`Unexpected graph query ${String(name)}`)
-  })
-  const neighbors = mock(async (source: unknown, edge: { name?: string }) => {
-    if (String(source) === '@fleet') return page(input.reserved ?? null)
-    if (edge.name === 'instance_runs_on_host') return page(input.hosts?.[0] ?? null)
-    throw new Error(`Unexpected neighbor query ${String(source)} ${String(edge)}`)
+function fixture(input: { invoke?: (target: string, input: unknown) => unknown }) {
+  const calls: Array<{
+    target: string
+    value: unknown
+  }> = []
+  const remote = adminSession((target, value) => {
+    calls.push({ target, value })
+    return input.invoke?.(target, value)
   })
-  const graph = { query, neighbors } as unknown as AdminGraphApi
   return {
-    binding,
-    graph,
-    invoke,
+    call: remote.call,
+    reflection: remote.reflection,
+    calls,
     connect: () =>
       connectAdminInstances(
-        { session: {} as never, graph },
+        { session: remote.session },
         {
-          bind: async () => binding,
           operationId: (kind) => `cli.instance.${kind}:test`,
         },
       ),
   }
 }
 
-function page(item: Node | null) {
-  return {
-    nodes: item === null ? [] : [item],
-    first: item,
-    graph: { nodes: item === null ? [] : [item], edges: [] },
-    cursor: null,
-  }
-}
-
 describe('V2 Admin Instance adapter', () => {
   test('lists caller-visible Instances through the Admin-owned Fleet operation', async () => {
     const contract = fixture({
-      invoke: (method) =>
-        method.name === 'listInstances'
+      invoke: (target) =>
+        target.endsWith('::listInstances')
           ? [
               {
                 id: '@instance-node',
                 slug: 'demo',
                 url: 'https://demo.eu.astrale.ai',
+                hostId: '@host-node',
+                region: 'fr-par',
                 state: 'ready',
                 createdAt: '2026-08-12T00:00:00.000Z',
                 updatedAt: '2026-08-12T00:00:00.000Z',
-                hostId: '@host-node',
-                region: 'fr-par',
               },
             ]
           : undefined,
@@ -140,17 +51,20 @@ describe('V2 Admin Instance adapter', () => {
         id: '@instance-node',
         slug: 'demo',
         url: 'https://demo.eu.astrale.ai',
-        state: 'ready',
-        createdAt: '2026-08-12T00:00:00.000Z',
         hostId: '@host-node',
         region: 'fr-par',
+        state: 'ready',
+        createdAt: '2026-08-12T00:00:00.000Z',
+        updatedAt: '2026-08-12T00:00:00.000Z',
       },
     ])
-    expect(contract.invoke).toHaveBeenCalledWith(
-      expect.objectContaining({ owner: 'Fleet', name: 'listInstances' }),
-      Path.id(NodeId('fleet')),
-      {},
-    )
+    expect(contract.calls).toEqual([
+      {
+        target: '/:admin.astrale.ai:core.fleet::listInstances',
+        value: {},
+      },
+    ])
+    expect(contract.reflection).not.toHaveBeenCalled()
   })
 
   test('delegates default placement to Fleet without reading Host inventory', async () => {
@@ -162,10 +76,7 @@ describe('V2 Admin Instance adapter', () => {
       createdAt: '2026-08-12T00:00:00.000Z',
       updatedAt: '2026-08-12T00:00:00.000Z',
     }
-    const contract = fixture({
-      hosts: [node('host-node', { id: 'host-paris', state: 'ready' })],
-      invoke: () => created,
-    })
+    const contract = fixture({ invoke: () => created })
 
     await expect((await contract.connect()).create('demo')).resolves.toMatchObject({
       id: created.id,
@@ -174,49 +85,18 @@ describe('V2 Admin Instance adapter', () => {
       state: created.state,
       createdAt: created.createdAt,
     })
-    expect(contract.invoke).toHaveBeenCalledWith(
-      expect.objectContaining({ owner: 'Fleet', name: 'createInstance' }),
-      Path.id(NodeId('fleet')),
-      { operationId: 'cli.instance.create:test', slug: 'demo' },
-    )
-    expect(contract.graph.query).not.toHaveBeenCalled()
-    expect(contract.graph.neighbors).not.toHaveBeenCalled()
-  })
-
-  test('resolves --host-id to an exact Host receiver and rejects the reserved Admin Host', async () => {
-    const reserved = node('admin-host', { id: 'admin', state: 'ready' })
-    const consumer = node('consumer-host', { id: 'consumer-paris', state: 'ready' })
-    const contract = fixture({
-      hosts: [reserved, consumer],
-      reserved,
-      invoke: () => ({
-        id: '@instance-node',
-        slug: 'demo',
-        url: 'https://demo.eu.astrale.ai',
-        state: 'ready',
-      }),
-    })
-    const api = await contract.connect()
-
-    await expect(api.create('demo', 'admin')).rejects.toMatchObject({ name: 'NotFoundError' })
-    await expect(api.create('demo', 'consumer-paris')).resolves.toMatchObject({ slug: 'demo' })
-    expect(contract.invoke).toHaveBeenCalledWith(
-      expect.objectContaining({ owner: 'Host', name: 'createInstance' }),
-      Path.id(NodeId('consumer-host')),
-      { operationId: 'cli.instance.create:test', slug: 'demo' },
-    )
+    expect(contract.calls).toEqual([
+      {
+        target: '/:admin.astrale.ai:core.fleet::createInstance',
+        value: { operationId: 'cli.instance.create:test', slug: 'demo' },
+      },
+    ])
   })
 
   test('refreshes and deletes through the resolved Instance receiver', async () => {
-    const instance = node('instance-node', {
-      slug: 'demo',
-      url: 'https://demo.eu.astrale.ai',
-      state: 'ready',
-    })
     const contract = fixture({
-      instances: [instance],
-      invoke: (method) =>
-        method.name === 'listInstances'
+      invoke: (target) =>
+        target.endsWith('::listInstances')
           ? [
               {
                 id: '@instance-node',
@@ -231,31 +111,34 @@ describe('V2 Admin Instance adapter', () => {
               id: '@instance-node',
               slug: 'demo',
               url: 'https://demo.eu.astrale.ai',
-              state: method.name === 'delete' ? 'deleted' : 'ready',
+              state: target.endsWith('::delete') ? 'deleted' : 'ready',
+              createdAt: '2026-08-12T00:00:00.000Z',
+              updatedAt: '2026-08-12T00:00:00.000Z',
             },
     })
     const api = await contract.connect()
 
     await expect(api.status('demo')).resolves.toMatchObject({ state: 'ready' })
     await expect(api.delete('@instance-node')).resolves.toMatchObject({ state: 'deleted' })
-    expect(contract.invoke.mock.calls.map(([method]) => method)).toEqual([
-      expect.objectContaining({ owner: 'Fleet', name: 'listInstances' }),
-      expect.objectContaining({ owner: 'Instance', name: 'status' }),
-      expect.objectContaining({ owner: 'Fleet', name: 'listInstances' }),
-      expect.objectContaining({ owner: 'Instance', name: 'delete' }),
+    expect(contract.calls).toEqual([
+      { target: '/:admin.astrale.ai:core.fleet::listInstances', value: {} },
+      {
+        target: '@instance-node::status',
+        value: { operationId: 'cli.instance.status:test' },
+      },
+      { target: '/:admin.astrale.ai:core.fleet::listInstances', value: {} },
+      {
+        target: '@instance-node::delete',
+        value: { operationId: 'cli.instance.delete:test' },
+      },
     ])
+    expect(contract.reflection).not.toHaveBeenCalled()
   })
 
   test('installs a resolved catalog Domain through Instance.installDomain', async () => {
-    const instance = node('instance-node', {
-      slug: 'demo',
-      url: 'https://demo.eu.astrale.ai',
-      state: 'ready',
-    })
     const contract = fixture({
-      instances: [instance],
-      invoke: (method) =>
-        method.name === 'listInstances'
+      invoke: (target) =>
+        target.endsWith('::listInstances')
           ? [
               {
                 id: '@instance-node',
@@ -282,10 +165,109 @@ describe('V2 Admin Instance adapter', () => {
       origin: 'crm.acme.dev',
       ok: true,
     })
-    expect(contract.invoke).toHaveBeenCalledWith(
-      expect.objectContaining({ owner: 'Instance', name: 'installDomain' }),
-      Path.id(NodeId('instance-node')),
-      { operationId: 'cli.instance.install-domain:test', domain: '@crm-domain' },
+    expect(contract.calls.at(-1)).toEqual({
+      target: '@instance-node::installDomain',
+      value: { operationId: 'cli.instance.install-domain:test', domain: '@crm-domain' },
+    })
+    expect(contract.reflection).not.toHaveBeenCalled()
+  })
+
+  test('connects without network I/O and list performs exactly one call', async () => {
+    const contract = fixture({ invoke: () => [] })
+
+    const api = await contract.connect()
+    expect(contract.call).not.toHaveBeenCalled()
+    expect(contract.reflection).not.toHaveBeenCalled()
+
+    await expect(api.list()).resolves.toEqual([])
+    expect(contract.call).toHaveBeenCalledTimes(1)
+    expect(contract.reflection).not.toHaveBeenCalled()
+  })
+
+  test('rejects malformed inventory, lifecycle, Method, and install outputs', async () => {
+    await expect((await fixture({ invoke: () => ({}) }).connect()).list()).rejects.toThrow(
+      'Admin Instance inventory is invalid.',
+    )
+    await expect(
+      (
+        await fixture({
+          invoke: () => [{ id: '@instance-node', slug: 'demo', state: 'mystery' }],
+        }).connect()
+      ).list(),
+    ).rejects.toThrow('Admin Instance state is invalid.')
+    await expect(
+      (
+        await fixture({
+          invoke: () => [{ id: 'not-a-path', slug: 'demo', state: 'ready' }],
+        }).connect()
+      ).list(),
+    ).rejects.toThrow('Admin Instance id is invalid.')
+    await expect(
+      (
+        await fixture({
+          invoke: () => [
+            { id: '@instance-node', slug: 'demo', hostId: 'not-a-path', state: 'ready' },
+          ],
+        }).connect()
+      ).list(),
+    ).rejects.toThrow('Admin Host id is invalid.')
+
+    const malformedStatus = fixture({
+      invoke: (target) =>
+        target.endsWith('::listInstances')
+          ? [
+              {
+                id: '@instance-node',
+                slug: 'demo',
+                state: 'ready',
+                createdAt: '2026-08-12T00:00:00.000Z',
+                updatedAt: '2026-08-12T00:00:00.000Z',
+              },
+            ]
+          : {
+              id: '@instance-node',
+              slug: 'demo',
+              state: 'ready',
+              failure: {},
+              createdAt: '2026-08-12T00:00:00.000Z',
+              updatedAt: '2026-08-12T00:00:00.000Z',
+            },
+    })
+    await expect((await malformedStatus.connect()).status('demo')).rejects.toThrow(
+      'Admin failure message is invalid.',
     )
+
+    const malformedInstall = fixture({
+      invoke: (target) =>
+        target.endsWith('::listInstances')
+          ? [
+              {
+                id: '@instance-node',
+                slug: 'demo',
+                state: 'ready',
+                createdAt: '2026-08-12T00:00:00.000Z',
+                updatedAt: '2026-08-12T00:00:00.000Z',
+              },
+            ]
+          : {
+              domain: '@crm-domain',
+              instance: '@instance-node',
+              origin: 'crm.acme.dev',
+              ok: 'yes',
+            },
+    })
+    await expect(
+      (await malformedInstall.connect()).installDomain('demo', '@crm-domain'),
+    ).rejects.toThrow('Admin Domain install outcome is invalid.')
+
+    const malformedInstallPath = fixture({
+      invoke: (target) =>
+        target.endsWith('::listInstances')
+          ? [{ id: '@instance-node', slug: 'demo', state: 'ready' }]
+          : { domain: 'not-a-path', instance: '@instance-node', origin: 'crm.acme.dev', ok: true },
+    })
+    await expect(
+      (await malformedInstallPath.connect()).installDomain('demo', '@crm-domain'),
+    ).rejects.toThrow('Admin Domain reference is invalid.')
   })
 })