You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .agents/skills/add-connector/SKILL.md
+65-16Lines changed: 65 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,8 +12,8 @@ You are an expert at adding knowledge base connectors to Sim. A connector syncs
12
12
When the user asks you to create a connector:
13
13
1. Use Context7 or WebFetch to read the service's API documentation
14
14
2. Determine the auth mode: **OAuth** (if Sim already has an OAuth provider for the service) or **API key** (if the service uses API key / Bearer token auth)
15
-
3. Create the connector directory and config
16
-
4. Register it in the connector registry
15
+
3. Create the connector directory: a client-safe `meta.ts` (declarative metadata) plus the runtime module that spreads it
16
+
4. Register it in BOTH the server registry and the client-safe meta registry
17
17
18
18
## Hard Rule: No Guessed Response Or Document Schemas
19
19
@@ -32,13 +32,19 @@ If the source schema is unknown, do one of these instead:
32
32
33
33
## Directory Structure
34
34
35
+
Each connector is split into a client-safe metadata file and a server-only runtime file. This mirrors the `XBlockMeta` / `BLOCK_META_REGISTRY` split in `apps/sim/blocks` — client components (the knowledge UI) only need the metadata (icon, name, auth, config fields), so the runtime functions (which pull server-only helpers like `input-validation.server` → `undici` → `node:net`) must stay out of the client bundle.
36
+
35
37
Create files in `apps/sim/connectors/{service}/`:
36
38
```
37
39
connectors/{service}/
38
-
├── index.ts # Barrel export
39
-
└── {service}.ts # ConnectorConfig definition
40
+
├── index.ts # Barrel export (re-exports the runtime connector)
└── {service}.ts # ConnectorConfig — spreads the meta + adds runtime functions
40
43
```
41
44
45
+
-`meta.ts` exports `{service}ConnectorMeta: ConnectorMeta`. It imports ONLY the icon from `@/components/icons`, `import type { ConnectorMeta } from '@/connectors/types'`, and any pure-data constants. It must NEVER import server/runtime code.
46
+
-`{service}.ts` exports `{service}Connector: ConnectorConfig`. It imports the meta via `import { {service}ConnectorMeta } from '@/connectors/{service}/meta'`, spreads it as the first property, and holds the runtime functions (which may import server-only helpers like `@/lib/knowledge/documents/utils`).
47
+
42
48
## Authentication
43
49
44
50
Connectors use a discriminated union for auth config (`ConnectorAuthConfig` in `connectors/types.ts`):
@@ -55,19 +61,17 @@ For services with existing OAuth providers in `apps/sim/lib/oauth/types.ts`. The
55
61
### API key mode
56
62
For services that use API key / Bearer token auth. The modal shows a password input with the configured `label` and `placeholder`. The API key is encrypted at rest using AES-256-GCM and stored in a dedicated `encryptedApiKey` column on the connector record. The sync engine decrypts it automatically — connectors receive the raw access token in `listDocuments`, `getDocument`, and `validateConfig`.
57
63
58
-
## ConnectorConfig Structure
64
+
## Connector Structure (meta.ts + runtime)
65
+
66
+
The declarative metadata lives in `meta.ts` (`ConnectorMeta`). The runtime functions live in `{service}.ts` (`ConnectorConfig`), which spreads the meta as its first property.
@@ -499,7 +531,9 @@ If the service already has an icon in `apps/sim/components/icons.tsx` (from a to
499
531
500
532
## Registering
501
533
502
-
Add one line to `apps/sim/connectors/registry.ts`:
534
+
Register in BOTH registries, keeping the same alphabetical-by-id ordering in each.
535
+
536
+
1.**Server registry** — `apps/sim/connectors/registry.server.ts` (server-only full registry; holds full connectors with runtime functions, imported by the sync engine and knowledge API routes):
2.**Client-safe meta registry** — `apps/sim/connectors/registry.ts` (imports each connector's `meta.ts` only, so client components can use it without pulling server-only code; the metadata counterpart to `BLOCK_META_REGISTRY`):
`registry.ts` exports `CONNECTOR_META_REGISTRY: ConnectorMetaRegistry` plus the helpers `getConnectorMeta(id)` and `getAllConnectorMeta()`, importing each `@/connectors/{service}/meta` directly — never the runtime module. `registry.server.ts` exports `CONNECTOR_REGISTRY: ConnectorRegistry`.
559
+
513
560
## Reference Implementations
514
561
515
562
-**OAuth + contentDeferred**: `apps/sim/connectors/google-drive/google-drive.ts` — file download with metadata-based hash, `orderBy` for deterministic pagination
description: Author or review a Drizzle DB migration for zero-downtime safety — expand/contract phasing, backward-compatibility with the deployed app version, and writing the `-- migration-safe` acknowledgment the check:migrations lint requires. Use when adding/editing files under `packages/db/migrations/` or changing `packages/db/schema.ts`.
4
+
---
5
+
6
+
# DB Migrate Skill
7
+
8
+
You make schema changes that survive a deploy without downtime. The `check:migrations` lint (`scripts/check-migrations-safety.ts`) is the deterministic gate; you are the judgment that decides whether a flagged change is actually safe and writes the annotation that satisfies it.
9
+
10
+
## The window (why this matters)
11
+
12
+
A deploy runs the migration, then rolls out the new app image via blue/green. The two are **not atomic and cannot be** — during cutover the old task set keeps serving against the **already-migrated** schema. So:
13
+
14
+
> Every migration must be backward-compatible with the app version that is *already deployed*.
15
+
16
+
If a migration drops a column the old code still reads, renames one, or adds a `NOT NULL` the old inserts don't populate, the old code throws until traffic fully shifts — the downtime we're guarding against. You can't fix this by reordering the pipeline; the only fix is discipline.
17
+
18
+
## Expand / contract
19
+
20
+
Split every breaking change across **two deploys**:
21
+
22
+
1.**Expand** (this PR): additive, backward-compatible schema + code that tolerates *both* the old and new shape.
23
+
2.**Contract** (a later PR, after expand is fully deployed): remove the old thing, now that nothing reads it.
24
+
25
+
Never put expand and contract in the same PR. If this PR both removes the code that used a column *and* drops the column, the old code is still live during cutover — split it.
26
+
27
+
### Per-operation playbook
28
+
29
+
| You want to | Do (deploy 1 = expand) | Do (deploy 2 = contract) |
30
+
|---|---|---|
31
+
| Add a required column |`ADD COLUMN` nullable or `DEFAULT`; code writes it | backfill, then `SET NOT NULL`|
32
+
| Rename a column/table | add the new name; code dual-writes / reads new-then-old | drop the old name |
33
+
| Drop a column/table | stop all reads/writes in code; ship it |`DROP` (annotate) |
34
+
| Change a column type | add a new column of the new type; dual-write | backfill, swap reads, drop old |
35
+
| Add FK / CHECK |`ADD CONSTRAINT ... NOT VALID`|`VALIDATE CONSTRAINT` separately |
36
+
| Index an existing table |`COMMIT;` breakpoint → `SET lock_timeout = 0` → `CREATE INDEX CONCURRENTLY IF NOT EXISTS` (see `packages/db/scripts/migrate.ts`) | — |
37
+
| Drop an index |`COMMIT;` breakpoint → `DROP INDEX CONCURRENTLY` — plain `DROP INDEX` takes ACCESS EXCLUSIVE on the table | — |
A `CREATE INDEX`, `ADD COLUMN`, or `ADD CONSTRAINT` against a table **created in the same migration** is always safe (no rows, no live traffic) — the lint already suppresses those.
41
+
42
+
## Tracking the contract (don't let it rot)
43
+
44
+
The contract half is deferred to a later deploy — and that is exactly when it gets forgotten, leaving dead columns, orphaned tables, and `NOT NULL`s that never land. Every deferred contract must become a durable, greppable TODO.
45
+
46
+
When an expand defers a drop, leave a **`contract-pending`** marker on the legacy column/table in `packages/db/schema.ts` — that is the file you will be editing when you finally do the drop, so the reminder lives where the work happens:
47
+
48
+
```ts
49
+
// contract-pending(after #5035 is fully deployed): drop once permission-check.ts stops reading it
50
+
workspaceId: text('workspace_id'),
51
+
```
52
+
53
+
Format: `contract-pending(<precondition>): <what to drop> — <why it's safe once the precondition holds>`. The precondition names the PR/release that removes the last reader and **must be fully deployed** before the contract ships.
54
+
55
+
-**The TODO list is a grep** — always accurate, never drifts: `grep -rn "contract-pending" packages/db apps/sim`. Run it when starting migration work to see what is owed.
56
+
- For anything with a real owner or schedule, also open a tracking issue and put its number in the marker.
57
+
-**Close the loop in the contract PR:** the contract migration's `-- migration-safe:` annotation references the expand, and you **delete the `contract-pending` marker** in the same PR:
ALTERTABLE"permission_group" DROP COLUMN "workspace_id";
61
+
```
62
+
- An expand merged **without** a marker for the drop it defers, or a contract merged **without** removing its marker, is a bug — flag it in review.
63
+
64
+
## The judgment the lint can't do
65
+
66
+
The lint flags risky *shapes*; it cannot know whether a given drop is *safe right now*. For each flagged statement, do the work it can't:
67
+
68
+
1.**Is the dependency gone?** Grep the app for the table/column: search `apps/sim` and `packages` for the column name, the Drizzle field (camelCase), and the table object. If any live read/write remains, it is **not** safe — fix the code first.
69
+
2.**Did the expand already ship?** The removal of that read/write must be in a deploy that is *already out*, not this same PR. If it's in this PR, split: land the code change now, do the destructive migration in a follow-up after it deploys.
70
+
3.**Backfills:** confirm the `UPDATE`/`DELETE` is batched (bounded `WHERE`/keyset, not a single whole-table statement), idempotent (safe to replay — a failed migration re-runs unjournaled files from the top), and safe under concurrent writes from the still-live old app.
71
+
72
+
## Workflow
73
+
74
+
1. Edit `packages/db/schema.ts`, then `cd packages/db && bunx drizzle-kit generate` to produce the SQL. If this is an expand that defers a drop, leave a `contract-pending` marker on the legacy column (see "Tracking the contract"). If this is the contract, delete the marker it resolves.
75
+
2. Hand-edit the generated SQL where the playbook requires it: `CONCURRENTLY` + `COMMIT;` breakpoint for indexes on existing tables, `NOT VALID` for constraints, batching for backfills.
76
+
3. Run `bun run check:migrations` (base defaults to `origin/staging`).
77
+
-**Hard errors** (`add-not-null-no-default`, `rename`, `index-not-concurrent`, `constraint-not-valid`, …): rewrite into expand/contract. Do **not** try to annotate them away — the lint won't accept it.
78
+
-**Annotate tier** (`drop-table`, `drop-column`, `drop-default`, `set-not-null`, `alter-type`, `drop-index`): only after you've confirmed steps 1–3 above, add a comment on the line directly above the statement:
79
+
```sql
80
+
-- migration-safe: `secret` read removed in v0.6.1 (#1234), shipped two deploys ago
81
+
ALTERTABLE"webhook" DROP COLUMN "secret";
82
+
```
83
+
The reason must be specific and name the PR/version that removed the dependency. An empty reason fails the lint.
84
+
-**Warnings** (`data-backfill`): non-blocking, but confirm the batching/idempotency before merging.
85
+
4. Verify locally: `cd packages/db && bun run db:migrate` against a dev DB.
86
+
87
+
## Hard rule
88
+
89
+
Never annotate a destructive statement just to make the lint pass. The annotation is a claim that you verified the old code no longer depends on it. If you can't make that claim truthfully, the change belongs in a later deploy — tell the user to split it.
Copy file name to clipboardExpand all lines: .agents/skills/ship/SKILL.md
+11-6Lines changed: 11 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
---
2
2
name: ship
3
-
description: Commit, push, and open a PR to staging in one shot
3
+
description: Commit, push, and open a PR to staging in one shot — runs the cleanup pass and, when migrations changed, the db-migrate safety review first
4
4
---
5
5
6
6
# Ship Command
@@ -16,12 +16,17 @@ When the user runs `/ship`:
16
16
- Types: `fix`, `feat`, `improvement`, `chore`
17
17
- Scope: short identifier (e.g., `undo-redo`, `api`, `ui`)
18
18
- Keep it concise
19
-
3.**Run pre-ship checks** from the repo root before staging:
19
+
3.**Run the cleanup pass** — only if the diff modifies UI code (any `.tsx` file, or anything under `apps/sim/components/`, `apps/sim/hooks/`, or `apps/sim/stores/`): `/cleanup`
20
+
- The six code-quality skills (effects, memo, callbacks, state, React Query, emcn) only apply to React code, so skip this step entirely when no UI was touched. When it runs, it applies fixes so they land in this commit.
21
+
4.**Run migration safety** — only if the diff touches `packages/db/migrations/**` or `packages/db/schema.ts`:
22
+
- Run `/db-migrate` to review the migration for zero-downtime safety (expand/contract phasing, backward-compatibility with the deployed app version).
23
+
-`bun run check:migrations origin/staging` must pass (staging is the PR base). Do not silence a flagged statement with a `-- migration-safe:` annotation unless `/db-migrate` confirmed the old code no longer depends on it; otherwise split the destructive change into a later deploy.
24
+
5.**Run pre-ship checks** from the repo root before staging:
20
25
-`bun run lint` to fix formatting issues
21
26
-`bun run check:api-validation:strict` to catch boundary contract failures before CI
22
-
4.**Stage and commit** the changes with the generated message
23
-
5.**Push to origin** using the current branch name
24
-
6.**Create a PR** to staging with a description in the user's voice
27
+
6.**Stage and commit** the changes with the generated message
28
+
7.**Push to origin** using the current branch name
29
+
8.**Create a PR** to staging with a description in the user's voice
- "Tested manually" is acceptable for testing section; include lint and boundary validation results when run
85
+
- "Tested manually" is acceptable for testing section; include lint, boundary validation, and (when migrations changed) `check:migrations` results when run
0 commit comments