@cubis/foundry 0.3.31 → 0.3.33

package/workflows/powers/nodejs-best-practices/SKILL.md

@@ -1,333 +1,49 @@
 ---
-name: nodejs-best-practices
-description: Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.
-allowed-tools: Read, Write, Edit, Glob, Grep
+name: "nodejs-best-practices"
+description: "Decision framework for modern Node.js backend architecture, operations, and security using current LTS-era practices."
+license: MIT
+metadata:
+  version: "2.0.0"
+  domain: "backend"
+  role: "decision-guide"
+  stack: "nodejs"
+  baseline: "Node 22/24 LTS era"
 ---
 
 # Node.js Best Practices
 
-> Principles and decision-making for Node.js development in 2025.
-> **Learn to THINK, not memorize code patterns.**
+## Purpose
 
----
-
-## ⚠️ How to Use This Skill
-
-This skill teaches **decision-making principles**, not fixed code to copy.
-
-- ASK user for preferences when unclear
-- Choose framework/pattern based on CONTEXT
-- Don't default to same solution every time
-
----
-
-## 1. Framework Selection (2025)
-
-### Decision Tree
-
-```
-What are you building?
-│
-├── Edge/Serverless (Cloudflare, Vercel)
-│   └── Hono (zero-dependency, ultra-fast cold starts)
-│
-├── High Performance API
-│   └── Fastify (2-3x faster than Express)
-│
-├── Enterprise/Team familiarity
-│   └── NestJS (structured, DI, decorators)
-│
-├── Legacy/Stable/Maximum ecosystem
-│   └── Express (mature, most middleware)
-│
-└── Full-stack with frontend
-    └── Next.js API Routes or tRPC
-```
-
-### Comparison Principles
-
-| Factor | Hono | Fastify | Express |
-|--------|------|---------|---------|
-| **Best for** | Edge, serverless | Performance | Legacy, learning |
-| **Cold start** | Fastest | Fast | Moderate |
-| **Ecosystem** | Growing | Good | Largest |
-| **TypeScript** | Native | Excellent | Good |
-| **Learning curve** | Low | Medium | Low |
-
-### Selection Questions to Ask:
-1. What's the deployment target?
-2. Is cold start time critical?
-3. Does team have existing experience?
-4. Is there legacy code to maintain?
-
----
-
-## 2. Runtime Considerations (2025)
-
-### Native TypeScript
-
-```
-Node.js 22+: --experimental-strip-types
-├── Run .ts files directly
-├── No build step needed for simple projects
-└── Consider for: scripts, simple APIs
-```
-
-### Module System Decision
-
-```
-ESM (import/export)
-├── Modern standard
-├── Better tree-shaking
-├── Async module loading
-└── Use for: new projects
-
-CommonJS (require)
-├── Legacy compatibility
-├── More npm packages support
-└── Use for: existing codebases, some edge cases
-```
+Use this skill to choose the right Node backend patterns for the actual constraints of the task, not by habit.
 
-### Runtime Selection
+## Decision flow
 
