@astrale-os/cli 1.0.0-beta.23 → 1.0.0-beta.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.23",
+  "version": "1.0.0-beta.24",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -57,6 +57,7 @@
     "jose": "^6.1.3",
     "ora": "^9.0.0",
     "ts-morph": "^25.0.1",
+    "tsconfig-paths": "4.2.0",
     "yaml": "^2.8.2",
     "zod": "^4.4.3"
   },

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

@@ -1209,6 +1209,201 @@ describe('UI source operations', () => {
     ).rejects.toBeInstanceOf(UiError)
   })
 
+  test('records multi-file component targets resolved through the consumer components alias', async () => {
+    const root = await lockedFixture()
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '@/components' },
+      }),
+    )
+    await writeFile(
+      path.join(root, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: {
+          paths: { '@/*': ['./src/*'], '@/components/*': ['./app/ui/*'] },
+        },
+      }),
+    )
+    await writeFile(
+      path.join(root, 'src/index.css'),
+      "@import '@astrale-os/ui/theme.css';\n@import '@astrale-os/ui/presets/astrale.css';\n",
+    )
+    const sidebar = path.join(root, 'src/components/astrale/component/sidebar/sidebar.tsx')
+    const hook = path.join(root, 'src/components/astrale/component/sidebar/use-mobile.ts')
+
+    const planned = await addUi(
+      ['component/sidebar'],
+      { project: root, dryRun: true, yes: true },
+      {
+        fetcher: mockFetch([], componentRegistry),
+        runner: async () => ({ code: 0, stdout: 'planned', stderr: '' }),
+      },
+    )
+    expect(planned.sources).toEqual([
+      expect.objectContaining({
+        files: [
+          'src/components/astrale/component/sidebar/sidebar.tsx',
+          'src/components/astrale/component/sidebar/use-mobile.ts',
+        ],
+      }),
+    ])
+
+    await addUi(
+      ['component/sidebar'],
+      { project: root, yes: true },
+      {
+        fetcher: mockFetch([], componentRegistry),
+        runner: async () => {
+          await mkdir(path.dirname(sidebar), { recursive: true })
+          await writeFile(sidebar, 'export const Sidebar = true\n')
+          await writeFile(hook, 'export const useMobile = true\n')
+          return { code: 0, stdout: '', stderr: '' }
+        },
+      },
+    )
+
+    const written = JSON.parse(await readFile(path.join(root, 'astrale-ui.lock.json'), 'utf8'))
+    expect(written.items['component/sidebar'].files).toEqual({
+      'src/components/astrale/component/sidebar/sidebar.tsx': digest(
+        'export const Sidebar = true\n',
+      ),
+      'src/components/astrale/component/sidebar/use-mobile.ts': digest(
+        'export const useMobile = true\n',
+      ),
+    })
+    expect((await doctorUi(root)).healthy).toBe(true)
+  })
+
+  test('resolves a components alias through package imports before tsconfig paths', async () => {
+    const root = await lockedFixture()
+    const manifestPath = path.join(root, 'package.json')
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+    manifest.imports = { '#app/*': './src/app/*' }
+    await writeFile(manifestPath, JSON.stringify(manifest))
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '#app/components' },
+      }),
+    )
+
+    const planned = await addUi(
+      ['pattern/chart/line/basic'],
+      { project: root, dryRun: true, yes: true },
+      {
+        fetcher: mockFetch(),
+        runner: async () => ({ code: 0, stdout: 'planned', stderr: '' }),
+      },
+    )
+
+    expect(planned.sources).toEqual([
+      expect.objectContaining({
+        files: ['src/app/components/astrale/pattern/chart/line-basic.tsx'],
+      }),
+    ])
+  })
+
+  test('rejects an unresolved package-import alias before invoking shadcn', async () => {
+    const root = await lockedFixture()
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '#missing/components' },
+      }),
+    )
+    let invoked = false
+
+    await expect(
+      addUi(
+        ['pattern/chart/line/basic'],
+        { project: root, yes: true },
+        {
+          fetcher: mockFetch(),
+          runner: async () => {
+            invoked = true
+            return { code: 0, stdout: '', stderr: '' }
+          },
+        },
+      ),
+    ).rejects.toMatchObject({ code: 'UI_PROJECT_UNSUPPORTED' })
+    expect(invoked).toBe(false)
+  })
+
+  test('resolves an extended JSONC baseUrl with the pinned shadcn config loader', async () => {
+    const root = await lockedFixture()
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '@/components' },
+      }),
+    )
+    await mkdir(path.join(root, 'config'), { recursive: true })
+    await writeFile(
+      path.join(root, 'tsconfig.json'),
+      '{\n  // shadcn loads this root config.\n  "extends": "./config/base.json",\n}\n',
+    )
+    await writeFile(
+      path.join(root, 'config/base.json'),
+      '{\n  "compilerOptions": {\n    "baseUrl": "..",\n    "paths": { "@/*": ["frontend/src/*"], },\n  },\n}\n',
+    )
+
+    const planned = await addUi(
+      ['pattern/chart/line/basic'],
+      { project: root, dryRun: true, yes: true },
+      {
+        fetcher: mockFetch(),
+        runner: async () => ({ code: 0, stdout: 'planned', stderr: '' }),
+      },
+    )
+
+    expect(planned.sources).toEqual([
+      expect.objectContaining({
+        files: ['frontend/src/components/astrale/pattern/chart/line-basic.tsx'],
+      }),
+    ])
+  })
+
+  test('rejects an alias mapping outside the project before invoking shadcn', async () => {
+    const root = await lockedFixture()
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '@/components' },
+      }),
+    )
+    await writeFile(
+      path.join(root, 'tsconfig.json'),
+      JSON.stringify({ compilerOptions: { paths: { '@/*': ['../outside/*'] } } }),
+    )
+    let invoked = false
+
+    await expect(
+      addUi(
+        ['pattern/chart/line/basic'],
+        { project: root, yes: true },
+        {
+          fetcher: mockFetch(),
+          runner: async () => {
+            invoked = true
+            return { code: 0, stdout: '', stderr: '' }
+          },
+        },
+      ),
+    ).rejects.toMatchObject({ code: 'UI_PROJECT_UNSUPPORTED' })
+    expect(invoked).toBe(false)
+  })
+
   test('restores the exact locked UI dependency after shadcn applies its compatible range', async () => {
     const root = await lockedFixture()
     const installed = path.join(root, 'components/astrale/pattern/chart/line-basic.tsx')
@@ -1335,10 +1530,22 @@ describe('UI source operations', () => {
     expect(invoked).toBe(false)
   })
 
-  test('restores declared files and package state after a partial shadcn failure', async () => {
+  test('restores alias-resolved files and package state after a partial shadcn failure', async () => {
     const root = await lockedFixture()
-    const first = path.join(root, 'components/astrale/pattern/chart/line-basic.tsx')
-    const second = path.join(root, 'components/astrale/pattern/chart/summary.tsx')
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '@/components' },
+      }),
+    )
+    await writeFile(
+      path.join(root, 'tsconfig.json'),
+      JSON.stringify({ compilerOptions: { paths: { '@/*': ['./src/*'] } } }),
+    )
+    const first = path.join(root, 'src/components/astrale/pattern/chart/line-basic.tsx')
+    const second = path.join(root, 'src/components/astrale/pattern/chart/summary.tsx')
     await mkdir(path.dirname(first), { recursive: true })
     await writeFile(first, 'consumer original\n')
     const twoFileRegistry: UiRegistry = {

package/src/ui/lock.ts

@@ -32,7 +32,7 @@ export function parseUiLock(value: unknown): UiLock {
   }
   for (const [address, item] of Object.entries(lock.items)) {
     if (
-      !/^(?:(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+|theme\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/u.test(
+      !/^(?:component\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*|(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+|theme\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/u.test(
         address,
       ) ||
       !isRecord(item) ||

package/src/ui/operations.ts

@@ -17,6 +17,7 @@ import {
   assertSupportedUiProject,
   discoverUiProject,
   projectRelative,
+  resolveUiRegistryTarget,
   type UiProject,
 } from './project'
 import {
@@ -724,13 +725,19 @@ export async function addUi(
     return addReleasedTheme(themes[0]!, itemDocuments[0]!, project, options)
   }
   await rejectLocalChanges(project, lock, items, options.overwrite === true)
-  const targets = (
+  const declaredTargets = items.flatMap((item) =>
+    item.files.flatMap((file) => (file.target ? [file.target] : [])),
+  )
+  const resolvedTargets = new Map(
     await Promise.all(
-      items.flatMap((item) =>
-        item.files
-          .filter((file) => file.target)
-          .map((file) => assertSafePlannedTarget(project, file.target!)),
+      declaredTargets.map(
+        async (target) => [target, await resolveUiRegistryTarget(project, target)] as const,
       ),
+    ),
+  )
+  const targets = (
+    await Promise.all(
+      [...resolvedTargets.values()].map((target) => assertSafePlannedTarget(project, target)),
     )
   ).filter((target, index, all) => all.indexOf(target) === index)
   const invocation = shadcnInvocation(project.manager, release.compatibility.shadcn, [
@@ -802,7 +809,9 @@ export async function addUi(
       sources: itemDocuments.map((item) => ({
         address: item.meta.canonicalAddress,
         dependencies: item.dependencies ?? [],
-        files: item.files.map((file) => file.target).filter(Boolean),
+        files: item.files
+          .map((file) => (file.target ? resolvedTargets.get(file.target) : undefined))
+          .filter(Boolean),
       })),
       command: [invocation.file, ...invocation.args],
       output: result.stdout,
@@ -824,7 +833,7 @@ export async function addUi(
       const files: Record<string, string> = {}
       for (const file of item.files) {
         if (!file.target) continue
-        const target = await safeTarget(project, file.target)
+        const target = await safeTarget(project, resolvedTargets.get(file.target)!)
         files[projectRelative(project, target)] = digest(await readFile(target))
       }
       lock.items[item.meta.canonicalAddress] = {

package/src/ui/project.ts

@@ -1,5 +1,6 @@
 import { access, lstat, readFile, realpath } from 'node:fs/promises'
 import path from 'node:path'
+import { loadConfig } from 'tsconfig-paths'
 
 import { UiError, type PackageManager } from './model'
 
@@ -40,6 +41,119 @@ async function readManifest(target: string): Promise<Record<string, unknown>> {
   }
 }
 
+function pathPatternMatch(pattern: string, candidate: string): string | undefined {
+  const wildcard = pattern.indexOf('*')
+  if (wildcard === -1) return pattern === candidate ? '' : undefined
+  const prefix = pattern.slice(0, wildcard)
+  const suffix = pattern.slice(wildcard + 1)
+  if (!candidate.startsWith(prefix) || !candidate.endsWith(suffix)) return undefined
+  return candidate.slice(prefix.length, candidate.length - suffix.length)
+}
+
+function resolvePackageImport(project: UiProject, candidate: string): string | undefined {
+  const imports = project.packageJson.imports
+  if (!imports || typeof imports !== 'object' || Array.isArray(imports)) return undefined
+  const matches = Object.entries(imports as Record<string, unknown>)
+    .flatMap(([pattern, target]) => {
+      const wildcard = pathPatternMatch(pattern, candidate)
+      if (wildcard === undefined || typeof target !== 'string' || !target.startsWith('./'))
+        return []
+      const wildcardIndex = pattern.indexOf('*')
+      return [
+        {
+          exact: wildcardIndex === -1,
+          prefixLength: wildcardIndex === -1 ? pattern.length : wildcardIndex,
+          suffixLength: wildcardIndex === -1 ? 0 : pattern.length - wildcardIndex - 1,
+          target: target.replaceAll('*', wildcard),
+        },
+      ]
+    })
+    .sort(
+      (left, right) =>
+        Number(right.exact) - Number(left.exact) ||
+        right.prefixLength - left.prefixLength ||
+        right.suffixLength - left.suffixLength,
+    )
+  return matches[0] ? path.resolve(project.root, matches[0].target) : undefined
+}
+
+async function resolveAlias(project: UiProject, candidate: string): Promise<string | undefined> {
+  const config = loadConfig(project.root)
+  if (config.resultType === 'failed') return undefined
+  const matches: Array<{
+    exact: boolean
+    prefixLength: number
+    suffixLength: number
+    resolved: string
+  }> = []
+  for (const [pattern, replacements] of Object.entries(config.paths)) {
+    const wildcard = pathPatternMatch(pattern, candidate)
+    if (wildcard === undefined) continue
+    const replacement = replacements?.[0]
+    if (!replacement) continue
+    const wildcardIndex = pattern.indexOf('*')
+    matches.push({
+      exact: wildcardIndex === -1,
+      prefixLength: wildcardIndex === -1 ? pattern.length : wildcardIndex,
+      suffixLength: wildcardIndex === -1 ? 0 : pattern.length - wildcardIndex - 1,
+      resolved: path.resolve(config.absoluteBaseUrl, replacement.replaceAll('*', wildcard)),
+    })
+  }
+  matches.sort(
+    (left, right) =>
+      Number(right.exact) - Number(left.exact) ||
+      right.prefixLength - left.prefixLength ||
+      right.suffixLength - left.suffixLength,
+  )
+  const best = matches[0]
+  if (!best) return undefined
+  const ambiguous = matches.some(
+    (match) =>
+      match.exact === best.exact &&
+      match.prefixLength === best.prefixLength &&
+      match.suffixLength === best.suffixLength &&
+      match.resolved !== best.resolved,
+  )
+  if (ambiguous) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'The components alias resolves to conflicting project paths.',
+      'Keep one authoritative compilerOptions.paths mapping for the components alias.',
+    )
+  }
+  return best.resolved
+}
+
+export async function resolveUiRegistryTarget(
+  project: UiProject,
+  declaredTarget: string,
+): Promise<string> {
+  if (!declaredTarget.startsWith('components/')) return declaredTarget
+  const components = await readFile(project.componentsPath, 'utf8')
+    .then((value) => JSON.parse(value) as { aliases?: { components?: unknown } })
+    .catch(() => undefined)
+  const componentsAlias = components?.aliases?.components
+  if (typeof componentsAlias !== 'string' || componentsAlias.length === 0) return declaredTarget
+  const suffix = declaredTarget.slice('components/'.length)
+  const directAlias = /^(?:\.?\.?\/|src\/|app\/|frontend\/|components\/)/u.test(componentsAlias)
+  const resolved =
+    resolvePackageImport(project, componentsAlias) ??
+    (await resolveAlias(project, componentsAlias)) ??
+    (directAlias ? path.resolve(project.root, componentsAlias) : undefined)
+  if (!resolved) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'components.json alias cannot be resolved through tsconfig.json or jsconfig.json.',
+      'Define a matching compilerOptions.paths entry for ' + componentsAlias + '.',
+    )
+  }
+  const relative = path.relative(project.root, path.join(resolved, suffix))
+  if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+    throw new UiError('UI_PROJECT_UNSUPPORTED', 'components.json alias escapes the project.')
+  }
+  return relative.split(path.sep).join('/')
+}
+
 function hasReactTailwind(manifest: Record<string, unknown>): boolean {
   const dependencies = {
     ...(manifest.dependencies as Record<string, string> | undefined),