amalgm 0.1.137 → 0.1.138

package/lib/layout.js

@@ -0,0 +1,337 @@
+'use strict';
+
+/**
+ * Amalgm filesystem layout — the one module that knows where Amalgm state
+ * lives on a user's machine.
+ *
+ * Canonical layout (visible root):
+ *
+ *   ~/amalgm/
+ *     .amalgm-root.json          installation identity + user-folder index
+ *     users/
+ *       aayush@example.com/      human-readable folder name; NOT the identity
+ *         .amalgm-user.json      stable identity — userId is authoritative
+ *         agents/ apps/ automations/ toolbox/ workspaces/ ...
+ *
+ * Rules:
+ * - The folder name is presentation; `.amalgm-user.json` is identity. If a
+ *   folder is renamed, resolution recovers by scanning user manifests.
+ * - Legacy layouts (hidden ~/.amalgm, uuid-named user folders) keep working:
+ *   resolution falls back to them, and migrate-layout leaves compat symlinks
+ *   at the old locations.
+ * - Explicit env (AMALGM_HOME / AMALGM_DIR) always wins — isolated runtimes
+ *   and tests depend on that.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ROOT_MANIFEST_NAME = '.amalgm-root.json';
+const USER_MANIFEST_NAME = '.amalgm-user.json';
+const LAYOUT_VERSION = 1;
+
+// Per-user roots for platform primitives. Everything Amalgm owns for a user
+// lives under one of these; anything else on disk is the user's own project.
+const PRIMITIVE_DIRS = Object.freeze([
+  'agents',
+  'apps',
+  'automations',
+  'toolbox',
+  'workspaces',
+]);
+
+function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+}
+
+function lstatOrNull(target) {
+  try {
+    return fs.lstatSync(target);
+  } catch {
+    return null;
+  }
+}
+
+/** Same charset as runtime-identity's sanitizeScopeSegment — kept identical so
+ *  legacy uuid folders resolve to the exact names they were created with. */
+function sanitizeFolderSegment(value, fallback = 'local') {
+  const clean = String(value || '')
+    .trim()
+    .replace(/[^A-Za-z0-9_.@-]/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return clean || fallback;
+}
+
+/** Folder name for a user identified by email: lowercased, same charset. */
+function emailFolderName(email) {
+  return sanitizeFolderSegment(String(email || '').trim().toLowerCase(), '');
+}
+
+function visibleRootPath() {
+  return path.join(os.homedir(), 'amalgm');
+}
+
+function hiddenRootPath() {
+  return path.join(os.homedir(), '.amalgm');
+}
+
+function rootManifestPath(homeDir) {
+  return path.join(homeDir, ROOT_MANIFEST_NAME);
+}
+
+function userManifestPath(userDir) {
+  return path.join(userDir, USER_MANIFEST_NAME);
+}
+
+function isAmalgmRoot(dir) {
+  return fs.existsSync(rootManifestPath(dir));
+}
+
+/**
+ * Where Amalgm state lives on this machine.
+ *
+ * Order: explicit AMALGM_HOME → initialized visible root (~/amalgm with a
+ * root manifest) → migrated hidden alias (~/.amalgm symlink → its target) →
+ * legacy hidden root (~/.amalgm directory) → visible root for fresh installs.
+ */
+function resolveAmalgmHome(env = process.env) {
+  if (env.AMALGM_HOME) return path.resolve(env.AMALGM_HOME);
+
+  const visible = visibleRootPath();
+  if (isAmalgmRoot(visible)) return visible;
+
+  const hidden = hiddenRootPath();
+  const hiddenStat = lstatOrNull(hidden);
+  if (hiddenStat?.isSymbolicLink()) {
+    try {
+      const target = fs.realpathSync(hidden);
+      return samePath(target, visible) ? visible : target;
+    } catch {
+      return visible;
+    }
+  }
+  if (hiddenStat) return hidden;
+  return visible;
+}
+
+/** Compare paths through realpath so macOS aliases like /var → /private/var match. */
+function samePath(a, b) {
+  const canonical = (p) => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  return canonical(a) === canonical(b);
+}
+
+function readRootManifest(homeDir) {
+  return readJson(rootManifestPath(homeDir), null);
+}
+
+function ensureRootManifest(homeDir) {
+  const existing = readRootManifest(homeDir);
+  if (existing?.installationId) return existing;
+  const manifest = {
+    schemaVersion: LAYOUT_VERSION,
+    installationId: existing?.installationId || crypto.randomBytes(8).toString('hex'),
+    createdAt: existing?.createdAt || new Date().toISOString(),
+    users: existing?.users || {},
+  };
+  writeJson(rootManifestPath(homeDir), manifest);
+  return manifest;
+}
+
+/** Record a user folder in the root manifest's index. The index is a cache —
+ *  user-manifest scans stay authoritative — but it makes the mapping legible. */
+function indexUserFolder(homeDir, folderName, { userId, email }) {
+  const manifest = ensureRootManifest(homeDir);
+  const entry = manifest.users?.[folderName];
+  if (entry?.userId === userId && (entry?.canonicalEmail || '') === (email || '')) return;
+  manifest.users = { ...manifest.users, [folderName]: { userId, canonicalEmail: email || '' } };
+  writeJson(rootManifestPath(homeDir), manifest);
+}
+
+function readUserManifest(userDir) {
+  const manifest = readJson(userManifestPath(userDir), null);
+  return typeof manifest?.userId === 'string' && manifest.userId.trim() ? manifest : null;
+}
+
+function writeUserManifest(userDir, { userId, email }) {
+  const existing = readUserManifest(userDir);
+  const canonicalEmail = String(email || existing?.canonicalEmail || '').trim().toLowerCase();
+  const emailHistory = Array.isArray(existing?.emailHistory) ? [...existing.emailHistory] : [];
+  if (canonicalEmail && !emailHistory.includes(canonicalEmail)) emailHistory.push(canonicalEmail);
+  const manifest = {
+    schemaVersion: LAYOUT_VERSION,
+    userId: String(userId).trim(),
+    canonicalEmail,
+    emailHistory,
+    createdAt: existing?.createdAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  writeJson(userManifestPath(userDir), manifest);
+  return manifest;
+}
+
+/** All user folders under <homeDir>/users. Real directories first, compat
+ *  symlinks after, both sorted — so scans prefer canonical folders. */
+function listUserEntries(homeDir) {
+  const usersDir = path.join(homeDir, 'users');
+  let names = [];
+  try {
+    names = fs.readdirSync(usersDir);
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const name of names.sort()) {
+    const dir = path.join(usersDir, name);
+    const stat = lstatOrNull(dir);
+    if (!stat) continue;
+    const isSymlink = stat.isSymbolicLink();
+    if (!isSymlink && !stat.isDirectory()) continue;
+    if (isSymlink && !fs.existsSync(dir)) continue; // broken link
+    entries.push({ name, dir, isSymlink, manifest: readUserManifest(dir) });
+  }
+  return [...entries.filter((e) => !e.isSymlink), ...entries.filter((e) => e.isSymlink)];
+}
+
+/** Find a user's folder by stable identity, regardless of its display name. */
+function findUserDirByUserId(homeDir, userId) {
+  const clean = String(userId || '').trim();
+  if (!clean) return null;
+  for (const entry of listUserEntries(homeDir)) {
+    if (entry.manifest?.userId === clean) return entry.dir;
+  }
+  return null;
+}
+
+/**
+ * Resolve the storage folder for a user scope (userId or 'local').
+ * Manifest identity wins; otherwise fall back to the legacy scope-named
+ * folder (which may itself be a compat symlink into the new layout).
+ */
+function resolveUserDir(homeDir, scope) {
+  const byId = findUserDirByUserId(homeDir, scope);
+  if (byId) return byId;
+  return path.join(homeDir, 'users', sanitizeFolderSegment(scope));
+}
+
+/**
+ * Ensure a user folder exists with its identity manifest. When the email is
+ * known the folder gets the readable email name (renaming a legacy uuid
+ * folder in place, leaving a compat symlink behind).
+ */
+function ensureUserDir(homeDir, { userId, email }) {
+  const cleanId = String(userId || '').trim();
+  if (!cleanId) throw new Error('ensureUserDir requires a userId');
+  const cleanEmail = String(email || '').trim().toLowerCase();
+
+  const existing = findUserDirByUserId(homeDir, cleanId);
+  if (existing) {
+    if (cleanEmail && readUserManifest(existing)?.canonicalEmail !== cleanEmail) {
+      return adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+    }
+    indexUserFolder(homeDir, path.basename(existing), { userId: cleanId, email: cleanEmail });
+    return existing;
+  }
+
+  const legacyDir = path.join(homeDir, 'users', sanitizeFolderSegment(cleanId));
+  if (lstatOrNull(legacyDir)?.isDirectory()) {
+    writeUserManifest(legacyDir, { userId: cleanId, email: cleanEmail });
+    if (cleanEmail) return adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+    indexUserFolder(homeDir, path.basename(legacyDir), { userId: cleanId, email: '' });
+    return legacyDir;
+  }
+
+  const folderName = (cleanEmail && emailFolderName(cleanEmail)) || sanitizeFolderSegment(cleanId);
+  const dir = path.join(homeDir, 'users', folderName);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeUserManifest(dir, { userId: cleanId, email: cleanEmail });
+  indexUserFolder(homeDir, folderName, { userId: cleanId, email: cleanEmail });
+  return dir;
+}
+
+/**
+ * Give a user's folder its readable email name. Renames the current folder
+ * and leaves a relative compat symlink at the old name so recorded absolute
+ * paths keep resolving. Idempotent; refuses to stomp an unrelated folder.
+ */
+function adoptUserEmail(homeDir, { userId, email }) {
+  const cleanId = String(userId || '').trim();
+  const folderName = emailFolderName(email);
+  if (!cleanId || !folderName) throw new Error('adoptUserEmail requires userId and email');
+
+  const current = findUserDirByUserId(homeDir, cleanId)
+    || (lstatOrNull(path.join(homeDir, 'users', sanitizeFolderSegment(cleanId)))?.isDirectory()
+      ? path.join(homeDir, 'users', sanitizeFolderSegment(cleanId))
+      : null);
+  if (!current) throw new Error(`No storage folder found for user ${cleanId}`);
+
+  writeUserManifest(current, { userId: cleanId, email });
+  const target = path.join(homeDir, 'users', folderName);
+  if (path.basename(current) === folderName) {
+    indexUserFolder(homeDir, folderName, { userId: cleanId, email });
+    return { dir: current, renamed: false };
+  }
+
+  const targetStat = lstatOrNull(target);
+  if (targetStat) {
+    const claimed = targetStat.isDirectory() ? readUserManifest(target)?.userId : null;
+    if (claimed !== cleanId) {
+      return { dir: current, renamed: false, conflict: folderName };
+    }
+    indexUserFolder(homeDir, folderName, { userId: cleanId, email });
+    return { dir: target, renamed: false };
+  }
+
+  fs.renameSync(current, target);
+  fs.symlinkSync(folderName, current); // relative sibling link, relocatable
+  indexUserFolder(homeDir, folderName, { userId: cleanId, email });
+  return { dir: target, renamed: true, from: current };
+}
+
+function userPrimitiveRoot(userDir, kind) {
+  if (!PRIMITIVE_DIRS.includes(kind)) {
+    throw new Error(`Unknown primitive root "${kind}". Use one of: ${PRIMITIVE_DIRS.join(', ')}`);
+  }
+  return path.join(userDir, kind);
+}
+
+module.exports = {
+  samePath,
+  LAYOUT_VERSION,
+  PRIMITIVE_DIRS,
+  ROOT_MANIFEST_NAME,
+  USER_MANIFEST_NAME,
+  adoptUserEmail,
+  emailFolderName,
+  ensureRootManifest,
+  ensureUserDir,
+  findUserDirByUserId,
+  hiddenRootPath,
+  isAmalgmRoot,
+  indexUserFolder,
+  listUserEntries,
+  readRootManifest,
+  readUserManifest,
+  resolveAmalgmHome,
+  resolveUserDir,
+  sanitizeFolderSegment,
+  userPrimitiveRoot,
+  visibleRootPath,
+  writeUserManifest,
+};

package/lib/migrate-layout.js

@@ -0,0 +1,212 @@
+'use strict';
+
+/**
+ * migrate-layout — move a machine onto the canonical Amalgm filesystem layout.
+ *
+ * Two phases, both idempotent and safe under a live runtime:
+ *
+ * 1. Root: rename the hidden ~/.amalgm directory to the visible ~/amalgm and
+ *    leave a symlink at ~/.amalgm. A rename preserves inodes, so processes
+ *    holding open files (sqlite, logs) are unaffected, and every recorded
+ *    absolute path keeps resolving through the symlink.
+ * 2. Users: give each users/<uuid> folder its readable email name (when the
+ *    email is known), writing .amalgm-user.json identity manifests and
+ *    leaving compat symlinks at the uuid names.
+ *
+ * Run directly:
+ *   node lib/migrate-layout.js [--home <dir>] [--email <email>]
+ *                              [--user <userId>=<email>]... [--dry-run]
+ *
+ * --email applies when exactly one user folder exists; --user pins emails to
+ * specific user ids. Users with no known email keep their uuid folder but
+ * still get an identity manifest.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const layout = require('./layout');
+
+function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function lstatOrNull(target) {
+  try {
+    return fs.lstatSync(target);
+  } catch {
+    return null;
+  }
+}
+
+function userIdForDir(dir) {
+  const manifest = layout.readUserManifest(dir);
+  if (manifest?.userId) return manifest.userId;
+  for (const file of ['computer.json', 'auth.json']) {
+    const record = readJson(path.join(dir, file), null);
+    if (typeof record?.user_id === 'string' && record.user_id.trim()) return record.user_id.trim();
+  }
+  return '';
+}
+
+function isIgnorableEntry(name) {
+  return name === '.DS_Store';
+}
+
+/** Rename hidden root → visible root and alias the old path. */
+function migrateRoot({ hiddenRoot, visibleRoot, dryRun, actions }) {
+  const hiddenStat = lstatOrNull(hiddenRoot);
+
+  if (hiddenStat?.isSymbolicLink()) {
+    const target = fs.realpathSync(hiddenRoot);
+    if (!layout.samePath(target, visibleRoot)) {
+      throw new Error(`${hiddenRoot} is a symlink to ${target}, expected ${visibleRoot}`);
+    }
+    return { moved: false, reason: 'already-migrated' };
+  }
+
+  if (!hiddenStat) {
+    if (!lstatOrNull(visibleRoot)) {
+      actions.push(`create ${visibleRoot}`);
+      if (!dryRun) fs.mkdirSync(visibleRoot, { recursive: true, mode: 0o700 });
+    }
+    return { moved: false, reason: 'no-hidden-root' };
+  }
+
+  if (!hiddenStat.isDirectory()) {
+    throw new Error(`${hiddenRoot} exists but is not a directory`);
+  }
+
+  const visibleStat = lstatOrNull(visibleRoot);
+  if (visibleStat) {
+    if (!visibleStat.isDirectory()) {
+      throw new Error(`${visibleRoot} exists but is not a directory`);
+    }
+    const entries = fs.readdirSync(visibleRoot).filter((name) => !isIgnorableEntry(name));
+    if (entries.length > 0) {
+      throw new Error(
+        `${visibleRoot} already exists and is not empty — refusing to migrate over it`,
+      );
+    }
+    actions.push(`remove empty ${visibleRoot}`);
+    if (!dryRun) fs.rmSync(visibleRoot, { recursive: true, force: true });
+  }
+
+  actions.push(`rename ${hiddenRoot} -> ${visibleRoot}`);
+  actions.push(`symlink ${hiddenRoot} -> ${path.basename(visibleRoot)}`);
+  if (!dryRun) {
+    fs.renameSync(hiddenRoot, visibleRoot);
+    fs.symlinkSync(path.basename(visibleRoot), hiddenRoot); // relative sibling link
+  }
+  return { moved: true };
+}
+
+/** Write identity manifests and adopt email folder names for every user. */
+function migrateUsers({ homeDir, emailByUserId, fallbackEmail, dryRun, actions }) {
+  const results = [];
+  const entries = layout.listUserEntries(homeDir).filter((entry) => !entry.isSymlink);
+  const soleEntry = entries.length === 1 ? entries[0] : null;
+
+  for (const entry of entries) {
+    const userId = userIdForDir(entry.dir);
+    if (!userId) {
+      results.push({ folder: entry.name, skipped: 'no-identity' });
+      continue;
+    }
+
+    const email = emailByUserId.get(userId)
+      || layout.readUserManifest(entry.dir)?.canonicalEmail
+      || (entry === soleEntry ? fallbackEmail : '');
+
+    if (dryRun) {
+      const wouldRename = email && layout.emailFolderName(email) !== entry.name;
+      actions.push(`manifest ${entry.dir} (userId=${userId}${email ? `, email=${email}` : ''})`);
+      if (wouldRename) {
+        actions.push(`rename users/${entry.name} -> users/${layout.emailFolderName(email)} (+ symlink)`);
+      }
+      results.push({ folder: entry.name, userId, email, renamed: Boolean(wouldRename) });
+      continue;
+    }
+
+    layout.writeUserManifest(entry.dir, { userId, email });
+    if (email) {
+      const adopted = layout.adoptUserEmail(homeDir, { userId, email });
+      results.push({
+        folder: path.basename(adopted.dir),
+        userId,
+        email,
+        renamed: Boolean(adopted.renamed),
+        conflict: adopted.conflict || null,
+      });
+      if (adopted.renamed) actions.push(`renamed users/${entry.name} -> users/${path.basename(adopted.dir)}`);
+    } else {
+      layout.indexUserFolder(homeDir, entry.name, { userId, email: '' });
+      results.push({ folder: entry.name, userId, email: '', renamed: false });
+    }
+  }
+  return results;
+}
+
+/**
+ * Migrate a machine to the canonical layout. Options:
+ *   home        OS home directory (default os.homedir())
+ *   users       [{ userId, email }] explicit email assignments
+ *   email       fallback email when exactly one user folder exists
+ *   dryRun      report actions without touching the filesystem
+ */
+function migrateLayout(options = {}) {
+  const home = options.home || os.homedir();
+  const hiddenRoot = path.join(home, '.amalgm');
+  const visibleRoot = path.join(home, 'amalgm');
+  const dryRun = Boolean(options.dryRun);
+  const actions = [];
+
+  const emailByUserId = new Map();
+  for (const user of options.users || []) {
+    if (user?.userId && user?.email) {
+      emailByUserId.set(String(user.userId).trim(), String(user.email).trim().toLowerCase());
+    }
+  }
+
+  const root = migrateRoot({ hiddenRoot, visibleRoot, dryRun, actions });
+  if (!dryRun) layout.ensureRootManifest(visibleRoot);
+
+  const users = migrateUsers({
+    // On a dry run the root has not actually moved yet — preview the user
+    // folders where they currently live.
+    homeDir: dryRun && root.moved ? hiddenRoot : visibleRoot,
+    emailByUserId,
+    fallbackEmail: String(options.email || '').trim().toLowerCase(),
+    dryRun,
+    actions,
+  });
+
+  return { home, root: visibleRoot, rootMoved: Boolean(root.moved), users, actions, dryRun };
+}
+
+function parseArgs(argv) {
+  const options = { users: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--home') options.home = argv[++index];
+    else if (arg === '--email') options.email = argv[++index];
+    else if (arg === '--user') {
+      const [userId, email] = String(argv[++index] || '').split('=');
+      options.users.push({ userId, email });
+    } else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return options;
+}
+
+if (require.main === module) {
+  const report = migrateLayout(parseArgs(process.argv.slice(2)));
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+module.exports = { migrateLayout };

package/lib/runtime-identity.js

@@ -5,6 +5,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const layout = require('./layout');
+
 const VALID_RUNTIME_LABELS = new Set(['main', 'preview', 'local']);
 
 function normalizeRuntimeLabel(value) {
@@ -82,6 +84,11 @@ function discoverLegacyUserScope(homeDir, label = '') {
   const fromAuth = userIdFromRecord(auth);
   if (fromAuth) return fromAuth;
 
+  // Identity manifests are authoritative when present (canonical layout).
+  for (const entry of layout.listUserEntries(homeDir)) {
+    if (entry.manifest?.userId) return entry.manifest.userId;
+  }
+
   const runtimeLabel = normalizeRuntimeLabel(label);
   if (!runtimeLabel) return '';
   try {
@@ -121,12 +128,14 @@ function resolveRuntimeUserScope(env = process.env, fallback = '') {
 }
 
 function defaultAmalgmHome(env = process.env) {
-  return env.AMALGM_HOME || path.join(os.homedir(), '.amalgm');
+  return layout.resolveAmalgmHome(env);
 }
 
 function scopedAmalgmDir(homeDir, userScope, label) {
   assertRuntimeLabel(label);
-  return path.join(homeDir, 'users', sanitizeScopeSegment(userScope));
+  // Manifest identity wins over folder naming; falls back to the legacy
+  // scope-named folder for machines without identity manifests.
+  return layout.resolveUserDir(homeDir, sanitizeScopeSegment(userScope));
 }
 
 function scopedRuntimeDir(homeDir, userScope, label) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.137",
+  "version": "0.1.138",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,
@@ -17,7 +17,7 @@
     "sync-runtime": "node ../../scripts/sync-npm-package-runtime.mjs",
     "prepack": "node ../../scripts/sync-npm-package-runtime.mjs",
     "pack:dry": "npm pack --dry-run",
-    "check": "node --check bin/amalgm.js && node --check lib/app-chat.js && node --check lib/react.js && node --check lib/auth-store.js && node --check lib/cli.js && node --check lib/paths.js && node --check lib/process-cleanup.js && node --check lib/runtime-identity.js && node --check lib/runtime-manifest.js && node --check lib/service.js && node --check lib/state-migration.js && node --check lib/supervisor.js && node --check lib/tunnel-chat.js && node --check lib/tunnel-events.js && node --check lib/updater.js && node --check runtime/lib/runtime-manifest.js && node --check runtime/scripts/runtime-auth.js && node --check runtime/scripts/proxy-token-store.js && node --check runtime/scripts/local-gateway.js && node --check runtime/scripts/port-monitor.js && node --check runtime/scripts/chat-server.js && node --check runtime/scripts/chat-server/index.js && node --check runtime/scripts/chat-server/config.js && node --check runtime/scripts/chat-core/tooling/native-binaries.js && node --check runtime/scripts/chat-core/tooling/package-import.js && node --check runtime/scripts/chat-core/tooling/runtime-home.js && node --check runtime/scripts/amalgm-mcp/index.js && node --check runtime/scripts/amalgm-mcp/config.js && node --check runtime/scripts/amalgm-mcp/events/pr-check-runner.js && node --check runtime/scripts/lib/project-paths.js && node --check runtime/scripts/lib/runtime-paths.js"
+    "check": "node --check bin/amalgm.js && node --check lib/app-chat.js && node --check lib/react.js && node --check lib/auth-store.js && node --check lib/cli.js && node --check lib/layout.js && node --check lib/migrate-layout.js && node --check lib/paths.js && node --check lib/process-cleanup.js && node --check lib/runtime-identity.js && node --check lib/runtime-manifest.js && node --check lib/service.js && node --check lib/state-migration.js && node --check lib/supervisor.js && node --check lib/tunnel-chat.js && node --check lib/tunnel-events.js && node --check lib/updater.js && node --check runtime/lib/runtime-manifest.js && node --check runtime/scripts/runtime-auth.js && node --check runtime/scripts/proxy-token-store.js && node --check runtime/scripts/local-gateway.js && node --check runtime/scripts/port-monitor.js && node --check runtime/scripts/chat-server.js && node --check runtime/scripts/chat-server/index.js && node --check runtime/scripts/chat-server/config.js && node --check runtime/scripts/chat-core/tooling/native-binaries.js && node --check runtime/scripts/chat-core/tooling/package-import.js && node --check runtime/scripts/chat-core/tooling/runtime-home.js && node --check runtime/scripts/amalgm-mcp/index.js && node --check runtime/scripts/amalgm-mcp/config.js && node --check runtime/scripts/amalgm-mcp/events/pr-check-runner.js && node --check runtime/scripts/lib/project-paths.js && node --check runtime/scripts/lib/runtime-paths.js"
   },
   "engines": {
     "node": ">=20"

package/runtime/scripts/amalgm-mcp/agent-bundles/app-entries.js

@@ -25,6 +25,17 @@ function cleanString(value) {
   return typeof value === 'string' ? value.trim() : '';
 }
 
+const NODE_INSTALL_COMMANDS = [
+  ['pnpm-lock.yaml', 'pnpm install --frozen-lockfile'],
+  ['yarn.lock', 'yarn install --frozen-lockfile'],
+  ['bun.lockb', 'bun install --frozen-lockfile'],
+  ['bun.lock', 'bun install --frozen-lockfile'],
+  ['package-lock.json', 'npm install'],
+  ['npm-shrinkwrap.json', 'npm install'],
+];
+
+const NODE_INSTALL_PATTERN = /\b(?:npm\s+(?:ci|install)|pnpm\s+install|yarn\s+install|bun\s+install)\b/;
+
 function slugify(value) {
   return String(value || '')
     .toLowerCase()
@@ -33,6 +44,22 @@ function slugify(value) {
     .slice(0, 60) || 'app';
 }
 
+function nodeBootstrapCommand(targetDir) {
+  if (!fs.existsSync(path.join(targetDir, 'package.json'))) return null;
+  for (const [marker, command] of NODE_INSTALL_COMMANDS) {
+    if (fs.existsSync(path.join(targetDir, marker))) return command;
+  }
+  return 'npm install';
+}
+
+function prepareBuildCommand(targetDir, buildCommand) {
+  const cleanedBuild = cleanString(buildCommand);
+  const bootstrap = nodeBootstrapCommand(targetDir);
+  if (!bootstrap) return cleanedBuild || null;
+  if (cleanedBuild && NODE_INSTALL_PATTERN.test(cleanedBuild)) return cleanedBuild;
+  return cleanedBuild ? `${bootstrap} && ${cleanedBuild}` : bootstrap;
+}
+
 function exportAppEntry(appId, options = {}) {
   const app = getApp(appId);
   if (!app) throw new Error(`App not found: ${appId}`);
@@ -62,6 +89,9 @@ function exportAppEntry(appId, options = {}) {
       skipped: packed.skipped,
     },
     skipped: packed.skipped,
+    // Export-time only (never stored in the bundle): lets the exporter bind
+    // tool paths that live inside this app's directory.
+    sourceCwd: app.cwd,
   };
 }
 
@@ -96,11 +126,12 @@ function materializeAppEntry(entry, options = {}) {
   if (!cleanString(options.rootDir)) throw new Error('rootDir is required');
   const targetDir = allocateInstallDir(path.resolve(options.rootDir), entry.app.name);
   unpackAppFiles(entry.files, targetDir);
+  const buildCommand = prepareBuildCommand(targetDir, entry.app.buildCommand);
   return {
     name: entry.app.name || 'App',
     description: entry.app.description || '',
     cwd: targetDir,
-    build_command: entry.app.buildCommand || null,
+    build_command: buildCommand,
     start_command: entry.app.startCommand,
     autostart: entry.app.autostart !== false,
     keep_alive: entry.app.keepAlive !== false,
@@ -114,7 +145,10 @@ function materializeAppEntry(entry, options = {}) {
 async function installAppEntry(entry, options = {}) {
   const register = options.register || registerApp;
   const input = materializeAppEntry(entry, options);
-  return register(input);
+  const record = await register(input);
+  // The materialized directory anchors app-bound tool path rewrites; make
+  // sure it survives register implementations that omit cwd.
+  return { ...record, cwd: record?.cwd || input.cwd };
 }
 
 module.exports = {