refactor(cli): address review feedback on bundled workspace packaging

- Add JSDoc to bundledWorkspacePackages.mjs (file header + all exports/functions)
- Deep-freeze entry objects so mutations cannot desync derived exports
- Extend post-build artifact check to cover all bundled workspace packages
  (previously only checked packages/protocol/dist; now checks dist/ for each
  package immediately after runTsc so a misconfigured tsconfig is caught early)

Author: stoicneko

apps/cli/scripts/buildSharedDeps.mjs

@@ -140,11 +140,10 @@ function sanitizeBundledWorkspacePackageJson(raw) {
 export function main() {
   for (const pkg of bundledWorkspaceDirs) {
     runTsc(resolve(repoRoot, 'packages', pkg, 'tsconfig.json'));
-  }
-
-  const protocolDist = resolve(repoRoot, 'packages', 'protocol', 'dist', 'index.js');
-  if (!existsSync(protocolDist)) {
-    throw new Error(`Expected @happier-dev/protocol build output missing: ${protocolDist}`);
+    const distDir = resolve(repoRoot, 'packages', pkg, 'dist');
+    if (!existsSync(distDir)) {
+      throw new Error(`Expected @happier-dev/${pkg} build output missing: ${distDir}`);
+    }
   }
 
   // If the CLI currently has bundled workspace deps under apps/cli/node_modules,

apps/cli/scripts/bundledWorkspacePackages.mjs

@@ -1,20 +1,55 @@
+/**
+ * Canonical list of workspace packages that are bundled into the CLI npm package.
+ *
+ * This module is the single source of truth consumed by both the build step
+ * (`buildSharedDeps.mjs`) and the bundle step (`bundleWorkspaceDeps.mjs`).
+ * Adding or removing a package here automatically keeps both steps in sync.
+ */
+
 import { resolve } from 'node:path';
 
+/**
+ * Frozen array of all workspace packages that must be compiled and bundled
+ * during `yarn prepack`. Each entry is itself frozen to prevent accidental
+ * mutation that could desync the derived exports.
+ *
+ * @type {ReadonlyArray<{dirName: string, packageName: string}>}
+ */
 export const bundledWorkspacePackages = Object.freeze([
-  { dirName: 'agents', packageName: '@happier-dev/agents' },
-  { dirName: 'cli-common', packageName: '@happier-dev/cli-common' },
-  { dirName: 'protocol', packageName: '@happier-dev/protocol' },
-  { dirName: 'release-runtime', packageName: '@happier-dev/release-runtime' },
+  Object.freeze({ dirName: 'agents', packageName: '@happier-dev/agents' }),
+  Object.freeze({ dirName: 'cli-common', packageName: '@happier-dev/cli-common' }),
+  Object.freeze({ dirName: 'protocol', packageName: '@happier-dev/protocol' }),
+  Object.freeze({ dirName: 'release-runtime', packageName: '@happier-dev/release-runtime' }),
 ]);
 
+/**
+ * Frozen array of directory names derived from {@link bundledWorkspacePackages}.
+ * Matches the subdirectory names under `packages/` in the monorepo root.
+ *
+ * @type {ReadonlyArray<string>}
+ */
 export const bundledWorkspaceDirNames = Object.freeze(
   bundledWorkspacePackages.map(({ dirName }) => dirName),
 );
 
+/**
+ * Frozen array of npm package names derived from {@link bundledWorkspacePackages}.
+ * Must stay in sync with the `bundledDependencies` field in `apps/cli/package.json`.
+ *
+ * @type {ReadonlyArray<string>}
+ */
 export const bundledWorkspacePackageNames = Object.freeze(
   bundledWorkspacePackages.map(({ packageName }) => packageName),
 );
 
+/**
+ * Creates the bundle descriptor objects used by `bundleWorkspaceDeps.mjs`.
+ * Each descriptor maps a workspace package to its source directory (in the
+ * monorepo) and the destination directory under `apps/cli/node_modules`.
+ *
+ * @param {{ repoRoot: string, happyCliDir: string }} opts
+ * @returns {Array<{ packageName: string, srcDir: string, destDir: string }>}
+ */
 export function createBundledWorkspaceBundles({ repoRoot, happyCliDir }) {
   return bundledWorkspacePackages.map(({ dirName, packageName }) => ({
     packageName,