@jaypie/mcp 0.1.0 → 0.1.1

package/prompts/Jaypie_Scrub.md

@@ -0,0 +1,177 @@
+---
+description: House style beyond linting to keep the repository clean and organized
+---
+
+# Jaypie Scrub File 🧽
+
+Repository style rules beyond linting
+
+## 🚒 Errors
+
+Jaypie offers a number of HTTP and special-use errors not limited to:
+`import { BadGatewayError, BadRequestError, ConfigurationError, ForbiddenError, InternalError, NotFoundError, TooManyRequestsError, UnauthorizedError } from "jaypie";`
+
+### Prefer to Throw Jaypie Errors
+
+* BadGatewayError when an external provider errors
+* InternalError for default 500 errors
+* ConfigurationError is a 500 variant when the problem is traceable to the coding or configuration of the system (incorrect type, incompatible options)
+
+<Bad>
+if (!item) {
+  log.error("Item not found");
+  return {
+    statusCode: 404,
+    body: JSON.stringify({ error: "Item not found" }),
+  };
+}
+</Bad>
+<Good>
+log.error("Item not found");
+throw new NotFoundError();
+</Good>
+
+### Throw Jaypie Errors to Return HTTP Errors in Express
+
+Inside a Jaypie `expressHandler`, thrown Jaypie errors will return the correct status to the client.
+Never try to alter `res` or return an error status code.
+
+### Avoid Custom Error Strings
+
+Though supported, rely on default error messages when throwing.
+Custom error messages should be logged.
+
+<Bad>
+throw new NotFoundError("Item not found");
+</Bad>
+<Good>
+log.error("Item not found");
+throw new NotFoundError();
+</Good>
+
+## 🧹 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.
+
+## 📢 Logging
+
+### Levels
+
+* Only use `log.trace` in the happy path
+* Use `log.debug` when straying from the happy path
+* Use `log.warn`, `log.error` as needed
+* Avoid the use of `info`
+
+### Logging Variables
+
+* Log variables with `log.var({ item })`
+* Only use single-key objects
+* The key can be changed for clarity
+* When logging large arrays, objects, and strings, consider logging abridged/truncated value or summary heuristics like length
+
+### Do Not Mix Strings and Objects
+
+<Bad>
+log.trace("Looking up item", { item: item.id });
+</Bad>
+<Good>
+log.trace(`Looking up item ${item.id}`);
+# OR
+log.trace(`Looking up item`);
+log.var({ item: item.id });
+</Good>
+
+### Separate Variables
+
+Do not combine into a single call:
+
+<Bad>
+log.debug({ userId: String(user.id), groupId: String(user.group) });
+</Bad>
+<Good>
+log.var({ userId: user.id });
+log.var({ groupId: user.group }); // Jaypie will coerce strings
+</Good>
+
+### Logging in Catch Statements
+
+* Log the highest level first
+* Use warn for errors that are part of normal operations like items not found, unauthorized users
+* Use error for things that should not happen like database connections failing
+* Follow up with lower-level debug and var logs as needed
+
+### Prefixing
+
+Using a prefix in square brackets helps identify functions and libraries.
+`log.trace("[newRoute] Starting route");`
+
+## 📛 Naming Things
+
+### Pluralization
+
+* Prefer singular
+* Objects should be singular
+* A model is singular. `Model.User`
+* Arrays should be plural
+
+## 🧪 Testing
+
+Aim for complete coverage of all happy paths, features, and error conditions.
+Whenever possible, confirm mocked functions are called.
+
+### Errors
+
+Jaypie Testkit includes custom matchers for errors: toBeJaypieError, toThrowBadGatewayError, toThrowBadRequestError, toThrowConfigurationError, toThrowForbiddenError, toThrowGatewayTimeoutError, toThrowInternalError, toThrowJaypieError, toThrowNotFoundError, toThrowUnauthorizedError, toThrowUnavailableError,
+`expect(fn).toThrowBadGatewayError();`
+`await expect(async() => fn()).toThrowBadGatewayError();`
+Do not use `.rejects`
+
+### Function Calls
+
+* Always test a function was called before testing specific values
+```
+expect(fn).toBeCalled();
+expect(fn).toBeCalledWith(12);
+```
+Avoid overly specific tests on mock values and strings, especially log string.
+Test key values that need to be passed through the application.
+Use asymmetric matchers for mock values and strings.
+
+### Mocks
+
+* Assume `jaypie` is mocked by `@jaypie/testkit/mock`
+* Both of these should be mocked in the subpackage's `testSetup.js` or `vitest.setup.ts`
+
+### No Test Code in Implementations
+
+Do not check for test conditions, environment variables, or mocks outside the test logic.
+Production code should never have special handling for test cases.
+All code should be structured to be fully mockable.
+Appropriate use of mocks should allow special handling to be dictated in the test file.
+
+### Observability
+
+* The primary happy path should check `log.not.toBeCalledAboveTrace()`
+* Check `expect(log.warn).toBeCalled();` for `warn` and `error` on error cases
+* Do not confirm calls to debug, var, or trace.
+
+### Organization
+
+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.
+
+## 🍱 Miscellaneous
+
+Alphabetize as much as possible.
+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.

