amalgm 0.1.153 → 0.1.154

package/runtime/scripts/amalgm-mcp/apps/portable.js

@@ -0,0 +1,334 @@
+'use strict';
+
+/**
+ * The portable-app boundary owned by Apps.
+ *
+ * Registration validates this package, sharing serializes it, and bundle
+ * install materializes it. Keeping those paths on one implementation makes
+ * portability a property of the app instead of a sharing-time guess.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { APP_MANIFEST_FILE, readAppManifest } = require('./manifest');
+
+const DEFAULT_MAX_FILE_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_TOTAL_BYTES = 12 * 1024 * 1024;
+
+const PLATFORM_EXCLUDED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.hg',
+  '.svn',
+  '.amalgm',
+]);
+
+const PLATFORM_EXCLUDED_FILES = new Set([
+  '.DS_Store',
+  'Thumbs.db',
+  '.npmrc',
+  '.yarnrc',
+  '.pypirc',
+  '.netrc',
+  'credentials.json',
+  'service-account.json',
+]);
+
+function toPosixPath(value) {
+  return String(value || '').split(path.sep).join('/');
+}
+
+function normalizePattern(value, field) {
+  let pattern = String(value || '').trim().replace(/\\/g, '/');
+  while (pattern.startsWith('./')) pattern = pattern.slice(2);
+  pattern = pattern.replace(/\/{2,}/g, '/');
+  if (!pattern || pattern.startsWith('/') || /^[A-Za-z]:\//.test(pattern)) {
+    throw new Error(`${field} must be relative to the app directory: ${value}`);
+  }
+  if (pattern.split('/').includes('..')) {
+    throw new Error(`${field} cannot leave the app directory: ${value}`);
+  }
+  return pattern.endsWith('/') ? `${pattern}**` : pattern;
+}
+
+function globRegex(pattern) {
+  let source = '^';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === '*') {
+      if (pattern[index + 1] === '*') {
+        index += 1;
+        if (pattern[index + 1] === '/') {
+          index += 1;
+          source += '(?:.*/)?';
+        } else {
+          source += '.*';
+        }
+      } else {
+        source += '[^/]*';
+      }
+    } else if (char === '?') {
+      source += '[^/]';
+    } else {
+      source += char.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+    }
+  }
+  return new RegExp(`${source}$`);
+}
+
+function compilePatterns(values, field) {
+  return values.map((value, index) => {
+    const pattern = normalizePattern(value, `${field}[${index}]`);
+    return { pattern, regex: globRegex(pattern), matched: false };
+  });
+}
+
+function firstMatch(compiled, relativePath) {
+  return compiled.find((entry) => entry.regex.test(relativePath)) || null;
+}
+
+function directorySelection(compiled, relativeDir) {
+  const probes = [
+    `${relativeDir}/__amalgm_file__`,
+    `${relativeDir}/nested/__amalgm_file__`,
+  ];
+  return compiled.find((entry) => (
+    entry.pattern.startsWith(`${relativeDir}/`)
+    || probes.some((probe) => entry.regex.test(probe))
+  )) || null;
+}
+
+function isPlatformExcludedFile(relativePath) {
+  const name = path.posix.basename(relativePath);
+  if (PLATFORM_EXCLUDED_FILES.has(name)) return true;
+  if (name === '.env' || name.startsWith('.env.')) return true;
+  if (name.endsWith('.log') || name.endsWith('.pem') || name.endsWith('.key')) return true;
+  return relativePath === '.ssh' || relativePath.startsWith('.ssh/');
+}
+
+function isBinary(buffer) {
+  const sample = buffer.subarray(0, 8192);
+  if (sample.includes(0)) return true;
+  return !buffer.equals(Buffer.from(buffer.toString('utf8'), 'utf8'));
+}
+
+function packagePortableApp(rootDir, options = {}) {
+  const root = path.resolve(rootDir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`App directory not found: ${root}`);
+  }
+
+  const manifest = readAppManifest(root);
+  const include = compilePatterns(manifest.package.include, 'package.include');
+  const exclude = compilePatterns(manifest.package.exclude, 'package.exclude');
+  if (firstMatch(exclude, APP_MANIFEST_FILE)) {
+    throw new Error(`${APP_MANIFEST_FILE} cannot be excluded; it is part of every portable app`);
+  }
+
+  const maxFileBytes = options.maxFileBytes || DEFAULT_MAX_FILE_BYTES;
+  const maxTotalBytes = options.maxTotalBytes || DEFAULT_MAX_TOTAL_BYTES;
+  const includeContent = options.includeContent === true;
+  const files = [];
+  const excluded = [];
+  const errors = [];
+  let totalBytes = 0;
+
+  function addFile(absolute, relative) {
+    const stat = fs.statSync(absolute);
+    if (stat.size > maxFileBytes) {
+      errors.push(`${relative} is ${stat.size} bytes; the per-file limit is ${maxFileBytes}`);
+      return;
+    }
+    if (totalBytes + stat.size > maxTotalBytes) {
+      errors.push(`adding ${relative} would exceed the ${maxTotalBytes}-byte app package limit`);
+      return;
+    }
+
+    const record = { path: relative, size: stat.size };
+    if (includeContent) {
+      const buffer = fs.readFileSync(absolute);
+      const binary = isBinary(buffer);
+      record.encoding = binary ? 'base64' : 'utf8';
+      record.content = binary ? buffer.toString('base64') : buffer.toString('utf8');
+      if (stat.mode & 0o111) record.executable = true;
+    }
+    totalBytes += stat.size;
+    files.push(record);
+  }
+
+  function visit(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+      .sort((left, right) => left.name.localeCompare(right.name));
+    for (const dirent of entries) {
+      const absolute = path.join(dir, dirent.name);
+      const relative = toPosixPath(path.relative(root, absolute));
+
+      if (dirent.isSymbolicLink()) {
+        const selected = firstMatch(include, relative) || directorySelection(include, relative);
+        if (selected) {
+          selected.matched = true;
+          excluded.push({ path: relative, reason: 'symlink' });
+        }
+        continue;
+      }
+
+      if (dirent.isDirectory()) {
+        if (PLATFORM_EXCLUDED_DIRS.has(dirent.name)) {
+          const selected = directorySelection(include, relative);
+          if (selected) {
+            selected.matched = true;
+            excluded.push({ path: `${relative}/`, reason: 'platform-excluded' });
+          }
+          continue;
+        }
+        visit(absolute);
+        continue;
+      }
+      if (!dirent.isFile()) continue;
+
+      const includedBy = firstMatch(include, relative);
+      if (!includedBy && relative !== APP_MANIFEST_FILE) continue;
+      if (includedBy) includedBy.matched = true;
+
+      const excludedBy = firstMatch(exclude, relative);
+      if (excludedBy) {
+        excludedBy.matched = true;
+        excluded.push({ path: relative, reason: 'manifest-excluded' });
+        continue;
+      }
+      if (relative !== APP_MANIFEST_FILE && isPlatformExcludedFile(relative)) {
+        excluded.push({ path: relative, reason: 'platform-excluded' });
+        continue;
+      }
+      addFile(absolute, relative);
+    }
+  }
+
+  visit(root);
+
+  for (const entry of include) {
+    if (!entry.matched && !entry.regex.test(APP_MANIFEST_FILE)) {
+      errors.push(`package.include pattern matched no files: ${entry.pattern}`);
+    }
+  }
+  if (files.every((file) => file.path === APP_MANIFEST_FILE)) {
+    errors.push('package.include selected no portable app files');
+  }
+  if (errors.length > 0) {
+    throw new Error(`App package is invalid:\n- ${errors.join('\n- ')}`);
+  }
+
+  files.sort((left, right) => left.path.localeCompare(right.path));
+  excluded.sort((left, right) => left.path.localeCompare(right.path));
+  return { rootDir: root, manifest, files, totalBytes, excluded };
+}
+
+function inspectPortableApp(rootDir, options = {}) {
+  return packagePortableApp(rootDir, { ...options, includeContent: false });
+}
+
+function packPortableApp(rootDir, options = {}) {
+  return packagePortableApp(rootDir, { ...options, includeContent: true });
+}
+
+function portabilityStatus(rootDir) {
+  try {
+    const result = inspectPortableApp(rootDir);
+    return { portable: true, files: result.files.length, totalBytes: result.totalBytes };
+  } catch (error) {
+    return { portable: false, error: error.message };
+  }
+}
+
+function assertInsideTarget(targetRoot, relativePath) {
+  const normalized = String(relativePath || '');
+  const resolved = path.resolve(targetRoot, normalized);
+  if (resolved !== targetRoot && !resolved.startsWith(targetRoot + path.sep)) {
+    throw new Error(`App file escapes the install directory: ${normalized}`);
+  }
+  return resolved;
+}
+
+function decodePackedFile(file) {
+  if (!file || typeof file.path !== 'string' || typeof file.content !== 'string') {
+    throw new Error('App files must include path and content strings');
+  }
+  if (
+    !file.path
+    || file.path.includes('\\')
+    || path.posix.isAbsolute(file.path)
+    || /^[A-Za-z]:/.test(file.path)
+    || file.path.split('/').includes('..')
+    || path.posix.normalize(file.path) !== file.path
+    || file.path === '.'
+  ) {
+    throw new Error(`Invalid app file path: ${file.path}`);
+  }
+  if (file.encoding !== 'utf8' && file.encoding !== 'base64') {
+    throw new Error(`Unsupported app file encoding for ${file.path}: ${file.encoding}`);
+  }
+
+  let buffer;
+  if (file.encoding === 'base64') {
+    const normalized = file.content.replace(/=+$/, '');
+    buffer = Buffer.from(file.content, 'base64');
+    if (buffer.toString('base64').replace(/=+$/, '') !== normalized) {
+      throw new Error(`Invalid base64 app file content: ${file.path}`);
+    }
+  } else {
+    buffer = Buffer.from(file.content, 'utf8');
+  }
+  if (!Number.isInteger(file.size) || file.size !== buffer.length) {
+    throw new Error(`App file size does not match content: ${file.path}`);
+  }
+  return buffer;
+}
+
+function validatePackedAppFiles(files, options = {}) {
+  if (!Array.isArray(files) || files.length === 0) throw new Error('App bundle must include files');
+
+  const maxFileBytes = options.maxFileBytes || DEFAULT_MAX_FILE_BYTES;
+  const maxTotalBytes = options.maxTotalBytes || DEFAULT_MAX_TOTAL_BYTES;
+  const seen = new Set();
+  const decoded = [];
+  let totalBytes = 0;
+
+  for (const file of files) {
+    if (seen.has(file?.path)) throw new Error(`Duplicate app file in bundle: ${file?.path}`);
+    const buffer = decodePackedFile(file);
+    seen.add(file.path);
+    if (buffer.length > maxFileBytes) {
+      throw new Error(`${file.path} exceeds the ${maxFileBytes}-byte app file limit`);
+    }
+    totalBytes += buffer.length;
+    if (totalBytes > maxTotalBytes) {
+      throw new Error(`App files exceed the ${maxTotalBytes}-byte package limit`);
+    }
+    decoded.push({ file, buffer });
+  }
+  return { decoded, totalBytes };
+}
+
+function unpackAppFiles(files, targetDir) {
+  const targetRoot = path.resolve(targetDir);
+  const { decoded } = validatePackedAppFiles(files);
+  fs.mkdirSync(targetRoot, { recursive: true });
+
+  let written = 0;
+  for (const { file, buffer } of decoded) {
+    const destination = assertInsideTarget(targetRoot, file.path);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.writeFileSync(destination, buffer, { mode: file.executable ? 0o755 : 0o644 });
+    written += 1;
+  }
+  return { written, targetDir: targetRoot };
+}
+
+module.exports = {
+  inspectPortableApp,
+  packPortableApp,
+  portabilityStatus,
+  unpackAppFiles,
+  validatePackedAppFiles,
+};

