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

package/dist/astrale.js

@@ -2578,7 +2578,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "1.0.0-beta.13",
+    version: "1.0.0-beta.14",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -83398,11 +83398,43 @@ var init_lock = __esm(() => {
 });
 
 // src/ui/project.ts
-import { access as access2, lstat, readFile as readFile17 } from "node:fs/promises";
+import { access as access2, lstat, readFile as readFile17, realpath as realpath2 } from "node:fs/promises";
 import path5 from "node:path";
 async function exists(target2) {
   return access2(target2).then(() => true, () => false);
 }
+async function readManifest(target2) {
+  try {
+    return JSON.parse(await readFile17(target2, "utf8"));
+  } catch (cause) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "package.json is not valid JSON.", undefined, {
+      cause
+    });
+  }
+}
+function hasReactTailwind(manifest) {
+  const dependencies = {
+    ...manifest.dependencies,
+    ...manifest.devDependencies,
+    ...manifest.peerDependencies
+  };
+  return Boolean(dependencies.react && dependencies["react-dom"] && dependencies.tailwindcss);
+}
+async function assertPhysicalProjectPath(root, target2) {
+  const physicalRoot = await realpath2(root);
+  let existing = target2;
+  while (!await exists(existing)) {
+    const parent = path5.dirname(existing);
+    if (parent === existing)
+      break;
+    existing = parent;
+  }
+  const physicalTarget = await realpath2(existing);
+  const relative = path5.relative(physicalRoot, physicalTarget);
+  if (relative === ".." || relative.startsWith(".." + path5.sep) || path5.isAbsolute(relative)) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "components.json CSS path escapes the project.");
+  }
+}
 async function discoverUiProject(input = process.cwd()) {
   let root = path5.resolve(input);
   if (!await exists(root)) {
@@ -83410,7 +83442,19 @@ async function discoverUiProject(input = process.cwd()) {
   }
   if (!(await lstat(root)).isDirectory())
     root = path5.dirname(root);
-  while (!await exists(path5.join(root, "package.json"))) {
+  while (true) {
+    const manifestPath = path5.join(root, "package.json");
+    if (await exists(manifestPath)) {
+      const manifest = await readManifest(manifestPath);
+      const parent2 = path5.dirname(root);
+      if (hasReactTailwind(manifest) || parent2 === root)
+        break;
+      if (await exists(path5.join(parent2, "package.json"))) {
+        root = parent2;
+        continue;
+      }
+      break;
+    }
     const parent = path5.dirname(root);
     if (parent === root) {
       throw new UiError("UI_PROJECT_UNSUPPORTED", "No package.json found from " + path5.resolve(input), "Run the command inside an existing React application or pass its path.");
@@ -83418,14 +83462,7 @@ async function discoverUiProject(input = process.cwd()) {
     root = parent;
   }
   const packageJsonPath = path5.join(root, "package.json");
-  let packageJson;
-  try {
-    packageJson = JSON.parse(await readFile17(packageJsonPath, "utf8"));
-  } catch (cause) {
-    throw new UiError("UI_PROJECT_UNSUPPORTED", "package.json is not valid JSON.", undefined, {
-      cause
-    });
-  }
+  const packageJson = await readManifest(packageJsonPath);
   let manager = "npm";
   let lockPath;
   for (const [file2, candidate2] of MANAGERS) {
@@ -83452,9 +83489,34 @@ async function discoverUiProject(input = process.cwd()) {
     }[manager];
     lockPath = path5.join(root, expectedLock);
   }
-  const cssCandidates = ["src/index.css", "src/app.css", "app/globals.css", "src/styles.css"];
+  const rootCssCandidates = ["src/index.css", "src/app.css", "app/globals.css", "src/styles.css"];
+  const frontendCssCandidates = [
+    "frontend/src/index.css",
+    "frontend/src/app.css",
+    "frontend/src/styles.css"
+  ];
+  const componentsPath = path5.join(root, "components.json");
+  const configuredCss = await readFile17(componentsPath, "utf8").then((value3) => {
+    const components = JSON.parse(value3);
+    const css = components.tailwind?.css;
+    if (typeof css !== "string" || css.length === 0)
+      return;
+    const target2 = path5.resolve(root, css);
+    const relative = path5.relative(root, target2);
+    if (relative === ".." || relative.startsWith(".." + path5.sep) || path5.isAbsolute(relative)) {
+      throw new UiError("UI_PROJECT_UNSUPPORTED", "components.json CSS path escapes the project.");
+    }
+    return { relative: relative.split(path5.sep).join("/"), target: target2 };
+  }).catch((error52) => {
+    if (error52 instanceof UiError)
+      throw error52;
+    return;
+  });
+  const configuredCssRelative = configuredCss?.relative;
+  const cssCandidates = configuredCssRelative !== undefined ? [configuredCssRelative] : await exists(path5.join(root, "frontend/package.json")) ? [...frontendCssCandidates, ...rootCssCandidates] : [...rootCssCandidates, ...frontendCssCandidates];
   const resolvedCss = await Promise.all(cssCandidates.map(async (file2) => await exists(path5.join(root, file2)) ? file2 : undefined));
-  const cssRelative = resolvedCss.find(Boolean) ?? "src/astrale-ui.css";
+  const cssRelative = configuredCssRelative ?? resolvedCss.find(Boolean) ?? "src/astrale-ui.css";
+  await assertPhysicalProjectPath(root, path5.join(root, cssRelative));
   return {
     root,
     packageJsonPath,
@@ -83462,7 +83524,7 @@ async function discoverUiProject(input = process.cwd()) {
     manager,
     lockPath,
     cssPath: path5.join(root, cssRelative),
-    componentsPath: path5.join(root, "components.json"),
+    componentsPath,
     uiLockPath: path5.join(root, "astrale-ui.lock.json")
   };
 }
@@ -83549,11 +83611,14 @@ async function json4(fetcher, url3, label) {
   }
 }
 async function resolveUiRelease(requested, fetcher = fetch) {
-  const versionDocument = requested ? { version: requested.replace(/^v/u, "") } : await json4(fetcher, NPM_PACKAGE + "/latest", "npm UI release");
+  const versionDocument = requested ? { version: requested.replace(/^v/u, "") } : await json4(fetcher, NPM_PACKAGE + "/beta", "npm UI release");
   const version2 = versionDocument.version;
   if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(version2)) {
     throw new UiError("UI_REGISTRY_UNAVAILABLE", "Invalid UI release version: " + version2);
   }
+  if (!requested && !/-beta\.\d+$/u.test(version2)) {
+    throw new UiError("UI_REGISTRY_UNAVAILABLE", "Invalid UI beta release version: " + version2);
+  }
   const ref2 = "v" + version2;
   const reference4 = await json4(fetcher, GITHUB_API + "/git/ref/tags/" + encodeURIComponent(ref2), "UI ref " + ref2);
   const commit = reference4.object.type === "commit" ? reference4.object.sha : (await json4(fetcher, reference4.object.url, "annotated UI tag " + ref2)).object.sha;
@@ -83656,7 +83721,7 @@ var init_runner = __esm(() => {
 });
 
 // src/ui/operations.ts
-import { access as access3, lstat as lstat2, mkdir as mkdir10, readFile as readFile18, realpath as realpath2, rm as rm3, writeFile as writeFile6 } from "node:fs/promises";
+import { access as access3, lstat as lstat2, mkdir as mkdir10, readFile as readFile18, realpath as realpath3, rm as rm3, writeFile as writeFile6 } from "node:fs/promises";
 import path6 from "node:path";
 async function exists2(target2) {
   return access3(target2).then(() => true, () => false);
@@ -84014,8 +84079,8 @@ async function safeTarget(project2, relative) {
   }
   const target2 = path6.resolve(project2.root, relative);
   projectRelative(project2, target2);
-  const parent = await realpath2(path6.dirname(target2));
-  const root = await realpath2(project2.root);
+  const parent = await realpath3(path6.dirname(target2));
+  const root = await realpath3(project2.root);
   if (parent !== root && !parent.startsWith(root + path6.sep)) {
     throw new UiError("UI_LOCK_INVALID", "Registry target escapes through a symlink: " + relative);
   }
@@ -84030,7 +84095,7 @@ async function assertSafePlannedTarget(project2, relative) {
   }
   const target2 = path6.resolve(project2.root, relative);
   projectRelative(project2, target2);
-  const root = await realpath2(project2.root);
+  const root = await realpath3(project2.root);
   const physicalTarget = path6.resolve(root, path6.relative(project2.root, target2));
   let current = root;
   for (const segment of path6.relative(root, physicalTarget).split(path6.sep)) {
@@ -88103,7 +88168,7 @@ function registerGroup(parent, group) {
 // src/program/build.ts
 async function buildProgram() {
   const program4 = new Command2;
-  program4.name("astrale").description("Astrale CLI — connect to existing Astrale kernels").version(package_default.version).showSuggestionAfterError(true).addOption(new Option2("--ci", "Machine mode: no prompts, structured errors on stderr")).addOption(new Option2("--no-prompt", "Disable interactive prompts")).action(async () => {
+  program4.name("astrale").description("Astrale CLI — connect to existing Astrale kernels").version(package_default.version, "-V, --cli-version", "output the CLI version (root alias: --version)").showSuggestionAfterError(true).addOption(new Option2("--ci", "Machine mode: no prompts, structured errors on stderr")).addOption(new Option2("--no-prompt", "Disable interactive prompts")).action(async () => {
     if (process.stdin.isTTY && process.stdout.isTTY) {
       const { shouldAutostartSetup: shouldAutostartSetup2 } = await Promise.resolve().then(() => (init_engine(), exports_engine));
       if (await shouldAutostartSetup2()) {
@@ -88263,6 +88328,16 @@ Examples:
 `);
   return program4;
 }
+// src/program/argv.ts
+function normalizeRootVersionArgv(argv) {
+  const normalized = [...argv];
+  const commandIndex = normalized.findIndex((token, index3) => index3 >= 2 && !token.startsWith("-"));
+  const versionIndex = normalized.indexOf("--version", 2);
+  if (versionIndex !== -1 && (commandIndex === -1 || versionIndex < commandIndex)) {
+    normalized[versionIndex] = "--cli-version";
+  }
+  return normalized;
+}
 // src/telemetry/recorder.ts
 import { appendFileSync as appendFileSync2 } from "node:fs";
 
@@ -88378,7 +88453,15 @@ function ensureSession(cwd) {
 init_settings();
 init_store();
 var NOOP = () => {};
-var HELP_VERSION = new Set(["-h", "--help", "-V", "--version", "help", "version"]);
+var HELP_VERSION = new Set([
+  "-h",
+  "--help",
+  "-V",
+  "--version",
+  "--cli-version",
+  "help",
+  "version"
+]);
 function isHelpOrVersion(args) {
   return args.every((a) => HELP_VERSION.has(a));
 }
@@ -88500,14 +88583,15 @@ var errorName;
 if (finalize2)
   process.on("exit", (code) => finalize2(code ?? 0, errorName));
 maybeTriggerAnalysis(process.argv);
-configureInvocation(process.argv);
+var argv = normalizeRootVersionArgv(process.argv);
+configureInvocation(argv);
 var program4 = await buildProgram();
 overrideExits(program4);
 program4.configureOutput({ writeErr: () => {
   return;
 } });
 try {
-  await program4.parseAsync();
+  await program4.parseAsync(argv);
 } catch (error52) {
   if (error52 instanceof CommanderError) {
     if (error52.exitCode === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.14",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",

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

@@ -72,6 +72,21 @@ describe('UI command machine contracts', () => {
     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>
@@ -99,10 +114,11 @@ describe('UI command machine contracts', () => {
   })
 })
 
-function mockFetch(): typeof fetch {
+function mockFetch(seen: string[] = []): 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' })
+    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: '' } })
     }

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

@@ -5,7 +5,7 @@ import { createHash } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { buildProgram } from '../index'
+import { buildProgram, normalizeRootVersionArgv } from '../index'
 
 // Help output is the public CLI contract: version, spec anchors, and skill mirror stay in sync.
 
@@ -195,7 +195,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '873d096c4e99f29ab1db17bec0abc4ad2de613f5e44f9cba97c95b052c8b5a98',
+      'd37c3d80b3067b3553b8527b10bf1c5632922d624b3d6072c3b03e7a507efc4f',
     )
   })
 
@@ -312,6 +312,99 @@ describe('help contract — connect-only command surface', () => {
 })
 
 describe('help contract — UI is project tooling', () => {
+  test('keeps the documented root version alias operational', async () => {
+    const program = await buildProgram()
+    let stdout = ''
+    program.exitOverride().configureOutput({
+      writeOut: (chunk) => {
+        stdout += chunk ?? ''
+      },
+    })
+
+    await expect(
+      program.parseAsync(normalizeRootVersionArgv(['node', 'astrale', '--version'])),
+    ).rejects.toMatchObject({ code: 'commander.version' })
+    expect(stdout.trim()).toBe(program.version() ?? '')
+    expect(program.helpInformation()).toMatch(/root alias:\s+--version/u)
+  })
+
+  test('routes root and subcommand version flags to their exact owners', async () => {
+    const program = await buildProgram()
+    const uiList = program.commands
+      .find((command) => command.name() === 'ui')
+      ?.commands.find((command) => command.name() === 'list')
+    let observedVersion: unknown
+    uiList?.action((_query, options) => {
+      observedVersion = options.version
+    })
+
+    const uiArgv = ['node', 'astrale', 'ui', 'list', 'chart', '--version', '0.3.0-beta.1']
+    expect(normalizeRootVersionArgv(uiArgv)).toEqual(uiArgv)
+    expect(normalizeRootVersionArgv(['node', 'astrale', '--version'])).toEqual([
+      'node',
+      'astrale',
+      '--cli-version',
+    ])
+    expect(normalizeRootVersionArgv(['node', 'astrale', '--ci', '--version'])).toEqual([
+      'node',
+      'astrale',
+      '--ci',
+      '--cli-version',
+    ])
+
+    await program.parseAsync(uiArgv)
+
+    expect(observedVersion).toBe('0.3.0-beta.1')
+  })
+
+  test('routes explicit versions with positional inputs for UI init and update', async () => {
+    const program = await buildProgram()
+    const uiInit = program.commands
+      .find((command) => command.name() === 'ui')
+      ?.commands.find((command) => command.name() === 'init')
+    const update = program.commands.find((command) => command.name() === 'update')
+    let initializedPath: unknown
+    let initializedVersion: unknown
+    let updateVersion: unknown
+    uiInit?.action((projectPath, options) => {
+      initializedPath = projectPath
+      initializedVersion = options.version
+    })
+    update?.action((options) => {
+      updateVersion = options.version
+    })
+
+    await program.parseAsync([
+      'node',
+      'astrale',
+      'ui',
+      'init',
+      './app',
+      '--version',
+      '0.3.0-beta.1',
+    ])
+    expect(initializedPath).toBe('./app')
+    expect(initializedVersion).toBe('0.3.0-beta.1')
+
+    await program.parseAsync(['node', 'astrale', 'update', '--version', '1.0.0-beta.13'])
+    expect(updateVersion).toBe('1.0.0-beta.13')
+  })
+
+  test('continues to admit global machine flags after a subcommand', async () => {
+    const program = await buildProgram()
+    const uiList = program.commands
+      .find((command) => command.name() === 'ui')
+      ?.commands.find((command) => command.name() === 'list')
+    let invoked = false
+    uiList?.action(() => {
+      invoked = true
+    })
+
+    await program.parseAsync(['node', 'astrale', 'ui', 'list', '--ci', '--no-prompt'])
+
+    expect(invoked).toBe(true)
+  })
+
   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')

package/src/program/argv.ts

@@ -0,0 +1,14 @@
+/**
+ * Keep `astrale --version` as the familiar root spelling without claiming the
+ * same flag after a subcommand. Commands such as `ui list` and `update` own
+ * their release `--version` value.
+ */
+export function normalizeRootVersionArgv(argv: readonly string[]): string[] {
+  const normalized = [...argv]
+  const commandIndex = normalized.findIndex((token, index) => index >= 2 && !token.startsWith('-'))
+  const versionIndex = normalized.indexOf('--version', 2)
+  if (versionIndex !== -1 && (commandIndex === -1 || versionIndex < commandIndex)) {
+    normalized[versionIndex] = '--cli-version'
+  }
+  return normalized
+}

package/src/program/build.ts

@@ -19,7 +19,7 @@ export async function buildProgram(): Promise<Command> {
     .description('Astrale CLI — connect to existing Astrale kernels')
     // Single source of truth = package.json (bumped by release-please together
     // with .release-please-manifest.json). Never hand-write a version literal.
-    .version(pkg.version)
+    .version(pkg.version, '-V, --cli-version', 'output the CLI version (root alias: --version)')
     .showSuggestionAfterError(true)
     .addOption(new Option('--ci', 'Machine mode: no prompts, structured errors on stderr'))
     .addOption(new Option('--no-prompt', 'Disable interactive prompts'))

package/src/program/index.ts

@@ -1,2 +1,3 @@
 export { buildProgram } from './build.js'
+export { normalizeRootVersionArgv } from './argv.js'
 export type { CommandArgument, CommandDefinition, CommandGroup, CommandOption } from './command.js'

package/src/telemetry/__tests__/recorder.test.ts

@@ -91,6 +91,7 @@ describe('beginInvocation', () => {
   test('writes nothing for help/version-only invocations', () => {
     beginInvocation(['node', 'astrale', '--help'])(0)
     beginInvocation(['node', 'astrale', '--version'])(0)
+    beginInvocation(['node', 'astrale', '--cli-version'])(0)
     beginInvocation(['node', 'astrale'])(0)
     expect(listSessions()).toHaveLength(0)
   })

package/src/telemetry/recorder.ts

@@ -17,7 +17,15 @@ import { eventsPath } from './store'
 export type Finalizer = (exitCode: number, errorName?: string) => void
 
 const NOOP: Finalizer = () => {}
-const HELP_VERSION = new Set(['-h', '--help', '-V', '--version', 'help', 'version'])
+const HELP_VERSION = new Set([
+  '-h',
+  '--help',
+  '-V',
+  '--version',
+  '--cli-version',
+  'help',
+  'version',
+])
 
 /** Bare invocation (every() is true for []) or only help/version tokens — skip. */
 function isHelpOrVersion(args: string[]): boolean {

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

@@ -114,6 +114,37 @@ function lock(): UiLock {
 }
 
 describe('UI release and runner contracts', () => {
+  test('resolves the default release from the public beta channel', async () => {
+    const seen: string[] = []
+    const fetcher = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = String(input)
+      if (url.endsWith('/@astrale-os/ui/beta')) {
+        seen.push(url)
+        return Response.json({ version: '0.3.0-beta.1' })
+      }
+      return mockFetch(seen)(input, init)
+    }) as typeof fetch
+
+    const release = await resolveUiRelease(undefined, fetcher)
+
+    expect(release.version).toBe('0.3.0-beta.1')
+    expect(seen[0]).toBe('https://registry.npmjs.org/@astrale-os/ui/beta')
+    expect(seen).not.toContain('https://registry.npmjs.org/@astrale-os/ui/latest')
+  })
+
+  test('rejects a public beta channel that does not resolve to a beta release', async () => {
+    const fetcher = (async (input: string | URL | Request) => {
+      const url = String(input)
+      if (url.endsWith('/@astrale-os/ui/beta')) return Response.json({ version: '0.3.0' })
+      throw new Error('release snapshot must not be fetched')
+    }) as typeof fetch
+
+    await expect(resolveUiRelease(undefined, fetcher)).rejects.toMatchObject({
+      code: 'UI_REGISTRY_UNAVAILABLE',
+      message: 'Invalid UI beta release version: 0.3.0',
+    })
+  })
+
   /** @evidence TEST-CLI-UI-ONE-SNAPSHOT */
   test('resolves one commit and reads the full release snapshot from it', async () => {
     const seen: string[] = []
@@ -211,6 +242,67 @@ describe('UI release and runner contracts', () => {
 })
 
 describe('UI initialization transaction', () => {
+  test('initializes the generated Domain frontend stylesheet instead of an unused fallback', async () => {
+    const root = await fixture()
+    await mkdir(path.join(root, 'frontend/src'), { recursive: true })
+    await writeFile(
+      path.join(root, 'frontend/package.json'),
+      JSON.stringify({ name: 'astrale-frontend', private: true, type: 'module' }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    const rootCssBefore = await readFile(path.join(root, 'src/index.css'), 'utf8')
+
+    await initUi(
+      { path: path.join(root, 'frontend'), version: '0.3.0-beta.0', install: false },
+      { fetcher: mockFetch() },
+    )
+
+    const css = await readFile(path.join(root, 'frontend/src/styles.css'), 'utf8')
+    const components = JSON.parse(await readFile(path.join(root, 'components.json'), 'utf8'))
+    expect(css).toContain("@import '@astrale-os/ui/theme.css';")
+    expect(css).toContain('/* Domain frontend */')
+    expect(components.tailwind.css).toBe('frontend/src/styles.css')
+    expect(await readFile(path.join(root, 'src/index.css'), 'utf8')).toBe(rootCssBefore)
+    expect(
+      JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8')).dependencies,
+    ).toHaveProperty('@astrale-os/ui')
+    expect(await Bun.file(path.join(root, 'src/astrale-ui.css')).exists()).toBe(false)
+
+    await writeFile(path.join(root, 'src/app.css'), '/* later root stylesheet */\n')
+    const repeated = await initUi(
+      { path: root, version: '0.3.0-beta.0', install: false },
+      { fetcher: mockFetch() },
+    )
+    expect(repeated.status).toBe('unchanged')
+  })
+
+  test('rejects configured and discovered stylesheets whose physical parent escapes', async () => {
+    const root = await fixture()
+    const outside = await fixture()
+    await symlink(outside, path.join(root, 'escaped'), 'dir')
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({ tailwind: { css: 'escaped/styles.css' } }),
+    )
+
+    await expect(
+      initUi({ path: root, version: '0.3.0-beta.0', install: false }, { fetcher: mockFetch() }),
+    ).rejects.toMatchObject({ code: 'UI_PROJECT_UNSUPPORTED' })
+    expect(await Bun.file(path.join(outside, 'styles.css')).exists()).toBe(false)
+
+    const automaticRoot = await fixture()
+    await rm(path.join(automaticRoot, 'src/index.css'))
+    const outsideCss = await readFile(path.join(outside, 'src/index.css'), 'utf8')
+    await symlink(outside, path.join(automaticRoot, 'frontend'), 'dir')
+    await expect(
+      initUi(
+        { path: automaticRoot, version: '0.3.0-beta.0', install: false },
+        { fetcher: mockFetch() },
+      ),
+    ).rejects.toMatchObject({ code: 'UI_PROJECT_UNSUPPORTED' })
+    expect(await readFile(path.join(outside, 'src/index.css'), 'utf8')).toBe(outsideCss)
+  })
+
   test('dry-run reports every mutation and writes nothing', async () => {
     const root = await fixture()
     const before = await readFile(path.join(root, 'package.json'), 'utf8')

package/src/ui/project.ts

@@ -1,4 +1,4 @@
-import { access, lstat, readFile } from 'node:fs/promises'
+import { access, lstat, readFile, realpath } from 'node:fs/promises'
 import path from 'node:path'
 
 import { UiError, type PackageManager } from './model'
@@ -29,6 +29,40 @@ async function exists(target: string): Promise<boolean> {
   )
 }
 
+async function readManifest(target: string): Promise<Record<string, unknown>> {
+  try {
+    return JSON.parse(await readFile(target, 'utf8')) as Record<string, unknown>
+  } catch (cause) {
+    throw new UiError('UI_PROJECT_UNSUPPORTED', 'package.json is not valid JSON.', undefined, {
+      cause,
+    })
+  }
+}
+
+function hasReactTailwind(manifest: Record<string, unknown>): boolean {
+  const dependencies = {
+    ...(manifest.dependencies as Record<string, string> | undefined),
+    ...(manifest.devDependencies as Record<string, string> | undefined),
+    ...(manifest.peerDependencies as Record<string, string> | undefined),
+  }
+  return Boolean(dependencies.react && dependencies['react-dom'] && dependencies.tailwindcss)
+}
+
+async function assertPhysicalProjectPath(root: string, target: string): Promise<void> {
+  const physicalRoot = await realpath(root)
+  let existing = target
+  while (!(await exists(existing))) {
+    const parent = path.dirname(existing)
+    if (parent === existing) break
+    existing = parent
+  }
+  const physicalTarget = await realpath(existing)
+  const relative = path.relative(physicalRoot, physicalTarget)
+  if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+    throw new UiError('UI_PROJECT_UNSUPPORTED', 'components.json CSS path escapes the project.')
+  }
+}
+
 export async function discoverUiProject(input = process.cwd()): Promise<UiProject> {
   let root = path.resolve(input)
   if (!(await exists(root))) {
@@ -36,7 +70,18 @@ export async function discoverUiProject(input = process.cwd()): Promise<UiProjec
   }
   if (!(await lstat(root)).isDirectory()) root = path.dirname(root)
 
-  while (!(await exists(path.join(root, 'package.json')))) {
+  while (true) {
+    const manifestPath = path.join(root, 'package.json')
+    if (await exists(manifestPath)) {
+      const manifest = await readManifest(manifestPath)
+      const parent = path.dirname(root)
+      if (hasReactTailwind(manifest) || parent === root) break
+      if (await exists(path.join(parent, 'package.json'))) {
+        root = parent
+        continue
+      }
+      break
+    }
     const parent = path.dirname(root)
     if (parent === root) {
       throw new UiError(
@@ -49,14 +94,7 @@ export async function discoverUiProject(input = process.cwd()): Promise<UiProjec
   }
 
   const packageJsonPath = path.join(root, 'package.json')
-  let packageJson: Record<string, unknown>
-  try {
-    packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8')) as Record<string, unknown>
-  } catch (cause) {
-    throw new UiError('UI_PROJECT_UNSUPPORTED', 'package.json is not valid JSON.', undefined, {
-      cause,
-    })
-  }
+  const packageJson = await readManifest(packageJsonPath)
 
   let manager: PackageManager = 'npm'
   let lockPath: string | undefined
@@ -90,11 +128,41 @@ export async function discoverUiProject(input = process.cwd()): Promise<UiProjec
     lockPath = path.join(root, expectedLock)
   }
 
-  const cssCandidates = ['src/index.css', 'src/app.css', 'app/globals.css', 'src/styles.css']
+  const rootCssCandidates = ['src/index.css', 'src/app.css', 'app/globals.css', 'src/styles.css']
+  const frontendCssCandidates = [
+    'frontend/src/index.css',
+    'frontend/src/app.css',
+    'frontend/src/styles.css',
+  ]
+  const componentsPath = path.join(root, 'components.json')
+  const configuredCss = await readFile(componentsPath, 'utf8')
+    .then((value) => {
+      const components = JSON.parse(value) as { tailwind?: { css?: unknown } }
+      const css = components.tailwind?.css
+      if (typeof css !== 'string' || css.length === 0) return undefined
+      const target = path.resolve(root, css)
+      const relative = path.relative(root, target)
+      if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+        throw new UiError('UI_PROJECT_UNSUPPORTED', 'components.json CSS path escapes the project.')
+      }
+      return { relative: relative.split(path.sep).join('/'), target }
+    })
+    .catch((error: unknown) => {
+      if (error instanceof UiError) throw error
+      return undefined
+    })
+  const configuredCssRelative = configuredCss?.relative
+  const cssCandidates =
+    configuredCssRelative !== undefined
+      ? [configuredCssRelative]
+      : (await exists(path.join(root, 'frontend/package.json')))
+        ? [...frontendCssCandidates, ...rootCssCandidates]
+        : [...rootCssCandidates, ...frontendCssCandidates]
   const resolvedCss = await Promise.all(
     cssCandidates.map(async (file) => ((await exists(path.join(root, file))) ? file : undefined)),
   )
-  const cssRelative = resolvedCss.find(Boolean) ?? 'src/astrale-ui.css'
+  const cssRelative = configuredCssRelative ?? resolvedCss.find(Boolean) ?? 'src/astrale-ui.css'
+  await assertPhysicalProjectPath(root, path.join(root, cssRelative))
 
   return {
     root,
@@ -103,7 +171,7 @@ export async function discoverUiProject(input = process.cwd()): Promise<UiProjec
     manager,
     lockPath,
     cssPath: path.join(root, cssRelative),
-    componentsPath: path.join(root, 'components.json'),
+    componentsPath,
     uiLockPath: path.join(root, 'astrale-ui.lock.json'),
   }
 }

package/src/ui/release.ts

@@ -67,11 +67,14 @@ export async function resolveUiRelease(
 ): Promise<UiRelease> {
   const versionDocument = requested
     ? { version: requested.replace(/^v/u, '') }
-    : await json<{ version: string }>(fetcher, NPM_PACKAGE + '/latest', 'npm UI release')
+    : await json<{ version: string }>(fetcher, NPM_PACKAGE + '/beta', 'npm UI release')
   const version = versionDocument.version
   if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(version)) {
     throw new UiError('UI_REGISTRY_UNAVAILABLE', 'Invalid UI release version: ' + version)
   }
+  if (!requested && !/-beta\.\d+$/u.test(version)) {
+    throw new UiError('UI_REGISTRY_UNAVAILABLE', 'Invalid UI beta release version: ' + version)
+  }
   const ref = 'v' + version
   const reference = await json<{
     object: { type: 'commit' | 'tag'; sha: string; url: string }