aws-lambda-devkit 0.1.0

package/docs/README.md

@@ -0,0 +1,23 @@
+# Lambda DevKit documentation
+
+Guides for **[Lambda DevKit](https://www.npmjs.com/package/aws-lambda-devkit)** — npm package **`aws-lambda-devkit`**, CLI **`lamkit`**.
+
+Complete walkthroughs for integrating the toolkit into your Node.js Lambda project. All examples use generic names (`worker`, `WORKER_QUEUE_URL`, etc.) — copy them and replace with your own paths and env vars.
+
+| Guide | Time | What you will learn |
+|-------|------|---------------------|
+| [Getting started](getting-started.md) | ~15 min | Install, project layout, first `lamkit test`, what the output means |
+| [Commands reference](commands.md) | Reference | Every CLI command and flag with copy-paste examples |
+| [Configuration reference](configuration.md) | Reference | Every `lamkit.config.*` field, env loading, asset links |
+| [Recipes](recipes.md) | Copy-paste | 22 end-to-end setups (SQS, HTTP, monorepo, real AWS, CI, …) |
+| [Troubleshooting](troubleshooting.md) | When stuck | Errors, causes, and step-by-step fixes |
+
+**Package name:** `aws-lambda-devkit`  
+**CLI command:** `lamkit`  
+**Config file:** `lamkit.config.js` (also `.mjs`, `.cjs`, or `.ts`)
+
+After `npm install -D aws-lambda-devkit`, open guides from:
+
+```
+node_modules/aws-lambda-devkit/docs/getting-started.md
+```

package/docs/commands.md

@@ -0,0 +1,294 @@
+# Commands reference
+
+Every **`lamkit`** command with examples. Installed via npm package **`aws-lambda-devkit`**.
+
+Run from the directory that contains `lamkit.config.*`, or pass `--cwd`.
+
+Install the CLI:
+
+```bash
+npm install -D aws-lambda-devkit
+npx lamkit --help
+```
+
+---
+
+## `lamkit init`
+
+Creates starter files in the current directory.
+
+```bash
+npx lamkit init
+npx lamkit init --force          # overwrite existing template files
+npx lamkit init --yes            # also add "test:lambda": "lamkit test" to package.json
+npx lamkit init --cwd ./packages/worker
+```
+
+**Creates:**
+
+| File | Purpose |
+|------|---------|
+| `lamkit.config.js` | Function definitions |
+| `.env.example` | Env var template |
+| `.vscode/launch.json` | VS Code debugger config |
+| `events/sample.json` | Example JSON payload |
+
+---
+
+## `lamkit list`
+
+Prints all configured functions.
+
+```bash
+npx lamkit list
+```
+
+**Example output:**
+
+```
+NAME    ENTRY                    TRIGGER
+-----------------------------------------
+worker  ./dist/handler.js        sqs
+api     ./dist/http.js           http
+```
+
+---
+
+## `lamkit config`
+
+Shows the **merged** config for one function (defaults + overrides). Useful to verify env vars resolved correctly.
+
+```bash
+npx lamkit config
+npx lamkit config worker
+```
+
+Queue URLs and secrets may be truncated or redacted in output.
+
+---
+
+## `lamkit test`
+
+Simulates an AWS event and invokes your handler locally. **No AWS credentials required** unless your handler calls AWS.
+
+### Basic usage
+
+```bash
+# Single function in config — name is optional
+npx lamkit test --data '{"orderId":"ord_123"}'
+
+# Named function
+npx lamkit test worker --data '{"orderId":"ord_123"}'
+
+# All functions in config
+npx lamkit test --all
+```
+
+### Payload sources (priority order)
+
+When you run `lamkit test`, lamkit picks the event payload like this:
+
+1. `--event path/to/file.json` — full raw event (highest priority)
+2. `--data` or `--data-file` — passed to the event builder
+3. `functions[].test.data` in config
+4. Empty / default sample for the trigger
+
+**Examples:**
+
+```bash
+# Inline JSON
+npx lamkit test --data '{"type":"ORDER_CREATED","id":"1"}'
+
+# JSON file
+npx lamkit test --data-file events/order-created.json
+
+# @file shorthand
+npx lamkit test --data @events/order-created.json
+
+# Raw captured SQSEvent (from CloudWatch or AWS samples)
+npx lamkit test --event events/captured-sqs.json
+```
+
+### SQS-specific flags
+
+```bash
+# Five records in one SQSEvent
+npx lamkit test --data '{"id":"1"}' --batch-size 5
+
+# Array payload → one record per element
+npx lamkit test --data '[{"id":"1"},{"id":"2"}]'
+```
+
+### Environment overrides
+
+```bash
+npx lamkit test --env LOG_LEVEL=debug --env FEATURE_X=true --data '{"id":"1"}'
+```
+
+Only affects that single invoke; does not change `.env`.
+
+### Debugging and inspection
+
+```bash
+# Print the built event without calling the handler
+npx lamkit test --dry-run --data '{"id":"1"}'
+
+# Node inspector (attach debugger)
+npx lamkit test --inspect
+npx lamkit test --inspect-brk
+
+# Reload handler module (bypass cache after code change)
+npx lamkit test --reload --data '{"id":"1"}'
+
+# Simulate cold start (Init Duration in REPORT)
+npx lamkit test --cold --data '{"id":"1"}'
+```
+
+### Exit codes
+
+```bash
+# Exit 1 if handler returns SQS batchItemFailures
+npx lamkit test worker --strict-batch --data '[{"id":"1"}]'
+```
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | Handler completed without throw (and strict-batch passed) |
+| `1` | Handler threw, timeout, or strict-batch failure |
+
+### Example successful output
+
+```
+✓ worker (sqs) — 42ms
+
+Logs:
+START RequestId: a1b2c3d4-... Version: $LATEST
+Received event: {"Records":[...]}
+END RequestId: a1b2c3d4-...
+REPORT RequestId: a1b2c3d4-...  Duration: 42.00 ms  Billed Duration: 100 ms  Memory Size: 512 MB  Max Memory Used: 89 MB
+```
+
+---
+
+## `lamkit send sqs`
+
+Sends one message to a **real** SQS queue. Requires `@aws-sdk/client-sqs` peer and AWS credentials.
+
+```bash
+npm install -D @aws-sdk/client-sqs
+
+npx lamkit send sqs worker --data '{"id":"1"}'
+npx lamkit send sqs worker --data-file events/payload.json
+npx lamkit send sqs worker --message 'plain text body'
+npx lamkit send sqs worker --data '{"id":"1"}' --queue-url 'https://sqs...'
+```
+
+FIFO queues (URL ends with `.fifo`): lamkit sets `MessageGroupId` and `MessageDeduplicationId` automatically.
+
+**Example output:**
+
+```
+Sent to https://sqs.us-east-1.amazonaws.com/123456789012/dev-worker
+MessageId: abc-123-def
+Run: lamkit listen worker
+```
+
+---
+
+## `lamkit send sns`
+
+Publishes to a **real** SNS topic. Requires `@aws-sdk/client-sns` peer.
+
+```bash
+npm install -D @aws-sdk/client-sns
+
+npx lamkit send sns notifier --data '{"event":"USER_SIGNUP"}'
+npx lamkit send sns notifier --topic-arn 'arn:aws:sns:us-east-1:123456789012:events'
+```
+
+This publishes only — it does not invoke your handler. To test the handler offline, use `lamkit test` with `trigger: 'sns'`.
+
+---
+
+## `lamkit listen`
+
+Long-polls a **real** SQS queue and invokes your **local** handler for each message.
+
+```bash
+npm install -D @aws-sdk/client-sqs
+
+# Poll until Ctrl+C
+npx lamkit listen worker
+
+# One poll batch, then exit
+npx lamkit listen worker --once
+
+# Fail if poll returns zero messages (useful in scripts)
+npx lamkit listen worker --once --expect-messages
+```
+
+### Common flags
+
+```bash
+npx lamkit listen worker --batch-size 5
+npx lamkit listen worker --no-batch-invoke    # one invoke per message
+npx lamkit listen worker --no-delete          # keep messages on queue (debug only)
+npx lamkit listen worker --reload             # reload handler each batch
+npx lamkit listen worker --queue-url 'https://sqs...'
+npx lamkit listen worker --no-extend-visibility
+```
+
+### Typical dev loop (two terminals)
+
+**Terminal 1:**
+
+```bash
+npx lamkit listen worker
+```
+
+**Terminal 2:**
+
+```bash
+npx lamkit send sqs worker --data '{"id":"1"}'
+```
+
+Use a **dev-only queue**. Pause the deployed Lambda event source mapping while listening, or both consumers will compete for messages.
+
+### Message lifecycle (AWS-aligned)
+
+| Handler result | Queue behavior |
+|----------------|----------------|
+| Success | Message deleted |
+| Throw or `batchItemFailures` | Message **not** deleted; becomes visible again after timeout |
+| `--no-delete` | Never delete (debug escape hatch) |
+
+---
+
+## Global options
+
+Most commands accept:
+
+```bash
+npx lamkit test worker --cwd /path/to/lambda-package --data '{"id":"1"}'
+```
+
+---
+
+## npm scripts (recommended)
+
+```json
+{
+  "scripts": {
+    "test:lambda": "lamkit test",
+    "test:lambda:all": "lamkit test --all",
+    "listen:worker": "lamkit listen worker",
+    "send:worker": "lamkit send sqs worker --data '{\"id\":\"1\"}'"
+  }
+}
+```
+
+```bash
+npm run test:lambda -- --data '{"id":"1"}'
+```
+
+Arguments after `--` are passed to `lamkit`.