otavia 0.1.0

package/src/config/__tests__/resolve-params.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import {
+  assertDeclaredParamsProvided,
+  MissingDeclaredParamsError,
+  MissingParamsError,
+  mergeParams,
+  resolveParams,
+} from "../resolve-params.js";
+
+describe("mergeParams", () => {
+  test("stack has A, B; cell has B, C → result has A(from stack), B(from cell), C(from cell)", () => {
+    const stack = { A: "stackA", B: "stackB" };
+    const cell = { B: "cellB", C: "cellC" };
+    const result = mergeParams(stack, cell);
+    expect(result.A).toBe("stackA");
+    expect(result.B).toBe("cellB");
+    expect(result.C).toBe("cellC");
+  });
+
+  test("empty stack and cell returns empty object", () => {
+    expect(mergeParams(undefined, undefined)).toEqual({});
+    expect(mergeParams({}, {})).toEqual({});
+  });
+
+  test("cell-only params", () => {
+    expect(mergeParams(undefined, { x: 1 })).toEqual({ x: 1 });
+  });
+
+  test("stack-only params", () => {
+    expect(mergeParams({ x: 1 }, undefined)).toEqual({ x: 1 });
+  });
+
+  test("cell !Param references top-level params", () => {
+    const stack = { REGION: "us-east-1", API_KEY: { secret: "BFL_API_KEY" } };
+    const cell = {
+      REGION: { param: "REGION" },
+      BFL_API_KEY: { param: "API_KEY" },
+    };
+    expect(mergeParams(stack, cell)).toEqual({
+      REGION: "us-east-1",
+      API_KEY: { secret: "BFL_API_KEY" },
+      BFL_API_KEY: { secret: "BFL_API_KEY" },
+    });
+  });
+});
+
+describe("resolveParams", () => {
+  test("all EnvRef/SecretRef present in envMap → replaced with strings", () => {
+    const merged = {
+      API_URL: { env: "API_URL" },
+      TOKEN: { secret: "API_TOKEN" },
+      plain: "hello",
+    };
+    const envMap = { API_URL: "https://api.example.com", API_TOKEN: "s3cret" };
+    const result = resolveParams(merged, envMap);
+    expect(result.API_URL).toBe("https://api.example.com");
+    expect(result.TOKEN).toBe("s3cret");
+    expect(result.plain).toBe("hello");
+  });
+
+  test("nested object: EnvRef inside object is resolved", () => {
+    const merged = {
+      dns: {
+        provider: "cloudflare",
+        zoneId: { env: "ZONE_ID" },
+      },
+    };
+    const envMap = { ZONE_ID: "zone-123" };
+    const result = resolveParams(merged, envMap);
+    expect(result).toEqual({
+      dns: {
+        provider: "cloudflare",
+        zoneId: "zone-123",
+      },
+    });
+  });
+
+  test("missing env key with onMissingParam throw → throws MissingParamsError with missing key listed", () => {
+    const merged = {
+      API_URL: { env: "API_URL" },
+      KEY: { env: "MISSING_VAR" },
+    };
+    const envMap = { API_URL: "https://api.example.com" };
+    expect(() => resolveParams(merged, envMap)).toThrow(MissingParamsError);
+    try {
+      resolveParams(merged, envMap);
+    } catch (e) {
+      expect(e).toBeInstanceOf(MissingParamsError);
+      expect((e as MissingParamsError).missingKeys).toContain("MISSING_VAR");
+    }
+  });
+
+  test("missing secret with onMissingParam throw → throws MissingParamsError", () => {
+    const merged = { TOKEN: { secret: "MISSING_SECRET" } };
+    const envMap = {};
+    expect(() => resolveParams(merged, envMap)).toThrow(MissingParamsError);
+    try {
+      resolveParams(merged, envMap);
+    } catch (e) {
+      expect((e as MissingParamsError).missingKeys).toContain("MISSING_SECRET");
+    }
+  });
+
+  test("missing with onMissingParam placeholder → use placeholder for missing", () => {
+    const merged = {
+      API_URL: { env: "API_URL" },
+      MISSING: { env: "MISSING_VAR" },
+      TOKEN: { secret: "API_TOKEN" },
+    };
+    const envMap = { API_URL: "https://api.example.com" };
+    const result = resolveParams(merged, envMap, {
+      onMissingParam: "placeholder",
+    });
+    expect(result.API_URL).toBe("https://api.example.com");
+    expect(result.MISSING).toBe("[missing]");
+    expect(result.TOKEN).toBe("[missing]");
+  });
+
+  test("default onMissingParam is throw", () => {
+    const merged = { X: { env: "NOT_IN_ENV" } };
+    expect(() => resolveParams(merged, {})).toThrow(MissingParamsError);
+  });
+});
+
+describe("assertDeclaredParamsProvided", () => {
+  test("passes when all declared params are present", () => {
+    expect(() =>
+      assertDeclaredParamsProvided(["A", "B"], { A: 1, B: { env: "B" } }, "cell-a")
+    ).not.toThrow();
+  });
+
+  test("throws when declared params are missing", () => {
+    expect(() =>
+      assertDeclaredParamsProvided(["A", "B"], { A: 1 }, "cell-a")
+    ).toThrow(MissingDeclaredParamsError);
+  });
+});

