Chore/audit fixes 20260601 2103 (#84)

* fix(docs): strip all backticks when parsing script catalog cells

stripBackticks only removed leading/trailing backticks, so a cell like `path` (note) left a trailing backtick on the split token — scripts-catalog.json shipped 'dev/preflight-host-dev.sh`'. Strip every backtick and regenerate.

Audit: F001

* ci(infra): unify docker action versions across workflows

validate-compose pinned docker/build-push-action@v6.18.0 and setup-buildx@v3.10.0 while the release workflow used v7.2.0 / v4.1.0. Align on the newer pins so each action resolves to one SHA repo-wide.

Audit: F003 (parity lint-meta rule tracked as follow-up)

* chore(ui): align eslint-plugin-env-access to 0.1.3 (matches api)

Shared env-access rule was enforced at 0.1.1 in ui vs 0.1.3 in api; unify so the same env-access checks run in both apps.

Audit: F004

* chore(api,docs): declare engines.node to match ui

ui pins engines.node >=24.0.0; api had only bun and docs none, despite all three using Node tooling (tsx/knip/node *.mjs). Declare consistently so older-Node environments get a warning.

Audit: F006

* chore(docs): pin dependencies to exact versions (match api/ui)

apps/docs used caret ranges while api/ui pin exact. Pinned each dep to its currently-resolved version (astro 6.3.6, sharp 0.34.5, etc. — not the caret floor) so installs are deterministic and --frozen-lockfile stays satisfiable.

Audit: F005

* test(api): cover web-push channel + extend test-sibling rule to .channel.ts

Guardrail-first: web-push.channel.ts had no test while its email/in-app/sse peers did. Extend logic-files-require-test-sibling to include .channel.ts so the gap surfaces as a lint:meta violation, then add the missing test (suppressed-on-no-subscriptions + missing-delivery-row no-op). Full api suite green (1052 pass).

Audit: F008

* docs: list the audit-monorepo and execute-audit skills on /skills/

Adds an 'Audit skills' section documenting the repo-root /audit-monorepo (read-only JSON audit) and /execute-audit (autonomous guardrail-first remediation) skills, and notes that root .claude/skills/ holds cross-app/audit skills.

Audit: docs follow-up (user request)

Author: agjs

.github/workflows/infra-compose-validate-compose.yml

@@ -196,11 +196,11 @@ jobs:
 
       - name: Set up Docker Buildx
         if: steps.filter.outputs.code == 'true'
-        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3.10.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
 
       - name: Build apps/api prod image
         if: steps.filter.outputs.code == 'true'
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           context: apps/api
           file: apps/api/Dockerfile.prod
@@ -212,7 +212,7 @@ jobs:
 
       - name: Build apps/ui prod image
         if: steps.filter.outputs.code == 'true'
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           context: apps/ui
           file: apps/ui/Dockerfile.prod

apps/api/package.json

@@ -6,6 +6,7 @@
   "private": true,
   "module": "src/index.ts",
   "engines": {
+    "node": ">=24.0.0",
     "bun": "1.3.14"
   },
   "packageManager": "bun@1.3.14",

apps/api/scripts/lint-meta/rules/testing/logic-files-require-test-sibling.ts

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { collectSourceFiles } from "../../context";
 import type { IMetaRule, IViolation } from "../../types";
 
-const SUFFIX_REQUIRES_TEST = /\.(service|utils|jobs|check)\.ts$/u;
+const SUFFIX_REQUIRES_TEST = /\.(service|utils|jobs|check|channel)\.ts$/u;
 
 export function checkLogicFilesHaveTests(root: string): IViolation[] {
   const violations: IViolation[] = [];
@@ -31,7 +31,7 @@ export function checkLogicFilesHaveTests(root: string): IViolation[] {
       rule: "logic-files-require-test-sibling",
       message: `Missing unit-test sibling. Expected \`${expectedTest.slice(
         root.length + 1
-      )}\` to exist alongside this \`*.{service,utils,jobs,check}.ts\` module — every piece of logic ships with a test.`,
+      )}\` to exist alongside this \`*.{service,utils,jobs,check,channel}.ts\` module — every piece of logic ships with a test.`,
     });
   }
 

