@glassly/miniapp-cli 0.1.0-dev.1

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.
@@ -0,0 +1,322 @@
1
+ import {describe, expect, test} from 'bun:test';
2
+ import {validateManifest} from './manifest';
3
+
4
+ const minimalValid = {
5
+ packageName: 'com.example.app',
6
+ version: '1.0.0',
7
+ name: 'Example',
8
+ hardwareRequirements: [{type: 'DISPLAY', level: 'REQUIRED'}],
9
+ };
10
+
11
+ describe('validateManifest', () => {
12
+ test('accepts a minimal valid manifest', () => {
13
+ const {valid, errors} = validateManifest(minimalValid);
14
+ expect(valid).toBe(true);
15
+ expect(errors).toEqual([]);
16
+ });
17
+
18
+ test('rejects non-object input', () => {
19
+ expect(validateManifest(null).valid).toBe(false);
20
+ expect(validateManifest('not an object').valid).toBe(false);
21
+ expect(validateManifest(42).valid).toBe(false);
22
+ });
23
+
24
+ describe('required top-level fields', () => {
25
+ test('packageName must be a non-empty string', () => {
26
+ const {errors} = validateManifest({...minimalValid, packageName: ''});
27
+ expect(errors.some((e) => e.includes('packageName'))).toBe(true);
28
+ });
29
+
30
+ test('version must be a non-empty string', () => {
31
+ const {errors} = validateManifest({...minimalValid, version: ''});
32
+ expect(errors.some((e) => e.includes('version'))).toBe(true);
33
+ });
34
+
35
+ test('name must be a non-empty string', () => {
36
+ const {errors} = validateManifest({...minimalValid, name: undefined});
37
+ expect(errors.some((e) => e.includes('name'))).toBe(true);
38
+ });
39
+ });
40
+
41
+ describe('hardwareRequirements (required)', () => {
42
+ test('missing field fails with a helpful message', () => {
43
+ const m = {...minimalValid} as Record<string, unknown>;
44
+ delete m.hardwareRequirements;
45
+ const {valid, errors} = validateManifest(m);
46
+ expect(valid).toBe(false);
47
+ expect(errors.some((e) => e.includes('hardwareRequirements is required'))).toBe(true);
48
+ expect(errors.some((e) => e.includes('DISPLAY'))).toBe(true); // listed example
49
+ });
50
+
51
+ test('empty array is allowed', () => {
52
+ const {valid} = validateManifest({...minimalValid, hardwareRequirements: []});
53
+ expect(valid).toBe(true);
54
+ });
55
+
56
+ test('non-array fails', () => {
57
+ const {errors} = validateManifest({
58
+ ...minimalValid,
59
+ hardwareRequirements: 'DISPLAY' as unknown as never,
60
+ });
61
+ expect(errors.some((e) => e.includes('must be an array'))).toBe(true);
62
+ });
63
+
64
+ test('unknown hardware type is rejected', () => {
65
+ const {errors} = validateManifest({
66
+ ...minimalValid,
67
+ hardwareRequirements: [{type: 'BRAINWAVE', level: 'REQUIRED'}],
68
+ });
69
+ expect(errors.some((e) => e.includes('unknown hardware "BRAINWAVE"'))).toBe(true);
70
+ });
71
+
72
+ test('unknown level is rejected', () => {
73
+ const {errors} = validateManifest({
74
+ ...minimalValid,
75
+ hardwareRequirements: [{type: 'DISPLAY', level: 'MAYBE'}],
76
+ });
77
+ expect(errors.some((e) => e.includes('unknown level "MAYBE"'))).toBe(true);
78
+ });
79
+
80
+ test('EXIST cannot be declared by authors', () => {
81
+ const {errors} = validateManifest({
82
+ ...minimalValid,
83
+ hardwareRequirements: [{type: 'EXIST', level: 'REQUIRED'}],
84
+ });
85
+ // EXIST is omitted from ALLOWED_HARDWARE_TYPES; it's injected at runtime.
86
+ expect(errors.some((e) => e.includes('unknown hardware "EXIST"'))).toBe(true);
87
+ });
88
+
89
+ test('entry must be an object', () => {
90
+ const {errors} = validateManifest({
91
+ ...minimalValid,
92
+ hardwareRequirements: ['DISPLAY'] as unknown as never,
93
+ });
94
+ expect(errors.some((e) => e.includes('must be an object'))).toBe(true);
95
+ });
96
+
97
+ test('description must be a string if set', () => {
98
+ const {errors} = validateManifest({
99
+ ...minimalValid,
100
+ hardwareRequirements: [{type: 'DISPLAY', level: 'REQUIRED', description: 42}],
101
+ });
102
+ expect(errors.some((e) => e.includes('description'))).toBe(true);
103
+ });
104
+
105
+ test('all real-world types accepted', () => {
106
+ const all = ['CAMERA', 'DISPLAY', 'MICROPHONE', 'SPEAKER', 'IMU', 'BUTTON', 'LIGHT', 'WIFI'];
107
+ const {valid} = validateManifest({
108
+ ...minimalValid,
109
+ hardwareRequirements: all.map((type) => ({type, level: 'OPTIONAL'})),
110
+ });
111
+ expect(valid).toBe(true);
112
+ });
113
+ });
114
+
115
+ describe('permissions (now validates objects, not strings)', () => {
116
+ test('string entries are rejected (pre-existing bug fixed)', () => {
117
+ const {errors} = validateManifest({
118
+ ...minimalValid,
119
+ permissions: ['MICROPHONE'] as unknown as never,
120
+ });
121
+ expect(errors.some((e) => e.includes('must be an object'))).toBe(true);
122
+ });
123
+
124
+ test('valid object entry passes', () => {
125
+ const {valid} = validateManifest({
126
+ ...minimalValid,
127
+ permissions: [{type: 'MICROPHONE', description: 'For transcription'}],
128
+ });
129
+ expect(valid).toBe(true);
130
+ });
131
+
132
+ test('unknown permission type is rejected', () => {
133
+ const {errors} = validateManifest({
134
+ ...minimalValid,
135
+ permissions: [{type: 'TELEPATHY'}],
136
+ });
137
+ expect(errors.some((e) => e.includes('unknown permission "TELEPATHY"'))).toBe(true);
138
+ });
139
+
140
+ test('missing type field is rejected', () => {
141
+ const {errors} = validateManifest({
142
+ ...minimalValid,
143
+ permissions: [{description: 'oops'}],
144
+ });
145
+ expect(errors.some((e) => e.includes('permissions[0].type'))).toBe(true);
146
+ });
147
+
148
+ test('bad required type is rejected', () => {
149
+ const {errors} = validateManifest({
150
+ ...minimalValid,
151
+ permissions: [{type: 'MICROPHONE', required: 'yes'}],
152
+ });
153
+ expect(errors.some((e) => e.includes('required'))).toBe(true);
154
+ });
155
+
156
+ test('permissions is optional', () => {
157
+ const m = {...minimalValid} as Record<string, unknown>;
158
+ delete m.permissions;
159
+ const {valid} = validateManifest(m);
160
+ expect(valid).toBe(true);
161
+ });
162
+ });
163
+
164
+ describe('Two-layer fields (sdkVersion / minHostVersion / entry / type)', () => {
165
+ test('accepts a two-layer manifest with full two-layer fields', () => {
166
+ const {valid, errors} = validateManifest({
167
+ ...minimalValid,
168
+ sdkVersion: '0.2.0',
169
+ minHostVersion: '1.42.0',
170
+ entry: {background: 'dist/background/index.js', ui: 'dist/ui/index.html'},
171
+ type: 'standard',
172
+ });
173
+ expect(errors).toEqual([]);
174
+ expect(valid).toBe(true);
175
+ });
176
+
177
+ test('sdkVersion must be a non-empty string when set', () => {
178
+ const {errors} = validateManifest({...minimalValid, sdkVersion: ''});
179
+ expect(errors.some((e) => e.includes('sdkVersion'))).toBe(true);
180
+ });
181
+
182
+ test('minHostVersion must be a non-empty string when set', () => {
183
+ const {errors} = validateManifest({...minimalValid, minHostVersion: 42});
184
+ expect(errors.some((e) => e.includes('minHostVersion'))).toBe(true);
185
+ });
186
+
187
+ test('entry.background is required when entry is set', () => {
188
+ const {errors} = validateManifest({...minimalValid, entry: {ui: 'dist/ui/index.html'}});
189
+ expect(errors.some((e) => e.includes('entry.background'))).toBe(true);
190
+ });
191
+
192
+ test('entry.ui must be a string when set', () => {
193
+ const {errors} = validateManifest({
194
+ ...minimalValid,
195
+ entry: {background: 'dist/background/index.js', ui: 42},
196
+ });
197
+ expect(errors.some((e) => e.includes('entry.ui'))).toBe(true);
198
+ });
199
+
200
+ test('entry must be an object (not array, not string)', () => {
201
+ const {errors} = validateManifest({...minimalValid, entry: 'dist/index.js'});
202
+ expect(errors.some((e) => e.includes('entry'))).toBe(true);
203
+ });
204
+
205
+ test('type must be "standard" or "background" when set', () => {
206
+ const {errors} = validateManifest({...minimalValid, type: 'weird'});
207
+ expect(errors.some((e) => e.includes('type'))).toBe(true);
208
+ });
209
+
210
+ test('type accepts "background" miniapps', () => {
211
+ const {valid} = validateManifest({...minimalValid, type: 'background'});
212
+ expect(valid).toBe(true);
213
+ });
214
+
215
+ test('manifests without two-layer fields still validate (legacy single-layer)', () => {
216
+ const {valid, errors} = validateManifest(minimalValid);
217
+ expect(errors).toEqual([]);
218
+ expect(valid).toBe(true);
219
+ });
220
+ });
221
+
222
+ describe('actions', () => {
223
+ test('accepts a well-formed action with typed parameters', () => {
224
+ const {valid, errors} = validateManifest({
225
+ ...minimalValid,
226
+ actions: [
227
+ {
228
+ id: 'add_todo',
229
+ description: 'Add an item to the user\'s todo list.',
230
+ parameters: {
231
+ type: 'object',
232
+ properties: {
233
+ text: {type: 'string', description: 'The todo text'},
234
+ tags: {type: 'array', items: {type: 'string'}},
235
+ },
236
+ required: ['text'],
237
+ },
238
+ outputSchema: {
239
+ type: 'object',
240
+ properties: {
241
+ ok: {type: 'boolean'},
242
+ message: {type: 'string'},
243
+ },
244
+ required: ['ok'],
245
+ },
246
+ },
247
+ ],
248
+ });
249
+ expect(errors).toEqual([]);
250
+ expect(valid).toBe(true);
251
+ });
252
+
253
+ test('rejects a non-object output schema', () => {
254
+ const {valid, errors} = validateManifest({
255
+ ...minimalValid,
256
+ actions: [{id: 'go', description: 'x', outputSchema: 'not-a-schema'}],
257
+ });
258
+ expect(valid).toBe(false);
259
+ expect(errors.some((e) => e.includes('outputSchema'))).toBe(true);
260
+ });
261
+
262
+ test('accepts an action with no parameters', () => {
263
+ const {valid} = validateManifest({
264
+ ...minimalValid,
265
+ actions: [{id: 'snooze', description: 'Snooze the current reminder.'}],
266
+ });
267
+ expect(valid).toBe(true);
268
+ });
269
+
270
+ test('rejects an id that breaks the pattern', () => {
271
+ const {valid, errors} = validateManifest({
272
+ ...minimalValid,
273
+ actions: [{id: 'Add-Todo', description: 'x'}],
274
+ });
275
+ expect(valid).toBe(false);
276
+ expect(errors.some((e) => e.includes('actions[0].id'))).toBe(true);
277
+ });
278
+
279
+ test('rejects duplicate action ids', () => {
280
+ const {valid, errors} = validateManifest({
281
+ ...minimalValid,
282
+ actions: [
283
+ {id: 'go', description: 'one'},
284
+ {id: 'go', description: 'two'},
285
+ ],
286
+ });
287
+ expect(valid).toBe(false);
288
+ expect(errors.some((e) => e.includes('duplicated'))).toBe(true);
289
+ });
290
+
291
+ test('rejects a missing/empty description', () => {
292
+ const {valid, errors} = validateManifest({
293
+ ...minimalValid,
294
+ actions: [{id: 'go', description: ' '}],
295
+ });
296
+ expect(valid).toBe(false);
297
+ expect(errors.some((e) => e.includes('description'))).toBe(true);
298
+ });
299
+
300
+ test('rejects "integer" param type (use "number")', () => {
301
+ const {valid, errors} = validateManifest({
302
+ ...minimalValid,
303
+ actions: [
304
+ {id: 'go', description: 'x', parameters: {type: 'object', properties: {n: {type: 'integer'}}}},
305
+ ],
306
+ });
307
+ expect(valid).toBe(false);
308
+ expect(errors.some((e) => e.includes('.type must be one of'))).toBe(true);
309
+ });
310
+
311
+ test('rejects an array param without items.type', () => {
312
+ const {valid, errors} = validateManifest({
313
+ ...minimalValid,
314
+ actions: [
315
+ {id: 'go', description: 'x', parameters: {type: 'object', properties: {a: {type: 'array'}}}},
316
+ ],
317
+ });
318
+ expect(valid).toBe(false);
319
+ expect(errors.some((e) => e.includes('items.type'))).toBe(true);
320
+ });
321
+ });
322
+ });
@@ -0,0 +1,340 @@
1
+ // Note: these enum string values must stay in sync with @glassly/miniapp.
2
+ // We cannot depend on @glassly/miniapp here because this lightweight CLI package
3
+ // is intentionally dependency-minimal (so `bunx @glassly/miniapp-cli` starts
4
+ // fast). Mirror string lists manually; failing validations point authors at
5
+ // the allowed values directly.
6
+ //
7
+ // Sources of truth:
8
+ // - AppPermissionType: mobile/modules/engine/src/types/applet.ts
9
+ // - HardwareType: mobile/modules/miniapp/src/hardware.ts
10
+ // - HardwareRequirementLevel: same
11
+ // - AppletPermission shape: {type, required?, description?}
12
+ // - HardwareRequirement shape: {type, level, description?}
13
+
14
+ export const ALLOWED_PERMISSIONS = [
15
+ 'MICROPHONE',
16
+ 'CAMERA',
17
+ 'CALENDAR',
18
+ 'LOCATION',
19
+ 'BACKGROUND_LOCATION',
20
+ 'READ_NOTIFICATIONS',
21
+ 'POST_NOTIFICATIONS',
22
+ 'API_KEYS',
23
+ 'MEMORY',
24
+ 'AI',
25
+ 'SPEAKERS',
26
+ ] as const;
27
+
28
+ export type AllowedPermission = (typeof ALLOWED_PERMISSIONS)[number];
29
+
30
+ export const ALLOWED_HARDWARE_TYPES = [
31
+ 'CAMERA',
32
+ 'DISPLAY',
33
+ 'MICROPHONE',
34
+ 'SPEAKER',
35
+ 'IMU',
36
+ 'BUTTON',
37
+ 'LIGHT',
38
+ 'WIFI',
39
+ // EXIST is injected by the phone at runtime (every miniapp needs glasses
40
+ // present). Do not allow authors to declare it — keep the surface minimal.
41
+ ] as const;
42
+
43
+ export type AllowedHardwareType = (typeof ALLOWED_HARDWARE_TYPES)[number];
44
+
45
+ export const ALLOWED_HARDWARE_LEVELS = ['REQUIRED', 'OPTIONAL'] as const;
46
+
47
+ export type AllowedHardwareLevel = (typeof ALLOWED_HARDWARE_LEVELS)[number];
48
+
49
+ export interface ManifestPermission {
50
+ type: AllowedPermission;
51
+ required?: boolean;
52
+ description?: string;
53
+ }
54
+
55
+ export interface ManifestHardwareRequirement {
56
+ type: AllowedHardwareType;
57
+ level: AllowedHardwareLevel;
58
+ description?: string;
59
+ }
60
+
61
+ export interface ManifestEntry {
62
+ /** Path to the background bundle entry, relative to the project root.
63
+ * Required for two-layer bundles. */
64
+ background: string;
65
+ /** Path to the UI HTML entry. Optional — pure-background miniapps
66
+ * don't include a WebView. */
67
+ ui?: string;
68
+ }
69
+
70
+ // Action parameter types — the MCP-compatible subset. "number" (not
71
+ // "integer") since the runtime is JavaScript; arrays of primitives allowed.
72
+ export const ALLOWED_ACTION_PARAM_TYPES = ['string', 'number', 'boolean', 'array'] as const;
73
+ export type AllowedActionParamType = (typeof ALLOWED_ACTION_PARAM_TYPES)[number];
74
+
75
+ export interface ManifestActionParameter {
76
+ type: AllowedActionParamType;
77
+ description?: string;
78
+ enum?: Array<string | number | boolean>;
79
+ /** For type: "array" — the primitive item type. */
80
+ items?: { type: 'string' | 'number' | 'boolean' };
81
+ }
82
+
83
+ /** JSON-Schema input descriptor for an action. Maps to an MCP tool inputSchema. */
84
+ export interface ManifestActionParameters {
85
+ type: 'object';
86
+ properties?: Record<string, ManifestActionParameter>;
87
+ required?: string[];
88
+ }
89
+
90
+ /**
91
+ * A declared action this miniapp exposes for other (system) miniapps to invoke
92
+ * via session.actions. Shape maps 1:1 onto an MCP tool.
93
+ */
94
+ export interface ManifestAction {
95
+ /** Unique-within-app id, ^[a-z][a-z0-9_]*$, ≤64 chars. */
96
+ id: string;
97
+ /** AI-facing contract — when to use the action. Required, non-empty. */
98
+ description: string;
99
+ parameters?: ManifestActionParameters;
100
+ /** JSON-Schema descriptor for the structured value returned by the handler. */
101
+ outputSchema?: Record<string, unknown>;
102
+ }
103
+
104
+ export interface MiniappManifestV1 {
105
+ packageName: string;
106
+ version: string;
107
+ name: string;
108
+ description?: string;
109
+ icon?: string;
110
+ port?: number;
111
+ permissions?: ManifestPermission[];
112
+ hardwareRequirements: ManifestHardwareRequirement[];
113
+ /** Semver of the @glassly/miniapp SDK ABI this bundle targets. */
114
+ sdkVersion?: string;
115
+ /** Lowest Glassly Manager host version that can run this bundle. */
116
+ minHostVersion?: string;
117
+ /** Two-layer bundle entry points. */
118
+ entry?: ManifestEntry;
119
+ /** Miniapp shape — defaults to "standard" (background + on-demand UI). */
120
+ type?: "standard" | "background";
121
+ /** Actions other (system) miniapps can invoke via session.actions. */
122
+ actions?: ManifestAction[];
123
+ }
124
+
125
+ const ACTION_ID_RE = /^[a-z][a-z0-9_]*$/;
126
+
127
+ function validateActionParameters(parameters: unknown, actionIndex: number, errors: string[]): void {
128
+ if (typeof parameters !== 'object' || parameters === null || Array.isArray(parameters)) {
129
+ errors.push(`actions[${actionIndex}].parameters must be a JSON-Schema object with "type": "object"`);
130
+ return;
131
+ }
132
+ const p = parameters as Record<string, unknown>;
133
+ if (p.type !== 'object') {
134
+ errors.push(`actions[${actionIndex}].parameters.type must be "object"`);
135
+ }
136
+ if (p.properties !== undefined) {
137
+ if (typeof p.properties !== 'object' || p.properties === null || Array.isArray(p.properties)) {
138
+ errors.push(`actions[${actionIndex}].parameters.properties must be an object`);
139
+ } else {
140
+ for (const [key, prop] of Object.entries(p.properties as Record<string, unknown>)) {
141
+ if (typeof prop !== 'object' || prop === null) {
142
+ errors.push(`actions[${actionIndex}].parameters.properties.${key} must be an object`);
143
+ continue;
144
+ }
145
+ const pr = prop as Record<string, unknown>;
146
+ if (typeof pr.type !== 'string' || !(ALLOWED_ACTION_PARAM_TYPES as readonly string[]).includes(pr.type)) {
147
+ errors.push(
148
+ `actions[${actionIndex}].parameters.properties.${key}.type must be one of: ${ALLOWED_ACTION_PARAM_TYPES.join(', ')} (use "number", not "integer")`,
149
+ );
150
+ }
151
+ if (pr.type === 'array') {
152
+ const items = pr.items as Record<string, unknown> | undefined;
153
+ const itemType = items?.type;
154
+ if (typeof itemType !== 'string' || !['string', 'number', 'boolean'].includes(itemType)) {
155
+ errors.push(
156
+ `actions[${actionIndex}].parameters.properties.${key}.items.type must be "string" | "number" | "boolean" for an array param`,
157
+ );
158
+ }
159
+ }
160
+ if (pr.description !== undefined && typeof pr.description !== 'string') {
161
+ errors.push(`actions[${actionIndex}].parameters.properties.${key}.description must be a string if set`);
162
+ }
163
+ if (pr.enum !== undefined && !Array.isArray(pr.enum)) {
164
+ errors.push(`actions[${actionIndex}].parameters.properties.${key}.enum must be an array if set`);
165
+ }
166
+ }
167
+ }
168
+ }
169
+ if (p.required !== undefined && (!Array.isArray(p.required) || !p.required.every((x) => typeof x === 'string'))) {
170
+ errors.push(`actions[${actionIndex}].parameters.required must be an array of strings if set`);
171
+ }
172
+ }
173
+
174
+ export function validateManifest(manifest: unknown): { valid: boolean; errors: string[] } {
175
+ const errors: string[] = [];
176
+
177
+ if (typeof manifest !== 'object' || manifest === null) {
178
+ return { valid: false, errors: ['Manifest must be a JSON object'] };
179
+ }
180
+
181
+ const m = manifest as Record<string, unknown>;
182
+
183
+ if (typeof m.packageName !== 'string' || !m.packageName) {
184
+ errors.push('packageName must be a non-empty string');
185
+ }
186
+
187
+ if (typeof m.version !== 'string' || !m.version) {
188
+ errors.push('version must be a non-empty string');
189
+ }
190
+
191
+ if (typeof m.name !== 'string' || !m.name) {
192
+ errors.push('name must be a non-empty string');
193
+ }
194
+
195
+ // permissions — optional array of {type, required?, description?}
196
+ if (m.permissions !== undefined) {
197
+ if (!Array.isArray(m.permissions)) {
198
+ errors.push('permissions must be an array of {type, required?, description?} objects');
199
+ } else {
200
+ m.permissions.forEach((perm, i) => {
201
+ if (typeof perm !== 'object' || perm === null) {
202
+ errors.push(
203
+ `permissions[${i}] must be an object like {"type": "MICROPHONE"}. Got: ${JSON.stringify(perm)}`,
204
+ );
205
+ return;
206
+ }
207
+ const p = perm as Record<string, unknown>;
208
+ if (typeof p.type !== 'string') {
209
+ errors.push(`permissions[${i}].type must be a string`);
210
+ return;
211
+ }
212
+ if (!(ALLOWED_PERMISSIONS as readonly string[]).includes(p.type)) {
213
+ errors.push(
214
+ `permissions[${i}].type: unknown permission "${p.type}". Allowed: ${ALLOWED_PERMISSIONS.join(', ')}`,
215
+ );
216
+ }
217
+ if (p.required !== undefined && typeof p.required !== 'boolean') {
218
+ errors.push(`permissions[${i}].required must be a boolean if set`);
219
+ }
220
+ if (p.description !== undefined && typeof p.description !== 'string') {
221
+ errors.push(`permissions[${i}].description must be a string if set`);
222
+ }
223
+ });
224
+ }
225
+ }
226
+
227
+ // hardwareRequirements — REQUIRED, array of {type, level, description?}
228
+ if (m.hardwareRequirements === undefined) {
229
+ errors.push(
230
+ 'hardwareRequirements is required. Example: [{"type": "DISPLAY", "level": "REQUIRED"}]. ' +
231
+ `Allowed types: ${ALLOWED_HARDWARE_TYPES.join(', ')}. ` +
232
+ `Levels: ${ALLOWED_HARDWARE_LEVELS.join(', ')}.`,
233
+ );
234
+ } else if (!Array.isArray(m.hardwareRequirements)) {
235
+ errors.push('hardwareRequirements must be an array of {type, level, description?} objects');
236
+ } else {
237
+ m.hardwareRequirements.forEach((req, i) => {
238
+ if (typeof req !== 'object' || req === null) {
239
+ errors.push(
240
+ `hardwareRequirements[${i}] must be an object like {"type": "DISPLAY", "level": "REQUIRED"}. Got: ${JSON.stringify(req)}`,
241
+ );
242
+ return;
243
+ }
244
+ const r = req as Record<string, unknown>;
245
+ if (typeof r.type !== 'string') {
246
+ errors.push(`hardwareRequirements[${i}].type must be a string`);
247
+ } else if (!(ALLOWED_HARDWARE_TYPES as readonly string[]).includes(r.type)) {
248
+ errors.push(
249
+ `hardwareRequirements[${i}].type: unknown hardware "${r.type}". Allowed: ${ALLOWED_HARDWARE_TYPES.join(', ')}`,
250
+ );
251
+ }
252
+ if (typeof r.level !== 'string') {
253
+ errors.push(`hardwareRequirements[${i}].level must be a string`);
254
+ } else if (!(ALLOWED_HARDWARE_LEVELS as readonly string[]).includes(r.level)) {
255
+ errors.push(
256
+ `hardwareRequirements[${i}].level: unknown level "${r.level}". Allowed: ${ALLOWED_HARDWARE_LEVELS.join(', ')}`,
257
+ );
258
+ }
259
+ if (r.description !== undefined && typeof r.description !== 'string') {
260
+ errors.push(`hardwareRequirements[${i}].description must be a string if set`);
261
+ }
262
+ });
263
+ }
264
+
265
+ // Optional sdkVersion / minHostVersion (semver-coercible strings).
266
+ // We don't enforce strict semver — many real-world manifests use a
267
+ // shorthand like "0.2" that semver.coerce normalises to "0.2.0". Reject
268
+ // only if the field is present and not a non-empty string.
269
+ if (m.sdkVersion !== undefined && (typeof m.sdkVersion !== 'string' || !m.sdkVersion)) {
270
+ errors.push('sdkVersion must be a non-empty string when set');
271
+ }
272
+ if (m.minHostVersion !== undefined && (typeof m.minHostVersion !== 'string' || !m.minHostVersion)) {
273
+ errors.push('minHostVersion must be a non-empty string when set');
274
+ }
275
+
276
+ // Optional entry object. When set, entry.background is required.
277
+ if (m.entry !== undefined) {
278
+ if (typeof m.entry !== 'object' || m.entry === null || Array.isArray(m.entry)) {
279
+ errors.push('entry must be an object like {"background": "background/index.js", "ui": "ui/index.html"}');
280
+ } else {
281
+ const e = m.entry as Record<string, unknown>;
282
+ if (typeof e.background !== 'string' || !e.background) {
283
+ errors.push('entry.background is required and must be a non-empty string path');
284
+ }
285
+ if (e.ui !== undefined && (typeof e.ui !== 'string' || !e.ui)) {
286
+ errors.push('entry.ui must be a non-empty string path when set');
287
+ }
288
+ }
289
+ }
290
+
291
+ if (m.type !== undefined) {
292
+ if (m.type !== 'standard' && m.type !== 'background') {
293
+ errors.push('type must be "standard" or "background" when set');
294
+ }
295
+ }
296
+
297
+ // actions — optional array of {id, description, parameters?}. The MCP-shaped
298
+ // capability surface other (system) miniapps invoke via session.actions.
299
+ if (m.actions !== undefined) {
300
+ if (!Array.isArray(m.actions)) {
301
+ errors.push('actions must be an array of {id, description, parameters?} objects');
302
+ } else {
303
+ const seenIds = new Set<string>();
304
+ m.actions.forEach((action, i) => {
305
+ if (typeof action !== 'object' || action === null) {
306
+ errors.push(`actions[${i}] must be an object like {"id": "add_todo", "description": "..."}`);
307
+ return;
308
+ }
309
+ const a = action as Record<string, unknown>;
310
+ if (typeof a.id !== 'string' || !ACTION_ID_RE.test(a.id)) {
311
+ errors.push(
312
+ `actions[${i}].id must match ^[a-z][a-z0-9_]*$ (lowercase, start with a letter). Got: ${JSON.stringify(a.id)}`,
313
+ );
314
+ } else if (a.id.length > 64) {
315
+ errors.push(`actions[${i}].id must be 64 characters or fewer`);
316
+ } else if (seenIds.has(a.id)) {
317
+ errors.push(`actions[${i}].id "${a.id}" is duplicated — action ids must be unique within a miniapp`);
318
+ } else {
319
+ seenIds.add(a.id);
320
+ }
321
+ if (typeof a.description !== 'string' || !a.description.trim()) {
322
+ errors.push(
323
+ `actions[${i}].description is required and must be a non-empty string (it's the AI-facing contract — say when to use the action)`,
324
+ );
325
+ }
326
+ if (a.parameters !== undefined) {
327
+ validateActionParameters(a.parameters, i, errors);
328
+ }
329
+ if (
330
+ a.outputSchema !== undefined &&
331
+ (typeof a.outputSchema !== 'object' || a.outputSchema === null || Array.isArray(a.outputSchema))
332
+ ) {
333
+ errors.push(`actions[${i}].outputSchema must be a JSON-Schema object when set`);
334
+ }
335
+ });
336
+ }
337
+ }
338
+
339
+ return { valid: errors.length === 0, errors };
340
+ }