softr-vibe-coding 1.8.0 → 1.10.0

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.
 
+## [1.10.0] - 2026-06-04
+- Bundle get-airtable-base CLI script for full base metadata export; document in SKILL.md, airtable.md, fields.md
+
+## [1.9.0] - 2026-06-04
+- Bundle get-softr-database CLI script for schema export; document in SKILL.md, softr-database.md, fields.md
+- Bump publish workflow to Node 24-based action majors — actions/checkout@v4 -> @v6, actions/setup-node@v4 -> @v6 (clears the Node 20 deprecation; GitHub forces Node 20 actions to Node 24 on 2026-06-16). No version bump, so this run skips publish.
+
 ## [1.8.0] - 2026-06-04
 - Expand references/native-chrome-styling.md to the full native shell — add Footer (semantic <footer> target + 160px/overflow-wrap contact-column email-wrap fix), floating "island" header/footer treatment, and Page background (Softr stacks the same fill on html/body/#page-content/inner-wrapper, so paint on html + clear the stack, EXCLUDING the .softr-topbar subtree so the dropdown panel survives) + a Console background-finder snippet; broaden SKILL.md Reference Guides row + README; add anti-patterns row for the page-background stacking; bump to 1.8.0
 

package/SKILL.md

@@ -86,8 +86,9 @@ When the user describes their block, figure out which of these areas apply and a
 
 - **Data source type**: Is it Airtable, Softr Database, REST API, or another source? This determines the data fetching approach. **Load the relevant data source guide** from the [datasources/](datasources/) directory before writing code.
 - **Data source fields**: For Airtable/Softr Database, you need actual field IDs. For REST APIs, you access the raw API response directly. If the user doesn't know field IDs:
-  - For **Softr Database**, the cleanest path is the **Softr Database MCP server** — ask whether they have it installed (`claude mcp list` shows it as `softr` or similar). If yes, query schema directly with the MCP tools instead of asking for paste-ins. If no, fall back to asking them to paste the `tablespace-with-tables` network response (DevTools -> Network -> filter that string while on Studio's Data tab) — the JSON contains every field ID, type, and dropdown option UUID. Optionally tell them they can install the MCP once with `claude mcp add --transport http softr https://mcp.softr.io/mcp` for future sessions. Full MCP details in [references/softr-database-mcp.md](references/softr-database-mcp.md); fallback paste-in workflows in [datasources/fields.md](datasources/fields.md#field-inspector-block).
-  - For **Airtable** and other sources where empty `q.select({})` works, suggest the Field Inspector block.
+  - For **Softr Database**, the cleanest path is the **Softr Database MCP server** — ask whether they have it installed (`claude mcp list` shows it as `softr` or similar). If yes, query schema directly with the MCP tools instead of asking for paste-ins. If no, the next-best option is the bundled **`get-softr-database` CLI script** — tell the user to run `python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py <database_id>` (it prompts for their Softr API key and exports the full schema to `~/Desktop/softr-database-<id>-<timestamp>.json` — Python stdlib only, nothing to install) and paste the resulting JSON into chat. As a final fallback, ask them to paste the `tablespace-with-tables` network response (DevTools -> Network -> filter that string while on Studio's Data tab) — same JSON content, different acquisition path. Optionally tell them they can install the MCP once with `claude mcp add --transport http softr https://mcp.softr.io/mcp` for future sessions. Full MCP details in [references/softr-database-mcp.md](references/softr-database-mcp.md); CLI script details in [datasources/softr-database.md](datasources/softr-database.md#bundled-cli-script-get-softr-database); fallback paste-in workflows in [datasources/fields.md](datasources/fields.md#field-inspector-block).
+  - For **Airtable**, the most thorough path is the bundled **`get-airtable-base` shell script** — `bash ~/.claude/skills/softr-vibe-coding/tools/get-airtable-base` (requires `jq` — `brew install jq` on macOS). It prompts for Base ID + PAT, then exports the full schema (every table, every field with both `fld...` IDs and column names, relationships, webhooks, interfaces) to a timestamped Desktop folder. The user pastes `02-schema.json` or the combined `00-bundle.json` into chat. For lighter inspection (just a few fields, runtime-only), suggest the Field Inspector block — empty `q.select({})` works for Airtable. CLI script details in [datasources/airtable.md](datasources/airtable.md#bundled-cli-script-get-airtable-base).
+  - For other non-Softr-DB sources where empty `q.select({})` works, suggest the Field Inspector block.
 - **Brand colors**: Already resolved in Step 1 (Detect the brand source). Don't re-ask. The brand source is one of:
   - **Project's `./DESIGN.md`** (recommended for client work — produced by the `building-design-md` skill)
   - **User's quick override** (paste of primary + accent + font)

package/bin/cli.js

@@ -10,7 +10,7 @@ var SETTINGS_FILE = path.join(os.homedir(), '.claude', 'settings.json');
 var PACKAGE_ROOT = path.resolve(__dirname, '..');
 
 var SKILL_FILES = ['SKILL.md', 'ui-ux-guidelines.md', 'README.md', 'LICENSE'];
-var SKILL_DIRS = ['references', 'datasources'];
+var SKILL_DIRS = ['references', 'datasources', 'tools'];
 
 var HOOK_COMMAND = 'npx -y --prefer-online ' + SKILL_NAME + '@latest sync';
 

package/datasources/airtable.md

@@ -55,6 +55,62 @@ The asymmetry matters because reads silently degrade while writes silently disab
 
 3. **Avoid renaming columns mid-project** -- use Airtable's Description field for clarification instead.
 
+## Bundled CLI script: `get-airtable-base`
+
+A Bash CLI bundled with this skill that exports an Airtable base's full metadata to a timestamped folder on your Desktop. Pulls schema, relationships, sync detection, webhooks, interfaces, and shares — everything the Airtable Web API exposes for a single base.
+
+**Script location after `npx softr-vibe-coding@latest init`:**
+
+```
+~/.claude/skills/softr-vibe-coding/tools/get-airtable-base
+```
+
+**Requirements:** `jq` (`brew install jq` on macOS), `curl` (preinstalled on macOS/Linux), Bash.
+
+**Run it:**
+
+```bash
+bash ~/.claude/skills/softr-vibe-coding/tools/get-airtable-base
+```
+
+The script prompts interactively for:
+
+- **Base ID** (e.g. `appXXXXXXXXXXXXXX` — find it in the Airtable URL or the API docs page for the base).
+- **Personal Access Token** (input hidden — needs `schema.bases:read` scope minimum, plus `webhook:manage` for webhooks, and optionally `enterpriseAccount:read` for shares).
+
+**Output folder:** `~/Desktop/airtable-base-<BASE_ID>-<UTC-timestamp>/` containing:
+
+| File | Contents |
+|---|---|
+| `00-bundle.json` | Combined bundle of all the below for easy sharing in one paste |
+| `01-base-info.json` | Collaborators, interfaces, invite links |
+| `02-schema.json` | Full schema: every table, every field (with both `fld...` IDs and column names), every view, `visibleFieldIds` per view |
+| `03-shares.json` | Enterprise-only shares — skipped on non-Enterprise plans |
+| `04-webhooks.json` | Registered webhooks |
+| `05-whoami.json` | Token identity and scopes — confirms which user/PAT was used and what it can access |
+| `06-relationships.json` | Derived from `02-schema.json`: sync destinations, cross-table links, lookup/rollup/count/formula field maps |
+
+After completion, the script opens the folder in Finder (macOS).
+
+**Optional alias** for a shorter command. Add to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+alias get-airtable-base='bash ~/.claude/skills/softr-vibe-coding/tools/get-airtable-base'
+```
+
+After `source ~/.zshrc`, run `get-airtable-base` from anywhere.
+
+**Getting a PAT:** https://airtable.com/create/tokens → Create token → grant `schema.bases:read` (add `data.records:read` only if you want to also read records via the Web API outside Softr). Scope to the specific base(s) the script should access.
+
+**When to use this:**
+
+- **Documenting field IDs alongside column names** in `q.select()` — the mitigation in [Maintainability gotcha](#maintainability-gotcha) above. Grep the `02-schema.json` for an `fld...` ID to find every block affected by a column rename.
+- **Bisecting a broken Action** when a column rename has silently disabled it — the freshest `02-schema.json` is the source of truth to grep against.
+- **Auditing relationships** (lookups, rollups, formulas, cross-table links, sync sources) — `06-relationships.json` summarizes everything the schema reveals about derived/referenced fields.
+- **Sharing schema with an AI assistant** — paste `00-bundle.json` (or just `02-schema.json` if smaller) into chat to give the assistant accurate, current schema context.
+
+This script reads only **metadata**, never records. To inspect record contents inside a Vibe Coding block, use the Field Inspector pattern in [fields.md](fields.md#field-inspector-block).
+
 ## Supported Fields
 
 | Field Type           | Writable  | Notes |

package/datasources/fields.md

@@ -107,19 +107,23 @@ export default function Block() {
 }
 ```
 
+**For Airtable specifically, the bundled `get-airtable-base` script is a more comprehensive alternative** — it exports the full base schema (every table, every field with `fld...` IDs and column names, relationships, webhooks, interfaces) to a Desktop folder via the Airtable Web API. Run with `bash ~/.claude/skills/softr-vibe-coding/tools/get-airtable-base` (requires `jq` — `brew install jq` on macOS). Best when you want a portable schema snapshot, are documenting field IDs alongside column names per the [airtable.md maintainability mitigation](airtable.md#maintainability-gotcha), or need to audit lookup/rollup/sync relationships. Full usage in [airtable.md](airtable.md#bundled-cli-script-get-airtable-base).
+
 **For Softr Database, find field IDs via:**
 
 1. **Softr Database MCP server (recommended for AI-assisted workflows)** -- if you're collaborating with an AI assistant (Claude Code, Claude Desktop, Cursor, ChatGPT, Mistral) to write Vibe Coding blocks, the official Softr MCP server is the cleanest path. The AI calls schema/list-fields tools directly against your workspace and reads back every field's `id`, `name`, `type`, and dropdown option UUIDs -- no copy-paste, no transcription errors. Full setup, scopes, and scope limitations (Softr DB only -- does NOT cover Airtable / external sources) in [../references/softr-database-mcp.md](../references/softr-database-mcp.md).
 
-2. **Network inspector (full schema in one shot, no MCP needed)** -- in Studio's Data tab with browser DevTools open, filter Network requests by `tablespace-with-tables`. The Response JSON contains every table's complete schema, including:
+2. **`get-softr-database` CLI script (bundled, no MCP needed)** -- a Python CLI bundled with this skill at `~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py`. Exports the full schema (every table, every field, all dropdown option UUIDs) to `~/Desktop/softr-database-<id>-<timestamp>.json`. Run with `python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py <database_id>` (prompts for API key) or set `SOFTR_API_KEY=xxx` env var to skip the prompt. Stdlib only, no `pip install`. Best when you want a portable JSON dump for sharing in chat, archiving, or diffing across schema versions. Full usage in [softr-database.md](softr-database.md#bundled-cli-script-get-softr-database).
+
+3. **Network inspector (full schema in one shot, no MCP needed)** -- in Studio's Data tab with browser DevTools open, filter Network requests by `tablespace-with-tables`. The Response JSON contains every table's complete schema, including:
    - Each field's `id`, `name`, `type`, and `options`
    - For dropdown / SELECT fields: the full `choices` array with every option's `id` (UUID), `label`, and `color`
 
    Use this when scaffolding a block that needs many field IDs at once, or to look up dropdown option UUIDs needed for write payloads. **When working with an AI assistant without the MCP installed**, paste this JSON response into the chat -- second-best way to share accurate field IDs and dropdown UUIDs in one shot.
 
-3. **Inline in Studio (one field at a time)** -- in the Data tab, click a field's name to open its edit drawer. The field ID appears next to the "Field name" label (e.g. `ID: 37fts`). Fastest for spot-checking a single field.
+4. **Inline in Studio (one field at a time)** -- in the Data tab, click a field's name to open its edit drawer. The field ID appears next to the "Field name" label (e.g. `ID: 37fts`). Fastest for spot-checking a single field.
 
-4. **Softr Database REST API with `fieldNames=true`** -- runtime inspection from inside a Vibe Coding block (internal-portal blocks only, since this exposes a PAT in client code):
+5. **Softr Database REST API with `fieldNames=true`** -- runtime inspection from inside a Vibe Coding block (internal-portal blocks only, since this exposes a PAT in client code):
 
 ```jsx
 import { useEffect, useState } from "react";

package/datasources/softr-database.md

@@ -24,11 +24,62 @@ q.select({ name: "First Name" })
 Find field IDs in this order of preference:
 
 1. **Softr Database MCP** (recommended when working with an AI assistant) — the AI calls schema/list-fields tools directly. See [../references/softr-database-mcp.md](../references/softr-database-mcp.md).
-2. **Network inspector** — DevTools -> Network -> filter `tablespace-with-tables` for the full schema including dropdown option UUIDs. Paste the JSON into chat to share with an AI when the MCP isn't installed.
-3. **Inline in Studio** — click a field's name in the Data tab; the ID appears in the field-edit drawer.
+2. **`get-softr-database` CLI script (bundled)** — a Python CLI bundled with this skill at `~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py`. Exports the full schema (every table, field, dropdown option UUID) to `~/Desktop/softr-database-<id>-<timestamp>.json`. Stdlib only, no `pip install`. See [Bundled CLI script](#bundled-cli-script-get-softr-database) below.
+3. **Network inspector** — DevTools -> Network -> filter `tablespace-with-tables` for the full schema including dropdown option UUIDs. Paste the JSON into chat to share with an AI when the MCP isn't installed.
+4. **Inline in Studio** — click a field's name in the Data tab; the ID appears in the field-edit drawer.
 
 The generic Field Inspector pattern with empty `q.select({})` does NOT work for Softr Database — see [fields.md](fields.md#field-inspector-block).
 
+## Bundled CLI script: `get-softr-database`
+
+A Python CLI bundled with this skill that exports a complete Softr Tables database schema (every table, every field, all dropdown option UUIDs) to a timestamped JSON file on your Desktop. Stdlib only — no `pip install` required.
+
+**Script location after `npx softr-vibe-coding@latest init`:**
+
+```
+~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py
+```
+
+**Run it directly:**
+
+```bash
+python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py <database_id>
+```
+
+It prompts for your Softr API key (input hidden via `getpass`). To skip the prompt entirely, pass via env var:
+
+```bash
+SOFTR_API_KEY=xxx python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py <database_id>
+```
+
+Run with no args to be prompted for both the database ID and API key.
+
+**Output:** `~/Desktop/softr-database-<databaseId>-<YYYYMMDD-HHMMSS>.json` containing:
+
+```json
+{
+  "exportedAt": "...",
+  "source": "https://tables-api.softr.io/api/v1",
+  "databaseId": "...",
+  "database": { /* full database metadata */ },
+  "tableCount": N,
+  "fieldCount": M,
+  "tables": [ /* every table with its full fields[] array */ ]
+}
+```
+
+**Optional alias** for a shorter command. Add to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+alias get-softr-database='python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py'
+```
+
+After `source ~/.zshrc`, just run `get-softr-database <database_id>` from anywhere.
+
+**Get your Softr API key:** Softr workspace settings → API keys → create a new key with read access to the target database.
+
+**When to use vs the MCP:** the MCP server is better for AI-assisted workflows (the assistant calls schema tools directly without any user action). This CLI script is better when you want a portable JSON file — for sharing in chat, archiving alongside your project, diffing across schema versions, or pasting a single big blob into Claude. The two approaches don't conflict; many projects use both.
+
 ## Supported Fields
 
 | Field Type     | Writable | Notes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "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"
@@ -11,6 +11,7 @@
     "ui-ux-guidelines.md",
     "references/",
     "datasources/",
+    "tools/",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

package/tools/get-airtable-base

@@ -0,0 +1,303 @@
+#!/bin/bash
+#
+# get-airtable-base
+# Pulls all available metadata for a single Airtable base via the Web API
+# and saves it to a timestamped folder on the Desktop.
+#
+
+set -euo pipefail
+
+# ---------- Colors ----------
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+GRAY='\033[0;90m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+# ---------- Pre-flight ----------
+if ! command -v jq &>/dev/null; then
+  echo -e "${RED}Error: jq is not installed.${NC}"
+  echo "Install it with: brew install jq"
+  exit 1
+fi
+
+if ! command -v curl &>/dev/null; then
+  echo -e "${RED}Error: curl is not installed.${NC}"
+  exit 1
+fi
+
+# ---------- Banner ----------
+echo ""
+echo -e "${BOLD}${BLUE}╔════════════════════════════════════════╗${NC}"
+echo -e "${BOLD}${BLUE}║     Airtable Base Metadata Fetcher     ║${NC}"
+echo -e "${BOLD}${BLUE}╚════════════════════════════════════════╝${NC}"
+echo ""
+
+# ---------- Prompts ----------
+read -r -p "$(echo -e "${BOLD}Base ID${NC} (e.g. appXXXXXXXXXXXXXX): ")" BASE_ID
+if [[ -z "$BASE_ID" ]]; then
+  echo -e "${RED}Error: Base ID is required.${NC}"
+  exit 1
+fi
+if [[ ! "$BASE_ID" =~ ^app[a-zA-Z0-9]{14}$ ]]; then
+  echo -e "${YELLOW}Warning: '$BASE_ID' doesn't look like a standard Base ID (app + 14 chars). Continuing anyway...${NC}"
+fi
+
+read -r -s -p "$(echo -e "${BOLD}Personal Access Token${NC} (input hidden): ")" TOKEN
+echo ""
+if [[ -z "$TOKEN" ]]; then
+  echo -e "${RED}Error: PAT is required.${NC}"
+  exit 1
+fi
+
+# ---------- Output folder ----------
+TIMESTAMP=$(date -u +%Y-%m-%dT%H-%M-%SZ)
+OUTPUT_DIR="$HOME/Desktop/airtable-base-$BASE_ID-$TIMESTAMP"
+mkdir -p "$OUTPUT_DIR"
+
+echo ""
+echo -e "${GRAY}Output: $OUTPUT_DIR${NC}"
+echo ""
+
+AUTH=(-H "Authorization: Bearer $TOKEN")
+API="https://api.airtable.com/v0"
+
+# ---------- Helper ----------
+# fetch URL OUTFILE LABEL [optional]
+# Writes response to OUTFILE (jq-pretty). Returns 0 on HTTP 2xx, 1 otherwise.
+fetch() {
+  local url="$1"
+  local outfile="$2"
+  local label="$3"
+  local optional="${4:-false}"
+
+  local tmp http_code body
+  tmp=$(mktemp)
+  http_code=$(curl -s -o "$tmp" -w "%{http_code}" "${AUTH[@]}" "$url" || echo "000")
+
+  if [[ "$http_code" =~ ^2 ]]; then
+    if jq '.' "$tmp" >"$outfile" 2>/dev/null; then
+      local size
+      size=$(wc -c <"$outfile" | tr -d ' ')
+      echo -e "  ${GREEN}✓${NC} $label ${GRAY}(${size} bytes)${NC}"
+      rm -f "$tmp"
+      return 0
+    else
+      echo -e "  ${RED}✗${NC} $label ${GRAY}(invalid JSON response)${NC}"
+      mv "$tmp" "$outfile.raw"
+      return 1
+    fi
+  else
+    body=$(cat "$tmp")
+    rm -f "$tmp"
+    if [[ "$optional" == "true" ]]; then
+      echo -e "  ${YELLOW}-${NC} $label ${GRAY}(HTTP $http_code — skipped)${NC}"
+    else
+      echo -e "  ${RED}✗${NC} $label ${GRAY}(HTTP $http_code)${NC}"
+      echo -e "${GRAY}    $body${NC}" | head -c 300
+      echo ""
+    fi
+    return 1
+  fi
+}
+
+# ---------- Phase 1: Identity & access ----------
+echo -e "${BOLD}Phase 1: Validating token...${NC}"
+
+fetch "$API/meta/whoami" \
+  "$OUTPUT_DIR/05-whoami.json" \
+  "Token identity (whoami)" || {
+    echo -e "${RED}Cannot continue — token is invalid or revoked.${NC}"
+    exit 1
+  }
+
+if [[ -f "$OUTPUT_DIR/05-whoami.json" ]]; then
+  scopes=$(jq -r '.scopes // [] | join(", ")' "$OUTPUT_DIR/05-whoami.json" 2>/dev/null || echo "(unknown)")
+  user_id=$(jq -r '.id // "(unknown)"' "$OUTPUT_DIR/05-whoami.json" 2>/dev/null || echo "(unknown)")
+  echo -e "${GRAY}    User: $user_id${NC}"
+  echo -e "${GRAY}    Scopes: $scopes${NC}"
+fi
+
+# ---------- Phase 2: Base schema + metadata ----------
+echo ""
+echo -e "${BOLD}Phase 2: Fetching base metadata...${NC}"
+
+fetch "$API/meta/bases/$BASE_ID?include=collaborators&include=interfaces&include=inviteLinks" \
+  "$OUTPUT_DIR/01-base-info.json" \
+  "Base info (collaborators, interfaces, invite links)" \
+  true || true
+
+fetch "$API/meta/bases/$BASE_ID/tables?include[]=visibleFieldIds" \
+  "$OUTPUT_DIR/02-schema.json" \
+  "Schema (tables, fields, views with visibleFieldIds)" || {
+    echo -e "${RED}Cannot continue without schema. Exiting.${NC}"
+    exit 1
+  }
+
+fetch "$API/meta/bases/$BASE_ID/shares" \
+  "$OUTPUT_DIR/03-shares.json" \
+  "Shares (Enterprise-only)" \
+  true || true
+
+fetch "$API/bases/$BASE_ID/webhooks" \
+  "$OUTPUT_DIR/04-webhooks.json" \
+  "Webhooks" \
+  true || true
+
+# ---------- Phase 3: Schema-derived relationships & sync detection ----------
+echo ""
+echo -e "${BOLD}Phase 3: Analyzing schema for relationships & sync...${NC}"
+
+if [[ -f "$OUTPUT_DIR/02-schema.json" ]]; then
+  jq '
+    {
+      sync_destinations: [
+        .tables[] | select([.fields[].type] | any(. == "externalSyncSource")) | {
+          tableId: .id,
+          tableName: .name,
+          syncedFields: [.fields[] | select(.type == "externalSyncSource") | {id, name}]
+        }
+      ],
+      cross_table_links: [
+        .tables[] as $t |
+        $t.fields[] | select(.type == "multipleRecordLinks") | {
+          fromTableId: $t.id,
+          fromTableName: $t.name,
+          fromFieldId: .id,
+          fromFieldName: .name,
+          toTableId: (.options.linkedTableId // null),
+          inverseFieldId: (.options.inverseLinkFieldId // null),
+          isReversed: (.options.isReversed // null),
+          prefersSingleRecordLink: (.options.prefersSingleRecordLink // null)
+        }
+      ],
+      lookup_fields: [
+        .tables[] as $t |
+        $t.fields[] | select(.type == "multipleLookupValues") | {
+          tableId: $t.id,
+          tableName: $t.name,
+          fieldId: .id,
+          fieldName: .name,
+          viaLinkFieldId: (.options.recordLinkFieldId // null),
+          targetFieldId: (.options.fieldIdInLinkedTable // null)
+        }
+      ],
+      rollup_fields: [
+        .tables[] as $t |
+        $t.fields[] | select(.type == "rollup") | {
+          tableId: $t.id,
+          tableName: $t.name,
+          fieldId: .id,
+          fieldName: .name,
+          viaLinkFieldId: (.options.recordLinkFieldId // null),
+          sourceFieldId: (.options.fieldIdInLinkedTable // null),
+          formula: (.options.reductionConditional // null)
+        }
+      ],
+      count_fields: [
+        .tables[] as $t |
+        $t.fields[] | select(.type == "count") | {
+          tableId: $t.id,
+          tableName: $t.name,
+          fieldId: .id,
+          fieldName: .name,
+          viaLinkFieldId: (.options.recordLinkFieldId // null)
+        }
+      ],
+      formula_fields: [
+        .tables[] as $t |
+        $t.fields[] | select(.type == "formula") | {
+          tableId: $t.id,
+          tableName: $t.name,
+          fieldId: .id,
+          fieldName: .name,
+          formula: (.options.formula // null),
+          referencedFieldIds: (.options.referencedFieldIds // [])
+        }
+      ]
+    }
+  ' "$OUTPUT_DIR/02-schema.json" > "$OUTPUT_DIR/06-relationships.json" 2>/dev/null
+
+  if [[ -f "$OUTPUT_DIR/06-relationships.json" ]]; then
+    sync_count=$(jq '.sync_destinations | length' "$OUTPUT_DIR/06-relationships.json")
+    link_count=$(jq '.cross_table_links | length' "$OUTPUT_DIR/06-relationships.json")
+    lookup_count=$(jq '.lookup_fields | length' "$OUTPUT_DIR/06-relationships.json")
+    rollup_count=$(jq '.rollup_fields | length' "$OUTPUT_DIR/06-relationships.json")
+    count_count=$(jq '.count_fields | length' "$OUTPUT_DIR/06-relationships.json")
+    formula_count=$(jq '.formula_fields | length' "$OUTPUT_DIR/06-relationships.json")
+    echo -e "  ${GREEN}✓${NC} Sync destinations: ${BOLD}$sync_count${NC}"
+    echo -e "  ${GREEN}✓${NC} Cross-table links: ${BOLD}$link_count${NC}"
+    echo -e "  ${GREEN}✓${NC} Lookup fields:     ${BOLD}$lookup_count${NC}"
+    echo -e "  ${GREEN}✓${NC} Rollup fields:     ${BOLD}$rollup_count${NC}"
+    echo -e "  ${GREEN}✓${NC} Count fields:      ${BOLD}$count_count${NC}"
+    echo -e "  ${GREEN}✓${NC} Formula fields:    ${BOLD}$formula_count${NC}"
+  fi
+fi
+
+# ---------- Phase 4: Combined bundle ----------
+echo ""
+echo -e "${BOLD}Phase 4: Building combined bundle...${NC}"
+
+# Ensure jq --slurpfile has something to read for endpoints that were skipped/failed.
+for f in 01-base-info.json 02-schema.json 03-shares.json 04-webhooks.json 05-whoami.json 06-relationships.json; do
+  [[ -f "$OUTPUT_DIR/$f" ]] || echo 'null' > "$OUTPUT_DIR/$f"
+done
+
+jq -n \
+  --slurpfile whoami "$OUTPUT_DIR/05-whoami.json" \
+  --slurpfile base "$OUTPUT_DIR/01-base-info.json" \
+  --slurpfile schema "$OUTPUT_DIR/02-schema.json" \
+  --slurpfile shares "$OUTPUT_DIR/03-shares.json" \
+  --slurpfile webhooks "$OUTPUT_DIR/04-webhooks.json" \
+  --slurpfile rels "$OUTPUT_DIR/06-relationships.json" \
+  '{
+     whoami: ($whoami[0] // null),
+     base_info: ($base[0] // null),
+     schema: ($schema[0] // null),
+     shares: ($shares[0] // null),
+     webhooks: ($webhooks[0] // null),
+     relationships: ($rels[0] // null)
+   }' > "$OUTPUT_DIR/00-bundle.json" 2>/dev/null || {
+     echo -e "  ${YELLOW}Could not build full bundle.${NC}"
+   }
+
+if [[ -f "$OUTPUT_DIR/00-bundle.json" ]]; then
+  size=$(wc -c <"$OUTPUT_DIR/00-bundle.json" | tr -d ' ')
+  echo -e "  ${GREEN}✓${NC} 00-bundle.json ${GRAY}(${size} bytes)${NC}"
+fi
+
+# ---------- Summary ----------
+echo ""
+echo -e "${BOLD}${GREEN}Done.${NC}"
+echo ""
+echo -e "${BOLD}Summary:${NC}"
+
+if [[ -f "$OUTPUT_DIR/02-schema.json" ]]; then
+  TABLE_COUNT=$(jq '.tables | length' "$OUTPUT_DIR/02-schema.json")
+  FIELD_COUNT=$(jq '[.tables[].fields | length] | add' "$OUTPUT_DIR/02-schema.json")
+  VIEW_COUNT=$(jq '[.tables[].views | length] | add' "$OUTPUT_DIR/02-schema.json")
+  echo -e "  Tables:     ${BOLD}$TABLE_COUNT${NC}"
+  echo -e "  Fields:     ${BOLD}$FIELD_COUNT${NC}"
+  echo -e "  Views:      ${BOLD}$VIEW_COUNT${NC}"
+fi
+
+if [[ -f "$OUTPUT_DIR/01-base-info.json" ]]; then
+  INT_COUNT=$(jq '.interfaces // {} | keys | length' "$OUTPUT_DIR/01-base-info.json" 2>/dev/null || echo 0)
+  [[ "$INT_COUNT" -gt 0 ]] && echo -e "  Interfaces: ${BOLD}$INT_COUNT${NC}"
+fi
+
+if [[ -f "$OUTPUT_DIR/04-webhooks.json" ]]; then
+  WH_COUNT=$(jq '.webhooks // [] | length' "$OUTPUT_DIR/04-webhooks.json" 2>/dev/null || echo 0)
+  [[ "$WH_COUNT" -gt 0 ]] && echo -e "  Webhooks:   ${BOLD}$WH_COUNT${NC}"
+fi
+
+echo ""
+echo -e "${GRAY}Folder: $OUTPUT_DIR${NC}"
+echo ""
+
+# Open in Finder
+if command -v open &>/dev/null; then
+  open "$OUTPUT_DIR"
+fi

package/tools/get-softr-database.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+get-softr-database
+==================
+Export a full Softr Tables database **schema** (every table, every field, and all
+of their details) to a timestamped JSON file on your Desktop.
+
+What it does
+------------
+Given a Softr API key and a database ID, it calls two endpoints:
+
+    GET /api/v1/databases/{id}           -> database metadata
+    GET /api/v1/databases/{id}/tables    -> all tables, each with its full
+                                            `fields` array (type, options,
+                                            choices, formulas, AI settings, ...)
+
+and writes the combined result to:
+
+    ~/Desktop/softr-database-<databaseId>-<YYYYMMDD-HHMMSS>.json
+
+Usage
+-----
+    get-softr-database                      # prompts for DB ID, then API key (hidden)
+    get-softr-database <database_id>        # prompts only for the API key
+    SOFTR_API_KEY=xxx get-softr-database <database_id>   # fully non-interactive
+
+The API key may also be supplied via the SOFTR_API_KEY environment variable, so
+it never has to be typed (or stored) in plain text.
+
+Only the Python standard library is used — no `pip install` required.
+"""
+
+import os
+import sys
+import json
+import getpass
+import datetime
+import urllib.request
+import urllib.error
+
+API_BASE = "https://tables-api.softr.io/api/v1"
+TIMEOUT_SECONDS = 60
+
+
+def api_get(path, api_key):
+    """GET a Softr Tables API path and return the parsed JSON body."""
+    req = urllib.request.Request(
+        API_BASE + path,
+        headers={
+            "Softr-Api-Key": api_key,
+            "Content-Type": "application/json",
+        },
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=TIMEOUT_SECONDS) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", "replace")
+        hint = ""
+        if e.code in (401, 403):
+            hint = "\n  (Check that the API key is correct and has access to this database.)"
+        elif e.code == 404:
+            hint = "\n  (Check that the database ID is correct.)"
+        raise SystemExit(f"\n[x] HTTP {e.code} on GET {path}\n  {body}{hint}")
+    except urllib.error.URLError as e:
+        raise SystemExit(f"\n[x] Network error on GET {path}: {e.reason}")
+    except json.JSONDecodeError:
+        raise SystemExit(f"\n[x] Could not parse JSON response from GET {path}")
+
+
+def prompt_database_id():
+    if len(sys.argv) > 1 and sys.argv[1].strip():
+        return sys.argv[1].strip()
+    try:
+        value = input("Softr database ID: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        raise SystemExit("\n[x] Cancelled.")
+    if not value:
+        raise SystemExit("[x] No database ID provided.")
+    return value
+
+
+def prompt_api_key():
+    value = os.environ.get("SOFTR_API_KEY", "").strip()
+    if value:
+        return value
+    try:
+        value = getpass.getpass("Softr API key (input hidden): ").strip()
+    except (EOFError, KeyboardInterrupt):
+        raise SystemExit("\n[x] Cancelled.")
+    if not value:
+        raise SystemExit("[x] No API key provided.")
+    return value
+
+
+def output_dir():
+    desktop = os.path.join(os.path.expanduser("~"), "Desktop")
+    return desktop if os.path.isdir(desktop) else os.path.expanduser("~")
+
+
+def main():
+    database_id = prompt_database_id()
+    api_key = prompt_api_key()
+
+    print(f"\n-> Fetching database {database_id} ...")
+    db = api_get(f"/databases/{database_id}", api_key).get("data", {}) or {}
+    print(f"   Database: {db.get('name', '(unknown)')}  "
+          f"({db.get('tablesCount', '?')} tables reported)")
+
+    print("-> Fetching tables and fields ...")
+    tables = api_get(f"/databases/{database_id}/tables", api_key).get("data", []) or []
+    total_fields = sum(len(t.get("fields", []) or []) for t in tables)
+    print(f"   Retrieved {len(tables)} tables, {total_fields} fields total.")
+
+    now = datetime.datetime.now()
+    payload = {
+        "exportedAt": now.isoformat(timespec="seconds"),
+        "source": API_BASE,
+        "databaseId": database_id,
+        "database": db,
+        "tableCount": len(tables),
+        "fieldCount": total_fields,
+        "tables": tables,
+    }
+
+    stamp = now.strftime("%Y%m%d-%H%M%S")
+    filename = f"softr-database-{database_id}-{stamp}.json"
+    path = os.path.join(output_dir(), filename)
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, ensure_ascii=False)
+
+    print(f"\n[ok] Saved schema to:\n     {path}")
+
+    # Brief per-table summary so the result is readable at a glance.
+    if tables:
+        print("\n     Tables:")
+        for t in tables:
+            print(f"       - {t.get('name', '(unnamed)')}: "
+                  f"{len(t.get('fields', []) or [])} fields")
+
+
+if __name__ == "__main__":
+    main()