apps/api/tests/lib/notifications/channels/web-push.channel.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  cleanDatabase,
+  db,
+  eq,
+  notification,
+  notificationDelivery,
+  requireDb,
+  users,
+} from "../../../helpers/db";
+import {
+  defineNotificationEvent,
+  webPushChannel,
+} from "../../../../src/lib/notifications";
+import { t } from "elysia";
+
+const insertTestUser = async (): Promise<string> => {
+  const [created] = await db
+    .insert(users)
+    .values({
+      email: "web-push-channel-test@example.com",
+      firstName: "W",
+      lastName: "P",
+    })
+    .returning();
+
+  if (!created) {
+    throw new Error("Failed to insert test user");
+  }
+
+  return created.id;
+};
+
+const testEvent = defineNotificationEvent({
+  type: "test.web_push.channel",
+  schema: t.Object({ message: t.String() }),
+  defaultChannels: ["in-app"],
+  render: {
+    inApp: ({ payload }) => ({
+      title: "web-push test",
+      body: payload.message,
+    }),
+  },
+});
+
+describe("webPushChannel.dispatch", () => {
+  beforeEach(async () => {
+    if (!(await requireDb())) {
+      return;
+    }
+
+    await cleanDatabase();
+  });
+
+  afterEach(async () => {
+    if (!(await requireDb())) {
+      return;
+    }
+
+    await cleanDatabase();
+  });
+
+  test("suppresses the delivery when the recipient has no push subscriptions", async () => {
+    if (!(await requireDb())) {
+      return;
+    }
+
+    const userId = await insertTestUser();
+    const [noti] = await db
+      .insert(notification)
+      .values({
+        recipientUserId: userId,
+        eventType: testEvent.type,
+        payload: { message: "hi" },
+        rendered: { title: "t", body: "b" },
+      })
+      .returning();
+
+    if (!noti) {
+      throw new Error("Failed to insert notification");
+    }
+
+    await db.insert(notificationDelivery).values({
+      notificationId: noti.id,
+      channel: "web-push",
+      status: "pending",
+    });
+
+    await webPushChannel.dispatch({
+      notificationId: noti.id,
+      recipientUserId: userId,
+      event: testEvent,
+      payload: { message: "hi" },
+      rendered: { title: "t", body: "b" },
+    });
+
+    const [row] = await db
+      .select()
+      .from(notificationDelivery)
+      .where(eq(notificationDelivery.notificationId, noti.id));
+
+    expect(row?.status).toBe("suppressed");
+    expect(row?.error).toBe("no_subscriptions");
+  });
+
+  test("is a no-op when the web-push delivery row is missing", async () => {
+    if (!(await requireDb())) {
+      return;
+    }
+
+    const userId = await insertTestUser();
+    const missingNotificationId = "00000000-0000-0000-0000-000000000000";
+
+    await webPushChannel.dispatch({
+      notificationId: missingNotificationId,
+      recipientUserId: userId,
+      event: testEvent,
+      payload: { message: "hi" },
+      rendered: { title: "t", body: "b" },
+    });
+
+    const rows = await db
+      .select()
+      .from(notificationDelivery)
+      .where(eq(notificationDelivery.notificationId, missingNotificationId));
+
+    expect(rows).toHaveLength(0);
+  });
+});

apps/docs/bun.lock

@@ -4,6 +4,10 @@
   "version": "0.1.0",
   "private": true,
   "description": "boringstack.xyz docs site for the BoringStack project. Astro Starlight, deployed via Cloudflare Pages.",
