@yalehwang/cloudpit 2.0.0 → 3.0.0

package/server/load-env.ts

@@ -49,10 +49,21 @@ try {
 }
 
 // Resolve the data root AFTER `.env` was read (module imports are hoisted, but this call is not),
-// so `CLOUDPIT_HOME` / `CLOUDCLI_HOME` from the file are honoured. The Cloudpit default migrates a
-// legacy `~/.cloudcli` layout once, and falls back to it if the copy fails. Exported so
-// `server/index.ts` reuses this single resolution instead of migrating a second time.
-export const DATA_ROOTS = resolveDataRoots({ defaultRoot: 'cloudpit' });
+// so `CLOUDPIT_HOME` from the file is honoured. The Cloudpit default (`~/.cloudpit`) is the only
+// default and migrates a legacy `~/.cloudcli` layout once; a failed migration is reported below
+// and does NOT fall back to the old root (v3.0). Exported so `server/index.ts` reuses this single
+// resolution instead of migrating a second time.
+export const DATA_ROOTS = resolveDataRoots();
+
+if (DATA_ROOTS.migrationError !== null) {
+  // v3.0: a failed one-time migration is an explicit error, never a silent fallback to
+  // `~/.cloudcli`. The server keeps running on the Cloudpit root so the operator can fix
+  // the cause (e.g. an occupied SQLite database) and restart.
+  console.error(
+    `Cloudpit data-root migration failed (${DATA_ROOTS.reason}): ${DATA_ROOTS.migrationError}. ` +
+      `Continuing with ${DATA_ROOTS.activeRoot}; the legacy root was left untouched.`,
+  );
+}
 
 if (!process.env.DATABASE_PATH) {
   process.env.DATABASE_PATH = DATA_ROOTS.authDatabasePath;

package/server/modules/browser-use/browser-use.service.ts

@@ -9,19 +9,52 @@ import spawn from 'cross-spawn';
 
 import { appConfigDb } from '@/modules/database/index.js';
 import { providerMcpService } from '@/modules/providers/index.js';
+import { createBrandEnvReader } from '@/shared/brand.js';
 import { getModuleDirectory } from '@/shared/utils.js';
 
 import { getBrowserUseRuntime } from './browser-use-runtime.js';
 import {
-  LEGACY_MCP_SERVER_NAMES,
   MCP_SERVER_NAME,
   mcpServerNamesToRemove,
 } from './mcp-server-names.js';
 
 const require = createRequire(import.meta.url);
 const __dirname = getModuleDirectory(import.meta.url);
-const MAX_SESSIONS_PER_OWNER = Number.parseInt(process.env.CLOUDCLI_BROWSER_USE_MAX_SESSIONS_PER_OWNER || '3', 10);
-const SESSION_TTL_MS = Number.parseInt(process.env.CLOUDCLI_BROWSER_USE_SESSION_TTL_MS || String(30 * 60 * 1000), 10);
+const DEFAULT_MAX_SESSIONS_PER_OWNER = 3;
+const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** The brand-controlled browser-use limits, resolved once per process. */
+export type BrowserUseEnvDefaults = {
+  maxSessionsPerOwner: number;
+  sessionTtlMs: number;
+  installTimeoutMs: number;
+};
+
+/**
+ * Resolve the browser-use limits from the brand environment.
+ *
+ * v3.0: only the `CLOUDPIT_*` spelling is read; a deployment that still exports
+ * `CLOUDCLI_*` gets these shipped defaults.
+ *
+ * Exported so the wiring criterion can drive the exact reads the service uses
+ * with an injected environment instead of mutating this process.
+ */
+export function readBrowserUseEnvDefaults(
+  env: Readonly<Record<string, string | undefined>>,
+): BrowserUseEnvDefaults {
+  const reader = createBrandEnvReader({ env });
+  const readInteger = (name: string, fallback: number) =>
+    Number.parseInt(reader.read(name).value || String(fallback), 10);
+
+  return {
+    maxSessionsPerOwner: readInteger('BROWSER_USE_MAX_SESSIONS_PER_OWNER', DEFAULT_MAX_SESSIONS_PER_OWNER),
+    sessionTtlMs: readInteger('BROWSER_USE_SESSION_TTL_MS', DEFAULT_SESSION_TTL_MS),
+    installTimeoutMs: readInteger('BROWSER_USE_INSTALL_TIMEOUT_MS', DEFAULT_INSTALL_TIMEOUT_MS),
+  };
+}
+
+const browserUseEnvDefaults = readBrowserUseEnvDefaults(process.env);
 const BROWSER_USE_SETTINGS_KEY = 'browser_use_settings';
 const BROWSER_USE_MCP_TOKEN_KEY = 'browser_use_mcp_token';
 
@@ -355,10 +388,7 @@ class BrowserUseRuntime {
  */
 export const browserUseRuntime = new BrowserUseRuntime();
 
-const INSTALL_COMMAND_TIMEOUT_MS = Number.parseInt(
-  process.env.CLOUDCLI_BROWSER_USE_INSTALL_TIMEOUT_MS || String(10 * 60 * 1000),
-  10,
-);
+const INSTALL_COMMAND_TIMEOUT_MS = browserUseEnvDefaults.installTimeoutMs;
 
 function runCommand(command: string, args: string[]): Promise<void> {
   return new Promise((resolve, reject) => {
@@ -406,7 +436,7 @@ function runCommand(command: string, args: string[]): Promise<void> {
 function formatInstallError(error: unknown): string {
   const message = error instanceof Error ? error.message : String(error);
   if (message.includes('sudo') && message.includes('password')) {
-    return 'Installing Chromium system dependencies requires administrator privileges. Run `npx playwright install-deps chromium` on the machine where CloudCLI runs, then try again.';
+    return 'Installing Chromium system dependencies requires administrator privileges. Run `npx playwright install-deps chromium` on the machine where Cloudpit runs, then try again.';
   }
   return message || 'Failed to install Browser runtime.';
 }
@@ -451,7 +481,7 @@ async function expireStaleSessions(now = Date.now()): Promise<void> {
     }
 
     const updatedAt = Date.parse(session.updatedAt);
-    if (!Number.isFinite(updatedAt) || now - updatedAt <= SESSION_TTL_MS) {
+    if (!Number.isFinite(updatedAt) || now - updatedAt <= browserUseEnvDefaults.sessionTtlMs) {
       return;
     }
 
@@ -540,7 +570,8 @@ export const browserUseService = {
 
   async registerAgentMcp() {
     const { command, args } = getMcpCommand();
-    await Promise.all(LEGACY_MCP_SERVER_NAMES.map((name) => removeMcpServerFromAllProviders(name)));
+    const mcpToken = getOrCreateMcpToken();
+    const mcpApiUrl = getMcpApiUrl();
     const results = await providerMcpService.addMcpServerToAllProviders({
       name: MCP_SERVER_NAME,
       scope: 'user',
@@ -548,8 +579,8 @@ export const browserUseService = {
       command,
       args,
       env: {
-        CLOUDCLI_BROWSER_USE_MCP_TOKEN: getOrCreateMcpToken(),
-        CLOUDCLI_BROWSER_USE_API_URL: getMcpApiUrl(),
+        CLOUDPIT_BROWSER_USE_MCP_TOKEN: mcpToken,
+        CLOUDPIT_BROWSER_USE_API_URL: mcpApiUrl,
       },
     });
     return { name: MCP_SERVER_NAME, command, args, results };
@@ -610,8 +641,8 @@ export const browserUseService = {
     };
 
     const activeOwnerSessions = ownerSessions(AGENT_OWNER_ID).filter((item) => item.status === 'ready');
-    if (activeOwnerSessions.length >= MAX_SESSIONS_PER_OWNER) {
-      throw new Error(`Browser is limited to ${MAX_SESSIONS_PER_OWNER} active agent sessions.`);
+    if (activeOwnerSessions.length >= browserUseEnvDefaults.maxSessionsPerOwner) {
+      throw new Error(`Browser is limited to ${browserUseEnvDefaults.maxSessionsPerOwner} active agent sessions.`);
     }
 
     const readiness = browserUseRuntime.probe();

package/server/modules/browser-use/index.ts

@@ -6,11 +6,10 @@
  */
 // getBrowserUseRuntime: used by Browser Use services and environment-mode regression coverage.
 export { getBrowserUseRuntime } from './browser-use-runtime.js';
-// The MCP registration names and the cleanup set: exported from a dependency-free leaf so the
-// Cloudpit runtime criterion can assert an uninstall removes the current name AND both legacy
-// spellings without importing the service (and its database/provider singletons) through the barrel.
+// The MCP registration name and the cleanup set: exported from a dependency-free leaf so the
+// Cloudpit runtime criterion can assert an uninstall removes exactly the current name without
+// importing the service (and its database/provider singletons) through the barrel.
 export {
-  LEGACY_MCP_SERVER_NAMES,
   MCP_SERVER_NAME,
   mcpServerNamesToRemove,
 } from './mcp-server-names.js';

package/server/modules/browser-use/mcp-server-names.ts

@@ -14,10 +14,11 @@
 /** The name this build registers with every provider. */
 export const MCP_SERVER_NAME = 'cloudpit-browser';
 
-/** Spellings earlier builds registered; an uninstall removes them as well. */
-export const LEGACY_MCP_SERVER_NAMES: string[] = ['cloudcli-browser', 'cloudcli-browser-use'];
-
-/** The names an uninstall must remove: the current registration plus every legacy spelling. */
+/**
+ * The names an uninstall must remove. 3.0 registers and cleans exactly one name: the 2.x
+ * uninstall path already removed the `cloudcli-browser` / `cloudcli-browser-use` registrations,
+ * so no legacy spelling is touched here any more.
+ */
 export function mcpServerNamesToRemove(): string[] {
-  return [MCP_SERVER_NAME, ...LEGACY_MCP_SERVER_NAMES];
+  return [MCP_SERVER_NAME];
 }

package/server/modules/browser-use/tests/browser-use.service.test.ts

@@ -1,10 +1,72 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 
-import { browserUseService } from '@/modules/browser-use/browser-use.service.js';
+import {
+  browserUseService,
+  readBrowserUseEnvDefaults,
+} from '@/modules/browser-use/browser-use.service.js';
 
 test('browser monitor list starts empty without agent sessions', async () => {
   const sessions = await browserUseService.listSessions();
 
   assert.deepEqual(sessions, []);
 });
+
+/** Resolve the service's brand-controlled limits over one in-memory environment. */
+function resolveBrowserUseEnv(env: Record<string, string | undefined>) {
+  return readBrowserUseEnvDefaults(env);
+}
+
+const DEFAULTS = {
+  maxSessionsPerOwner: 3,
+  sessionTtlMs: 30 * 60 * 1000,
+  installTimeoutMs: 10 * 60 * 1000,
+};
+
+test('browser-use AC4: no brand env set keeps the shipped defaults', () => {
+  assert.deepEqual(resolveBrowserUseEnv({}), DEFAULTS);
+});
+
+test('browser-use AC3: CLOUDPIT_* supplies every value', () => {
+  const defaults = resolveBrowserUseEnv({
+    CLOUDPIT_BROWSER_USE_MAX_SESSIONS_PER_OWNER: '7',
+    CLOUDPIT_BROWSER_USE_SESSION_TTL_MS: '60000',
+    CLOUDPIT_BROWSER_USE_INSTALL_TIMEOUT_MS: '120000',
+  });
+
+  assert.deepEqual(defaults, {
+    maxSessionsPerOwner: 7,
+    sessionTtlMs: 60_000,
+    installTimeoutMs: 120_000,
+  });
+});
+
+test('browser-use AC5 (v3.0): the legacy spelling is ignored and the shipped defaults apply', () => {
+  const defaults = resolveBrowserUseEnv({
+    CLOUDCLI_BROWSER_USE_MAX_SESSIONS_PER_OWNER: '7',
+    CLOUDCLI_BROWSER_USE_SESSION_TTL_MS: '60000',
+    CLOUDCLI_BROWSER_USE_INSTALL_TIMEOUT_MS: '120000',
+  });
+
+  assert.deepEqual(defaults, DEFAULTS);
+});
+
+test('browser-use AC3: both spellings set means the new value wins', () => {
+  const defaults = resolveBrowserUseEnv({
+    CLOUDPIT_BROWSER_USE_MAX_SESSIONS_PER_OWNER: '7',
+    CLOUDCLI_BROWSER_USE_MAX_SESSIONS_PER_OWNER: '9',
+  });
+
+  assert.equal(defaults.maxSessionsPerOwner, 7);
+  assert.equal(defaults.sessionTtlMs, DEFAULTS.sessionTtlMs);
+  assert.equal(defaults.installTimeoutMs, DEFAULTS.installTimeoutMs);
+});
+
+test('browser-use AC2 (v3.0): an empty new value reads absent, not the legacy spelling', () => {
+  const defaults = resolveBrowserUseEnv({
+    CLOUDPIT_BROWSER_USE_MAX_SESSIONS_PER_OWNER: '',
+    CLOUDCLI_BROWSER_USE_MAX_SESSIONS_PER_OWNER: '9',
+  });
+
+  assert.equal(defaults.maxSessionsPerOwner, DEFAULTS.maxSessionsPerOwner);
+});

package/server/modules/cli/asset-migration-files.ts

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Synchronous filesystem seam for `cloudpit migrate-assets`.
+ *
+ * The command copies the legacy asset tree and scans provider transcripts
+ * read-only, so every call is synchronous and every call goes through this
+ * seam. Tests inject a fixture-rooted adapter to prove the dry run touches
+ * nothing; the composition root injects {@link createNodeAssetMigrationFileSystem}.
+ */
+export type AssetMigrationFileSystem = {
+  pathExists(filePath: string): boolean;
+  isDirectory(filePath: string): boolean;
+  listDirectoryNames(directoryPath: string): string[];
+  readTextFile(filePath: string): string;
+  readFileBytes(filePath: string): Buffer;
+  copyFile(sourcePath: string, targetPath: string): void;
+  createDirectory(directoryPath: string): void;
+};
+
+/** Node-backed implementation wired by `cli.module.ts` and by the command's tests. */
+export function createNodeAssetMigrationFileSystem(): AssetMigrationFileSystem {
+  return {
+    pathExists: (filePath) => fs.existsSync(filePath),
+    isDirectory: (filePath) => {
+      try {
+        return fs.statSync(filePath).isDirectory();
+      } catch {
+        return false;
+      }
+    },
+    listDirectoryNames: (directoryPath) => fs.readdirSync(directoryPath),
+    readTextFile: (filePath) => fs.readFileSync(filePath, 'utf8'),
+    readFileBytes: (filePath) => fs.readFileSync(filePath),
+    copyFile: (sourcePath, targetPath) => {
+      fs.copyFileSync(sourcePath, targetPath);
+    },
+    createDirectory: (directoryPath) => {
+      fs.mkdirSync(directoryPath, { recursive: true });
+    },
+  };
+}
+
+/**
+ * Every regular file under `rootPath`, recursively, as absolute paths sorted
+ * lexicographically so the report is stable across runs. A missing or
+ * non-directory root is an empty list rather than an error: both the legacy
+ * assets root and the provider transcript roots are legitimately absent on a
+ * fresh machine, and an absent directory means "nothing to migrate".
+ *
+ * Symlinked directories are NOT followed: the asset store is a flat
+ * upload directory and a link loop must not hang the command.
+ */
+export function listFilesUnder(
+  fileSystem: AssetMigrationFileSystem,
+  rootPath: string,
+): string[] {
+  if (!fileSystem.isDirectory(rootPath)) return [];
+  const files: string[] = [];
+  const pendingDirectories = [rootPath];
+  while (pendingDirectories.length > 0) {
+    const directoryPath = pendingDirectories.pop() as string;
+    let entries: string[];
+    try {
+      entries = fileSystem.listDirectoryNames(directoryPath);
+    } catch {
+      // A directory that vanished between listing and reading contributes
+      // nothing; a permission failure on a transcript directory must not abort
+      // the whole scan.
+      continue;
+    }
+    for (const entryName of entries) {
+      const entryPath = path.join(directoryPath, entryName);
+      if (fileSystem.isDirectory(entryPath)) {
+        pendingDirectories.push(entryPath);
+      } else {
+        files.push(entryPath);
+      }
+    }
+  }
+  return files.sort();
+}
+
+/** True when two files hold byte-identical content. */
+export function filesHaveSameContent(
+  fileSystem: AssetMigrationFileSystem,
+  leftPath: string,
+  rightPath: string,
+): boolean {
+  try {
+    return fileSystem.readFileBytes(leftPath).equals(fileSystem.readFileBytes(rightPath));
+  } catch {
+    return false;
+  }
+}

package/server/modules/cli/asset-migration-report.ts

@@ -0,0 +1,123 @@
+import type { CliOutput } from '@/shared/types.js';
+
+/**
+ * Report shape, option parsing and terminal rendering for
+ * `cloudpit migrate-assets`.
+ *
+ * Split from the orchestration service so the migration flow reads as one
+ * sequence (scan → copy → rewrite → verify) and the command's public report
+ * contract lives in one place.
+ */
+
+/** The `--json` report. Field names are the command's public contract. */
+export type AssetMigrationReport = {
+  /** Files copied into the Cloudpit root (planned count in a dry run). */
+  copied: number;
+  /** Files already present with identical content (planned count in a dry run). */
+  skipped: number;
+  /** Relative paths whose target exists with different content; never overwritten. */
+  conflicts: string[];
+  /** App-owned documents whose paths were rewritten (planned count in a dry run). */
+  rewritten: number;
+  /** External references that must be resolved by hand, one `file:line` per hit. */
+  unrewritable: string[];
+  /** Backup files created before the first write. */
+  backupPaths: string[];
+  /** Failures; a non-empty list means the rewrite was rolled back. */
+  errors: string[];
+};
+
+/** Parsed command flags. */
+export type AssetMigrationOptions = {
+  mode: 'scan' | 'rewrite';
+  json: boolean;
+};
+
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_UNREWRITABLE = 3;
+
+export const USAGE = `
+Usage:
+  cloudpit migrate-assets --dry-run [--json]
+  cloudpit migrate-assets --rewrite [--json]
+
+Options:
+  --dry-run    Scan only: report what would be copied and rewritten; write nothing.
+  --rewrite    Copy legacy assets into the Cloudpit root and rewrite persisted paths.
+  --json       Print the report as JSON on stdout.
+  -h, --help   Show this help information.
+
+The legacy ~/.cloudcli/assets directory is never deleted. Provider transcripts are
+scanned read-only and reported as unrewritable (exit code 3 when any exist).
+`.trim();
+
+/**
+ * Parses the command's own flags. Unknown flags and a missing mode are usage
+ * errors returned as a message (not thrown), so the caller can print usage and
+ * exit non-zero instead of starting a migration by accident.
+ */
+export function parseAssetMigrationOptions(
+  argumentsList: string[],
+): AssetMigrationOptions | string {
+  let dryRun = false;
+  let rewrite = false;
+  let json = false;
+  for (const argument of argumentsList) {
+    if (argument === '--dry-run') dryRun = true;
+    else if (argument === '--rewrite') rewrite = true;
+    else if (argument === '--json') json = true;
+    else return `Unknown option: ${argument}`;
+  }
+  if (dryRun && rewrite) return '--dry-run and --rewrite are mutually exclusive';
+  if (!dryRun && !rewrite) return 'Specify --dry-run or --rewrite';
+  return { mode: rewrite ? 'rewrite' : 'scan', json };
+}
+
+/** Renders the human-readable report; `--json` callers skip this. */
+export function printAssetMigrationReport(
+  output: CliOutput,
+  report: AssetMigrationReport,
+  mode: AssetMigrationOptions['mode'],
+  legacyRoot: string,
+  newRoot: string,
+): void {
+  output.log(mode === 'rewrite'
+    ? 'Asset migration'
+    : 'Asset migration (dry run — nothing was written)');
+  output.log(`  legacy root:   ${legacyRoot}`);
+  output.log(`  cloudpit root: ${newRoot}`);
+  output.log(
+    `  copied=${report.copied} skipped=${report.skipped} conflicts=${report.conflicts.length}`
+    + ` rewritten=${report.rewritten} unrewritable=${report.unrewritable.length}`
+    + ` backups=${report.backupPaths.length}`,
+  );
+  for (const conflict of report.conflicts) output.log(`  conflict: ${conflict}`);
+  for (const reference of report.unrewritable) output.log(`  unrewritable: ${reference}`);
+  for (const backupPath of report.backupPaths) output.log(`  backup: ${backupPath}`);
+}
+
+/**
+ * Warnings and errors go to stderr in both render modes so a `--json` run's
+ * stdout stays one parseable object.
+ */
+export function printAssetMigrationDiagnostics(
+  output: CliOutput,
+  report: AssetMigrationReport,
+  legacyRoot: string,
+): void {
+  if (report.unrewritable.length > 0) {
+    output.error(
+      `[WARN] ${report.unrewritable.length} reference(s) still point at ${legacyRoot};`
+      + ' provider transcripts are not rewritten — resolve them by hand.',
+    );
+  }
+  for (const error of report.errors) output.error(`[ERROR] ${error}`);
+}
+
+/** `0` clean, `1` failed/rolled back, `3` success with unrewritable transcript references. */
+export function assetMigrationExitCode(report: AssetMigrationReport): number {
+  if (report.errors.length > 0) return EXIT_FAILED;
+  if (report.unrewritable.length > 0) return EXIT_UNREWRITABLE;
+  return EXIT_OK;
+}