@camstack/develop 0.0.0-stage → 0.1.1
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/dist/catalogue/addons.d.ts +10 -0
- package/dist/catalogue/addons.d.ts.map +1 -0
- package/dist/catalogue/addons.js +132 -0
- package/dist/catalogue/capabilities.d.ts +9 -0
- package/dist/catalogue/capabilities.d.ts.map +1 -0
- package/dist/catalogue/capabilities.js +46 -0
- package/dist/examples/catalogue.d.ts +7 -0
- package/dist/examples/catalogue.d.ts.map +1 -0
- package/dist/examples/catalogue.js +97 -0
- package/dist/examples/find.d.ts +7 -0
- package/dist/examples/find.d.ts.map +1 -0
- package/dist/examples/find.js +72 -0
- package/dist/index.d.ts +15 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +13 -0
- package/dist/naming.d.ts +6 -0
- package/dist/naming.d.ts.map +1 -0
- package/dist/naming.js +31 -0
- package/dist/scaffold/addon.d.ts +8 -0
- package/dist/scaffold/addon.d.ts.map +1 -0
- package/dist/scaffold/addon.js +241 -0
- package/dist/scaffold/cap-stub.d.ts +8 -0
- package/dist/scaffold/cap-stub.d.ts.map +1 -0
- package/dist/scaffold/cap-stub.js +69 -0
- package/dist/scaffold/extend.d.ts +8 -0
- package/dist/scaffold/extend.d.ts.map +1 -0
- package/dist/scaffold/extend.js +163 -0
- package/dist/scaffold/templates.d.ts +2 -0
- package/dist/scaffold/templates.d.ts.map +1 -0
- package/dist/scaffold/templates.js +9 -0
- package/dist/skills.d.ts +8 -0
- package/dist/skills.d.ts.map +1 -0
- package/dist/skills.js +39 -0
- package/dist/types.d.ts +109 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/dist/validate/addon.d.ts +8 -0
- package/dist/validate/addon.d.ts.map +1 -0
- package/dist/validate/addon.js +119 -0
- package/dist/validate/entries.d.ts +8 -0
- package/dist/validate/entries.d.ts.map +1 -0
- package/dist/validate/entries.js +110 -0
- package/dist/workspace.d.ts +11 -0
- package/dist/workspace.d.ts.map +1 -0
- package/dist/workspace.js +65 -0
- package/package.json +42 -4
- package/skills/README.md +45 -0
- package/skills/add-addon.md +126 -0
- package/skills/add-capability.md +89 -0
- package/skills/architecture.md +79 -0
- package/skills/sync-docs.md +59 -0
- package/README.md +0 -3
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: architecture
|
|
3
|
+
description: Architecture pointers for CamStack plugin authors — process model, capabilities, media, deploy.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Architecture for plugin authors
|
|
7
|
+
|
|
8
|
+
Deep dives live in the **camstack-server** repository under `docs/architecture/`.
|
|
9
|
+
Start with `docs/architecture/overview.md`. Facts that change often are in
|
|
10
|
+
generated `docs/reference/*` — do not copy them into skills.
|
|
11
|
+
|
|
12
|
+
## Kernel and addons
|
|
13
|
+
|
|
14
|
+
- Kernel owns processes, transport, registries.
|
|
15
|
+
- Features are addons. Cross-addon calls only via typed capabilities (`ctx.api`).
|
|
16
|
+
- Addons never import each other.
|
|
17
|
+
|
|
18
|
+
## Process model
|
|
19
|
+
|
|
20
|
+
- Default: **one addon = one process**.
|
|
21
|
+
- Co-locate only via `execution.group`, and only for allowed non-live cases —
|
|
22
|
+
never device providers or frame-rate data planes just to save RAM.
|
|
23
|
+
- Lifecycle = respawn a runner. No in-process hot-reload of business logic.
|
|
24
|
+
|
|
25
|
+
## Capabilities
|
|
26
|
+
|
|
27
|
+
- Declared by **name** in the addon manifest.
|
|
28
|
+
- Behavioural metadata only in `*.cap.ts`.
|
|
29
|
+
- After any cap change: `npm run codegen`.
|
|
30
|
+
- Registration is one atomic `registerNode` RPC — no shadow registries / wait
|
|
31
|
+
loops.
|
|
32
|
+
|
|
33
|
+
## Bytes and frames
|
|
34
|
+
|
|
35
|
+
- Cross-addon bytes: `ctx.peerBytes` (tickets), not base64 cap fields, not
|
|
36
|
+
private HTTP servers.
|
|
37
|
+
- Frames do not cross process boundaries at frame-rate; fetch compressed /
|
|
38
|
+
by-handle when needed.
|
|
39
|
+
|
|
40
|
+
## Logging and events
|
|
41
|
+
|
|
42
|
+
- Device-related lines carry `tags: { deviceId }` (numeric id).
|
|
43
|
+
- Events via `ctx.eventBus` + `EventCategory` are telemetry and may be dropped;
|
|
44
|
+
durable work needs RPC (or event + reconcile).
|
|
45
|
+
- Branches that drop work silently must log.
|
|
46
|
+
|
|
47
|
+
## Deploy reality
|
|
48
|
+
|
|
49
|
+
Editing source and rebuilding `dist/` does **nothing** on a live node until:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
camstack deploy packages/addon-<name>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Framework packages (`types`, `system`, `sdk`, `ui-library`) travel inside
|
|
56
|
+
`@camstack/server` — need a server update, not an addon deploy.
|
|
57
|
+
|
|
58
|
+
## Suggested reading (server repo)
|
|
59
|
+
|
|
60
|
+
| Topic | Page |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| Orientation | `docs/architecture/overview.md` |
|
|
63
|
+
| Transport / cross-node | `docs/architecture/transport.md` |
|
|
64
|
+
| Capabilities | `docs/architecture/capabilities.md` |
|
|
65
|
+
| Addon boot / crashes | `docs/architecture/addon-lifecycle.md` |
|
|
66
|
+
| Device model | `docs/architecture/device-model.md` |
|
|
67
|
+
| Data planes / decode | `docs/architecture/data-planes.md` |
|
|
68
|
+
| Update / release | `docs/architecture/update-and-release.md` |
|
|
69
|
+
| Decisions | `docs/decisions/` |
|
|
70
|
+
|
|
71
|
+
## Examples
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
camstack develop find-example provider
|
|
75
|
+
camstack develop find-example notifier
|
|
76
|
+
camstack develop find-example osd
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
See also public docs: Develop → Examples from core addons.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sync-docs
|
|
3
|
+
description: Update CamStack documentation after a change. Know what is generated and must never be hand-edited.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Keeping the docs true
|
|
7
|
+
|
|
8
|
+
Anything derivable from the repository is **generated**. Your job is prose.
|
|
9
|
+
|
|
10
|
+
## Never edit (regenerated)
|
|
11
|
+
|
|
12
|
+
| File | Derived from |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| `docs/reference/packages.md` | workspace manifests |
|
|
15
|
+
| `docs/reference/addons.md` | `camstack.addons[]` |
|
|
16
|
+
| `docs/reference/capabilities.md` | `*.cap.ts` |
|
|
17
|
+
| `docs/reference/guards.md` | `scripts/check-*` + CI |
|
|
18
|
+
| `docs/reference/subsystems.md` | `docs/subsystems.yaml` × workspace × frontmatter |
|
|
19
|
+
| `docs/reference/api.md` | caps + Zod shapes |
|
|
20
|
+
| `docs/decisions/index.md` | ADR frontmatter |
|
|
21
|
+
|
|
22
|
+
Pre-commit regenerates them; CI fails on drift. Do not restate table facts in
|
|
23
|
+
prose.
|
|
24
|
+
|
|
25
|
+
## Hand-written index
|
|
26
|
+
|
|
27
|
+
`docs/subsystems.yaml` — chapter list. Touch when adding a subsystem, not when
|
|
28
|
+
adding one more file to one.
|
|
29
|
+
|
|
30
|
+
## Frontmatter: `covers` vs `applies-to`
|
|
31
|
+
|
|
32
|
+
- **`applies-to:`** — verified against these files on `last-verified` (arms
|
|
33
|
+
staleness).
|
|
34
|
+
- **`covers:`** — describes these files (no staleness arm). For class-level
|
|
35
|
+
pages with many implementers.
|
|
36
|
+
|
|
37
|
+
## What to write (stop at first yes)
|
|
38
|
+
|
|
39
|
+
1. Learned something expensive? → `docs/history/sessions.md` (include wrong turns).
|
|
40
|
+
2. Chose between real alternatives? → new `docs/decisions/` record from
|
|
41
|
+
`template.md`. State a violable rule; put the failure in Context.
|
|
42
|
+
3. Changed how a whole subsystem behaves? → matching `docs/architecture/*.md`.
|
|
43
|
+
4. Package-local traps? → that package's `CLAUDE.md`.
|
|
44
|
+
5. Repo-wide rule? → root `CLAUDE.md` + prefer a guard in `scripts/` wired to CI.
|
|
45
|
+
|
|
46
|
+
## Verify
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
npm run docs:check
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Dead paths fail. Staleness warnings are reported, not failed.
|
|
53
|
+
|
|
54
|
+
## Do not
|
|
55
|
+
|
|
56
|
+
- Restate a generated table.
|
|
57
|
+
- Leave orphaned comments describing deleted behaviour.
|
|
58
|
+
- Add an architecture page for one addon.
|
|
59
|
+
- Manufacture a decision with no rejected alternative.
|
package/README.md
DELETED