+  "engines": {
+    "node": ">=24.0.0",
+    "bun": "1.3.14"
+  },
   "packageManager": "bun@1.3.14",
   "scripts": {
     "dev": "astro dev",
@@ -25,24 +29,24 @@
     "a11y": "bash scripts/a11y.sh"
   },
   "dependencies": {
-    "@astrojs/react": "^5.0.5",
-    "@astrojs/sitemap": "^3.7.2",
-    "@astrojs/starlight": "^0.39.2",
-    "@tailwindcss/vite": "^4.3.0",
-    "astro": "^6.3.5",
-    "astro-mermaid": "^2.0.1",
-    "clsx": "^2.1.1",
+    "@astrojs/react": "5.0.5",
+    "@astrojs/sitemap": "3.7.2",
+    "@astrojs/starlight": "0.39.2",
+    "@tailwindcss/vite": "4.3.0",
+    "astro": "6.3.6",
+    "astro-mermaid": "2.0.1",
+    "clsx": "2.1.1",
     "mermaid": "11.15.0",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "reading-time": "^1.5.0",
-    "sharp": "^0.34.0",
-    "tailwindcss": "^4.3.0",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
+    "reading-time": "1.5.0",
+    "sharp": "0.34.5",
+    "tailwindcss": "4.3.0",
     "ws": "8.20.1"
   },
   "devDependencies": {
-    "@axe-core/cli": "^4.11.3",
-    "http-server": "^14.1.1",
+    "@axe-core/cli": "4.11.3",
+    "http-server": "14.1.1",
     "starlight-llms-txt": "0.6.1",
     "wrangler": "4.93.0"
   },

apps/docs/package.json

@@ -94,7 +94,10 @@ function parseMarkdownTableSection(text, heading) {
 }
 
 function stripBackticks(value) {
-  return value.replace(/^`+|`+$/gu, "").trim();
+  // Remove every backtick, not just leading/trailing. Markdown cells like
+  // `` `path/to/script.sh` (then X) `` carry an inline closing backtick that a
+  // start/end-only strip would leave on the token after a whitespace split.
+  return value.replace(/`/gu, "").trim();
 }
 
 function parseCommandName(cell, runner) {

apps/docs/scripts/docs-catalog-lib.mjs

@@ -3,7 +3,7 @@ title: Agent skills
 description: Slash-command skills shipped with BoringStack. Each one encodes a task, its conventions, and a ready-to-paste prompt.
 ---
 
-BoringStack ships agent skills in `apps/api/.claude/skills/` and `apps/ui/.claude/skills/`. Each skill is a markdown file with a prompt that an agent follows. Type the skill name (e.g., `/add-full-feature`) in Claude Code or Cursor and the agent runs the workflow.
+BoringStack ships agent skills in the repo root `.claude/skills/` (cross-app and audit skills) and per-app in `apps/api/.claude/skills/` and `apps/ui/.claude/skills/`. Each skill is a markdown file with a prompt that an agent follows. Type the skill name (e.g., `/add-full-feature`) in Claude Code or Cursor and the agent runs the workflow.
 
 ## Full-stack skills
 
@@ -41,6 +41,28 @@ Checks BoringStack-specific invariants: ACL ability checks on every route, multi
 
 On the UI: no raw `fetch` outside `openapi.ts`, no `dangerouslySetInnerHTML`, no `import.meta.env` outside `src/lib/env/`, no token storage in `localStorage`, no JSX strings without i18n, CSRF + content-type validation.
 
+## Audit skills
+
+Two repo-root skills that pair up for autonomous, agent-to-agent maintenance. The
+audit is machine-readable on purpose: one agent finds the work, another executes it.
+
+### /audit-monorepo
+
+Read-only, full-monorepo audit (apps/api, apps/ui, apps/docs, infra, scripts, CI). Fans
+out parallel read-only subagents per app and concern, then writes a single
+evidence-backed JSON report to `.audit/audit-report.json` — every finding cites exact
+files, ranked for an autonomous agent to execute. Each finding is also classified by
+whether a linter/parser **guardrail** could enforce it, so fixes extend the tooling
+rather than patch one instance ("lint as a contract").
+
+### /execute-audit
+
+Reads `.audit/audit-report.json` and works every finding to completion on a single
+branch. Guardrail-first: when a finding is a class a rule can catch, it extends the
+relevant `lint:meta` rule so the bug surfaces as a violation, then fixes the code —
+validating each fix with the repo's own `bun run check`, committing per finding, and
+reverting-and-continuing on failure.
+
 ## Related
 
 - [First feature in 10 minutes](/skills/first-feature-tutorial/)  - end-to-end walkthrough.