@collective-intelligence/lint 0.1.23 → 0.1.24
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 +7 -0
- package/package.json +4 -3
- package/skills/ci-solution-structure/SKILL.md +117 -0
- package/skills/ci-solution-structure/references/composition.md +63 -0
- package/skills/ci-solution-structure/references/enforcement.md +80 -0
- package/skills/ci-solution-structure/references/package-shape.md +105 -0
- package/skills/ci-solution-structure/references/tiers.md +55 -0
package/README.md
CHANGED
|
@@ -64,6 +64,13 @@ A JSON config works the same way:
|
|
|
64
64
|
|
|
65
65
|
The `RuleName` type lists every rule name.
|
|
66
66
|
|
|
67
|
+
## Agent skill
|
|
68
|
+
|
|
69
|
+
The package ships the agent skill `ci-solution-structure` at
|
|
70
|
+
`skills/ci-solution-structure/SKILL.md`. In a Harness Intelligence repository,
|
|
71
|
+
the `collective-intelligence` pack installs the skill and adds the plugin with
|
|
72
|
+
`ci-solution/package-entrypoint` to the managed lint config.
|
|
73
|
+
|
|
67
74
|
## Rules
|
|
68
75
|
|
|
69
76
|
| Rule | Enforces | Group |
|
package/package.json
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@collective-intelligence/lint",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.24",
|
|
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,
|
|
7
7
|
"files": [
|
|
8
8
|
"dist",
|
|
9
|
-
"README.md"
|
|
9
|
+
"README.md",
|
|
10
|
+
"skills"
|
|
10
11
|
],
|
|
11
12
|
"main": "./dist/index.js",
|
|
12
13
|
"types": "./dist/index.d.ts",
|
|
@@ -47,5 +48,5 @@
|
|
|
47
48
|
"typescript": "7.0.2",
|
|
48
49
|
"ultracite": "7.10.7"
|
|
49
50
|
},
|
|
50
|
-
"gitHead": "
|
|
51
|
+
"gitHead": "d34b4b06bb1d6cc9cfb4594b57675729177c2707"
|
|
51
52
|
}
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ci-solution-structure
|
|
3
|
+
description: |
|
|
4
|
+
Collective Intelligence (CI) solution turborepo structure: tiers, package shape and composition.
|
|
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
|
|
7
|
+
`turbo boundaries` or `ci-solution/*` lint errors.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# CI Solution Structure
|
|
11
|
+
|
|
12
|
+
A CI solution is a turborepo. Each workspace package lives at `packages/<tier>/<name>` and has
|
|
13
|
+
exactly one tier. Imports follow the Stable Dependencies Principle and point down the arrows; an
|
|
14
|
+
import may skip tiers:
|
|
15
|
+
|
|
16
|
+
```text
|
|
17
|
+
apps/* composition roots: routes, app API, server root, deploy declaration
|
|
18
|
+
↓
|
|
19
|
+
packages/organization/<name> CI identity: App Roles → Capabilities, groups, External Apps
|
|
20
|
+
↓
|
|
21
|
+
packages/features/<name> one user-visible capability
|
|
22
|
+
↓
|
|
23
|
+
packages/modules/<name> a domain capability that several features need
|
|
24
|
+
↓
|
|
25
|
+
packages/foundation/<name> generic machinery
|
|
26
|
+
|
|
27
|
+
packages/tooling/<name> shared config and build tools; every tier imports it
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Invariants
|
|
31
|
+
|
|
32
|
+
- Package names are flat: `packages/features/invoicing` is `@acme/invoicing`. Only the folder shows
|
|
33
|
+
the tier.
|
|
34
|
+
- Inside one tier, only foundation and tooling packages import each other. A feature reaches another
|
|
35
|
+
feature only through the app.
|
|
36
|
+
- The app composes cross-domain needs: each package exports its view or headless part, and the app
|
|
37
|
+
places the parts side by side.
|
|
38
|
+
- Every cross-package import targets an exported subpath, such as `@acme/invoicing/views`.
|
|
39
|
+
- Foundation carries no product terms (domain nouns, product copy, App Role names, Capability keys):
|
|
40
|
+
another product could use it 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.
|
|
43
|
+
- `apps/extensions` is a pure composition root: `src/index.ts` passes the organization package and
|
|
44
|
+
every package `./ci` to `declarePackage`.
|
|
45
|
+
- The CI SDKs own the realtime transport. A package contributes only Realtime Topic definitions, in
|
|
46
|
+
`./headless`.
|
|
47
|
+
- Every workspace has a `turbo.json` with exactly one `tier:*` tag; `turbo boundaries` checks only
|
|
48
|
+
tagged workspaces.
|
|
49
|
+
|
|
50
|
+
## References
|
|
51
|
+
|
|
52
|
+
- [Tiers](references/tiers.md): read when you choose the tier for new, moved or split code, decide
|
|
53
|
+
whether a new package is worth it, or compose a cross-domain need.
|
|
54
|
+
- [Package shape](references/package-shape.md): read when you add or change a subpath, `exports`, a
|
|
55
|
+
Capability or a Realtime Topic in a feature or module package.
|
|
56
|
+
- [Composition](references/composition.md): read when you change the organization package, App
|
|
57
|
+
Roles, groups, External Apps or `apps/extensions`.
|
|
58
|
+
- [Enforcement](references/enforcement.md): read when you add a workspace, edit tier tags or the root
|
|
59
|
+
boundaries table, configure `@collective-intelligence/lint`, or fix a `turbo boundaries` or
|
|
60
|
+
`ci-solution/*` error.
|
|
61
|
+
|
|
62
|
+
## Workflow: add a feature package
|
|
63
|
+
|
|
64
|
+
1. Read [Tiers](references/tiers.md). Scan the sibling packages in `features/` and `modules/`, and
|
|
65
|
+
classify the behavior by invariant owner and domain-worthiness.
|
|
66
|
+
|
|
67
|
+
**Complete when:** you name the invariant owner, every sibling you compared, and the real
|
|
68
|
+
boundary that makes a new feature package correct. When the owner is an existing package or a
|
|
69
|
+
module, apply steps 2 to 5 to that package instead.
|
|
70
|
+
|
|
71
|
+
2. Read [Package shape](references/package-shape.md). Create `packages/features/<name>` with only the
|
|
72
|
+
subpaths the feature needs, one `exports` entry per subpath, and a `turbo.json` tagged
|
|
73
|
+
`tier:features`.
|
|
74
|
+
|
|
75
|
+
**Complete when:** every folder under `src/` has an `index.ts` or `index.tsx` and exactly one
|
|
76
|
+
`exports` entry, `exports` has no other entry, and every cross-package import targets a module,
|
|
77
|
+
foundation or tooling package.
|
|
78
|
+
|
|
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`.
|
|
82
|
+
|
|
83
|
+
**Complete when:** every new Capability is granted to at least one App Role or reported as
|
|
84
|
+
intentionally unassigned, `apps/extensions/src/index.ts` and `apps/extensions/package.json`
|
|
85
|
+
include the package, and the organization package `version` is bumped.
|
|
86
|
+
|
|
87
|
+
4. Compose the package in each app that uses it: the `./api` group into the app API, the `./server`
|
|
88
|
+
Layer into the server root, the `./views` exports into routes or pages.
|
|
89
|
+
|
|
90
|
+
**Complete when:** each app wires every subpath it needs, through exported subpaths only.
|
|
91
|
+
|
|
92
|
+
5. Run `turbo boundaries` and the repository lint, type-check and test scripts.
|
|
93
|
+
|
|
94
|
+
**Complete when:** every command passes, or each failure that predates the change is reported
|
|
95
|
+
with its file, line and rule.
|
|
96
|
+
|
|
97
|
+
## Workflow: review a package change
|
|
98
|
+
|
|
99
|
+
1. List every changed workspace and file. Map each workspace to its tier and each file to its
|
|
100
|
+
subpath or to package configuration.
|
|
101
|
+
|
|
102
|
+
**Complete when:** every changed file has exactly one tier and one subpath or configuration role.
|
|
103
|
+
|
|
104
|
+
2. Classify every added or changed import against the tier direction, the
|
|
105
|
+
[subpath direction](references/package-shape.md#subpath-direction) and the exported subpaths.
|
|
106
|
+
|
|
107
|
+
**Complete when:** every import in scope is marked allowed or violation, with file and line.
|
|
108
|
+
|
|
109
|
+
3. Check the change against every [invariant](#invariants).
|
|
110
|
+
|
|
111
|
+
**Complete when:** each invariant has a pass, fail or not-applicable result with current
|
|
112
|
+
evidence.
|
|
113
|
+
|
|
114
|
+
4. Run `turbo boundaries` and the lint on the changed workspaces.
|
|
115
|
+
|
|
116
|
+
**Complete when:** every violation from steps 2 to 4 cites file, line and the violated rule, and
|
|
117
|
+
names the tier, package or subpath that resolves it.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Organization Package and `apps/extensions`
|
|
2
|
+
|
|
3
|
+
The solution deploys to CI as one Extension Package.
|
|
4
|
+
|
|
5
|
+
## Organization package
|
|
6
|
+
|
|
7
|
+
`packages/organization/<name>` (tag `tier:organization`) owns:
|
|
8
|
+
|
|
9
|
+
- the package identity: FQN, display name and `version`. Bump `version` by hand on every change of a
|
|
10
|
+
declaration. The FQN is a constant, because it cannot be a Package Variable;
|
|
11
|
+
- the Package Variables: origins and callback URLs, never credentials;
|
|
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.
|
|
18
|
+
|
|
19
|
+
It imports the Capability keys from each feature and module `./ci` and checks each grant against them:
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import type { InvoicingCapability } from "@acme/invoicing/ci"
|
|
23
|
+
|
|
24
|
+
const accountantCapabilities = [
|
|
25
|
+
"invoicing:read",
|
|
26
|
+
"invoicing:write"
|
|
27
|
+
] as const satisfies readonly InvoicingCapability[]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
It exports what the deploy declaration needs, for example `packageManifest`, `variables` and
|
|
31
|
+
`organizationComponents` (the components in deploy order).
|
|
32
|
+
|
|
33
|
+
## `apps/extensions`
|
|
34
|
+
|
|
35
|
+
`apps/extensions/src` holds only `index.ts` and the media files it deploys:
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import { declarePackage } from "@collective-intelligence/extensions-sdk"
|
|
39
|
+
import { customerComponents } from "@acme/customer/ci"
|
|
40
|
+
import { invoicingComponents } from "@acme/invoicing/ci"
|
|
41
|
+
import {
|
|
42
|
+
organizationComponents,
|
|
43
|
+
packageManifest,
|
|
44
|
+
variables
|
|
45
|
+
} from "@acme/organization"
|
|
46
|
+
|
|
47
|
+
export default declarePackage({
|
|
48
|
+
components: [
|
|
49
|
+
...organizationComponents,
|
|
50
|
+
...customerComponents,
|
|
51
|
+
...invoicingComponents
|
|
52
|
+
],
|
|
53
|
+
manifest: packageManifest,
|
|
54
|
+
variables
|
|
55
|
+
})
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
- `apps/extensions/package.json` lists the organization package and every imported package as
|
|
59
|
+
`workspace:*` dependencies.
|
|
60
|
+
- `ci deploy --declaration ./src/index.ts` bundles every workspace import into the release asset; only
|
|
61
|
+
the SDK host modules stay external. Code that `./ci` pulls in ships in that asset.
|
|
62
|
+
- Package Media paths such as `media/logo.png` resolve next to the declaration module, so media files
|
|
63
|
+
stay in `apps/extensions/src/media`.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Enforcement
|
|
2
|
+
|
|
3
|
+
`turbo boundaries` checks the direction between packages. `@collective-intelligence/lint` checks the
|
|
4
|
+
folders and imports inside and into a package.
|
|
5
|
+
|
|
6
|
+
## `turbo boundaries`
|
|
7
|
+
|
|
8
|
+
The root `package.json` workspace globs `["apps/*", "packages/*/*"]` make every tier folder entry a
|
|
9
|
+
workspace. Each workspace `turbo.json` extends the root and carries exactly one tier tag (`tier:app`
|
|
10
|
+
for `apps/*`):
|
|
11
|
+
|
|
12
|
+
```json
|
|
13
|
+
{ "extends": ["//"], "tags": ["tier:features"] }
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The root `turbo.json` `boundaries.tags` table encodes the tier diagram in [SKILL.md](../SKILL.md):
|
|
17
|
+
each tier tag allows every tier below it and `tier:tooling`; `tier:foundation` and `tier:tooling`
|
|
18
|
+
also allow themselves.
|
|
19
|
+
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"boundaries": {
|
|
23
|
+
"implicitDependencies": ["server-only"],
|
|
24
|
+
"tags": {
|
|
25
|
+
"tier:features": {
|
|
26
|
+
"dependencies": {
|
|
27
|
+
"allow": ["tier:modules", "tier:foundation", "tier:tooling"]
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
- `implicitDependencies: ["server-only"]`: server code imports the `server-only` marker module that
|
|
36
|
+
the framework supplies, without a `package.json` entry. Without this line `turbo boundaries` reports
|
|
37
|
+
it as an undeclared dependency.
|
|
38
|
+
- `turbo boundaries` also reports an import of a file outside the package directory and an import of
|
|
39
|
+
a package that `package.json` does not declare.
|
|
40
|
+
- An untagged workspace has no rule, so `turbo boundaries` never checks its imports. Close the gap
|
|
41
|
+
with two repository tests: one reads the root workspace globs and fails unless every workspace has
|
|
42
|
+
a `turbo.json` that extends `//` and carries exactly one known tier tag; one runs
|
|
43
|
+
`turbo boundaries` on a throwaway fixture workspace with the real root table and expects a failure
|
|
44
|
+
for feature → feature and module → feature.
|
|
45
|
+
- Run `turbo boundaries` in the repository `check` script.
|
|
46
|
+
|
|
47
|
+
Read the error `` Package `@acme/a` found without any tag listed in allowlist for `@acme/b` `` as:
|
|
48
|
+
`@acme/b` imports `@acme/a` against the direction. Move the shared part down a tier, or compose both
|
|
49
|
+
packages in the app (see [Tiers](tiers.md#cross-domain-composition)).
|
|
50
|
+
|
|
51
|
+
## `@collective-intelligence/lint`
|
|
52
|
+
|
|
53
|
+
An oxlint plugin. Install it with `oxlint` as dev dependencies, and extend the `recommended` config
|
|
54
|
+
in each lint scope's `oxlint.config.ts`:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
import { recommended } from "@collective-intelligence/lint"
|
|
58
|
+
import { defineConfig } from "oxlint"
|
|
59
|
+
|
|
60
|
+
export default defineConfig({ extends: [recommended] })
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
In a repository that Harness Intelligence manages, the `collective-intelligence` pack adds the plugin
|
|
64
|
+
and `ci-solution/package-entrypoint` to the managed lint config of every scope, so apps need no
|
|
65
|
+
plugin setup. Each solution package (`packages/<tier>/<name>`) still extends `recommended` in its
|
|
66
|
+
`oxlint.local.ts` for the three solution-layout rules. Outside Harness Intelligence, extend
|
|
67
|
+
`recommended` as shown.
|
|
68
|
+
|
|
69
|
+
`recommended` enables every rule as an error. Each rule enforces one part of the
|
|
70
|
+
[package shape](package-shape.md):
|
|
71
|
+
|
|
72
|
+
| Rule | Enforces |
|
|
73
|
+
| -------------------------------- | ---------------------------------------------------------------------- |
|
|
74
|
+
| `ci-solution/package-entrypoint` | Cross-package imports target an exported subpath. |
|
|
75
|
+
| `ci-solution/subpath-imports` | The [subpath direction](package-shape.md#subpath-direction). |
|
|
76
|
+
| `ci-solution/subpath-entrypoint` | An import into another subpath targets the folder or its `index` file. |
|
|
77
|
+
| `ci-solution/subpath-index` | Every subpath folder under `src/` has an `index.ts` or `index.tsx`. |
|
|
78
|
+
|
|
79
|
+
`package-entrypoint` finds each package through `node_modules`, so the package manager must link the
|
|
80
|
+
workspace packages. The package documentation is the authority for rule options.
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Package Shape
|
|
2
|
+
|
|
3
|
+
Feature and module packages share one shape. Each subpath is a folder under `src/` with one
|
|
4
|
+
`index.ts` or `index.tsx` entrypoint and one `package.json` `exports` entry. Create only the
|
|
5
|
+
subpaths the package needs.
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
packages/features/invoicing/ @acme/invoicing
|
|
9
|
+
├── package.json
|
|
10
|
+
├── turbo.json tier:features
|
|
11
|
+
└── src/
|
|
12
|
+
├── ci/index.ts
|
|
13
|
+
├── domain/index.ts
|
|
14
|
+
├── api/index.ts
|
|
15
|
+
├── server/index.ts
|
|
16
|
+
├── headless/index.ts
|
|
17
|
+
└── views/index.ts
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"exports": {
|
|
23
|
+
"./ci": "./src/ci/index.ts",
|
|
24
|
+
"./domain": "./src/domain/index.ts",
|
|
25
|
+
"./api": "./src/api/index.ts",
|
|
26
|
+
"./server": "./src/server/index.ts",
|
|
27
|
+
"./headless": "./src/headless/index.ts",
|
|
28
|
+
"./views": "./src/views/index.ts"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`exports` lists only subpaths, with no root `.` entry.
|
|
34
|
+
|
|
35
|
+
## Subpaths
|
|
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 foundation ui package, reading data through the typed client and TanStack Query. | the app |
|
|
45
|
+
|
|
46
|
+
`ci/` ships in the deploy bundle (see [Composition](composition.md)), so it holds declarations only:
|
|
47
|
+
the extensions SDK and constants from `domain/`.
|
|
48
|
+
|
|
49
|
+
When the repository installs `effect-backend-structure` and `frontend-domain-structure`, they own the
|
|
50
|
+
inside of `server/` and `views/`; this skill owns the package boundary around them.
|
|
51
|
+
|
|
52
|
+
## Subpath direction
|
|
53
|
+
|
|
54
|
+
| Folder | Must not import |
|
|
55
|
+
| ----------- | --------------------------------------- |
|
|
56
|
+
| `domain/` | `server/`, `views/`, `headless/`, `ci/` |
|
|
57
|
+
| `ci/` | `views/`, `headless/` |
|
|
58
|
+
| `headless/` | `server/` |
|
|
59
|
+
| `views/` | `server/` |
|
|
60
|
+
| `api/` | no limit |
|
|
61
|
+
| `server/` | no limit |
|
|
62
|
+
|
|
63
|
+
An import into another subpath targets its folder or its `index` file. Imports inside one subpath are
|
|
64
|
+
free.
|
|
65
|
+
|
|
66
|
+
## Capabilities
|
|
67
|
+
|
|
68
|
+
A package defines its Capability keys in `ci/` as an `as const` list and exports the key type:
|
|
69
|
+
|
|
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]
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`server/` handlers and `views/` controls gate on these keys through the foundation access package.
|
|
81
|
+
|
|
82
|
+
## Realtime Topics
|
|
83
|
+
|
|
84
|
+
The CI SDKs own the transport:
|
|
85
|
+
|
|
86
|
+
- `@collective-intelligence/external-apps-client-sdk`: `createRealtimeClient`, the topic registry and
|
|
87
|
+
the stream lifecycle.
|
|
88
|
+
- `@collective-intelligence/external-apps-client-sdk-react`: `RealtimeProvider` and
|
|
89
|
+
`useRealtimeTopic(topic, onChanges)`.
|
|
90
|
+
- `@collective-intelligence/external-apps-server-sdk`: the `realtime` option of the BFF handlers
|
|
91
|
+
mounts the ticket route `POST {basePath}/realtime/ticket`.
|
|
92
|
+
|
|
93
|
+
The app mounts `RealtimeProvider` and the ticket route once. A package defines its topics in
|
|
94
|
+
`headless/`. A topic names one CI entity schema and an optional equality filter on one data path:
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
export const invoicesOfCustomer = (customerId: string) => ({
|
|
98
|
+
schema: "acme.invoicing.invoice",
|
|
99
|
+
filter: { field: "customer", eq: customerId }
|
|
100
|
+
})
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
A widget registers the topic with `useRealtimeTopic`. Events carry ids only, so `onChanges`
|
|
104
|
+
invalidates the widget queries and the data reloads through the package `api/`. The client
|
|
105
|
+
delivers the changes of a tab in one jittered batch, so a burst of changes refetches once.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Tiers
|
|
2
|
+
|
|
3
|
+
## Choosing a tier
|
|
4
|
+
|
|
5
|
+
Start with the **invariant owner**: the smallest stable domain responsible for the behavior, its
|
|
6
|
+
rules, and the changes that must stay coherent. A route name, a screen region, a file type or a reuse
|
|
7
|
+
count alone does not establish ownership.
|
|
8
|
+
|
|
9
|
+
Classify in this order; the first match owns the code:
|
|
10
|
+
|
|
11
|
+
1. Generic machinery with no product terms → `foundation`: the Effect runtime bridge, sign-in and
|
|
12
|
+
access checks, actor and slot state, form lifecycle, env validation, the shared ui kit
|
|
13
|
+
(primitives, shadcn components, theme).
|
|
14
|
+
2. Shared TypeScript, lint or build configuration → `tooling`.
|
|
15
|
+
3. Solution-wide CI identity → `organization`: package identity, Package Variables, Organization
|
|
16
|
+
settings, App Roles and their Capability grants, groups, External Apps. See
|
|
17
|
+
[Composition](composition.md).
|
|
18
|
+
4. A domain capability that two or more features need, with its own CI resources, data and views
|
|
19
|
+
(for example customer membership and a customer selector) → `modules`.
|
|
20
|
+
5. One user-visible capability with its workflow, policy, state, data, CI resources and screens →
|
|
21
|
+
`features`.
|
|
22
|
+
6. Routes, layouts, the app API, the server root, and the wiring of several packages for one surface
|
|
23
|
+
(a page, a home dashboard, a global search) → the app.
|
|
24
|
+
|
|
25
|
+
A detail with no independent invariant stays with its current owner. Prefer the narrowest honest
|
|
26
|
+
owner; move code to a broader owner only when that owner truly governs it.
|
|
27
|
+
|
|
28
|
+
When foundation code needs a product type, such as the Capability key union, make it generic over
|
|
29
|
+
that type. The app binds the type from the organization package.
|
|
30
|
+
|
|
31
|
+
## Domain-worthiness
|
|
32
|
+
|
|
33
|
+
Before you create or split a package, **scan the siblings** in the target tier. Compare invariant
|
|
34
|
+
owner, product language, workflow, change cadence and consumers. Extend or rename an existing package
|
|
35
|
+
when it already covers the responsibility.
|
|
36
|
+
|
|
37
|
+
A new package is worthy when it has a coherent responsibility, a stable name and at least one real
|
|
38
|
+
boundary: independent policy, lifecycle, state, workflow, CI resources, a consumer contract or reuse
|
|
39
|
+
scope. File count is no boundary. Reject a navigational split, such as one package per panel, button
|
|
40
|
+
or page fragment.
|
|
41
|
+
|
|
42
|
+
A supporting concept (comments, attachments, tags) stays inside its first feature. It becomes a
|
|
43
|
+
module when a second feature needs it.
|
|
44
|
+
|
|
45
|
+
## Cross-domain composition
|
|
46
|
+
|
|
47
|
+
When one surface needs parts of two packages, each package exports its part and the app composes
|
|
48
|
+
them:
|
|
49
|
+
|
|
50
|
+
- A home page shows an invoice summary: `@acme/invoicing/views` exports `InvoiceSummaryBox`; the app
|
|
51
|
+
places it on the home page.
|
|
52
|
+
- A global search lists invoices: `@acme/invoicing/headless` exports `invoiceSearchSource`; the app
|
|
53
|
+
registers it with the search.
|
|
54
|
+
- A module needs feature behavior: the module exposes a prop, slot or callback, and the app passes the
|
|
55
|
+
feature part in. When several features need the same behavior, move it down into the module.
|