otavia 0.1.0

package/src/config/otavia-yaml-schema.ts

@@ -0,0 +1,49 @@
+/**
+ * Schema types for otavia.yaml
+ */
+
+export interface OtaviaYamlDns {
+  provider?: string;
+  zone?: string;
+  zoneId?: string;
+}
+
+export interface OtaviaYamlDomain {
+  host: string;
+  dns?: OtaviaYamlDns;
+}
+
+export interface OtaviaYamlOAuthCallback {
+  /** Cell name mounted in otavia paths, e.g. "sso". */
+  cell: string;
+  /** Callback path inside that cell, e.g. "/oauth/callback". */
+  path: string;
+}
+
+export interface OtaviaYamlOAuth {
+  callback?: OtaviaYamlOAuthCallback;
+}
+
+/** One cell in the stack: mount path segment (e.g. "sso") and its package (e.g. "@otavia/sso"). */
+export interface CellEntry {
+  mount: string;
+  package: string;
+  params?: Record<string, unknown>;
+}
+
+/**
+ * cellsList is the canonical form: ordered list of { package, mount, params? }.
+ * cells keeps a compatibility map mount -> package for display/legacy behavior.
+ */
+export interface OtaviaYaml {
+  stackName: string;
+  /** Optional default cell for "/" redirect (fallback: first cell mount). */
+  defaultCell?: string;
+  /** mount -> package (for display/serialization). Use cellsList for iteration. */
+  cells: Record<string, string>;
+  /** Ordered list of { mount, package }; first is default/first cell. */
+  cellsList: CellEntry[];
+  domain: OtaviaYamlDomain;
+  params?: Record<string, unknown>;
+  oauth?: OtaviaYamlOAuth;
+}

package/src/config/ports.ts

@@ -0,0 +1,57 @@
+export type PortStage = "dev" | "test";
+
+export type StagePorts = {
+  portBase: number;
+  frontend: number;
+  backend: number;
+  dynamodb: number;
+  minio: number;
+};
+
+type PortOffsets = {
+  frontend: number;
+  backend: number;
+  dynamodb: number;
+  minio: number;
+};
+
+const OFFSETS: Record<PortStage, PortOffsets> = {
+  dev: {
+    frontend: 100,
+    backend: 1900,
+    dynamodb: 2001,
+    minio: 2000,
+  },
+  test: {
+    frontend: 100,
+    backend: 910,
+    dynamodb: 12,
+    minio: 1014,
+  },
+};
+
+export function resolvePortsFromPortBase(stage: PortStage, portBase: number): StagePorts {
+  const offsets = OFFSETS[stage];
+  return {
+    portBase,
+    frontend: portBase + offsets.frontend,
+    backend: portBase + offsets.backend,
+    dynamodb: portBase + offsets.dynamodb,
+    minio: portBase + offsets.minio,
+  };
+}
+
+export function resolvePortsFromEnv(
+  stage: PortStage,
+  env: Record<string, string | undefined> = process.env
+): StagePorts {
+  const raw = env.PORT_BASE?.trim();
+  if (!raw) {
+    throw new Error(`Missing PORT_BASE for stage "${stage}". Define it in .env.dev/.env.test or process env.`);
+  }
+  const portBase = Number.parseInt(raw, 10);
+  if (!Number.isFinite(portBase)) {
+    throw new Error(`Invalid PORT_BASE for stage "${stage}": "${raw}"`);
+  }
+  return resolvePortsFromPortBase(stage, portBase);
+}