-| Runtime | Best For |
-|---------|----------|
-| **Node.js** | General purpose, largest ecosystem |
-| **Bun** | Performance, built-in bundler |
-| **Deno** | Security-first, built-in TypeScript |
-
----
-
-## 3. Architecture Principles
-
-### Layered Structure Concept
-
-```
-Request Flow:
-│
-├── Controller/Route Layer
-│   ├── Handles HTTP specifics
-│   ├── Input validation at boundary
-│   └── Calls service layer
-│
-├── Service Layer
-│   ├── Business logic
-│   ├── Framework-agnostic
-│   └── Calls repository layer
-│
-└── Repository Layer
-    ├── Data access only
-    ├── Database queries
-    └── ORM interactions
-```
-
-### Why This Matters:
-- **Testability**: Mock layers independently
-- **Flexibility**: Swap database without touching business logic
-- **Clarity**: Each layer has single responsibility
-
-### When to Simplify:
-- Small scripts → Single file OK
-- Prototypes → Less structure acceptable
-- Always ask: "Will this grow?"
-
----
-
-## 4. Error Handling Principles
-
-### Centralized Error Handling
-
-```
-Pattern:
-├── Create custom error classes
-├── Throw from any layer
-├── Catch at top level (middleware)
-└── Format consistent response
-```
-
-### Error Response Philosophy
-
-```
-Client gets:
-├── Appropriate HTTP status
-├── Error code for programmatic handling
-├── User-friendly message
-└── NO internal details (security!)
-
-Logs get:
-├── Full stack trace
-├── Request context
-├── User ID (if applicable)
-└── Timestamp
-```
-
-### Status Code Selection
-
-| Situation | Status | When |
-|-----------|--------|------|
-| Bad input | 400 | Client sent invalid data |
-| No auth | 401 | Missing or invalid credentials |
-| No permission | 403 | Valid auth, but not allowed |
-| Not found | 404 | Resource doesn't exist |
-| Conflict | 409 | Duplicate or state conflict |
-| Validation | 422 | Schema valid but business rules fail |
-| Server error | 500 | Our fault, log everything |
-
----
+1. Clarify deployment target (container, serverless, edge).
+2. Select framework/runtime shape based on latency and team constraints.
+3. Define API, validation, auth, and observability boundaries.
+4. Implement smallest safe slice, then harden.
 
-## 5. Async Patterns Principles
+## Core guidance
 
-### When to Use Each
+- Prefer typed boundaries (TypeScript + schema validation).
+- Keep transport concerns out of business logic.
+- Standardize error envelopes and correlation IDs.
+- Enforce timeout, retry, and circuit-breaker strategy for downstream calls.
+- Use graceful shutdown and health/readiness probes.
 
-| Pattern | Use When |
-|---------|----------|
-| `async/await` | Sequential async operations |
-| `Promise.all` | Parallel independent operations |
-| `Promise.allSettled` | Parallel where some can fail |
-| `Promise.race` | Timeout or first response wins |
+## Security and reliability
 
-### Event Loop Awareness
+- Validate all request input before business logic.
+- Use least-privilege credentials and secret rotation.
+- Avoid blocking the event loop in request paths.
+- Add rate limits and abuse controls on external endpoints.
 
-```
-I/O-bound (async helps):
-├── Database queries
-├── HTTP requests
-├── File system
-└── Network operations
+## Performance
 
-CPU-bound (async doesn't help):
-├── Crypto operations
-├── Image processing
-├── Complex calculations
-└── → Use worker threads or offload
-```
+- Measure before optimizing.
+- Profile CPU and heap in realistic workloads.
+- Use streaming/backpressure for large I/O paths.
 