package/runtime/scripts/amalgm-mcp/apps/rest.js

@@ -4,6 +4,7 @@
 
 const { getApp, getConnectedRoutes, loadApps, updateAppMeta } = require('./store');
 const { healthSnapshot, recordHeartbeat, recordReady } = require('./health');
+const { hasAppManifest } = require('./manifest');
 const {
   deleteApp,
   connectDns,
@@ -122,7 +123,14 @@ async function handleUpdate(body, sendJson, options = {}) {
   try {
     const appId = appIdFromBody(body);
     if (!appId) return sendJson(400, { error: 'app_id is required' });
-    if (!getApp(appId)) return sendJson(404, { error: 'App not found' });
+    const current = getApp(appId);
+    if (!current) return sendJson(404, { error: 'App not found' });
+
+    if (hasAppManifest(current.cwd)) {
+      return sendJson(400, {
+        error: 'This app reads name, description, and tool_ids from amalgm.app.json; edit the manifest and redeploy',
+      });
+    }
 
     const updates = {};
     if (typeof body?.name === 'string' && body.name.trim()) updates.name = body.name.trim();

package/runtime/scripts/amalgm-mcp/apps/supervisor.js

@@ -8,10 +8,12 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn } = require('child_process');
-const { APPS_DIR, DEFAULT_CWD } = require('../config');
+const { APPS_DIR } = require('../config');
 const { runtimePort } = require('../../../lib/runtime-manifest');
 const { syncAppRoutesToGateway } = require('./advertise');
 const { clearAppHealth } = require('./health');
+const { hasAppManifest } = require('./manifest');
+const { inspectPortableApp } = require('./portable');
 const {
   allocatePort,
   allocateUniqueAppRef,
@@ -535,12 +537,29 @@ function clearAppLinkFromTools(appId) {
 }
 
 async function registerApp(input) {
-  const name = String(input.name || '').trim() || 'App';
-  const cwd = path.resolve(input.cwd || input.root_dir || DEFAULT_CWD);
-  const startCommand = String(input.start_command || input.startCommand || '').trim();
-  if (!startCommand) throw new Error('start_command is required');
+  const requestedCwd = input.cwd || input.root_dir;
+  if (!requestedCwd || !String(requestedCwd).trim()) throw new Error('cwd is required');
+  const cwd = path.resolve(requestedCwd);
   if (!fs.existsSync(cwd)) throw new Error(`cwd does not exist: ${cwd}`);
 
+  const legacyFields = [
+    'name',
+    'description',
+    'build_command',
+    'buildCommand',
+    'start_command',
+    'startCommand',
+    'tool_ids',
+    'toolIds',
+  ].filter((field) => input[field] !== undefined);
+  if (legacyFields.length > 0) {
+    throw new Error(
+      `App registration reads ${legacyFields.join(', ')} from amalgm.app.json; remove those fields from the request`,
+    );
+  }
+
+  const { manifest } = inspectPortableApp(cwd);
+
   const port = allocatePort(input.port);
   if (!port) throw new Error('No valid app port available');
 
@@ -549,19 +568,19 @@ async function registerApp(input) {
   const app = {
     id: input.id || cryptoRandomId(),
     kind: 'app',
-    name,
-    description: input.description || '',
+    name: manifest.name,
+    description: manifest.description,
     cwd,
     port,
-    buildCommand: input.build_command || input.buildCommand || null,
-    startCommand,
+    buildCommand: manifest.buildCommand,
+    startCommand: manifest.startCommand,
     appRef,
     app_ref: appRef,
     publicUrl: publicUrlForRef(appRef),
     dnsConnected: input.connect_dns !== false,
     autostart: input.autostart !== false,
     keepAlive: input.keep_alive !== false,
-    toolIds: Array.isArray(input.tool_ids || input.toolIds) ? (input.tool_ids || input.toolIds) : [],
+    toolIds: manifest.toolIds,
     desiredState: 'running',
     status: 'registered',
     pid: null,
@@ -576,10 +595,16 @@ async function registerApp(input) {
   data.apps.push(app);
   saveApps(data);
 
-  if (app.buildCommand) await runBuild(app);
-  await startApp(app.id);
-  const deployed = updateAppMeta(app.id, { lastDeployedAt: new Date().toISOString() });
-  return deployed;
+  try {
+    if (app.buildCommand) await runBuild(app);
+    await startApp(app.id);
+    return updateAppMeta(app.id, { lastDeployedAt: new Date().toISOString() });
+  } catch (error) {
+    const current = loadApps();
+    current.apps = current.apps.filter((item) => item.id !== app.id);
+    saveApps(current, { source: 'apps:register-failed' });
+    throw new Error(`App registration failed: ${error.message}`);
+  }
 }
 
 async function redeployApp(appId, updates = {}) {
@@ -595,10 +620,32 @@ async function redeployApp(appId, updates = {}) {
     }
     patch.port = parsed;
   }
-  if (updates.build_command !== undefined) patch.buildCommand = updates.build_command || null;
-  if (updates.start_command !== undefined) patch.startCommand = updates.start_command;
   if (updates.keep_alive !== undefined) patch.keepAlive = updates.keep_alive !== false;
   if (updates.autostart !== undefined) patch.autostart = updates.autostart !== false;
+
+  const nextCwd = patch.cwd || app.cwd;
+  if (hasAppManifest(nextCwd)) {
+    const legacyFields = ['build_command', 'start_command', 'tool_ids']
+      .filter((field) => updates[field] !== undefined);
+    if (legacyFields.length > 0) {
+      throw new Error(
+        `Redeploy reads ${legacyFields.join(', ')} from amalgm.app.json; edit the manifest instead`,
+      );
+    }
+    const { manifest } = inspectPortableApp(nextCwd);
+    Object.assign(patch, {
+      name: manifest.name,
+      description: manifest.description,
+      buildCommand: manifest.buildCommand,
+      startCommand: manifest.startCommand,
+      toolIds: manifest.toolIds,
+    });
+  } else {
+    // Pre-manifest apps remain operable. They can start, stop, and redeploy,
+    // but sharing rejects them until their project gains a valid manifest.
+    if (updates.build_command !== undefined) patch.buildCommand = updates.build_command || null;
+    if (updates.start_command !== undefined) patch.startCommand = updates.start_command;
+  }
   if (Object.keys(patch).length > 0) app = updateAppMeta(appId, patch);
 
   if (!app.startCommand) throw new Error('startCommand is required');

package/runtime/scripts/amalgm-mcp/apps/tools.js

@@ -9,6 +9,7 @@
 const { textResult, errorResult } = require('../lib/tool-result');
 const { getConnectedRoutes, loadApps } = require('./store');
 const { healthSnapshot } = require('./health');
+const { inspectPortableApp, portabilityStatus } = require('./portable');
 const {
   connectDns,
   disconnectDns,
@@ -28,6 +29,7 @@ function healthSummary(app) {
 }
 
 function appSummary(app) {
+  const portability = portabilityStatus(app.cwd);
   return [
     `${app.name} (${app.id})`,
     `status: ${app.status}`,
@@ -36,6 +38,9 @@ function appSummary(app) {
     `dns: ${app.dnsConnected ? app.publicUrl : 'disconnected'}`,
     `autostart: ${app.autostart !== false}`,
     `keepAlive: ${app.keepAlive !== false}`,
+    portability.portable
+      ? `portable: yes (${portability.files} files, ${portability.totalBytes} bytes)`
+      : `portable: no (${String(portability.error || 'invalid app package').split('\n')[0]})`,
     healthSummary(app),
     app.error ? `error: ${app.error}` : null,
   ].filter(Boolean).join('\n');
@@ -45,21 +50,17 @@ module.exports = [
   {
     name: 'apps_register',
     description:
-      'Register a user-hosted app from an existing project on this computer. Apps should be production services: prefer passing a build_command such as "npm run build" and a production start_command such as "npm run start -- --host 0.0.0.0 --port {port}" or any command that binds to PORT/{port}. The MCP does not scaffold or enforce a framework; it stores the record in ~/.amalgm, starts it, keeps it alive while the computer is on, and connects it to app DNS by default.',
+      'Validate and register a user-hosted app from an existing project. The project must contain amalgm.app.json; that manifest is the single source of truth for name, description, buildCommand, startCommand, toolIds, and portable package files. Registration fails before storing the app if the manifest or package is invalid, then runs the declared build, starts the app, keeps it alive, and connects app DNS by default.',
     inputSchema: {
       type: 'object',
       properties: {
-        name: { type: 'string', description: 'Human-readable app name' },
-        cwd: { type: 'string', description: 'Project directory on this computer' },
+        cwd: { type: 'string', description: 'Project directory containing amalgm.app.json' },
         port: { type: 'number', description: 'Port the app should bind to. If omitted, one is allocated.' },
-        build_command: { type: 'string', description: 'Optional production build command, run before start/redeploy' },
-        start_command: { type: 'string', description: 'Required production start command. Use {port} or PORT.' },
-        description: { type: 'string' },
         connect_dns: { type: 'boolean', description: 'Whether to expose through app DNS immediately. Defaults true.' },
         autostart: { type: 'boolean', description: 'Start on Amalgm boot. Defaults true.' },
         keep_alive: { type: 'boolean', description: 'Restart if the process exits. Defaults true.' },
       },
-      required: ['start_command'],
+      required: ['cwd'],
     },
     async handler(args) {
       try {
@@ -70,6 +71,32 @@ module.exports = [
       }
     },
   },
+  {
+    name: 'apps_validate',
+    description:
+      'Dry-run the exact app package used by registration and sharing. Validates amalgm.app.json, resolves package.include/package.exclude, applies platform credential and dependency exclusions, and reports the files and byte size without registering or starting the app.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: 'Project directory containing amalgm.app.json' },
+      },
+      required: ['cwd'],
+    },
+    async handler(args) {
+      try {
+        const result = inspectPortableApp(args.cwd);
+        return textResult(JSON.stringify({
+          portable: true,
+          manifest: result.manifest,
+          files: result.files,
+          totalBytes: result.totalBytes,
+          excluded: result.excluded,
+        }, null, 2));
+      } catch (err) {
+        return errorResult(err.message);
+      }
+    },
+  },
   {
     name: 'apps_list',
     description: 'List locally registered apps from ~/.amalgm/apps.json.',
@@ -92,15 +119,15 @@ module.exports = [
   {
     name: 'apps_redeploy',
     description:
-      'Redeploy an app: optionally update cwd/build/start/port settings, run its build command if configured, then restart the production process. DNS connection state is preserved.',
+      'Redeploy an app. Manifest apps reread and validate amalgm.app.json, update their stored metadata/commands/tool ids, run buildCommand, and restart. cwd, port, and lifecycle settings may be updated; build_command/start_command are accepted only for pre-manifest legacy apps. DNS connection state is preserved.',
     inputSchema: {
       type: 'object',
       properties: {
         app_id: { type: 'string' },
         cwd: { type: 'string' },
         port: { type: 'number' },
-        build_command: { type: 'string' },
-        start_command: { type: 'string' },
+        build_command: { type: 'string', description: 'Legacy apps only; manifest apps read buildCommand from amalgm.app.json.' },
+        start_command: { type: 'string', description: 'Legacy apps only; manifest apps read startCommand from amalgm.app.json.' },
         autostart: { type: 'boolean' },
         keep_alive: { type: 'boolean' },
       },