@astrale-os/cli 0.8.1-alpha.0 → 0.8.1-alpha.2

package/src/kernel/expand.ts

@@ -1,192 +0,0 @@
-import type { KernelCommandOpts } from './types'
-
-/** CLI bridge for @self resolution and stale-registration error hints. */
-import { readConfig } from '../lib/config'
-import { getDefault, getIdentity, setRegistration } from '../lib/identity'
-import { decodeTokenClaims, readIdpSession } from '../lib/idp'
-import { resolveInstanceTarget } from '../lib/instance-target'
-import { fileExists, keypairPaths } from '../lib/keys'
-import { KEYS_DIR } from '../lib/paths'
-import {
-  containsSelfRef,
-  expandSelfReferences,
-  resolveSelfNodeId,
-  selfRefusalError,
-  type SelfResolverContext,
-  type SelfResolution,
-} from '../lib/self'
-import { lookupImplicitOwnedInstance, withKernelClient } from './client'
-
-/** Metadata attached to errors so the NotFoundError path can hint at stale `@self` expansions. */
-export type SelfExpansionMeta = {
-  original: string
-  expanded: string
-  selfId: string
-  identity?: string
-  slug?: string
-}
-
-/** Build the same target/signing context `withKernelClient` will use. */
-export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfResolverContext> {
-  const config = await readConfig()
-  // Mirror withKernelClient's slug logic: --url without -i ⇒ no slug.
-  let slug: string | undefined
-  let defaultIdentity: string | undefined
-  if (opts.url && !opts.instance) {
-    slug = undefined
-  } else {
-    const resolved = await resolveInstanceTarget(
-      opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
-      {
-        config,
-        admin: {},
-        managed: (instanceSlug) => lookupImplicitOwnedInstance(instanceSlug, opts),
-      },
-    )
-    slug = resolved.name
-    defaultIdentity = resolved.defaultIdentity
-  }
-
-  // Mirror resolveCredential's instance-signed branch: when targeting a
-  // child for which the CLI generated a dedicated keypair, the call signs
-  // as the instance itself, not as a user identity.
-  let instanceSigned = false
-  if (!opts.creds && !opts.as && !defaultIdentity && slug && slug !== 'manager') {
-    const { privatePath } = keypairPaths(slug, KEYS_DIR)
-    instanceSigned = await fileExists(privatePath)
-  }
-
-  // Identity lookup failures should surface as real CLI errors, not @self refusals.
-  let identity: SelfResolverContext['identity']
-  if (!opts.creds) {
-    const identityName = opts.as ?? defaultIdentity
-    if (identityName) {
-      const i = await getIdentity(identityName)
-      identity = { ...i, name: identityName }
-    } else {
-      identity = await getDefault()
-    }
-  }
-
-  let idpSubject: string | undefined
-  if (identity && (identity.source ?? 'key') === 'idp') {
-    instanceSigned = false
-    const session = await readIdpSession(identity.name)
-    const claims = decodeTokenClaims(session?.id_token ?? session?.access_token)
-    if (typeof claims?.sub === 'string' && claims.sub.trim().length > 0) {
-      idpSubject = claims.sub
-    }
-  }
-
-  return { identity, instanceSlug: slug, credsJwt: opts.creds, instanceSigned, idpSubject }
-}
-
-/**
- * Run `fn`; if it throws a `NotFoundError`, stamp expansion metadata onto the
- * error so `formatKernelError` can append the stale-registration hint. The
- * error is re-thrown either way.
- */
-export async function withSelfHint<T>(
-  fn: () => Promise<T>,
-  meta: SelfExpansionMeta | undefined,
-): Promise<T> {
-  if (!meta) return fn()
-  try {
-    return await fn()
-  } catch (err) {
-    if (err instanceof Error && err.name === 'NotFoundError') {
-      ;(err as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf = meta
-    }
-    throw err
-  }
-}
-
-/** Convenience: resolve the nodeId once, or throw the typed refusal. */
-export function resolveOrThrow(selfCtx: SelfResolverContext): string {
-  const r: SelfResolution = resolveSelfNodeId(selfCtx)
-  if ('reason' in r) throw selfRefusalError(r)
-  return r.id
-}
-
-export type ResolveSelfIdLazyDeps = {
-  whoami?: (opts: KernelCommandOpts) => Promise<{ id?: unknown; kernelUrl: string }>
-  setRegistration?: typeof setRegistration
-  now?: () => Date
-}
-
-/**
- * Resolve @self for IdP identities through one whoami refresh, then cache the
- * current node id. Non-IdP refusals stay typed and local.
- */
-export async function resolveSelfIdLazy(
-  selfCtx: SelfResolverContext,
-  opts: KernelCommandOpts,
-  deps: ResolveSelfIdLazyDeps = {},
-): Promise<string> {
-  const r: SelfResolution = resolveSelfNodeId(selfCtx)
-  const cachedId = 'reason' in r ? undefined : r.id
-  const isIdp = (selfCtx.identity?.source ?? 'key') === 'idp'
-
-  if (isIdp && selfCtx.instanceSlug && selfCtx.identity) {
-    let lookup: { id?: unknown; kernelUrl: string }
-    try {
-      lookup = await (deps.whoami ?? whoamiSelfId)(opts)
-    } catch {
-      if (cachedId) return cachedId
-      if ('reason' in r) throw selfRefusalError(r)
-      throw selfRefusalError({ reason: 'idp-no-sub', identityName: selfCtx.identity.name })
-    }
-
-    const resolvedId =
-      typeof lookup.id === 'string' && lookup.id.trim().length > 0 ? lookup.id : undefined
-    if (!resolvedId) {
-      if (cachedId) return cachedId
-      if ('reason' in r) throw selfRefusalError(r)
-      throw selfRefusalError({ reason: 'idp-no-sub', identityName: selfCtx.identity.name })
-    }
-
-    const cached = selfCtx.identity.registrations?.[selfCtx.instanceSlug]
-    if (cached?.sub !== resolvedId || cached?.iss !== lookup.kernelUrl) {
-      await (deps.setRegistration ?? setRegistration)(selfCtx.identity.name, selfCtx.instanceSlug, {
-        iss: lookup.kernelUrl,
-        sub: resolvedId,
-        registeredAt: (deps.now ?? (() => new Date()))().toISOString(),
-      })
-    }
-    return resolvedId
-  }
-
-  if (!('reason' in r)) return r.id
-  throw selfRefusalError(r)
-}
-
-async function whoamiSelfId(opts: KernelCommandOpts): Promise<{ id?: unknown; kernelUrl: string }> {
-  let kernelUrl = ''
-  const me = await withKernelClient(opts, (ctx) => {
-    kernelUrl = ctx.url
-    return ctx.client.as(ctx.credential).auth.whoami()
-  })
-  return { id: me.id, kernelUrl }
-}
-
-/** Expand @self in path-like commands and return metadata for NotFound hints. */
-export async function expandSelfInPath(
-  path: string,
-  opts: KernelCommandOpts,
-): Promise<{ path: string; meta: SelfExpansionMeta | undefined }> {
-  if (!containsSelfRef(path)) return { path, meta: undefined }
-  const selfCtx = await buildSelfContext(opts)
-  const id = await resolveSelfIdLazy(selfCtx, opts)
-  const expanded = expandSelfReferences(path, id)
-  if (expanded === path) return { path, meta: undefined }
-  return {
-    path: expanded,
-    meta: {
-      original: path,
-      expanded,
-      selfId: id,
-      identity: selfCtx.identity?.name,
-      slug: selfCtx.instanceSlug,
-    },
-  }
-}

package/src/kernel/graph.ts

@@ -1,96 +0,0 @@
-import type {
-  GetResultWire,
-  GraphApi,
-  GraphNodeWire,
-  MutationResultWire,
-  PatchInput,
-  QueryASTInput,
-} from '@astrale-os/kernel-client/graph'
-
-import { createGraph, rawOf } from '@astrale-os/kernel-client/graph'
-
-import type { ClientContext } from './client'
-
-export type {
-  GetResultWire,
-  GraphApi,
-  GraphNodeWire,
-  MutationResultWire,
-  PatchInput,
-  QueryASTInput,
-}
-
-/** A node row as it crosses the graph doors — the shared item shape for `get`/`ls`/`describe`. */
-export type GraphNode = GraphNodeWire
-
-/**
- * Bind the graph sugar (`function.get` / `function.mutate` + the read/write
- * helpers) over a CLI client session. The sugar is pure over a call capability;
- * we hand it `ClientSession.call` — the same surface every command already uses.
- */
-export function bindGraph(ctx: ClientContext): GraphApi {
-  return createGraph((method, params) => ctx.client.call(method, params))
-}
-
-/**
- * Split a `function.get` page into addressed root and descendants. Root matches
- * path/id first, then falls back to the shallowest node in the page.
- */
-export function splitRoot(
-  nodes: readonly GraphNode[],
-  rootPath: string,
-): { root: GraphNode | undefined; children: GraphNode[] } {
-  const raw = rawOf(rootPath)
-  const idForm = rootPath.startsWith('@') ? rootPath.slice(1) : undefined
-
-  let idx = nodes.findIndex(
-    (n) => rawOf(n.path) === raw || (idForm !== undefined && n.id === idForm),
-  )
-  if (idx < 0 && nodes.length > 0) {
-    let min = Number.POSITIVE_INFINITY
-    nodes.forEach((n, i) => {
-      const depth = rawOf(n.path).split('/').length
-      if (depth < min) {
-        min = depth
-        idx = i
-      }
-    })
-  }
-
-  const root = idx >= 0 ? nodes[idx] : undefined
-  const children = idx >= 0 ? nodes.filter((_, i) => i !== idx) : [...nodes]
-  return { root, children }
-}
-
-/** The children cursor of a single-root `function.get` result, if the page overflowed. */
-export function childrenCursor(result: GetResultWire): string | undefined {
-  const next = result.next
-  if (!next) return undefined
-  return Object.values(next)[0]?.children
-}
-
-/**
- * Strip a fully-qualified prop key to its leaf name. Node props travel under
- * qualified keys (`<domain>:class.X.property.name` / `<domain>:interface.I.property.name`);
- * this recovers `name`.
- */
-export function unqualifyKey(key: string): string {
-  const dot = key.lastIndexOf('.property.')
-  if (dot >= 0) return key.slice(dot + '.property.'.length)
-  const slash = key.lastIndexOf('/')
-  return slash >= 0 ? key.slice(slash + 1) : key
-}
-
-/** Read a node prop by its unqualified leaf name (exact key wins, else a qualified match). */
-export function nodeProp(
-  node: { props: Record<string, unknown> } | null | undefined,
-  name: string,
-): unknown {
-  const props = node?.props
-  if (!props) return undefined
-  if (name in props) return props[name]
-  for (const [k, v] of Object.entries(props)) {
-    if (unqualifyKey(k) === name) return v
-  }
-  return undefined
-}

package/src/kernel/index.ts

@@ -1,29 +0,0 @@
-export {
-  withKernelClient,
-  withAdminKernelClient,
-  resolveKernelTarget,
-  type ClientContext,
-  type ResolvedKernelTarget,
-} from './client'
-export { resolveCredential } from './auth'
-export { formatKernelError } from './errors'
-export {
-  buildSelfContext,
-  expandSelfInPath,
-  withSelfHint,
-  resolveOrThrow,
-  resolveSelfIdLazy,
-  type SelfExpansionMeta,
-} from './expand'
-export { runKernelCommand } from './run'
-export { bindGraph, splitRoot, childrenCursor, nodeProp, unqualifyKey } from './graph'
-export type {
-  GetResultWire,
-  GraphApi,
-  GraphNode,
-  GraphNodeWire,
-  MutationResultWire,
-  PatchInput,
-  QueryASTInput,
-} from './graph'
-export type { KernelCommandOpts, CallCommandOpts } from './types'

package/src/kernel/options.ts

@@ -1,22 +0,0 @@
-import type { CommandOption } from '../command'
-
-/**
- * Flags consumed by `withKernelClient` (and therefore valid on any command
- * that talks to a kernel). Spread these into a command's `options` to expose
- * the same `--url / --instance / --timeout / --as / --creds / --debug`
- * surface as `astrale call`.
- */
-export const KERNEL_PASSTHROUGH_OPTIONS: CommandOption[] = [
-  {
-    flags: '--url <url>',
-    description: 'Target a kernel URL directly (overrides instance resolution)',
-  },
-  {
-    flags: '-i, --instance <name>',
-    description: 'Target a specific instance (overrides active)',
-  },
-  { flags: '--timeout <ms>', description: 'Request timeout in ms (default: 30000)' },
-  { flags: '--as <identity>', description: 'Call as a specific identity' },
-  { flags: '--creds <token>', description: 'Use a pre-signed credential (e.g. delegation token)' },
-  { flags: '--debug', description: 'Print full error diagnostics on failure' },
-]

package/src/kernel/types.ts

@@ -1,14 +0,0 @@
-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__/domain-identity.test.ts

@@ -1,60 +0,0 @@
-/**
- * `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__/fs-atomic.test.ts

@@ -1,104 +0,0 @@
-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')
-  })
-})

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

@@ -1,79 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-
-import { IdentityStoreSchema } from '../identity'
-
-describe('IdentityStoreSchema', () => {
-  test('parses valid store', () => {
-    const result = IdentityStoreSchema.parse({
-      default: 'manager',
-      identities: {
-        manager: { subject: 'manager', createdAt: '2024-01-01T00:00:00Z' },
-      },
-    })
-    expect(result.default).toBe('manager')
-    expect(result.identities.manager.subject).toBe('manager')
-  })
-
-  test('parses multiple identities', () => {
-    const result = IdentityStoreSchema.parse({
-      default: 'admin',
-      identities: {
-        admin: {
-          subject: 'admin',
-          createdAt: '2024-01-01T00:00:00Z',
-          issuer: 'https://admin.example.com',
-        },
-        user: { subject: 'user-principal', createdAt: '2024-06-15T12:00:00Z' },
-      },
-    })
-    expect(Object.keys(result.identities)).toHaveLength(2)
-    expect(result.identities.admin.issuer).toBe('https://admin.example.com')
-    expect(result.identities.user.subject).toBe('user-principal')
-  })
-
-  test('parses IdP-backed identities without key metadata', () => {
-    const result = IdentityStoreSchema.parse({
-      default: 'alice',
-      identities: {
-        alice: {
-          source: 'idp',
-          subject: 'user_123',
-          idp: 'workos',
-          issuer: 'https://example.authkit.app',
-          audience: 'https://api.example.com',
-          createdAt: '2024-01-01T00:00:00Z',
-          claims: { email: 'alice@example.com' },
-        },
-      },
-    })
-
-    expect(result.identities.alice.source).toBe('idp')
-    expect(result.identities.alice.kid).toBeUndefined()
-    expect(result.identities.alice.idp).toBe('workos')
-  })
-
-  test('rejects missing default field', () => {
-    expect(() =>
-      IdentityStoreSchema.parse({
-        identities: { manager: { subject: 'manager', createdAt: '2024-01-01' } },
-      }),
-    ).toThrow()
-  })
-
-  test('rejects identity missing subject', () => {
-    expect(() =>
-      IdentityStoreSchema.parse({
-        default: 'manager',
-        identities: { manager: { createdAt: '2024-01-01' } },
-      }),
-    ).toThrow()
-  })
-
-  test('accepts empty identities record', () => {
-    const result = IdentityStoreSchema.parse({
-      default: 'nobody',
-      identities: {},
-    })
-    expect(Object.keys(result.identities)).toHaveLength(0)
-  })
-})