softr-vibe-coding 2.8.0 → 2.8.2

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this skill are documented here. Versions follow [Semantic
 
 Entries from 1.3.1 onward are generated automatically from git commit subjects between version bumps (see `.github/workflows/publish.yml`). Entries before 1.3.1 were backfilled by hand from the existing commit history.
 
+## [2.8.2] - 2026-09-10
+- Corrections on evidence: Softr never strips the trailing newline; the array-argument rejection was client-side stringification, not an empty server schema (2.8.2)
+
+## [2.8.1] - 2026-09-10
+- Verifying a push: errors:null is not proof — fetch-back byte-compare, deployed==disk pre-check, two-block swaps (2.8.1)
+- Inventory + keyboard-picker snippet reconciled with the shipped projects-table shape
+
 ## [2.8.0] - 2026-09-09
 - Dropdowns searchable by default, reset controls only when dirty, create → open the new record
 

package/README.md

@@ -185,7 +185,7 @@ softr-vibe-coding/
 │   │                                 # Scripting Extension, cross-table cascades,
 │   │                                 # batch update gotchas, field-ID discipline,
 │   │                                 # Airtable formulas
-│   ├── softr-mcp.md                  # Official Softr MCP server — vibe coding block
+│   ├── softr-mcp.md                  # Official Softr MCP server — vibe coding block (+ push verification protocol)
 │   │                                 # tools (create/edit/version/deploy), integrations
 │   │                                 # browsing (Airtable/Sheets/Notion/Supabase),
 │   │                                 # Softr DB schema + record tools incl. deletes,
@@ -204,7 +204,7 @@ softr-vibe-coding/
 │   ├── anti-patterns.md              # Categorized violation catalog
 │   │                                 # Data access, mutations, hooks, layout,
 │   │                                 # permissions, editable settings, helper blocks
-│   ├── common-patterns.md            # Small reusable patterns
+│   ├── common-patterns.md            # Small reusable patterns (localStorage state, clipboard, nav blocker, drag-to-reorder, create → open, clickable row + inner link, keyboard picker)
 │   │                                 # localStorage cross-page state, clipboard copy,
 │   │                                 # navigation blocker, scroll-condensing header,
 │   │                                 # auth-aware CTA, image masks, blobs, dot lists

package/SKILL.md

@@ -89,6 +89,7 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
    - Static block: no hardcoded user-visible copy — every string/image/link is an editable setting (see [references/editable-settings.md](references/editable-settings.md#granularity-doctrine-settings-first-static-blocks))
    - Array-setting rows keyed by **index**, never by a builder-editable field value
    - Media settings that may start empty (`src: ""`) gated with a conditional render or placeholder — never an unconditional `<img src={setting.src}>`
+   - **Deploying through the MCP:** `errors: null` on a push is not proof — fetch the block's `sourceCode` back and byte-compare it to the file you sent, trailing newline included (Softr stores exactly what it receives; the one-byte drift we once blamed on it was a chunked read on our side), and prove deployed == disk *before* editing so a Studio-side change is never overwritten. Protocol in [references/softr-mcp.md → Verifying a push](references/softr-mcp.md#verifying-a-push--the-deployed-source-is-the-only-proof)
 
 ## What to Clarify
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "Claude Code skill for generating production-ready Softr Vibe Coding blocks (JSX). Installs into ~/.claude/skills/ and auto-updates on each Claude Code session.",
   "bin": {
     "softr-vibe-coding": "./bin/cli.js"

package/references/common-patterns.md

@@ -513,4 +513,6 @@ function onKeyDown(e) {
 <input autoFocus value={query} onChange={function (e) { setQuery(e.target.value); setActive(0); }} onKeyDown={onKeyDown} … />
 ```
 
+Make the rows themselves focusable too (`tabIndex={0}`, an `onKeyDown` that opens on Enter only when `event.target === event.currentTarget`, so an Enter on the anchor inside the row is not handled twice), and let `onMouseEnter` *and* `onFocus` both move the highlight onto the row — the highlight is the single answer to "which record does Enter open", whichever device last touched it. That is the shape `projects-table.jsx` shipped on 2026-09-10.
+
 Paint the highlighted row with the same colour the mouse hover gets (`data-active="true"` + `bg-[#FFF7EF]`) and scroll it into view when it moves (`querySelector('[data-active="true"]').scrollIntoView({ block: "nearest" })` in a `useEffect` on `activeIdx`) — the Combo in [searchable-dropdown.md](searchable-dropdown.md#one-flat-row-list-for-the-keyboard) does the same. Reset `active` to 0 whenever the query changes: the old index points at a row that may no longer be in the list. `autoFocus` is right only when the block *is* the page's reason to exist — an index page whose first act is always a search; on a page with content above the table, a focus steal scrolls the page to the box.

package/references/softr-mcp.md

@@ -101,35 +101,94 @@ components, adding a hook — where being sure of "the exact current text" of a
 is harder than being sure of the whole file. Also use it when the local file is the source of truth and
 has drifted from the deployed block in ways you have not enumerated.
 
-### The array-argument serialization quirk, and why it is a security issue
-
-**Several tools on this server take an array argument, and some MCP clients serialize it as a JSON
-*string* instead.** The API then rejects it with a Jackson error before it reaches any business logic:
+### Verifying a push — the deployed source is the only proof
+
+`update_vibe_coding_block_code` returning `errors: null, warnings: null` proves the code **compiled**.
+It does not prove the block now holds the code you meant to send. Verified 2026-09-09: a push of a
+67KB block came back clean and had silently dropped one blank line at a read-chunk boundary — valid
+JavaScript, so the compiler had nothing to say. Only a byte comparison caught it. Treat every push as
+unverified until you have pulled the source back down and compared it.
+
+**The protocol, per block:**
+
+1. **Before editing, prove deployed == disk.** Call `get_vibe_coding_block_code`, extract
+   `sourceCode`, and compare it byte-for-byte to your local mirror. If they differ, someone changed
+   the block in Studio since your last push — stop and reconcile; do not overwrite work you have not
+   seen. (Large results are persisted to a file by most clients rather than returned inline; compare
+   from that file with a script, never by eye.)
+2. Edit the local file. Run a parser and `no-undef` lint on it first — `node --check` does **not**
+   accept a `.jsx` extension, so use esbuild (`esbuild file.jsx --loader:.jsx=jsx --jsx=automatic
+   --log-level=error --outfile=/dev/null`) plus eslint with `@babel/eslint-parser`. The bugs that
+   actually bite Softr blocks are semantic — `useRecordUpdate({ select: … })` instead of `fields:`,
+   an invented identifier — and the push is the first thing that reports them.
+3. Push the **entire** file.
+4. **Fetch it back and compare again.** Identical, or you are not done: diff, fix, re-push.
+
+**Compare byte for byte, trailing newline included.** Softr stores exactly what it receives: across
+58 push→fetch pairs between 2026-08-26 and 2026-09-10 (14 blocks, 16–161 KB each) the fetched
+`sourceCode` was byte- and MD5-identical to the text sent, including two pushes sent *without* a
+final newline and stored without one. The "deployed block is one byte shorter" we chased on
+2026-09-09 was our own read: an agent that reads a large file in chunks can drop the final
+newline (or a blank line at a chunk boundary) before transmission. A comparison that normalises
+the trailing newline hides exactly that class of error — so do not normalise anything; a mismatch
+means re-send, whatever the byte.
+
+**One file, two blocks, two datasource pairs.** When the same source is deployed to two pages, the
+local file holds ONE page's `datasource.define()` pair. Push it as-is to that block; for the other,
+build the swapped text in a scratch location, push that, and verify each block against its own
+expectation (disk for the first, disk-with-swap for the second). Never save the swapped copy over
+the local mirror — the mirror records which page it belongs to, and the block's header comment
+records the other page's pair. Search-replace would avoid the swap altogether
+([above](#which-edit-tool-full-replace-vs-targeted-search-replace)) — when the client can send its
+array argument ([below](#the-array-argument-serialization-quirk-and-why-it-is-a-security-issue)).
+
+**Do not read a 100KB block into a model's context to push it.** The full-replace tool takes the
+whole file as a string parameter, so the source has to pass through whatever is making the call. A
+large multi-block deploy is safer farmed out one file per subagent — a fresh context per file means
+no compaction can land mid-file — and the byte comparison is what makes that delegation safe, not
+trust in the agent. The steps that need judgement are the *edit* and the *review of the diff*; the
+fetch, the compare and the push itself are mechanical, and can run on the cheapest tier available
+without lowering the bar, because a wrong result fails loudly rather than plausibly.
+
+**What a push also resets.** Every code push puts the block's derived Actions back on Softr's
+default permissions (see the next section for why that can be a security problem and how to verify
+the restoration). If page-level visibility is the access control in your app, record that decision
+so nobody chases the reset after every round; if it is not, re-tighten and read back.
+
+### The array-argument rejection, and why it is a security issue
+
+**Several workspace-server tools take an array argument, and a call that sends it as a JSON *string*
+is rejected** by Jackson before it reaches any business logic:
 
 ```
 Cannot deserialize value of type `java.util.ArrayList<java.util.Map<String,Object>>`
 from String value (token `JsonToken.VALUE_STRING`)
 ```
 
-Root cause: the server advertises an **empty schema** for its tools (`{"type":"object"}`, no property
-definitions), so a client has no type information to serialize against. Confirmed 2026-09-09 on:
-
 | Tool | Array argument | Fallback if it fails |
 |---|---|---|
 | `update_vibe_coding_block_code_search_replace` | `operations` | Use `update_vibe_coding_block_code` (full replace) |
 | `set_vibe_coding_block_action_visibility` | `updates` | **NONE — a human must fix it in Studio** |
 
-It is intermittent, and that is the trap: on 2026-09-09 both tools accepted the array early in a
-session and rejected it an hour later, same shapes, same session. Do not conclude from one success
-that the path is reliable for the rest of your work.
-
-**Why the second row is a security problem, not an inconvenience.** Every code push resets the block's
-auto-registered Actions to Softr's defaults, and the default for a `genericActions` **ADD_RECORD is
-`ALL_USERS`** — writable by logged-OUT visitors. The documented remedy is to re-tighten with
-`set_vibe_coding_block_action_visibility`. When that call is the one that fails, a routine cosmetic push
-silently leaves public write access on the block, and nothing in the push result says so: the push
-itself returns `errors: null, warnings: null`. Verified live 2026-09-09 — one push left four ADD_RECORD
-actions open across two blocks.
+**Where the string comes from — corrected 2026-09-10.** The first write-up of this (2026-09-09)
+blamed the server for advertising an empty schema. The transcripts say otherwise: the workspace
+server's schema declares both parameters as `type: array`, all 13 rejected calls had sent a JSON
+string, and all 84 successful calls to the same two tools had sent a real array — same day, same
+shapes, different payload type. The stringification happened on the client side, most likely on
+calls made while the tool definitions had not been loaded into the model's context (deferred
+schemas), so there was no type to serialise against. **Load the tool's schema before calling it,
+and pass arrays as arrays.** (Empty schemas are real on Softr's *per-application* MCP servers —
+every tool there is advertised as `{"type":"object"}` with a name-only description — but the
+workspace server is not affected.)
+
+**Why the second row is a security problem, not an inconvenience.** Every code push resets the
+block's auto-registered Actions to Softr's defaults, and the default for a `genericActions`
+**ADD_RECORD is `ALL_USERS`** — writable by logged-OUT visitors — while UPDATE_RECORD and
+DELETE_RECORD default to `LOGGED_IN_USERS` in the same response. The documented remedy is to
+re-tighten with `set_vibe_coding_block_action_visibility`. When that call is the one that fails, a
+routine cosmetic push silently leaves public write access on the block, and nothing in the push
+result says so: the push itself returns `errors: null, warnings: null`. Verified live 2026-09-09 —
+one push left four ADD_RECORD actions open across two blocks.
 
 **So treat permission restoration as a step that must be VERIFIED, never assumed:**