@collective-intelligence/extensions-sdk 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md ADDED
@@ -0,0 +1,28 @@
1
+ # `@collective-intelligence/extensions-sdk`: agent guide
2
+
3
+ The portable declaration SDK of Collective Intelligence (CI) extension
4
+ packages: schemas, Knowledge, Skills, Workflows, connectors, roles and
5
+ manifests. Its root loads no Effect, React, Zod, database or HTTP code. The
6
+ package `README.md` holds the full API.
7
+
8
+ ## Rules
9
+
10
+ - Import declarations from the root `.`. Its `/effect` entry is empty: this
11
+ SDK has no I/O client and no Expected Error.
12
+ - Keep one `effect` (`^4.1.0`) in the extension package. It is a required
13
+ peer.
14
+ - Take Effect APIs of the extension SDK family from their `/effect` entries:
15
+ `effectSchema`, `withWorkflowDefault` and the Dataset Provider ports from
16
+ `extensions-sdk-backend/effect`; `StudioApi` from
17
+ `extensions-sdk-frontend-react/effect`.
18
+ - Author a schema with Effect through `effectSchema(...)`; give
19
+ `{ codec: true }` only to an output schema.
20
+
21
+ ## Index
22
+
23
+ - [docs/effect.md](docs/effect.md): read when an extension package uses
24
+ Effect, or you choose the entry of an Effect API of the family.
25
+ - [skills/extensions-sdk-move-to-effect/SKILL.md](skills/extensions-sdk-move-to-effect/SKILL.md):
26
+ run when a package depends on `extensions-sdk-backend-effect`, imports an
27
+ Effect API outside an `/effect` entry, or lint reports
28
+ `ci-solution/effect-subpath`.
package/README.md CHANGED
@@ -1364,8 +1364,9 @@ const source = definePackageSchema({
1364
1364
  The SDK freezes its projections and source envelope but never mutates
1365
1365
  or freezes the provider-native object. Declaration materialization normalizes
1366
1366
  even directly implemented structural sources, so mutable projections, older
1367
- dialects, and unresolved local references cannot leak into manifests. Effect
1368
- and Zod integrations belong in their optional adapter packages.
1367
+ dialects, and unresolved local references cannot leak into manifests. The
1368
+ Effect integration belongs in `@collective-intelligence/extensions-sdk-backend/effect`;
1369
+ the SDK family publishes no Zod adapter.
1369
1370
 
1370
1371
  ## Manifests and consumer profiles
1371
1372
 
package/docs/effect.md ADDED
@@ -0,0 +1,43 @@
1
+ # Effect in extension packages
2
+
3
+ Each SDK of the extension family has an `/effect` entry and `effect`
4
+ `^4.1.0` as a required peer. The extension package installs one copy of
5
+ `effect`; each SDK build keeps it external.
6
+
7
+ | Package | `/effect` holds |
8
+ | ------------------------------- | ----------------------------------------------------------------------------- |
9
+ | `extensions-sdk` | nothing: no I/O client, no Expected Error |
10
+ | `extensions-sdk-backend` | `effectSchema`, `withWorkflowDefault`, the Dataset Provider ports and Schemas |
11
+ | `extensions-sdk-frontend` | nothing: its loaders come from the host |
12
+ | `extensions-sdk-frontend-react` | the `StudioApi` service and its tagged errors |
13
+
14
+ ## Rules
15
+
16
+ - Import declarations from the root of `extensions-sdk`, also in an Effect
17
+ package. An empty `/effect` is the convention, not a gap.
18
+ - The package `extensions-sdk-backend-effect` is removed after its last
19
+ version 0.2.0. Import `extensions-sdk-backend/effect` instead.
20
+ - `ci package build` bundles each SDK `/effect` entry into the release and
21
+ keeps the root entries Host-provided. An earlier `ci` CLI keeps `/effect`
22
+ external, and `ci package validate` rejects that release: use a CLI that
23
+ bundles `/effect`.
24
+ - The `ci-solution/effect-subpath` rule of `@collective-intelligence/lint`
25
+ reports an Effect API from outside `/effect`, a `<sdk>-effect` package, and
26
+ the deprecated paths.
27
+
28
+ ## Schemas with Effect
29
+
30
+ ```ts
31
+ import { effectSchema } from "@collective-intelligence/extensions-sdk-backend/effect"
32
+ import * as Schema from "effect/Schema"
33
+
34
+ const input = effectSchema(Schema.Struct({ id: Schema.NonEmptyString }))
35
+ const output = effectSchema(Schema.Struct({ found: Schema.Boolean }), {
36
+ codec: true
37
+ })
38
+ ```
39
+
40
+ - `effectSchema(schema)` is decode-only. An output declaration needs
41
+ `{ codec: true }`.
42
+ - Use `withWorkflowDefault(value)` for a default that the projected JSON
43
+ Schema must show; `withDecodingDefault...` is opaque to the projection.
package/package.json CHANGED
@@ -1,12 +1,15 @@
1
1
  {
2
2
  "name": "@collective-intelligence/extensions-sdk",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "Framework-neutral authoring contracts for Collective Intelligence extension packages.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "files": [
8
8
  "dist",
9
- "README.md"
9
+ "README.md",
10
+ "AGENTS.md",
11
+ "docs",
12
+ "skills"
10
13
  ],
11
14
  "main": "./dist/index.js",
12
15
  "types": "./dist/index.d.ts",
@@ -55,5 +58,5 @@
55
58
  "typescript": "7.0.2",
56
59
  "ultracite": "7.10.7"
57
60
  },
58
- "gitHead": "399369a97e85b54b43aeac887e7ba9c960cb7505"
61
+ "gitHead": "51fdea833e25fe215b3cf0d70adf1984b8e0f81c"
59
62
  }
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: extensions-sdk-move-to-effect
3
+ description: Move a Collective Intelligence extension package to the `/effect` convention of the extension SDK family. Use when a package depends on `@collective-intelligence/extensions-sdk-backend-effect`, imports an Effect API outside an `/effect` entry, has more than one `effect` version, or lint reports `ci-solution/effect-subpath`.
4
+ ---
5
+
6
+ # Move an extension package to `/effect`
7
+
8
+ Reference: [effect.md](../../docs/effect.md).
9
+
10
+ ## Steps
11
+
12
+ 1. **Find the old paths.** Search the package for
13
+ `@collective-intelligence/extensions-sdk-backend-effect` in imports and in
14
+ `package.json`, and run oxlint with the `recommended` config of
15
+ `@collective-intelligence/lint`. Done when you have each import and each
16
+ `ci-solution/effect-subpath` finding.
17
+ 2. **Rewrite the imports.** `extensions-sdk-backend-effect` becomes
18
+ `@collective-intelligence/extensions-sdk-backend/effect`; each other
19
+ finding names its `/effect` entry. Declarations stay on the root of
20
+ `extensions-sdk`. Done when step 1 finds nothing.
21
+ 3. **Fix the dependencies.** Remove `extensions-sdk-backend-effect`. Add
22
+ `effect` `^4.1.0` once; keep one `effect@` version in the lockfile. Done
23
+ when the lockfile holds one `effect` version.
24
+ 4. **Check the CLI.** Use a `ci` CLI version that bundles an SDK `/effect`
25
+ entry (see the CLI `CHANGELOG.md`). Done when `ci package build` and
26
+ `ci package validate` pass.
27
+ 5. **Verify.** Run the type-check and the package tests. Done when both pass
28
+ and oxlint reports no `ci-solution/effect-subpath` finding.