@camstack/develop 0.1.44 → 0.1.45
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/CHANGELOG.md +6 -0
- package/dist/examples/catalogue.d.ts.map +1 -1
- package/dist/examples/catalogue.js +76 -0
- package/dist/examples/find.js +2 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/scaffold/addon.d.ts.map +1 -1
- package/dist/scaffold/addon.js +104 -10
- package/dist/scaffold/extend.js +5 -4
- package/dist/scaffold/integration-device.d.ts +10 -0
- package/dist/scaffold/integration-device.d.ts.map +1 -0
- package/dist/scaffold/integration-device.js +438 -0
- package/dist/scaffold/integration-exporter.d.ts +9 -0
- package/dist/scaffold/integration-exporter.d.ts.map +1 -0
- package/dist/scaffold/integration-exporter.js +267 -0
- package/dist/scaffold/integration-service.d.ts +7 -0
- package/dist/scaffold/integration-service.d.ts.map +1 -0
- package/dist/scaffold/integration-service.js +153 -0
- package/dist/types.d.ts +9 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +16 -1
- package/package.json +1 -1
- package/skills/camstack-addon.md +36 -1
- package/skills/camstack-capability.md +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.1.45] - 2026-11-05
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- scaffold_addon gains device-integration, service-integration and exporter kinds built on typed integration instances; find_example points at the real implementations and the public addon-examples; traps list the integration rules
|
|
15
|
+
|
|
10
16
|
## [0.1.44] - 2026-11-01
|
|
11
17
|
|
|
12
18
|
### Changed
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"catalogue.d.ts","sourceRoot":"","sources":["../../src/examples/catalogue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,
|
|
1
|
+
{"version":3,"file":"catalogue.d.ts","sourceRoot":"","sources":["../../src/examples/catalogue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EA8KhD,CAAA"}
|
|
@@ -87,6 +87,82 @@ export const CORE_EXAMPLES = [
|
|
|
87
87
|
demonstrates: 'Host shell — merges builtin nav + addon pages.',
|
|
88
88
|
tags: ['admin-ui', 'pages', 'shell', 'nav'],
|
|
89
89
|
},
|
|
90
|
+
{
|
|
91
|
+
id: 'integration-device-enpal',
|
|
92
|
+
packageDir: 'packages/addon-provider-enpal',
|
|
93
|
+
kind: 'device-integration',
|
|
94
|
+
demonstrates: 'Device integration (role devices): instance record with a secret, discovery and adoption, the Gateway adopted as a SIBLING of the equipment, integrationId on every device.',
|
|
95
|
+
tags: [
|
|
96
|
+
'integration',
|
|
97
|
+
'instance',
|
|
98
|
+
'records',
|
|
99
|
+
'secret',
|
|
100
|
+
'adoption',
|
|
101
|
+
'gateway',
|
|
102
|
+
'devices',
|
|
103
|
+
'enpal',
|
|
104
|
+
],
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
id: 'integration-device-example',
|
|
108
|
+
packageDir: 'packages/example-device-integration',
|
|
109
|
+
repository: 'camstack/addon-examples',
|
|
110
|
+
kind: 'device-integration',
|
|
111
|
+
demonstrates: 'Public minimal device integration: typed instance record, test, adoption, Gateway sibling, device-removal-hook.',
|
|
112
|
+
tags: ['integration', 'instance', 'public', 'example', 'devices', 'adoption', 'gateway'],
|
|
113
|
+
},
|
|
114
|
+
{
|
|
115
|
+
id: 'integration-service-cloudflare',
|
|
116
|
+
packageDir: 'packages/addon-cloudflare',
|
|
117
|
+
kind: 'service-integration',
|
|
118
|
+
demonstrates: 'Service integrations (role services): a typed connection with a secret and a test, no devices.',
|
|
119
|
+
tags: ['integration', 'instance', 'services', 'secret', 'test', 'connection'],
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
id: 'integration-service-google',
|
|
123
|
+
packageDir: 'packages/addon-google-services',
|
|
124
|
+
kind: 'service-integration',
|
|
125
|
+
demonstrates: 'Service integration records served through integration-instances.',
|
|
126
|
+
tags: ['integration', 'instance', 'services', 'records', 'google'],
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
id: 'integration-service-example',
|
|
130
|
+
packageDir: 'packages/example-service-integration',
|
|
131
|
+
repository: 'camstack/addon-examples',
|
|
132
|
+
kind: 'service-integration',
|
|
133
|
+
demonstrates: 'Public minimal service integration: typed connection, password secret, test, no devices.',
|
|
134
|
+
tags: ['integration', 'instance', 'public', 'example', 'services', 'secret', 'test'],
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
id: 'exporter-ha-export',
|
|
138
|
+
packageDir: 'packages/addon-provider-homeassistant/src/ha-export',
|
|
139
|
+
kind: 'exporter',
|
|
140
|
+
demonstrates: 'Exporter: export targets are integration instances with minted ids, exposure keyed by instance id (target-instances.ts).',
|
|
141
|
+
tags: [
|
|
142
|
+
'exporter',
|
|
143
|
+
'export',
|
|
144
|
+
'device-export',
|
|
145
|
+
'instance',
|
|
146
|
+
'target',
|
|
147
|
+
'multi-instance',
|
|
148
|
+
'homeassistant',
|
|
149
|
+
],
|
|
150
|
+
},
|
|
151
|
+
{
|
|
152
|
+
id: 'exporter-hap',
|
|
153
|
+
packageDir: 'packages/addon-export-hap',
|
|
154
|
+
kind: 'exporter',
|
|
155
|
+
demonstrates: 'Exporter with several bridges, each an integration instance.',
|
|
156
|
+
tags: ['exporter', 'export', 'device-export', 'instance', 'homekit', 'hap'],
|
|
157
|
+
},
|
|
158
|
+
{
|
|
159
|
+
id: 'exporter-example',
|
|
160
|
+
packageDir: 'packages/example-exporter',
|
|
161
|
+
repository: 'camstack/addon-examples',
|
|
162
|
+
kind: 'exporter',
|
|
163
|
+
demonstrates: 'Public minimal exporter: device-export + integration-instances, minted ids, action button in the instance form.',
|
|
164
|
+
tags: ['exporter', 'export', 'public', 'example', 'device-export', 'instance', 'target'],
|
|
165
|
+
},
|
|
90
166
|
{
|
|
91
167
|
id: 'system-builtins',
|
|
92
168
|
packageDir: 'packages/system',
|
package/dist/examples/find.js
CHANGED
|
@@ -60,8 +60,9 @@ function scoreExample(example, tokens, workspaceRoot) {
|
|
|
60
60
|
reasons.push(`text~${token}`);
|
|
61
61
|
}
|
|
62
62
|
}
|
|
63
|
+
// A public example lives in another repository: there is nothing to look for in this checkout.
|
|
63
64
|
const abs = path.join(workspaceRoot, example.packageDir);
|
|
64
|
-
if (!fs.existsSync(abs)) {
|
|
65
|
+
if (example.repository === undefined && !fs.existsSync(abs)) {
|
|
65
66
|
score = Math.max(0, score - 2);
|
|
66
67
|
reasons.push('package missing in this checkout');
|
|
67
68
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
/** @camstack/develop — shared developer tooling for CLI + MCP. */
|
|
2
|
-
export type { AddonCapabilityRef, AddonManifestEntry, AddonPackageSummary, CapabilitySummary, ExampleEntry, ExampleHit, ExtendAddonOptions, ExtendAddonResult, ScaffoldAddonOptions, ScaffoldAddonResult, ScaffoldCapOptions, ScaffoldCapResult, SkillInfo, ValidationFinding, ValidationResult, WorkspacePaths, } from './types.js';
|
|
2
|
+
export type { AddonCapabilityRef, AddonManifestEntry, AddonPackageSummary, CapabilitySummary, ExampleEntry, ExampleHit, ExtendAddonOptions, ExtendAddonResult, ScaffoldAddonOptions, ScaffoldAddonResult, ScaffoldKind, ScaffoldCapOptions, ScaffoldCapResult, SkillInfo, ValidationFinding, ValidationResult, WorkspacePaths, } from './types.js';
|
|
3
|
+
export { SCAFFOLD_KINDS, isScaffoldKind } from './types.js';
|
|
3
4
|
export { findWorkspaceRoot, requireWorkspaceRoot, resolveWorkspacePaths, } from './workspace.js';
|
|
4
5
|
export { toCamelName, toCapExportName, toClassName, toFileName, } from './naming.js';
|
|
5
6
|
export { findAddonPackage, listAddonPackages, whoProvides, } from './catalogue/addons.js';
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,GACf,MAAM,YAAY,CAAA;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
/** @camstack/develop — shared developer tooling for CLI + MCP. */
|
|
2
|
+
export { SCAFFOLD_KINDS, isScaffoldKind } from './types.js';
|
|
2
3
|
export { findWorkspaceRoot, requireWorkspaceRoot, resolveWorkspacePaths, } from './workspace.js';
|
|
3
4
|
export { toCamelName, toCapExportName, toClassName, toFileName, } from './naming.js';
|
|
4
5
|
export { findAddonPackage, listAddonPackages, whoProvides, } from './catalogue/addons.js';
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"addon.d.ts","sourceRoot":"","sources":["../../src/scaffold/addon.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;
|
|
1
|
+
{"version":3,"file":"addon.d.ts","sourceRoot":"","sources":["../../src/scaffold/addon.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAkH5E;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,mBAAmB,CA6GhF"}
|
package/dist/scaffold/addon.js
CHANGED
|
@@ -2,6 +2,9 @@ import * as fs from 'node:fs';
|
|
|
2
2
|
import * as path from 'node:path';
|
|
3
3
|
import { toClassName, toFileName } from '../naming.js';
|
|
4
4
|
import { CORE_EXAMPLES } from '../examples/catalogue.js';
|
|
5
|
+
import { DEVICE_ADDON_TS, DEVICE_ADOPTION_TS, DEVICE_DEVICES_TS, DEVICE_INSTANCES_TS, } from './integration-device.js';
|
|
6
|
+
import { EXPORTER_ADDON_TS, EXPORTER_INSTANCES_TS } from './integration-exporter.js';
|
|
7
|
+
import { SERVICE_ADDON_TS, SERVICE_INSTANCES_TS } from './integration-service.js';
|
|
5
8
|
import { renderTemplate } from './templates.js';
|
|
6
9
|
const KIND_EXAMPLE = {
|
|
7
10
|
empty: null,
|
|
@@ -11,7 +14,83 @@ const KIND_EXAMPLE = {
|
|
|
11
14
|
'post-analysis': 'post-analysis',
|
|
12
15
|
'model-studio': 'model-studio',
|
|
13
16
|
'admin-ui': 'admin-ui',
|
|
17
|
+
'device-integration': 'provider-enpal',
|
|
18
|
+
'service-integration': 'integration-service',
|
|
19
|
+
exporter: 'ha-export',
|
|
14
20
|
};
|
|
21
|
+
const INTEGRATION_NOTES = [
|
|
22
|
+
'Public examples: `camstack/addon-examples` (`example-device-integration`, `example-service-integration`, `example-exporter`).',
|
|
23
|
+
'',
|
|
24
|
+
'Integration rules (D1007, D996, D1009):',
|
|
25
|
+
'- The integration is a typed instance record served through `integration-instances`; a secret is a `password` field (`.meta({ secret: true })` on the kind).',
|
|
26
|
+
'- No `globalSettingsSchema()`, no `integration_settings`, no `integrations.getSettings` / `setSettings` (retired).',
|
|
27
|
+
'- Data changes go through a D987 migration with read-back, never a dual read path.',
|
|
28
|
+
'- The Gateway is a SIBLING of the devices it brings, never their parent.',
|
|
29
|
+
'- An exporter provides `integration-instances` and is multi-instance: minted ids, exposure keyed by instance id.',
|
|
30
|
+
'',
|
|
31
|
+
];
|
|
32
|
+
function integrationPlan(kind, fileName) {
|
|
33
|
+
switch (kind) {
|
|
34
|
+
case 'device-integration':
|
|
35
|
+
return {
|
|
36
|
+
manifestFields: [
|
|
37
|
+
'"integrationRole": "devices"',
|
|
38
|
+
'"instanceMode": "multiple"',
|
|
39
|
+
'"mode": "account"',
|
|
40
|
+
],
|
|
41
|
+
capabilities: [
|
|
42
|
+
'device-provider',
|
|
43
|
+
'integration-instances',
|
|
44
|
+
'device-adoption',
|
|
45
|
+
'device-removal-hook',
|
|
46
|
+
],
|
|
47
|
+
category: 'providers',
|
|
48
|
+
files: [
|
|
49
|
+
{ relative: `src/${fileName}.addon.ts`, template: DEVICE_ADDON_TS },
|
|
50
|
+
{
|
|
51
|
+
relative: `src/${fileName}-instances.ts`,
|
|
52
|
+
template: DEVICE_INSTANCES_TS,
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
relative: `src/${fileName}-devices.ts`,
|
|
56
|
+
template: DEVICE_DEVICES_TS,
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
relative: `src/${fileName}-adoption.ts`,
|
|
60
|
+
template: DEVICE_ADOPTION_TS,
|
|
61
|
+
},
|
|
62
|
+
],
|
|
63
|
+
};
|
|
64
|
+
case 'service-integration':
|
|
65
|
+
return {
|
|
66
|
+
manifestFields: ['"integrationRole": "services"', '"instanceMode": "multiple"'],
|
|
67
|
+
capabilities: ['integration-instances'],
|
|
68
|
+
category: 'messaging',
|
|
69
|
+
files: [
|
|
70
|
+
{ relative: `src/${fileName}.addon.ts`, template: SERVICE_ADDON_TS },
|
|
71
|
+
{
|
|
72
|
+
relative: `src/${fileName}-instances.ts`,
|
|
73
|
+
template: SERVICE_INSTANCES_TS,
|
|
74
|
+
},
|
|
75
|
+
],
|
|
76
|
+
};
|
|
77
|
+
case 'exporter':
|
|
78
|
+
return {
|
|
79
|
+
manifestFields: ['"integrationRole": "services"', '"instanceMode": "multiple"'],
|
|
80
|
+
capabilities: ['device-export', 'integration-instances'],
|
|
81
|
+
category: 'messaging',
|
|
82
|
+
files: [
|
|
83
|
+
{ relative: `src/${fileName}.addon.ts`, template: EXPORTER_ADDON_TS },
|
|
84
|
+
{
|
|
85
|
+
relative: `src/${fileName}-instances.ts`,
|
|
86
|
+
template: EXPORTER_INSTANCES_TS,
|
|
87
|
+
},
|
|
88
|
+
],
|
|
89
|
+
};
|
|
90
|
+
default:
|
|
91
|
+
return null;
|
|
92
|
+
}
|
|
93
|
+
}
|
|
15
94
|
/**
|
|
16
95
|
* Scaffold a new addon package under `packages/addon-<name>/`.
|
|
17
96
|
* Aligned with `@camstack/nx-plugin:addon` templates, plus a vite.config.ts
|
|
@@ -35,6 +114,12 @@ export function scaffoldAddon(options) {
|
|
|
35
114
|
description,
|
|
36
115
|
projectRoot: path.relative(options.workspaceRoot, projectRoot).replace(/\\/g, '/'),
|
|
37
116
|
};
|
|
117
|
+
const plan = integrationPlan(kind, fileName);
|
|
118
|
+
vars['extraFields'] = (plan?.manifestFields ?? []).map((f) => `\n ${f},`).join('');
|
|
119
|
+
vars['categoryField'] = plan ? `\n "category": "${plan.category}",` : '';
|
|
120
|
+
vars['capabilities'] = JSON.stringify((plan?.capabilities ?? []).map((name) => ({ name })), null, 2)
|
|
121
|
+
.split('\n')
|
|
122
|
+
.join('\n ');
|
|
38
123
|
const files = [
|
|
39
124
|
{ relative: 'package.json', content: renderTemplate(PACKAGE_JSON, vars) },
|
|
40
125
|
{ relative: 'README.md', content: renderTemplate(README_MD, vars) },
|
|
@@ -42,10 +127,17 @@ export function scaffoldAddon(options) {
|
|
|
42
127
|
{ relative: 'tsconfig.json', content: renderTemplate(TSCONFIG, vars) },
|
|
43
128
|
{ relative: 'vite.config.ts', content: renderTemplate(VITE_CONFIG, vars) },
|
|
44
129
|
{ relative: 'src/index.ts', content: renderTemplate(INDEX_TS, vars) },
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
130
|
+
...(plan
|
|
131
|
+
? plan.files.map((f) => ({
|
|
132
|
+
relative: f.relative,
|
|
133
|
+
content: renderTemplate(f.template, vars),
|
|
134
|
+
}))
|
|
135
|
+
: [
|
|
136
|
+
{
|
|
137
|
+
relative: `src/${fileName}.addon.ts`,
|
|
138
|
+
content: renderTemplate(ADDON_TS, vars),
|
|
139
|
+
},
|
|
140
|
+
]),
|
|
49
141
|
];
|
|
50
142
|
const exampleId = KIND_EXAMPLE[kind];
|
|
51
143
|
const example = exampleId ? CORE_EXAMPLES.find((e) => e.id === exampleId) : undefined;
|
|
@@ -59,6 +151,7 @@ export function scaffoldAddon(options) {
|
|
|
59
151
|
'',
|
|
60
152
|
`- \`${example.packageDir}\` — ${example.demonstrates}`,
|
|
61
153
|
'',
|
|
154
|
+
...(plan ? INTEGRATION_NOTES : []),
|
|
62
155
|
'Rules:',
|
|
63
156
|
'- One addon = one process (shared `execution.group` only when allowed).',
|
|
64
157
|
'- Never import another addon; use `ctx.api`.',
|
|
@@ -127,14 +220,14 @@ const PACKAGE_JSON = `{
|
|
|
127
220
|
"displayName": "<%= displayName %>",
|
|
128
221
|
"addons": [
|
|
129
222
|
{
|
|
130
|
-
"id": "<%= fileName %>"
|
|
223
|
+
"id": "<%= fileName %>",<%= extraFields %><%= categoryField %>
|
|
131
224
|
"name": "<%= displayName %>",
|
|
132
225
|
"description": "<%= description %>",
|
|
133
226
|
"entry": "./dist/<%= fileName %>.addon.js",
|
|
134
227
|
"execution": {
|
|
135
228
|
"placement": "hub-only"
|
|
136
229
|
},
|
|
137
|
-
"capabilities":
|
|
230
|
+
"capabilities": <%= capabilities %>
|
|
138
231
|
}
|
|
139
232
|
]
|
|
140
233
|
},
|
|
@@ -228,10 +321,11 @@ const ADDON_TS = `/**
|
|
|
228
321
|
*/
|
|
229
322
|
import { BaseAddon, type ProviderRegistration } from '@camstack/types'
|
|
230
323
|
|
|
231
|
-
//
|
|
232
|
-
//
|
|
233
|
-
//
|
|
234
|
-
//
|
|
324
|
+
// An addon has no settings page of its own (D1007). What an operator
|
|
325
|
+
// configures is an integration INSTANCE (scaffold kind device-integration,
|
|
326
|
+
// service-integration or exporter); a per-device setting lives in
|
|
327
|
+
// ctx.settings.*DeviceStore. No on/off switch: the capability toggle is an
|
|
328
|
+
// addon's ONE enable (D777).
|
|
235
329
|
type <%= className %>Config = Readonly<Record<string, never>>
|
|
236
330
|
|
|
237
331
|
const DEFAULTS: <%= className %>Config = {}
|
package/dist/scaffold/extend.js
CHANGED
|
@@ -140,10 +140,11 @@ const ADDON_TS = `/**
|
|
|
140
140
|
*/
|
|
141
141
|
import { BaseAddon, type ProviderRegistration } from '@camstack/types'
|
|
142
142
|
|
|
143
|
-
//
|
|
144
|
-
//
|
|
145
|
-
//
|
|
146
|
-
//
|
|
143
|
+
// An addon has no settings page of its own (D1007). What an operator
|
|
144
|
+
// configures is an integration INSTANCE (scaffold kind device-integration,
|
|
145
|
+
// service-integration or exporter); a per-device setting lives in
|
|
146
|
+
// ctx.settings.*DeviceStore. No on/off switch: the capability toggle is an
|
|
147
|
+
// addon's ONE enable (D777).
|
|
147
148
|
type <%= className %>Config = Readonly<Record<string, never>>
|
|
148
149
|
|
|
149
150
|
const DEFAULTS: <%= className %>Config = {}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Templates of the `device-integration` scaffold (D1007, D996, D865): an addon whose integration
|
|
3
|
+
* is a typed instance record (connection + secret + test) and which brings devices. The
|
|
4
|
+
* integration's Gateway device is a SIBLING of the devices it brings, never their parent.
|
|
5
|
+
*/
|
|
6
|
+
export declare const DEVICE_INSTANCES_TS = "/**\n * <%= displayName %> integrations as `integration-instances` (D1007): one `connections` record per\n * integration, keyed by the registry id, holding the connection to ONE <%= displayName %> system. The\n * token is a secret by TYPE; the records door keeps it in the keychain. The Gateway device is not\n * part of the record: it is a device OF the integration, adopted from it.\n */\nimport {\n type ConfigUISchema,\n defineEntryKind,\n entryBody,\n type IntegrationTestConnectionResult,\n RecordIntegrationInstances,\n type RecordsAccess,\n} from '@camstack/types'\nimport { z } from 'zod'\n\nexport const <%= className %>ConnectionsKind = defineEntryKind('connections', {\n title: '<%= displayName %> integrations',\n schema: entryBody({\n host: z.string().optional(),\n token: z.string().optional().meta({ secret: true }),\n }),\n writeTrigger: 'an operator adds, edits or removes a <%= displayName %> integration',\n})\nexport type <%= className %>ConnectionBody = z.infer<typeof <%= className %>ConnectionsKind.schema>\n\n/** Every record kind this addon declares, keyed by its name. */\nexport const <%= className %>RecordKinds = { connections: <%= className %>ConnectionsKind } as const\n\nexport function build<%= className %>ConnectionForm(): ConfigUISchema {\n return {\n sections: [\n {\n id: 'connection',\n title: 'Connection',\n columns: 1,\n fields: [\n { type: 'text', key: 'name', label: 'Name' },\n { type: 'text', key: 'host', label: 'Host' },\n { type: 'password', key: 'token', label: 'Token', showToggle: true },\n ],\n },\n ],\n }\n}\n\nexport interface <%= className %>InstanceDeps {\n /** Re-apply the runtime from the records after a create, update, enable or delete. */\n readonly onChanged: () => Promise<void>\n /** Probe the remote with the (possibly unsaved) values; a failed probe is not a pass. */\n readonly probe: (values: Readonly<Record<string, unknown>>) => Promise<IntegrationTestConnectionResult>\n}\n\nexport function build<%= className %>Instances(\n records: Pick<RecordsAccess, 'kind' | 'owner'>,\n deps: <%= className %>InstanceDeps,\n): RecordIntegrationInstances<<%= className %>ConnectionBody> {\n return new RecordIntegrationInstances<<%= className %>ConnectionBody>(\n records,\n <%= className %>ConnectionsKind,\n {\n description: {\n role: 'devices',\n discovery: { mode: 'account', scopedToInstance: true },\n instanceMode: 'multiple',\n kind: 'server',\n canTest: true,\n },\n formSchema: () => build<%= className %>ConnectionForm(),\n initialBody: (name): <%= className %>ConnectionBody => ({ name }),\n configured: (body) => (body.host ?? '').length > 0,\n onChanged: () => deps.onChanged(),\n test: ({ values }) => deps.probe(values),\n },\n )\n}\n";
|
|
7
|
+
export declare const DEVICE_DEVICES_TS = "/**\n * The devices of an integration. Every one carries its `integrationId` in its persisted config, so\n * a cascade can find what an integration owns. The Gateway is the integration's own presence in the\n * device list and a SIBLING of the sensors: nothing is its child.\n *\n * Per-device configuration lives ONLY in `ctx.settings.*DeviceStore`, never in a field of the\n * addon's own storage (D865).\n */\nimport { BaseDevice, type DeviceContext, type DeviceFeature, DeviceType } from '@camstack/types'\nimport { z } from 'zod'\n\nexport const <%= className %>_SYSTEM = '<%= fileName %>'\nexport const <%= className %>_GATEWAY_ID = 'gateway'\n\nexport const <%= className %>GatewaySchema = z.object({\n equipment: z.literal(<%= className %>_GATEWAY_ID),\n integrationId: z.string().min(1).describe('Owning integration'),\n system: z.literal(<%= className %>_SYSTEM).optional(),\n})\n\nexport class <%= className %>GatewayDevice extends BaseDevice<typeof <%= className %>GatewaySchema> {\n readonly features: readonly DeviceFeature[] = []\n\n constructor(ctx: DeviceContext) {\n <%= className %>GatewaySchema.parse(ctx.persistedConfig ?? {})\n super(ctx, <%= className %>GatewaySchema, { type: DeviceType.Gateway })\n }\n}\n\nexport const <%= className %>SensorSchema = z.object({\n equipment: z.string().min(1).describe('Remote id of the sensor'),\n integrationId: z.string().min(1).describe('Owning integration'),\n system: z.literal(<%= className %>_SYSTEM).optional(),\n})\n\nexport class <%= className %>SensorDevice extends BaseDevice<typeof <%= className %>SensorSchema> {\n readonly features: readonly DeviceFeature[] = []\n\n constructor(ctx: DeviceContext) {\n <%= className %>SensorSchema.parse(ctx.persistedConfig ?? {})\n super(ctx, <%= className %>SensorSchema, { type: DeviceType.Sensor })\n }\n}\n";
|
|
8
|
+
export declare const DEVICE_ADOPTION_TS = "/**\n * Discovery and adoption for <%= displayName %>. The Gateway and every sensor are offered as\n * SIBLING candidates (the Gateway is never the parent of the sensors); adopting one creates a\n * top-level device carrying the integration id. Replace `discover` with a real read of the remote.\n */\nimport {\n DeviceType,\n type DiscoveredChildDevice,\n errMsg,\n type IDeviceAdoptionProvider,\n type IScopedLogger,\n} from '@camstack/types'\nimport { <%= className %>_GATEWAY_ID } from './<%= fileName %>-devices.js'\n\nexport interface RemoteSensor {\n readonly id: string\n readonly name: string\n}\n\nexport interface <%= className %>AdoptionDeps {\n readonly hasIntegration: (integrationId: string) => Promise<boolean>\n readonly listIntegrations: () => Promise<readonly string[]>\n /** What the remote reports for the integration, or null while it is unreachable. */\n readonly discover: (integrationId: string) => Promise<readonly RemoteSensor[] | null>\n /** Remote ids of the devices already adopted for the integration, with their device id. */\n readonly adopted: (integrationId: string) => Promise<ReadonlyMap<string, number>>\n readonly create: (input: {\n readonly integrationId: string\n readonly equipment: string\n readonly type: DeviceType.Gateway | DeviceType.Sensor\n readonly name: string\n }) => Promise<number>\n readonly remove: (deviceId: number) => Promise<void>\n readonly logger: IScopedLogger\n}\n\nexport function build<%= className %>AdoptionProvider(\n deps: <%= className %>AdoptionDeps,\n): IDeviceAdoptionProvider {\n async function candidates(integrationId: string): Promise<readonly DiscoveredChildDevice[]> {\n const sensors = await deps.discover(integrationId)\n const adopted = await deps.adopted(integrationId)\n const offered: DiscoveredChildDevice[] = [\n {\n childNativeId: <%= className %>_GATEWAY_ID,\n name: '<%= displayName %>',\n type: DeviceType.Gateway,\n status: sensors === null ? 'offline' : 'online',\n metadata: {},\n alreadyAdopted: adopted.has(<%= className %>_GATEWAY_ID),\n adoptedDeviceId: adopted.get(<%= className %>_GATEWAY_ID) ?? null,\n capabilities: [],\n },\n ]\n for (const sensor of sensors ?? []) {\n offered.push({\n childNativeId: sensor.id,\n name: sensor.name,\n type: DeviceType.Sensor,\n status: 'online',\n metadata: {},\n alreadyAdopted: adopted.has(sensor.id),\n adoptedDeviceId: adopted.get(sensor.id) ?? null,\n capabilities: [],\n })\n }\n return offered\n }\n\n async function status(integrationId: string) {\n const all = await candidates(integrationId)\n return {\n lastDiscoveryAt: Date.now(),\n candidateCount: all.length,\n adoptedCount: all.filter((c) => c.alreadyAdopted).length,\n lastError: null,\n }\n }\n\n return {\n listCandidateFilters: async () => ({\n filters: [{ id: 'devices', label: 'Devices', isDefault: true }],\n }),\n listCandidates: async ({ integrationId, page, pageSize }) => {\n const all = await candidates(integrationId)\n const start = (page - 1) * pageSize\n return {\n candidates: all.slice(start, start + pageSize),\n totalCount: all.length,\n page,\n pageSize,\n }\n },\n getCandidate: async ({ integrationId, childNativeId }) =>\n (await candidates(integrationId)).find((c) => c.childNativeId === childNativeId) ?? null,\n getStatus: async () => {\n try {\n let candidateCount = 0\n let adoptedCount = 0\n for (const integrationId of await deps.listIntegrations()) {\n const s = await status(integrationId)\n candidateCount += s.candidateCount\n adoptedCount += s.adoptedCount\n }\n return { lastDiscoveryAt: Date.now(), candidateCount, adoptedCount, lastError: null }\n } catch (err: unknown) {\n return { lastDiscoveryAt: null, candidateCount: 0, adoptedCount: 0, lastError: errMsg(err) }\n }\n },\n refresh: async ({ integrationId }) => status(integrationId),\n adopt: async ({ integrationId, childNativeIds, perCandidate }) => {\n if (!(await deps.hasIntegration(integrationId))) {\n throw new Error('<%= fileName %> adopt: integration ' + integrationId + ' not found')\n }\n const offered = await candidates(integrationId)\n const adopted: Array<{\n readonly childNativeId: string\n readonly parentDeviceId: number\n readonly accessoryDeviceIds: readonly number[]\n }> = []\n for (const childNativeId of childNativeIds) {\n const candidate = offered.find((c) => c.childNativeId === childNativeId)\n if (candidate === undefined) {\n deps.logger.warn('<%= fileName %> adopt: the remote reports nothing for this id', {\n meta: { childNativeId, integrationId },\n })\n continue\n }\n const deviceId = await deps.create({\n integrationId,\n equipment: childNativeId,\n type: candidate.type === DeviceType.Gateway ? DeviceType.Gateway : DeviceType.Sensor,\n name: perCandidate?.[childNativeId]?.name ?? candidate.name,\n })\n adopted.push({ childNativeId, parentDeviceId: deviceId, accessoryDeviceIds: [] })\n }\n if (adopted.length === 0) throw new Error('<%= fileName %> adopt: nothing was adopted')\n return { adopted }\n },\n release: async ({ camDeviceId }) => {\n await deps.remove(camDeviceId)\n },\n resync: async () => ({ changed: false, rebuiltChildren: 0 }),\n }\n}\n";
|
|
9
|
+
export declare const DEVICE_ADDON_TS = "/**\n * <%= displayName %> \u2014 a device integration (role `devices`, D996). An integration is one typed\n * connection record (secret + test) served through `integration-instances`; the devices it brings\n * are adopted from it and carry its `integrationId`. There is no addon-level settings page and no\n * legacy settings row: if the operator can configure it, it is an instance.\n *\n * Deleting a device is learned through `device-removal-hook` (a tombstone, D865), never from the\n * device missing from a list. A failed read of the remote changes nothing (D49).\n */\nimport {\n type AddonInitResult,\n BaseDeviceProvider,\n type ConfigUISchema,\n type CreateDeviceSpec,\n type DeviceConstructor,\n DeviceType,\n deviceAdoptionCapability,\n deviceRemovalHookCapability,\n type IDevice,\n type IntegrationTestConnectionResult,\n integrationInstancesCapability,\n type RecordIntegrationInstances,\n} from '@camstack/types'\nimport { build<%= className %>AdoptionProvider } from './<%= fileName %>-adoption.js'\nimport {\n <%= className %>_SYSTEM,\n <%= className %>GatewayDevice,\n <%= className %>SensorDevice,\n} from './<%= fileName %>-devices.js'\nimport {\n build<%= className %>Instances,\n <%= className %>RecordKinds,\n type <%= className %>ConnectionBody,\n} from './<%= fileName %>-instances.js'\n\nexport class <%= className %>Addon extends BaseDeviceProvider {\n protected readonly addonId = '<%= fileName %>'\n protected readonly providerName = '<%= displayName %>'\n // The Gateway and the sensors are siblings: both are restored as top-level devices.\n protected readonly deviceClasses: Partial<Record<DeviceType, DeviceConstructor<IDevice>>> = {\n [DeviceType.Gateway]: <%= className %>GatewayDevice,\n [DeviceType.Sensor]: <%= className %>SensorDevice,\n }\n\n constructor() {\n super({})\n }\n\n protected override async onInitialize(): Promise<AddonInitResult> {\n const regs = this.providerRegistrationsFromSuper(await super.onInitialize())\n const records = this.ctx.records\n if (records === undefined) {\n throw new Error('<%= fileName %>: ctx.records is required (hub-only addon)')\n }\n await records.declare(<%= className %>RecordKinds)\n const instances = build<%= className %>Instances(records, {\n onChanged: async () => {\n this.ctx.logger.info('<%= displayName %> integrations changed')\n },\n probe: (values) => this.probe(values),\n })\n return {\n providers: [\n ...regs,\n { capability: deviceAdoptionCapability, provider: this.buildAdoptionProvider(instances) },\n { capability: integrationInstancesCapability, provider: instances.toProvider() },\n {\n capability: deviceRemovalHookCapability,\n // Device DATA only (footage, history, rows). Settings are cleared centrally. Idempotent.\n provider: {\n onDeviceRemoved: async () => ({ counts: {} }),\n listDeviceData: async () => [],\n },\n },\n ],\n }\n }\n\n /** Replace with a real call to the remote; `rejected` is a definite no, `inconclusive` is \"could not tell\". */\n private async probe(\n values: Readonly<Record<string, unknown>>,\n ): Promise<IntegrationTestConnectionResult> {\n const host = values['host']\n if (typeof host !== 'string' || host.length === 0) {\n return { success: false, status: 'rejected', error: 'Host is required' }\n }\n return { success: true, status: 'validated' }\n }\n\n private buildAdoptionProvider(\n instances: RecordIntegrationInstances<<%= className %>ConnectionBody>,\n ) {\n return build<%= className %>AdoptionProvider({\n hasIntegration: async (integrationId) => (await instances.readResolved(integrationId)) !== null,\n listIntegrations: async () => (await instances.listResolved()).map((read) => read.id),\n discover: async (integrationId) => {\n const read = await instances.readResolved(integrationId)\n if (read === null) return null\n // Replace with a real read of the remote using read.body (host, token).\n return []\n },\n adopted: async (integrationId) => {\n const reg = this.ctx.kernel.deviceRegistry\n const devices = this.ctx.kernel.devices\n const out = new Map<string, number>()\n if (!reg || !devices) return out\n for (const d of reg.getAllForAddon(this.addonId)) {\n const config = await devices.loadConfig(d.id).catch((): Record<string, unknown> => ({}))\n if (config['integrationId'] !== integrationId) continue\n const equipment = config['equipment']\n if (typeof equipment === 'string') out.set(equipment, d.id)\n }\n return out\n },\n create: async ({ integrationId, equipment, type, name }) => {\n const devices = this.ctx.kernel.devices\n if (!devices) throw new Error('<%= fileName %> adopt: kernel.devices unavailable')\n const config = { equipment, integrationId, system: <%= className %>_SYSTEM }\n const stableId = this.generateStableId(type, config)\n const meta = { type, name, integrationId }\n const device =\n type === DeviceType.Gateway\n ? await devices.create(stableId, <%= className %>GatewayDevice, config, null, meta)\n : await devices.create(stableId, <%= className %>SensorDevice, config, null, meta)\n return device.id\n },\n remove: async (id) => {\n await this.ctx.kernel.devices?.remove(id)\n },\n logger: this.ctx.logger,\n })\n }\n\n protected override generateStableId(\n _type: DeviceType,\n config?: Record<string, unknown>,\n ): string {\n const integrationId = config?.['integrationId']\n const equipment = config?.['equipment']\n if (typeof integrationId !== 'string' || integrationId.length === 0) {\n throw new Error('<%= fileName %> generateStableId: integrationId required')\n }\n if (typeof equipment !== 'string' || equipment.length === 0) {\n throw new Error('<%= fileName %> generateStableId: equipment required')\n }\n return '<%= fileName %>:' + integrationId + ':' + equipment\n }\n\n override async supportsManualCreation(): Promise<boolean> {\n return false\n }\n\n protected async onGetCreationSchema(_type: DeviceType): Promise<ConfigUISchema | null> {\n return null\n }\n\n protected async onCreateDevice(\n _type: DeviceType,\n _config: Record<string, unknown>,\n ): Promise<CreateDeviceSpec> {\n throw new Error('<%= displayName %> devices are adopted from the integration')\n }\n}\n\nexport default <%= className %>Addon\n";
|
|
10
|
+
//# sourceMappingURL=integration-device.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"integration-device.d.ts","sourceRoot":"","sources":["../../src/scaffold/integration-device.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,mBAAmB,u1FA4E/B,CAAA;AAED,eAAO,MAAM,iBAAiB,wzDA2C7B,CAAA;AAED,eAAO,MAAM,kBAAkB,ikLAiJ9B,CAAA;AAED,eAAO,MAAM,eAAe,miNAqK3B,CAAA"}
|