feat(fleet): add reviewed v1-to-v2 migration preview (#788)

packages/mosaic/src/fleet/generated-env-boundary.ts

@@ -1,6 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { chmod, lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { compareCodePoints } from './deterministic-order.js';
 
 export type AgentEnvironmentKind = 'generated' | 'local';
 
@@ -30,6 +32,15 @@ export interface AgentEnvironmentProjectionResult {
   readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
 }
 
+/** Sanitized, non-mutating projection evidence safe for migration output. */
+export interface AgentEnvironmentProjectionPreview {
+  readonly agentName: string;
+  readonly generated: 'rebuild';
+  readonly legacy: 'absent' | 'regenerate-only' | 'relocate-local' | 'quarantine';
+  readonly relocatedKeys: readonly string[];
+  readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
+}
+
 /** A projection fully validated without changing managed files. */
 export interface PreparedAgentEnvironmentProjection {
   readonly mosaicHome: string;
@@ -40,6 +51,7 @@ export interface PreparedAgentEnvironmentProjection {
   readonly generated: string;
   readonly local: string;
   readonly legacy?: string;
+  readonly legacyRelocatedKeys: readonly string[];
   readonly quarantinePath?: string;
   readonly diagnostics: readonly AgentEnvironmentDiagnostic[];
 }
@@ -186,6 +198,7 @@ export async function prepareAgentEnvironmentProjection(
     generated,
     local,
     ...(legacy === undefined ? {} : { legacy }),
+    legacyRelocatedKeys: Object.keys(legacyDisposition.localValues).sort(compareCodePoints),
     ...(quarantinePath === undefined ? {} : { quarantinePath }),
     diagnostics: legacyDisposition.diagnostics,
   };
@@ -208,6 +221,33 @@ export async function prepareAgentGeneratedProjectionDeletion(
   return generatedPath;
 }
 
+export async function previewAgentEnvironmentProjection(
+  options: AgentEnvironmentProjectionOptions,
+): Promise<AgentEnvironmentProjectionPreview> {
+  const prepared = await prepareAgentEnvironmentProjection(options);
+  const relocatedKeys = prepared.legacyRelocatedKeys;
+  const legacy =
+    prepared.legacy === undefined
+      ? 'absent'
+      : prepared.diagnostics.length > 0
+        ? 'quarantine'
+        : relocatedKeys.length > 0
+          ? 'relocate-local'
+          : 'regenerate-only';
+  return {
+    agentName: options.agentName,
+    generated: 'rebuild',
+    legacy,
+    relocatedKeys,
+    diagnostics: [...prepared.diagnostics].sort((left, right): number =>
+      compareCodePoints(
+        `${left.key}:${left.code}:${left.sha256}`,
+        `${right.key}:${right.code}:${right.sha256}`,
+      ),
+    ),
+  };
+}
+
 /** Applies a previously prepared deterministic projection. */
 export async function applyPreparedAgentEnvironmentProjection(
   prepared: PreparedAgentEnvironmentProjection,
@@ -279,7 +319,7 @@ function normalizeGeneratedValues(
   for (const key of GENERATED_AGENT_ENV_KEYS) {
     const value = values[key];
     if (value === undefined) throw new AgentEnvBoundaryError('missing-key', key, '');
-    normalized[key] = value;
+    normalized[key] = key === 'MOSAIC_AGENT_WORKDIR' ? expandHomeDirectory(value) : value;
   }
   for (const [key, value] of Object.entries(values)) {
     if (!GENERATED_KEY_SET.has(key)) throw new AgentEnvBoundaryError('unknown-key', key, value);
@@ -288,17 +328,23 @@ function normalizeGeneratedValues(
   return Object.freeze(normalized);
 }
 
+function expandHomeDirectory(path: string): string {
+  if (path === '~') return homedir();
+  if (!path.startsWith('~/') || path.split('/').includes('..')) return path;
+  return join(homedir(), path.slice(2));
+}
+
 function renderLocalAgentEnvironment(values: Readonly<Record<string, string>>): string {
   if (Object.keys(values).length === 0) return '';
   const parsed = parseAgentEnvironment(
     Object.entries(values)
-      .sort(([left], [right]): number => left.localeCompare(right))
+      .sort(([left], [right]): number => compareCodePoints(left, right))
       .map(([key, value]): string => `${key}=${value}`)
       .join('\n'),
     'local',
   );
   return `${Object.entries(parsed)
-    .sort(([left], [right]): number => left.localeCompare(right))
+    .sort(([left], [right]): number => compareCodePoints(left, right))
     .map(([key, value]): string => `${key}=${value}`)
     .join('\n')}\n`;
 }