@astrale-os/cli 0.4.0-alpha.13

package/src/kernel/types.ts

@@ -0,0 +1,14 @@
+import type { OutputOpts } from '../lib/output'
+
+export type KernelCommandOpts = OutputOpts & {
+  url?: string
+  instance?: string
+  timeout?: string
+  as?: string
+  creds?: string
+  debug?: boolean
+}
+
+export type CallCommandOpts = KernelCommandOpts & {
+  data?: string
+}

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

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { InstanceStore } from '../instance'
+
+import {
+  DEFAULT_ADMIN_TARGET_NAME,
+  DEFAULT_ADMIN_TARGET_URL,
+  resolveAdminTargetFromStore,
+} from '../admin-target'
+import { DEFAULT_CONFIG, type AstraleConfig } from '../config'
+
+const instances: InstanceStore = {
+  active: 'primary',
+  instances: {
+    primary: {
+      url: 'https://primary.example.com',
+      issuer: 'https://primary-issuer.example.com',
+    },
+    admin: {
+      url: 'https://bookmarked-admin.example.com',
+      issuer: 'https://bookmarked-issuer.example.com',
+      defaultIdentity: 'admin-workos',
+    },
+    alias: { url: 'https://alias-admin.example.com', name: 'named-admin' },
+  },
+}
+
+describe('resolveAdminTargetFromStore', () => {
+  test('uses hosted admin default without active instance coupling', () => {
+    expect(resolveAdminTargetFromStore({}, DEFAULT_CONFIG, instances)).toEqual({
+      name: DEFAULT_ADMIN_TARGET_NAME,
+      registrationSlug: DEFAULT_ADMIN_TARGET_NAME,
+      url: DEFAULT_ADMIN_TARGET_URL,
+      issuer: DEFAULT_ADMIN_TARGET_URL,
+      source: 'default',
+      configured: false,
+    })
+  })
+
+  test('uses configured admin bookmark', () => {
+    const config: AstraleConfig = {
+      ...DEFAULT_CONFIG,
+      admin: { instance: 'admin' },
+    }
+
+    expect(resolveAdminTargetFromStore({}, config, instances)).toEqual({
+      name: 'admin',
+      registrationSlug: 'admin',
+      url: 'https://bookmarked-admin.example.com',
+      issuer: 'https://bookmarked-issuer.example.com',
+      defaultIdentity: 'admin-workos',
+      source: 'config-instance',
+      configured: true,
+    })
+  })
+
+  test('allows explicit admin bookmark and admin url overrides', () => {
+    expect(
+      resolveAdminTargetFromStore({ admin: 'alias' }, DEFAULT_CONFIG, instances),
+    ).toMatchObject({
+      name: 'alias',
+      url: 'https://alias-admin.example.com',
+      issuer: 'https://alias-admin.example.com',
+      source: 'admin',
+    })
+
+    expect(
+      resolveAdminTargetFromStore(
+        { adminUrl: 'https://override-admin.example.com' },
+        DEFAULT_CONFIG,
+        instances,
+      ),
+    ).toMatchObject({
+      name: 'admin',
+      url: 'https://override-admin.example.com',
+      issuer: 'https://override-admin.example.com',
+      source: 'admin-url',
+    })
+  })
+
+  test('accepts -i and --url as admin target overrides', () => {
+    expect(
+      resolveAdminTargetFromStore({ instance: 'admin' }, DEFAULT_CONFIG, instances),
+    ).toMatchObject({
+      name: 'admin',
+      url: 'https://bookmarked-admin.example.com',
+      source: 'admin',
+    })
+
+    expect(
+      resolveAdminTargetFromStore(
+        { url: 'https://override.example.com' },
+        DEFAULT_CONFIG,
+        instances,
+      ),
+    ).toMatchObject({
+      name: 'admin',
+      url: 'https://override.example.com',
+      source: 'admin-url',
+    })
+  })
+
+  test('rejects conflicting admin target overrides', () => {
+    expect(() =>
+      resolveAdminTargetFromStore(
+        { admin: 'admin', adminUrl: 'https://override-admin.example.com' },
+        DEFAULT_CONFIG,
+        instances,
+      ),
+    ).toThrow('Choose one admin target override')
+  })
+})

