@astrale-os/cli 0.4.0-alpha.13

package/src/commands/__tests__/domain-list.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { DomainInfo } from '../../lib/admin-domain'
+
+import { byDefaultThenName, domainProjection, type DomainRow } from '../domain/list'
+
+const strip = (s: string): string => s.replace(/\[[0-9;]*m/g, '')
+
+function entry(over: Partial<DomainInfo>): DomainInfo {
+  return {
+    id: over.origin ?? 'id',
+    origin: 'x.astrale.ai',
+    name: 'x',
+    createdAt: '',
+    updatedAt: '',
+    ...over,
+  }
+}
+
+describe('domain list — ordering', () => {
+  test('install-by-default sorts first, then alphabetical by origin', () => {
+    const rows = [
+      entry({ origin: 'zeta.astrale.ai' }),
+      entry({ origin: 'alpha.astrale.ai' }),
+      entry({ origin: 'mid.astrale.ai', installByDefault: true }),
+      entry({ origin: 'beta.astrale.ai', installByDefault: true }),
+    ]
+    rows.sort(byDefaultThenName)
+    expect(rows.map((r) => r.origin)).toEqual([
+      'beta.astrale.ai', // default group, alpha order
+      'mid.astrale.ai',
+      'alpha.astrale.ai', // non-default group, alpha order
+      'zeta.astrale.ai',
+    ])
+  })
+})
+
+describe('domain list — projection', () => {
+  test('row carries name/origin/url and a default marker; -q paths are install urls', () => {
+    const proj = domainProjection([
+      entry({
+        origin: 'crm.acme.dev',
+        name: 'crm',
+        url: 'https://crm.acme.dev',
+        installByDefault: true,
+      }),
+    ])
+    const row = proj.rows[0]
+    expect(strip(row.name)).toBe('crm')
+    expect(strip(row.origin)).toBe('crm.acme.dev')
+    expect(strip(row.url)).toBe('https://crm.acme.dev')
+    expect(strip(row.default)).toBe('default')
+    // The quiet/pipeable token is the install URL, not the origin.
+    expect(proj.paths).toEqual(['https://crm.acme.dev'])
+  })
+
+  test('an unpublished entry shows a placeholder url and falls back to origin for -q', () => {
+    const proj = domainProjection([entry({ origin: 'pending.dev', name: 'pending' })])
+    expect(strip(proj.rows[0].url)).toBe('(unpublished)')
+    expect(strip(proj.rows[0].default)).toBe('')
+    expect(proj.paths).toEqual(['pending.dev'])
+  })
+
+  test('STATUS cell is empty without --check, live/down with it', () => {
+    const base = entry({ origin: 'a.dev', url: 'https://a.dev' })
+    expect(strip(domainProjection([base]).rows[0].status)).toBe('')
+
+    const live: DomainRow = { ...base, reachable: true, checkError: null }
+    expect(strip(domainProjection([live]).rows[0].status)).toBe('● live')
+
+    const down: DomainRow = { ...base, reachable: false, checkError: 'meta HTTP 502' }
+    expect(strip(domainProjection([down]).rows[0].status)).toBe('○ meta HTTP 502')
+  })
+})

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

@@ -0,0 +1,136 @@
+import type { Command } from 'commander'
+
+import { describe, expect, test } from 'bun:test'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { buildProgram } from '../../program'
+
+// The `astrale-cli` skill claims `astrale --help` is the source of truth and
+// "never drifts". These tests hold that claim to account: the version is
+// single-sourced from package.json, no internal `§` spec anchors leak into
+// rendered help, and the workspace skill mirror stays byte-identical.
+
+const cliRoot = join(import.meta.dir, '../../..')
+
+/** Every command in the tree (root + groups + nested subgroups), depth-first. */
+function allCommands(cmd: Command): Command[] {
+  return [cmd, ...cmd.commands.flatMap(allCommands)]
+}
+
+describe('help contract — version is single-sourced', () => {
+  test('program version === package.json === release-please manifest', async () => {
+    const program = await buildProgram()
+    const pkg = JSON.parse(readFileSync(join(cliRoot, 'package.json'), 'utf8')) as {
+      version: string
+    }
+    const manifest = JSON.parse(
+      readFileSync(join(cliRoot, '.release-please-manifest.json'), 'utf8'),
+    ) as Record<string, string>
+
+    // `bin/astrale.ts` -> buildProgram -> .version(pkg.version): asserting the
+    // rendered version equals BOTH JSON sources catches a re-hardcoded literal
+    // and a manifest/package.json divergence (release-please bumps both).
+    expect(program.version()).toBe(pkg.version)
+    expect(manifest['.']).toBe(pkg.version)
+  })
+})
+
+describe('help contract — no internal SPEC anchors leak to users', () => {
+  test('no rendered --help text contains a § section anchor', async () => {
+    const program = await buildProgram()
+    const offenders = allCommands(program)
+      .filter((c) => c.helpInformation().includes('§'))
+      .map((c) => c.name() || '<root>')
+
+    expect(offenders).toEqual([])
+  })
+})
+
+describe('help contract — IdP/auth surface is registered', () => {
+  test('idp group and auth commands are visible in --help tree', async () => {
+    const program = await buildProgram()
+    const names = allCommands(program).map((command) => command.name())
+
+    expect(names).toContain('idp')
+    expect(names).toContain('add')
+    expect(names).toContain('login')
+    expect(names).toContain('token')
+    expect(names).toContain('update')
+    expect(program.helpInformation()).toContain('idp')
+    expect(program.helpInformation()).toContain('update')
+  })
+})
+
+describe('help contract — admin target surface is registered', () => {
+  test('admin group and admin-target flags are visible', async () => {
+    const program = await buildProgram()
+    const names = allCommands(program).map((command) => command.name())
+    const instanceCreate = allCommands(program).find((command) => command.name() === 'create')
+
+    expect(names).toContain('admin')
+    expect(names).toContain('status')
+    expect(names).toContain('use')
+    expect(program.helpInformation()).toContain('admin')
+    expect(instanceCreate?.helpInformation()).toContain('--admin <name>')
+    expect(instanceCreate?.helpInformation()).toContain('--admin-url <url>')
+  })
+
+  test('instance create is the alphaCreate flow, not legacy Instance.init DX', async () => {
+    const program = await buildProgram()
+    const instanceCreate = allCommands(program).find((command) => command.name() === 'create')
+    const help = instanceCreate?.helpInformation() ?? ''
+
+    expect(help).toContain('Instance.alphaCreate')
+    expect(help).not.toContain('--no-use')
+    expect(help).not.toContain('Instance.init requires --host-id')
+  })
+})
+
+describe('help contract — connect-only command surface', () => {
+  test('runtime management commands are not registered', async () => {
+    const program = await buildProgram()
+    const names = allCommands(program).map((command) => command.name())
+
+    // 'logs' and 'domain' are NOT in this list anymore: each was once LOCAL
+    // runtime management (the historical `astrale logs`, removed with
+    // start/stop; the historical `astrale domain`, local domain wiring) and each
+    // has since been RECLAIMED for a connect-side meaning through the admin
+    // control plane — `astrale logs <service>` tails a MANAGED service's buffer;
+    // `astrale domain publish` registers an installable domain in the admin's
+    // catalog and `astrale domain install <url>` mounts one on an instance.
+    for (const removed of [
+      'init',
+      'start',
+      'stop',
+      'restart',
+      'reset',
+      'bootstrap',
+      'tunnel',
+      'graph',
+      'server',
+      'env',
+    ]) {
+      expect(names).not.toContain(removed)
+    }
+  })
+})
+
+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
+  // when the CLI repo is tested standalone — only assert parity when present.
+  const mirror = join(cliRoot, '../.agents/skills/astrale-cli/SKILL.md')
+
+  test('canonical skill file exists and is non-empty', () => {
+    expect(existsSync(canonical)).toBe(true)
+    expect(readFileSync(canonical, 'utf8').length).toBeGreaterThan(0)
+  })
+
+  test.skipIf(!existsSync(mirror))(
+    'workspace mirror is byte-identical to the canonical skill',
+    () => {
+      expect(readFileSync(mirror, 'utf8')).toBe(readFileSync(canonical, 'utf8'))
+    },
+  )
+})

