Merge pull request #14 from podverse/feature/app-gating

Feature/app gating

Author: mitchdowney

.cursor/skills/api-testing/SKILL.md

@@ -50,7 +50,7 @@ Use this skill when adding or changing auth endpoints, versioned routes, or any
 ## Quick reference
 
 - **Default execution strategy (agent/sandbox):** start with the leanest targeted integration test command that verifies the change (for example a single test file), then expand scope only if needed.
-- Run tests: `npm run test` from repo root (or `./scripts/nix/with-env npm run test` in Nix/agent). First step is the requirements check, then Vitest runs for `apps/api` and `apps/management-api` (globalSetup then test files), then for `metaboost-signing` and `@metaboost/rss-parser`.
+- Run tests: `npm run test:e2e:api` from repo root for API integration tests only (or `./scripts/nix/with-env npm run test:e2e:api` in Nix/agent). First step is the requirements check, then Vitest runs for `apps/api` and `apps/management-api`. For unit-only (no DB needed): `npm run test:unit`. Full suite: `npm test`.
 - Run one API integration test file (preferred during iteration): `./scripts/nix/with-env npm run test -w apps/api -- src/test/<file>.test.ts`
 - Test env: `apps/api/src/test/setup.ts` sets defaults (DB_PORT 5632, VALKEY_PORT 6579, DB_APP_NAME metaboost_app_test, etc.). globalSetup uses the same defaults so it can run without setupFiles.
 - Mailer in tests: No real SMTP. `auth-mailer.test.ts` sets `MAILER_ENABLED=true` and mocks `../lib/mailer/send.js` to capture tokens for verify-email, reset-password, and confirm-email-change.

.cursor/skills/global/SKILL.md

@@ -15,6 +15,7 @@ version: 1.1.1
 ## TypeScript
 
 - Extend `tsconfig.base.json` in apps. Use ESM (NodeNext). Avoid type assertions (`as`) when a better approach exists.
+- Prefer **named exports**; avoid `export default` in ordinary modules when a named export works. See **.cursor/skills/prefer-named-exports/SKILL.md** (Next.js `page` defaults excepted).
 
 ## Plan Management
 

.cursor/skills/prefer-named-exports/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: prefer-named-exports
+description: >-
+  Prefer named exports in TypeScript/ESM modules; avoid default exports when a named export
+  is sufficient. Use in Metaboost and Podverse when adding or editing modules, API routes, worker
+  commands, packages, and app code. Framework-required defaults are the exception.
+version: 1.0.0
+---
+
+# Prefer named exports
+
+## When to use
+
+- Creating or changing `.ts` / `.tsx` modules, `packages/*`, and app code in this monorepo.
+- Refactoring imports; choosing export style for a new function, component, or command.
+
+## Rules
+
+- **Prefer** `export function name`, `export const name`, and `export type` / `export { x }` so names stay stable at import sites and refactors are easier to trace.
+- **Avoid** `export default` for ordinary modules when there is a single main export: use a **named** export with a clear, stable name.
+
+## Exceptions (defaults are fine)
+
+- **Next.js (App Router)**: `page.tsx`, `layout.tsx`, and similar files that the framework **requires** as the default export.
+- **Stricter framework contracts**: e.g. Storybook or tooling that only accepts `export default` (prefer named exports in the same file for everything else, or a thin default wrapper that re-exports a named symbol).
+- **Generated or third-party patterns**: match the existing file’s style when the file is not yours to own.
+
+## Imports
+
+- Use `import { foo } from './bar.js'`, not `import foo from './bar.js'`, for named exports.
+- Re-exporting: `export { foo } from './bar.js'` in barrels instead of re-exporting a default with an alias, when possible.
+
+## Related
+
+- ESM: `.js` extension in import paths (see repo `tsconfig` / `.cursorrules` stack notes). The Podverse monorepo has the same skill for cross-repo consistency.

.cursor/skills/release-changelog/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: release-changelog
+description: "Keep the upcoming release note buffer updated on develop; ties into publish workflows (alpha → staging.N, beta → beta.N, main → RTM) and GitHub release/archive automation."
+---
+
+# Release changelog (Metaboost)
+
+## When to use
+
+When you ship or finish work that is **worth calling out** in preprod/prod release notes: behavior changes, new surfaces, important fixes, or ops-impacting updates—not every internal cleanup.
+
+## What to update
+
+- Edit [docs/operations/CHANGELOG-UPCOMING.md](../../docs/operations/CHANGELOG-UPCOMING.md) on **`develop` only** (promotion branches are triggers only—see [PUBLISH.md](../../PUBLISH.md)).
+
+## Conventions
+
+1. **Order** — **Most important first** (safety, security, data, then big features, then smaller fixes; skip low-signal items).
+2. **Wording** — Short, clear lines; link issues/PRs if useful.
+3. **Markers** — Put new bullets between `UPCOMING-AUTO-START` and `UPCOMING-AUTO-END` so post-publish automation can reset that block via PR. Notes **above** the block are not auto-cleared.
+4. **Brevity** — Concise, not a duplicate of git log.
+
+## Naming in CI
+
+- Git branch **`alpha`** still produces **`X.Y.Z-staging.N`** and float **`staging`** in GHCR (cluster “alpha” in GitOps is separate). Branch **`beta`** → `-beta.N` and `:beta`. Branch **`main`** → RTM **`X.Y.Z`** and `:prod`.
+
+## Related
+
+- [PUBLISH.md](../../PUBLISH.md) — full publish flow, Git tag, and GitOps pins.

