otavia 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "otavia",
+  "version": "0.1.0",
+  "description": "CLI for Otavia stack (deploy, dev, local tooling)",
+  "type": "module",
+  "exports": {
+    "./dev/main-frontend-runtime/main-entry": "./src/commands/dev/main-frontend-runtime/main-entry.ts",
+    "./dev/main-frontend-runtime/vite-config": "./src/commands/dev/main-frontend-runtime/vite-config.ts"
+  },
+  "bin": {
+    "otavia": "src/cli.ts"
+  },
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.x",
+    "@aws-sdk/client-s3": "^3.x",
+    "commander": "^12.1.0",
+    "concurrently": "^9.2.1",
+    "esbuild": "^0.24.0",
+    "hono": "^4.6.0",
+    "yaml": "^2.5.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "@types/node": "^25.5.0",
+    "@vitejs/plugin-react": "^4.x",
+    "typescript": "^5.8.3",
+    "vite": "^7.x"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { loadOtaviaYaml } from "./config/load-otavia-yaml.js";
+import { setupCommand } from "./commands/setup.js";
+import { cleanCommand } from "./commands/clean.js";
+import { awsLoginCommand, awsLogoutCommand } from "./commands/aws.js";
+import { devCommand } from "./commands/dev.js";
+import { testUnitCommand, testE2eCommand } from "./commands/test.js";
+import { typecheckCommand } from "./commands/typecheck.js";
+import { lintCommand } from "./commands/lint.js";
+import { deployCommand } from "./commands/deploy.js";
+import { listCellsCommand } from "./commands/cell.js";
+import { initCommand } from "./commands/init.js";
+
+const program = new Command();
+
+program
+  .name("otavia")
+  .description("CLI for Otavia stack")
+  .version("0.1.0");
+
+const placeholderAction = async () => {
+  console.log("Not implemented");
+};
+
+program.hook("preAction", (_thisCommand, actionCommand) => {
+  if (actionCommand.name() === "init") return;
+  try {
+    loadOtaviaYaml(process.cwd());
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+});
+
+program
+  .command("init")
+  .description("Create otavia.yaml and a starter cell under cells/app")
+  .option("--force", "Overwrite existing otavia.yaml and cells/app/cell.yaml")
+  .option("--stack-name <name>", "CloudFormation stack name (default: current directory name)")
+  .option("--domain <host>", "Primary domain host (default: example.com)")
+  .action(
+    (_args: unknown, cmd: { opts: () => { force?: boolean; stackName?: string; domain?: string } }) => {
+      const opts = cmd.opts();
+      initCommand(process.cwd(), {
+        force: opts.force,
+        stackName: opts.stackName,
+        domain: opts.domain,
+      });
+    }
+  );
+
+program.command("setup")
+  .description("Setup Otavia stack")
+  .option("--tunnel", "Setup tunnel for remote dev")
+  .action(
+    async (
+      _args: unknown,
+      cmd: {
+        opts: () => { tunnel?: boolean };
+        getOptionValueSource: (name: string) => string | undefined;
+      }
+    ) => {
+      const opts = cmd.opts();
+      const source = cmd.getOptionValueSource("tunnel");
+      await setupCommand(process.cwd(), { tunnel: opts.tunnel, tunnelSpecified: source === "cli" });
+    }
+  );
+program.command("dev")
+  .description("Start development")
+  .option("--tunnel", "Enable cloudflared tunnel and use tunnel host URLs")
+  .option("--tunnel-host <host>", "Tunnel hostname or full URL used as public base URL")
+  .option("--tunnel-config <path>", "Path to cloudflared config.yml")
+  .option("--tunnel-protocol <protocol>", "Tunnel transport protocol: quic, http2, or auto")
+  .action(
+    async (
+      _args: unknown,
+      cmd: {
+        opts: () => {
+          tunnel?: boolean;
+          tunnelHost?: string;
+          tunnelConfig?: string;
+          tunnelProtocol?: string;
+        };
+      }
+    ) => {
+      const opts = cmd.opts();
+      await devCommand(process.cwd(), {
+        tunnel: opts.tunnel,
+        tunnelHost: opts.tunnelHost,
+        tunnelConfig: opts.tunnelConfig,
+        tunnelProtocol: opts.tunnelProtocol,
+      });
+    }
+  );
+program.command("test")
+  .description("Run tests (unit then e2e)")
+  .action(async () => {
+    const rootDir = process.cwd();
+    await testUnitCommand(rootDir);
+    await testE2eCommand(rootDir);
+  });
+program.command("test:unit")
+  .description("Run unit tests")
+  .action(async () => {
+    await testUnitCommand(process.cwd());
+  });
+program.command("test:e2e")
+  .description("Run e2e tests")
+  .action(async () => {
+    await testE2eCommand(process.cwd());
+  });
+program.command("deploy")
+  .description("Deploy stack (build, upload, CloudFormation)")
+  .option("--yes", "Skip confirmation")
+  .action(async (_args: unknown, cmd: { opts: () => { yes?: boolean } }) => {
+    await deployCommand(process.cwd(), { yes: cmd.opts().yes });
+  });
+program
+  .command("typecheck")
+  .description("Type check all cells")
+  .action(async () => {
+    await typecheckCommand(process.cwd());
+  });
+program
+  .command("lint")
+  .description("Lint all cells")
+  .option("--fix", "Apply safe fixes")
+  .option("--unsafe", "Apply unsafe fixes")
+  .action(async (_args: unknown, cmd: { opts: () => { fix?: boolean; unsafe?: boolean } }) => {
+    const opts = cmd.opts();
+    await lintCommand(process.cwd(), { fix: opts.fix, unsafe: opts.unsafe });
+  });
+program.command("clean").description("Clean artifacts").action(() => {
+  cleanCommand(process.cwd());
+});
+
+const aws = program.command("aws").description("AWS-related commands");
+aws.command("login").description("AWS login").action(async () => { await awsLoginCommand(process.cwd()); });
+aws.command("logout").description("AWS logout").action(async () => { await awsLogoutCommand(process.cwd()); });
+
+const cell = program.command("cell").description("List and manage cells");
+cell
+  .command("list")
+  .description("List cells from otavia.yaml and their resolved directories")
+  .action(() => {
+    listCellsCommand(process.cwd());
+  });
+
+program.parseAsync(process.argv).catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/commands/__tests__/aws-auth.test.ts

@@ -0,0 +1,32 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+import { checkAwsCredentials } from "../aws-auth.js";
+
+describe("checkAwsCredentials", () => {
+  test("uses AWS_PROFILE from root .env when process env missing", async () => {
+    const rootDir = mkdtempSync(join(tmpdir(), "otavia-aws-auth-"));
+    writeFileSync(join(rootDir, ".env"), "AWS_PROFILE=my-sso-profile\n");
+
+    const calls: Array<{ args: string[]; env: Record<string, string | undefined> }> = [];
+    const result = await checkAwsCredentials(rootDir, async (args, env) => {
+      calls.push({ args, env });
+      return 0;
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.profile).toBe("my-sso-profile");
+    expect(calls[0]?.args).toEqual(["sts", "get-caller-identity", "--output", "json"]);
+    expect(calls[0]?.env.AWS_PROFILE).toBe("my-sso-profile");
+  });
+
+  test("reports invalid credentials when sts check fails", async () => {
+    const rootDir = mkdtempSync(join(tmpdir(), "otavia-aws-auth-"));
+    writeFileSync(join(rootDir, ".env"), "AWS_PROFILE=expired-profile\n");
+
+    const result = await checkAwsCredentials(rootDir, async () => 255);
+    expect(result.ok).toBe(false);
+    expect(result.profile).toBe("expired-profile");
+  });
+});

package/src/commands/__tests__/cell.test.ts

@@ -0,0 +1,44 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, expect, test } from "bun:test";
+import { listCellsCommand } from "../cell.js";
+
+describe("listCellsCommand", () => {
+  test("prints mounts and paths for cells in otavia.yaml", () => {
+    const root = mkdtempSync(join(tmpdir(), "otavia-cell-list-"));
+    try {
+      writeFileSync(
+        join(root, "otavia.yaml"),
+        `
+stackName: test-stack
+domain:
+  host: example.com
+cells:
+  sso: "@otavia/sso"
+  drive: "@otavia/drive"
+`,
+        "utf-8"
+      );
+      const ssoDir = join(root, "cells", "sso");
+      mkdirSync(ssoDir, { recursive: true });
+      writeFileSync(join(ssoDir, "cell.yaml"), "name: sso\n", "utf-8");
+
+      const lines: string[] = [];
+      const origLog = console.log;
+      console.log = (...args: unknown[]) => {
+        lines.push(args.map(String).join(" "));
+      };
+      try {
+        listCellsCommand(root);
+      } finally {
+        console.log = origLog;
+      }
+
+      expect(lines.some((l) => l.includes("sso") && l.includes("@otavia/sso"))).toBe(true);
+      expect(lines.some((l) => l.includes("drive") && l.includes("(no cell.yaml)"))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/commands/__tests__/dev.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { resolveDevPublicBaseUrl, resolveDevTunnelEnabled } from "../dev";
+
+describe("resolveDevPublicBaseUrl", () => {
+  test("uses tunnel public base URL when tunnel is enabled", () => {
+    expect(
+      resolveDevPublicBaseUrl({
+        tunnelEnabled: true,
+        tunnelPublicBaseUrl: "https://mybox.dev.example.com",
+        gatewayOnly: false,
+        vitePort: 7100,
+      })
+    ).toBe("https://mybox.dev.example.com");
+  });
+
+  test("uses localhost vite base URL in normal local dev", () => {
+    expect(
+      resolveDevPublicBaseUrl({
+        tunnelEnabled: false,
+        gatewayOnly: false,
+        vitePort: 7100,
+      })
+    ).toBe("http://localhost:7100");
+  });
+
+  test("returns undefined in gateway-only mode", () => {
+    expect(
+      resolveDevPublicBaseUrl({
+        tunnelEnabled: false,
+        gatewayOnly: true,
+        vitePort: 7100,
+      })
+    ).toBeUndefined();
+  });
+});
+
+describe("resolveDevTunnelEnabled", () => {
+  test("defaults to false when option is missing", () => {
+    expect(resolveDevTunnelEnabled()).toBe(false);
+  });
+
+  test("uses explicit tunnel=true", () => {
+    expect(resolveDevTunnelEnabled({ tunnel: true })).toBe(true);
+  });
+
+  test("uses explicit tunnel=false", () => {
+    expect(resolveDevTunnelEnabled({ tunnel: false })).toBe(false);
+  });
+});

package/src/commands/__tests__/init.test.ts

@@ -0,0 +1,47 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, expect, test } from "bun:test";
+import { loadOtaviaYaml } from "../../config/load-otavia-yaml.js";
+import { initCommand } from "../init.js";
+
+describe("initCommand", () => {
+  test("creates otavia.yaml, cells/app/cell.yaml, and valid config", () => {
+    const root = mkdtempSync(join(tmpdir(), "otavia-init-"));
+    try {
+      initCommand(root, { stackName: "demo-stack", domain: "app.example.dev" });
+      expect(existsSync(join(root, "otavia.yaml"))).toBe(true);
+      expect(existsSync(join(root, "cells", "app", "cell.yaml"))).toBe(true);
+      const otavia = loadOtaviaYaml(root);
+      expect(otavia.stackName).toBe("demo-stack");
+      expect(otavia.domain.host).toBe("app.example.dev");
+      expect(otavia.cells.app).toBe("@otavia/app");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("refuses to overwrite without --force", () => {
+    const root = mkdtempSync(join(tmpdir(), "otavia-init-"));
+    try {
+      writeFileSync(join(root, "otavia.yaml"), "stackName: x\ndomain:\n  host: h\ncells:\n  a: '@otavia/a'\n", "utf-8");
+      expect(() => initCommand(root, {})).toThrow(/already exists/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("appends common entries to existing .gitignore", () => {
+    const root = mkdtempSync(join(tmpdir(), "otavia-init-"));
+    try {
+      writeFileSync(join(root, ".gitignore"), "custom\n", "utf-8");
+      initCommand(root, { stackName: "s", domain: "d.example.com" });
+      const gi = readFileSync(join(root, ".gitignore"), "utf-8");
+      expect(gi).toContain("custom");
+      expect(gi).toContain("node_modules/");
+      expect(gi).toContain(".otavia/");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/commands/__tests__/setup.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildCognitoUserPoolClientUpdateArgs,
+  buildOAuthCallbackUrl,
+  buildTunnelConfigYaml,
+  bootstrapNamedTunnel,
+  ensureCloudflaredInstalled,
+  ensureCloudflaredLogin,
+  fetchCloudflareZonesWithToken,
+  isAwsSsoExpiredError,
+  resolveTunnelSetupEnabled,
+  type CommandRunner,
+} from "../setup";
+
+describe("resolveTunnelSetupEnabled", () => {
+  test("uses explicit --tunnel=true without prompting", async () => {
+    const enabled = await resolveTunnelSetupEnabled(
+      { tunnel: true, tunnelSpecified: true },
+      {
+        isTTY: true,
+        ask: async () => {
+          throw new Error("should not ask");
+        },
+      }
+    );
+    expect(enabled).toBe(true);
+  });
+
+  test("uses explicit --tunnel=false without prompting", async () => {
+    const enabled = await resolveTunnelSetupEnabled(
+      { tunnel: false, tunnelSpecified: true },
+      {
+        isTTY: true,
+        ask: async () => {
+          throw new Error("should not ask");
+        },
+      }
+    );
+    expect(enabled).toBe(false);
+  });
+
+  test("defaults to false when non-interactive and option unspecified", async () => {
+    const enabled = await resolveTunnelSetupEnabled(
+      { tunnelSpecified: false },
+      {
+        isTTY: false,
+      }
+    );
+    expect(enabled).toBe(false);
+  });
+
+  test("prompts user when interactive and option unspecified", async () => {
+    const enabled = await resolveTunnelSetupEnabled(
+      { tunnelSpecified: false },
+      {
+        isTTY: true,
+        ask: async () => "y",
+      }
+    );
+    expect(enabled).toBe(true);
+  });
+});
+
+function makeRunner(sequence: Array<{ cmd: string; exitCode: number }>): CommandRunner {
+  let idx = 0;
+  return async (args) => {
+    const step = sequence[idx];
+    if (!step) {
+      throw new Error(`unexpected command: ${args.join(" ")}`);
+    }
+    expect(args.join(" ")).toBe(step.cmd);
+    idx += 1;
+    return { exitCode: step.exitCode, stdout: "", stderr: "" };
+  };
+}
+
+describe("ensureCloudflaredInstalled", () => {
+  test("installs with brew on macOS when cloudflared is missing", async () => {
+    const run = makeRunner([
+      { cmd: "cloudflared --version", exitCode: 1 },
+      { cmd: "brew --version", exitCode: 0 },
+      { cmd: "brew install cloudflared", exitCode: 0 },
+      { cmd: "cloudflared --version", exitCode: 0 },
+    ]);
+    await ensureCloudflaredInstalled({ run, platform: "darwin" });
+  });
+});
+
+describe("ensureCloudflaredLogin", () => {
+  test("runs cloudflared tunnel login when not logged in", async () => {
+    const run = makeRunner([
+      { cmd: "cloudflared tunnel list", exitCode: 1 },
+      { cmd: "cloudflared tunnel login", exitCode: 0 },
+      { cmd: "cloudflared tunnel list", exitCode: 0 },
+    ]);
+    await ensureCloudflaredLogin({ run, hasExistingCert: false });
+  });
+
+  test("does not force login when cert exists; retries list", async () => {
+    const run = makeRunner([
+      { cmd: "cloudflared tunnel list", exitCode: 1 },
+      { cmd: "cloudflared tunnel list", exitCode: 0 },
+    ]);
+    await ensureCloudflaredLogin({ run, hasExistingCert: true });
+  });
+});
+
+describe("bootstrapNamedTunnel", () => {
+  test("creates tunnel and routes DNS", async () => {
+    const run = makeRunner([
+      {
+        cmd: "cloudflared tunnel create --credentials-file /tmp/otavia/credentials.json otavia-dev-mybox",
+        exitCode: 0,
+      },
+      {
+        cmd: "cloudflared tunnel route dns --overwrite-dns otavia-dev-mybox mybox.dev.example.com",
+        exitCode: 0,
+      },
+    ]);
+    const result = await bootstrapNamedTunnel({
+      configDir: "/tmp/otavia",
+      devRoot: "dev.example.com",
+      machineName: "mybox",
+      run,
+    });
+    expect(result.tunnelName).toBe("otavia-dev-mybox");
+    expect(result.hostname).toBe("mybox.dev.example.com");
+    expect(result.credentialsPath).toBe("/tmp/otavia/credentials.json");
+  });
+});
+
+describe("buildTunnelConfigYaml", () => {
+  test("renders config for fixed host", () => {
+    const yaml = buildTunnelConfigYaml({
+      tunnelName: "otavia-dev-mybox",
+      credentialsPath: "/tmp/otavia/credentials.json",
+      hostname: "mybox.dev.example.com",
+      localPort: 7100,
+    });
+    expect(yaml).toContain("tunnel: otavia-dev-mybox");
+    expect(yaml).toContain('hostname: "mybox.dev.example.com"');
+    expect(yaml).toContain("service: http://127.0.0.1:7100");
+  });
+});
+
+describe("buildOAuthCallbackUrl", () => {
+  test("builds callback URL from host + cell + path", () => {
+    expect(buildOAuthCallbackUrl("mybox.dev.example.com", "sso", "/oauth/callback")).toBe(
+      "https://mybox.dev.example.com/sso/oauth/callback"
+    );
+  });
+});
+
+describe("fetchCloudflareZonesWithToken", () => {
+  test("returns zones on successful API response", async () => {
+    const zones = await fetchCloudflareZonesWithToken("token", async () => {
+      return new Response(
+        JSON.stringify({
+          success: true,
+          result: [
+            { id: "z1", name: "example.com" },
+            { id: "z2", name: "dev.example.com" },
+          ],
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      );
+    });
+    expect(zones).toEqual([
+      { id: "z1", name: "example.com" },
+      { id: "z2", name: "dev.example.com" },
+    ]);
+  });
+
+  test("returns empty list on API failure", async () => {
+    const zones = await fetchCloudflareZonesWithToken("token", async () => {
+      return new Response("denied", { status: 403 });
+    });
+    expect(zones).toEqual([]);
+  });
+});
+
+describe("isAwsSsoExpiredError", () => {
+  test("detects common AWS SSO expiration errors", () => {
+    expect(isAwsSsoExpiredError("Error when retrieving token from sso: Token has expired and refresh failed")).toBe(true);
+    expect(isAwsSsoExpiredError("ExpiredToken: The security token included in the request is expired")).toBe(true);
+  });
+
+  test("does not match unrelated errors", () => {
+    expect(isAwsSsoExpiredError("AccessDeniedException: User is not authorized")).toBe(false);
+  });
+});
+
+describe("buildCognitoUserPoolClientUpdateArgs", () => {
+  test("keeps existing OAuth config when present", () => {
+    const args = buildCognitoUserPoolClientUpdateArgs(
+      {
+        AllowedOAuthFlows: ["code"],
+        AllowedOAuthScopes: ["openid", "email", "profile"],
+        SupportedIdentityProviders: ["COGNITO"],
+      },
+      ["https://mymbp.shazhou.work/sso/oauth/callback"],
+      ["https://mymbp.shazhou.work"]
+    );
+    expect(args).toContain("--allowed-o-auth-flows-user-pool-client");
+    expect(args).toEqual(
+      expect.arrayContaining([
+        "--allowed-o-auth-flows",
+        "code",
+        "--allowed-o-auth-scopes",
+        "openid",
+        "email",
+        "profile",
+        "--supported-identity-providers",
+        "COGNITO",
+      ])
+    );
+  });
+
+  test("falls back to safe OAuth defaults when describe has empty lists", () => {
+    const args = buildCognitoUserPoolClientUpdateArgs(
+      {
+        AllowedOAuthFlows: [],
+        AllowedOAuthScopes: [],
+        SupportedIdentityProviders: [],
+      },
+      ["https://mymbp.shazhou.work/sso/oauth/callback"],
+      ["https://mymbp.shazhou.work"]
+    );
+    expect(args).toEqual(
+      expect.arrayContaining([
+        "--allowed-o-auth-flows",
+        "code",
+        "--allowed-o-auth-scopes",
+        "openid",
+        "email",
+        "profile",
+        "--supported-identity-providers",
+        "COGNITO",
+      ])
+    );
+  });
+
+  test("uses merged identity providers when explicitly provided", () => {
+    const args = buildCognitoUserPoolClientUpdateArgs(
+      {
+        AllowedOAuthFlows: ["code"],
+        AllowedOAuthScopes: ["openid", "email", "profile"],
+        SupportedIdentityProviders: ["COGNITO"],
+      },
+      ["https://mymbp.shazhou.work/sso/oauth/callback"],
+      ["https://mymbp.shazhou.work"],
+      ["COGNITO", "Google", "Microsoft"]
+    );
+    expect(args).toEqual(
+      expect.arrayContaining([
+        "--supported-identity-providers",
+        "COGNITO",
+        "Google",
+        "Microsoft",
+      ])
+    );
+  });
+});

package/src/commands/aws-auth.ts

@@ -0,0 +1,32 @@
+import { getAwsProfile } from "./aws.js";
+
+export type AwsCliRunner = (
+  args: string[],
+  env: Record<string, string | undefined>
+) => Promise<number>;
+
+const defaultAwsCliRunner: AwsCliRunner = async (args, env) => {
+  const proc = Bun.spawn(["aws", ...args], {
+    cwd: process.cwd(),
+    env: { ...process.env, ...env },
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  return await proc.exited;
+};
+
+export async function checkAwsCredentials(
+  rootDir: string,
+  runAwsCli: AwsCliRunner = defaultAwsCliRunner
+): Promise<{ ok: boolean; profile: string }> {
+  const profile = getAwsProfile(rootDir);
+  const env: Record<string, string | undefined> = {
+    AWS_PROFILE: process.env.AWS_PROFILE ?? profile,
+    AWS_REGION: process.env.AWS_REGION,
+  };
+  const exitCode = await runAwsCli(
+    ["sts", "get-caller-identity", "--output", "json"],
+    env
+  );
+  return { ok: exitCode === 0, profile };
+}