@astrale-os/cli 0.4.0-alpha.13

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

@@ -0,0 +1,246 @@
+import { describe, expect, test } from 'bun:test'
+import { chmod, mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  releaseBase,
+  shouldUpdate,
+  updateAstrale,
+  writeInstallMetadata,
+  type InstallMetadata,
+} from '../update'
+
+async function makeFakeRelease(
+  root: string,
+  version: string,
+  options: { binaryVersion?: string; legacyManifest?: boolean } = {},
+): Promise<string> {
+  const release = join(root, 'release')
+  const payload = join(root, 'payload')
+  const binaryVersion = options.binaryVersion ?? version
+  await mkdir(release, { recursive: true })
+  await mkdir(payload, { recursive: true })
+  await writeFile(
+    join(payload, 'astrale'),
+    `#!/usr/bin/env sh\nif [ "$1" = "--version" ]; then echo "${binaryVersion}"; exit 0; fi\necho astrale\n`,
+  )
+  await chmod(join(payload, 'astrale'), 0o755)
+
+  const asset = join(release, 'astrale-darwin-arm64.tar.gz')
+  const tar = Bun.spawn(['tar', '-C', payload, '-czf', asset, 'astrale'])
+  expect(await tar.exited).toBe(0)
+  const shaProc = Bun.spawn(['shasum', '-a', '256', asset], { stdout: 'pipe' })
+  const sha = (await new Response(shaProc.stdout).text()).trim().split(/\s+/)[0]
+  expect(await shaProc.exited).toBe(0)
+  await writeFile(join(release, 'sha256sums.txt'), `${sha}  astrale-darwin-arm64.tar.gz\n`)
+  await writeFile(
+    join(release, 'manifest.json'),
+    JSON.stringify(
+      {
+        version,
+        binaryVersion: options.binaryVersion,
+        channel: 'alpha',
+        repo: 'astrale-os/cli',
+        assets: options.legacyManifest
+          ? {
+              'darwin-arm64': 'astrale-darwin-arm64.tar.gz',
+            }
+          : {
+              'darwin-arm64': {
+                name: 'astrale-darwin-arm64.tar.gz',
+                sha256: sha,
+              },
+            },
+      },
+      null,
+      2,
+    ),
+  )
+  return release
+}
+
+async function makeInstall(
+  root: string,
+  version: string,
+): Promise<{ meta: InstallMetadata; path: string }> {
+  const bin = join(root, 'bin', 'astrale')
+  await mkdir(join(root, 'bin'), { recursive: true })
+  await writeFile(
+    bin,
+    `#!/usr/bin/env sh\nif [ "$1" = "--version" ]; then echo "${version}"; exit 0; fi\necho old\n`,
+  )
+  await chmod(bin, 0o755)
+  const path = join(root, 'home', 'install.json')
+  const meta: InstallMetadata = {
+    method: 'script',
+    channel: 'alpha',
+    version,
+    repo: 'astrale-os/cli',
+    bin,
+  }
+  await writeInstallMetadata(meta, path)
+  return { meta, path }
+}
+
+describe('update helpers', () => {
+  test('releaseBase resolves exact versions and channels', () => {
+    const meta: InstallMetadata = {
+      method: 'script',
+      channel: 'alpha',
+      repo: 'astrale-os/cli',
+      bin: '/tmp/astrale',
+    }
+    expect(releaseBase(meta, {})).toBe('https://github.com/astrale-os/cli/releases/download/alpha')
+    expect(releaseBase(meta, { channel: 'canary' })).toBe(
+      'https://github.com/astrale-os/cli/releases/download/canary',
+    )
+    expect(releaseBase(meta, { version: '0.4.1' })).toBe(
+      'https://github.com/astrale-os/cli/releases/download/cli/v0.4.1',
+    )
+  })
+
+  test('shouldUpdate is exact and predictable', () => {
+    expect(shouldUpdate('0.4.0', '0.4.0')).toBe(false)
+    expect(shouldUpdate('0.4.0', '0.4.1')).toBe(true)
+  })
+})
+
+describe('updateAstrale', () => {
+  test('check compares the installed release identity from metadata', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { path } = await makeInstall(root, 'main-abc123')
+    const release = await makeFakeRelease(root, 'main-abc123', { binaryVersion: '1.0.0' })
+    process.env.ASTRALE_UPDATE_BASE = `file://${release}`
+    try {
+      const result = await updateAstrale({
+        check: true,
+        currentVersion: '1.0.0',
+        platform: { os: 'darwin', arch: 'arm64' },
+        installPath: path,
+      })
+
+      expect(result).toMatchObject({
+        status: 'up-to-date',
+        currentVersion: 'main-abc123',
+        latestVersion: 'main-abc123',
+      })
+    } finally {
+      delete process.env.ASTRALE_UPDATE_BASE
+    }
+  })
+
+  test('check reports available update without replacing the binary', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { path, meta } = await makeInstall(root, '1.0.0')
+    const release = await makeFakeRelease(root, '1.1.0')
+    process.env.ASTRALE_UPDATE_BASE = `file://${release}`
+    try {
+      const result = await updateAstrale({
+        check: true,
+        currentVersion: '1.0.0',
+        platform: { os: 'darwin', arch: 'arm64' },
+        installPath: path,
+      })
+
+      expect(result).toMatchObject({
+        status: 'available',
+        currentVersion: '1.0.0',
+        latestVersion: '1.1.0',
+      })
+      expect(await readFile(meta.bin, 'utf8')).toContain('echo old')
+    } finally {
+      delete process.env.ASTRALE_UPDATE_BASE
+    }
+  })
+
+  test('supports legacy string asset manifests', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { path, meta } = await makeInstall(root, '1.0.0')
+    const release = await makeFakeRelease(root, '1.1.0', { legacyManifest: true })
+    process.env.ASTRALE_UPDATE_BASE = `file://${release}`
+    try {
+      const check = await updateAstrale({
+        check: true,
+        currentVersion: '1.0.0',
+        platform: { os: 'darwin', arch: 'arm64' },
+        installPath: path,
+      })
+
+      expect(check).toMatchObject({
+        status: 'available',
+        latestVersion: '1.1.0',
+      })
+
+      const result = await updateAstrale({
+        currentVersion: '1.0.0',
+        platform: { os: 'darwin', arch: 'arm64' },
+        installPath: path,
+      })
+
+      expect(result).toMatchObject({
+        status: 'updated',
+        currentVersion: '1.1.0',
+      })
+      const versionProc = Bun.spawn([meta.bin, '--version'], { stdout: 'pipe' })
+      expect(await new Response(versionProc.stdout).text()).toBe('1.1.0\n')
+      expect(await versionProc.exited).toBe(0)
+    } finally {
+      delete process.env.ASTRALE_UPDATE_BASE
+    }
+  })
+
+  test('updates the binary and install metadata', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { path, meta } = await makeInstall(root, '1.0.0')
+    const release = await makeFakeRelease(root, '1.1.0')
+    process.env.ASTRALE_UPDATE_BASE = `file://${release}`
+    try {
+      const result = await updateAstrale({
+        currentVersion: '1.0.0',
+        platform: { os: 'darwin', arch: 'arm64' },
+        installPath: path,
+      })
+
+      expect(result).toMatchObject({
+        status: 'updated',
+        previousVersion: '1.0.0',
+        currentVersion: '1.1.0',
+      })
+      const versionProc = Bun.spawn([meta.bin, '--version'], { stdout: 'pipe' })
+      expect(await new Response(versionProc.stdout).text()).toBe('1.1.0\n')
+      expect(await versionProc.exited).toBe(0)
+      const updatedMeta = JSON.parse(await readFile(path, 'utf8')) as InstallMetadata
+      expect(updatedMeta.version).toBe('1.1.0')
+    } finally {
+      delete process.env.ASTRALE_UPDATE_BASE
+    }
+  })
+
+  test('updates canary-style releases whose binary reports the package version', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { path, meta } = await makeInstall(root, 'main-old123')
+    const release = await makeFakeRelease(root, 'main-new456', { binaryVersion: '1.0.0' })
+    process.env.ASTRALE_UPDATE_BASE = `file://${release}`
+    try {
+      const result = await updateAstrale({
+        currentVersion: '1.0.0',
+        platform: { os: 'darwin', arch: 'arm64' },
+        installPath: path,
+      })
+
+      expect(result).toMatchObject({
+        status: 'updated',
+        previousVersion: 'main-old123',
+        currentVersion: 'main-new456',
+      })
+      const versionProc = Bun.spawn([meta.bin, '--version'], { stdout: 'pipe' })
+      expect(await new Response(versionProc.stdout).text()).toBe('1.0.0\n')
+      expect(await versionProc.exited).toBe(0)
+      const updatedMeta = JSON.parse(await readFile(path, 'utf8')) as InstallMetadata
+      expect(updatedMeta.version).toBe('main-new456')
+    } finally {
+      delete process.env.ASTRALE_UPDATE_BASE
+    }
+  })
+})

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

