starlight-mega-menu 1.0.2 → 1.0.4

package/.github/dependabot.yml

@@ -0,0 +1,40 @@
+---
+version: 2
+updates:
+  # --- GitHub Actions ---
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "chore(deps):"
+    labels:
+      - "dependencies"
+    assignees:
+      - "robinmordasiewicz"
+    open-pull-requests-limit: 10
+    groups:
+      actions-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  # --- npm ---
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "chore(deps):"
+    labels:
+      - "dependencies"
+    assignees:
+      - "robinmordasiewicz"
+    open-pull-requests-limit: 10
+    groups:
+      npm-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"

package/.github/workflows/release.yml

@@ -27,12 +27,12 @@ jobs:
     if: "!contains(github.event.head_commit.message, '[skip ci]') && !contains(github.event.head_commit.message, 'chore(release):')"
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 'lts/*'
           registry-url: 'https://registry.npmjs.org'

package/.pre-commit-config.yaml

@@ -0,0 +1,91 @@
+---
+# =============================================================================
+# GOVERNANCE CHECKS (fail-fast)
+#
+# These run FIRST. Direct commits to main are forbidden — all changes must
+# go through a pull request linked to a GitHub issue. If this hook fails:
+#
+#   1. Create a GitHub issue describing the change
+#   2. Create a feature branch:  git checkout -b feat/<issue>-description
+#   3. Commit to the feature branch, then open a PR with "Closes #<issue>"
+#
+# See CONTRIBUTING.md for the full workflow.
+# =============================================================================
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: no-commit-to-branch
+        name: "GOVERNANCE: never commit directly to main"
+        args: ["--branch", "main"]
+
+  # ===========================================================================
+  # Repository-specific hooks (escape hatch)
+  #
+  # Runs scripts/pre-commit-local.sh if present and executable. Repos use
+  # this for language-specific checks (ruff, eslint, tsc, etc.) that do not
+  # belong in the universal config.
+  # ===========================================================================
+  - repo: local
+    hooks:
+      - id: local-hooks
+        name: Repository-specific hooks
+        entry: bash -c 'if [ -x scripts/pre-commit-local.sh ]; then scripts/pre-commit-local.sh; fi'
+        language: system
+        always_run: true
+        pass_filenames: false
+
+  # ===========================================================================
+  # File hygiene
+  # ===========================================================================
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+      - id: check-yaml
+        args: ["--allow-multiple-documents"]
+      - id: check-json
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  # ===========================================================================
+  # Security
+  # ===========================================================================
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+
+  # ===========================================================================
+  # Linting
+  # ===========================================================================
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.38.0
+    hooks:
+      - id: yamllint
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.47.0
+    hooks:
+      - id: markdownlint
+        args: ["--fix"]
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.11.0.1
+    hooks:
+      - id: shellcheck
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.10
+    hooks:
+      - id: actionlint
+
+ci:
+  autofix_prs: true
+  autoupdate_schedule: weekly
+  skip: [local-hooks, gitleaks]

package/CLAUDE.md

@@ -2,17 +2,102 @@
 
 ## Repository Workflow
 
-This repo enforces a strict governance workflow. Follow it exactly:
+This repo enforces a strict governance workflow.
+**DO NOT STOP after creating a PR** — the task is
+not complete until the PR is merged, all post-merge
+workflows succeed, and local branches are cleaned.
 
-1. **Create a GitHub issue** before making any changes
-2. **Create a feature branch** from `main` — never commit to `main` directly
-3. **Open a PR** that links to the issue using `Closes #N`
-4. **CI must pass** — the "Check linked issues" check blocks PRs without a linked issue
-5. **Merge** — squash merge preferred, branch auto-deletes after merge
+### Making Changes (Steps 1-5)
 
-## Use the `/ship` Skill
+1. **Create a GitHub issue** before making any
+   changes
+2. **Create a feature branch** from `main` — never
+   commit to `main` directly
+3. **Commit changes** with conventional format
+   (`feat:`, `fix:`, `docs:`) and push to remote
+4. **Open a PR** that links to the issue using
+   `Closes #N` — fill out the PR template completely
+5. **Fix any CI failures** — monitor checks with
+   `gh pr checks <NUMBER>`, fix locally, push to
+   trigger re-runs
 