package/src/config/__tests__/resource-names.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import {
+  bucketPhysicalName,
+  tablePhysicalName,
+} from "../resource-names.js";
+
+describe("tablePhysicalName", () => {
+  test("returns myapp-server-next-realms for (myapp, server-next, realms)", () => {
+    expect(tablePhysicalName("myapp", "server-next", "realms")).toBe(
+      "myapp-server-next-realms",
+    );
+  });
+
+  test("normalizes uppercase to lowercase", () => {
+    expect(tablePhysicalName("MyApp", "Server-Next", "Realms")).toBe(
+      "myapp-server-next-realms",
+    );
+  });
+
+  test("normalizes underscore to hyphen", () => {
+    expect(tablePhysicalName("my_app", "server_next", "realms_table")).toBe(
+      "my-app-server-next-realms-table",
+    );
+  });
+});
+
+describe("bucketPhysicalName", () => {
+  test("returns normalized name when length ≤63", () => {
+    const name = bucketPhysicalName("myapp", "server-next", "assets");
+    expect(name).toBe("myapp-server-next-assets");
+    expect(name.length).toBeLessThanOrEqual(63);
+  });
+
+  test("normalizes uppercase and underscore like table", () => {
+    expect(bucketPhysicalName("MyApp", "server_next", "Assets")).toBe(
+      "myapp-server-next-assets",
+    );
+  });
+
+  test("when total length > 63, result ≤63 and includes hash suffix", () => {
+    const stackName = "myapp";
+    const cellId = "server-next";
+    const bucketKey = "a".repeat(60);
+    const full = `${stackName}-${cellId}-${bucketKey}`;
+    expect(full.length).toBeGreaterThan(63);
+
+    const name = bucketPhysicalName(stackName, cellId, bucketKey);
+    expect(name.length).toBeLessThanOrEqual(63);
+    expect(name.length).toBe(63);
+    expect(name).toMatch(/^[a-z0-9-]+$/);
+    expect(name).toMatch(/-[a-f0-9]{8}$/);
+  });
+
+  test("same inputs produce same bucket name (deterministic)", () => {
+    const stackName = "longstack";
+    const cellId = "longcell";
+    const bucketKey = "x".repeat(50);
+    const a = bucketPhysicalName(stackName, cellId, bucketKey);
+    const b = bucketPhysicalName(stackName, cellId, bucketKey);
+    expect(a).toBe(b);
+  });
+});

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

