@jaypie/mcp 0.3.2 → 0.4.0

package/skills/variables.md

@@ -0,0 +1,146 @@
+---
+description: Environment variables reference
+related: secrets, cdk, datadog
+---
+
+# Environment Variables
+
+Configuration variables used in Jaypie applications.
+
+## Project Variables
+
+| Variable | Description | Values |
+|----------|-------------|--------|
+| `PROJECT_ENV` | Environment identifier | local, sandbox, kitchen, lab, studio, production |
+| `PROJECT_KEY` | Project name for logging | e.g., my-api |
+| `PROJECT_NONCE` | Unique resource suffix | e.g., dev, staging, prod |
+| `PROJECT_CHAOS` | Chaos engineering mode | none, partial, full |
+
+### Usage
+
+```typescript
+const env = process.env.PROJECT_ENV || "local";
+const key = process.env.PROJECT_KEY || "unknown";
+
+log.info("Starting", { env, project: key });
+```
+
+## Node Environment
+
+| Variable | Description | Values |
+|----------|-------------|--------|
+| `NODE_ENV` | Node.js environment | development, production, test |
+| `LOG_LEVEL` | Logging verbosity | trace, debug, info, warn, error |
+
+### Log Level in Development
+
+```bash
+# Very verbose
+LOG_LEVEL=trace npm run dev
+
+# Normal debugging
+LOG_LEVEL=debug npm run dev
+```
+
+## CDK Infrastructure Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CDK_ENV_BUCKET` | S3 bucket name |
+| `CDK_ENV_QUEUE_URL` | SQS queue URL |
+| `CDK_ENV_SNS_ROLE_ARN` | SNS role ARN |
+| `CDK_ENV_SNS_TOPIC_ARN` | SNS topic ARN |
+| `CDK_ENV_DATADOG_API_KEY_ARN` | Datadog API key ARN |
+| `CDK_ENV_TABLE` | DynamoDB table name |
+
+### Passing to Lambda
+
+```typescript
+const handler = new JaypieLambda(this, "Handler", {
+  environment: {
+    PROJECT_ENV: "production",
+    PROJECT_KEY: "my-api",
+    CDK_ENV_BUCKET: bucket.bucketName,
+    CDK_ENV_QUEUE_URL: queue.queueUrl,
+  },
+});
+```
+
+## Secret Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SECRET_MONGODB_URI` | MongoDB connection secret name |
+| `SECRET_API_KEY` | Third-party API key secret name |
+
+### Usage Pattern
+
+```typescript
+// Secret name from env, value from Secrets Manager
+const secretName = process.env.SECRET_MONGODB_URI;
+const mongoUri = await getSecret(secretName);
+```
+
+## AWS Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AWS_PROFILE` | Default AWS profile |
+| `AWS_REGION` | Default AWS region |
+| `AWS_DEFAULT_REGION` | Fallback region |
+| `AWS_SESSION_TOKEN` | Session token (Lambda runtime) |
+| `AWS_ACCESS_KEY_ID` | Access key (if not using profile) |
+| `AWS_SECRET_ACCESS_KEY` | Secret key (if not using profile) |
+
+## Datadog Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DATADOG_API_KEY` or `DD_API_KEY` | API key |
+| `DATADOG_APP_KEY` or `DD_APP_KEY` | Application key |
+| `DD_ENV` | Environment tag |
+| `DD_SERVICE` | Service name tag |
+| `DD_VERSION` | Version tag |
+| `DD_SOURCE` | Log source (default: lambda) |
+
+### Unified Service Tagging
+
+```typescript
+environment: {
+  DD_ENV: process.env.PROJECT_ENV,
+  DD_SERVICE: process.env.PROJECT_KEY,
+  DD_VERSION: process.env.npm_package_version,
+}
+```
+
+## Local Development
+
+### .env Files
+
+```bash
+# .env.local (not committed)
+PROJECT_ENV=local
+PROJECT_KEY=my-api
+LOG_LEVEL=debug
+MONGODB_URI=mongodb://localhost:27017/dev
+```
+
+### Loading .env
+
+```typescript
+import "dotenv/config";
+
+// Or in package.json
+"scripts": {
+  "dev": "dotenv -- node src/index.js"
+}
+```
+
+## Environment Detection
+
+```typescript
+const isProduction = process.env.PROJECT_ENV === "production";
+const isLocal = process.env.PROJECT_ENV === "local";
+const isDevelopment = !isProduction;
+```
+

