@arcote.tech/arc-cli 0.7.3 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcote.tech/arc-cli",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "CLI tool for Arc framework",
   "module": "index.ts",
   "main": "dist/index.js",
@@ -12,12 +12,13 @@
     "build": "bun build --target=bun ./src/index.ts --outdir=dist --external @arcote.tech/arc --external @arcote.tech/arc-ds --external @arcote.tech/arc-react --external @arcote.tech/platform && chmod +x dist/index.js"
   },
   "dependencies": {
-    "@arcote.tech/arc": "^0.7.3",
-    "@arcote.tech/arc-ds": "^0.7.3",
-    "@arcote.tech/arc-react": "^0.7.3",
-    "@arcote.tech/arc-host": "^0.7.3",
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.3",
-    "@arcote.tech/platform": "^0.7.3",
+    "@arcote.tech/arc": "^0.7.5",
+    "@arcote.tech/arc-ds": "^0.7.5",
+    "@arcote.tech/arc-react": "^0.7.5",
+    "@arcote.tech/arc-host": "^0.7.5",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.5",
+    "@arcote.tech/arc-adapter-db-postgres": "^0.7.5",
+    "@arcote.tech/platform": "^0.7.5",
     "@clack/prompts": "^0.9.0",
     "commander": "^11.1.0",
     "chokidar": "^3.5.3",

package/src/builder/build-cache.ts

@@ -1,11 +1,30 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { join } from "path";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
 
-// v2: switched from `modules-bundle` (one unit) to `modules-chunk:<name>`
-// (one unit per chunk group). Old v1 entries are irrelevant.
-const CACHE_VERSION = 2;
+// Schema version — bump if cache entry shape changes.
+const CACHE_SCHEMA_VERSION = 3;
 const CACHE_FILE = ".build-cache.json";
 
+/**
+ * Combined cache fingerprint: schema version + CLI version. Lets a newer CLI
+ * automatically invalidate dist/ produced by an older CLI even when source
+ * hashes match. Without this, a build-logic change in the CLI (e.g.
+ * externalization rules in buildContextClient) silently kept stale dist/
+ * around — see the v0.7.3 "creatorWorkspaces not found in context" incident.
+ */
+function readCliVersion(): string {
+  try {
+    // Bundled CLI lives at `<pkg>/dist/index.js`; package.json is one level up.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8"));
+    return typeof pkg.version === "string" ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+const CACHE_FINGERPRINT = `${CACHE_SCHEMA_VERSION}:${readCliVersion()}`;
+
 export interface CacheEntry {
   inputHash: string;
   outputHash?: string;
@@ -13,22 +32,22 @@ export interface CacheEntry {
 }
 
 export interface BuildCache {
-  version: typeof CACHE_VERSION;
+  version: string;
   units: Record<string, CacheEntry>;
 }
 
 function emptyCache(): BuildCache {
-  return { version: CACHE_VERSION, units: {} };
+  return { version: CACHE_FINGERPRINT, units: {} };
 }
 
 /** Loads cache from .arc/platform/.build-cache.json. Returns empty cache on
- *  missing file, parse error, or version mismatch. */
+ *  missing file, parse error, or fingerprint mismatch (schema OR CLI version). */
 export function loadBuildCache(arcDir: string): BuildCache {
   const path = join(arcDir, CACHE_FILE);
   if (!existsSync(path)) return emptyCache();
   try {
     const raw = JSON.parse(readFileSync(path, "utf-8"));
-    if (raw?.version !== CACHE_VERSION || typeof raw.units !== "object") {
+    if (raw?.version !== CACHE_FINGERPRINT || typeof raw.units !== "object") {
       return emptyCache();
     }
     return raw as BuildCache;

package/src/commands/platform-deploy.ts

@@ -2,12 +2,14 @@ import { existsSync, readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { bootstrap } from "../deploy/bootstrap";
+import { postgresEnvs } from "../deploy/compose";
 import {
   deployConfigExists,
   loadDeployConfig,
   saveDeployConfig,
 } from "../deploy/config";
 import { updateEnvDeployment } from "../deploy/deploy-env";
+import { ensurePersistedSecret } from "../deploy/env-file";
 import { buildImage, sanitizeImageName } from "../deploy/image";
 import { detectRemoteState } from "../deploy/remote-state";
 import { dockerLogin, dockerPush } from "../deploy/registry";
@@ -74,6 +76,17 @@ export async function platformDeploy(
   }
   cfg = loadDeployConfig(ws.rootDir);
 
+  // For every env opted into postgres, make sure the sidecar password is
+  // materialised in `deploy.arc.<env>.env` (gitignored) and in process.env.
+  // Compose generation interpolates `${ARC_PG_PASSWORD_<UPPER>}` later; this
+  // step has to happen before bootstrap renders + uploads compose.yml.
+  const pgEnvs = postgresEnvs(cfg);
+  for (const pg of pgEnvs) {
+    ensurePersistedSecret(ws.rootDir, pg.name, pg.passwordKey, () =>
+      crypto.randomUUID().replace(/-/g, ""),
+    );
+  }
+
   // Filter envs if an arg was provided
   const targetEnvs = envArg
     ? envArg in cfg.envs

package/src/deploy/bootstrap.ts

@@ -160,6 +160,31 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
  * Used by bootstrap to detect legacy v0.5 stacks that have no registry
  * container and need a fresh stack write + restart.
  */
+/**
+ * Atomically set `KEY=value` in a remote `.env`-style file. Replaces an
+ * existing line with the same key or appends one. Same awk pattern used by
+ * deploy-env.ts to update ARC_IMAGE_<ENV>; values are shell-escaped so
+ * passwords containing `$`, `"`, etc. survive intact.
+ */
+async function writeEnvLine(
+  target: DeployTarget,
+  envPath: string,
+  key: string,
+  value: string,
+): Promise<void> {
+  const escapedValue = value.replace(/"/g, '\\"').replace(/\$/g, "\\$");
+  const script = [
+    `touch ${envPath} && `,
+    `awk -v line="${key}=${escapedValue}" -v key="${key}=" '`,
+    `  BEGIN { replaced=0 } `,
+    `  $0 ~ "^"key { print line; replaced=1; next } `,
+    `  { print } `,
+    `  END { if (!replaced) print line } `,
+    `' ${envPath} > ${envPath}.tmp && mv ${envPath}.tmp ${envPath}`,
+  ].join("");
+  await assertExec(target, script);
+}
+
 async function isRegistryRunning(cfg: DeployConfig): Promise<boolean> {
   const res = await sshExec(
     cfg.target,
@@ -239,6 +264,23 @@ async function upStack(inputs: BootstrapInputs): Promise<void> {
     `touch ${cfg.target.remoteDir}/.env`,
   );
 
+  // Propagate postgres sidecar passwords to /opt/arc/.env so compose can
+  // interpolate `${ARC_PG_PASSWORD_<UPPER>}` for both the pg container and
+  // arc-<env>'s DATABASE_URL. Local source is `deploy.arc.<env>.env` /
+  // process.env (populated by `ensurePersistedSecret` in platform-deploy).
+  // Idempotent: re-runs with the same value are no-ops.
+  for (const [name, env] of Object.entries(cfg.envs)) {
+    if (env.db?.type !== "postgres") continue;
+    const key = `ARC_PG_PASSWORD_${name.toUpperCase().replace(/-/g, "_")}`;
+    const value = process.env[key];
+    if (!value) {
+      throw new Error(
+        `bootstrap: ${key} not set — postgres env "${name}" requires a password`,
+      );
+    }
+    await writeEnvLine(cfg.target, `${cfg.target.remoteDir}/.env`, key, value);
+  }
+
   // Pre-register the deploy user with the private registry so containers can
   // pull. We do this AFTER `docker compose up -d caddy registry` runs (below)
   // — the registry needs to be reachable for `docker login` to succeed.

package/src/deploy/compose.ts

@@ -3,13 +3,18 @@ import type { DeployConfig } from "./config";
 // ---------------------------------------------------------------------------
 // docker-compose.yml generator
 //
-// Services:
-//   - caddy (public 80/443, loopback 127.0.0.1:2019 for deploy tunnel)
-//   - arc-<env> per entry in deploy.arc.json envs (bind-mounts project dir)
+// Services emitted, in order:
+//   - caddy      (public 80/443, loopback 127.0.0.1:2019 for deploy tunnel)
+//   - registry   (private image store on arc-net, fronted by Caddy auth)
+//   - arc-<env>  (one per entry in deploy.arc.json envs)
+//   - arc-db-<env> (one per env that opts into `db: { type: "postgres" }`)
 //
-// No custom images: vanilla `caddy:2-alpine` and `oven/bun:1-alpine` from
-// Docker Hub. The Arc CLI and user's built artifacts come via the volume
-// mount at /opt/arc/<env>/ — rsynced by the deploy command.
+// SQLite envs persist `/app/.arc/data` in a named volume per env. Postgres
+// envs run a `postgres:16-alpine` sidecar on the docker network — the arc
+// container connects via `DATABASE_URL`, no port is exposed to the host.
+//
+// No custom images: vanilla `caddy:2-alpine`, `registry:2`, `postgres:*`,
+// and `oven/bun:1-alpine` from Docker Hub.
 // ---------------------------------------------------------------------------
 
 export interface ComposeOptions {
@@ -48,8 +53,6 @@ export function generateCompose({ cfg }: ComposeOptions): string {
   lines.push("      REGISTRY_AUTH: htpasswd");
   lines.push('      REGISTRY_AUTH_HTPASSWD_REALM: "Arc Registry"');
   lines.push("      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd");
-  // Large image layers (framework peers + arc-cli bundle + chunks) need a
-  // generous upload limit. Default 100MB triggers 413 on real apps.
   lines.push('      REGISTRY_HTTP_HOST: "https://' + cfg.registry.domain + '"');
   lines.push("    networks:");
   lines.push("      - arc-net");
@@ -58,7 +61,8 @@ export function generateCompose({ cfg }: ComposeOptions): string {
   lines.push("");
 
   for (const [name, env] of Object.entries(cfg.envs)) {
-    const upperName = name.toUpperCase().replace(/-/g, "_");
+    const upperName = upperEnvName(name);
+    const usePostgres = env.db?.type === "postgres";
     lines.push(`  arc-${name}:`);
     // Image ref comes from /opt/arc/.env, written per-deploy with the content
     // hash of the latest build. Default to a placeholder so `docker compose
@@ -69,18 +73,34 @@ export function generateCompose({ cfg }: ComposeOptions): string {
     );
     lines.push(`    container_name: arc-${name}`);
     lines.push("    restart: unless-stopped");
-    lines.push("    volumes:");
-    // Only the data volume — user code lives entirely inside the image.
-    // SQLite + uploads persist across redeploys.
-    lines.push(`      - arc-data-${name}:/app/.arc/data`);
+    if (usePostgres) {
+      lines.push("    depends_on:");
+      lines.push(`      arc-db-${name}:`);
+      lines.push("        condition: service_healthy");
+    }
+    // SQLite envs need a writable volume for `/app/.arc/data`. Postgres
+    // envs keep their state in the sidecar volume; no host-side bind needed.
+    if (!usePostgres) {
+      lines.push("    volumes:");
+      lines.push(`      - arc-data-${name}:/app/.arc/data`);
+    }
     lines.push("    environment:");
     lines.push("      PORT: 5005");
     const userEnv = env.envVars ?? {};
     if (!("NODE_ENV" in userEnv)) {
       lines.push("      NODE_ENV: production");
     }
-    // PORT is reserved — user envVars can't override.
-    const reserved = new Set(["PORT"]);
+    if (usePostgres) {
+      // Connection string follows the docker-internal DNS name + the
+      // password sourced from `deploy.arc.<env>.env`. `arc platform deploy`
+      // ensures `ARC_PG_PASSWORD_<UPPER>` exists in that file before
+      // assembling compose, so the `${VAR:?}` interpolation never fails.
+      lines.push(
+        `      DATABASE_URL: "postgresql://arc:\${ARC_PG_PASSWORD_${upperName}:?missing ARC_PG_PASSWORD_${upperName}}@arc-db-${name}:5432/arc"`,
+      );
+    }
+    // PORT + DATABASE_URL are reserved — user envVars can't override them.
+    const reserved = new Set(["PORT", "DATABASE_URL"]);
     for (const [k, v] of Object.entries(userEnv)) {
       if (reserved.has(k)) continue;
       lines.push(`      ${k}: ${JSON.stringify(v)}`);
@@ -93,6 +113,36 @@ export function generateCompose({ cfg }: ComposeOptions): string {
     lines.push("");
   }
 
+  // Postgres sidecars (after the arc services so the YAML reads top-down:
+  // app -> its database). One service per opted-in env.
+  for (const [name, env] of Object.entries(cfg.envs)) {
+    if (env.db?.type !== "postgres") continue;
+    const upperName = upperEnvName(name);
+    const image = env.db.image ?? "postgres:16-alpine";
+    lines.push(`  arc-db-${name}:`);
+    lines.push(`    image: ${image}`);
+    lines.push(`    container_name: arc-db-${name}`);
+    lines.push("    restart: unless-stopped");
+    lines.push("    environment:");
+    lines.push("      POSTGRES_USER: arc");
+    lines.push("      POSTGRES_DB: arc");
+    lines.push(
+      `      POSTGRES_PASSWORD: \${ARC_PG_PASSWORD_${upperName}:?missing ARC_PG_PASSWORD_${upperName}}`,
+    );
+    lines.push("    volumes:");
+    lines.push(`      - arc-pgdata-${name}:/var/lib/postgresql/data`);
+    lines.push("    healthcheck:");
+    lines.push('      test: ["CMD-SHELL", "pg_isready -U arc -d arc"]');
+    lines.push("      interval: 5s");
+    lines.push("      timeout: 3s");
+    lines.push("      retries: 20");
+    lines.push("    networks:");
+    lines.push("      - arc-net");
+    // No `ports:` — the database is only reachable from other containers
+    // on `arc-net`. Exposing 5432 to the host would defeat the isolation.
+    lines.push("");
+  }
+
   lines.push("networks:");
   lines.push("  arc-net:");
   lines.push("");
@@ -100,9 +150,29 @@ export function generateCompose({ cfg }: ComposeOptions): string {
   lines.push("  caddy_data:");
   lines.push("  caddy_config:");
   lines.push("  registry_data:");
-  for (const [name] of Object.entries(cfg.envs)) {
-    lines.push(`  arc-data-${name}:`);
+  for (const [name, env] of Object.entries(cfg.envs)) {
+    if (env.db?.type === "postgres") {
+      lines.push(`  arc-pgdata-${name}:`);
+    } else {
+      lines.push(`  arc-data-${name}:`);
+    }
   }
 
   return lines.join("\n") + "\n";
 }
+
+function upperEnvName(name: string): string {
+  return name.toUpperCase().replace(/-/g, "_");
+}
+
+/** Env names whose `deploy.arc.<env>.env` file must contain a generated
+ *  `ARC_PG_PASSWORD_<UPPER>` before compose can be rendered. */
+export function postgresEnvs(cfg: DeployConfig): { name: string; passwordKey: string }[] {
+  const out: { name: string; passwordKey: string }[] = [];
+  for (const [name, env] of Object.entries(cfg.envs)) {
+    if (env.db?.type !== "postgres") continue;
+    out.push({ name, passwordKey: `ARC_PG_PASSWORD_${upperEnvName(name)}` });
+  }
+  return out;
+}
+

package/src/deploy/config.ts

@@ -22,11 +22,24 @@ export interface DeployTarget {
   sshKey?: string;
 }
 
+/**
+ * Database choice per environment. Omit to keep the historical default
+ * (SQLite in a named volume at `/app/.arc/data`). Selecting `postgres`
+ * makes `arc platform deploy` provision a `postgres:16-alpine` sidecar
+ * service on the docker network, persist its data in
+ * `arc-pgdata-<envName>`, and inject `DATABASE_URL` into the arc container.
+ */
+export type DeployEnvDb =
+  | { type: "sqlite" }
+  | { type: "postgres"; image?: string };
+
 export interface DeployEnv {
   /** Subdomain or full domain routed by Caddy. */
   domain: string;
   /** Extra env vars passed to the arc container. */
   envVars?: Record<string, string>;
+  /** Optional storage backend selector. Default = sqlite. */
+  db?: DeployEnvDb;
 }
 
 export interface DeployCaddy {
@@ -247,7 +260,25 @@ export function validateDeployConfig(input: unknown): DeployConfig {
         envVars[k] = v;
       }
     }
-    validated.envs[name] = { domain, envVars };
+    const dbRaw = (env as Record<string, unknown>).db;
+    let db: DeployEnvDb | undefined;
+    if (dbRaw !== undefined) {
+      if (!isObject(dbRaw)) throw cfgErr(`envs.${name}.db`, "object");
+      const dbType = requireString(dbRaw, `envs.${name}.db.type`);
+      if (dbType === "sqlite") {
+        db = { type: "sqlite" };
+      } else if (dbType === "postgres") {
+        db = {
+          type: "postgres",
+          image: optionalString(dbRaw, `envs.${name}.db.image`),
+        };
+      } else {
+        throw new Error(
+          `deploy.arc.json: envs.${name}.db.type must be "sqlite" or "postgres" (got "${dbType}")`,
+        );
+      }
+    }
+    validated.envs[name] = { domain, envVars, db };
   }
 
   const provision = (input as Record<string, unknown>).provision;

package/src/deploy/env-file.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "fs";
+import { appendFileSync, existsSync, readFileSync } from "fs";
 import { join } from "path";
 
 // ---------------------------------------------------------------------------
@@ -57,6 +57,40 @@ export function applyDeployGlobals(globals: Record<string, string>): void {
   }
 }
 
+/**
+ * Ensure a value exists for `key` in `deploy.arc.<envName>.env`. If absent,
+ * generate one via `generate()`, append it to the file (creating the file
+ * if needed), and return it. Pre-existing values (from the file or
+ * process.env) are returned unchanged.
+ *
+ * Used to bootstrap secrets the framework owns end-to-end (e.g. the
+ * Postgres sidecar password) without forcing the user to hand-edit the
+ * file before the first deploy.
+ */
+export function ensurePersistedSecret(
+  rootDir: string,
+  envName: string,
+  key: string,
+  generate: () => string,
+): string {
+  if (process.env[key]) return process.env[key]!;
+
+  const path = join(rootDir, `deploy.arc.${envName}.env`);
+  if (existsSync(path)) {
+    const existing = parseEnvFile(readFileSync(path, "utf-8"), path);
+    if (existing[key]) {
+      process.env[key] = existing[key];
+      return existing[key];
+    }
+  }
+
+  const value = generate();
+  const prefix = existsSync(path) && !readFileSync(path, "utf-8").endsWith("\n") ? "\n" : "";
+  appendFileSync(path, `${prefix}${key}=${value}\n`);
+  process.env[key] = value;
+  return value;
+}
+
 // ---------------------------------------------------------------------------
 // Parser
 // ---------------------------------------------------------------------------

package/src/platform/server.ts

@@ -52,17 +52,39 @@ export async function initContextHandler(
   context: any,
   dbPath: string,
 ): Promise<ContextHandler> {
+  const factory = await resolveDbAdapterFactory(dbPath);
+  const dbAdapter = factory(context);
+  const handler = new ContextHandler(context, dbAdapter);
+  await handler.init();
+  return handler;
+}
+
+/**
+ * Pick the database adapter factory based on runtime configuration.
+ *
+ * - When `DATABASE_URL` is set (Postgres sidecar generated by deploy, or any
+ *   external Postgres the operator wired up themselves), connect over the
+ *   network using the postgres adapter.
+ * - Otherwise fall back to the SQLite file at `dbPath`. The directory is
+ *   created on demand so first-boot in a fresh data volume just works.
+ *
+ * Both adapters share the `DBAdapterFactory` contract from arc-core, so the
+ * caller never needs to know which backend is live.
+ */
+async function resolveDbAdapterFactory(dbPath: string) {
+  const databaseUrl = process.env.DATABASE_URL;
+  if (databaseUrl && databaseUrl.length > 0) {
+    const { createPostgreSQLAdapterFactoryFromUrl } = await import(
+      "@arcote.tech/arc-adapter-db-postgres"
+    );
+    return createPostgreSQLAdapterFactoryFromUrl(databaseUrl);
+  }
   const { createBunSQLiteAdapterFactory } = await import(
     "@arcote.tech/arc-adapter-db-sqlite"
   );
-
   const dbDir = dbPath.substring(0, dbPath.lastIndexOf("/"));
   if (dbDir) mkdirSync(dbDir, { recursive: true });
-
-  const dbAdapter = createBunSQLiteAdapterFactory(dbPath)(context);
-  const handler = new ContextHandler(context, dbAdapter);
-  await handler.init();
-  return handler;
+  return createBunSQLiteAdapterFactory(dbPath);
 }
 
 // ---------------------------------------------------------------------------
@@ -536,17 +558,14 @@ export async function startPlatformServer(
     };
   }
 
-  // Context available — use createArcServer with platform handlers on top
-  const { createBunSQLiteAdapterFactory } = await import(
-    "@arcote.tech/arc-adapter-db-sqlite"
-  );
+  // Context available — use createArcServer with platform handlers on top.
+  // `resolveDbAdapterFactory` picks SQLite or Postgres based on DATABASE_URL.
   const dbPath = opts.dbPath || join(ws.arcDir, "data", "arc.db");
-  const dbDir = dbPath.substring(0, dbPath.lastIndexOf("/"));
-  if (dbDir) mkdirSync(dbDir, { recursive: true });
+  const dbAdapterFactory = await resolveDbAdapterFactory(dbPath);
 
   const arcServer = await createArcServer({
     context,
-    dbAdapterFactory: createBunSQLiteAdapterFactory(dbPath),
+    dbAdapterFactory,
     port,
     httpHandlers: [
       // Platform-specific handlers (checked AFTER arc handlers)