@stacksjs/defaults 0.72.102 → 0.73.0

package/ai/skills/stacks-guard/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: stacks-guard
-description: Use for safety rails — warns on destructive commands (rm -rf, DROP TABLE, force-push, git reset --hard) and provides freeze mode for focused debugging. Invoke with /stacks-guard.
+description: Use for safety rails in a Stacks project - detecting destructive commands (rm -rf, DROP TABLE, force-push, git reset --hard, migrate:fresh against production), installing a PreToolUse hook that blocks them before they run, freeze mode for focused debugging, and a pre-commit safety scan. Invoke with /stacks-guard.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
 ---
 
-# /stacks-guard — Safety Rails
+# /stacks-guard - Safety Rails
 
 Prevent destructive actions and enforce focus during debugging sessions.
 
 ## Destructive Command Detection
 
-### 🔴 CRITICAL — Block and require confirmation
+### 🔴 CRITICAL - Block and require confirmation
 
 | Pattern | Risk |
 |---------|------|
@@ -32,7 +32,7 @@ Risk: [what will be destroyed]
 Reversible: [yes/no]
 ```
 
-### 🟡 WARNING — Warn but allow
+### 🟡 WARNING - Warn but allow
 
 | Pattern | Risk |
 |---------|------|
@@ -44,11 +44,11 @@ Reversible: [yes/no]
 | Modifying `config/services.ts` | Contains API keys |
 | Modifying `storage/framework/core/*/src/index.ts` | Public package API |
 
-### 🟢 INFORMATIONAL — Note but don't block
+### 🟢 INFORMATIONAL - Note but don't block
 
 | Pattern | Note |
 |---------|------|
-| `git rebase` | History rewrite — ensure not shared |
+| `git rebase` | History rewrite - ensure not shared |
 | `bun update` (major versions) | May introduce breaking changes |
 | Modifying CI/CD config | Affects deployment pipeline |
 | Changing auth/permissions code | Security-sensitive |
@@ -85,14 +85,89 @@ Before commits, scan for:
 
 ## Stacks-Specific Guards
 
-- **Don't edit `storage/framework/types/*.d.ts`** — these are auto-generated
+- **Don't edit `storage/framework/types/*.d.ts`** - these are auto-generated
 - **Don't edit `storage/framework/defaults/app/Models/`** without also generating migrations
-- **Don't modify `config/services.ts` in commits** — contains API keys
-- **Check `storage/framework/core/*/package.json` versions** — workspace packages should stay in sync
+- **Don't modify `config/services.ts` in commits** - contains API keys
+- **Check `storage/framework/core/*/package.json` versions** - workspace packages should stay in sync
+
+## Make it enforcing
+
+Everything above is advisory: it works only while the agent is paying attention.
+A **PreToolUse hook** turns it into enforcement, because the harness runs it on
+every Bash call before the command executes.
+
+[scripts/block-destructive.sh](scripts/block-destructive.sh) is the hook. It
+reads the tool call on stdin, exits 2 with a message on stderr when the command
+matches a blocked pattern, and exits 0 otherwise. It blocks two lists: commands
+that are unrecoverable anywhere (`rm -rf /` or `~` or `.`, force-push,
+`reset --hard`, `clean -f`, `branch -D`, `DROP TABLE`, `TRUNCATE TABLE`), and
+commands that are routine locally but destructive against production
+(`migrate:fresh`, `seed --fresh`, `cloud:remove`, `cloud:cleanup`, gated on the
+command naming a production env).
+
+Deliberately not blocked: a plain `git push`, `rm -rf node_modules`,
+`buddy migrate:fresh` locally. A guard that fires on regenerable things gets
+turned off, and a guard that is off protects nothing.
+
+Credit: adapted from Matt Pocock's `git-guardrails-claude-code` skill (MIT),
+<https://github.com/mattpocock/skills>.
+
+### Install
+
+1. **Ask the scope.** This project (`.claude/settings.json`) or every project
+   (`~/.claude/settings.json`)?
+2. **Copy the script** to `.claude/hooks/block-destructive.sh` or
+   `~/.claude/hooks/block-destructive.sh`, and `chmod +x` it.
+3. **Register it.** Merge into the existing `hooks.PreToolUse` array rather than
+   overwriting the file:
+
+   ```json
+   {
+     "hooks": {
+       "PreToolUse": [
+         {
+           "matcher": "Bash",
+           "hooks": [
+             {
+               "type": "command",
+               "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-destructive.sh"
+             }
+           ]
+         }
+       ]
+     }
+   }
+   ```
+
+   For the global install, the command is `~/.claude/hooks/block-destructive.sh`.
+4. **Tune the lists.** Ask the user what to add or remove. A repo that never
+   deploys does not need the production list. A repo with a protected `main` may
+   want a plain `git push` blocked too.
+5. **Verify.** Each of these should print a BLOCKED line and exit 2:
+
+   ```bash
+   echo '{"tool_input":{"command":"git push --force origin main"}}' | .claude/hooks/block-destructive.sh
+   ```
+
+   And each of these should exit 0 silently:
+
+   ```bash
+   echo '{"tool_input":{"command":"rm -rf node_modules"}}' | .claude/hooks/block-destructive.sh
+   ```
+
+`.claude/` is gitignored in a Stacks project, so a project-scope install is
+per-developer. To make it a team rule, commit the script under `scripts/` and
+have `buddy setup:ai` users point their hook at that path.
 
 ## Rules
 
 - **Never silently allow destructive commands.**
-- **Don't be annoying.** `rm file.txt` doesn't need a warning. `rm -rf node_modules` is fine — it's regenerable.
+- **Don't be annoying.** `rm file.txt` doesn't need a warning. `rm -rf node_modules` is fine - it's regenerable.
 - **Respect user intent.** After warning once, if confirmed, proceed.
-- **Context matters.** Force-push to personal branch ≠ force-push to main.
+- **Context matters.** Force-push to a personal branch is not force-push to main.
+
+## Downstream
+
+> Guard installed? `/stacks-retro` is where a near-miss becomes a permanent
+> check, and `/stacks-wizard` is for the production steps a human should be
+> doing by hand anyway.

package/ai/skills/stacks-guard/scripts/block-destructive.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Claude Code PreToolUse hook: block destructive commands before they run.
+#
+# Reads the tool call on stdin, exits 2 with a message on stderr when the
+# command matches a blocked pattern, and exits 0 otherwise.
+#
+# Adapted from Matt Pocock's `git-guardrails-claude-code` skill (MIT),
+# https://github.com/mattpocock/skills
+#
+# Install: see the stacks-guard skill. Customise the two pattern lists below;
+# they are a starting point, not a policy.
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+if command -v jq >/dev/null 2>&1; then
+  COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
+else
+  # No jq: fall back to the raw payload. Coarser, but it still matches.
+  COMMAND="$INPUT"
+fi
+
+[[ -z "$COMMAND" ]] && exit 0
+
+# Unrecoverable. These destroy work or data that no command brings back.
+BLOCKED=(
+  'rm[[:space:]]+-[a-zA-Z]*[rR][a-zA-Z]*f?[[:space:]]+(/|~|\.)([[:space:]]|$)'
+  'git[[:space:]]+push[[:space:]].*--force'
+  'git[[:space:]]+push[[:space:]].*-f([[:space:]]|$)'
+  'git[[:space:]]+reset[[:space:]]+--hard'
+  'git[[:space:]]+clean[[:space:]]+-[a-zA-Z]*f'
+  'git[[:space:]]+branch[[:space:]]+-D'
+  'git[[:space:]]+checkout[[:space:]]+--[[:space:]]+\.'
+  'git[[:space:]]+restore[[:space:]]+\.'
+  'DROP[[:space:]]+(TABLE|DATABASE|SCHEMA)'
+  'TRUNCATE[[:space:]]+TABLE'
+)
+
+# Destructive only against production. Same commands are routine locally.
+PROD_BLOCKED=(
+  '(buddy|bud|stacks)[[:space:]]+migrate:fresh'
+  '(buddy|bud|stacks)[[:space:]]+seed[[:space:]].*--fresh'
+  '(buddy|bud|stacks)[[:space:]]+cloud:remove'
+  '(buddy|bud|stacks)[[:space:]]+cloud:cleanup'
+)
+
+for pattern in "${BLOCKED[@]}"; do
+  if printf '%s' "$COMMAND" | grep -qE "$pattern"; then
+    printf 'BLOCKED: this command matches the destructive pattern /%s/ and the user has not authorised it. Ask them to run it themselves, or propose a reversible alternative.\n' "$pattern" >&2
+    exit 2
+  fi
+done
+
+# A command is production-facing when it says so, or when it is reading a
+# production env file.
+if printf '%s' "$COMMAND" | grep -qE '(APP_ENV=production|NODE_ENV=production|--env[= ]production|\.env\.production)'; then
+  for pattern in "${PROD_BLOCKED[@]}"; do
+    if printf '%s' "$COMMAND" | grep -qE "$pattern"; then
+      printf 'BLOCKED: this command matches /%s/ against production. It drops or removes live infrastructure. Ask the user to run it themselves.\n' "$pattern" >&2
+      exit 2
+    fi
+  done
+fi
+
+exit 0

package/ai/skills/stacks-handoff/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: stacks-handoff
+description: Compact the current conversation into a portable handoff document for another agent or session to pick up.
+disable-model-invocation: true
+argument-hint: "What will the next session be used for?"
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Handoff
+
+Write a handoff document summarising the current conversation so a fresh agent
+can continue the work. Save it to the OS temp directory, not the workspace: a
+handoff is scaffolding for one hop, and a stray `HANDOFF.md` in the repo is
+sediment.
+
+If the user passed an argument, treat it as a description of what the next
+session will focus on and tailor the document to that.
+
+Credit: adapted from Matt Pocock's `handoff` skill (MIT),
+<https://github.com/mattpocock/skills>.
+
+## What goes in
+
+- **The goal**, in one paragraph. What the next session is trying to achieve.
+- **Where things stand.** What is done, what is in flight, what is untouched.
+- **The decisions already made, and why.** This is the part a summary of the
+  diff cannot recover, so it is the part worth the most words.
+- **What is known to be broken or unverified.** Name the command that would
+  prove it either way.
+- **Suggested skills.** Name which `stacks-*` skills the next agent should call
+  the Skill tool for. A handoff that does not point at `stacks-orm` before a
+  model change is handing over a landmine.
+- **Open questions** the next session has to resolve, or take back to the user.
+
+## What stays out
+
+Do not duplicate content already captured elsewhere. Reference it by path,
+branch, URL or commit instead:
+
+- Committed code and its diff.
+- A spec, plan or ADR already written to disk.
+- An issue or PR on the tracker.
+- Anything a `stacks-*` skill already documents. Point at the skill.
+
+## Redact before you write
+
+The document leaves this session, so treat it as publishable. Write
+`<REDACTED>` in place of:
+
+- Anything from `.env`, `.env.production` or `config/services.ts`.
+- `APP_KEY`, AWS keys, `HCLOUD_TOKEN`, registrar and DNS API tokens, database
+  URLs with credentials in them.
+- Personal data pulled out of a database during the session.
+
+Reference the variable name and where it lives, never the value.
+
+## Finish
+
+Tell the user the absolute path, and say in one line what the next session
+should do first.
+
+## Before you hand off at all
+
+A handoff is narrow. It buys **portability**, and you only need it when
+something is actually travelling: a different agent, a different directory or
+repo, a colleague, or a side task forked mid-phase. If none of those apply, the
+cheaper moves are to continue, to clear, or to compact. `stacks-flow` has the
+ordered tree.

package/ai/skills/stacks-health/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-health
-description: Use when implementing health checks in a Stacks application — service monitoring, health endpoints, or diagnostic checks. Covers @stacksjs/health (currently WIP — Oh Dear integration planned).
+description: Use when implementing health checks in a Stacks application - service monitoring, health endpoints, or diagnostic checks. Covers @stacksjs/health (currently WIP - Oh Dear integration planned).
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-http/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-http
-description: Use when working with HTTP utilities in a Stacks application — HTTP status codes, making outbound HTTP requests via HttxClient, reactive fetch composables (useFetch/createFetch), or HTTP-related helpers. Covers @stacksjs/http, @stacksjs/httx, and the fetch composables in @stacksjs/composables.
+description: Use when working with HTTP utilities in a Stacks application - HTTP status codes, making outbound HTTP requests via HttxClient, reactive fetch composables (useFetch/createFetch), or HTTP-related helpers. Covers @stacksjs/http, @stacksjs/httx, and the fetch composables in @stacksjs/composables.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-i18n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-i18n
-description: Use when working with internationalization in a Stacks application — translations, locale management, pluralization, date/number/currency formatting, or loading translation files. Covers @stacksjs/i18n with translator, formatter, loader, and pluralization modules.
+description: Use when working with internationalization in a Stacks application - translations, locale management, pluralization, date/number/currency formatting, or loading translation files. Covers @stacksjs/i18n with translator, formatter, loader, and pluralization modules.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob