@jaypie/mcp 0.8.44 → 0.8.46

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.44#b696c1bf"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.46#f41e75e8"
     ;
 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.44",
+  "version": "0.8.46",
   "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.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/mcp/0.8.46.md

@@ -0,0 +1,11 @@
+---
+version: 0.8.46
+date: 2026-04-19
+summary: Add repokit skill documenting the @jaypie/repokit tooling bundle
+---
+
+## Changes
+
+- Added `skill("repokit")` covering what ships in `@jaypie/repokit` (`dotenv`, `env-cmd`, `rimraf`, `sort-package-json`, `tsx`), when to reach for it, and usage patterns — including the `env-cmd -f .env -- <cmd>` `--` separator gotcha
+- Registered `repokit` under the development category in `skill("skills")` and `skill("agents")`
+- Cross-linked from `skill("monorepo")` (added to related, recommended as root devDependency) and `skill("variables")` (added "Loading from `.env` Files" section)

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/agents.md

@@ -33,7 +33,7 @@ Complete stack styles, techniques, and traditions.
 `mcp__jaypie__skill(alias: String)`
 
 Contents: index, releasenotes
-Development: apikey, documentation, errors, llm, logs, mocks, monorepo, style, subpackages, tests, tools
+Development: apikey, documentation, errors, llm, logs, mocks, monorepo, repokit, style, subpackages, tests, tools
 Infrastructure: apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, websockets
 Patterns: api, fabric, handlers, models, services, vocabulary
 Recipes: recipe-api-server

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/monorepo.md

@@ -1,6 +1,6 @@
 ---
 description: Initialize a Jaypie monorepo project
-related: subpackage, cicd, style, tests
+related: subpackage, cicd, repokit, style, tests
 ---
 
 # Jaypie Monorepo Setup
@@ -130,9 +130,11 @@ npm-debug.log*
 Install root dev dependencies:
 
 ```bash
-npm install --save-dev @jaypie/eslint @jaypie/testkit eslint rimraf sort-package-json tsx vite vite-plugin-dts vitest
+npm install --save-dev @jaypie/eslint @jaypie/repokit @jaypie/testkit eslint vite vite-plugin-dts vitest
 ```
 
+`@jaypie/repokit` bundles `dotenv`, `env-cmd`, `rimraf`, `sort-package-json`, and `tsx` at consistent versions. See `skill("repokit")`.
+
 ## Workspace Conventions
 
 | Directory | Purpose |

package/skills/repokit.md

