@drkmttr/adhere 0.9.4 → 0.10.0

package/presets/alchemy/data/never-disable-tls-verification.md

@@ -2,13 +2,17 @@
 description: A database client or migration config must verify the server's TLS certificate, or connect inside the private network, never setting rejectUnauthorized: false or sslmode=no-verify to make a connection work.
 ---
 
-```ts must
+## Must
+
+```ts
 const url = new URL(connection.connectionString);
 url.searchParams.set("sslmode", "verify-full");
 const db = yield* Drizzle.Postgres(url.toString());
 ```
 
-```ts never
+## Never
+
+```ts
 export default defineConfig({
   dialect: "postgresql",
   dbCredentials: { url: process.env.DATABASE_URL!, ssl: { rejectUnauthorized: false } },

package/presets/alchemy/data/parameterized-sql.md

@@ -2,12 +2,16 @@
 description: SQL must pass values as parameters, through tagged-template interpolation, sql.in, sql.insert, or prepare().bind(), never by string concatenation or a template string handed to an unsafe or raw API.
 ---
 
-```ts must
+## Must
+
+```ts
 const user = yield* sql`SELECT * FROM users WHERE email = ${email}`;
 const row = yield* Effect.promise(() => d1.prepare("SELECT * FROM users WHERE id = ?").bind(id).first());
 ```
 
-```ts never
+## Never
+
+```ts
 const user = yield* sql.unsafe(`SELECT * FROM users WHERE email = '${email}'`);
 const row = yield* Effect.promise(() => d1.prepare("SELECT * FROM users WHERE id = " + id).first());
 ```

package/presets/alchemy/data/private-endpoint-at-runtime.md

@@ -2,11 +2,15 @@
 description: Service code should reach its database through the bound private connection, and should not use the public connection URI or TCP proxy, which is meant for laptops and CI.
 ---
 
-```ts should
+## Should
+
+```ts
 const conn = yield* Railway.ConnectPostgres(Db);
 const db = yield* Drizzle.Postgres(conn.connectionString);
 ```
 
-```ts should not
+## Should not
+
+```ts
 const db = yield* Drizzle.Postgres(Db.publicConnectionUri);
 ```

package/presets/alchemy/data/single-migration-owner.md

@@ -2,12 +2,16 @@
 description: Each database must have one migration owner: when a resource's migrations prop applies the directory, scripts and CI must never also run drizzle-kit migrate or prisma migrate against the same database.
 ---
 
-```ts must
+## Must
+
+```ts
 const branch = yield* Neon.Branch("Main", { project, migrations: "./migrations" });
 // package.json: "deploy": "alchemy deploy"
 ```
 
-```ts never
+## Never
+
+```ts
 const branch = yield* Neon.Branch("Main", { project, migrations: "./migrations" });
 // package.json: "deploy": "drizzle-kit migrate && alchemy deploy"
 ```

package/presets/alchemy/durable/idempotent-event-handlers.md

@@ -2,13 +2,17 @@
 description: A handler for events delivered at least once, such as Stripe webhooks, scheduled callbacks, or bucket and queue events, must be idempotent, upserting by a stable ID or deduplicating by event ID, never doing blind inserts, increments, or charges.
 ---
 
-```ts must
+## Must
+
+```ts
 yield* Stripe.consumeEvents([CustomerSubscriptionUpdated], (event) =>
   kv.put(`entitlement:${event.data.object.customer}`, JSON.stringify(entitlementOf(event))),
 );
 ```
 
-```ts never
+## Never
+
+```ts
 yield* Stripe.consumeEvents([InvoicePaid], (event) =>
   sql`UPDATE accounts SET credits = credits + 100 WHERE customer = ${event.data.object.customer}`,
 );

package/presets/alchemy/durable/io-inside-steps.md

@@ -2,7 +2,9 @@
 description: In a Workflow or Durable Function, every side effect, such as an HTTP call, binding call, or write, must run inside a task or step, and code outside steps must be deterministic, never doing I/O or reading the clock or randomness, because the body replays.
 ---
 
