Delete supervise docs/scaffolding and pm2 leftover; add repo-hygiene CI guard; scope MCP npx

Author: djadmin

.github/workflows/cli.yml

@@ -21,15 +21,33 @@ jobs:
         run: |
           command -v caddy >/dev/null 2>&1 || brew install caddy
 
+      - name: Guard against committing private / generated files
+        run: |
+          # Fail if anything machine-specific, generated, or paid ever gets tracked.
+          # .gitignore stops accidental `git add`; this catches a file already committed.
+          forbidden=$(git ls-files | grep -E '(^|/)apps\.json$|^pids/|^logs/|^Caddyfile$|^dashboard\.html$|^\.claude/|(^|/)\.DS_Store$' || true)
+          # The paid Mac app lives in the private devkit-app repo; only MenuBarApp/docs/ is public.
+          paid=$(git ls-files 'MenuBarApp/*' | grep -vE '^MenuBarApp/docs/' || true)
+          if [ -n "$forbidden$paid" ]; then
+            echo "::error::forbidden files are tracked in this public repo:"
+            printf '%s\n' "$forbidden" "$paid"
+            exit 1
+          fi
+          echo "repo hygiene OK"
+
       - name: Syntax check CLI and tests
         run: |
           bash -n bin/devkit
           bash -n install.sh
           bash -n test/test_registry.sh
+          bash -n test/test_scan.sh
           bash -n test/test_install.sh
 
       - name: Run CLI integration suite
         run: bash test/test_registry.sh
 
+      - name: Run scan suite
+        run: bash test/test_scan.sh
+
       - name: Run installer smoke test
         run: bash test/test_install.sh

CLAUDE.md

@@ -46,4 +46,20 @@ They are regenerated by `devkit reload`.
 
 ## Public release constraint
 
-Avoid baking machine-specific paths, usernames, repo URLs, or private project names into committed files.
+This repo is **public**. Avoid baking machine-specific paths, usernames, or private
+project names into committed files.
+
+**Never commit (privacy / paid product):**
+
+- `apps.json` — the live registry; it contains your real project names and paths. Only the
+  sanitized `apps.example.json` is tracked.
+- `pids/`, `logs/`, `Caddyfile`, `dashboard.html` — runtime + generated, machine-specific.
+- `.claude/settings.local.json` (local paths / allow-rules) and `.claude/` generally.
+- Anything under `MenuBarApp/` except `MenuBarApp/docs/` — the Mac app is the **paid**
+  product and lives in the private `devkit-app` repo. Never let its source land here.
+
+These are all in `.gitignore`, but `.gitignore` only stops accidental `git add` — it does
+not catch a file that is already tracked. The `cli.yml` workflow has a **repo-hygiene
+guard** that fails the build if any of the above ever becomes tracked. Do not weaken it.
+If you add a new kind of local/generated/private file, add it to both `.gitignore` and
+that guard.

README.md

@@ -118,53 +118,17 @@ Browse everything at `http://dash.localhost`.
 
 ---
 
-## Crash Recovery (opt-in)
-
-By default devkit starts an app and steps back — if the app later dies, it stays down
-until you start it again. Opt a devkit-managed app into automatic recovery with a
-restart policy:
-
-```bash
-devkit register api --port 3000 --cmd "npm start" --restart on-failure
-# or change it later:
-devkit update api --restart on-failure        # policies: no (default) | on-failure | always
-```
-
-Then install the background supervisor once:
-
-```bash
-devkit supervise install      # installs a launchd agent that watches your apps
-devkit supervise status       # list supervised apps + agent state
-devkit supervise uninstall    # remove it
-```
-
-How it behaves:
-
-- It only revives apps you actually want running. `devkit start` marks intent up;
-  `devkit stop` / `stop-all` marks it down — so the supervisor **never restarts something
-  you deliberately stopped**.
-- Crash loops are throttled with exponential backoff (5s → capped at 5min), reset once an
-  app comes back healthy.
-- Each pass also re-checks the proxy, so `.localhost` routing self-heals even when no
-  devkit command is running.
-
-`devkit supervise tick` runs a single pass by hand (this is what the launchd agent calls).
-
-Tuning env vars: `DEVKIT_SUPERVISE_INTERVAL` (seconds between checks, default 10),
-`DEVKIT_SUPERVISE_BACKOFF_BASE` (default 5), `DEVKIT_SUPERVISE_BACKOFF_CAP` (default 300).
-For a non-Homebrew Caddy setup, set `DEVKIT_CADDY_MANAGED=1` so reloads still apply.
-
----
-
 ## Reliability
 
-- 97 CLI lifecycle tests (including crash recovery, restart policy, and the launchd plist)
+- 114 CLI lifecycle tests + 23 scan tests
 - 18 installer smoke tests
 - GitHub Actions on fresh macOS runners
 