-### Avoiding Event Loop Blocking
-
-- Never use sync methods in production (fs.readFileSync, etc.)
-- Offload CPU-intensive work
-- Use streaming for large data
-
----
-
-## 6. Validation Principles
-
-### Validate at Boundaries
-
-```
-Where to validate:
-├── API entry point (request body/params)
-├── Before database operations
-├── External data (API responses, file uploads)
-└── Environment variables (startup)
-```
-
-### Validation Library Selection
-
-| Library | Best For |
-|---------|----------|
-| **Zod** | TypeScript first, inference |
-| **Valibot** | Smaller bundle (tree-shakeable) |
-| **ArkType** | Performance critical |
-| **Yup** | Existing React Form usage |
-
-### Validation Philosophy
-
-- Fail fast: Validate early
-- Be specific: Clear error messages
-- Don't trust: Even "internal" data
-
----
-
-## 7. Security Principles
-
-### Security Checklist (Not Code)
-
-- [ ] **Input validation**: All inputs validated
-- [ ] **Parameterized queries**: No string concatenation for SQL
-- [ ] **Password hashing**: bcrypt or argon2
-- [ ] **JWT verification**: Always verify signature and expiry
-- [ ] **Rate limiting**: Protect from abuse
-- [ ] **Security headers**: Helmet.js or equivalent
-- [ ] **HTTPS**: Everywhere in production
-- [ ] **CORS**: Properly configured
-- [ ] **Secrets**: Environment variables only
-- [ ] **Dependencies**: Regularly audited
-
-### Security Mindset
-
-```
-Trust nothing:
-├── Query params → validate
-├── Request body → validate
-├── Headers → verify
-├── Cookies → validate
-├── File uploads → scan
-└── External APIs → validate response
-```
-
----
-
-## 8. Testing Principles
-
-### Test Strategy Selection
-
-| Type | Purpose | Tools |
-|------|---------|-------|
-| **Unit** | Business logic | node:test, Vitest |
-| **Integration** | API endpoints | Supertest |
-| **E2E** | Full flows | Playwright |
-
-### What to Test (Priorities)
-
-1. **Critical paths**: Auth, payments, core business
-2. **Edge cases**: Empty inputs, boundaries
-3. **Error handling**: What happens when things fail?
-4. **Not worth testing**: Framework code, trivial getters
-
-### Built-in Test Runner (Node.js 22+)
-
-```
-node --test src/**/*.test.ts
-├── No external dependency
-├── Good coverage reporting
-└── Watch mode available
-```
-
----
-
-## 10. Anti-Patterns to Avoid
-
-### ❌ DON'T:
-- Use Express for new edge projects (use Hono)
-- Use sync methods in production code
-- Put business logic in controllers
-- Skip input validation
-- Hardcode secrets
-- Trust external data without validation
-- Block event loop with CPU work
-
-### ✅ DO:
-- Choose framework based on context
-- Ask user for preferences when unclear
-- Use layered architecture for growing projects
-- Validate all inputs
-- Use environment variables for secrets
-- Profile before optimizing
-
----
-
-## 11. Decision Checklist
-
-Before implementing:
-
-- [ ] **Asked user about stack preference?**
-- [ ] **Chosen framework for THIS context?** (not just default)
-- [ ] **Considered deployment target?**
-- [ ] **Planned error handling strategy?**
-- [ ] **Identified validation points?**
-- [ ] **Considered security requirements?**
-
----
+## Output expectation
 
-> **Remember**: Node.js best practices are about decision-making, not memorizing patterns. Every project deserves fresh consideration based on its requirements.
+Return concrete architecture choices with tradeoffs, then implementation steps and verification criteria.

package/workflows/powers/postman/POWER.md

@@ -2,242 +2,20 @@
 ---
 inclusion: manual
 name: "postman"
-description: "Automate API testing and collection management with Postman - create workspaces, collections, environments, and run tests programmatically"
+description: "Compatibility wrapper skill. Canonical MCP skill moved to mcp/skills/postman."
+metadata:
+  deprecated: true
+  replaced_by: "postman"
+  moved_to: "mcp/skills/postman/SKILL.md"
+  removal_target: "v0.6.0"
 ---
 
+# postman (Compatibility Wrapper)
 
-# Onboarding
+This legacy workflow-path skill is kept for backward compatibility.
 
-Before proceeding, validate that the user has completed the following steps before using this power.
+Canonical MCP skill path:
+- mcp/skills/postman/SKILL.md
 