package/skills/writing.md

@@ -0,0 +1,153 @@
+---
+description: Documentation and writing style
+---
+
+# Writing Style
+
+Guidelines for writing Jaypie documentation.
+
+## Principles
+
+1. **Concise** - Fewer words, more clarity
+2. **Scannable** - Use headings, lists, tables
+3. **Actionable** - Show, don't tell
+4. **Current** - Keep examples up to date
+
+## Formatting
+
+### Headings
+
+```markdown
+# Page Title (H1 - one per file)
+## Major Section (H2)
+### Subsection (H3)
+```
+
+### Code Blocks
+
+Always specify language:
+
+```typescript
+import { log } from "jaypie";
+log.info("Message", { context });
+```
+
+### Lists
+
+Use bullets for unordered items:
+- First item
+- Second item
+
+Use numbers for sequential steps:
+1. First step
+2. Second step
+
+### Tables
+
+Use for structured comparisons:
+
+| Option | Description |
+|--------|-------------|
+| `verbose` | Enable verbose logging |
+| `timeout` | Request timeout in ms |
+
+## Voice
+
+- **Active voice**: "Run the command" not "The command should be run"
+- **Present tense**: "Returns a string" not "Will return a string"
+- **Second person**: "You can configure" not "Users can configure"
+- **Imperative mood**: "Create a file" not "You should create a file"
+
+## Code Examples
+
+### Good Example
+
+```typescript
+// Clear purpose
+import { NotFoundError } from "jaypie";
+
+throw new NotFoundError("User not found");
+```
+
+### Bad Example
+
+```typescript
+// Avoid: no explanation, poor naming
+import { NotFoundError } from "jaypie";
+const e = new NotFoundError("err");
+throw e;
+```
+
+## Structure
+
+### Skill Files
+
+```markdown
+---
+description: Brief description for index listing
+related: alias1, alias2
+---
+
+# Skill Title
+
+One sentence overview.
+
+## Quick Start
+
+Minimal working example.
+
+## Details
+
+Deeper explanation with examples.
+
+## Reference
+
+Tables, options, API details.
+```
+
+### README Files
+
+```markdown
+# Package Name
+
+One-line description.
+
+## Installation
+
+\`\`\`bash
+npm install package-name
+\`\`\`
+
+## Usage
+
+\`\`\`typescript
+import { feature } from "package-name";
+feature();
+\`\`\`
+
+## API
+
+Document exports.
+
+## License
+
+MIT
+```
+
+## Anti-Patterns
+
+Avoid:
+- Long paragraphs (use lists)
+- Vague language ("various", "etc.")
+- Redundant words ("in order to" → "to")
+- Future promises ("will be added")
+- Passive voice ("is used by" → "uses")
+
+## Checklist
+
+Before publishing:
+- [ ] Code examples run without errors
+- [ ] All links work
+- [ ] No placeholder text
+- [ ] Spelling and grammar checked
+- [ ] Frontmatter complete

package/prompts/Branch_Management.md

@@ -1,34 +0,0 @@
----
-description: Process for creating, merging branches (always read)
----
-
-# Branch Management
-
-## Naming Conventions
-
-Name branches after the ticket or use a generic naming scheme.
-
-### Ticket Naming
-
-If the issue is from a ticketing system such as GitHub, Jira, or Linear, use `feat/{{ ticket }}`.
-Jira and Linear usually include a keyword like `DEV-12`.
-For GitHub tickets use `GITHUB-#`.
-
-### Generic Naming
-
-Check the first eight characters of the latest commit hash with `git -C workspace rev-parse --short=8 HEAD`
-Create a new branch prefixed with `feat/`.
-Make the branch name a concise two- or three-word summary of the ticket.
-Lead with the most important word.
-Use dashes, for example `feat/readme-update-abcd5678`.
-
-## Development
-
-Refer to [Development_Process.md](./Development_Process.md) for details on process, scripts, and tests expected in the development step.
-
-## Completion
-
-Push the completed branch.
-Start a new pull request.
-Describe the changes and any failing validation steps.
-Mark it closing the issue.

package/prompts/Development_Process.md

