@astrale-os/cli 0.4.0-alpha.13

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@astrale-os/cli",
+  "version": "0.4.0-alpha.13",
+  "description": "Astrale CLI — connect to existing Astrale kernels",
+  "keywords": [
+    "astrale",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Astrale",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astrale-os/cli.git"
+  },
+  "bin": {
+    "astrale": "./dist/astrale.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    ".check-workspace.cjs",
+    "studio/server",
+    "studio/shared",
+    "studio/client/dist",
+    "studio/package.json"
+  ],
+  "type": "module",
+  "exports": {
+    "./keys": "./src/lib/keys.ts",
+    "./paths": "./src/lib/paths.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "preinstall": "node .check-workspace.cjs",
+    "prepare": "husky",
+    "build": "bun scripts/build.ts",
+    "prepack": "bun scripts/build.ts",
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "pnpm exec oxfmt --write .",
+    "format:check": "pnpm exec oxfmt --check .",
+    "test": "bun test src",
+    "test:watch": "bun test --watch src"
+  },
+  "dependencies": {
+    "@astrale-os/kernel-client": ">=0.2.0 <1.0.0",
+    "@astrale-os/kernel-core": ">=0.4.1 <1.0.0",
+    "@inquirer/prompts": "^8.5.2",
+    "chalk": "^5.6.2",
+    "chokidar": "^4.0.3",
+    "commander": ">=13.0.0 <14.0.0",
+    "jose": "^6.1.3",
+    "ora": "^9.0.0",
+    "ts-morph": "^25.0.1",
+    "yaml": "^2.8.2",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@astrale-os/ox": ">=0.1.0 <1.0.0",
+    "@astrale/commitlint-config": "jsr:~2.0.1",
+    "@commitlint/cli": "~20.3.1",
+    "@commitlint/config-conventional": "~20.3.1",
+    "@types/bun": "^1.1.16",
+    "@types/node": "^22.0.0",
+    "@typescript/native-preview": "latest",
+    "husky": "~9.1.7",
+    "lint-staged": "~16.2.7",
+    "oxfmt": "0.52.0",
+    "oxlint": "latest",
+    "typescript": "~6.0.1-rc"
+  },
+  "lint-staged": {
+    "*.{js,cjs,mjs,ts,tsx}": [
+      "oxlint --fix --no-error-on-unmatched-pattern",
+      "oxfmt --write"
+    ],
+    "*.{json,yml,yaml}": [
+      "oxfmt --write"
+    ]
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.28.0"
+}

package/src/command.ts

