@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.
- 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/package.json +1 -1
- package/skills/README.md +9 -4
- package/skills/{add-addon.md → camstack-addon.md} +44 -3
- package/skills/{add-capability.md → camstack-capability.md} +27 -5
- package/skills/{sync-docs.md → camstack-docs.md} +12 -5
- package/skills/camstack-secrets.md +49 -0
|
@@ -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
|
|
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
|
|
7
|
+
* (see camstack-capability skill).
|
|
8
8
|
*/
|
|
9
9
|
export function scaffoldCapStub(options) {
|
|
10
10
|
const fileName = toFileName(options.name);
|
package/dist/skills.d.ts.map
CHANGED
|
@@ -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;
|
|
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: '
|
|
15
|
-
{
|
|
16
|
-
|
|
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
|
|
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
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
|
-
| `
|
|
10
|
-
| `
|
|
11
|
-
| `
|
|
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
|
|
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:
|
|
3
|
-
description:
|
|
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 `
|
|
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:
|
|
3
|
-
description: Add or change a CamStack capability (*.cap.ts)
|
|
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
|
-
|
|
88
|
-
`@camstack/
|
|
89
|
-
|
|
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:
|
|
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,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
|
+
```
|