package/src/lib/__tests__/binary.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
+import { readFile, unlink } from 'node:fs/promises'
+
+import { presentBinary, type BinaryLike } from '../binary'
+
+const png = (): BinaryLike => ({
+  status: 200,
+  contentType: 'image/png',
+  body: new Uint8Array([1, 2, 3, 4]),
+})
+
+describe('presentBinary', () => {
+  let chunks: Buffer[] = []
+  let originalWrite: typeof process.stdout.write
+
+  beforeEach(() => {
+    chunks = []
+    originalWrite = process.stdout.write.bind(process.stdout)
+    process.stdout.write = mock((chunk: string | Uint8Array) => {
+      chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : Buffer.from(chunk))
+      return true
+    }) as typeof process.stdout.write
+  })
+
+  afterEach(() => {
+    process.stdout.write = originalWrite
+  })
+
+  test('--raw writes the raw bytes to stdout', async () => {
+    await presentBinary(png(), { raw: true })
+    expect(Array.from(Buffer.concat(chunks))).toEqual([1, 2, 3, 4])
+  })
+
+  test('--json writes a base64-wrapped JSON envelope', async () => {
+    await presentBinary(png(), { json: true })
+    const obj = JSON.parse(Buffer.concat(chunks).toString())
+    expect(obj.contentType).toBe('image/png')
+    expect([...Buffer.from(obj.bodyBase64, 'base64')]).toEqual([1, 2, 3, 4])
+  })
+
+  test('--json inlines text for text-like content types', async () => {
+    await presentBinary(
+      { status: 200, contentType: 'text/plain', body: new TextEncoder().encode('hi') },
+      { json: true },
+    )
+    const obj = JSON.parse(Buffer.concat(chunks).toString())
+    expect(obj.body).toBe('hi')
+  })
+
+  test('-o writes raw bytes to a file', async () => {
+    const tmp = `${process.env.TMPDIR ?? '/tmp'}/astrale-bin-test-${process.pid}.bin`
+    await presentBinary(png(), {}, { outFile: tmp })
+    expect([...(await readFile(tmp))]).toEqual([1, 2, 3, 4])
+    await unlink(tmp)
+  })
+})

package/src/lib/__tests__/command-dx.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test'
+import { CommanderError } from 'commander'
+
+import { buildProgram } from '../../program'
+import { collectCommandCatalog, renderCommanderError } from '../command-dx'
+
+// `renderCommanderError` styles commands with `chalk.bold`, which emits ANSI
+// codes only when chalk detects a color-capable stdout (TTY). Strip them so the
+// assertions are deterministic whether the suite runs under a TTY or in CI.
+// (Built from a char code so the regex source carries no literal control char.)
+const ANSI_RE = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g')
+const stripAnsi = (s: string): string => s.replace(ANSI_RE, '')
+
+describe('command DX suggestions', () => {
+  test('collects command paths from the registered program tree', async () => {
+    const program = await buildProgram()
+    const usages = collectCommandCatalog(program).map((entry) => entry.usage)
+
+    expect(usages).toContain('identity use <name>')
+    expect(usages).toContain('instance use [name]')
+    expect(usages).toContain('admin status')
+    expect(usages).toContain('admin use [bookmark]')
+    expect(usages).toContain('use <name>')
+    expect(usages).toContain('update')
+    expect(usages).toContain('ls [path]')
+    expect(usages).toContain('status')
+  })
+
+  test('explains shared verbs as namespaced commands, not arity errors', async () => {
+    const program = await buildProgram()
+    const error = new CommanderError(
+      1,
+      'commander.excessArguments',
+      'error: too many arguments. Expected 0 arguments but got 2.',
+    )
+    const rendered = stripAnsi(renderCommanderError(program, error, ['delete', 'demo-system']))
+
+    expect(rendered).toContain('Unknown command: astrale delete demo-system')
+    expect(rendered).toContain('"delete" is available under:')
+    expect(rendered).toContain('astrale identity delete <name>')
+    expect(rendered).toContain('astrale instance delete <id>')
+    expect(rendered).not.toContain('too many arguments')
+  })
+
+  test('suggests nearest command for typo paths', async () => {
+    const program = await buildProgram()
+    const error = new CommanderError(
+      1,
+      'commander.excessArguments',
+      'error: too many arguments. Expected 0 arguments but got 2.',
+    )
+    const rendered = stripAnsi(renderCommanderError(program, error, ['indetityl', 'ist']))
+
+    expect(rendered).toContain('Unknown command: astrale indetityl ist')
+    expect(rendered).toContain('Did you mean:')
+    expect(rendered).toContain('astrale identity list')
+  })
+})

