@hybridlabor-api/aos 4.8.0 → 4.9.0

package/skills/global_config/dockerfile-validator/scripts/test_validate.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# CI-friendly regression entrypoint for dockerfile-validator.
+# Runs syntax checks, regression tests, and optional ShellCheck linting.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+readonly SCRIPT_DIR
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+readonly SKILL_DIR
+
+VALIDATOR_SCRIPT="$SKILL_DIR/scripts/dockerfile-validate.sh"
+REGRESSION_SCRIPT="$SKILL_DIR/tests/test_regression.sh"
+STRICT_SHELLCHECK="${STRICT_SHELLCHECK:-false}"
+
+echo "Running dockerfile-validator CI checks..."
+
+# Fast syntax guard for scripts used by the regression suite.
+bash -n "$VALIDATOR_SCRIPT" "$REGRESSION_SCRIPT" "$0"
+
+# Regression coverage for parser/best-practice branches.
+bash "$REGRESSION_SCRIPT"
+
+if command -v shellcheck >/dev/null 2>&1; then
+    shellcheck "$VALIDATOR_SCRIPT" "$REGRESSION_SCRIPT" "$0"
+    echo "ShellCheck: PASS"
+elif [[ "$STRICT_SHELLCHECK" == "true" ]]; then
+    echo "ShellCheck: required but not installed (STRICT_SHELLCHECK=true)" >&2
+    exit 1
+else
+    echo "ShellCheck: SKIP (not installed; set STRICT_SHELLCHECK=true to require it)"
+fi
+
+echo "PASS: dockerfile-validator CI checks"

package/skills/global_config/dockerfile-validator/tests/fixtures/copy-before-yarn-lock-read.Dockerfile

@@ -0,0 +1,6 @@
+FROM node:20-alpine
+WORKDIR /app
+COPY . .
+RUN cat yarn.lock >/dev/null 2>&1 || true
+USER 1000
+CMD ["node", "server.js"]

package/skills/global_config/dockerfile-validator/tests/fixtures/copy-before-yarn.Dockerfile

@@ -0,0 +1,6 @@
+FROM node:20-alpine
+WORKDIR /app
+COPY . .
+RUN yarn
+USER 1000
+CMD ["node", "server.js"]

package/skills/global_config/dockerfile-validator/tests/fixtures/from-platform-nonroot.Dockerfile

@@ -0,0 +1,7 @@
+FROM --platform=linux/amd64 golang:1.24-alpine AS build
+WORKDIR /src
+RUN printf '#!/bin/sh\necho hello\n' > /out && chmod +x /out
+
+FROM --platform linux/amd64 gcr.io/distroless/static-debian11:nonroot AS runtime
+COPY --from=build /out /out
+ENTRYPOINT ["/out"]