package/prompts/Write_Efficient_Prompt_Guides.md

@@ -0,0 +1,48 @@
+---
+description: Maintaining code-generation agent guides
+---
+
+# Write Efficient Prompt Guides
+
+An efficient prompt conveys maximum information in minimal words.
+
+## Process
+
+If provided with an existing guide, update the guide.
+Apply these standards dogmatically.
+If provided content, create a new guide.
+
+## Goals
+
+* Apply a crisp, declarative writing style
+* Consider how each phrase can be written for maximum clarity
+* Remove superfluous language
+* Remove tasks only a human can perform
+* Prefer semantic meaning (like headings) and clarity over aesthetic concerns (like font size)
+
+## Suggested Outline for a New Guide
+
+```markdown
+# Guide title
+
+One-line overview of the guide's value
+
+## Goal
+
+Aim or "outputs" of the guide
+
+## Guidelines
+
+Assumptions and prerequisites factoring in the implementation
+
+## Process
+
+Setup and steps to reproduce
+```
+
+## 🏠 Studio House Style
+
+Focus on clarity using terse and pithy language.
+Place each sentence on its own line to enhance version control diffs.
+Avoid the second-person pronoun; instructions may imply the reader without using “you.”
+Reference abstract third persons when a party must be mentioned.

package/prompts/Write_and_Maintain_Engaging_Readme.md

@@ -0,0 +1,67 @@
+---
+description: Maintaining human-centric documentation
+globs: README.md
+---
+
+# Write and Maintain an Engaging README.md
+
+Engaging READMEs invite all audiences to explore the contents.
+They present documentation in an accessible and organized manner.
+
+## 🔧 Maintenance Checklist (Outputs)
+
+Ensure all spelling and grammar have been checked.
+Confirm that all external links operate without redirection.
+Verify that external links land on meaningful pages.
+Check markdown syntax.
+
+## 📥 Task Prerequisites (Inputs)
+
+Most repositories contain an existing README.
+If only a README is provided, review and maintain it without considering drift from the code.
+If code is included, review the provided code and update the README accordingly.
+If no README is present, verify that a README.md file exists before creating a new one.
+
+## ✍️ Editorial Guidelines
+
+Adhere to the existing heading hierarchy.
+Refrain from modifying established sections.
+Maintain the style, tone, and technical formatting already in use.
+Avoid adding emojis if the current document does not use them.
+
+## 📋 Suggested Outline
+
+Structure the document so that the content flows from the most common audience's high-level needs to a complete reference.
+Avoid creating empty sections.
+
+```markdown
+# Document Title
+Description // a tagline or tl;dr that extends beyond the title
+## ✈️ Overview – an introduction for documents of extensive length
+## 💿 Installation - or ## 💿 Setup
+## 📋 Usage – a quick overview of the most common uses
+## 📖 Reference – a detailed guide to all uses, ideally arranged alphabetically
+## 💻 Development – instructions for setting up a local environment
+## 🚀 Deployment – guidelines for deploying to staging and production environments
+## 🛣️ Roadmap
+## 📝 Changelog
+## 📎 Appendix - or ## 🖇️ Footnotes as needed
+## 📜 License – typically defaulting to “All rights reserved.” unless specified otherwise
+```
+
+## 🧑‍💻 Technical Audience
+
+Assume that the audience is technical and capable of following explicit instructions.
+Include code examples as necessary.
+Declare required import statements at the beginning of example blocks.
+
+## 🏠 Studio House Style
+
+Adhere to the Chicago Manual of Style.
+Focus on clarity using terse and pithy language.
+Apply whitespace around headings to reduce visual clutter.
+Place each sentence on its own line to enhance version control diffs.
+Apply business formal language with dry whimsy when appropriate.
+Emojis may introduce second-level headings and conclude first- or third-level headings as appropriate.
+Avoid the second-person pronoun; instructions may imply the reader without using “you.”
+Reference abstract third persons when a party must be mentioned.