package/src/lib/__tests__/concurrency.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test'
+
+import { mapBounded } from '../concurrency'
+
+const tick = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+describe('mapBounded', () => {
+  test('preserves input order regardless of completion order', async () => {
+    const out = await mapBounded([30, 10, 20, 0], 4, async (ms, i) => {
+      await tick(ms)
+      return i
+    })
+    expect(out).toEqual([0, 1, 2, 3])
+  })
+
+  test('never exceeds the concurrency bound', async () => {
+    let inFlight = 0
+    let peak = 0
+    await mapBounded(
+      Array.from({ length: 12 }, (_, i) => i),
+      3,
+      async () => {
+        inFlight++
+        peak = Math.max(peak, inFlight)
+        await tick(5)
+        inFlight--
+      },
+    )
+    expect(peak).toBeLessThanOrEqual(3)
+  })
+
+  test('processes every item exactly once', async () => {
+    const seen: number[] = []
+    await mapBounded([1, 2, 3, 4, 5], 2, async (n) => {
+      seen.push(n)
+    })
+    expect(seen.sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5])
+  })
+
+  test('empty input → empty output, fn never called', async () => {
+    let called = false
+    const out = await mapBounded([], 4, async () => {
+      called = true
+    })
+    expect(out).toEqual([])
+    expect(called).toBe(false)
+  })
+
+  test('limit below 1 is clamped (still makes progress)', async () => {
+    const out = await mapBounded([1, 2, 3], 0, async (n) => n * 2)
+    expect(out).toEqual([2, 4, 6])
+  })
+
+  test('a rejection propagates', async () => {
+    await expect(
+      mapBounded([1, 2, 3], 2, async (n) => {
+        if (n === 2) throw new Error('boom')
+        return n
+      }),
+    ).rejects.toThrow('boom')
+  })
+})

package/src/lib/__tests__/config.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test'
+
+import { DEFAULT_ADMIN_TARGET_URL } from '../admin-target'
+import { AstraleConfigSchema } from '../config'
+
+describe('AstraleConfigSchema', () => {
+  test('parses valid config', () => {
+    const result = AstraleConfigSchema.parse({
+      issuer: 'https://test.astrale.ai',
+    })
+    expect(result.issuer).toBe('https://test.astrale.ai')
+    expect(result.admin.url).toBe(DEFAULT_ADMIN_TARGET_URL)
+  })
+
+  test('applies defaults for empty object', () => {
+    const result = AstraleConfigSchema.parse({})
+    expect(result.issuer).toBe('https://unregistered.invalid')
+    expect(result.admin).toEqual({
+      name: 'admin',
+      url: DEFAULT_ADMIN_TARGET_URL,
+      issuer: DEFAULT_ADMIN_TARGET_URL,
+    })
+  })
+
+  test('rejects non-url issuer', () => {
+    expect(() => AstraleConfigSchema.parse({ issuer: 'not-a-url' })).toThrow()
+  })
+
+  test('strips removed local-runtime config keys', () => {
+    const result = AstraleConfigSchema.parse({
+      issuer: 'https://test.astrale.ai',
+      managerPort: 9000,
+      removedRuntimeKey: true,
+    })
+    expect('managerPort' in result).toBe(false)
+    expect('removedRuntimeKey' in result).toBe(false)
+  })
+
+  test('accepts configured admin bookmark', () => {
+    const result = AstraleConfigSchema.parse({
+      admin: { instance: 'staging-admin' },
+    })
+    expect(result.admin).toEqual({ instance: 'staging-admin' })
+  })
+
+  test('rejects admin config with url and instance together', () => {
+    expect(() =>
+      AstraleConfigSchema.parse({
+        admin: { url: DEFAULT_ADMIN_TARGET_URL, instance: 'admin' },
+      }),
+    ).toThrow()
+  })
+})

