@hiveku-apps/sync 0.5.3 → 0.5.5

package/README.md

@@ -130,8 +130,8 @@ Pass `--trust` to pre-trust the folder in `~/.codex/config.toml` (so Codex loads
 the repo config without its first-run trust prompt).
 
 **Approvals.** Codex asks first only for a **fixed list** of high-risk Hiveku
-tools: the 246 names in `src/codex-prompt-tools.json`, the same list as the
-Hiveku Codex plugin 0.1.16. It includes `deploy_site`, `site_delete`,
+tools: the 278 names in `src/codex-prompt-tools.json`, the same list as the
+Hiveku Codex plugin 0.3.13. It includes `deploy_site`, `site_delete`,
 `project_files_bulk_save` and every `hiveku_batch`, and it is written as
 `[mcp_servers.hiveku.tools.<tool>] approval_mode = "prompt"`. **Every other tool
 on the `hiveku` server runs without asking** (`default_tools_approval_mode =
@@ -160,6 +160,15 @@ The folder has to carry the list itself: Codex uses the folder's
 `[mcp_servers.hiveku]` instead of the plugin's, including for approvals, so the
 plugin's prompts do not apply here.
 
+**Revealing values.** Because `project_secrets_reveal` and `hiveku_batch` ask
+first here, the block also sends the header `X-Hiveku-Client =
+"hiveku-sync/<version>"`: the declaration that this folder asks a person before
+a reveal. Hiveku then lets a reveal through after your Codex prompt instead of
+also asking for a dashboard approval (a reveal inside `hiveku_batch` still gets
+the dashboard approval). When your own table for either of those two tools wins
+over the block, the block sends the plain `codex` label instead, and every
+reveal takes the dashboard approval.
+
 Headless and bypass modes:
 
 - **`codex exec` never stops to ask.** Under a `read-only` or `workspace-write`
@@ -253,7 +262,7 @@ Your site, unless the tier is bound to the branch.
 
 ```bash
 hiveku-sync deploy <development|staging|production> [<slug>] [--wait]
-hiveku-sync pull-env [<slug>] [--target development|staging|production]
+hiveku-sync pull-env [<slug>] [--target development|staging|production] [--yes] [--no-wait] [--approval-token <token>]
 ```
 
 ## Versions
@@ -295,9 +304,16 @@ their own version first, and never publishes: run `hiveku-sync deploy` after
 it when the live site should match. Images, fonts and videos in the shared
 asset store, the database, CMS entries and secrets are not part of versions.
 
-`pull-env` applies the same `_DEV` / `_PROD` / `_STAGING` suffix resolution the
-preview machine uses: for `development` it strips `_DEV` to the base key and
-skips `_PROD`/`_STAGING`; `--target production` does the inverse.
+`pull-env` writes the values one tier runs with, through
+`project_secrets_reveal`, as Hiveku resolves them (`FOO_PROD` over `FOO` for
+production, `FOO_DEV` for development). A person approves every pull: it prints
+the approval link, then waits up to 10 minutes, asking again every 5 seconds
+(`--no-wait` stops after the link, and `--approval-token <token>` resumes the
+wait). Development goes to `.env.local`; `--target staging` to
+`.env.staging.local`; `--target production` to `.env.production.local`, and only
+with `--yes`. The file is mode 0600, git-ignored, and written only when a value
+came back. Sensitive (write-only) variables and platform credentials never come
+back; their names are listed in the file as comments with the reason.
 
 ## Safety
 

package/bin/hiveku-sync.mjs

@@ -40,6 +40,7 @@ export function parseFlags(argv) {
     'confirm',
     'fingerprint',
     'limit',
+    'approval-token',
   ]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -130,10 +131,14 @@ Ship a project (the agent-native deploy loop):
                                       and version ARE saved, the deploy failed.
   deploy <env> [<slug>] [--wait]    Deploy to development | staging | production and
                                     (with --wait) poll to a terminal status.
-  pull-env [<slug>]                 Write project secrets → .env.local (git-ignored),
-           [--target <env>]           with the same _DEV/_PROD/_STAGING resolution the
-                                      preview uses. --target staging|production for the
-                                      other tiers.
+  pull-env [<slug>]                 Write one tier's values → .env.local (git-ignored,
+           [--target <env>] [--yes]   mode 0600, values never printed) through the
+           [--approval-token <t>]     reveal: a person approves on the link it prints,
+           [--no-wait]                and it waits up to 10 minutes. --target staging
+                                      writes .env.staging.local; --target production
+                                      writes .env.production.local and needs --yes.
+                                      --no-wait stops after the link (exit 3);
+                                      --approval-token resumes that wait.
 
 Versions (Your site = the project's main source; rollback never publishes):
   commit [<slug>] [-m "<name>"]     Save what is on Hiveku and not yet in a version as
@@ -401,11 +406,16 @@ async function main() {
       break;
     }
     case 'pull-env': {
-      await runPullEnv({
-        slug: positional[0],
-        profile: flags['profile'],
-        target: typeof flags['target'] === 'string' ? flags['target'] : 'development',
-      });
+      setExitCode(
+        await runPullEnv({
+          slug: positional[0],
+          profile: flags['profile'],
+          target: typeof flags['target'] === 'string' ? flags['target'] : 'development',
+          yes: flags['yes'] === true,
+          approvalToken: typeof flags['approval-token'] === 'string' ? flags['approval-token'] : undefined,
+          wait: flags['no-wait'] !== true,
+        }),
+      );
       break;
     }
     case 'commit': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder, and ship projects (push/deploy/pull-env) from the terminal. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
   "type": "module",
   "license": "MIT",

package/src/codex-prompt-tools.json

@@ -1,5 +1,5 @@
 {
-  "source": "locus2012/hiveku-codex-plugin main (af0fd36, 0.3.8), plugins/hiveku/.mcp.json: every hiveku.tools entry with approval_mode \"prompt\" (project_vcs_rollback included)",
+  "source": "locus2012/hiveku-codex-plugin feature/secrets-b3-declare-client (4f9d569, 0.3.14), plugins/hiveku/.mcp.json: every hiveku.tools entry with approval_mode \"prompt\" (project_vcs_rollback included)",
   "why": "hiveku-sync writes its own [mcp_servers.hiveku] into a Codex folder. Codex then uses that entry, not the plugin's, for the server's connection and for every tool's approval mode, so these prompts must be written here too. Refresh this list whenever the Codex plugin's prompt list changes.",
   "tools": [
     "deploy_site",
@@ -19,6 +19,16 @@
     "project_vcs_resolve",
     "project_vcs_pr_update",
     "project_vcs_queue_add",
+    "project_secrets_set",
+    "project_secrets_delete",
+    "project_secrets_apply_to_preview",
+    "project_secrets_reveal",
+    "project_secrets_replace",
+    "project_secrets_mark_sensitive",
+    "project_ab_test_create",
+    "project_ab_test_update",
+    "project_ab_test_action",
+    "project_ab_test_delete",
     "hiveku_batch",
     "project_checkpoint_restore",
     "checkpoint_restore",

package/src/codex.mjs

@@ -95,6 +95,35 @@ export const CODEX_PROMPT_TOOLS = [
   ...new Set(JSON.parse(readFileSync(new URL('./codex-prompt-tools.json', import.meta.url), 'utf8')).tools),
 ];
 
+/** This package's version, as published (package.json ships in every npm package). */
+export const SYNC_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/**
+ * X-Hiveku-Client for the folder's [mcp_servers.hiveku]: `hiveku-sync/<version>`,
+ * the declaration that this config asks a person before project_secrets_reveal
+ * (plan "Server-side approval"; the builder's src/lib/secrets/reveal-client.ts).
+ * The MCP server forwards it to the builder, which lets a release at or above
+ * its listed minimum skip the dashboard approval for a reveal Codex prompted
+ * for. Set here, never by the model.
+ *
+ * True only while the block itself writes the prompt for the reveal and for
+ * hiveku_batch (which can carry a reveal): when the folder's own config
+ * declares either table, the user's setting wins (userTables) and may not ask,
+ * so the block sends the plain `codex` label instead. The MCP server reads
+ * both as Codex for its memory-log label and rate-limit bucket. The CLI's own
+ * calls (pull-env included) send no X-Hiveku-Client at all, so a reveal they
+ * make takes the dashboard approval.
+ */
+export const DECLARED_CLIENT = `hiveku-sync/${SYNC_VERSION}`;
+const DECLARATION_NEEDS_PROMPTS = ['project_secrets_reveal', 'hiveku_batch'];
+
+/** The X-Hiveku-Client value for a block that leaves out the user's own tables. */
+export function codexClientHeader(userTables = []) {
+  const skip = new Set(userTables);
+  const asks = DECLARATION_NEEDS_PROMPTS.every((tool) => CODEX_PROMPT_TOOLS.includes(tool) && !skip.has(tool));
+  return asks ? DECLARED_CLIENT : 'codex';
+}
+
 /** A TOML bare key when the name allows it, a quoted key otherwise. */
 function tomlKey(name) {
   return /^[A-Za-z0-9_-]+$/.test(name) ? name : JSON.stringify(name);
@@ -309,14 +338,16 @@ function codexTomlRegion({ baseUrl, profile, apiKey, userTables = [] }) {
   // MCP server (Codex config reference, "mcp_servers.<id>.http_headers"; the
   // docs' example is `http_headers = { "X-Figma-Region" = "us-east-1" }`, next
   // to bearer_token_env_var). TOML allows the key once per table, so the
-  // client label rides in the same inline table as an inlined key.
-  // X-Hiveku-Client: codex is what the MCP server's memory log shows as
-  // "via Codex"; it is a label, never authentication. The key and the URL come
-  // from .env, so they are escaped: a quote in either would otherwise end the
-  // string early and leave the block itself unreadable.
+  // client header rides in the same inline table as an inlined key.
+  // X-Hiveku-Client is hiveku-sync/<version> (codexClientHeader): the
+  // declaration that this block asks before a reveal, which the MCP server's
+  // memory log still shows as "via Codex"; it is never authentication. The key
+  // and the URL come from .env, so they are escaped: a quote in either would
+  // otherwise end the string early and leave the block itself unreadable.
+  const client = tomlString(codexClientHeader(userTables));
   const auth = apiKey
-    ? `http_headers = { "Authorization" = ${tomlString(`Bearer ${apiKey}`)}, "X-Hiveku-Client" = "codex" }`
-    : `bearer_token_env_var = "OLYMPUS_API_KEY"\nhttp_headers = { "X-Hiveku-Client" = "codex" }`;
+    ? `http_headers = { "Authorization" = ${tomlString(`Bearer ${apiKey}`)}, "X-Hiveku-Client" = ${client} }`
+    : `bearer_token_env_var = "OLYMPUS_API_KEY"\nhttp_headers = { "X-Hiveku-Client" = ${client} }`;
   // default_tools_approval_mode = "approve": this folder exists so the agent
   // can operate the account — per-call approval prompts would also cancel
   // every tool call in headless `codex exec` (CI/cron, this lane's core use)

package/src/envPull.mjs

@@ -0,0 +1,311 @@
+/**
+ * `hiveku-sync pull-env`: one tier of a project's variables into a local env
+ * file, through project_secrets_reveal (plan B3), never project_secrets_list.
+ *
+ * The same flow and file rules as the Claude Code plugin's `hiveku env pull`
+ * (hiveku-claude-plugin lib/env-pull.mjs): keep the two in step.
+ *
+ * WHY THE REVEAL. Agents read secret values only for non-sensitive keys,
+ * through a reveal that asks every time and is logged (Abe, 2026-10-06).
+ * project_secrets_list stops returning values at the cutover (it answers
+ * values_moved without metadata_only); the reveal returns the values the tier
+ * runs with, resolved by the server (FOO_PROD over FOO, the deploy's own
+ * precedence), never a sensitive key and never a platform credential.
+ *
+ * WHO APPROVES. This CLI's own MCP client sends no X-Hiveku-Client, so it does
+ * not declare that it asked anyone (the Codex config this package writes does,
+ * codex.mjs DECLARED_CLIENT, because Codex prompts there). Every pull takes
+ * the dashboard approval: the CLI prints the approval link, then repeats the
+ * same call with the token every 5 seconds for up to 10 minutes. A poll while
+ * nobody has decided does not spend the project's reveals.
+ *
+ * THE FILE: written only when a value came back (an empty answer never
+ * replaces an existing file); mode 0600 even over an existing file; values
+ * encoded so dotenv + dotenv-expand (Next.js, Vite, Expo) read them back
+ * exactly; withheld names as one-line comments with their reasons. Only names
+ * reach the terminal.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const REVEAL_TOOL = 'project_secrets_reveal';
+
+/** How often the CLI asks again while a person decides, and for how long. */
+export const APPROVAL_POLL_MS = 5_000;
+export const APPROVAL_WAIT_MS = 10 * 60_000;
+/** Polls that fail in a row (network, 5xx) before the wait gives up. */
+const MAX_POLL_FAILURES = 3;
+
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TOKEN_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export class EnvPullError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'EnvPullError';
+    this.code = code;
+  }
+}
+
+/** Which file a tier's values go to (Next.js loads .env.production.local only for production builds). */
+export function envFileForTier(tier) {
+  if (tier === 'production') return '.env.production.local';
+  if (tier === 'staging') return '.env.staging.local';
+  return '.env.local';
+}
+
+/** An approval token from the command line: refused unless it has the token's shape. */
+export function approvalTokenFrom(raw) {
+  if (raw === undefined) return undefined;
+  const token = String(raw).trim();
+  if (!TOKEN_RE.test(token)) throw new EnvPullError('bad_token', 'That is not an approval token. Use the token the first run printed.');
+  return token;
+}
+
+/** One line of server text for a comment or the terminal: no line breaks or control characters. */
+function oneLine(text, max = 300) {
+  return String(text ?? '')
+    .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+
+/**
+ * What one tools/call of project_secrets_reveal answered:
+ *   { kind: 'values', values, withheld, notApproved, tier }
+ *   { kind: 'approval_required', approval, withheld }
+ *   { kind: 'pending' }
+ *   { kind: 'refused', code, message }
+ * The MCP proxy returns a builder error as a tool result
+ * { error, status, details: { code, message } }, with isError set.
+ */
+export function readRevealAnswer(res) {
+  if (res?.error) {
+    return { kind: 'refused', code: 'rpc_error', message: oneLine(res.error.message || 'The Hiveku server refused the call.') };
+  }
+  const text = res?.result?.content?.[0]?.text;
+  let body = null;
+  try {
+    body = typeof text === 'string' ? JSON.parse(text) : null;
+  } catch {
+    body = null;
+  }
+  body = asObject(body);
+  if (!body) return { kind: 'refused', code: 'unreadable_answer', message: 'The reveal answered with something that is not JSON.' };
+
+  const failed = res?.result?.isError === true || (typeof body.error === 'string' && typeof body.status === 'number' && body.status >= 400);
+  if (failed) {
+    const details = asObject(body.details) ?? body;
+    const code = String(details.code || body.code || details.error || body.error || 'refused');
+    if (code === 'approval_pending') return { kind: 'pending' };
+    return { kind: 'refused', code, message: oneLine(details.message || body.message || body.error || 'The reveal was refused.') };
+  }
+
+  const data = asObject(body.data) && !('values' in body) && !('code' in body) ? body.data : body;
+  const withheld = Array.isArray(data.withheld) ? data.withheld.filter((w) => asObject(w) && typeof w.key === 'string') : [];
+  if (data.code === 'approval_required') {
+    const approval = asObject(data.approval);
+    // The link and the token are printed for the person, so both must be plain: an https link with
+    // no spaces or control characters, and a token of the token's own shape.
+    if (!approval || !TOKEN_RE.test(String(approval.token)) || !/^https:\/\/[^\s\u0000-\u001f\u007f]+$/.test(String(approval.approve_url))) {
+      return { kind: 'refused', code: 'unexpected_answer', message: 'The reveal asked for an approval without a usable link.' };
+    }
+    return { kind: 'approval_required', approval, withheld };
+  }
+  const values = asObject(data.values);
+  if (values) {
+    const clean = {};
+    for (const [key, value] of Object.entries(values)) if (typeof value === 'string') clean[key] = value;
+    const notApproved = Array.isArray(data.not_approved) ? data.not_approved.filter((k) => typeof k === 'string') : [];
+    return { kind: 'values', values: clean, withheld, notApproved, tier: data.tier };
+  }
+  return { kind: 'refused', code: 'unexpected_answer', message: 'The reveal answered in a shape this version does not read. Update hiveku-sync.' };
+}
+
+/** A refusal as one sentence for the terminal. */
+function refusalText(answer) {
+  const byCode = {
+    approval_declined: 'A person declined the request. Nothing was written.',
+    approval_used: 'That approval was already used. Run pull-env again to ask once more.',
+    approval_unknown: 'That approval is unknown or its 10 minutes ran out. Run pull-env again to ask once more.',
+    approval_mismatch: 'That approval was for another tier or another key. Run pull-env again without --approval-token.',
+    reveal_rate_limited: 'This site\'s values were revealed 20 times in the last hour, the most allowed. Try again later.',
+    reveal_requests_rate_limited: '20 approvals were asked for this site in the last hour, the most allowed. Try again later.',
+    scope_denied: 'This folder\'s key is read-only, and revealing values needs a full key.',
+  };
+  return byCode[answer.code] || `${answer.message || 'The reveal was refused.'} (${answer.code})`;
+}
+
+/**
+ * Reveal one tier's values, waiting for a person's approval when the server
+ * asks for one. `call(args)` sends one project_secrets_reveal and returns the
+ * JSON-RPC answer. With `approvalToken` it resumes a wait a first run started
+ * (no new request is made). `onApprovalRequired(approval)` is told the link
+ * once, before the wait; with `wait: false` the pull stops there and throws
+ * approval_waiting (the token is in the error's `approval`).
+ */
+export async function revealTier({
+  call,
+  projectId,
+  tier,
+  approvalToken,
+  wait = true,
+  onApprovalRequired,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now = () => Date.now(),
+  pollMs = APPROVAL_POLL_MS,
+  waitMs = APPROVAL_WAIT_MS,
+}) {
+  const args = { project_id: projectId, tier };
+  let answer;
+  let token = approvalToken;
+  if (token) {
+    answer = readRevealAnswer(await call({ ...args, approval_token: token }));
+  } else {
+    answer = readRevealAnswer(await call(args));
+    if (answer.kind === 'approval_required') {
+      token = answer.approval.token;
+      await onApprovalRequired?.(answer.approval, answer.withheld);
+      if (!wait) {
+        const err = new EnvPullError('approval_waiting', 'Waiting for a person to approve. Run pull-env again with --approval-token once they have.');
+        err.approval = answer.approval;
+        throw err;
+      }
+      answer = { kind: 'pending' };
+    }
+  }
+  if (answer.kind === 'pending') {
+    // Only a call that carries a token can be pending; without one, a repeat would
+    // ask a person again on every poll.
+    if (!token) throw new EnvPullError('unexpected_answer', 'The reveal said it is waiting for an approval it never asked for. Pull again.');
+    const deadline = now() + waitMs;
+    let failures = 0;
+    while (answer.kind === 'pending') {
+      if (now() >= deadline) {
+        throw new EnvPullError('approval_timeout', 'Nobody approved within 10 minutes, so nothing was written. Run pull-env again to ask once more.');
+      }
+      await sleep(pollMs);
+      try {
+        answer = readRevealAnswer(await call({ ...args, approval_token: token }));
+        failures = 0;
+      } catch (err) {
+        failures += 1;
+        if (failures >= MAX_POLL_FAILURES) throw err;
+        answer = { kind: 'pending' };
+      }
+    }
+  }
+  if (answer.kind === 'values') return answer;
+  if (answer.kind === 'approval_required') {
+    throw new EnvPullError('unexpected_answer', 'The reveal asked for a new approval in the middle of a wait. Run pull-env again.');
+  }
+  throw new EnvPullError(answer.code || 'refused', refusalText(answer));
+}
+
+/**
+ * A value in the form the dotenv loaders read back exactly (dotenv parse plus
+ * dotenv-expand, as Next.js 15, Vite and Expo load .env files), or null when
+ * no form does:
+ *   - nothing to quote or expand: written bare;
+ *   - otherwise in single quotes, which dotenv keeps literally (line breaks
+ *     included), with every `$` written `\$` so it is not expanded into
+ *     another variable;
+ *   - a value with a single quote goes in backticks the same way;
+ *   - null for a value with both, with a carriage return or NUL (dotenv turns
+ *     CR into LF), or ending in a backslash (dotenv reads `\'` as a quote
+ *     inside the value and runs on to the next line).
+ */
+export function encodeEnvValue(value) {
+  const v = String(value);
+  if (v === '') return '';
+  if (/[\r\0]/.test(v) || v.endsWith('\\')) return null;
+  if (/^[A-Za-z0-9_\-.,:/@+%~^=]+$/.test(v)) return v;
+  const escaped = v.replace(/\$/g, '\\$');
+  if (!v.includes("'")) return `'${escaped}'`;
+  if (!v.includes('`')) return `\`${escaped}\``;
+  return null;
+}
+
+/**
+ * The env file's text: the values, sorted, then what was not included and
+ * why, as comments. Returns the names written and the names left out.
+ */
+export function renderEnvFile({ values, withheld = [], notApproved = [], tier, file }) {
+  const written = [];
+  const unwritable = [];
+  const lines = [
+    `# Written by \`hiveku-sync pull-env\` from Hiveku: this site's ${tier} values, revealed with a person's approval.`,
+    `# ${file} holds real values: keep it out of git and never paste it anywhere.`,
+  ];
+  for (const key of Object.keys(values).sort()) {
+    if (!KEY_RE.test(key)) {
+      unwritable.push({ key: oneLine(key, 80), why: 'not a variable name a .env file can hold' });
+      continue;
+    }
+    const encoded = encodeEnvValue(values[key]);
+    if (encoded === null) {
+      unwritable.push({ key, why: 'its value cannot be written to a .env file exactly (set it by hand)' });
+      continue;
+    }
+    lines.push(`${key}=${encoded}`);
+    written.push(key);
+  }
+  const notes = [
+    ...withheld.map((w) => ({ key: oneLine(w.key, 80), why: oneLine(w.why || w.reason || 'withheld') })),
+    ...notApproved.map((key) => ({ key: oneLine(key, 80), why: 'added after the person approved; pull again to include it' })),
+    ...unwritable,
+  ];
+  if (notes.length) {
+    lines.push('', '# Not included (their values are never shown; set them by hand if local dev needs them):');
+    for (const note of notes) lines.push(`# ${note.key}: ${note.why}`);
+  }
+  lines.push('');
+  return { text: lines.join('\n'), written, notes };
+}
+
+/**
+ * Write `text` to `target` with mode 0600, also over an existing file: a new
+ * file is created 0600 beside it and renamed over it.
+ */
+export async function writeEnvFileSecure(target, text) {
+  const dir = path.dirname(target);
+  const temp = path.join(dir, `.${path.basename(target)}.${randomUUID()}.tmp`);
+  const handle = await fs.open(temp, 'wx', 0o600);
+  try {
+    await handle.writeFile(text, 'utf8');
+    await handle.chmod(0o600);
+  } finally {
+    await handle.close();
+  }
+  try {
+    await fs.rename(temp, target);
+  } catch (err) {
+    await fs.unlink(temp).catch(() => {});
+    throw err;
+  }
+}
+
+/** Add `file` to the folder's .gitignore unless a line there already covers it. */
+export async function ensureGitignored(dir, file) {
+  const gi = path.join(dir, '.gitignore');
+  let text = '';
+  try {
+    text = await fs.readFile(gi, 'utf8');
+  } catch {
+    /* no .gitignore yet */
+  }
+  const covered = text.split(/\r?\n/).some((line) => {
+    const rule = line.trim();
+    return rule === file || rule === `/${file}` || rule === '.env*' || rule === '*.local' || rule === '.env*.local';
+  });
+  if (covered) return false;
+  const prefix = text && !text.endsWith('\n') ? '\n' : '';
+  await fs.writeFile(gi, `${text}${prefix}${file}\n`, 'utf8');
+  return true;
+}

