amalgm 0.1.51 → 0.1.53

package/lib/tunnel-events.js

@@ -122,36 +122,55 @@ function sanitizePreviewWsHeaders(headers = {}) {
   return out;
 }
 
-function readArtifactRoutes() {
-  const file = path.join(AMALGM_DIR, 'artifacts.json');
+function readAppsFile() {
+  const appsFile = path.join(AMALGM_DIR, 'apps.json');
+  const legacyArtifactsFile = path.join(AMALGM_DIR, 'artifacts.json');
   let parsed = null;
   try {
-    parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    parsed = JSON.parse(fs.readFileSync(appsFile, 'utf8'));
   } catch {
-    return [];
+    try {
+      parsed = JSON.parse(fs.readFileSync(legacyArtifactsFile, 'utf8'));
+    } catch {
+      return [];
+    }
   }
 
-  const artifacts = Array.isArray(parsed?.artifacts) ? parsed.artifacts : [];
-  return artifacts
-    .filter((artifact) => {
-      const connected = artifact.dnsConnected !== false && artifact.connected !== false;
-      const desiredRunning = (artifact.desiredState || 'running') === 'running';
-      const active = artifact.status !== 'stopped' && artifact.status !== 'error';
-      return connected && desiredRunning && active && artifact.port && (artifact.artifactRef || artifact.artifact_ref);
+  return Array.isArray(parsed?.apps)
+    ? parsed.apps
+    : (Array.isArray(parsed?.artifacts) ? parsed.artifacts : []);
+}
+
+function readAppRoutes() {
+  const apps = readAppsFile();
+  return apps
+    .filter((app) => {
+      const connected = app.dnsConnected !== false && app.connected !== false;
+      const desiredRunning = (app.desiredState || 'running') === 'running';
+      const active = app.status !== 'stopped' && app.status !== 'error';
+      return connected && desiredRunning && active && app.port && (app.appRef || app.app_ref || app.artifactRef || app.artifact_ref);
     })
-    .map((artifact) => ({
-      artifact_ref: artifact.artifactRef || artifact.artifact_ref,
-      port: Number(artifact.port),
-      name: artifact.name,
+    .map((app) => ({
+      app_ref: app.appRef || app.app_ref || app.artifactRef || app.artifact_ref,
+      port: Number(app.port),
+      name: app.name,
     }))
     .filter((route) =>
-      /^[a-z0-9]{8,24}$/.test(route.artifact_ref)
+      /^[a-z0-9]{8,24}$/.test(route.app_ref)
       && Number.isInteger(route.port)
       && route.port > 0
       && route.port <= 65535,
     );
 }
 
+function legacyArtifactRoutes(routes) {
+  return routes.map((route) => ({
+    artifact_ref: route.app_ref,
+    port: route.port,
+    name: route.name,
+  }));
+}
+
 function readRuntimePorts() {
   try {
     const parsed = JSON.parse(fs.readFileSync(RUNTIME_STATE_FILE, 'utf8'));
@@ -175,7 +194,7 @@ function allowedTargetPorts() {
   for (const port of [runtimePorts.gateway, runtimePorts.mcp, runtimePorts.chat]) {
     if (Number.isInteger(port) && port > 0 && port <= 65535) ports.add(port);
   }
-  for (const route of readArtifactRoutes()) ports.add(route.port);
+  for (const route of readAppRoutes()) ports.add(route.port);
   return ports;
 }
 
@@ -252,11 +271,13 @@ function createEventTunnel({ record, foreground = false }) {
 
       if (ws.readyState !== WebSocket.OPEN) return;
 
+      const appRoutes = readAppRoutes();
       send({
         type: 'hello',
         app_version: require('../package.json').version,
         runtime_gateway_port: runtimeGatewayPort(),
-        artifact_routes: readArtifactRoutes(),
+        app_routes: appRoutes,
+        artifact_routes: legacyArtifactRoutes(appRoutes),
       });
 
       try {
@@ -287,11 +308,13 @@ function createEventTunnel({ record, foreground = false }) {
     return out;
   }
 
-  function advertiseArtifacts() {
+  function advertiseApps() {
+    const appRoutes = readAppRoutes();
     send({
-      type: 'artifact_routes',
+      type: 'app_routes',
       runtime_gateway_port: runtimeGatewayPort(),
-      artifact_routes: readArtifactRoutes(),
+      app_routes: appRoutes,
+      artifact_routes: legacyArtifactRoutes(appRoutes),
     });
   }
 
@@ -436,14 +459,16 @@ function createEventTunnel({ record, foreground = false }) {
       lastGatewayFrameAt = Date.now();
       log(`connected ${record.computer_id}`);
       void postPresence(record, true);
+      const appRoutes = readAppRoutes();
       send({
         type: 'hello',
         app_version: require('../package.json').version,
         runtime_gateway_port: runtimeGatewayPort(),
-        artifact_routes: readArtifactRoutes(),
+        app_routes: appRoutes,
+        artifact_routes: legacyArtifactRoutes(appRoutes),
       });
       if (!routeTimer) {
-        routeTimer = setInterval(advertiseArtifacts, 30000);
+        routeTimer = setInterval(advertiseApps, 30000);
         if (typeof routeTimer.unref === 'function') routeTimer.unref();
       }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,
@@ -29,11 +29,11 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@openai/codex": "^0.128.0",
     "@opencode-ai/sdk": "^1.14.29",
+    "agent-browser": "^0.27.0",
     "ai": "^6.0.116",
     "better-sqlite3": "^12.10.0",
     "cron-parser": "^5.5.0",
     "opencode-ai": "^1.14.35",
-    "playwright-core": "^1.59.1",
     "tsx": "^4.21.0",
     "ws": "^8.18.3",
     "zod": "^4.1.8"

package/runtime/lib/harnesses.js

@@ -56,8 +56,8 @@ function buildGatewayCliModel(gatewayId, harness) {
 // lib/modelNaming.ts
 var DEFAULT_MODEL_IDS = {
   claude_code: "anthropic/claude-opus-4.7",
-  codex: "openai/gpt-5.4-thinking-xhigh",
-  opencode: "opencode-anthropic-claude-sonnet-4-6",
+  codex: "openai/gpt-5.5",
+  opencode: "opencode-deepseek-deepseek-v4-pro",
   pi: "pi-anthropic-claude-sonnet-4.6",
   amp: "amp-default",
   cursor: "cursor/composer-2-fast"
@@ -492,6 +492,14 @@ var OPENCODE_MODELS = [
     providerGroup: "xai"
   },
   // ── DeepSeek ──
+  {
+    id: DEFAULT_MODEL_IDS.opencode,
+    name: "DeepSeek V4 Pro",
+    description: "DeepSeek flagship model",
+    cliModel: buildGatewayCliModel("deepseek/deepseek-v4-pro", "opencode"),
+    provider: "opencode",
+    providerGroup: "deepseek"
+  },
   {
     id: "opencode-deepseek-deepseek-v3.2",
     name: "DeepSeek V3.2",
@@ -765,7 +773,7 @@ var HARNESSES = {
     description: "Open-source coding agent",
     logoKey: "opencode",
     models: OPENCODE_MODELS,
-    defaultModelId: "opencode-anthropic-claude-sonnet-4-6",
+    defaultModelId: DEFAULT_MODEL_IDS.opencode,
     supportedAuthMethods: ["amalgm", "byok"],
     dynamicModels: true
   },
@@ -916,7 +924,7 @@ function resolveHarnessModel(harnessId, modelId) {
   return {
     modelId: normalizedModelId,
     cliModel: model?.cliModel ?? adaptedModel,
-    reasoningEffort: selection?.reasoningEffort ?? model?.reasoningEffort
+    reasoningEffort: selection?.reasoningEffort ?? model?.reasoningEffort ?? (harnessId === "codex" ? "xhigh" : void 0)
   };
 }
 function getAuthMethodsForHarness(harnessId) {

package/runtime/scripts/amalgm-mcp/agents/store.js

@@ -50,7 +50,7 @@ const BUILTIN_AGENT_BLUEPRINTS = [
     description: 'OpenAI Codex agent — code generation and analysis',
     adapter: 'codex',
     baseHarnessId: 'codex',
-    baseModelId: 'openai/gpt-5.4',
+    baseModelId: 'openai/gpt-5.5',
   },
   {
     id: 'opencode',
@@ -58,7 +58,7 @@ const BUILTIN_AGENT_BLUEPRINTS = [
     description: 'Open-source agent — multi-provider coding assistant',
     adapter: 'opencode',
     baseHarnessId: 'opencode',
-    baseModelId: 'opencode-anthropic-claude-sonnet-4-6',
+    baseModelId: 'opencode-deepseek-deepseek-v4-pro',
   },
   {
     id: 'pi',
@@ -85,7 +85,7 @@ const BUILTIN_AGENTS = BUILTIN_AGENT_BLUEPRINTS.map((agent) => ({
   status: DEFAULT_AGENT_STATUS,
 }));
 
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{12}$/i;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 function nowIso() {
   return new Date().toISOString();
@@ -406,7 +406,7 @@ function seedBuiltinAgents(options = {}) {
         description: existing?.description ?? blueprint.description,
         adapter: existing?.adapter || blueprint.adapter,
         baseHarnessId: existing?.baseHarnessId || blueprint.baseHarnessId,
-        baseModelId: existing?.baseModelId || blueprint.baseModelId,
+        baseModelId: blueprint.baseModelId,
         systemPrompt: existing?.systemPrompt || '',
         files: existing?.files || [],
         skills: existing?.skills || [],
@@ -423,7 +423,7 @@ function seedBuiltinAgents(options = {}) {
         authDetails: existing?.authDetails,
         configDir: existing?.configDir,
         createdAt: existing?.createdAt,
-        authMethod: defaultAgentAuthMethod(existing?.baseHarnessId || blueprint.baseHarnessId, existing),
+        authMethod: persistedAuthMethod(existing?.baseHarnessId || blueprint.baseHarnessId),
       }, existing);
       if (existing && agentsEqualForWrite(existing, next)) continue;
       upsertAgentRow(db, next);

package/runtime/scripts/amalgm-mcp/{artifacts → apps}/advertise.js

@@ -3,7 +3,7 @@ const {
   COMPUTER_RECORD_FILE,
   GATEWAY_BASE_URL,
   GATEWAY_INTERNAL_SECRET,
-  ARTIFACT_ROUTE_SYNC_INTERVAL_MS,
+  APP_ROUTE_SYNC_INTERVAL_MS,
 } = require('../config');
 const { readJson } = require('../lib/storage');
 const { getConnectedRoutes } = require('./store');
@@ -31,19 +31,34 @@ function loadComputerRecord() {
   };
 }
 
-async function postArtifactRoutes(computerId, routes, authHeaders) {
-  const response = await fetch(
-    `${GATEWAY_BASE_URL}/internal/computers/${encodeURIComponent(computerId)}/artifact-routes`,
-    {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        ...authHeaders,
-      },
-      body: JSON.stringify({ routes }),
-    },
+async function postAppRoutes(computerId, routes, authHeaders) {
+  const body = JSON.stringify({ routes });
+  const headers = {
+    'content-type': 'application/json',
+    ...authHeaders,
+  };
+  let response = await fetch(
+    `${GATEWAY_BASE_URL}/internal/computers/${encodeURIComponent(computerId)}/app-routes`,
+    { method: 'POST', headers, body },
   );
 
+  if (response.status === 404) {
+    response = await fetch(
+      `${GATEWAY_BASE_URL}/internal/computers/${encodeURIComponent(computerId)}/artifact-routes`,
+      {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          routes: routes.map((route) => ({
+            artifact_ref: route.app_ref,
+            port: route.port,
+            name: route.name,
+          })),
+        }),
+      },
+    );
+  }
+
   if (response.ok) {
     lastFailure = '';
     return response.json().catch(() => ({ ok: true, routesCount: routes.length }));
@@ -53,7 +68,7 @@ async function postArtifactRoutes(computerId, routes, authHeaders) {
   throw new Error(`Gateway route sync failed (${response.status}): ${text.slice(0, 300)}`);
 }
 
-function syncArtifactRoutesToGateway(reason = 'manual', options = {}) {
+function syncAppRoutesToGateway(reason = 'manual', options = {}) {
   const { throwOnError = false } = options;
 
   syncQueue = syncQueue
@@ -67,7 +82,7 @@ function syncArtifactRoutesToGateway(reason = 'manual', options = {}) {
       if (!computerId) {
         warnOnce(
           'missing-computer',
-          `[AmalgmMCP] Skipping artifact route sync: missing computer_id in ${COMPUTER_RECORD_FILE}.`,
+          `[AmalgmMCP] Skipping app route sync: missing computer_id in ${COMPUTER_RECORD_FILE}.`,
         );
         return { ok: false, skipped: 'missing-computer' };
       }
@@ -82,7 +97,7 @@ function syncArtifactRoutesToGateway(reason = 'manual', options = {}) {
       if (!authHeaders) {
         warnOnce(
           'missing-auth',
-          '[AmalgmMCP] Skipping artifact route sync: neither tunnel_token nor AMALGM_GATEWAY_INTERNAL_SECRET is configured.',
+          '[AmalgmMCP] Skipping app route sync: neither tunnel_token nor AMALGM_GATEWAY_INTERNAL_SECRET is configured.',
         );
         return { ok: false, skipped: 'missing-auth' };
       }
@@ -90,17 +105,17 @@ function syncArtifactRoutesToGateway(reason = 'manual', options = {}) {
       const routes = getConnectedRoutes();
 
       try {
-        const payload = await postArtifactRoutes(computerId, routes, authHeaders);
+        const payload = await postAppRoutes(computerId, routes, authHeaders);
         if (reason !== 'interval') {
           console.log(
-            `[AmalgmMCP] Synced artifact routes (${reason}): computer=${computerId} count=${routes.length}`,
+            `[AmalgmMCP] Synced app routes (${reason}): computer=${computerId} count=${routes.length}`,
           );
         }
         return { ok: true, computerId, routes, payload };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (message !== lastFailure || reason !== 'interval') {
-          console.warn(`[AmalgmMCP] Artifact route sync failed (${reason}): ${message}`);
+          console.warn(`[AmalgmMCP] App route sync failed (${reason}): ${message}`);
         }
         lastFailure = message;
         if (throwOnError) throw err;
@@ -111,13 +126,13 @@ function syncArtifactRoutesToGateway(reason = 'manual', options = {}) {
   return syncQueue;
 }
 
-function startArtifactRouteSyncLoop() {
+function startAppRouteSyncLoop() {
   if (routeSyncTimer) return routeSyncTimer;
 
-  void syncArtifactRoutesToGateway('boot');
+  void syncAppRoutesToGateway('boot');
   routeSyncTimer = setInterval(() => {
-    void syncArtifactRoutesToGateway('interval');
-  }, ARTIFACT_ROUTE_SYNC_INTERVAL_MS);
+    void syncAppRoutesToGateway('interval');
+  }, APP_ROUTE_SYNC_INTERVAL_MS);
 
   if (typeof routeSyncTimer.unref === 'function') {
     routeSyncTimer.unref();
@@ -127,6 +142,6 @@ function startArtifactRouteSyncLoop() {
 }
 
 module.exports = {
-  startArtifactRouteSyncLoop,
-  syncArtifactRoutesToGateway,
+  startAppRouteSyncLoop,
+  syncAppRoutesToGateway,
 };

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

@@ -0,0 +1,144 @@
+/**
+ * /apps/* REST routes for the Next.js API and local tunnel runtime.
+ */
+
+const { getConnectedRoutes, loadApps } = require('./store');
+const {
+  deleteApp,
+  connectDns,
+  disconnectDns,
+  redeployApp,
+  registerApp,
+  startApp,
+  stopApp,
+} = require('./supervisor');
+
+function appIdFromBody(body) {
+  return body?.app_id || body?.appId || body?.artifact_id || body?.artifactId;
+}
+
+function legacyApp(app) {
+  if (!app) return app;
+  return {
+    ...app,
+    kind: app.kind === 'app' ? 'artifact' : app.kind,
+    artifactRef: app.appRef,
+    artifact_ref: app.app_ref,
+    artifactUrl: app.appUrl || app.publicUrl,
+  };
+}
+
+function appPayload(app, options = {}) {
+  return options.legacy ? { artifact: legacyApp(app) } : { app };
+}
+
+async function handleList(sendJson, options = {}) {
+  const data = loadApps();
+  if (options.legacy) {
+    return sendJson(200, {
+      version: data.version,
+      artifacts: data.apps.map(legacyApp),
+    });
+  }
+  sendJson(200, data);
+}
+
+async function handleRoutes(sendJson, options = {}) {
+  const routes = getConnectedRoutes();
+  sendJson(200, {
+    routes: options.legacy
+      ? routes.map((route) => ({
+        artifact_ref: route.app_ref,
+        port: route.port,
+        name: route.name,
+      }))
+      : routes,
+  });
+}
+
+async function handleRegister(body, sendJson, options = {}) {
+  try {
+    const app = await registerApp(body || {});
+    sendJson(200, appPayload(app, options));
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleRedeploy(body, sendJson, options = {}) {
+  try {
+    const appId = appIdFromBody(body);
+    if (!appId) return sendJson(400, { error: 'app_id is required' });
+    const app = await redeployApp(appId, body);
+    sendJson(200, appPayload(app, options));
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleStart(body, sendJson, options = {}) {
+  try {
+    const appId = appIdFromBody(body);
+    if (!appId) return sendJson(400, { error: 'app_id is required' });
+    const app = await startApp(appId);
+    sendJson(200, appPayload(app, options));
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleStop(body, sendJson, options = {}) {
+  try {
+    const appId = appIdFromBody(body);
+    if (!appId) return sendJson(400, { error: 'app_id is required' });
+    const app = await stopApp(appId);
+    sendJson(200, appPayload(app, options));
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleDelete(body, sendJson, options = {}) {
+  try {
+    const appId = appIdFromBody(body);
+    if (!appId) return sendJson(400, { error: 'app_id is required' });
+    const app = await deleteApp(appId);
+    sendJson(200, appPayload(app, options));
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleConnectDns(body, sendJson, options = {}) {
+  try {
+    const appId = appIdFromBody(body);
+    if (!appId) return sendJson(400, { error: 'app_id is required' });
+    const app = await connectDns(appId);
+    sendJson(200, appPayload(app, options));
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+async function handleDisconnectDns(body, sendJson, options = {}) {
+  try {
+    const appId = appIdFromBody(body);
+    if (!appId) return sendJson(400, { error: 'app_id is required' });
+    const app = await disconnectDns(appId);
+    sendJson(200, appPayload(app, options));
+  } catch (err) {
+    sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+module.exports = {
+  handleConnectDns,
+  handleDelete,
+  handleDisconnectDns,
+  handleList,
+  handleRedeploy,
+  handleRegister,
+  handleRoutes,
+  handleStart,
+  handleStop,
+};

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

@@ -0,0 +1,171 @@
+/**
+ * App storage — ~/.amalgm/apps.json
+ *
+ * This is intentionally local-first. The laptop volume is the source of truth;
+ * the public gateway only gets ephemeral route advertisements while the
+ * computer is connected.
+ */
+
+const crypto = require('crypto');
+const {
+  APPS_DIR,
+  APPS_FILE,
+  APPS_DOMAIN,
+  APP_PORT_MIN,
+  APP_PORT_MAX,
+  LEGACY_ARTIFACTS_FILE,
+} = require('../config');
+const { ensureDir, readJson, writeJsonAtomic } = require('../lib/storage');
+const { appendStateEvent } = require('../state/events');
+
+function ensureAppsDirs() {
+  ensureDir(APPS_DIR);
+  if (!readJson(APPS_FILE, null)) {
+    const legacy = readJson(LEGACY_ARTIFACTS_FILE, null);
+    const legacyApps = Array.isArray(legacy?.artifacts) ? legacy.artifacts : [];
+    writeJsonAtomic(APPS_FILE, { version: 1, apps: legacyApps.map(normalizeApp) });
+  }
+}
+
+function publicUrlForRef(appRef) {
+  return `https://${appRef}.${APPS_DOMAIN}/`;
+}
+
+function genAppRef() {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  const bytes = crypto.randomBytes(12);
+  let out = '';
+  for (let i = 0; i < 12; i += 1) {
+    out += chars[bytes[i] % chars.length];
+  }
+  return out;
+}
+
+function normalizeApp(app) {
+  const appRef = app.appRef || app.app_ref || app.artifactRef || app.artifact_ref || genAppRef();
+  const savedUrl = app.appUrl || app.publicUrl || '';
+  const publicUrl = savedUrl && !String(savedUrl).includes('.artifacts.')
+    ? savedUrl
+    : publicUrlForRef(appRef);
+  const dnsConnected =
+    app.dnsConnected !== undefined
+      ? app.dnsConnected !== false
+      : app.connected !== false;
+
+  return {
+    ...app,
+    kind: 'app',
+    appRef,
+    app_ref: appRef,
+    appUrl: publicUrl,
+    publicUrl,
+    dnsConnected,
+    autostart: app.autostart !== false,
+    keepAlive: app.keepAlive !== false,
+    desiredState: app.desiredState || (app.status === 'stopped' ? 'stopped' : 'running'),
+    status: app.status || 'stopped',
+    pid: app.pid || null,
+    error: app.error || null,
+  };
+}
+
+function loadApps() {
+  let data = readJson(APPS_FILE, null);
+  if (!data) {
+    const legacy = readJson(LEGACY_ARTIFACTS_FILE, null);
+    data = Array.isArray(legacy?.artifacts)
+      ? { version: 1, apps: legacy.artifacts }
+      : { version: 1, apps: [] };
+  }
+  const apps = Array.isArray(data.apps) ? data.apps.map(normalizeApp) : [];
+  return { version: 1, apps };
+}
+
+function publishAppsChange(data, source = 'apps') {
+  try {
+    appendStateEvent({
+      resource: 'apps',
+      op: 'replace',
+      value: Array.isArray(data?.apps) ? data.apps.map(normalizeApp) : [],
+      source,
+    });
+  } catch (error) {
+    console.warn('[Apps] Local Live Store publish failed:', error.message);
+  }
+}
+
+function saveApps(data, options = {}) {
+  ensureDir(APPS_DIR);
+  const normalizedData = {
+    version: 1,
+    apps: Array.isArray(data.apps) ? data.apps.map(normalizeApp) : [],
+  };
+  writeJsonAtomic(APPS_FILE, normalizedData);
+  publishAppsChange(normalizedData, options.source || 'apps:save');
+}
+
+function updateAppMeta(appId, updates) {
+  const data = loadApps();
+  const app = data.apps.find((item) => item.id === appId);
+  if (!app) return null;
+  Object.assign(app, updates, { updatedAt: new Date().toISOString() });
+  saveApps(data);
+  return normalizeApp(app);
+}
+
+function getApp(appId) {
+  return loadApps().apps.find((app) => app.id === appId) || null;
+}
+
+function allocatePort(preferredPort) {
+  if (preferredPort !== undefined && preferredPort !== null) {
+    const parsed = Number(preferredPort);
+    if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) return parsed;
+    return null;
+  }
+
+  const used = new Set(loadApps().apps.map((app) => Number(app.port)));
+  for (let port = APP_PORT_MIN; port <= APP_PORT_MAX; port += 1) {
+    if (!used.has(port)) return port;
+  }
+  return null;
+}
+
+function allocateUniqueAppRef() {
+  const used = new Set(loadApps().apps.map((app) => app.appRef));
+  for (let attempt = 0; attempt < 12; attempt += 1) {
+    const candidate = genAppRef();
+    if (!used.has(candidate)) return candidate;
+  }
+  throw new Error('Could not allocate app DNS ref');
+}
+
+function getConnectedRoutes() {
+  return loadApps()
+    .apps
+    .filter((app) =>
+      app.dnsConnected
+      && app.desiredState === 'running'
+      && app.status !== 'stopped'
+      && app.status !== 'error'
+      && app.port
+      && app.appRef,
+    )
+    .map((app) => ({
+      app_ref: app.appRef,
+      port: app.port,
+      name: app.name,
+    }));
+}
+
+module.exports = {
+  allocatePort,
+  allocateUniqueAppRef,
+  ensureAppsDirs,
+  getApp,
+  getConnectedRoutes,
+  loadApps,
+  publicUrlForRef,
+  saveApps,
+  updateAppMeta,
+};