@jaypie/mcp 0.8.43 → 0.8.45

package/dist/suites/docs/index.js

@@ -9,7 +9,7 @@ import { gt } from 'semver';
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.43#947cd2b1"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.45#115144e4"
     ;
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.8.43",
+  "version": "0.8.45",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/jaypie/1.2.42.md

@@ -0,0 +1,11 @@
+---
+version: 1.2.42
+date: 2026-04-19
+summary: Re-export jaypieApiKeyId and HTTP.HEADER.API_KEY via @jaypie/kit
+---
+
+## Changes
+
+- Bumped `@jaypie/kit` to `^1.2.8`, exposing:
+  - `jaypieApiKeyId(key, { namespace, salt? })` — derives a deterministic UUIDv5 from a hashed API key
+  - `HTTP.HEADER.API_KEY` (`"X-Api-Key"`)

package/release-notes/kit/1.2.8.md

@@ -0,0 +1,13 @@
+---
+version: 1.2.8
+date: 2026-04-19
+summary: Add jaypieApiKeyId helper and X-Api-Key HTTP header constant
+---
+
+## Changes
+
+- Added `jaypieApiKeyId(key, { namespace, salt? })` — derives a deterministic UUIDv5 from the hashed key, suitable for use as a user-facing DynamoDB id
+  - Same key + namespace always produces the same id; preserves direct `get-item` lookup (no GSI)
+  - Namespace is required (consumer-scoped) to avoid cross-application collisions
+  - `salt` passes through to `hashJaypieKey` (defaults to `process.env.PROJECT_SALT`)
+- Added `HTTP.HEADER.API_KEY` (`"X-Api-Key"`) to the HTTP header constants

package/release-notes/mcp/0.8.44.md

@@ -0,0 +1,11 @@
+---
+version: 0.8.44
+date: 2026-04-19
+summary: Pin cicd skill GitHub Actions to Node 24-native majors
+---
+
+## Changes
+
+- Documents the Node 24-native action majors (`actions/checkout@v6`, `actions/setup-node@v6`, `actions/cache@v5`, `actions/upload-artifact@v7`, `actions/download-artifact@v8`, `aws-actions/configure-aws-credentials@v6`) at the top of `skills/cicd.md`.
+- Updates example workflows in `skills/cicd.md`, `skills/cicd-actions.md`, and `skills/cicd-deploy.md` so scaffolds land on Node 24-native actions on the first pass, avoiding the Node 20 deprecation warning and `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` opt-in.
+- Updates `workspaces/documentation/docs/guides/cicd.md` to match.

package/release-notes/mcp/0.8.45.md

@@ -0,0 +1,12 @@
+---
+version: 0.8.45
+date: 2026-04-19
+summary: Document jaypieApiKeyId helper and UUIDv5 DynamoDB id pattern in the apikey skill
+---
+
+## Changes
+
+- Updated `skill("apikey")`:
+  - Added a "Derive UUID Id" section documenting `jaypieApiKeyId(key, { namespace, salt? })`
+  - Reworked the "DynamoDB Storage Pattern" section to recommend UUIDv5-from-hash as the primary pattern when the id is user-facing, with the raw hex hash pattern documented as the alternative for hidden presentation
+  - Contrasted both approaches with the `xid = hash` + GSI pattern

package/release-notes/testkit/1.2.36.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.36
+date: 2026-04-19
+summary: Add jaypieApiKeyId mock
+---
+
+## Changes
+
+- Added `jaypieApiKeyId` mock — returns the fixed UUID `"00000000-0000-5000-8000-000000000000"`

package/skills/apikey.md

@@ -5,7 +5,7 @@ related: dynamodb, secrets, style, tests
 
 # API Keys
 
-Jaypie provides three functions for working with API keys: `generateJaypieKey`, `validateJaypieKey`, and `hashJaypieKey`. Available from `jaypie` or `@jaypie/kit`.
+Jaypie provides four functions for working with API keys: `generateJaypieKey`, `validateJaypieKey`, `hashJaypieKey`, and `jaypieApiKeyId`. Available from `jaypie` or `@jaypie/kit`.
 
 ## Generate
 
@@ -144,6 +144,29 @@ Returns a 64-character hex string. Deterministic — same key and salt always pr
 2. `process.env.PROJECT_SALT` environment variable
 3. No salt — plain SHA-256 (logs a warning)
 
+## Derive UUID Id
+
+> **Version note:** `jaypieApiKeyId` requires `jaypie >= 1.2.22` / `@jaypie/kit >= 1.2.8`.
+
+`jaypieApiKeyId(key, { namespace, salt? })` derives a deterministic UUIDv5 from the hashed key. Use this when the id must be surfaced in UIs, API responses, or resource URLs — a 64-char hex hash is not ergonomic, but a UUID is:
+
+```typescript
+import { jaypieApiKeyId } from "jaypie";
+
+const APIKEY_NAMESPACE = "b85e1a7a-5c7e-4e7b-9b8e-7c3a9d2f4e5b";
+
+const id = jaypieApiKeyId(key, { namespace: APIKEY_NAMESPACE });
+// "c4e1b0d2-..."
+```
+
+Properties:
+
+- **Deterministic** — same key + namespace always produces the same id; auth stays `getEntity({ id })`, still no GSI required
+- **One-way** — derives from the hash, so the plaintext key cannot be recovered
+- **Presentable** — a standard UUID, safe to expose externally
+
+Pick a stable namespace UUID per application (a random UUIDv4 is fine) so ids cannot collide across unrelated services.
+
 ## Typical Workflow
 
 1. **Generate** a key and return it to the user (only time plaintext is visible)
