@astrale-os/cli 0.8.0-alpha.0 → 0.8.1-alpha.2

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

@@ -0,0 +1,289 @@
+import type { DomainBinding } from '@astrale-os/kernel-client/domain'
+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 { AdminGraphApi } from '../../graph'
+
+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 DomainBinding
+  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)}`)
+  })
+  const graph = { query, neighbors } as unknown as AdminGraphApi
+  return {
+    binding,
+    graph,
+    invoke,
+    connect: () =>
+      connectAdminInstances(
+        { session: {} as never, graph },
+        {
+          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'
+          ? [
+              {
+                id: '@instance-node',
+                slug: 'demo',
+                url: 'https://demo.eu.astrale.ai',
+                state: 'ready',
+                createdAt: '2026-08-12T00:00:00.000Z',
+                updatedAt: '2026-08-12T00:00:00.000Z',
+                hostId: '@host-node',
+                region: 'fr-par',
+              },
+            ]
+          : undefined,
+    })
+
+    await expect((await contract.connect()).list()).resolves.toEqual([
+      {
+        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',
+      },
+    ])
+    expect(contract.invoke).toHaveBeenCalledWith(
+      expect.objectContaining({ owner: 'Fleet', name: 'listInstances' }),
+      Path.id(NodeId('fleet')),
+      {},
+    )
+  })
+
+  test('invokes Fleet.createInstance with an internal operation identity', async () => {
+    const created = {
+      id: '@instance-node',
+      slug: 'demo',
+      url: 'https://demo.eu.astrale.ai',
+      state: 'ready',
+      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,
+    })
+
+    await expect((await contract.connect()).create('demo')).resolves.toMatchObject({
+      id: created.id,
+      slug: created.slug,
+      url: created.url,
+      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' },
+    )
+  })
+
+  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' },
+    )
+  })
+
+  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'
+          ? [
+              {
+                id: '@instance-node',
+                slug: 'demo',
+                url: 'https://demo.eu.astrale.ai',
+                state: 'ready',
+                createdAt: '2026-08-12T00:00:00.000Z',
+                updatedAt: '2026-08-12T00:00:00.000Z',
+              },
+            ]
+          : {
+              id: '@instance-node',
+              slug: 'demo',
+              url: 'https://demo.eu.astrale.ai',
+              state: method.name === 'delete' ? 'deleted' : 'ready',
+            },
+    })
+    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' }),
+    ])
+  })
+
+  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'
+          ? [
+              {
+                id: '@instance-node',
+                slug: 'demo',
+                url: 'https://demo.eu.astrale.ai',
+                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: true,
+              installedRevision: `sha256:${'a'.repeat(64)}`,
+            },
+    })
+    const api = await contract.connect()
+
+    await expect(api.installDomain('demo', '@crm-domain')).resolves.toMatchObject({
+      domain: '@crm-domain',
+      instance: '@instance-node',
+      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' },
+    )
+  })
+})

package/src/admin/instance/client.ts

@@ -0,0 +1,298 @@
+import type { DomainBinding } from '@astrale-os/kernel-client/domain'
+import type { ClientSession } from '@astrale-os/kernel-client/session'
+import type { Node } from '@astrale-os/sdk/graph/node'
+
+import { bind } from '@astrale-os/kernel-client/domain'
+import { Path } from '@astrale-os/sdk/graph/path'
+import { Query } from '@astrale-os/sdk/query'
+
+import { readAllNodes, type AdminGraphApi } from '../graph'
+import {
+  AdminHostNotFoundError,
+  AdminInstanceNotFoundError,
+  findOwnedInstance,
+  type DomainInstallReceipt,
+  type InstanceInfo,
+  type InstanceState,
+  type OwnedInstanceInfo,
+} from './model'
+
+const ADMIN_ORIGIN = 'admin.astrale.ai'
+const PAGE_SIZE = 256
+const MAXIMUM_INSTANCES = 10_000
+const MAXIMUM_PAGES = Math.ceil(MAXIMUM_INSTANCES / PAGE_SIZE) + 1
+
+const HostRef = Object.freeze({ origin: ADMIN_ORIGIN, kind: 'class' as const, name: 'Host' })
+const fleetReservesAdminHost = Object.freeze({
+  origin: ADMIN_ORIGIN,
+  kind: 'class' as const,
+  name: 'fleet_reserves_admin_host',
+})
+
+export interface AdminInstanceContext {
+  readonly session: ClientSession
+  readonly graph: AdminGraphApi
+}
+
+export interface AdminInstanceApi {
+  list(): Promise<OwnedInstanceInfo[]>
+  create(slug: string, hostId?: string): Promise<InstanceInfo>
+  status(identifier: string): Promise<InstanceInfo>
+  delete(identifier: string): Promise<InstanceInfo>
+  installDomain(identifier: string, domain: string): Promise<DomainInstallReceipt>
+}
+
+export interface AdminInstanceDependencies {
+  readonly bind?: (session: ClientSession) => Promise<DomainBinding>
+  readonly operationId?: (kind: 'create' | 'status' | 'delete' | 'install-domain') => string
+}
+
+/**
+ * Bind one discovered Admin root revision and expose only the public Instance
+ * product journey. No Host lifecycle method is present on this capability.
+ */
+export async function connectAdminInstances(
+  context: AdminInstanceContext,
+  dependencies: AdminInstanceDependencies = {},
+): Promise<AdminInstanceApi> {
+  const binding = await (dependencies.bind ?? bindInstalledAdmin)(context.session)
+  if (binding.$.publication?.origin !== ADMIN_ORIGIN || binding.$.origin !== ADMIN_ORIGIN) {
+    throw new TypeError('Configured Admin target does not serve the Admin Domain.')
+  }
+
+  const Instance = binding.$.class('Instance')
+  const Host = binding.$.class('Host')
+  const Fleet = binding.$.class('Fleet')
+  const fleet = binding.$.core.nodes.fleet?.path
+  if (fleet === undefined) throw new TypeError('Admin Domain has no singleton Fleet receiver.')
+
+  const operationId = dependencies.operationId ?? defaultOperationId
+
+  const list = async (): Promise<OwnedInstanceInfo[]> => {
+    const result: unknown = await binding.$.invoke(
+      Fleet.$.method('listInstances') as never,
+      fleet,
+      {} as never,
+    )
+    if (!Array.isArray(result)) throw new TypeError('Admin Instance inventory is invalid.')
+    return result.map((value) => instanceFromSummary(value) as OwnedInstanceInfo)
+  }
+
+  const requireInstance = async (identifier: string): Promise<OwnedInstanceInfo> => {
+    const found = findOwnedInstance(await list(), identifier)
+    if (found === undefined) throw new AdminInstanceNotFoundError(identifier)
+    return found
+  }
+
+  const invokeInstance = async (
+    method: 'status' | 'delete',
+    identifier: string,
+  ): Promise<InstanceInfo> => {
+    const instance = await requireInstance(identifier)
+    const output = await binding.$.invoke(
+      Instance.$.method(method) as never,
+      Path.parse(instance.id),
+      { operationId: operationId(method) } as never,
+    )
+    return instanceFromSummary(output)
+  }
+
+  return Object.freeze({
+    list,
+    async create(slug: string, hostId?: string) {
+      const input = Object.freeze({
+        operationId: operationId('create'),
+        slug,
+      })
+      if (hostId !== undefined) {
+        const selected = await hostInventory(context.graph, binding, Host, fleet)
+        const host = selected.hosts.find(
+          (item) => item.id === hostId && item.state === 'ready' && item.path !== selected.reserved,
+        )
+        if (host === undefined) throw new AdminHostNotFoundError(hostId)
+        return instanceFromSummary(
+          await binding.$.invoke(
+            Host.$.method('createInstance') as never,
+            Path.parse(host.path),
+            input as never,
+          ),
+        )
+      }
+
+      // Preserve the existing interactive multi-Host picker without accepting a
+      // doomed operation first. Graph read policy exposes only caller-usable
+      // Hosts; the reserved Admin Host is excluded explicitly.
+      const inventory = await hostInventory(context.graph, binding, Host, fleet)
+      const eligible = inventory.hosts.filter(
+        (host) => host.state === 'ready' && host.path !== inventory.reserved,
+      )
+      if (eligible.length > 1) throw hostSelectionRequired(eligible.map((host) => host.id))
+
+      return instanceFromSummary(
+        await binding.$.invoke(Fleet.$.method('createInstance') as never, fleet, input as never),
+      )
+    },
+    status: (identifier: string) => invokeInstance('status', identifier),
+    delete: (identifier: string) => invokeInstance('delete', identifier),
+    async installDomain(identifier: string, domain: string): Promise<DomainInstallReceipt> {
+      const instance = await requireInstance(identifier)
+      const output = await binding.$.invoke(
+        Instance.$.method('installDomain') as never,
+        Path.parse(instance.id),
+        {
+          operationId: operationId('install-domain'),
+          domain: Path.parse(domain).raw,
+        } as never,
+      )
+      return domainInstallReceipt(output)
+    },
+  })
+}
+
+async function bindInstalledAdmin(session: ClientSession): Promise<DomainBinding> {
+  return bind(session, await session.installed(ADMIN_ORIGIN))
+}
+
+interface HostInventoryItem {
+  readonly id: string
+  readonly nodeId: string
+  readonly path: string
+  readonly state: string
+}
+
+async function hostInventory(
+  graph: AdminGraphApi,
+  binding: DomainBinding,
+  Host: ReturnType<DomainBinding['$']['class']>,
+  fleet: Path,
+): Promise<{ readonly hosts: readonly HostInventoryItem[]; readonly reserved?: string }> {
+  const [nodes, reservedPage] = await Promise.all([
+    readAllNodes(
+      graph,
+      Query.from({ kind: 'node', definitions: [HostRef] }).select({
+        kind: 'nodes',
+        projection: { kind: 'value' },
+      }),
+      {
+        label: 'Admin Host inventory',
+        maximum: MAXIMUM_INSTANCES,
+        maximumPages: MAXIMUM_PAGES,
+      },
+    ),
+    graph.neighbors(fleet, fleetReservesAdminHost, {
+      direction: 'outgoing',
+      page: { size: 1 },
+    }),
+  ])
+  const reserved = reservedPage.first === null ? undefined : Path.id(reservedPage.first.id).raw
+  return Object.freeze({
+    hosts: Object.freeze(
+      nodes.map((node) =>
+        Object.freeze({
+          id: requiredStringProperty(Host, node, 'id'),
+          nodeId: String(node.id),
+          path: Path.id(node.id).raw,
+          state: requiredStringProperty(Host, node, 'state'),
+        }),
+      ),
+    ),
+    ...(reserved === undefined ? {} : { reserved }),
+  })
+}
+
+function hostSelectionRequired(ids: readonly string[]): Error {
+  return new Error(
+    `alphaCreate could not choose a host: ${ids.length} ready hosts are assigned (${[...ids].sort().join(', ')}). ` +
+      'Specify host_id once multi-host placement is enabled.',
+  )
+}
+
+type DynamicDefinition = ReturnType<DomainBinding['$']['class']>
+
+function instanceFromSummary(input: unknown): InstanceInfo {
+  const value = record(input, 'Admin Instance summary')
+  const failure = value.failure === undefined ? undefined : record(value.failure, 'Admin failure')
+  return Object.freeze({
+    id: requiredString(value.id, 'Admin Instance id'),
+    slug: requiredString(value.slug, 'Admin Instance slug'),
+    url: optionalStringValue(value.url) ?? '',
+    state: instanceState(value.state),
+    ...(value.hostId === undefined
+      ? {}
+      : { hostId: requiredString(value.hostId, 'Admin Host id') }),
+    ...(value.region === undefined ? {} : { region: requiredString(value.region, 'Admin region') }),
+    ...(value.phase === undefined
+      ? {}
+      : { phase: requiredString(value.phase, 'Admin Instance phase') }),
+    ...(failure === undefined
+      ? {}
+      : { error: requiredString(failure.message, 'Admin failure message') }),
+    ...(value.createdAt === undefined
+      ? {}
+      : { createdAt: requiredString(value.createdAt, 'Admin Instance creation time') }),
+    ...(value.organizationId === undefined
+      ? {}
+      : { organizationId: requiredString(value.organizationId, 'Admin organization id') }),
+  })
+}
+
+function domainInstallReceipt(input: unknown): DomainInstallReceipt {
+  const value = record(input, 'Admin Domain install receipt')
+  const failure = value.failure === undefined ? undefined : record(value.failure, 'Admin failure')
+  if (typeof value.ok !== 'boolean') throw new TypeError('Admin Domain install outcome is invalid.')
+  return Object.freeze({
+    domain: requiredString(value.domain, 'Admin Domain reference'),
+    instance: requiredString(value.instance, 'Admin Instance reference'),
+    origin: requiredString(value.origin, 'Installed Domain origin'),
+    ok: value.ok,
+    ...(value.installedRevision === undefined
+      ? {}
+      : {
+          installedRevision: requiredString(value.installedRevision, 'Installed Domain revision'),
+        }),
+    ...(failure === undefined
+      ? {}
+      : { error: requiredString(failure.message, 'Admin Domain install failure') }),
+  })
+}
+
+function requiredStringProperty(definition: DynamicDefinition, node: Node, name: string): string {
+  return requiredString(
+    node.props[definition.$.property(name).key],
+    `Admin ${definition.name}.${name}`,
+  )
+}
+
+function instanceState(input: unknown): InstanceState {
+  if (
+    input === 'provisioning' ||
+    input === 'ready' ||
+    input === 'deleting' ||
+    input === 'failed' ||
+    input === 'deleted'
+  ) {
+    return input
+  }
+  throw new TypeError('Admin Instance state is invalid.')
+}
+
+function requiredString(input: unknown, label: string): string {
+  if (typeof input !== 'string' || input.length === 0) throw new TypeError(`${label} is invalid.`)
+  return input
+}
+
+function optionalStringValue(input: unknown): string | undefined {
+  if (input === undefined) return undefined
+  return requiredString(input, 'Admin string value')
+}
+
+function record(input: unknown, label: string): Readonly<Record<string, unknown>> {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    throw new TypeError(`${label} is invalid.`)
+  }
+  return input as Readonly<Record<string, unknown>>
+}
+
+function defaultOperationId(kind: 'create' | 'status' | 'delete' | 'install-domain'): string {
+  return `cli.instance.${kind}:${globalThis.crypto.randomUUID()}`
+}

package/src/admin/instance/index.ts

@@ -0,0 +1,16 @@
+export {
+  connectAdminInstances,
+  type AdminInstanceApi,
+  type AdminInstanceContext,
+  type AdminInstanceDependencies,
+} from './client'
+export {
+  AdminHostNotFoundError,
+  AdminInstanceNotFoundError,
+  findOwnedInstance,
+  formatInstanceLocation,
+  type DomainInstallReceipt,
+  type InstanceInfo,
+  type InstanceState,
+  type OwnedInstanceInfo,
+} from './model'

package/src/admin/instance/model.ts

@@ -0,0 +1,65 @@
+/** CLI-stable projection of one caller-visible Admin Instance. */
+export type InstanceState = 'provisioning' | 'ready' | 'deleting' | 'failed' | 'deleted'
+
+export interface InstanceInfo {
+  readonly id: string
+  readonly slug: string
+  readonly url: string
+  readonly hostId?: string
+  readonly region?: string
+  readonly state?: InstanceState
+  readonly phase?: string
+  readonly error?: string | null
+  readonly createdAt?: string
+  readonly organizationId?: string
+}
+
+/** An Instance returned through the caller-scoped Admin graph inventory. */
+export interface OwnedInstanceInfo extends InstanceInfo {
+  readonly state: InstanceState
+}
+
+export interface DomainInstallReceipt {
+  readonly domain: string
+  readonly instance: string
+  readonly origin: string
+  readonly ok: boolean
+  readonly installedRevision?: string
+  readonly error?: string
+}
+
+export class AdminInstanceNotFoundError extends Error {
+  readonly name = 'NotFoundError'
+
+  constructor(readonly identifier: string) {
+    super(`No owned Admin Instance matches ${JSON.stringify(identifier)}.`)
+  }
+}
+
+export class AdminHostNotFoundError extends Error {
+  readonly name = 'NotFoundError'
+
+  constructor(readonly identifier: string) {
+    super(`No caller-usable Admin Host matches ${JSON.stringify(identifier)}.`)
+  }
+}
+
+/** Match an owner-scoped Instance by slug, canonical Node Path, or bare Node id. */
+export function findOwnedInstance(
+  instances: readonly OwnedInstanceInfo[],
+  identifier: string,
+): OwnedInstanceInfo | undefined {
+  return instances.find(
+    (instance) =>
+      instance.slug === identifier ||
+      instance.id === identifier ||
+      (instance.id.startsWith('@') && instance.id.slice(1) === identifier),
+  )
+}
+
+/** Human-readable location of an Instance (state, region, and Host Path). */
+export function formatInstanceLocation(info: InstanceInfo): string {
+  return [info.state && info.state !== 'ready' ? info.state : undefined, info.region, info.hostId]
+    .filter(Boolean)
+    .join(' · ')
+}

package/src/admin/instance/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "types": ["@types/node"]
+  },
+  "include": ["*.ts"],
+  "exclude": ["__tests__"]
+}