shimwrappercheck 0.2.0

package/dashboard/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "shimwrappercheck-dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "next": "14.2.18",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "daisyui": "^4.12.14",
+    "tailwindcss": "^3.4.15"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "autoprefixer": "^10.4.20",
+    "eslint": "^8.57.0",
+    "eslint-config-next": "14.2.18",
+    "postcss": "^8.4.49",
+    "typescript": "^5.7.2"
+  }
+}

package/dashboard/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/dashboard/tailwind.config.js

@@ -0,0 +1,14 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    "./app/**/*.{js,ts,jsx,tsx,mdx}",
+    "./components/**/*.{js,ts,jsx,tsx,mdx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [require("daisyui")],
+  daisyui: {
+    themes: ["light", "dark"],
+  },
+};

package/dashboard/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/docs/SHIM_WRAPPER_CONCEPT.md

@@ -0,0 +1,79 @@
+# Shim Wrapper Concept (Enforced Checks)
+
+## Why
+
+Teams often want a guaranteed flow: change code -> run checks -> deploy/push.
+A shim wrapper ensures checks run even when developers or agents use the CLI directly.
+
+## Core idea
+
+- Put a wrapper earlier in PATH (or use local npm bin).
+- The wrapper runs checks first.
+- Only after checks pass, the real CLI runs.
+- Git hooks provide a second safety net.
+
+## Wrapper design
+
+1) Resolve the project root.
+2) Detect which checks to run based on changed files (e.g. `src/` vs `supabase/functions/`).
+3) Run a checks script (repo-specific).
+4) Call the real CLI (not the wrapper).
+5) Run optional post-deploy hooks (health ping, logs).
+6) Optionally push commits if ahead of upstream.
+
+## Command filtering
+
+You can limit which Supabase commands trigger checks and hooks:
+
+- `SHIM_ENFORCE_COMMANDS="functions,db,migration"` to run checks only for these commands.
+- `SHIM_HOOK_COMMANDS="functions,db,migration"` to run hooks only for these commands.
+- Use `all` or `none` to enable/disable completely.
+
+Persist these settings in `.shimwrappercheckrc` (or set `SHIM_CONFIG_FILE`).
+
+## Avoiding recursion
+
+When the wrapper is called via `npx` or local `node_modules/.bin`, it must not call itself.
+To avoid recursion:
+
+- Set `SUPABASE_REAL_BIN` to the real CLI path.
+- Or store the real path in `~/.supabase-real-bin`.
+- If no real CLI is found, use `npx --package supabase supabase ...`.
+
+## Recommended layers
+
+- Shim wrapper (this package).
+- Git pre-push hook running the same checks.
+- CI checks for extra safety.
+
+## Typical flows
+
+### Backend repo
+
+- `supabase functions deploy <name>`
+- Wrapper runs backend checks
+- Deploy happens only if checks pass
+
+### Frontend repo
+
+- `git push`
+- Hook runs lint/test/build
+- Push is blocked on failure
+
+### Mixed repo
+
+- Wrapper runs backend checks for deploy
+- Hook runs path-specific checks for push
+
+## Dashboard and AGENTS.md
+
+- The **dashboard** (`dashboard/`) is a Next.js Web UI: status, run checks, edit `.shimwrappercheckrc`, and edit **AGENTS.md**.
+- **AGENTS.md** at project root is read by AI agents (Cursor, Codex). It can be edited via the dashboard so agents and humans share one source of truth; agents should respect its content.
+
+## Setup checklist
+
+1) Add checks script (repo-specific).
+2) Use shim wrapper instead of raw CLI.
+3) Add a pre-push hook for redundancy.
+4) Validate PATH (or use `npx supabase`).
+5) Optionally run the dashboard to manage config and AGENTS.md.

package/docs/WORKFLOW_AND_GAP_ANALYSIS.md

