@openplanr/protocol 0.14.0 → 0.16.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.
@@ -0,0 +1,181 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://openplanr.dev/schemas/v1.23.0/implementation-result.schema.json",
4
+ "x-openplanr-contract": {
5
+ "id": "implementation-result",
6
+ "version": "1.23.0"
7
+ },
8
+ "type": "object",
9
+ "additionalProperties": false,
10
+ "required": [
11
+ "outcome",
12
+ "task",
13
+ "changed",
14
+ "checks",
15
+ "issues"
16
+ ],
17
+ "properties": {
18
+ "outcome": {
19
+ "type": "object",
20
+ "additionalProperties": false,
21
+ "required": [
22
+ "status",
23
+ "summary"
24
+ ],
25
+ "properties": {
26
+ "status": {
27
+ "enum": [
28
+ "completed",
29
+ "partial",
30
+ "blocked",
31
+ "awaiting-acceptance"
32
+ ]
33
+ },
34
+ "summary": {
35
+ "$ref": "#/$defs/nonBlankText"
36
+ }
37
+ }
38
+ },
39
+ "task": {
40
+ "oneOf": [
41
+ {
42
+ "title": "Planr task",
43
+ "type": "object",
44
+ "additionalProperties": false,
45
+ "required": [
46
+ "kind",
47
+ "id",
48
+ "path"
49
+ ],
50
+ "properties": {
51
+ "kind": {
52
+ "const": "planr-task"
53
+ },
54
+ "id": {
55
+ "$ref": "#/$defs/taskId"
56
+ },
57
+ "path": {
58
+ "$ref": "#/$defs/relativePath"
59
+ }
60
+ }
61
+ },
62
+ {
63
+ "title": "Direct request",
64
+ "type": "object",
65
+ "additionalProperties": false,
66
+ "required": [
67
+ "kind"
68
+ ],
69
+ "properties": {
70
+ "kind": {
71
+ "const": "direct-request"
72
+ }
73
+ }
74
+ }
75
+ ]
76
+ },
77
+ "changed": {
78
+ "type": "array",
79
+ "items": {
80
+ "type": "object",
81
+ "additionalProperties": false,
82
+ "required": [
83
+ "path",
84
+ "purpose"
85
+ ],
86
+ "properties": {
87
+ "path": {
88
+ "$ref": "#/$defs/relativePath"
89
+ },
90
+ "purpose": {
91
+ "$ref": "#/$defs/nonBlankText"
92
+ }
93
+ }
94
+ },
95
+ "minItems": 0,
96
+ "maxItems": 4096
97
+ },
98
+ "checks": {
99
+ "type": "array",
100
+ "items": {
101
+ "type": "object",
102
+ "additionalProperties": false,
103
+ "required": [
104
+ "command",
105
+ "status",
106
+ "detail"
107
+ ],
108
+ "properties": {
109
+ "command": {
110
+ "$ref": "#/$defs/nonBlankText"
111
+ },
112
+ "status": {
113
+ "enum": [
114
+ "passed",
115
+ "failed",
116
+ "not-run"
117
+ ]
118
+ },
119
+ "detail": {
120
+ "$ref": "#/$defs/nonBlankText"
121
+ },
122
+ "acceptanceIds": {
123
+ "type": "array",
124
+ "items": {
125
+ "type": "string",
126
+ "pattern": "^(?:[A-Z][A-Z0-9]*-[0-9]+\\.)?AC-[0-9]+$"
127
+ },
128
+ "minItems": 0,
129
+ "maxItems": 256,
130
+ "uniqueItems": true
131
+ }
132
+ }
133
+ },
134
+ "minItems": 0,
135
+ "maxItems": 256
136
+ },
137
+ "issues": {
138
+ "type": "array",
139
+ "items": {
140
+ "type": "object",
141
+ "additionalProperties": false,
142
+ "required": [
143
+ "problem",
144
+ "impact",
145
+ "nextAction"
146
+ ],
147
+ "properties": {
148
+ "problem": {
149
+ "$ref": "#/$defs/nonBlankText"
150
+ },
151
+ "impact": {
152
+ "$ref": "#/$defs/nonBlankText"
153
+ },
154
+ "nextAction": {
155
+ "$ref": "#/$defs/nonBlankText"
156
+ }
157
+ }
158
+ },
159
+ "minItems": 0,
160
+ "maxItems": 256
161
+ }
162
+ },
163
+ "$defs": {
164
+ "nonBlankText": {
165
+ "type": "string",
166
+ "minLength": 1,
167
+ "maxLength": 16384,
168
+ "pattern": ".*\\S.*"
169
+ },
170
+ "relativePath": {
171
+ "type": "string",
172
+ "minLength": 1,
173
+ "maxLength": 1024,
174
+ "pattern": "^(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//).+$"
175
+ },
176
+ "taskId": {
177
+ "type": "string",
178
+ "pattern": "^T-[0-9]{3}$"
179
+ }
180
+ }
181
+ }
@@ -233,7 +233,10 @@
233
233
  ]
