@hiveku-apps/sync 0.1.0 → 0.2.0

package/README.md

@@ -78,6 +78,53 @@ narrowed tool list. Available: `full`, `sales`, `marketing`, `helpdesk`,
 `pm`, `dev`. Change `HIVEKU_PROFILE` in `.env` and reload the MCP server
 in your editor to switch.
 
+## Coder projects — pull, ship, deploy
+
+Beyond memory/rules/skills, `hiveku-sync` can drive a Hiveku **website project**
+end-to-end from the terminal — the same push/deploy loop the VS Code extension's
+Source Control gives you, but headless (Claude Code in a terminal, CI, a cron).
+
+```bash
+hiveku-sync projects                    # list the account's coder projects
+hiveku-sync pull-project <slug-or-id>   # → ./projects/<slug>/  (+ .hiveku/projects.json)
+
+cd projects/<slug>
+hiveku-sync pull-env                    # secrets → .env.local (git-ignored)
+# ...edit files, run the dev server...
+hiveku-sync status                      # diff local vs the deploy source
+hiveku-sync push                        # save changes to the deploy source
+hiveku-sync push --deploy development --wait   # ...then deploy and wait
+```
+
+**`push` writes the deploy source, lane-routed.** This is the important part.
+`deploy_site` builds from `builder_code_versions` (+ the S3/CDN asset store) —
+**not** a GitHub branch. So `push`:
+
+- routes **CDN-servable binary** (images/fonts/video under `public/<subdir>/`)
+  to `assets_upload` (S3 → CloudFront). A binary put in `builder_code_versions`
+  renders in the Fly preview but **vanishes on deploy** (the build excludes it) —
+  `push` never makes that mistake.
+- routes everything else (code, config, text-under-public) to
+  `project_files_bulk_save` in small, per-batch-verified batches (transport-safe
+  vs one giant call).
+- diffs correctly: code via a single `project_files_status` call (so
+  `only_remote` stays reliable — chunking it produces phantom deletions), assets
+  via `assets_list` (so unchanged images aren't re-uploaded every push).
+
+Flags: `--include-deletes` (remove code paths missing locally), `--no-assets` /
+`--assets-all`, `--commit "msg"` (also record a Hiveku-native `main` commit),
+`--deploy <env> [--wait]`, `--dry-run`.
+
+```bash
+hiveku-sync deploy <development|staging|production> [<slug>] [--wait]
+hiveku-sync pull-env [<slug>] [--target development|staging|production]
+hiveku-sync commit -m "msg"   # legacy GitHub-branch commit (GitHub-connected projects only)
+```
+
+`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.
+
 ## Safety
 
 - **Manifest pin** — `.hiveku/manifest.json` records the API key preview.
@@ -91,7 +138,7 @@ in your editor to switch.
 
 ## How writes work
 
-`hiveku-sync` is pull-only. To persist changes back to Olympus, call the
-`memory_create` / `memory_update` / `memory_delete` MCP tools through
-Claude (or whichever LLM you've wired up). Then `hiveku-sync pull` to
-refresh the local copies.
+For **projects**, `hiveku-sync push` / `deploy` write straight back to Hiveku
+(see "Coder projects" above). For **memory/rules/skills**, `pull` is read-only —
+persist changes with the `memory_create` / `memory_update` / `memory_delete` MCP
+tools through Claude, then `hiveku-sync pull` to refresh the local copies.

package/bin/hiveku-sync.mjs

@@ -16,20 +16,39 @@ import {
   runProjectStatus,
   runProjectPush,
 } from '../src/projects.mjs';
+import { runPush, runDeploy, runPullEnv } from '../src/push.mjs';
+import { pathToFileURL } from 'node:url';
 
-function parseFlags(argv) {
+export function parseFlags(argv) {
   const positional = [];
   const flags = {};
-  // Short flags that take a value (next arg is the value, not a new flag).
+  // Short flags that take the NEXT arg as their value.
   const VALUE_SHORT = new Set(['m']);
+  // Long flags that take the next arg as their value when not given with `=`.
+  const VALUE_LONG = new Set([
+    'message',
+    'commit',
+    'deploy',
+    'target',
+    'branch',
+    'profile',
+    'parent',
+  ]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg.startsWith('--')) {
       const eq = arg.indexOf('=');
-      if (eq === -1) {
-        flags[arg.slice(2)] = true;
-      } else {
+      if (eq !== -1) {
         flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      } else {
+        const key = arg.slice(2);
+        const nextIsValue = i + 1 < argv.length && !argv[i + 1].startsWith('-');
+        if (VALUE_LONG.has(key) && nextIsValue) {
+          flags[key] = argv[i + 1];
+          i += 1;
+        } else {
+          flags[key] = true;
+        }
       }
     } else if (arg.startsWith('-') && arg.length > 1) {
       const key = arg.slice(1);
@@ -59,18 +78,44 @@ Coder projects:
   projects                          List the account's coder projects.
   pull-project <slug-or-id>         Pull a project's source into ./projects/<slug>/.
                   [--branch=<name>] Records the project mapping in .hiveku/projects.json.
-  status [<slug>] [--json]          Diff local ./projects/<slug>/ vs Hiveku DB.
-                                    cd into the project folder to omit <slug>.
-  push  [<slug>] -m "<message>"     Save+commit changed files to the project's
-                  [--branch=<name>] GitHub branch via MCP (same path as the v3
-                  [--include-deletes] sidebar). Add --include-deletes to commit
-                  [--dry-run]       paths missing locally as deletions.
+  status [<slug>] [--json]          Diff local ./projects/<slug>/ vs the deploy source
+                                    (builder_code_versions). cd in to omit <slug>.
+
+Ship a project (the agent-native deploy loop):
+  push [<slug>]                     Save local changes to the DEPLOY SOURCE, lane-routed:
+       [--include-deletes]            images/fonts/video under public/<subdir>/ → the
+       [--no-assets] [--assets-all]   S3/CDN asset store; everything else → batched,
+       [--commit "<msg>"]             verified bulk_save. This is what deploy reads.
+       [--deploy <env>] [--wait]      --commit also records a Hiveku 'main' commit.
+       [--dry-run] [--branch=<name>]  --deploy <env> [--wait] deploys after the push.
+  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.
+  commit [<slug>] -m "<msg>"        GitHub-branch commit via project_commit (only for
+                  [--branch=<name>]   GitHub-connected projects; most sites use push).
+                  [--include-deletes]
 
   help                              Show this message.
 
 Profiles: full, sales, marketing, helpdesk, pm, dev
 `;
 
+function commitMessageFrom(flags) {
+  // --commit "msg" | --commit=msg | -m "msg" | --message "msg". A bare --commit
+  // (boolean true) means "commit with no message" → fall back to the default.
+  const c = typeof flags['commit'] === 'string' ? flags['commit'] : undefined;
+  const m = typeof flags['m'] === 'string' ? flags['m'] : undefined;
+  const msg = typeof flags['message'] === 'string' ? flags['message'] : undefined;
+  if (c) return c;
+  if (m) return m;
+  if (msg) return msg;
+  if (flags['commit'] === true) return 'hiveku-sync: push';
+  return undefined;
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const { positional, flags } = parseFlags(rest);
@@ -144,16 +189,55 @@ async function main() {
       break;
     }
     case 'push': {
-      // Positional layout: `push [<slug>]`. -m / --message is required.
-      const slug = positional[0];
-      const message = flags['m'] || flags['message'];
-      if (!message) {
-        console.error('Error: push requires -m "<commit message>"\n');
+      const deployEnv = typeof flags['deploy'] === 'string' ? flags['deploy'] : undefined;
+      await runPush({
+        slug: positional[0],
+        profile: flags['profile'],
+        commit: commitMessageFrom(flags),
+        deploy: deployEnv,
+        wait: !!flags['wait'],
+        includeDeletes: !!flags['include-deletes'],
+        noAssets: !!flags['no-assets'],
+        assetsAll: !!flags['assets-all'],
+        dryRun: !!flags['dry-run'],
+        branch: flags['branch'],
+      });
+      break;
+    }
+    case 'deploy': {
+      // `deploy <env> [<slug>]` — env is the first positional.
+      const environment = positional[0];
+      if (!environment) {
+        console.error('Error: deploy requires an environment: development | staging | production\n');
+        console.error(HELP);
+        process.exit(1);
+      }
+      await runDeploy({
+        environment,
+        slugOrId: positional[1],
+        wait: !!flags['wait'],
+        profile: flags['profile'],
+      });
+      break;
+    }
+    case 'pull-env': {
+      await runPullEnv({
+        slug: positional[0],
+        profile: flags['profile'],
+        target: typeof flags['target'] === 'string' ? flags['target'] : 'development',
+      });
+      break;
+    }
+    case 'commit': {
+      // The legacy GitHub-branch commit path (project_commit). Requires a repo.
+      const message = commitMessageFrom(flags);
+      if (!message || message === 'hiveku-sync: push') {
+        console.error('Error: commit requires -m "<commit message>"\n');
         console.error(HELP);
         process.exit(1);
       }
       await runProjectPush({
-        slug,
+        slug: positional[0],
         message,
         branch: flags['branch'],
         profile: flags['profile'],
@@ -175,8 +259,14 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  console.error(`hiveku-sync: ${err.message}`);
-  if (process.env.HIVEKU_SYNC_DEBUG) console.error(err.stack);
-  process.exit(1);
-});
+// Only run the CLI when invoked directly — importing this module (e.g. from
+// tests to reach parseFlags) must not execute main().
+const isEntrypoint =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntrypoint) {
+  main().catch((err) => {
+    console.error(`hiveku-sync: ${err.message}`);
+    if (process.env.HIVEKU_SYNC_DEBUG) console.error(err.stack);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.1.0",
-  "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
+  "version": "0.2.0",
+  "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",
   "author": "Hiveku",
@@ -36,6 +36,7 @@
     "access": "public"
   },
   "scripts": {
-    "start": "node bin/hiveku-sync.mjs"
+    "start": "node bin/hiveku-sync.mjs",
+    "test": "node --test 'test/*.test.mjs'"
   }
 }

package/src/projects.mjs

@@ -19,8 +19,11 @@ import {
   writeFileAtomic,
   readJson,
 } from './util.mjs';
+// NOTE: push.mjs imports helpers from this module; the cycle is safe because
+// both sides reference the imports only inside functions (never at module eval).
+import { computePushPlan } from './push.mjs';
 
-const PROJECTS_DIR = 'projects';
+export const PROJECTS_DIR = 'projects';
 const PROJECTS_MANIFEST = '.hiveku/projects.json';
 
 const IGNORE_DIRS = new Set([
@@ -46,11 +49,11 @@ const RUN_HINTS = {
   static: 'npx serve .',
 };
 
-function sha256(content) {
+export function sha256(content) {
   return createHash('sha256').update(content).digest('hex');
 }
 
-async function clientFromCwd({ profileOverride } = {}) {
+export async function clientFromCwd({ profileOverride } = {}) {
   const baseDir = process.cwd();
   const dotenv = await loadDotenv(join(baseDir, '.env'));
   const apiKey = readEnv(process.env, dotenv, 'OLYMPUS_API_KEY');
@@ -86,7 +89,7 @@ async function listAllRemoteFiles(client, projectId) {
   return all;
 }
 
-async function walkLocalFiles(rootDir) {
+export async function walkLocalFiles(rootDir) {
   const out = [];
   async function recurse(dir) {
     let entries;
@@ -125,16 +128,16 @@ function runHintForProjectType(type) {
   return RUN_HINTS[type] || `# Unknown project_type "${type}". Inspect package.json/requirements.txt to find the dev command.`;
 }
 
-async function readProjectsManifest(baseDir) {
+export async function readProjectsManifest(baseDir) {
   const data = await readJson(join(baseDir, PROJECTS_MANIFEST));
   return data && typeof data === 'object' ? data : { projects: {} };
 }
 
-async function writeProjectsManifest(baseDir, manifest) {
+export async function writeProjectsManifest(baseDir, manifest) {
   await writeFileAtomic(join(baseDir, PROJECTS_MANIFEST), JSON.stringify(manifest, null, 2));
 }
 
-async function resolveProject(client, slugOrId) {
+export async function resolveProject(client, slugOrId) {
   // Accept either UUID (use directly) or slug (look up via list_projects).
   const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
   if (UUID_RE.test(slugOrId)) {
@@ -227,19 +230,22 @@ export async function runPullProject({ slugOrId, profile, branch }) {
     runHintForProjectType(project.project_type),
     '```',
     '',
-    '## Commit changes back',
+    '## Ship changes back',
     '',
-    'This folder is NOT a git clone — it\'s a snapshot. Use the Hiveku MCP `project_commit` tool',
-    'to write edits back to the project\'s GitHub branch (same path the v3 sidebar uses).',
+    "This folder is NOT a git clone — it's a snapshot. `push` writes your edits to the",
+    'DEPLOY SOURCE (what `deploy` builds from), lane-routing images/fonts/video to the',
+    'S3/CDN asset store and everything else to versioned code files.',
     '',
     'From this folder:',
     '',
     '```bash',
-    `hiveku-sync status   # diff local vs remote`,
-    `hiveku-sync push -m "your message"   # save + commit changed files via MCP`,
+    'hiveku-sync pull-env                          # project secrets → .env.local',
+    'hiveku-sync status                            # diff local vs the deploy source',
+    'hiveku-sync push                              # save changes back',
+    'hiveku-sync push --deploy development --wait  # ...then deploy and wait',
     '```',
     '',
-    'Or ask Claude in this workspace to commit the changed files for you.',
+    'Or ask Claude in this workspace to push/deploy for you.',
     '',
   ]
     .filter((line) => line !== undefined)
@@ -263,7 +269,7 @@ export async function runPullProject({ slugOrId, profile, branch }) {
   return { dest, written, skipped, projectId, slug: localSlug };
 }
 
-async function findProjectFolder({ slug, baseDir }) {
+export async function findProjectFolder({ slug, baseDir }) {
   // Allow status/push to be called from inside ./projects/<slug>/, ./<slug>/,
   // or the account root with an explicit slug arg.
   const manifest = await readProjectsManifest(baseDir);
@@ -310,39 +316,68 @@ export async function runProjectStatus({ slug, profile, json = false }) {
     throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);
   }
 
-  const localManifest = await buildLocalManifest(folder);
-  const diff = (await client.callToolJson('project_files_status', {
-    project_id: info.project_id,
-    local: localManifest,
-  })).data;
+  // Deploy-source-accurate + asset-lane-aware — the SAME diff `push` runs, so
+  // status never flags unchanged images as only_local (code goes through
+  // project_files_status; assets through assets_list).
+  const { diff, assetAll, assetToUpload, assetSkipped, plan } = await computePushPlan({
+    client,
+    projectId: info.project_id,
+    folder,
+    includeDeletes: true,
+  });
 
   if (json) {
-    console.log(JSON.stringify({ slug: resolvedSlug, project_id: info.project_id, ...diff }, null, 2));
-    return diff;
+    console.log(
+      JSON.stringify(
+        {
+          slug: resolvedSlug,
+          project_id: info.project_id,
+          code: diff,
+          assets: {
+            to_upload: assetToUpload.map((f) => f.path),
+            unchanged: assetSkipped,
+            total_local: assetAll.length,
+          },
+          plan,
+        },
+        null,
+        2,
+      ),
+    );
+    return { diff, plan };
   }
 
-  const sum = summarizeDiff(diff);
+  const changed = diff.changed?.length || 0;
+  const onlyLocal = diff.only_local?.length || 0;
+  const onlyRemote = diff.only_remote?.length || 0;
+  const unchanged = diff.same_count || 0;
   console.log(`Project: ${resolvedSlug}  (${info.project_id})`);
-  console.log(`  changed:     ${sum.changed}`);
-  console.log(`  only_local:  ${sum.only_local}`);
-  console.log(`  only_remote: ${sum.only_remote}`);
-  console.log(`  unchanged:   ${sum.same}`);
-  if (sum.changed > 0) {
-    console.log('\nChanged files:');
-    for (const f of diff.changed.slice(0, 20)) console.log(`  M  ${f.path}`);
-    if (diff.changed.length > 20) console.log(`  ... and ${diff.changed.length - 20} more`);
-  }
-  if (sum.only_local > 0) {
-    console.log('\nLocal-only (will be added on push):');
-    for (const f of diff.only_local.slice(0, 20)) console.log(`  +  ${f.path}`);
-    if (diff.only_local.length > 20) console.log(`  ... and ${diff.only_local.length - 20} more`);
-  }
-  if (sum.only_remote > 0) {
-    console.log('\nRemote-only (deleted locally or never pulled — pass --include-deletes to push to commit deletions):');
-    for (const f of diff.only_remote.slice(0, 20)) console.log(`  -  ${f.path}`);
-    if (diff.only_remote.length > 20) console.log(`  ... and ${diff.only_remote.length - 20} more`);
-  }
-  return diff;
+  console.log('Compared against the DEPLOY SOURCE (builder_code_versions + asset store).\n');
+  console.log('Code:');
+  console.log(`  changed:     ${changed}`);
+  console.log(`  added:       ${onlyLocal}`);
+  console.log(`  remote-only: ${onlyRemote}`);
+  console.log(`  unchanged:   ${unchanged}`);
+  console.log('Assets (images/fonts/video under public/<subdir>/):');
+  console.log(`  to upload:   ${assetToUpload.length}  (new or changed)`);
+  console.log(`  unchanged:   ${assetSkipped}`);
+  console.log(`  total local: ${assetAll.length}`);
+
+  const printList = (items, marker, header, getPath = (f) => f.path) => {
+    if (!items || items.length === 0) return;
+    console.log(`\n${header}`);
+    for (const f of items.slice(0, 20)) console.log(`  ${marker}  ${getPath(f)}`);
+    if (items.length > 20) console.log(`  ... and ${items.length - 20} more`);
+  };
+  printList(diff.changed, 'M', 'Changed code:');
+  printList(diff.only_local, '+', 'Added code (will be created on push):');
+  printList(
+    diff.only_remote,
+    '-',
+    'Remote-only code (deleted locally or never pulled — push --include-deletes to delete):',
+  );
+  printList(assetToUpload, 'A', 'Assets to upload (new or changed):');
+  return { diff, plan };
 }
 
 export async function runProjectPush({

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 };
+}