package/src/config/resolve-cell-dir.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Resolve cell package root directory from project root by package name (e.g. @otavia/sso) or mount slug.
+ *
+ * **Default layout:** `cells/<name>/cell.yaml` (name = mount or last segment of package name).
+ * For scoped packages, `cells/<slug>` is checked before `apps/<slug>` and before `node_modules`.
+ */
+export function resolveCellDir(rootDir: string, packageOrMount: string): string {
+  const isPackageName = packageOrMount.includes("/") || packageOrMount.startsWith("@");
+  if (isPackageName) {
+    const slug = packageOrMount.split("/").pop() ?? packageOrMount;
+    const cellsSlug = resolve(rootDir, "cells", slug);
+    if (existsSync(resolve(cellsSlug, "cell.yaml"))) return cellsSlug;
+    const appsSlug = resolve(rootDir, "apps", slug);
+    if (existsSync(resolve(appsSlug, "cell.yaml"))) return appsSlug;
+    const dir = resolveCellDirByPackage(rootDir, packageOrMount);
+    if (dir) return dir;
+    return cellsSlug;
+  }
+  const cellsSubdir = resolve(rootDir, "cells", packageOrMount);
+  if (existsSync(resolve(cellsSubdir, "cell.yaml"))) {
+    return cellsSubdir;
+  }
+  const appsSubdir = resolve(rootDir, "apps", packageOrMount);
+  if (existsSync(resolve(appsSubdir, "cell.yaml"))) {
+    return appsSubdir;
+  }
+  const sibling = resolve(rootDir, "..", packageOrMount);
+  if (existsSync(resolve(sibling, "cell.yaml"))) {
+    return sibling;
+  }
+  return cellsSubdir;
+}
+
+/**
+ * Find package root (directory containing cell.yaml) by walking node_modules from rootDir upward.
+ */
+function resolveCellDirByPackage(rootDir: string, packageName: string): string | null {
+  let dir = resolve(rootDir);
+  const parts = packageName.split("/");
+  const pkgPath = parts.length === 2 && packageName.startsWith("@")
+    ? `${parts[0]}/${parts[1]}`
+    : parts[0];
+  while (dir !== resolve(dir, "..")) {
+    const candidate = resolve(dir, "node_modules", pkgPath);
+    const cellYaml = resolve(candidate, "cell.yaml");
+    if (existsSync(cellYaml)) {
+      return candidate;
+    }
+    dir = resolve(dir, "..");
+  }
+  return null;
+}

package/src/config/resolve-params.ts

@@ -0,0 +1,160 @@
+import { isEnvRef, isParamRef, isSecretRef } from "./cell-yaml-schema.js";
+
+/** Thrown when a required !Env or !Secret is missing from envMap and onMissingParam is "throw". */
+export class MissingParamsError extends Error {
+  readonly missingKeys: string[];
+
+  constructor(missingKeys: string[]) {
+    const message = [
+      "",
+      "Missing required params:",
+      ...missingKeys.map((k) => `  ${k}`),
+      "",
+      "Add them to your .env files, then retry.",
+      "",
+    ].join("\n");
+    super(message);
+    this.name = "MissingParamsError";
+    this.missingKeys = missingKeys;
+  }
+}
+
+/** Thrown when a cell declares required params but otavia.yaml does not provide values. */
+export class MissingDeclaredParamsError extends Error {
+  readonly missingKeys: string[];
+
+  constructor(missingKeys: string[], context?: string) {
+    const header = context ? `Missing required params for ${context}:` : "Missing required params:";
+    const message = ["", header, ...missingKeys.map((k) => `  ${k}`), ""].join("\n");
+    super(message);
+    this.name = "MissingDeclaredParamsError";
+    this.missingKeys = missingKeys;
+  }
+}
+
+/** True if value is a plain object (nested config), not EnvRef/SecretRef. */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    !Array.isArray(v) &&
+    !isEnvRef(v) &&
+    !isSecretRef(v)
+  );
+}
+
+/**
+ * Merge stack and cell params; top-level key override: cell wins over stack.
+ */
+export function mergeParams(
+  stackParams?: Record<string, unknown>,
+  cellParams?: Record<string, unknown>
+): Record<string, unknown> {
+  const stack = stackParams ?? {};
+  const cell = cellParams ?? {};
+
+  function resolveCellValue(value: unknown): unknown {
+    if (isParamRef(value)) {
+      return stack[value.param];
+    }
+    if (Array.isArray(value)) {
+      return value.map((v) => resolveCellValue(v));
+    }
+    if (typeof value === "object" && value !== null) {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        out[k] = resolveCellValue(v);
+      }
+      return out;
+    }
+    return value;
+  }
+
+  const resolvedCell: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(cell)) {
+    resolvedCell[k] = resolveCellValue(v);
+  }
+  return { ...stack, ...resolvedCell };
+}
+
+/**
+ * Validate that all declared param keys exist in provided params.
+ * Value `undefined` is treated as missing.
+ */
+export function assertDeclaredParamsProvided(
+  declaredParams: string[] | undefined,
+  providedParams: Record<string, unknown>,
+  context?: string
+): void {
+  if (!declaredParams || declaredParams.length === 0) return;
+  const missing: string[] = [];
+  for (const key of declaredParams) {
+    if (!Object.prototype.hasOwnProperty.call(providedParams, key) || providedParams[key] === undefined) {
+      missing.push(key);
+    }
+  }
+  if (missing.length > 0) {
+    throw new MissingDeclaredParamsError(missing, context);
+  }
+}
+
+const PLACEHOLDER = "[missing]";
+
+/**
+ * Resolve !Env and !Secret in merged params using envMap.
+ * Recurses into nested objects; only leaf EnvRef/SecretRef are replaced.
+ * - onMissingParam "throw": throw MissingParamsError with list of missing keys.
+ * - onMissingParam "placeholder": use PLACEHOLDER for missing values.
+ */
+export function resolveParams(
+  mergedParams: Record<string, unknown>,
+  envMap: Record<string, string>,
+  options?: { onMissingParam?: "throw" | "placeholder" }
+): Record<string, string | unknown> {
+  const onMissing = options?.onMissingParam ?? "throw";
+  const missingKeys: string[] = [];
+
+  function resolveValue(value: unknown): string | unknown {
+    if (isEnvRef(value)) {
+      const v = envMap[value.env];
+      if (v === undefined) {
+        if (onMissing === "throw") {
+          missingKeys.push(value.env);
+          return value;
+        }
+        return PLACEHOLDER;
+      }
+      return v;
+    }
+    if (isSecretRef(value)) {
+      const v = envMap[value.secret];
+      if (v === undefined) {
+        if (onMissing === "throw") {
+          missingKeys.push(value.secret);
+          return value;
+        }
+        return PLACEHOLDER;
+      }
+      return v;
+    }
+    if (isPlainObject(value)) {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(value)) {
+        out[k] = resolveValue(v);
+      }
+      return out;
+    }
+    return value;
+  }
+
+  const result: Record<string, string | unknown> = {};
+  for (const [key, value] of Object.entries(mergedParams)) {
+    result[key] = resolveValue(value);
+  }
+
+  if (onMissing === "throw" && missingKeys.length > 0) {
+    throw new MissingParamsError([...new Set(missingKeys)]);
+  }
+
+  return result;
+}

