@collective-intelligence/lint 0.2.1 → 0.2.3

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/README.md CHANGED
@@ -82,6 +82,7 @@ the `collective-intelligence` pack installs the skill and adds the plugin with
82
82
  | `ci-solution/effect-subpath` | An SDK Effect API comes from the SDK's `/effect` subpath; removed SDK paths are reported. | Effect convention |
83
83
  | `ci-solution/no-run-in-view` | A view module calls no `fetch` and runs no Effect. | Effect convention |
84
84
  | `ci-solution/effect-actors` | XState side-effect actors are `fromEffect` actors. | Effect convention |
85
+ | `ci-solution/effect-writes` | No module takes TanStack Query `useMutation`; writes run in `fromEffect` actors. | Effect convention |
85
86
 
86
87
  ### Package boundaries
87
88
 
@@ -156,7 +157,8 @@ The rule reports each file in a folder that has neither.
156
157
  ### Effect convention
157
158
 
158
159
  An app keeps its side effects in XState machines: each side effect is a
159
- `fromEffect` actor, and views read data through TanStack Query. These rules
160
+ `fromEffect` actor, views read data through TanStack Query, and writes refresh
161
+ those reads through the SDK `QueryCache`. These rules
160
162
  check the parts of that convention that imports and calls show.
161
163
 
162
164
  #### `effect-subpath`
@@ -207,13 +209,41 @@ entry.
207
209
 
208
210
  The rule reports each `fromPromise`, `fromCallback`, `fromObservable` and
209
211
  `fromEventObservable` that an import, a re-export or a namespace import
210
- (`XState.fromPromise`, `XState["fromPromise"]`) takes from `xstate` or
211
- `xstate/*`. Make side-effect actors with `fromEffect` from
212
- `@collective-intelligence/external-apps-client-sdk-react/effect`. Machines and
212
+ (`XState.fromPromise`, `XState["fromPromise"]`,
213
+ `const { fromPromise } = XState`) takes from `xstate` or `xstate/*`. Make side-effect actors with `fromEffect` from
214
+ `@collective-intelligence/external-apps-client-sdk-react/effect` in a detached
215
+ app, or from `@collective-intelligence/extensions-sdk-frontend-react/effect` in
216
+ a hosted Studio Widget. Machines and
213
217
  `fromTransition` actors have no side effects and are not reported. A local name
214
218
  that shadows the namespace import, such as a parameter named `XState`, is not
215
219
  reported.
216
220
 
221
+ #### `effect-writes`
222
+
223
+ The rule reports each `useMutation` that an import, a re-export or a namespace
224
+ import (`ReactQuery.useMutation`, `ReactQuery["useMutation"]`,
225
+ `const { useMutation } = ReactQuery`) takes from `@tanstack/react-query`. Write through a `fromEffect` actor from
226
+ `@collective-intelligence/external-apps-client-sdk-react/effect` in a detached
227
+ app, or from `@collective-intelligence/extensions-sdk-frontend-react/effect` in
228
+ a hosted Studio Widget; after the write, the actor refreshes reads through the
229
+ `QueryCache` of the same entrypoint (`invalidate`, `setData`).
230
+
231
+ The rule checks every module. `useMutation` runs only during a React render,
232
+ so a module that takes it is a view, a hook or a helper of one of them.
233
+
234
+ `useQuery` and the other reads are not reported, and neither are
235
+ `useMutationState` and `useIsMutating`: they only read the state of a
236
+ `useMutation`. A `useMutation` from another library, such as
237
+ `@apollo/client`, is not reported. The entity hooks of
238
+ `@collective-intelligence/external-apps-client-sdk-react/resources`
239
+ (`useEntityCreate`, `useEntityUpdate`, `useEntityDelete`) are not reported:
240
+ the SDK writes and refreshes its own entity reads.
241
+
242
+ The rule checks no query key. An app that builds the SDK's `"ci-entities"`
243
+ key by hand, for example in `invalidateQueries`, is not reported: the SDK
244
+ owns that key for its entity reads but exports no key or refresh function for
245
+ them yet, so a report would have no supported fix.
246
+
217
247
  ## Adding a rule
218
248
 
219
249
  Each rule is a plain Oxlint rule in its own folder, `src/rules/<rule>/`:
package/dist/index.js CHANGED
@@ -53,6 +53,48 @@ var moduleSpecifiers = (check) => {
53
53
  }
