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

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.15",
     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;
@@ -83590,7 +83655,10 @@ async function readRegistry(commit, fetcher) {
   return { name: root.name ?? "astrale-ui", homepage: root.homepage, items: installable };
 }
 async function resolveRegistryItems(source2, sourceUrl, commit, fetcher, visited) {
-  const direct = Array.isArray(source2.items) ? source2.items : [];
+  const releaseRoot = RAW + "/" + commit + "/";
+  const sourceRelative = sourceUrl.slice(releaseRoot.length);
+  const sourceDirectory = sourceRelative.slice(0, Math.max(0, sourceRelative.lastIndexOf("/")));
+  const direct = Array.isArray(source2.items) ? source2.items.map((item) => qualifyRegistryItemPaths(item, sourceDirectory)) : [];
   const includes = source2.include ?? [];
   if (!Array.isArray(includes)) {
     throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry include must be an array.");
@@ -83599,12 +83667,12 @@ async function resolveRegistryItems(source2, sourceUrl, commit, fetcher, visited
     throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry contains too many included documents.");
   }
   const nested = await Promise.all(includes.map(async (include) => {
-    if (typeof include !== "string" || include.startsWith("/") || !include.endsWith("registry.json") || include.split("/").includes("..")) {
+    if (typeof include !== "string" || !isSafeRelative2(include) || !/^[A-Za-z0-9._/-]+$/u.test(include) || !include.endsWith("registry.json") || include === "registry.json") {
       throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry contains an unsafe include.");
     }
+    const sourceDirectoryUrl = sourceUrl.slice(0, sourceUrl.lastIndexOf("/") + 1);
     const url3 = new URL(include, sourceUrl).toString();
-    const releaseRoot = RAW + "/" + commit + "/";
-    if (!url3.startsWith(releaseRoot) || visited.has(url3)) {
+    if (url3 !== sourceDirectoryUrl + include || !url3.startsWith(releaseRoot) || !url3.startsWith(sourceDirectoryUrl) || visited.has(url3)) {
       throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry include escaped or repeated the release snapshot.");
     }
     visited.add(url3);
@@ -83613,6 +83681,33 @@ async function resolveRegistryItems(source2, sourceUrl, commit, fetcher, visited
   }));
   return direct.concat(nested.flat());
 }
+function qualifyRegistryItemPaths(item, sourceDirectory) {
+  if (!item || typeof item !== "object")
+    return item;
+  const candidate2 = item;
+  if (!Array.isArray(candidate2.files))
+    return item;
+  return {
+    ...candidate2,
+    files: candidate2.files.map((file2) => {
+      if (!file2 || typeof file2 !== "object")
+        return file2;
+      const candidateFile = file2;
+      if (typeof candidateFile.path !== "string")
+        return file2;
+      if (!isSafeRelative2(candidateFile.path) || sourceDirectory !== "" && (candidateFile.path === sourceDirectory || candidateFile.path.startsWith(sourceDirectory + "/"))) {
+        throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry contains an invalid installable item path.");
+      }
+      if (sourceDirectory === "")
+        return file2;
+      const qualified = sourceDirectory + "/" + candidateFile.path;
+      if (!isSafeRelative2(qualified)) {
+        throw new UiError("UI_REGISTRY_UNAVAILABLE", "UI registry contains an invalid installable item path.");
+      }
+      return { ...candidateFile, path: qualified };
+    })
+  };
+}
 function isInstallableItem(item) {
   if (!item || typeof item !== "object")
     return false;
@@ -83630,7 +83725,11 @@ async function readUiRegistryItem(release, expected, fetcher = fetch) {
   return item;
 }
 function isSafeRelative2(value3) {
-  return value3.length > 0 && !value3.startsWith("/") && !/^[A-Za-z]:[\\/]/u.test(value3) && !value3.includes("\\") && !value3.split("/").includes("..");
+  const segments = value3.split("/");
+  return value3.length > 0 && !value3.startsWith("/") && !/^[A-Za-z]:[\\/]/u.test(value3) && !value3.includes("\\") && !/[?#%]/u.test(value3) && ![...value3].some((character) => {
+    const code = character.codePointAt(0) ?? 0;
+    return code <= 31 || code === 127;
+  }) && segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 }
 function registryItemUrl(release, itemName) {
   return RAW + "/" + release.commit + "/registry/public/r/" + encodeURIComponent(itemName) + ".json";
@@ -83656,7 +83755,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 +84113,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 +84129,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 +88202,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 +88362,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 +88487,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 +88617,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.15",
   "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: '' } })
     }
@@ -119,7 +135,14 @@ function mockFetch(): typeof fetch {
       })
     }
     if (url.endsWith('/registry/patterns/chart/registry.json')) {
-      return Response.json({ items: [item] })
+      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'] })

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

@@ -19,7 +19,7 @@ const registry: UiRegistry = {
       description: 'A controlled chart.',
       files: [
         {
-          path: 'registry/patterns/chart/line-basic.tsx',
+          path: 'line-basic.tsx',
           type: 'registry:component',
           target: 'components/astrale/pattern/chart/line-basic.tsx',
         },
@@ -79,6 +79,7 @@ function builtItem(item: UiRegistry['items'][number]) {
     ...item,
     files: item.files.map((file, index) => ({
       ...file,
+      path: `registry/patterns/chart/${file.path}`,
       content: index === 0 ? 'export const Chart = true\n' : 'export const Summary = true\n',
     })),
   }
@@ -114,6 +115,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[] = []
@@ -121,6 +153,7 @@ describe('UI release and runner contracts', () => {
     expect(release.commit).toBe(commit)
     expect(release.compatibility.base).toBe('base')
     expect(release.registry.items).toHaveLength(1)
+    expect(release.registry.items[0]?.files[0]?.path).toBe('registry/patterns/chart/line-basic.tsx')
     expect(seen.filter((url) => new URL(url).hostname === 'raw.githubusercontent.com')).toEqual(
       expect.arrayContaining([
         expect.stringContaining('/' + commit + '/tooling/compatibility.json'),
@@ -162,6 +195,114 @@ describe('UI release and runner contracts', () => {
     expect(seen.some((url) => url.endsWith('/registry/registry.json'))).toBe(false)
   })
 
+  test('rejects noncanonical and encoded registry includes before fetching them', async () => {
+    const unsafeIncludes = [
+      '%2e%2e/other/registry.json',
+      'registry/%2Fother/registry.json',
+      'registry/other/registry.json?raw=1',
+      'registry/other/registry.json#item',
+      'https://example.invalid/registry.json',
+      './registry/other/registry.json',
+    ]
+
+    for (const include of unsafeIncludes) {
+      const seen: string[] = []
+      const fallback = mockFetch(seen)
+      const fetcher = (async (input: string | URL | Request, init?: RequestInit) => {
+        const url = String(input)
+        if (url.endsWith('/' + commit + '/registry.json')) {
+          return Response.json({ include: [include] })
+        }
+        return fallback(input, init)
+      }) as typeof fetch
+
+      await expect(resolveUiRelease('0.3.0-beta.0', fetcher)).rejects.toMatchObject({
+        code: 'UI_REGISTRY_UNAVAILABLE',
+      })
+      expect(seen.some((url) => url.includes('example.invalid') || url.includes('/other/'))).toBe(
+        false,
+      )
+    }
+  })
+
+  test('rejects malformed and already-qualified family-local item paths', async () => {
+    const unsafePaths = [
+      '',
+      '/absolute.tsx',
+      'C:/windows.tsx',
+      './line-basic.tsx',
+      '../line-basic.tsx',
+      '%2e%2e/line-basic.tsx',
+      'registry/patterns/chart/line-basic.tsx',
+    ]
+
+    for (const unsafePath of unsafePaths) {
+      const supplied = structuredClone(registry)
+      supplied.items[0]!.files[0]!.path = unsafePath
+      await expect(resolveUiRelease('0.3.0-beta.0', mockFetch([], supplied))).rejects.toMatchObject(
+        {
+          code: 'UI_REGISTRY_UNAVAILABLE',
+        },
+      )
+    }
+  })
+
+  test('qualifies every item file relative to its declaring nested registry', async () => {
+    const rootItem = {
+      ...structuredClone(registry.items[0]!),
+      name: 'pattern-chart-root',
+      files: [
+        {
+          ...structuredClone(registry.items[0]!.files[0]!),
+          path: 'registry/root.tsx',
+          target: 'components/astrale/pattern/chart/root.tsx',
+        },
+      ],
+      meta: { canonicalAddress: 'pattern/chart/root' },
+    }
+    const chartItem = {
+      ...structuredClone(registry.items[0]!),
+      files: [
+        structuredClone(registry.items[0]!.files[0]!),
+        {
+          ...structuredClone(registry.items[0]!.files[0]!),
+          path: 'parts/legend.tsx',
+          target: 'components/astrale/pattern/chart/parts/legend.tsx',
+        },
+      ],
+    }
+    const nestedItem = {
+      ...structuredClone(registry.items[0]!),
+      name: 'pattern-chart-nested-line',
+      files: [structuredClone(registry.items[0]!.files[0]!)],
+      meta: { canonicalAddress: 'pattern/chart/nested-line' },
+    }
+    const fallback = mockFetch()
+    const fetcher = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = String(input)
+      if (url.endsWith('/' + commit + '/registry.json')) {
+        return Response.json({
+          items: [rootItem],
+          include: ['registry/patterns/chart/registry.json'],
+        })
+      }
+      if (url.endsWith('/registry/patterns/chart/registry.json')) {
+        return Response.json({ items: [chartItem], include: ['nested/registry.json'] })
+      }
+      if (url.endsWith('/registry/patterns/chart/nested/registry.json')) {
+        return Response.json({ items: [nestedItem] })
+      }
+      return fallback(input, init)
+    }) as typeof fetch
+
+    const release = await resolveUiRelease('0.3.0-beta.0', fetcher)
+    expect(release.registry.items.map((item) => item.files.map((file) => file.path))).toEqual([
+      ['registry/root.tsx'],
+      ['registry/patterns/chart/line-basic.tsx', 'registry/patterns/chart/parts/legend.tsx'],
+      ['registry/patterns/chart/nested/line-basic.tsx'],
+    ])
+  })
+
   /** @evidence TEST-CLI-UI-BOUNDED-REMOTE-DOCUMENTS */
   test('bounds and normalizes malformed registry responses', async () => {
     const fallback = mockFetch()
@@ -211,6 +352,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')
@@ -445,7 +647,7 @@ describe('UI source operations', () => {
           files: [
             registry.items[0]!.files[0]!,
             {
-              path: 'registry/patterns/chart/summary.tsx',
+              path: 'summary.tsx',
               type: 'registry:component',
               target: 'components/astrale/pattern/chart/summary.tsx',
             },

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 }
@@ -149,7 +152,12 @@ async function resolveRegistryItems(
   fetcher: Fetch,
   visited: Set<string>,
 ): Promise<unknown[]> {
-  const direct = Array.isArray(source.items) ? source.items : []
+  const releaseRoot = RAW + '/' + commit + '/'
+  const sourceRelative = sourceUrl.slice(releaseRoot.length)
+  const sourceDirectory = sourceRelative.slice(0, Math.max(0, sourceRelative.lastIndexOf('/')))
+  const direct = Array.isArray(source.items)
+    ? source.items.map((item) => qualifyRegistryItemPaths(item, sourceDirectory))
+    : []
   const includes = source.include ?? []
   if (!Array.isArray(includes)) {
     throw new UiError('UI_REGISTRY_UNAVAILABLE', 'UI registry include must be an array.')
@@ -164,15 +172,21 @@ async function resolveRegistryItems(
     includes.map(async (include) => {
       if (
         typeof include !== 'string' ||
-        include.startsWith('/') ||
+        !isSafeRelative(include) ||
+        !/^[A-Za-z0-9._/-]+$/u.test(include) ||
         !include.endsWith('registry.json') ||
-        include.split('/').includes('..')
+        include === 'registry.json'
       ) {
         throw new UiError('UI_REGISTRY_UNAVAILABLE', 'UI registry contains an unsafe include.')
       }
+      const sourceDirectoryUrl = sourceUrl.slice(0, sourceUrl.lastIndexOf('/') + 1)
       const url = new URL(include, sourceUrl).toString()
-      const releaseRoot = RAW + '/' + commit + '/'
-      if (!url.startsWith(releaseRoot) || visited.has(url)) {
+      if (
+        url !== sourceDirectoryUrl + include ||
+        !url.startsWith(releaseRoot) ||
+        !url.startsWith(sourceDirectoryUrl) ||
+        visited.has(url)
+      ) {
         throw new UiError(
           'UI_REGISTRY_UNAVAILABLE',
           'UI registry include escaped or repeated the release snapshot.',
@@ -186,6 +200,40 @@ async function resolveRegistryItems(
   return direct.concat(nested.flat())
 }
 
+function qualifyRegistryItemPaths(item: unknown, sourceDirectory: string): unknown {
+  if (!item || typeof item !== 'object') return item
+  const candidate = item as { files?: unknown }
+  if (!Array.isArray(candidate.files)) return item
+  return {
+    ...candidate,
+    files: candidate.files.map((file) => {
+      if (!file || typeof file !== 'object') return file
+      const candidateFile = file as { path?: unknown }
+      if (typeof candidateFile.path !== 'string') return file
+      if (
+        !isSafeRelative(candidateFile.path) ||
+        (sourceDirectory !== '' &&
+          (candidateFile.path === sourceDirectory ||
+            candidateFile.path.startsWith(sourceDirectory + '/')))
+      ) {
+        throw new UiError(
+          'UI_REGISTRY_UNAVAILABLE',
+          'UI registry contains an invalid installable item path.',
+        )
+      }
+      if (sourceDirectory === '') return file
+      const qualified = sourceDirectory + '/' + candidateFile.path
+      if (!isSafeRelative(qualified)) {
+        throw new UiError(
+          'UI_REGISTRY_UNAVAILABLE',
+          'UI registry contains an invalid installable item path.',
+        )
+      }
+      return { ...candidateFile, path: qualified }
+    }),
+  }
+}
+
 function isInstallableItem(item: unknown): item is UiRegistry['items'][number] {
   if (!item || typeof item !== 'object') return false
   const candidate = item as Partial<UiRegistry['items'][number]>
@@ -253,12 +301,18 @@ export async function readUiRegistryItem(
 }
 
 function isSafeRelative(value: string): boolean {
+  const segments = value.split('/')
   return (
     value.length > 0 &&
     !value.startsWith('/') &&
     !/^[A-Za-z]:[\\/]/u.test(value) &&
     !value.includes('\\') &&
-    !value.split('/').includes('..')
+    !/[?#%]/u.test(value) &&
+    ![...value].some((character) => {
+      const code = character.codePointAt(0) ?? 0
+      return code <= 31 || code === 127
+    }) &&
+    segments.every((segment) => segment.length > 0 && segment !== '.' && segment !== '..')
   )
 }