@openplanr/protocol 0.14.0 → 0.15.0
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/README.md +15 -1
- package/package.json +2 -2
- package/registries/commands.json +10 -10
- package/registries/roles.json +43 -133
- package/registries/skills.json +14 -14
- package/registries/task-kinds.json +2 -2
- package/schemas/v1.22.0/design-document.schema.json +506 -0
- package/schemas/v1.22.0/design-review-bundle.schema.json +822 -0
- package/schemas/v1.5.0/role-registry.schema.json +4 -1
- package/src/contracts.mjs +15 -0
- package/src/design-contracts.d.mts +15 -1
- package/src/design-contracts.mjs +141 -2
- package/src/generated/canonical-registries.mjs +69 -159
- package/src/json-schema.mjs +4 -0
- package/src/registries.mjs +20 -4
- package/src/review-experience-contracts.d.mts +1 -0
- package/src/review-experience-contracts.mjs +47 -5
|
@@ -233,7 +233,10 @@
|
|
|
233
233
|
]
|
|
234
234
|
},
|
|
235
235
|
"nativeId": {
|
|
236
|
-
"
|
|
236
|
+
"type": "string",
|
|
237
|
+
"pattern": "^(?:[a-z][a-z0-9]*(?:-[a-z0-9]+)*:)?[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
|
|
238
|
+
"minLength": 1,
|
|
239
|
+
"maxLength": 128
|
|
237
240
|
},
|
|
238
241
|
"generatedPath": {
|
|
239
242
|
"$ref": "common.schema.json#/$defs/relativePath"
|
package/src/contracts.mjs
CHANGED
|
@@ -14,6 +14,7 @@ import { dirname, join, relative, resolve, sep } from 'node:path';
|
|
|
14
14
|
import { fileURLToPath } from 'node:url';
|
|
15
15
|
import { PROTOCOL_V115_CONTRACTS, validateDiagramReviewArtifact } from './browser-contracts.mjs';
|
|
16
16
|
import { deepFreeze } from './canonical-json.mjs';
|
|
17
|
+
import { validateDesignProps } from './design-contracts.mjs';
|
|
17
18
|
import { DESIGN_HANDOFF_CONTRACT_FILES } from './design-handoff-contracts.mjs';
|
|
18
19
|
import {
|
|
19
20
|
assertDiagramData,
|
|
@@ -84,6 +85,7 @@ const foundationPaths = {
|
|
|
84
85
|
'design-document': {
|
|
85
86
|
'1.9.0': 'schemas/v1.9.0/design-document.schema.json',
|
|
86
87
|
'1.20.0': 'schemas/v1.20.0/design-document.schema.json',
|
|
88
|
+
'1.22.0': 'schemas/v1.22.0/design-document.schema.json',
|
|
87
89
|
},
|
|
88
90
|
'design-review-workspace': { '1.9.0': 'schemas/v1.9.0/design-review-workspace.schema.json' },
|
|
89
91
|
'design-workspace-create': { '1.9.0': 'schemas/v1.9.0/design-workspace-create.schema.json' },
|
|
@@ -94,6 +96,7 @@ const foundationPaths = {
|
|
|
94
96
|
'1.10.0': 'schemas/v1.10.0/design-review-bundle.schema.json',
|
|
95
97
|
'1.16.0': 'schemas/v1.16.0/design-review-bundle.schema.json',
|
|
96
98
|
'1.20.0': 'schemas/v1.20.0/design-review-bundle.schema.json',
|
|
99
|
+
'1.22.0': 'schemas/v1.22.0/design-review-bundle.schema.json',
|
|
97
100
|
},
|
|
98
101
|
'design-review-context': { '1.10.0': 'schemas/v1.10.0/design-review-context.schema.json' },
|
|
99
102
|
'design-review-handoff': { '1.10.0': 'schemas/v1.10.0/design-review-handoff.schema.json' },
|
|
@@ -1381,6 +1384,18 @@ function validateStudioArtifact(kind, value, resolved) {
|
|
|
1381
1384
|
}
|
|
1382
1385
|
function validateGenericArtifact(kind, value, resolved) {
|
|
1383
1386
|
const errors = validateResolvedArtifact(value, resolved);
|
|
1387
|
+
if (
|
|
1388
|
+
!errors.length &&
|
|
1389
|
+
resolved.protocolVersion === '1.22.0' &&
|
|
1390
|
+
['design-document', 'design-review-bundle'].includes(kind)
|
|
1391
|
+
)
|
|
1392
|
+
errors.push(
|
|
1393
|
+
...validateDesignProps(kind === 'design-document' ? value : value.design).map((detail) => ({
|
|
1394
|
+
path: '$',
|
|
1395
|
+
rule: 'design-props',
|
|
1396
|
+
detail,
|
|
1397
|
+
})),
|
|
1398
|
+
);
|
|
1384
1399
|
if (kind === 'guided-questionnaire' && resolved.protocolVersion === '1.2.0')
|
|
1385
1400
|
errors.push(...guidedQuestionnaireCompatibilityErrors(value));
|
|
1386
1401
|
return errors;
|
|
@@ -14,11 +14,18 @@ export interface DesignFrame {
|
|
|
14
14
|
height: number | 'auto';
|
|
15
15
|
}
|
|
16
16
|
|
|
17
|
+
export type DesignProp =
|
|
18
|
+
| { type: 'enum'; options: string[]; default: string }
|
|
19
|
+
| { type: 'boolean'; default: boolean };
|
|
20
|
+
|
|
21
|
+
export type DesignPropValue = string | boolean;
|
|
22
|
+
|
|
17
23
|
export interface DesignScreen {
|
|
18
24
|
id: string;
|
|
19
25
|
title: string;
|
|
20
26
|
description?: string;
|
|
21
27
|
source: DesignSource;
|
|
28
|
+
props?: Record<string, DesignProp>;
|
|
22
29
|
/** Stable feedback anchors, unique within this screen. */
|
|
23
30
|
anchors?: string[];
|
|
24
31
|
}
|
|
@@ -32,6 +39,7 @@ export interface DesignVariant {
|
|
|
32
39
|
issue?: string;
|
|
33
40
|
/** Sparse screen overrides inherit unchanged sources from screens. */
|
|
34
41
|
sources?: Record<string, DesignSource>;
|
|
42
|
+
props?: Record<string, Record<string, DesignPropValue>>;
|
|
35
43
|
}
|
|
36
44
|
|
|
37
45
|
export interface DesignBoardPosition {
|
|
@@ -56,7 +64,7 @@ export interface DesignLayout {
|
|
|
56
64
|
|
|
57
65
|
export interface DesignDocument {
|
|
58
66
|
kind: 'openplanr-design-document';
|
|
59
|
-
schemaVersion: '1.0.0';
|
|
67
|
+
schemaVersion: '1.0.0' | '1.1.0';
|
|
60
68
|
id: string;
|
|
61
69
|
title: string;
|
|
62
70
|
brief: {
|
|
@@ -79,8 +87,14 @@ export interface DesignDocument {
|
|
|
79
87
|
|
|
80
88
|
export declare const DESIGN_DOCUMENT_VERSION: '1.0.0';
|
|
81
89
|
export declare const DESIGN_DOCUMENT_V1_SCHEMA: Readonly<Record<string, unknown>>;
|
|
90
|
+
export declare const DESIGN_DOCUMENT_V120_SCHEMA: Readonly<Record<string, unknown>>;
|
|
82
91
|
export declare const DESIGN_DOCUMENT_SCHEMA: Readonly<Record<string, unknown>>;
|
|
83
92
|
export declare function validateDesignDocument(value: unknown): { ok: boolean; errors: string[] };
|
|
84
93
|
export declare function assertDesignDocument(value: unknown): DesignDocument;
|
|
85
94
|
|
|
86
95
|
export declare function initialFrameHeight(document: Pick<DesignDocument, 'frames'>): number;
|
|
96
|
+
|
|
97
|
+
export declare function validateDesignProps(document: {
|
|
98
|
+
screens: Pick<DesignScreen, 'id' | 'props'>[];
|
|
99
|
+
variants: Pick<DesignVariant, 'props'>[];
|
|
100
|
+
}): string[];
|
package/src/design-contracts.mjs
CHANGED
|
@@ -175,8 +175,8 @@ export const DESIGN_DOCUMENT_V1_SCHEMA = freeze({
|
|
|
175
175
|
},
|
|
176
176
|
});
|
|
177
177
|
|
|
178
|
-
/** @type {typeof import('./design-contracts.d.mts').
|
|
179
|
-
export const
|
|
178
|
+
/** @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_V120_SCHEMA} */
|
|
179
|
+
export const DESIGN_DOCUMENT_V120_SCHEMA = freeze({
|
|
180
180
|
...DESIGN_DOCUMENT_V1_SCHEMA,
|
|
181
181
|
$id: 'https://openplanr.dev/schemas/v1.20.0/design-document.schema.json',
|
|
182
182
|
'x-openplanr-contract': { id: 'design-document', version: '1.20.0' },
|
|
@@ -235,6 +235,135 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
|
|
|
235
235
|
},
|
|
236
236
|
});
|
|
237
237
|
|
|
238
|
+
const PROP_TOKEN_SCHEMA = {
|
|
239
|
+
type: 'string',
|
|
240
|
+
minLength: 1,
|
|
241
|
+
maxLength: 128,
|
|
242
|
+
pattern: '^[a-z][a-z0-9-]*(?![\\s\\S])',
|
|
243
|
+
};
|
|
244
|
+
const propTokenPattern = new RegExp(PROP_TOKEN_SCHEMA.pattern, 'u');
|
|
245
|
+
const isPropToken = (value) =>
|
|
246
|
+
typeof value === 'string' &&
|
|
247
|
+
value.length <= PROP_TOKEN_SCHEMA.maxLength &&
|
|
248
|
+
propTokenPattern.test(value);
|
|
249
|
+
|
|
250
|
+
const currentDocument =
|
|
251
|
+
/** @type {{ properties: Record<string, unknown>; [key: string]: unknown }} */ (
|
|
252
|
+
structuredClone(DESIGN_DOCUMENT_V120_SCHEMA)
|
|
253
|
+
);
|
|
254
|
+
currentDocument.$id = 'https://openplanr.dev/schemas/v1.22.0/design-document.schema.json';
|
|
255
|
+
currentDocument['x-openplanr-contract'] = { id: 'design-document', version: '1.22.0' };
|
|
256
|
+
currentDocument.properties.schemaVersion = { enum: ['1.0.0', '1.1.0'] };
|
|
257
|
+
const screenSchema = /** @type {{ items: { properties: Record<string, unknown> } }} */ (
|
|
258
|
+
currentDocument.properties.screens
|
|
259
|
+
);
|
|
260
|
+
screenSchema.items.properties.props = {
|
|
261
|
+
type: 'object',
|
|
262
|
+
propertyNames: PROP_TOKEN_SCHEMA,
|
|
263
|
+
additionalProperties: {
|
|
264
|
+
oneOf: [
|
|
265
|
+
{
|
|
266
|
+
type: 'object',
|
|
267
|
+
additionalProperties: false,
|
|
268
|
+
required: ['type', 'options', 'default'],
|
|
269
|
+
properties: {
|
|
270
|
+
type: { const: 'enum' },
|
|
271
|
+
options: {
|
|
272
|
+
type: 'array',
|
|
273
|
+
minItems: 1,
|
|
274
|
+
uniqueItems: true,
|
|
275
|
+
items: PROP_TOKEN_SCHEMA,
|
|
276
|
+
},
|
|
277
|
+
default: PROP_TOKEN_SCHEMA,
|
|
278
|
+
},
|
|
279
|
+
},
|
|
280
|
+
{
|
|
281
|
+
type: 'object',
|
|
282
|
+
additionalProperties: false,
|
|
283
|
+
required: ['type', 'default'],
|
|
284
|
+
properties: { type: { const: 'boolean' }, default: { type: 'boolean' } },
|
|
285
|
+
},
|
|
286
|
+
],
|
|
287
|
+
},
|
|
288
|
+
};
|
|
289
|
+
const variantSchema = /** @type {{ items: { properties: Record<string, unknown> } }} */ (
|
|
290
|
+
currentDocument.properties.variants
|
|
291
|
+
);
|
|
292
|
+
variantSchema.items.properties.props = {
|
|
293
|
+
type: 'object',
|
|
294
|
+
propertyNames: { $ref: '#/$defs/id' },
|
|
295
|
+
additionalProperties: {
|
|
296
|
+
type: 'object',
|
|
297
|
+
propertyNames: PROP_TOKEN_SCHEMA,
|
|
298
|
+
additionalProperties: { anyOf: [PROP_TOKEN_SCHEMA, { type: 'boolean' }] },
|
|
299
|
+
},
|
|
300
|
+
};
|
|
301
|
+
currentDocument.allOf = [
|
|
302
|
+
{
|
|
303
|
+
if: { properties: { schemaVersion: { const: '1.1.0' } }, required: ['schemaVersion'] },
|
|
304
|
+
else: {
|
|
305
|
+
properties: {
|
|
306
|
+
screens: { items: { not: { required: ['props'] } } },
|
|
307
|
+
variants: { items: { not: { required: ['props'] } } },
|
|
308
|
+
},
|
|
309
|
+
},
|
|
310
|
+
},
|
|
311
|
+
];
|
|
312
|
+
/** @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_SCHEMA} */
|
|
313
|
+
export const DESIGN_DOCUMENT_SCHEMA = freeze(currentDocument);
|
|
314
|
+
|
|
315
|
+
/** Validate prop references and values after structural validation.
|
|
316
|
+
* @type {typeof import('./design-contracts.d.mts').validateDesignProps}
|
|
317
|
+
*/
|
|
318
|
+
export function validateDesignProps(document) {
|
|
319
|
+
const errors = [];
|
|
320
|
+
const checkToken = (value, path) => {
|
|
321
|
+
if (!isPropToken(value))
|
|
322
|
+
errors.push(
|
|
323
|
+
`${path}: ${JSON.stringify(value)} must be a lowercase token matching ${PROP_TOKEN_SCHEMA.pattern} with at most ${PROP_TOKEN_SCHEMA.maxLength} characters`,
|
|
324
|
+
);
|
|
325
|
+
};
|
|
326
|
+
const screens = new Map(document.screens.map((screen) => [screen.id, screen]));
|
|
327
|
+
for (const [index, screen] of document.screens.entries()) {
|
|
328
|
+
for (const [name, prop] of Object.entries(screen.props ?? {})) {
|
|
329
|
+
const path = `$.screens[${index}].props.${name}`;
|
|
330
|
+
checkToken(name, path);
|
|
331
|
+
if (prop.type === 'enum') {
|
|
332
|
+
for (const [optionIndex, option] of prop.options.entries())
|
|
333
|
+
checkToken(option, `${path}.options[${optionIndex}]`);
|
|
334
|
+
checkToken(prop.default, `${path}.default`);
|
|
335
|
+
if (!prop.options.includes(prop.default))
|
|
336
|
+
errors.push(`${path}.default: '${prop.default}' is not an enum option`);
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
for (const [index, variant] of document.variants.entries()) {
|
|
341
|
+
for (const [screenId, values] of Object.entries(variant.props ?? {})) {
|
|
342
|
+
const screen = screens.get(screenId);
|
|
343
|
+
const path = `$.variants[${index}].props.${screenId}`;
|
|
344
|
+
if (!screen) {
|
|
345
|
+
errors.push(`${path}: unknown screen '${screenId}'`);
|
|
346
|
+
continue;
|
|
347
|
+
}
|
|
348
|
+
for (const [name, value] of Object.entries(values)) {
|
|
349
|
+
checkToken(name, `${path}.${name}`);
|
|
350
|
+
if (typeof value === 'string') checkToken(value, `${path}.${name}`);
|
|
351
|
+
const props = screen.props ?? {};
|
|
352
|
+
const prop = Object.hasOwn(props, name) ? props[name] : undefined;
|
|
353
|
+
if (!prop) errors.push(`${path}.${name}: unknown prop '${name}' on screen '${screenId}'`);
|
|
354
|
+
else if (prop.type === 'boolean' && typeof value !== 'boolean')
|
|
355
|
+
errors.push(`${path}.${name}: expected a boolean, received ${JSON.stringify(value)}`);
|
|
356
|
+
else if (
|
|
357
|
+
prop.type === 'enum' &&
|
|
358
|
+
(typeof value !== 'string' || !prop.options.includes(value))
|
|
359
|
+
)
|
|
360
|
+
errors.push(`${path}.${name}: ${JSON.stringify(value)} is not an enum option`);
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
}
|
|
364
|
+
return errors;
|
|
365
|
+
}
|
|
366
|
+
|
|
238
367
|
/**
|
|
239
368
|
* Validate structure plus stable identity and cross-reference constraints.
|
|
240
369
|
* @returns {ReturnType<typeof import('./design-contracts.d.mts').validateDesignDocument>}
|
|
@@ -243,7 +372,17 @@ export function validateDesignDocument(value) {
|
|
|
243
372
|
const errors = validateJson(value, DESIGN_DOCUMENT_SCHEMA).map(
|
|
244
373
|
({ path, detail }) => `${path}: ${detail}`,
|
|
245
374
|
);
|
|
375
|
+
if (
|
|
376
|
+
value?.schemaVersion === '1.0.0' &&
|
|
377
|
+
['screens', 'variants'].some(
|
|
378
|
+
(field) =>
|
|
379
|
+
Array.isArray(value[field]) &&
|
|
380
|
+
value[field].some((item) => item && Object.hasOwn(item, 'props')),
|
|
381
|
+
)
|
|
382
|
+
)
|
|
383
|
+
errors.push('$.schemaVersion: props require schemaVersion "1.1.0"');
|
|
246
384
|
if (errors.length > 0) return { ok: false, errors };
|
|
385
|
+
errors.push(...validateDesignProps(value));
|
|
247
386
|
|
|
248
387
|
for (const field of ['frames', 'screens', 'flows', 'variants']) {
|
|
249
388
|
const seen = new Set();
|