takos-control 1.0.0

package/src/application/services/deployment/artifacts.ts

@@ -0,0 +1,105 @@
+/**
+ * Artifact access and cryptographic helpers for deployments.
+ *
+ * Handles reading bundle/wasm content from object storage, verifying
+ * integrity hashes, and encrypting/decrypting env-vars and bindings
+ * snapshots.
+ */
+import type { WorkerBinding } from '../../../platform/providers/cloudflare/wfp.ts';
+import { decrypt, decryptEnvVars, maskEnvVars, type EncryptedData } from '../../../shared/utils/crypto';
+import { computeSHA256, constantTimeEqual } from '../../../shared/utils/hash';
+import type { Deployment, DeploymentEnv } from './models';
+import { InternalError, NotFoundError, ValidationError } from 'takos-common/errors';
+
+export async function getBundleContent(env: DeploymentEnv, deployment: Deployment): Promise<string> {
+  if (!deployment.bundle_r2_key || !env.WORKER_BUNDLES) {
+    throw new NotFoundError('Bundle');
+  }
+
+  const object = await env.WORKER_BUNDLES.get(deployment.bundle_r2_key);
+  if (!object) {
+    throw new NotFoundError(`Bundle at ${deployment.bundle_r2_key}`);
+  }
+
+  return object.text();
+}
+
+export async function verifyBundleIntegrity(bundleContent: string, deployment: Deployment): Promise<void> {
+  if (deployment.bundle_hash) {
+    const actual = await computeSHA256(bundleContent);
+    if (!constantTimeEqual(actual, deployment.bundle_hash)) {
+      throw new ValidationError(`Bundle hash mismatch: expected ${deployment.bundle_hash}, got ${actual}`);
+    }
+  }
+
+  if (typeof deployment.bundle_size === 'number') {
+    const size = new TextEncoder().encode(bundleContent).byteLength;
+    if (size !== deployment.bundle_size) {
+      throw new ValidationError(`Bundle size mismatch: expected ${deployment.bundle_size}, got ${size}`);
+    }
+  }
+}
+
+export async function getWasmContent(env: DeploymentEnv, deployment: Deployment): Promise<ArrayBuffer | null> {
+  if (!deployment.wasm_r2_key || !env.WORKER_BUNDLES) {
+    return null;
+  }
+
+  const object = await env.WORKER_BUNDLES.get(deployment.wasm_r2_key);
+  if (!object) {
+    return null;
+  }
+
+  return object.arrayBuffer();
+}
+
+export async function decryptBindings(encryptionKey: string, deployment: Deployment): Promise<WorkerBinding[]> {
+  if (!deployment.bindings_snapshot_encrypted) {
+    return [];
+  }
+
+  let encryptedParsed: unknown;
+  try {
+    encryptedParsed = JSON.parse(deployment.bindings_snapshot_encrypted);
+  } catch (err) {
+    throw new InternalError(`Failed to parse bindings_snapshot_encrypted for deployment ${deployment.id}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (
+    typeof encryptedParsed !== 'object' || encryptedParsed === null ||
+    typeof (encryptedParsed as Record<string, unknown>).ciphertext !== 'string' ||
+    typeof (encryptedParsed as Record<string, unknown>).iv !== 'string'
+  ) {
+    throw new InternalError(`Invalid encrypted data structure for deployment ${deployment.id}: missing ciphertext or iv`);
+  }
+  const encrypted = encryptedParsed as EncryptedData;
+
+  const decrypted = await decrypt(encrypted, encryptionKey, deployment.id);
+
+  let bindingsParsed: unknown;
+  try {
+    bindingsParsed = JSON.parse(decrypted);
+  } catch (err) {
+    throw new InternalError(`Failed to parse decrypted bindings for deployment ${deployment.id}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!Array.isArray(bindingsParsed)) {
+    throw new InternalError(`Decrypted bindings for deployment ${deployment.id} is not an array`);
+  }
+  return bindingsParsed as WorkerBinding[];
+}
+
+export async function getEnvVars(encryptionKey: string, deployment: Deployment): Promise<Record<string, string>> {
+  if (!deployment.env_vars_snapshot_encrypted) {
+    return {};
+  }
+
+  return decryptEnvVars(
+    deployment.env_vars_snapshot_encrypted,
+    encryptionKey,
+    deployment.id
+  );
+}
+
+export async function getMaskedEnvVars(encryptionKey: string, deployment: Deployment): Promise<Record<string, string>> {
+  const envVars = await getEnvVars(encryptionKey, deployment);
+  return maskEnvVars(envVars);
+}

package/src/application/services/deployment/deployment-artifacts.ts

@@ -0,0 +1,143 @@
+/**
+ * Pure helper / utility functions for the deployment service.
+ *
+ * These are stateless functions extracted from service.ts to reduce file size
+ * and improve testability.
+ */
+import type { WorkerBinding } from '../../../platform/providers/cloudflare/wfp.ts';
+import { safeJsonParseOrDefault } from '../../../shared/utils';
+import type { ServiceRuntimeConfigState } from '../platform/worker-desired-state';
+import type {
+  ArtifactKind,
+  Deployment,
+  DeploymentEnv,
+  CreateDeploymentInput,
+  DeploymentTarget,
+} from './models';
+import {
+  type DeploymentProviderRegistryLike,
+  parseDeploymentTargetConfig,
+} from './provider';
+import { BadRequestError, ConflictError } from 'takos-common/errors';
+
+export function getDeploymentProviderRegistry(env: DeploymentEnv): DeploymentProviderRegistryLike | undefined {
+  return env.DEPLOYMENT_PROVIDER_REGISTRY;
+}
+
+export function resolveDeploymentArtifactBaseRef(serviceId: string, target?: DeploymentTarget): string {
+  const routeRef = target?.route_ref?.trim()
+    || (target?.endpoint?.kind === 'service-ref' ? target.endpoint.ref.trim() : '')
+    || '';
+  return routeRef || `worker-${serviceId}`;
+}
+
+export function buildDeploymentArtifactRef(baseRef: string, version: number): string {
+  return `${baseRef}-v${version}`;
+}
+
+export function resolveDeploymentArtifactRef(options: {
+  serviceId: string;
+  version: number;
+  target?: DeploymentTarget;
+  persistedArtifactRef?: string | null;
+}): string {
+  const persistedArtifactRef = options.persistedArtifactRef?.trim();
+  if (persistedArtifactRef) {
+    return persistedArtifactRef;
+  }
+  return buildDeploymentArtifactRef(
+    resolveDeploymentArtifactBaseRef(options.serviceId, options.target),
+    options.version,
+  );
+}
+
+export function resolveDeploymentServiceId(input: {
+  workerId?: string | null;
+  serviceId?: string | null;
+}): string {
+  const serviceId = input.serviceId?.trim() || input.workerId?.trim() || '';
+  if (!serviceId) {
+    throw new BadRequestError('Deployment requires a service identifier');
+  }
+  return serviceId;
+}
+
+export function extractErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function parseRuntimeConfig(raw: string | null | undefined): ServiceRuntimeConfigState {
+  const parsed = safeJsonParseOrDefault<{
+    compatibility_date?: string;
+    compatibility_flags?: string[];
+    limits?: { cpu_ms?: number; subrequests?: number };
+    mcp_server?: ServiceRuntimeConfigState['mcp_server'];
+  }>(raw, {});
+
+  return {
+    compatibility_date: parsed.compatibility_date,
+    compatibility_flags: Array.isArray(parsed.compatibility_flags) ? parsed.compatibility_flags : [],
+    limits: parsed.limits && typeof parsed.limits === 'object' ? parsed.limits : {},
+    mcp_server: parsed.mcp_server,
+    updated_at: null,
+  };
+}
+
+export function snapshotFromOverride(
+  override: NonNullable<CreateDeploymentInput['snapshotOverride']>
+): {
+  envVars: Record<string, string>;
+  bindings: WorkerBinding[];
+  runtimeConfig: ServiceRuntimeConfigState;
+} {
+  return {
+    envVars: { ...override.envVars },
+    bindings: [...override.bindings],
+    runtimeConfig: {
+      compatibility_date: override.runtimeConfig?.compatibility_date,
+      compatibility_flags: override.runtimeConfig?.compatibility_flags ?? [],
+      limits: override.runtimeConfig?.limits ?? {},
+      mcp_server: override.runtimeConfig?.mcp_server,
+      updated_at: null,
+    },
+  };
+}
+
+export function assertMatchingIdempotentRequest(
+  deployment: Deployment,
+  expected: {
+    artifactKind: ArtifactKind;
+    bundleHash: string | null;
+    bundleSize: number | null;
+    imageRef?: string;
+    strategy: 'direct' | 'canary';
+    canaryWeight?: number;
+  }
+): void {
+  const expectedRoutingStatus = expected.strategy === 'canary' ? 'canary' : 'active';
+  const expectedRoutingWeight = expected.strategy === 'canary'
+    ? expected.canaryWeight ?? 1
+    : 100;
+
+  if (
+    deployment.routing_status !== expectedRoutingStatus ||
+    deployment.routing_weight !== expectedRoutingWeight
+  ) {
+    throw new ConflictError('Idempotency-Key reuse does not match the original deployment request');
+  }
+
+  if (expected.artifactKind === 'container-image') {
+    const deploymentTarget = parseDeploymentTargetConfig(deployment);
+    const existingImageRef = deploymentTarget.artifact?.image_ref;
+    if (existingImageRef !== expected.imageRef) {
+      throw new ConflictError('Idempotency-Key reuse does not match the original deployment request');
+    }
+  } else {
+    if (
+      deployment.bundle_hash !== expected.bundleHash ||
+      deployment.bundle_size !== expected.bundleSize
+    ) {
+      throw new ConflictError('Idempotency-Key reuse does not match the original deployment request');
+    }
+  }
+}

package/src/application/services/deployment/execute.ts

@@ -0,0 +1,364 @@
+/**
+ * Deployment execution orchestrator.
+ *
+ * Implements the multi-step deployment pipeline: deploy worker, update routing,
+ * reconcile MCP, and handle failure rollback. Extracted from DeploymentService
+ * to keep the main service file focused on coordination.
+ */
+import { safeJsonParseOrDefault } from '../../../shared/utils';
+import type { ServiceRuntimeConfigState } from '../platform/worker-desired-state';
+import type { Deployment, DeploymentEnv } from './models';
+import {
+  createDeploymentProvider,
+  parseDeploymentTargetConfig,
+} from './provider';
+import {
+  getDeploymentById,
+  getDeploymentEvents,
+  getDeploymentServiceId,
+  getServiceDeploymentBasics,
+  logDeploymentEvent,
+  updateDeploymentRecord,
+} from './store';
+import { executeDeploymentStep, updateDeploymentState } from './state';
+import { reconcileManagedWorkerMcpServer } from '../platform/mcp';
+import type { RoutingTarget } from '../routing/types';
+import {
+  applyRoutingDbUpdates,
+  applyRoutingToHostnames,
+  buildRoutingTarget,
+  collectHostnames,
+  fetchServiceWithDomains,
+  restoreRoutingSnapshot,
+  snapshotRouting,
+  type RoutingSnapshot,
+} from './routing';
+import { rollbackDeploymentSteps } from './rollback';
+import { deployments, getDb, services } from '../../../infra/db';
+import { eq } from 'drizzle-orm';
+import { CF_COMPATIBILITY_DATE } from '../../../shared/constants';
+import { logError } from '../../../shared/utils/logger';
+import { InternalError, NotFoundError } from 'takos-common/errors';
+import {
+  getDeploymentProviderRegistry,
+  resolveDeploymentArtifactRef,
+  parseRuntimeConfig,
+  extractErrorMessage,
+} from './deployment-artifacts';
+import {
+  getBundleContent,
+  verifyBundleIntegrity,
+  getWasmContent,
+  decryptBindings,
+} from './artifacts';
+
+/**
+ * Execute a deployment through all pipeline steps (deploy_worker, update_routing, finalize).
+ *
+ * This is the core orchestration extracted from DeploymentService.executeDeployment.
+ */
+export async function executeDeploymentPipeline(
+  env: DeploymentEnv,
+  encryptionKey: string,
+  deploymentId: string,
+): Promise<Deployment> {
+  const deployment = await getDeploymentById(env.DB, deploymentId);
+
+  if (!deployment) {
+    throw new NotFoundError(`Deployment ${deploymentId}`);
+  }
+
+  if (deployment.status === 'success' || deployment.status === 'rolled_back') {
+    return deployment;
+  }
+
+  const completedStepNames = (await getDeploymentEvents(env.DB, deploymentId))
+    .filter((event) => event.event_type === 'step_completed' && event.step_name)
+    .map((event) => event.step_name as string);
+
+  await updateDeploymentState(env.DB, deploymentId, 'in_progress', deployment.deploy_state);
+  const deploymentServiceId = getDeploymentServiceId(deployment);
+
+  let workerHostname: string | null = null;
+  let deploymentArtifactRef: string | null = null;
+  let routingRollbackSnapshot: RoutingSnapshot | null = null;
+
+  try {
+    const serviceBasics = await getServiceDeploymentBasics(env.DB, deploymentServiceId);
+    if (!serviceBasics.exists) {
+      throw new NotFoundError('Worker');
+    }
+
+    workerHostname = serviceBasics.hostname;
+    deploymentArtifactRef = resolveDeploymentArtifactRef({
+      serviceId: deploymentServiceId,
+      version: deployment.version,
+      target: parseDeploymentTargetConfig(deployment),
+      persistedArtifactRef: deployment.artifact_ref,
+    });
+
+    const deployArtifactRef = deploymentArtifactRef;
+    const provider = createDeploymentProvider(deployment, {
+      providerRegistry: getDeploymentProviderRegistry(env),
+      cloudflareEnv: env,
+      orchestratorUrl: env.OCI_ORCHESTRATOR_URL,
+      orchestratorToken: env.OCI_ORCHESTRATOR_TOKEN,
+    });
+
+    if (!deployArtifactRef) {
+      throw new InternalError('Deployment artifact ref is missing');
+    }
+
+    const isContainerDeploy = deployment.artifact_kind === 'container-image';
+
+    if (!completedStepNames.includes('deploy_worker')) {
+      await executeDeploymentStep(env.DB, deploymentId, 'deploying_worker', 'deploy_worker', async () => {
+        let bundleContent: string | undefined;
+        let wasmContent: ArrayBuffer | null = null;
+
+        if (!isContainerDeploy) {
+          bundleContent = await getBundleContent(env, deployment);
+          await verifyBundleIntegrity(bundleContent, deployment);
+          wasmContent = deployment.wasm_r2_key
+            ? await getWasmContent(env, deployment)
+            : null;
+        }
+
+        const runtimeConfig = parseRuntimeConfig(deployment.runtime_config_snapshot_json);
+        const compatibilityDate = runtimeConfig.compatibility_date || CF_COMPATIBILITY_DATE;
+        const compatibilityFlags = runtimeConfig.compatibility_flags.length > 0
+          ? runtimeConfig.compatibility_flags
+          : wasmContent
+            ? ['nodejs_compat']
+            : [];
+
+        const bindings = (!isContainerDeploy && deployment.bindings_snapshot_encrypted)
+          ? await decryptBindings(encryptionKey, deployment)
+          : [];
+        const deployResult = await provider.deploy({
+          deployment,
+          artifactRef: deployArtifactRef,
+          bundleContent,
+          wasmContent,
+          bindings,
+          compatibilityDate,
+          compatibilityFlags,
+          limits: runtimeConfig.limits,
+        });
+
+        // Store resolved endpoint from container provider in provider_state_json
+        if (deployResult?.resolvedEndpoint) {
+          const providerState = safeJsonParseOrDefault<Record<string, unknown>>(
+            deployment.provider_state_json,
+            {},
+          );
+          providerState.resolved_endpoint = deployResult.resolvedEndpoint;
+          if (deployResult.logsRef) {
+            providerState.logs_ref = deployResult.logsRef;
+          }
+          await updateDeploymentRecord(env.DB, deploymentId, {
+            providerStateJson: JSON.stringify(providerState),
+          });
+          // Update in-memory deployment for routing step
+          deployment.provider_state_json = JSON.stringify(providerState);
+        }
+      });
+      completedStepNames.push('deploy_worker');
+    }
+
+    if (!completedStepNames.includes('update_routing')) {
+      await executeDeploymentStep(env.DB, deploymentId, 'routing', 'update_routing', async () => {
+        const db = getDb(env.DB);
+
+        const serviceRouteRecord = await fetchServiceWithDomains(env, deploymentServiceId);
+
+        if (!serviceRouteRecord) {
+          throw new NotFoundError('Worker');
+        }
+
+        const hostnameList = collectHostnames(serviceRouteRecord);
+
+        if (hostnameList.length === 0) {
+          return;
+        }
+
+        routingRollbackSnapshot = await snapshotRouting(env, hostnameList);
+
+        if (env.WORKER_BUNDLES && routingRollbackSnapshot) {
+          const snapshotKey = `deployment-snapshots/${deploymentId}.json`;
+          await env.WORKER_BUNDLES.put(snapshotKey, JSON.stringify(routingRollbackSnapshot));
+        }
+
+        const nowIso = new Date().toISOString();
+        const promoteToActive = deployment.routing_status !== 'canary';
+
+        let activeDeployment = null;
+        if (!promoteToActive && serviceRouteRecord.activeDeploymentId) {
+          activeDeployment = await db.select({
+            id: deployments.id,
+            artifactRef: deployments.artifactRef,
+            targetJson: deployments.targetJson,
+            routingStatus: deployments.routingStatus,
+          })
+            .from(deployments)
+            .where(eq(deployments.id, serviceRouteRecord.activeDeploymentId))
+            .get() ?? null;
+        }
+
+        // For container deploys, inject the resolved endpoint as the routing target
+        let deploymentTarget = parseDeploymentTargetConfig(deployment);
+        if (isContainerDeploy) {
+          const providerState = safeJsonParseOrDefault<Record<string, unknown>>(
+            deployment.provider_state_json,
+            {},
+          );
+          const resolvedEp = providerState.resolved_endpoint as { base_url?: string } | undefined;
+          if (resolvedEp?.base_url) {
+            deploymentTarget = {
+              ...deploymentTarget,
+              endpoint: { kind: 'http-url', base_url: resolvedEp.base_url },
+            };
+          }
+        }
+
+        const routingCtx = {
+          deploymentId,
+          deploymentVersion: deployment.version,
+          deployArtifactRef,
+          deploymentTarget,
+          serviceRouteRecord,
+          desiredRoutingStatus: deployment.routing_status,
+          desiredRoutingWeight: deployment.routing_weight,
+          activeDeployment,
+        };
+
+        const { target, auditDetails } = buildRoutingTarget(routingCtx, hostnameList);
+
+        await applyRoutingToHostnames(env, hostnameList, target);
+
+        try {
+          await applyRoutingDbUpdates(env, routingCtx, nowIso);
+        } catch (dbErr) {
+          if (routingRollbackSnapshot) {
+            await restoreRoutingSnapshot(env, routingRollbackSnapshot).catch((e) => {
+              logError('Failed to restore routing snapshot during rollback', e, { module: 'deployment' });
+            });
+          }
+          throw dbErr;
+        }
+
+        await logDeploymentEvent(
+          env.DB,
+          deploymentId,
+          'routing_updated',
+          'update_routing',
+          promoteToActive ? 'Promoted deployment to active routing' : 'Configured canary routing',
+          {
+            actorAccountId: deployment.deployed_by ?? null,
+            details: auditDetails,
+          }
+        );
+      });
+      completedStepNames.push('update_routing');
+    }
+
+    const finishedAt = new Date().toISOString();
+    await updateDeploymentRecord(env.DB, deploymentId, {
+      deployState: 'completed',
+      status: 'success',
+      completedAt: finishedAt,
+      updatedAt: finishedAt,
+    });
+    try {
+      const db = getDb(env.DB);
+      await db.update(services)
+        .set({
+          status: 'deployed',
+          updatedAt: finishedAt,
+        })
+        .where(eq(services.id, deploymentServiceId))
+        .run();
+    } catch (e) {
+      logError('Failed to update service status to deployed (non-critical)', e, { module: 'deployment' });
+    }
+
+    const runtimeConfig = safeJsonParseOrDefault<Partial<ServiceRuntimeConfigState>>(
+      deployment.runtime_config_snapshot_json,
+      {},
+    );
+    const currentService = await getServiceDeploymentBasics(env.DB, deploymentServiceId);
+
+    await reconcileManagedWorkerMcpServer(env.DB, env, {
+      spaceId: deployment.space_id,
+      serviceId: deploymentServiceId,
+      enabled: runtimeConfig.mcp_server?.enabled === true,
+      name: runtimeConfig.mcp_server?.name ?? null,
+      url: currentService.hostname && runtimeConfig.mcp_server?.path
+        ? `https://${currentService.hostname}${runtimeConfig.mcp_server.path}`
+        : null,
+    }).catch((err) => {
+      logError('Failed to reconcile managed worker MCP server', err, { module: 'deploymentservice' });
+    });
+
+    await logDeploymentEvent(env.DB, deploymentId, 'completed', null, 'Deployment completed successfully');
+
+    // Clean up routing snapshot after successful deployment
+    if (env.WORKER_BUNDLES) {
+      const snapshotKey = `deployment-snapshots/${deploymentId}.json`;
+      await env.WORKER_BUNDLES.delete(snapshotKey).catch((e) => {
+        logError('Failed to clean up deployment snapshot (non-critical)', e, { module: 'deployment' });
+      });
+    }
+
+    const finalDeployment = await getDeploymentById(env.DB, deploymentId);
+    if (!finalDeployment) {
+      throw new InternalError(`Deployment ${deploymentId} not found after successful completion`);
+    }
+    return finalDeployment;
+  } catch (error) {
+    const errorMessage = extractErrorMessage(error);
+    const now = new Date().toISOString();
+
+    await rollbackDeploymentSteps({
+      env,
+      deploymentId,
+      deployment,
+      completedStepNames,
+      routingRollbackSnapshot,
+      workerHostname,
+      deploymentArtifactRef,
+      provider: createDeploymentProvider(deployment, {
+        providerRegistry: getDeploymentProviderRegistry(env),
+        cloudflareEnv: env,
+        orchestratorUrl: env.OCI_ORCHESTRATOR_URL,
+        orchestratorToken: env.OCI_ORCHESTRATOR_TOKEN,
+      }),
+    });
+
+    await updateDeploymentRecord(env.DB, deploymentId, {
+      deployState: 'failed',
+      status: 'failed',
+      stepError: errorMessage,
+      updatedAt: now,
+    });
+    const currentService = await getServiceDeploymentBasics(env.DB, deploymentServiceId);
+    if (!currentService.activeDeploymentId) {
+      try {
+        const db = getDb(env.DB);
+        await db.update(services)
+          .set({
+            status: 'failed',
+            updatedAt: now,
+          })
+          .where(eq(services.id, deploymentServiceId))
+          .run();
+      } catch (e) {
+        logError('Failed to update service status to failed (non-critical)', e, { module: 'deployment' });
+      }
+    }
+
+    await logDeploymentEvent(env.DB, deploymentId, 'failed', deployment.current_step, errorMessage);
+
+    throw error;
+  }
+}

package/src/application/services/deployment/group-deploy-manifest.ts

@@ -0,0 +1,71 @@
+/**
+ * Minimal AppManifest type mirror for group-deploy.
+ *
+ * The canonical parser lives in `apps/cli/src/lib/app-manifest.ts`.
+ * This file re-declares the shape so that `packages/control` can depend
+ * on it without pulling in CLI-specific imports (commander, ora, etc.).
+ *
+ * Keep this in sync with the CLI's AppManifest type.
+ */
+
+export type AppResourceType = 'd1' | 'r2' | 'kv' | 'secretRef';
+
+export interface AppResource {
+  type: AppResourceType;
+  binding?: string;
+  migrations?: string | { up: string; down: string };
+  /** For secretRef: whether to auto-generate a random value */
+  generate?: boolean;
+}
+
+export interface WorkerServiceBuild {
+  fromWorkflow: {
+    path: string;
+    job: string;
+    artifact: string;
+    artifactPath: string;
+  };
+}
+
+export interface WorkerService {
+  type: 'worker';
+  build: WorkerServiceBuild;
+  env?: Record<string, string>;
+  bindings?: {
+    d1?: string[];
+    r2?: string[];
+    kv?: string[];
+    services?: string[];
+  };
+}
+
+export interface AppRoute {
+  name?: string;
+  target: string;
+  path?: string;
+  ingress?: string;
+  timeoutMs?: number;
+}
+
+export interface AppManifest {
+  apiVersion: 'takos.dev/v1alpha1';
+  kind: 'App';
+  metadata: {
+    name: string;
+    appId?: string;
+  };
+  spec: {
+    version: string;
+    description?: string;
+    icon?: string;
+    category?: string;
+    tags?: string[];
+    capabilities?: string[];
+    env?: {
+      required?: string[];
+    };
+    resources?: Record<string, AppResource>;
+    workers: Record<string, WorkerService>;
+    routes?: AppRoute[];
+  };
+}