package/prompts/templates/cdk-subpackage/bin/cdk.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import cdk from "aws-cdk-lib";
+import { AppStack } from "../lib/cdk-app.ts";
+import { InfrastructureStack } from "../lib/cdk-infrastructure.ts";
+
+const app = new cdk.App();
+
+new InfrastructureStack(app, "InfrastructureStack");
+
+new AppStack(app, "AppStack");

package/prompts/templates/cdk-subpackage/cdk.json

@@ -0,0 +1,19 @@
+{
+  "app": "npx ts-node --prefer-ts-exts bin/cdk.ts",
+  "watch": {
+    "include": [
+      "**"
+    ],
+    "exclude": [
+      "README.md",
+      "cdk*.json",
+      "**/*.d.ts",
+      "**/*.js",
+      "tsconfig.json",
+      "package*.json",
+      "yarn.lock",
+      "node_modules",
+      "test"
+    ]
+  }
+}

package/prompts/templates/cdk-subpackage/lib/cdk-app.ts

@@ -0,0 +1,41 @@
+import {
+  JaypieAppStack,
+  JaypieApiGateway,
+  JaypieExpressLambda,
+  JaypieMongoDbSecret,
+  JaypieLambda,
+} from "@jaypie/constructs";
+
+import * as cdk from "aws-cdk-lib";
+import { Construct } from "constructs";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+
+export class AppStack extends JaypieAppStack {
+  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    const mongoConnectionString = new JaypieMongoDbSecret(this);
+
+    const expressLambda = new JaypieExpressLambda(this, "expressLambda", {
+      code: lambda.Code.fromAsset("../express"),
+      handler: "dist/index.expressLambda",
+      secrets: [mongoConnectionString],
+    });
+
+    new JaypieApiGateway(this, "apiGateway", {
+      handler: expressLambda,
+      host: "api.example.com",
+      zone: "example.com",
+    });
+
+    new JaypieLambda(
+      this,
+      "lambdaWorker",
+      {
+        code: lambda.Code.fromAsset("../lambda"),
+        handler: "dist/index.lambdaWorker",
+        secrets: [mongoConnectionString],
+      },
+    );
+  }
+}

package/prompts/templates/cdk-subpackage/lib/cdk-infrastructure.ts

@@ -0,0 +1,15 @@
+import {
+  JaypieInfrastructureStack,
+  JaypieWebDeploymentBucket,
+} from "@jaypie/constructs";
+
+export class InfrastructureStack extends JaypieInfrastructureStack {
+  constructor(scope, id, props = {}) {
+    super(scope, id, props);
+
+    new JaypieWebDeploymentBucket(this, "DeploymentBucket", {
+      // * host is not needed if CDK_ENV_WEB_SUBDOMAIN and CDK_ENV_WEB_HOSTED_ZONE or CDK_ENV_HOSTED_ZONE 
+      // * zone is not needed if CDK_ENV_WEB_HOSTED_ZONE or CDK_ENV_HOSTED_ZONE
+    });
+  }
+}

