@camstack/develop 0.1.2 → 0.1.3

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.
@@ -2,7 +2,7 @@ import type { ScaffoldCapOptions, ScaffoldCapResult } from '../types.js';
2
2
  /**
3
3
  * Write a minimal `*.cap.ts` stub under packages/types. Does NOT edit
4
4
  * `capabilities/index.ts` or run codegen — those remain explicit next steps
5
- * (see add-capability skill).
5
+ * (see camstack-capability skill).
6
6
  */
7
7
  export declare function scaffoldCapStub(options: ScaffoldCapOptions): ScaffoldCapResult;
8
8
  //# sourceMappingURL=cap-stub.d.ts.map
@@ -4,7 +4,7 @@ import { toCapExportName, toClassName, toFileName } from '../naming.js';
4
4
  /**
5
5
  * Write a minimal `*.cap.ts` stub under packages/types. Does NOT edit
6
6
  * `capabilities/index.ts` or run codegen — those remain explicit next steps
7
- * (see add-capability skill).
7
+ * (see camstack-capability skill).
8
8
  */
9
9
  export function scaffoldCapStub(options) {
10
10
  const fileName = toFileName(options.name);
@@ -1 +1 @@
1
- {"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAI3C,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AAaD,wBAAgB,UAAU,IAAI,SAAS,SAAS,EAAE,CAQjD;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKjF"}
1
+ {"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAI3C,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AA4BD,wBAAgB,UAAU,IAAI,SAAS,SAAS,EAAE,CAQjD;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMjF"}
package/dist/skills.js CHANGED
@@ -11,15 +11,29 @@ export function resolveSkillsDir() {
11
11
  return candidates[0];
12
12
  }
13
13
  const SKILL_FILES = [
14
- { id: 'add-addon', file: 'add-addon.md', title: 'Add or extend an addon' },
15
- { id: 'add-capability', file: 'add-capability.md', title: 'Add or change a capability' },
16
- { id: 'sync-docs', file: 'sync-docs.md', title: 'Keep documentation true' },
14
+ { id: 'camstack-addon', file: 'camstack-addon.md', title: 'Add or extend an addon' },
15
+ {
16
+ id: 'camstack-capability',
17
+ file: 'camstack-capability.md',
18
+ title: 'Add or change a capability',
19
+ },
20
+ { id: 'camstack-secrets', file: 'camstack-secrets.md', title: 'Secrets in an addon' },
21
+ { id: 'camstack-docs', file: 'camstack-docs.md', title: 'Keep documentation true' },
17
22
  {
18
23
  id: 'architecture',
19
24
  file: 'architecture.md',
20
25
  title: 'Architecture pointers for plugin authors',
21
26
  },
22
27
  ];
28
+ /**
29
+ * The ids before the 2026-10-09 rename to the server repository's skill names.
30
+ * Still accepted by `readSkill`, so a pinned agent prompt keeps working.
31
+ */
32
+ const SKILL_ALIASES = {
33
+ 'add-addon': 'camstack-addon',
34
+ 'add-capability': 'camstack-capability',
35
+ 'sync-docs': 'camstack-docs',
36
+ };
23
37
  export function listSkills() {
24
38
  const dir = resolveSkillsDir();
25
39
  return SKILL_FILES.map((s) => ({
@@ -30,7 +44,8 @@ export function listSkills() {
30
44
  }));
31
45
  }
32
46
  export function readSkill(id) {
33
- const info = listSkills().find((s) => s.id === id);
47
+ const canonical = SKILL_ALIASES[id] ?? id;
48
+ const info = listSkills().find((s) => s.id === canonical);
34
49
  if (!info)
35
50
  return null;
36
51
  if (!fs.existsSync(info.absolutePath))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@camstack/develop",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "CamStack developer tooling — catalogue, scaffold, validate, and example lookup shared by the CLI and MCP server.",
5
5
  "keywords": [
6
6
  "camstack",
package/skills/README.md CHANGED
@@ -6,11 +6,16 @@ third-party use (no private hostnames, no hub-specific ops).
6
6
 
7
7
  | Skill | File | Job |
8
8
  | --- | --- | --- |
9
- | `add-addon` | [add-addon.md](./add-addon.md) | New or extended addon |
10
- | `add-capability` | [add-capability.md](./add-capability.md) | New or changed `*.cap.ts` |
11
- | `sync-docs` | [sync-docs.md](./sync-docs.md) | Generated vs prose docs |
9
+ | `camstack-addon` | [camstack-addon.md](./camstack-addon.md) | New or extended addon |
10
+ | `camstack-capability` | [camstack-capability.md](./camstack-capability.md) | New or changed `*.cap.ts` |
11
+ | `camstack-secrets` | [camstack-secrets.md](./camstack-secrets.md) | Password / token / key fields |
12
+ | `camstack-docs` | [camstack-docs.md](./camstack-docs.md) | Generated vs prose docs |
12
13
  | `architecture` | [architecture.md](./architecture.md) | Plugin-author architecture pointers |
13
14
 
15
+ The ids match the server repository's `.claude/skills/<id>/` skills (renamed
16
+ on 2026-10-09); the old ids `add-addon`, `add-capability` and `sync-docs` still
17
+ resolve as aliases.
18
+
14
19
  ## How to use
15
20
 
16
21
  ### CLI
@@ -18,7 +23,7 @@ third-party use (no private hostnames, no hub-specific ops).
18
23
  ```bash
19
24
  # From a camstack-server checkout:
20
25
  camstack develop skills
21
- camstack develop skill add-addon
26
+ camstack develop skill camstack-addon
22
27
 
23
28
  # Scaffold / validate with the same tooling agents should call:
24
29
  camstack develop scaffold addon my-feature --kind provider
@@ -1,6 +1,6 @@
1
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.
2
+ name: camstack-addon
3
+ description: Create or change a CamStack addon (plugin), or extend a package with a new manifest entry. Covers the silent wiring misses, the runtime traps, deploy, and proving the new code is the code running.
4
4
  ---
5
5
 
6
6
  # Adding or extending an addon
@@ -48,6 +48,22 @@ Rules that bite:
48
48
  - Never `console.log` — use `ctx.logger`.
49
49
  - Never import another addon — use `ctx.api`.
50
50
 
51
+ Rules that bite at RUNTIME, not at build time:
52
+
53
+ - **A `BaseAddon` subclass must call `super({})`** (or `super(defaults)`).
54
+ Without it init throws `Cannot convert undefined or null to object` while
55
+ build, tests and validation pass and the addon is listed as running.
56
+ - **Declare a settings collection before querying it** (`declareCollection`
57
+ in `init()`); the in-memory test store hides the miss.
58
+ - **Device state in a forked addon can go stale** — reconcile
59
+ `proxy.state.<cap>.value` with `refresh()` on a timer.
60
+ - **Two per-device stores.** A forked addon reads `<addonId>:addon-devices`;
61
+ write device config through the UI path (`applyDeviceSettingsPatch`).
62
+ - **Bundle pure-JS dependencies** (`devDependencies`); runtime
63
+ `dependencies` are for natives only.
64
+ - **Credentials** are declared by schema type and never read from the
65
+ environment — see the `camstack-secrets` skill.
66
+
51
67
  ## 3. Wire it — four places, one silent
52
68
 
53
69
  | # | Place | If you miss it |
@@ -83,7 +99,7 @@ npm run build -w packages/addon-<name> && ls packages/addon-<name>/dist/
83
99
  Generated on commit: `docs/reference/{addons,packages,capabilities,…}.md` —
84
100
  do not hand-edit. You write: `docs/history/sessions.md`, a decision record when
85
101
  you rejected a real alternative, architecture prose only when a whole subsystem
86
- changed. Run `npm run docs:check`. Use the `sync-docs` skill.
102
+ changed. Run `npm run docs:check`. Use the `camstack-docs` skill.
87
103
 
88
104
  ## 7. Ship
89
105
 
@@ -95,6 +111,31 @@ camstack deploy packages/addon-<name> -n <nodeId>
95
111
  Local `dist/` has **no runtime effect** until deploy. Builtins need a
96
112
  `@camstack/server` install.
97
113
 
114
+ Deploy traps:
115
+
116
+ - `deploy` **installs** a package that is not on the target — a second
117
+ provider on a singleton can break a working one. Check first.
118
+ - It ships what is **built** in that package, committed or not.
119
+ - It may not respawn the runner: confirm a fresh process, or call
120
+ `addons.restartAddon({ addonId })`.
121
+ - After deploying a multi-entry package, check every cap it provides still has
122
+ a provider (`capabilities.getCapability`).
123
+ - The post-deploy health probe races the restart — use `--no-verify` and poll.
124
+
125
+ **Proof the change is live:** grep the deployed bundle for a string new in this
126
+ build, then exercise the behaviour (call the cap, watch the new log line).
127
+
128
+ ## Done-gate
129
+
130
+ ```
131
+ ADDON DONE — <addonId>
132
+ wiring: manifest + vite entries + index re-export; check-addon-entries ok
133
+ checks: typecheck / tests / build emitted <dist path>
134
+ deployed: <nodes> — fresh runner; caps registered
135
+ proved: <the call / log line observed>
136
+ docs: <files | none needed: reason>
137
+ ```
138
+
98
139
  ## Extending (second entry in one package)
99
140
 
100
141
  Multi-entry packages (auth, cloudflare, …) need a new id, source file, manifest
@@ -1,6 +1,6 @@
1
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.
2
+ name: camstack-capability
3
+ description: Add or change a CamStack capability (*.cap.ts) — necessity, cardinality, codegen and the hand-edits it cannot do, providers and bindings, CAP_INPUT_DEFAULTS, and what must be published for it to reach a hub.
4
4
  ---
5
5
 
6
6
  # Adding or changing a capability
@@ -48,6 +48,11 @@ export type IFooProvider = InferProvider<typeof fooCapability>
48
48
  to `auth: 'admin'`.
49
49
  - `runtimeState` must include `lastFetchedAt: z.number()`.
50
50
  - Behavioural metadata lives **only** here.
51
+ - A cap hosted on every node and called with `{nodeId}` is `mode: 'singleton'`
52
+ — never `'per-node'`, which codegen does not wire (every call then answers
53
+ "provider not available").
54
+ - Give every method an explicit `auth` tier; the tier baseline is checked
55
+ (`npx tsx scripts/check-method-tiers.ts --update` to accept a deliberate change).
51
56
 
52
57
  ## 2. Two hand-edits codegen cannot do
53
58
 
@@ -66,6 +71,10 @@ npm run codegen
66
71
 
67
72
  Skipping is silent drift. CI `codegen:check` catches it later.
68
73
 
74
+ Input `.default()`s run only where the router parses them. A call from an addon
75
+ through `ctx.api` gets codegen's `CAP_INPUT_DEFAULTS` instead, which carries
76
+ TOP-LEVEL defaults only — a nested default arrives `undefined` on that path.
77
+
69
78
  ## 4. Implement and declare
70
79
 
71
80
  - System: `context.registerProvider(cap, impl)` / return from `onInitialize`.
@@ -74,6 +83,12 @@ Skipping is silent drift. CI `codegen:check` catches it later.
74
83
  - Flat providers — no nested sub-objects.
75
84
  - If agents must expose the cap, also add it to the agent-side curated list in
76
85
  `server/backend` (hand-maintained).
86
+ - Two addons implementing one cap both register unconditionally; the operator
87
+ picks by binding (`capabilities.setActiveSingleton`, the collection enable
88
+ toggle, or a device binding) — never a private setting.
89
+ - Never hand-write an interface over a cap; narrow the generated client
90
+ (`Pick<AddonApi['foo'], …>`). A hand copy keeps compiling after a method is
91
+ removed and fails at runtime.
77
92
 
78
93
  ## 5. Spec + docs
79
94
 
@@ -84,6 +99,13 @@ alternative.
84
99
 
85
100
  ## 6. Ship
86
101
 
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.
102
+ A cap change is a framework change: the hub serves the cap definitions bundled
103
+ in `@camstack/system`, so it ships inside a published `@camstack/server` (force
104
+ `@camstack/system` into the publish — an edit under `packages/types` does not
105
+ mark it changed) and reaches a node through `serverManagement.applyServerUpdate`.
106
+ Then deploy the providing addon. An additive OUTPUT field needs only the
107
+ addon redeployed; a new INPUT field needs the server update (the hub strips
108
+ keys its schema does not know).
109
+
110
+ `No procedure found on path "<cap>.<method>"` = the node runs the old server;
111
+ `method '<m>' not found on provider` = the addon is stale.
@@ -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,49 @@
1
+ ---
2
+ name: camstack-secrets
3
+ description: Handle a credential in a CamStack addon — a password, token or key field, hidden credential state, or a secret a spawned child process needs. Declared by schema type, stored in the keychain, never in the environment or on argv.
4
+ ---
5
+
6
+ # Secrets in an addon
7
+
8
+ Every password, token and key lives in the hub's keychain. A settings blob
9
+ holds a marker (`{ "$secret": "secret://<owner>/<scope>/<field>", "v": 1 }`)
10
+ where the value used to be. Long form: `docs/architecture/secrets-keychain.md`
11
+ in the server repository.
12
+
13
+ ## 1. Declare it by type, never by name
14
+
15
+ - Config-UI field: `type: 'password'`, or `secret: true` on a `text` /
16
+ `textarea` field. Zod device-config field: `.meta({ secret: true })`.
17
+ - A declared field is keychain-backed by `BaseAddon`: `this.config` holds the
18
+ value, the stored blob holds the marker.
19
+ - Hidden credential state (a token you mint or receive) goes in
20
+ `protected readonly secretStatePaths = [...]`.
21
+ - An array of rows with a secret needs an id field (`itemIdKey`, default `'id'`).
22
+
23
+ ## 2. Read and clear it
24
+
25
+ - Your own reads (`this.config`, `this.ctx.settings.read*`, …) answer VALUES.
26
+ Never read the `initialize(context)` parameter's settings — that view holds
27
+ markers; call `super.initialize(context)` and use `this.ctx`.
28
+ - A value the keychain cannot serve right now reads as its marker
29
+ (`isSecretMarker(v)`) — "stored, unavailable". Run degraded; never mint a
30
+ replacement.
31
+ - `''` never clears a secret: `this.clearSecrets(['key'])`.
32
+
33
+ ## 3. Never the environment, never argv
34
+
35
+ - No credential is read from an env var, not even an optional "power user"
36
+ token.
37
+ - A child process gets a FILE: a fresh 0700 temp dir, the value written with
38
+ mode 0600, the path on argv (`--token-file <path>`), the dir removed when the
39
+ child exits. Build error messages from a child's output through a scrubber.
40
+ - No client secret or private key in a publishable package — every package is
41
+ public on npm.
42
+
43
+ ## 4. Check
44
+
45
+ ```bash
46
+ npx tsx scripts/check-secret-fields-declared.ts
47
+ npx tsx scripts/check-no-raw-secret-read.ts
48
+ npx tsx scripts/check-no-client-secrets.ts
49
+ ```