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

package/src/kernel/client.ts

@@ -5,7 +5,12 @@ import type { AdminTargetCommandOpts } from '../lib/admin-target'
 import type { KernelCommandOpts } from './types'
 
 import { AstraleError } from '../errors'
-import { adminInstanceMethod, type InstanceInfo } from '../lib/admin-instance'
+import {
+  callOwnedInstances,
+  findOwnedInstance,
+  type InstanceInfo,
+  type OwnedInstanceInfo,
+} from '../lib/admin-instance'
 import { readConfig } from '../lib/config'
 import { resolveInstanceTarget, type ResolvedInstanceTarget } from '../lib/instance-target'
 import { resolveCredential } from './auth'
@@ -37,18 +42,15 @@ export async function resolveKernelTarget(
   // Ad-hoc `--url` — unknown kernel. Stamp the URL itself as audience,
   // no slug for per-instance signing.
   if (opts.url && !opts.instance) {
-    const resolved = await resolveInstanceTarget(
-      { source: 'url', url: opts.url },
-      { config, admin: adminLookupOpts(opts) },
-    )
+    const resolved = await resolveInstanceTarget({ source: 'url', url: opts.url }, { config })
     return resolvedToKernelTarget(resolved)
   }
   const resolved = await resolveInstanceTarget(
     opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
     {
       config,
-      admin: adminLookupOpts(opts),
-      managed: (slug) => lookupManagedInstance(slug, opts),
+      admin: {},
+      managed: (slug) => lookupImplicitOwnedInstance(slug, opts),
     },
   )
   return resolvedToKernelTarget(resolved, opts.url)
@@ -68,21 +70,46 @@ export async function withKernelClient<T>(
   return withResolvedKernelClient(opts, config, target, fn)
 }
 
-async function lookupManagedInstance(slug: string, opts: KernelCommandOpts): Promise<InstanceInfo> {
-  return await withAdminKernelClient(
-    adminLookupOpts(opts),
-    async (ctx) =>
-      (await ctx.client.call(adminInstanceMethod('info'), { id: slug })) as InstanceInfo,
-  )
+export async function listOwnedInstances(
+  opts: KernelCommandOpts & AdminTargetCommandOpts,
+): Promise<OwnedInstanceInfo[]> {
+  return await withAdminKernelClient(opts, async (ctx) => callOwnedInstances(ctx.client))
 }
 
-function adminLookupOpts(opts: KernelCommandOpts): KernelCommandOpts & AdminTargetCommandOpts {
-  return {
-    as: opts.as,
-    creds: opts.creds,
-    timeout: opts.timeout,
-    debug: opts.debug,
-  }
+export async function lookupOwnedInstance(
+  slug: string,
+  opts: KernelCommandOpts & AdminTargetCommandOpts,
+): Promise<OwnedInstanceInfo> {
+  const instance = findOwnedInstance(await listOwnedInstances(opts), slug)
+  if (instance) return instance
+  throw new AstraleError('INSTANCE_NOT_FOUND', `No owned instance matches "${slug}".`)
+}
+
+export type ImplicitOwnedInstanceLookupDependencies = {
+  lookupOwned: (
+    slug: string,
+    opts: KernelCommandOpts & AdminTargetCommandOpts,
+  ) => Promise<OwnedInstanceInfo>
+}
+
+/**
+ * Resolve an implicit managed target through the caller's owner inventory.
+ *
+ * Target `--as` / `--creds` belong to the eventual child-kernel call. They
+ * must not authenticate the admin discovery request: leaving them out lets
+ * `withAdminKernelClient` use the admin bookmark's default WorkOS identity.
+ */
+export async function lookupImplicitOwnedInstance(
+  slug: string,
+  targetOpts: KernelCommandOpts,
+  deps: ImplicitOwnedInstanceLookupDependencies = {
+    lookupOwned: lookupOwnedInstance,
+  },
+): Promise<InstanceInfo> {
+  return await deps.lookupOwned(slug, {
+    timeout: targetOpts.timeout,
+    debug: targetOpts.debug,
+  })
 }
 
 function resolvedToKernelTarget(

package/src/kernel/expand.ts

@@ -1,7 +1,5 @@
-import type { InstanceInfo } from '../lib/admin-instance'
 import type { KernelCommandOpts } from './types'
 
-import { adminInstanceMethod } from '../lib/admin-instance'
 /** CLI bridge for @self resolution and stale-registration error hints. */
 import { readConfig } from '../lib/config'
 import { getDefault, getIdentity, setRegistration } from '../lib/identity'
@@ -17,7 +15,7 @@ import {
   type SelfResolverContext,
   type SelfResolution,
 } from '../lib/self'
-import { withAdminKernelClient, withKernelClient } from './client'
+import { lookupImplicitOwnedInstance, withKernelClient } from './client'
 
 /** Metadata attached to errors so the NotFoundError path can hint at stale `@self` expansions. */
 export type SelfExpansionMeta = {
@@ -41,8 +39,8 @@ export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfRes
       opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
       {
         config,
-        admin: adminLookupOpts(opts),
-        managed: (instanceSlug) => lookupManagedInstance(instanceSlug, opts),
+        admin: {},
+        managed: (instanceSlug) => lookupImplicitOwnedInstance(instanceSlug, opts),
       },
     )
     slug = resolved.name
@@ -83,23 +81,6 @@ export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfRes
   return { identity, instanceSlug: slug, credsJwt: opts.creds, instanceSigned, idpSubject }
 }
 
-function adminLookupOpts(opts: KernelCommandOpts): KernelCommandOpts {
-  return {
-    as: opts.as,
-    creds: opts.creds,
-    timeout: opts.timeout,
-    debug: opts.debug,
-  }
-}
-
-async function lookupManagedInstance(slug: string, opts: KernelCommandOpts): Promise<InstanceInfo> {
-  return await withAdminKernelClient(
-    adminLookupOpts(opts),
-    async (ctx) =>
-      (await ctx.client.call(adminInstanceMethod('info'), { id: slug })) as InstanceInfo,
-  )
-}
-
 /**
  * Run `fn`; if it throws a `NotFoundError`, stamp expansion metadata onto the
  * error so `formatKernelError` can append the stale-registration hint. The

package/src/lib/__tests__/instance-candidates.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 
-import type { InstanceInfo } from '../admin-instance'
+import type { OwnedInstanceInfo } from '../admin-instance'
 import type { InstanceStore } from '../instance'
 
 import { collectInstanceCandidates, describeInstanceCandidate } from '../instance-candidates'
@@ -13,48 +13,116 @@ const store: InstanceStore = {
   },
 }
 
-const managedDemo: InstanceInfo = {
+const managedDemo: OwnedInstanceInfo = {
   id: 'demo',
   slug: 'demo',
   url: 'https://demo.eu.astrale.ai',
+  state: 'ready',
   region: 'eu',
 }
 
 describe('collectInstanceCandidates', () => {
   test('bookmark and managed at the same URL collapse into one candidate', () => {
     const candidates = collectInstanceCandidates('demo', store, [managedDemo])
-    expect(candidates).toHaveLength(1)
-    expect(candidates[0]).toMatchObject({ source: 'bookmark', key: 'demo' })
+    expect(candidates).toEqual([
+      {
+        source: 'bookmark',
+        key: 'demo',
+        url: 'https://demo.eu.astrale.ai/api',
+        entry: store.instances.demo,
+      },
+    ])
   })
 
   test('bookmark and managed at different URLs are both candidates', () => {
-    const conflicting: InstanceInfo = { ...managedDemo, url: 'https://demo.us.astrale.ai' }
+    const conflicting: OwnedInstanceInfo = {
+      ...managedDemo,
+      url: 'https://demo.us.astrale.ai',
+    }
     const candidates = collectInstanceCandidates('demo', store, [conflicting])
-    expect(candidates).toHaveLength(2)
-    expect(candidates.map((c) => c.source)).toEqual(['bookmark', 'managed'])
+    expect(
+      candidates.map((candidate) => ({
+        source: candidate.source,
+        key: candidate.key,
+        url: candidate.url,
+        id: candidate.source === 'managed' ? candidate.info.id : undefined,
+      })),
+    ).toEqual([
+      {
+        source: 'bookmark',
+        key: 'demo',
+        url: 'https://demo.eu.astrale.ai/api',
+        id: undefined,
+      },
+      {
+        source: 'managed',
+        key: 'demo',
+        url: 'https://demo.us.astrale.ai/api',
+        id: 'demo',
+      },
+    ])
   })
 
   test('multiple managed instances with the same slug are all candidates', () => {
-    const a: InstanceInfo = { id: 'x1', slug: 'twin', url: 'https://twin.eu.astrale.ai' }
-    const b: InstanceInfo = { id: 'x2', slug: 'twin', url: 'https://twin.us.astrale.ai' }
+    const a: OwnedInstanceInfo = {
+      id: 'x1',
+      slug: 'twin',
+      url: 'https://twin.eu.astrale.ai',
+      state: 'ready',
+    }
+    const b: OwnedInstanceInfo = {
+      id: 'x2',
+      slug: 'twin',
+      url: 'https://twin.us.astrale.ai',
+      state: 'ready',
+    }
     const candidates = collectInstanceCandidates('twin', store, [a, b])
-    expect(candidates).toHaveLength(2)
-    expect(candidates.every((c) => c.source === 'managed')).toBe(true)
+    expect(
+      candidates.map((candidate) => ({
+        source: candidate.source,
+        key: candidate.key,
+        id: candidate.source === 'managed' ? candidate.info.id : undefined,
+      })),
+    ).toEqual([
+      { source: 'managed', key: 'twin', id: 'x1' },
+      { source: 'managed', key: 'twin', id: 'x2' },
+    ])
   })
 
   test('managed instances with a different slug are ignored', () => {
-    const unrelated: InstanceInfo = { id: 'z', slug: 'zeta', url: 'https://zeta.eu.astrale.ai' }
-    expect(collectInstanceCandidates('demo', store, [unrelated])).toHaveLength(1)
+    const unrelated: OwnedInstanceInfo = {
+      id: 'z',
+      slug: 'zeta',
+      url: 'https://zeta.eu.astrale.ai',
+      state: 'ready',
+    }
+    expect(
+      collectInstanceCandidates('demo', store, [unrelated]).map((candidate) => ({
+        source: candidate.source,
+        key: candidate.key,
+      })),
+    ).toEqual([{ source: 'bookmark', key: 'demo' }])
   })
 
   test('bookmark resolution honours slug aliases', () => {
     const candidates = collectInstanceCandidates('oth', store, [])
-    expect(candidates).toHaveLength(1)
-    expect(candidates[0]).toMatchObject({ source: 'bookmark', key: 'other' })
+    expect(
+      candidates.map((candidate) => ({
+        source: candidate.source,
+        key: candidate.key,
+        url: candidate.url,
+      })),
+    ).toEqual([
+      {
+        source: 'bookmark',
+        key: 'other',
+        url: 'https://other.example.com/api',
+      },
+    ])
   })
 
   test('unknown name yields no candidates', () => {
-    expect(collectInstanceCandidates('missing', store, [])).toHaveLength(0)
+    expect(collectInstanceCandidates('missing', store, [])).toEqual([])
   })
 })
 
@@ -65,9 +133,16 @@ describe('describeInstanceCandidate', () => {
     expect(describeInstanceCandidate(bookmark!)).toContain('https://demo.eu.astrale.ai/api')
 
     const [managed] = collectInstanceCandidates('twin', store, [
-      { id: 'x', slug: 'twin', url: 'https://twin.eu.astrale.ai', region: 'eu' },
+      {
+        id: 'x',
+        slug: 'twin',
+        url: 'https://twin.eu.astrale.ai',
+        state: 'ready',
+        region: 'eu',
+      },
     ])
-    expect(describeInstanceCandidate(managed!)).toContain('(managed)')
-    expect(describeInstanceCandidate(managed!)).toContain('eu')
+    expect(describeInstanceCandidate(managed!)).toBe(
+      'twin (managed) https://twin.eu.astrale.ai/api — eu',
+    )
   })
 })

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

@@ -98,7 +98,7 @@ describe('resolveInstanceTarget', () => {
     })
   })
 
-  test('managed slug resolves through injected Instance.info lookup', async () => {
+  test('managed slug resolves through the injected managed lookup', async () => {
     await expect(
       resolveInstanceTarget(
         { source: 'name', name: 'bryan' },
@@ -181,6 +181,14 @@ describe('instance target helpers', () => {
 
     expect(isManagedInstanceNotFound(auth)).toBe(false)
   })
+
+  test('recognizes an owner-scoped lookup miss', () => {
+    expect(
+      isManagedInstanceNotFound(
+        new AstraleError('INSTANCE_NOT_FOUND', 'No owned instance matches "missing".'),
+      ),
+    ).toBe(true)
+  })
 })
 
 describe('isManagedInstanceNotFound: kernel InternalKernelError wrap', () => {

package/src/lib/__tests__/view-port-allocation.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import net from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { findFreePort } from '../port'
+import { withViewPortAllocationLock } from '../view/port-allocation'
+
+let tmp: string
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'astrale-view-port-'))
+})
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true })
+})
+
+function listen(port: number): Promise<net.Server> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.once('error', reject)
+    server.listen({ port, host: '127.0.0.1', exclusive: true }, () => resolve(server))
+  })
+}
+
+function close(server: net.Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()))
+  })
+}
+
+describe('view port allocation', () => {
+  test('never overlaps concurrent allocation critical sections', async () => {
+    const lockPath = join(tmp, 'ports.lock')
+    let active = 0
+    let maxActive = 0
+
+    const contender = () =>
+      withViewPortAllocationLock(async () => {
+        active++
+        maxActive = Math.max(maxActive, active)
+        await Bun.sleep(40)
+        active--
+      }, lockPath)
+
+    await Promise.all([contender(), contender()])
+
+    // Without the view-specific lock both contenders enter before either
+    // delay completes, making this 2 and recreating the probe/bind window.
+    expect(maxActive).toBe(1)
+  })
+
+  test('serializes concurrent probe-then-listen allocations', async () => {
+    const base = await findFreePort(48000, 200)
+    expect(base).not.toBeNull()
+    if (base === null) throw new Error('test port window exhausted')
+    const lockPath = join(tmp, 'ports.lock')
+
+    const allocate = () =>
+      withViewPortAllocationLock(async () => {
+        const port = await findFreePort(base, 4)
+        if (port === null) throw new Error('test port window exhausted')
+
+        // Widen the exact pre-fix race: both callers would finish the advisory
+        // probe before either one binds, then one would fail with EADDRINUSE.
+        await Bun.sleep(40)
+        const server = await listen(port)
+        return { port, server }
+      }, lockPath)
+
+    const allocations = await Promise.all([allocate(), allocate()])
+    try {
+      const ports = allocations.map(({ port }) => port).sort((a, b) => a - b)
+      expect(ports[0]).toBe(base)
+      expect(ports[1]).toBeGreaterThan(base)
+    } finally {
+      await Promise.all(allocations.map(({ server }) => close(server)))
+    }
+  })
+})

package/src/lib/admin-instance.ts

@@ -5,10 +5,14 @@
  */
 export const ADMIN_INSTANCE = '/:admin.astrale.ai:class.Instance'
 
-export function adminInstanceMethod(method: 'alphaCreate' | 'delete' | 'info' | 'list'): string {
+export function adminInstanceMethod(
+  method: 'alphaCreate' | 'delete' | 'info' | 'list' | 'listMine',
+): string {
   return `${ADMIN_INSTANCE}:${method}`
 }
 
+export type InstanceState = 'provisioning' | 'ready' | 'failed'
+
 /** Read shape returned by `Instance.list` / `info` / `delete` (domain `InstanceInfoSchema`). */
 export type InstanceInfo = {
   id: string
@@ -16,10 +20,31 @@ export type InstanceInfo = {
   url: string
   hostId?: string
   region?: string
-  state?: 'provisioning' | 'ready' | 'failed'
+  state?: InstanceState
   phase?: string
   error?: string | null
   createdAt?: string
+  organizationId?: string
+}
+
+/** Owner-scoped read shape returned by `Instance.listMine`. */
+export type OwnedInstanceInfo = InstanceInfo & {
+  state: InstanceState
+}
+
+/** Call the owner-scoped list contract through any admin client-shaped object. */
+export async function callOwnedInstances(client: {
+  call: (path: string, params: Record<string, never>) => Promise<unknown>
+}): Promise<OwnedInstanceInfo[]> {
+  return (await client.call(adminInstanceMethod('listMine'), {})) as OwnedInstanceInfo[]
+}
+
+/** Match an owner-scoped instance by its stable node id or human slug. */
+export function findOwnedInstance(
+  instances: readonly OwnedInstanceInfo[],
+  identifier: string,
+): OwnedInstanceInfo | undefined {
+  return instances.find((instance) => instance.id === identifier || instance.slug === identifier)
 }
 
 /** Human-readable location of a managed instance ("region · hostId"). */

package/src/lib/instance-candidates.ts

@@ -1,11 +1,11 @@
 import type { InstanceEntry, InstanceStore } from './instance'
 
-import { formatInstanceLocation, type InstanceInfo } from './admin-instance'
+import { formatInstanceLocation, type OwnedInstanceInfo } from './admin-instance'
 import { normalizeInstanceKernelUrl, resolveInstanceKey } from './instance'
 
 export type InstanceCandidate =
   | { source: 'bookmark'; key: string; url: string; entry: InstanceEntry }
-  | { source: 'managed'; key: string; url: string; info: InstanceInfo }
+  | { source: 'managed'; key: string; url: string; info: OwnedInstanceInfo }
 
 /**
  * Gather every instance a bare name can refer to — the local bookmark
@@ -16,7 +16,7 @@ export type InstanceCandidate =
 export function collectInstanceCandidates(
   name: string,
   store: InstanceStore,
-  managed: InstanceInfo[],
+  managed: OwnedInstanceInfo[],
 ): InstanceCandidate[] {
   const out: InstanceCandidate[] = []
 

package/src/lib/instance-target.ts

@@ -170,6 +170,7 @@ export function adminTargetToInstance(target: ResolvedAdminTarget): ResolvedInst
 }
 
 export function isManagedInstanceNotFound(error: unknown): boolean {
+  if (error instanceof AstraleError && error.code === 'INSTANCE_NOT_FOUND') return true
   if (!(error instanceof Error)) return false
   if (error.name === 'NotFoundError') return true
   // The admin kernel reports a missing instance node as InternalKernelError

package/src/lib/view/port-allocation.ts

@@ -0,0 +1,19 @@
+import { join } from 'node:path'
+
+import { withFileLock } from '../fs-atomic'
+import { VIEW_DIR } from './session'
+
+const VIEW_PORT_LOCK = join(VIEW_DIR, 'ports.lock')
+
+/**
+ * Keep the free-port probe and detached server startup in one cross-process
+ * critical section. A probe alone is only advisory: without this lock, two
+ * concurrent `astrale view` processes can both observe 4419 as free before
+ * either child binds it.
+ */
+export function withViewPortAllocationLock<T>(
+  fn: () => Promise<T>,
+  lockPath = VIEW_PORT_LOCK,
+): Promise<T> {
+  return withFileLock(lockPath, fn)
+}