package/src/commands/__tests__/install-identity-override.test.ts

@@ -0,0 +1,65 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+
+import { domainRefFromTarget, isIdentityOverride, probeDeclaredOrigin } from '../domain/install'
+
+describe('admin-path target classification', () => {
+  test('an http(s) url installs by url', () => {
+    expect(domainRefFromTarget('https://crm.acme.dev')).toEqual({ url: 'https://crm.acme.dev' })
+    expect(domainRefFromTarget('http://localhost:8787')).toEqual({ url: 'http://localhost:8787' })
+  })
+
+  test('a bare origin installs by catalog origin (the unique registry key)', () => {
+    expect(domainRefFromTarget('crm.acme.dev')).toEqual({ origin: 'crm.acme.dev' })
+    // A host:port that is not a url is still an origin, not a url.
+    expect(domainRefFromTarget('dist.astrale.ai')).toEqual({ origin: 'dist.astrale.ai' })
+  })
+})
+
+describe('identity-override detection', () => {
+  test('origin matching the serving host is not an override', () => {
+    expect(isIdentityOverride('crm.acme.dev', 'crm.acme.dev')).toBe(false)
+    expect(isIdentityOverride('CRM.Acme.Dev', 'crm.acme.dev')).toBe(false)
+  })
+
+  test('origin differing from the serving host is an override', () => {
+    // The spec §5 attack shape: a fork on workers.dev claiming a well-known origin.
+    expect(isIdentityOverride('distribution.astrale.ai', 'crm.workers.dev')).toBe(true)
+    // The scaffold default also aliases until the placeholder origin is edited.
+    expect(isIdentityOverride('hldom.example.dev', 'hldom-example-dev.acme.workers.dev')).toBe(true)
+  })
+})
+
+describe('declared-origin probe (/meta)', () => {
+  const servers: { stop(): void }[] = []
+  afterAll(() => {
+    for (const s of servers) s.stop()
+  })
+
+  function serveMeta(handler: (req: Request) => Response): string {
+    const server = Bun.serve({ port: 0, fetch: handler })
+    servers.push(server)
+    return `http://localhost:${server.port}`
+  }
+
+  test('reads domainName from a well-formed /meta', async () => {
+    const url = serveMeta((req) =>
+      new URL(req.url).pathname === '/meta'
+        ? Response.json({ iss: 'https://x', domainName: 'crm.acme.dev' })
+        : new Response('nope', { status: 404 }),
+    )
+    expect(await probeDeclaredOrigin(url)).toBe('crm.acme.dev')
+  })
+
+  test('degrades to undefined on missing domainName, non-200, bad JSON, or dead host', async () => {
+    const noName = serveMeta(() => Response.json({ iss: 'https://x' }))
+    expect(await probeDeclaredOrigin(noName)).toBeUndefined()
+
+    const error = serveMeta(() => new Response('boom', { status: 500 }))
+    expect(await probeDeclaredOrigin(error)).toBeUndefined()
+
+    const badJson = serveMeta(() => new Response('<html>', { status: 200 }))
+    expect(await probeDeclaredOrigin(badJson)).toBeUndefined()
+
+    expect(await probeDeclaredOrigin('http://127.0.0.1:1')).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const cliRoot = join(import.meta.dir, '../../..')
+
+let tmp: string
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'astrale-instance-bookmark-'))
+})
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true })
+})
+
+describe('instance bookmark command', () => {
+  test('normalizes managed instance public roots to /api when creating a bookmark', async () => {
+    const result = await runBookmark(
+      'testmarc',
+      '--url',
+      'https://testmarc.eu.astrale.ai',
+      '--skip-probe',
+    )
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('Bookmarked "testmarc"')
+
+    const store = await readInstances()
+    expect(store.instances.testmarc.url).toBe('https://testmarc.eu.astrale.ai/api')
+  })
+
+  test('repairs an existing managed-root bookmark without clearing optional fields', async () => {
+    await mkdir(tmp, { recursive: true })
+    await writeFile(
+      join(tmp, 'instances.json'),
+      JSON.stringify(
+        {
+          active: 'testmarc',
+          instances: {
+            testmarc: {
+              url: 'https://testmarc.eu.astrale.ai',
+              issuer: 'https://issuer.example.com',
+              defaultIdentity: 'marc',
+              caFile: '/tmp/ca.pem',
+              createdAt: '2026-06-10T00:00:00.000Z',
+              kind: 'bookmark',
+              mode: 'remote',
+            },
+          },
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+
+    const result = await runBookmark(
+      'testmarc',
+      '--url',
+      'https://testmarc.eu.astrale.ai',
+      '--skip-probe',
+    )
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('Updated bookmark "testmarc"')
+
+    const store = await readInstances()
+    expect(store.instances.testmarc.url).toBe('https://testmarc.eu.astrale.ai/api')
+    expect(store.instances.testmarc.issuer).toBe('https://issuer.example.com')
+    expect(store.instances.testmarc.defaultIdentity).toBe('marc')
+    expect(store.instances.testmarc.caFile).toBe('/tmp/ca.pem')
+    expect(store.instances.testmarc.createdAt).toBe('2026-06-10T00:00:00.000Z')
+  })
+})
+
+async function readInstances(): Promise<{
+  active: string
+  instances: Record<string, Record<string, unknown>>
+}> {
+  return JSON.parse(await readFile(join(tmp, 'instances.json'), 'utf-8'))
+}
+
+async function runBookmark(...args: string[]): Promise<{
+  exitCode: number
+  stdout: string
+  stderr: string
+}> {
+  const proc = Bun.spawn({
+    cmd: ['bun', join(cliRoot, 'bin/astrale.ts'), 'instance', 'bookmark', ...args],
+    env: { ...process.env, ASTRALE_HOME: tmp },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  return { exitCode, stdout, stderr }
+}

package/src/commands/__tests__/instance-create-hosts.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from 'bun:test'
+
+import { parseEligibleHostIds } from '../instance/create'
+
+// `instance create` recovers from alphaCreate's MULTI-host ambiguity by popping
+// a picker; the recovery hinges on pulling the eligible ids out of that error.
+// These pin the parse to the server's wording (Option B — no admin change).
+describe('parseEligibleHostIds', () => {
+  test('extracts the ids the server listed (the recoverable, >1 case)', () => {
+    const e = new Error(
+      'alphaCreate could not choose a host: 2 ready hosts are assigned (host-1, host-paris-02). ' +
+        'Specify host_id once multi-host placement is enabled.',
+    )
+    expect(parseEligibleHostIds(e)).toEqual(['host-1', 'host-paris-02'])
+  })
+
+  test('returns null for the no-host error (nothing to pick — falls through to fatal)', () => {
+    const e = new Error(
+      'alphaCreate could not choose a host: no ready host is assigned to this user. ' +
+        'Ask an admin to assign (grant USE) a host.',
+    )
+    expect(parseEligibleHostIds(e)).toBeNull()
+  })
+
+  test('returns null for unrelated errors and non-Error values', () => {
+    expect(parseEligibleHostIds(new Error('Permission denied'))).toBeNull()
+    expect(parseEligibleHostIds('something odd')).toBeNull()
+  })
+})

package/src/commands/__tests__/instance-list-rows.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { InstanceInfo } from '../../lib/admin-instance'
+
+import { buildInstanceRows, type Bookmark } from '../instance/list'
+
+const managed: InstanceInfo[] = [
+  { id: 'demo', slug: 'demo', url: 'https://demo.eu.astrale.ai', region: 'eu' },
+]
+
+function bookmark(overrides: Partial<Bookmark> = {}): Bookmark {
+  return {
+    name: 'demo',
+    url: 'https://demo.eu.astrale.ai/api',
+    issuer: null,
+    active: false,
+    defaultIdentity: null,
+    createdAt: null,
+    ...overrides,
+  }
+}
+
+describe('buildInstanceRows', () => {
+  test('a bookmark of a managed instance does not produce a second row', () => {
+    const rows = buildInstanceRows(managed, [bookmark()], { managed: true, bookmarks: true })
+    expect(rows).toHaveLength(1)
+    expect(rows[0]).toMatchObject({ kind: 'managed' })
+  })
+
+  test('the active marker moves onto the merged managed row', () => {
+    const rows = buildInstanceRows(managed, [bookmark({ active: true })], {
+      managed: true,
+      bookmarks: true,
+    })
+    expect(rows).toHaveLength(1)
+    expect(rows[0]?.name).toContain('*')
+  })
+
+  test('a same-name bookmark with a different URL stays a separate row', () => {
+    const rows = buildInstanceRows(managed, [bookmark({ url: 'https://elsewhere.example.com' })], {
+      managed: true,
+      bookmarks: true,
+    })
+    expect(rows).toHaveLength(2)
+    expect(rows.map((row) => row.kind)).toEqual(['managed', 'bookmark'])
+  })
+
+  test('unrelated bookmarks are listed as before', () => {
+    const rows = buildInstanceRows(
+      managed,
+      [bookmark(), bookmark({ name: 'local', url: 'http://localhost:3001/api' })],
+      { managed: true, bookmarks: true },
+    )
+    expect(rows).toHaveLength(2)
+    expect(rows.map((row) => row.name)).toEqual(['demo', 'local'])
+  })
+
+  test('--bookmarked never merges (managed hidden)', () => {
+    const rows = buildInstanceRows(managed, [bookmark()], { managed: false, bookmarks: true })
+    expect(rows).toHaveLength(1)
+    expect(rows[0]).toMatchObject({ kind: 'bookmark' })
+  })
+})

package/src/commands/__tests__/logs.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from 'bun:test'
+
+import { buildEventsParams, normalizePage, parseServiceName, parseTimeFlag } from '../logs'
+
+describe('parseTimeFlag', () => {
+  test('passes through epoch-ms', () => {
+    expect(parseTimeFlag('--since', '1718841600000')).toBe(1718841600000)
+    expect(parseTimeFlag('--since', '0')).toBe(0)
+    expect(parseTimeFlag('--since', '-5')).toBe(-5)
+  })
+
+  test('parses ISO-8601 to epoch ms', () => {
+    expect(parseTimeFlag('--since', '2026-06-20T00:00:00Z')).toBe(
+      Date.parse('2026-06-20T00:00:00Z'),
+    )
+  })
+
+  test('throws on garbage', () => {
+    expect(() => parseTimeFlag('--since', 'not-a-time')).toThrow('--since')
+  })
+})
+
+describe('buildEventsParams', () => {
+  test('defaults limit when unset, no other fields', () => {
+    expect(buildEventsParams({})).toEqual({ limit: 200 })
+  })
+
+  test('maps typed flags into a JournalFilter', () => {
+    expect(
+      buildEventsParams({
+        topic: 'op:*:failed',
+        principal: 'id_abc',
+        since: '1000',
+        until: '2000',
+        limit: '50',
+        cursor: '7',
+      }),
+    ).toEqual({
+      topic: 'op:*:failed',
+      principal: 'id_abc' as never,
+      since: 1000,
+      until: 2000,
+      limit: 50,
+      cursor: 7,
+    })
+  })
+
+  test('rejects a non-positive limit', () => {
+    expect(() => buildEventsParams({ limit: '0' })).toThrow('--limit')
+    expect(() => buildEventsParams({ limit: '-3' })).toThrow('--limit')
+    expect(() => buildEventsParams({ limit: 'x' })).toThrow('--limit')
+  })
+
+  test('rejects a non-positive cursor', () => {
+    expect(() => buildEventsParams({ cursor: '0' })).toThrow('--cursor')
+  })
+
+  test('omits empty topic/principal', () => {
+    expect(buildEventsParams({ topic: '', principal: '' })).toEqual({ limit: 200 })
+  })
+})
+
+describe('normalizePage', () => {
+  const entry = (seq: number) => ({
+    seq,
+    event: {
+      id: `e${seq}`,
+      topic: 'op:x',
+      payload: {},
+      metadata: { traceId: 't', timestamp: seq, principal: 'p', root: 'r' },
+    },
+  })
+
+  test('wraps a bare entry array and derives nextCursor from max seq', () => {
+    const page = normalizePage([entry(3), entry(7), entry(5)])
+    expect(page.entries).toHaveLength(3)
+    expect(page.nextCursor).toBe(7)
+  })
+
+  test('empty array → empty entries, null cursor', () => {
+    expect(normalizePage([])).toEqual({ entries: [], nextCursor: null })
+  })
+
+  test('accepts a paged { entries, nextCursor } shape', () => {
+    const page = normalizePage({ entries: [entry(1)], nextCursor: 42 })
+    expect(page.entries).toHaveLength(1)
+    expect(page.nextCursor).toBe(42)
+  })
+
+  test('paged shape without nextCursor falls back to max seq', () => {
+    expect(normalizePage({ entries: [entry(9)] }).nextCursor).toBe(9)
+  })
+
+  test('non-array, non-page input → empty', () => {
+    expect(normalizePage(null)).toEqual({ entries: [], nextCursor: null })
+    expect(normalizePage(undefined)).toEqual({ entries: [], nextCursor: null })
+    expect(normalizePage('nope')).toEqual({ entries: [], nextCursor: null })
+  })
+})
+
+describe('parseServiceName', () => {
+  test('bare name is returned as-is', () => {
+    expect(parseServiceName('my-notes')).toBe('my-notes')
+  })
+
+  test('host → first label', () => {
+    expect(parseServiceName('my-notes.svc.eu.astrale.ai')).toBe('my-notes')
+  })
+
+  test('full URL → hostname first label', () => {
+    expect(parseServiceName('https://my-notes.example.dev/path')).toBe('my-notes')
+  })
+
+  test('trims whitespace', () => {
+    expect(parseServiceName('  my-notes  ')).toBe('my-notes')
+  })
+})

package/src/commands/__tests__/ls.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'bun:test'
+
+import { basename, classNameOf } from '../ls'
+
+// Regression: the formatter used to read `item.slug` (never returned by the
+// kernel), blanking the name column and breaking `-q`/`-R`. The real fields are
+// `path` (absolute) and `class` (serialized ClassPath).
+describe('ls — display projection (slug-bug regression)', () => {
+  test('basename derives the display name from the absolute path', () => {
+    expect(basename('/dist.astrale.ai')).toBe('dist.astrale.ai')
+    expect(basename('/kernel.astrale.ai')).toBe('kernel.astrale.ai')
+    expect(basename('/')).toBe('/')
+    expect(basename(undefined)).toBe('')
+  })
+
+  test('classNameOf parses the kind from the serialized class path', () => {
+    expect(classNameOf({ class: '/:kernel.astrale.ai:class.Domain' })).toBe('Domain')
+    expect(classNameOf({ class: '/:kernel.astrale.ai:class.Folder' })).toBe('Folder')
+  })
+
+  test('classNameOf falls back to the most specific label, then ?', () => {
+    expect(classNameOf({ __labels: ['Node', 'Domain', 'Container'] })).toBe('Container')
+    expect(classNameOf({})).toBe('?')
+  })
+})

package/src/commands/__tests__/setup-plan.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const cliRoot = join(import.meta.dir, '../../..')
+
+// `astrale setup --plan --json` is the agent-facing contract: a read-only gap
+// report where every unsatisfied step carries the command to fix it. These pin
+// that shape on a FRESH home (nothing configured) so it stays machine-parseable.
+
+let tmp: string
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'astrale-setup-plan-'))
+})
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true })
+})
+
+type PlanStep = { id: string; group: string; state: string; summary: string; fix?: string }
+type Plan = { connected: boolean; steps: PlanStep[] }
+
+async function runSetupPlan(...args: string[]): Promise<{ exitCode: number; plan: Plan }> {
+  const proc = Bun.spawn({
+    cmd: ['bun', join(cliRoot, 'bin/astrale.ts'), 'setup', '--plan', '--json', ...args],
+    env: { ...process.env, ASTRALE_HOME: tmp },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+  return { exitCode, plan: JSON.parse(stdout) as Plan }
+}
+
+describe('astrale setup --plan', () => {
+  test('reports a fresh home as not connected, with a fix per connect gap', async () => {
+    const { exitCode, plan } = await runSetupPlan()
+    expect(exitCode).toBe(0)
+    expect(plan.connected).toBe(false)
+
+    const byId = Object.fromEntries(plan.steps.map((s) => [s.id, s]))
+
+    // Not signed in, with the granular command an agent would run.
+    expect(byId.auth.state).toBe('gap')
+    expect(byId.auth.fix).toBe('astrale auth login')
+
+    // The admin control plane always has a baked default → satisfied.
+    expect(byId.admin.state).toBe('satisfied')
+
+    // No active instance yet.
+    expect(byId.instance.state).toBe('gap')
+    expect(byId.instance.fix).toContain('astrale instance create')
+  })
+
+  test('threads the positional slug into the instance fix hint', async () => {
+    const { plan } = await runSetupPlan('my-app')
+    const instance = plan.steps.find((s) => s.id === 'instance')
+    expect(instance?.fix).toBe('astrale instance create my-app')
+  })
+})