package/skills/global_config/dockerfile-validator/tests/test_regression.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VALIDATOR="$SKILL_DIR/scripts/dockerfile-validate.sh"
+FIXTURES_DIR="$SKILL_DIR/tests/fixtures"
+TMP_DIR="$(mktemp -d)"
+
+cleanup() {
+    rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+
+pass() {
+    echo "  PASS: $1"
+    PASS=$((PASS + 1))
+}
+
+fail() {
+    echo "  FAIL: $1"
+    FAIL=$((FAIL + 1))
+}
+
+make_stub_tools() {
+    mkdir -p "$TMP_DIR/bin"
+
+    cat > "$TMP_DIR/bin/hadolint" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+exit 0
+EOF
+
+    cat > "$TMP_DIR/bin/checkov" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+exit 0
+EOF
+
+    chmod +x "$TMP_DIR/bin/hadolint" "$TMP_DIR/bin/checkov"
+}
+
+validator_output() {
+    local dockerfile="$1"
+    PATH="$TMP_DIR/bin:$PATH" bash "$VALIDATOR" "$dockerfile" 2>&1 || true
+}
+
+validator_exit_code() {
+    local dockerfile="$1"
+    local exit_code=0
+    PATH="$TMP_DIR/bin:$PATH" bash "$VALIDATOR" "$dockerfile" >/dev/null 2>&1 || exit_code=$?
+    echo "$exit_code"
+}
+
+assert_output_contains() {
+    local label="$1"
+    local dockerfile="$2"
+    local pattern="$3"
+
+    local output
+    output="$(validator_output "$dockerfile")"
+
+    if echo "$output" | grep -qE "$pattern"; then
+        pass "$label"
+    else
+        fail "$label (missing pattern: $pattern)"
+        echo "    --- validator output ---"
+        echo "$output" | sed 's/^/    /'
+        echo "    --- end output ---"
+    fi
+}
+
+assert_output_not_contains() {
+    local label="$1"
+    local dockerfile="$2"
+    local pattern="$3"
+
+    local output
+    output="$(validator_output "$dockerfile")"
+
+    if echo "$output" | grep -qE "$pattern"; then
+        fail "$label (unexpected pattern: $pattern)"
+        echo "    --- validator output ---"
+        echo "$output" | sed 's/^/    /'
+        echo "    --- end output ---"
+    else
+        pass "$label"
+    fi
+}
+
+assert_exit_zero() {
+    local label="$1"
+    local dockerfile="$2"
+
+    local exit_code
+    exit_code="$(validator_exit_code "$dockerfile")"
+
+    if [[ "$exit_code" -eq 0 ]]; then
+        pass "$label"
+    else
+        fail "$label (expected 0, got $exit_code)"
+    fi
+}
+
+echo "Running dockerfile-validator regression tests..."
+echo ""
+
+make_stub_tools
+
+COPY_BEFORE_YARN="$FIXTURES_DIR/copy-before-yarn.Dockerfile"
+COPY_BEFORE_YARN_LOCK="$FIXTURES_DIR/copy-before-yarn-lock-read.Dockerfile"
+FROM_PLATFORM_NONROOT="$FIXTURES_DIR/from-platform-nonroot.Dockerfile"
+
+echo "[copy-before-yarn]"
+assert_output_contains \
+    "flags COPY . before bare RUN yarn" \
+    "$COPY_BEFORE_YARN" \
+    "COPY \\. appears before dependency installation"
+assert_exit_zero \
+    "warn-only result stays non-failing" \
+    "$COPY_BEFORE_YARN"
+
+echo ""
+echo "[copy-before-yarn-lock-read]"
+assert_output_not_contains \
+    "does not misclassify yarn.lock as yarn install" \
+    "$COPY_BEFORE_YARN_LOCK" \
+    "COPY \\. appears before dependency installation"
+assert_exit_zero \
+    "non-install RUN after COPY . remains non-failing" \
+    "$COPY_BEFORE_YARN_LOCK"
+
+echo ""
+echo "[from-platform-nonroot]"
+assert_output_contains \
+    "parses --platform final image as non-root base" \
+    "$FROM_PLATFORM_NONROOT" \
+    "No USER directive, but final base image is non-root: gcr.io/distroless/static-debian11:nonroot"
+assert_output_not_contains \
+    "does not emit root warning for non-root distroless base" \
+    "$FROM_PLATFORM_NONROOT" \
+    "container will run as root"
+assert_output_contains \
+    "optimization stage reports parsed minimal final base" \
+    "$FROM_PLATFORM_NONROOT" \
+    "Using minimal base for final stage: gcr.io/distroless/static-debian11:nonroot"
+assert_output_not_contains \
+    "base image analysis never treats --platform as image" \
+    "$FROM_PLATFORM_NONROOT" \
+    "Consider Alpine alternative for: --platform"
+assert_exit_zero \
+    "platform flag fixture exits successfully" \
+    "$FROM_PLATFORM_NONROOT"
+
+echo ""
+echo "Summary: $PASS passed, $FAIL failed"
+
+if [[ "$FAIL" -ne 0 ]]; then
+    exit 1
+fi
+
+echo "PASS: dockerfile-validator regression tests"

package/skills/global_config/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: finishing-a-development-branch
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work
+category: engineering-method
+source: superpowers
+date_added: "2026-09-25"
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
+
+## Step 1: Verify Tests
+
+Run the project's full test suite (`npm test` / `cargo test` / `pytest` / `go test ./...`).
+
+**If tests fail**, report the failures and stop — the menu comes after a green suite:
+
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+```
+
+**If tests pass:** continue to Step 2.
+
+## Step 2: Detect Environment
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+# Capture now, while still inside the workspace — Step 5 changes directory
+# before cleanup (Step 6) needs this value
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+```
+
+This determines which menu to show and how cleanup works:
+
+| State | Menu | Cleanup |
+|-------|------|---------|
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 3 options | No worktree to clean up |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 3 options | Provenance-based (see Step 6) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 2 options (no merge) | Externally managed — leave in place |
+
+## Step 3: Determine Base Branch
+
+The base branch is whatever this work forked from — usually named in the
+plan, the conversation, or the branch's upstream. If it is not already
+known, ask: "This branch split from <your best guess> - is that correct?"
+Confirm before merging: merging into the wrong base is expensive to undo.
+
+## Step 4: Present Options
+
+**Normal repo and named-branch worktree — present exactly these 3 options:**
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+
+Which option?
+```
+
+**Detached HEAD — present exactly these 2 options:**
+
+```
+Implementation complete. You're on a detached HEAD (externally managed workspace).
+
+1. Push as new branch and create a Pull Request
+2. Keep as-is (I'll handle it later)
+
+Which option?
+```
+
+Present the menu exactly as written — concise, with every option coming
+from the list above. Discarding the work happens only in response to your
+human partner explicitly asking for it (see "If your human partner asks to
+discard the work" below). Wait for their answer; the integration decision
+is theirs.
+
+## Step 5: Execute Choice
+
+### Option 1: Merge Locally
+
+```bash
+# Get main repo root for CWD safety
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+# Merge first — verify success before removing anything
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+```
+
+If tests fail on the merged result: stop, leave the worktree and branch in
+place, and investigate — nothing has been pushed, so the merge is local
+and recoverable.
+
+Once the merged result is green: clean up the worktree (Step 6), then
+delete the branch:
+
+```bash
+git branch -d <feature-branch>
+```
+
+### Option 2: Push and Create PR
+
+```bash
+git push -u origin <feature-branch>
+# From a detached HEAD, name the new branch on the remote:
+# git push origin HEAD:refs/heads/<new-branch>
+```
+
+Then create the pull/merge request against <base-branch> with the forge's
+tooling — its CLI if one is available, or the creation URL most forges
+print when you push — following the repo's PR template and conventions if
+present, and report the URL to your human partner.
+
+Keep the worktree — your human partner iterates on PR feedback there.
+
+### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+### If your human partner asks to discard the work
+
+This path exists only as a response to an explicit request to throw the
+work away. Confirm first:
+
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for that exact confirmation. When it arrives:
+
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+```
+
+Then clean up the worktree (Step 6) and force-delete the branch:
+
+```bash
+git branch -D <feature-branch>
+```
+
+## Step 6: Cleanup Workspace
+
+**Runs for Option 1 and confirmed discards.** Options 2 and 3 always
+preserve the worktree. Both callers have already changed directory to the
+main repo root — worktree removal must run from outside the worktree —
+and use the `GIT_DIR`/`GIT_COMMON`/`WORKTREE_PATH` values captured in
+Step 2, from before that directory change.
+
+**If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
+
+**If `WORKTREE_PATH` is under `.worktrees/` or `worktrees/`:** Superpowers
+created this worktree — we own cleanup:
+
+```bash
+git worktree remove "$WORKTREE_PATH"
+git worktree prune  # Self-healing: clean up any stale registrations
+```
+
+**If removal is refused** (`contains modified or untracked files`): the
+worktree holds files that exist nowhere else — uncommitted plans, notes,
+or scratch work. Never `--force` on your own initiative. Show your human
+partner what is at stake and ask:
+
+```bash
+git -C "$WORKTREE_PATH" status --porcelain -uall
+```
+
+```
+Worktree removal refused — these files were never committed:
+
+<file list>
+
+1. Commit them to <branch> before cleanup
+2. Move them into <main repo root>
+3. Delete them (unrecoverable)
+
+Which?
+```
+
+Carry out the choice, then remove the worktree.
+
+**Otherwise:** The host environment owns this workspace — leave it in
+place. If your platform provides a workspace-exit tool, use it.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | yes | - | - | yes |
+| 2. Create PR | - | yes | yes | - |
+| 3. Keep as-is | - | - | yes | - |
+| Discard (explicit request only) | - | - | - | yes (force) |
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Tests passed earlier this session" | Run the suite on the tree you are about to integrate. A green run only proves the tree it ran on. |
+| "They obviously want it merged" | Integration is your human partner's decision. Present the menu and wait. |
+| "They seem done with this feature — I'll offer to discard it" | The menu is complete as written. Discard happens only when your human partner asks for it in so many words. |
+| "'Yeah, get rid of it' counts as confirmation" | Only the typed word `discard` authorizes deletion. |
+| "The PR is up, so the worktree is clutter now" | PR feedback gets fixed in that worktree. It stays until the work lands. |
+| "This other worktree looks stale — I'll clean it too" | Clean up only worktrees under `.worktrees/` or `worktrees/`. Everything else belongs to the host. |
+| "Removal refused — `--force` is just finishing the cleanup" | The refusal means files exist only in that worktree. `--force` destroys them permanently. Show your human partner and ask. |
+| "The merged-result failure is probably flaky" | A failing merged result stops everything. Branch and worktree stay put while you investigate. |
+| "The base branch is obviously main" | Confirm the fork point or ask. Merging into the wrong base is expensive to undo. |
+| "The push was rejected — force-push will fix it" | A rejected push means the remote moved. Investigate; force-push only on your human partner's explicit request. |