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

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.15",
+    version: "1.0.0-beta.17",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -83525,7 +83525,8 @@ async function discoverUiProject(input = process.cwd()) {
     lockPath,
     cssPath: path5.join(root, cssRelative),
     componentsPath,
-    uiLockPath: path5.join(root, "astrale-ui.lock.json")
+    uiLockPath: path5.join(root, "astrale-ui.lock.json"),
+    isAstraleDomain: await exists(path5.join(root, "astrale.config.ts")) && await exists(path5.join(root, "ui/index.ts")) && await exists(path5.join(root, "frontend/package.json"))
   };
 }
 function assertSupportedUiProject(project2) {
@@ -83768,6 +83769,108 @@ async function readOptional(target2) {
 function manifestDependencies(manifest) {
   return { ...manifest.dependencies };
 }
+function domainRegistryPackagePath(project2) {
+  return path6.join(project2.root, "components/package.json");
+}
+function pnpmWorkspacePath(project2) {
+  return path6.join(project2.root, "pnpm-workspace.yaml");
+}
+function domainRegistryPackageName(manifest) {
+  const name = typeof manifest.name === "string" ? manifest.name : "astrale-domain";
+  return name + "-ui-registry";
+}
+function appendWorkspace(manifest, workspace) {
+  const configured = manifest.workspaces;
+  if (configured === undefined) {
+    manifest.workspaces = [workspace];
+    return;
+  }
+  if (Array.isArray(configured) && configured.every((value3) => typeof value3 === "string")) {
+    if (!configured.includes(workspace))
+      manifest.workspaces = [...configured, workspace];
+    return;
+  }
+  if (configured && typeof configured === "object") {
+    const candidate2 = configured;
+    if (Array.isArray(candidate2.packages) && candidate2.packages.every((value3) => typeof value3 === "string")) {
+      if (!candidate2.packages.includes(workspace)) {
+        manifest.workspaces = { ...candidate2, packages: [...candidate2.packages, workspace] };
+      }
+      return;
+    }
+  }
+  throw new UiError("UI_PROJECT_UNSUPPORTED", "package.json has an invalid workspaces field.");
+}
+async function appendPnpmWorkspace(project2, workspace) {
+  const target2 = pnpmWorkspacePath(project2);
+  const source2 = await readOptional(target2);
+  if (source2 === undefined) {
+    await writeFile6(target2, `packages:
+  - '` + workspace + `'
+`, "utf8");
+    return;
+  }
+  const document = $parseDocument(source2);
+  if (document.errors.length > 0) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "pnpm-workspace.yaml is not valid YAML.");
+  }
+  const packages = document.get("packages", true);
+  if (!$isSeq(packages)) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "pnpm-workspace.yaml must declare a packages sequence.");
+  }
+  const values = packages.toJSON();
+  if (!Array.isArray(values) || !values.every((value3) => typeof value3 === "string")) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "pnpm-workspace.yaml must declare a packages sequence.");
+  }
+  if (!values.includes(workspace))
+    packages.add(workspace);
+  await writeFile6(target2, String(document), "utf8");
+}
+async function hasDomainRegistryWorkspace(project2) {
+  if (!project2.isAstraleDomain || !await exists2(domainRegistryPackagePath(project2)))
+    return false;
+  const registryManifest = JSON.parse(await readFile18(domainRegistryPackagePath(project2), "utf8"));
+  if (registryManifest.private !== true || typeof registryManifest.name !== "string" || registryManifest.name === UI_PACKAGE || registryManifest.name === project2.packageJson.name) {
+    return false;
+  }
+  if (project2.manager === "pnpm") {
+    const source2 = await readOptional(pnpmWorkspacePath(project2));
+    if (source2 === undefined)
+      return false;
+    const document = $parseDocument(source2);
+    if (document.errors.length > 0)
+      return false;
+    const packages = document.get("packages", true);
+    const values = $isSeq(packages) ? packages.toJSON() : undefined;
+    return Array.isArray(values) && values.includes("components");
+  }
+  const configured = project2.packageJson.workspaces;
+  const workspaces = Array.isArray(configured) ? configured : configured && typeof configured === "object" ? configured.packages : undefined;
+  return Array.isArray(workspaces) && workspaces.includes("components");
+}
+async function writeDomainRegistryWorkspace(project2, manifest) {
+  if (!project2.isAstraleDomain)
+    return;
+  if (project2.manager === "pnpm")
+    await appendPnpmWorkspace(project2, "components");
+  else
+    appendWorkspace(manifest, "components");
+  const target2 = domainRegistryPackagePath(project2);
+  const existing = await readOptional(target2);
+  const registryManifest = existing ? JSON.parse(existing) : { name: domainRegistryPackageName(manifest) };
+  if (registryManifest.private === false) {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "The Astrale registry source workspace must remain private.");
+  }
+  if (registryManifest.name === UI_PACKAGE || registryManifest.name === manifest.name || registryManifest.name !== undefined && typeof registryManifest.name !== "string") {
+    throw new UiError("UI_PROJECT_UNSUPPORTED", "The Astrale registry source workspace must have a distinct package name.");
+  }
+  await writeJson(target2, {
+    ...registryManifest,
+    name: registryManifest.name ?? domainRegistryPackageName(manifest),
+    private: true,
+    type: registryManifest.type ?? "module"
+  });
+}
 async function initUi(options, dependencies = {}) {
   const project2 = await discoverUiProject(options.path);
   assertSupportedUiProject(project2);
@@ -83782,7 +83885,7 @@ async function initUi(options, dependencies = {}) {
       return;
     });
     const requestedVersion = options.version?.replace(/^v/u, "");