-```ts must
+## Must
+
+```ts
 export default Cloudflare.Workflow("Notify", Effect.fn(function* (input: { roomId: string; message: string }) {
   const stored = yield* Cloudflare.Workflows.task("store", kv.put(`notify:${input.roomId}`, input.message));
   yield* Cloudflare.Workflows.sleep("cooldown", "30 seconds");
@@ -10,7 +12,9 @@ export default Cloudflare.Workflow("Notify", Effect.fn(function* (input: { roomI
 }));
 ```
 
-```ts never
+## Never
+
+```ts
 export default Cloudflare.Workflow("Notify", Effect.fn(function* (input: { roomId: string; message: string }) {
   yield* kv.put(`notify:${input.roomId}:${Date.now()}`, input.message); // repeats on every replay
 }));

package/presets/alchemy/durable/no-self-triggering-bucket-writes.md

@@ -2,13 +2,17 @@
 description: A bucket-event handler that writes back into the bucket it listens to should filter its subscription by prefix or suffix so its own writes do not match, and should not subscribe to every object created in that bucket.
 ---
 
-```ts should
+## Should
+
+```ts
 yield* AWS.S3.consumeBucketEvents(bucket, { events: ["s3:ObjectCreated:*"], prefix: "incoming/" }, (stream) =>
   stream.pipe(Stream.runForEach((event) => putObject({ Key: `processed/${event.key}`, Body: "..." }))),
 );
 ```
 
-```ts should not
+## Should not
+
+```ts
 yield* AWS.S3.consumeBucketEvents(bucket, { events: ["s3:ObjectCreated:*"] }, (stream) =>
   stream.pipe(Stream.runForEach((event) => putObject({ Key: `processed/${event.key}`, Body: "..." }))), // triggers itself
 );

package/presets/alchemy/durable/stable-step-names.md

@@ -2,10 +2,14 @@
 description: Workflow task, sleep, and waitForEvent names are replay keys, so they must be stable across replays, never built from the clock, randomness, or other values that change between runs.
 ---
 
-```ts must
+## Must
+
+```ts
 yield* Cloudflare.Workflows.task("charge-card", chargeCard(input.orderId));
 ```
 
-```ts never
+## Never
+
+```ts
 yield* Cloudflare.Workflows.task(`charge-${Date.now()}`, chargeCard(input.orderId));
 ```

package/presets/alchemy/durable/webhook-state-is-truth.md

@@ -2,12 +2,16 @@
 description: Access to paid features must be gated on state recorded from Stripe webhooks in the app's own store, never granted because the user reached a success_url or return_url.
 ---
 
-```ts must
+## Must
+
+```ts
 const entitlement = yield* kv.get(`entitlement:${customerId}`);
 if (entitlement === null) return HttpServerResponse.empty({ status: 402 });
 ```
 
-```ts never
+## Never
+
+```ts
 if (url.pathname === "/welcome") {
   yield* kv.put(`entitlement:${customerId}`, "active"); // reached the success URL, not paid
 }

package/presets/alchemy/providers/diff-guards-unresolved-props.md

@@ -2,14 +2,18 @@
 description: A custom provider's diff must check isResolved(news) and return undefined before comparing props that may still be unresolved Outputs, never comparing them directly.
 ---
 
-```ts must
+## Must
+
+```ts
 diff: Effect.fn(function* ({ news, olds }) {
   if (!isResolved(news)) return undefined;
   if (news.region !== olds.region) return { action: "replace" } as const;
 }),
 ```
 
-```ts never
+## Never
+
+```ts
 diff: Effect.fn(function* ({ news, olds }) {
   if (news.region !== olds.region) return { action: "replace" } as const;
 }),

package/presets/alchemy/providers/idempotent-delete.md

@@ -1,14 +1,19 @@
 ---
-description: A custom provider's delete must treat a resource that is already gone as success, catching the not-found error, never failing when it runs again.
+description: The delete handler of a resource provider, the `delete:` lifecycle method given the resource's `output`, must treat a resource that is already gone as success, catching the not-found error, never failing when it runs again. Code outside a provider's delete handler, such as a runtime binding, a Worker route, or a storage client, is not in scope.
+level: warning
 ---
 
-```ts must
+## Must
+
+```ts
 delete: ({ output }) =>
   Effect.tryPromise(() => stripe.products.del(output.productId)).pipe(
     Effect.catchIf(isNotFound, () => Effect.void),
   ),
 ```
 
-```ts never
+## Never
+
+```ts
 delete: ({ output }) => Effect.promise(() => stripe.products.del(output.productId)),
 ```

package/presets/alchemy/providers/lazy-layer-construction.md

@@ -2,11 +2,15 @@
 description: A custom provider, credentials, or state-store Layer must defer resolving credentials and opening connections until an operation runs, never resolving credentials, connecting, or prompting while the Layer is built, because every CLI command builds it.
 ---
 
-```ts must
+## Must
+
+```ts
 export const PostgresState = Layer.effect(State, Effect.cached(makePostgresState(props)));
 ```
 
-```ts never
+## Never
+
+```ts
 export const PostgresState = Layer.effect(State, Effect.gen(function* () {
   const sql = postgres(process.env.DATABASE_URL!); // connects on every CLI command
   return makeState(sql);

package/presets/alchemy/providers/reconcile-from-observed-state.md

@@ -2,7 +2,9 @@
 description: A custom provider's reconcile must read the resource's live state and converge it in one flow that serves create, update, and adoption, never branching into separate create and update bodies on output === undefined or trusting olds as proof the resource exists.
 ---
 
-```ts must
+## Must
+
+```ts
 reconcile: Effect.fn(function* ({ news, output }) {
   let live = yield* observe(output);
   if (live === undefined) live = yield* create(news);
@@ -11,7 +13,9 @@ reconcile: Effect.fn(function* ({ news, output }) {
 }),
 ```
 
-```ts never
+## Never
+
+```ts
 reconcile: Effect.fn(function* ({ news, olds, output }) {
   if (output === undefined) return yield* create(news);
   yield* updateTags(output.id, olds.tags, news.tags);

package/presets/alchemy/resources/anchor-paths-with-import-meta.md

@@ -2,13 +2,17 @@
 description: A path prop such as main or rootDir on a resource declared outside the directory alchemy runs from must be anchored to the declaring file with import.meta, never given as a bare relative string, which resolves from the root instead.
 ---
 
-```ts must
+## Must
+
+```ts
 // backend/src/api.ts
 export default Cloudflare.Worker("Api", { main: import.meta.url }, program);
 export const Site = Cloudflare.Website.Vite("Site", { rootDir: path.resolve(import.meta.dirname, "../frontend") });
 ```
 
-```ts never
+## Never
+
+```ts
 // backend/src/api.ts
 export default Cloudflare.Worker("Api", { main: "src/api.ts" }, program); // resolves to <root>/src/api.ts
 ```

package/presets/alchemy/resources/idempotent-actions-and-seeds.md

@@ -2,7 +2,9 @@
 description: An Action body and a SQL file listed in importFiles must be safe to run again, using IF NOT EXISTS, ON CONFLICT, or upserts, never one-shot inserts or calls that duplicate data or fail when an interrupted deploy retries them.
 ---
 
-```ts must
+## Must
+
+```ts
 export const Migrate = Alchemy.Action("Migrate", Effect.fn(function* () {
   const db = yield* D1Client;
   yield* db.exec("CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)");
@@ -10,7 +12,9 @@ export const Migrate = Alchemy.Action("Migrate", Effect.fn(function* () {
 }));
 ```
 
-```ts never
+## Never
+
+```ts
 export const Seed = Alchemy.Action("Seed", Effect.fn(function* () {
   const db = yield* D1Client;
   yield* db.exec("CREATE TABLE users (id TEXT, name TEXT)");

package/presets/alchemy/resources/previews-reference-shared-resources.md

@@ -2,14 +2,18 @@
 description: Preview stages should reference a long-lived database or cluster with ref and create only cheap per-stage pieces such as a branch, and should not provision a whole project or cluster for every preview.
 ---
 
-```ts should
+## Should
+
+```ts
 const project = stage.startsWith("pr-")
   ? yield* Neon.Project.ref("AppDb", { stage: "staging" })
   : yield* Neon.Project("AppDb", { region: "aws-us-east-1" });
 const branch = yield* Neon.Branch("Branch", { project });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const project = yield* Neon.Project("AppDb", { region: "aws-us-east-1" }); // a new project per PR
 const branch = yield* Neon.Branch("Branch", { project });
 ```

package/presets/alchemy/resources/protect-irreplaceable-data.md

@@ -2,11 +2,15 @@
 description: A bucket or database holding user or business data should be retained with RemovalPolicy.retain(), at least in production, and forceDestroy should be set only on buckets whose contents are disposable; irreplaceable data should not depend on the default destroy policy.
 ---
 
-```ts should
+## Should
+
+```ts
 const uploads = yield* Cloudflare.R2.Bucket("Uploads").pipe(RemovalPolicy.retain(stage === "prod"));
 const cache = yield* Cloudflare.R2.Bucket("Cache", { forceDestroy: true });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const userUploads = yield* Cloudflare.R2.Bucket("UserUploads", { forceDestroy: true });
 ```

package/presets/alchemy/resources/remote-state-for-ci.md

@@ -2,7 +2,9 @@
 description: A stack deployed from CI or by more than one machine must use a shared state store such as Cloudflare.state() or AWS.state(), never Alchemy.localState(), which lives on one machine's disk where CI runners cannot see it.
 ---
 
-```ts must
+## Must
+
+```ts
 export default Alchemy.Stack("App", { providers: Cloudflare.providers(), state: Cloudflare.state() },
   Effect.gen(function* () {
     const api = yield* Api;
@@ -11,7 +13,9 @@ export default Alchemy.Stack("App", { providers: Cloudflare.providers(), state:
 );
 ```
 
-```ts never
+## Never
+
+```ts
 // deployed by .github/workflows/deploy.yml
 export default Alchemy.Stack("App", { providers: Cloudflare.providers(), state: Alchemy.localState() },
   Effect.gen(function* () {

package/presets/alchemy/resources/stable-logical-ids.md

@@ -2,12 +2,16 @@
 description: A resource's logical ID, its first argument, must stay the same from one deploy to the next, never built from timestamps, random values, UUIDs, or commit SHAs, because a new logical ID replaces the resource and deletes the old one with its data.
 ---
 
-```ts must
+## Must
+
+```ts
 const uploads = yield* Cloudflare.R2.Bucket("Uploads");
 const jobs = yield* AWS.SQS.Queue("Jobs");
 ```
 
-```ts never
+## Never
+
+```ts
 const uploads = yield* Cloudflare.R2.Bucket(`Uploads-${Date.now()}`);
 const db = yield* Neon.Project(`Db-${process.env.GITHUB_SHA}`);
 ```

package/presets/alchemy/resources/stage-unique-physical-names.md

@@ -2,7 +2,9 @@
 description: In a stack deployed to several stages, a resource whose physical name is global to an account or org should omit name, so alchemy derives one per stage, or derive it from the stage, and should not hardcode a single name every stage shares.
 ---
 
-```ts should
+## Should
+
+```ts
 const traces = yield* Axiom.Dataset("Traces", Stack.useSync(({ stage }) => ({
   name: `${stage}-traces`,
   kind: "otel:traces:v1" as const,
@@ -10,6 +12,8 @@ const traces = yield* Axiom.Dataset("Traces", Stack.useSync(({ stage }) => ({
 const branch = yield* Neon.Branch("Preview", { project });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const traces = yield* Axiom.Dataset("Traces", { name: "app-traces", kind: "otel:traces:v1" });
 ```

package/presets/alchemy/runtime/bind-tag-not-implementation.md

@@ -2,7 +2,9 @@
 description: When a runtime is split into a Tag class and a make Layer, other runtimes must import and bind only the Tag, and only the Stack provides the Layer; another Worker or Function must never import or provide that implementation Layer.
 ---
 
-```ts must
+## Must
+
+```ts
 // src/Admin.ts
 import { Api } from "./Api.ts";
 
@@ -14,7 +16,9 @@ export default Cloudflare.Worker("Admin", { main: import.meta.url },
 );
 ```
 
-```ts never
+## Never
+
+```ts
 // src/Admin.ts
 import ApiLive, { Api } from "./Api.ts";
 

package/presets/alchemy/runtime/deterministic-config-defaults.md

@@ -2,12 +2,16 @@
 description: A Config default or fallback used by a runtime must be deterministic, because it is evaluated at deploy time and at runtime, never computed from the clock, randomness, or per-process values.
 ---
 
-```ts must
+## Must
+
+```ts
 const port = yield* Config.Number("PORT").pipe(Config.withDefault(3000));
 const region = yield* Config.String("REGION").pipe(Config.withDefault("us-east-1"));
 ```
 
-```ts never
+## Never
+
+```ts
 const instanceId = yield* Config.String("INSTANCE_ID").pipe(Config.withDefault(crypto.randomUUID()));
 const startedAt = yield* Config.String("STARTED_AT").pipe(Config.withDefault(new Date().toISOString()));
 ```

package/presets/alchemy/runtime/disposables-in-request-scope.md

@@ -2,7 +2,9 @@
 description: Connections, pools, sockets, and anything else with a finalizer must be acquired inside a handler or method, where the event's scope releases them, never at module scope or in a runtime's construction Effect, whose finalizers may never run.
 ---
 
-```ts must
+## Must
+
+```ts
 Effect.gen(function* () {
   const url = yield* Config.Redacted("DATABASE_URL");
   return {
@@ -18,7 +20,9 @@ Effect.gen(function* () {
 });
 ```
 
-```ts never
+## Never
+
+```ts
 Effect.gen(function* () {
   const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // one pool for the isolate
   yield* Effect.addFinalizer(() => Effect.promise(() => pool.end())); // workerd never runs this

package/presets/alchemy/runtime/lambda-no-post-response-work.md

@@ -2,7 +2,9 @@
 description: In a Lambda handler, anything that must not be lost must be written durably, to a queue or a table, inside the handler before it responds, never left to a dangling promise, a forked fiber, or a finalizer, because Lambda freezes the instance after the response.
 ---
 
-```ts must
+## Must
+
+```ts
 fetch: Effect.gen(function* () {
   const event = yield* HttpServerRequest.schemaBodyJson(AuditEvent);
   yield* sendMessage({ MessageBody: JSON.stringify(event) });
@@ -10,7 +12,9 @@ fetch: Effect.gen(function* () {
 }),
 ```
 
-```ts never
+## Never
+
+```ts
 fetch: Effect.gen(function* () {
   const event = yield* HttpServerRequest.schemaBodyJson(AuditEvent);
   void fetch(AUDIT_URL, { method: "POST", body: JSON.stringify(event) }); // may never run

package/presets/alchemy/runtime/no-per-request-work-at-construction.md

@@ -2,7 +2,9 @@
 description: A runtime's construction Effect runs at deploy time and again at cold start, so it must only build resources, bindings, layers, and handler groups, never do per-request work such as queries, writes, bound calls, or starting consumers.
 ---
 
-```ts must
+## Must
+
+```ts
 Effect.gen(function* () {
   const table = yield* AWS.DynamoDB.Table("Jobs", { partitionKey: "id", attributes: { id: "S" } });
   const putItem = yield* AWS.DynamoDB.PutItem(table);
@@ -15,7 +17,9 @@ Effect.gen(function* () {
 });
 ```
 
-```ts never
+## Never
+
+```ts
 Effect.gen(function* () {
   const putItem = yield* AWS.DynamoDB.PutItem(table);
   yield* putItem({ Item: { id: { S: "seed" } } }); // runs at deploy and on every cold start

package/presets/alchemy/runtime/resolve-config-and-bindings-at-construction.md

@@ -2,7 +2,9 @@
 description: In a Worker, Function, or Service, Config values and binding factories must be yielded in the outer construction Effect and captured for the handlers, never yielded for the first time inside fetch or another request handler, which does not run at deploy time, so nothing gets bound.
 ---
 
-```ts must
+## Must
+
+```ts
 export default Cloudflare.Worker("Api", { main: import.meta.url },
   Effect.gen(function* () {
     const apiKey = yield* Config.Redacted("API_KEY");
@@ -17,7 +19,9 @@ export default Cloudflare.Worker("Api", { main: import.meta.url },
 );
 ```
 
-```ts never
+## Never
+
+```ts
 export default Cloudflare.Worker("Api", { main: import.meta.url },
   Effect.gen(function* () {
     return {

package/presets/alchemy/secrets/let-alchemy-mint-infra-secrets.md

@@ -2,12 +2,16 @@
 description: A token the infrastructure owns, such as a webhook secret or bearer token, should be minted once with alchemy's Random or left for alchemy to provision, and should not be a hardcoded literal or regenerated on every deploy with crypto.randomUUID().
 ---
 
-```ts should
+## Should
+
+```ts
 export const WebhookSecret = Random("WebhookSecret");
 const auth = yield* BetterAuth({ basePath: "/api/auth", emailAndPassword: { enabled: true } });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const webhookSecret = crypto.randomUUID(); // a new secret on every deploy
 const auth = yield* BetterAuth({ basePath: "/api/auth", secret: Redacted.make("dev-secret") });
 ```

package/presets/alchemy/secrets/never-logged-returned-or-output.md

@@ -2,14 +2,18 @@
 description: A secret, credential, connection string, token, signed URL, or private key must never be logged, returned in an HTTP response, or returned as a stack output; code must expose only names, presence, or non-secret metadata.
 ---
 
-```ts must
+## Must
+
+```ts
 if (url.pathname === "/secret") {
   return yield* HttpServerResponse.json({ name: "API_TOKEN", set: Redacted.value(token).length > 0 });
 }
 return { serial: certificate.serial, expires: certificate.notAfter }; // stack output
 ```
 
-```ts never
+## Never
+
+```ts
 yield* Effect.log(`token=${Redacted.value(token)}`);
 return { databaseUrl: connection.databaseUrl, tlsKey: certificate.privateKey }; // stack output
 ```

package/presets/alchemy/secrets/none-in-browser-env.md

@@ -2,13 +2,17 @@
 description: A value in an env key that a framework inlines into the browser bundle, such as VITE_, NEXT_PUBLIC_, PUBLIC_, or NUXT_PUBLIC_, must be public configuration, never a secret, credential, or connection string, even wrapped in Redacted.
 ---
 
-```ts must
+## Must
+
+```ts
 const site = yield* Cloudflare.Website.Vite("Site", {
   env: { VITE_API_URL: api.url, STRIPE_SECRET_KEY: Config.Redacted("STRIPE_SECRET_KEY") },
 });
 ```
 
-```ts never
+## Never
+
+```ts
 const site = yield* Cloudflare.Website.Vite("Site", {
   env: { VITE_STRIPE_SECRET_KEY: Config.Redacted("STRIPE_SECRET_KEY"), VITE_DATABASE_URL: branch.connectionUri },
 });

package/presets/alchemy/secrets/redacted-until-use.md

@@ -2,7 +2,9 @@
 description: A secret should be read with Config.Redacted, passed to resources and env as Redacted, and unwrapped with Redacted.value only at the call that needs the raw string; it should not be read with Config.String or process.env, or unwrapped early into plain variables.
 ---
 
-```ts should
+## Should
+
+```ts
 const apiKey = yield* Config.Redacted("OPENAI_API_KEY");
 return {
   fetch: Effect.gen(function* () {
@@ -12,7 +14,9 @@ return {
 };
 ```
 
-```ts should not
+## Should not
+
+```ts
 const apiKey = Redacted.value(yield* Config.Redacted("OPENAI_API_KEY"));
 const webhook = process.env.SLACK_WEBHOOK_URL!;
 return { fetch: handler(apiKey, webhook) };

package/presets/alchemy/secrets/unwrap-before-compare-or-send.md

@@ -2,14 +2,18 @@
 description: A Redacted value must be unwrapped with Redacted.value before it is compared, sent, or serialized, never put into a template literal, string concatenation, String(), or JSON, where it becomes the literal text <redacted> and silently fails every check.
 ---
 
-```ts must
+## Must
+
+```ts
 const expected = yield* Config.Redacted("AUTH_TOKEN");
 if (request.headers.authorization !== `Bearer ${Redacted.value(expected)}`) {
   return HttpServerResponse.empty({ status: 401 });
 }
 ```
 
-```ts never
+## Never
+
+```ts
 const expected = yield* Config.Redacted("AUTH_TOKEN");
 if (request.headers.authorization !== `Bearer ${expected}`) { // compares against "Bearer <redacted>"
   return HttpServerResponse.empty({ status: 401 });