@openplanr/protocol 0.6.1 → 0.7.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 +10 -0
- package/lib/dashboard/closed-json-contract.mjs +99 -109
- package/lib/dashboard/operate-experience-audit-display-contract.d.mts +128 -153
- package/lib/dashboard/operate-experience-audit-display-contract.mjs +530 -585
- package/lib/dashboard/operate-experience-display-contract.d.mts +415 -437
- package/lib/dashboard/operate-experience-display-contract.mjs +777 -831
- package/lib/dashboard/operate-experience-surface-contract.d.mts +143 -148
- package/lib/dashboard/operate-experience-surface-contract.mjs +72 -73
- package/lib/dashboard/operate-review-contract.d.mts +7 -14
- package/lib/dashboard/operate-review-contract.mjs +46 -42
- package/lib/dashboard/operate-review-display-workspace-contract.d.mts +2 -5
- package/lib/dashboard/operate-review-display-workspace-contract.mjs +158 -104
- package/lib/dashboard/operate-review-payload-safety.mjs +4 -2
- package/lib/dashboard/operate-review-workspace-projection-v2.d.mts +47 -33
- package/lib/protocol/index.d.ts +2647 -543
- package/package.json +1 -1
- package/registries/artifact-theme.json +64 -0
- package/registries/commands.json +40 -40
- package/registries/skills.json +5 -5
- package/schemas/v1.14.0/artifact-theme.schema.json +316 -0
- package/src/browser-contracts.d.mts +4 -1
- package/src/browser-contracts.mjs +16 -5
- package/src/canonical-json.d.mts +6 -1
- package/src/canonical-json.mjs +100 -22
- package/src/compat/live-evidence-v2.mjs +1611 -485
- package/src/compat/operate-experience-live-patch.mjs +67 -15
- package/src/compat/operating-planning-contracts.mjs +183 -51
- package/src/contracts.d.mts +54 -13
- package/src/contracts.mjs +635 -343
- package/src/design-contracts.mjs +58 -21
- package/src/design-handoff-contracts.d.mts +67 -11
- package/src/design-handoff-contracts.mjs +236 -119
- package/src/design-publication-contracts.mjs +98 -33
- package/src/diagram-authoring-contracts.d.mts +422 -78
- package/src/diagram-authoring-contracts.mjs +1715 -335
- package/src/diagram-contracts.d.mts +4 -1
- package/src/diagram-contracts.mjs +16 -4
- package/src/enterprise-contracts.d.mts +211 -46
- package/src/enterprise-contracts.mjs +738 -184
- package/src/errors.mjs +4 -0
- package/src/generated/canonical-registries.mjs +45 -45
- package/src/index.d.mts +8 -8
- package/src/index.mjs +36 -20
- package/src/json-schema.d.mts +21 -6
- package/src/json-schema.mjs +66 -18
- package/src/planning-contracts.d.mts +8 -2
- package/src/planning-contracts.mjs +33 -7
- package/src/registries.d.mts +11 -3
- package/src/registries.mjs +369 -87
- package/src/review-experience-contracts.d.mts +7 -2
- package/src/review-experience-contracts.mjs +198 -49
- package/src/semver.mjs +5 -1
- package/src/skill-source-contracts.d.mts +36 -16
- package/src/skill-source-contracts.mjs +25 -6
- package/src/task-contracts.d.mts +13 -3
- package/src/task-contracts.mjs +181 -40
- package/src/workspace-contracts.d.mts +38 -10
- package/src/workspace-contracts.mjs +147 -33
package/src/design-contracts.mjs
CHANGED
|
@@ -1,6 +1,10 @@
|
|
|
1
|
+
// @ts-check
|
|
1
2
|
import { validateJson } from './json-schema.mjs';
|
|
2
3
|
|
|
3
|
-
/**
|
|
4
|
+
/**
|
|
5
|
+
* The authored document version is independent of the Protocol release.
|
|
6
|
+
* @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_VERSION}
|
|
7
|
+
*/
|
|
4
8
|
export const DESIGN_DOCUMENT_VERSION = '1.0.0';
|
|
5
9
|
|
|
6
10
|
const freeze = (value) => {
|
|
@@ -14,6 +18,7 @@ const freeze = (value) => {
|
|
|
14
18
|
/**
|
|
15
19
|
* Portable source of truth for the packaged Protocol 1.9 schema. Rendering,
|
|
16
20
|
* file existence, symlink containment and revisions belong to the design domain.
|
|
21
|
+
* @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_SCHEMA}
|
|
17
22
|
*/
|
|
18
23
|
export const DESIGN_DOCUMENT_SCHEMA = freeze({
|
|
19
24
|
$schema: 'https://json-schema.org/draft/2020-12/schema',
|
|
@@ -23,8 +28,17 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
|
|
|
23
28
|
type: 'object',
|
|
24
29
|
additionalProperties: false,
|
|
25
30
|
required: [
|
|
26
|
-
'kind',
|
|
27
|
-
'
|
|
31
|
+
'kind',
|
|
32
|
+
'schemaVersion',
|
|
33
|
+
'id',
|
|
34
|
+
'title',
|
|
35
|
+
'brief',
|
|
36
|
+
'frames',
|
|
37
|
+
'screens',
|
|
38
|
+
'screenOrder',
|
|
39
|
+
'variants',
|
|
40
|
+
'selectedVariant',
|
|
41
|
+
'defaultView',
|
|
28
42
|
],
|
|
29
43
|
properties: {
|
|
30
44
|
kind: { const: 'openplanr-design-document' },
|
|
@@ -49,16 +63,20 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
|
|
|
49
63
|
path: { $ref: '#/$defs/localPath' },
|
|
50
64
|
tokens: { $ref: '#/$defs/localPath' },
|
|
51
65
|
spacing: {
|
|
52
|
-
type: 'array',
|
|
66
|
+
type: 'array',
|
|
67
|
+
minItems: 1,
|
|
68
|
+
uniqueItems: true,
|
|
53
69
|
items: { type: 'number', minimum: 0, maximum: 16384 },
|
|
54
70
|
},
|
|
55
71
|
},
|
|
56
72
|
},
|
|
57
73
|
assets: { $ref: '#/$defs/paths' },
|
|
58
74
|
frames: {
|
|
59
|
-
type: 'array',
|
|
75
|
+
type: 'array',
|
|
76
|
+
minItems: 1,
|
|
60
77
|
items: {
|
|
61
|
-
type: 'object',
|
|
78
|
+
type: 'object',
|
|
79
|
+
additionalProperties: false,
|
|
62
80
|
required: ['id', 'label', 'width', 'height'],
|
|
63
81
|
properties: {
|
|
64
82
|
id: { $ref: '#/$defs/id' },
|
|
@@ -69,9 +87,11 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
|
|
|
69
87
|
},
|
|
70
88
|
},
|
|
71
89
|
screens: {
|
|
72
|
-
type: 'array',
|
|
90
|
+
type: 'array',
|
|
91
|
+
minItems: 1,
|
|
73
92
|
items: {
|
|
74
|
-
type: 'object',
|
|
93
|
+
type: 'object',
|
|
94
|
+
additionalProperties: false,
|
|
75
95
|
required: ['id', 'title', 'source'],
|
|
76
96
|
properties: {
|
|
77
97
|
id: { $ref: '#/$defs/id' },
|
|
@@ -86,7 +106,8 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
|
|
|
86
106
|
flows: {
|
|
87
107
|
type: 'array',
|
|
88
108
|
items: {
|
|
89
|
-
type: 'object',
|
|
109
|
+
type: 'object',
|
|
110
|
+
additionalProperties: false,
|
|
90
111
|
required: ['id', 'title', 'screens'],
|
|
91
112
|
properties: {
|
|
92
113
|
id: { $ref: '#/$defs/id' },
|
|
@@ -96,9 +117,11 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
|
|
|
96
117
|
},
|
|
97
118
|
},
|
|
98
119
|
variants: {
|
|
99
|
-
type: 'array',
|
|
120
|
+
type: 'array',
|
|
121
|
+
minItems: 1,
|
|
100
122
|
items: {
|
|
101
|
-
type: 'object',
|
|
123
|
+
type: 'object',
|
|
124
|
+
additionalProperties: false,
|
|
102
125
|
required: ['id', 'label', 'status'],
|
|
103
126
|
properties: {
|
|
104
127
|
id: { $ref: '#/$defs/id' },
|
|
@@ -120,13 +143,17 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
|
|
|
120
143
|
text: { type: 'string', minLength: 1, pattern: '\\S' },
|
|
121
144
|
ids: { type: 'array', items: { $ref: '#/$defs/id' }, uniqueItems: true },
|
|
122
145
|
localPath: {
|
|
123
|
-
type: 'string',
|
|
124
|
-
|
|
146
|
+
type: 'string',
|
|
147
|
+
minLength: 1,
|
|
148
|
+
description:
|
|
149
|
+
'Path relative to the authored document directory. No URL, traversal, encoded path, query or fragment.',
|
|
125
150
|
pattern: '^(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)(?!.*[/ ]$)[^\\\\:\\u0000-\\u001F%?#]+$',
|
|
126
151
|
},
|
|
127
152
|
paths: { type: 'array', items: { $ref: '#/$defs/localPath' }, uniqueItems: true },
|
|
128
153
|
source: {
|
|
129
|
-
type: 'object',
|
|
154
|
+
type: 'object',
|
|
155
|
+
additionalProperties: false,
|
|
156
|
+
required: ['html'],
|
|
130
157
|
properties: {
|
|
131
158
|
html: { $ref: '#/$defs/localPath' },
|
|
132
159
|
styles: { $ref: '#/$defs/paths' },
|
|
@@ -136,16 +163,21 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
|
|
|
136
163
|
},
|
|
137
164
|
});
|
|
138
165
|
|
|
139
|
-
/**
|
|
166
|
+
/**
|
|
167
|
+
* Validate structure plus stable identity and cross-reference constraints.
|
|
168
|
+
* @returns {ReturnType<typeof import('./design-contracts.d.mts').validateDesignDocument>}
|
|
169
|
+
*/
|
|
140
170
|
export function validateDesignDocument(value) {
|
|
141
|
-
const errors = validateJson(value, DESIGN_DOCUMENT_SCHEMA)
|
|
142
|
-
|
|
171
|
+
const errors = validateJson(value, DESIGN_DOCUMENT_SCHEMA).map(
|
|
172
|
+
({ path, detail }) => `${path}: ${detail}`,
|
|
173
|
+
);
|
|
143
174
|
if (errors.length > 0) return { ok: false, errors };
|
|
144
175
|
|
|
145
176
|
for (const field of ['frames', 'screens', 'flows', 'variants']) {
|
|
146
177
|
const seen = new Set();
|
|
147
178
|
for (const [index, item] of (value[field] ?? []).entries()) {
|
|
148
|
-
if (seen.has(item.id))
|
|
179
|
+
if (seen.has(item.id))
|
|
180
|
+
errors.push(`$.${field}[${index}].id: duplicate identity '${item.id}'`);
|
|
149
181
|
seen.add(item.id);
|
|
150
182
|
}
|
|
151
183
|
}
|
|
@@ -170,15 +202,20 @@ export function validateDesignDocument(value) {
|
|
|
170
202
|
}
|
|
171
203
|
const selected = value.variants.find(({ id }) => id === value.selectedVariant);
|
|
172
204
|
if (!selected) errors.push(`$.selectedVariant: unknown variant '${value.selectedVariant}'`);
|
|
173
|
-
else if (selected.status !== 'ready')
|
|
205
|
+
else if (selected.status !== 'ready')
|
|
206
|
+
errors.push('$.selectedVariant: selected variant must be ready');
|
|
174
207
|
|
|
175
208
|
for (const [index, spacing] of (value.designSystem?.spacing ?? []).entries()) {
|
|
176
|
-
if (!Number.isFinite(spacing))
|
|
209
|
+
if (!Number.isFinite(spacing))
|
|
210
|
+
errors.push(`$.designSystem.spacing[${index}]: expected a finite spacing value`);
|
|
177
211
|
}
|
|
178
212
|
return { ok: errors.length === 0, errors };
|
|
179
213
|
}
|
|
180
214
|
|
|
181
|
-
/**
|
|
215
|
+
/**
|
|
216
|
+
* Return the original valid document; never normalize authored design intent.
|
|
217
|
+
* @returns {ReturnType<typeof import('./design-contracts.d.mts').assertDesignDocument>}
|
|
218
|
+
*/
|
|
182
219
|
export function assertDesignDocument(value) {
|
|
183
220
|
const result = validateDesignDocument(value);
|
|
184
221
|
if (!result.ok) throw new TypeError(`Invalid design document:\n${result.errors.join('\n')}`);
|
|
@@ -3,14 +3,36 @@ export type DesignHandoffStatus = 'ready' | 'attention' | 'blocked' | 'stale';
|
|
|
3
3
|
export type DesignHandoffCheckStatus = 'pass' | 'attention' | 'blocked' | 'stale';
|
|
4
4
|
export type DesignHandoffSchema = Readonly<Record<string, unknown>>;
|
|
5
5
|
|
|
6
|
-
export interface DesignHandoffAction {
|
|
6
|
+
export interface DesignHandoffAction {
|
|
7
|
+
id: string;
|
|
8
|
+
label: string;
|
|
9
|
+
}
|
|
7
10
|
export interface DesignHandoffEvidenceReference {
|
|
8
11
|
id: string;
|
|
9
|
-
kind:
|
|
12
|
+
kind:
|
|
13
|
+
| 'design-revision'
|
|
14
|
+
| 'selected-direction'
|
|
15
|
+
| 'design-specification'
|
|
16
|
+
| 'rendered-verification'
|
|
17
|
+
| 'review-context'
|
|
18
|
+
| 'review-feedback'
|
|
19
|
+
| 'review-metadata'
|
|
20
|
+
| 'review-handoff'
|
|
21
|
+
| 'screen'
|
|
22
|
+
| 'frame'
|
|
23
|
+
| 'component'
|
|
24
|
+
| 'state'
|
|
25
|
+
| 'flow'
|
|
26
|
+
| 'token'
|
|
27
|
+
| 'review-decision'
|
|
28
|
+
| 'element-anchor';
|
|
10
29
|
path: string;
|
|
11
30
|
revision?: DesignHandoffDigest;
|
|
12
31
|
digest?: DesignHandoffDigest;
|
|
13
|
-
anchor?:
|
|
32
|
+
anchor?:
|
|
33
|
+
| { section: string }
|
|
34
|
+
| { screenId: string; elementId?: string }
|
|
35
|
+
| { reviewId: string; pinId: string };
|
|
14
36
|
}
|
|
15
37
|
export interface DesignHandoffReadinessCheck {
|
|
16
38
|
id: string;
|
|
@@ -58,10 +80,28 @@ export interface DesignImplementationHandoff {
|
|
|
58
80
|
reviewHandoff: { version: number; contentDigest: DesignHandoffDigest };
|
|
59
81
|
};
|
|
60
82
|
sources: DesignHandoffEvidenceReference[];
|
|
61
|
-
requirements: Array<{
|
|
83
|
+
requirements: Array<{
|
|
84
|
+
id: string;
|
|
85
|
+
kind:
|
|
86
|
+
| 'behavior'
|
|
87
|
+
| 'visual-state'
|
|
88
|
+
| 'responsive'
|
|
89
|
+
| 'accessibility'
|
|
90
|
+
| 'content-data-assumption'
|
|
91
|
+
| 'constraint'
|
|
92
|
+
| 'verification-intent';
|
|
93
|
+
statement: string;
|
|
94
|
+
sourceRefs: string[];
|
|
95
|
+
verification: string[];
|
|
96
|
+
}>;
|
|
62
97
|
contentDigest: DesignHandoffDigest;
|
|
63
98
|
markdown: string;
|
|
64
|
-
approval?: {
|
|
99
|
+
approval?: {
|
|
100
|
+
actorId: string;
|
|
101
|
+
approvedAt: string;
|
|
102
|
+
contentDigest: DesignHandoffDigest;
|
|
103
|
+
authority: 'prepare-plan';
|
|
104
|
+
};
|
|
65
105
|
supersededBy?: { id: string; version: number; contentDigest: DesignHandoffDigest };
|
|
66
106
|
revocation?: { actorId: string; revokedAt: string; reason: string };
|
|
67
107
|
}
|
|
@@ -70,7 +110,11 @@ export interface DesignPlanningLineage {
|
|
|
70
110
|
schemaVersion: '1.0.0';
|
|
71
111
|
handoff: { id: string; version: number; contentDigest: DesignHandoffDigest };
|
|
72
112
|
specId: string;
|
|
73
|
-
mappings: Array<{
|
|
113
|
+
mappings: Array<{
|
|
114
|
+
requirementId: string;
|
|
115
|
+
acceptanceRefs: Array<{ storyId: string; acceptanceId: string }>;
|
|
116
|
+
taskIds: string[];
|
|
117
|
+
}>;
|
|
74
118
|
}
|
|
75
119
|
|
|
76
120
|
export declare const DESIGN_HANDOFF_PROTOCOL_VERSION: '1.11.0';
|
|
@@ -85,8 +129,20 @@ export declare const DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA: DesignHandoffSchema;
|
|
|
85
129
|
export declare const DESIGN_PLANNING_LINEAGE_SCHEMA: DesignHandoffSchema;
|
|
86
130
|
export declare const DESIGN_HANDOFF_SCHEMAS: Readonly<Record<string, DesignHandoffSchema>>;
|
|
87
131
|
export declare function isDesignHandoffRelativePath(value: unknown): value is string;
|
|
88
|
-
export declare function assertDesignHandoffContract<T>(
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
export declare function
|
|
132
|
+
export declare function assertDesignHandoffContract<T>(
|
|
133
|
+
value: T,
|
|
134
|
+
schemaOrName: DesignHandoffSchema | keyof typeof DESIGN_HANDOFF_SCHEMAS,
|
|
135
|
+
): T;
|
|
136
|
+
export declare function assertDesignHandoffReadiness<
|
|
137
|
+
T extends DesignHandoffReadiness | DesignHandoffReadinessAbsence,
|
|
138
|
+
>(value: T): T;
|
|
139
|
+
export declare function designImplementationHandoffDigest(
|
|
140
|
+
value: DesignImplementationHandoff,
|
|
141
|
+
): DesignHandoffDigest;
|
|
142
|
+
export declare function assertDesignImplementationHandoff<T extends DesignImplementationHandoff>(
|
|
143
|
+
value: T,
|
|
144
|
+
): T;
|
|
145
|
+
export declare function assertDesignPlanningLineage<T extends DesignPlanningLineage>(
|
|
146
|
+
value: T,
|
|
147
|
+
handoff?: DesignImplementationHandoff,
|
|
148
|
+
): T;
|