@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { IdentityStore } from '../identity'
+import type { InstanceStore } from '../instance'
+
+import { resolveUseTarget } from '../use-target'
+
+const instances: InstanceStore = {
+  active: 'staging',
+  instances: {
+    staging: { url: 'https://staging.example.com', slug: 'stage' },
+    prod: { url: 'https://prod.example.com' },
+  },
+}
+
+const identities: IdentityStore = {
+  default: 'alice',
+  identities: {
+    alice: { subject: 'alice', createdAt: '2026-01-01T00:00:00.000Z', source: 'key' },
+    prod: { subject: 'prod-user', createdAt: '2026-01-01T00:00:00.000Z', source: 'key' },
+  },
+}
+
+describe('resolveUseTarget', () => {
+  test('resolves identity-only names', () => {
+    expect(resolveUseTarget('alice', instances, identities)).toEqual({
+      kind: 'identity',
+      name: 'alice',
+    })
+  })
+
+  test('resolves instance keys and slugs', () => {
+    expect(resolveUseTarget('staging', instances, identities)).toEqual({
+      kind: 'instance',
+      name: 'staging',
+    })
+    expect(resolveUseTarget('stage', instances, identities)).toEqual({
+      kind: 'instance',
+      name: 'staging',
+    })
+  })
+
+  test('refuses ambiguous names', () => {
+    expect(resolveUseTarget('prod', instances, identities)).toEqual({
+      kind: 'ambiguous',
+      name: 'prod',
+    })
+  })
+
+  test('reports missing names', () => {
+    expect(resolveUseTarget('missing', instances, identities)).toEqual({
+      kind: 'missing',
+      name: 'missing',
+    })
+  })
+})

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

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test'
+
+import { validateName } from '../validation'
+
+describe('validateName', () => {
+  test('accepts valid names', () => {
+    expect(() => validateName('manager', 'Instance')).not.toThrow()
+    expect(() => validateName('my-instance', 'Instance')).not.toThrow()
+    expect(() => validateName('my_instance', 'Instance')).not.toThrow()
+    expect(() => validateName('my.instance', 'Instance')).not.toThrow()
+    expect(() => validateName('Instance123', 'Instance')).not.toThrow()
+    expect(() => validateName('a', 'Identity')).not.toThrow()
+  })
+
+  test('rejects empty string', () => {
+    expect(() => validateName('', 'Instance')).toThrow(/Invalid instance name/)
+  })
+
+  test('rejects whitespace', () => {
+    expect(() => validateName(' ', 'Instance')).toThrow(/Invalid instance name/)
+    expect(() => validateName('my instance', 'Instance')).toThrow(/Invalid instance name/)
+  })
+
+  test('rejects special characters', () => {
+    expect(() => validateName('my/instance', 'Instance')).toThrow(/Invalid instance name/)
+    expect(() => validateName('my@instance', 'Identity')).toThrow(/Invalid identity name/)
+    expect(() => validateName('name!', 'Instance')).toThrow()
+  })
+
+  test('includes entity type in error message', () => {
+    expect(() => validateName('', 'Instance')).toThrow('instance')
+    expect(() => validateName('', 'Identity')).toThrow('identity')
+  })
+})