.cursor/skills/unit-tests-confident-granularity/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: unit-tests-confident-granularity
+description: Enforces Metaboost unit-test scope at a confident-not-bulletproof level. Use when writing unit tests to avoid both under-testing and excessive combinatorial test complexity.
+version: 1.0.0
+---
+
+# Unit Tests - Confident Granularity
+
+## Goal
+
+Deliver strong confidence without turning test suites into unmaintainable exhaustive matrices.
+
+## Confident Coverage Rule
+
+For each critical module under test, include:
+
+1. Happy path behavior.
+2. Guard/rejection behavior for invalid input or state.
+3. Boundary behavior (limits, edge values, time windows).
+4. Safe-failure behavior (no privileged fallback).
+
+## Stop Conditions (Avoid Over-Testing)
+
+Do not keep adding unit tests once all are true:
+
+- Every meaningful branch has at least one direct assertion.
+- At least one representative negative case exists for each guard.
+- Additional cases only duplicate already-proven behavior.
+
+## What To Avoid
+
+- Exhaustive Cartesian permutations that do not add new behavior confidence.
+- Snapshot-heavy tests for business logic.
+- Tests that lock internal implementation details instead of module contract.
+
+## Permutation Sampling Guidance
+
+When a matrix is large, use representative rows:
+
+- One allow example per permission source (owner, admin, etc.).
+- One deny example per missing permission path.
+- One edge case for malformed/missing data.
+
+Add more rows only when they validate a different branch.

.cursor/skills/unit-tests-risk-first/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: unit-tests-risk-first
+description: Prioritizes unit tests by risk and regression impact in Metaboost. Use when adding or expanding unit tests so coverage is focused on auth, authorization, security boundaries, and high-reuse helpers before lower-risk code.
+version: 1.0.0
+---
+
+# Unit Tests - Risk First
+
+## Use This Skill When
+
+- Creating a new unit-test backlog.
+- Expanding coverage in a large area and deciding what to test first.
+- Choosing between multiple candidate modules for limited time.
+
+## Priority Order
+
+1. **Auth and identity boundaries**
+   - JWT claim handling, assertion verification, session/cookie safety.
+2. **Authorization decisions**
+   - Permission and role checks, allow/deny branching.
+3. **Security-sensitive transforms**
+   - Token hashing/expiry logic, request binding checks, serialization guards.
+4. **High-reuse helper logic**
+   - Shared helper functions used by multiple apps/packages.
+5. **UI utility logic**
+   - Frontend policy helpers that gate user actions.
+
+## Selection Rule
+
+When choosing the next test target, prefer modules with:
+
+- Higher blast radius (many callers or privileged code path).
+- Higher probability of silent failure (wrong allow/deny outcome).
+- Higher user/security impact if behavior drifts.
+
+Skip low-risk wrappers until higher-risk targets have coverage.
+
+## Required Output Shape
+
+When proposing or implementing tests, include:
+
+- Why this target is high-priority.
+- Which behavior branches are being covered.
+- Which lower-priority targets are intentionally deferred.

.cursor/skills/unit-tests-security-authz-template/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: unit-tests-security-authz-template
+description: Provides a repeatable case template for auth, permission, and security-sensitive unit tests in Metaboost. Use when testing JWT, assertion validation, cookie/session helpers, bucket policy, or similar allow/deny logic.
+version: 1.0.0
+---
+
+# Unit Tests - Security/Authz Template
+
+## Use This Skill When
+
+- Testing auth token helpers and claim validation.
+- Testing permission policy (bucket/admin/role/message CRUD decisions).
+- Testing security-sensitive request binding and replay controls.
+
+## Standard Case Template
+
+For each function/module, cover these case buckets:
+
+1. **Accept valid input**
+   - Confirm expected allow/success behavior.
+2. **Reject invalid input**
+   - Missing/empty/malformed token, claim, id, or mask.
+3. **Enforce boundary rule**
+   - Time window, max TTL, min/max limits, bitmask edge.
+4. **Enforce deny precedence**
+   - Non-owner/non-admin or missing permission bit remains denied.
+5. **Preserve safe failure**
+   - Errors return non-privileged result (`null`, `false`, or explicit reject response).
+
+## Assertions Checklist
+
+- Assert on outcome and error code/message contract where relevant.
+- Verify no accidental allow behavior in negative paths.
+- Keep fixtures minimal and explicit.
+- Mock only unstable boundaries (network, time, cache, external services).
+
+## Matrix Update Rule
+
+When introducing a new auth/authz/security module:
+
+1. Add the module to the active test target matrix plan.
+2. Add at least one test from each relevant case bucket above.
+3. Record any intentionally deferred cases and why they are lower priority.

.cursorrules

@@ -9,6 +9,7 @@
 - No `any` types
 - **Strict equality**: Use `===` and `!==` only (no `==` or `!=`).
 - **Avoid type assertions (`as`)**: Prefer proper types, optional chaining, type guards, or narrowing.
+- **Named exports**: Prefer named `export` in TypeScript modules; avoid `export default` when a named export works. Framework-required defaults (e.g. Next.js `page.tsx`) are the exception. See `.cursor/skills/prefer-named-exports/SKILL.md`.
 
 ## Formatting