amalgm 0.1.153 → 0.1.154

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.153",
+  "version": "0.1.154",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

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

@@ -3,11 +3,10 @@
 /**
  * Portable app bundle entries.
  *
- * An exported entry carries the app's registration record (commands, lifecycle
- * flags) plus its packed file tree. Machine-bound state — cwd, port, appRef,
- * public URL, pid/status — stays behind: install writes the files into a fresh
- * local directory and registers through the normal supervisor path, which
- * allocates a new port and DNS ref, runs the build, and starts the process.
+ * The app manifest is canonical. An exported entry carries that manifest and
+ * its selected files; install writes them into a fresh directory and calls the
+ * normal Apps registration path, which validates, builds, starts, and routes
+ * the recipient's copy.
  */
 
 const fs = require('fs');
@@ -15,37 +14,12 @@ const path = require('path');
 
 const { getApp } = require('../apps/store');
 const { registerApp } = require('../apps/supervisor');
-const { packAppFiles, unpackAppFiles } = require('./app-files');
+const { inspectPortableApp, packPortableApp, unpackAppFiles } = require('../apps/portable');
 
 function isObject(value) {
   return !!value && typeof value === 'object' && !Array.isArray(value);
 }
 
-function cleanString(value) {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-function uniqueToolIds(value) {
-  if (!Array.isArray(value)) return [];
-  const out = [];
-  for (const item of value) {
-    const id = cleanString(item);
-    if (id && !out.includes(id)) out.push(id);
-  }
-  return out;
-}
-
-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()
@@ -54,54 +28,39 @@ 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}`);
-  if (!cleanString(app.startCommand)) {
-    throw new Error(`App has no start command and cannot be shared: ${appId}`);
-  }
   if (!app.cwd) throw new Error(`App has no working directory: ${appId}`);
 
-  const packed = packAppFiles(app.cwd, options);
-  if (packed.files.length === 0) {
-    throw new Error(`App directory has no shareable files: ${app.cwd}`);
+  let packed;
+  try {
+    packed = packPortableApp(app.cwd, options);
+  } catch (error) {
+    throw new Error(`App ${app.name || appId} is not portable: ${error.message}`);
   }
+  const { manifest } = packed;
 
   return {
     entry: {
       sourceAppId: app.id,
+      manifest,
+      // Derived summary for bundle renderers. Install never trusts this copy;
+      // it reads the materialized amalgm.app.json through Apps registration.
       app: {
-        name: app.name || 'App',
-        description: app.description || '',
-        buildCommand: app.buildCommand || null,
-        startCommand: app.startCommand,
-        autostart: app.autostart !== false,
-        keepAlive: app.keepAlive !== false,
+        name: manifest.name,
+        description: manifest.description,
+        buildCommand: manifest.buildCommand,
+        startCommand: manifest.startCommand,
+        autostart: true,
+        keepAlive: true,
       },
-      // Tools that belong to this app; ids are stable across install, so the
-      // recipient's registration points at the same tool ids.
-      toolIds: uniqueToolIds(app.toolIds),
+      toolIds: manifest.toolIds,
       files: packed.files,
       totalBytes: packed.totalBytes,
-      skipped: packed.skipped,
+      skipped: packed.excluded,
     },
-    skipped: packed.skipped,
+    skipped: packed.excluded,
     // Export-time only (never stored in the bundle): lets the exporter bind
     // tool paths that live inside this app's directory.
     sourceCwd: app.cwd,
@@ -110,10 +69,6 @@ function exportAppEntry(appId, options = {}) {
 
 function assertInstallableEntry(entry) {
   if (!isObject(entry)) throw new Error('app entry must be an object');
-  if (!isObject(entry.app)) throw new Error('app entry is missing its app record');
-  if (!cleanString(entry.app.startCommand)) {
-    throw new Error('app entry must include a start command');
-  }
   if (!Array.isArray(entry.files) || entry.files.length === 0) {
     throw new Error('app entry must include files');
   }
@@ -136,17 +91,15 @@ function allocateInstallDir(rootDir, name) {
  */
 function materializeAppEntry(entry, options = {}) {
   assertInstallableEntry(entry);
-  if (!cleanString(options.rootDir)) throw new Error('rootDir is required');
-  const targetDir = allocateInstallDir(path.resolve(options.rootDir), entry.app.name);
+  if (typeof options.rootDir !== 'string' || !options.rootDir.trim()) throw new Error('rootDir is required');
+  const targetDir = allocateInstallDir(path.resolve(options.rootDir), entry.manifest?.name || entry.app?.name);
   unpackAppFiles(entry.files, targetDir);
-  const buildCommand = prepareBuildCommand(targetDir, entry.app.buildCommand);
+  const portable = inspectPortableApp(targetDir);
+  if (entry.manifest && JSON.stringify(entry.manifest) !== JSON.stringify(portable.manifest)) {
+    throw new Error('App bundle manifest summary does not match amalgm.app.json');
+  }
   return {
-    name: entry.app.name || 'App',
-    description: entry.app.description || '',
     cwd: targetDir,
-    build_command: buildCommand,
-    start_command: entry.app.startCommand,
-    tool_ids: uniqueToolIds(entry.toolIds),
     // A downloaded app is a fresh registration: it should come up now and
     // keep coming back with the recipient runtime.
     autostart: true,
@@ -161,7 +114,13 @@ function materializeAppEntry(entry, options = {}) {
 async function installAppEntry(entry, options = {}) {
   const register = options.register || registerApp;
   const input = materializeAppEntry(entry, options);
-  const record = await register(input);
+  let record;
+  try {
+    record = await register(input);
+  } catch (error) {
+    fs.rmSync(input.cwd, { recursive: true, force: true });
+    throw error;
+  }
   // 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 };

package/runtime/scripts/amalgm-mcp/agent-bundles/export.js

@@ -155,7 +155,7 @@ function bundleTitleAndDescription(agents, automations, apps, sharedTools) {
   return { title: 'Shared bundle', description: '' };
 }
 
-function bundleWarnings({ hooks, tools, automations, apps, skippedAppFiles }) {
+function bundleWarnings({ hooks, tools, automations, apps, excludedAppFiles }) {
   return [
     'Instructions, skill text, tool descriptions, and hook commands are shared as plain text.',
     'Secrets pasted into free-text instructions or files are not automatically detected.',
@@ -163,7 +163,7 @@ function bundleWarnings({ hooks, tools, automations, apps, skippedAppFiles }) {
     ...(tools > 0 ? ['Tools can call external services or local commands. Recipients should reconnect credentials on their own machine.'] : []),
     ...(automations > 0 ? ['This bundle includes automations. Their workflows run code and call tools on the importing machine — review workflow scripts before importing.'] : []),
     ...(apps > 0 ? ['This bundle includes apps. Their build and start commands execute on install — review commands before importing.'] : []),
-    ...(skippedAppFiles > 0 ? [`${skippedAppFiles} app file${skippedAppFiles === 1 ? ' was' : 's were'} excluded from the bundle (dependencies, build outputs, env files, or size limits). Builds re-run on install.`] : []),
+    ...(excludedAppFiles > 0 ? [`${excludedAppFiles} app path${excludedAppFiles === 1 ? ' was' : 's were'} excluded by the app manifest or platform safety rules.`] : []),
   ];
 }
 
@@ -238,13 +238,13 @@ function createBundle(input = {}, options = {}) {
 
   const apps = [];
   const appCwdBySourceId = new Map();
-  let skippedAppFiles = 0;
+  let excludedAppFiles = 0;
   const appToolIds = [];
   for (const appId of [...appIds, ...dependencyAppIds]) {
     const exported = exportAppEntry(appId);
     apps.push(exported.entry);
     appCwdBySourceId.set(exported.entry.sourceAppId, exported.sourceCwd);
-    skippedAppFiles += exported.skipped.length;
+    excludedAppFiles += exported.skipped.length;
     // App → tool closure: tools that belong to a bundled app travel with it.
     appToolIds.push(...(exported.entry.toolIds || []));
   }
@@ -276,7 +276,7 @@ function createBundle(input = {}, options = {}) {
       tools: tools.length,
       automations: automations.length,
       apps: apps.length,
-      skippedAppFiles,
+      excludedAppFiles,
     }),
     ...appLinkWarnings,
   ];

package/runtime/scripts/amalgm-mcp/agent-bundles/graph.js

@@ -164,6 +164,7 @@ function standaloneToolIds(bundle) {
 function appElementData(entry) {
   return {
     sourceAppId: appEntryId(entry),
+    manifest: cloneJson(entry.manifest || {}),
     app: cloneJson(entry.app || {}),
     files: (Array.isArray(entry.files) ? entry.files : []).map((file) => ({
       path: file.path,

package/runtime/scripts/amalgm-mcp/agent-bundles/install.js

@@ -6,6 +6,8 @@ const { upsertAgentConfig, agentFieldsFromConfig } = require('../agent-config/st
 const { normalizeAgentConfig } = require('../agent-config/schema');
 const { createAgent, getAllAgentsWithBuiltins } = require('../agents/store');
 const { defaultToolboxService } = require('../toolbox/service');
+const { APP_MANIFEST_FILE, normalizeAppManifest } = require('../apps/manifest');
+const { validatePackedAppFiles } = require('../apps/portable');
 const { installAutomationEntry } = require('./automation-entries');
 const { installAppEntry } = require('./app-entries');
 const { rewriteAppBoundPaths } = require('./tool-bindings');
@@ -15,6 +17,7 @@ const {
   LEGACY_AGENT_BUNDLE_KIND,
   agentEntryId,
   appEntryId,
+  automationEntryId,
   isObject,
   nowIso,
   standaloneToolIds,
@@ -22,6 +25,55 @@ const {
   withBundleGraph,
 } = require('./graph');
 
+function assertUniqueRecords(label, records, idForRecord) {
+  const seen = new Set();
+  for (const record of records) {
+    const id = idForRecord(record);
+    if (!id) throw new Error(`${label} entries must include ids`);
+    if (seen.has(id)) throw new Error(`Bundle contains duplicate ${label} id: ${id}`);
+    seen.add(id);
+  }
+}
+
+function assertPortableAppEntry(entry) {
+  const files = Array.isArray(entry?.files) ? entry.files : [];
+  const validated = validatePackedAppFiles(files);
+  if (entry.totalBytes !== validated.totalBytes) {
+    throw new Error(`Bundle app ${appEntryId(entry) || '(unknown)'} totalBytes does not match its files`);
+  }
+  const manifestFiles = files.filter((file) => file?.path === APP_MANIFEST_FILE);
+  if (manifestFiles.length !== 1) {
+    throw new Error(`Bundle app ${appEntryId(entry) || '(unknown)'} must contain exactly one ${APP_MANIFEST_FILE}`);
+  }
+  const manifestFile = manifestFiles[0];
+  if (manifestFile.encoding !== 'utf8' || typeof manifestFile.content !== 'string') {
+    throw new Error(`${APP_MANIFEST_FILE} must be a UTF-8 app file`);
+  }
+
+  let manifest;
+  try {
+    manifest = normalizeAppManifest(JSON.parse(manifestFile.content));
+  } catch (error) {
+    throw new Error(`Bundle app ${appEntryId(entry) || '(unknown)'} has an invalid manifest: ${error.message}`);
+  }
+
+  if (JSON.stringify(entry.manifest) !== JSON.stringify(manifest)) {
+    throw new Error(`Bundle app ${appEntryId(entry) || '(unknown)'} manifest summary does not match ${APP_MANIFEST_FILE}`);
+  }
+  if (JSON.stringify(entry.toolIds || []) !== JSON.stringify(manifest.toolIds)) {
+    throw new Error(`Bundle app ${appEntryId(entry) || '(unknown)'} tool ids do not match ${APP_MANIFEST_FILE}`);
+  }
+  const summary = entry.app || {};
+  if (
+    summary.name !== manifest.name
+    || summary.description !== manifest.description
+    || summary.buildCommand !== manifest.buildCommand
+    || summary.startCommand !== manifest.startCommand
+  ) {
+    throw new Error(`Bundle app ${appEntryId(entry) || '(unknown)'} summary does not match ${APP_MANIFEST_FILE}`);
+  }
+}
+
 function uniqueAgentName(name) {
   const base = String(name || 'Imported agent').trim() || 'Imported agent';
   const existing = new Set(
@@ -78,10 +130,18 @@ function validateBundle(bundle) {
   const agents = Array.isArray(bundle.agents) ? bundle.agents : [];
   const automations = Array.isArray(bundle.automations) ? bundle.automations : [];
   const apps = Array.isArray(bundle.apps) ? bundle.apps : [];
+  const tools = Array.isArray(bundle.tools) ? bundle.tools : [];
+  const toolActions = Array.isArray(bundle.toolActions) ? bundle.toolActions : [];
   const toolHeads = standaloneToolIds(bundle);
   if (agents.length === 0 && automations.length === 0 && apps.length === 0 && toolHeads.length === 0) {
     throw new Error('bundle must include at least one agent, automation, app, or tool');
   }
+  assertUniqueRecords('agent', agents, agentEntryId);
+  assertUniqueRecords('automation', automations, automationEntryId);
+  assertUniqueRecords('app', apps, appEntryId);
+  assertUniqueRecords('tool', tools, (tool) => String(tool?.id || '').trim());
+  assertUniqueRecords('tool action', toolActions, (action) => String(action?.id || '').trim());
+  apps.forEach(assertPortableAppEntry);
   if (agents.length > 0) assertClosedAgentBundleGraph(bundle);
   return withBundleGraph(bundle);
 }

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

@@ -0,0 +1,135 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const APP_MANIFEST_FILE = 'amalgm.app.json';
+const APP_MANIFEST_SCHEMA_VERSION = 1;
+
+const TOP_LEVEL_FIELDS = new Set([
+  'schemaVersion',
+  'name',
+  'description',
+  'buildCommand',
+  'startCommand',
+  'toolIds',
+  'package',
+]);
+const PACKAGE_FIELDS = new Set(['include', 'exclude']);
+
+function isObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function cleanString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function uniqueStrings(value, field, errors, options = {}) {
+  if (value === undefined && options.optional) return [];
+  if (!Array.isArray(value)) {
+    errors.push(`${field} must be an array of strings`);
+    return [];
+  }
+
+  const result = [];
+  value.forEach((item, index) => {
+    const cleaned = cleanString(item);
+    if (!cleaned) {
+      errors.push(`${field}[${index}] must be a non-empty string`);
+    } else if (!result.includes(cleaned)) {
+      result.push(cleaned);
+    }
+  });
+  return result;
+}
+
+function unknownFields(value, allowed, prefix) {
+  if (!isObject(value)) return [];
+  return Object.keys(value)
+    .filter((key) => !allowed.has(key))
+    .map((key) => `${prefix}${key} is not supported`);
+}
+
+function normalizeAppManifest(value) {
+  if (!isObject(value)) throw new Error(`${APP_MANIFEST_FILE} must contain a JSON object`);
+
+  const errors = unknownFields(value, TOP_LEVEL_FIELDS, '');
+  if (value.schemaVersion !== APP_MANIFEST_SCHEMA_VERSION) {
+    errors.push(`schemaVersion must be ${APP_MANIFEST_SCHEMA_VERSION}`);
+  }
+
+  const name = cleanString(value.name);
+  if (!name) errors.push('name must be a non-empty string');
+
+  const description = value.description === undefined ? '' : cleanString(value.description);
+  if (value.description !== undefined && typeof value.description !== 'string') {
+    errors.push('description must be a string');
+  }
+
+  const buildCommand = value.buildCommand == null ? null : cleanString(value.buildCommand);
+  if (value.buildCommand != null && !buildCommand) {
+    errors.push('buildCommand must be a non-empty string or null');
+  }
+
+  const startCommand = cleanString(value.startCommand);
+  if (!startCommand) errors.push('startCommand must be a non-empty string');
+
+  const toolIds = uniqueStrings(value.toolIds, 'toolIds', errors, { optional: true });
+
+  if (!isObject(value.package)) {
+    errors.push('package must be an object');
+  } else {
+    errors.push(...unknownFields(value.package, PACKAGE_FIELDS, 'package.'));
+  }
+  const include = uniqueStrings(value.package?.include, 'package.include', errors);
+  const exclude = uniqueStrings(value.package?.exclude, 'package.exclude', errors, { optional: true });
+  if (include.length === 0) errors.push('package.include must select at least one app file');
+
+  if (errors.length > 0) {
+    throw new Error(`${APP_MANIFEST_FILE} is invalid:\n- ${errors.join('\n- ')}`);
+  }
+
+  return {
+    schemaVersion: APP_MANIFEST_SCHEMA_VERSION,
+    name,
+    description,
+    buildCommand,
+    startCommand,
+    toolIds,
+    package: { include, exclude },
+  };
+}
+
+function appManifestPath(rootDir) {
+  return path.join(path.resolve(rootDir), APP_MANIFEST_FILE);
+}
+
+function hasAppManifest(rootDir) {
+  if (typeof rootDir !== 'string' || !rootDir.trim()) return false;
+  return fs.existsSync(appManifestPath(rootDir));
+}
+
+function readAppManifest(rootDir) {
+  const manifestPath = appManifestPath(rootDir);
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`${APP_MANIFEST_FILE} is required for app registration and sharing: ${manifestPath}`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`${APP_MANIFEST_FILE} is not valid JSON: ${error.message}`);
+  }
+  return normalizeAppManifest(parsed);
+}
+
+module.exports = {
+  APP_MANIFEST_FILE,
+  APP_MANIFEST_SCHEMA_VERSION,
+  appManifestPath,
+  hasAppManifest,
+  normalizeAppManifest,
+  readAppManifest,
+};