@@ -1,89 +0,0 @@
----
-description: Development workflow, required reading for coding tasks (always read)
----
-
-# Development Process
-
-## Baseline Conditions
-
-Check package.json scripts for available commands: build, format, lint, test, and typecheck.
-Run each available script to establish baseline state.
-Document all errors and warnings from the baseline run.
-Do not fix baseline errors or warnings.
-Use this baseline to identify new issues introduced by development work.
-
-## Development
-
-Implement the requested feature or fix.
-Write tests to validate the work whenever possible.
-Run tests to verify functionality (do not run lint or typecheck yet).
-When development is complete, commit changes using conventional commit format.
-Conventional commit format: `type: scope: description` (examples: `feat: api: add user endpoint`, `fix: auth: handle expired tokens`, `chore: config: update dependencies`).
-
-## Validation
-
-Check package.json for available scripts before running validation steps.
-Skip any step that does not have a corresponding npm script.
-If a npm script produces errors or warnings, note them for context in subsequent steps.
-Include any pre-existing build, lint, test, and type warnings in instructions to disregard when fixing new issues.
-Skip any step that cannot be passed due to pre-existing failures.
-Commit after each successful validation step to create restore points.
-
-### Scrub
-
-Follow code style rules in packages/mcp/prompts/Jaypie_Scrub.md.
-Repository-specific style guides (CLAUDE.md, .cursorrules) override Jaypie_Scrub.md when they conflict.
-Applying scrub rules can prevent errors in subsequent validation steps, especially testing.
-If no errors are found, no commit is needed for this step.
-
-### Test
-
-Run `npm run test` to execute the test suite.
-Compare results to baseline: only fix failures introduced by your changes.
-Determine root cause of each new failure:
-- Unchanged test failing: implementation likely broke existing functionality
-- Test covering intentionally modified behavior: test needs updating
-- New test failing: fix the test or implementation as appropriate
-Fix identified issues and re-run tests until only baseline failures remain.
-Commit fixes with message describing what was corrected.
-
-### Type Check
-
-Run `npm run typecheck` (runs typecheck across all workspace packages).
-Note: Some packages output `[TODO] Convert @jaypie/package to TypeScript` - this is expected and should be ignored.
-Compare results to baseline: only fix type errors introduced by your changes.
-Fix new type errors and re-run typecheck until only baseline errors remain.
-Commit fixes with message describing type corrections.
-
-### Format and Lint
-
-Run `npm run format` (runs package.json sorting and auto-fixes linting issues).
-Check git status to see if format updated any files.
-If files were modified by format, review changes and commit them.
-Run `npm run lint` to check for remaining lint errors.
-Fix any new lint errors introduced by your changes (compare to baseline).
-Commit lint fixes with appropriate message.
-
-### Build
-
-Run `npm run build` (uses Lerna to build all packages in dependency order).
-Compare results to baseline: only fix build errors introduced by your changes.
-Fix new build errors and re-run build until only baseline errors remain.
-Commit build fixes with appropriate message.
-Verify dist/ directories were created/updated for modified packages.
-
-## Documentation
-
-Check if README.md updates are needed:
-- Public API changes (function signatures, exports, parameters)
-- New features that users need to know about
-- Breaking changes to existing functionality
-- Changes to installation or setup procedures
-
-Do NOT update README.md for:
-- Internal refactoring
-- Test updates
-- Bug fixes that don't change behavior
-- Dependency updates
-
-If updates are needed, modify README.md to reflect changes and commit with message `docs: update README`.

package/prompts/Jaypie_Agent_Rules.md