package/src/config/resource-names.ts

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+
+const S3_BUCKET_MAX_LENGTH = 63;
+const HASH_SUFFIX_LENGTH = 8;
+
+/**
+ * Normalize a segment for use in physical resource names: lowercase, hyphens only.
+ * S3 bucket names allow only lowercase, digits, and hyphens (no underscore).
+ */
+function normalizeSegment(s: string): string {
+  return s.toLowerCase().replace(/_/g, "-");
+}
+
+/**
+ * Build the base physical name: `<stackName>-<cellId>-<key>` normalized.
+ */
+function basePhysicalName(
+  stackName: string,
+  cellId: string,
+  key: string,
+): string {
+  const s = `${normalizeSegment(stackName)}-${normalizeSegment(cellId)}-${normalizeSegment(key)}`;
+  return s;
+}
+
+/**
+ * Table physical name for DynamoDB: `<stackName>-<cellId>-<tableKey>`.
+ * Normalized to lowercase with hyphens (any uppercase or underscore is normalized).
+ */
+export function tablePhysicalName(
+  stackName: string,
+  cellId: string,
+  tableKey: string,
+): string {
+  return basePhysicalName(stackName, cellId, tableKey);
+}
+
+/**
+ * Bucket physical name for S3: same pattern as table, but length must be ≤63.
+ * S3 rules: only lowercase, digits, hyphens (no underscore).
+ *
+ * Truncation rule when length > 63: take the first (63 - 1 - 8) = 54 characters
+ * of the full normalized name (so we truncate proportionally across stackName,
+ * cellId, and bucketKey), then append a hyphen and the first 8 hex chars of
+ * SHA256(full normalized string) so the result is unique and deterministic.
+ */
+export function bucketPhysicalName(
+  stackName: string,
+  cellId: string,
+  bucketKey: string,
+): string {
+  const full = basePhysicalName(stackName, cellId, bucketKey);
+  if (full.length <= S3_BUCKET_MAX_LENGTH) {
+    return full;
+  }
+  const truncateTo = S3_BUCKET_MAX_LENGTH - 1 - HASH_SUFFIX_LENGTH; // 54
+  const truncated = full.slice(0, truncateTo);
+  const hash = createHash("sha256").update(full).digest("hex").slice(0, HASH_SUFFIX_LENGTH);
+  return `${truncated}-${hash}`;
+}

