@camstack/develop 0.1.2 → 0.1.4
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/hub/admin-token-store.d.ts +53 -0
- package/dist/hub/admin-token-store.d.ts.map +1 -0
- package/dist/hub/admin-token-store.js +139 -0
- package/dist/hub/credentials.d.ts +53 -0
- package/dist/hub/credentials.d.ts.map +1 -0
- package/dist/hub/credentials.js +149 -0
- package/dist/hub/hub-client.d.ts +57 -0
- package/dist/hub/hub-client.d.ts.map +1 -0
- package/dist/hub/hub-client.js +176 -0
- package/dist/hub/hub-tls.d.ts +16 -0
- package/dist/hub/hub-tls.d.ts.map +1 -0
- package/dist/hub/hub-tls.js +67 -0
- package/dist/hub/hub-url.d.ts +17 -0
- package/dist/hub/hub-url.d.ts.map +1 -0
- package/dist/hub/hub-url.js +44 -0
- package/dist/hub/session-store.d.ts +38 -0
- package/dist/hub/session-store.d.ts.map +1 -0
- package/dist/hub/session-store.js +117 -0
- package/dist/index.d.ts +14 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -2
- package/dist/scaffold/addon.d.ts.map +1 -1
- package/dist/scaffold/addon.js +6 -0
- package/dist/scaffold/cap-stub.d.ts +1 -1
- package/dist/scaffold/cap-stub.js +1 -1
- package/dist/skills.d.ts.map +1 -1
- package/dist/skills.js +19 -4
- package/dist/types.d.ts +6 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/skills/README.md +12 -4
- package/skills/camstack-addon.md +445 -0
- package/skills/camstack-capability.md +218 -0
- package/skills/{sync-docs.md → camstack-docs.md} +12 -5
- package/skills/camstack-secrets.md +136 -0
- package/skills/add-addon.md +0 -126
- package/skills/add-capability.md +0 -89
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
3
|
-
description:
|
|
2
|
+
name: camstack-docs
|
|
3
|
+
description: Keep CamStack documentation true after a change — what is generated and must never be hand-edited, what prose to write, ADRs, and the docs check.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Keeping the docs true
|
|
@@ -20,7 +20,9 @@ Anything derivable from the repository is **generated**. Your job is prose.
|
|
|
20
20
|
| `docs/decisions/index.md` | ADR frontmatter |
|
|
21
21
|
|
|
22
22
|
Pre-commit regenerates them; CI fails on drift. Do not restate table facts in
|
|
23
|
-
prose.
|
|
23
|
+
prose. Regenerate by hand with `npm run docs:generate`. A generated file that
|
|
24
|
+
conflicts in a rebase is never hand-merged: take either side, regenerate,
|
|
25
|
+
stage.
|
|
24
26
|
|
|
25
27
|
## Hand-written index
|
|
26
28
|
|
|
@@ -40,8 +42,13 @@ adding one more file to one.
|
|
|
40
42
|
2. Chose between real alternatives? → new `docs/decisions/` record from
|
|
41
43
|
`template.md`. State a violable rule; put the failure in Context.
|
|
42
44
|
3. Changed how a whole subsystem behaves? → matching `docs/architecture/*.md`.
|
|
43
|
-
4. Package-local traps? → that package's `CLAUDE.md
|
|
44
|
-
|
|
45
|
+
4. Package-local traps? → that package's `AGENTS.md` (`CLAUDE.md` beside it
|
|
46
|
+
is a one-line `@AGENTS.md` import), or its notes page under `docs/addons/`.
|
|
47
|
+
5. Repo-wide rule? → root `AGENTS.md`, one line, + prefer a guard in `scripts/`.
|
|
48
|
+
|
|
49
|
+
A decision record takes the next free number (`docs/decisions/conventions.md`),
|
|
50
|
+
is copied from `docs/decisions/template.md`, and is never edited once accepted
|
|
51
|
+
— supersede it instead.
|
|
45
52
|
|
|
46
53
|
## Verify
|
|
47
54
|
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: camstack-secrets
|
|
3
|
+
description: Handle a credential in CamStack — a password, token, API key or private key in an addon's settings, a device config, `secretStatePaths`, a token the addon mints, the hub's own secrets, or a credential a spawned child process (ffmpeg, a tunnel CLI) needs. Covers the keychain and `secret://` markers, declaring a secret by schema type, the read and clear rules, never using environment variables or argv, 0600 temp files for children, log scrubbing, the UI field, and the guards that enforce it. Use for "add a password field", "store a token", "pass a key to a subprocess", "a setting reads as { $secret }", "check-secret-fields-declared failed".
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Secrets and the keychain
|
|
7
|
+
|
|
8
|
+
Every password, token and key CamStack holds lives in ONE place: the hub's
|
|
9
|
+
keychain, encrypted. A settings blob, device config, integration or storage
|
|
10
|
+
location holds a **marker** where the value used to be:
|
|
11
|
+
|
|
12
|
+
```json
|
|
13
|
+
{ "$secret": "secret://<owner>/<scope>/<fieldPath>", "v": 1 }
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Long form, with what it protects against and what it does not:
|
|
17
|
+
`docs/architecture/secrets-keychain.md`. Records: D783 (declared by type; never
|
|
18
|
+
on argv, env or logs), D787 (marker contract), D788 (master key location is
|
|
19
|
+
configuration), D789 (the admin form round-trips the marker), D797 (the hub's
|
|
20
|
+
own secrets), D798 (an addon reads its own settings resolved).
|
|
21
|
+
|
|
22
|
+
> Skill names with no file in this pack (`camstack-ui`, `camstack-ui-admin`,
|
|
23
|
+
> `camstack-server-change`, `camstack-diagnose`, `camstack-publish-ci`) are
|
|
24
|
+
> server-repository skills under `.claude/skills/`; this text stands on its own.
|
|
25
|
+
|
|
26
|
+
## 1. Workflow
|
|
27
|
+
|
|
28
|
+
1. **Declare** every secret by its schema TYPE (§2). Never rely on a key name.
|
|
29
|
+
2. **Read** it the resolved way and handle "stored but unavailable" (§3).
|
|
30
|
+
3. **Hand it to a child** only through an owner-only file (§4) — never env,
|
|
31
|
+
never argv.
|
|
32
|
+
4. **Keep it out of logs, fixtures and the repository** (§5).
|
|
33
|
+
5. **Render** it with the library secret field (§6).
|
|
34
|
+
6. **Run the guards** (§7) and paste the done-gate (§8).
|
|
35
|
+
|
|
36
|
+
## 2. Declare it — by type, never by name
|
|
37
|
+
|
|
38
|
+
- Config-UI field: `type: 'password'`, or `secret: true` on a `text` /
|
|
39
|
+
`textarea` field. Zod device-config field: `.meta({ secret: true })`.
|
|
40
|
+
`storage: 'inline'` opts a field OUT (a masked non-secret). A JSON textarea
|
|
41
|
+
that holds a secret stays inline — the keychain stores strings.
|
|
42
|
+
- A declared field is keychain-backed by `BaseAddon` with no further code: the
|
|
43
|
+
blob stores the marker, `this.config` holds the value.
|
|
44
|
+
- **Hidden state that is a credential** — a token you mint or receive, never a
|
|
45
|
+
form field — goes in `protected readonly secretStatePaths = [...]`
|
|
46
|
+
(`'ingressToken'`, `'identity.pincode'`, `'tokens[userId].accessToken'`).
|
|
47
|
+
- **An array of rows with a secret** needs an id field (`itemIdKey`, default
|
|
48
|
+
`'id'`): refs are addressed by item id, so a reorder keeps them.
|
|
49
|
+
- A credential-named field that is NOT declared fails
|
|
50
|
+
`scripts/check-secret-fields-declared.ts`.
|
|
51
|
+
|
|
52
|
+
## 3. Read and clear it
|
|
53
|
+
|
|
54
|
+
- **Every read of your own settings answers VALUES** — `this.config`,
|
|
55
|
+
`this.state()`, `this.resolveGlobalStore()`, `this.readStoredGlobalKey()`,
|
|
56
|
+
every `this.ctx.settings.read*` — never a marker (D798). Writing back what you
|
|
57
|
+
read is a no-op (no keychain version, no `onConfigChanged`).
|
|
58
|
+
- **Never touch the `initialize(context)` parameter's settings** — that is the
|
|
59
|
+
kernel's unwrapped view and answers markers. Call `super.initialize(context)`
|
|
60
|
+
and use `this.ctx`. `scripts/check-no-raw-secret-read.ts` fails on it.
|
|
61
|
+
- **Locked is never empty.** A value the keychain cannot serve right now reads
|
|
62
|
+
as its MARKER (`isSecretMarker(v)` is true; it is listed in
|
|
63
|
+
`this.unresolvedSecrets`) — never as `''` or absent. Run degraded; do NOT
|
|
64
|
+
mint a replacement. An addon write over a secret it could not read is refused
|
|
65
|
+
(`SecretOverwriteRefusedError`), so "absent → mint → save" cannot loop.
|
|
66
|
+
- **`''` never clears a secret.** To forget one: `this.clearSecrets(['key'])`.
|
|
67
|
+
|
|
68
|
+
## 4. Never through the environment or argv — files for children
|
|
69
|
+
|
|
70
|
+
- **No secret reaches any process through its environment** — not an addon
|
|
71
|
+
credential, not the session signing key, not the cluster secret, not "an
|
|
72
|
+
optional token for power users" (D797 removed `HF_TOKEN`,
|
|
73
|
+
`CAMSTACK_SECRET_KEY` and the like). A credential is a declared field, read
|
|
74
|
+
from your config.
|
|
75
|
+
- The hub's own secrets live in the keychain under owner `system`; an agent's
|
|
76
|
+
cluster secret lives in its own `agent.json` (0600). The keychain master key
|
|
77
|
+
comes from `keychain.keyFile` in `config.yaml`, the desktop app's OS
|
|
78
|
+
keychain, or the default key file — never an env var (D788).
|
|
79
|
+
- **A child process that needs a credential gets an owner-only FILE**: a fresh
|
|
80
|
+
`0700` temp dir, the value written with `mode: 0o600`, the PATH passed on
|
|
81
|
+
argv (`--auth-key=file:<path>`, `--token-file <path>`), the dir removed when
|
|
82
|
+
the child settles — success or failure. Worked example:
|
|
83
|
+
`packages/addon-tailscale/src/auth-key-file.ts`; also
|
|
84
|
+
`packages/addon-cloudflare/src/tunnel/cloudflared-invocation.ts`.
|
|
85
|
+
- A URL with embedded credentials is a secret on argv too: build it for the
|
|
86
|
+
child from a file or a pipe the child reads, never from a string you log.
|
|
87
|
+
- Client-side developer tooling is different: the `camstack` CLI's
|
|
88
|
+
`$CAMSTACK_TOKEN` / `--token-file` and `scripts/hub/hub.mjs`'s credential chain
|
|
89
|
+
(`--token-file`, the 0600 admin token file, the `camstack login` session) are a developer's own credentials on their own machine,
|
|
90
|
+
not server-side secrets.
|
|
91
|
+
|
|
92
|
+
## 5. Logs, fixtures, the repository
|
|
93
|
+
|
|
94
|
+
- A value your addon resolved from the keychain is scrubbed from its logs
|
|
95
|
+
automatically; a message you BUILD with it (an error string from a child,
|
|
96
|
+
`Command failed: …`) is your job — pass it through a scrubber.
|
|
97
|
+
- Recorded fixtures never carry a live camera credential
|
|
98
|
+
(`scripts/check-no-credential-urls-in-fixtures.ts`).
|
|
99
|
+
- No OAuth client secret in a publishable package
|
|
100
|
+
(`scripts/check-no-client-secrets.ts`) and no private key of any kind
|
|
101
|
+
(`scripts/check-no-service-account-keys.ts`) — every package is public on
|
|
102
|
+
npm. A secret that must exist server-side for a public integration lives
|
|
103
|
+
behind a broker, not in source.
|
|
104
|
+
- A secret that was ever committed or published is rotated, not just deleted.
|
|
105
|
+
|
|
106
|
+
## 6. In the UI
|
|
107
|
+
|
|
108
|
+
The secret field is `SecretFieldControl` (`packages/ui-library/src/composites/config-secret-field.tsx`) plus
|
|
109
|
+
`PasswordInput` from the ui-library; the admin form shows "set", never the
|
|
110
|
+
value (D789), and a reveal happens in a dialog. Details: `camstack-ui-admin`.
|
|
111
|
+
|
|
112
|
+
## 7. Guards — run the ones you touched
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npx tsx scripts/check-secret-fields-declared.ts
|
|
116
|
+
npx tsx scripts/check-no-raw-secret-read.ts
|
|
117
|
+
npx tsx scripts/check-no-client-secrets.ts
|
|
118
|
+
npx tsx scripts/check-no-service-account-keys.ts
|
|
119
|
+
npx tsx scripts/check-no-credential-urls-in-fixtures.ts
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Operators moving an old hub's plaintext into the keychain use the one-off
|
|
123
|
+
`scripts/ops/keychain-migrate-hub.mjs`; the product ships no migration code.
|
|
124
|
+
A lost master key is recovered with the `RESET_KEYCHAIN` trigger file
|
|
125
|
+
(D799, `docs/architecture/secrets-keychain.md` §"A lost master key").
|
|
126
|
+
|
|
127
|
+
## 8. Done-gate — paste it before "done"
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
SECRETS DONE — <addon / field>
|
|
131
|
+
declared: <field → password | secret:true | .meta({secret:true}) | secretStatePaths entry>
|
|
132
|
+
read path: <this.config / resolved reads; marker (unavailable) handled as: …>
|
|
133
|
+
children: <0600 file via <helper> | no child needs it>
|
|
134
|
+
env/argv: none — <grep result for the value's variable on spawn calls>
|
|
135
|
+
guards: <the commands above and their result>
|
|
136
|
+
```
|
package/skills/add-addon.md
DELETED
|
@@ -1,126 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: add-addon
|
|
3
|
-
description: Add a new CamStack addon (plugin), or extend an existing package with a new manifest entry. Covers silent wiring misses and deploy.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Adding or extending an addon
|
|
7
|
-
|
|
8
|
-
## Tooling (prefer this over hand-copying)
|
|
9
|
-
|
|
10
|
-
```bash
|
|
11
|
-
camstack develop scaffold addon <name> [--kind empty|provider|notifier|osd|post-analysis]
|
|
12
|
-
camstack develop extend <existing-addon> --entry <new-id>
|
|
13
|
-
camstack develop find-example <topic>
|
|
14
|
-
camstack develop validate <name-or-path>
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
Nx equivalent (same idea): `nx g @camstack/nx-plugin:addon <name>`.
|
|
18
|
-
The develop scaffold also writes `vite.config.ts` `entries` — the miss that
|
|
19
|
-
fails only at runtime.
|
|
20
|
-
|
|
21
|
-
## 1. Decide where it lives
|
|
22
|
-
|
|
23
|
-
- **Builtin** (`packages/system/src/builtins/<name>/`) if the kernel cannot
|
|
24
|
-
function without it on every node. Ships inside `@camstack/server`.
|
|
25
|
-
- **Package** (`packages/addon-<name>/`) otherwise. Opt-in via install /
|
|
26
|
-
`camstack deploy`.
|
|
27
|
-
|
|
28
|
-
Read `docs/architecture/addon-lifecycle.md` in the server repo if unsure.
|
|
29
|
-
|
|
30
|
-
## 2. Write the addon
|
|
31
|
-
|
|
32
|
-
```
|
|
33
|
-
packages/addon-<name>/
|
|
34
|
-
package.json camstack.addons[]
|
|
35
|
-
vite.config.ts entries map MUST include every addon entry
|
|
36
|
-
src/<name>.addon.ts BaseAddon subclass
|
|
37
|
-
src/index.ts
|
|
38
|
-
__tests__/
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
Rules that bite:
|
|
42
|
-
|
|
43
|
-
- Providers on the logging path must not log into themselves.
|
|
44
|
-
- Hot `write`-style methods must not throw (fan-out callers die with them).
|
|
45
|
-
- Behavioural cap metadata (`kind`, `defaultActive`, `mode`) lives only in
|
|
46
|
-
`*.cap.ts`, never the manifest.
|
|
47
|
-
- Emit only through `ctx.eventBus` with `EventCategory`.
|
|
48
|
-
- Never `console.log` — use `ctx.logger`.
|
|
49
|
-
- Never import another addon — use `ctx.api`.
|
|
50
|
-
|
|
51
|
-
## 3. Wire it — four places, one silent
|
|
52
|
-
|
|
53
|
-
| # | Place | If you miss it |
|
|
54
|
-
| --- | --- | --- |
|
|
55
|
-
| 1 | `camstack.addons[]` in package.json | addon does not exist |
|
|
56
|
-
| 2 | **`vite.config.ts` `entries` map** | compiles, fails at runtime |
|
|
57
|
-
| 3 | `src/index.ts` re-export | hard to import / test |
|
|
58
|
-
| 4 | `packages/system/src/index.ts` (builtins only) | same |
|
|
59
|
-
|
|
60
|
-
`description` is required in practice — Admin UI and generated docs show `—`
|
|
61
|
-
without it. Manifest fields: `execution.placement`, `execution.group`,
|
|
62
|
-
`instanceMode`, `storageLocations`, `icon` / `color`, `protected`.
|
|
63
|
-
|
|
64
|
-
## 4. Opt-in (no manifest `enabled` flag)
|
|
65
|
-
|
|
66
|
-
Every declared addon loads. Prefer config-default inertness (`enabled: false` +
|
|
67
|
-
empty required field) and still register the provider so the UI can turn it on.
|
|
68
|
-
Alternatively: a separate npm package (install = opt-in), or
|
|
69
|
-
`addons.setCapabilityProviderEnabled` for collection caps.
|
|
70
|
-
|
|
71
|
-
## 5. Verify
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
npm run codegen # only if you touched a *.cap.ts
|
|
75
|
-
camstack develop validate <pkg>
|
|
76
|
-
npx tsx scripts/check-addon-entries.ts
|
|
77
|
-
npm run typecheck -w packages/addon-<name>
|
|
78
|
-
npm run build -w packages/addon-<name> && ls packages/addon-<name>/dist/
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
## 6. Documentation
|
|
82
|
-
|
|
83
|
-
Generated on commit: `docs/reference/{addons,packages,capabilities,…}.md` —
|
|
84
|
-
do not hand-edit. You write: `docs/history/sessions.md`, a decision record when
|
|
85
|
-
you rejected a real alternative, architecture prose only when a whole subsystem
|
|
86
|
-
changed. Run `npm run docs:check`. Use the `sync-docs` skill.
|
|
87
|
-
|
|
88
|
-
## 7. Ship
|
|
89
|
-
|
|
90
|
-
```bash
|
|
91
|
-
camstack deploy packages/addon-<name>
|
|
92
|
-
camstack deploy packages/addon-<name> -n <nodeId>
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
Local `dist/` has **no runtime effect** until deploy. Builtins need a
|
|
96
|
-
`@camstack/server` install.
|
|
97
|
-
|
|
98
|
-
## Extending (second entry in one package)
|
|
99
|
-
|
|
100
|
-
Multi-entry packages (auth, cloudflare, …) need a new id, source file, manifest
|
|
101
|
-
row, **and** vite `entries` key. Prefer:
|
|
102
|
-
|
|
103
|
-
```bash
|
|
104
|
-
camstack develop extend <package> --entry <new-id>
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
## Device-page widgets
|
|
108
|
-
|
|
109
|
-
There is no addon-level route onto a camera settings page. Sections come from
|
|
110
|
-
capabilities bound to the device. Ask: would another vendor implement this cap
|
|
111
|
-
unchanged?
|
|
112
|
-
|
|
113
|
-
- **Yes (generic)** — `deviceConfig.ui.kind: 'widget'` and register the host
|
|
114
|
-
widget. Framework derives the section.
|
|
115
|
-
- **No (owned)** — cap sets `exposesDeviceSettings: true`; provider returns a
|
|
116
|
-
hydrated `ConfigUISchema`.
|
|
117
|
-
|
|
118
|
-
Do not put `type: 'widget'` only in an addon's `deviceSettingsSchema()` hoping
|
|
119
|
-
the device page picks it up — that path feeds a different Admin surface and can
|
|
120
|
-
silently show nothing.
|
|
121
|
-
|
|
122
|
-
## Custom actions (operator buttons)
|
|
123
|
-
|
|
124
|
-
Populate **both** the entry module's `customActions` export and
|
|
125
|
-
`onInitialize`'s `customActions`, or the bridge 404s depending on in-process vs
|
|
126
|
-
forked. See `docs/architecture/addon-custom-actions.md`.
|
package/skills/add-capability.md
DELETED
|
@@ -1,89 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: add-capability
|
|
3
|
-
description: Add or change a CamStack capability (*.cap.ts). Covers necessity, codegen, and the hand-edits codegen cannot do.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Adding or changing a capability
|
|
7
|
-
|
|
8
|
-
## Tooling
|
|
9
|
-
|
|
10
|
-
```bash
|
|
11
|
-
camstack develop scaffold cap <name> [--scope system|device] [--mode singleton|collection]
|
|
12
|
-
camstack develop list-caps
|
|
13
|
-
camstack develop who-provides <cap-name>
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
The scaffold writes a stub only. You still hand-edit the index + run codegen.
|
|
17
|
-
|
|
18
|
-
## 0. Do you need one?
|
|
19
|
-
|
|
20
|
-
A new capability is a **framework** change: codegen, and in production it reaches
|
|
21
|
-
nodes only through a published `@camstack/server`. Prefer:
|
|
22
|
-
|
|
23
|
-
- Enumerating providers → `addons.listCapabilityProviders({ capName })`
|
|
24
|
-
- Addon config → `globalSettingsSchema()` + `addon-settings`
|
|
25
|
-
- Enable/disable a provider → `addons.setCapabilityProviderEnabled`
|
|
26
|
-
- Additive field on an existing method → redeploy the providing addon only
|
|
27
|
-
|
|
28
|
-
Mint a cap when several addons must implement or call genuinely new behaviour.
|
|
29
|
-
|
|
30
|
-
## 1. Define it
|
|
31
|
-
|
|
32
|
-
`packages/types/src/capabilities/<name>.cap.ts`:
|
|
33
|
-
|
|
34
|
-
```ts
|
|
35
|
-
export const fooCapability = {
|
|
36
|
-
name: 'foo',
|
|
37
|
-
scope: 'system', // or 'device'
|
|
38
|
-
mode: 'singleton', // or 'collection'
|
|
39
|
-
methods: { … },
|
|
40
|
-
} as const satisfies CapabilityDefinition
|
|
41
|
-
|
|
42
|
-
export type IFooProvider = InferProvider<typeof fooCapability>
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
- Mount is derived from mode unless `server-provided` / `hub-only` / `skip`.
|
|
46
|
-
- `internal: true` + `mount: { kind: 'skip' }` = in-process only, no tRPC route.
|
|
47
|
-
- `internal: true` without skip still gets a router; unannotated methods floor
|
|
48
|
-
to `auth: 'admin'`.
|
|
49
|
-
- `runtimeState` must include `lastFetchedAt: z.number()`.
|
|
50
|
-
- Behavioural metadata lives **only** here.
|
|
51
|
-
|
|
52
|
-
## 2. Two hand-edits codegen cannot do
|
|
53
|
-
|
|
54
|
-
In `packages/types/src/capabilities/index.ts`:
|
|
55
|
-
|
|
56
|
-
1. Value re-export of the capability + types.
|
|
57
|
-
2. Member of the `AnyCapability` union.
|
|
58
|
-
|
|
59
|
-
Miss either → compiles but invisible to consumers.
|
|
60
|
-
|
|
61
|
-
## 3. Codegen
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
npm run codegen
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
Skipping is silent drift. CI `codegen:check` catches it later.
|
|
68
|
-
|
|
69
|
-
## 4. Implement and declare
|
|
70
|
-
|
|
71
|
-
- System: `context.registerProvider(cap, impl)` / return from `onInitialize`.
|
|
72
|
-
- Device: `ctx.registerNativeCap(cap, impl)` from a `BaseDevice` subclass.
|
|
73
|
-
- Declare the capability **by name** in the addon manifest.
|
|
74
|
-
- Flat providers — no nested sub-objects.
|
|
75
|
-
- If agents must expose the cap, also add it to the agent-side curated list in
|
|
76
|
-
`server/backend` (hand-maintained).
|
|
77
|
-
|
|
78
|
-
## 5. Spec + docs
|
|
79
|
-
|
|
80
|
-
Router tests under `server/backend/src/__tests__/cap-routers/`. Generated
|
|
81
|
-
`docs/reference/capabilities.md` updates on commit. Append
|
|
82
|
-
`docs/history/sessions.md`; write a decision when you rejected a real
|
|
83
|
-
alternative.
|
|
84
|
-
|
|
85
|
-
## 6. Ship
|
|
86
|
-
|
|
87
|
-
Framework change: `camstack deploy packages/types` in development, published
|
|
88
|
-
`@camstack/server` in production. Additive method fields need only the providing
|
|
89
|
-
addon redeployed.
|