@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.
@@ -1,6 +1,6 @@
1
1
  ---
2
- name: sync-docs
3
- description: Update CamStack documentation after a change. Know what is generated and must never be hand-edited.
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
- 5. Repo-wide rule? → root `CLAUDE.md` + prefer a guard in `scripts/` wired to CI.
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
+ ```
@@ -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`.
@@ -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.