@hiveku-apps/sync 0.3.6 → 0.4.0

package/README.md

@@ -177,10 +177,32 @@ 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 -m "Updated the pricing section on the Home page"
+                                        # save changes, then save them as one version
 hiveku-sync push --deploy development --wait   # ...then deploy and wait
 ```
 
+`pull-project` pages through the site (`project_vcs_checkout` with `limit`,
+then `cursor`), so a site of any size comes down, including the ones over
+150 MB that cannot be sent in one answer. `--branch <name>` pulls that
+branch's working tree instead of Your site; `.hiveku/projects.json` records
+the branch, the version the pull came from (`head_commit_id`) and, on a
+branch, its `working_tree_etag`. Later `push`, `status`, `commit`,
+`versions` and `rollback` in that folder act on the same branch unless you
+pass `--branch` (`--branch main` for Your site).
+
+Each pull also records the files it wrote (`.hiveku/pulled/<slug>.json`). The
+next pull moves the ones its tree no longer has (another branch's files, files
+deleted on Hiveku) out of the project folder into
+`.hiveku/set-aside/<slug>/<time>/`, so a push can never send them back; files
+you created yourself are listed, never moved. The run hints go to the project
+folder's `.hiveku/RUN.md`, which push never sends.
+
+On a branch, `push` compares the branch's `working_tree_etag` with the one
+recorded at pull time. If someone saved on the branch since, it lists the files
+that may hold their work and changes nothing (exit 1); pull again, or pass
+`--force` to overwrite them.
+
 **`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`:
@@ -195,17 +217,65 @@ hiveku-sync push --deploy development --wait   # ...then deploy and wait
 - 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).
+- sends each batch again with only the files that did not land (a large batch
+  can stop at the route's time budget and name the rest in `remaining_paths`),
+  and lists every file that still did not save.
+- with `--include-deletes`, deletes only files this folder could hold: never
+  dot files (`.gitignore`, `.ai/memory.md`), build folders, or files Hiveku
+  manages (`soul.md`, `data/marketing/...`), which a pull never brings down.
 
 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`.
