@astrale-os/cli 1.0.0-beta.12 → 1.0.0-beta.13

package/src/admin/instance/client.ts

@@ -2,14 +2,7 @@ import type { ClientSession } from '@astrale-os/sdk/client/session'
 
 import { Path } from '@astrale-os/sdk/graph/path'
 
-import {
-  bindAdmin,
-  invokeAdminMethod,
-  requireAdminBinding,
-  requireAdminClass,
-  requireAdminCore,
-  type AdminBinding,
-} from '../binding'
+import { AdminContract, callAdminMethod } from '../contract'
 import {
   AdminInstanceNotFoundError,
   findOwnedInstance,
@@ -32,33 +25,24 @@ export interface AdminInstanceApi {
 }
 
 export interface AdminInstanceDependencies {
-  readonly bind?: (session: ClientSession) => Promise<AdminBinding>
   readonly operationId?: (kind: 'create' | 'status' | 'delete' | 'install-domain') => string
 }
 
 /**
- * Bind one discovered Admin root revision and expose only the public Instance
- * product journey. No Host lifecycle method is present on this capability.
+ * Connect the public Instance journey through stable Admin call paths. Routine
+ * operations perform no schema discovery. No Host lifecycle method is present.
  */
 export async function connectAdminInstances(
   context: AdminInstanceContext,
   dependencies: AdminInstanceDependencies = {},
 ): Promise<AdminInstanceApi> {
-  const binding = requireAdminBinding(await (dependencies.bind ?? bindAdmin)(context.session))
-
-  const Instance = requireAdminClass(binding, 'Instance', 'node')
-  const Fleet = requireAdminClass(binding, 'Fleet', 'node')
-  const fleet = requireAdminCore(binding, 'fleet')
-
   const operationId = dependencies.operationId ?? defaultOperationId
 
   const list = async (): Promise<OwnedInstanceInfo[]> => {
-    const result: unknown = await invokeAdminMethod(
+    const result: unknown = await callAdminMethod(
       context.session,
-      binding,
-      Fleet,
+      AdminContract.fleet,
       'listInstances',
-      fleet,
       {},
     )
     if (!Array.isArray(result)) throw new TypeError('Admin Instance inventory is invalid.')
@@ -76,14 +60,9 @@ export async function connectAdminInstances(
     identifier: string,
   ): Promise<InstanceInfo> => {
     const instance = await requireInstance(identifier)
-    const output = await invokeAdminMethod(
-      context.session,
-      binding,
-      Instance,
-      method,
-      Path.parse(instance.id),
-      { operationId: operationId(method) },
-    )
+    const output = await callAdminMethod(context.session, Path.parse(instance.id), method, {
+      operationId: operationId(method),
+    })
     return instanceFromSummary(output)
   }
 
@@ -95,19 +74,17 @@ export async function connectAdminInstances(
         slug,
       })
       return instanceFromSummary(
-        await invokeAdminMethod(context.session, binding, Fleet, 'createInstance', fleet, input),
+        await callAdminMethod(context.session, AdminContract.fleet, 'createInstance', input),
       )
     },
     status: (identifier: string) => invokeInstance('status', identifier),
     delete: (identifier: string) => invokeInstance('delete', identifier),
     async installDomain(identifier: string, domain: string): Promise<DomainInstallReceipt> {
       const instance = await requireInstance(identifier)
-      const output = await invokeAdminMethod(
+      const output = await callAdminMethod(
         context.session,
-        binding,
-        Instance,
-        'installDomain',
         Path.parse(instance.id),
+        'installDomain',
         {
           operationId: operationId('install-domain'),
           domain: Path.parse(domain).raw,
@@ -122,9 +99,15 @@ function instanceFromSummary(input: unknown): InstanceInfo {
   const value = record(input, 'Admin Instance summary')
   const failure = value.failure === undefined ? undefined : record(value.failure, 'Admin failure')
   return Object.freeze({
-    id: requiredString(value.id, 'Admin Instance id'),
+    id: requiredNodePath(value.id, 'Admin Instance id'),
     slug: requiredString(value.slug, 'Admin Instance slug'),
     url: optionalStringValue(value.url) ?? '',
+    ...(value.hostId === undefined
+      ? {}
+      : { hostId: requiredNodePath(value.hostId, 'Admin Host id') }),
+    ...(value.region === undefined
+      ? {}
+      : { region: requiredString(value.region, 'Admin Host region') }),
     state: instanceState(value.state),
     ...(value.phase === undefined
       ? {}
@@ -135,6 +118,9 @@ function instanceFromSummary(input: unknown): InstanceInfo {
     ...(value.createdAt === undefined
       ? {}
       : { createdAt: requiredString(value.createdAt, 'Admin Instance creation time') }),
+    ...(value.updatedAt === undefined
+      ? {}
+      : { updatedAt: requiredString(value.updatedAt, 'Admin Instance update time') }),
     ...(value.organizationId === undefined
       ? {}
       : { organizationId: requiredString(value.organizationId, 'Admin organization id') }),
@@ -146,8 +132,8 @@ function domainInstallReceipt(input: unknown): DomainInstallReceipt {
   const failure = value.failure === undefined ? undefined : record(value.failure, 'Admin failure')
   if (typeof value.ok !== 'boolean') throw new TypeError('Admin Domain install outcome is invalid.')
   return Object.freeze({
-    domain: requiredString(value.domain, 'Admin Domain reference'),
-    instance: requiredString(value.instance, 'Admin Instance reference'),
+    domain: requiredNodePath(value.domain, 'Admin Domain reference'),
+    instance: requiredNodePath(value.instance, 'Admin Instance reference'),
     origin: requiredString(value.origin, 'Installed Domain origin'),
     ok: value.ok,
     ...(value.installedRevision === undefined
@@ -179,6 +165,15 @@ function requiredString(input: unknown, label: string): string {
   return input
 }
 
+function requiredNodePath(input: unknown, label: string): string {
+  const value = requiredString(input, label)
+  try {
+    return Path.parse(value).raw
+  } catch {
+    throw new TypeError(`${label} is invalid.`)
+  }
+}
+
 function optionalStringValue(input: unknown): string | undefined {
   if (input === undefined) return undefined
   return requiredString(input, 'Admin string value')

package/src/admin/instance/model.ts

@@ -5,10 +5,13 @@ export interface InstanceInfo {
   readonly id: string
   readonly slug: string
   readonly url: string
+  readonly hostId?: string
+  readonly region?: string
   readonly state: InstanceState
   readonly phase?: string
   readonly error?: string | null
   readonly createdAt?: string
+  readonly updatedAt?: string
   readonly organizationId?: string
 }
 

package/src/commands/__tests__/call.test.ts

@@ -26,4 +26,38 @@ describe('call command result lifetime', () => {
     if (materialized.kind !== 'stream') throw new Error('expected a materialized stream')
     expect(Object.isFrozen(materialized.values)).toBe(true)
   })
+
+  test('drains streaming binary bytes before the command session closes', async () => {
+    let sessionOpen = true
+    async function* body() {
+      for (const chunk of [new Uint8Array([1, 2]), new Uint8Array([3])]) {
+        if (!sessionOpen) throw new Error('session closed before binary consumption')
+        yield chunk
+      }
+    }
+
+    const materialized = await materializeCallResult({
+      kind: 'binary',
+      invocation: { source: 'https://kernel.test' as never, id: 'test-binary' },
+      value: {
+        body: body(),
+        mediaType: 'application/octet-stream',
+        status: 206,
+        headers: { 'content-range': 'bytes 0-2/3' },
+      },
+    })
+    sessionOpen = false
+
+    expect(materialized).toMatchObject({
+      kind: 'binary',
+      value: {
+        mediaType: 'application/octet-stream',
+        status: 206,
+        headers: { 'content-range': 'bytes 0-2/3' },
+      },
+    })
+    if (materialized.kind !== 'binary') throw new Error('expected materialized binary')
+    expect([...materialized.value.body]).toEqual([1, 2, 3])
+    expect(Object.isFrozen(materialized.value)).toBe(true)
+  })
 })

package/src/commands/__tests__/read-commands.test.ts

@@ -200,6 +200,33 @@ describe('query command', () => {
     ])
   })
 
+  test('retains the opaque continuation in machine output without wrapping the graph result', async () => {
+    const { queryCommand } = await import('../query')
+    const result = {
+      kind: 'graph' as const,
+      graph: {
+        nodes: [{ id: 'issue-1', class: 'issues.astrale.ai:class.Issue', props: {} }],
+        edges: [],
+      },
+      selection: { kind: 'node' as const, ids: ['issue-1'] },
+    }
+    queryResult = {
+      result,
+      page: { next: 'opaque-next-page' },
+    }
+
+    await queryCommand([], {
+      json: true,
+      definition: '/:issues.astrale.ai:class.Issue',
+      limit: '1',
+    })
+
+    expect(JSON.parse(stdout)).toEqual({
+      ...result,
+      page: { next: 'opaque-next-page' },
+    })
+  })
+
   test('resolves @self inside the command session and never relabels transport failure as input', async () => {
     const { queryCommand } = await import('../query')
     await queryCommand(['@self'], { json: true, limit: '2' })

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

@@ -1,11 +1,13 @@
-import { describe, expect, test } from 'bun:test'
+import type { AuthApi, Identity, IssuerId, MintedCredential } from '@astrale-os/sdk/auth'
+
+import { describe, expect, mock, test } from 'bun:test'
 
 import { AstraleError } from '../../errors'
-import { parseTtl } from '../token'
+import { issueToken, parseTtl } from '../token'
 
 describe('parseTtl', () => {
-  test('defaults to 3600 seconds', () => {
-    expect(parseTtl(undefined)).toBe(3600)
+  test('defaults below the five-minute local source-credential lifetime', () => {
+    expect(parseTtl(undefined)).toBe(240)
   })
 
   test('rejects non-positive and non-integer values', () => {
@@ -19,3 +21,46 @@ describe('parseTtl', () => {
     expect(parseTtl('90')).toBe(90)
   })
 })
+
+describe('issueToken', () => {
+  const kernel = 'https://kernel.test' as IssuerId
+  const identity = {
+    id: 'caller' as Identity['id'],
+    issuer: 'https://issuer.test' as Identity['issuer'],
+    subject: 'caller' as Identity['subject'],
+    frozen: false,
+    requiredClaims: [],
+  } satisfies Identity
+
+  test('mints a reusable top-level credential for the Kernel audience', async () => {
+    const mint = mock(async () => 'kernel-token' as MintedCredential)
+    const delegate = mock(async () => 'delegated-token' as MintedCredential)
+    const whoami = mock(async () => identity)
+    const auth = { mint, delegate, whoami } satisfies Pick<AuthApi, 'delegate' | 'mint' | 'whoami'>
+
+    await expect(issueToken(auth, kernel, kernel, 90)).resolves.toBe(
+      'kernel-token' as MintedCredential,
+    )
+    expect(mint).toHaveBeenCalledWith({ ttlSeconds: 90 })
+    expect(whoami).not.toHaveBeenCalled()
+    expect(delegate).not.toHaveBeenCalled()
+  })
+
+  test('delegates the selected identity only for an external audience', async () => {
+    const mint = mock(async () => 'kernel-token' as MintedCredential)
+    const delegate = mock(async () => 'delegated-token' as MintedCredential)
+    const whoami = mock(async () => identity)
+    const auth = { mint, delegate, whoami } satisfies Pick<AuthApi, 'delegate' | 'mint' | 'whoami'>
+
+    await expect(issueToken(auth, kernel, 'https://service.test' as IssuerId, 120)).resolves.toBe(
+      'delegated-token' as MintedCredential,
+    )
+    expect(mint).not.toHaveBeenCalled()
+    expect(whoami).toHaveBeenCalledTimes(1)
+    expect(delegate).toHaveBeenCalledWith(identity.id, {
+      audience: 'https://service.test',
+      ttlSeconds: 120,
+      attenuation: { kind: 'identity', self: true },
+    })
+  })
+})

package/src/commands/call.ts

@@ -4,7 +4,7 @@ import type { ConnectionContext, KernelCommandOpts } from '../connection'
 import type { CommandDefinition } from '../program/index'
 
 import { createPathCall, expandSelfInCall, runKernelCommand, withSelfHint } from '../connection'
-import { presentBinary } from '../lib/binary'
+import { presentBinary, readBinaryBody } from '../lib/binary'
 import { failInput, log } from '../lib/log'
 import { output, present } from '../lib/output'
 
@@ -15,8 +15,20 @@ type CallOpts = KernelCommandOpts & {
 }
 
 type CallResult = Awaited<ReturnType<ConnectionContext['session']['dispatch']>>
+type BinaryCallResult = Extract<CallResult, { readonly kind: 'binary' }>
+type BinaryCallInput = Omit<BinaryCallResult, 'value'> & {
+  readonly value: Omit<BinaryCallResult['value'], 'body' | 'status'> & {
+    readonly body: Uint8Array | AsyncIterable<Uint8Array>
+    readonly status?: number
+  }
+}
+type CallResultInput = Exclude<CallResult, { readonly kind: 'binary' }> | BinaryCallInput
+type MaterializedBinaryCallResult = Omit<BinaryCallResult, 'value'> & {
+  readonly value: Omit<BinaryCallInput['value'], 'body'> & { readonly body: Uint8Array }
+}
 type MaterializedCallResult =
-  | Exclude<CallResult, { readonly kind: 'stream' }>
+  | Exclude<CallResult, { readonly kind: 'binary' | 'stream' }>
+  | MaterializedBinaryCallResult
   | { readonly kind: 'stream'; readonly values: readonly unknown[] }
 
 export async function callCommand(
@@ -68,7 +80,16 @@ export async function callCommand(
 }
 
 /** Drain a session-backed stream before the command-scoped Client Session closes. */
-export async function materializeCallResult(result: CallResult): Promise<MaterializedCallResult> {
+export async function materializeCallResult(
+  result: CallResultInput,
+): Promise<MaterializedCallResult> {
+  if (result.kind === 'binary') {
+    const body = await readBinaryBody(result.value.body)
+    return Object.freeze({
+      ...result,
+      value: Object.freeze({ ...result.value, body }),
+    })
+  }
   if (result.kind !== 'stream') return result
   const values: unknown[] = []
   for await (const value of result.stream) values.push(value)
@@ -171,6 +192,10 @@ Behavior:
   input without executing. Remote-bound functions auto-mint a
   worker-scoped credential; --creds overrides it.
 
+  Streaming binary bodies are consumed while the Client session remains live,
+  then presented through the same --output, --raw, and --json paths as buffered
+  binary. JSON retains the application HTTP status and text/base64 body.
+
 Self-reference:
   @self expands to your nodeId on the active instance (path head or
   bare param value, e.g. node=@self). --data and stdin payloads are

package/src/commands/query.ts

@@ -60,7 +60,12 @@ export async function queryCommand(sources: string[], opts: QueryOpts): Promise<
       return withSelfHint(() => context.graph.query(resolved.ast, { page: resolved.page }), meta)
     },
     format: (response, format) => {
-      output(response.result, format)
+      output(
+        response.page.next === undefined
+          ? response.result
+          : { ...response.result, page: { next: response.page.next } },
+        format,
+      )
       if (response.page.next && !isMachine(format)) {
         process.stderr.write(`  cursor: ${response.page.next}\n`)
       }
@@ -102,7 +107,8 @@ Behavior:
   one exact Edge-Class expansion; --direction defaults to outgoing. --ast and
   --file accept a complete canonical astrale.graph.query/v6 document, including
   Property ordering and Node or Edge reference/value projections. --cursor resumes
-  one caller-bound query scope.
+  one caller-bound query scope. Machine output adds page.next only when another
+  page exists; pass that opaque value back through --cursor.
 
   Legacy depth/children selector JSON and raw Cypher are not portable Kernel
   V2 query contracts and are not accepted.

package/src/commands/token.ts

@@ -1,4 +1,4 @@
-import { issuer } from '@astrale-os/sdk/auth'
+import { issuer, type AuthApi, type IssuerId, type MintedCredential } from '@astrale-os/sdk/auth'
 
 import type { KernelCommandOpts } from '../connection'
 import type { CommandDefinition } from '../program/index'
@@ -10,8 +10,8 @@ import { failInput, log } from '../lib/log'
 import { output } from '../lib/output'
 
 /**
- * `astrale token` — mint a fresh delegation token for the active instance
- * + active identity through the bound AuthApi.
+ * `astrale token` — mint a fresh audience-bound token for the active instance
+ * and selected identity through the bound AuthApi.
  */
 export type TokenOpts = KernelCommandOpts & {
   audience?: string
@@ -21,6 +21,8 @@ export type TokenOpts = KernelCommandOpts & {
   for?: string
 }
 
+const DEFAULT_TOKEN_TTL_SECONDS = 4 * 60
+
 export async function tokenCommand(opts: TokenOpts): Promise<void> {
   const commandOpts: TokenOpts = opts.for && !opts.as ? { ...opts, as: opts.for } : opts
   let ttl: number
@@ -31,18 +33,13 @@ export async function tokenCommand(opts: TokenOpts): Promise<void> {
   }
   await runKernelCommand<string>({
     opts: commandOpts,
-    label: 'Minting delegation token',
+    label: 'Minting token',
     fn: async (ctx) => {
       const audience =
         commandOpts.audience === undefined
           ? ctx.target.kernelIssuer
           : issuer.accept(commandOpts.audience)
-      const self = await ctx.auth.whoami()
-      return ctx.auth.delegate(self.id, {
-        audience,
-        ttlSeconds: ttl,
-        attenuation: { kind: 'identity', self: true },
-      })
+      return issueToken(ctx.auth, ctx.target.kernelIssuer, audience, ttl)
     },
     format: (token, fmtOpts) => {
       if (fmtOpts.json || fmtOpts.format !== undefined) {
@@ -50,15 +47,31 @@ export async function tokenCommand(opts: TokenOpts): Promise<void> {
         return
       }
       if (!fmtOpts.raw && (process.stdout.isTTY ?? false)) {
-        log.dim('  (delegation token — ES256, self-identity)')
+        log.dim('  (audience-bound token — ES256, self-identity)')
       }
       process.stdout.write(`${token}\n`)
     },
   })
 }
 
+/** Issue either a top-level Kernel credential or an external-audience delegation. */
+export async function issueToken(
+  auth: Pick<AuthApi, 'delegate' | 'mint' | 'whoami'>,
+  kernel: IssuerId,
+  audience: IssuerId,
+  ttlSeconds: number,
+): Promise<MintedCredential> {
+  if (audience === kernel) return auth.mint({ ttlSeconds })
+  const self = await auth.whoami()
+  return auth.delegate(self.id, {
+    audience,
+    ttlSeconds,
+    attenuation: { kind: 'identity', self: true },
+  })
+}
+
 export function parseTtl(raw: string | undefined): number {
-  if (raw === undefined) return 3600
+  if (raw === undefined) return DEFAULT_TOKEN_TTL_SECONDS
   if (!/^\d+$/.test(raw)) {
     throw new AstraleError(
       'INVALID_FLAG',
@@ -77,16 +90,17 @@ export function parseTtl(raw: string | undefined): number {
 
 export default {
   name: 'token',
-  description: 'Mint a fresh delegation token for the active instance + identity',
+  description: 'Mint a fresh audience-bound credential for the active instance + identity',
   afterHelpText: `
 Behavior:
-  Delegates the selected authenticated identity for 3600 seconds by default.
-  The default audience is the target Kernel issuer; choose --audience when the
-  credential is intended for another service. --for is an alias of --as.
+  Mints a token for the selected authenticated identity for 240 seconds by default.
+  The default Kernel audience produces a top-level Grant credential reusable with
+  --creds. A different --audience produces a delegated service envelope. --for is
+  an alias of --as.
 
-  The receiver must admit the exact token audience. A Kernel-audience token can
-  be reused with --creds; a service-audience token can be sent as a Bearer token
-  to that service's authenticated endpoint.
+  Every receiver must admit the exact token audience. A service-audience token can
+  be sent as a Bearer token only to that service's authenticated endpoint. The
+  requested lifetime cannot exceed the selected source credential's remaining life.
 
 Examples:
   $ export TOKEN=$(astrale token --audience shell.astrale.ai --raw)
@@ -98,7 +112,7 @@ Examples:
       flags: '--audience <aud>',
       description: 'Token audience (default: target Kernel issuer)',
     },
-    { flags: '--ttl <sec>', description: 'TTL in seconds (default: 3600)' },
+    { flags: '--ttl <sec>', description: 'TTL in seconds (default: 240)' },
     { flags: '--for <identity>', description: 'Mint the token for this identity (alias of --as)' },
   ],
   action: async (opts) => {

package/src/commands/ui/__tests__/commands.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+
+import addCommand from '../add'
+import listCommand from '../list'
+
+class ExitError extends Error {}
+
+const commit = 'a'.repeat(40)
+const item = {
+  name: 'pattern-chart-line-basic',
+  type: 'registry:block',
+  title: 'Line chart',
+  description: 'A controlled chart.',
+  dependencies: ['@astrale-os/ui@^0.3.0-beta.0'],
+  files: [
+    {
+      path: 'registry/patterns/chart/line-basic.tsx',
+      type: 'registry:component',
+      target: 'components/astrale/pattern/chart/line-basic.tsx',
+    },
+  ],
+  meta: { canonicalAddress: 'pattern/chart/line/basic' },
+}
+
+let stdout = ''
+let stderr = ''
+let originalArgv: string[]
+let originalExit: typeof process.exit
+let originalFetch: typeof globalThis.fetch
+let originalStdout: typeof process.stdout.write
+let originalStderr: typeof process.stderr.write
+
+beforeEach(() => {
+  stdout = ''
+  stderr = ''
+  originalArgv = process.argv
+  originalExit = process.exit
+  originalFetch = globalThis.fetch
+  originalStdout = process.stdout.write
+  originalStderr = process.stderr.write
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdout += String(chunk)
+    return true
+  }) as typeof process.stdout.write
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderr += String(chunk)
+    return true
+  }) as typeof process.stderr.write
+  process.exit = (() => {
+    throw new ExitError()
+  }) as typeof process.exit
+  globalThis.fetch = mockFetch()
+})
+
+afterEach(() => {
+  process.argv = originalArgv
+  process.exit = originalExit
+  globalThis.fetch = originalFetch
+  process.stdout.write = originalStdout
+  process.stderr.write = originalStderr
+})
+
+describe('UI command machine contracts', () => {
+  test('list emits exactly one parseable JSON value', async () => {
+    const action = listCommand.action as (
+      query: string | undefined,
+      options: { json?: boolean; limit?: string },
+    ) => Promise<void>
+    await action('line-basic', { json: true, limit: '100' })
+
+    expect(stderr).toBe('')
+    expect(JSON.parse(stdout)).toEqual([item])
+  })
+
+  test('add rejects missing items without prompting in machine mode', async () => {
+    process.argv = ['node', 'astrale', '--no-prompt', 'ui', 'add']
+    const add = addCommand.action as (items: string[], options: { json?: boolean }) => Promise<void>
+    await expect(add([], { json: true })).rejects.toBeInstanceOf(ExitError)
+    expect(JSON.parse(stderr)).toMatchObject({ error: 'UI_ITEM_NOT_FOUND' })
+    expect(stdout).toBe('')
+  })
+
+  test('registry failures retain a stable code without leaking transport secrets', async () => {
+    globalThis.fetch = (async () => {
+      throw new Error('Authorization: Bearer npm_super_secret_value_that_must_not_escape')
+    }) as unknown as typeof fetch
+    const action = listCommand.action as (
+      query: string | undefined,
+      options: { json?: boolean; limit?: string },
+    ) => Promise<void>
+    await expect(action('line-basic', { json: true, limit: '100' })).rejects.toBeInstanceOf(
+      ExitError,
+    )
+    expect(JSON.parse(stderr)).toEqual({
+      error: 'UI_REGISTRY_UNAVAILABLE',
+      message: 'Unable to reach npm UI release.',
+    })
+    expect(stderr).not.toContain('super_secret')
+  })
+})
+
+function mockFetch(): typeof fetch {
+  return (async (input: string | URL | Request) => {
+    const url = String(input)
+    if (url.endsWith('/@astrale-os/ui/latest')) return Response.json({ version: '0.3.0-beta.0' })
+    if (url.includes('/git/ref/tags/')) {
+      return Response.json({ object: { type: 'commit', sha: commit, url: '' } })
+    }
+    if (url.endsWith('/tooling/compatibility.json')) {
+      return Response.json({
+        version: 1,
+        shadcn: '4.18.0',
+        base: 'base',
+        style: 'nova',
+        baseUi: '1.7.0',
+        react: '^18.3.1 || ^19.0.0',
+        tailwind: '^4.3.3',
+        presets: ['astrale', 'compact', 'expressive'],
+      })
+    }
+    if (url.endsWith('/registry/patterns/chart/registry.json')) {
+      return Response.json({ items: [item] })
+    }
+    if (url.endsWith('/registry.json')) {
+      return Response.json({ include: ['registry/patterns/chart/registry.json'] })
+    }
+    return new Response('not found', { status: 404 })
+  }) as typeof fetch
+}

package/src/commands/ui/add.ts

@@ -0,0 +1,51 @@
+import type { CommandDefinition } from '../../program'
+
+import { promptMultiSelect } from '../../lib/prompt'
+import { addUi, listLockedUi, UiError } from '../../ui'
+import { UI_JSON_OPTION, UI_PROJECT_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+type Options = UiCommandOptions & { dryRun?: boolean; overwrite?: boolean; yes?: boolean }
+
+export default {
+  name: 'add',
+  description: 'Install consumer-owned Astrale pattern or block source',
+  arguments: [
+    {
+      name: 'items',
+      description: 'Canonical pattern or block addresses',
+      required: false,
+      variadic: true,
+    },
+  ],
+  options: [
+    UI_PROJECT_OPTION,
+    { flags: '--dry-run', description: 'Show exact files and dependencies without writing' },
+    { flags: '--overwrite', description: 'Allow replacing locally changed installed source' },
+    { flags: '--yes', description: 'Confirm the planned operation non-interactively' },
+    UI_JSON_OPTION,
+  ],
+  afterHelpText:
+    '\nInstalled source belongs to the application. Ordinary add never overwrites local edits.\nUse diff first, then --overwrite --yes when replacement is intentional.\n',
+  action: async (items: string[], options: Options) =>
+    runUiCommand(options, async () => {
+      let selected = items
+      if (selected.length === 0) {
+        if (process.argv.includes('--ci') || process.argv.includes('--no-prompt')) {
+          throw new UiError('UI_ITEM_NOT_FOUND', 'No UI item was provided in non-interactive mode.')
+        }
+        const available = await listLockedUi(options.project)
+        selected =
+          (await promptMultiSelect(
+            'Choose Astrale UI source to install',
+            available.map((item) => ({
+              name: item.title ?? item.meta.canonicalAddress,
+              value: item.meta.canonicalAddress,
+              description: item.description,
+            })),
+          )) ?? []
+        if (selected.length === 0)
+          throw new UiError('UI_ITEM_NOT_FOUND', 'No UI item was selected.')
+      }
+      return addUi(selected, options)
+    }),
+} satisfies CommandDefinition