@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.
Files changed (58) hide show
  1. package/README.md +10 -0
  2. package/lib/dashboard/closed-json-contract.mjs +99 -109
  3. package/lib/dashboard/operate-experience-audit-display-contract.d.mts +128 -153
  4. package/lib/dashboard/operate-experience-audit-display-contract.mjs +530 -585
  5. package/lib/dashboard/operate-experience-display-contract.d.mts +415 -437
  6. package/lib/dashboard/operate-experience-display-contract.mjs +777 -831
  7. package/lib/dashboard/operate-experience-surface-contract.d.mts +143 -148
  8. package/lib/dashboard/operate-experience-surface-contract.mjs +72 -73
  9. package/lib/dashboard/operate-review-contract.d.mts +7 -14
  10. package/lib/dashboard/operate-review-contract.mjs +46 -42
  11. package/lib/dashboard/operate-review-display-workspace-contract.d.mts +2 -5
  12. package/lib/dashboard/operate-review-display-workspace-contract.mjs +158 -104
  13. package/lib/dashboard/operate-review-payload-safety.mjs +4 -2
  14. package/lib/dashboard/operate-review-workspace-projection-v2.d.mts +47 -33
  15. package/lib/protocol/index.d.ts +2647 -543
  16. package/package.json +1 -1
  17. package/registries/artifact-theme.json +64 -0
  18. package/registries/commands.json +40 -40
  19. package/registries/skills.json +5 -5
  20. package/schemas/v1.14.0/artifact-theme.schema.json +316 -0
  21. package/src/browser-contracts.d.mts +4 -1
  22. package/src/browser-contracts.mjs +16 -5
  23. package/src/canonical-json.d.mts +6 -1
  24. package/src/canonical-json.mjs +100 -22
  25. package/src/compat/live-evidence-v2.mjs +1611 -485
  26. package/src/compat/operate-experience-live-patch.mjs +67 -15
  27. package/src/compat/operating-planning-contracts.mjs +183 -51
  28. package/src/contracts.d.mts +54 -13
  29. package/src/contracts.mjs +635 -343
  30. package/src/design-contracts.mjs +58 -21
  31. package/src/design-handoff-contracts.d.mts +67 -11
  32. package/src/design-handoff-contracts.mjs +236 -119
  33. package/src/design-publication-contracts.mjs +98 -33
  34. package/src/diagram-authoring-contracts.d.mts +422 -78
  35. package/src/diagram-authoring-contracts.mjs +1715 -335
  36. package/src/diagram-contracts.d.mts +4 -1
  37. package/src/diagram-contracts.mjs +16 -4
  38. package/src/enterprise-contracts.d.mts +211 -46
  39. package/src/enterprise-contracts.mjs +738 -184
  40. package/src/errors.mjs +4 -0
  41. package/src/generated/canonical-registries.mjs +45 -45
  42. package/src/index.d.mts +8 -8
  43. package/src/index.mjs +36 -20
  44. package/src/json-schema.d.mts +21 -6
  45. package/src/json-schema.mjs +66 -18
  46. package/src/planning-contracts.d.mts +8 -2
  47. package/src/planning-contracts.mjs +33 -7
  48. package/src/registries.d.mts +11 -3
  49. package/src/registries.mjs +369 -87
  50. package/src/review-experience-contracts.d.mts +7 -2
  51. package/src/review-experience-contracts.mjs +198 -49
  52. package/src/semver.mjs +5 -1
  53. package/src/skill-source-contracts.d.mts +36 -16
  54. package/src/skill-source-contracts.mjs +25 -6
  55. package/src/task-contracts.d.mts +13 -3
  56. package/src/task-contracts.mjs +181 -40
  57. package/src/workspace-contracts.d.mts +38 -10
  58. package/src/workspace-contracts.mjs +147 -33
@@ -1,6 +1,10 @@
1
+ // @ts-check
1
2
  import { validateJson } from './json-schema.mjs';
2
3
 
3
- /** The authored document version is independent of the Protocol release. */
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', 'schemaVersion', 'id', 'title', 'brief', 'frames', 'screens',
27
- 'screenOrder', 'variants', 'selectedVariant', 'defaultView',
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', minItems: 1, uniqueItems: true,
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', minItems: 1,
75
+ type: 'array',
76
+ minItems: 1,
60
77
  items: {
61
- type: 'object', additionalProperties: false,
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', minItems: 1,
90
+ type: 'array',
91
+ minItems: 1,
73
92
  items: {
74
- type: 'object', additionalProperties: false,
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', additionalProperties: false,
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', minItems: 1,
120
+ type: 'array',
121
+ minItems: 1,
100
122
  items: {
101
- type: 'object', additionalProperties: false,
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', minLength: 1,
124
- description: 'Path relative to the authored document directory. No URL, traversal, encoded path, query or fragment.',
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', additionalProperties: false, required: ['html'],
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
- /** Validate structure plus stable identity and cross-reference constraints. */
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
- .map(({ path, detail }) => `${path}: ${detail}`);
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)) errors.push(`$.${field}[${index}].id: duplicate identity '${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') errors.push('$.selectedVariant: selected variant must be 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)) errors.push(`$.designSystem.spacing[${index}]: expected a finite spacing value`);
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
- /** Return the original valid document; never normalize authored design intent. */
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 { id: string; label: string }
6
+ export interface DesignHandoffAction {
7
+ id: string;
8
+ label: string;
9
+ }
7
10
  export interface DesignHandoffEvidenceReference {
8
11
  id: string;
9
- kind: 'design-revision' | 'selected-direction' | 'design-specification' | 'rendered-verification' | 'review-context' | 'review-feedback' | 'review-metadata' | 'review-handoff' | 'screen' | 'frame' | 'component' | 'state' | 'flow' | 'token' | 'review-decision' | 'element-anchor';
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?: { section: string } | { screenId: string; elementId?: string } | { reviewId: string; pinId: string };
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<{ id: string; kind: 'behavior' | 'visual-state' | 'responsive' | 'accessibility' | 'content-data-assumption' | 'constraint' | 'verification-intent'; statement: string; sourceRefs: string[]; verification: string[] }>;
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?: { actorId: string; approvedAt: string; contentDigest: DesignHandoffDigest; authority: 'prepare-plan' };
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<{ requirementId: string; acceptanceRefs: Array<{ storyId: string; acceptanceId: string }>; taskIds: string[] }>;
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>(value: T, schemaOrName: DesignHandoffSchema | keyof typeof DESIGN_HANDOFF_SCHEMAS): T;
89
- export declare function assertDesignHandoffReadiness<T extends DesignHandoffReadiness | DesignHandoffReadinessAbsence>(value: T): T;
90
- export declare function designImplementationHandoffDigest(value: DesignImplementationHandoff): DesignHandoffDigest;
91
- export declare function assertDesignImplementationHandoff<T extends DesignImplementationHandoff>(value: T): T;
92
- export declare function assertDesignPlanningLineage<T extends DesignPlanningLineage>(value: T, handoff?: DesignImplementationHandoff): T;
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;