-Explicitly covers stale pid files, orphan recovery, restart pressure, port conflicts,
-failed starts, out-of-band `apps.json` edits, malformed registries, and supervised crash
-recovery.
+Explicitly covers stale pid files, orphan recovery, port conflicts, fail-fast on a
+crashing start, out-of-band `apps.json` edits, and malformed registries.
+
+devkit manages an app's lifecycle on demand (`start` / `stop` / `restart`); it does not
+run a background daemon, so a crashed app stays down until you start it again.
 
 ```bash
 bash test/test_registry.sh

bin/devkit

@@ -43,19 +43,12 @@ LOCK_DIR="$DEVKIT_HOME/.registry.lock"
 STAMP_FILE="$DEVKIT_HOME/.caddy.fingerprint"
 BREW_CADDYFILE="${DEVKIT_BREW_CADDYFILE:-/opt/homebrew/etc/Caddyfile}"
 
-# ── Supervisor (opt-in crash recovery) ──────────────────────────────────────
-# wants/  records desired state (set on start, cleared on stop) so the supervisor only
-#         revives apps you actually want up — it never fights a manual `devkit stop`.
-# state/  holds per-app backoff counters so a crash-looping app can't be hammered.
+# Desired-state markers. `wants/` records which apps were last started vs stopped. These
+# are advisory only today (written on start/stop, read by nothing) — kept as the seam for
+# a future reliability layer, which will be process-compose, not a hand-rolled supervisor.
+# TODO: fully remove these + the inert `restart` policy in a focused pass.
 WANTS_DIR="$DEVKIT_HOME/supervisor/wants"
 SUPERVISOR_STATE_DIR="$DEVKIT_HOME/supervisor/state"
-SUPERVISOR_LOCK="$DEVKIT_HOME/supervisor/.tick.lock"
-SUPERVISOR_LOG="$LOGS_DIR/_supervisor.log"
-SUPERVISOR_LABEL="com.devkit.supervisor"
-SUPERVISOR_PLIST="$HOME/Library/LaunchAgents/$SUPERVISOR_LABEL.plist"
-SUPERVISOR_INTERVAL="${DEVKIT_SUPERVISE_INTERVAL:-10}"
-SUPERVISOR_BACKOFF_BASE="${DEVKIT_SUPERVISE_BACKOFF_BASE:-5}"
-SUPERVISOR_BACKOFF_CAP="${DEVKIT_SUPERVISE_BACKOFF_CAP:-300}"
 DEVKIT_BIN_SELF="$SCRIPT_DIR/$(basename -- "${BASH_SOURCE[0]}")"
 
 die() { echo "devkit: $*" >&2; exit 1; }
@@ -382,7 +375,6 @@ is_running() {
 #   stopped  — managed, down, no recorded failure (identical to never-started)
 app_state() {
   local name="$1" managed="$2"
-  [[ "$managed" == "pm2" ]] && managed="devkit"
   case "$managed" in
     external) echo "external"; return 0 ;;
     devkit)
@@ -1512,45 +1504,50 @@ OUT
 # Wire the devkit MCP server into an AI agent so it can register/manage apps as
 # structured tool calls (instead of relying on a CLAUDE.md text instruction).
 cmd_setup_mcp() {
+  # Prefer a local checkout (handy during development); otherwise run the published
+  # package with `npx -y devkit-mcp`, so a standalone CLI install needs nothing extra.
+  # Either way the agent gets the same stdio MCP server.
   local candidates=(
     "$REPO_HOME/../devkit-mcp/index.js"
     "$REPO_HOME/devkit-mcp/index.js"
-    "$REPO_HOME/mcp-server/index.js"
     "$DEVKIT_HOME/devkit-mcp/index.js"
-    "$DEVKIT_HOME/mcp-server/index.js"
   )
   local server="" c
   for c in "${candidates[@]}"; do
-    if [[ -f "$c" ]]; then
-      server="$(cd "$(dirname "$c")" && pwd)/index.js"
-      break
-    fi
+    if [[ -f "$c" ]]; then server="$(cd "$(dirname "$c")" && pwd)/index.js"; break; fi
   done
-  [[ -n "$server" ]] || die "could not find the devkit MCP server (index.js) — expected near $REPO_HOME/../devkit-mcp/"
-
-  need node
 
-  # Install the MCP's dependencies if missing, otherwise the server crashes on first
-  # call with "Cannot find module @modelcontextprotocol/sdk".
-  local server_dir; server_dir=$(dirname "$server")
-  if [[ ! -d "$server_dir/node_modules/@modelcontextprotocol" ]]; then
-    need npm
-    echo "installing devkit MCP dependencies..."
-    (cd "$server_dir" && npm install --silent) || die "npm install failed in $server_dir"
+  local -a runcmd
+  if [[ -n "$server" ]]; then
+    need node
+    # Install deps if missing, else the server crashes with "Cannot find module
+    # @modelcontextprotocol/sdk" on first call.
+    local server_dir; server_dir=$(dirname "$server")
+    if [[ ! -d "$server_dir/node_modules/@modelcontextprotocol" ]]; then
+      need npm
+      echo "installing devkit MCP dependencies..."
+      (cd "$server_dir" && npm install --silent) || die "npm install failed in $server_dir"
+    fi
+    runcmd=(node "$server")
+  else
+    # Unscoped "devkit-mcp" is taken by an unrelated package on npm, so we publish under
+    # the @djadmin scope. npx fetches it on first use (then caches).
+    need npx
+    runcmd=(npx -y @djadmin/devkit-mcp)
   fi
 
   if command -v claude >/dev/null 2>&1; then
-    if claude mcp add devkit -- node "$server"; then
-      echo "devkit MCP registered with Claude Code. Restart Claude Code to load it."
+    if claude mcp add devkit -- "${runcmd[@]}"; then
+      echo "devkit MCP registered with Claude Code (${runcmd[*]}). Restart Claude Code to load it."
     else
-      die "failed to register the MCP with Claude Code (try: claude mcp add devkit -- node \"$server\")"
+      die "failed to register the MCP with Claude Code (try: claude mcp add devkit -- ${runcmd[*]})"
     fi
   else
     echo "Claude Code CLI not found. Add the devkit MCP to your agent manually:"
-    echo "  command: node"
-    echo "  args:    $server"
+    echo "  command: ${runcmd[0]}"
+    echo "  args:    ${runcmd[*]:1}"
     echo
-    echo "  Claude Code:  claude mcp add devkit -- node \"$server\""
+    echo "  Claude Code:  claude mcp add devkit -- ${runcmd[*]}"
     echo "  Cursor / Windsurf / other: see your agent's MCP config docs."
   fi
 }