@@ -0,0 +1,159 @@
+# Workflow & Gap Analysis (no code changes yet)
+
+This doc describes the **desired workflow**, what **already exists**, and what **still needs to be done**. No code has been changed; this is the plan for when you "come in the door" next.
+
+---
+
+## 1. Desired workflow (your description)
+
+### First-time setup: one CLI command + wizard
+
+- User runs **one CLI command** that sets up the whole shimwrapper.
+- A **wizard** runs with questions like:
+  - "Do you want this? Do you want that?"
+  - Prettier, Lint, snake/processes, authentication where needed
+  - AI review → "You need to log in to Codex" (or Cursor)
+  - etc.
+- User **confirms** what they want; everything is configured from that.
+
+### Later: change things via GUI
+
+- User clicks a **link** (e.g. from CLI output or README) → **graphical surface (dashboard)** opens.
+- In the dashboard:
+  - **On/off toggles** per check (e.g. "Don’t run this check").
+  - **Grouping**: e.g. "Supabase pushes/deploys" vs "GitHub pushes/deploys".
+  - **Which commands** run checks/hooks – configurable, with sensible defaults.
+
+### Presets
+
+- **Default preset: "Vibe Code"**
+  - Includes: **GitHub** (Git) + **Supabase**, with all relevant commands.
+  - User can select this preset and then tweak individual categories/commands.
+- **Custom presets**
+  - User can **create new presets** (e.g. "Create new preset").
+  - **Drag & drop** providers into a preset (e.g. drag "GitHub" into the new preset).
+  - When opening a preset (e.g. "GitHub"), all commands for that provider are listed and can be **toggled on/off**.
+- Presets are the main way to say "which commands" (Supabase vs Git vs both, and which subcommands).
+
+### Summary of desired UX
+
+| When | What |
+|------|------|
+| First time | One CLI → wizard → "Want this? Want that?" (Prettier, Lint, AI review, auth hints, etc.) → confirm → full setup |
+| Later | Open dashboard via link → toggles per check, groups (Supabase vs GitHub), presets (Vibe Code default, custom by drag & drop) |
+| Presets | Vibe Code = GitHub + Supabase, all commands; custom presets = drag provider in, then toggle commands |
+
+---
+
+## 2. What we already have
+
+### CLI
+
+| Piece | Status | Notes |
+|-------|--------|--------|
+| **Single entry** | ✅ | `npx shimwrappercheck init` sets up shim + config + hooks. |
+| **Wizard (init)** | ✅ | Asks: Supabase shim? Git wrapper? Which commands for checks/hooks? AI review? Codex/Cursor login? run-checks.sh / ai-code-review.sh / Husky or git pre-push. |
+| **Not a single "setup everything" command** | ⚠️ | User must first `npm i -D shimwrappercheck`, then `npx shimwrappercheck init`. So "one command" could mean: one command that does install + init (e.g. `npx shimwrappercheck setup` or `create-shimwrapper`). |
+| **Prettier / Lint / snake in wizard** | ❌ | Init does **not** ask "Do you want Prettier? Lint? Snake?" – it only asks for run-checks.sh template (which already contains lint/build/test). So no explicit Prettier/Lint/snake toggles in the wizard. |
+| **Auth hints** | ✅ | Init offers "log in to Codex" / "Cursor agent login" if AI review is enabled. |
+| **install** | ✅ | `npx shimwrappercheck install` drops PATH shims (supabase, git, shim). |
+
+### Config (today)
+
+- **.shimwrappercheckrc**: key=value (SHIM_ENFORCE_COMMANDS, SHIM_HOOK_COMMANDS, SHIM_GIT_ENFORCE_COMMANDS, SHIM_AUTO_PUSH, SHIM_CHECKS_ARGS, etc.).
+- **No presets**: no concept of "Vibe Code" or "custom preset" in config.
+- **No per-check toggles in config**: run-checks.sh has --frontend, --backend, --no-ai-review; config only has SHIM_CHECKS_ARGS (e.g. "--no-ai-review"). So "disable this check" = pass args, not a structured list of enabled checks.
+
+### Dashboard (today)
+
+| Feature | Status | Notes |
+|---------|--------|--------|
+| **Open via link** | ✅ | User can run dashboard locally and open in browser; README has the link. No "open dashboard" link printed by CLI after init (could be added). |
+| **Status** | ✅ | Shows: config exists, AGENTS.md, run-checks script, Husky, Git hook, Supabase. |
+| **Run checks** | ✅ | Button "Nur Checks ausführen". |
+| **Edit .shimwrappercheckrc** | ✅ | Config page = raw text editor. |
+| **Edit AGENTS.md** | ✅ | Agents page = raw text editor. |
+| **On/off toggles per check** | ❌ | No UI to enable/disable individual checks (e.g. "run lint", "run AI review"). |
+| **Grouping (Supabase vs GitHub)** | ❌ | No UI grouping "Supabase commands" vs "Git commands". |
+| **Presets** | ❌ | No presets (Vibe Code, custom), no drag & drop. |
+| **"Which commands" per provider** | ❌ | No UI to select which Supabase commands (functions, db, migration, …) or Git commands (push, commit, …) run checks/hooks; that’s only in raw .shimwrappercheckrc. |
+
+### Run-checks and checks
+
+- **run-checks.sh**: frontend (lint, check:mock-data, build, test, npm audit, optional Snyk), backend (deno fmt/lint/audit), AI review (Codex/Cursor). No explicit "Prettier" step in template (lint covers style in many setups); no "snake" as a separate step.
+- So: **Prettier / Lint / snake** in the wizard would mean either extending the wizard to ask for them and/or extending run-checks.sh (or a config that run-checks.sh reads) to turn steps on/off.
+
+---
+
+## 3. What it should look like (target)
+
+### First-time flow
+
+1. **One command** (e.g. `npx shimwrappercheck setup` or similar):
+   - Ensures package is present (install if needed).
+   - Runs wizard.
+2. **Wizard** (can stay in init, or be invoked by setup):
+   - "Do you want Supabase shim? Git (GitHub) wrapper?"
+   - "Do you want Prettier / Lint / (snake?) in checks?" (or: "Use default checks (lint, build, test, optional AI review)?")
+   - "Do you want AI review? → You’ll need to log in to Codex (or Cursor)." → offer login.
+   - Create run-checks.sh, ai-code-review.sh, hooks, package.json scripts, .shimwrappercheckrc.
+   - At the end: "To change options later, open the dashboard: [link]."
+
+### Dashboard (target)
+
+1. **Presets**
+   - **Default: "Vibe Code"** – GitHub + Supabase, all commands (Supabase: functions, db, migration, …; Git: push, …). User can select this and then refine.
+   - **Custom presets**: "Create new preset" → name → **drag & drop** providers (e.g. "GitHub", "Supabase") into the preset. When a provider is in the preset, show its commands with toggles.
+   - Preset selection (dropdown or cards): e.g. "Vibe Code" | "My Preset" | "+ New preset".
+
+2. **Grouping**
+   - **Supabase** section: list of commands (functions deploy, db push, migration, …) with **on/off** for "run checks" and "run hooks" (or one toggle per command that means "enforce checks for this command").
+   - **GitHub (Git)** section: list of commands (push, commit, merge, rebase, …) with on/off for "run checks".
+
+3. **Checks**
+   - **On/off toggles** for checks that run inside run-checks.sh (or equivalent):
+   - e.g. Lint, Prettier, Build, Test, npm audit, Snyk, Backend (deno fmt/lint/audit), AI review.
+   - Optional: "Authentication: Codex / Cursor" with hint "Run `codex login` or `agent login` if not done."
+
+4. **Link from CLI**
+   - After init/setup: print "Dashboard: http://localhost:3000 (run from dashboard/: npm run dev)" or a stable URL if deployed.
+
+### Data model (for presets and toggles)
+
+- **Current**: .shimwrappercheckrc (flat key=value).
+- **Target** (conceptual):
+  - **Presets**: list of presets; each preset has a name and a set of "providers" (Supabase, Git) and per-provider "commands" (which subcommands get checks/hooks).
+  - **Active preset** or "current config" derived from one preset + overrides.
+  - **Checks**: list of check types (lint, prettier, build, test, ai-review, …) with on/off. This could stay in .shimwrappercheckrc as new keys (e.g. SHIM_CHECK_LINT=1, SHIM_CHECK_AI_REVIEW=1) or a small JSON that run-checks.sh or the shim reads.
+
+So we need:
+- A way to **store presets** (e.g. JSON in repo or in .shimwrappercheckrc include, or a new file like `.shimwrappercheck-presets.json`).
+- A way to **map preset + toggles** to existing env vars (SHIM_ENFORCE_COMMANDS, SHIM_HOOK_COMMANDS, SHIM_GIT_ENFORCE_COMMANDS, SHIM_CHECKS_ARGS) so the existing bins don’t need a full rewrite.
+
+---
+
+## 4. What still has to be done (concise)
+
+| # | Area | To do |
+|---|------|--------|
+| 1 | **CLI: single entry** | Add a single command (e.g. `npx shimwrappercheck setup`) that installs package if needed and runs init wizard. |
+| 2 | **Wizard: Prettier / Lint / snake** | Extend init (or setup) to ask "Prettier? Lint? Snake?" (or a small set of check categories) and write run-checks.sh or config so those run/skip. |
+| 3 | **Wizard: auth** | Keep current "log in to Codex / Cursor" prompts; optionally print dashboard link at end. |
+| 4 | **Dashboard: presets** | Introduce presets (data model + storage). Default preset "Vibe Code" = GitHub + Supabase, all commands. UI: select preset, "Create new preset", drag & drop providers into preset. |
+| 5 | **Dashboard: grouping** | Supabase section (commands + toggles), GitHub section (commands + toggles). Each command has "run checks" on/off (and optionally "run hooks" for Supabase). |
+| 6 | **Dashboard: check toggles** | On/off for: Lint, Prettier, Build, Test, (Snyk?), Backend checks, AI review. Persist to config / run-checks args so run-checks.sh respects them. |
+| 7 | **Config ↔ presets** | When user selects preset or toggles, write .shimwrappercheckrc (and optional presets file) so existing shim bins work without change. |
+| 8 | **CLI → dashboard link** | After init/setup, print dashboard URL (local or deployed). |
+
+---
+
+## 5. Suggested order (when you implement)
+
+1. **Presets data model** (file format + default "Vibe Code" preset).
+2. **Dashboard: Presets UI** (select preset, show Supabase vs Git groups, command toggles) and **map to .shimwrappercheckrc**.
+3. **Dashboard: Check toggles** (lint, prettier, build, test, AI review, …) and **map to SHIM_CHECKS_ARGS or run-checks config**.
+4. **Dashboard: Custom presets** (create new, drag & drop providers).
+5. **CLI: setup command** (install + init) and **wizard: Prettier/Lint/snake** (if you want them in the wizard).
+6. **CLI: print dashboard link** at end of init/setup.
+
+No code has been changed in this repo; the above is the plan for when you start implementing.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "shimwrappercheck",
+  "version": "0.2.0",
+  "description": "Supabase CLI shim wrapper that enforces checks before deploy/push. Dashboard, presets, AGENTS.md.",
+  "license": "MIT",
+  "bin": {
+    "supabase": "bin/supabase",
+    "shimwrappercheck": "bin/shimwrappercheck",
+    "git": "bin/git",
+    "shim": "bin/shim"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "templates",
+    "docs",
+    "dashboard",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/cli-checked.sh

@@ -0,0 +1,307 @@
+#!/usr/bin/env bash
+# Generic CLI shim wrapper: run checks (optional), then call the real CLI.
+set -euo pipefail
+
+WRAPPER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+resolve_project_root() {
+  if [[ -n "${SHIM_PROJECT_ROOT:-}" ]]; then
+    echo "$SHIM_PROJECT_ROOT"
+    return
+  fi
+  if command -v git >/dev/null 2>&1; then
+    local root
+    root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+    if [[ -n "$root" ]]; then
+      echo "$root"
+      return
+    fi
+  fi
+  pwd
+}
+
+PROJECT_ROOT="$(resolve_project_root)"
+cd "$PROJECT_ROOT"
+
+CONFIG_FILE="${SHIM_CONFIG_FILE:-$PROJECT_ROOT/.shimwrappercheckrc}"
+if [[ -f "$CONFIG_FILE" ]]; then
+  # shellcheck disable=SC1090
+  source "$CONFIG_FILE"
+fi
+
+ARGS_IN=("$@")
+ARGS_TEXT_RAW=" ${*:-} "
+CLI_NAME=""
+CLI_ARGS=()
+CHECKS_PASSTHROUGH=()
+
+RUN_CHECKS=true
+CHECKS_ONLY=false
+FORCE_FRONTEND=false
+RUN_PUSH=false
+
+matches_command_list() {
+  local list="$1"
+  local text="$2"
+
+  list="$(echo "$list" | tr '[:upper:]' '[:lower:]')"
+  text="$(echo "$text" | tr '[:upper:]' '[:lower:]')"
+
+  if [[ -z "$list" ]] || [[ "$list" == "all" ]]; then
+    return 0
+  fi
+  if [[ "$list" == "none" ]]; then
+    return 1
+  fi
+
+  IFS=',' read -r -a items <<< "$list"
+  for item in "${items[@]}"; do
+    item="$(echo "$item" | xargs)"
+    [[ -z "$item" ]] && continue
+    if [[ "$text" == *" $item "* ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Parse args: allow either `shim <cli> ...` or `shim --cli <cli> -- ...`
+consume_cli=false
+pass_through=false
+for arg in "${ARGS_IN[@]}"; do
+  if [[ "$arg" == "--" ]]; then
+    pass_through=true
+    continue
+  fi
+
+  if [[ "$pass_through" == true ]]; then
+    if [[ -z "$CLI_NAME" ]]; then
+      CLI_NAME="$arg"
+    else
+      CLI_ARGS+=("$arg")
+    fi
+    continue
+  fi
+
+  if [[ -z "$CLI_NAME" ]] && [[ "$arg" == "--cli" ]]; then
+    consume_cli=true
+    continue
+  fi
+
+  if [[ "$consume_cli" == true ]] && [[ -z "$CLI_NAME" ]]; then
+    CLI_NAME="$arg"
+    consume_cli=false
+    continue
+  fi
+
+  if [[ -z "$CLI_NAME" ]] && [[ "$arg" != -* ]]; then
+    CLI_NAME="$arg"
+    continue
+  fi
+
+  case "$arg" in
+    --no-checks) RUN_CHECKS=false ;;
+    --checks-only) CHECKS_ONLY=true ;;
+    --no-ai-review|--ai-review) CHECKS_PASSTHROUGH+=("$arg") ;;
+    --with-frontend) FORCE_FRONTEND=true ;;
+    --no-push) RUN_PUSH=false ;;
+    --auto-push) RUN_PUSH=true ;;
+    *) CLI_ARGS+=("$arg") ;;
+  esac
+done
+
+[[ -n "${SHIM_DISABLE_CHECKS:-}" ]] && RUN_CHECKS=false
+if [[ -n "${SHIM_CLI_AUTO_PUSH:-}" ]]; then
+  case "${SHIM_CLI_AUTO_PUSH}" in
+    1|true|TRUE|yes|YES) RUN_PUSH=true ;;
+    0|false|FALSE|no|NO) RUN_PUSH=false ;;
+  esac
+fi
+
+if [[ -z "$CLI_NAME" ]] && [[ "$CHECKS_ONLY" != true ]]; then
+  echo "No CLI provided. Usage: shim <cli> [shim flags] <args>" >&2
+  echo "or: shim --cli <cli> -- <args>" >&2
+  exit 1
+fi
+
+ARGS_TEXT=" ${CLI_ARGS[*]:-} "
+if [[ "$CHECKS_ONLY" != true ]]; then
+  enforce_list="${SHIM_CLI_ENFORCE_COMMANDS:-${SHIM_ENFORCE_COMMANDS:-all}}"
+  if ! matches_command_list "$enforce_list" "$ARGS_TEXT"; then
+    RUN_CHECKS=false
+  fi
+fi
+
+should_run_hooks=false
+hook_list="${SHIM_CLI_HOOK_COMMANDS:-all}"
+if matches_command_list "$hook_list" "$ARGS_TEXT"; then
+  should_run_hooks=true
+fi
+
+resolve_hook_list() {
+  local list="$1"
+  local default_name="$2"
+  local resolved=()
+
+  if [[ -n "$list" ]]; then
+    IFS=',' read -r -a items <<< "$list"
+    for item in "${items[@]}"; do
+      item="$(echo "$item" | xargs)"
+      [[ -z "$item" ]] && continue
+      if [[ "$item" != /* ]]; then
+        item="$PROJECT_ROOT/$item"
+      fi
+      resolved+=("$item")
+    done
+  elif [[ -n "$default_name" ]] && [[ -f "$PROJECT_ROOT/scripts/$default_name" ]]; then
+    resolved+=("$PROJECT_ROOT/scripts/$default_name")
+  fi
+
+  printf '%s\n' "${resolved[@]}"
+}
+
+resolve_checks_script() {
+  local script="${SHIM_CLI_CHECKS_SCRIPT:-}"
+  if [[ -n "$script" ]]; then
+    if [[ "$script" != /* ]]; then
+      script="$PROJECT_ROOT/$script"
+    fi
+    echo "$script"
+    return
+  fi
+  script="${SHIM_CHECKS_SCRIPT:-}"
+  if [[ -n "$script" ]]; then
+    if [[ "$script" != /* ]]; then
+      script="$PROJECT_ROOT/$script"
+    fi
+    echo "$script"
+    return
+  fi
+  local candidates=("scripts/run-checks.sh" "scripts/shim-checks.sh")
+  for candidate in "${candidates[@]}"; do
+    if [[ -f "$PROJECT_ROOT/$candidate" ]]; then
+      echo "$PROJECT_ROOT/$candidate"
+      return
+    fi
+  done
+  echo ""
+}
+
+if [[ "$RUN_CHECKS" = true ]]; then
+  run_frontend=false
+  run_backend=false
+  run_ai_review=true
+
+  changed_files=""
+  if command -v git >/dev/null 2>&1; then
+    unstaged=$(git diff --name-only --diff-filter=ACMR || true)
+    staged=$(git diff --name-only --cached --diff-filter=ACMR || true)
+    changed_files=$(printf "%s\n%s\n" "$unstaged" "$staged")
+  fi
+
+  if [[ -n "$changed_files" ]]; then
+    echo "$changed_files" | grep -q '^src/' && run_frontend=true
+    echo "$changed_files" | grep -q '^supabase/functions/' && run_backend=true
+  fi
+
+  if [[ "$FORCE_FRONTEND" = true ]] || [[ "$ARGS_TEXT_RAW" == *" --with-frontend "* ]]; then
+    run_frontend=true
+  fi
+
+  if [[ "$ARGS_TEXT_RAW" == *" --no-ai-review "* ]]; then
+    run_ai_review=false
+  fi
+  if [[ -n "${SKIP_AI_REVIEW:-}" ]]; then
+    run_ai_review=false
+  fi
+
+  if [[ "$run_frontend" = true ]] || [[ "$run_backend" = true ]]; then
+    CHECKS_SCRIPT="$(resolve_checks_script)"
+    if [[ -n "$CHECKS_SCRIPT" ]]; then
+      CHECKS_ARGS=()
+      if [[ -n "${SHIM_CLI_CHECKS_ARGS:-}" ]]; then
+        read -r -a CHECKS_ARGS <<< "${SHIM_CLI_CHECKS_ARGS}"
+      elif [[ -n "${SHIM_CHECKS_ARGS:-}" ]]; then
+        read -r -a CHECKS_ARGS <<< "${SHIM_CHECKS_ARGS}"
+      fi
+      [[ "$run_frontend" = true ]] && CHECKS_ARGS+=(--frontend)
+      [[ "$run_backend" = true ]] && CHECKS_ARGS+=(--backend)
+      [[ "$run_ai_review" = false ]] && CHECKS_ARGS+=(--no-ai-review)
+      CHECKS_ARGS+=("${CHECKS_PASSTHROUGH[@]}")
+      bash "$CHECKS_SCRIPT" "${CHECKS_ARGS[@]}"
+    else
+      echo "Shim checks: no checks script found; skipping." >&2
+    fi
+  fi
+fi
+
+if [[ "$CHECKS_ONLY" = true ]]; then
+  exit 0
+fi
+
+REAL_BIN="${SHIM_CLI_REAL_BIN:-${SHIM_REAL_BIN:-}}"
+if [[ -z "$REAL_BIN" ]]; then
+  REAL_BIN="$(command -v "$CLI_NAME" || true)"
+fi
+if [[ -n "$REAL_BIN" ]] && { [[ "$REAL_BIN" == *"node_modules"* ]] || [[ "$REAL_BIN" == "$WRAPPER_DIR"* ]]; }; then
+  REAL_BIN=""
+fi
+
+if [[ -z "$REAL_BIN" ]]; then
+  echo "Real binary for '$CLI_NAME' not found. Set SHIM_CLI_REAL_BIN." >&2
+  exit 1
+fi
+
+pre_hooks="$(resolve_hook_list "${SHIM_CLI_PRE_HOOKS:-}" "cli-pre-hook.sh")"
+post_hooks="$(resolve_hook_list "${SHIM_CLI_POST_HOOKS:-}" "cli-post-hook.sh")"
+
+if [[ "$should_run_hooks" = true ]] && [[ -n "$pre_hooks" ]]; then
+  while IFS= read -r hook; do
+    [[ -z "$hook" ]] && continue
+    if [[ -f "$hook" ]]; then
+      bash "$hook" "$CLI_NAME" "${CLI_ARGS[@]}"
+    else
+      echo "Pre-hook not found: $hook" >&2
+    fi
+  done <<< "$pre_hooks"
+fi
+
+set +e
+if [[ "$(basename "$REAL_BIN")" == "$CLI_NAME" ]]; then
+  "$REAL_BIN" "${CLI_ARGS[@]}"
+else
+  "$REAL_BIN" "$CLI_NAME" "${CLI_ARGS[@]}"
+fi
+CLI_RC=$?
+set -e
+
+if [[ $CLI_RC -ne 0 ]]; then
+  exit $CLI_RC
+fi
+
+if [[ "$should_run_hooks" = true ]] && [[ -n "$post_hooks" ]]; then
+  while IFS= read -r hook; do
+    [[ -z "$hook" ]] && continue
+    if [[ -f "$hook" ]]; then
+      bash "$hook" "$CLI_NAME" "${CLI_ARGS[@]}" || true
+    else
+      echo "Post-hook not found: $hook" >&2
+    fi
+  done <<< "$post_hooks"
+fi
+
+if [[ "$RUN_PUSH" = true ]] && command -v git >/dev/null 2>&1; then
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    if git rev-parse --abbrev-ref --symbolic-full-name @{u} >/dev/null 2>&1; then
+      ahead=$(git rev-list --count @{u}..HEAD)
+      if [[ "${ahead:-0}" -gt 0 ]]; then
+        echo "Pushing commits to remote..."
+        git push
+      else
+        echo "No commits to push."
+      fi
+    else
+      echo "No upstream configured; skipping git push."
+    fi
+  fi
+fi

package/scripts/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+const path = require('path');
+
+const cmd = process.argv[2];
+
+if (cmd === 'setup') {
+  require(path.join(__dirname, 'setup'));
+  return;
+}
+
+if (!cmd || cmd === 'init') {
+  require(path.join(__dirname, 'init'));
+  return;
+}
+
+if (cmd === 'install') {
+  require(path.join(__dirname, 'install'));
+  return;
+}
+
+console.error('Unknown command:', cmd);
+console.error('Usage: shimwrappercheck [setup|init|install]');
+process.exit(1);