-When available, use `/ship` to handle the full workflow (issue creation, branch, commit, PR) in one step.
+### Waiting for Auto-Merge (Step 6)
+
+6. **Wait for auto-merge** — PRs merge automatically
+   (squash) once all CI checks pass. Poll until the
+   PR state is `MERGED`:
+
+   ```
+   gh pr view <NUMBER> --json state --jq '.state'
+   ```
+
+   If the PR is not merging, check for issues:
+
+   ```
+   gh pr view <NUMBER> --json mergeable,mergeStateStatus
+   ```
+
+### Post-Merge Monitoring (Steps 7-8)
+
+7. **Monitor post-merge workflows** — merging to
+   `main` triggers additional workflows (docs
+   builds, governance sync, etc.). Discover and
+   watch them:
+
+   ```
+   git checkout main && git pull origin main
+   MERGE_SHA=$(git rev-parse HEAD)
+   sleep 10
+   gh run list --branch main --commit $MERGE_SHA
+   gh run watch <RUN-ID> --exit-status
+   ```
+
+8. **Iterate on failures** — if any workflow fails:
+   - View logs: `gh run view <RUN-ID> --log-failed`
+   - Analyze the root cause
+   - Fix the code locally
+   - Create a new issue, branch, and PR with the fix
+   - Return to Step 5 and repeat until all workflows
+     pass
+   - For pre-existing failures unrelated to your
+     changes: create a GitHub issue (per CI
+     Monitoring rules below) and continue
+
+### Cleanup (Steps 9-10)
+
+9. **Clean up branches** — only after all workflows
+    succeed. Delete your feature branch and any other
+    stale local branches already merged to `main`:
+
+    ```
+    git branch -d <branch-name>
+    git branch --merged main | grep -v '^\*\|main' | xargs -r git branch -d
+    ```
+
+10. **Verify completion** — confirm clean state:
+
+    ```
+    git status
+    git branch
+    gh run list --branch main --limit 5
+    ```
+
+## Task Completion Criteria
+
+A task is **not complete** until ALL of the
+following are true:
+
+- GitHub issue created and linked to PR
+- PR merged to `main` via auto-merge
+- All workflows triggered by the merge completed
+  successfully
+- Local feature branch deleted
+- No stale merged branches remain locally
+- Current branch is `main` with clean working tree
+
+If any post-merge workflow fails due to your
+changes, fix and resubmit. Do not clean up branches
+until all workflows are green.
 
 ## Branch Naming
 
@@ -29,6 +114,167 @@ Use the format `<prefix>/<issue-number>-short-description`:
 - Every PR must link to an issue
 - Fill out the PR template completely
 - Follow conventional commit messages (`feat:`, `fix:`, `docs:`)