@@ -0,0 +1,115 @@
+/**
+ * Schema types for otavia cell.yaml (otavia variant).
+ * Excludes: pathPrefix, bucketNameSuffix, dev, domain, domains, cloudflare, network.
+ */
+
+export type SecretRef = { secret: string };
+export type EnvRef = { env: string };
+export type ParamRef = { param: string };
+
+/**
+ * Param value shape used by config pipeline.
+ * NOTE: cell.yaml itself does not support !Env/!Secret; these refs come from otavia.yaml params.
+ */
+export type RawParamValue =
+  | string
+  | SecretRef
+  | EnvRef
+  | ParamRef
+  | Record<string, unknown>;
+
+export function isSecretRef(v: unknown): v is SecretRef {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    "secret" in v &&
+    !("env" in v)
+  );
+}
+
+export function isEnvRef(v: unknown): v is EnvRef {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    "env" in v &&
+    !("secret" in v)
+  );
+}
+
+export function isParamRef(v: unknown): v is ParamRef {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    "param" in v &&
+    !("env" in v) &&
+    !("secret" in v)
+  );
+}
+
+export interface BackendEntry {
+  handler: string;
+  app?: string;
+  timeout: number;
+  memory: number;
+  routes: string[];
+}
+
+export interface BackendConfig {
+  dir?: string;
+  runtime: string;
+  entries: Record<string, BackendEntry>;
+}
+
+export interface FrontendEntry {
+  entry: string;
+  routes: string[];
+}
+
+export interface FrontendConfig {
+  dir: string;
+  entries: Record<string, FrontendEntry>;
+}
+
+export interface TableGsi {
+  keys: Record<string, string>;
+  projection: string;
+}
+
+export interface TableConfig {
+  keys: Record<string, string>;
+  gsi?: Record<string, TableGsi>;
+}
+
+export interface TestingConfig {
+  unit?: string;
+  e2e?: string;
+}
+
+export type OAuthRole = "resource_server" | "authorization_server" | "both";
+
+export interface OAuthConfig {
+  enabled: boolean;
+  role: OAuthRole;
+  scopes: string[];
+}
+
+export interface CognitoConfig {
+  region: string;
+  userPoolId: string;
+  clientId: string;
+  hostedUiUrl?: string;
+  clientSecret?: string;
+}
+
+export interface CellConfig {
+  name: string;
+  backend?: BackendConfig;
+  frontend?: FrontendConfig;
+  testing?: TestingConfig;
+  tables?: Record<string, TableConfig>;
+  buckets?: Record<string, Record<string, unknown>>;
+  oauth?: OAuthConfig;
+  cognito?: CognitoConfig;
+  /** Declared required param keys; values are provided by otavia.yaml. */
+  params?: string[];
+}

package/src/config/load-cell-yaml.ts

