otavia 0.1.0

package/src/deploy/cloudflare-dns.ts

@@ -0,0 +1,261 @@
+/**
+ * Cloudflare DNS + ACM certificate automation for deploy.
+ * Creates ACM cert, adds DNS validation record via Cloudflare API,
+ * waits for validation, then creates CNAME to CloudFront.
+ */
+
+type CloudflareDnsRecord = {
+  id: string;
+  name: string;
+  type: string;
+  content: string;
+};
+
+type AcmValidationRecord = {
+  Name: string;
+  Type: string;
+  Value: string;
+};
+
+type AwsRunner = (
+  args: string[],
+  env: Record<string, string | undefined>,
+  opts?: { pipeStderr?: boolean }
+) => Promise<{ exitCode: number; stdout: string }>;
+
+export type CloudflareDnsOptions = {
+  domainHost: string;
+  zoneId: string;
+  cloudflareToken: string;
+  awsEnv: Record<string, string | undefined>;
+  awsCli: AwsRunner;
+  region?: string;
+};
+
+async function cfApi(
+  path: string,
+  token: string,
+  options?: { method?: string; body?: unknown }
+): Promise<unknown> {
+  const res = await fetch(`https://api.cloudflare.com/client/v4${path}`, {
+    method: options?.method ?? "GET",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: options?.body ? JSON.stringify(options.body) : undefined,
+  });
+  const data = (await res.json()) as { success: boolean; result: unknown; errors?: unknown[] };
+  if (!data.success) {
+    throw new Error(`Cloudflare API error: ${JSON.stringify(data.errors)}`);
+  }
+  return data.result;
+}
+
+/** Request ACM certificate and return ARN. */
+async function requestAcmCertificate(
+  domainHost: string,
+  awsCli: AwsRunner,
+  awsEnv: Record<string, string | undefined>,
+  region: string,
+): Promise<string> {
+  const { exitCode, stdout } = await awsCli(
+    [
+      "acm", "request-certificate",
+      "--domain-name", domainHost,
+      "--validation-method", "DNS",
+      "--region", region,
+      "--output", "json",
+    ],
+    awsEnv,
+    { pipeStderr: true },
+  );
+  if (exitCode !== 0) throw new Error("Failed to request ACM certificate");
+  const data = JSON.parse(stdout) as { CertificateArn: string };
+  return data.CertificateArn;
+}
+
+/** Get DNS validation record from ACM certificate. Retries until available. */
+async function getAcmValidationRecord(
+  certArn: string,
+  awsCli: AwsRunner,
+  awsEnv: Record<string, string | undefined>,
+  region: string,
+): Promise<AcmValidationRecord> {
+  for (let i = 0; i < 30; i++) {
+    const { exitCode, stdout } = await awsCli(
+      [
+        "acm", "describe-certificate",
+        "--certificate-arn", certArn,
+        "--region", region,
+        "--query", "Certificate.DomainValidationOptions[0].ResourceRecord",
+        "--output", "json",
+      ],
+      awsEnv,
+      { pipeStderr: true },
+    );
+    if (exitCode === 0) {
+      const record = JSON.parse(stdout) as AcmValidationRecord | null;
+      if (record?.Name && record?.Value) return record;
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  throw new Error("Timed out waiting for ACM validation record");
+}
+
+/** Create or update a DNS record in Cloudflare. */
+async function upsertCloudflareRecord(
+  zoneId: string,
+  token: string,
+  name: string,
+  type: string,
+  content: string,
+): Promise<void> {
+  const cleanName = name.replace(/\.$/, "");
+  const cleanContent = content.replace(/\.$/, "");
+
+  // Search for existing record — use search param for partial match since
+  // Cloudflare's exact name filter can miss records with zone suffix appended
+  const allRecords = (await cfApi(
+    `/zones/${zoneId}/dns_records?type=${type}&per_page=100`,
+    token,
+  )) as CloudflareDnsRecord[];
+  const existing = allRecords.filter(
+    (r) => r.name === cleanName || r.name.startsWith(cleanName.split(".")[0]),
+  );
+
+  if (existing.length > 0) {
+    // Update existing
+    await cfApi(`/zones/${zoneId}/dns_records/${existing[0].id}`, token, {
+      method: "PUT",
+      body: { type, name: cleanName, content: cleanContent, ttl: 1, proxied: false },
+    });
+  } else {
+    // Create new
+    await cfApi(`/zones/${zoneId}/dns_records`, token, {
+      method: "POST",
+      body: { type, name: cleanName, content: cleanContent, ttl: 1, proxied: false },
+    });
+  }
+}
+
+/** Wait for ACM certificate to be issued. */
+async function waitForAcmValidation(
+  certArn: string,
+  awsCli: AwsRunner,
+  awsEnv: Record<string, string | undefined>,
+  region: string,
+): Promise<void> {
+  console.log("  Waiting for ACM certificate validation...");
+  for (let i = 0; i < 60; i++) {
+    const { exitCode, stdout } = await awsCli(
+      [
+        "acm", "describe-certificate",
+        "--certificate-arn", certArn,
+        "--region", region,
+        "--query", "Certificate.Status",
+        "--output", "text",
+      ],
+      awsEnv,
+      { pipeStderr: true },
+    );
+    if (exitCode === 0) {
+      const status = stdout.trim();
+      if (status === "ISSUED") {
+        console.log("  Certificate issued.");
+        return;
+      }
+      if (status === "FAILED") {
+        throw new Error("ACM certificate validation failed");
+      }
+    }
+    if (i % 5 === 0 && i > 0) console.log(`  Still waiting... (${i * 5}s)`);
+    await new Promise((r) => setTimeout(r, 5000));
+  }
+  throw new Error("Timed out waiting for ACM certificate validation (5 minutes)");
+}
+
+/** Check if an ISSUED ACM certificate already exists for the domain. */
+async function findExistingCertificate(
+  domainHost: string,
+  awsCli: AwsRunner,
+  awsEnv: Record<string, string | undefined>,
+  region: string,
+): Promise<string | null> {
+  const { exitCode, stdout } = await awsCli(
+    [
+      "acm", "list-certificates",
+      "--region", region,
+      "--query", `CertificateSummaryList[?DomainName=='${domainHost}' && Status=='ISSUED'].CertificateArn | [0]`,
+      "--output", "text",
+    ],
+    awsEnv,
+    { pipeStderr: true },
+  );
+  if (exitCode !== 0) return null;
+  const arn = stdout.trim();
+  return arn && arn !== "None" ? arn : null;
+}
+
+/**
+ * Ensure ACM certificate exists for domain with Cloudflare DNS validation.
+ * Returns certificate ARN.
+ */
+export async function ensureAcmCertificateWithCloudflare(
+  opts: CloudflareDnsOptions,
+): Promise<string> {
+  const region = opts.region ?? "us-east-1";
+
+  // Check for existing valid certificate
+  const existing = await findExistingCertificate(opts.domainHost, opts.awsCli, opts.awsEnv, region);
+  if (existing) {
+    console.log(`  Using existing ACM certificate: ${existing}`);
+    return existing;
+  }
+
+  // Request new certificate
+  console.log(`  Requesting ACM certificate for ${opts.domainHost}...`);
+  const certArn = await requestAcmCertificate(opts.domainHost, opts.awsCli, opts.awsEnv, region);
+  console.log(`  Certificate ARN: ${certArn}`);
+
+  // Get validation record
+  const validationRecord = await getAcmValidationRecord(certArn, opts.awsCli, opts.awsEnv, region);
+  console.log(`  Adding DNS validation record to Cloudflare...`);
+
+  // Create validation record in Cloudflare
+  await upsertCloudflareRecord(
+    opts.zoneId,
+    opts.cloudflareToken,
+    validationRecord.Name,
+    validationRecord.Type,
+    validationRecord.Value,
+  );
+  console.log(`  DNS record created: ${validationRecord.Name}`);
+
+  // Wait for validation
+  await waitForAcmValidation(certArn, opts.awsCli, opts.awsEnv, region);
+
+  return certArn;
+}
+
+/**
+ * Create CNAME record pointing domain to CloudFront distribution.
+ */
+export async function createCloudFrontDnsRecord(
+  opts: {
+    domainHost: string;
+    cloudFrontDomain: string;
+    zoneId: string;
+    cloudflareToken: string;
+  },
+): Promise<void> {
+  console.log(`  Creating DNS record: ${opts.domainHost} → ${opts.cloudFrontDomain}`);
+  await upsertCloudflareRecord(
+    opts.zoneId,
+    opts.cloudflareToken,
+    opts.domainHost,
+    "CNAME",
+    opts.cloudFrontDomain,
+  );
+  console.log(`  DNS record created.`);
+}

package/src/deploy/cloudfront.ts

@@ -0,0 +1,228 @@
+/**
+ * Generate CloudFront distribution: single domain, path behaviors per cell.
+ * Reference: cell-cli cloudfront.ts generateCloudFrontPlatform.
+ */
+
+const CACHING_DISABLED_POLICY = "4135ea2d-6df8-44a3-9df3-4b5a84be39ad";
+const CACHING_OPTIMIZED_POLICY = "658327ea-f89d-4fab-a63d-7e88639e58f6";
+
+export interface GenerateCloudFrontOptions {
+  domainHost: string;
+  defaultOriginId: string;
+  /** Root path ("/") should redirect to /<mount>/ when set. */
+  defaultCellMount?: string;
+  /** S3 frontend bucket ref - used for default origin */
+  frontendBucketRef?: string;
+  /** Path behaviors: pathPattern (e.g. /sso/*) -> originId. API origins use originId as Api Ref. */
+  pathBehaviors: Array<{ pathPattern: string; originId: string; isApi?: boolean }>;
+  hostedZoneId?: string;
+  certificateArn?: string;
+  stackName: string;
+}
+
+import type { CfnFragment } from "./types.js";
+
+export function generateCloudFrontDistribution(options: GenerateCloudFrontOptions): CfnFragment {
+  const {
+    domainHost,
+    defaultOriginId,
+    defaultCellMount,
+    frontendBucketRef = "FrontendBucket",
+    pathBehaviors,
+    hostedZoneId,
+    certificateArn,
+    stackName,
+  } = options;
+
+  const resources: Record<string, unknown> = {};
+  const conditions: Record<string, unknown> = {};
+  const rootRedirectPath = defaultCellMount ? `/${defaultCellMount}/` : "/";
+  const rootIndexPath = defaultCellMount ? `/${defaultCellMount}/index.html` : "/index.html";
+
+  const autoCert = !certificateArn && !!domainHost && !!hostedZoneId;
+  let certificateRef: unknown;
+  if (autoCert) {
+    resources.AcmCertificate = {
+      Type: "AWS::CertificateManager::Certificate",
+      Properties: {
+        DomainName: domainHost,
+        ValidationMethod: "DNS",
+        DomainValidationOptions: [{ DomainName: domainHost, HostedZoneId: hostedZoneId }],
+      },
+    };
+    certificateRef = { Ref: "AcmCertificate" };
+  } else if (certificateArn) {
+    certificateRef = certificateArn;
+  }
+
+  const useCustomDomain = !!domainHost && (autoCert || !!certificateArn);
+  conditions.UseCustomDomain = {
+    "Fn::Not": [{ "Fn::Equals": [useCustomDomain ? domainHost : "", ""] }],
+  };
+
+  resources.FrontendOAC = {
+    Type: "AWS::CloudFront::OriginAccessControl",
+    Properties: {
+      OriginAccessControlConfig: {
+        Name: `${stackName}-frontend-oac`,
+        OriginAccessControlOriginType: "s3",
+        SigningBehavior: "always",
+        SigningProtocol: "sigv4",
+      },
+    },
+  };
+
+  resources.SpaRewriteFunction = {
+    Type: "AWS::CloudFront::Function",
+    Properties: {
+      Name: `${stackName}-spa-rewrite`,
+      AutoPublish: true,
+      FunctionCode: [
+        "function handler(event) {",
+        "  var uri = event.request.uri;",
+        `  var rootRedirectPath = ${JSON.stringify(rootRedirectPath)};`,
+        `  var rootIndexPath = ${JSON.stringify(rootIndexPath)};`,
+        "  if (uri === '/') {",
+        "    return {",
+        "      statusCode: 302,",
+        "      statusDescription: 'Found',",
+        "      headers: {",
+        "        location: { value: rootRedirectPath }",
+        "      }",
+        "    };",
+        "  } else if (uri.lastIndexOf('.') <= uri.lastIndexOf('/')) {",
+        "    var parts = uri.split('/').filter(Boolean);",
+        "    if (parts.length > 0) {",
+        "      event.request.uri = '/' + parts[0] + '/index.html';",
+        "    } else {",
+        "      event.request.uri = rootIndexPath;",
+        "    }",
+        "  }",
+        "  return event.request;",
+        "}",
+      ].join("\n"),
+      FunctionConfig: {
+        Comment: "SPA fallback",
+        Runtime: "cloudfront-js-2.0",
+      },
+    },
+  };
+
+  const origins: unknown[] = [
+    {
+      Id: defaultOriginId,
+      DomainName: { "Fn::GetAtt": [frontendBucketRef, "RegionalDomainName"] },
+      OriginAccessControlId: { "Fn::GetAtt": ["FrontendOAC", "Id"] },
+      S3OriginConfig: { OriginAccessIdentity: "" },
+    },
+  ];
+
+  const seenApiOrigins = new Set<string>();
+  for (const b of pathBehaviors) {
+    if (b.isApi && !seenApiOrigins.has(b.originId)) {
+      seenApiOrigins.add(b.originId);
+      origins.push({
+        Id: b.originId,
+        DomainName: {
+          "Fn::Sub": `\${${b.originId}}.execute-api.\${AWS::Region}.amazonaws.com`,
+        },
+        CustomOriginConfig: {
+          HTTPSPort: 443,
+          OriginProtocolPolicy: "https-only",
+        },
+      });
+    }
+  }
+
+  const cacheBehaviors = pathBehaviors.map((b) => ({
+    PathPattern: b.pathPattern,
+    TargetOriginId: b.originId,
+    ViewerProtocolPolicy: "https-only" as const,
+    AllowedMethods: ["GET", "HEAD", "OPTIONS", "PUT", "POST", "PATCH", "DELETE"],
+    Compress: true,
+    CachePolicyId: CACHING_DISABLED_POLICY,
+    OriginRequestPolicyId: "b689b0a8-53d0-40ab-baf2-68738e2966ac",
+  }));
+
+  resources.FrontendCloudFront = {
+    Type: "AWS::CloudFront::Distribution",
+    Properties: {
+      DistributionConfig: {
+        Enabled: true,
+        DefaultRootObject: "index.html",
+        Origins: origins,
+        DefaultCacheBehavior: {
+          TargetOriginId: defaultOriginId,
+          ViewerProtocolPolicy: "redirect-to-https",
+          AllowedMethods: ["GET", "HEAD", "OPTIONS"],
+          Compress: true,
+          CachePolicyId: CACHING_OPTIMIZED_POLICY,
+          FunctionAssociations: [
+            {
+              EventType: "viewer-request",
+              FunctionARN: { "Fn::GetAtt": ["SpaRewriteFunction", "FunctionARN"] },
+            },
+          ],
+        },
+        CacheBehaviors: cacheBehaviors,
+        Aliases: {
+          "Fn::If": ["UseCustomDomain", [domainHost], { Ref: "AWS::NoValue" }],
+        },
+        ViewerCertificate: {
+          "Fn::If": [
+            "UseCustomDomain",
+            {
+              AcmCertificateArn: certificateRef,
+              SslSupportMethod: "sni-only",
+              MinimumProtocolVersion: "TLSv1.2_2021",
+            },
+            { CloudFrontDefaultCertificate: true },
+          ],
+        },
+      },
+    },
+  };
+
+  resources.FrontendBucketPolicy = {
+    Type: "AWS::S3::BucketPolicy",
+    DependsOn: "FrontendCloudFront",
+    Properties: {
+      Bucket: { Ref: frontendBucketRef },
+      PolicyDocument: {
+        Version: "2012-10-17",
+        Statement: [
+          {
+            Sid: "AllowCloudFrontOAC",
+            Effect: "Allow",
+            Principal: { Service: "cloudfront.amazonaws.com" },
+            Action: "s3:GetObject",
+            Resource: { "Fn::Sub": `\${${frontendBucketRef}.Arn}/*` },
+            Condition: {
+              StringEquals: {
+                "AWS:SourceArn": {
+                  "Fn::Sub":
+                    "arn:aws:cloudfront::${AWS::AccountId}:distribution/${FrontendCloudFront}",
+                },
+              },
+            },
+          },
+        ],
+      },
+    },
+  };
+
+  return {
+    Resources: resources,
+    Outputs: {
+      FrontendUrl: {
+        Description: "CloudFront URL",
+        Value: { "Fn::Sub": "https://${FrontendCloudFront.DomainName}" },
+      },
+      FrontendDistributionId: {
+        Description: "CloudFront distribution ID",
+        Value: { Ref: "FrontendCloudFront" },
+      },
+    },
+    Conditions: conditions,
+  };
+}

package/src/deploy/dynamodb.ts

@@ -0,0 +1,68 @@
+import type { TableConfig } from "../config/cell-yaml-schema.js";
+import type { CfnFragment } from "./types.js";
+import { toPascalCase } from "./types.js";
+
+/**
+ * Generate a single DynamoDB table fragment.
+ * Uses KeySchema, AttributeDefinitions, BillingMode PAY_PER_REQUEST, GSI if present.
+ */
+export function generateDynamoDBTable(
+  tableName: string,
+  tableKey: string,
+  config: TableConfig
+): CfnFragment {
+  const logicalId = `${toPascalCase(tableKey)}Table`;
+  const keys = Object.entries(config.keys);
+
+  const attrMap = new Map<string, string>();
+  for (const [name, type] of keys) {
+    attrMap.set(name, type);
+  }
+  if (config.gsi) {
+    for (const gsi of Object.values(config.gsi)) {
+      for (const [name, type] of Object.entries(gsi.keys)) {
+        attrMap.set(name, type);
+      }
+    }
+  }
+
+  const properties: Record<string, unknown> = {
+    TableName: tableName,
+    BillingMode: "PAY_PER_REQUEST",
+    AttributeDefinitions: [...attrMap.entries()].map(([name, type]) => ({
+      AttributeName: name,
+      AttributeType: type,
+    })),
+    KeySchema: keys.map(([name], i) => ({
+      AttributeName: name,
+      KeyType: i === 0 ? "HASH" : "RANGE",
+    })),
+  };
+
+  if (config.gsi) {
+    properties.GlobalSecondaryIndexes = Object.entries(config.gsi).map(
+      ([indexName, gsi]) => ({
+        IndexName: indexName,
+        KeySchema: Object.entries(gsi.keys).map(([name], i) => ({
+          AttributeName: name,
+          KeyType: i === 0 ? "HASH" : "RANGE",
+        })),
+        Projection: { ProjectionType: gsi.projection },
+      })
+    );
+  }
+
+  return {
+    Resources: {
+      [logicalId]: {
+        Type: "AWS::DynamoDB::Table",
+        Properties: properties,
+      },
+    },
+    Outputs: {
+      [`${logicalId}Arn`]: {
+        Value: { "Fn::GetAtt": [logicalId, "Arn"] },
+      },
+    },
+  };
+}

package/src/deploy/lambda.ts

@@ -0,0 +1,121 @@
+import type { CfnFragment } from "./types.js";
+import { toPascalCase } from "./types.js";
+
+export interface LambdaFragmentProps {
+  handlerPath: string;
+  runtime: string;
+  timeout: number;
+  memory: number;
+  envVars: Record<string, string>;
+  /** Logical IDs of DynamoDB table resources (e.g. SsoThreadsTable) for IAM */
+  tableLogicalIds?: string[];
+  /** Logical IDs of S3 bucket resources for IAM */
+  bucketLogicalIds?: string[];
+  /** For Secrets Manager refs: key -> secret name (cell/secretName) */
+  secretRefs?: Record<string, string>;
+}
+
+/**
+ * Generate Lambda function + IAM role for one backend entry.
+ * Env vars from resolved params; IAM policy for DynamoDB and S3 if provided.
+ */
+export function generateLambdaFragment(
+  entryKey: string,
+  logicalIdPrefix: string,
+  props: LambdaFragmentProps
+): CfnFragment {
+  const pascalEntry = toPascalCase(entryKey);
+  const functionLogicalId = `${logicalIdPrefix}${pascalEntry}Function`;
+  const roleLogicalId = `${logicalIdPrefix}${pascalEntry}LambdaRole`;
+
+  const envVariables: Record<string, string> = { ...props.envVars };
+  if (props.secretRefs) {
+    for (const [key, secretName] of Object.entries(props.secretRefs)) {
+      envVariables[key] = `{{resolve:secretsmanager:${secretName}}}`;
+    }
+  }
+
+  const policyStatements: unknown[] = [
+    {
+      Effect: "Allow",
+      Action: ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
+      Resource: "*",
+    },
+  ];
+
+  if (props.tableLogicalIds && props.tableLogicalIds.length > 0) {
+    const tableResources: unknown[] = [];
+    for (const id of props.tableLogicalIds) {
+      tableResources.push({ "Fn::GetAtt": [id, "Arn"] });
+      tableResources.push({ "Fn::Sub": `\${${id}.Arn}/index/*` });
+    }
+    policyStatements.push({
+      Effect: "Allow",
+      Action: [
+        "dynamodb:GetItem",
+        "dynamodb:PutItem",
+        "dynamodb:UpdateItem",
+        "dynamodb:DeleteItem",
+        "dynamodb:Query",
+        "dynamodb:BatchGetItem",
+        "dynamodb:BatchWriteItem",
+        "dynamodb:Scan",
+      ],
+      Resource: tableResources,
+    });
+  }
+
+  if (props.bucketLogicalIds && props.bucketLogicalIds.length > 0) {
+    const bucketResources: unknown[] = [];
+    for (const id of props.bucketLogicalIds) {
+      bucketResources.push({ "Fn::GetAtt": [id, "Arn"] });
+      bucketResources.push({ "Fn::Sub": `\${${id}.Arn}/*` });
+    }
+    policyStatements.push({
+      Effect: "Allow",
+      Action: ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"],
+      Resource: bucketResources,
+    });
+  }
+
+  const resources: Record<string, unknown> = {
+    [roleLogicalId]: {
+      Type: "AWS::IAM::Role",
+      Properties: {
+        AssumeRolePolicyDocument: {
+          Version: "2012-10-17",
+          Statement: [
+            {
+              Effect: "Allow",
+              Principal: { Service: "lambda.amazonaws.com" },
+              Action: "sts:AssumeRole",
+            },
+          ],
+        },
+        Policies: [
+          {
+            PolicyName: "LambdaPolicy",
+            PolicyDocument: {
+              Version: "2012-10-17",
+              Statement: policyStatements,
+            },
+          },
+        ],
+      },
+    },
+    [functionLogicalId]: {
+      Type: "AWS::Lambda::Function",
+      Properties: {
+        Runtime: props.runtime,
+        Handler: "index.handler",
+        Code: { S3Bucket: "PLACEHOLDER", S3Key: props.handlerPath },
+        Timeout: props.timeout,
+        MemorySize: props.memory,
+        Role: { "Fn::GetAtt": [roleLogicalId, "Arn"] },
+        Environment: { Variables: envVariables },
+      },
+    },
+  };
+
+  return { Resources: resources };
+}