+- Never consider a task complete until post-merge workflows pass
+- Always delete local feature branches after successful merge
+- Always clean up stale merged branches and workspace clutter when noticed
+
+## CI Monitoring and Problem Reporting
+
+When monitoring CI workflows, **never ignore
+failures** — even pre-existing or unrelated ones.
+You are authorized to create GitHub issues without
+asking for confirmation. This is a standing
+instruction, not a suggestion.
+
+For every problem observed:
+
+1. **Immediately create a GitHub issue** — do not
+   ask whether to create it, just create it
+   - Use a clear, descriptive title
+   - Include the workflow run URL or relevant logs
+   - Note it was discovered during CI monitoring
+   - Apply the `bug` label
+2. **Continue with your primary task** — issue
+   creation must not block your current work
+3. **Report to the user** what issues you created
+
+Do not ask "Want me to create an issue?" — the
+answer is always yes. See a problem, file an issue,
+move on.
+
+## Workspace Hygiene
+
+Apply the same proactive approach as CI monitoring
+to local workspace cleanliness. Do not ignore
+problems just because they predate your current
+task.
+
+When you notice stale local branches, leftover
+files, or other workspace issues:
+
+1. **Fix it immediately** — delete merged branches,
+   remove temp files, clean up artifacts
+2. **Report what you cleaned** — tell the user what
+   housekeeping you performed
+3. **Do not skip cleanup because "it's not my
+   task"** — a clean workspace is everyone's
+   responsibility
+
+Stale branch cleanup command:
+
+```
+git branch --merged main | grep -v '^\*\|main' | xargs -r git branch -d
+```
+
+## Documentation Pipeline
+
+All repos publish docs to GitHub Pages using a
+shared pipeline:
+
+| Repo | Role |
+| ---- | ---- |
+| `f5xc-docs-theme` | Astro/Starlight config, CSS, logos, layout |
+| `f5xc-docs-builder` | Dockerfile, npm deps, build scripts |
+| `f5xc-template` | CI workflow, governance files |
+
+Content repos only need a `docs/` directory — the
+build container and workflow handle everything else.
+CI builds trigger when files in `docs/` change on
+`main`.
+
+### Where to make changes
+
+- **Site appearance, navigation, or Astro config** —
+  change `f5xc-docs-theme` (owns
+  `astro.config.mjs`, `content.config.ts`,
+  CSS, and logos)
+- **Build process, Docker image, or npm deps** —
+  change `f5xc-docs-builder` (owns the
+  Dockerfile and dependency set)
+- **CI workflow or governance files** —
+  change `f5xc-template`
+- **Page content and images** —
+  change the `docs/` directory in the content
+  repo itself
+- **Never** add `astro.config.mjs`,
+  `package.json`, or build config to a content
+  repo — the pipeline provides these
+
+## Content Authoring
+
+### Structure
+
+- Place `.md` or `.mdx` files in the `docs/`
+  directory
+- `docs/index.mdx` is required — include YAML
+  frontmatter with at least a `title:` field
+- Static assets (images, diagrams) go in
+  subdirectories like `docs/images/` — folders
+  with no `.md`/`.mdx` files are auto-mounted
+  as public assets
+- Reference assets with root-relative paths:
+  `![alt](/images/diagram.png)`
+
+### MDX Rules
+
+- Bare `<` is treated as a JSX tag — use `&lt;`
+  or wrap in backtick inline code
+- `{` and `}` are JSX expressions — use `\{`
+  and `\}` or wrap in backtick inline code
+- Never use curly braces in `.mdx` filenames
+
+### Local Preview
+
+Run the live dev server (restart to pick up
+changes):
+
+```bash
+docker run --rm -it \
+  -v "$(pwd)/docs:/content/docs" \
+  -p 4321:4321 \
+  --entrypoint sh \
+  ghcr.io/robinmordasiewicz/f5xc-docs-builder:latest \
+  -c '
+    npm install --legacy-peer-deps && \
+    npm update --legacy-peer-deps && \
+    cp /app/node_modules/f5xc-docs-theme/astro.config.mjs \
+       /app/astro.config.mjs && \
+    cp /app/node_modules/f5xc-docs-theme/src/content.config.ts \
+       /app/src/content.config.ts && \
+    cp -r /content/docs/* /app/src/content/docs/ && \
+    DOCS_TITLE=$(grep -m1 "^title:" /app/src/content/docs/index.mdx \
+      | sed "s/title: *[\"]*//;s/[\"]*$//") \
+    npx astro dev --host
+  '
+```
+
+Open `http://localhost:4321`. File changes on the
+host require restarting the container.
+
+If your `docs/` directory contains static asset
+subdirectories (images, diagrams — folders with
+no `.md`/`.mdx` files), add a volume mount for
+each one so they are served as public assets:
+
+```bash
+-v "$(pwd)/docs/images:/app/public/images:ro"
+```
+
+For a full production build:
+
+```bash
+docker run --rm \
+  -v "$(pwd)/docs:/content/docs:ro" \
+  -v "$(pwd)/output:/output" \
+  -e GITHUB_REPOSITORY="<owner>/<repo>" \
+  ghcr.io/robinmordasiewicz/f5xc-docs-builder:latest
+```
+
+Serve with `npx serve output/ -l 8080` and open
+`http://localhost:8080/<repo>/`.
+
+Full content authoring guide:
+<https://robinmordasiewicz.github.io/f5xc-docs-builder/06-content-authors/>
 
 ## Reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-mega-menu",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A HashiCorp-style mega-menu navigation plugin for Astro Starlight",
   "type": "module",
   "license": "MIT",