@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "yaml";
+import type { CellConfig } from "./cell-yaml-schema.js";
+
+const OAUTH_ROLES = new Set(["resource_server", "authorization_server", "both"]);
+
+/**
+ * Load and parse cell.yaml from cellDir.
+ * cell.yaml should only declare required param keys; !Env/!Secret are not supported here.
+ */
+export function loadCellConfig(cellDir: string): CellConfig {
+  const filePath = path.join(cellDir, "cell.yaml");
+  let content: string;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to read cell.yaml: ${message}`);
+  }
+
+  if (/(^|[\s:[{,])!(Env|Secret)\b/m.test(content)) {
+    throw new Error("cell.yaml: !Env and !Secret are not supported; move refs to otavia.yaml params");
+  }
+
+  const doc = parseDocument(content);
+  const raw = doc.toJS() as Record<string, unknown> | null | undefined;
+
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("cell.yaml: invalid YAML or empty document");
+  }
+
+  const name = raw.name;
+  if (name == null) {
+    throw new Error("cell.yaml: missing required field 'name'");
+  }
+  if (typeof name !== "string" || name.trim() === "") {
+    throw new Error("cell.yaml: 'name' must be a non-empty string");
+  }
+
+  if (raw.params != null) {
+    if (!Array.isArray(raw.params)) {
+      throw new Error("cell.yaml: 'params' must be an array of strings");
+    }
+    for (let i = 0; i < raw.params.length; i += 1) {
+      if (typeof raw.params[i] !== "string" || raw.params[i].trim() === "") {
+        throw new Error(`cell.yaml: params[${i}] must be a non-empty string`);
+      }
+    }
+  }
+
+  if (raw.oauth != null) {
+    if (typeof raw.oauth !== "object" || Array.isArray(raw.oauth)) {
+      throw new Error("cell.yaml: 'oauth' must be an object");
+    }
+    const oauth = raw.oauth as Record<string, unknown>;
+    if ("issuerPath" in oauth) {
+      throw new Error("cell.yaml: 'oauth.issuerPath' is not supported in v1; issuer path is derived from mount");
+    }
+    if ("discovery" in oauth) {
+      throw new Error("cell.yaml: 'oauth.discovery' is not supported in v1; discovery is automatic for oauth-enabled cells");
+    }
+
+    if (typeof oauth.enabled !== "boolean") {
+      throw new Error("cell.yaml: 'oauth.enabled' must be a boolean");
+    }
+    if (typeof oauth.role !== "string" || !OAUTH_ROLES.has(oauth.role)) {
+      throw new Error(
+        "cell.yaml: 'oauth.role' must be one of: resource_server, authorization_server, both"
+      );
+    }
+    if (!Array.isArray(oauth.scopes)) {
+      throw new Error("cell.yaml: 'oauth.scopes' must be an array of strings");
+    }
+    for (let i = 0; i < oauth.scopes.length; i += 1) {
+      const scope = oauth.scopes[i];
+      if (typeof scope !== "string" || scope.trim() === "") {
+        throw new Error(`cell.yaml: oauth.scopes[${i}] must be a non-empty string`);
+      }
+    }
+    if (oauth.enabled && oauth.scopes.length === 0) {
+      throw new Error("cell.yaml: 'oauth.scopes' must be a non-empty array of strings when oauth.enabled is true");
+    }
+  }
+
+  return raw as unknown as CellConfig;
+}

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

@@ -0,0 +1,256 @@
+import fs from "fs";
+import path from "path";
+import { parseDocument, type SchemaOptions } from "yaml";
+import type { OtaviaYaml } from "./otavia-yaml-schema.js";
+import { isEnvRef, isParamRef, isSecretRef } from "./cell-yaml-schema.js";
+
+const CONFIG_FILENAME = "otavia.yaml";
+const DEFAULT_SCOPE = "@otavia";
+
+type CellRef = { mount: string; package: string; params?: Record<string, unknown> };
+
+const customTags: SchemaOptions["customTags"] = [
+  {
+    tag: "!Secret",
+    resolve(value: string) {
+      return { secret: value ?? "" };
+    },
+  },
+  {
+    tag: "!Env",
+    resolve(value: string) {
+      return { env: value ?? "" };
+    },
+  },
+  {
+    tag: "!Param",
+    resolve(value: string) {
+      return { param: value ?? "" };
+    },
+  },
+];
+
+function walkParamTree(
+  value: unknown,
+  pathLabel: string,
+  visitor: (v: unknown, p: string) => void
+): void {
+  visitor(value, pathLabel);
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return;
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    walkParamTree(v, `${pathLabel}.${k}`, visitor);
+  }
+}
+
+function packageToMount(packageName: string): string {
+  const trimmed = packageName.trim();
+  if (trimmed.length === 0) return trimmed;
+  const parts = trimmed.split("/");
+  return trimmed.startsWith("@") ? (parts[1] ?? "") : (parts[0] ?? "");
+}
+
+function normalizeParams(value: unknown, pathLabel: string): Record<string, unknown> | undefined {
+  if (value == null) return undefined;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${pathLabel} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseCells(data: unknown): { cells: Record<string, string>; cellsList: CellRef[] } {
+  if (data == null) {
+    throw new Error("otavia.yaml: missing cells");
+  }
+  if (Array.isArray(data)) {
+    if (data.length === 0) {
+      throw new Error("otavia.yaml: cells must be a non-empty array or object");
+    }
+    const cellsList: CellRef[] = [];
+    for (let i = 0; i < data.length; i += 1) {
+      const item = data[i];
+      const itemPath = `otavia.yaml: cells[${i}]`;
+      if (typeof item === "string") {
+        const mount = item.trim();
+        if (!mount) throw new Error(`${itemPath} must be a non-empty string`);
+        cellsList.push({ mount, package: `${DEFAULT_SCOPE}/${mount}` });
+        continue;
+      }
+      if (item == null || typeof item !== "object" || Array.isArray(item)) {
+        throw new Error(`${itemPath} must be a string or an object { package, mount?, params? }`);
+      }
+      const record = item as Record<string, unknown>;
+      const packageName = typeof record.package === "string" ? record.package.trim() : "";
+      if (!packageName) throw new Error(`${itemPath}.package must be a non-empty string`);
+      const mount =
+        typeof record.mount === "string" && record.mount.trim()
+          ? record.mount.trim()
+          : packageToMount(packageName);
+      if (!mount) throw new Error(`${itemPath}.mount is required when package cannot infer mount`);
+      const params = normalizeParams(record.params, `${itemPath}.params`);
+      cellsList.push({ mount, package: packageName, params });
+    }
+    const cells = Object.fromEntries(cellsList.map((c) => [c.mount, c.package]));
+    return { cells, cellsList };
+  }
+  if (typeof data === "object" && !Array.isArray(data)) {
+    const entries = Object.entries(data as Record<string, unknown>);
+    if (entries.length === 0) {
+      throw new Error("otavia.yaml: cells object must have at least one entry");
+    }
+    const cellsList: CellRef[] = [];
+    for (const [mountRaw, cellDef] of entries) {
+      const mount = mountRaw.trim();
+      if (typeof mount !== "string" || mount === "") {
+        throw new Error("otavia.yaml: cells keys (mount) must be non-empty strings");
+      }
+      if (typeof cellDef === "string") {
+        const packageName = cellDef.trim();
+        if (!packageName) {
+          throw new Error(`otavia.yaml: cells["${mount}"] must be a non-empty package name string`);
+        }
+        cellsList.push({ mount, package: packageName });
+        continue;
+      }
+      if (cellDef == null || typeof cellDef !== "object" || Array.isArray(cellDef)) {
+        throw new Error(
+          `otavia.yaml: cells["${mount}"] must be a package string or object { package, params? }`
+        );
+      }
+      const record = cellDef as Record<string, unknown>;
+      const packageName = typeof record.package === "string" ? record.package.trim() : "";
+      if (!packageName) {
+        throw new Error(`otavia.yaml: cells["${mount}"].package must be a non-empty string`);
+      }
+      const params = normalizeParams(record.params, `otavia.yaml: cells["${mount}"].params`);
+      cellsList.push({ mount, package: packageName, params });
+    }
+    const cells = Object.fromEntries(cellsList.map((c) => [c.mount, c.package]));
+    return { cells, cellsList };
+  }
+  throw new Error("otavia.yaml: cells must be an array or an object");
+}
+
+export function loadOtaviaYaml(rootDir: string): OtaviaYaml {
+  const configPath = path.resolve(rootDir, CONFIG_FILENAME);
+  if (!fs.existsSync(configPath)) {
+    throw new Error("otavia.yaml not found");
+  }
+  const raw = fs.readFileSync(configPath, "utf-8");
+  const doc = parseDocument(raw, { customTags });
+  const data = doc.toJSON() as Record<string, unknown> | null | undefined;
+  if (data == null || typeof data !== "object") {
+    throw new Error("otavia.yaml: invalid YAML or empty document");
+  }
+
+  if (data.stackName == null || data.stackName === "") {
+    throw new Error("otavia.yaml: missing stackName");
+  }
+  if (typeof data.stackName !== "string") {
+    throw new Error("otavia.yaml: stackName must be a string");
+  }
+
+  const { cells, cellsList } = parseCells(data.cells);
+  let defaultCell: string | undefined;
+  if (data.defaultCell != null) {
+    if (typeof data.defaultCell !== "string") {
+      throw new Error("otavia.yaml: defaultCell must be a string");
+    }
+    const normalized = data.defaultCell.trim();
+    if (!normalized) {
+      throw new Error("otavia.yaml: defaultCell must be a string");
+    }
+    const mountSet = new Set(cellsList.map((cell) => cell.mount));
+    if (!mountSet.has(normalized)) {
+      throw new Error(
+        `otavia.yaml: defaultCell "${normalized}" must match one of configured cell mounts`
+      );
+    }
+    defaultCell = normalized;
+  }
+
+  if (data.domain == null || typeof data.domain !== "object") {
+    throw new Error("otavia.yaml: missing domain");
+  }
+  const domain = data.domain as Record<string, unknown>;
+  if (domain.host == null || domain.host === "") {
+    throw new Error("otavia.yaml: missing domain.host");
+  }
+  if (typeof domain.host !== "string") {
+    throw new Error("otavia.yaml: domain.host must be a string");
+  }
+
+  const result: OtaviaYaml = {
+    stackName: data.stackName as string,
+    defaultCell,
+    cells,
+    cellsList,
+    domain: {
+      host: domain.host as string,
+      dns:
+        domain.dns != null && typeof domain.dns === "object"
+          ? {
+              provider:
+                (domain.dns as Record<string, unknown>).provider as
+                  | string
+                  | undefined,
+              zone: (domain.dns as Record<string, unknown>).zone as
+                | string
+                | undefined,
+              zoneId: (domain.dns as Record<string, unknown>).zoneId as
+                | string
+                | undefined,
+            }
+          : undefined,
+    },
+  };
+  if (data.params != null && typeof data.params === "object" && !Array.isArray(data.params)) {
+    result.params = data.params as Record<string, unknown>;
+    walkParamTree(result.params, "otavia.yaml: params", (v, p) => {
+      if (isParamRef(v)) {
+        throw new Error(`${p} cannot use !Param; top-level params only allow plain values, !Env, !Secret`);
+      }
+    });
+  }
+  for (const cell of result.cellsList) {
+    if (!cell.params) continue;
+    walkParamTree(cell.params, `otavia.yaml: cells["${cell.mount}"].params`, (v, p) => {
+      if (isEnvRef(v) || isSecretRef(v)) {
+        throw new Error(`${p} cannot use !Env/!Secret; use !Param to reference top-level params`);
+      }
+    });
+  }
+
+  if (data.oauth != null) {
+    if (typeof data.oauth !== "object" || Array.isArray(data.oauth)) {
+      throw new Error("otavia.yaml: oauth must be an object");
+    }
+    const oauth = data.oauth as Record<string, unknown>;
+    if (oauth.callback != null) {
+      if (typeof oauth.callback !== "object" || Array.isArray(oauth.callback)) {
+        throw new Error("otavia.yaml: oauth.callback must be an object");
+      }
+      const callback = oauth.callback as Record<string, unknown>;
+      if (typeof callback.cell !== "string" || callback.cell.trim() === "") {
+        throw new Error("otavia.yaml: oauth.callback.cell must be a non-empty string");
+      }
+      if (typeof callback.path !== "string" || callback.path.trim() === "") {
+        throw new Error("otavia.yaml: oauth.callback.path must be a non-empty string");
+      }
+      const cell = callback.cell.trim();
+      const callbackPath = callback.path.trim();
+      if (!callbackPath.startsWith("/")) {
+        throw new Error("otavia.yaml: oauth.callback.path must start with '/'");
+      }
+      const mountSet = new Set(result.cellsList.map((entry) => entry.mount));
+      if (!mountSet.has(cell)) {
+        throw new Error(
+          `otavia.yaml: oauth.callback.cell "${cell}" must match one of configured cells`
+        );
+      }
+      result.oauth = { callback: { cell, path: callbackPath } };
+    } else {
+      result.oauth = {};
+    }
+  }
+  return result;
+}