package/prompts/templates/express-subpackage/index.ts

@@ -0,0 +1,8 @@
+import serverlessExpress from "@codegenie/serverless-express";
+import app from "./src/app.js";
+
+export default serverlessExpress({ app });
+
+if (process.env.NODE_ENV === "development") {
+  app.listen(8080);
+}

package/prompts/templates/express-subpackage/src/app.ts

@@ -0,0 +1,18 @@
+import { cors, echoRoute, EXPRESS, noContentRoute, notFoundRoute } from "jaypie";
+import express from "express";
+import resourceRouter from "./routes/resource.router.js";
+
+const app = express();
+
+// Built-in Jaypie routes
+app.get(EXPRESS.PATH.ROOT, noContentRoute);
+app.use("/_sy/echo", cors(), echoRoute);
+
+// Application routes
+app.use(/^\/resource$/, cors(), resourceRouter);
+app.use("/resource/", cors(), resourceRouter);
+
+// Catch-all
+app.all(EXPRESS.PATH.ANY, notFoundRoute);
+
+export default app;

package/prompts/templates/express-subpackage/src/handler.config.ts

@@ -0,0 +1,44 @@
+import { force } from "jaypie";
+
+interface HandlerConfigOptions {
+  locals?: Record<string, any>;
+  setup?: Array<() => void | Promise<void>>;
+  teardown?: Array<() => void | Promise<void>>;
+  validate?: Array<() => boolean | Promise<boolean>>;
+}
+
+interface HandlerConfig {
+  name: string;
+  locals: Record<string, any>;
+  setup: Array<() => void | Promise<void>>;
+  teardown: Array<() => void | Promise<void>>;
+  validate: Array<() => boolean | Promise<boolean>>;
+}
+
+const handlerConfig = (
+  nameOrConfig: string | (HandlerConfig & { name: string }),
+  options: HandlerConfigOptions = {}
+): HandlerConfig => {
+  let name: string;
+  let locals: Record<string, any>;
+  let setup: Array<() => void | Promise<void>>;
+  let teardown: Array<() => void | Promise<void>>;
+  let validate: Array<() => boolean | Promise<boolean>>;
+
+  if (typeof nameOrConfig === "object") {
+    ({ name, locals = {}, setup = [], teardown = [], validate = [] } = nameOrConfig);
+  } else {
+    name = nameOrConfig;
+    ({ locals = {}, setup = [], teardown = [], validate = [] } = options);
+  }
+
+  return {
+    name,
+    locals: { ...force.object(locals) },
+    setup: [...force.array(setup)],
+    teardown: [...force.array(teardown)],
+    validate: [...force.array(validate)],
+  };
+};
+
+export default handlerConfig;

package/prompts/templates/express-subpackage/src/routes/resource/__tests__/resourceGet.route.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import resourceGet from "../resourceGet.route.js";
+
+describe("Resource Get Route", () => {
+  it("returns resource data", async () => {
+    const mockRequest = {
+      query: { search: "test" },
+      locals: {},
+    } as any;
+
+    const response = await resourceGet(mockRequest);
+    
+    expect(response.message).toBe("Resource endpoint");
+    expect(response.query).toEqual({ search: "test" });
+    expect(response.timestamp).toBeDefined();
+  });
+
+  it("handles empty query", async () => {
+    const mockRequest = {
+      query: {},
+      locals: {},
+    } as any;
+
+    const response = await resourceGet(mockRequest);
+    
+    expect(response.message).toBe("Resource endpoint");
+    expect(response.query).toEqual({});
+  });
+});

package/prompts/templates/express-subpackage/src/routes/resource/resourceGet.route.ts

@@ -0,0 +1,22 @@
+import { expressHandler } from "jaypie";
+import type { Request } from "express";
+import handlerConfig from "../../handler.config.js";
+
+interface ResourceGetResponse {
+  message: string;
+  query: Record<string, any>;
+  timestamp: string;
+}
+
+export default expressHandler(
+  handlerConfig("resourceGet"),
+  async (req: Request): Promise<ResourceGetResponse> => {
+    const { query } = req;
+    
+    return {
+      message: "Resource endpoint",
+      query,
+      timestamp: new Date().toISOString(),
+    };
+  }
+);

