@kensio/skills 1.13.1 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/skills",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "Install Kensio agent skills into any agent that reads SKILL.md.",
   "keywords": [
     "agent-skills",

package/skills/dynamodb-single-table/SKILL.md

@@ -3,7 +3,7 @@ name: dynamodb-single-table
 description: Model data in Amazon DynamoDB as one table by default, reading the current AWS guidance before committing to a schema, writing the access patterns down before any keys exist, holding every entity type in one table, overloading generic partition and sort keys across those types, overloading and sparsifying secondary indexes, and splitting items by write rate. Use when designing or reviewing a DynamoDB schema, when a CDK stack is about to gain a second table, when an entity needs a query it has no key for, when application code fetches from two tables to assemble one response, when a Scan or a filter expression appears, when a partition runs hot or a write throttles, and when asked how to model users, orders, events or tenants in DynamoDB.
 license: Apache-2.0
 metadata:
-  version: "1.13.1"
+  version: "1.14.0"
 ---
 
 # Single-table design in DynamoDB

package/skills/github-issue-drafting/SKILL.md

@@ -3,7 +3,7 @@ name: github-issue-drafting
 description: Draft a GitHub issue from a short note or a rough idea, grounding every claim about the code in the repository the issue will be filed against, splitting work that is really two issues, and filing it with `gh` once the user has approved the draft. Use when turning a to-do item, a Slack message, a code TODO, a failing test or a bug report into an issue, when asked to "write up an issue for" something, to "raise", "file" or "open an issue", when asked whether something should be one issue or several, and when tidying the titles, types or labels of issues that already exist.
 license: Apache-2.0
 metadata:
-  version: "1.13.1"
+  version: "1.14.0"
 ---
 
 # GitHub issue drafting

package/skills/isolated-testing-style/SKILL.md

@@ -3,7 +3,7 @@ name: isolated-testing-style
 description: Write tests that start from given/when/then, use real collaborators through simulation rather than stubs and mocks, take their isolation from randomised data rather than shared setup and teardown, and assert behaviour rather than call counts. Use when writing or reviewing tests, when a test needs a collaborator faked, when reaching for a mock, spy, `toHaveBeenCalledWith`, `beforeEach`/`afterEach` fixtures or a hardcoded expected hash, when test setup has grown tangled, and when asked "how should I test this?".
 license: Apache-2.0
 metadata:
-  version: "1.13.1"
+  version: "1.14.0"
 ---
 
 # Isolated testing style

package/skills/pangram-check/SKILL.md

@@ -4,7 +4,7 @@ description: Send the prose of a finished document to Pangram, a commercial AI-t
 license: Apache-2.0
 compatibility: Needs a Pangram API key and network access. Every run is billed.
 metadata:
-  version: "1.13.1"
+  version: "1.14.0"
 disable-model-invocation: true
 ---
 

package/skills/part-factory-test-data/SKILL.md

@@ -3,7 +3,7 @@ name: part-factory-test-data
 description: Build test data with @kensio/part-factory, keeping in the factory everything a test does not care about, passing dependencies at call time so factories stay independent, and choosing between StaticFactory, DynamicFactory, VariantFactory, MappedFactory and AsyncMappedFactory. Use when writing test fixtures or builders, when a test file is full of object literals, when a shared event, message or payload shape is being hand-written, when a required field is about to be made optional to ease test setup, and when tempted to wrap a factory in a helper function that applies overrides.
 license: Apache-2.0
 metadata:
-  version: "1.13.1"
+  version: "1.14.0"
 ---
 
 # Building test data with Part Factory

package/skills/skill-template/SKILL.md

@@ -3,7 +3,7 @@ name: skill-template
 description: Scaffold a new agent skill, writing the SKILL.md and its frontmatter to the Agent Skills specification, then wrapping it as a plugin in this repo with package.json, plugin.json and a marketplace entry. Use when the user asks to "add a new skill", "create a skill", "write a SKILL.md" or "start a new plugin", and when checking whether an existing skill is portable between agents.
 license: Apache-2.0
 metadata:
-  version: "1.13.1"
+  version: "1.14.0"
 ---
 
 # Skill template

package/skills/technical-prose-style/SKILL.md

@@ -3,7 +3,7 @@ name: technical-prose-style
 description: Write documentation, READMEs, code comments, commit messages, release notes and PR text as plain technical prose, by removing the constructions that make unedited LLM prose tiring to read. It targets significance tails, contrastive definition, negation framing, appositive tails, colon explainers and a vocabulary that keeps renaming the same thing. Ships a script that scores prose against Django, Go, Rust and Python documentation. Use when writing or editing docs, a README, a changelog, a blog post or any prose for human readers, when asked to improve, tighten or rewrite writing, when prose "sounds like AI" or "sounds like Claude", and when reviewing documentation in a pull request.
 license: Apache-2.0
 metadata:
-  version: "1.13.1"
+  version: "1.14.0"
 ---
 
 # Technical prose style

package/skills/yulin-aws-simulation/SKILL.md

@@ -3,7 +3,7 @@ name: yulin-aws-simulation
 description: Use the @kensio/yulin in-process AWS simulator well when testing AWS code, using it directly rather than building a harness around it, driving tests, local dev and production from one synthesized CDK template, intercepting SDK clients with SimSdk, controlling simulated time, matching service errors by name, and handling properties Yulin refuses to simulate. Use when writing or reviewing tests that touch AWS, when replacing aws-sdk-client-mock or hand-rolled AWS stubs, when a CDK stack needs testing, when test setup around Yulin is growing helper classes or wrapper functions, and when Yulin refuses a template property or an SDK command.
 license: Apache-2.0
 metadata:
-  version: "1.13.1"
+  version: "1.14.0"
 ---
 
 # Testing with Yulin
@@ -12,9 +12,11 @@ metadata:
 network and no AWS account. Its own docs are the authority on the API. This skill covers how to use
 it well, and that lives mostly outside the API.
 
-Read the package docs for anything API-shaped. Start with
-[the README](https://github.com/KensioSoftware/yulin#readme), then `docs/sdk/` for interception and
-`docs/services/<name>/` for each simulated service.
+Read the package docs for anything API-shaped.
+[yulinsim.dev/llms.txt](https://yulinsim.dev/llms.txt) indexes every page as plain markdown, one
+link per guide and one per simulated service. Drop the `llms.txt` from a link for the HTML page. The
+same pages ship in the repository, as [the README](https://github.com/KensioSoftware/yulin#readme),
+then `docs/sdk/` for interception and `docs/services/<name>/` for each simulated service.
 
 This skill serves the `isolated-testing-style` skill, the general argument for simulation over
 stubs.
@@ -84,8 +86,7 @@ The two options that make a wrapper unnecessary:
 
 - **`transform`** is given the parsed template and answers with the one to deploy. It runs on the
   deployment and again on every re-read. A wrapper cannot do that. Use it for what a simulation
-  genuinely cannot resolve, such as an ARN carrying a real account, or a hosted zone ID that came
-  from `HostedZone.fromLookup`.
+  genuinely cannot resolve, such as an ARN carrying a real account.
 - **`watch`** re-applies the file when it changes, updating the stack in place. This is for dev
   servers. A `cdk synth` becomes a stack update without restarting the process, and resources the
   change left alone keep what they hold.
@@ -93,11 +94,23 @@ The two options that make a wrapper unnecessary:
 ```typescript
 await simAws.cloudFormation().deployTemplateFile({
   templatePath: "cdk.out/SiteStack.template.json",
-  transform: withoutLookedUpHostedZone,
+  transform: withRealAccountArnsResolved,
   watch: { onUpdated: () => srv.reload() },
 });
 ```
 
+A hosted zone ID that came from `HostedZone.fromLookup` needs no transform of its own. An
+`AWS::Route53::RecordSet` naming a hosted zone ID that no zone holds gets one registered under that
+ID as the record is created, and its records resolve. The zone takes its name from the records that
+name it. Register it yourself with `simAws.route53().registerHostedZone({ id, name })` where a test
+depends on the name, such as one listing zones by name.
+
+A failed `cdk synth` leaves the previous template in `cdk.out` where it was, and the tests carry on
+running against it. An edit that leaves an unused variable behind fails `tsc` and exits non-zero,
+with the error hidden behind a redirect. The test that runs next passes against the template from
+before the change. Check that the synthesized JSON changed before concluding anything from a
+construct change.
+
 ## Intercept real SDK clients, never hand-roll stubs
 
 `SimSdk` replaces the `send` method of an AWS SDK client class or instance, so real clients answer
@@ -270,6 +283,11 @@ control also needs `lambda:InvokeFunction`. The tests passed, the release went o
 Report a false pass with what production does and what the simulation did. Report a false refusal
 with the property and the template that carries it.
 
+A workaround kept while the issue is open wants a comment naming that issue, and a revisit when it
+closes. One test file carried a comment saying its handler could not reach simulated AWS from inside
+a simulated Lambda, citing KensioSoftware/yulin#638. That held when it was written and was fixed in
+1.16.0. The comment went on shaping the design of the test for months after that.
+
 ## Deploy expensive context once per test file
 
 Vitest gives each test file its own worker, so module-level state is already isolated between files.
@@ -322,3 +340,74 @@ The handler still runs in process. It can close over test state and be stepped t
 debugger. The difference from calling it directly is that a missing `s3:PutObject` on the execution
 role now fails the test, at the point AWS would have failed it. A binding can target a function by
 `logicalId`, `functionName`, `arn`, `cdkPath`, or `imageRepository` for a container image function.
+
+### Invoke through simulated Lambda
+
+Binding a handler proves nothing about IAM on its own. The execution role, the function's
+environment and its outbound HTTP are all applied by the invocation. The test has to go through
+`simAws.lambda().invoke(new InvokeCommand({ FunctionName, Payload }))` to get any of them. A test
+holding the same handler reference and calling it directly runs it in the test's own scope, as the
+test's own caller, with none of the three.
+
+The difference shows up under mutation. Removing `dynamodb:GetItem` from the role's policy in the
+CDK stack and re-synthesizing failed every invoked case:
+
+```
+AccessDenied: User: arn:aws:iam::111111111111:role/UserFunctionServiceRole1B2C3D4E
+is not authorized to perform: dynamodb:GetItem
+```
+
+The cases calling the handler directly passed. A suite that stays green through that mutation was
+never covering the policy.
+
+### Read the environment inside the handler
+
+A bound handler gets the function's declared environment variables with nothing stubbed.
+`SimProcessEnvironment` holds a run's variables in an `AsyncLocalStorage` store and resolves
+`process.env` to that store for the length of the run. Concurrent runs each see their own. Its own
+doc comment states the one limit:
+
+<!-- prose-check:off -->
+
+> The one thing this cannot reach is a read that already happened. A handler module doing
+> `const TABLE = process.env.TABLE_NAME` at module scope is evaluated when the test file imports it,
+> long before any run, so it captures the host value.
+
+<!-- prose-check:on -->
+
+So read the environment inside the handler body. Memoise there where a warm container should build
+its clients once. The substituted `Date` a bound handler reads works the same way, and a time
+captured at module scope is captured equally early.
+
+Yulin ships `SimLambdaEnvironmentConflicts` to warn about this, and it warns only where the host
+value and the declared value differ. A suite that stubs the right values stays quiet and never
+learns. The rule stays invisible for as long as the stubs agree.
+
+A `vi.stubEnv` around a bound handler is the sign that the handler reads too early. Moving the reads
+into the handler body removed every `vi.stubEnv` from one repository.
+
+### What a binding buys, and what the zip path buys
+
+Deploying without `bindings` runs the bundle `cdk synth` produced. `deployTemplateFile` publishes
+the cloud assembly's assets into the staging bucket in simulated S3, and the function's modules are
+evaluated as CommonJS in a vm sandbox. That sandbox hands the code its own `process.env`, its own
+`Date` and its own HTTP clients, and the module-scope problem above never arises there.
+
+Both paths authorise through the execution role. The same policy mutation fails a zip-path test
+exactly as it fails a bound one. The choice between them is about what else the test needs:
+
+- **A binding** keeps a breakpoint working and lets the handler close over test state.
+- **The zip path** exercises the artefact that deploys, its imports and its bundling included.
+
+### Outbound HTTP is answered by the simulation
+
+From 1.16.2, a simulated Lambda's `fetch` and its `node:http` and `node:https` are answered by the
+simulation for every hostname simulated Route 53 resolves. Those requests go through the same
+in-process entry point one arriving on localhost uses. A Cognito user pool domain, an HTTP API and a
+load balancer are all answered without the test knowing which of them it asked. Everything else
+reaches the network as it was addressed.
+
+This is what makes an OAuth authorization code exchange testable. That exchange lives only at the
+hosted `/oauth2/token` endpoint of the user pool domain and has no SDK operation behind it. A
+handler that cannot reach the domain leaves the whole exchange uncovered. The same routing lets
+`CognitoJwtVerifier` fetch a simulated pool's JWKS from inside a handler with no cache primed.