package/src/lib/admin-domain.ts

@@ -0,0 +1,25 @@
+/**
+ * The admin `DomainEntry` surface used by `astrale domain publish`. The merged
+ * admin domain models the installable-domain REGISTRY as the `DomainEntry`
+ * class (named `DomainEntry`, not `Domain`, because `Domain` is a reserved
+ * kernel node-kind); `publish` upserts a `name → url` catalog entry the child
+ * kernel later installs from. Publishing only makes a domain INSTALLABLE —
+ * mounting it on an instance is the separate `domain install` step (or the
+ * admin's install-by-default policy).
+ */
+export const ADMIN_DOMAIN = '/admin.astrale.ai/class.DomainEntry'
+
+/** Read shape returned by `DomainEntry.publish` / `info` / `list` (domain `DomainInfoSchema`). */
+export type DomainInfo = {
+  id: string
+  /** dist.astrale.ai — the authority origin (== JWT aud + kernel path prefix). */
+  origin: string
+  /** 'distribution' — the node slug + the id used in install plans / the CLI. */
+  name: string
+  /** https://dist.astrale.ai — the published worker URL the kernel installs from. */
+  url?: string
+  description?: string
+  installByDefault?: boolean
+  createdAt: string
+  updatedAt: string
+}

package/src/lib/admin-instance.ts

