@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,8 @@
1
+ import type { ValidationResult } from '../types.js';
2
+ /**
3
+ * Validate one addon package (or the whole workspace when query omitted).
4
+ * Combines manifest shape checks with the vite-entries guard. Does not
5
+ * open SQLite, call a hub, or run codegen.
6
+ */
7
+ export declare function validateAddon(workspaceRoot: string, query?: string): ValidationResult;
8
+ //# sourceMappingURL=addon.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"addon.d.ts","sourceRoot":"","sources":["../../src/validate/addon.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAqB,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEtE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CA8BrF"}
@@ -0,0 +1,119 @@
1
+ import * as fs from 'node:fs';
2
+ import * as path from 'node:path';
3
+ import { findAddonPackage } from '../catalogue/addons.js';
4
+ import { listCapabilities } from '../catalogue/capabilities.js';
5
+ import { asRecord, readJsonFile } from '../workspace.js';
6
+ import { checkAddonEntries } from './entries.js';
7
+ /**
8
+ * Validate one addon package (or the whole workspace when query omitted).
9
+ * Combines manifest shape checks with the vite-entries guard. Does not
10
+ * open SQLite, call a hub, or run codegen.
11
+ */
12
+ export function validateAddon(workspaceRoot, query) {
13
+ const findings = [];
14
+ if (query === undefined || query.trim() === '' || query === '--all') {
15
+ findings.push(...checkAddonEntries(workspaceRoot).findings);
16
+ return { ok: findings.every((f) => f.level !== 'error'), findings };
17
+ }
18
+ const pkg = findAddonPackage(workspaceRoot, query);
19
+ if (!pkg) {
20
+ return {
21
+ ok: false,
22
+ findings: [
23
+ {
24
+ level: 'error',
25
+ code: 'not-found',
26
+ message: `No addon package matched: ${query}`,
27
+ },
28
+ ],
29
+ };
30
+ }
31
+ findings.push(...checkManifestShape(pkg.packageDir, pkg.packageName));
32
+ findings.push(...checkDeclaredCapsExist(workspaceRoot, pkg.packageDir, pkg.packageName));
33
+ findings.push(...checkAddonEntries(workspaceRoot, pkg.packageDir).findings);
34
+ return {
35
+ ok: findings.every((f) => f.level !== 'error'),
36
+ findings,
37
+ };
38
+ }
39
+ function checkManifestShape(pkgDir, pkgName) {
40
+ const findings = [];
41
+ const pkg = readJsonFile(path.join(pkgDir, 'package.json'));
42
+ if (!pkg) {
43
+ return [
44
+ {
45
+ level: 'error',
46
+ code: 'no-package-json',
47
+ message: `${pkgName}: missing package.json`,
48
+ path: pkgDir,
49
+ },
50
+ ];
51
+ }
52
+ const camstack = asRecord(pkg['camstack']);
53
+ const addons = camstack?.['addons'];
54
+ if (!Array.isArray(addons) || addons.length === 0) {
55
+ findings.push({
56
+ level: 'error',
57
+ code: 'no-addons',
58
+ message: `${pkgName}: camstack.addons[] is empty or missing`,
59
+ path: path.join(pkgDir, 'package.json'),
60
+ });
61
+ return findings;
62
+ }
63
+ for (const raw of addons) {
64
+ const addon = asRecord(raw);
65
+ if (!addon)
66
+ continue;
67
+ const id = typeof addon['id'] === 'string' ? addon['id'] : '(unnamed)';
68
+ if (typeof addon['description'] !== 'string' || addon['description'].trim() === '') {
69
+ findings.push({
70
+ level: 'warn',
71
+ code: 'missing-description',
72
+ message: `${pkgName} → ${id}: description missing (Admin UI + docs show "—")`,
73
+ path: path.join(pkgDir, 'package.json'),
74
+ });
75
+ }
76
+ if (!fs.existsSync(path.join(pkgDir, 'vite.config.ts'))) {
77
+ findings.push({
78
+ level: 'warn',
79
+ code: 'no-vite-config',
80
+ message: `${pkgName}: no vite.config.ts — entry may not be built`,
81
+ path: pkgDir,
82
+ });
83
+ }
84
+ }
85
+ return findings;
86
+ }
87
+ function checkDeclaredCapsExist(workspaceRoot, pkgDir, pkgName) {
88
+ const known = new Set(listCapabilities(workspaceRoot).map((c) => c.name));
89
+ const pkg = readJsonFile(path.join(pkgDir, 'package.json'));
90
+ const camstack = asRecord(pkg?.['camstack']);
91
+ const addons = camstack?.['addons'];
92
+ if (!Array.isArray(addons))
93
+ return [];
94
+ const findings = [];
95
+ for (const raw of addons) {
96
+ const addon = asRecord(raw);
97
+ if (!addon)
98
+ continue;
99
+ const id = typeof addon['id'] === 'string' ? addon['id'] : '(unnamed)';
100
+ const caps = addon['capabilities'];
101
+ if (!Array.isArray(caps))
102
+ continue;
103
+ for (const cap of caps) {
104
+ const rec = asRecord(cap);
105
+ const name = rec && typeof rec['name'] === 'string' ? rec['name'] : null;
106
+ if (!name)
107
+ continue;
108
+ if (!known.has(name)) {
109
+ findings.push({
110
+ level: 'error',
111
+ code: 'unknown-capability',
112
+ message: `${pkgName} → ${id}: declares unknown capability \`${name}\``,
113
+ path: path.join(pkgDir, 'package.json'),
114
+ });
115
+ }
116
+ }
117
+ }
118
+ return findings;
119
+ }
@@ -0,0 +1,8 @@
1
+ import type { ValidationResult } from '../types.js';
2
+ /**
3
+ * Port of `scripts/check-addon-entries.ts` as a library API (no process.exit).
4
+ * Every `camstack.addons[].entry` must have a source file and, when the
5
+ * package uses an explicit vite `entries` map, a matching key.
6
+ */
7
+ export declare function checkAddonEntries(workspaceRoot: string, packageDir?: string): ValidationResult;
8
+ //# sourceMappingURL=entries.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/validate/entries.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAqB,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEtE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAa9F"}
@@ -0,0 +1,110 @@
1
+ import * as fs from 'node:fs';
2
+ import * as path from 'node:path';
3
+ import { asRecord, readJsonFile } from '../workspace.js';
4
+ /**
5
+ * Port of `scripts/check-addon-entries.ts` as a library API (no process.exit).
6
+ * Every `camstack.addons[].entry` must have a source file and, when the
7
+ * package uses an explicit vite `entries` map, a matching key.
8
+ */
9
+ export function checkAddonEntries(workspaceRoot, packageDir) {
10
+ const findings = [];
11
+ const targets = packageDir !== undefined ? [path.resolve(packageDir)] : collectPackageDirs(workspaceRoot);
12
+ for (const pkgDir of targets) {
13
+ checkPackage(pkgDir, findings);
14
+ }
15
+ return {
16
+ ok: findings.every((f) => f.level !== 'error'),
17
+ findings,
18
+ };
19
+ }
20
+ function collectPackageDirs(workspaceRoot) {
21
+ const out = [];
22
+ for (const root of ['packages', 'server']) {
23
+ const rootDir = path.join(workspaceRoot, root);
24
+ if (!fs.existsSync(rootDir))
25
+ continue;
26
+ for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
27
+ if (entry.isDirectory())
28
+ out.push(path.join(rootDir, entry.name));
29
+ }
30
+ }
31
+ return out;
32
+ }
33
+ function viteEntryKeys(pkgDir) {
34
+ const configPath = path.join(pkgDir, 'vite.config.ts');
35
+ if (!fs.existsSync(configPath))
36
+ return null;
37
+ const source = fs.readFileSync(configPath, 'utf-8');
38
+ const block = /entries\s*[:=]\s*\{([\s\S]*?)\n\s*\}/.exec(source);
39
+ if (!block?.[1])
40
+ return null;
41
+ const keys = new Set();
42
+ for (const match of block[1].matchAll(/(?:['"]([^'"]+)['"]|([A-Za-z_$][\w$]*))\s*:/g)) {
43
+ const key = match[1] ?? match[2];
44
+ if (key !== undefined)
45
+ keys.add(key);
46
+ }
47
+ return keys.size > 0 ? keys : null;
48
+ }
49
+ function entryToStem(entry) {
50
+ const match = /^\.?\/?dist\/(.+)\.(?:js|mjs|cjs)$/.exec(entry);
51
+ return match?.[1] ?? null;
52
+ }
53
+ function checkPackage(pkgDir, findings) {
54
+ const pkg = readJsonFile(path.join(pkgDir, 'package.json'));
55
+ if (!pkg)
56
+ return;
57
+ const camstack = asRecord(pkg['camstack']);
58
+ const addons = camstack?.['addons'];
59
+ if (!Array.isArray(addons) || addons.length === 0)
60
+ return;
61
+ const pkgName = typeof pkg['name'] === 'string' ? pkg['name'] : path.basename(pkgDir);
62
+ const entryKeys = viteEntryKeys(pkgDir);
63
+ for (const raw of addons) {
64
+ const addon = asRecord(raw);
65
+ if (!addon)
66
+ continue;
67
+ const addonId = typeof addon['id'] === 'string' ? addon['id'] : '(unnamed)';
68
+ const entry = addon['entry'];
69
+ if (typeof entry !== 'string' || entry.length === 0) {
70
+ findings.push({
71
+ level: 'error',
72
+ code: 'missing-entry',
73
+ message: `${pkgName} → ${addonId}: manifest has no \`entry\``,
74
+ path: pkgDir,
75
+ });
76
+ continue;
77
+ }
78
+ const stem = entryToStem(entry);
79
+ if (stem === null) {
80
+ findings.push({
81
+ level: 'error',
82
+ code: 'bad-entry-shape',
83
+ message: `${pkgName} → ${addonId}: entry \`${entry}\` is not ./dist/<path>.js`,
84
+ path: pkgDir,
85
+ });
86
+ continue;
87
+ }
88
+ const candidates = [`src/${stem}.ts`, `src/${stem}.tsx`, `src/${stem}/index.ts`];
89
+ const sourceRel = candidates.find((c) => fs.existsSync(path.join(pkgDir, c)));
90
+ if (sourceRel === undefined) {
91
+ findings.push({
92
+ level: 'error',
93
+ code: 'missing-source',
94
+ message: `${pkgName} → ${addonId}: entry \`${entry}\` has no source — expected one of ` +
95
+ candidates.join(', '),
96
+ path: pkgDir,
97
+ });
98
+ continue;
99
+ }
100
+ if (entryKeys !== null && !entryKeys.has(stem)) {
101
+ findings.push({
102
+ level: 'error',
103
+ code: 'missing-vite-entry',
104
+ message: `${pkgName} → ${addonId}: entry \`${entry}\` is never built — add ` +
105
+ `'${stem}': '${sourceRel}' to vite.config.ts entries map`,
106
+ path: path.join(pkgDir, 'vite.config.ts'),
107
+ });
108
+ }
109
+ }
110
+ }
@@ -0,0 +1,11 @@
1
+ import type { WorkspacePaths } from './types.js';
2
+ /**
3
+ * Walk up from `cwd` until we find a camstack-server workspace root
4
+ * (package.json with workspaces covering `packages/*`).
5
+ */
6
+ export declare function findWorkspaceRoot(cwd?: string): string | null;
7
+ export declare function resolveWorkspacePaths(root: string): WorkspacePaths;
8
+ export declare function requireWorkspaceRoot(cwd?: string): string;
9
+ export declare function asRecord(value: unknown): Record<string, unknown> | null;
10
+ export declare function readJsonFile(filePath: string): Record<string, unknown> | null;
11
+ //# sourceMappingURL=workspace.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAkB5E;AASD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAMlE;AAED,wBAAgB,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIvE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQ7E"}
@@ -0,0 +1,65 @@
1
+ import * as fs from 'node:fs';
2
+ import * as path from 'node:path';
3
+ /**
4
+ * Walk up from `cwd` until we find a camstack-server workspace root
5
+ * (package.json with workspaces covering `packages/*`).
6
+ */
7
+ export function findWorkspaceRoot(cwd = process.cwd()) {
8
+ let dir = path.resolve(cwd);
9
+ for (;;) {
10
+ const pkgPath = path.join(dir, 'package.json');
11
+ if (fs.existsSync(pkgPath)) {
12
+ try {
13
+ const parsed = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
14
+ if (isWorkspaceRoot(parsed) && fs.existsSync(path.join(dir, 'packages'))) {
15
+ return dir;
16
+ }
17
+ }
18
+ catch {
19
+ /* keep walking */
20
+ }
21
+ }
22
+ const parent = path.dirname(dir);
23
+ if (parent === dir)
24
+ return null;
25
+ dir = parent;
26
+ }
27
+ }
28
+ function isWorkspaceRoot(parsed) {
29
+ if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
30
+ return false;
31
+ const workspaces = parsed.workspaces;
32
+ if (!Array.isArray(workspaces))
33
+ return false;
34
+ return workspaces.some((w) => typeof w === 'string' && w.includes('packages'));
35
+ }
36
+ export function resolveWorkspacePaths(root) {
37
+ return {
38
+ root,
39
+ packagesDir: path.join(root, 'packages'),
40
+ capsDir: path.join(root, 'packages', 'types', 'src', 'capabilities'),
41
+ };
42
+ }
43
+ export function requireWorkspaceRoot(cwd) {
44
+ const root = findWorkspaceRoot(cwd);
45
+ if (!root) {
46
+ throw new Error('Not inside a camstack-server workspace. Run from the repo root (or a subdirectory).');
47
+ }
48
+ return root;
49
+ }
50
+ export function asRecord(value) {
51
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
52
+ ? value
53
+ : null;
54
+ }
55
+ export function readJsonFile(filePath) {
56
+ if (!fs.existsSync(filePath))
57
+ return null;
58
+ try {
59
+ const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
60
+ return asRecord(parsed);
61
+ }
62
+ catch {
63
+ return null;
64
+ }
65
+ }
package/package.json CHANGED
@@ -1,6 +1,44 @@
1
1
  {
2
2
  "name": "@camstack/develop",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.2",
4
+ "description": "CamStack developer tooling — catalogue, scaffold, validate, and example lookup shared by the CLI and MCP server.",
5
+ "keywords": [
6
+ "camstack",
7
+ "develop",
8
+ "addon",
9
+ "scaffold",
10
+ "mcp"
11
+ ],
12
+ "license": "MIT",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "https://github.com/camstack/server"
16
+ },
17
+ "type": "module",
18
+ "main": "./dist/index.js",
19
+ "types": "./dist/index.d.ts",
20
+ "exports": {
21
+ ".": {
22
+ "types": "./dist/index.d.ts",
23
+ "import": "./dist/index.js"
24
+ },
25
+ "./package.json": "./package.json"
26
+ },
27
+ "files": [
28
+ "dist",
29
+ "skills"
30
+ ],
31
+ "scripts": {
32
+ "build": "tsc -p tsconfig.build.json",
33
+ "typecheck": "tsc --noEmit -p tsconfig.spec.json",
34
+ "test": "vitest run"
35
+ },
36
+ "engines": {
37
+ "node": ">=24"
38
+ },
39
+ "devDependencies": {
40
+ "@types/node": "^24",
41
+ "typescript": "~6.0.3",
42
+ "vitest": "^3.0.0"
43
+ }
44
+ }
@@ -0,0 +1,45 @@
1
+ # CamStack developer skill pack
2
+
3
+ Portable markdown procedures for humans and AI agents authoring CamStack
4
+ addons. Same checklist as the server-repo Claude/Cursor skills, sanitized for
5
+ third-party use (no private hostnames, no hub-specific ops).
6
+
7
+ | Skill | File | Job |
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 |
12
+ | `architecture` | [architecture.md](./architecture.md) | Plugin-author architecture pointers |
13
+
14
+ ## How to use
15
+
16
+ ### CLI
17
+
18
+ ```bash
19
+ # From a camstack-server checkout:
20
+ camstack develop skills
21
+ camstack develop skill add-addon
22
+
23
+ # Scaffold / validate with the same tooling agents should call:
24
+ camstack develop scaffold addon my-feature --kind provider
25
+ camstack develop find-example notifier
26
+ camstack develop validate my-feature
27
+ ```
28
+
29
+ ### MCP
30
+
31
+ ```bash
32
+ npx @camstack/mcp-develop
33
+ # or: node packages/mcp-develop/dist/server.js
34
+ ```
35
+
36
+ Tools wrap the same `@camstack/develop` operations (`list_addons`,
37
+ `scaffold_addon`, `validate_addon`, `find_example`, `get_skill`, …).
38
+
39
+ ### Agents
40
+
41
+ Point the agent at this directory (or load individual `.md` files) at session
42
+ start. Prefer CLI/MCP tools over improvising wiring.
43
+
44
+ Published with `@camstack/develop` (`skills/` in the package `files` list).
45
+ Public docs: [Develop → MCP and skills](https://docs.camstack.com/docs/develop/mcp-and-skills).
@@ -0,0 +1,126 @@
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`.
@@ -0,0 +1,89 @@
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.