package/src/lib/__tests__/design.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from 'bun:test'
+
+import { IdentifierCollisionError, ReservedSlugError } from '../../errors'
+import { InstanceStoreSchema, assertNoCollision, resolveInstanceKey } from '../instance'
+import { validateSlug } from '../validation'
+
+const baseStore = InstanceStoreSchema.parse({
+  active: 'staging',
+  instances: {
+    staging: {
+      url: 'https://staging.example.com',
+      createdAt: '2024-02-01T00:00:00Z',
+      slug: 'staging',
+      name: 'Staging Cluster',
+      kind: 'bookmark',
+      mode: 'remote',
+    },
+    localdev: {
+      url: 'https://localdev.example.com',
+      createdAt: '2024-02-02T00:00:00Z',
+      slug: 'localdev',
+      kind: 'bookmark',
+      mode: 'remote',
+    },
+  },
+})
+
+describe('DESIGN — §4.7 slug + namespace', () => {
+  test('validateSlug accepts URL-safe slugs', () => {
+    expect(() => validateSlug('foo')).not.toThrow()
+    expect(() => validateSlug('foo-bar')).not.toThrow()
+    expect(() => validateSlug('f00-bar-1')).not.toThrow()
+  })
+
+  test('validateSlug rejects invalid slugs', () => {
+    expect(() => validateSlug('Foo')).toThrow(/Invalid slug/)
+    expect(() => validateSlug('-foo')).toThrow(/Invalid slug/)
+    expect(() => validateSlug('foo_bar')).toThrow(/Invalid slug/)
+    expect(() => validateSlug('foo.bar')).toThrow(/Invalid slug/)
+    expect(() => validateSlug('')).toThrow(/Invalid slug/)
+  })
+
+  test('validateSlug rejects reserved "manager"', () => {
+    expect(() => validateSlug('manager')).toThrow(ReservedSlugError)
+  })
+
+  test('assertNoCollision rejects existing key', () => {
+    expect(() => assertNoCollision(baseStore, ['staging'])).toThrow(IdentifierCollisionError)
+  })
+
+  test('assertNoCollision rejects existing slug', () => {
+    expect(() => assertNoCollision(baseStore, ['localdev'])).toThrow(IdentifierCollisionError)
+  })
+
+  test('assertNoCollision rejects existing name', () => {
+    expect(() => assertNoCollision(baseStore, ['Staging Cluster'])).toThrow(
+      IdentifierCollisionError,
+    )
+  })
+
+  test('assertNoCollision accepts new identifier', () => {
+    expect(() => assertNoCollision(baseStore, ['newname'])).not.toThrow()
+  })
+
+  test('assertNoCollision ignoreKey skips that entry', () => {
+    expect(() =>
+      assertNoCollision(baseStore, ['staging', 'Staging Cluster'], 'staging'),
+    ).not.toThrow()
+  })
+})
+
+describe('DESIGN — §7 resolver', () => {
+  test('resolveInstanceKey matches by key', () => {
+    expect(resolveInstanceKey(baseStore, 'staging')).toBe('staging')
+  })
+
+  test('resolveInstanceKey matches by slug', () => {
+    expect(resolveInstanceKey(baseStore, 'localdev')).toBe('localdev')
+  })
+
+  test('resolveInstanceKey matches by name', () => {
+    expect(resolveInstanceKey(baseStore, 'Staging Cluster')).toBe('staging')
+  })
+
+  test('resolveInstanceKey returns null on miss', () => {
+    expect(resolveInstanceKey(baseStore, 'nope')).toBeNull()
+  })
+})
+
+describe('DESIGN — backward compat registry', () => {
+  test('legacy store without kind/slug/mode parses', () => {
+    const legacy = InstanceStoreSchema.parse({
+      active: 'old',
+      instances: { old: { url: 'http://x', createdAt: '2023-01-01' } },
+    })
+    expect(legacy.instances.old.kind).toBeUndefined()
+    expect(legacy.instances.old.mode).toBeUndefined()
+  })
+})

