mirror of
https://github.com/obra/superpowers.git
synced 2026-06-16 15:49:05 +08:00
Compare commits
1 Commits
codex/shel
...
docs-porti
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
e881d97bfb |
13
README.md
13
README.md
@@ -4,7 +4,7 @@ Superpowers is a complete software development methodology for your coding agent
|
|||||||
|
|
||||||
## Quickstart
|
## Quickstart
|
||||||
|
|
||||||
Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [OpenCode](#opencode), [Pi](#pi).
|
Give your agent Superpowers: [Claude Code](#claude-code), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [OpenCode](#opencode), [Pi](#pi).
|
||||||
|
|
||||||
## How it works
|
## How it works
|
||||||
|
|
||||||
@@ -60,17 +60,6 @@ The Superpowers marketplace provides Superpowers and some other related plugins
|
|||||||
/plugin install superpowers@superpowers-marketplace
|
/plugin install superpowers@superpowers-marketplace
|
||||||
```
|
```
|
||||||
|
|
||||||
### Antigravity
|
|
||||||
|
|
||||||
Install Superpowers as a plugin from this repository:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
agy plugin install https://github.com/obra/superpowers
|
|
||||||
```
|
|
||||||
|
|
||||||
Antigravity runs the plugin's session-start hook, so Superpowers is active from
|
|
||||||
the first message. Reinstall with the same command to update.
|
|
||||||
|
|
||||||
### Codex App
|
### Codex App
|
||||||
|
|
||||||
Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
|
Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
|
||||||
|
|||||||
@@ -1,211 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
#
|
|
||||||
# Lint shell scripts in this repository.
|
|
||||||
#
|
|
||||||
# Usage:
|
|
||||||
# scripts/lint-shell.sh [--all] [--format] [--strict] [file ...]
|
|
||||||
#
|
|
||||||
# By default, runs ShellCheck and shell syntax checks on changed shell scripts.
|
|
||||||
# Use --format to format with shfmt before linting. Use --all for the full tracked
|
|
||||||
# baseline, or pass files explicitly to lint a smaller set.
|
|
||||||
set -euo pipefail
|
|
||||||
|
|
||||||
usage() {
|
|
||||||
sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'
|
|
||||||
}
|
|
||||||
|
|
||||||
die() {
|
|
||||||
echo "error: $*" >&2
|
|
||||||
exit 1
|
|
||||||
}
|
|
||||||
|
|
||||||
require_tool() {
|
|
||||||
command -v "$1" >/dev/null 2>&1 || die "required tool '$1' is not on PATH"
|
|
||||||
}
|
|
||||||
|
|
||||||
is_shell_file() {
|
|
||||||
local path="$1"
|
|
||||||
local first_line=""
|
|
||||||
|
|
||||||
[[ -f "$path" ]] || return 1
|
|
||||||
|
|
||||||
case "$path" in
|
|
||||||
*.sh)
|
|
||||||
return 0
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
|
|
||||||
IFS= read -r first_line <"$path" || true
|
|
||||||
[[ "$first_line" =~ ^#!.*[/[:space:]](bash|dash|ksh|sh)([[:space:]]|$) ]]
|
|
||||||
}
|
|
||||||
|
|
||||||
ensure_git_work_tree() {
|
|
||||||
git rev-parse --is-inside-work-tree >/dev/null 2>&1 \
|
|
||||||
|| die "run this from inside a git work tree, or pass files explicitly"
|
|
||||||
}
|
|
||||||
|
|
||||||
add_shell_file() {
|
|
||||||
local path
|
|
||||||
local existing
|
|
||||||
|
|
||||||
path="$1"
|
|
||||||
if ! is_shell_file "$path"; then
|
|
||||||
return 0
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ "${#files[@]}" -gt 0 ]]; then
|
|
||||||
for existing in "${files[@]}"; do
|
|
||||||
if [[ "$existing" == "$path" ]]; then
|
|
||||||
return 0
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
fi
|
|
||||||
|
|
||||||
files+=("$path")
|
|
||||||
}
|
|
||||||
|
|
||||||
collect_all_shell_files() {
|
|
||||||
local path
|
|
||||||
|
|
||||||
ensure_git_work_tree
|
|
||||||
|
|
||||||
while IFS= read -r -d '' path; do
|
|
||||||
add_shell_file "$path"
|
|
||||||
done < <(git ls-files -z)
|
|
||||||
}
|
|
||||||
|
|
||||||
collect_changed_shell_files() {
|
|
||||||
local path
|
|
||||||
|
|
||||||
ensure_git_work_tree
|
|
||||||
|
|
||||||
if git rev-parse --verify HEAD >/dev/null 2>&1; then
|
|
||||||
while IFS= read -r -d '' path; do
|
|
||||||
add_shell_file "$path"
|
|
||||||
done < <(git diff --name-only -z --diff-filter=ACMR HEAD)
|
|
||||||
|
|
||||||
while IFS= read -r -d '' path; do
|
|
||||||
add_shell_file "$path"
|
|
||||||
done < <(git diff --cached --name-only -z --diff-filter=ACMR)
|
|
||||||
else
|
|
||||||
collect_all_shell_files
|
|
||||||
fi
|
|
||||||
|
|
||||||
while IFS= read -r -d '' path; do
|
|
||||||
add_shell_file "$path"
|
|
||||||
done < <(git ls-files --others --exclude-standard -z)
|
|
||||||
}
|
|
||||||
|
|
||||||
collect_requested_shell_files() {
|
|
||||||
local path
|
|
||||||
|
|
||||||
for path in "$@"; do
|
|
||||||
add_shell_file "$path"
|
|
||||||
done
|
|
||||||
}
|
|
||||||
|
|
||||||
syntax_shell_for() {
|
|
||||||
local path="$1"
|
|
||||||
local first_line=""
|
|
||||||
|
|
||||||
IFS= read -r first_line <"$path" || true
|
|
||||||
|
|
||||||
case "$first_line" in
|
|
||||||
*"/sh"* | *" env sh"* | *"/dash"* | *" env dash"*)
|
|
||||||
printf 'sh'
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
printf 'bash'
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
}
|
|
||||||
|
|
||||||
run_syntax_checks() {
|
|
||||||
local file
|
|
||||||
local shell_name
|
|
||||||
|
|
||||||
for file in "$@"; do
|
|
||||||
shell_name="$(syntax_shell_for "$file")"
|
|
||||||
case "$shell_name" in
|
|
||||||
sh)
|
|
||||||
sh -n "$file"
|
|
||||||
;;
|
|
||||||
bash)
|
|
||||||
bash -n "$file"
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
die "unsupported shell for syntax check: $shell_name"
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
done
|
|
||||||
}
|
|
||||||
|
|
||||||
format=false
|
|
||||||
strict=false
|
|
||||||
all=false
|
|
||||||
requested_files=()
|
|
||||||
|
|
||||||
while [[ $# -gt 0 ]]; do
|
|
||||||
case "$1" in
|
|
||||||
--all)
|
|
||||||
all=true
|
|
||||||
;;
|
|
||||||
--format)
|
|
||||||
format=true
|
|
||||||
;;
|
|
||||||
--strict)
|
|
||||||
strict=true
|
|
||||||
;;
|
|
||||||
-h | --help)
|
|
||||||
usage
|
|
||||||
exit 0
|
|
||||||
;;
|
|
||||||
--)
|
|
||||||
shift
|
|
||||||
requested_files+=("$@")
|
|
||||||
break
|
|
||||||
;;
|
|
||||||
-*)
|
|
||||||
die "unknown option: $1"
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
requested_files+=("$1")
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
shift
|
|
||||||
done
|
|
||||||
|
|
||||||
require_tool shellcheck
|
|
||||||
if [[ "$format" == true ]]; then
|
|
||||||
require_tool shfmt
|
|
||||||
fi
|
|
||||||
|
|
||||||
files=()
|
|
||||||
if [[ "${#requested_files[@]}" -gt 0 ]]; then
|
|
||||||
collect_requested_shell_files "${requested_files[@]}"
|
|
||||||
elif [[ "$all" == true ]]; then
|
|
||||||
collect_all_shell_files
|
|
||||||
else
|
|
||||||
collect_changed_shell_files
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ "${#files[@]}" -eq 0 ]]; then
|
|
||||||
echo "No shell files found."
|
|
||||||
exit 0
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ "$format" == true ]]; then
|
|
||||||
echo "Formatting ${#files[@]} shell files"
|
|
||||||
shfmt_args=(-i 2 -ci -bn)
|
|
||||||
shfmt "${shfmt_args[@]}" -w "${files[@]}"
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo "Linting ${#files[@]} shell files"
|
|
||||||
|
|
||||||
shellcheck_args=(--severity=warning --external-sources --source-path=SCRIPTDIR)
|
|
||||||
if [[ "$strict" == true ]]; then
|
|
||||||
shellcheck_args+=("--enable=check-extra-masked-returns,check-set-e-suppressed,quote-safe-variables,deprecate-which,avoid-nullary-conditions")
|
|
||||||
fi
|
|
||||||
|
|
||||||
shellcheck "${shellcheck_args[@]}" "${files[@]}"
|
|
||||||
run_syntax_checks "${files[@]}"
|
|
||||||
@@ -123,6 +123,16 @@ git branch -d <feature-branch>
|
|||||||
```bash
|
```bash
|
||||||
# Push branch
|
# Push branch
|
||||||
git push -u origin <feature-branch>
|
git push -u origin <feature-branch>
|
||||||
|
|
||||||
|
# Create PR
|
||||||
|
gh pr create --title "<title>" --body "$(cat <<'EOF'
|
||||||
|
## Summary
|
||||||
|
<2-3 bullets of what changed>
|
||||||
|
|
||||||
|
## Test Plan
|
||||||
|
- [ ] <verification steps>
|
||||||
|
EOF
|
||||||
|
)"
|
||||||
```
|
```
|
||||||
|
|
||||||
**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
|
**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
|
||||||
|
|||||||
@@ -41,7 +41,7 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw
|
|||||||
|
|
||||||
## Platform Adaptation
|
## Platform Adaptation
|
||||||
|
|
||||||
Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), [pi-tools.md](references/pi-tools.md), and [antigravity-tools.md](references/antigravity-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
|
Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), and [pi-tools.md](references/pi-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
|
||||||
|
|
||||||
# Using Skills
|
# Using Skills
|
||||||
|
|
||||||
|
|||||||
@@ -1,96 +0,0 @@
|
|||||||
# Antigravity CLI (`agy`) Tool Mapping
|
|
||||||
|
|
||||||
Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On the Antigravity CLI (`agy`) these resolve to the tools below.
|
|
||||||
|
|
||||||
| Action skills request | Antigravity CLI equivalent |
|
|
||||||
|----------------------|----------------------|
|
|
||||||
| Read a file | `view_file` |
|
|
||||||
| Create a new file | `write_to_file` |
|
|
||||||
| Edit a file | `replace_file_content` |
|
|
||||||
| Edit a file in several places at once | `multi_replace_file_content` |
|
|
||||||
| Run a shell command | `run_command` |
|
|
||||||
| Search file contents | `grep_search` |
|
|
||||||
| Find files by name / list a directory | `list_dir` (no dedicated glob tool — combine `list_dir` with `grep_search`) |
|
|
||||||
| Fetch a URL | `read_url_content` |
|
|
||||||
| Search the web | `search_web` |
|
|
||||||
| Pose a structured question to your human partner | `ask_question` |
|
|
||||||
| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName` — `self` for full-capability work, `research` for read-only (see [Subagent support](#subagent-support)) |
|
|
||||||
| Multiple parallel dispatches | Multiple entries in one `invoke_subagent` call's `Subagents` array |
|
|
||||||
| Task tracking ("create a todo", "mark complete") | a **task artifact** — `write_to_file` with `IsArtifact: true` and `ArtifactType: "task"` (see [Task tracking](#task-tracking)). **Not** `manage_task`, which manages background processes. |
|
|
||||||
|
|
||||||
## Invoking a skill — read its `SKILL.md`
|
|
||||||
|
|
||||||
Antigravity surfaces every installed skill's `name` + `description` to you at the
|
|
||||||
start of each session, but it has **no `Skill`/`activate_skill` tool**. To load a
|
|
||||||
skill, **read its `SKILL.md` with `view_file`, setting `IsSkillFile: true`** when
|
|
||||||
the skill applies — e.g. `view_file` on
|
|
||||||
`.../plugins/superpowers/skills/<skill-name>/SKILL.md` with `IsSkillFile: true`.
|
|
||||||
(`IsSkillFile` is agy's own signal that you're reading a file to *execute its
|
|
||||||
instructions*, not to edit or preview it — set it whenever you load a skill.)
|
|
||||||
|
|
||||||
This is the blessed skill-loading mechanism on this harness. The general rule
|
|
||||||
"never read skill files manually" means "don't bypass your platform's
|
|
||||||
skill-loading mechanism" — and on Antigravity, reading `SKILL.md` *is* that
|
|
||||||
mechanism. Reading it honors the rule rather than breaking it.
|
|
||||||
|
|
||||||
You already know which skills exist and what they're for: their names and
|
|
||||||
descriptions are in front of you at session start. When a description matches
|
|
||||||
what you're about to do, read that skill's `SKILL.md` before acting.
|
|
||||||
|
|
||||||
## Subagent support
|
|
||||||
|
|
||||||
Antigravity dispatches subagents with `invoke_subagent`, passing each one a
|
|
||||||
`TypeName` in the `Subagents` array. Two `TypeName`s are **built in** — use them
|
|
||||||
directly, no `define_subagent` needed:
|
|
||||||
|
|
||||||
- **`self`** — a full clone of you, with every tool you have (including
|
|
||||||
`write_to_file`/`replace_file_content`/`run_command`). The safe default for
|
|
||||||
general-purpose work: implementing, fixing, anything that edits files or runs
|
|
||||||
commands.
|
|
||||||
- **`research`** — read-only (file reading, `grep_search`, web/URL fetch; no write
|
|
||||||
or command access). Use it when you specifically want a subagent that can't make
|
|
||||||
changes — investigation and read-only review.
|
|
||||||
|
|
||||||
Call `define_subagent` only for a custom system prompt or capability mix: set
|
|
||||||
`enable_write_tools: true` to grant file edits **and** `run_command`,
|
|
||||||
`enable_subagent_tools` for nested dispatch, `enable_mcp_tools` for MCP. Then
|
|
||||||
invoke it by the name you gave it. (`manage_subagents` lists/kills running
|
|
||||||
subagents.)
|
|
||||||
|
|
||||||
Skills dispatch with `Subagent (general-purpose):` and either reference a
|
|
||||||
prompt-template file (e.g. `superpowers:subagent-driven-development`'s
|
|
||||||
`./implementer-prompt.md`) or supply an inline prompt. On Antigravity:
|
|
||||||
|
|
||||||
| Skill dispatch form | Antigravity equivalent |
|
|
||||||
|---------------------|----------------------|
|
|
||||||
| An implementer-style `*-prompt.md` template (writes code, runs tests) | Fill the template, then `invoke_subagent` with `TypeName: "self"` and the filled prompt |
|
|
||||||
| A read-only reviewer template (`spec-reviewer`, `code-quality-reviewer`, `code-reviewer`, `requesting-code-review`'s `./code-reviewer.md`) | `invoke_subagent` with `TypeName: "research"` and the filled review template |
|
|
||||||
| Inline prompt (no template referenced) | `invoke_subagent` with `TypeName: "self"` (or `"research"` if the task only reads) and your inline prompt |
|
|
||||||
|
|
||||||
### Prompt filling
|
|
||||||
|
|
||||||
Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or
|
|
||||||
`[FULL TEXT of task]`. Fill all placeholders before passing the complete prompt to
|
|
||||||
`invoke_subagent`. The prompt template itself contains the agent's role, review
|
|
||||||
criteria, and expected output format — the subagent will follow it.
|
|
||||||
|
|
||||||
### Parallel dispatch
|
|
||||||
|
|
||||||
Put multiple entries in a single `invoke_subagent` call's `Subagents` array to run
|
|
||||||
independent subagent work in parallel. Keep dependent tasks sequential, but do not
|
|
||||||
serialize independent subagent tasks just to preserve a simpler history.
|
|
||||||
|
|
||||||
## Task tracking
|
|
||||||
|
|
||||||
Antigravity has **no todo / `TodoWrite` tool** (`manage_task` manages background
|
|
||||||
processes — `list`/`kill`/`status`/`send_input` — it is *not* a checklist). When a
|
|
||||||
skill says to create a todo list or track tasks, maintain a **task artifact**: a
|
|
||||||
markdown checklist saved with `write_to_file` (`IsArtifact: true`,
|
|
||||||
`ArtifactMetadata.ArtifactType: "task"`), edited with `replace_file_content` /
|
|
||||||
`multi_replace_file_content` as you go.
|
|
||||||
|
|
||||||
At the start of any multi-step task, create the task artifact listing every step of
|
|
||||||
your plan. As you complete each step, edit the artifact to mark it done (`- [x]`).
|
|
||||||
If the plan changes, update the checklist. Keep it current — it is your source of
|
|
||||||
truth for what remains; once the conversation gets long, re-read it before starting
|
|
||||||
each step.
|
|
||||||
@@ -1,16 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
# Run all Antigravity (agy) integration tests.
|
|
||||||
set -euo pipefail
|
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
||||||
|
|
||||||
echo "=== Antigravity integration tests ==="
|
|
||||||
|
|
||||||
for t in "$SCRIPT_DIR"/test-*.sh; do
|
|
||||||
echo
|
|
||||||
echo ">>> $t"
|
|
||||||
bash "$t"
|
|
||||||
done
|
|
||||||
|
|
||||||
echo
|
|
||||||
echo "=== All Antigravity tests passed ==="
|
|
||||||
@@ -1,53 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
# Validate the Antigravity (agy) integration. agy installs the existing plugin
|
|
||||||
# directly (`agy plugin install <repo-url>`): it loads the bundled skills and
|
|
||||||
# runs the SessionStart hook for bootstrap, so there is no agy-specific scaffold
|
|
||||||
# to test. What IS agy-specific is the tool mapping — agy has no `Skill` tool and
|
|
||||||
# loads skills by reading SKILL.md with view_file — and SKILL.md pointing at it.
|
|
||||||
#
|
|
||||||
# Mirrors tests/pi/test-pi-extension.mjs's "tools reference documents
|
|
||||||
# harness-specific mappings" check. CI-safe: does not require `agy` installed.
|
|
||||||
set -euo pipefail
|
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
||||||
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
|
|
||||||
|
|
||||||
MAPPING="$REPO_ROOT/skills/using-superpowers/references/antigravity-tools.md"
|
|
||||||
SKILL="$REPO_ROOT/skills/using-superpowers/SKILL.md"
|
|
||||||
|
|
||||||
fail() { echo "FAIL: $*" >&2; exit 1; }
|
|
||||||
|
|
||||||
echo "test-antigravity-tools: checking Antigravity tool mapping"
|
|
||||||
|
|
||||||
# --- Mapping exists ---------------------------------------------------------
|
|
||||||
[ -f "$MAPPING" ] || fail "tool mapping missing at $MAPPING"
|
|
||||||
|
|
||||||
# --- Skill-load mechanism: view_file on SKILL.md (IsSkillFile), no Skill tool -
|
|
||||||
grep -qiE "view_file" "$MAPPING" \
|
|
||||||
|| fail "mapping does not document view_file as the file/skill-read tool"
|
|
||||||
grep -qiE "SKILL\.md" "$MAPPING" \
|
|
||||||
|| fail "mapping does not document reading SKILL.md as the skill-load path"
|
|
||||||
grep -q "IsSkillFile" "$MAPPING" \
|
|
||||||
|| fail "mapping does not document setting IsSkillFile when loading a skill"
|
|
||||||
|
|
||||||
# --- Core action→tool mappings are documented -------------------------------
|
|
||||||
for tool in write_to_file replace_file_content run_command grep_search invoke_subagent; do
|
|
||||||
grep -q "$tool" "$MAPPING" \
|
|
||||||
|| fail "mapping does not document the '$tool' tool"
|
|
||||||
done
|
|
||||||
|
|
||||||
# --- Subagents use the built-in self/research types -------------------------
|
|
||||||
grep -q '`self`' "$MAPPING" \
|
|
||||||
|| fail "mapping does not document the built-in 'self' subagent type"
|
|
||||||
grep -q '`research`' "$MAPPING" \
|
|
||||||
|| fail "mapping does not document the built-in 'research' subagent type"
|
|
||||||
|
|
||||||
# --- Task tracking documents the 'task' artifact mechanism ------------------
|
|
||||||
grep -qE 'ArtifactType.*task|task. artifact' "$MAPPING" \
|
|
||||||
|| fail "mapping does not document task tracking as a 'task' artifact"
|
|
||||||
|
|
||||||
# --- SKILL.md Platform Adaptation links the mapping -------------------------
|
|
||||||
grep -q "antigravity-tools.md" "$SKILL" \
|
|
||||||
|| fail "SKILL.md Platform Adaptation does not reference antigravity-tools.md"
|
|
||||||
|
|
||||||
echo "PASS: Antigravity tool mapping valid (view_file skill-load, agy tools, SKILL.md link)"
|
|
||||||
@@ -1,179 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
set -euo pipefail
|
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
|
||||||
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
|
|
||||||
SCRIPT_UNDER_TEST="$REPO_ROOT/scripts/lint-shell.sh"
|
|
||||||
|
|
||||||
FAILURES=0
|
|
||||||
TEST_ROOT="$(mktemp -d)"
|
|
||||||
|
|
||||||
cleanup() {
|
|
||||||
rm -rf "$TEST_ROOT"
|
|
||||||
}
|
|
||||||
trap cleanup EXIT
|
|
||||||
|
|
||||||
pass() {
|
|
||||||
echo " [PASS] $1"
|
|
||||||
}
|
|
||||||
|
|
||||||
fail() {
|
|
||||||
echo " [FAIL] $1"
|
|
||||||
FAILURES=$((FAILURES + 1))
|
|
||||||
}
|
|
||||||
|
|
||||||
assert_contains() {
|
|
||||||
local haystack="$1"
|
|
||||||
local needle="$2"
|
|
||||||
local description="$3"
|
|
||||||
|
|
||||||
if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
|
|
||||||
pass "$description"
|
|
||||||
else
|
|
||||||
fail "$description"
|
|
||||||
echo " expected to find: $needle"
|
|
||||||
echo " in:"
|
|
||||||
printf '%s\n' "$haystack" | sed 's/^/ /'
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
assert_not_contains() {
|
|
||||||
local haystack="$1"
|
|
||||||
local needle="$2"
|
|
||||||
local description="$3"
|
|
||||||
|
|
||||||
if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
|
|
||||||
fail "$description"
|
|
||||||
echo " did not expect to find: $needle"
|
|
||||||
echo " in:"
|
|
||||||
printf '%s\n' "$haystack" | sed 's/^/ /'
|
|
||||||
else
|
|
||||||
pass "$description"
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
configure_git_identity() {
|
|
||||||
local repo="$1"
|
|
||||||
|
|
||||||
git -C "$repo" config user.name "Test Bot"
|
|
||||||
git -C "$repo" config user.email "test@example.com"
|
|
||||||
}
|
|
||||||
|
|
||||||
write_stub_tool() {
|
|
||||||
local path="$1"
|
|
||||||
local name="$2"
|
|
||||||
|
|
||||||
cat >"$path" <<EOF
|
|
||||||
#!/usr/bin/env bash
|
|
||||||
{
|
|
||||||
printf '${name}:'
|
|
||||||
for arg in "\$@"; do
|
|
||||||
printf ' <%s>' "\$arg"
|
|
||||||
done
|
|
||||||
printf '\n'
|
|
||||||
} >> "\$SUPERPOWERS_SHELL_LINT_TEST_LOG"
|
|
||||||
exit 0
|
|
||||||
EOF
|
|
||||||
chmod +x "$path"
|
|
||||||
}
|
|
||||||
|
|
||||||
make_fixture_repo() {
|
|
||||||
local repo="$1"
|
|
||||||
|
|
||||||
git init -q -b main "$repo"
|
|
||||||
configure_git_identity "$repo"
|
|
||||||
|
|
||||||
mkdir -p "$repo/hooks"
|
|
||||||
cat >"$repo/tracked.sh" <<'EOF'
|
|
||||||
#!/usr/bin/env bash
|
|
||||||
echo "tracked"
|
|
||||||
EOF
|
|
||||||
cat >"$repo/hooks/session-start" <<'EOF'
|
|
||||||
#!/bin/sh
|
|
||||||
echo "extensionless"
|
|
||||||
EOF
|
|
||||||
cat >"$repo/README.md" <<'EOF'
|
|
||||||
# Fixture
|
|
||||||
|
|
||||||
```bash
|
|
||||||
echo "not a shell script"
|
|
||||||
```
|
|
||||||
EOF
|
|
||||||
cat >"$repo/untracked.sh" <<'EOF'
|
|
||||||
#!/usr/bin/env bash
|
|
||||||
echo "untracked"
|
|
||||||
EOF
|
|
||||||
|
|
||||||
git -C "$repo" add tracked.sh hooks/session-start README.md
|
|
||||||
git -C "$repo" commit -q -m "fixture"
|
|
||||||
|
|
||||||
printf '\necho "changed"\n' >>"$repo/tracked.sh"
|
|
||||||
printf '\necho "changed extensionless"\n' >>"$repo/hooks/session-start"
|
|
||||||
}
|
|
||||||
|
|
||||||
run_lint_shell() {
|
|
||||||
local repo="$1"
|
|
||||||
local fakebin="$2"
|
|
||||||
local log="$3"
|
|
||||||
shift 3
|
|
||||||
|
|
||||||
(
|
|
||||||
cd "$repo"
|
|
||||||
PATH="$fakebin:$PATH" \
|
|
||||||
SUPERPOWERS_SHELL_LINT_TEST_LOG="$log" \
|
|
||||||
bash "$SCRIPT_UNDER_TEST" "$@"
|
|
||||||
)
|
|
||||||
}
|
|
||||||
|
|
||||||
echo "Shell lint script tests"
|
|
||||||
|
|
||||||
fixture="$TEST_ROOT/repo"
|
|
||||||
fakebin="$TEST_ROOT/bin"
|
|
||||||
log="$TEST_ROOT/tool.log"
|
|
||||||
mkdir -p "$fixture" "$fakebin"
|
|
||||||
: >"$log"
|
|
||||||
write_stub_tool "$fakebin/shellcheck" "shellcheck"
|
|
||||||
write_stub_tool "$fakebin/shfmt" "shfmt"
|
|
||||||
make_fixture_repo "$fixture"
|
|
||||||
|
|
||||||
if output="$(run_lint_shell "$fixture" "$fakebin" "$log" 2>&1)"; then
|
|
||||||
pass "lint-shell check mode exits successfully with stub tools"
|
|
||||||
else
|
|
||||||
fail "lint-shell check mode exits successfully with stub tools"
|
|
||||||
printf '%s\n' "$output" | sed 's/^/ /'
|
|
||||||
fi
|
|
||||||
|
|
||||||
tool_log="$(cat "$log")"
|
|
||||||
assert_contains "$output" "Linting 3 shell files" "reports changed shell file count"
|
|
||||||
assert_not_contains "$tool_log" "shfmt:" "does not run shfmt in lint mode"
|
|
||||||
assert_contains "$tool_log" "shellcheck:" "runs ShellCheck"
|
|
||||||
assert_contains "$tool_log" "<--severity=warning>" "uses warning severity as the baseline"
|
|
||||||
assert_contains "$tool_log" "<--external-sources>" "allows ShellCheck to follow sourced files"
|
|
||||||
assert_contains "$tool_log" "<--source-path=SCRIPTDIR>" "resolves ShellCheck sources relative to each script"
|
|
||||||
assert_contains "$tool_log" "<hooks/session-start>" "includes changed extensionless shell shebang file"
|
|
||||||
assert_contains "$tool_log" "<tracked.sh>" "includes changed tracked .sh file"
|
|
||||||
assert_contains "$tool_log" "<untracked.sh>" "includes untracked shell files by default"
|
|
||||||
assert_not_contains "$tool_log" "README.md" "ignores Markdown with shell snippets"
|
|
||||||
|
|
||||||
: >"$log"
|
|
||||||
if output="$(run_lint_shell "$fixture" "$fakebin" "$log" --all --format 2>&1)"; then
|
|
||||||
pass "lint-shell --format exits successfully with stub tools"
|
|
||||||
else
|
|
||||||
fail "lint-shell --format exits successfully with stub tools"
|
|
||||||
printf '%s\n' "$output" | sed 's/^/ /'
|
|
||||||
fi
|
|
||||||
|
|
||||||
tool_log="$(cat "$log")"
|
|
||||||
assert_contains "$tool_log" "<-w>" "uses shfmt write mode with --format"
|
|
||||||
assert_contains "$tool_log" "shellcheck:" "runs ShellCheck after --format"
|
|
||||||
assert_contains "$tool_log" "<--severity=warning>" "keeps warning severity after --format"
|
|
||||||
assert_contains "$tool_log" "<hooks/session-start>" "--all includes tracked extensionless shell shebang file"
|
|
||||||
assert_contains "$tool_log" "<tracked.sh>" "--all includes tracked .sh file"
|
|
||||||
assert_not_contains "$tool_log" "untracked.sh" "--all ignores untracked shell files"
|
|
||||||
|
|
||||||
if [[ "$FAILURES" -eq 0 ]]; then
|
|
||||||
echo "All shell lint script tests passed"
|
|
||||||
else
|
|
||||||
echo "$FAILURES shell lint script test(s) failed"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
Reference in New Issue
Block a user