@hiveku-apps/sync 0.3.5 → 0.4.0

package/README.md

@@ -108,9 +108,52 @@ This writes, merge-safely (only Hiveku-managed regions are touched):
   and deprecated).
 
 Pass `--trust` to pre-trust the folder in `~/.codex/config.toml` (so Codex loads
-the repo config without its first-run trust prompt). Codex ignores repo-level
-approval/sandbox config, so the safe-work rules ship as instructions in
-`AGENTS.md`, not enforced permissions.
+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`,
+`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 =
+"approve"`), and that includes many deletes and sends, for example
+`crm_delete_contact`, `content_delete` and `survey_send`. So the safe-work rules
+in `AGENTS.md` still apply to every tool: they are instructions, not enforced
+permissions.
+
+**Your own setting wins.** When `.codex/config.toml` already has your own
+`[mcp_servers.hiveku.tools.<tool>]` table for a listed tool, outside the
+hiveku-sync block, hiveku-sync leaves that tool out of its block (TOML does not
+allow a table to be declared twice) and prints a line naming it. If your table
+sets no `approval_mode`, Codex uses the server default, `approve`, so that tool
+runs without asking, and the line says so. Add `approval_mode = "prompt"` to
+your table to have it ask first.
+
+hiveku-sync checks the updated file before it writes anything. It stops only
+when its own block would declare a table or key that another line of the file
+also declares, for example your own copy of `[mcp_servers.hiveku]`. Then it
+writes nothing in the folder and names that line by its number. It reads the
+file as Codex does, so TOML 1.1 syntax and a byte-order mark at the start are
+fine, and it leaves the rest of the file, including any line it cannot read,
+to you and Codex.
+
+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.
+
+Headless and bypass modes:
+
+- **`codex exec` never stops to ask.** Under a `read-only` or `workspace-write`
+  sandbox it cancels the listed calls and runs the rest.
+- **The bypass flag skips every prompt.** With
+  `--dangerously-bypass-approvals-and-sandbox` (`--yolo`), in `codex exec` or in
+  interactive `codex`, and with `danger-full-access` in `codex exec`
+  (`-s danger-full-access` or `sandbox_mode = "danger-full-access"`), the listed
+  tools run unattended too, like every other Hiveku tool.
+
+Folders set up by a hiveku-sync without these prompts (0.3.5 and earlier)
+approve every tool: run `hiveku-sync codex` in them once, with a release that has
+them, to add the prompts.
 
 > **This vs. the plugin.** For a single account, you can instead install the
 > published [Hiveku Codex plugin](https://github.com/locus2012/hiveku-codex-plugin)
@@ -134,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`:
@@ -152,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.
@@ -202,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,46 +93,108 @@ 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.
 
 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.
+/**
+ * Plain lines naming the listed tools whose own config.toml table hiveku-sync
+ * left alone. A table that sets no approval_mode gets the server default
+ * ("approve"), so those tools are said to run without asking.
+ */
+function userToolTablesLines({ userToolTables = [], userTablesWithoutApprovalMode = [] }) {
+  const lines = [];
+  const kept = userToolTables.filter((tool) => !userTablesWithoutApprovalMode.includes(tool));
+  if (kept.length) {
+    const them = kept.length === 1 ? 'it' : 'them';
+    lines.push(
+      `your own setting kept for ${kept.join(', ')}: .codex/config.toml sets ${them} outside the hiveku-sync block, so hiveku-sync did not add its "ask first" setting for ${them}.`,
+    );
+  }
+  const bare = userTablesWithoutApprovalMode;
+  if (bare.length) {
+    const one = bare.length === 1;
+    lines.push(
+      `${bare.join(', ')} ${one ? 'runs' : 'run'} without asking: your own ${one ? 'table' : 'tables'} for ${one ? 'it' : 'them'} in .codex/config.toml, outside the hiveku-sync block, ${one ? 'sets' : 'set'} no approval_mode, so Codex uses the server default ("approve"). To have ${one ? 'it' : 'them'} ask first, add approval_mode = "prompt" to ${one ? 'that table' : 'those tables'}.`,
+    );
+  }
+  return lines;
+}
+
+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);
@@ -163,6 +229,7 @@ async function main() {
             ? `    MCP auth: inlined your OLYMPUS_API_KEY`
             : `    MCP auth: reads the OLYMPUS_API_KEY env var — after pasting your key into .env, run \`hiveku-sync codex\` to inline it, or \`export OLYMPUS_API_KEY=...\``,
         );
+        for (const line of userToolTablesLines(result.codex)) console.log(`    ${line}`);
         if (result.codex.trust === 'added') console.log(`    trust: pre-trusted this folder in ~/.codex/config.toml`);
       }
       console.log(`  then: cd ${result.folder} && hiveku-sync pull`);
@@ -172,6 +239,7 @@ async function main() {
       const result = await runCodex({ folder: positional[0], trust: !!flags['trust'] });
       console.log(`Codex lane ready in ${result.folder} (profile=${result.profile})`);
       console.log(`  AGENTS.md + .codex/config.toml written (git-ignored).`);
+      for (const line of userToolTablesLines(result)) console.log(`  ${line}`);
       console.log(
         result.inlinedKey
           ? `  MCP auth: inlined OLYMPUS_API_KEY from .env.`
@@ -231,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),
@@ -247,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': {
@@ -275,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.5",
+  "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",