@@ -216,14 +239,33 @@ See `~secrets` for the full secrets management pattern.
 
 ## DynamoDB Storage Pattern
 
-Store hashed API keys in DynamoDB for direct lookup without a GSI:
+Store API keys in DynamoDB keyed on a deterministic id derived from the plaintext. Both patterns preserve direct `get-item` lookup (no GSI).
+
+### Preferred: UUIDv5 from hash (id safe to expose)
+
+```typescript
+const APIKEY_NAMESPACE = "b85e1a7a-5c7e-4e7b-9b8e-7c3a9d2f4e5b";
+
+// model = "apikey", id = uuidv5(hash, namespace) — standard UUID, safe to surface
+{ model: "apikey", id: jaypieApiKeyId(key, { namespace: APIKEY_NAMESPACE }), ownerId: "user_123", createdAt: "..." }
+```
+
+Use this when the id will appear in API responses, UI, or resource URLs. Auth stays a single `getEntity({ model: "apikey", id: jaypieApiKeyId(presented, { namespace }) })`.
+
+### Alternative: Raw hash id (hidden presentation)
 
 ```typescript
-// model = "apikey", id = hash — enables direct get-item lookup
+// model = "apikey", id = hash — a 64-char hex string, functional but not ergonomic
 { model: "apikey", id: hashJaypieKey(key), ownerId: "user_123", createdAt: "..." }
 ```
 
-This uses the `JaypieDynamoDb` default key convention (`model`/`id`). See `skill("dynamodb")` for table setup and query patterns.
+Use when presentation does not matter — internal-only tables, throwaway tooling, or when you are already storing a separate public identifier.
+
+Both patterns use the `JaypieDynamoDb` default key convention (`model`/`id`). See `skill("dynamodb")` for table setup and query patterns.
+
+### Why not `xid = hash` with a GSI?
+
+Another common pattern is `{ id: randomUUID(), xid: hashJaypieKey(key) }` with a GSI on `xid`. It works, but every auth lookup becomes a `query` against a GSI instead of a `get-item`, and you pay the per-deploy cost of an extra index. The UUIDv5 derivation sidesteps both by keeping the id deterministic.
 
 ## See Also
 

package/skills/cicd-actions.md

@@ -176,13 +176,13 @@ runs:
   using: 'composite'
   steps:
     - name: Setup Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v6
       with:
         node-version: ${{ inputs.node-version }}
         cache: 'npm'
 
     - name: Cache node_modules
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: |
           node_modules
@@ -194,7 +194,7 @@ runs:
 
     - name: Cache build outputs
       if: inputs.cache-builds == 'true'
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: |
           packages/*/dist
@@ -282,7 +282,7 @@ runs:
           ${{ inputs.extra-args }}
 
     - name: Upload CDK outputs
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: cdk-outputs
         path: ${{ inputs.working-directory }}/cdk-outputs.json
@@ -302,7 +302,7 @@ jobs:
       id-token: write
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: ./.github/actions/setup-environment
         with:

package/skills/cicd-deploy.md

@@ -30,7 +30,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: ./.github/actions/setup-node-and-cache
       - uses: ./.github/actions/npm-install-build
         with:
@@ -40,7 +40,7 @@ jobs:
   typecheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: ./.github/actions/setup-node-and-cache
       - uses: ./.github/actions/npm-install-build
         with:
@@ -53,7 +53,7 @@ jobs:
       matrix:
         node-version: [22, 24, 25]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: ./.github/actions/setup-node-and-cache
         with:
           node-version: ${{ matrix.node-version }}
@@ -68,7 +68,7 @@ jobs:
       id-token: write
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: ./.github/actions/setup-environment
         with:
@@ -112,7 +112,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: ./.github/actions/setup-node-and-cache
       - uses: ./.github/actions/npm-install-build
         with:
@@ -122,7 +122,7 @@ jobs:
   typecheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: ./.github/actions/setup-node-and-cache
       - uses: ./.github/actions/npm-install-build
         with:
@@ -135,7 +135,7 @@ jobs:
       matrix:
         node-version: [22, 24, 25]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: ./.github/actions/setup-node-and-cache
         with:
           node-version: ${{ matrix.node-version }}
@@ -150,7 +150,7 @@ jobs:
       id-token: write
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: ./.github/actions/setup-environment
         with:
@@ -200,7 +200,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 

package/skills/cicd.md

@@ -15,6 +15,21 @@ Jaypie projects use GitHub Actions for continuous integration and deployment.
 | `cicd-deploy` | CDK deployment workflows (sandbox, production) |
 | `cicd-environments` | GitHub Environments configuration |
 
+## Action Versions
+
+GitHub Actions deprecated Node 20 runners on 2025-09-19. Pin third-party actions to majors that natively run on Node 24 to avoid deprecation warnings and the `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` opt-in.
+
+| Action | Tag |
+|---|---|
+| `actions/checkout` | `v6` |
+| `actions/setup-node` | `v6` |
+| `actions/cache` | `v5` |
+| `actions/upload-artifact` | `v7` |
+| `actions/download-artifact` | `v8` |
+| `aws-actions/configure-aws-credentials` | `v6` |
+
+Refresh this list against the [Node 20 deprecation changelog](https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/) when bumping action versions.
+
 ## Standard Workflows
 
 ### npm-check.yml
@@ -34,8 +49,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: 24
       - run: npm ci
@@ -44,8 +59,8 @@ jobs:
   typecheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: 24
       - run: npm ci
@@ -57,8 +72,8 @@ jobs:
       matrix:
         node-version: [22, 24, 25]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm ci
@@ -87,8 +102,8 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: 24
           registry-url: 'https://registry.npmjs.org'