234
234
  },
235
235
  "nativeId": {
236
- "$ref": "common.schema.json#/$defs/identifier"
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' },
@@ -221,7 +224,10 @@ const foundationPaths = {
221
224
  'task-kind-registry': { '1.5.0': 'schemas/v1.5.0/task-kind-registry.schema.json' },
222
225
  'task-manifest': { '1.5.0': 'schemas/v1.5.0/task-manifest.schema.json' },
223
226
  'task-output-manifest': { '1.5.0': 'schemas/v1.5.0/task-output-manifest.schema.json' },
224
- 'implementation-result': { '1.5.0': 'schemas/v1.5.0/implementation-result.schema.json' },
227
+ 'implementation-result': {
228
+ '1.5.0': 'schemas/v1.5.0/implementation-result.schema.json',
229
+ '1.23.0': 'schemas/v1.23.0/implementation-result.schema.json',
230
+ },
225
231
  'rule-catalog': { '1.5.0': 'schemas/v1.5.0/rule-catalog.schema.json' },
226
232
  'command-catalog': { '1.5.0': 'schemas/v1.5.0/command-catalog.schema.json' },
227
233
  'skill-catalog': {
@@ -1381,6 +1387,18 @@ function validateStudioArtifact(kind, value, resolved) {
1381
1387
  }
1382
1388
  function validateGenericArtifact(kind, value, resolved) {
1383
1389
  const errors = validateResolvedArtifact(value, resolved);
1390
+ if (
1391
+ !errors.length &&
1392
+ resolved.protocolVersion === '1.22.0' &&
1393
+ ['design-document', 'design-review-bundle'].includes(kind)
1394
+ )
1395
+ errors.push(
1396
+ ...validateDesignProps(kind === 'design-document' ? value : value.design).map((detail) => ({
1397
+ path: '$',
1398
+ rule: 'design-props',
1399
+ detail,
1400
+ })),
1401
+ );
1384
1402
  if (kind === 'guided-questionnaire' && resolved.protocolVersion === '1.2.0')
1385
1403
  errors.push(...guidedQuestionnaireCompatibilityErrors(value));
1386
1404
  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[];
@@ -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').DESIGN_DOCUMENT_SCHEMA} */
179
- export const DESIGN_DOCUMENT_SCHEMA = freeze({
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();
@@ -0,0 +1,3 @@
1
+ /** Exported local design review, without workspace transport fields. */
2
+ export declare const DESIGN_REVIEW_BUNDLE_SCHEMA: Readonly<Record<string, unknown>>;
3
+ export declare const DESIGN_WORKSPACE_VERSION: '1.0.0';
@@ -0,0 +1,92 @@
1
+ // @ts-check
2
+ import { DESIGN_DOCUMENT_V1_SCHEMA } from './design-contracts.mjs';
3
+
4
+ /** @type {typeof import('./design-review-bundle-contracts.d.mts').DESIGN_WORKSPACE_VERSION} */
5
+ export const DESIGN_WORKSPACE_VERSION = '1.0.0';
6
+
7
+ // An explicit presentation-only model. Authored paths, source provenance, and
8
+ // design-system references are deliberately not part of a published workspace.
9
+ const designProperties =
10
+ /** @type {Record<string, { items: { properties: Record<string, unknown>; required: string[] } }>} */ (
11
+ structuredClone(DESIGN_DOCUMENT_V1_SCHEMA.properties)
12
+ );
13
+ for (const key of ['kind', 'schemaVersion', 'brief', 'assets', 'designSystem'])
14
+ delete designProperties[key];
15
+ delete designProperties.screens.items.properties.source;
16
+ designProperties.screens.items.required = ['id', 'title'];
17
+ delete designProperties.variants.items.properties.sources;
18
+ /** @type {typeof import('./design-review-bundle-contracts.d.mts').DESIGN_REVIEW_BUNDLE_SCHEMA} */
19
+ export const DESIGN_REVIEW_BUNDLE_SCHEMA = {
20
+ $schema: 'https://json-schema.org/draft/2020-12/schema',
21
+ $id: 'https://openplanr.dev/schemas/v1.9.0/design-review-bundle.schema.json',
22
+ 'x-openplanr-contract': { id: 'design-review-bundle', version: '1.9.0' },
23
+ type: 'object',
24
+ additionalProperties: false,
25
+ properties: {
26
+ kind: { const: 'openplanr-design-review-bundle' },
27
+ schemaVersion: { const: DESIGN_WORKSPACE_VERSION },
28
+ design: {
29
+ type: 'object',
30
+ additionalProperties: false,
31
+ properties: designProperties,
32
+ required: [
33
+ 'id',
34
+ 'title',
35
+ 'frames',
36
+ 'screens',
37
+ 'screenOrder',
38
+ 'variants',
39
+ 'selectedVariant',
40
+ 'defaultView',
41
+ ],
42
+ },
43
+ envelope: {
44
+ type: 'object',
45
+ required: ['schemaVersion', 'artifacts', 'viewer'],
46
+ },
47
+ entries: {
48
+ type: 'array',
49
+ minItems: 1,
50
+ maxItems: 256,
51
+ items: {
52
+ type: 'object',
53
+ additionalProperties: false,
54
+ required: ['artifactId', 'screenId', 'variantId', 'frameId'],
55
+ properties: Object.fromEntries(
56
+ ['artifactId', 'screenId', 'variantId', 'frameId'].map((key) => [
57
+ key,
58
+ { type: 'string', minLength: 1, maxLength: 128 },
59
+ ]),
60
+ ),
61
+ },
62
+ },
63
+ state: {
64
+ type: ['object', 'null'],
65
+ additionalProperties: false,
66
+ properties: {
67
+ positions: {
68
+ type: 'object',
69
+ additionalProperties: {
70
+ type: 'object',
71
+ additionalProperties: false,
72
+ required: ['x', 'y'],
73
+ properties: {
74
+ x: { type: 'number', minimum: -1e7, maximum: 1e7 },
75
+ y: { type: 'number', minimum: -1e7, maximum: 1e7 },
76
+ },
77
+ },
78
+ },
79
+ },
80
+ },
81
+ revision: { type: 'string', minLength: 1, maxLength: 128 },
82
+ verification: {
83
+ type: ['object', 'null'],
84
+ additionalProperties: false,
85
+ properties: {
86
+ status: { enum: ['verified', 'unverified', 'failed', 'pending'] },
87
+ },
88
+ },
89
+ },
90
+ required: ['kind', 'schemaVersion', 'design', 'envelope', 'entries', 'revision'],
91
+ $defs: structuredClone(DESIGN_DOCUMENT_V1_SCHEMA.$defs),
92
+ };