@astrale-os/cli 0.4.0-alpha.13

package/src/commands/update.ts

@@ -0,0 +1,267 @@
+import type { CommandDefinition } from '../command'
+
+import pkg from '../../package.json' with { type: 'json' }
+import { fatal, log } from '../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../lib/output'
+import { confirmDefaultYes } from '../lib/prompt'
+import {
+  applySdkUpdate,
+  findSdkOutdated,
+  foreignPackageManager,
+  inDomainProject,
+  type SdkOutdated,
+} from '../lib/sdk-deps'
+import { ASTRALE_CLI_SKILL, detectSkill, installSkills, SKILL_INSTALL_HINT } from '../lib/skills'
+import { updateAstrale } from '../lib/update'
+
+type UpdateOpts = RawOutputOpts & {
+  check?: boolean
+  channel?: string
+  version?: string
+  skills?: boolean
+  deps?: boolean
+  yes?: boolean
+}
+
+/**
+ * Refresh the astrale agent skills alongside the binary. Delegates to the same
+ * `npx skills add` installer `astrale setup` uses; re-running it updates an
+ * existing install to the latest published SKILL.md.
+ *
+ * Only refreshes skills the user already has — `astrale update` keeps an existing
+ * install current, it does not foist skills on a non-agent user; fresh installs
+ * go through `astrale setup`. Best-effort: a failure here never fails the update
+ * (the binary is already swapped), so we warn and move on.
+ */
+async function refreshSkills(): Promise<void> {
+  if (!detectSkill(ASTRALE_CLI_SKILL).installed) {
+    log.dim(`  Agent skills not installed — get them with: ${SKILL_INSTALL_HINT}`)
+    return
+  }
+  log.step(`Refreshing the astrale agent skills — ${SKILL_INSTALL_HINT}`)
+  if (await installSkills()) {
+    log.success('astrale agent skills up to date')
+  } else {
+    log.warn(`Skill refresh did not complete — run it later: ${SKILL_INSTALL_HINT}`)
+  }
+}
+
+/**
+ * Keep the project's first-party `@astrale-os/*` dependencies current by
+ * delegating to pnpm (`pnpm outdated` to detect, `pnpm update --latest` to
+ * apply). Runs only inside a domain project (the `astrale.config.ts` marker) and
+ * only when pnpm owns it; elsewhere it's a silent no-op. On a dry run (`check`)
+ * it only reports. Otherwise it lists the available bumps and applies them behind
+ * a single confirm — pnpm rewrites package.json AND the lockfile (no build scripts
+ * run; the user runs `pnpm install` to materialize). Returns true when bumps were
+ * available (so `--check` can exit 10). Best-effort: pnpm missing or any error
+ * surfaces as "up to date".
+ */
+async function refreshSdkDeps(check: boolean, assumeYes = false): Promise<boolean> {
+  if (!inDomainProject()) return false
+
+  const foreign = foreignPackageManager()
+  if (foreign) {
+    if (!check) {
+      log.dim(
+        `  SDK dep check uses pnpm; this project uses ${foreign} — update it with ${foreign}.`,
+      )
+    }
+    return false
+  }
+
+  const outdated = await findSdkOutdated()
+  if (outdated.length === 0) {
+    if (!check) log.dim('  @astrale-os SDK packages are up to date')
+    return false
+  }
+
+  const plural = outdated.length === 1 ? '' : 's'
+  log.info(`@astrale-os SDK package${plural} with a newer release (${outdated.length}):`)
+  for (const o of outdated) log.dim(`  ${o.pkg}  ${o.current} → ${o.latest}`)
+
+  if (check) return true // dry run — report only
+
+  if (
+    !assumeYes &&
+    !(await confirmDefaultYes(
+      `Update ${outdated.length} @astrale-os dep${plural} (pnpm update --latest)?`,
+    ))
+  ) {
+    log.dim('  Skipped — your package.json is unchanged.')
+    return true
+  }
+  log.step('pnpm update --latest --lockfile-only "@astrale-os/*"')
+  if (await applySdkUpdate()) {
+    log.success(`Updated ${outdated.length} @astrale-os dep${plural} in package.json + lockfile`)
+    log.dim('  Run `pnpm install` to materialize the new versions.')
+  } else {
+    log.warn('  Update did not complete — run it yourself: pnpm update --latest "@astrale-os/*"')
+  }
+  return true
+}
+
+/**
+ * Read-only staleness report for tooling — `astrale update --check --json`.
+ * domain-studio polls this on load to drive its "update available" badge. It is
+ * unified and NON-THROWING: the CLI axis catches the package-managed / no-metadata
+ * case (reported as `managed`, never stale), and the SDK axis is already
+ * best-effort. Skills are intentionally absent — they ride along with `astrale
+ * update`, so a stale CLI or SDK is the only signal worth surfacing.
+ */
+export type StaleReport = {
+  stale: boolean
+  cli: { stale: boolean; managed: boolean; current?: string; latest?: string; channel?: string }
+  sdk: { stale: boolean; inProject: boolean; outdated: SdkOutdated[] }
+}
+
+async function cliStale(opts: UpdateOpts): Promise<StaleReport['cli']> {
+  try {
+    const r = await updateAstrale({
+      check: true,
+      channel: opts.channel,
+      version: opts.version,
+      currentVersion: pkg.version,
+    })
+    // `check: true` never returns 'updated'; narrow for the type checker.
+    if (r.status === 'updated') return { stale: false, managed: false, current: r.currentVersion }
+    return {
+      stale: r.status === 'available',
+      managed: false,
+      current: r.currentVersion,
+      latest: r.latestVersion,
+      channel: r.channel,
+    }
+  } catch {
+    // A package-managed install (or missing metadata) can't self-update — not stale.
+    return { stale: false, managed: true }
+  }
+}
+
+async function sdkStale(): Promise<StaleReport['sdk']> {
+  if (!inDomainProject() || foreignPackageManager()) {
+    return { stale: false, inProject: inDomainProject(), outdated: [] }
+  }
+  const outdated = await findSdkOutdated()
+  return { stale: outdated.length > 0, inProject: true, outdated }
+}
+
+export default {
+  name: 'update',
+  description: 'Check for and install Astrale CLI updates',
+  options: [
+    { flags: '--check', description: 'Only check whether an update is available' },
+    {
+      flags: '--channel <name>',
+      description: 'Update from a release channel (alpha, beta, rc, canary, stable)',
+    },
+    { flags: '--version <version>', description: 'Update to an exact version tag' },
+    { flags: '--no-skills', description: 'Skip refreshing the astrale agent skills' },
+    { flags: '--no-deps', description: 'Skip checking @astrale-os SDK dependency versions' },
+    {
+      flags: '--yes',
+      description: 'Non-interactive: apply CLI + skills + SDK deps without prompts',
+    },
+    ...RAW_OUTPUT_OPTIONS,
+  ],
+  afterHelpText: `
+Behavior:
+  Keeps three things current, in order. (1) The CLI binary: updates official
+  script installs only — if Astrale was installed by another package manager this
+  command refuses so that manager stays in charge; downloads are checksum-verified
+  before the binary is replaced. (2) The agent skills: if the astrale skills (cli +
+  domain) are already installed, refreshes them to the latest by delegating to
+  "npx skills add astrale-os/cli -g" — the same installer "astrale setup" uses;
+  fresh installs go through "astrale setup". (3) SDK deps: inside a pnpm domain
+  project, proposes any @astrale-os/* dependency with a newer release and, on
+  confirm, runs "pnpm update --latest --lockfile-only" (updates package.json AND
+  the lockfile, honoring your registry + supply-chain age policy; run "pnpm
+  install" to materialize).
+
+  --check is a dry run (binary + SDK deps; exit 10 if anything is available) and
+  never writes. With --json it emits a unified staleness report
+  ({ stale, cli, sdk }) for tooling — non-throwing, skills omitted (they ride
+  along with an update). --yes applies all three non-interactively (no prompts) and
+  is resilient — a binary that can't self-update (package-managed) warns but never
+  blocks the skills/deps steps; this is what domain-studio's "Update now" runs.
+  --no-skills / --no-deps skip those steps in a real run.
+
+Examples:
+  $ astrale update
+  $ astrale update --check
+  $ astrale update --yes
+  $ astrale update --no-skills
+  $ astrale update --no-deps
+  $ astrale update --channel canary
+  $ astrale update --version 0.4.0-alpha.10
+`,
+  action: async (opts: UpdateOpts) => {
+    try {
+      // Tooling path: a machine-readable `--check` (e.g. domain-studio's update
+      // badge polling `astrale update --check --json`) gets a unified,
+      // non-throwing staleness report — CLI + SDK only — and exits.
+      if (opts.check && isMachine(opts)) {
+        const cli = await cliStale(opts)
+        const sdk = await sdkStale()
+        const report: StaleReport = { stale: cli.stale || sdk.stale, cli, sdk }
+        output(report, opts)
+        if (report.stale) process.exitCode = 10
+        return
+      }
+
+      // Axis A — the CLI binary. Isolated so that under --yes (a non-interactive
+      // full update, e.g. domain-studio's "Update now") a binary that can't
+      // self-update — package-managed, no metadata — WARNS but does not abort the
+      // skills/deps axes. Without --yes the error surfaces as before.
+      let result: Awaited<ReturnType<typeof updateAstrale>> | null = null
+      try {
+        result = await updateAstrale({
+          check: opts.check,
+          channel: opts.channel,
+          version: opts.version,
+          currentVersion: pkg.version,
+        })
+      } catch (e) {
+        if (!opts.yes) throw e
+        log.warn(`CLI self-update skipped: ${e instanceof Error ? e.message : String(e)}`)
+      }
+
+      // Machine mode WITHOUT --yes (e.g. `astrale update --json`): emit the binary
+      // result and stop — never silently refresh skills / edit deps for a pipe.
+      if (result && isMachine(opts) && !opts.yes) {
+        output(result, opts)
+        return
+      }
+
+      // `available` only happens under --check (a real run already swapped the
+      // binary and returns `updated`).
+      let anyAvailable = false
+      if (result?.status === 'available') {
+        log.info(
+          `Astrale update available: ${result.currentVersion} -> ${result.latestVersion} (${result.channel})`,
+        )
+        anyAvailable = true
+      } else if (result?.status === 'up-to-date') {
+        log.success(`Astrale is up to date: ${result.currentVersion}`)
+      } else if (result?.status === 'updated') {
+        log.success(`Updated astrale ${result.previousVersion} -> ${result.currentVersion}`)
+        log.dim(`  channel: ${result.channel}`)
+        log.dim(`  binary: ${result.bin}`)
+      }
+
+      // Axis B — agent skills. Keep an existing install current with the CLI.
+      // Skip on --check (a dry run) and when the user opted out with --no-skills.
+      if (!opts.check && opts.skills !== false) await refreshSkills()
+
+      // Axis C — first-party @astrale-os/* deps in the current domain project.
+      // Runs on --check too (reports availability); --yes applies without a prompt.
+      if (opts.deps !== false && (await refreshSdkDeps(opts.check === true, opts.yes === true))) {
+        anyAvailable = true
+      }
+
+      if (opts.check && anyAvailable) process.exitCode = 10
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/use.ts

@@ -0,0 +1,87 @@
+import type { CommandDefinition } from '../command'
+
+import { setDefault } from '../lib/identity'
+import { readIdentities } from '../lib/identity'
+import { readInstances } from '../lib/instance'
+import { fatal, log } from '../lib/log'
+import { resolveUseTarget } from '../lib/use-target'
+import instanceUseCommand from './instance/use'
+
+type UseOpts = {
+  identity?: boolean
+  instance?: boolean
+  adoptDefault?: boolean
+  skipJwksCheck?: boolean
+}
+
+async function useIdentity(name: string): Promise<void> {
+  await setDefault(name)
+  log.success(`Active identity set to "${name}"`)
+}
+
+export default {
+  name: 'use',
+  description: 'Set the active identity or instance when the name is unambiguous',
+  afterHelpText: `
+Behavior:
+  \`astrale use <name>\` is a convenience resolver for local CLI context. It
+  switches identity when <name> is only an identity, switches instance when
+  <name> is only an instance, and refuses ambiguous names. In scripts, prefer
+  the explicit namespace commands or pass --identity / --instance.
+
+Examples:
+  $ astrale use staging
+  $ astrale use alice
+  $ astrale use staging --instance
+  $ astrale use alice --identity
+`,
+  arguments: [{ name: 'name', description: 'Identity or instance name', required: true }],
+  options: [
+    { flags: '--identity', description: 'Treat <name> as an identity' },
+    { flags: '--instance', description: 'Treat <name> as an instance' },
+    { flags: '--adopt-default', description: 'When using an instance, adopt its default identity' },
+    { flags: '--skip-jwks-check', description: 'When using an instance, skip the JWKS check' },
+  ],
+  action: async (name: string, opts: UseOpts) => {
+    try {
+      if (opts.identity && opts.instance) {
+        fatal('Choose either --identity or --instance, not both')
+      }
+
+      if (opts.identity) {
+        await useIdentity(name)
+        return
+      }
+
+      if (opts.instance) {
+        await instanceUseCommand.action(name, opts)
+        return
+      }
+
+      const [instances, identities] = await Promise.all([readInstances(), readIdentities()])
+      const target = resolveUseTarget(name, instances, identities)
+
+      if (target.kind === 'identity') {
+        await useIdentity(target.name)
+        return
+      }
+
+      if (target.kind === 'instance') {
+        await instanceUseCommand.action(target.name, opts)
+        return
+      }
+
+      if (target.kind === 'ambiguous') {
+        fatal(
+          `Both an identity and an instance are named "${name}". Use: astrale identity use ${name} or astrale instance use ${name}`,
+        )
+      }
+
+      fatal(
+        `No identity or instance named "${name}". Try: astrale identity list or astrale instance list`,
+      )
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/errors.ts

@@ -0,0 +1,65 @@
+export class AstraleError extends Error {
+  code: string
+  hint?: string
+
+  constructor(code: string, message: string, hint?: string) {
+    super(message)
+    this.name = 'AstraleError'
+    this.code = code
+    this.hint = hint
+  }
+}
+
+export class AuthError extends AstraleError {
+  constructor(message: string, hint?: string) {
+    super('AUTH_ERROR', message, hint ?? 'Run `astrale identity create <name>` to set up keys')
+  }
+}
+
+// ── Typed errors (DESIGN.md §4.6, §4.7, §5.1, §10, §11, §12) ─────────
+
+export class IssuerUnreachableError extends AstraleError {
+  constructor(url: string, hint?: string) {
+    super(
+      'ISSUER_UNREACHABLE',
+      `Issuer endpoint "${url}" not reachable`,
+      hint ?? 'Check the target URL and issuer configuration',
+    )
+  }
+}
+
+export class ReservedSlugError extends AstraleError {
+  constructor(slug: string) {
+    super('RESERVED_SLUG', `Slug "${slug}" is reserved`, 'Pick a different slug')
+  }
+}
+
+export class IdentifierCollisionError extends AstraleError {
+  constructor(identifier: string, existingEntity: string) {
+    super(
+      'IDENTIFIER_COLLISION',
+      `Identifier "${identifier}" collides with existing ${existingEntity}`,
+      'Slug and name share the same CLI namespace (§4.7). Pick a unique value.',
+    )
+  }
+}
+
+export class IdentityKeyMissingError extends AstraleError {
+  constructor(subject: string) {
+    super(
+      'IDENTITY_KEY_MISSING',
+      `No private key on disk for identity "${subject}"`,
+      `Run \`astrale identity create ${subject}\` to generate one.`,
+    )
+  }
+}
+
+export class NotImplementedError extends AstraleError {
+  constructor(feature: string, hint?: string) {
+    super(
+      'NOT_IMPLEMENTED',
+      `"${feature}" is not implemented in v1`,
+      hint ?? 'Track the design implementation progress for updates',
+    )
+  }
+}

package/src/kernel/__tests__/auth.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { AstraleConfig } from '../../lib/config'
+import type { Identity } from '../../lib/identity'
+
+import { resolveKeyIdentityAuthOptions } from '../auth'
+
+const config: AstraleConfig = {
+  issuer: 'https://unregistered.invalid',
+  admin: {
+    name: 'admin',
+    url: 'https://admin.eu.astrale.ai/api',
+    issuer: 'https://admin.eu.astrale.ai/api',
+  },
+}
+
+describe('resolveKeyIdentityAuthOptions', () => {
+  test('uses key identity issuer before global config issuer', () => {
+    const identity: Identity = {
+      subject: 'system',
+      source: 'key',
+      mode: 'local',
+      issuer: 'https://51-15-255-161.sslip.io',
+      createdAt: '2026-01-01T00:00:00.000Z',
+    }
+
+    expect(
+      resolveKeyIdentityAuthOptions(identity, config, 'https://51-15-255-161.sslip.io', 'scw-e2e'),
+    ).toEqual({
+      issuer: 'https://51-15-255-161.sslip.io',
+      subject: undefined,
+      audience: 'https://51-15-255-161.sslip.io',
+    })
+  })
+
+  test('uses target audience as issuer for imported system bootstrap identities', () => {
+    const identity: Identity = {
+      subject: 'system',
+      source: 'key',
+      mode: 'local',
+      createdAt: '2026-01-01T00:00:00.000Z',
+    }
+
+    expect(
+      resolveKeyIdentityAuthOptions(identity, config, 'https://51-15-255-161.sslip.io', 'scw-e2e'),
+    ).toEqual({
+      issuer: 'https://51-15-255-161.sslip.io',
+      subject: undefined,
+      audience: 'https://51-15-255-161.sslip.io',
+    })
+  })
+
+  test('registration issuer and subject still override identity issuer', () => {
+    const identity: Identity = {
+      subject: 'alice',
+      source: 'key',
+      mode: 'local',
+      issuer: 'https://identity.example.com',
+      createdAt: '2026-01-01T00:00:00.000Z',
+      registrations: {
+        prod: {
+          iss: 'https://prod.example.com/iss/thumbprint',
+          sub: 'node-1',
+          registeredAt: '2026-01-01T00:00:00.000Z',
+        },
+      },
+    }
+
+    expect(
+      resolveKeyIdentityAuthOptions(identity, config, 'https://prod.example.com', 'prod'),
+    ).toEqual({
+      issuer: 'https://prod.example.com/iss/thumbprint',
+      subject: 'node-1',
+      audience: 'https://prod.example.com',
+    })
+  })
+})

package/src/kernel/__tests__/errors.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from 'bun:test'
+
+// We test the stripMethodSuffix behavior indirectly through the module's exports.
+// Since stripMethodSuffix is private, we test the pattern directly.
+const stripMethodSuffix = (msg: string): string => {
+  return msg.replace(/(\/[^"\s:]+)::([a-zA-Z]\w*)/g, '$1')
+}
+
+describe('stripMethodSuffix', () => {
+  test('strips ::listChildren from path', () => {
+    expect(stripMethodSuffix('Path not found: "/nonexistent::listChildren"')).toBe(
+      'Path not found: "/nonexistent"',
+    )
+  })
+
+  test('strips ::get from path', () => {
+    expect(stripMethodSuffix('Path not found: "/some/path::get"')).toBe(
+      'Path not found: "/some/path"',
+    )
+  })
+
+  test('strips any method name', () => {
+    expect(stripMethodSuffix('"/kernel.astrale.ai/Root::describe"')).toBe(
+      '"/kernel.astrale.ai/Root"',
+    )
+  })
+
+  test('does not strip from non-path strings', () => {
+    expect(stripMethodSuffix('regular::text')).toBe('regular::text')
+  })
+
+  test('handles multiple paths in one message', () => {
+    expect(stripMethodSuffix('"/a/b::get" and "/c/d::list"')).toBe('"/a/b" and "/c/d"')
+  })
+
+  test('preserves messages without method suffixes', () => {
+    expect(stripMethodSuffix('No path found')).toBe('No path found')
+  })
+
+  test('does not strip single colon (not a method dispatch)', () => {
+    expect(stripMethodSuffix('"/a/b:notMethod"')).toBe('"/a/b:notMethod"')
+  })
+})

package/src/kernel/__tests__/remote-routing.test.ts

@@ -0,0 +1,70 @@
+import type { FnMap } from '@astrale-os/kernel-client'
+import type { ClientSession } from '@astrale-os/kernel-client/session'
+
+import { describe, expect, test } from 'bun:test'
+
+import { mintDelegationPath } from '../remote-routing'
+
+function unsignedJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown) =>
+    Buffer.from(JSON.stringify(value)).toString('base64url').replace(/=+$/, '')
+  return `${encode({ alg: 'none' })}.${encode(payload)}.signature`
+}
+
+/** A ClientSession stub that records call paths and returns a canned whoami node. */
+function stubClient(whoamiNode: unknown): {
+  client: ClientSession<FnMap>
+  calls: Array<{ path: string }>
+} {
+  const calls: Array<{ path: string }> = []
+  const client = {
+    call: async (path: string) => {
+      calls.push({ path })
+      return whoamiNode
+    },
+  } as unknown as ClientSession<FnMap>
+  return { client, calls }
+}
+
+describe('mintDelegationPath — caller self-anchor resolution', () => {
+  test('resolves an IdP identity to its NODE id via whoami (not the JWT sub)', async () => {
+    // A WorkOS subject is the upstream user id, NOT the kernel node id — `@<sub>`
+    // would 404. whoami returns the caller's own identity node; its id is the anchor.
+    const { client, calls } = stubClient({ id: 'ef280077-6039-4a1a-9d06-403718d8e112' })
+    const credential = unsignedJwt({ sub: 'user_01KC9MW1M6S5J6V9ERSRJ8RDYF' })
+
+    expect(await mintDelegationPath(client, credential)).toBe(
+      '@ef280077-6039-4a1a-9d06-403718d8e112::mintDelegationCredential',
+    )
+    expect(calls).toEqual([{ path: '/:kernel.astrale.ai:interface.Identity:whoami' }])
+  })
+
+  test('legacy system subject maps to the __system__ graph node WITHOUT a whoami call', async () => {
+    const { client, calls } = stubClient({ id: 'unused' })
+    expect(await mintDelegationPath(client, unsignedJwt({ sub: 'system' }))).toBe(
+      '@__system__::mintDelegationCredential',
+    )
+    expect(calls).toEqual([])
+  })
+
+  test('opaque non-JWT credential falls back to __system__ (no whoami)', async () => {
+    const { client, calls } = stubClient({ id: 'unused' })
+    expect(await mintDelegationPath(client, 'not-a-jwt')).toBe(
+      '@__system__::mintDelegationCredential',
+    )
+    expect(calls).toEqual([])
+  })
+
+  test('throws when whoami returns no id (cannot address the caller)', async () => {
+    const { client } = stubClient({ notAnId: true })
+    await expect(mintDelegationPath(client, unsignedJwt({ sub: 'abc' }))).rejects.toThrow(
+      /could not resolve the caller identity/i,
+    )
+  })
+})
+
+// `lookupRemoteBinding` (the proactive `<path>::get` resolver) was removed: the
+// kernel now carries the worker's `iss` on the redirect and the ClientSession
+// follows it reactively, minting via `mintRemoteCredential` (the cache mint
+// wired in `kernel/client.ts`). The slug→iss audience derivation it tested now
+// lives in the kernel resolver (`runtime/__tests__/resolver-remote.test.ts`).