@astrale-os/cli 0.6.2-alpha.0 → 0.7.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.6.2-alpha.0",
+  "version": "0.7.0-alpha.0",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",

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

@@ -1,9 +1,15 @@
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, mock, test } from 'bun:test'
 
 import type { IdentityStore } from '../../lib/identity'
 
 import { AuthError } from '../../errors'
-import { ADMIN_INSTANCE, adminInstanceMethod } from '../../lib/admin-instance'
+import {
+  ADMIN_INSTANCE,
+  adminInstanceMethod,
+  callOwnedInstances,
+  findOwnedInstance,
+  type OwnedInstanceInfo,
+} from '../../lib/admin-instance'
 import { assertAlphaCreateIdentity } from '../instance/create'
 
 describe('admin-backed instance commands', () => {
@@ -12,6 +18,47 @@ describe('admin-backed instance commands', () => {
     expect(adminInstanceMethod('list')).toBe('/:admin.astrale.ai:class.Instance:list')
   })
 
+  test('findOwnedInstance matches owner inventory by slug or stable node id', () => {
+    const owned = {
+      id: 'instance-node',
+      slug: 'demo',
+      url: 'https://demo.eu.astrale.ai',
+      state: 'failed',
+      organizationId: 'org_123',
+      hostId: 'host-1',
+      region: 'eu',
+      phase: 'installing:default-domains',
+      error: 'postInstall failed',
+      createdAt: '2026-07-16T00:00:00.000Z',
+    } satisfies OwnedInstanceInfo
+
+    expect(findOwnedInstance([owned], 'demo')).toBe(owned)
+    expect(findOwnedInstance([owned], 'instance-node')).toBe(owned)
+    expect(findOwnedInstance([owned], 'other')).toBeUndefined()
+  })
+
+  test('owner-scoped discovery calls listMine with an empty input', async () => {
+    const owned: OwnedInstanceInfo[] = [
+      {
+        id: 'instance-node',
+        slug: 'demo',
+        url: 'https://demo.eu.astrale.ai',
+        state: 'ready',
+      },
+    ]
+    const call = mock(async () => owned)
+
+    await expect(callOwnedInstances({ call })).resolves.toEqual([
+      {
+        id: 'instance-node',
+        slug: 'demo',
+        url: 'https://demo.eu.astrale.ai',
+        state: 'ready',
+      },
+    ])
+    expect(call).toHaveBeenCalledWith('/:admin.astrale.ai:class.Instance:listMine', {})
+  })
+
   test('instance create preflight points fresh installs at WorkOS login', () => {
     const store: IdentityStore = {
       default: 'manager',

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

@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
+
+import type { OwnedInstanceInfo } from '../../lib/admin-instance'
+
+import { adminDomainMethod } from '../../lib/admin-domain'
+import { adminInstanceMethod } from '../../lib/admin-instance'
+
+class ExitError extends Error {
+  constructor(readonly code: string | number | null | undefined) {
+    super(`process.exit(${String(code)})`)
+  }
+}
+
+const calls: Array<{ path: string; params: unknown }> = []
+let inventory: OwnedInstanceInfo[] = []
+
+const clientCall = mock(async (path: string, params: unknown): Promise<unknown> => {
+  calls.push({ path, params })
+  if (path === adminInstanceMethod('listMine')) return inventory
+  throw new Error(`Unexpected admin call: ${path}`)
+})
+
+mock.module('../../kernel', () => ({
+  runKernelCommand: mock(),
+}))
+
+mock.module('../../kernel/client', () => ({
+  withAdminKernelClient: async (
+    _opts: unknown,
+    run: (ctx: { client: { call: typeof clientCall } }) => Promise<unknown>,
+  ) => run({ client: { call: clientCall } }),
+}))
+
+let stderr = ''
+let originalExit: typeof process.exit
+let originalStderrWrite: typeof process.stderr.write
+
+beforeEach(() => {
+  calls.length = 0
+  inventory = []
+  stderr = ''
+  clientCall.mockClear()
+  originalExit = process.exit
+  originalStderrWrite = process.stderr.write.bind(process.stderr)
+  process.exit = ((code?: string | number | null) => {
+    throw new ExitError(code)
+  }) as typeof process.exit
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderr += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+    return true
+  }) as typeof process.stderr.write
+})
+
+afterEach(() => {
+  process.exit = originalExit
+  process.stderr.write = originalStderrWrite
+})
+
+async function runInstall(instance: string): Promise<void> {
+  const command = (await import('../domain/install')).default
+  const action = command.action as (
+    target: string | undefined,
+    opts: Record<string, unknown>,
+  ) => Promise<void>
+  await action('crm.acme.dev', {
+    instance,
+    json: true,
+    noPrompt: true,
+  })
+}
+
+describe('admin domain install owner boundary', () => {
+  test('rejects a foreign target after listMine without attempting an install', async () => {
+    inventory = [
+      {
+        id: 'owned-id',
+        slug: 'owned',
+        url: 'https://owned.eu.astrale.ai',
+        state: 'ready',
+      },
+    ]
+
+    await expect(runInstall('foreign')).rejects.toEqual(new ExitError(1))
+
+    expect(JSON.parse(stderr)).toMatchObject({
+      error: 'INSTANCE_NOT_MANAGED',
+      message: 'Instance "foreign" is not admin-managed (managed: owned).',
+    })
+    expect(calls).toEqual([{ path: adminInstanceMethod('listMine'), params: {} }])
+  })
+
+  test.each([
+    {
+      state: 'provisioning' as const,
+      phase: 'installing:default-domains',
+      error: undefined,
+    },
+    {
+      state: 'failed' as const,
+      phase: undefined,
+      error: 'postInstall failed',
+    },
+  ])('rejects an owned $state target before the install RPC', async (status) => {
+    inventory = [
+      {
+        id: `${status.state}-id`,
+        slug: 'owned',
+        url: 'https://owned.eu.astrale.ai',
+        ...status,
+      },
+    ]
+
+    await expect(runInstall('owned')).rejects.toEqual(new ExitError(1))
+
+    const payload = JSON.parse(stderr) as { error: string; message: string; hint?: string }
+    expect(payload.error).toBe('INSTANCE_NOT_READY')
+    expect(payload.message).toContain(`Instance "owned" is ${status.state}`)
+    expect(payload.hint).toBe(status.error ?? 'Run: astrale instance status owned')
+    expect(calls).toEqual([{ path: adminInstanceMethod('listMine'), params: {} }])
+    expect(calls.some((call) => call.path === adminDomainMethod('install'))).toBe(false)
+  })
+})

package/src/commands/__tests__/help-contract.test.ts

@@ -129,6 +129,21 @@ describe('help contract — read command split', () => {
   })
 })
 
+describe('help contract — payload sources', () => {
+  test('call excludes --file while mutate supports it', async () => {
+    const program = await buildProgram()
+    const call = allCommands(program).find((command) => command.name() === 'call')
+    const mutate = allCommands(program).find((command) => command.name() === 'mutate')
+    const callHelp = call?.helpInformation() ?? ''
+    const mutateHelp = mutate?.helpInformation() ?? ''
+
+    expect(callHelp).toContain('--data <json>')
+    expect(callHelp).not.toContain('--file <path>')
+    expect(mutateHelp).toContain('--data <json>')
+    expect(mutateHelp).toContain('--file <path>')
+  })
+})
+
 describe('help contract — skill is single-source, not duplicated', () => {
   const canonical = join(cliRoot, 'skills/astrale-cli/SKILL.md')
   // Workspace mirror lives in the superrepo, outside this submodule. Absent

package/src/commands/call.ts

@@ -261,7 +261,7 @@ Examples:
   $ astrale call /:host.astrale.ai:class.KernelInstance:list
   $ astrale call /:blog.acme.com:class.Author:list limit=10
   $ astrale call '@self::deactivate'
-  $ astrale call /:shell.astrale.ai:class.Application:available --json
+  $ astrale call /:shell.astrale.ai:function.search-domains --json
 `,
   arguments: [
     {

package/src/commands/domain/install.ts

@@ -8,7 +8,7 @@ import { AstraleError } from '../../errors'
 import { runKernelCommand } from '../../kernel'
 import { withAdminKernelClient } from '../../kernel/client'
 import { adminDomainMethod, type DomainInfo } from '../../lib/admin-domain'
-import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
+import { callOwnedInstances, type OwnedInstanceInfo } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { getActive } from '../../lib/instance'
 import { fatal, log, withSpinner } from '../../lib/log'
@@ -125,7 +125,7 @@ async function installViaAdmin(target: string | undefined, opts: InstallOpts): P
 
   try {
     await withAdminKernelClient(adminOpts, async (ctx) => {
-      const instances = (await ctx.client.call(adminInstanceMethod('list'), {})) as InstanceInfo[]
+      const instances = await callOwnedInstances(ctx.client)
 
       const ref = await resolveDomainRef(ctx, target, interactive)
       const slug = await resolveTargetSlug(opts, target, interactive, instances)
@@ -139,6 +139,7 @@ async function installViaAdmin(target: string | undefined, opts: InstallOpts): P
           `Install the url directly onto it instead: astrale domain install <url> --direct -i ${slug}`,
         )
       }
+      assertInstallTargetReady(match)
 
       const label = ref.origin ?? ref.url ?? 'domain'
       const result = await withSpinner(
@@ -168,10 +169,20 @@ async function installViaAdmin(target: string | undefined, opts: InstallOpts): P
       log.dim(`  url:    ${result.url}`)
     })
   } catch (e) {
-    fatal(e)
+    fatal(e, opts)
   }
 }
 
+function assertInstallTargetReady(instance: OwnedInstanceInfo): void {
+  if (instance.state === 'ready') return
+  const detail = instance.phase && instance.phase !== instance.state ? ` (${instance.phase})` : ''
+  throw new AstraleError(
+    'INSTANCE_NOT_READY',
+    `Instance "${instance.slug}" is ${instance.state}${detail}; domains cannot be installed yet.`,
+    instance.error ?? `Run: astrale instance status ${instance.slug}`,
+  )
+}
+
 /**
  * Classify the positional install target for the admin path: an http(s) URL
  * installs by `url`, anything else is treated as a catalog `origin` (the unique
@@ -219,7 +230,7 @@ async function resolveTargetSlug(
   opts: InstallOpts,
   target: string | undefined,
   interactive: boolean,
-  instances: InstanceInfo[],
+  instances: OwnedInstanceInfo[],
 ): Promise<string> {
   if (opts.instance) return opts.instance
   const active = await activeSlug()

package/src/commands/instance/active.ts

@@ -2,8 +2,8 @@ import chalk from 'chalk'
 
 import type { CommandDefinition } from '../../command'
 
-import { withAdminKernelClient } from '../../kernel/client'
-import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
+import { listOwnedInstances } from '../../kernel/client'
+import { findOwnedInstance } from '../../lib/admin-instance'
 import { getActive, normalizeInstanceKernelUrl } from '../../lib/instance'
 import { log } from '../../lib/log'
 import { RAW_OUTPUT_OPTIONS, isMachine, output, type RawOutputOpts } from '../../lib/output'
@@ -48,11 +48,8 @@ async function resolveActiveForDisplay(): Promise<{
   }
 
   try {
-    const managed = await withAdminKernelClient(
-      {},
-      async (ctx) =>
-        (await ctx.client.call(adminInstanceMethod('info'), { id: active.name })) as InstanceInfo,
-    )
+    const managed = findOwnedInstance(await listOwnedInstances({}), active.name)
+    if (!managed) return { name: active.name }
     return {
       name: managed.slug,
       url: normalizeInstanceKernelUrl(managed.url),

package/src/commands/instance/list.ts

@@ -4,11 +4,11 @@ import type { CommandDefinition } from '../../command'
 import type { KernelCommandOpts } from '../../kernel'
 import type { Column } from '../../lib/output'
 
-import { withAdminKernelClient } from '../../kernel/client'
+import { listOwnedInstances } from '../../kernel/client'
 import {
-  adminInstanceMethod,
   formatInstanceLocation,
   type InstanceInfo,
+  type OwnedInstanceInfo,
 } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { normalizeInstanceKernelUrl, readInstances } from '../../lib/instance'
@@ -59,14 +59,10 @@ export default {
         createdAt: entry.createdAt ?? null,
       }))
 
-      let managed: InstanceInfo[] = []
+      let managed: OwnedInstanceInfo[] = []
       if (!opts.bookmarked) {
         managed = await withSpinner('Fetching instances', !isMachine(opts), () =>
-          withAdminKernelClient(
-            opts,
-            async (ctx) =>
-              (await ctx.client.call(adminInstanceMethod('list'), {})) as InstanceInfo[],
-          ),
+          listOwnedInstances(opts),
         )
       }
       if (isMachine(opts)) {

package/src/commands/instance/status.ts

@@ -3,8 +3,9 @@ import chalk from 'chalk'
 import type { CommandDefinition } from '../../command'
 import type { KernelCommandOpts } from '../../kernel'
 
-import { withAdminKernelClient } from '../../kernel/client'
-import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
+import { AstraleError } from '../../errors'
+import { listOwnedInstances } from '../../kernel/client'
+import { findOwnedInstance } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { fatal, log, withSpinner } from '../../lib/log'
 import { isMachine, output, type RawOutputOpts } from '../../lib/output'
@@ -19,22 +20,26 @@ export default {
   action: async (id: string, opts: StatusOpts) => {
     try {
       const result = await withSpinner(`Fetching instance ${id}`, !isMachine(opts), () =>
-        withAdminKernelClient(
-          opts,
-          async (ctx) =>
-            (await ctx.client.call(adminInstanceMethod('info'), { id })) as InstanceInfo,
-        ),
+        listOwnedInstances(opts).then((instances) => {
+          const match = findOwnedInstance(instances, id)
+          if (match) return match
+          throw new AstraleError(
+            'INSTANCE_NOT_FOUND',
+            `No owned instance matches "${id}".`,
+            'Run `astrale instance list` to see your instances.',
+          )
+        }),
       )
       if (isMachine(opts)) {
         output(result, opts)
         return
       }
       console.log(`${chalk.bold(result.slug)} ${chalk.dim(result.url)}`)
-      if (result.state)
-        log.dim(`  state: ${result.state}${result.phase ? ` (${result.phase})` : ''}`)
+      log.dim(`  state: ${result.state}${result.phase ? ` (${result.phase})` : ''}`)
       if (result.error) log.dim(`  error: ${result.error}`)
       if (result.region) log.dim(`  region: ${result.region}`)
       if (result.hostId) log.dim(`  host: ${result.hostId}`)
+      if (result.organizationId) log.dim(`  organization: ${result.organizationId}`)
       if (result.createdAt) log.dim(`  created: ${result.createdAt}`)
     } catch (e) {
       fatal(e, opts)

package/src/commands/instance/use.ts

@@ -1,8 +1,8 @@
 import type { CommandDefinition } from '../../command'
+import type { OwnedInstanceInfo } from '../../lib/admin-instance'
 
 import { AstraleError } from '../../errors'
-import { withAdminKernelClient } from '../../kernel/client'
-import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
+import { listOwnedInstances } from '../../kernel/client'
 import { ADMIN_TARGET_OPTIONS } from '../../lib/admin-target'
 import { getDefault, setDefault } from '../../lib/identity'
 import {
@@ -121,7 +121,12 @@ async function resolveUseTarget(name: string, opts: UseOpts): Promise<ResolvedIn
   }
 
   assertManagedReady(chosen.info)
-  const { repointedFrom } = await upsertManagedBookmark(chosen.key, chosen.info.slug, chosen.url)
+  const { repointedFrom } = await upsertManagedBookmark(
+    chosen.key,
+    chosen.info.slug,
+    chosen.url,
+    chosen.info.organizationId,
+  )
   if (repointedFrom) {
     log.warn(`Bookmark "${chosen.key}" repointed: ${repointedFrom} → ${chosen.url}`)
   }
@@ -133,29 +138,26 @@ async function resolveUseTarget(name: string, opts: UseOpts): Promise<ResolvedIn
  * Best-effort: an unreachable or unauthenticated admin kernel degrades to
  * bookmark-only resolution.
  */
-async function fetchManagedInstances(name: string, opts: UseOpts): Promise<InstanceInfo[]> {
+async function fetchManagedInstances(name: string, opts: UseOpts): Promise<OwnedInstanceInfo[]> {
   try {
     validateSlug(name)
   } catch {
     return []
   }
   try {
-    return await withAdminKernelClient(
-      opts,
-      async (ctx) => (await ctx.client.call(adminInstanceMethod('list'), {})) as InstanceInfo[],
-    )
+    return await listOwnedInstances(opts)
   } catch {
     return []
   }
 }
 
-function assertManagedReady(info: InstanceInfo): void {
-  if (!info.state || info.state === 'ready') return
+function assertManagedReady(info: OwnedInstanceInfo): void {
+  if (info.state === 'ready') return
   const detail = info.phase && info.phase !== info.state ? ` (${info.phase})` : ''
   throw new AstraleError(
     'INSTANCE_NOT_READY',
     `Instance "${info.slug}" is ${info.state}${detail}; it cannot be selected yet.`,
-    info.error ?? undefined,
+    info.error ?? `Run: astrale instance status ${info.slug}`,
   )
 }
 

package/src/commands/view.ts

@@ -18,6 +18,7 @@ import { fatal, log } from '../lib/log'
 import { isMachine, output, type RawOutputOpts } from '../lib/output'
 import { findFreePort } from '../lib/port'
 import { run, spawnHandle } from '../lib/proc'
+import { withViewPortAllocationLock } from '../lib/view/port-allocation'
 import {
   applyViewUrlOverride,
   candidateSlug,
@@ -232,16 +233,45 @@ async function startSession(
   await ensureViewerAssets()
   const config = await readConfig()
   const kernelTarget = await resolveKernelTarget(opts, config)
+  const [instances, identities, runtime] = await Promise.all([
+    readInstances(),
+    readIdentities(),
+    resolveServeRuntime(),
+  ])
+  return withViewPortAllocationLock(() =>
+    startSessionLocked(
+      view,
+      target,
+      opts,
+      kernelTarget,
+      instances.active,
+      identities.default,
+      runtime,
+    ),
+  )
+}
+
+/**
+ * Called under the cross-process port-allocation lock. Keep the lock until the
+ * detached child answers its readiness probe: only then is the selected port
+ * durably owned and safe for the next CLI process to scan.
+ */
+async function startSessionLocked(
+  view: ResolvedView,
+  target: ResolvedTarget | undefined,
+  opts: ViewOpts,
+  kernelTarget: { url: string; caFile?: string },
+  activeInstance: string | undefined,
+  defaultIdentity: string | undefined,
+  runtime: { file: string; args: string[] },
+): Promise<ViewSessionRecord> {
   const port = await findFreePort(VIEW_PORT_BASE, VIEW_PORT_SPAN)
   if (port === null) {
-    fatal(
-      new Error(
-        `No free port in ${VIEW_PORT_BASE}-${VIEW_PORT_BASE + VIEW_PORT_SPAN - 1} — close sessions with \`astrale view --close --all\``,
-      ),
+    throw new Error(
+      `No free port in ${VIEW_PORT_BASE}-${VIEW_PORT_BASE + VIEW_PORT_SPAN - 1} — close sessions with \`astrale view --close --all\``,
     )
   }
 
-  const [instances, identities] = await Promise.all([readInstances(), readIdentities()])
   const id = `v-${randomBytes(3).toString('hex')}`
   const nonce = randomBytes(12).toString('hex')
   const record: ViewSessionRecord = {
@@ -252,8 +282,8 @@ async function startSession(
     pageUrl: `http://127.0.0.1:${port}/s/${nonce}/`,
     view,
     target,
-    instance: opts.instance ?? (opts.url ? opts.url : instances.active),
-    identity: opts.creds ? '(pre-signed creds)' : (opts.as ?? identities.default),
+    instance: opts.instance ?? (opts.url ? opts.url : activeInstance),
+    identity: opts.creds ? '(pre-signed creds)' : (opts.as ?? defaultIdentity),
     createdAt: new Date().toISOString(),
   }
   const serveConfig: ViewServeConfig = {
@@ -276,7 +306,6 @@ async function startSession(
   await mkdir(VIEW_DIR, { recursive: true })
   await writeFile(configPath(id), JSON.stringify(serveConfig, null, 2))
   const logFd = openSync(logPath(id), 'a')
-  const runtime = await resolveServeRuntime()
   const child = spawnHandle(
     runtime.file,
     [...runtime.args, '__view-serve', '--config', configPath(id)],
@@ -287,7 +316,7 @@ async function startSession(
   )
   child.unref()
   closeSync(logFd)
-  if (!child.pid) fatal(new Error('Failed to spawn the view session server'))
+  if (!child.pid) throw new Error('Failed to spawn the view session server')
   const live = { ...record, pid: child.pid }
   await saveRecord(live)
 
@@ -304,10 +333,8 @@ async function startSession(
   }
   const tail = await readFile(logPath(id), 'utf8').catch(() => '')
   await closeSession(live)
-  return fatal(
-    new Error(
-      `View session server did not come up.${tail ? `\n--- server log ---\n${tail.slice(-2000)}` : ''}`,
-    ),
+  throw new Error(
+    `View session server did not come up.${tail ? `\n--- server log ---\n${tail.slice(-2000)}` : ''}`,
   )
 }
 

package/src/kernel/__tests__/client-owned-lookup.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, mock, test } from 'bun:test'
+
+import type { OwnedInstanceInfo } from '../../lib/admin-instance'
+import type { AdminTargetCommandOpts } from '../../lib/admin-target'
+import type { KernelCommandOpts } from '../types'
+
+import { lookupImplicitOwnedInstance } from '../client'
+
+describe('implicit managed target owner discovery', () => {
+  test('keeps target credentials out of the admin inventory lookup', async () => {
+    const owned: OwnedInstanceInfo = {
+      id: 'owned-id',
+      slug: 'owned',
+      url: 'https://owned.eu.astrale.ai',
+      state: 'ready',
+    }
+    let captured:
+      | {
+          slug: string
+          opts: KernelCommandOpts & AdminTargetCommandOpts
+        }
+      | undefined
+    const lookupOwned = mock(
+      async (slug: string, opts: KernelCommandOpts & AdminTargetCommandOpts) => {
+        captured = { slug, opts }
+        return owned
+      },
+    )
+
+    await lookupImplicitOwnedInstance(
+      'owned',
+      {
+        as: 'target-identity',
+        creds: 'target-delegation',
+        timeout: '45000',
+        debug: true,
+      },
+      { lookupOwned },
+    )
+
+    expect(captured).toEqual({
+      slug: 'owned',
+      opts: {
+        timeout: '45000',
+        debug: true,
+      },
+    })
+    expect(captured?.opts).not.toHaveProperty('as')
+    expect(captured?.opts).not.toHaveProperty('creds')
+  })
+})