@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,3 +1,4 @@
1
+ // @ts-check
1
2
  /**
2
3
  * Minimal JSON Schema (draft 2020-12) subset extracted from conformance/runner.mjs.
3
4
  * Supports the constructs used by packaged Protocol schemas, including local
@@ -80,14 +81,22 @@ const validateNode = (value, schema, path, errs, context) => {
80
81
  if (schema.type !== undefined) {
81
82
  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
82
83
  if (!types.some((t) => matchesType(value, t))) {
83
- errs.push({ path, rule: 'type', detail: `expected ${types.join('|')}, got ${typeOf(value)}` });
84
+ errs.push({
85
+ path,
86
+ rule: 'type',
87
+ detail: `expected ${types.join('|')}, got ${typeOf(value)}`,
88
+ });
84
89
  return;
85
90
  }
86
91
  }
87
92
 
88
93
  if (schema.const !== undefined) {
89
94
  if (value !== schema.const) {
90
- errs.push({ path, rule: 'const', detail: `expected ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}` });
95
+ errs.push({
96
+ path,
97
+ rule: 'const',
98
+ detail: `expected ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`,
99
+ });
91
100
  }
92
101
  }
93
102
 
@@ -103,25 +112,49 @@ const validateNode = (value, schema, path, errs, context) => {
103
112
 
104
113
  if (typeof value === 'string') {
105
114
  if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
106
- errs.push({ path, rule: 'minLength', detail: `length ${value.length} < ${schema.minLength}` });
115
+ errs.push({
116
+ path,
117
+ rule: 'minLength',
118
+ detail: `length ${value.length} < ${schema.minLength}`,
119
+ });
107
120
  }
108
121
  if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
109
- errs.push({ path, rule: 'maxLength', detail: `length ${value.length} > ${schema.maxLength}` });
122
+ errs.push({
123
+ path,
124
+ rule: 'maxLength',
125
+ detail: `length ${value.length} > ${schema.maxLength}`,
126
+ });
110
127
  }
111
128
  if (typeof schema.pattern === 'string') {
112
129
  try {
113
130
  if (!new RegExp(schema.pattern).test(value)) {
114
- errs.push({ path, rule: 'pattern', detail: `value ${JSON.stringify(value)} does not match /${schema.pattern}/` });
131
+ errs.push({
132
+ path,
133
+ rule: 'pattern',
134
+ detail: `value ${JSON.stringify(value)} does not match /${schema.pattern}/`,
135
+ });
115
136
  }
116
137
  } catch (e) {
117
- errs.push({ path, rule: 'pattern', detail: `invalid regex /${schema.pattern}/: ${e.message}` });
138
+ errs.push({
139
+ path,
140
+ rule: 'pattern',
141
+ detail: `invalid regex /${schema.pattern}/: ${e instanceof Error ? e.message : String(e)}`,
142
+ });
118
143
  }
119
144
  }
120
145
  if (typeof schema.format === 'string') {
121
146
  if (schema.format === 'date' && !FORMAT_DATE.test(value)) {
122
- errs.push({ path, rule: 'format:date', detail: `value ${JSON.stringify(value)} is not YYYY-MM-DD` });
147
+ errs.push({
148
+ path,
149
+ rule: 'format:date',
150
+ detail: `value ${JSON.stringify(value)} is not YYYY-MM-DD`,
151
+ });
123
152
  } else if (schema.format === 'date-time' && !FORMAT_DATETIME.test(value)) {
124
- errs.push({ path, rule: 'format:date-time', detail: `value ${JSON.stringify(value)} is not ISO 8601 date-time` });
153
+ errs.push({
154
+ path,
155
+ rule: 'format:date-time',
156
+ detail: `value ${JSON.stringify(value)} is not ISO 8601 date-time`,
157
+ });
125
158
  }
126
159
  }
127
160
  }
@@ -174,10 +207,18 @@ const validateNode = (value, schema, path, errs, context) => {
174
207
  const minimum = Number.isSafeInteger(schema.minContains) ? schema.minContains : 1;
175
208
  const maximum = Number.isSafeInteger(schema.maxContains) ? schema.maxContains : null;
176
209
  if (matches < minimum) {
177
- errs.push({ path, rule: 'contains', detail: `matched ${matches} contained items; expected at least ${minimum}` });
210
+ errs.push({
211
+ path,
212
+ rule: 'contains',
213
+ detail: `matched ${matches} contained items; expected at least ${minimum}`,
214
+ });
178
215
  }
179
216
  if (maximum !== null && matches > maximum) {
180
- errs.push({ path, rule: 'contains', detail: `matched ${matches} contained items; expected at most ${maximum}` });
217
+ errs.push({
218
+ path,
219
+ rule: 'contains',
220
+ detail: `matched ${matches} contained items; expected at most ${maximum}`,
221
+ });
181
222
  }
182
223
  }
183
224
  }
@@ -196,8 +237,8 @@ const validateNode = (value, schema, path, errs, context) => {
196
237
  if (schema.additionalProperties === false) {
197
238
  errs.push({ path, rule: 'additionalProperties', detail: `unknown property '${k}'` });
198
239
  } else if (
199
- schema.additionalProperties === true
200
- || (schema.additionalProperties !== null && typeof schema.additionalProperties === 'object')
240
+ schema.additionalProperties === true ||
241
+ (schema.additionalProperties !== null && typeof schema.additionalProperties === 'object')
201
242
  ) {
202
243
  validateNode(v, schema.additionalProperties, `${path}.${k}`, errs, context);
203
244
  }
@@ -264,11 +305,15 @@ const validateNode = (value, schema, path, errs, context) => {
264
305
  }
265
306
  };
266
307
 
267
- /** @returns {{ path: string, rule: string, detail: string }[]} */
268
- export const validateJson = (value, schema, {
269
- resolveRef = null,
270
- base = schema?.$id ?? null,
271
- } = {}) => {
308
+ /** @type {typeof import('./json-schema.d.mts').validateJson} */
309
+ export const validateJson = (
310
+ value,
311
+ schema,
312
+ {
313
+ resolveRef,
314
+ base = /** @type {{ $id?: string } | null | undefined} */ (schema)?.$id ?? null,
315
+ } = {},
316
+ ) => {
272
317
  const errs = [];
273
318
  validateNode(value, schema, '$', errs, {
274
319
  rootSchema: schema,
@@ -279,5 +324,8 @@ export const validateJson = (value, schema, {
279
324
  return errs;
280
325
  };
281
326
 
282
- /** Alias matching legacy runner export name. */
327
+ /**
328
+ * Alias matching legacy runner export name.
329
+ * @type {typeof import('./json-schema.d.mts').validate}
330
+ */
283
331
  export const validate = validateJson;
@@ -1,5 +1,11 @@
1
- export interface PlanningIssue { path: string; rule: string; detail: string }
2
- export declare function normalizePlanningTask<T extends Record<string, unknown>>(value: T): T & {
1
+ export interface PlanningIssue {
2
+ path: string;
3
+ rule: string;
4
+ detail: string;
5
+ }
6
+ export declare function normalizePlanningTask<T extends Record<string, unknown>>(
7
+ value: T,
8
+ ): T & {
3
9
  reviewRisks: string[];
4
10
  browserSurfaces: string[];
5
11
  acceptanceRefs: string[];
@@ -1,10 +1,14 @@
1
+ // @ts-check
1
2
  const LEGACY_TASK_FIELDS = Object.freeze({
2
3
  review_risks: 'reviewRisks',
3
4
  browser_surfaces: 'browserSurfaces',
4
5
  acceptance_refs: 'acceptanceRefs',
5
6
  });
6
7
 
7
- /** Translate released snake-case task metadata into the canonical 1.7 names. */
8
+ /**
9
+ * Translate released snake-case task metadata into the canonical 1.7 names.
10
+ * @returns {ReturnType<typeof import('./planning-contracts.d.mts').normalizePlanningTask>}
11
+ */
8
12
  export function normalizePlanningTask(value) {
9
13
  const task = structuredClone(value ?? {});
10
14
  for (const [legacy, canonical] of Object.entries(LEGACY_TASK_FIELDS)) {
@@ -17,7 +21,10 @@ export function normalizePlanningTask(value) {
17
21
  return task;
18
22
  }
19
23
 
20
- /** Validate that every story criterion is assigned and named in task verification. */
24
+ /**
25
+ * Validate that every story criterion is assigned and named in task verification.
26
+ * @returns {ReturnType<typeof import('./planning-contracts.d.mts').validatePlanningAcceptanceCoverage>}
27
+ */
21
28
  export function validatePlanningAcceptanceCoverage(stories, tasks) {
22
29
  const issues = [];
23
30
  const tasksByStory = new Map();
@@ -31,21 +38,40 @@ export function validatePlanningAcceptanceCoverage(stories, tasks) {
31
38
  const criteria = story.acceptanceCriteria ?? [];
32
39
  const ids = new Set(criteria.map((criterion) => criterion.id));
33
40
  if (ids.size !== criteria.length) {
34
- issues.push({ path: `${story.id}.acceptanceCriteria`, rule: 'unique', detail: 'Acceptance IDs must be unique within the story.' });
41
+ issues.push({
42
+ path: `${story.id}.acceptanceCriteria`,
43
+ rule: 'unique',
44
+ detail: 'Acceptance IDs must be unique within the story.',
45
+ });
35
46
  }
36
47
  for (const criterion of criteria) {
37
- const mapped = (tasksByStory.get(story.id) ?? []).filter((task) => task.acceptanceRefs.includes(criterion.id));
48
+ const mapped = (tasksByStory.get(story.id) ?? []).filter((task) =>
49
+ task.acceptanceRefs.includes(criterion.id),
50
+ );
38
51
  if (mapped.length === 0) {
39
- issues.push({ path: `${story.id}.${criterion.id}`, rule: 'coverage', detail: 'Acceptance criterion is not mapped to a task.' });
52
+ issues.push({
53
+ path: `${story.id}.${criterion.id}`,
54
+ rule: 'coverage',
55
+ detail: 'Acceptance criterion is not mapped to a task.',
56
+ });
40
57
  continue;
41
58
  }
42
59
  if (mapped.every((task) => !String(task.testRequirements ?? '').includes(criterion.id))) {
43
- issues.push({ path: `${story.id}.${criterion.id}`, rule: 'verification', detail: 'A mapped task must name the acceptance ID in Test Requirements.' });
60
+ issues.push({
61
+ path: `${story.id}.${criterion.id}`,
62
+ rule: 'verification',
63
+ detail: 'A mapped task must name the acceptance ID in Test Requirements.',
64
+ });
44
65
  }
45
66
  }
46
67
  for (const task of tasksByStory.get(story.id) ?? []) {
47
68
  for (const reference of task.acceptanceRefs) {
48
- if (!ids.has(reference)) issues.push({ path: `${task.id}.acceptanceRefs`, rule: 'reference', detail: `${reference} is not declared by ${story.id}.` });
69
+ if (!ids.has(reference))
70
+ issues.push({
71
+ path: `${task.id}.acceptanceRefs`,
72
+ rule: 'reference',
73
+ detail: `${reference} is not declared by ${story.id}.`,
74
+ });
49
75
  }
50
76
  }
51
77
  }
@@ -21,12 +21,17 @@ export interface ResolveOutputPathOptions {
21
21
  readonly pathArguments?: Readonly<Record<string, string>>;
22
22
  }
23
23
  export declare const CANONICAL_REGISTRIES: CanonicalRegistries;
24
- export declare function getCanonicalRegistry(name: keyof CanonicalRegistries): Record<string, unknown>;
24
+ export declare function getCanonicalRegistry(
25
+ name: keyof CanonicalRegistries,
26
+ ): Record<string, unknown>;
25
27
  export declare function validateCanonicalRegistries(registries?: CanonicalRegistries): true;
26
28
  export declare function getRole(roleId: string): Record<string, unknown>;
27
29
  export declare function resolveLegacyRoleAlias(alias: string): Record<string, unknown> | null;
28
30
  export declare function resolveTaskKind(taskKind: string): Record<string, unknown>;
29
- export declare function getOutput(outputId: string, registries?: CanonicalRegistries): OutputCatalogEntry;
31
+ export declare function getOutput(
32
+ outputId: string,
33
+ registries?: CanonicalRegistries,
34
+ ): OutputCatalogEntry;
30
35
  export declare function getOutputPathTemplate(
31
36
  outputId: string,
32
37
  projectMode?: OutputProjectMode,
@@ -37,4 +42,7 @@ export declare function resolveOutputPath(
37
42
  options?: ResolveOutputPathOptions,
38
43
  registries?: CanonicalRegistries,
39
44
  ): string;
40
- export declare function routeLegacyTask(value: { legacyType: 'UI' | 'Tech'; legacyAgent?: string | null }): Record<string, unknown>;
45
+ export declare function routeLegacyTask(value: {
46
+ legacyType: 'UI' | 'Tech';
47
+ legacyAgent?: string | null;
48
+ }): Record<string, unknown>;