54
54
  };
55
55
  };
56
+ var moduleExportName = (node) => node.type === "Literal" ? node.value : node.name;
57
+ var moduleMembers = (sourceCode, isModule, check) => {
58
+ const isNamespace = (node) => {
59
+ if (node?.type !== "Identifier") {
60
+ return false;
61
+ }
62
+ const variable = declaredVariable(sourceCode, node);
63
+ return variable !== null && variable.defs.some(({ node: definition }) => definition.type === "ImportNamespaceSpecifier" && definition.parent.type === "ImportDeclaration" && isModule(definition.parent.source.value));
64
+ };
65
+ return {
66
+ ExportNamedDeclaration: (node) => {
67
+ if (node.source !== null && isModule(node.source.value)) {
68
+ for (const specifier of node.specifiers) {
69
+ check(specifier, moduleExportName(specifier.local));
70
+ }
71
+ }
72
+ },
73
+ ImportDeclaration: (node) => {
74
+ if (isModule(node.source.value)) {
75
+ for (const specifier of node.specifiers) {
76
+ if (specifier.type === "ImportSpecifier") {
77
+ check(specifier, moduleExportName(specifier.imported));
78
+ }
79
+ }
80
+ }
81
+ },
82
+ MemberExpression: (node) => {
83
+ if (isNamespace(node.object)) {
84
+ check(node, staticPropertyName(node.property, node.computed));
85
+ }
86
+ },
87
+ VariableDeclarator: (node) => {
88
+ if (node.id.type === "ObjectPattern" && isNamespace(node.init)) {
89
+ for (const property of node.id.properties) {
90
+ if (property.type === "Property") {
91
+ check(property, staticPropertyName(property.key, property.computed));
92
+ }
93
+ }
94
+ }
95
+ }
96
+ };
97
+ };
56
98
 
57
99
  // src/rules/effect-actors/effect-actors.ts