@@ -0,0 +1,26 @@
+/**
+ * The admin `Instance` surface used by `astrale instance
+ * list/status/create/delete`. The merged admin domain models instances as the
+ * `Instance` class (provisioned via `Instance.init`); these commands target it.
+ */
+export const ADMIN_INSTANCE = '/admin.astrale.ai/class.Instance'
+
+/** Read shape returned by `Instance.list` / `info` / `delete` (domain `InstanceInfoSchema`). */
+export type InstanceInfo = {
+  id: string
+  slug: string
+  url: string
+  hostId?: string
+  region?: string
+  state?: 'provisioning' | 'ready' | 'failed'
+  phase?: string
+  error?: string | null
+  createdAt?: string
+}
+
+/** Human-readable location of a managed instance ("region · hostId"). */
+export function formatInstanceLocation(info: InstanceInfo): string {
+  return [info.state && info.state !== 'ready' ? info.state : undefined, info.region, info.hostId]
+    .filter(Boolean)
+    .join(' · ')
+}

package/src/lib/admin-target.ts

@@ -0,0 +1,217 @@
+import { z } from 'zod'
+
+import type { AstraleConfig } from './config'
+import type { InstanceStore } from './instance'
+
+import { AstraleError } from '../errors'
+import { readInstances, resolveInstanceKey } from './instance'
+import { isHttpUrl } from './validation'
+
+export const DEFAULT_ADMIN_TARGET_NAME = 'admin'
+export const DEFAULT_ADMIN_TARGET_URL = 'https://admin.eu.astrale.ai/api'
+
+export const DEFAULT_ADMIN_TARGET_CONFIG = {
+  name: DEFAULT_ADMIN_TARGET_NAME,
+  url: DEFAULT_ADMIN_TARGET_URL,
+  issuer: DEFAULT_ADMIN_TARGET_URL,
+} satisfies AdminTargetConfig
+
+const HttpUrlSchema = z.string().refine(isHttpUrl, {
+  message: 'expected a valid http:// or https:// URL',
+})
+
+export const AdminTargetConfigSchema = z
+  .object({
+    /** Friendly name / auth registration slug for direct URL admin targets. */
+    name: z.string().min(1).optional(),
+    /** Direct admin kernel URL. */
+    url: HttpUrlSchema.optional(),
+    /** Kernel issuer / JWT audience when different from url. */
+    issuer: HttpUrlSchema.optional(),
+    /** Bookmark name for the admin kernel. */
+    instance: z.string().min(1).optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.url && value.instance) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['instance'],
+        message: 'admin target must use either url or instance, not both',
+      })
+    }
+    if (!value.url && !value.instance) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'admin target requires url or instance',
+      })
+    }
+    if (value.issuer && !value.url) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['issuer'],
+        message: 'admin issuer is only valid with a direct url target',
+      })
+    }
+  })
+
+export type AdminTargetConfig = z.infer<typeof AdminTargetConfigSchema>
+
+export type AdminTargetCommandOpts = {
+  admin?: string
+  adminUrl?: string
+  instance?: string
+  url?: string
+}
+
+export type AdminTargetSource = 'admin-url' | 'admin' | 'config-instance' | 'config-url' | 'default'
+
+export type ResolvedAdminTarget = {
+  name: string
+  url: string
+  issuer: string
+  defaultIdentity?: string
+  caFile?: string
+  source: AdminTargetSource
+  configured: boolean
+  registrationSlug: string
+}
+
+export const ADMIN_TARGET_OPTIONS = [
+  {
+    flags: '--admin <name>',
+    description: 'Admin kernel bookmark to use for this admin operation',
+  },
+  {
+    flags: '--admin-url <url>',
+    description: 'Admin kernel URL to use for this admin operation',
+  },
+]
+
+export async function resolveAdminTarget(
+  opts: AdminTargetCommandOpts,
+  config: AstraleConfig,
+  store?: InstanceStore,
+): Promise<ResolvedAdminTarget> {
+  return resolveAdminTargetFromStore(opts, config, store ?? (await readInstances()))
+}
+
+export function resolveAdminTargetFromStore(
+  opts: AdminTargetCommandOpts,
+  config: AstraleConfig,
+  store: InstanceStore,
+): ResolvedAdminTarget {
+  const override = readOverride(opts)
+  if (override) {
+    return override.kind === 'url'
+      ? directTarget({
+          url: override.url,
+          name: DEFAULT_ADMIN_TARGET_NAME,
+          source: override.source,
+          configured: false,
+        })
+      : bookmarkTarget(store, override.instance, override.source, false)
+  }
+
+  const admin = config.admin
+  if (admin.instance) {
+    return bookmarkTarget(store, admin.instance, 'config-instance', true)
+  }
+
+  const isDefaultDirectTarget =
+    admin.url === DEFAULT_ADMIN_TARGET_URL &&
+    admin.issuer === DEFAULT_ADMIN_TARGET_URL &&
+    admin.name === DEFAULT_ADMIN_TARGET_NAME
+
+  return directTarget({
+    url: admin.url ?? DEFAULT_ADMIN_TARGET_URL,
+    issuer: admin.issuer,
+    name: admin.name ?? DEFAULT_ADMIN_TARGET_NAME,
+    source: isDefaultDirectTarget ? 'default' : 'config-url',
+    configured: !isDefaultDirectTarget,
+  })
+}
+
+function readOverride(opts: AdminTargetCommandOpts):
+  | { kind: 'url'; url: string; source: AdminTargetSource }
+  | {
+      kind: 'instance'
+      instance: string
+      source: AdminTargetSource
+    }
+  | null {
+  const selected = [
+    opts.adminUrl ? { label: '--admin-url', kind: 'url' as const, value: opts.adminUrl } : null,
+    opts.admin ? { label: '--admin', kind: 'instance' as const, value: opts.admin } : null,
+    opts.url ? { label: '--url', kind: 'url' as const, value: opts.url } : null,
+    opts.instance
+      ? { label: '-i/--instance', kind: 'instance' as const, value: opts.instance }
+      : null,
+  ].filter((entry): entry is NonNullable<typeof entry> => entry !== null)
+
+  if (selected.length > 1) {
+    throw new AstraleError(
+      'INVALID_FLAG',
+      `Choose one admin target override, not ${selected.map((entry) => entry.label).join(', ')}`,
+      'Use --admin <bookmark> or --admin-url <url> for admin operations.',
+    )
+  }
+
+  const first = selected[0]
+  if (!first) return null
+  if (first.kind === 'url') {
+    return {
+      kind: 'url',
+      url: first.value,
+      source: 'admin-url',
+    }
+  }
+  return {
+    kind: 'instance',
+    instance: first.value,
+    source: 'admin',
+  }
+}
+
+function bookmarkTarget(
+  store: InstanceStore,
+  identifier: string,
+  source: AdminTargetSource,
+  configured: boolean,
+): ResolvedAdminTarget {
+  const key = resolveInstanceKey(store, identifier)
+  const entry = key ? store.instances[key] : undefined
+  if (!key || !entry?.url) {
+    throw new AstraleError(
+      'ADMIN_TARGET_NOT_FOUND',
+      `Admin target "${identifier}" is not bookmarked.`,
+      `Bookmark it first: astrale instance bookmark ${identifier} --url <admin-url>`,
+    )
+  }
+  return {
+    name: key,
+    registrationSlug: key,
+    url: entry.url,
+    issuer: entry.issuer ?? entry.url,
+    defaultIdentity: entry.defaultIdentity,
+    ...(entry.caFile ? { caFile: entry.caFile } : {}),
+    source,
+    configured,
+  }
+}
+
+function directTarget(input: {
+  url: string
+  issuer?: string
+  name: string
+  source: AdminTargetSource
+  configured: boolean
+}): ResolvedAdminTarget {
+  return {
+    name: input.name,
+    registrationSlug: input.name,
+    url: input.url,
+    issuer: input.issuer ?? input.url,
+    source: input.source,
+    configured: input.configured,
+  }
+}