package/src/lib/__tests__/domain-identity.test.ts

@@ -0,0 +1,60 @@
+/**
+ * `inferAlg` regression tests.
+ *
+ * (The historical `collectFunctionSubs` adversarial suite — 15 cases that
+ * pinned the raw-spec edge-walker against both wire forms / both member
+ * namespaces — was removed when the CLI converged onto the kernel's
+ * canonical resolver. Subs derivation now runs the IDENTICAL
+ * `Graph.fromWire` → `deserializeDomainFromGraph` → `collectFunctionSubs`
+ * pipeline the kernel uses at install validation, so drift is impossible
+ * by construction. The contract is pinned by
+ * `kernel/core/__tests__/domain/resolve-callables-agreement.test.ts`.)
+ */
+
+import { describe, expect, test } from 'bun:test'
+
+import { AstraleError } from '../../errors'
+import { inferAlg } from '../domain-identity'
+
+describe('inferAlg', () => {
+  // Adversarial: older CLI releases generated ES256 keys without
+  // stamping `alg`. Every fresh-machine `astrale domain install` then
+  // crashed with "alg is required when jwk.alg is not present" because the
+  // CLI read `privateJwk.alg as string` directly and handed `undefined` to
+  // jose's importJWK. The fix sets `alg` at keygen time AND falls back to
+  // inferring from `crv`/`kty` for already-issued keys (META_TRACE #34).
+
+  test('returns explicit alg when present', () => {
+    expect(inferAlg({ alg: 'ES256' })).toBe('ES256')
+    expect(inferAlg({ alg: 'EdDSA' })).toBe('EdDSA')
+  })
+
+  test('infers ES256 from P-256 EC keys (crv + kty) when alg is missing', () => {
+    expect(inferAlg({ kty: 'EC', crv: 'P-256' })).toBe('ES256')
+  })
+
+  test('infers EdDSA from Ed25519 OKP keys (crv + kty) when alg is missing', () => {
+    expect(inferAlg({ kty: 'OKP', crv: 'Ed25519' })).toBe('EdDSA')
+  })
+
+  test('explicit alg wins over inferable shape (no second-guessing)', () => {
+    // If a file says ES256 but has Ed25519 components, that's a broken
+    // file — don't silently override. assertKeyPairConsistent will catch
+    // the mismatch downstream.
+    expect(inferAlg({ alg: 'ES256', kty: 'OKP', crv: 'Ed25519' })).toBe('ES256')
+  })
+
+  test('throws AstraleError with hint when no alg/crv/kty resolves', () => {
+    expect(() => inferAlg({})).toThrow(AstraleError)
+    expect(() => inferAlg({ kty: 'EC' })).toThrow(AstraleError)
+    expect(() => inferAlg({ kty: 'EC', crv: 'P-384' })).toThrow(AstraleError)
+  })
+
+  test('error message includes keyPath when provided', () => {
+    expect(() => inferAlg({}, '/path/to/broken.jwk')).toThrow(/\/path\/to\/broken\.jwk/)
+  })
+
+  test('treats empty-string alg as missing', () => {
+    expect(inferAlg({ alg: '', kty: 'EC', crv: 'P-256' })).toBe('ES256')
+  })
+})