@@ -0,0 +1,97 @@
+---
+description: Bundled development tooling for Jaypie repositories (dotenv, env-cmd, rimraf, sort-package-json, tsx)
+related: monorepo, subpackages, variables
+---
+
+# Repokit
+
+`@jaypie/repokit` is a convenience bundle that consolidates common development tooling used across Jaypie repositories into a single devDependency. Install once and get `dotenv`, `env-cmd`, `rimraf`, `sort-package-json`, and `tsx` at consistent versions.
+
+## What Ships
+
+| Tool | Purpose |
+|------|---------|
+| `dotenv` | Load environment variables from `.env` files (re-exported for programmatic use) |
+| `env-cmd` | Run commands with env file loaded (CLI; use in npm scripts) |
+| `rimraf` | Cross-platform `rm -rf` (re-exported and available as CLI) |
+| `sort-package-json` | Enforce consistent `package.json` key ordering (CLI) |
+| `tsx` | Run TypeScript files directly without precompilation (CLI) |
+
+## When to Reach for It
+
+- **Monorepo root devDependency** — single install so every package has access to the same tooling versions
+- **Subpackages** — add as a devDependency where build/clean/script tooling is needed
+- **Avoid** listing each of the five underlying packages individually — let `@jaypie/repokit` pin them
+
+## Install
+
+```bash
+npm install --save-dev @jaypie/repokit
+# Or in a monorepo root:
+npm install --save-dev @jaypie/repokit -w .
+```
+
+## Programmatic Exports
+
+```typescript
+import { config, rimraf } from "@jaypie/repokit";
+
+config();                 // dotenv — loads process.env from .env
+await rimraf("./dist");   // cross-platform directory removal
+```
+
+Re-exports:
+
+- Everything from `dotenv` (`config`, `parse`, `populate`, etc.)
+- `rimraf` from `rimraf`
+
+## CLI Usage in `package.json` Scripts
+
+```json
+{
+  "scripts": {
+    "clean": "rimraf ./dist",
+    "clean:all": "rimraf ./packages/*/dist",
+    "format:package": "sort-package-json ./package.json ./packages/*/package.json",
+    "script:setup": "tsx scripts/setup.ts",
+    "start:dev": "env-cmd -f .env.development -- node server.js"
+  }
+}
+```
+
+### `env-cmd` — the `--` separator is required
+
+`env-cmd -f <file> -- <command>` passes the env file to the process and runs the command with those variables loaded. **Omit the `--` and env-cmd treats the file as an rc/JSON config instead of a dotenv file, which silently does the wrong thing.**
+
+```bash
+# Correct — `.env.dev` is read as a dotenv file
+env-cmd -f .env.dev -- node server.js
+
+# Wrong — `.env.dev` is parsed as JSON/rc config; server.js still runs but without env vars
+env-cmd -f .env.dev node server.js
+```
+
+Use this pattern to load repo-level `.env` files into scripts without hard-coding variables in `package.json`.
+
+### `tsx` — for TypeScript scripts
+
+```bash
+tsx scripts/seed.ts
+env-cmd -f .env.local -- tsx scripts/seed.ts   # combine with env-cmd
+```
+
+### `sort-package-json` — for consistency
+
+Add a `format:package` script and run it before committing, or enforce it in a pre-commit hook.
+
+## Why Not the Five Packages Directly?
+
+- **One devDependency vs five** — fewer entries in `package.json` and `package-lock.json`
+- **Pinned versions** — every Jaypie repo using repokit gets the same `dotenv`/`rimraf`/etc. version
+- **Easier upgrades** — bump repokit once, all tooling updates together
+
+## See Also
+
+- `skill("monorepo")` — repokit is a recommended devDependency for the monorepo root
+- `skill("subpackages")` — use repokit as a devDependency in any package that needs build/clean/script tooling
+- `skill("variables")` — pair `env-cmd` with `.env` files to load project environment variables

package/skills/skills.md

@@ -16,7 +16,7 @@ Look up skills by alias: `mcp__jaypie__skill(alias)`
 | Category | Skills |
 |----------|--------|
 | contents | index, releasenotes |
-| development | apikey, documentation, errors, llm, logs, mocks, monorepo, style, subpackages, tests, tools |
+| development | apikey, documentation, errors, llm, logs, mocks, monorepo, repokit, style, subpackages, tests, tools |
 | infrastructure | apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, websockets |
 | patterns | api, fabric, handlers, models, services, vocabulary |
 | recipes | recipe-api-server |

package/skills/variables.md

@@ -1,6 +1,6 @@
 ---
 description: Environment variables reference
-related: apikey, cdk, datadog, secrets
+related: apikey, cdk, datadog, repokit, secrets
 ---
 
 # Environment Variables
@@ -49,6 +49,21 @@ LOG_LEVEL=trace npm run dev
 LOG_LEVEL=debug npm run dev
 ```
 
+### Loading from `.env` Files
+
+Use `env-cmd` (bundled with `@jaypie/repokit`) to load a dotenv file into a script. The `--` separator is required — without it, `env-cmd` treats the file as rc/JSON config and silently does the wrong thing:
+
+```json
+{
+  "scripts": {
+    "start:dev": "env-cmd -f .env.development -- node server.js",
+    "script:seed": "env-cmd -f .env.local -- tsx scripts/seed.ts"
+  }
+}
+```
+
+See `skill("repokit")` for the full tooling bundle.
+
 ## CDK Infrastructure Variables
 
 | Variable | Description |