@camstack/develop 0.0.0-stage → 0.1.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.
Files changed (52) hide show
  1. package/dist/catalogue/addons.d.ts +10 -0
  2. package/dist/catalogue/addons.d.ts.map +1 -0
  3. package/dist/catalogue/addons.js +132 -0
  4. package/dist/catalogue/capabilities.d.ts +9 -0
  5. package/dist/catalogue/capabilities.d.ts.map +1 -0
  6. package/dist/catalogue/capabilities.js +46 -0
  7. package/dist/examples/catalogue.d.ts +7 -0
  8. package/dist/examples/catalogue.d.ts.map +1 -0
  9. package/dist/examples/catalogue.js +97 -0
  10. package/dist/examples/find.d.ts +7 -0
  11. package/dist/examples/find.d.ts.map +1 -0
  12. package/dist/examples/find.js +72 -0
  13. package/dist/index.d.ts +15 -0
  14. package/dist/index.d.ts.map +1 -0
  15. package/dist/index.js +13 -0
  16. package/dist/naming.d.ts +6 -0
  17. package/dist/naming.d.ts.map +1 -0
  18. package/dist/naming.js +31 -0
  19. package/dist/scaffold/addon.d.ts +8 -0
  20. package/dist/scaffold/addon.d.ts.map +1 -0
  21. package/dist/scaffold/addon.js +221 -0
  22. package/dist/scaffold/cap-stub.d.ts +8 -0
  23. package/dist/scaffold/cap-stub.d.ts.map +1 -0
  24. package/dist/scaffold/cap-stub.js +69 -0
  25. package/dist/scaffold/extend.d.ts +8 -0
  26. package/dist/scaffold/extend.d.ts.map +1 -0
  27. package/dist/scaffold/extend.js +163 -0
  28. package/dist/scaffold/templates.d.ts +2 -0
  29. package/dist/scaffold/templates.d.ts.map +1 -0
  30. package/dist/scaffold/templates.js +9 -0
  31. package/dist/skills.d.ts +8 -0
  32. package/dist/skills.d.ts.map +1 -0
  33. package/dist/skills.js +39 -0
  34. package/dist/types.d.ts +109 -0
  35. package/dist/types.d.ts.map +1 -0
  36. package/dist/types.js +2 -0
  37. package/dist/validate/addon.d.ts +8 -0
  38. package/dist/validate/addon.d.ts.map +1 -0
  39. package/dist/validate/addon.js +119 -0
  40. package/dist/validate/entries.d.ts +8 -0
  41. package/dist/validate/entries.d.ts.map +1 -0
  42. package/dist/validate/entries.js +110 -0
  43. package/dist/workspace.d.ts +11 -0
  44. package/dist/workspace.d.ts.map +1 -0
  45. package/dist/workspace.js +65 -0
  46. package/package.json +42 -4
  47. package/skills/README.md +45 -0
  48. package/skills/add-addon.md +126 -0
  49. package/skills/add-capability.md +89 -0
  50. package/skills/architecture.md +79 -0
  51. package/skills/sync-docs.md +59 -0
  52. 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
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.