package/src/deploy/__tests__/template.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { generateTemplate } from "../template.js";
+
+function createMinimalOtaviaRoot(): string {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "otavia-deploy-test-"));
+  fs.writeFileSync(
+    path.join(tmp, "otavia.yaml"),
+    `
+stackName: test-stack
+cells:
+  - sso
+domain:
+  host: example.com
+params:
+  FOO: bar
+`,
+    "utf-8"
+  );
+  const ssoDir = path.join(tmp, "apps", "sso");
+  fs.mkdirSync(ssoDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(ssoDir, "cell.yaml"),
+    `
+name: sso
+params:
+  - FOO
+tables:
+  users:
+    keys: { pk: S, sk: S }
+backend:
+  runtime: nodejs20.x
+  entries:
+    api:
+      handler: index.ts
+      timeout: 30
+      memory: 256
+      routes:
+        - /api/*
+`,
+    "utf-8"
+  );
+  return tmp;
+}
+
+describe("generateTemplate", () => {
+  test("produces valid YAML with AWS::DynamoDB::Table, AWS::Lambda::Function, and AWS::ApiGatewayV2::Api", () => {
+    const rootDir = createMinimalOtaviaRoot();
+    try {
+      const yaml = generateTemplate(rootDir);
+      expect(typeof yaml).toBe("string");
+      expect(yaml).toContain("AWSTemplateFormatVersion");
+      expect(yaml).toContain("Resources:");
+
+      expect(yaml).toContain("AWS::DynamoDB::Table");
+      expect(yaml).toContain("AWS::Lambda::Function");
+      expect(yaml).toContain("AWS::ApiGatewayV2::Api");
+
+      expect(yaml).toContain("SsoUsersTable");
+      expect(yaml).toContain("SsoApiFunction");
+      expect(yaml).toContain("SsoHttpApi");
+    } finally {
+      fs.rmSync(rootDir, { recursive: true });
+    }
+  });
+
+  test("includes frontend bucket and CloudFront when domain.host is set", () => {
+    const rootDir = createMinimalOtaviaRoot();
+    try {
+      const yaml = generateTemplate(rootDir);
+      expect(yaml).toContain("FrontendBucket");
+      expect(yaml).toContain("AWS::CloudFront::Distribution");
+    } finally {
+      fs.rmSync(rootDir, { recursive: true });
+    }
+  });
+
+  test("derives CloudFront API behaviors from backend entry routes", () => {
+    const rootDir = createMinimalOtaviaRoot();
+    try {
+      const yaml = generateTemplate(rootDir);
+      expect(yaml).toContain("PathPattern: /sso/api/*");
+      expect(yaml).not.toContain("PathPattern: /sso/*");
+    } finally {
+      fs.rmSync(rootDir, { recursive: true });
+    }
+  });
+
+  test("uses defaultCell as CloudFront root redirect target", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "otavia-deploy-test-"));
+    fs.writeFileSync(
+      path.join(tmp, "otavia.yaml"),
+      `
+stackName: test-stack
+defaultCell: drive
+cells:
+  sso: "@otavia/sso"
+  drive: "@otavia/drive"
+domain:
+  host: example.com
+`,
+      "utf-8"
+    );
+    const ssoDir = path.join(tmp, "apps", "sso");
+    fs.mkdirSync(ssoDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(ssoDir, "cell.yaml"),
+      `
+name: sso
+backend:
+  runtime: nodejs20.x
+  entries:
+    api:
+      handler: index.ts
+      timeout: 30
+      memory: 256
+      routes:
+        - /api/*
+`,
+      "utf-8"
+    );
+    const driveDir = path.join(tmp, "apps", "drive");
+    fs.mkdirSync(driveDir, { recursive: true });
+    fs.writeFileSync(path.join(driveDir, "cell.yaml"), "name: drive\n", "utf-8");
+    try {
+      const yaml = generateTemplate(tmp);
+      expect(yaml).toContain('var rootRedirectPath = "/drive/";');
+      expect(yaml).toContain("statusCode: 302");
+      expect(yaml).toContain("location: { value: rootRedirectPath }");
+      expect(yaml).not.toContain("event.request.uri = '/index.html';");
+    } finally {
+      fs.rmSync(tmp, { recursive: true });
+    }
+  });
+});

