@arcote.tech/arc-cli 0.7.0 → 0.7.2

package/src/commands/platform-deploy.ts

@@ -36,6 +36,13 @@ interface PlatformDeployOptions {
    * Format: bare content hash (e.g. `abc123def456`) or full ref.
    */
   imageTag?: string;
+  /**
+   * Force the Ansible host-bootstrap step to run even when the marker says
+   * the host is already configured. Default behavior skips Ansible whenever
+   * the server is reachable and has Docker — use this after editing the
+   * embedded playbook or to recover from a corrupted host config.
+   */
+  forceBootstrap?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -78,7 +85,7 @@ export async function platformDeploy(
     : Object.keys(cfg.envs);
 
   // 2. Ensure local build (unless --image-tag rollback skips build+push entirely)
-  const manifestPath = join(ws.modulesDir, "manifest.json");
+  const manifestPath = join(ws.arcDir, "manifest.json");
   if (!options.imageTag) {
     const needBuild = options.rebuild || !existsSync(manifestPath);
     if (needBuild && !options.skipBuild) {
@@ -91,9 +98,8 @@ export async function platformDeploy(
     }
   }
 
-  // 3. Resolve the full image ref. Two paths:
-  //    a) --image-tag <hash> — rollback / pin. No build, no push.
-  //    b) Default — buildImage locally, push to private registry.
+  // 3. Build the image locally. Push happens AFTER bootstrap so the registry
+  // container exists when we try to push to it (chicken-and-egg otherwise).
   const imageName = sanitizeImageName(ws.rootPkg.name ?? ws.appName);
   let fullRef: string;
   let contentHash: string;
@@ -119,31 +125,34 @@ export async function platformDeploy(
       log(`contentHash: ${contentHash}`);
       return;
     }
-
-    // 4. Push to the private registry. dockerLogin reads password from the
-    // env var named in cfg.registry.passwordEnv.
-    log(`Logging in to ${cfg.registry.domain}...`);
-    await dockerLogin(cfg.registry);
-    log(`Pushing ${fullRef}...`);
-    await dockerPush(fullRef);
-    ok("Image pushed");
   }
 
-  // 5. Detect remote state, bootstrap if needed
+  // 4. Detect remote state + bootstrap. This brings up caddy + registry on
+  // first deploy (and regenerates the stack if config changed). MUST run
+  // before dockerLogin/dockerPush — without registry container + Caddy vhost
+  // for it, dockerLogin would TLS-fail.
   log("Inspecting remote server...");
   const state = await detectRemoteState(cfg);
   log(`Remote state: ${state.kind}`);
 
   const cliVersion = readCliVersion();
   const configHash = await hashDeployConfig(ws.rootDir);
-  if (state.kind !== "ready") {
-    await bootstrap({
-      cfg,
-      rootDir: ws.rootDir,
-      state,
-      cliVersion,
-      configHash,
-    });
+  await bootstrap({
+    cfg,
+    rootDir: ws.rootDir,
+    state,
+    cliVersion,
+    configHash,
+    forceAnsible: options.forceBootstrap,
+  });
+
+  // 5. Push the image to the now-running registry.
+  if (!options.imageTag) {
+    log(`Logging in to ${cfg.registry.domain}...`);
+    await dockerLogin(cfg.registry);
+    log(`Pushing ${fullRef}...`);
+    await dockerPush(fullRef);
+    ok("Image pushed");
   }
 
   // 6. Update each env — atomic /opt/arc/.env line + pull + up + health

package/src/deploy/ansible.ts

@@ -1,10 +1,24 @@
 import { spawn as nodeSpawn } from "node:child_process";
-import { mkdirSync, writeFileSync } from "fs";
-import { tmpdir } from "os";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { homedir, tmpdir } from "os";
 import { join } from "path";
 import { ASSETS, materializeAssets } from "./assets";
 import type { DeployProvisionAnsible, DeployTarget } from "./config";
 
+function pickSshKeyForAnsible(configured?: string): string | null {
+  if (configured) {
+    const expanded = configured.startsWith("~")
+      ? join(homedir(), configured.slice(1))
+      : configured;
+    return existsSync(expanded) ? expanded : null;
+  }
+  for (const name of ["id_ed25519", "id_ecdsa", "id_rsa"]) {
+    const path = join(homedir(), ".ssh", name);
+    if (existsSync(path)) return path;
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Runs Ansible from embedded assets. Inventory is generated on the fly,
 // targeting the single host described by DeployTarget. Runs as root on the
@@ -27,12 +41,18 @@ export async function runAnsible(inputs: AnsibleInputs): Promise<void> {
   const user = inputs.asRoot ? "root" : inputs.target.user;
   const port = inputs.ansible?.sshPort ?? inputs.target.port;
 
+  // IdentitiesOnly=yes + explicit -i prevent ssh from walking every key in
+  // ssh-agent (the server's MaxAuthTries=3 trips when the agent holds >3 keys
+  // and ours isn't first). PreferredAuthentications=publickey skips gssapi
+  // prompts that also count against MaxAuthTries.
+  const sshKey = pickSshKeyForAnsible(inputs.target.sshKey);
+  const sshKeyArg = sshKey ? ` -o IdentitiesOnly=yes -i ${sshKey}` : "";
   const inventory = [
     "[arc]",
     `${inputs.target.host} ansible_user=${user} ansible_port=${port}`,
     "",
     "[arc:vars]",
-    "ansible_ssh_common_args='-o StrictHostKeyChecking=accept-new -o BatchMode=yes'",
+    `ansible_ssh_common_args='-o StrictHostKeyChecking=accept-new -o BatchMode=yes -o PreferredAuthentications=publickey${sshKeyArg}'`,
     "ansible_python_interpreter=/usr/bin/python3",
     "",
   ].join("\n");

package/src/deploy/assets/ansible/site.yml

@@ -115,7 +115,22 @@
         - { policy: deny, dir: incoming }
         - { policy: allow, dir: outgoing }
 
-    - name: Open firewall ports
+    - name: Remove legacy ufw limit rule on SSH (replaced by plain allow)
+      # If a prior bootstrap installed `ufw limit 22/tcp`, drop it — otherwise
+      # the limit rule shadows the allow rule and rate-throttles deploy flows.
+      ufw:
+        rule: limit
+        port: "{{ ssh_port }}"
+        proto: tcp
+        delete: true
+      ignore_errors: true
+
+    - name: Open firewall ports (SSH key-only auth, no brute-force surface)
+      # SSH on port 22: PasswordAuthentication=no + key-only means brute force
+      # is impossible without the operator's private key. Rate-limiting (ufw
+      # limit / fail2ban sshd jail) breaks legitimate deploy flows that open
+      # many short SSH connections in sequence (canSsh → sshExec → scp → ...).
+      # 80/443: Caddy ACME + app traffic, never rate-limited.
       ufw:
         rule: allow
         port: "{{ item }}"
@@ -129,17 +144,18 @@
       ufw:
         state: enabled
 
-    - name: Configure fail2ban for sshd
+    - name: Disable fail2ban sshd jail
+      # Key-only SSH + ufw rate-limit make fail2ban for sshd redundant and
+      # actively harmful when the operator's IP roams. Keep fail2ban installed
+      # for future jails (web/db) but turn off the sshd jail explicitly.
       copy:
         dest: /etc/fail2ban/jail.local
         content: |
           [sshd]
-          enabled = true
-          port = {{ ssh_port }}
-          maxretry = 5
-          findtime = 600
-          bantime = 3600
+          enabled = false
+          {% if extra_allowed_ips %}
           ignoreip = 127.0.0.1/8 ::1 {{ extra_allowed_ips | join(' ') }}
+          {% endif %}
         mode: "0644"
       notify: restart fail2ban
 

package/src/deploy/assets.ts

@@ -201,7 +201,22 @@ const ANSIBLE_SITE_YML = `---
         - { policy: deny, dir: incoming }
         - { policy: allow, dir: outgoing }
 
-    - name: Open firewall ports
+    - name: Remove legacy ufw limit rule on SSH (replaced by plain allow)
+      # If a prior bootstrap installed \`ufw limit 22/tcp\`, drop it — otherwise
+      # the limit rule shadows the allow rule and rate-throttles deploy flows.
+      ufw:
+        rule: limit
+        port: "{{ ssh_port }}"
+        proto: tcp
+        delete: true
+      ignore_errors: true
+
+    - name: Open firewall ports (SSH key-only auth, no brute-force surface)
+      # SSH on port 22: PasswordAuthentication=no + key-only means brute force
+      # is impossible without the operator's private key. Rate-limiting (ufw
+      # limit / fail2ban sshd jail) breaks legitimate deploy flows that open
+      # many short SSH connections in sequence (canSsh -> sshExec -> scp -> ...).
+      # 80/443: Caddy ACME + app traffic, never rate-limited.
       ufw:
         rule: allow
         port: "{{ item }}"
@@ -215,17 +230,18 @@ const ANSIBLE_SITE_YML = `---
       ufw:
         state: enabled
 
-    - name: Configure fail2ban for sshd
+    - name: Disable fail2ban sshd jail
+      # Key-only SSH + ufw rate-limit make fail2ban for sshd redundant and
+      # actively harmful when the operator's IP roams. Keep fail2ban installed
+      # for future jails (web/db) but turn off the sshd jail explicitly.
       copy:
         dest: /etc/fail2ban/jail.local
         content: |
           [sshd]
-          enabled = true
-          port = {{ ssh_port }}
-          maxretry = 5
-          findtime = 600
-          bantime = 3600
+          enabled = false
+          {% if extra_allowed_ips %}
           ignoreip = 127.0.0.1/8 ::1 {{ extra_allowed_ips | join(' ') }}
+          {% endif %}
         mode: "0644"
       notify: restart fail2ban
 

package/src/deploy/bootstrap.ts

@@ -13,6 +13,32 @@ import { ok, log, err } from "../platform/shared";
 import { writeStateMarker, STATE_MARKER_PATH } from "./remote-state";
 import type { RemoteState } from "./remote-state";
 import { assertExec, baseSshArgs, canSsh, scpUpload, sshExec, waitForSsh } from "./ssh";
+import type { DeployTarget } from "./config";
+
+/**
+ * Wait until *any* of the supplied SSH targets accepts a connection. Polls
+ * all targets in parallel each round; the first one that succeeds wins.
+ * Useful when we don't know whether the host is on its first ansible-less
+ * boot (root only) or already hardened (deploy user only).
+ */
+async function waitForAnySsh(
+  targets: DeployTarget[],
+  opts: { timeoutMs?: number; intervalMs?: number } = {},
+): Promise<void> {
+  const timeout = opts.timeoutMs ?? 300_000;
+  const interval = opts.intervalMs ?? 5_000;
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    const results = await Promise.all(targets.map((t) => canSsh(t)));
+    if (results.some(Boolean)) return;
+    await Bun.sleep(interval);
+  }
+  throw new Error(
+    `Timed out waiting for SSH on ${targets
+      .map((t) => `${t.user}@${t.host}`)
+      .join(" or ")}`,
+  );
+}
 
 // ---------------------------------------------------------------------------
 // Bootstrap orchestrator.
@@ -35,6 +61,8 @@ export interface BootstrapInputs {
   cliVersion: string;
   /** sha256 of deploy.arc.json — used for the remote state marker. */
   configHash: string;
+  /** Force the ansible run even when the host is already bootstrapped. */
+  forceAnsible?: boolean;
 }
 
 export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
@@ -66,16 +94,31 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
     saveDeployConfig(rootDir, cfg);
 
     log("Waiting for SSH to come up...");
-    await waitForSsh({ ...cfg.target, user: "root" });
+    // On a brand-new VM only root exists; on a re-applied (no-op) terraform
+    // the deploy user already exists and root login is disabled by ansible
+    // hardening. Probe both — succeed on whichever lands first.
+    await waitForAnySsh([
+      { ...cfg.target, user: "root" },
+      { ...cfg.target, user: cfg.target.user },
+    ]);
     ok("SSH reachable");
   }
 
-  if (state.kind === "unreachable" || state.kind === "no-docker") {
+  // Ansible only runs on fresh hosts (unreachable / no-docker) by default —
+  // it's idempotent but slow (~30–60s) and the host config rarely drifts.
+  // `--force-bootstrap` re-runs it on demand (after editing the embedded
+  // playbook, or to recover from manual host edits).
+  const needAnsible =
+    state.kind === "unreachable" ||
+    state.kind === "no-docker" ||
+    inputs.forceAnsible === true;
+
+  if (needAnsible) {
     log("Running Ansible bootstrap (Docker + firewall + SSH hardening)...");
     // Run as root whenever the configured user can't SSH (covers both freshly
     // provisioned VMs and second-attempt deploys after ansible failure).
     const deployUserWorks =
-      state.kind === "no-docker" && (await canSsh(cfg.target));
+      state.kind !== "unreachable" && (await canSsh(cfg.target));
     const asRoot = !deployUserWorks;
     await runAnsible({
       target: cfg.target,
@@ -85,7 +128,21 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
     ok("Host bootstrapped");
   }
 
-  if (state.kind !== "ready") {
+  // Force upStack whenever:
+  //   - stack isn't fully ready, OR
+  //   - marker is missing (legacy v0.5 deploy with no .arc-state.json), OR
+  //   - configHash differs from last bootstrap (deploy.arc.json changed), OR
+  //   - registry container isn't running (e.g. legacy stack predates v0.7)
+  // Without this, an old v0.5 stack (no registry container) is classified as
+  // "ready" and bootstrap is skipped — then `docker login` on the next step
+  // hits a vhost that doesn't exist and fails with a TLS error.
+  const needUpStack =
+    state.kind !== "ready" ||
+    state.marker === null ||
+    state.marker.configHash !== inputs.configHash ||
+    !(await isRegistryRunning(cfg));
+
+  if (needUpStack) {
     await upStack(inputs);
     ok("Docker stack up");
   }
@@ -98,6 +155,23 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
   });
 }
 
+/**
+ * Returns true iff `registry` service is up in /opt/arc/docker-compose.yml.
+ * Used by bootstrap to detect legacy v0.5 stacks that have no registry
+ * container and need a fresh stack write + restart.
+ */
+async function isRegistryRunning(cfg: DeployConfig): Promise<boolean> {
+  const res = await sshExec(
+    cfg.target,
+    `cd ${cfg.target.remoteDir} && docker compose ps --status running --format '{{.Service}}' 2>/dev/null || true`,
+    { quiet: true },
+  );
+  return res.stdout
+    .split("\n")
+    .map((s) => s.trim())
+    .includes("registry");
+}
+
 async function upStack(inputs: BootstrapInputs): Promise<void> {
   const { cfg } = inputs;
   const workDir = join(tmpdir(), "arc-deploy", `stack-${Date.now()}`);
@@ -206,19 +280,26 @@ async function sshDockerLogin(cfg: DeployConfig): Promise<void> {
       `Registry password env var ${cfg.registry.passwordEnv} is not set on the deploy host (CLI machine).`,
     );
   }
-  // Pipe via stdin — keeps password off the command line and shell history.
-  const cmd = `echo "$ARC_REGISTRY_PASSWORD_FORWARDED" | docker login ${cfg.registry.domain} -u ${cfg.registry.username} --password-stdin`;
+  // Stream password over SSH stdin — never reach the command line (no shell
+  // history, no `ps`, no double-shell-escape bugs). The remote shell pipes
+  // its own stdin straight into `docker login --password-stdin`.
+  const cmd = `docker login ${cfg.registry.domain} -u ${cfg.registry.username} --password-stdin`;
   const proc = spawn({
     cmd: [
       "ssh",
       ...baseSshArgs(cfg.target),
       `${cfg.target.user}@${cfg.target.host}`,
       "--",
-      `ARC_REGISTRY_PASSWORD_FORWARDED='${password.replace(/'/g, "'\\''")}' bash -c ${JSON.stringify(cmd)}`,
+      cmd,
     ],
+    stdin: "pipe",
     stdout: "pipe",
     stderr: "pipe",
   });
+  if (proc.stdin) {
+    await (proc.stdin as any).write(new TextEncoder().encode(password));
+    await (proc.stdin as any).end?.();
+  }
   const exit = await proc.exited;
   if (exit !== 0) {
     const stderr = await new Response(proc.stderr).text();
@@ -256,33 +337,61 @@ async function listConfiguredEnvs(cfg: DeployConfig): Promise<string[]> {
  * fail repeatedly. Fail fast with an actionable hint instead.
  */
 async function assertRegistryDnsResolves(cfg: DeployConfig): Promise<void> {
+  // Source of truth for "is the DNS update live?" is the authoritative NS for
+  // the apex domain — public resolvers (8.8.8.8 / 1.1.1.1) cache for minutes
+  // after a record change and disagree among themselves during propagation.
+  // Let's Encrypt ACME validates against the authoritative NS too, so this
+  // matches what Caddy will see when it tries to issue the cert.
+  const apex = apexDomain(cfg.registry.domain);
+  let nameservers = await digQuery("8.8.8.8", "NS", apex);
+  nameservers = nameservers.map((s) => s.replace(/\.$/, ""));
+
+  // Sources to query, in order: authoritative NS, then public resolvers.
+  // Accept the first source where any answer matches target.host.
+  const sources = [...nameservers, "1.1.1.1", "8.8.8.8"];
+  let lastAnswers: string[] = [];
+
+  for (const source of sources) {
+    const answers = await digQuery(source, "A", cfg.registry.domain);
+    if (answers.length === 0) continue;
+    lastAnswers = answers;
+    if (answers.includes(cfg.target.host)) return;
+  }
+
+  if (lastAnswers.length === 0) {
+    throw new Error(
+      `Registry DNS not configured: ${cfg.registry.domain} doesn't resolve. ` +
+        `Add an A record pointing to ${cfg.target.host} and re-run deploy.`,
+    );
+  }
+  throw new Error(
+    `Registry DNS mismatch: ${cfg.registry.domain} resolves to [${lastAnswers.join(", ")}], ` +
+      `but target host is ${cfg.target.host}. Update the A record before continuing.`,
+  );
+}
+
+function apexDomain(host: string): string {
+  // Naive eTLD+1 extraction: last 2 labels. Works for `.pl`, `.com`, etc.
+  // For `.co.uk` style TLDs the authoritative NS query still returns the
+  // correct NS — dig handles the SOA chase upstream.
+  const parts = host.split(".");
+  return parts.slice(-2).join(".");
+}
+
+async function digQuery(
+  server: string,
+  type: "A" | "NS",
+  name: string,
+): Promise<string[]> {
   const proc = spawn({
-    cmd: ["dig", "+short", "+time=3", "+tries=1", cfg.registry.domain],
+    cmd: ["dig", `@${server}`, "+short", "+time=3", "+tries=1", type, name],
     stdout: "pipe",
     stderr: "ignore",
   });
   const exit = await proc.exited;
-  if (exit !== 0) {
-    err(
-      `\`dig\` is not available — skipping DNS pre-flight for ${cfg.registry.domain}.`,
-    );
-    return;
-  }
-  const resolved = (await new Response(proc.stdout).text())
+  if (exit !== 0) return [];
+  return (await new Response(proc.stdout).text())
     .split("\n")
     .map((s) => s.trim())
     .filter(Boolean);
-
-  if (resolved.length === 0) {
-    throw new Error(
-      `Registry DNS not configured: ${cfg.registry.domain} doesn't resolve. ` +
-        `Add an A record pointing to ${cfg.target.host} and re-run deploy.`,
-    );
-  }
-  if (!resolved.includes(cfg.target.host)) {
-    throw new Error(
-      `Registry DNS mismatch: ${cfg.registry.domain} resolves to [${resolved.join(", ")}], ` +
-        `but target host is ${cfg.target.host}. Update the A record before continuing.`,
-    );
-  }
 }

package/src/deploy/compose.ts

@@ -61,10 +61,11 @@ export function generateCompose({ cfg }: ComposeOptions): string {
     const upperName = name.toUpperCase().replace(/-/g, "_");
     lines.push(`  arc-${name}:`);
     // Image ref comes from /opt/arc/.env, written per-deploy with the content
-    // hash of the latest build. The `:?` fallback fails compose with a clear
-    // error if the env var isn't set — that means "deploy hasn't run yet".
+    // hash of the latest build. Default to a placeholder so `docker compose
+    // pull caddy registry` doesn't fail with `:?` interpolation errors on this
+    // service before the first deploy ever sets ARC_IMAGE_<ENV>.
     lines.push(
-      `    image: \${ARC_IMAGE_${upperName}:?Run \\\`arc platform deploy ${name}\\\` to publish an image first}`,
+      `    image: \${ARC_IMAGE_${upperName}:-arc-${name}:not-deployed}`,
     );
     lines.push(`    container_name: arc-${name}`);
     lines.push("    restart: unless-stopped");

package/src/deploy/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+import { applyDeployGlobals, loadDeployEnvFiles } from "./env-file";
 
 // ---------------------------------------------------------------------------
 // deploy.arc.json — single source of truth for deployment configuration.
@@ -86,8 +87,17 @@ export function deployConfigExists(rootDir: string): boolean {
 }
 
 /**
- * Load deploy.arc.json, expand `${VAR}` references against process.env,
- * and validate shape. Throws with a precise error on any issue.
+ * Load deploy.arc.json + side-car env files (deploy.arc.env for globals,
+ * deploy.arc.<env>.env for per-env secrets), expand `${VAR}` references
+ * against process.env, and validate shape.
+ *
+ * Resolution order (last wins):
+ *   1. deploy.arc.json `envs.<name>.envVars` (declared in config)
+ *   2. deploy.arc.<name>.env (sidecar file, gitignored)
+ *   3. existing process.env values (CI/CD secret store)
+ *
+ * Globals from `deploy.arc.env` populate process.env (without overriding
+ * existing values), so terraform/dockerLogin/ansible see them naturally.
  */
 export function loadDeployConfig(rootDir: string): DeployConfig {
   const path = deployConfigPath(rootDir);
@@ -101,8 +111,33 @@ export function loadDeployConfig(rootDir: string): DeployConfig {
   } catch (e) {
     throw new Error(`Invalid JSON in ${DEPLOY_CONFIG_FILE}: ${(e as Error).message}`);
   }
+
+  // Read env names from raw JSON (pre-validation) to know which sidecar
+  // files to look for. Validation runs next.
+  const envNames = isObject(parsed) && isObject(parsed.envs)
+    ? Object.keys(parsed.envs)
+    : [];
+  const envFiles = loadDeployEnvFiles(rootDir, envNames);
+
+  // Globals → process.env (without overriding) so downstream code can read
+  // HCLOUD_TOKEN, ARC_REGISTRY_PASSWORD etc. as if they were exported in shell.
+  applyDeployGlobals(envFiles.globals);
+
   const expanded = expandEnvVars(parsed, process.env);
-  return validateDeployConfig(expanded);
+  const validated = validateDeployConfig(expanded);
+
+  // Merge sidecar per-env vars into cfg.envs[name].envVars.
+  // Existing keys (declared in deploy.arc.json) win over sidecar — config is
+  // the source of truth for variable NAMES, sidecar provides VALUES for
+  // anything not pinned otherwise.
+  for (const [envName, vars] of Object.entries(envFiles.perEnv)) {
+    if (!(envName in validated.envs)) continue;
+    const env = validated.envs[envName];
+    const merged: Record<string, string> = { ...vars, ...(env.envVars ?? {}) };
+    validated.envs[envName] = { ...env, envVars: merged };
+  }
+
+  return validated;
 }
 
 export function saveDeployConfig(rootDir: string, cfg: DeployConfig): void {

package/src/deploy/deploy-env.ts

@@ -51,7 +51,7 @@ export async function updateEnvDeployment(
   const envPath = `${cfg.target.remoteDir}/.env`;
   const escapedRef = fullRef.replace(/"/g, '\\"');
   const updateScript = [
-    `touch ${envPath}`,
+    `touch ${envPath} && `,
     `awk -v line="${envVarName}=${escapedRef}" -v key="${envVarName}=" '`,
     `  BEGIN { replaced=0 } `,
     `  $0 ~ "^"key { print line; replaced=1; next } `,

package/src/deploy/env-file.ts

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+// ---------------------------------------------------------------------------
+// Per-env secret files for `arc platform deploy`.
+//
+// Layout next to deploy.arc.json:
+//   deploy.arc.env          — globals (HCLOUD_TOKEN, ARC_REGISTRY_PASSWORD, ...)
+//   deploy.arc.<env>.env    — per-env user-app secrets (one file per env name
+//                              declared in deploy.arc.json)
+//
+// Both files are optional. `process.env` ALWAYS wins — CI/CD pipelines that
+// set secrets through the runner's secret store don't need a file on disk.
+//
+// Format: KEY=VALUE per line. `#` starts a comment. Surrounding single or
+// double quotes are stripped. Values may NOT span multiple lines (keep it
+// boring, no escape sequences).
+// ---------------------------------------------------------------------------
+
+export interface DeployEnvFiles {
+  /** Variables from `deploy.arc.env`. Applied to process.env unless already set. */
+  globals: Record<string, string>;
+  /** envName → variables from `deploy.arc.<envName>.env`. Merged into cfg.envs[name].envVars. */
+  perEnv: Record<string, Record<string, string>>;
+}
+
+export function loadDeployEnvFiles(
+  rootDir: string,
+  envNames: readonly string[],
+): DeployEnvFiles {
+  const globalsPath = join(rootDir, "deploy.arc.env");
+  const globals = existsSync(globalsPath)
+    ? parseEnvFile(readFileSync(globalsPath, "utf-8"), globalsPath)
+    : {};
+
+  const perEnv: Record<string, Record<string, string>> = {};
+  for (const name of envNames) {
+    const envPath = join(rootDir, `deploy.arc.${name}.env`);
+    if (existsSync(envPath)) {
+      perEnv[name] = parseEnvFile(readFileSync(envPath, "utf-8"), envPath);
+    }
+  }
+
+  return { globals, perEnv };
+}
+
+/**
+ * Apply globals to process.env. Existing values win — env vars set in the
+ * shell or by a CI runner take precedence over the file. This lets pipelines
+ * inject secrets via their native secret store without rewriting the file.
+ */
+export function applyDeployGlobals(globals: Record<string, string>): void {
+  for (const [k, v] of Object.entries(globals)) {
+    if (process.env[k] === undefined) {
+      process.env[k] = v;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+function parseEnvFile(
+  content: string,
+  pathForErrors: string,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const lines = content.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const eq = line.indexOf("=");
+    if (eq <= 0) {
+      throw new Error(
+        `${pathForErrors}:${i + 1}: malformed line (expected KEY=VALUE): ${raw}`,
+      );
+    }
+
+    const key = line.slice(0, eq).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      throw new Error(
+        `${pathForErrors}:${i + 1}: invalid variable name "${key}"`,
+      );
+    }
+
+    let value = line.slice(eq + 1).trim();
+    // Strip surrounding quotes (single or double) — leave inner content alone.
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    out[key] = value;
+  }
+
+  return out;
+}