agentsdotmd 1.1.2 → 1.1.3

package/bin/agentsdotmd.js

@@ -50,9 +50,7 @@ cli
 
     try {
       const contents = await Promise.all(promises)
-      const header = `<!-- This file is auto-generated by the agentsdotmd CLI from your package.json script.
-Do not edit this file directly. To add custom instructions, create a local file ./MY_AGENTS.md
-and add it to your agentsdotmd command in package.json. -->\n\n`
+      const header = `<!-- This AGENTS.md file is generated. Look for an agents.md package.json script to see what files to update instead. -->\n\n`
       const content = header + contents.join('\n') + '\n'
       fs.writeFileSync('AGENTS.md', content)
       console.log(`AGENTS.md generated successfully with ${files.length} file(s)`)

package/changelog.md

@@ -1,5 +1,11 @@
 # changelog
 
+## 1.1.3
+
+### Patch Changes
+
+- vitest.md instructions update
+
 ## 1.1.2
 
 ### Patch Changes

package/dedent.md

@@ -0,0 +1,16 @@
+## dedent
+
+when creating long strings in functions use dedent so that we can indent the string content and make it more readable
+
+for example:
+
+```ts
+import dedent from 'string-dedent'
+
+const content = dedent`
+  some content
+```
+
+IMPORTANT: notice that i have at start and end a new line. this is required when using string-dedent. Also notice npm package `string-dedent` instead of `dedent`.
+
+When creating code snippets alias dedent to variables like html or javascript so that I get syntax highlight in my editor: `const html = dedent`

package/fly.md

@@ -4,6 +4,8 @@ fly is a deployment platform. some packages use it to deploy the website. you ca
 
 usually there are 2 fly apps for each package, one staging environment and one production. these are 2 different apps at 2 different urls, you can target the right app usually by using `pnpm fly:preview` or `pnpm fly:prod`. sometimes there is only `pnpm fly` and you can use that instead. These scripts will append the right --app argument to work on the right fly app.
 
+Never deploy with fly yourself. ask the user to do it
+
 ## reading logs
 
 you can read fly apps logs using `pnpm fly:preview logs --no-tail | tail -n 100`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsdotmd",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "",
   "type": "module",
   "main": "index.js",

package/prisma.md

@@ -49,10 +49,10 @@ this simply means to always include a check in prisma queries to make sure that
 
 ```typescript
 const resource = await prisma.resource.findFirst({
-    where: { resourceId, parentResource: { users: { some: { userId } } } },
-})
+  where: { resourceId, parentResource: { users: { some: { userId } } } },
+});
 if (!resource) {
-    throw new AppError(`cannot find resource`)
+  throw new AppError(`cannot find resource`);
 }
 ```
 
@@ -81,4 +81,24 @@ if (!user.subscription) {
         JSON.stringify({ message: `user has no subscription` }),
     )
 }
-````
+````
+
+## foreign key constraints
+
+sometimes you will get errors like "Invalid `upsert()` invocation: Foreign key constraint violated on the constraint: `filed1_filed2_fkey`". This can be caused by the following issue
+
+- a field that has a relation to table X is being passed a value where no table X exists for that id. You can fix the issue by making sure that the table exists before doing the create or upsert
+- With upsert, even if the create branch is valid, the update branch can violate the FK.
+
+```ts
+await prisma.child.upsert({
+  where: { id: 1 },
+  create: {
+    parent: { connect: { id: 1 } },
+  },
+  update: {
+    parent: { connect: { id: 9999 } }, // no such parent
+  },
+});
+```
+-

package/react.md

@@ -37,3 +37,15 @@
 - non component code should be put in the src/lib folder.
 
 - hooks should be put in the src/hooks.tsx file. do not create a new file for each new hook. also notice that you should never create custom hooks, only do it if asked for.
+
+## zustand
+
+zustand is the preferred way to created global React state. put it in files like state.ts or x-state.ts where x is something that describe a portion of app state in case of multiple global states or multiple apps
+
+- minimize number of props. do not use props if you can use zustand state instead. the app has global zustand state that lets you get a piece of state down from the component tree by using something like `useStore(x => x.something)` or `useLoaderData<typeof loader>()` or even useRouteLoaderData if you are deep in the react component tree
+
+- do not consider local state truthful when interacting with server. when interacting with the server with rpc or api calls never use state from the render function as input for the api call. this state can easily become stale or not get updated in the closure context. instead prefer using zustand `useStore.getState().stateValue`. notice that useLoaderData or useParams should be fine in this case.
+
+- NEVER add zustand state setter methods. instead use useStore.setState to set state. For example never add a method `setVariable` in the state type. Instead call `setState` directly
+
+- zustand already merges new partial state with the previous state. NEVER DO `useStore.setState({ ...useStore.getInitialState(), ... })` unless for resetting state

package/retries-and-resumability.md

@@ -0,0 +1,84 @@
+# Retryable, Resumable, Idempotent Tasks — Summary
+
+## Problem
+
+- Long-running tasks (e.g.,Notion sync, AI chat, website generation) take minutes.
+- Keeping a single connection open → network error probability grows with time.
+- Tasks also do outbound network calls → compound failure surface.
+- Risk of duplicate/concurrent runs corrupting state.
+
+## Goals
+
+- **Resumable**: continue from last checkpoint after failures.
+- **Retryable**: safe to retry automatically.
+- **Idempotent**: side effects via upserts/deterministic writes.
+- **Single-flight**: prevent concurrent execution per task.
+
+## Core Principles
+
+- Checkpoint progress (cursor/step) frequently.
+- Deterministic ordering (e.g., pages list) so “skip until cursor” is correct.
+- At-least-once safe semantics: dedupe by (task_id, sequence/event_id).
+- Small, explicit payload carrying resume info on every retry.
+
+## Client vs Server State
+
+### Client-held (prefer for AI chat / interactive flows)
+
+- Client persists: messages[], partial assistant text, last_event_seq.
+- Request includes: task_id (resume_token), messages[], partial_assistant, last_event_seq.
+- Server is stateless: reconstructs from request; uses model “prefill” to resume (verify model support; Anthropic supports; OpenAI may vary).
+- Benefit: fewer server-side moving parts. Cost: model compatibility + client must track emitted events.
+
+### Server-held (required for background jobs / fixed retry bodies, e.g., QStash)
+
+- DB state per task: {task_id, step, cursor (last_synced_page_id), checksum, updated_at}.
+- Resume by skipping to cursor using deterministic ordering.
+- Needed when infrastructure cannot modify retry payloads.
+
+## Concurrency Control
+
+- Single-flight/lease per task_id:
+  - Acquire lease with TTL + heartbeats.
+  - If a retry arrives while running: attach to existing run or reject with retry-after.
+  - Release lease on completion or expiry.
+
+## API Shape (minimal)
+
+- POST /tasks/start → {task_id, optional cursor}
+- POST /tasks/resume → body must include:
+  - task_id (resume_token)
+  - last_cursor (e.g., last_synced_page_id)
+  - last_event_seq (for stream dedupe)
+  - client_state if server is stateless (e.g., messages[])
+- GET /tasks/status?task_id=… → {step, cursor, percent}
+
+## Retry Strategy
+
+- Exponential backoff + jitter; cap total time.
+- Persist checkpoint before/after each substantial step.
+- Retries always include last_cursor + last_event_seq.
+- Treat transport and model/API timeouts as retriable; invalid input as terminal.
+
+## Event Replay (AI chat)
+
+- All server events carry monotonically increasing seq.
+- Client sends last_event_seq on resume; server suppresses ≤ seq to avoid duplicates.
+
+## Sync Pattern
+
+- Pre-compute deterministic ordered page list.
+- Cursor = last_synced_page_id.
+- On resume: “skip-until-cursor” then continue.
+- Idempotent writes (upsert by external_id).
+
+## Spice Flow Notes
+
+- Current “retry same body” is insufficient; add ability to override body on retry.
+- Temporary workaround: client-managed loop that updates last_cursor and re-posts.
+
+## What to Verify
+
+- Model prefill/continuation support for chosen LLM.
+- Lease/lock implementation (row-level lock or key-value lease with TTL).
+- Observability: log task_id, step, cursor, retry_count, lease_owner.

package/shadcn.md

@@ -16,4 +16,8 @@
 
 this project uses shadcn components placed in the website/src/components/ui folder. never add a new shadcn component yourself by writing code. instead use the shadcn cli installed locally.
 
-try to reuse these available components when you can, for example for buttons, tooltips, scroll areas, etc.
+try to reuse these available components when you can, for example for buttons, tooltips, scroll areas, etc.
+
+## reusing shadcn components
+
+when creating a new React component or adding jsx before creating your own buttons or other elements first check the files inside `src/components/ui` and `src/components` to see what is already available. So you can reuse things like Button and Tooltip components instead of creating your own.

package/stripe.md

@@ -7,6 +7,31 @@ the Stripe billing portal is used to
 - send user to payment to create a sub via `stripe.checkout.sessions.create`
 - let user change plan, cancel or change payment method ("manage subscription") via `stripe.billingPortal.sessions.create`
 
+## customerId
+
+every time you are about to do a call to `checkout.sessions.create` make sure that we create the Stripe customer first. So that we do not get duplicate Stripe customers for different subscriptions:
+
+```ts
+
+let customerId = org.stripeCustomerId
+
+if (!customerId) {
+    const customer = await stripe.customers.create({
+        email: org.email || undefined,
+        name: org.name || undefined,
+    })
+
+    customerId = customer.id
+
+    await prisma.org.update({
+        where: { id: orgId },
+        data: { stripeCustomerId: customerId },
+    })
+}
+
+ await stripe.checkout.sessions.create({ customer: customerId, ... })
+```
+
 ## subscriptions
 
 a subscription is active if state is in
@@ -14,6 +39,18 @@ a subscription is active if state is in
 - trialing
 - active
 
+```ts
+await prisma.subscription.findFirst({
+  where: {
+    orgId: orgId,
+    status: {
+      in: ["active", "trialing"],
+    },
+    // ...
+  },
+});
+```
+
 a subscription can be reactivated if state is NOT in
 
 - canceled
@@ -21,6 +58,3 @@ a subscription can be reactivated if state is NOT in
 - unpaid
 
 > If sub is in any of these states the user will not be able to use the billing portal to reactivate it. Meaning we should treat a subscription in these states as completely missing. Forcing the user to create a new one instead of shoging the "manage subscription" button that redirects the user to the billing portal. BUT customer id must be preserved, reusing previous sub customerId in `stripe.billingPortal.sessions.create({ customer: prevCustomerId })`
-
-
-##

package/tailwind.md

@@ -11,3 +11,5 @@ for margin, padding, gaps, widths and heights it is preferable to use multiples
 4 is equal to 16px which is the default font size of the page. this way every spacing is a multiple of the height and width of a default letter.
 
 user interfaces are mostly text so using the letter width and height as a base unit makes it easier to reason about the layout and sizes.
+
+use grow instead of flex-1.

package/typescript.md

@@ -6,6 +6,10 @@
 
 - always add the {} block body in arrow functions: arrow functions should never be written as `onClick={(x) => setState('')}`. NEVER. instead you should ALWAYS write `onClick={() => {setState('')}}`. this way it's easy to add new statements in the arrow function without refactoring it.
 
+- in array operations .map, .filter, .reduce and .flatMap are preferred over .forEach and for of loops. For example prefer doing `.push(...array.map(x => x.items))` over mutating array variables inside for loops. Always think of how to turn for loops into expressions using .map, .filter or .flatMap if you ever are about to write a for loop.
+
+- if you encounter typescript errors like "undefined | T is not assignable to T" after .filter(Boolean) operations: use a guarded function instead of Boolean: `.filter(isTruthy)`. implemented as `function isTruthy<T>(value: T): value is NonNullable<T> { return Boolean(value) }`
+
 - minimize useless comments: do not add useless comments if the code is self descriptive. only add comments if requested or if this was a change that i asked for, meaning it is not obvious code and needs some inline documentation. if a comment is required because the part of the code was result of difficult back and forth with me, keep it very short.
 
 - ALWAYS add all information encapsulated in my prompt to comments: when my prompt is super detailed and in depth, all this information should be added to comments in your code. this is because if the prompt is very detailed it must be the fruit of a lot of research. all this information would be lost if you don't put it in the code. next LLM calls would misinterpret the code and miss context.
@@ -28,7 +32,7 @@
 
 - when creating urls from a path and a base url, prefer using `new URL(path, baseUrl).toString()` instead of normal string interpolation. use type-safe react-router `href` or spiceflow `this.safePath` (available inside routes) if possible
 
-- for node built-in imports, never import singular names. instead do `import fs from 'node:fs'`, same for path, os, etc.
+- for node built-in imports, never import singular exported names. instead do `import fs from 'node:fs'`, same for path, os, etc.
 
 - NEVER start the development server with pnpm dev yourself. there is no reason to do so, even with &
 

package/vitest.md

@@ -2,6 +2,8 @@
 
 do not write new test files unless asked. do not write tests if there is not already a test or describe block for that function or module.
 
+if the inputs for the tests is an array of repetitive fields and long content, generate this input data programmatically instead of hardcoding everything. only hardcode the important parts and generate other repetitive fields in a .map or .reduce
+
 tests should validate complex and non-obvious logic. if a test looks like a placeholder, do not add it.
 
 use vitest to run tests. tests should be run from the current package directory and not root. try using the test script instead of vitest directly. additional vitest flags can be added at the end, like --run to disable watch mode or -u to update snapshots.