@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 +28 -0
- package/README.md +3 -2
- package/docs/effect.md +43 -0
- package/package.json +6 -3
- package/skills/extensions-sdk-move-to-effect/SKILL.md +28 -0
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.
|
|
1368
|
-
|
|
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.
|
|
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": "
|
|
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.
|