-## Step 1
-
-Generate and maintain `cbx_config.json` as the only Postman configuration source (workspace: `./cbx_config.json`, global: `~/.cbx/cbx_config.json`). Use named profiles in `postman.profiles` and choose `postman.activeProfileName`. Use env-first authentication by default: keep `apiKey` as `null`, set `apiKeyEnvVar` to `POSTMAN_API_KEY` (or another profile alias), and read the key from environment variables. Only store `apiKey` inline when the user explicitly requests file-based key storage. Keep workspace selection in the active profile `workspaceId` (`null` when unknown).
-
-## Step 2
-
-Create a hook that runs anytime the source code or configuration file has been changed. Save the hook in .kiro/hooks/hookname.kiro.hook. Example hook format. Please update the patterns to match the project's file structure.
-
-```json
-{
-  "enabled": true,
-  "name": "API Postman Testing",
-  "description": "Monitors API source code changes across multiple programming languages and automatically runs Postman collection tests to validate functionality",
-  "version": "1",
-  "when": {
-    "type": "fileEdited",
-    "patterns": [
-      "*.js",
-      "*.ts",
-      "*.py",
-      "*.java",
-      "*.cs",
-      "*.go", 
-      "*.rs",
-      "*.php",
-      "*.rb",
-      "*.kt",
-      "*.swift",
-      "*.scala",
-      "package.json",
-      "requirements.txt",
-      "Pipfile",
-      "pom.xml",
-      "build.gradle",
-      "*.csproj",
-      "go.mod",
-      "Cargo.toml",
-      "composer.json",
-      "Gemfile",
-      "build.sbt",
-      "openapi.yaml",
-      "openapi.yml",
-      "swagger.yaml",
-      "swagger.yml",
-      "api.yaml",
-      "api.yml"
-    ]
-  },
-  "then": {
-    "type": "askAgent",
-    "prompt": "API source code or configuration has been modified. Please retrieve the contents of the .postman.json file. If the file does not exist or is empty, create a Postman collection for the API. If it exists, get the collection ID and run the collection, showing me the results and propose fixes for any errors found."
-  }
-}
-```
-# Overview
-
-Automate API testing and collection management with Postman. Create workspaces, collections, environments, and run tests programmatically.
-
-**Authentication**: Env-first via `cbx_config.json` + profile env alias (default `POSTMAN_API_KEY`); inline `apiKey` is optional.
-
-## Available MCP Servers
-
-### postman
-**Package:** `@postman/postman-mcp-server`
-**Connection:** SSE-based MCP server
-**Authentication:** Postman API key via Bearer token
-**Mode:** Minimal (40 essential tools) - Default configuration
-**Endpoint:** https://mcp.postman.com/minimal
-
-**Note:** This power connects to Postman's hosted MCP server via SSE. To enable Full mode (112 tools) for advanced collaboration and enterprise features, change the URL to `https://mcp.postman.com/full`.
-
-**Available Tools (40 in Minimal Mode):**
-
-**Workspace Management:**
-- `createWorkspace` - Create a new workspace
-- `getWorkspace` - Get workspace details
-- `getWorkspaces` - List all accessible workspaces
-- `updateWorkspace` - Update workspace properties
-
-**Collection Management:**
-- `createCollection` - Create a new API collection
-- `getCollection` - Get detailed collection information
-- `getCollections` - List all collections in a workspace
-- `putCollection` - Replace/update entire collection
-- `duplicateCollection` - Create a copy of a collection
-- `createCollectionRequest` - Add a request to a collection
-- `createCollectionResponse` - Add a response example to a request
-
-**Environment Management:**
-- `createEnvironment` - Create a new environment
-- `getEnvironment` - Get environment details
-- `getEnvironments` - List all environments
-- `putEnvironment` - Replace/update entire environment
-
-**Mock Server Management:**
-- `createMock` - Create a mock server
-- `getMock` - Get mock server details
-- `getMocks` - List all mock servers
-- `updateMock` - Update mock server configuration
-- `publishMock` - Make mock server public
-
-**API Specification Management:**
-- `createSpec` - Create a new API specification
-- `getSpec` - Get specification details
-- `getAllSpecs` - List all specifications
-- `getSpecDefinition` - Get complete spec definition
-- `updateSpecProperties` - Update spec metadata
-- `createSpecFile` - Add a file to a spec
-- `getSpecFile` - Get a specific spec file
-- `getSpecFiles` - List all files in a spec
-- `updateSpecFile` - Update a spec file
-
-**Code Generation & Sync:**
-- `generateCollection` - Generate collection from API spec
-- `generateSpecFromCollection` - Generate spec from collection
-- `getGeneratedCollectionSpecs` - Get specs generated from a collection
-- `getSpecCollections` - Get collections generated from a spec
-- `syncCollectionWithSpec` - Sync collection with its spec
-- `syncSpecWithCollection` - Sync spec with its collection
-
-**Testing & Execution:**
-- `runCollection` - Execute a collection with automated tests
-
-**User & Metadata:**
-- `getAuthenticatedUser` - Get current user information
-- `getTaggedEntities` - Get entities by tag
-- `getStatusOfAnAsyncApiTask` - Check async task status
-- `getEnabledTools` - List available tools by mode
-
-## Tool Usage Examples
-
-```javascript
-// Create workspace
-mcp_postman_createWorkspace({
-  "workspace": { "name": "My API Project", "type": "personal" }
-})
-
-// Create collection
-mcp_postman_createCollection({
-  "workspace": "workspace-id",
-  "collection": {
-    "info": {
-      "name": "User API",
-      "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
-    }
-  }
-})
-
-// Create environment
-mcp_postman_createEnvironment({
-  "workspace": "workspace-id",
-  "environment": {
-    "name": "Local",
-    "values": [
-      { "key": "base_url", "value": "http://localhost:3000", "enabled": true }
-    ]
-  }
-})
-
-// Run collection
-mcp_postman_runCollection({
-  "collectionId": "collection-id",
-  "environmentId": "environment-id"
-})
-```
-
-## Workflows
-
-**Project Setup:**
-```javascript
-const { workspace } = await mcp_postman_createWorkspace({ "workspace": { "name": "Project", "type": "personal" }})
-const { collection } = await mcp_postman_createCollection({ "workspace": workspace.id, "collection": { "info": { "name": "API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }}})
-const { environment } = await mcp_postman_createEnvironment({ "workspace": workspace.id, "environment": { "name": "Local", "values": [{ "key": "base_url", "value": "http://localhost:3000", "enabled": true }]}})
-// Save IDs to .postman.json
-```
-
-**Generate from OpenAPI:**
-```javascript
-const { spec } = await mcp_postman_createSpec({ "workspaceId": "workspace-id", "name": "API Spec", "type": "OPENAPI:3.0", "files": [{ "path": "openapi.yaml", "content": "..." }]})
-const result = await mcp_postman_generateCollection({ "specId": spec.id, "elementType": "collection", "name": "Generated Collection" })
-```
-
-**Automated Testing:**
-```javascript
-const { workspaces } = await mcp_postman_getWorkspaces()
-const { collections } = await mcp_postman_getCollections({ "workspace": workspaces[0].id })
-const { environments } = await mcp_postman_getEnvironments({ "workspace": workspaces[0].id })
-for (const collection of collections) {
-  await mcp_postman_runCollection({ "collectionId": collection.uid, "environmentId": environments[0]?.id })
-}
-```
-
-## Best Practices
-
-- Store workspace/collection/environment IDs in `.postman.json`
-- Use environment variables for different contexts (local/staging/production)
-- Add post-request test scripts for validation
-- Organize requests in folders
-- Run collections before deployment
-- Ensure API server is running before tests
-
-## Troubleshooting
-
-**"Collection not found"**: Call `getCollections` to verify ID and permissions
-
-**"Environment not found"**: Call `getEnvironments` with correct workspace ID
-
-**Test failures**: Verify API server running, check environment variables (base_url, api_key), review test scripts
-
-**"Invalid API key"**: Generate new key at postman.com Settings → API Keys, verify permissions
-
-## Configuration
-
-**MCP Configuration (Minimal mode - 40 tools):**
-```json
-{
-  "mcpServers": {
-    "postman": {
-      "url": "https://mcp.postman.com/minimal",
-      "headers": {
-        "Authorization": "Bearer ${POSTMAN_API_KEY}"
-      }
-    }
-  }
-}
-```
-
-**Full mode (112 tools):** Change URL to `https://mcp.postman.com/full`
-
-**API Key Permissions:** Workspace management, collection read/write, environment read/write, collection runs
+Install MCP skills with: cbx workflows install --include-mcp
 ````