+`--assets-all`, `-m "name"` (the version name; `--commit "name"` still works),
+`--no-version`, `--branch <name>`, `--force`, `--deploy <env> [--wait]`,
+`--dry-run`. Images, fonts and videos live in one asset store shared by Your
+site and every branch, so a push to a branch says so before it uploads them
+(and in `--dry-run`). `--deploy` publishes what that tier is set to publish:
+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 commit -m "msg"   # legacy GitHub-branch commit (GitHub-connected projects only)
 ```
 
+## Versions
+
+"Your site" is the project's main source: what the preview shows and what a
+deploy ships. A save is live there at once, but it is not a **version** until
+one is saved, and a version is what you can go back to.
+
+- **`push` saves one version** after every file has landed:
+  `project_vcs_commit` with no files and no deletions (source `sync_cli`),
+  which saves everything on Your site (or the branch) not yet in a version,
+  from every writer (the Hiveku AI, the editor, other tools). So the name comes
+  from `-m`, otherwise from everything `project_vcs_status` says is waiting
+  ("Added the Pricing page and edited the Home page"), or only from the pages
+  the push changed on a server that cannot say. The first version after a
+  version from before versions of Your site is named by Hiveku ("Your site up
+  to <date>"). `--no-version` skips it.
+- **Names are read by the site owner.** Describe what changed for visitors;
+  never file paths, file extensions, `fix:`-style prefixes or tool names.
+  A typed name that breaks this is refused before anything is written.
+- **Exit codes:** `0` done; `1` some files did not save, or the push was
+  refused (they are listed, and there is no version and no deploy); `2` every
+  file IS saved but the version was not (the message says why and prints the
+  exact `hiveku-sync commit` that tries again); `3` the files and the version
+  ARE saved and only the deploy failed (`hiveku-sync deploy` tries again).
+
+```bash
+hiveku-sync commit [-m "name"]          # save what is waiting as one version (sends no files)
+hiveku-sync commit --github -m "msg"    # the old GitHub push (GitHub-connected projects only)
+hiveku-sync versions [--limit 50]       # the versions, newest first, and what is waiting
+hiveku-sync rollback <version id>       # dry run: what going back would change
+```
+
+`rollback` is a dry run unless you add `--apply`, and `--apply` needs the
+`--confirm` id the dry run printed (it prints the whole command), so it only goes
+ahead if nobody changed the site since you looked. Rolling back writes a NEW
+version equal to the old one, so it can be undone, saves unsaved changes as
+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.
@@ -245,7 +315,7 @@ suggested it and when. The two account-memory rows (`account` and
 `account-suggestions`) are never written under `memory/`, even when an older
 server still lists them.
 
-Nothing uploads this file: `push`, `commit` and `status` leave any
+Nothing uploads this file: `push`, `commit --github` and `status` leave any
 `hiveku-data/account/` folder out, and the next `pull` replaces it. To add a
 fact, suggest it with the `account_memory_append` tool; an owner keeps or
 removes it on the dashboard.

package/bin/hiveku-sync.mjs

@@ -18,6 +18,7 @@ import {
   runProjectPush,
 } from '../src/projects.mjs';
 import { runPush, runDeploy, runPullEnv } from '../src/push.mjs';
+import { runRollback, runVersionCommit, runVersions } from '../src/versions.mjs';
 import { pathToFileURL } from 'node:url';
 
 export function parseFlags(argv) {
@@ -34,6 +35,9 @@ export function parseFlags(argv) {
     'branch',
     'profile',
     'parent',
+    'confirm',
+    'fingerprint',
+    'limit',
   ]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -89,27 +93,59 @@ Memory/rules/skills:
 
 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.
+  pull-project <slug-or-id>         Pull Your site's files (or, with --branch, that
+                  [--branch=<name>]   branch's working tree) into ./projects/<slug>/,
+                                      page by page (any size). Records the project,
+                                      branch and version in .hiveku/projects.json.
+                                      Files an earlier pull wrote that are not in
+                                      this one move to .hiveku/set-aside/<slug>/.
   status [<slug>] [--json]          Diff local ./projects/<slug>/ vs the deploy source
-                                    (builder_code_versions). cd in to omit <slug>.
+         [--branch=<name>]            (builder_code_versions), or the pulled branch.
+                                      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.
+       [-m "<version name>"]          images/fonts/video under public/<subdir>/ → the
+       [--no-version]                 S3/CDN asset store; everything else → batched,
+       [--include-deletes]            verified bulk_save. This is what deploy reads.
+       [--no-assets] [--assets-all]   Then saves ONE version of Your site (or of the
+       [--deploy <env>] [--wait]      branch) named by -m, or from the pages changed.
+       [--dry-run] [--branch=<name>]  Names are plain language for the site owner (no
+       [--force]                      file paths, extensions or "fix:" prefixes).
+                                      --no-version skips the version. --deploy <env>
+                                      [--wait] deploys after the push. --branch writes
+                                      to that branch (default: the branch pulled);
+                                      if someone saved on it since the pull, push
+                                      refuses unless --force.
+                                      Exit 0 done; 1 some files did not save or the
+                                      push was refused (no version, no deploy); 2
+                                      files ARE saved but the version was not (it
+                                      prints the \`commit\` that retries it); 3 files
+                                      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.
-  commit [<slug>] -m "<msg>"        GitHub-branch commit via project_commit (only for
-                  [--branch=<name>]   GitHub-connected projects; most sites use push).
-                  [--include-deletes]
+
+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
+         [--branch=<name>]            one version (no files are sent: push first).
+         [--dry-run]                  Without -m it is named from what changed. Exit 2
+                                      when the version could not be saved.
+  commit --github -m "<msg>"        The old GitHub push via project_commit (only for
+         [--branch=<name>]            GitHub-connected projects).
+         [--include-deletes]
+  versions [<slug>] [--branch=<b>]  The versions, newest first, and what is waiting.
+           [--limit N] [--json]
+  rollback <version id> [<slug>]    Show what going back to that version would change.
+           [--branch=<name>]          Nothing changes (a dry run). It prints the exact
+           [--apply --confirm <id>]   --apply command, with the --confirm id it saw;
+           [--fingerprint <fp>]       applying writes a NEW version equal to the old one
+           [-m "<name>"]              (so it can be undone) and is refused if the site
+                                      changed since the dry run. Publish separately
+                                      with deploy.
 
   help                              Show this message.
 
@@ -140,19 +176,25 @@ function userToolTablesLines({ userToolTables = [], userTablesWithoutApprovalMod
   return lines;
 }
 
-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.
+export function commitMessageFrom(flags) {
+  // --commit "msg" | --commit=msg | -m "msg" | --message "msg": the version
+  // name. A bare --commit (boolean true, from before versions were the
+  // default) names nothing: the version is then named from what changed.
   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;
 }
 
+/** A command's exit code, from the result object it returned (0 when it says nothing). */
+function setExitCode(result) {
+  const code = result && typeof result.exit_code === 'number' ? result.exit_code : 0;
+  if (code) process.exitCode = code;
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const { positional, flags } = parseFlags(rest);
@@ -257,12 +299,13 @@ async function main() {
         slug: positional[0],
         profile: flags['profile'],
         json: !!flags['json'],
+        branch: flags['branch'],
       });
       break;
     }
     case 'push': {
       const deployEnv = typeof flags['deploy'] === 'string' ? flags['deploy'] : undefined;
-      await runPush({
+      const result = await runPush({
         slug: positional[0],
         profile: flags['profile'],
         commit: commitMessageFrom(flags),
@@ -273,7 +316,10 @@ async function main() {
         assetsAll: !!flags['assets-all'],
         dryRun: !!flags['dry-run'],
         branch: flags['branch'],
+        noVersion: !!flags['no-version'],
+        force: !!flags['force'],
       });
+      setExitCode(result);
       break;
     }
     case 'deploy': {
@@ -301,21 +347,63 @@ async function main() {
       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);
+      if (flags['github']) {
+        // The old GitHub-branch path (project_commit). Requires a connected repo.
+        const message = commitMessageFrom(flags);
+        if (!message) {
+          console.error('Error: commit --github requires -m "<message>"\n');
+          console.error(HELP);
+          process.exit(1);
+        }
+        await runProjectPush({
+          slug: positional[0],
+          message,
+          branch: flags['branch'],
+          profile: flags['profile'],
+          includeDeletes: !!flags['include-deletes'],
+          dryRun: !!flags['dry-run'],
+        });
+        break;
       }
-      await runProjectPush({
+      // Default: save what is on Hiveku as one version (no files sent).
+      const result = await runVersionCommit({
         slug: positional[0],
-        message,
+        name: commitMessageFrom(flags),
         branch: flags['branch'],
         profile: flags['profile'],
-        includeDeletes: !!flags['include-deletes'],
         dryRun: !!flags['dry-run'],
       });
+      setExitCode(result);
+      break;
+    }
+    case 'versions': {
+      const result = await runVersions({
+        slug: positional[0],
+        branch: flags['branch'],
+        limit: typeof flags['limit'] === 'string' ? flags['limit'] : undefined,
+        json: !!flags['json'],
+        profile: flags['profile'],
+      });
+      setExitCode(result);
+      break;
+    }
+    case 'rollback': {
+      if (!positional[0]) {
+        console.error('Error: rollback requires a version id (see `hiveku-sync versions`).\n');
+        console.error(HELP);
+        process.exit(1);
+      }
+      const result = await runRollback({
+        versionId: positional[0],
+        slug: positional[1],
+        branch: flags['branch'],
+        apply: !!flags['apply'],
+        head: typeof flags['confirm'] === 'string' ? flags['confirm'] : undefined,
+        fingerprint: typeof flags['fingerprint'] === 'string' ? flags['fingerprint'] : undefined,
+        name: commitMessageFrom(flags),
+        profile: flags['profile'],
+      });
+      setExitCode(result);
       break;
     }
     case 'help':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.3.6",
+  "version": "0.4.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",

package/src/codex-prompt-tools.json

@@ -1,5 +1,5 @@
 {
-  "source": "locus2012/hiveku-codex-plugin 0.1.16 (5b4e580), plugins/hiveku/.mcp.json: every hiveku.tools entry (all approval_mode \"prompt\")",
+  "source": "locus2012/hiveku-codex-plugin 0.1.16 (5b4e580), plugins/hiveku/.mcp.json: every hiveku.tools entry (all approval_mode \"prompt\"); plus project_vcs_rollback (Versions Wave 2, hiveku-codex-plugin feature/versions-wave2)",
   "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",
@@ -13,6 +13,7 @@
     "project_vcs_stash",
     "project_vcs_prune",
     "project_vcs_branch_preview_teardown",
+    "project_vcs_rollback",
     "project_vcs_revert",
     "hiveku_batch",
     "project_checkpoint_restore",

package/src/codex.mjs

@@ -43,7 +43,7 @@ import { loadDotenv, safeSlug } from './util.mjs';
  * The FIXED list of high-risk Hiveku tools that Codex asks about before
  * running. It is the Hiveku Codex plugin's own prompt list, copied name for
  * name (codex-prompt-tools.json says which release; 246 names at plugin
- * 0.1.16). It includes hiveku_batch, because Codex asks by the name of the tool
+ * 0.1.16, plus project_vcs_rollback from Versions Wave 2). It includes hiveku_batch, because Codex asks by the name of the tool
  * it calls and a batch carries other tools.
  *
  * It is a list of names, not a category. Every tool not on it runs without
@@ -72,11 +72,11 @@ import { loadDotenv, safeSlug } from './util.mjs';
  * default_tools_approval_mode = "approve" here, every Hiveku tool ran without
  * a prompt, with or without the plugin installed.
  *
- * Adding another prompt list (the unmerged Versions Wave 2 branch has
- * RESTORE_TOOLS, for example): put its names into this one Set, so each tool
+ * Adding another prompt list: put its names into this one Set, so each tool
  * still gets exactly one table. A second block of tables would define some
- * tables twice (four of Wave 2's five names are already here), and that makes
- * the whole config.toml invalid TOML.
+ * tables twice, and that makes the whole config.toml invalid TOML. (Versions
+ * Wave 2 did this: its five roll-back tools are in codex-prompt-tools.json,
+ * project_vcs_rollback included.)
  *
  * The user's own table wins: a listed tool that already has its own
  * [mcp_servers.hiveku.tools.<tool>] table outside the managed block gets no
@@ -148,6 +148,13 @@ Non-negotiables (also in CLAUDE.md, restated because they are load-bearing):
   — \`changed\` = they edited it, \`only_remote\` = they added files you lack). Before any tree-replace
   (\`delete_missing: true\`), \`dry_run\` first and READ the would-delete list — a file you did not send
   may be someone else's NEW work. Never blind-overwrite.
+- **Version every change.** After saving and verifying, call \`project_vcs_commit({ project_id, message })\`
+  with NO files, once per change, before \`deploy_site\` (or \`hiveku-sync push -m "..."\`, which does both);
+  409 \`nothing_to_commit\` means it is already a version: not an error.
+  The name is plain language for the site owner ("Updated the pricing section on the Home page"): never file
+  paths, extensions, \`fix:\` prefixes or tool names. Roll back with \`project_vcs_rollback\`: dry run first,
+  apply only after the user agrees, with the dry run's \`head_commit_id\` as \`expected_head_commit_id\` (on Your
+  site also its \`live_fingerprint\` as \`expected_live_fingerprint\`); publishing is a separate \`deploy_site\`.
 - **Keep ALL scratch work in \`.hiveku/tmp/\`** — never \`/tmp\` (shared across accounts), your home
   dir, or the repo root.
 - **Never ingest local agent config into a project push.** \`.codex/config.toml\`, \`.mcp.json\`, and

package/src/init.mjs

@@ -96,7 +96,7 @@ Hiveku dashboard under Account memory.
 
 Then run \`hiveku-sync pull\` to refresh the local copies.
 
-## Coder projects (pull / status / push)
+## Coder projects (pull / push / versions)
 
 Each account has zero or more coder projects (Next.js, Vite, Python Lambda,
 Expo). To work on one locally:
@@ -105,25 +105,54 @@ Expo). To work on one locally:
 hiveku-sync projects                        # list the account's projects
 hiveku-sync pull-project <slug-or-id>       # snapshot into ./projects/<slug>/
 cd projects/<slug>
-# follow the run instructions in RUN.md (npm install && npm run dev for nextjs, etc.)
+# follow the run instructions in .hiveku/RUN.md (npm install && npm run dev for nextjs, etc.)
 \`\`\`
 
-This is **not a git clone** — the local folder is a snapshot. To check whether
-edits are in sync with the Hiveku DB, and to commit changes back to the
-project's connected GitHub branch (same path the v3 sidebar uses):
+This is **not a git clone** — the local folder is a snapshot of **Your site**
+(the project's main source; \`--branch <name>\` pulls a branch instead).
+\`push\` saves your edits to Hiveku and then saves them as ONE **version**, which
+can be rolled back later:
 
 \`\`\`bash
-hiveku-sync status                          # diff local vs Hiveku DB
-hiveku-sync push -m "fix: header overlap"   # save + commit changed files via MCP
+hiveku-sync status                          # diff local vs Hiveku
+hiveku-sync push -m "Updated the pricing section on the Home page"
+hiveku-sync versions                        # the version history, newest first
+hiveku-sync rollback <version id>           # dry run: what going back would change
+hiveku-sync deploy production               # publishing is always its own step
 \`\`\`
 
-You can also ask Claude in this workspace to:
-- "Pull project <slug>"
-- "Show me which files are out of sync with Hiveku"
-- "Commit the changes in projects/<slug> to the dev branch with message '...'"
-
-Claude has the \`project_files_list\`, \`project_file_get\`, \`project_files_status\`,
-and \`project_commit\` MCP tools available under the **${profile}** profile.
+- **Version names are read by the site owner.** Describe what changed for their
+  visitors ("Added a contact form to the About page"): never file paths, file
+  extensions, \`fix:\`-style prefixes or tool names. A version holds everything
+  waiting on Your site, including the Hiveku AI's and the editor's changes, so
+  without \`-m\` push names it from all of that; \`--no-version\` skips it.
+- **One version per change the owner would recognise**: push as often as you
+  like with \`--no-version\`, then save the version once (\`hiveku-sync commit -m "..."\`)
+  before you deploy.
+- **Exit codes:** 0 done; 1 some files did not save, or the push was refused
+  (listed; no version, no deploy); 2 every file IS saved but the version was not
+  (it prints the \`hiveku-sync commit\` that retries it); 3 the files and the
+  version ARE saved and only the deploy failed.
+- **On a branch, someone else may have saved since you pulled.** push then
+  refuses and lists the files that may hold their work: pull again (it replaces
+  your local copies, so keep your edits somewhere first), or \`--force\` to
+  overwrite. A pull moves the files an earlier pull wrote that are not on what
+  it pulls now (another branch's, or deleted on Hiveku) out of the project folder
+  into \`.hiveku/set-aside/\`, so they are never pushed back by mistake.
+- **Rolling back** writes a NEW version equal to the old one, so it can be undone,
+  and it never publishes. Run the dry run, show the owner what it changes, and only
+  after they agree run the \`--apply\` command it prints. Then offer \`deploy\`
+  separately.
+
+Through the MCP tools the same loop is: save (\`project_files_bulk_save\` /
+\`project_file_save\`), verify, then \`project_vcs_commit({ project_id, message })\`
+with **no files** (one version, plain-language name; 409 \`nothing_to_commit\`
+means it is already a version), then \`deploy_site\`.
+\`project_vcs_status\` says whether changes are waiting to be saved as a version;
+\`project_vcs_rollback\` rolls back (dry run by default; applying needs the dry
+run's \`head_commit_id\` as \`expected_head_commit_id\`, and on Your site its
+\`live_fingerprint\` as \`expected_live_fingerprint\`). The \`project_*\` tools come
+with the \`dev\` and \`full\` profiles (this folder uses **${profile}**).
 
 ## When Hiveku itself gets in your way