@hiveku-apps/sync 0.1.0 → 0.3.0

package/src/push.mjs

@@ -0,0 +1,618 @@
+/**
+ * `hiveku-sync` deploy-lane commands — the agent-native push/deploy/pull-env
+ * loop. This is the CLI equivalent of the VS Code extension's Source Control
+ * "Push", so a headless agent (Claude Code in a terminal) gets the SAME proven
+ * mechanics without hand-rolling an MCP client:
+ *
+ *   push      Save local changes to the DEPLOY SOURCE (builder_code_versions),
+ *             lane-routed: CDN-servable binary (images/fonts/video under
+ *             public/<subdir>/) → assets_upload (S3/CDN); everything else →
+ *             batched, per-batch-verified project_files_bulk_save. This is what
+ *             deploy_site actually reads — NOT project_commit's GitHub branch.
+ *   deploy    deploy_site + poll deploy_get to a terminal status (--wait).
+ *   pull-env  project_secrets_list → .env.local with the same _DEV/_PROD/
+ *             _STAGING resolution the preview machine uses.
+ *
+ * Why not just project_commit (the old push)? project_commit is the GitHub
+ * path (needs a connected repo) AND sends every file in one unbatched call.
+ * bulk_save works on every project, batches for transport reliability, and —
+ * critically — never puts an image in builder_code_versions where it renders
+ * in the Fly preview but VANISHES on deploy (asset-build-bypass excludes it).
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+
+import {
+  clientFromCwd,
+  findProjectFolder,
+  resolveProject,
+  walkLocalFiles,
+  readProjectsManifest,
+  writeProjectsManifest,
+} from './projects.mjs';
+import { writeFileAtomic, readEnv, loadDotenv } from './util.mjs';
+
+const PROJECTS_DIR = 'projects';
+
+// ── Lane classification — mirrors the server's asset-build-bypass rule
+// (hiveku_builder/src/lib/deployment/asset-build-bypass.ts). A file resolves
+// into a public/ SUBDIRECTORY (public/<subdir>/...) → the CDN serves it and the
+// build must NOT bundle it, so it belongs in the asset lane. src/ assets and
+// public/ ROOT files (favicon.ico, robots.txt) stay code-lane. The BINARY guard
+// is added on top because assets_upload rejects code MIME types — a text file
+// under public/<subdir>/ (a .json/.html) still goes code-lane. This exactly
+// matches the VS Code extension's verified predicate (scm.ts push()).
+export function resolveAssetBuildPath(filePath) {
+  const clean = filePath.replace(/^\//, '');
+  return clean.startsWith('src/') || clean.startsWith('public/')
+    ? clean
+    : `public/${clean.replace(/^public\//, '')}`;
+}
+
+export function isCdnServableAssetPath(filePath) {
+  return /^public\/[^/]+\//.test(resolveAssetBuildPath(filePath));
+}
+
+/**
+ * The actual push routing decision: 'asset' → assets_upload (S3/CDN), 'code' →
+ * bulk_save. A file goes to the asset lane ONLY when it is BINARY *and* resolves
+ * under public/<subdir>/. The binary gate matters because assets_upload rejects
+ * code MIME types — a text file under public/<subdir>/ (a .json/.html) and every
+ * source file stays code-lane even though its path may resolve under public/.
+ */
+export function laneFor(filePath, encoding) {
+  return encoding === 'base64' && isCdnServableAssetPath(filePath) ? 'asset' : 'code';
+}
+
+/** Cheap, robust binary sniff: a NUL in the first 8KB, or a lossy utf-8 decode. */
+export function looksBinary(buf) {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return buf.toString('utf8').includes('�');
+}
+
+function sha256Hex(str) {
+  return createHash('sha256').update(str).digest('hex');
+}
+
+/** Read one file and shape it for a save/commit, choosing utf-8 vs base64. */
+async function readForPush(root, rel) {
+  const buf = await readFile(join(root, rel));
+  const binary = looksBinary(buf);
+  return {
+    path: rel,
+    content: binary ? buf.toString('base64') : buf.toString('utf8'),
+    encoding: binary ? 'base64' : 'utf-8',
+    bytes: buf.length,
+  };
+}
+
+// Concurrency-bounded map (no deps). Preserves input order in results.
+async function runLimited(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i], i);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+/** Resolve the account baseDir + project folder the same way status/push do. */
+function resolveBaseDir(cwd = process.cwd()) {
+  const idx = cwd.indexOf(`${sep}${PROJECTS_DIR}${sep}`);
+  return idx > -1 ? cwd.slice(0, idx) : cwd;
+}
+
+async function localCodeManifest(codeFiles) {
+  // codeFiles already read (utf-8). sha256 of the content string, matching the
+  // server's project_files_status hashing (and hiveku-sync's existing status).
+  return codeFiles.map((f) => ({ path: f.path, sha256: sha256Hex(f.content) }));
+}
+
+// ── assets_list → { resolvedPath -> byteSize } so we can skip re-uploading
+// unchanged images instead of flagging all 468 as only_local (the noise the
+// momentum session hit). assets_upload mirrors non-public paths under public/,
+// so we compare on the resolved public/ form. Size is the change signal —
+// assets_list doesn't expose a content hash, and a same-size same-path asset is
+// treated as unchanged (documented heuristic; --assets-all forces re-upload).
+async function remoteAssetMap(client, projectId) {
+  const map = new Map();
+  let page = 1;
+  const limit = 200;
+  while (true) {
+    let result;
+    try {
+      result = await client.callToolJson('assets_list', { project_id: projectId, page, limit });
+    } catch {
+      break;
+    }
+    const batch = result?.data || result?.assets || [];
+    for (const a of batch) {
+      const p = a.file_path || a.path;
+      if (!p) continue;
+      const size = a.file_size ?? a.size ?? a.bytes ?? null;
+      map.set(resolveAssetBuildPath(p), size);
+    }
+    const totalPages =
+      result?.pagination?.total_pages ?? result?.pagination?.pages ?? 1;
+    if (batch.length === 0 || page >= totalPages) break;
+    page += 1;
+  }
+  return map;
+}
+
+/**
+ * Compute what a push WOULD do — the deploy-source-accurate, asset-lane-aware
+ * diff shared by `push` and `status`. No writes. Returns the classified local
+ * files, the code diff (one status call), the asset diff (assets_list), and a
+ * summary plan.
+ */
+export async function computePushPlan({ client, projectId, folder, includeDeletes = false, noAssets = false, assetsAll = false }) {
+  // 1. Read + lane-classify every local file.
+  const rels = (await walkLocalFiles(folder)).map((abs) =>
+    relative(folder, abs).split(sep).join('/'),
+  );
+  const codeAll = [];
+  const assetAll = [];
+  for (const rel of rels) {
+    const f = await readForPush(folder, rel);
+    if (laneFor(rel, f.encoding) === 'asset') assetAll.push(f);
+    else codeAll.push(f);
+  }
+
+  // 2. CODE diff — ONE project_files_status call (never chunked: only_remote is
+  //    computed against the whole manifest, so chunking produces phantom
+  //    deletions — the exact gotcha the momentum session hit). Only CODE files
+  //    are sent, so binary assets never show up as false only_local.
+  const diff = (
+    await client.callToolJson('project_files_status', {
+      project_id: projectId,
+      local: await localCodeManifest(codeAll),
+    })
+  ).data;
+  const changedSet = new Set([
+    ...(diff.changed || []).map((c) => c.path),
+    ...(diff.only_local || []).map((c) => c.path),
+  ]);
+  const codeToSave = codeAll.filter((f) => changedSet.has(f.path));
+  // only_remote = code-lane paths (builder_code_versions) missing locally —
+  // status never reports binary assets (those live in builder_project_assets),
+  // so every only_remote entry is a genuine code deletion. If a public/<subdir>/
+  // image DOES show up here, it's a stale code_versions duplicate (the VANISH
+  // cause) and deleting it is correct — project_file_delete only touches
+  // code_versions, never the CDN asset we just uploaded.
+  const codeToDelete = includeDeletes ? (diff.only_remote || []).map((c) => c.path) : [];
+
+  // 3. ASSET diff — asset-lane-aware, so unchanged images aren't re-sent.
+  const assetToUpload = [];
+  let assetSkipped = 0;
+  if (!noAssets && assetAll.length > 0) {
+    const remote = await remoteAssetMap(client, projectId);
+    for (const f of assetAll) {
+      const key = resolveAssetBuildPath(f.path);
+      if (assetsAll) {
+        assetToUpload.push(f);
+      } else if (!remote.has(key)) {
+        assetToUpload.push(f); // new
+      } else {
+        const size = remote.get(key);
+        if (size != null && Number(size) !== f.bytes) assetToUpload.push(f); // size changed
+        else assetSkipped += 1;
+      }
+    }
+  }
+
+  const plan = {
+    project_id: projectId,
+    code_save: codeToSave.length,
+    code_delete: codeToDelete.length,
+    asset_upload: assetToUpload.length,
+    asset_unchanged: assetSkipped,
+    asset_skipped_lane: noAssets ? assetAll.length : 0,
+  };
+  return { codeAll, assetAll, diff, codeToSave, codeToDelete, assetToUpload, assetSkipped, plan };
+}
+
+// Thin CLI wrapper: resolve the MCP client + project folder from cwd, then run
+// the (fully testable) orchestration in pushProject.
+export async function runPush({ slug, profile, ...opts } = {}) {
+  const baseDir = resolveBaseDir();
+  const { client } = await clientFromCwd({ profileOverride: profile });
+  const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  if (!existsSync(folder)) {
+    throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);
+  }
+  return pushProject({
+    client,
+    projectId: info.project_id,
+    slug: resolvedSlug,
+    folder,
+    baseDir,
+    info,
+    ...opts,
+  });
+}
+
+/**
+ * Core push orchestration — no cwd/network resolution, so it can be driven with
+ * a fake MCP client + temp folder in tests. Lane-classifies local files, diffs
+ * code (one status call) + assets (assets_list), then batches bulk_save +
+ * assets_upload + deletions, with optional commit marker + deploy.
+ */
+export async function pushProject({
+  client,
+  projectId,
+  slug: resolvedSlug,
+  folder,
+  baseDir,
+  info = {},
+  commit,
+  deploy,
+  wait = false,
+  includeDeletes = false,
+  noAssets = false,
+  assetsAll = false,
+  dryRun = false,
+  branch,
+}) {
+  const {
+    codeAll,
+    assetAll,
+    codeToSave,
+    codeToDelete,
+    assetToUpload,
+    assetSkipped,
+    plan: basePlan,
+  } = await computePushPlan({ client, projectId, folder, includeDeletes, noAssets, assetsAll });
+  const plan = { project: resolvedSlug, ...basePlan };
+
+  if (dryRun) {
+    console.log('[dry run] push plan:');
+    console.log(`  code save:      ${plan.code_save}`);
+    console.log(`  code delete:    ${plan.code_delete}${includeDeletes ? '' : ' (pass --include-deletes to apply)'}`);
+    console.log(`  asset upload:   ${plan.asset_upload}`);
+    console.log(`  asset skip:     ${plan.asset_unchanged} unchanged${noAssets ? `, ${assetAll.length} lane-skipped (--no-assets)` : ''}`);
+    if (codeToSave.length) {
+      console.log('\n  files to save:');
+      for (const f of codeToSave.slice(0, 30)) console.log(`    M  ${f.path}`);
+      if (codeToSave.length > 30) console.log(`    ... and ${codeToSave.length - 30} more`);
+    }
+    if (assetToUpload.length) {
+      console.log('\n  assets to upload:');
+      for (const f of assetToUpload.slice(0, 20)) console.log(`    A  ${f.path}`);
+      if (assetToUpload.length > 20) console.log(`    ... and ${assetToUpload.length - 20} more`);
+    }
+    return { dryRun: true, plan };
+  }
+
+  if (codeToSave.length === 0 && codeToDelete.length === 0 && assetToUpload.length === 0) {
+    console.log('Nothing to push — local is in sync with the deploy source.');
+    if (deploy) return runDeployFor({ client, projectId, slug: resolvedSlug, environment: deploy, wait });
+    return { skipped: true, plan };
+  }
+
+  const failedPaths = [];
+  let codeSaved = 0;
+
+  // ── Code lane: batched, per-batch-verified bulk_save ──────────────────────
+  const BATCH_FILES = 40;
+  const BATCH_BYTES = 4_000_000; // well under the server's 20MB cap; sized for MCP-transport reliability
+  let batch = [];
+  let batchBytes = 0;
+  let batchNo = 0;
+  const flush = async () => {
+    if (batch.length === 0) return;
+    batchNo += 1;
+    const files = batch.map((f) => ({ path: f.path, content: f.content, encoding: f.encoding }));
+    const label = batch;
+    batch = [];
+    batchBytes = 0;
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      let r;
+      try {
+        r = (
+          await client.callToolJson('project_files_bulk_save', {
+            project_id: projectId,
+            files,
+            commit_message: commit || 'hiveku-sync: push local changes',
+          })
+        ).data;
+      } catch (e) {
+        if (attempt >= 2) failedPaths.push(...label.map((f) => f.path));
+        continue;
+      }
+      const succeeded = r?.summary?.succeeded ?? files.length;
+      codeSaved += succeeded;
+      if (succeeded === files.length) return;
+      const bad = (r?.results || []).filter((x) => x.ok === false).map((x) => x.path);
+      if (attempt >= 2) failedPaths.push(...(bad.length ? bad : label.map((f) => f.path)));
+    }
+  };
+  for (const f of codeToSave) {
+    if (batch.length >= BATCH_FILES || (batchBytes > 0 && batchBytes + f.content.length > BATCH_BYTES)) {
+      await flush();
+      console.log(`  code ${codeSaved}/${codeToSave.length}`);
+    }
+    batch.push(f);
+    batchBytes += f.content.length;
+  }
+  await flush();
+
+  // ── Asset lane: assets_upload, bounded concurrency, retry once ────────────
+  let assetDone = 0;
+  await runLimited(assetToUpload, 5, async (f) => {
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      try {
+        await client.callToolJson('assets_upload', {
+          project_id: projectId,
+          file_path: f.path,
+          content: f.content,
+        });
+        assetDone += 1;
+        if (assetDone % 10 === 0 || assetDone === assetToUpload.length) {
+          console.log(`  assets ${assetDone}/${assetToUpload.length}`);
+        }
+        return;
+      } catch (e) {
+        if (attempt >= 2) failedPaths.push(f.path);
+      }
+    }
+  });
+
+  // ── Deletions (code lane only) ────────────────────────────────────────────
+  let deleted = 0;
+  for (const p of codeToDelete) {
+    try {
+      await client.callToolJson('project_file_delete', { project_id: projectId, file_path: p });
+      deleted += 1;
+    } catch {
+      failedPaths.push(p);
+    }
+  }
+
+  console.log(
+    `Pushed: ${codeSaved} code file${codeSaved !== 1 ? 's' : ''}` +
+      `, ${assetDone} asset${assetDone !== 1 ? 's' : ''}` +
+      (deleted ? `, ${deleted} deletion${deleted !== 1 ? 's' : ''}` : '') +
+      (assetSkipped ? ` (${assetSkipped} asset${assetSkipped !== 1 ? 's' : ''} unchanged)` : ''),
+  );
+  if (failedPaths.length) {
+    console.log(`  ⚠ ${failedPaths.length} file(s) FAILED: ${failedPaths.slice(0, 10).join(', ')}${failedPaths.length > 10 ? '…' : ''}`);
+  }
+
+  // ── Optional: record a Hiveku-native main commit (version-history marker).
+  // Files are already saved via bulk_save; this snapshots the current state on
+  // `main` so `hiveku-sync` history shows the push. GitHub not required.
+  if (commit) {
+    try {
+      const c = (
+        await client.callToolJson('project_vcs_commit', {
+          project_id: projectId,
+          message: commit,
+          branch: branch || info.branch || undefined,
+          deletedFiles: codeToDelete.length ? codeToDelete : undefined,
+        })
+      ).data;
+      console.log(`  committed on ${c?.branch_name || branch || 'main'} (${c?.checkpoint_hash ? c.checkpoint_hash.slice(0, 12) : c?.id || 'recorded'})`);
+    } catch (e) {
+      console.log(`  ⚠ commit marker failed (files ARE saved): ${(e && e.message) || e}`);
+    }
+  }
+
+  // Update manifest timestamps.
+  const manifest = await readProjectsManifest(baseDir);
+  manifest.projects = manifest.projects || {};
+  manifest.projects[resolvedSlug] = {
+    ...(manifest.projects[resolvedSlug] || { project_id: projectId }),
+    last_push_at: new Date().toISOString(),
+  };
+  await writeProjectsManifest(baseDir, manifest);
+
+  const result = { plan, code_saved: codeSaved, assets_uploaded: assetDone, deleted, failed: failedPaths };
+  if (deploy) {
+    const d = await runDeployFor({ client, projectId, slug: resolvedSlug, environment: deploy, wait });
+    result.deploy = d;
+  }
+  return result;
+}
+
+// ── Deploy ──────────────────────────────────────────────────────────────────
+
+const DEPLOY_SUCCESS = new Set(['completed', 'ready', 'succeeded', 'success', 'deployed', 'live']);
+const DEPLOY_FAILURE = new Set(['failed', 'error', 'errored', 'cancelled', 'canceled', 'timed_out']);
+
+export function normalizeEnv(env) {
+  const e = String(env || 'development').toLowerCase();
+  if (e === 'preview' || e === 'dev-preview' || e === 'dev') return 'development';
+  if (e === 'prod') return 'production';
+  if (e === 'stage') return 'staging';
+  return e;
+}
+
+async function runDeployFor({ client, projectId, slug, environment, wait }) {
+  const env = normalizeEnv(environment);
+  if (!['development', 'staging', 'production'].includes(env)) {
+    throw new Error(`Invalid environment "${environment}" — use development | staging | production.`);
+  }
+  console.log(`Deploying ${slug} → ${env}…`);
+  const started = (
+    await client.callToolJson('deploy_site', { project_id: projectId, environment: env })
+  ).data;
+  const deploymentId = started?.deployment_id || started?.deploy_id || started?.id;
+  const startUrl = started?.url || started?.preview_url;
+  console.log(`  deployment_id: ${deploymentId || '(none returned)'}`);
+  if (startUrl) console.log(`  url: ${startUrl}`);
+
+  if (!wait) {
+    console.log('  (not waiting — pass --wait to poll to completion)');
+    return { deployment_id: deploymentId, environment: env, url: startUrl, waited: false };
+  }
+  if (!deploymentId) {
+    console.log('  ⚠ no deployment_id to poll — check deploy_status manually.');
+    return { environment: env, waited: false };
+  }
+
+  const POLL_MS = 8000;
+  const MAX_MS = env === 'production' ? 30 * 60 * 1000 : 15 * 60 * 1000;
+  const t0 = Date.now();
+  let last = '';
+  while (Date.now() - t0 < MAX_MS) {
+    await new Promise((r) => setTimeout(r, POLL_MS));
+    let dep;
+    try {
+      dep = (await client.callToolJson('deploy_get', { project_id: projectId, deployment_id: deploymentId })).data;
+    } catch {
+      continue; // transient — keep polling
+    }
+    const status = String(dep?.status || 'queued').toLowerCase();
+    if (status !== last) {
+      const secs = Math.round((Date.now() - t0) / 1000);
+      console.log(`  [${secs}s] ${status}`);
+      last = status;
+    }
+    if (DEPLOY_SUCCESS.has(status)) {
+      const url = dep?.url || dep?.preview_url || startUrl;
+      console.log(`  ✓ deployed: ${url || '(url pending)'}`);
+      return { deployment_id: deploymentId, environment: env, status, url, waited: true, ok: true };
+    }
+    if (DEPLOY_FAILURE.has(status)) {
+      console.log(`  ✗ deploy ${status}${dep?.error ? `: ${dep.error}` : ''}`);
+      if (dep?.build_logs) {
+        const tail = String(dep.build_logs).split('\n').slice(-15).join('\n');
+        console.log('  --- build log (tail) ---\n' + tail);
+      }
+      const err = new Error(`Deploy ${status}${dep?.error ? `: ${dep.error}` : ''}`);
+      err.deploy = { deployment_id: deploymentId, environment: env, status, error: dep?.error };
+      throw err;
+    }
+  }
+  console.log(`  ⚠ still ${last || 'pending'} after ${Math.round(MAX_MS / 60000)}min — check deploy_status.`);
+  return { deployment_id: deploymentId, environment: env, status: last, waited: true, ok: false };
+}
+
+export async function runDeploy({ slugOrId, environment, wait = false, profile }) {
+  if (!environment) throw new Error('Usage: hiveku-sync deploy <development|staging|production> [<slug>] [--wait]');
+  const baseDir = resolveBaseDir();
+  const { client } = await clientFromCwd({ profileOverride: profile });
+
+  // Resolve project: prefer the pulled-folder manifest (slug), else treat the
+  // arg as a slug/UUID via list_projects.
+  let projectId;
+  let slug = slugOrId;
+  try {
+    const { slug: s, info } = await findProjectFolder({ slug: slugOrId, baseDir });
+    projectId = info.project_id;
+    slug = s;
+  } catch {
+    if (!slugOrId) throw new Error('No project folder detected — pass a project slug or UUID: hiveku-sync deploy <env> <slug>');
+    const project = await resolveProject(client, slugOrId);
+    projectId = project.id;
+    slug = project.slug || project.name || project.id;
+  }
+  return runDeployFor({ client, projectId, slug, environment, wait });
+}
+
+// ── pull-env ──────────────────────────────────────────────────────────────
+
+// Resolution mirrors the preview machine (project_secrets_set): _DEV wins for
+// development and is stripped to its base key; _PROD/_PRODUCTION are for
+// production, _STAGING for staging. Suffixes for OTHER tiers are skipped.
+const TIER_SUFFIX = {
+  development: ['_DEV'],
+  staging: ['_STAGING'],
+  production: ['_PROD', '_PRODUCTION'],
+};
+const ALL_SUFFIXES = ['_DEV', '_STAGING', '_PROD', '_PRODUCTION'];
+
+export function resolveSecretsForTier(secrets, tier) {
+  const want = TIER_SUFFIX[tier] || TIER_SUFFIX.development;
+  const base = {};
+  const overrides = {};
+  for (const [key, value] of Object.entries(secrets || {})) {
+    const suffix = ALL_SUFFIXES.find((s) => key.endsWith(s));
+    if (!suffix) {
+      base[key] = value;
+      continue;
+    }
+    if (want.includes(suffix)) {
+      overrides[key.slice(0, -suffix.length)] = value; // strip suffix → base name
+    }
+    // suffix for another tier → skip
+  }
+  return { ...base, ...overrides }; // tier override wins over the base key
+}
+
+function envFileForTier(tier) {
+  if (tier === 'production') return '.env.production.local';
+  if (tier === 'staging') return '.env.staging.local';
+  return '.env.local';
+}
+
+export function serializeEnv(map) {
+  const lines = [
+    '# Generated by `hiveku-sync pull-env` from Hiveku project secrets.',
+    '# Do NOT commit — this file is git-ignored.',
+    '',
+  ];
+  for (const key of Object.keys(map).sort()) {
+    let v = String(map[key] ?? '');
+    // Quote if it contains whitespace, #, quotes, or newlines.
+    if (/[\s#'"\n]/.test(v)) {
+      v = `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
+    }
+    lines.push(`${key}=${v}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+export async function runPullEnv({ slug, profile, target = 'development' } = {}) {
+  const tier = normalizeEnv(target);
+  if (!['development', 'staging', 'production'].includes(tier)) {
+    throw new Error(`Invalid --target "${target}" — use development | staging | production.`);
+  }
+  const baseDir = resolveBaseDir();
+  const { client } = await clientFromCwd({ profileOverride: profile });
+  const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  const projectId = info.project_id;
+
+  const res = (await client.callToolJson('project_secrets_list', { project_id: projectId })).data;
+  const secrets = res?.secrets || {};
+  const count = Object.keys(secrets).length;
+  if (count === 0) {
+    console.log(`No secrets set on ${resolvedSlug}. Nothing to write.`);
+    return { written: 0 };
+  }
+
+  const resolved = resolveSecretsForTier(secrets, tier);
+  const outName = envFileForTier(tier);
+  const outPath = join(folder, outName);
+  await writeFileAtomic(outPath, serializeEnv(resolved));
+
+  // Make sure the env file is git-ignored so it never gets pushed.
+  const gitignorePath = join(folder, '.gitignore');
+  let ignore = '';
+  try {
+    ignore = await readFile(gitignorePath, 'utf8');
+  } catch {
+    /* no .gitignore yet */
+  }
+  if (!ignore.split('\n').some((l) => l.trim() === outName)) {
+    await writeFileAtomic(
+      gitignorePath,
+      (ignore && !ignore.endsWith('\n') ? ignore + '\n' : ignore) + outName + '\n',
+    );
+  }
+
+  console.log(`Wrote ${Object.keys(resolved).length} var${Object.keys(resolved).length !== 1 ? 's' : ''} → ${outName} (tier: ${tier}, from ${count} secret${count !== 1 ? 's' : ''}).`);
+  return { written: Object.keys(resolved).length, path: outPath, tier };
+}