amalgm 0.0.0 → 0.0.1

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

@@ -0,0 +1,402 @@
+/**
+ * Minimal artifact supervisor.
+ *
+ * Runs user-provided commands. It does not scaffold, wrap, or impose an app
+ * framework. The artifact process is expected to bind to PORT / {port}.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { DEFAULT_CWD } = require('../config');
+const { syncArtifactRoutesToGateway } = require('./advertise');
+const {
+  allocatePort,
+  allocateUniqueArtifactRef,
+  getArtifact,
+  loadArtifacts,
+  publicUrlForRef,
+  saveArtifacts,
+  updateArtifactMeta,
+} = require('./store');
+
+const running = new Map();
+const stopping = new Set();
+const restartTimers = new Map();
+
+const ARTIFACT_ENV_ALLOWLIST = [
+  'PATH',
+  'HOME',
+  'USER',
+  'LOGNAME',
+  'SHELL',
+  'TMPDIR',
+  'TMP',
+  'TEMP',
+  'LANG',
+  'LC_ALL',
+  'LC_CTYPE',
+  'TERM',
+  'NODE_ENV',
+  'COREPACK_HOME',
+  'PNPM_HOME',
+  'YARN_CACHE_FOLDER',
+  'BUN_INSTALL',
+  'PLAYWRIGHT_BROWSERS_PATH',
+];
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function syncRoutesBestEffort(reason) {
+  try {
+    await syncArtifactRoutesToGateway(reason);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`[AmalgmMCP] Artifact route sync failed (${reason}): ${message}`);
+  }
+}
+
+function replacePort(command, port) {
+  return String(command || '').replace(/\{port\}/g, String(port));
+}
+
+function buildEnv(artifact) {
+  const env = {};
+  for (const key of ARTIFACT_ENV_ALLOWLIST) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+
+  return {
+    ...env,
+    PORT: String(artifact.port),
+    AMALGM_ARTIFACT_ID: artifact.id,
+    AMALGM_ARTIFACT_REF: artifact.artifactRef,
+    AMALGM_ARTIFACT_URL: artifact.publicUrl,
+  };
+}
+
+function runCommand(command, cwd, env, timeoutMs = 10 * 60 * 1000) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      cwd,
+      env,
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    let output = '';
+    const timer = setTimeout(() => {
+      try { child.kill('SIGTERM'); } catch {}
+      reject(new Error(`Command timed out after ${Math.round(timeoutMs / 1000)}s`));
+    }, timeoutMs);
+
+    const append = (chunk) => {
+      output += chunk.toString();
+      if (output.length > 12_000) output = output.slice(-12_000);
+    };
+    child.stdout?.on('data', append);
+    child.stderr?.on('data', append);
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        resolve(output);
+      } else {
+        reject(new Error(output.trim() || `Command exited with code ${code}`));
+      }
+    });
+  });
+}
+
+async function runBuild(artifact) {
+  if (!artifact.buildCommand) return;
+  updateArtifactMeta(artifact.id, { status: 'building', error: null });
+  const command = replacePort(artifact.buildCommand, artifact.port);
+  await runCommand(command, artifact.cwd, buildEnv(artifact));
+}
+
+function startArtifactProcess(artifact) {
+  if (!artifact.startCommand) throw new Error('startCommand is required');
+  if (!fs.existsSync(artifact.cwd)) throw new Error(`Artifact cwd does not exist: ${artifact.cwd}`);
+
+  const command = replacePort(artifact.startCommand, artifact.port);
+  const child = spawn(command, {
+    cwd: artifact.cwd,
+    env: buildEnv(artifact),
+    shell: true,
+    detached: process.platform !== 'win32',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+
+  running.set(artifact.id, child);
+  child.unref();
+  child.stdout?.on('data', (chunk) => {
+    console.log(`[Artifact:${artifact.id}] ${chunk.toString().trim()}`);
+  });
+  child.stderr?.on('data', (chunk) => {
+    console.error(`[Artifact:${artifact.id}] ${chunk.toString().trim()}`);
+  });
+  child.on('exit', (code) => {
+    const activeChild = running.get(artifact.id);
+    if (activeChild && activeChild !== child) return;
+    running.delete(artifact.id);
+    const wasStopping = stopping.has(artifact.id);
+    stopping.delete(artifact.id);
+    if (wasStopping) return;
+
+    const current = getArtifact(artifact.id);
+    if (!current) return;
+
+    if (current.desiredState === 'running' && current.keepAlive !== false) {
+      updateArtifactMeta(artifact.id, {
+        status: 'restarting',
+        pid: null,
+        error: code === 0 ? null : `Process exited with code ${code}`,
+      });
+      void syncRoutesBestEffort(`exit:${artifact.id}`);
+      const timer = setTimeout(() => {
+        restartTimers.delete(artifact.id);
+        startArtifact(artifact.id).catch((err) => {
+          updateArtifactMeta(artifact.id, { status: 'error', error: err.message, pid: null });
+        });
+      }, 2000);
+      restartTimers.set(artifact.id, timer);
+      return;
+    }
+
+    updateArtifactMeta(artifact.id, {
+      status: code === 0 ? 'stopped' : 'error',
+      pid: null,
+      error: code === 0 ? null : `Process exited with code ${code}`,
+    });
+    void syncRoutesBestEffort(`exit:${artifact.id}`);
+  });
+
+  return child;
+}
+
+async function startArtifact(artifactId) {
+  const artifact = getArtifact(artifactId);
+  if (!artifact) throw new Error(`Artifact not found: ${artifactId}`);
+  const existingTimer = restartTimers.get(artifactId);
+  if (existingTimer) clearTimeout(existingTimer);
+  restartTimers.delete(artifactId);
+
+  if (running.has(artifactId)) {
+    const current = updateArtifactMeta(artifact.id, {
+      desiredState: 'running',
+      status: 'running',
+      error: null,
+    });
+    await syncRoutesBestEffort(`start:${artifactId}`);
+    return current;
+  }
+
+  if (artifact.pid && isProcessAlive(artifact.pid)) {
+    const current = updateArtifactMeta(artifact.id, {
+      desiredState: 'running',
+      status: 'running',
+      error: null,
+    });
+    await syncRoutesBestEffort(`start:${artifactId}`);
+    return current;
+  }
+
+  if (artifact.pid && !isProcessAlive(artifact.pid)) {
+    updateArtifactMeta(artifact.id, { pid: null });
+  }
+
+  const child = startArtifactProcess(artifact);
+  const current = updateArtifactMeta(artifact.id, {
+    desiredState: 'running',
+    status: 'running',
+    pid: child.pid,
+    error: null,
+    lastStartedAt: new Date().toISOString(),
+  });
+  await syncRoutesBestEffort(`start:${artifactId}`);
+  return current;
+}
+
+async function stopArtifact(artifactId, options = {}) {
+  const artifact = getArtifact(artifactId);
+  if (!artifact) throw new Error(`Artifact not found: ${artifactId}`);
+
+  const timer = restartTimers.get(artifactId);
+  if (timer) clearTimeout(timer);
+  restartTimers.delete(artifactId);
+  stopping.add(artifactId);
+
+  const child = running.get(artifactId);
+  if (child?.pid) {
+    try { process.kill(-child.pid, 'SIGTERM'); } catch {}
+    try { child.kill('SIGTERM'); } catch {}
+  } else if (artifact.pid) {
+    try { process.kill(artifact.pid, 'SIGTERM'); } catch {}
+  }
+  running.delete(artifactId);
+
+  setTimeout(() => stopping.delete(artifactId), 1000);
+  const current = updateArtifactMeta(artifactId, {
+    desiredState: options.desiredState || 'stopped',
+    status: 'stopped',
+    pid: null,
+  });
+  await syncRoutesBestEffort(`stop:${artifactId}`);
+  return current;
+}
+
+async function deleteArtifact(artifactId) {
+  const artifact = getArtifact(artifactId);
+  if (!artifact) throw new Error(`Artifact not found: ${artifactId}`);
+
+  const timer = restartTimers.get(artifactId);
+  if (timer) clearTimeout(timer);
+  restartTimers.delete(artifactId);
+
+  await stopArtifact(artifactId, { desiredState: 'stopped' }).catch(() => {});
+
+  const data = loadArtifacts();
+  data.artifacts = data.artifacts.filter((item) => item.id !== artifactId);
+  saveArtifacts(data);
+
+  stopping.delete(artifactId);
+  running.delete(artifactId);
+  await syncRoutesBestEffort(`delete:${artifactId}`);
+
+  return artifact;
+}
+
+async function registerArtifact(input) {
+  const name = String(input.name || '').trim() || 'Artifact';
+  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');
+  if (!fs.existsSync(cwd)) throw new Error(`cwd does not exist: ${cwd}`);
+
+  const port = allocatePort(input.port);
+  if (!port) throw new Error('No valid artifact port available');
+
+  const artifactRef = allocateUniqueArtifactRef();
+  const now = new Date().toISOString();
+  const artifact = {
+    id: input.id || cryptoRandomId(),
+    kind: 'artifact',
+    name,
+    description: input.description || '',
+    cwd,
+    port,
+    buildCommand: input.build_command || input.buildCommand || null,
+    startCommand,
+    artifactRef,
+    artifact_ref: artifactRef,
+    publicUrl: publicUrlForRef(artifactRef),
+    dnsConnected: input.connect_dns !== false,
+    autostart: input.autostart !== false,
+    keepAlive: input.keep_alive !== false,
+    desiredState: 'running',
+    status: 'registered',
+    pid: null,
+    createdAt: now,
+    updatedAt: now,
+    lastStartedAt: null,
+    lastDeployedAt: null,
+    error: null,
+  };
+
+  const data = loadArtifacts();
+  data.artifacts.push(artifact);
+  saveArtifacts(data);
+
+  if (artifact.buildCommand) await runBuild(artifact);
+  await startArtifact(artifact.id);
+  return updateArtifactMeta(artifact.id, { lastDeployedAt: new Date().toISOString() });
+}
+
+async function redeployArtifact(artifactId, updates = {}) {
+  let artifact = getArtifact(artifactId);
+  if (!artifact) throw new Error(`Artifact not found: ${artifactId}`);
+
+  const patch = {};
+  if (updates.cwd || updates.root_dir) patch.cwd = path.resolve(updates.cwd || updates.root_dir);
+  if (updates.port !== undefined) {
+    const parsed = Number(updates.port);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+      throw new Error('port must be between 1 and 65535');
+    }
+    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;
+  if (Object.keys(patch).length > 0) artifact = updateArtifactMeta(artifactId, patch);
+
+  if (!artifact.startCommand) throw new Error('startCommand is required');
+  if (!fs.existsSync(artifact.cwd)) throw new Error(`cwd does not exist: ${artifact.cwd}`);
+
+  if (artifact.buildCommand) await runBuild(artifact);
+  await stopArtifact(artifactId, { desiredState: 'running' });
+  await startArtifact(artifactId);
+  return updateArtifactMeta(artifactId, { lastDeployedAt: new Date().toISOString() });
+}
+
+function cryptoRandomId() {
+  return `artifact-${Math.random().toString(36).slice(2, 8)}${Date.now().toString(36).slice(-4)}`;
+}
+
+async function connectDns(artifactId) {
+  const artifact = getArtifact(artifactId);
+  if (!artifact) throw new Error(`Artifact not found: ${artifactId}`);
+  const current = updateArtifactMeta(artifactId, { dnsConnected: true });
+  await syncRoutesBestEffort(`connect-dns:${artifactId}`);
+  return current;
+}
+
+async function disconnectDns(artifactId) {
+  const artifact = getArtifact(artifactId);
+  if (!artifact) throw new Error(`Artifact not found: ${artifactId}`);
+  const current = updateArtifactMeta(artifactId, { dnsConnected: false });
+  await syncRoutesBestEffort(`disconnect-dns:${artifactId}`);
+  return current;
+}
+
+async function startRegisteredArtifacts() {
+  const data = loadArtifacts();
+  await Promise.allSettled(data.artifacts.map(async (artifact) => {
+    if (artifact.pid && !isProcessAlive(artifact.pid)) {
+      updateArtifactMeta(artifact.id, { pid: null });
+    }
+
+    if (artifact.autostart !== false && artifact.desiredState === 'running') {
+      await startArtifact(artifact.id).catch((err) => {
+        updateArtifactMeta(artifact.id, { status: 'error', error: err.message, pid: null });
+      });
+    }
+  }));
+  await syncRoutesBestEffort('boot');
+}
+
+module.exports = {
+  deleteArtifact,
+  connectDns,
+  disconnectDns,
+  redeployArtifact,
+  registerArtifact,
+  runBuild,
+  startArtifact,
+  startRegisteredArtifacts,
+  stopArtifact,
+};

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

@@ -0,0 +1,176 @@
+/**
+ * Minimal artifact MCP tools.
+ *
+ * An artifact is a user-hosted production service. We do not scaffold or wrap
+ * it; we register the command, keep it alive locally, and expose an artifact
+ * DNS route while this computer is connected.
+ */
+
+const { textResult, errorResult } = require('../lib/tool-result');
+const { getConnectedRoutes, loadArtifacts } = require('./store');
+const {
+  connectDns,
+  disconnectDns,
+  redeployArtifact,
+  registerArtifact,
+  startArtifact,
+  stopArtifact,
+} = require('./supervisor');
+
+function artifactSummary(artifact) {
+  return [
+    `${artifact.name} (${artifact.id})`,
+    `status: ${artifact.status}`,
+    `cwd: ${artifact.cwd}`,
+    `port: ${artifact.port}`,
+    `dns: ${artifact.dnsConnected ? artifact.publicUrl : 'disconnected'}`,
+    `autostart: ${artifact.autostart !== false}`,
+    `keepAlive: ${artifact.keepAlive !== false}`,
+    artifact.error ? `error: ${artifact.error}` : null,
+  ].filter(Boolean).join('\n');
+}
+
+module.exports = [
+  {
+    name: 'artifacts_register',
+    description:
+      'Register a user-hosted artifact from an existing project on this computer. Artifacts 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 artifact DNS by default.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Human-readable artifact name' },
+        cwd: { type: 'string', description: 'Project directory on this computer' },
+        port: { type: 'number', description: 'Port the artifact 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 artifact 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'],
+    },
+    async handler(args) {
+      try {
+        const artifact = await registerArtifact(args || {});
+        return textResult(`Artifact registered.\n\n${artifactSummary(artifact)}`);
+      } catch (err) {
+        return errorResult(err.message);
+      }
+    },
+  },
+  {
+    name: 'artifacts_list',
+    description: 'List locally registered artifacts from ~/.amalgm/artifacts.json.',
+    inputSchema: { type: 'object', properties: {} },
+    async handler() {
+      const artifacts = loadArtifacts().artifacts;
+      if (artifacts.length === 0) return textResult('No artifacts registered.');
+      return textResult(artifacts.map(artifactSummary).join('\n\n'));
+    },
+  },
+  {
+    name: 'artifacts_routes',
+    description: 'List artifact DNS routes currently advertised by this computer.',
+    inputSchema: { type: 'object', properties: {} },
+    async handler() {
+      const routes = getConnectedRoutes();
+      return textResult(JSON.stringify({ routes }, null, 2));
+    },
+  },
+  {
+    name: 'artifacts_redeploy',
+    description:
+      'Redeploy an artifact: optionally update cwd/build/start/port settings, run its build command if configured, then restart the production process. DNS connection state is preserved.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string' },
+        cwd: { type: 'string' },
+        port: { type: 'number' },
+        build_command: { type: 'string' },
+        start_command: { type: 'string' },
+        autostart: { type: 'boolean' },
+        keep_alive: { type: 'boolean' },
+      },
+      required: ['artifact_id'],
+    },
+    async handler(args) {
+      try {
+        const artifact = await redeployArtifact(args.artifact_id, args || {});
+        return textResult(`Artifact redeployed.\n\n${artifactSummary(artifact)}`);
+      } catch (err) {
+        return errorResult(err.message);
+      }
+    },
+  },
+  {
+    name: 'artifacts_disconnect_dns',
+    description:
+      'Disconnect an artifact from artifact DNS without stopping the local process. The artifact remains registered locally and can be reconnected later.',
+    inputSchema: {
+      type: 'object',
+      properties: { artifact_id: { type: 'string' } },
+      required: ['artifact_id'],
+    },
+    async handler({ artifact_id }) {
+      try {
+        const artifact = await disconnectDns(artifact_id);
+        return textResult(`Artifact DNS disconnected.\n\n${artifactSummary(artifact)}`);
+      } catch (err) {
+        return errorResult(err.message);
+      }
+    },
+  },
+  {
+    name: 'artifacts_connect_dns',
+    description: 'Reconnect a registered artifact to artifact DNS.',
+    inputSchema: {
+      type: 'object',
+      properties: { artifact_id: { type: 'string' } },
+      required: ['artifact_id'],
+    },
+    async handler({ artifact_id }) {
+      try {
+        const artifact = await connectDns(artifact_id);
+        return textResult(`Artifact DNS connected.\n\n${artifactSummary(artifact)}`);
+      } catch (err) {
+        return errorResult(err.message);
+      }
+    },
+  },
+  {
+    name: 'artifacts_start',
+    description: 'Start a stopped registered artifact using its production start command.',
+    inputSchema: {
+      type: 'object',
+      properties: { artifact_id: { type: 'string' } },
+      required: ['artifact_id'],
+    },
+    async handler({ artifact_id }) {
+      try {
+        const artifact = await startArtifact(artifact_id);
+        return textResult(`Artifact started.\n\n${artifactSummary(artifact)}`);
+      } catch (err) {
+        return errorResult(err.message);
+      }
+    },
+  },
+  {
+    name: 'artifacts_stop',
+    description: 'Stop a registered artifact and mark it as intentionally stopped.',
+    inputSchema: {
+      type: 'object',
+      properties: { artifact_id: { type: 'string' } },
+      required: ['artifact_id'],
+    },
+    async handler({ artifact_id }) {
+      try {
+        const artifact = await stopArtifact(artifact_id);
+        return textResult(`Artifact stopped.\n\n${artifactSummary(artifact)}`);
+      } catch (err) {
+        return errorResult(err.message);
+      }
+    },
+  },
+];