58
100
  var SIDE_EFFECT_ACTORS = new Set([
@@ -62,11 +104,9 @@ var SIDE_EFFECT_ACTORS = new Set([
62
104
  "fromPromise"
63
105
  ]);
64
106
  var messages = {
65
- sideEffectActor: "`{{name}}` makes XState actor logic outside Effect. Make the actor with `fromEffect` from `@collective-intelligence/external-apps-client-sdk-react/effect`."
107
+ sideEffectActor: "`{{name}}` makes XState actor logic outside Effect. Make the actor with `fromEffect` from `@collective-intelligence/external-apps-client-sdk-react/effect` in a detached app, or from `@collective-intelligence/extensions-sdk-frontend-react/effect` in a Studio Widget."
66
108
  };
67
109
  var isXState = (source) => source === "xstate" || source.startsWith("xstate/");
68
- var nameOf = (node) => node.type === "Literal" ? node.value : node.name;
69
- var isXStateNamespace = (variable) => variable !== null && variable.defs.some(({ node }) => node.type === "ImportNamespaceSpecifier" && node.parent.type === "ImportDeclaration" && isXState(node.parent.source.value));
70
110
  var effectActors = {
71
111
  group: "effect-convention",
72
112
  rule: defineRule({
@@ -80,29 +120,7 @@ var effectActors = {
80
120
  });
81
121
  }
82
122
  };
83
- return {
84
- ExportNamedDeclaration: (node) => {
85
- if (node.source !== null && isXState(node.source.value)) {
86
- for (const specifier of node.specifiers) {
87
- check(specifier, nameOf(specifier.local));
88
- }
89
- }
90
- },
91
- ImportDeclaration: (node) => {
92
- if (isXState(node.source.value)) {
93
- for (const specifier of node.specifiers) {
94
- if (specifier.type === "ImportSpecifier") {
95
- check(specifier, nameOf(specifier.imported));
96
- }
97
- }
98
- }
99
- },
100
- MemberExpression: (node) => {
101
- if (node.object.type === "Identifier" && isXStateNamespace(declaredVariable(context.sourceCode, node.object))) {
102
- check(node, staticPropertyName(node.property, node.computed));
103
- }
104
- }
105
- };
123
+ return moduleMembers(context.sourceCode, isXState, check);
106
124
  },
107
125
  meta: {
108
126
  docs: {
@@ -189,9 +207,9 @@ var MOVED = new Map([
189
207
  ]
190
208
  ]);
191
209
  var messages2 = {
210
+ outsideEffect: "`{{specifier}}` imports an SDK Effect API from outside its `/effect` subpath. Import `{{replacement}}`.",
192
211
  removed: "`{{specifier}}` is removed after 0.2.0. Import `{{replacement}}`.",
193
- removedMoved: "`{{specifier}}` is removed after 0.2.0. Import {{names}} from `{{moved}}`, and each other name from `{{replacement}}`.",
194
- outsideEffect: "`{{specifier}}` imports an SDK Effect API from outside its `/effect` subpath. Import `{{replacement}}`."
212
+ removedMoved: "`{{specifier}}` is removed after 0.2.0. Import {{names}} from `{{moved}}`, and each other name from `{{replacement}}`."
195
213
  };
196
214
  var effectSubpathFor = (specifier) => {
197
215
  const parsed = parsePackageSpecifier(specifier);
@@ -243,8 +261,42 @@ var effectSubpath = {
243
261
  })
244
262
  };
245
263
 
246
- // src/rules/no-run-in-view/no-run-in-view.ts
264
+ // src/rules/effect-writes/effect-writes.ts
247
265
  import { defineRule as defineRule3 } from "@oxlint/plugins";
266
+ var messages3 = {
267
+ mutationHook: "`useMutation` writes outside Effect. Write through a `fromEffect` actor from `@collective-intelligence/external-apps-client-sdk-react/effect` in a detached app, or from `@collective-intelligence/extensions-sdk-frontend-react/effect` in a Studio Widget; refresh reads through the `QueryCache` of the same entrypoint."
268
+ };
269
+ var isTanStackQuery = (source) => source === "@tanstack/react-query";
270
+ var takesTanStackQuery = (statement) => (statement.type === "ImportDeclaration" || statement.type === "ExportNamedDeclaration") && statement.source !== null && isTanStackQuery(statement.source.value);
271
+ var effectWrites = {
272
+ group: "effect-convention",
273
+ rule: defineRule3({
274
+ create(context) {
275
+ const program = context.sourceCode.ast;
276
+ if (!program.body.some(takesTanStackQuery)) {
277
+ return {};
278
+ }
279
+ return moduleMembers(context.sourceCode, isTanStackQuery, (node, name) => {
280
+ if (name === "useMutation") {
281
+ context.report({
282
+ messageId: "mutationHook",
283
+ node
284
+ });
285
+ }
286
+ });
287
+ },
288
+ meta: {
289
+ docs: {
290
+ description: "Disallow TanStack Query `useMutation`; writes run in `fromEffect` actors."
291
+ },
292
+ messages: messages3,
293
+ type: "problem"
294
+ }
295
+ })
296
+ };
297
+
298
+ // src/rules/no-run-in-view/no-run-in-view.ts
299
+ import { defineRule as defineRule4 } from "@oxlint/plugins";
248
300
 
249
301
  // src/workspace/layout.ts
250
302
  import path2 from "node:path";
@@ -312,21 +364,21 @@ var layoutFile = (filename) => {
312
364
  const subpath = segments && segments.length > 1 ? subpathOfSegments(segments) : null;
313
365
  return owner && subpath ? { owner, subpath } : null;
314
366
  };
367
+ var JSX_FILE = /\.[jt]sx$/u;
368
+ var isViewModule = (filename) => JSX_FILE.test(filename) || layoutFile(filename)?.subpath === "views";
315
369
 
316
370
  // src/rules/no-run-in-view/no-run-in-view.ts
317
- var JSX_FILE = /\.[jt]sx$/u;
318
371
  var RUN_FUNCTION = /^run(?:Callback|Fork|Promise|PromiseExit|Sync|SyncExit)(?:With)?$/u;
319
372
  var FETCH_OBJECTS = ["globalThis", "window"];
320
373
  var isRunFunction = (name) => name !== null && RUN_FUNCTION.test(name);
321
374
  var isEffectModule = (source) => source === "effect" || source.startsWith("effect/") || source.startsWith("@effect/");
322
- var messages3 = {
375
+ var messages4 = {
323
376
  fetch: "A view module calls `fetch`. Read data with TanStack Query, or call the API in a `fromEffect` actor.",
324
377
  run: "A view module runs an Effect with `{{name}}`. Run the Effect in a `fromEffect` actor."
325
378
  };
326
- var isViewModule = (filename) => JSX_FILE.test(filename) || layoutFile(filename)?.subpath === "views";
327
379
  var noRunInView = {
328
380
  group: "effect-convention",
329
- rule: defineRule3({
381
+ rule: defineRule4({
330
382
  create(context) {
331
383
  if (!isViewModule(context.filename)) {
332
384
  return {};
@@ -384,19 +436,19 @@ var noRunInView = {
384
436
  docs: {
385
437
  description: "Disallow `fetch` calls and Effect run functions in view modules; side effects run in `fromEffect` actors."
386
438
  },
387
- messages: messages3,
439
+ messages: messages4,
388
440
  type: "problem"
389
441
  }
390
442
  })
391
443
  };
392
444
 
393
445
  // src/rules/package-entrypoint/package-entrypoint.ts
394
- import { defineRule as defineRule4 } from "@oxlint/plugins";
446
+ import { defineRule as defineRule5 } from "@oxlint/plugins";
395
447
  import path3 from "node:path";
396
448
  var packageName = (target) => target.name ?? path3.basename(target.root);
397
449
  var packageEntrypoint = {
398
450
  group: "package-boundaries",
399
- rule: defineRule4({
451
+ rule: defineRule5({
400
452
  create(context) {
401
453
  const directory = path3.dirname(context.filename);
402
454
  const owner = packageOf(directory);
@@ -444,11 +496,11 @@ var packageEntrypoint = {
444
496
  };
445
497
 
446
498
  // src/rules/subpath-entrypoint/subpath-entrypoint.ts
447
- import { defineRule as defineRule5 } from "@oxlint/plugins";
499
+ import { defineRule as defineRule6 } from "@oxlint/plugins";
448
500
  import path4 from "node:path";
449
501
  var subpathEntrypoint = {
450
502
  group: "solution-layout",
451
- rule: defineRule5({
503
+ rule: defineRule6({
452
504
  create(context) {
453
505
  const directory = path4.dirname(context.filename);
454
506
  const owner = packageOf(directory);
@@ -485,7 +537,7 @@ var subpathEntrypoint = {
485
537
  };
486
538
 
487
539
  // src/rules/subpath-imports/subpath-imports.ts
488
- import { defineRule as defineRule6 } from "@oxlint/plugins";
540
+ import { defineRule as defineRule7 } from "@oxlint/plugins";
489
541
  import path5 from "node:path";
490
542
  var FORBIDDEN_IMPORTS = {
491
543
  api: [],
@@ -497,7 +549,7 @@ var FORBIDDEN_IMPORTS = {
497
549
  };
498
550
  var subpathImports = {
499
551
  group: "solution-layout",
500
- rule: defineRule6({
552
+ rule: defineRule7({
501
553
  create(context) {
502
554
  const file = layoutFile(context.filename);
503
555
  if (file === null) {
@@ -542,13 +594,13 @@ var subpathImports = {
542
594
  };
543
595
 
544
596
  // src/rules/subpath-index/subpath-index.ts
545
- import { defineRule as defineRule7 } from "@oxlint/plugins";
597
+ import { defineRule as defineRule8 } from "@oxlint/plugins";
546
598
  import { existsSync as existsSync2 } from "node:fs";
547
599
  import path6 from "node:path";
548
600
  var INDEX_FILES = ["index.ts", "index.tsx"];
549
601
  var subpathIndex = {
550
602
  group: "solution-layout",
551
- rule: defineRule7({
603
+ rule: defineRule8({
552
604
  create(context) {
553
605
  const file = layoutFile(context.filename);
554
606
  if (file === null) {
@@ -584,6 +636,7 @@ var subpathIndex = {
584
636
  var rules = {
585
637
  "effect-actors": effectActors,
586
638
  "effect-subpath": effectSubpath,
639
+ "effect-writes": effectWrites,
587
640
  "no-run-in-view": noRunInView,
588
641
  "package-entrypoint": packageEntrypoint,
589
642
  "subpath-entrypoint": subpathEntrypoint,
package/dist/rule.d.ts CHANGED
@@ -7,3 +7,5 @@ export interface LintRule {
7
7
  export declare const staticPropertyName: (key: ESTree.PropertyKey, computed: boolean) => string | null;
8
8
  export declare const declaredVariable: (sourceCode: SourceCode, node: ESTree.IdentifierReference) => Variable | null;
9
9
  export declare const moduleSpecifiers: (check: (literal: ESTree.StringLiteral) => void) => Visitor;
10
+ export declare const moduleExportName: (node: ESTree.ModuleExportName) => string;
11
+ export declare const moduleMembers: (sourceCode: SourceCode, isModule: (source: string) => boolean, check: (node: ESTree.Node, name: string | null) => void) => Visitor;
@@ -0,0 +1,2 @@
1
+ import type { LintRule } from "../../rule.ts";
2
+ export declare const effectWrites: LintRule;
@@ -2,6 +2,7 @@ import type { LintRule } from "../rule.ts";
2
2
  export declare const rules: {
3
3
  readonly "effect-actors": LintRule;
4
4
  readonly "effect-subpath": LintRule;
5
+ readonly "effect-writes": LintRule;
5
6
  readonly "no-run-in-view": LintRule;
6
7
  readonly "package-entrypoint": LintRule;
7
8
  readonly "subpath-entrypoint": LintRule;
@@ -9,3 +9,4 @@ export interface LayoutFile {
9
9
  readonly subpath: Subpath;
10
10
  }
11
11
  export declare const layoutFile: (filename: string) => LayoutFile | null;
12
+ export declare const isViewModule: (filename: string) => boolean;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@collective-intelligence/lint",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "Oxlint plugin with the Collective Intelligence lint rules: package boundaries and solution package layout.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -48,5 +48,5 @@
48
48
  "typescript": "7.0.2",
49
49
  "ultracite": "7.10.7"
50
50
  },
51
- "gitHead": "51fdea833e25fe215b3cf0d70adf1984b8e0f81c"
51
+ "gitHead": "1718b80bc8d0ba696d78ac8f5f905c8dc46fe0c5"
52
52
  }
@@ -3,7 +3,7 @@ name: ci-solution-structure
3
3
  description: |
4
4
  Collective Intelligence (CI) solution turborepo structure: tiers, package shape and composition.
5
5
  Use when creating, moving, splitting or reviewing a solution workspace package, adding a package
6
- subpath, declaring CI resources, Capabilities, App Roles or Realtime Topics, or fixing
6
+ subpath, declaring CI resources, Access Capabilities, Access Profiles or Realtime Topics, or fixing
7
7
  `turbo boundaries` or `ci-solution/*` lint errors.
8
8
  ---
9
9
 
@@ -16,7 +16,7 @@ import may skip tiers:
16
16
  ```text
17
17
  apps/* composition roots: routes, app API, server root, deploy declaration
18
18
  ↓
19
- packages/organization/<name> CI identity: App Roles → Capabilities, groups, External Apps
19
+ packages/organization/<name> CI identity: Access Profiles, grants, groups, External Apps
20
20
  ↓
21
21
  packages/features/<name> one user-visible capability
22
22
  ↓
@@ -36,10 +36,11 @@ packages/tooling/<name> shared config and build tools; every tier imports
36
36
  - The app composes cross-domain needs: each package exports its view or headless part, and the app
37
37
  places the parts side by side.
38
38
  - Every cross-package import targets an exported subpath, such as `@acme/invoicing/views`.
39
- - Modules carry no product terms (domain nouns, product copy, App Role names, Capability keys):
39
+ - Modules carry no product terms (domain nouns, product copy, profile names, Capability codes):
40
40
  another product could use them unchanged.
41
- - Each package declares its own CI resources and Capabilities (CI App Permissions) in `./ci`. Only
42
- the organization package names App Roles and grants Capabilities to them.
41
+ - Each package declares its own CI resources, Access Capabilities and Knowledge Data Policies in
42
+ `./ci`. Only the organization package declares Access Profiles, their grants and the Max
43
+ Privileges of each External App.
43
44
  - `apps/extensions` is a pure composition root: `src/index.ts` passes the organization package and
44
45
  every package `./ci` to `declarePackage`.
45
46
  - The CI SDKs own the realtime transport. A package contributes only Realtime Topic definitions, in
@@ -53,8 +54,8 @@ packages/tooling/<name> shared config and build tools; every tier imports
53
54
  whether a new package is worth it, or compose a cross-domain need.
54
55
  - [Package shape](references/package-shape.md): read when you add or change a subpath, `exports`, a
55
56
  Capability or a Realtime Topic in a feature or entity package.
56
- - [Composition](references/composition.md): read when you change the organization package, App
57
- Roles, groups, External Apps or `apps/extensions`.
57
+ - [Composition](references/composition.md): read when you change the organization package, Access
58
+ Profiles, grants, groups, External Apps or `apps/extensions`.
58
59
  - [Enforcement](references/enforcement.md): read when you add a workspace, edit tier tags or the root
59
60
  boundaries table, configure `@collective-intelligence/lint`, or fix a `turbo boundaries` or
60
61
  `ci-solution/*` error.
@@ -76,11 +77,12 @@ packages/tooling/<name> shared config and build tools; every tier imports
76
77
  `exports` entry, `exports` has no other entry, and every cross-package import targets an entity,
77
78
  module or tooling package.
78
79
 
79
- 3. Read [Composition](references/composition.md). Declare the CI resources and Capability keys in
80
- `./ci` and the Realtime Topics in `./headless`. Grant the new Capabilities to App Roles in the
81
- organization package, and add the `./ci` components to `apps/extensions`.
80
+ 3. Read [Composition](references/composition.md). Declare the CI resources and Access Capabilities
81
+ in `./ci` and the Realtime Topics in `./headless`. Add the new Capabilities to Access Profiles
82
+ and to the Max Privileges of each External App that uses them in the organization package, and
83
+ add the `./ci` components to `apps/extensions`.
82
84
 
83
- **Complete when:** every new Capability is granted to at least one App Role or reported as
85
+ **Complete when:** every new Capability is held by at least one Access Profile or reported as
84
86
  intentionally unassigned, `apps/extensions/src/index.ts` and `apps/extensions/package.json`
85
87
  include the package, and the organization package `version` is bumped.
86
88
 
@@ -10,21 +10,33 @@ The solution deploys to CI as one Extension Package.
10
10
  declaration. The FQN is a constant, because it cannot be a Package Variable;
11
11
  - the Package Variables: origins and callback URLs, never credentials;
12
12
  - the Organization settings;
13
- - the App Roles: each App Role lists its Capabilities (`appPermissions`) and its platform permissions
14
- (`platformPermissions`, for example `knowledge:read` and `knowledge:write`);
15
- - one Organization Group per App Role, bound to the App Role with a group binding;
16
- - one External App per frontend (`declareExternalApplication`), which carries the App Roles and group
17
- bindings.
13
+ - the Access Profiles (`declareAccessProfile`): each profile allows core capabilities, for example
14
+ `coreCapabilities.platform.knowledge`, and the capabilities of the feature and entity packages;
15
+ - one Organization Group per user profile, with a declared grant of the profile to the Group
16
+ (`declareAccessProfileGrant`);
17
+ - one External App per frontend (`declareExternalApplication`), with a `server` profile granted to
18
+ its server, an `anonymous` profile granted to its visitors when it has any, and its Max Privileges
19
+ (`declareAccessMaxPrivileges`). Without Max Privileges the app's user tokens read nothing.
18
20
 
19
- It imports the Capability keys from each feature and entity `./ci` and checks each grant against them:
21
+ It imports the capability handles from each feature and entity `./ci`, so a profile names only
22
+ declared capabilities:
20
23
 
21
24
  ```ts
22
- import type { InvoicingCapability } from "@acme/invoicing/ci"
25
+ import {
26
+ access,
27
+ declareAccessProfile
28
+ } from "@collective-intelligence/extensions-sdk"
29
+ import { invoicing } from "@acme/invoicing/ci"
23
30
 
24
- const accountantCapabilities = [
25
- "invoicing:read",
26
- "invoicing:write"
27
- ] as const satisfies readonly InvoicingCapability[]
31
+ export const accountant = declareAccessProfile({
32
+ definition: {
33
+ audience: "user",
34
+ capabilities: [access.allow(invoicing.invoices, "manage")],
35
+ lifecycle: { deployMode: "upsert", readonly: true }
36
+ },
37
+ manifest: { fqn: "acme.organization.profiles.accountant", version: "1.0.0" },
38
+ presentation: { displayName: "Accountant" }
39
+ })
28
40
  ```
29
41
 
30
42
  It exports what the deploy declaration needs, for example `packageManifest`, `variables` and
@@ -92,6 +92,7 @@ XState machines and out of views:
92
92
  | `ci-solution/effect-subpath` | An SDK Effect API comes from `<sdk>/effect`; removed SDK paths are errors. |
93
93
  | `ci-solution/no-run-in-view` | A view module (`.tsx`, `.jsx`, `views/`) calls no `fetch` and runs no Effect. |
94
94
  | `ci-solution/effect-actors` | XState side-effect actors are `fromEffect`, not `fromPromise` or `fromCallback`. |
95
+ | `ci-solution/effect-writes` | No module takes TanStack Query `useMutation`; writes are `fromEffect` actors. |
95
96
 
96
97
  `package-entrypoint` finds each package through `node_modules`, so the package manager must link the
97
98
  workspace packages. The package documentation is the authority for rule options.
@@ -34,14 +34,14 @@ packages/features/invoicing/ @acme/invoicing
34
34
 
35
35
  ## Subpaths
36
36
 
37
- | Subpath | Holds | Consumers |
38
- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
39
- | `ci/` | Config-as-code CI resources declared with `@collective-intelligence/extensions-sdk` (`declareKnowledgeEntitySchema`, `declareKnowledgePolicy` and others), and the Capability keys. | organization package, `apps/extensions` |
40
- | `domain/` | Effect Schema models, branded ids, pure rules, domain errors. No runtime concerns. | every other subpath, other packages |
41
- | `api/` | The Effect `HttpApiGroup` contract: endpoints with payload, success and error schemas from `domain/`. | the app API, the typed client in `views/` |
42
- | `server/` | The handlers of the `api/` group and the Layer that provides them. Calls CI as the signed-in user. | the app server root only |
43
- | `headless/` | UI state without rendering: actors (UI state only; server data stays in queries), hooks, query keys, search sources, Realtime Topic definitions. | `views/`, the app |
44
- | `views/` | Wired screens and widgets built on the shared UI package, reading data through the typed client and TanStack Query. | the app |
37
+ | Subpath | Holds | Consumers |
38
+ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
39
+ | `ci/` | Config-as-code CI resources declared with `@collective-intelligence/extensions-sdk` (`declareKnowledgeEntitySchema`, `declareAccessCapabilities`, `declareAccessKnowledgeDataPolicy` and others). | organization package, `apps/extensions` |
40
+ | `domain/` | Effect Schema models, branded ids, pure rules, domain errors. No runtime concerns. | every other subpath, other packages |
41
+ | `api/` | The Effect `HttpApiGroup` contract: endpoints with payload, success and error schemas from `domain/`. | the app API, the typed client in `views/` |
42
+ | `server/` | The handlers of the `api/` group and the Layer that provides them. Calls CI as the signed-in user. | the app server root only |
43
+ | `headless/` | UI state without rendering: actors (UI state only; server data stays in queries), hooks, query keys, search sources, Realtime Topic definitions. | `views/`, the app |
44
+ | `views/` | Wired screens and widgets built on the shared UI package, reading data through the typed client and TanStack Query. | the app |
45
45
 
46
46
  `ci/` ships in the deploy bundle (see [Composition](composition.md)), so it holds declarations only:
47
47
  the extensions SDK and constants from `domain/`.
@@ -65,19 +65,22 @@ free.
65
65
 
66
66
  ## Capabilities
67
67
 
68
- A package defines its Capability keys in `ci/` as an `as const` list and exports the key type:
68
+ A package declares its Access Capabilities in `ci/` and exports the handle:
69
69
 
70
70
  ```ts
71
- export const invoicingCapabilities = [
72
- "invoicing:read",
73
- "invoicing:write",
74
- "invoicing:approve"
75
- ] as const
76
-
77
- export type InvoicingCapability = (typeof invoicingCapabilities)[number]
71
+ import { declareAccessCapabilities } from "@collective-intelligence/extensions-sdk"
72
+
73
+ export const invoicing = declareAccessCapabilities({
74
+ definition: {
75
+ lifecycle: { deployMode: "upsert", readonly: true },
76
+ nodes: { approvals: { kind: "switch" }, invoices: { kind: "readManage" } }
77
+ },
78
+ manifest: { fqn: "acme.invoicing", version: "1.0.0" }
79
+ })
78
80
  ```
79
81
 
80
- `server/` handlers and `views/` controls gate on these keys through the access module package.
82
+ `server/` handlers and `views/` controls gate on these capabilities; Knowledge Data Policies in
83
+ `ci/` name them as the capability that opens a schema.
81
84
 
82
85
  ## Realtime Topics
83
86