package/src/lib/__tests__/format.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from 'bun:test'
+
+import { formatElapsed } from '../format'
+
+describe('formatElapsed', () => {
+  test('formats milliseconds under 1s', () => {
+    expect(formatElapsed(50)).toBe('50ms')
+    expect(formatElapsed(999)).toBe('999ms')
+    expect(formatElapsed(0)).toBe('0ms')
+  })
+
+  test('rounds fractional ms', () => {
+    expect(formatElapsed(50.7)).toBe('51ms')
+    expect(formatElapsed(0.4)).toBe('0ms')
+  })
+
+  test('formats seconds at 1000ms+', () => {
+    expect(formatElapsed(1000)).toBe('1.00s')
+    expect(formatElapsed(1500)).toBe('1.50s')
+    expect(formatElapsed(12345)).toBe('12.35s')
+  })
+})

package/src/lib/__tests__/fs-atomic.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, readdir, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { atomicWrite, withFileLock } from '../fs-atomic'
+
+let tmp: string
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'astrale-fs-atomic-'))
+})
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true })
+})
+
+describe('atomicWrite', () => {
+  test('writes the content with mode 0600 and leaves no tmp files behind', async () => {
+    const path = join(tmp, 'out.json')
+
+    await atomicWrite(path, '{"a":1}')
+
+    expect(await readFile(path, 'utf-8')).toBe('{"a":1}')
+    expect(((await stat(path)).mode & 0o777).toString(8)).toBe('600')
+    expect(await readdir(tmp)).toEqual(['out.json'])
+  })
+})
+
+describe('withFileLock', () => {
+  test('serializes concurrent read-modify-write cycles', async () => {
+    const lockPath = join(tmp, 'counter.lock')
+    const counterPath = join(tmp, 'counter')
+    await writeFile(counterPath, '0')
+
+    const bump = () =>
+      withFileLock(
+        lockPath,
+        async () => {
+          const value = Number(await readFile(counterPath, 'utf-8'))
+          await new Promise((r) => setTimeout(r, 2))
+          await writeFile(counterPath, String(value + 1))
+        },
+        { pollIntervalMs: 2 },
+      )
+    await Promise.all(Array.from({ length: 20 }, bump))
+
+    expect(await readFile(counterPath, 'utf-8')).toBe('20')
+  })
+
+  test('takes over a lock whose mtime is stale', async () => {
+    const lockPath = join(tmp, 'stale.lock')
+    await writeFile(lockPath, JSON.stringify({ pid: process.pid }))
+    const past = new Date(Date.now() - 60_000)
+    await utimes(lockPath, past, past)
+
+    const ran = await withFileLock(lockPath, async () => 'ran', { pollIntervalMs: 5 })
+
+    expect(ran).toBe('ran')
+  })
+
+  test('takes over a fresh lock held by a dead pid', async () => {
+    const lockPath = join(tmp, 'dead.lock')
+    await writeFile(lockPath, JSON.stringify({ pid: 99999999 }))
+
+    const ran = await withFileLock(lockPath, async () => 'ran', { pollIntervalMs: 5 })
+
+    expect(ran).toBe('ran')
+  })
+
+  test('releases the lock when fn throws', async () => {
+    const lockPath = join(tmp, 'throw.lock')
+
+    await expect(
+      withFileLock(lockPath, async () => {
+        throw new Error('boom')
+      }),
+    ).rejects.toThrow('boom')
+
+    const ran = await withFileLock(lockPath, async () => 'ran', { timeoutMs: 200 })
+    expect(ran).toBe('ran')
+  })
+
+  test('creates a missing parent directory', async () => {
+    const lockPath = join(tmp, 'nested', 'deep', 'a.lock')
+
+    const ran = await withFileLock(lockPath, async () => 'ran')
+
+    expect(ran).toBe('ran')
+  })
+
+  test('times out while a live holder keeps the lock', async () => {
+    const lockPath = join(tmp, 'held.lock')
+    await writeFile(lockPath, JSON.stringify({ pid: process.pid }))
+
+    await expect(
+      withFileLock(lockPath, async () => 'ran', {
+        pollIntervalMs: 20,
+        staleAfterMs: 60_000,
+        timeoutMs: 150,
+      }),
+    ).rejects.toThrow('Timed out')
+  })
+})