package/src/deploy/api-gateway.ts

@@ -0,0 +1,96 @@
+import type { CfnFragment } from "./types.js";
+import { toPascalCase } from "./types.js";
+
+export interface HttpApiRoute {
+  /** Logical id of the Lambda function (e.g. SsoApiFunction) */
+  functionLogicalId: string;
+}
+
+/**
+ * Generate API Gateway HTTP API with integrations to Lambda.
+ * One route per backend entry; path stripping: /<cellId>/api -> Lambda receives /api (handled by gateway/integration).
+ */
+export function generateHttpApi(
+  logicalIdPrefix: string,
+  apiName: string,
+  routes: HttpApiRoute[]
+): CfnFragment {
+  const resources: Record<string, unknown> = {};
+
+  const apiLogicalId = `${logicalIdPrefix}HttpApi`;
+  resources[apiLogicalId] = {
+    Type: "AWS::ApiGatewayV2::Api",
+    Properties: {
+      Name: apiName,
+      ProtocolType: "HTTP",
+      CorsConfiguration: {
+        AllowOrigins: ["*"],
+        AllowMethods: ["*"],
+        AllowHeaders: ["*"],
+      },
+    },
+  };
+
+  for (let i = 0; i < routes.length; i++) {
+    const route = routes[i];
+    const pascal = toPascalCase(route.functionLogicalId.replace(/Function$/, "") || "Default");
+    const integrationId = `${logicalIdPrefix}${pascal}Integration`;
+    const routeId = `${logicalIdPrefix}${pascal}Route`;
+    const permId = `${logicalIdPrefix}${pascal}LambdaPermission`;
+
+    resources[integrationId] = {
+      Type: "AWS::ApiGatewayV2::Integration",
+      Properties: {
+        ApiId: { Ref: apiLogicalId },
+        IntegrationType: "AWS_PROXY",
+        IntegrationUri: { "Fn::GetAtt": [route.functionLogicalId, "Arn"] },
+        PayloadFormatVersion: "2.0",
+      },
+    };
+
+    resources[routeId] = {
+      Type: "AWS::ApiGatewayV2::Route",
+      Properties: {
+        ApiId: { Ref: apiLogicalId },
+        RouteKey: "$default",
+        Target: {
+          "Fn::Sub": `integrations/\${${integrationId}}`,
+        },
+      },
+    };
+
+    resources[permId] = {
+      Type: "AWS::Lambda::Permission",
+      Properties: {
+        FunctionName: { Ref: route.functionLogicalId },
+        Action: "lambda:InvokeFunction",
+        Principal: "apigateway.amazonaws.com",
+        SourceArn: {
+          "Fn::Sub": `arn:aws:execute-api:\${AWS::Region}:\${AWS::AccountId}:\${${apiLogicalId}}/*`,
+        },
+      },
+    };
+  }
+
+  const stageLogicalId = `${logicalIdPrefix}HttpApiStage`;
+  resources[stageLogicalId] = {
+    Type: "AWS::ApiGatewayV2::Stage",
+    Properties: {
+      ApiId: { Ref: apiLogicalId },
+      StageName: "$default",
+      AutoDeploy: true,
+    },
+  };
+
+  return {
+    Resources: resources,
+    Outputs: {
+      [`${logicalIdPrefix}HttpApiId`]: { Value: { Ref: apiLogicalId } },
+      [`${logicalIdPrefix}HttpApiEndpoint`]: {
+        Value: {
+          "Fn::Sub": `https://\${${apiLogicalId}}.execute-api.\${AWS::Region}.amazonaws.com`,
+        },
+      },
+    },
+  };
+}