package/src/mcp.mjs

@@ -68,6 +68,16 @@ export class HivekuMcpClient {
     return result;
   }
 
+  /**
+   * The tools/call result as it came, a tool error (isError) included, for a
+   * caller that reads the error's code itself: pull-env waits on
+   * approval_pending, which arrives as a tool error. A JSON-RPC error or an
+   * HTTP failure still throws.
+   */
+  async callToolResult(name, args = {}) {
+    return this._request('tools/call', { name, arguments: args });
+  }
+
   async callTool(name, args = {}) {
     const result = await this._request('tools/call', { name, arguments: args });
     if (result?.isError) {

package/src/push.mjs

@@ -10,8 +10,9 @@
  *             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.
+ *   pull-env  project_secrets_reveal → .env.local (or .env.staging.local /
+ *             .env.production.local): the values the tier runs with, after a
+ *             person approves (src/envPull.mjs).
  *
  * After a push whose files all landed, push saves them as ONE version of Your
  * site (or of the branch it pushed to): project_vcs_commit with NO files and
@@ -41,7 +42,16 @@ import {
   readProjectsManifest,
   writeProjectsManifest,
 } from './projects.mjs';
-import { writeFileAtomic, readEnv, loadDotenv } from './util.mjs';
+import {
+  EnvPullError,
+  REVEAL_TOOL,
+  approvalTokenFrom,
+  ensureGitignored,
+  envFileForTier,
+  renderEnvFile,
+  revealTier,
+  writeEnvFileSecure,
+} from './envPull.mjs';
 import {
   branchLabel,
   checkedVersionName,
@@ -674,106 +684,82 @@ export async function runDeploy({ slugOrId, environment, wait = false, profile,
 
 // ── 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' } = {}) {
+/**
+ * `hiveku-sync pull-env [<slug>] [--target <tier>] [--yes]`: one tier's values
+ * into a local env file, through project_secrets_reveal (src/envPull.mjs),
+ * never project_secrets_list. The server resolves the tier (FOO_PROD over FOO,
+ * the dev/staging fallback), so nothing is resolved here.
+ *
+ *   - development is the default; staging needs --target staging, and
+ *     production needs --target production AND --yes;
+ *   - a person approves on the link it prints, and it waits up to 10 minutes
+ *     (--no-wait prints the link and stops with exit 3; --approval-token
+ *     resumes that wait without asking again);
+ *   - the file is written only when a value came back, mode 0600 even over an
+ *     existing file, with the withheld names as comments; only names are
+ *     printed.
+ *
+ * Returns { written, notIncluded, path, tier }, or { exit_code } when it
+ * stopped before writing.
+ */
+export async function runPullEnv({ slug, profile, target = 'development', yes = false, approvalToken, wait = true, client: givenClient, log = console.log } = {}) {
   const tier = normalizeEnv(target);
   if (!['development', 'staging', 'production'].includes(tier)) {
     throw new Error(`Invalid --target "${target}" — use development | staging | production.`);
   }
+  if (tier === 'production' && yes !== true) {
+    throw new Error(
+      'pull-env --target production writes the values production runs with to .env.production.local. ' +
+        'Add --yes to confirm that is what you want.',
+    );
+  }
+  const token = approvalTokenFrom(approvalToken);
   const baseDir = resolveBaseDir();
-  const { client } = await clientFromCwd({ profileOverride: profile });
-  const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  const client = givenClient ?? (await clientFromCwd({ profileOverride: profile })).client;
+  const { slug: resolvedSlug, folder, info } = await findProjectFolder({ slug, baseDir });
   const projectId = info.project_id;
+  const file = envFileForTier(tier);
 
-  const res = (await client.callToolJson('project_secrets_list', { project_id: projectId })).data;
-  const secrets = res?.secrets || {};
-  // Variables marked sensitive are write-only on the platform: the server OMITS them
-  // from `secrets` and lists their names here. Without saying so, the .env file below
-  // would be silently incomplete and the user would go debugging a phantom.
-  const sensitiveKeys = Array.isArray(res?.sensitive_keys) ? res.sensitive_keys : [];
-  const count = Object.keys(secrets).length;
-  if (count === 0 && sensitiveKeys.length === 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 = '';
+  const call = async (args) => ({ result: await client.callToolResult(REVEAL_TOOL, args) });
+  let answer;
   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',
-    );
+    answer = await revealTier({
+      call,
+      projectId,
+      tier,
+      approvalToken: token,
+      wait,
+      onApprovalRequired: (approval) => {
+        log(`A person must approve revealing ${resolvedSlug}'s ${tier} values before ${file} is written.`);
+        log(`Approve here (anyone in the account who can see the site's variables): ${approval.approve_url}`);
+        log(
+          wait
+            ? 'Waiting up to 10 minutes for the approval...'
+            : `Then run: hiveku-sync pull-env ${resolvedSlug} --target ${tier}${tier === 'production' ? ' --yes' : ''} --approval-token ${approval.token}`,
+        );
+      },
+    });
+  } catch (err) {
+    if (err instanceof EnvPullError && err.code === 'approval_waiting') {
+      log(err.message);
+      return { written: 0, exit_code: 3, tier };
+    }
+    throw err;
   }
 
-  console.log(`Wrote ${Object.keys(resolved).length} var${Object.keys(resolved).length !== 1 ? 's' : ''} → ${outName} (tier: ${tier}, from ${count} secret${count !== 1 ? 's' : ''}).`);
-  if (sensitiveKeys.length > 0) {
-    const names = sensitiveKeys.slice().sort();
-    console.log(
-      `Skipped ${names.length} sensitive var${names.length !== 1 ? 's' : ''}: ${names.join(', ')}.`,
-    );
-    console.log('These are write-only on Hiveku and cannot be read back. Set them by hand if your local build needs them.');
+  const { text, written, notes } = renderEnvFile({ values: answer.values, withheld: answer.withheld, notApproved: answer.notApproved, tier, file });
+  const notIncluded = notes.map((n) => `${n.key} (${n.why})`);
+  if (written.length === 0) {
+    // Never an empty file over a real one (the list-based pull did exactly that).
+    log(`No ${tier} value could be revealed for ${resolvedSlug}, so ${file} was left as it was.`);
+    if (notIncluded.length) log(`Not revealed: ${notIncluded.join('; ')}`);
+    return { written: 0, notIncluded: notes.map((n) => n.key), exit_code: 1, tier };
   }
-  return { written: Object.keys(resolved).length, skippedSensitive: sensitiveKeys, path: outPath, tier };
+  const outPath = join(folder, file);
+  await writeEnvFileSecure(outPath, text);
+  // Make sure the env file is git-ignored so it never gets pushed.
+  await ensureGitignored(folder, file);
+  log(`Wrote ${written.length} ${tier} value${written.length === 1 ? '' : 's'} → ${file} (mode 0600; values not shown): ${written.join(', ')}`);
+  if (notIncluded.length) log(`Not included (set by hand if needed): ${notIncluded.join('; ')}`);
+  return { written: written.length, notIncluded: notes.map((n) => n.key), path: outPath, tier };
 }