@@ -0,0 +1,40 @@
+export type CommandArgument = {
+  name: string
+  description: string
+  required?: boolean
+}
+
+export type CommandOption = {
+  flags: string
+  description: string
+  default?: string
+  choices?: string[]
+}
+
+export type CommandDefinition = {
+  name: string
+  description: string
+  /** One-line summary shown in the parent's command list (Commander `.summary()`). */
+  summary?: string
+  aliases?: string[]
+  arguments?: CommandArgument[]
+  options?: CommandOption[]
+  /**
+   * Free-form prose appended to `<cmd> --help` (Commander `addHelpText('after')`).
+   * Use for command-local behavior the flag list cannot express + canonical
+   * examples. Pre-wrap lines to ~78 cols — Commander prints it verbatim.
+   */
+  afterHelpText?: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Commander passes typed args at runtime
+  action: (...args: any[]) => Promise<void>
+}
+
+export type CommandGroup = {
+  name: string
+  description: string
+  /** One-line summary shown in the program's command list (Commander `.summary()`). */
+  summary?: string
+  commands: CommandDefinition[]
+  /** Nested subgroups (one extra level of `astrale foo bar baz` nesting). */
+  subgroups?: CommandGroup[]
+}

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

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { IdentityStore } from '../../lib/identity'
+
+import { AuthError } from '../../errors'
+import { ADMIN_INSTANCE } from '../../lib/admin-instance'
+import { assertAlphaCreateIdentity } from '../instance/create'
+
+describe('admin-backed instance commands', () => {
+  test('target the merged Instance class', () => {
+    expect(ADMIN_INSTANCE).toBe('/admin.astrale.ai/class.Instance')
+  })
+
+  test('instance create preflight points fresh installs at WorkOS login', () => {
+    const store: IdentityStore = {
+      default: 'manager',
+      identities: {
+        manager: {
+          subject: 'manager',
+          createdAt: '2026-06-08T00:00:00.000Z',
+          source: 'key',
+          mode: 'local',
+        },
+      },
+    }
+
+    expect(() => assertAlphaCreateIdentity(store)).toThrow(AuthError)
+    expect(() => assertAlphaCreateIdentity(store)).toThrow('WorkOS login required')
+  })
+
+  test('instance create preflight accepts IdP-backed identities', () => {
+    const store: IdentityStore = {
+      default: 'bryan',
+      identities: {
+        bryan: {
+          subject: 'user_123',
+          createdAt: '2026-06-08T00:00:00.000Z',
+          source: 'idp',
+          mode: 'remote',
+          idp: 'workos',
+          issuer: 'https://auth.example.com',
+        },
+      },
+    }
+
+    expect(() => assertAlphaCreateIdentity(store)).not.toThrow()
+  })
+
+  test('--as selection must also be IdP-backed', () => {
+    const store: IdentityStore = {
+      default: 'local',
+      identities: {
+        local: {
+          subject: 'local',
+          createdAt: '2026-06-08T00:00:00.000Z',
+          source: 'key',
+          mode: 'local',
+        },
+        workos: {
+          subject: 'user_123',
+          createdAt: '2026-06-08T00:00:00.000Z',
+          source: 'idp',
+          mode: 'remote',
+          idp: 'workos',
+          issuer: 'https://auth.example.com',
+        },
+      },
+    }
+
+    expect(() => assertAlphaCreateIdentity(store, { as: 'local' })).toThrow(AuthError)
+    expect(() => assertAlphaCreateIdentity(store, { as: 'workos' })).not.toThrow()
+  })
+})

package/src/commands/__tests__/auth-login.test.ts

