@remits/remits-cli 0.1.120 → 0.1.122

package/index.js

@@ -19,6 +19,9 @@ const openBrowser = (openModule && typeof openModule === 'function')
 
 //const DEFAULT_BASE_URL = process.env.REMITS_BASE_URL || 'http://localhost:8080';
 const DEFAULT_BASE_URL = process.env.REMITS_BASE_URL || 'https://remits-529558023549.us-east5.run.app';
+
+// How many compile failures print their full message before the rest are listed by identifier only.
+const COMPILE_FAILURES_SHOWN = 5;
 const SESSION_DIR = path.join(os.homedir(), '.remits-cli');
 const SESSIONS_FILE = path.join(SESSION_DIR, 'sessions.json');
 const CONFIG_FILE = path.join(SESSION_DIR, 'config.json');
@@ -2817,7 +2820,7 @@ async function pushComponentsCommand(flags) {
   // or, worse, conclude staging was broken and go on reading trunk. Scaled by payload size, floored at
   // the old default, and overridable.
   const api = buildAxios(baseUrl, session.token, stageTimeoutMs(components, flags));
-  const response = await stageOrRefuse(api, cwd, {
+  const stagePayload = {
     token: session.token,
     accountId,
     branchName,
@@ -2846,11 +2849,50 @@ async function pushComponentsCommand(flags) {
     // Kept for a platform that predates stageMode. Same meaning it always had.
     replace: !changedOnly,
     components
-  });
+  };
+
+  let response;
+  try {
+    response = await stageOrRefuse(api, cwd, stagePayload);
+  } catch (err) {
+    // A REFUSED stage is evidence too. Recording it only on the success path is how a lane ends up with
+    // an envelope that says nothing happened between two packets, when in fact a stage was attempted and
+    // the platform rejected it. The packet is best-effort: a failing stage must surface the STAGE error,
+    // never an error from writing the record of it.
+    try {
+      await appendVerificationPacket(api, cwd, session, accountId, flags, {
+        type: 'stage',
+        success: false,
+        claim: 'Components refused at staging',
+        world: buildCommandWorld(err.responseBody || {}, { accountId, dataMode, branchName, workspace, host: normalizeBaseUrl(baseUrl), sourceLayer: 'staged' }),
+        revision: collectVerificationSource(cwd, flags),
+        assertions: [
+          { id: 'stage', stageMode },
+          { id: 'stage_refused', value: err.message }
+        ],
+        evidenceCategories: ['stage'],
+        rawRefs: { command: 'components stage' },
+        stage: (err.responseBody || {}).stage,
+        compileValidation: (err.responseBody || {}).compileValidation,
+        changedFromWorkingTree: changedFromWorkingTree || [],
+        unrepresentableChanges: unstageable
+      }, { quiet: true });
+    } catch (packetError) {
+      // Deliberately swallowed and named, not silent.
+      console.error('Could not record the refused-stage verification packet: ' + packetError.message);
+    }
+    throw err;
+  }
   response.changedFromWorkingTree = changedFromWorkingTree || [];
   response.changedFromWorkingTreeAvailable = changedFromWorkingTree !== null;
   response.requestedStageMode = stageMode;
   response.unrepresentableChanges = unstageable;
+  if (response.success === false) {
+    // A 200 that says `success:false`. The 422 path throws out of stageOrRefuse above and never lands
+    // here, so this stays as the belt-and-braces case — print whatever detail came with it first.
+    printCompileValidation(response.compileValidation, { stderr: true });
+    throw new Error(response.message || 'Server stage failed');
+  }
 
   await appendVerificationPacket(api, cwd, session, accountId, flags, {
     type: 'stage',
@@ -2947,6 +2989,17 @@ async function stageOrRefuse(api, cwd, payload) {
       refusal.refused = true;
       throw refusal;
     }
+    if (body && body.message) {
+      // The server's `message` is ONE line derived from the FIRST failure. The rest of the detail is in
+      // the body, and the caller cannot see the body — an agent handed "compile failed for Reader 41"
+      // over a stage with nine broken components fixes one, re-stages, and pays nine round trips. Render
+      // the whole list HERE, where the body is still in hand, then throw the one-line summary.
+      printCompileValidation(body.compileValidation, { stderr: true });
+      const failure = new Error(body.message);
+      failure.responseBody = body;
+      failure.status = status;
+      throw failure;
+    }
     throw err;
   }
 }
@@ -2967,6 +3020,60 @@ function printComponentPolicy(response) {
   (policy.overrides || []).forEach((id) => console.log('Policy override recorded for rule: ' + id));
 }
 
+/**
+ * What the platform compiled, and what it could not.
+ *
+ * Prints on BOTH outcomes, including `attempted: 0`. A silent pass and a pass that validated nothing look
+ * identical otherwise, and they are not the same claim: when git cannot identify the changed set the
+ * server has no workset to validate and says so (`skipped[].reason`). Reporting that as silence would be
+ * the same confident-wrong-number this surface exists to remove.
+ */
+function printCompileValidation(validation, options) {
+  // Failures go to stderr so `--json` stdout stays parseable: a caller that asked for JSON is a program,
+  // and a refusal must not put prose in the middle of its document.
+  const emit = (options && options.stderr) ? console.error : console.log;
+  if (!validation || validation.attempted == null) return;
+  const failures = Array.isArray(validation.failures) ? validation.failures : [];
+  if (validation.attempted === 0) {
+    const reasons = (Array.isArray(validation.skipped) ? validation.skipped : [])
+      .map((entry) => (entry && entry.reason) || '')
+      .filter((reason) => reason && reason !== 'no-compilable-source');
+    if (reasons.length) {
+      emit('Compile validation: NOT RUN — ' + reasons.join(', ') +
+        '. Nothing in this stage was compile-checked.');
+      if (reasons.includes('workset-unknown')) {
+        emit('  git could not identify the changed set, so there was no workset to validate.');
+        emit('  Stage from a git working tree, or re-stage the component explicitly, to get the check.');
+      }
+    }
+    return;
+  }
+  const status = validation.success === true ? 'passed' : 'failed';
+  emit('Compile validation: ' + status + ' — ' + validation.passed + '/' + validation.attempted +
+    ' compiled in ' + validation.durationMs + 'ms' +
+    (validation.concurrency ? ' (' + validation.concurrency + ' parallel)' : ''));
+  const shown = failures.slice(0, COMPILE_FAILURES_SHOWN);
+  shown.forEach((failure) => {
+    emit('  ' + (failure.type || 'component') + ' ' + (failure.id || failure.name || '') +
+      ': ' + (failure.message || 'compile failed'));
+  });
+  if (failures.length > shown.length) {
+    // Named, not counted. "3 more failure(s)" sends an agent back for another round trip to learn WHICH
+    // three; the identifiers are already in hand and cost one line.
+    emit('  ' + (failures.length - shown.length) + ' more failed: ' +
+      failures.slice(COMPILE_FAILURES_SHOWN)
+        .map((failure) => (failure.type || 'component') + ' ' + (failure.id || failure.name || '?'))
+        .join(', '));
+    emit('  Re-run with --json for every compile message.');
+  }
+  if (validation.success !== true) {
+    // The lane is written BEFORE it is validated, because the compile has to resolve through the staged
+    // overlay to see the source it is judging. So a refusal does not mean "nothing was staged".
+    emit('  The rejected source IS in the lane: staging writes, then compiles what it wrote.');
+    emit('  A run in this lane will resolve the broken component until you fix it and re-stage.');
+  }
+}
+
 function shouldPrintFullComponentResponse(flags) {
   return flagEnabled(flags.verbose);
 }
@@ -3088,6 +3195,7 @@ function printStageSummary(response, flags) {
   if (overlay != null) {
     console.log('Materialized overlay now held by the lane:', overlay, 'component(s)');
   }
+  printCompileValidation(response.compileValidation);
 
   // The trap `--changed-only` leaves behind: it merges, so a lane inherited from an earlier full snapshot
   // keeps every one of those entries resolving ahead of committed source. Silence here is what made
@@ -4501,7 +4609,22 @@ async function commitComponentsCommand(flags) {
   const landing = await acquireLandingLease(flags, accountId, branchName);
   try {
   if (!skipGit) {
-    console.log('Phase 1/3: local git commit/push');
+    console.log('Phase 1/4: staged compile validation');
+    // MERGE semantics on purpose (`--changed-only`, never `--workset`). A workset stage RECONCILES the
+    // lane — it deletes every entry outside the git changed set — and the lane is frequently shared. A
+    // validation pass must not be able to delete another agent's staged work as a side effect of somebody
+    // running `components commit`. This adds the changed components to the lane and leaves the rest alone.
+    await pushComponentsCommand(Object.assign({}, flags, {
+      branch: branchName,
+      'account-id': accountId,
+      mode: 'stage',
+      workset: false,
+      'replace-lane': false,
+      replaceLane: false,
+      'changed-only': true
+    }));
+
+    console.log('Phase 2/4: local git commit/push');
     const status = runGit(cwd, 'git status --porcelain');
     if (status || allowEmpty) {
       runGit(cwd, 'git add -A');
@@ -4528,14 +4651,12 @@ async function commitComponentsCommand(flags) {
     console.log('Skipping local git phase. Prefer `remits-cli components sync` if you only need the server sync step.');
   }
 
-  console.log('Phase 2/3: server sync');
+  console.log('Phase 3/4: server sync');
   if (flagEnabled(flags.safe)) {
-    // The honest limit, stated where it applies. `components commit` runs git add/commit/push BEFORE the
-    // server sync, so a --safe gate here cannot stop the push — it stops the PLATFORM from writing bad
-    // overlays. The branch may already be pushed when the gate refuses; that is recoverable, an
-    // unintended ComponentVariant tree is much less so.
-    console.log('  --safe: the branch is already pushed. The gate below stops the platform from WRITING a');
-    console.log('  surprising plan; it cannot un-push. Use `components sync --safe` alone for a pre-push gate.');
+    // Compile validation already ran before the push. The sync safety gates still run after the push
+    // because they need the server's remote-branch plan.
+    console.log('  --safe: compile validation ran before git push; the sync plan gate below runs before');
+    console.log('  the platform writes trunk rows or ComponentVariant overlays.');
   }
   const syncResponse = await syncComponentsCommand({
     ...flags,
@@ -4544,7 +4665,7 @@ async function commitComponentsCommand(flags) {
   });
 
   if (!skipGit) {
-    console.log('Phase 3/3: local fast-forward pull');
+    console.log('Phase 4/4: local fast-forward pull');
     runGit(cwd, 'git fetch origin ' + shellQuote(branchName));
     const expectedSha = syncResponse && syncResponse.sync && syncResponse.sync.postSyncSha;
     if (expectedSha) {
@@ -11144,13 +11265,13 @@ function printComponentsHelp(subcommand) {
   if (subcommand === 'commit') {
     console.log('Usage: remits-cli components commit [--safe] [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
     console.log('');
-    console.log('Runs local git add/commit/push, then server sync. Prefer explicit git + components sync when you need inspectable phases.');
+    console.log('Runs staged compile validation, local git add/commit/push, server sync, then fast-forward pull.');
+    console.log('Prefer explicit stage + git + components sync when you need inspectable phases.');
     console.log('components commit does not support --dry-run.');
     console.log('');
-    console.log('--safe passes the sync gates through to phase 2. The honest limit: git push happens in phase 1,');
-    console.log('so the gate stops the PLATFORM from writing a surprising plan — it cannot un-push the branch.');
-    console.log('For a gate that runs before anything leaves your machine, push yourself and use');
-    console.log('`remits-cli components sync --safe`.');
+    console.log('Phase 1 merge-stages the git-changed components and compile-validates their runtime source.');
+    console.log('It uses --changed-only semantics, so it never reconciles a lane you share with another agent.');
+    console.log('--safe also gates the server sync plan before any trunk rows or ComponentVariant overlays are written.');
     return;
   }
   console.log('Usage: remits-cli components <stage|status|lanes|entries|clear|sync|commit|promotion|branches|branch>');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.120",
+  "version": "0.1.122",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -60,6 +60,12 @@ reference named after it.
 - **edit → stage → run, every time.** The platform executes whatever is in the staging cache at the
   moment a run starts. Edit a file, run a test without `remits-cli components stage`, and the test runs
   the OLD code. This is the single most common mistake. (`development-loop.md`)
+- **Staging and sync fail early on broken runtime-compiled Groovy.** Stage validates changed source in the
+  active lane; sync validates changed/new compiled components before writing DB rows or branch variants.
+  Agent files are Utility components internally. A stage refused BY COMPILE VALIDATION still wrote the
+  lane — the compile has to resolve through the staged overlay to see the source it is judging — so fix and
+  re-stage before running anything in that lane. (A policy or edit-lease refusal is the opposite: it
+  returns before any write.) (`development-loop.md`, `component-integrity.md`, `branch-variants.md`)
 - **Stage your WORKSET, not the whole repo: `remits-cli components stage --workset`.** It uploads only
   the components git reports changed and makes the lane hold exactly them. A plain `components stage` is
   a FULL SNAPSHOT — it puts every component in the repo into the lane, so "115 staged" tells a human

package/skills/remits-cli/references/branch-variants.md

@@ -222,6 +222,12 @@ remits-cli components sync --dry-run # inspect overrides/additions/tombstones wi
 remits-cli components sync           # writes ComponentVariant overlays ONLY
 ```
 
+`components stage` validates changed runtime-compiled source through the active branch/workspace lane,
+and `components sync` validates changed/new Groovy source before writing a `ComponentVariant`. This is
+intentional: a branch overlay that cannot compile should fail at staging/sync time, not later when the
+subscriber's workflow first resolves it. `Agent` files in `components/agents/` are the `Utility`
+component kind internally; the CLI and validator normalize both names to the same target.
+
 Promotion back to trunk is a **git** operation followed by a **trunk** sync — the platform merges nothing
 for you, and merging a branch promotes its **deletions** as hard deletes. Do not improvise it: follow
 `features/subscriber-branch-promotions.md`. For a real trunk promotion with many `new_` files, use
@@ -330,7 +336,8 @@ The analogous hazard is different, and you must still respect it:
   `removed`, `unchanged`, `skipped`, and `errors` without writing rows, caching the sync SHA, or clearing
   staging. Existing overlay ids appear as `variantId`; an `unchanged` row with `pruned:true` means the
   branch has converged back to trunk and the overlay would be removed. It is rejected on trunk, and
-  `components commit --dry-run` is unsupported because `commit` performs local git writes before syncing.
+  `components commit --dry-run` is unsupported because `commit` performs compile validation and local git
+  writes before syncing.
 - **The sync refuses a wholesale removal.** Above roughly a third of a kind — or **100% of a kind at any
   size** — it aborts that kind, reports why, and points at a rebase. Rebasing is almost always the real
   fix. Only when the removals are genuinely deliberate, re-run with `--force-tombstones`.

package/skills/remits-cli/references/command-reference.md

@@ -198,7 +198,7 @@ remits-cli components lanes [--json]                         # every indexed sta
 remits-cli components entries --lane-id <id> [--json|--verbose]  # authoritative staged files for one lane
 remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
 remits-cli components sync [--safe [--yes]] [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
-remits-cli components commit [--safe] [--message "msg"] [--data-mode test|prod] [--force-tombstones]   # --safe gates phase 2; it cannot un-push phase 1
+remits-cli components commit [--safe] [--message "msg"] [--data-mode test|prod] [--force-tombstones]   # phase 1 merge-stages + compile-validates changed source (never reconciles the lane); --safe gates sync writes
 remits-cli components branches [--json]                                # branches carrying committed variants, with counts + drift
 remits-cli components branch <name> [--json]                           # one branch: overridden / added / removed, drift flags, subscribers
 remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]

package/skills/remits-cli/references/component-integrity.md

@@ -87,21 +87,41 @@ every live component present at its real id, and nothing extra.
 
 | Command | What it touches | Danger |
 |---|---|---|
-| `remits-cli components stage` (alias: deprecated `push`) | **Redis staging cache only.** Never mutates the DB or git. The safe iteration surface. | none |
+| `remits-cli components stage` (alias: deprecated `push`) | **Redis staging cache only.** Never mutates the DB or git. The safe iteration surface. A plain stage or `--workset` RECONCILES the lane (entries outside the manifest are dropped); `--changed-only` merges. | none for the DB; a lane you share with another agent is reconciled by the first two |
 | `remits-cli components status` | Reads this lane's staging scope (account/user/branch/workspace) and branch resolution, and lists every other lane on the branch. | none |
 | `remits-cli components clear` | Clears THIS lane's staging cache without changing DB or git. Never touches another workspace lane. | none |
 | `remits-cli components sync` **on trunk** | **Server-side git→DB reconcile of the whole account** (create/update/**delete**/rename). Reads the pushed remote; ignores local files. | **high** |
 | `remits-cli components sync` **on a variant branch** | Writes `ComponentVariant` overlays for that branch only. Never touches trunk rows or the account's trunk branch. When the checkout identifies a subscribing account, the branch-local `account-info.json` is refreshed for that subscriber; `--dry-run` reports the plan without writes. | medium (a missing file becomes a **tombstone** that hides the component from subscribers) |
-| `remits-cli components commit` | **One shot:** `git add -A` + commit + `git push` + **`components sync`** + `git pull --ff-only`. Blindly stages the *entire* working tree (including any drift) and reconciles it into prod. Inherits the danger of whichever sync mode the branch selects. | **highest on trunk** |
+| `remits-cli components commit` | **One shot:** changed-source compile validation (a `--changed-only` MERGE stage, so it never reconciles the lane) + `git add -A` + commit + `git push` + **`components sync`** + `git pull --ff-only`. Blindly stages the *entire* working tree (including any drift) and reconciles it into prod. Inherits the danger of whichever sync mode the branch selects. | **highest on trunk** |
 
 Key implications:
-- **`stage` is always safe** — stage and test as much as you want; it never reconciles or deletes.
-- **`components commit` is the most dangerous command**, not a mere convenience wrapper: it `git add -A`
-  commits and pushes whatever is in the working tree, then immediately syncs. Never run it while the tree
-  contains drift or unexplained changes. Prefer the explicit, observable
-  `git commit → git push → components sync → git pull` sequence so each phase can be inspected.
+- **`stage` never touches the DB or git** — stage and test as much as you want. It is safe *for your
+  components*; it is not inert *for the lane*. A full snapshot and `--workset` both reconcile the lane to
+  their manifest, so on a lane shared with another agent they drop that agent's staged entries. Use
+  `--changed-only` when you mean "add mine, leave theirs".
+- **A COMPILE-VALIDATION refusal still wrote the lane; a policy refusal does not.** Read the status code,
+  because the two refusals leave opposite states behind:
+  - **422 (compile validation)** — the entries are already stored. Validation runs after the write because
+    the compile has to resolve through the staged overlay to see the source it is judging. The response
+    says so with `laneHoldsRejectedSource`. Until you fix the source and re-stage, a run in that lane
+    resolves the broken component.
+  - **409 (account policy, or another agent's edit lease)** — refused before anything was written. The lane
+    is exactly as it was; nothing to undo.
+- **"Compile validation: NOT RUN" is a real answer.** The check keys off the git changed set. If git
+  cannot identify one — you are not in a working tree, or git failed — there is no workset to validate and
+  the CLI says `workset-unknown` rather than implying a pass.
+- **`components commit` is the most dangerous command**, not a mere convenience wrapper: it first
+  merge-stages and compile-validates the changed runtime source, then `git add -A`, commits, pushes, and
+  immediately syncs. Never run it while the tree contains drift or unexplained changes. Prefer the explicit,
+  observable `components stage → git commit → git push → components sync → git pull` sequence so each
+  phase can be inspected.
 - **`components sync` acts on the pushed remote**, so local edits are invisible to it until committed **and
   pushed**, and a drifted **remote** is dangerous even when your local tree looks fine.
+- **Runtime-compiled component source is validated before durable writes.** When a trunk sync or variant
+  sync sees changed/new Groovy source for a `Reader`, `Action`, `Embeddable`, `HtmlTemplate`, `Rule`,
+  `Test`, `Agent`/`Utility`, or `Tool`, the platform compiles it before accepting the DB row or
+  `ComponentVariant` overlay. A compile failure lands in `syncResults.errors` and the branch SHA cache is
+  not advanced, so fix the source and retry the same sync.
 - After a successful non-dry-run `components sync` / `components commit`, the server clears the full
   staging scope for that lane (account/user/branch/workspace). This is the expected clean state: old Redis aliases should not keep shadowing
   the newly synced DB rows. `components sync --dry-run` intentionally leaves staging untouched.

package/skills/remits-cli/references/development-loop.md

@@ -218,6 +218,28 @@ remits-cli components stage --workset    # every edit: stage what you changed
 
 This uploads your local component changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
 
+For runtime-compiled components (`Reader`, `Action`, `Embeddable`, `HtmlTemplate`, `Rule`, `Test`,
+`Agent`/`Utility`, and `Tool`), staging also validates the Groovy source that is part of the submitted
+workset. Validation resolves through the same branch/workspace staging lane a later run will use and
+compiles candidates in a small bounded pool, so a syntax/compile error is reported by `components stage`
+instead of waiting for the next workflow to trip over it. A full repository stage does not compile every
+component in the repo; it validates only entries known to be in the current workset, plus explicit partial
+source updates.
+
+Two things to read correctly when it refuses:
+
+- **The lane already holds what it rejected — on a 422.** The compile has to resolve through the staged
+  overlay to see the source it is judging, so the entries are written first and compiled second. `422`
+  means "staged, and rejected", not "nothing happened" — fix the source and re-stage before running
+  anything in that lane. A `409` is the other kind of refusal (account policy, or another agent's edit
+  lease) and writes nothing at all.
+- **Every failure is printed, not just the first.** The one-line error is the first failure; the full list
+  (identified by type and id) follows it. Fix them in one pass rather than one round trip each.
+
+If git cannot identify the changed set — you are not in a working tree, or git failed — there is no
+workset to validate, and the CLI prints `Compile validation: NOT RUN — workset-unknown` rather than
+silently implying a pass.
+
 ##### Stage your workset, not the whole repo
 
 There are three stage modes, and the difference decides what a run in your lane resolves and what a
@@ -321,7 +343,7 @@ If no relevant Test component exists yet, consider creating one. Test components
 
 New test files use the `new_` prefix (e.g., `new_MyTest.groovy`) and no `id:` in the sidecar — see "Creating a component that does not exist yet" in Step 2. Run them **by name** (`remits-cli test run --test "My Test"`) until a sync assigns an id and renames the file.
 
-**How to write the Test itself is not a CLI concern** — what a suite can assert, how mocks behave across HTTP/relay boundaries, driving an embeddable in-process, and the front-stage-only rule all live in `guides/components/test-components.md`. Read that before authoring a suite.
+**How to write the Test itself is not a CLI concern** — what a suite can assert, how mocks behave across HTTP/relay boundaries, driving an embeddable in-process, and the front-stage-only rule all live in `guides/test-components.md`. Read that before authoring a suite.
 
 **Option B — Visual verification with Playwright** (for UI changes or when the user wants to "see it"):
 
@@ -362,7 +384,7 @@ They are not interchangeable. The loader's request carries **no path**, so it re
 purely from the embeddable-scoped token key's persisted context. The browser `tokenKey` names the account
 preview URL; `embedTokenKey` names the host-loader credential. The response also echoes `injectionType` /
 `renderMode` / `headMode`, which decide what a host actually receives
-(`guides/components/embeddable-components.md`).
+(`guides/embeddable-components.md`).
 
 **This works for a `new_` component that has never been synced.** The embed token key carries the
 component NAME as well as its id, so a staged, id-less Embeddable is loader-addressable — you do not