@@ -1,110 +0,0 @@
----
-trigger: always_on
-description: Baseline rules in Jaypie repositories. Required reading.
----
-
-# Jaypie's Agent Rules
-
-This repository uses Jaypie, an opinionated event-driven fullstack library.
-
-## Errors
-
-Jaypie providers errors that will be handled properly when thrown (e.g., presenting the correct status code).
-
-`import { BadGatewayError, BadRequestError, ConfigurationError, ForbiddenError, GatewayTimeoutError, GoneError, IllogicalError, InternalError, MethodNotAllowedError, NotFoundError, NotImplementedError, RejectedError, TeapotError, UnauthorizedError, UnavailableError, UnhandledError, UnreachableCodeError } from "jaypie";`
-
-ConfigurationError is a special InternalError 500 that is also thrown when types are incorrect.
-
-Though supported, rely on default error messages when throwing.
-Custom error messages should be logged not thrown
-
-<Bad>
-throw new NotFoundError("Item not found");
-</Bad>
-<Good>
-log.error("Item not found");
-throw new NotFoundError();
-</Good>
-
-Error messages may be returned to the user especially in express.
-
-## Logging
-
-`import { log } from "jaypie";`
-`log` has methods `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `var`.
-Only `trace` and `var` should be used in "happy paths".
-`debug` should be used when execution deviates from the happy path.
-`info` should rarely be used.
-`var` expects a _single_ key-value pair like `log.var({ key: "value" });`.
-Do _not_ pass multiple keys to `var`.
-
-## Testing
-
-`@jaypie/testkit` is a testing library used with vitest providing custom matchers and mocks for the main Jaypie library.
-Always use the testkit to mock Jaypie.
-Always create a manual mock for a models package.
-Always mock network calls and external commands.
-Jaypie relies heavily on mocking to confirm expected behavior and prevent behavior drift.
-
-See [Jaypie_Mocks_and_Testkit.md](./Jaypie_Mocks_and_Testkit.md) for more context.
-
-### Configuration
-
-Mocks and matchers are usually configured at the subpackage-level in `testSetup.js` (legacy path) or `vitest.setup.[js|ts]` (modern path).
-The subpackage `[vite|vitest].config[js|ts]` will reference the setup file.
-All jaypie functions are mocked with `vi.mock("jaypie", async () => vi.importActual("@jaypie/testkit/mock"));`
-
-vitest.setup.ts
-```typescript
-import { matchers as jaypieMatchers } from "@jaypie/testkit";
-import * as extendedMatchers from "jest-extended";
-import { expect , vi} from "vitest";
-
-expect.extend(extendedMatchers);
-expect.extend(jaypieMatchers);
-
-vi.mock("jaypie", async () => vi.importActual("@jaypie/testkit/mock"));
-```
-
-### Errors
-
-Use matchers to test errors.
-`expect(fn).toThrowBadGatewayError();`
-`await expect(async() => fn()).toThrowBadGatewayError();`
-Do not use `.rejects`
-
-### Matchers
-
-toBeCalledAboveTrace, toBeCalledWithInitialParams, toBeClass, toBeJaypieError, toMatchBase64, toMatchJwt, toMatchMongoId, toMatchSchema, toMatchSignedCookie, toMatchUuid4, toMatchUuid5, toMatchUuid, toThrowBadGatewayError, toThrowBadRequestError, toThrowConfigurationError, toThrowForbiddenError, toThrowGatewayTimeoutError, toThrowInternalError, toThrowJaypieError, toThrowNotFoundError, toThrowUnauthorizedError, toThrowUnavailableError,
-
-### Order of Tests
-
-Tests are named `./__tests__/<subject>.spec.<js|ts>`.
-Each file should have one top-level `describe` block.
-Organize tests in one of seven second-level describe block sections in this order:
-
-1. Base Cases - it is the type we expect ("It is a Function"). For functions, the simplest possible call works and returns not undefined ("It Works"). For objects, the expected shape.
-2. Error Conditions - any error handling the code performs
-3. Security - any security checks the code performs
-4. Observability - any logging the code performs
-5. Happy Paths - The most common use case
-6. Features - Features in addition to the happy path
-7. Specific Scenarios - Special cases
-Omit describe blocks for sections that are not applicable or empty.
-Whenever possible, especially when refactoring, write the test first so the user can confirm the expected behavior passes/fails.
-
-### Test Coverage
-
-Aim for complete coverage of all happy paths, features, and error conditions.
-Whenever possible, confirm mocked functions are called.
-Confirm calls to log above debug in Observability. Do not confirm calls to debug, var, or trace.
-
-## Linting
-
-Use double quotes, trailing commas, and semicolons.
-Do not delete `// eslint-disable-next-line no-shadow` comments; add when shadowing variables, especially `error` in catch blocks.
-
-### Beyond Lint
-
-Whenever a hard-coded value like `site: "datadoghq.com"` is used, define a constant at the top of the file, `const DATADOG_SITE = "datadoghq.com"`, and reference that throughout.
-Alphabetize as much as possible.