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

package/src/commands/ui/doctor.ts

@@ -0,0 +1,13 @@
+import type { CommandDefinition } from '../../program'
+
+import { doctorUi } from '../../ui'
+import { UI_JSON_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+export default {
+  name: 'doctor',
+  description: 'Verify Astrale UI package, CSS, config, lock, and installed source integrity',
+  arguments: [{ name: 'path', description: 'Application directory', required: false }],
+  options: [UI_JSON_OPTION],
+  action: async (path: string | undefined, options: UiCommandOptions) =>
+    runUiCommand(options, () => doctorUi(path)),
+} satisfies CommandDefinition

package/src/commands/ui/init.ts

@@ -0,0 +1,38 @@
+import type { CommandDefinition } from '../../program'
+
+import { initUi, type UiPreset } from '../../ui'
+import { UI_JSON_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+type Options = UiCommandOptions & {
+  preset?: UiPreset
+  version?: string
+  dryRun?: boolean
+  force?: boolean
+  install?: boolean
+}
+
+export default {
+  name: 'init',
+  description: 'Initialize Astrale UI in an existing React and Tailwind v4 application',
+  arguments: [{ name: 'path', description: 'Application directory', required: false }],
+  options: [
+    {
+      flags: '--preset <name>',
+      description: 'Visual preset',
+      choices: ['astrale', 'compact', 'expressive'],
+      default: 'astrale',
+    },
+    { flags: '--version <version>', description: 'Exact @astrale-os/ui version or release tag' },
+    { flags: '--dry-run', description: 'Print the complete plan without writing or installing' },
+    { flags: '--force', description: 'Replace an existing Astrale UI lock intentionally' },
+    {
+      flags: '--no-install',
+      description: 'Write configuration without running the package manager',
+    },
+    UI_JSON_OPTION,
+  ],
+  afterHelpText:
+    '\nExamples:\n  $ astrale ui init --preset astrale\n  $ astrale ui init ./app --dry-run --json\n',
+  action: async (path: string | undefined, options: Options) =>
+    runUiCommand(options, () => initUi({ path, ...options })),
+} satisfies CommandDefinition

package/src/commands/ui/list.ts

@@ -0,0 +1,26 @@
+import type { CommandDefinition } from '../../program'
+
+import { listUi } from '../../ui'
+import { UI_JSON_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+type Options = UiCommandOptions & { type?: string; limit?: string; version?: string }
+
+export default {
+  name: 'list',
+  description: 'List or search Astrale patterns and blocks',
+  arguments: [{ name: 'query', description: 'Optional search text', required: false }],
+  options: [
+    {
+      flags: '--type <type>',
+      description: 'Restrict to pattern or block',
+      choices: ['pattern', 'block'],
+    },
+    { flags: '--limit <n>', description: 'Maximum results', default: '100' },
+    { flags: '--version <version>', description: 'Exact release to inspect' },
+    UI_JSON_OPTION,
+  ],
+  action: async (query: string | undefined, options: Options) =>
+    runUiCommand(options, () =>
+      listUi(query, { type: options.type, limit: Number(options.limit), version: options.version }),
+    ),
+} satisfies CommandDefinition

package/src/commands/ui/preset-apply.ts

@@ -0,0 +1,19 @@
+import type { CommandDefinition } from '../../program'
+
+import { applyPreset, type UiPreset } from '../../ui'
+import { UI_JSON_OPTION, UI_PROJECT_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+type Options = UiCommandOptions & { dryRun?: boolean }
+
+export default {
+  name: 'apply',
+  description: 'Change the preset CSS import without rewriting component source',
+  arguments: [{ name: 'name', description: 'Preset name' }],
+  options: [
+    UI_PROJECT_OPTION,
+    { flags: '--dry-run', description: 'Show the CSS and lock change without writing' },
+    UI_JSON_OPTION,
+  ],
+  action: async (name: UiPreset, options: Options) =>
+    runUiCommand(options, () => applyPreset(name, options)),
+} satisfies CommandDefinition

package/src/commands/ui/preset-list.ts

@@ -0,0 +1,12 @@
+import type { CommandDefinition } from '../../program'
+
+import { UI_PRESETS } from '../../ui'
+import { UI_JSON_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+export default {
+  name: 'list',
+  description: 'List qualified Astrale UI visual presets',
+  options: [UI_JSON_OPTION],
+  action: async (options: UiCommandOptions) =>
+    runUiCommand(options, async () => UI_PRESETS.map((name) => ({ name }))),
+} satisfies CommandDefinition

package/src/commands/ui/shared.ts

@@ -0,0 +1,25 @@
+import { fatal } from '../../lib/log'
+import { output } from '../../lib/output'
+
+export type UiCommandOptions = { json?: boolean; project?: string }
+
+export async function runUiCommand(
+  options: UiCommandOptions,
+  operation: () => Promise<unknown>,
+): Promise<void> {
+  try {
+    output(await operation(), { json: options.json })
+  } catch (error) {
+    fatal(error, { json: options.json })
+  }
+}
+
+export const UI_PROJECT_OPTION = {
+  flags: '--project <path>',
+  description: 'Existing application root (defaults to the current project)',
+} as const
+
+export const UI_JSON_OPTION = {
+  flags: '--json',
+  description: 'Emit one machine-readable JSON value',
+} as const

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

@@ -39,11 +39,26 @@ describe('presentBinary', () => {
 
   test('--json inlines text for text-like content types', async () => {
     await presentBinary(
-      { mediaType: 'text/plain', body: new TextEncoder().encode('hi') },
+      { mediaType: 'text/plain', status: 202, body: new TextEncoder().encode('hi') },
       { json: true },
     )
     const obj = JSON.parse(Buffer.concat(chunks).toString())
     expect(obj.body).toBe('hi')
+    expect(obj.status).toBe(202)
+  })
+
+  test('--raw drains streaming binary chunks in exact order', async () => {
+    await presentBinary(
+      {
+        mediaType: 'application/octet-stream',
+        body: (async function* () {
+          yield new Uint8Array([1, 2])
+          yield new Uint8Array([3, 4])
+        })(),
+      },
+      { raw: true },
+    )
+    expect(Array.from(Buffer.concat(chunks))).toEqual([1, 2, 3, 4])
   })
 
   test('-o writes raw bytes to a file', async () => {

package/src/lib/binary.ts

@@ -7,14 +7,31 @@ import { output } from './output'
 
 /** A binary kernel result: bytes (or a stream of them) plus its content-type. */
 export type BinaryLike = {
-  readonly body: Uint8Array
+  readonly body: Uint8Array | AsyncIterable<Uint8Array>
   readonly mediaType: string
+  readonly status?: number
   readonly headers?: Readonly<Record<string, string>>
 }
 
 /** Collapse a (possibly streamed) binary body into a single byte array. */
-export async function readBinaryBody(body: Uint8Array): Promise<Uint8Array> {
-  return body
+export async function readBinaryBody(
+  body: Uint8Array | AsyncIterable<Uint8Array>,
+): Promise<Uint8Array> {
+  if (body instanceof Uint8Array) return new Uint8Array(body)
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for await (const chunk of body) {
+    const detached = new Uint8Array(chunk)
+    chunks.push(detached)
+    size += detached.byteLength
+  }
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
 }
 
 function isTextLike(contentType: string): boolean {
@@ -43,13 +60,13 @@ function humanSize(bytes: number): string {
 function jsonEnvelope(resp: BinaryLike, bytes: Uint8Array): Record<string, unknown> {
   if (isTextLike(resp.mediaType)) {
     return {
-      status: 200,
+      status: resp.status ?? 200,
       contentType: resp.mediaType,
       body: new TextDecoder().decode(bytes),
     }
   }
   return {
-    status: 200,
+    status: resp.status ?? 200,
     contentType: resp.mediaType,
     bodyBase64: Buffer.from(bytes).toString('base64'),
   }

package/src/lib/proc.ts

@@ -22,7 +22,11 @@ export function run(
   opts: { cwd?: string } = {},
 ): Promise<RunResult> {
   return new Promise((resolve, reject) => {
-    const child = spawn(file, args, { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    const child = spawn(file, args, {
+      cwd: opts.cwd,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
     let stdout = ''
     let stderr = ''
     child.stdout?.setEncoding('utf8')
@@ -50,7 +54,7 @@ export function runInherit(
   opts: { cwd?: string } = {},
 ): Promise<number> {
   return new Promise((resolve, reject) => {
-    const child = spawn(file, args, { cwd: opts.cwd, stdio: 'inherit' })
+    const child = spawn(file, args, { cwd: opts.cwd, shell: false, stdio: 'inherit' })
     child.on('error', reject)
     child.on('close', (code) => resolve(code ?? -1))
   })
@@ -73,6 +77,7 @@ export function spawnHandle(
   return spawn(file, args, {
     cwd: opts.cwd,
     env: opts.env,
+    shell: false,
     // `detached` makes the child its own process-group leader so the caller can
     // tear down the whole tree (the child AND its grandchildren) with a single
     // group signal — `process.kill(-child.pid, …)`.

package/src/program/.spec/api.d.ts

@@ -5,6 +5,7 @@ export interface CommandArgument {
   readonly name: string
   readonly description: string
   readonly required?: boolean
+  readonly variadic?: boolean
 }
 
 /** One Commander-compatible option in a CLI command definition. */

package/src/program/__tests__/program.test.ts

@@ -181,13 +181,21 @@ describe('program composition', () => {
       'status',
       'studio',
       'token',
+      'ui',
+      'ui add',
+      'ui doctor',
+      'ui init',
+      'ui list',
+      'ui preset',
+      'ui preset apply',
+      'ui preset list',
       'update',
       'use',
       'view',
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '56d2049ff4f7ddd24abdd9df39d4a827757f1b39a92dc7fb55933105d722f97f',
+      '873d096c4e99f29ab1db17bec0abc4ad2de613f5e44f9cba97c95b052c8b5a98',
     )
   })
 
@@ -281,7 +289,7 @@ describe('help contract — admin target surface is registered', () => {
 describe('help contract — connect-only command surface', () => {
   test('runtime management commands are not registered', async () => {
     const program = await buildProgram()
-    const names = allCommands(program).map((command) => command.name())
+    const names = program.commands.map((command) => command.name())
 
     // `logs` and `domain` have managed/admin meanings, so only retired verbs are absent.
     for (const removed of [
@@ -303,6 +311,28 @@ describe('help contract — connect-only command surface', () => {
   })
 })
 
+describe('help contract — UI is project tooling', () => {
+  test('UI commands are local-only and add accepts zero or more canonical addresses', async () => {
+    const program = await buildProgram()
+    const ui = program.commands.find((command) => command.name() === 'ui')
+    const add = ui?.commands.find((command) => command.name() === 'add')
+
+    expect(ui?.commands.map((command) => command.name())).toEqual([
+      'init',
+      'list',
+      'add',
+      'doctor',
+      'preset',
+    ])
+    expect(add?.helpInformation()).toContain('[items...]')
+    for (const command of ui?.commands ?? []) {
+      const help = command.helpInformation()
+      expect(help).not.toContain('--url <url>')
+      expect(help).not.toContain('--anonymous')
+    }
+  })
+})
+
 describe('help contract — read command split', () => {
   test('get is point-read only and query owns structured read flags', async () => {
     const program = await buildProgram()

package/src/program/build.ts

@@ -63,6 +63,27 @@ export async function buildProgram(): Promise<Command> {
   registerCommand(program, (await import('../commands/view-serve')).default)
   registerCommand(program, (await import('../commands/studio')).default)
 
+  registerGroup(program, {
+    name: 'ui',
+    description: 'Initialize and install Astrale UI in local applications',
+    commands: [
+      (await import('../commands/ui/init')).default,
+      (await import('../commands/ui/list')).default,
+      (await import('../commands/ui/add')).default,
+      (await import('../commands/ui/doctor')).default,
+    ],
+    subgroups: [
+      {
+        name: 'preset',
+        description: 'List and apply qualified Astrale UI presets',
+        commands: [
+          (await import('../commands/ui/preset-list')).default,
+          (await import('../commands/ui/preset-apply')).default,
+        ],
+      },
+    ],
+  })
+
   registerGroup(program, {
     name: 'instance',
     description: 'Manage admin-provisioned instances and local bookmarks',
@@ -154,6 +175,7 @@ Command groups:
   Getting started  setup     (sign in, pick an instance, equip your workspace)
   Kernel        get, mutate, call, query, introspect, logs, view, token
   Management    admin, instance, domain, identity, auth, idp, update
+  Application   ui        (initialize, inspect, and install Astrale UI source)
   Agent         browser   (drive the GUI via agent-browser)
   Studio        studio    (launch the local Domain Studio GUI for a workspace)
 
@@ -172,7 +194,7 @@ Examples:
   $ astrale instance bookmark staging --url https://kernel.example.com
   $ astrale instance create my-app
   $ astrale instance status staging
-  $ astrale token --audience shell.astrale.ai --ttl 3600
+  $ astrale token --audience shell.astrale.ai
   $ astrale query /:notes.example.dev:class.Note --limit 50
   $ astrale introspect /:kernel.astrale.ai:class.Identity:whois
   $ astrale query --file query.v6.json --cursor "$CURSOR"

package/src/program/command.ts

@@ -2,6 +2,7 @@ export interface CommandArgument {
   readonly name: string
   readonly description: string
   readonly required?: boolean
+  readonly variadic?: boolean
 }
 
 export interface CommandOption {

package/src/program/registry.ts

@@ -18,7 +18,8 @@ export function registerCommand(parent: Command, def: CommandDefinition): void {
 
   if (def.arguments) {
     for (const arg of def.arguments) {
-      const bracket = arg.required !== false ? `<${arg.name}>` : `[${arg.name}]`
+      const name = arg.variadic ? `${arg.name}...` : arg.name
+      const bracket = arg.required !== false ? `<${name}>` : `[${name}]`
       cmd.argument(bracket, arg.description)
     }
   }

package/src/ui/.spec/api.d.ts

@@ -0,0 +1,14 @@
+export {
+  addUi,
+  applyPreset,
+  diffUi,
+  doctorUi,
+  initUi,
+  listUi,
+  viewUi,
+  type InitUiOptions,
+} from '../operations.js'
+export { UI_PRESETS, UiError, type UiLock, type UiPreset } from '../model.js'
+export { discoverUiProject, type UiProject } from '../project.js'
+export { resolveUiRelease } from '../release.js'
+export { shadcnInvocation, type UiRunner } from '../runner.js'

package/src/ui/.spec/architecture.md

@@ -0,0 +1,10 @@
+# UI local tooling
+
+This private CLI owner manages an existing local React project. It does not connect to a Kernel and
+does not add React, Base UI, Tailwind, shadcn, or the UI runtime to the installed CLI dependency
+graph.
+
+One operation resolves one immutable UI commit. Package compatibility and registry reads use that
+commit, and the detected package manager invokes the release-qualified shadcn CLI on demand.
+Application writes complete before the lock advances. Dry-run, list, view, diff, and doctor do not
+claim a file mutation.

package/src/ui/.spec/laws.ts

@@ -0,0 +1,36 @@
+import { defineLaw } from '@astrale-os/spec/authoring'
+
+export const CLI_UI_ONE_SNAPSHOT = defineLaw({
+  id: 'CLI-UI-ONE-SNAPSHOT',
+  statement:
+    'Each UI operation resolves one immutable repository commit and reads compatibility, registry, and item source only from that snapshot.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-ONE-SNAPSHOT' }],
+})
+
+export const CLI_UI_LOCK_AFTER_SUCCESS = defineLaw({
+  id: 'CLI-UI-LOCK-AFTER-SUCCESS',
+  statement:
+    'Dry runs and failed package or source operations do not advance astrale-ui.lock.json.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-LOCK-AFTER-SUCCESS' }],
+})
+
+export const CLI_UI_BOUNDED_REMOTE_DOCUMENTS = defineLaw({
+  id: 'CLI-UI-BOUNDED-REMOTE-DOCUMENTS',
+  statement:
+    'Release metadata and registry documents are size-bounded, include-bounded, and normalized to stable UI registry errors before any project mutation.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-BOUNDED-REMOTE-DOCUMENTS' }],
+})
+
+export const CLI_UI_EXACT_ITEM_SOURCE = defineLaw({
+  id: 'CLI-UI-EXACT-ITEM-SOURCE',
+  statement:
+    'An add operation admits the exact built item document against the release index and records a content-bearing source digest before invoking project tooling.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-EXACT-ITEM-SOURCE' }],
+})
+
+export const CLI_UI_SEMANTIC_DIFF = defineLaw({
+  id: 'CLI-UI-SEMANTIC-DIFF',
+  statement:
+    'Diff is read-only, path-contained, and classifies locked source and files as upstream changed, unchanged, modified, or deleted without delegating truth to tool output.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-SEMANTIC-DIFF' }],
+})

package/src/ui/.spec/layout.ts

@@ -0,0 +1,16 @@
+import { defineLayout } from '@astrale-os/spec/authoring'
+
+export default defineLayout({
+  entries: [
+    '.spec/',
+    '__tests__/',
+    'index.ts',
+    'lock.ts',
+    'model.ts',
+    'operations.ts',
+    'project.ts',
+    'release.ts',
+    'runner.ts',
+  ],
+  exact: true,
+})