package/prompts/templates/express-subpackage/src/routes/resource.router.ts

@@ -0,0 +1,11 @@
+import express from "express";
+import { EXPRESS } from "jaypie";
+import resourceGetRoute from "./resource/resourceGet.route.js";
+
+const router = express.Router();
+router.use(express.json({ strict: false }));
+
+// Single example route
+router.get(EXPRESS.PATH.ROOT, resourceGetRoute);
+
+export default router;

package/prompts/templates/express-subpackage/src/types/express.ts

@@ -0,0 +1,9 @@
+declare global {
+  namespace Express {
+    interface Request {
+      locals?: Record<string, any>;
+    }
+  }
+}
+
+export {};

package/prompts/templates/project-monorepo/.vscode/settings.json

@@ -0,0 +1,72 @@
+{
+  "cSpell.words": [
+    "addgroup",
+    "adduser",
+    "arcxp",
+    "autofix",
+    "buildvcs",
+    "CDKTAG",
+    "certificatemanager",
+    "cicd",
+    "civisibility",
+    "clonedeep",
+    "codegenie",
+    "cogenticat",
+    "composables",
+    "coreutils",
+    "datadoghq",
+    "ddsource",
+    "ddtags",
+    "dnsutils",
+    "dushi",
+    "e2bdev",
+    "ejectability",
+    "elif",
+    "envsubst",
+    "esmodules",
+    "Ferdinandi",
+    "Finlayson",
+    "finlaysonstudio",
+    "finstu",
+    "finstuapps",
+    "fontface",
+    "hola",
+    "hygen",
+    "iconsets",
+    "importx",
+    "initzero",
+    "invokeid",
+    "isequal",
+    "jaypie",
+    "jsonapi",
+    "knowdev",
+    "knowtrace",
+    "modelcontextprotocol",
+    "nobuild",
+    "npmjs",
+    "nuxt",
+    "oidc",
+    "openmeteo",
+    "pinia",
+    "pipefail",
+    "procps",
+    "repomix",
+    "retryable",
+    "rimfaf",
+    "roboto",
+    "rollup",
+    "sorpresa",
+    "ssoins",
+    "stddev",
+    "subpackages",
+    "supertest",
+    "testkit",
+    "unplugin",
+    "vendia",
+    "vite",
+    "vitest",
+    "vuekit",
+    "vuetify",
+    "wght"
+  ]
+}

package/prompts/templates/project-monorepo/eslint.config.mjs

@@ -0,0 +1 @@
+export { default as default } from "@jaypie/eslint";

package/prompts/templates/project-monorepo/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@project-org/project-name",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "clean": "npm run clean --workspaces && npm run clean:root",
+    "clean:root": "rimraf node_modules package-lock.json",
+    "format": "eslint --fix",
+    "format:package": "sort-package-json ./package.json ./packages/*/package.json",
+    "lint": "eslint",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "typecheck": "npm run typecheck --workspaces"
+  }
+}

package/prompts/templates/project-monorepo/tsconfig.base.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "sourceMap": true,
+    "composite": true,
+    "paths": {
+      "@pkg-a/*": ["packages/pkg-a/src/*"],
+      "@pkg-b/*": ["packages/pkg-b/src/*"]
+    }
+  }
+}

package/prompts/templates/project-monorepo/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "references": [
+    { "path": "packages/pkg-a" },
+    { "path": "packages/pkg-b" }
+  ]
+}

package/prompts/templates/project-monorepo/vitest.workspace.js

@@ -0,0 +1,3 @@
+import { defineWorkspace } from "vitest/config";
+
+export default defineWorkspace(["packages/*"]);

package/prompts/templates/project-subpackage/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@project-org/project-name",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "vite build",
+    "clean": "rimfaf dist",
+    "format": "eslint --fix",
+    "format:package": "sort-package-json",
+    "lint": "eslint",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "typecheck": "tsc --noEmit"
+  }
+}