@@ -0,0 +1,178 @@
+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-auth-login-'))
+})
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true })
+})
+
+describe('auth login command', () => {
+  test('rejects requested audience when provider mints a different access-token aud', async () => {
+    const server = oauthServer({
+      accessToken: unsignedJwt({
+        iss: 'http://127.0.0.1',
+        sub: 'user_123',
+        aud: 'unknown/api',
+        exp: 1893456000,
+      }),
+    })
+    try {
+      await writeIdpConfig(server.url)
+
+      const result = await runAuthLogin(
+        '--idp',
+        'test',
+        '--name',
+        'alice',
+        '--client-credentials',
+        '--client-secret-env',
+        'TEST_CLIENT_SECRET',
+        '--audience',
+        'https://kernel.example.com',
+        '--raw',
+      )
+
+      expect(result.exitCode).toBe(1)
+      expect(result.stderr).toContain(
+        'IdP response access_token was not minted for requested audience https://kernel.example.com',
+      )
+      expect(
+        await readFile(join(tmp, 'idp-sessions', 'alice.json'), 'utf-8').catch(() => null),
+      ).toBeNull()
+    } finally {
+      await server.stop()
+    }
+  })
+
+  test('stores the session when provider mints the requested access-token aud', async () => {
+    const server = oauthServer({
+      accessToken: unsignedJwt({
+        iss: 'http://127.0.0.1',
+        sub: 'user_123',
+        aud: 'https://kernel.example.com',
+        exp: 1893456000,
+      }),
+    })
+    try {
+      await writeIdpConfig(server.url)
+
+      const result = await runAuthLogin(
+        '--idp',
+        'test',
+        '--name',
+        'alice',
+        '--client-credentials',
+        '--client-secret-env',
+        'TEST_CLIENT_SECRET',
+        '--audience',
+        'https://kernel.example.com',
+        '--raw',
+      )
+
+      expect(result.exitCode).toBe(0)
+      const session = JSON.parse(await readFile(join(tmp, 'idp-sessions', 'alice.json'), 'utf-8'))
+      expect(session.audience).toBe('https://kernel.example.com')
+      expect(session.subject).toBe('user_123')
+    } finally {
+      await server.stop()
+    }
+  })
+})
+
+async function writeIdpConfig(baseUrl: string): Promise<void> {
+  await mkdir(join(tmp, 'idps', 'test'), { recursive: true })
+  await writeFile(
+    join(tmp, 'idps', 'index.json'),
+    JSON.stringify(
+      {
+        idps: {
+          test: {
+            issuer: baseUrl,
+            createdAt: '2026-01-01T00:00:00.000Z',
+            updatedAt: '2026-01-01T00:00:00.000Z',
+          },
+        },
+      },
+      null,
+      2,
+    ) + '\n',
+  )
+  await writeFile(
+    join(tmp, 'idps', 'test', 'metadata.json'),
+    JSON.stringify(
+      {
+        issuer: baseUrl,
+        token_endpoint: `${baseUrl}/token`,
+        jwks_uri: `${baseUrl}/jwks`,
+      },
+      null,
+      2,
+    ) + '\n',
+  )
+  await writeFile(
+    join(tmp, 'idps', 'test', 'client.json'),
+    JSON.stringify(
+      {
+        client_id: 'client_123',
+        client_secret_env: 'TEST_CLIENT_SECRET',
+      },
+      null,
+      2,
+    ) + '\n',
+  )
+}
+
+function oauthServer(args: { accessToken: string }): { url: string; stop: () => Promise<void> } {
+  const server = Bun.serve({
+    port: 0,
+    fetch: async (request) => {
+      const url = new URL(request.url)
+      if (url.pathname !== '/token') return new Response('not found', { status: 404 })
+      return Response.json({
+        access_token: args.accessToken,
+        token_type: 'Bearer',
+        expires_in: 3600,
+      })
+    },
+  })
+  return {
+    url: `http://${server.hostname}:${server.port}`,
+    stop: () => server.stop(true),
+  }
+}
+
+async function runAuthLogin(...args: string[]): Promise<{
+  exitCode: number
+  stdout: string
+  stderr: string
+}> {
+  const proc = Bun.spawn({
+    cmd: ['bun', join(cliRoot, 'bin/astrale.ts'), 'auth', 'login', ...args],
+    env: { ...process.env, ASTRALE_HOME: tmp, TEST_CLIENT_SECRET: 'secret_123' },
+    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 }
+}
+
+function unsignedJwt(payload: Record<string, unknown>): string {
+  return [base64url({ alg: 'none', typ: 'JWT' }), base64url(payload), ''].join('.')
+}
+
+function base64url(value: Record<string, unknown>): string {
+  return Buffer.from(JSON.stringify(value)).toString('base64url')
+}

package/src/commands/__tests__/auth-token.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdir, mkdtemp, 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-auth-token-'))
+  await mkdir(join(tmp, 'idp-sessions'), { recursive: true })
+  await writeFile(
+    join(tmp, 'identities.json'),
+    JSON.stringify(
+      {
+        default: 'alice',
+        identities: {
+          alice: {
+            subject: 'user_123',
+            createdAt: '2026-01-01T00:00:00.000Z',
+            source: 'idp',
+            mode: 'remote',
+            idp: 'workos',
+            issuer: 'https://api.workos.com',
+          },
+        },
+      },
+      null,
+      2,
+    ) + '\n',
+  )
+  await writeFile(
+    join(tmp, 'idp-sessions', 'alice.json'),
+    JSON.stringify(
+      {
+        identity: 'alice',
+        idp: 'workos',
+        issuer: 'https://api.workos.com',
+        subject: 'user_123',
+        access_token: 'access-token-123',
+        id_token: 'id-token-123',
+        token_type: 'Bearer',
+        scope: 'openid profile email',
+        expires_at: '2999-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      },
+      null,
+      2,
+    ) + '\n',
+  )
+})
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true })
+})
+
+describe('auth token command', () => {
+  test('prints the active IdP access token with --raw', async () => {
+    const result = await runAuthToken('--raw')
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toBe('access-token-123\n')
+    expect(result.stderr).toBe('')
+  })
+
+  test('can select by IdP and print id token metadata as JSON', async () => {
+    const result = await runAuthToken('--idp', 'workos', '--type', 'id', '--json')
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stderr).toBe('')
+
+    const body = JSON.parse(result.stdout) as { identity: string; type: string; token: string }
+    expect(body.identity).toBe('alice')
+    expect(body.type).toBe('id')
+    expect(body.token).toBe('id-token-123')
+  })
+
+  test('two parallel CLI processes refresh a single-use token exactly once', async () => {
+    const server = rotationServer()
+    try {
+      await writeExpiredSessionWithIdp(server.url)
+
+      const [a, b] = await Promise.all([runAuthToken('--raw'), runAuthToken('--raw')])
+
+      expect(a.exitCode).toBe(0)
+      expect(b.exitCode).toBe(0)
+      expect(a.stdout).toBe(b.stdout)
+      expect(server.refreshCount()).toBe(1)
+    } finally {
+      await server.stop()
+    }
+  })
+
+  test('an IdP outage does not tell the user to re-login', async () => {
+    const server = rotationServer({ status: 503 })
+    try {
+      await writeExpiredSessionWithIdp(server.url)
+
+      const result = await runAuthToken('--raw')
+
+      expect(result.exitCode).toBe(1)
+      expect(result.stderr).not.toContain('astrale auth login')
+    } finally {
+      await server.stop()
+    }
+  })
+
+  test('--no-refresh prints the cached token without contacting the IdP', async () => {
+    const server = rotationServer()
+    try {
+      await writeExpiredSessionWithIdp(server.url)
+
+      const result = await runAuthToken('--raw', '--no-refresh')
+
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toBe('expired-access-token\n')
+      expect(server.refreshCount()).toBe(0)
+    } finally {
+      await server.stop()
+    }
+  })
+})
+
+async function writeExpiredSessionWithIdp(baseUrl: string): Promise<void> {
+  await mkdir(join(tmp, 'idps', 'test'), { recursive: true })
+  await writeFile(
+    join(tmp, 'idps', 'index.json'),
+    JSON.stringify({
+      idps: {
+        test: {
+          issuer: baseUrl,
+          createdAt: '2026-01-01T00:00:00.000Z',
+          updatedAt: '2026-01-01T00:00:00.000Z',
+        },
+      },
+    }),
+  )
+  await writeFile(
+    join(tmp, 'idps', 'test', 'metadata.json'),
+    JSON.stringify({
+      issuer: baseUrl,
+      token_endpoint: `${baseUrl}/token`,
+      jwks_uri: `${baseUrl}/jwks`,
+    }),
+  )
+  await writeFile(join(tmp, 'idps', 'test', 'client.json'), JSON.stringify({ client_id: 'c_1' }))
+  await writeFile(
+    join(tmp, 'idp-sessions', 'alice.json'),
+    JSON.stringify({
+      identity: 'alice',
+      idp: 'test',
+      issuer: baseUrl,
+      subject: 'user_123',
+      access_token: 'expired-access-token',
+      refresh_token: 'rt-0',
+      token_type: 'Bearer',
+      expires_at: new Date(Date.now() - 3_600_000).toISOString(),
+      updatedAt: '2026-01-01T00:00:00.000Z',
+    }),
+  )
+}
+
+function rotationServer(opts?: { status?: number }): {
+  url: string
+  refreshCount: () => number
+  stop: () => Promise<void>
+} {
+  // WorkOS-style single-use rotation: presenting anything but the CURRENT
+  // refresh token is invalid_grant.
+  let current = 'rt-0'
+  let count = 0
+  const server = Bun.serve({
+    port: 0,
+    fetch: async (request) => {
+      const url = new URL(request.url)
+      if (url.pathname !== '/token') return new Response('not found', { status: 404 })
+      if (opts?.status) {
+        return Response.json({ error_description: 'unavailable' }, { status: opts.status })
+      }
+      const form = new URLSearchParams(await request.text())
+      if (form.get('refresh_token') !== current) {
+        return Response.json(
+          { error: 'invalid_grant', error_description: 'Refresh token already exchanged.' },
+          { status: 400 },
+        )
+      }
+      await new Promise((r) => setTimeout(r, 50))
+      count += 1
+      current = `rt-${count}`
+      return Response.json({
+        access_token: `rotated-access-${count}`,
+        refresh_token: current,
+        token_type: 'Bearer',
+        expires_in: 3600,
+      })
+    },
+  })
+  return {
+    url: `http://${server.hostname}:${server.port}`,
+    refreshCount: () => count,
+    stop: () => server.stop(true),
+  }
+}
+
+async function runAuthToken(...args: string[]): Promise<{
+  exitCode: number
+  stdout: string
+  stderr: string
+}> {
+  const proc = Bun.spawn({
+    cmd: ['bun', join(cliRoot, 'bin/astrale.ts'), 'auth', 'token', ...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__/call.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'bun:test'
+
+import { parseKeyValue, coerceValue } from '../call'
+
+describe('coerceValue', () => {
+  test('parses JSON objects', () => {
+    expect(coerceValue('{"a":1}')).toEqual({ a: 1 })
+  })
+
+  test('parses JSON arrays', () => {
+    expect(coerceValue('[1,2,3]')).toEqual([1, 2, 3])
+  })
+
+  test('falls through on invalid JSON object', () => {
+    expect(coerceValue('{not-json}')).toBe('{not-json}')
+  })
+
+  test('parses booleans', () => {
+    expect(coerceValue('true')).toBe(true)
+    expect(coerceValue('false')).toBe(false)
+  })
+
+  test('parses null', () => {
+    expect(coerceValue('null')).toBe(null)
+  })
+
+  test('parses numbers', () => {
+    expect(coerceValue('42')).toBe(42)
+    expect(coerceValue('3.14')).toBe(3.14)
+    expect(coerceValue('-1')).toBe(-1)
+    expect(coerceValue('0')).toBe(0)
+  })
+
+  test('returns strings for non-special values', () => {
+    expect(coerceValue('hello')).toBe('hello')
+    expect(coerceValue('')).toBe('')
+    expect(coerceValue('some text')).toBe('some text')
+  })
+
+  test('preserves hex, octal, and exotic numeric strings as strings', () => {
+    expect(coerceValue('0x1f')).toBe('0x1f')
+    expect(coerceValue('0o77')).toBe('0o77')
+    expect(coerceValue('0b101')).toBe('0b101')
+    expect(coerceValue('1e308')).toBe('1e308')
+    expect(coerceValue('Infinity')).toBe('Infinity')
+  })
+})
+
+describe('parseKeyValue', () => {
+  test('parses simple key=value pairs', () => {
+    expect(parseKeyValue(['name=test', 'count=5'])).toEqual({
+      name: 'test',
+      count: 5,
+    })
+  })
+
+  test('handles values with = in them', () => {
+    expect(parseKeyValue(['query=a=b'])).toEqual({ query: 'a=b' })
+  })
+
+  test('throws on missing =', () => {
+    expect(() => parseKeyValue(['noequals'])).toThrow('expected key=value')
+  })
+
+  test('parses JSON values', () => {
+    expect(parseKeyValue(['data={"x":1}'])).toEqual({ data: { x: 1 } })
+  })
+
+  test('handles empty value', () => {
+    expect(parseKeyValue(['key='])).toEqual({ key: '' })
+  })
+})