@arcote.tech/arc-cli 0.6.1 → 0.7.0

package/src/deploy/deploy-env.ts

@@ -0,0 +1,129 @@
+import type { DeployConfig, DeployTarget } from "./config";
+import { assertExec, sshExec } from "./ssh";
+
+// ---------------------------------------------------------------------------
+// deploy-env — per-env update flow. Called once per env after the image is
+// pushed to the private registry.
+//
+// Sequence:
+//   1. Atomically update /opt/arc/.env line `ARC_IMAGE_<ENV>=<fullRef>` so
+//      docker compose pulls the new ref on next up.
+//   2. `docker compose pull arc-<env>` — fetches new image layers.
+//   3. `docker compose up -d arc-<env>` — recreates the container.
+//   4. Prune older image tags on the host (keep N most recent).
+//   5. Health-check via SSH (curl localhost via internal Docker network).
+//
+// No SSH tunnel, no rsync, no HTTP API. Compose.yml on the host stays static
+// — only `.env` changes per deploy. Idempotent: running twice with the same
+// fullRef is a no-op once docker detects the image is up to date.
+// ---------------------------------------------------------------------------
+
+export interface UpdateEnvDeploymentOptions {
+  target: DeployTarget;
+  cfg: DeployConfig;
+  env: string;
+  fullRef: string;
+  /** How many image tags to keep per workspace (oldest pruned). Default 3. */
+  retainImages?: number;
+}
+
+export interface UpdateEnvDeploymentResult {
+  env: string;
+  fullRef: string;
+  /** True if `docker compose up -d` actually recreated the container (i.e. image changed). */
+  redeployed: boolean;
+}
+
+const HEALTH_RETRIES = 10;
+const HEALTH_DELAY_MS = 1000;
+
+export async function updateEnvDeployment(
+  opts: UpdateEnvDeploymentOptions,
+): Promise<UpdateEnvDeploymentResult> {
+  const { target, cfg, env, fullRef } = opts;
+  const upperEnv = env.toUpperCase().replace(/-/g, "_");
+  const envVarName = `ARC_IMAGE_${upperEnv}`;
+
+  // Step 1 — atomic .env line update. Use awk to either replace the existing
+  // line or append a new one, write to .env.tmp, then mv. mv on the same fs
+  // is atomic, so concurrent reads see either the old or new file, never a
+  // partial write.
+  const envPath = `${cfg.target.remoteDir}/.env`;
+  const escapedRef = fullRef.replace(/"/g, '\\"');
+  const updateScript = [
+    `touch ${envPath}`,
+    `awk -v line="${envVarName}=${escapedRef}" -v key="${envVarName}=" '`,
+    `  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, updateScript);
+
+  // Step 2 — pull. May be a no-op if `fullRef` was already pulled previously.
+  await assertExec(
+    target,
+    `cd ${cfg.target.remoteDir} && docker compose pull arc-${env}`,
+  );
+
+  // Step 3 — recreate. `up -d` is a no-op if the container is already running
+  // with the requested image; otherwise it recreates. Either way the container
+  // ends in "running" state with the desired image.
+  await assertExec(
+    target,
+    `cd ${cfg.target.remoteDir} && docker compose up -d arc-${env}`,
+  );
+
+  // Step 4 — retention. Find image tags for this workspace, sort by created
+  // time (newest first), drop the top N, delete the rest. `:latest` is moved
+  // by docker push and stays — we never explicitly delete it.
+  const retain = opts.retainImages ?? 3;
+  const imageBaseName = imageBaseFromRef(fullRef);
+  if (imageBaseName) {
+    const pruneScript = [
+      `docker images "${imageBaseName}" --format "{{.Repository}}:{{.Tag}} {{.CreatedAt}}" `,
+      `| grep -v ":latest " `,
+      `| sort -k2,3 -r `,
+      `| tail -n +${retain + 1} `,
+      `| awk '{print $1}' `,
+      `| xargs -r docker rmi 2>/dev/null || true`,
+    ].join("");
+    await sshExec(target, pruneScript, { quiet: true });
+  }
+
+  // Step 5 — health check. arc-<env> exposes 5005 inside the docker network;
+  // from the host we can reach it via `docker exec caddy curl -fsS ...`
+  // (no port mapped to host). Cheap, requires no public DNS.
+  const ok = await healthCheck(target, env);
+
+  return { env, fullRef, redeployed: ok };
+}
+
+/**
+ * Extract the `<registry>/<workspace>` prefix from a full image ref so we can
+ * list its tags for retention. `registry.example.com/app:abc123` → `registry.example.com/app`.
+ */
+function imageBaseFromRef(fullRef: string): string | null {
+  const colonIdx = fullRef.lastIndexOf(":");
+  return colonIdx > 0 ? fullRef.slice(0, colonIdx) : null;
+}
+
+async function healthCheck(target: DeployTarget, env: string): Promise<boolean> {
+  for (let i = 0; i < HEALTH_RETRIES; i++) {
+    const res = await sshExec(
+      target,
+      `docker exec arc-${env} wget -qO- http://localhost:5005/health 2>&1 || echo HEALTHCHECK_FAILED`,
+      { quiet: true },
+    );
+    if (res.exitCode === 0 && !res.stdout.includes("HEALTHCHECK_FAILED")) {
+      return true;
+    }
+    await sleep(HEALTH_DELAY_MS);
+  }
+  return false;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/deploy/htpasswd.ts

@@ -0,0 +1,28 @@
+// ---------------------------------------------------------------------------
+// htpasswd — bcrypt-hashed line for the registry's basic-auth file.
+//
+// Format: `<user>:<bcrypt-hash>` (one entry per line in `/auth/htpasswd`).
+// The `registry:2` container reads this file when REGISTRY_AUTH=htpasswd.
+//
+// Zero external binaries: Bun.password.hash supports bcrypt natively, so dev
+// machines don't need apache2-utils / htpasswd CLI installed.
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate one htpasswd line for the given user/password pair. Throws on
+ * empty input — guard against silent misconfiguration that would lock
+ * everyone out of the registry.
+ */
+export async function generateHtpasswd(
+  user: string,
+  password: string,
+): Promise<string> {
+  if (!user || !password) {
+    throw new Error("htpasswd: user and password must both be non-empty");
+  }
+  const hash = await Bun.password.hash(password, {
+    algorithm: "bcrypt",
+    cost: 10,
+  });
+  return `${user}:${hash}\n`;
+}

package/src/deploy/image-template.ts

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// image-template — Dockerfile generation for `arc platform deploy`.
+//
+// Image layout:
+//   /app/.arc/platform/   ← module chunks, shell, styles, framework manifest,
+//                            server bundles, AND `host.js` (the arc-cli bundle
+//                            copied from the same CLI that produced the build)
+//   /app/node_modules/    ← framework peers installed at image build time
+//   /app/public/          ← workspace public assets (if present)
+//   /app/manifest.json    ← webmanifest (if present)
+//   /app/locales/         ← compiled translation catalogs (if present)
+//
+// The arc-cli bundle ships INSIDE the image as `host.js` — no `bun add arc-cli`
+// from npm, no `ARG ARC_CLI_VERSION`. The CLI that runs `arc platform deploy`
+// embeds its own bundled bytes, so what the user installed locally is exactly
+// what the container executes. Eliminates the npm/local skew entirely.
+//
+// Layer order is chosen for cache efficiency: framework peers change rarely
+// (per release of those peers), user artifacts change every deploy.
+// ---------------------------------------------------------------------------
+
+export interface DockerfileInputs {
+  /** True if `<rootDir>/public/` exists and should be copied into the image. */
+  hasPublicDir: boolean;
+  /** True if a webmanifest file (`manifest.json` or `manifest.webmanifest`) lives at workspace root. */
+  hasManifest: boolean;
+  /** Path of the webmanifest relative to workspace root, if `hasManifest` is true. */
+  manifestPath?: string;
+  /** True if `<rootDir>/locales/` exists. Compiled .json catalogs from buildTranslations live there. */
+  hasLocales: boolean;
+}
+
+export function generateDockerfile(inputs: DockerfileInputs): string {
+  const conditionalCopies: string[] = [];
+  if (inputs.hasPublicDir) {
+    conditionalCopies.push("COPY public/ /app/public/");
+  }
+  if (inputs.hasManifest && inputs.manifestPath) {
+    conditionalCopies.push(`COPY ${inputs.manifestPath} /app/${inputs.manifestPath}`);
+  }
+  if (inputs.hasLocales) {
+    conditionalCopies.push("COPY locales/ /app/locales/");
+  }
+
+  return [
+    "# Generated by `arc platform deploy` — do not edit by hand.",
+    "FROM oven/bun:1-alpine",
+    "",
+    "RUN apk add --no-cache tini ca-certificates",
+    "",
+    "WORKDIR /app",
+    "",
+    "# Layer 1 — framework peers as /app/package.json + install into /app/node_modules.",
+    "# resolveWorkspace() walks up looking for the first package.json (finds /app/),",
+    "# loadServerContext resolves @arcote.tech/platform from /app/node_modules.",
+    "# Cached, invalidates only on .arc/platform/package.json change.",
+    "COPY .arc/platform/package.json /app/package.json",
+    "RUN cd /app && bun install --production --no-save",
+    "",
+    "# Layer 2 — user artifacts (chunks, shell, styles, server bundles, host.js).",
+    "# host.js IS the arc-cli bundle — `arc platform deploy` copied it here from",
+    "# whatever arc-cli was on the user's PATH. No npm dependency at runtime.",
+    "COPY .arc/platform/ /app/.arc/platform/",
+    ...conditionalCopies,
+    "",
+    "ENV PORT=5005",
+    "ENV NODE_ENV=production",
+    "EXPOSE 5005",
+    "",
+    'ENTRYPOINT ["tini", "--"]',
+    'CMD ["bun", "run", "/app/.arc/platform/host.js", "platform", "start"]',
+    "",
+  ].join("\n");
+}

package/src/deploy/image.ts

@@ -0,0 +1,237 @@
+import { spawn } from "bun";
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import type { WorkspaceInfo } from "../platform/shared";
+import { generateDockerfile, type DockerfileInputs } from "./image-template";
+
+// ---------------------------------------------------------------------------
+// image — local Docker image build for `arc platform deploy`.
+//
+// Tag scheme:
+//   <imageName>:<contentHash>   — deterministic content-addressable tag
+//   <imageName>:latest          — movable convenience tag
+//
+// `contentHash` = sha256(manifest.json bytes, with `buildTime` field stripped).
+// The first 12 hex chars become the tag. Stripping buildTime guarantees the
+// same source produces the same hash on every build — so reruns push a no-op
+// (registry detects "already pushed"), and rollback can address an old image
+// by its hash without needing a metadata lookup.
+//
+// The arc-cli bundle (`dist/index.js`) is copied INTO the image at
+// `.arc/platform/host.js`. Whatever CLI ran `arc platform deploy` becomes the
+// CLI that runs `arc platform start` inside the container. No npm dependency,
+// no version skew between the host that built the image and the image itself.
+// ---------------------------------------------------------------------------
+
+export interface BuildImageOptions {
+  /** Image name (typically the workspace package name, sanitized). */
+  imageName: string;
+  /** Optional registry hostname for `fullRef`. If absent, fullRef = imageTag. */
+  registryDomain?: string;
+}
+
+export interface BuildImageResult {
+  /** `<imageName>:<contentHash>` — local tag. */
+  imageTag: string;
+  /** `<registry>/<imageName>:<contentHash>` if `registryDomain` was set, else equal to `imageTag`. */
+  fullRef: string;
+  /** Truncated sha256 of the manifest content (12 hex chars). */
+  contentHash: string;
+}
+
+export async function buildImage(
+  ws: WorkspaceInfo,
+  opts: BuildImageOptions,
+): Promise<BuildImageResult> {
+  await ensureDocker();
+
+  const manifestPath = join(ws.modulesDir, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(
+      `No build manifest at ${manifestPath}. Run \`arc platform build\` first or omit --skip-build.`,
+    );
+  }
+
+  // Embed THIS CLI's own bundle inside the image. `host.js` becomes the
+  // runtime entry point — the image runs whatever bytes the user has locally,
+  // no npm install dance, no version skew.
+  embedCliBundle(ws);
+
+  // contentHash MUST be computed AFTER embedCliBundle. host.js bytes flow
+  // into the manifest indirectly via the docker layer, but our hash is over
+  // manifest.json alone — embedding doesn't touch that. Order kept for
+  // safety if we later widen the hash inputs.
+  const contentHash = computeContentHash(manifestPath);
+  const imageTag = `${opts.imageName}:${contentHash}`;
+  const fullRef = opts.registryDomain
+    ? `${opts.registryDomain}/${imageTag}`
+    : imageTag;
+
+  const dockerfileInputs = collectDockerfileInputs(ws);
+  const dockerfile = generateDockerfile(dockerfileInputs);
+
+  // Write Dockerfile to a temp location and pass via -f. Cannot drop it into
+  // the workspace root because users may have their own Dockerfile, and we
+  // never want to clutter the repo with generated artifacts.
+  const buildContextDir = ws.rootDir;
+  const dockerfileDir = join(tmpdir(), `arc-image-${Date.now()}`);
+  mkdirSync(dockerfileDir, { recursive: true });
+  const dockerfilePath = join(dockerfileDir, "Dockerfile");
+  writeFileSync(dockerfilePath, dockerfile);
+
+  const buildArgs = [
+    "build",
+    "-f",
+    dockerfilePath,
+    "-t",
+    fullRef,
+    "-t",
+    `${opts.imageName}:latest`,
+    buildContextDir,
+  ];
+
+  const proc = spawn({
+    cmd: ["docker", ...buildArgs],
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  const exit = await proc.exited;
+  if (exit !== 0) {
+    throw new Error(`docker build failed (exit ${exit})`);
+  }
+
+  return { imageTag, fullRef, contentHash };
+}
+
+// ---------------------------------------------------------------------------
+// CLI bundle embedding
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy this CLI's `dist/index.js` into the workspace's `.arc/platform/host.js`.
+ * The Dockerfile then COPYs `.arc/platform/` whole-cloth, so the bundle lands
+ * in the image at `/app/.arc/platform/host.js` — that's what CMD runs.
+ *
+ * "This CLI" = whichever arc-cli is executing right now (resolved via
+ * `import.meta.url` walking up to the package.json with name
+ * `@arcote.tech/arc-cli`). The image therefore runs identical bytes to the
+ * CLI that produced the build — no npm registry roundtrip, no version skew.
+ */
+function embedCliBundle(ws: WorkspaceInfo): void {
+  const source = locateCliBundle();
+  const target = join(ws.arcDir, "host.js");
+  copyFileSync(source, target);
+}
+
+/**
+ * Walk up from this module's location until we find a package.json with
+ * `name: "@arcote.tech/arc-cli"`. Return `<that dir>/dist/index.js`.
+ *
+ * Works in both source (`packages/cli/src/deploy/image.ts`) and bundled
+ * (`packages/cli/dist/index.js`) execution contexts: the bundle path itself
+ * is `dist/index.js` so locateCliBundle returns it directly.
+ */
+function locateCliBundle(): string {
+  const here = fileURLToPath(import.meta.url);
+  let cur = dirname(here);
+  while (cur !== "/" && cur !== "") {
+    const candidate = join(cur, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+        if (pkg.name === "@arcote.tech/arc-cli") {
+          const distIndex = join(realpathSync(cur), "dist", "index.js");
+          if (!existsSync(distIndex)) {
+            throw new Error(
+              `arc-cli bundle missing at ${distIndex}. Run \`bun run build\` in packages/cli/.`,
+            );
+          }
+          return distIndex;
+        }
+      } catch (e) {
+        if (e instanceof Error && e.message.startsWith("arc-cli bundle")) throw e;
+        // Malformed package.json — keep walking.
+      }
+    }
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  throw new Error(
+    "Could not locate @arcote.tech/arc-cli package.json walking up from " + here,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export async function ensureDocker(): Promise<void> {
+  try {
+    const proc = spawn({
+      cmd: ["docker", "--version"],
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const exit = await proc.exited;
+    if (exit !== 0) throw new Error("docker --version exited non-zero");
+  } catch {
+    throw new Error(
+      "Docker is not available on PATH. Install Docker Desktop (or docker engine + buildx) before running deploy.",
+    );
+  }
+}
+
+function computeContentHash(manifestPath: string): string {
+  const raw = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  // Strip the only non-deterministic field. The hash needs to be stable across
+  // identical builds so the registry can dedupe and rollback can address a
+  // specific build by tag.
+  delete raw.buildTime;
+  const canonical = JSON.stringify(raw);
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 12);
+}
+
+function collectDockerfileInputs(ws: WorkspaceInfo): DockerfileInputs {
+  const hasPublicDir = existsSync(join(ws.rootDir, "public"));
+  const hasLocales = existsSync(join(ws.rootDir, "locales"));
+
+  let manifestPath: string | undefined;
+  for (const name of ["manifest.webmanifest", "manifest.json"]) {
+    if (existsSync(join(ws.rootDir, name))) {
+      manifestPath = name;
+      break;
+    }
+  }
+
+  return {
+    hasPublicDir,
+    hasManifest: !!manifestPath,
+    manifestPath,
+    hasLocales,
+  };
+}
+
+/**
+ * Sanitize a workspace package name into a Docker-safe image name.
+ * Replaces forbidden chars (`@`, `/`, uppercase) with dashes. Empty input
+ * falls back to "arc-app".
+ */
+export function sanitizeImageName(name: string): string {
+  const cleaned = name
+    .toLowerCase()
+    .replace(/^@/, "")
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return cleaned || "arc-app";
+}

package/src/deploy/registry.ts

@@ -0,0 +1,79 @@
+import { spawn } from "bun";
+import type { DeployRegistry } from "./config";
+
+// ---------------------------------------------------------------------------
+// registry — Docker CLI helpers for talking to our private registry.
+//
+// `docker login` stores credentials in `~/.docker/config.json` (local CLI host
+// or remote target). We never embed passwords in commands — always pipe via
+// stdin so they don't show up in `ps` or shell history.
+// ---------------------------------------------------------------------------
+
+/**
+ * Log in to a private Docker registry. Reads password from the env var named
+ * in `registry.passwordEnv` to keep the secret off the command line. Returns
+ * once `docker login` exits cleanly; throws with the captured stderr otherwise.
+ */
+export async function dockerLogin(registry: DeployRegistry): Promise<void> {
+  const password = process.env[registry.passwordEnv];
+  if (!password) {
+    throw new Error(
+      `Registry password env var ${registry.passwordEnv} is not set. ` +
+        `Set it in your shell before running deploy.`,
+    );
+  }
+
+  const proc = spawn({
+    cmd: [
+      "docker",
+      "login",
+      registry.domain,
+      "-u",
+      registry.username,
+      "--password-stdin",
+    ],
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  proc.stdin.write(password);
+  await proc.stdin.end();
+
+  const exit = await proc.exited;
+  if (exit !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(
+      `docker login ${registry.domain} failed (exit ${exit}): ${stderr.trim()}`,
+    );
+  }
+}
+
+/**
+ * Logout from a registry — removes its credentials from
+ * `~/.docker/config.json`. Useful in CI teardown; rarely needed locally.
+ */
+export async function dockerLogout(domain: string): Promise<void> {
+  const proc = spawn({
+    cmd: ["docker", "logout", domain],
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  await proc.exited;
+}
+
+/**
+ * Push a pre-tagged image. Caller is responsible for tagging the local image
+ * with the full registry-qualified ref (e.g. `registry.example.com/app:hash`)
+ * via `docker tag` before this call — `buildImage` already does that.
+ */
+export async function dockerPush(fullRef: string): Promise<void> {
+  const proc = spawn({
+    cmd: ["docker", "push", fullRef],
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  const exit = await proc.exited;
+  if (exit !== 0) {
+    throw new Error(`docker push ${fullRef} failed (exit ${exit})`);
+  }
+}