-    const desired = (!requestedVersion || requestedVersion === lock.package.version) && (!options.preset || options.preset === lock.preset) && css.includes(UI_PACKAGE + "/theme.css") && css.includes(UI_PACKAGE + "/presets/" + lock.preset + ".css") && components?.style === "base-nova";
+    const desired = (!requestedVersion || requestedVersion === lock.package.version) && (!options.preset || options.preset === lock.preset) && css.includes(UI_PACKAGE + "/theme.css") && css.includes(UI_PACKAGE + "/presets/" + lock.preset + ".css") && components?.style === "base-nova" && (!project2.isAstraleDomain || await hasDomainRegistryWorkspace(project2));
     if (!desired) {
       throw new UiError("UI_ITEM_CONFLICT", "Existing Astrale UI initialization differs from the requested state.", "Run astrale ui doctor, then repeat init with --force after reviewing the changes.");
     }
@@ -83801,6 +83904,8 @@ async function initUi(options, dependencies = {}) {
       cssRelative,
       "components.json",
       "astrale-ui.lock.json",
+      ...project2.isAstraleDomain ? ["components/package.json"] : [],
+      ...project2.isAstraleDomain && project2.manager === "pnpm" ? ["pnpm-workspace.yaml"] : [],
       ...project2.lockPath ? [projectRelative(project2, project2.lockPath)] : []
     ],
     tooling: {
@@ -83812,11 +83917,19 @@ async function initUi(options, dependencies = {}) {
   };
   if (options.dryRun)
     return plan;
+  if (project2.isAstraleDomain) {
+    await assertSafePlannedTarget(project2, "components/package.json");
+    if (project2.manager === "pnpm") {
+      await assertSafePlannedTarget(project2, "pnpm-workspace.yaml");
+    }
+  }
   const mutationPaths = [
     project2.packageJsonPath,
     project2.cssPath,
     project2.componentsPath,
     project2.uiLockPath,
+    ...project2.isAstraleDomain ? [domainRegistryPackagePath(project2)] : [],
+    ...project2.isAstraleDomain && project2.manager === "pnpm" ? [pnpmWorkspacePath(project2)] : [],
     ...project2.lockPath ? [project2.lockPath] : []
   ];
   const snapshots = new Map;
@@ -83828,6 +83941,7 @@ async function initUi(options, dependencies = {}) {
       ...manifestDependencies(manifest),
       [UI_PACKAGE]: release.version
     };
+    await writeDomainRegistryWorkspace(project2, manifest);
     await writeJson(project2.packageJsonPath, manifest);
     const currentCss = await readOptional(project2.cssPath) ?? "";
     const imports = [
@@ -83900,6 +84014,17 @@ async function initUi(options, dependencies = {}) {
     throw error52;
   }
 }
+async function pinUiDependency(project2, version2, runner) {
+  const manifest = JSON.parse(await readFile18(project2.packageJsonPath, "utf8"));
+  if (manifestDependencies(manifest)[UI_PACKAGE] === version2)
+    return;
+  manifest.dependencies = { ...manifestDependencies(manifest), [UI_PACKAGE]: version2 };
+  await writeJson(project2.packageJsonPath, manifest);
+  const result = await runner(project2.manager, ["install"], project2.root);
+  if (result.code !== 0) {
+    throw new UiError("UI_DEPENDENCY_INSTALL_FAILED", project2.manager + " install failed while restoring the locked UI release.", result.stderr.trim() || undefined);
+  }
+}
 async function listUi(query4, options, dependencies = {}) {
   const release = await resolveUiRelease(options.version, dependencies.fetcher);
   const needle = query4?.trim().toLowerCase();
@@ -83965,6 +84090,7 @@ async function addUi(addresses, options, dependencies = {}) {
           throw new UiError("UI_TOOL_FAILED", "The pinned shadcn operation omitted an item file.");
         }
       }
+      await pinUiDependency(project2, lock.package.version, dependencies.runner ?? defaultUiRunner);
     }
   } catch (error52) {
     for (const [target2, previous] of snapshots) {
@@ -84148,6 +84274,7 @@ async function writeJson(target2, value3) {
 `, "utf8");
 }
 var init_operations3 = __esm(() => {
+  init_dist();
   init_lock();
   init_model7();
   init_project3();
@@ -84281,7 +84408,7 @@ var init_add = __esm(() => {
     ],
     afterHelpText: `
 Installed source belongs to the application. Ordinary add never overwrites local edits.
-Use diff first, then --overwrite --yes when replacement is intentional.
+Run astrale ui doctor before intentionally replacing local source with --overwrite --yes.
 `,
     action: async (items, options) => runUiCommand(options, async () => {
       let selected2 = items;

package/package.json

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

package/src/commands/ui/add.ts

@@ -25,7 +25,7 @@ export default {
     UI_JSON_OPTION,
   ],
   afterHelpText:
-    '\nInstalled source belongs to the application. Ordinary add never overwrites local edits.\nUse diff first, then --overwrite --yes when replacement is intentional.\n',
+    '\nInstalled source belongs to the application. Ordinary add never overwrites local edits.\nRun astrale ui doctor before intentionally replacing local source with --overwrite --yes.\n',
   action: async (items: string[], options: Options) =>
     runUiCommand(options, async () => {
       let selected = items

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

@@ -312,6 +312,24 @@ describe('help contract — connect-only command surface', () => {
 })
 
 describe('help contract — UI is project tooling', () => {
+  test('add recovery guidance uses only registered UI commands', async () => {
+    const program = await buildProgram()
+    const uiAdd = program.commands
+      .find((command) => command.name() === 'ui')
+      ?.commands.find((command) => command.name() === 'add')
+    let help = ''
+    uiAdd?.configureOutput({
+      writeOut: (chunk) => {
+        help += chunk ?? ''
+      },
+    })
+    uiAdd?.outputHelp()
+
+    expect(help).toContain('astrale ui doctor')
+    expect(help).toContain('--overwrite --yes')
+    expect(help).not.toMatch(/\b(?:astrale ui )?diff\b/u)
+  })
+
   test('keeps the documented root version alias operational', async () => {
     const program = await buildProgram()
     let stdout = ''

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

@@ -94,7 +94,11 @@ async function fixture(): Promise<string> {
     JSON.stringify({
       name: 'fixture',
       private: true,
-      dependencies: { react: '19.2.8', 'react-dom': '19.2.8', tailwindcss: '4.3.3' },
+      dependencies: {
+        react: '19.2.8',
+        'react-dom': '19.2.8',
+        tailwindcss: '4.3.3',
+      },
       packageManager: 'pnpm@11.13.1',
     }),
   )
@@ -102,6 +106,16 @@ async function fixture(): Promise<string> {
   return root
 }
 
+async function lockedFixture(): Promise<string> {
+  const root = await fixture()
+  const manifestPath = path.join(root, 'package.json')
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+  manifest.dependencies['@astrale-os/ui'] = '0.3.0-beta.0'
+  await writeFile(manifestPath, JSON.stringify(manifest))
+  await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+  return root
+}
+
 function lock(): UiLock {
   return {
     $schema: 'https://example.invalid/ui-lock.schema.json',
@@ -360,6 +374,10 @@ describe('UI initialization transaction', () => {
       JSON.stringify({ name: 'astrale-frontend', private: true, type: 'module' }),
     )
     await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    await writeFile(path.join(root, 'pnpm-workspace.yaml'), "packages:\n  - 'frontend'\n")
     const rootCssBefore = await readFile(path.join(root, 'src/index.css'), 'utf8')
 
     await initUi(
@@ -375,8 +393,14 @@ describe('UI initialization transaction', () => {
     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')
+    ).toHaveProperty('@astrale-os/ui', '0.3.0-beta.0')
     expect(await Bun.file(path.join(root, 'src/astrale-ui.css')).exists()).toBe(false)
+    expect(JSON.parse(await readFile(path.join(root, 'components/package.json'), 'utf8'))).toEqual({
+      name: 'fixture-ui-registry',
+      private: true,
+      type: 'module',
+    })
+    expect(await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')).toContain('components')
 
     await writeFile(path.join(root, 'src/app.css'), '/* later root stylesheet */\n')
     const repeated = await initUi(
@@ -386,6 +410,153 @@ describe('UI initialization transaction', () => {
     expect(repeated.status).toBe('unchanged')
   })
 
+  test('adds the private registry workspace to an npm-authored Domain manifest', async () => {
+    const root = await fixture()
+    const manifestPath = path.join(root, 'package.json')
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+    manifest.packageManager = 'npm@11.16.0'
+    manifest.workspaces = ['frontend']
+    await writeFile(manifestPath, JSON.stringify(manifest))
+    await writeFile(path.join(root, 'package-lock.json'), '{}')
+    await mkdir(path.join(root, 'frontend/src'), { recursive: true })
+    await writeFile(
+      path.join(root, 'frontend/package.json'),
+      JSON.stringify({ name: 'astrale-frontend', private: true }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+
+    const result = await initUi(
+      { path: root, version: '0.3.0-beta.0', install: false },
+      { fetcher: mockFetch() },
+    )
+
+    expect(result.files).toEqual(expect.arrayContaining(['components/package.json']))
+    expect(JSON.parse(await readFile(manifestPath, 'utf8')).workspaces).toEqual([
+      'frontend',
+      'components',
+    ])
+    expect(JSON.parse(await readFile(path.join(root, 'components/package.json'), 'utf8'))).toEqual({
+      name: 'fixture-ui-registry',
+      private: true,
+      type: 'module',
+    })
+  })
+
+  test('rejects a Domain registry workspace whose physical parent escapes the project', async () => {
+    const root = await fixture()
+    const outside = 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 }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    await symlink(outside, path.join(root, 'components'), 'dir')
+    const outsideManifest = await readFile(path.join(outside, 'package.json'), 'utf8')
+    const rootManifest = await readFile(path.join(root, 'package.json'), 'utf8')
+
+    await expect(
+      initUi({ path: root, version: '0.3.0-beta.0', install: false }, { fetcher: mockFetch() }),
+    ).rejects.toMatchObject({ code: 'UI_LOCK_INVALID' })
+    expect(await readFile(path.join(outside, 'package.json'), 'utf8')).toBe(outsideManifest)
+    expect(await readFile(path.join(root, 'package.json'), 'utf8')).toBe(rootManifest)
+    expect(await Bun.file(path.join(root, 'astrale-ui.lock.json')).exists()).toBe(false)
+  })
+
+  test('rejects a symlinked pnpm workspace manifest before any Domain mutation', async () => {
+    const root = await fixture()
+    const outside = 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 }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    const outsideWorkspace = path.join(outside, 'workspace.yaml')
+    await writeFile(outsideWorkspace, "packages:\n  - 'outside'\n")
+    await symlink(outsideWorkspace, path.join(root, 'pnpm-workspace.yaml'), 'file')
+    const outsideBefore = await readFile(outsideWorkspace, 'utf8')
+
+    await expect(
+      initUi({ path: root, version: '0.3.0-beta.0', install: false }, { fetcher: mockFetch() }),
+    ).rejects.toMatchObject({ code: 'UI_LOCK_INVALID' })
+    expect(await readFile(outsideWorkspace, 'utf8')).toBe(outsideBefore)
+    expect(await Bun.file(path.join(root, 'components/package.json')).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'astrale-ui.lock.json')).exists()).toBe(false)
+  })
+
+  test('restores every Domain workspace mutation when dependency installation fails', 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 }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    await writeFile(path.join(root, 'pnpm-workspace.yaml'), "packages:\n  - 'frontend'\n")
+    const manifestBefore = await readFile(path.join(root, 'package.json'), 'utf8')
+    const cssBefore = await readFile(path.join(root, 'frontend/src/styles.css'), 'utf8')
+    const workspaceBefore = await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')
+
+    await expect(
+      initUi(
+        { path: root, version: '0.3.0-beta.0' },
+        {
+          fetcher: mockFetch(),
+          runner: async () => ({ code: 1, stdout: '', stderr: 'install failed' }),
+        },
+      ),
+    ).rejects.toMatchObject({ code: 'UI_DEPENDENCY_INSTALL_FAILED' })
+
+    expect(await readFile(path.join(root, 'package.json'), 'utf8')).toBe(manifestBefore)
+    expect(await readFile(path.join(root, 'frontend/src/styles.css'), 'utf8')).toBe(cssBefore)
+    expect(await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')).toBe(workspaceBefore)
+    expect(await Bun.file(path.join(root, 'components/package.json')).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'components.json')).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'astrale-ui.lock.json')).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'pnpm-lock.yaml')).exists()).toBe(false)
+  })
+
+  test('rejects a registry workspace that could shadow the public UI package', 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 }),
+    )
+    await writeFile(path.join(root, 'frontend/src/styles.css'), '/* Domain frontend */\n')
+    await mkdir(path.join(root, 'ui'), { recursive: true })
+    await writeFile(path.join(root, 'ui/index.ts'), 'export {}\n')
+    await writeFile(path.join(root, 'astrale.config.ts'), 'export default {}\n')
+    await writeFile(path.join(root, 'pnpm-workspace.yaml'), "packages:\n  - 'frontend'\n")
+    await mkdir(path.join(root, 'components'), { recursive: true })
+    await writeFile(
+      path.join(root, 'components/package.json'),
+      JSON.stringify({ name: '@astrale-os/ui', private: true, version: '0.3.0-beta.0' }),
+    )
+    const workspaceBefore = await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')
+
+    await expect(
+      initUi({ path: root, version: '0.3.0-beta.0', install: false }, { fetcher: mockFetch() }),
+    ).rejects.toMatchObject({ code: 'UI_PROJECT_UNSUPPORTED' })
+    expect(await readFile(path.join(root, 'pnpm-workspace.yaml'), 'utf8')).toBe(workspaceBefore)
+    expect(
+      JSON.parse(await readFile(path.join(root, 'components/package.json'), 'utf8')).name,
+    ).toBe('@astrale-os/ui')
+  })
+
   test('rejects configured and discovered stylesheets whose physical parent escapes', async () => {
     const root = await fixture()
     const outside = await fixture()
@@ -526,8 +697,7 @@ describe('UI source operations', () => {
   })
 
   test('add dry-run invokes the exact shadcn version and does not advance the lock', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     const before = await readFile(path.join(root, 'astrale-ui.lock.json'), 'utf8')
     const calls: Array<{ file: string; args: string[] }> = []
     const result = await addUi(
@@ -555,8 +725,7 @@ describe('UI source operations', () => {
   })
 
   test('successful add records installed file digests and doctor detects later edits', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     await writeFile(
       path.join(root, 'components.json'),
       JSON.stringify({ style: 'base-nova', tailwind: { css: 'src/index.css' } }),
@@ -609,9 +778,80 @@ describe('UI source operations', () => {
     ).rejects.toBeInstanceOf(UiError)
   })
 
+  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')
+    const calls: Array<{ file: string; args: string[] }> = []
+
+    await addUi(
+      ['pattern/chart/line/basic'],
+      { project: root, yes: true },
+      {
+        fetcher: mockFetch(),
+        runner: async (file, args) => {
+          calls.push({ file, args })
+          if (args[0] === 'dlx') {
+            await mkdir(path.dirname(installed), { recursive: true })
+            await writeFile(installed, 'export const Chart = true\n')
+            const manifestPath = path.join(root, 'package.json')
+            const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+            manifest.dependencies['@astrale-os/ui'] = '^0.3.0-beta.0'
+            await writeFile(manifestPath, JSON.stringify(manifest))
+          }
+          return { code: 0, stdout: '', stderr: '' }
+        },
+      },
+    )
+
+    expect(calls).toEqual([
+      expect.objectContaining({ file: 'pnpm', args: expect.arrayContaining(['dlx']) }),
+      { file: 'pnpm', args: ['install'] },
+    ])
+    expect(
+      JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8')).dependencies[
+        '@astrale-os/ui'
+      ],
+    ).toBe('0.3.0-beta.0')
+  })
+
+  test('rolls back item and package state when restoring the locked dependency fails', async () => {
+    const root = await lockedFixture()
+    const manifestPath = path.join(root, 'package.json')
+    const lockPath = path.join(root, 'astrale-ui.lock.json')
+    const installed = path.join(root, 'components/astrale/pattern/chart/line-basic.tsx')
+    const manifestBefore = await readFile(manifestPath, 'utf8')
+    const lockBefore = await readFile(lockPath, 'utf8')
+
+    await expect(
+      addUi(
+        ['pattern/chart/line/basic'],
+        { project: root, yes: true },
+        {
+          fetcher: mockFetch(),
+          runner: async (_file, args) => {
+            if (args[0] === 'dlx') {
+              await mkdir(path.dirname(installed), { recursive: true })
+              await writeFile(installed, 'export const Chart = true\n')
+              const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+              manifest.dependencies['@astrale-os/ui'] = '^0.3.0-beta.0'
+              await writeFile(manifestPath, JSON.stringify(manifest))
+              return { code: 0, stdout: '', stderr: '' }
+            }
+            await writeFile(path.join(root, 'pnpm-lock.yaml'), 'partial lock\n')
+            return { code: 1, stdout: '', stderr: 'registry timeout' }
+          },
+        },
+      ),
+    ).rejects.toMatchObject({ code: 'UI_DEPENDENCY_INSTALL_FAILED' })
+
+    expect(await readFile(manifestPath, 'utf8')).toBe(manifestBefore)
+    expect(await readFile(lockPath, 'utf8')).toBe(lockBefore)
+    expect(await Bun.file(installed).exists()).toBe(false)
+    expect(await Bun.file(path.join(root, 'pnpm-lock.yaml')).exists()).toBe(false)
+  })
+
   test('preflights symlink targets without invoking shadcn', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     const outside = await mkdtemp(path.join(tmpdir(), 'astrale-ui-outside-'))
     temporary.push(outside)
     await symlink(outside, path.join(root, 'components'))
@@ -633,8 +873,7 @@ describe('UI source operations', () => {
   })
 
   test('restores declared files and package state after a partial shadcn failure', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    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 mkdir(path.dirname(first), { recursive: true })
@@ -676,8 +915,7 @@ describe('UI source operations', () => {
   })
 
   test('overwrite requires explicit yes confirmation before invoking shadcn', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     let invoked = false
     await expect(
       addUi(
@@ -697,8 +935,7 @@ describe('UI source operations', () => {
 
   /** @evidence TEST-CLI-UI-EXACT-ITEM-SOURCE */
   test('rejects a built item that differs from the admitted release index before invoking shadcn', async () => {
-    const root = await fixture()
-    await writeFile(path.join(root, 'astrale-ui.lock.json'), JSON.stringify(lock()))
+    const root = await lockedFixture()
     const fallback = mockFetch()
     let invoked = false
     const malformed = (async (input: string | URL | Request, init?: RequestInit) => {

package/src/ui/operations.ts

@@ -1,5 +1,6 @@
 import { access, lstat, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
+import { isSeq, parseDocument } from 'yaml'
 
 import { digest, parseUiLock, readUiLock } from './lock'
 import {
@@ -42,6 +43,140 @@ function manifestDependencies(manifest: Record<string, unknown>): Record<string,
   return { ...(manifest.dependencies as Record<string, string> | undefined) }
 }
 
+function domainRegistryPackagePath(project: UiProject): string {
+  return path.join(project.root, 'components/package.json')
+}
+
+function pnpmWorkspacePath(project: UiProject): string {
+  return path.join(project.root, 'pnpm-workspace.yaml')
+}
+
+function domainRegistryPackageName(manifest: Record<string, unknown>): string {
+  const name = typeof manifest.name === 'string' ? manifest.name : 'astrale-domain'
+  return name + '-ui-registry'
+}
+
+function appendWorkspace(manifest: Record<string, unknown>, workspace: string): void {
+  const configured = manifest.workspaces
+  if (configured === undefined) {
+    manifest.workspaces = [workspace]
+    return
+  }
+  if (Array.isArray(configured) && configured.every((value) => typeof value === 'string')) {
+    if (!configured.includes(workspace)) manifest.workspaces = [...configured, workspace]
+    return
+  }
+  if (configured && typeof configured === 'object') {
+    const candidate = configured as { packages?: unknown }
+    if (
+      Array.isArray(candidate.packages) &&
+      candidate.packages.every((value) => typeof value === 'string')
+    ) {
+      if (!candidate.packages.includes(workspace)) {
+        manifest.workspaces = { ...candidate, packages: [...candidate.packages, workspace] }
+      }
+      return
+    }
+  }
+  throw new UiError('UI_PROJECT_UNSUPPORTED', 'package.json has an invalid workspaces field.')
+}
+
+async function appendPnpmWorkspace(project: UiProject, workspace: string): Promise<void> {
+  const target = pnpmWorkspacePath(project)
+  const source = await readOptional(target)
+  if (source === undefined) {
+    await writeFile(target, "packages:\n  - '" + workspace + "'\n", 'utf8')
+    return
+  }
+  const document = parseDocument(source)
+  if (document.errors.length > 0) {
+    throw new UiError('UI_PROJECT_UNSUPPORTED', 'pnpm-workspace.yaml is not valid YAML.')
+  }
+  const packages = document.get('packages', true)
+  if (!isSeq(packages)) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'pnpm-workspace.yaml must declare a packages sequence.',
+    )
+  }
+  const values = packages.toJSON()
+  if (!Array.isArray(values) || !values.every((value) => typeof value === 'string')) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'pnpm-workspace.yaml must declare a packages sequence.',
+    )
+  }
+  if (!values.includes(workspace)) packages.add(workspace)
+  await writeFile(target, String(document), 'utf8')
+}
+
+async function hasDomainRegistryWorkspace(project: UiProject): Promise<boolean> {
+  if (!project.isAstraleDomain || !(await exists(domainRegistryPackagePath(project)))) return false
+  const registryManifest = JSON.parse(
+    await readFile(domainRegistryPackagePath(project), 'utf8'),
+  ) as Record<string, unknown>
+  if (
+    registryManifest.private !== true ||
+    typeof registryManifest.name !== 'string' ||
+    registryManifest.name === UI_PACKAGE ||
+    registryManifest.name === project.packageJson.name
+  ) {
+    return false
+  }
+  if (project.manager === 'pnpm') {
+    const source = await readOptional(pnpmWorkspacePath(project))
+    if (source === undefined) return false
+    const document = parseDocument(source)
+    if (document.errors.length > 0) return false
+    const packages = document.get('packages', true)
+    const values = isSeq(packages) ? packages.toJSON() : undefined
+    return Array.isArray(values) && values.includes('components')
+  }
+  const configured = project.packageJson.workspaces
+  const workspaces = Array.isArray(configured)
+    ? configured
+    : configured && typeof configured === 'object'
+      ? (configured as { packages?: unknown }).packages
+      : undefined
+  return Array.isArray(workspaces) && workspaces.includes('components')
+}
+
+async function writeDomainRegistryWorkspace(
+  project: UiProject,
+  manifest: Record<string, unknown>,
+): Promise<void> {
+  if (!project.isAstraleDomain) return
+  if (project.manager === 'pnpm') await appendPnpmWorkspace(project, 'components')
+  else appendWorkspace(manifest, 'components')
+  const target = domainRegistryPackagePath(project)
+  const existing = await readOptional(target)
+  const registryManifest = existing
+    ? (JSON.parse(existing) as Record<string, unknown>)
+    : { name: domainRegistryPackageName(manifest) }
+  if (registryManifest.private === false) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'The Astrale registry source workspace must remain private.',
+    )
+  }
+  if (
+    registryManifest.name === UI_PACKAGE ||
+    registryManifest.name === manifest.name ||
+    (registryManifest.name !== undefined && typeof registryManifest.name !== 'string')
+  ) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'The Astrale registry source workspace must have a distinct package name.',
+    )
+  }
+  await writeJson(target, {
+    ...registryManifest,
+    name: registryManifest.name ?? domainRegistryPackageName(manifest),
+    private: true,
+    type: registryManifest.type ?? 'module',
+  })
+}
+
 export type InitUiOptions = {
   path?: string
   preset?: UiPreset
@@ -73,7 +208,8 @@ export async function initUi(
       (!options.preset || options.preset === lock.preset) &&
       css.includes(UI_PACKAGE + '/theme.css') &&
       css.includes(UI_PACKAGE + '/presets/' + lock.preset + '.css') &&
-      components?.style === 'base-nova'
+      components?.style === 'base-nova' &&
+      (!project.isAstraleDomain || (await hasDomainRegistryWorkspace(project)))
     if (!desired) {
       throw new UiError(
         'UI_ITEM_CONFLICT',
@@ -96,6 +232,8 @@ export async function initUi(
       cssRelative,
       'components.json',
       'astrale-ui.lock.json',
+      ...(project.isAstraleDomain ? ['components/package.json'] : []),
+      ...(project.isAstraleDomain && project.manager === 'pnpm' ? ['pnpm-workspace.yaml'] : []),
       ...(project.lockPath ? [projectRelative(project, project.lockPath)] : []),
     ],
     tooling: {
@@ -107,11 +245,20 @@ export async function initUi(
   }
   if (options.dryRun) return plan
 
+  if (project.isAstraleDomain) {
+    await assertSafePlannedTarget(project, 'components/package.json')
+    if (project.manager === 'pnpm') {
+      await assertSafePlannedTarget(project, 'pnpm-workspace.yaml')
+    }
+  }
+
   const mutationPaths = [
     project.packageJsonPath,
     project.cssPath,
     project.componentsPath,
     project.uiLockPath,
+    ...(project.isAstraleDomain ? [domainRegistryPackagePath(project)] : []),
+    ...(project.isAstraleDomain && project.manager === 'pnpm' ? [pnpmWorkspacePath(project)] : []),
     ...(project.lockPath ? [project.lockPath] : []),
   ]
   const snapshots = new Map<string, string | undefined>()
@@ -123,6 +270,7 @@ export async function initUi(
       ...manifestDependencies(manifest),
       [UI_PACKAGE]: release.version,
     }
+    await writeDomainRegistryWorkspace(project, manifest)
     await writeJson(project.packageJsonPath, manifest)
 
     const currentCss = (await readOptional(project.cssPath)) ?? ''
@@ -214,6 +362,28 @@ export async function initUi(
   }
 }
 
+async function pinUiDependency(
+  project: UiProject,
+  version: string,
+  runner: UiRunner,
+): Promise<void> {
+  const manifest = JSON.parse(await readFile(project.packageJsonPath, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  if (manifestDependencies(manifest)[UI_PACKAGE] === version) return
+  manifest.dependencies = { ...manifestDependencies(manifest), [UI_PACKAGE]: version }
+  await writeJson(project.packageJsonPath, manifest)
+  const result = await runner(project.manager, ['install'], project.root)
+  if (result.code !== 0) {
+    throw new UiError(
+      'UI_DEPENDENCY_INSTALL_FAILED',
+      project.manager + ' install failed while restoring the locked UI release.',
+      result.stderr.trim() || undefined,
+    )
+  }
+}
+
 export async function listUi(
   query: string | undefined,
   options: { type?: string; limit?: number; version?: string },
@@ -323,6 +493,7 @@ export async function addUi(
           throw new UiError('UI_TOOL_FAILED', 'The pinned shadcn operation omitted an item file.')
         }
       }
+      await pinUiDependency(project, lock.package.version, dependencies.runner ?? defaultUiRunner)
     }
   } catch (error) {
     for (const [target, previous] of snapshots) {

package/src/ui/project.ts

@@ -12,6 +12,7 @@ export type UiProject = {
   cssPath: string
   componentsPath: string
   uiLockPath: string
+  isAstraleDomain: boolean
 }
 
 const MANAGERS: readonly [string, PackageManager][] = [
@@ -173,6 +174,10 @@ export async function discoverUiProject(input = process.cwd()): Promise<UiProjec
     cssPath: path.join(root, cssRelative),
     componentsPath,
     uiLockPath: path.join(root, 'astrale-ui.lock.json'),
+    isAstraleDomain:
+      (await exists(path.join(root, 'astrale.config.ts'))) &&
+      (await exists(path.join(root, 'ui/index.ts'))) &&
+      (await exists(path.join(root, 'frontend/package.json'))),
   }
 }