@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.30

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

@@ -0,0 +1,152 @@
+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('list forwards an explicit release without consulting the beta channel', async () => {
+    const seen: string[] = []
+    globalThis.fetch = mockFetch(seen)
+    const action = listCommand.action as (
+      query: string | undefined,
+      options: { json?: boolean; limit?: string; version?: string },
+    ) => Promise<void>
+
+    await action('line-basic', { json: true, limit: '100', version: '0.3.0-beta.1' })
+
+    expect(JSON.parse(stdout)).toEqual([item])
+    expect(seen.some((url) => url.endsWith('/@astrale-os/ui/beta'))).toBe(false)
+    expect(seen.some((url) => url.includes('/git/ref/tags/v0.3.0-beta.1'))).toBe(true)
+  })
+
+  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(seen: string[] = []): typeof fetch {
+  return (async (input: string | URL | Request) => {
+    const url = String(input)
+    seen.push(url)
+    if (url.endsWith('/@astrale-os/ui/beta')) return Response.json({ version: '0.3.0-beta.1' })
+    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,
+            files: item.files.map((file) => ({ ...file, path: 'line-basic.tsx' })),
+          },
+        ],
+      })
+    }
+    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, block, or theme source',
+  arguments: [
+    {
+      name: 'items',
+      description: 'Canonical registry addresses or a local exported theme CSS file',
+      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. Use theme/<name> for a released theme or ./theme.css for a playground export.\nOrdinary add never overwrites local edits. Run astrale ui doctor before intentionally replacing local source with --overwrite --yes.\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

package/src/commands/ui/doctor.ts

@@ -0,0 +1,21 @@
+import type { CommandDefinition } from '../../program'
+
+import { doctorUi, UiError } from '../../ui'
+import { UI_JSON_OPTION, UI_PROJECT_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_PROJECT_OPTION, UI_JSON_OPTION],
+  action: async (path: string | undefined, options: UiCommandOptions) =>
+    runUiCommand(options, () => {
+      if (path && options.project) {
+        throw new UiError(
+          'UI_ITEM_CONFLICT',
+          'Choose either the positional application path or --project, not both.',
+        )
+      }
+      return doctorUi(options.project ?? 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, blocks, and themes',
+  arguments: [{ name: 'query', description: 'Optional search text', required: false }],
+  options: [
+    {
+      flags: '--type <type>',
+      description: 'Restrict to pattern, block, or theme',
+      choices: ['pattern', 'block', 'theme'],
+    },
+    { 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/commands/update.ts

@@ -11,8 +11,13 @@ import {
   inDomainProject,
   type SdkOutdated,
 } from '../lib/sdk-deps'
-import { ASTRALE_CLI_SKILL, detectSkill, installSkills, SKILL_INSTALL_HINT } from '../lib/skills'
-import { DEFAULT_UPDATE_CHANNEL, updateAstrale } from '../lib/update'
+import {
+  checkAstraleSkills,
+  type SkillApplyResult,
+  type SkillCheckResult,
+  syncAstraleSkills,
+} from '../lib/skills'
+import { DEFAULT_UPDATE_CHANNEL, packageManagedUpdateError, updateAstrale } from '../lib/update'
 
 type UpdateOpts = RawOutputOpts & {
   check?: boolean
@@ -23,26 +28,26 @@ type UpdateOpts = RawOutputOpts & {
   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}`)
+async function refreshSkills(): Promise<SkillApplyResult> {
+  log.step('Ensuring Astrale agent skills are current and healthy')
+  const result = await syncAstraleSkills()
+  if (result.status === 'unchanged') log.success('Astrale skills already up to date')
+  else if (result.status === 'installed') log.success('Astrale skills installed')
+  else if (result.status === 'updated') log.success('Astrale skills updated')
+  else if (result.status === 'repaired') log.success('Astrale skills repaired and updated')
+  return result
+}
+
+function skillCheckStale(skills: SkillCheckResult): boolean {
+  return skills.status === 'update-available' || skills.status === 'repair-needed'
+}
+
+function printSkillCheck(skills: SkillCheckResult): void {
+  if (skills.status === 'current') log.success('Astrale skills are up to date')
+  else if (skills.status === 'update-available') log.info('Astrale skills update available')
+  else if (skills.status === 'repair-needed') log.warn('Astrale skills need repair')
+  else if (skills.status === 'unavailable') {
+    log.warn(`Could not verify Astrale skills${skills.error ? `: ${skills.error}` : ''}`)
   }
 }
 
@@ -104,14 +109,22 @@ async function refreshSdkDeps(check: boolean, assumeYes = false): Promise<boolea
 /**
  * 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.
+ * unified and NON-THROWING: an explicit package-managed result uses npm release
+ * identity, while script-install failures remain script failures in `error`
+ * instead of being recategorized. The SDK axis is already best-effort. Skills
+ * report meaningful health/freshness states without exposing installer metadata.
  */
 export type StaleReport = {
   stale: boolean
-  cli: { stale: boolean; managed: boolean; current?: string; latest?: string; channel?: string }
+  cli: {
+    stale: boolean
+    managed: boolean
+    current?: string
+    latest?: string
+    channel?: string
+    error?: string
+  }
+  skills: SkillCheckResult
   sdk: { stale: boolean; inProject: boolean; outdated: SdkOutdated[] }
 }
 
@@ -138,6 +151,15 @@ export async function cliStale(
       version: target.version,
       currentVersion: running,
     })
+    if (r.status === 'managed') {
+      const latest = await dependencies.fetchPackageVersion(target).catch(() => undefined)
+      return {
+        stale: latest !== undefined && latest !== running,
+        managed: true,
+        current: running,
+        ...(latest === undefined ? {} : { latest, channel: 'npm' }),
+      }
+    }
     if (r.status === 'updated') {
       return {
         stale: false,
@@ -154,13 +176,12 @@ export async function cliStale(
       latest: r.latestVersion,
       channel: r.channel,
     }
-  } catch {
-    const latest = await dependencies.fetchPackageVersion(target).catch(() => undefined)
+  } catch (error) {
     return {
-      stale: latest !== undefined && latest !== running,
-      managed: true,
+      stale: false,
+      managed: false,
       current: running,
-      ...(latest === undefined ? {} : { latest, channel: 'npm' }),
+      error: error instanceof Error ? error.message : String(error),
     }
   }
 }
@@ -202,7 +223,7 @@ export default {
       default: DEFAULT_UPDATE_CHANNEL,
     },
     { flags: '--version <version>', description: 'Update to an exact version tag' },
-    { flags: '--no-skills', description: 'Skip refreshing the astrale agent skills' },
+    { flags: '--no-skills', description: 'Skip ensuring the Astrale agent skills' },
     { flags: '--no-deps', description: 'Skip checking @astrale-os SDK dependency versions' },
     {
       flags: '--yes',
@@ -215,23 +236,22 @@ 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
+  before the binary is replaced. (2) The Astrale agent skills: installs every
+  top-level skill published from astrale-os/cli main, updates healthy older
+  installs, repairs inconsistent installs, and verifies the result before
+  reporting success. (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).
 
   The default release channel is beta; --channel overrides it for one run.
-  --check is a dry run (binary + SDK deps; exit 10 if anything is available) and
+  --check is a dry run (binary + skills + 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
+  ({ stale, cli, skills, sdk }) for tooling. --yes applies all three non-interactively 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.
+  blocks the skills/deps steps; a skill failure fails the command rather than
+  claiming a partial success. --no-skills / --no-deps explicitly skip those axes.
 
 Examples:
   $ astrale update
@@ -246,11 +266,18 @@ Examples:
     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.
+      // non-throwing staleness report and exits.
       if (opts.check && isMachine(opts)) {
         const cli = await cliStale(opts)
+        const skills: SkillCheckResult =
+          opts.skills === false ? { status: 'skipped' } : await checkAstraleSkills()
         const sdk = await sdkStale()
-        const report: StaleReport = { stale: cli.stale || sdk.stale, cli, sdk }
+        const report: StaleReport = {
+          stale: cli.stale || skillCheckStale(skills) || sdk.stale,
+          cli,
+          skills,
+          sdk,
+        }
         output(report, opts)
         if (report.stale) process.exitCode = 10
         return
@@ -294,11 +321,25 @@ Examples:
         log.success(`Updated astrale ${result.previousVersion} -> ${result.currentVersion}`)
         log.dim(`  channel: ${result.channel}`)
         log.dim(`  binary: ${result.bin}`)
+      } else if (result?.status === 'managed') {
+        const error = packageManagedUpdateError(result.executable)
+        if (!opts.yes) throw error
+        log.warn(`CLI self-update skipped: ${error.message}`)
       }
 
-      // 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 B — agent skills. A successful real update guarantees a verified
+      // latest cohort; --check remains read-only and reports its status.
+      if (opts.skills !== false) {
+        if (opts.check) {
+          const skills = await checkAstraleSkills()
+          printSkillCheck(skills)
+          if (skillCheckStale(skills)) anyAvailable = true
+        } else {
+          await refreshSkills()
+        }
+      } else if (!opts.check) {
+        log.dim('  Astrale skills skipped (--no-skills)')
+      }
 
       // Axis C — first-party @astrale-os/* deps in the current domain project.
       // Runs on --check too (reports availability); --yes applies without a prompt.
@@ -308,7 +349,7 @@ Examples:
 
       if (opts.check && anyAvailable) process.exitCode = 10
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition