@ccdd/core 3.3.1 → 4.0.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 (38) hide show
  1. package/README.md +69 -62
  2. package/dist/src/artifact-scope.d.ts +6 -0
  3. package/dist/src/artifact-scope.js +27 -0
  4. package/dist/src/artifact-scope.js.map +1 -0
  5. package/dist/src/definitions.d.ts +33 -23
  6. package/dist/src/sdk.d.ts +3 -8
  7. package/dist/src/sdk.js +2 -3
  8. package/dist/src/sdk.js.map +1 -1
  9. package/dist/src/tools/contracts.d.ts +34 -78
  10. package/examples/artifact-folders/README.md +18 -0
  11. package/examples/artifact-folders/coding-style/ccdd.json +128 -0
  12. package/examples/artifact-folders/coding-style/style.md +3 -0
  13. package/examples/artifact-folders/explosion/blind-pair.mjs +19 -0
  14. package/examples/artifact-folders/explosion/ccdd.json +220 -0
  15. package/examples/artifact-folders/explosion/effect/ccdd.json +128 -0
  16. package/examples/artifact-folders/explosion/preview/ccdd.json +142 -0
  17. package/examples/artifact-folders/theme-image/ccdd.json +128 -0
  18. package/examples/artifact-folders/theme-image/theme.png +0 -0
  19. package/examples/computed-views/README.md +12 -0
  20. package/examples/computed-views/checkout/ccdd.json +133 -0
  21. package/examples/computed-views/search/ccdd.json +133 -0
  22. package/examples/computed-views/view.mjs +13 -0
  23. package/examples/custom-text-reader/README.md +7 -19
  24. package/examples/custom-text-reader/spec/ccdd.json +60 -0
  25. package/examples/custom-text-reader/view.mjs +20 -0
  26. package/examples/custom-text-reader/why/ccdd.json +46 -0
  27. package/package.json +21 -7
  28. package/examples/artifact-groups/README.md +0 -60
  29. package/examples/artifact-groups/ccdd.config.ts +0 -37
  30. package/examples/custom-text-reader/ccdd.config.ts +0 -64
  31. package/examples/generated-artifacts/README.md +0 -55
  32. package/examples/generated-artifacts/ccdd.config.ts +0 -86
  33. /package/examples/{artifact-groups → artifact-folders/explosion/effect}/effect.md +0 -0
  34. /package/examples/{artifact-groups → artifact-folders/explosion/preview}/preview.png +0 -0
  35. /package/examples/{generated-artifacts/scenarios/checkout.json → computed-views/checkout/scenario.json} +0 -0
  36. /package/examples/{generated-artifacts/scenarios/search.json → computed-views/search/scenario.json} +0 -0
  37. /package/examples/custom-text-reader/{spec.md → spec/spec.md} +0 -0
  38. /package/examples/custom-text-reader/{why.md → why/why.md} +0 -0
package/examples/artifact-folders/explosion/blind-pair.mjs ADDED
@@ -0,0 +1,19 @@
1
+ import { readFile, writeFile } from 'node:fs/promises';
2
+ import { join } from 'node:path';
3
+ import { randomInt } from 'node:crypto';
4
+ import { resolveScopePath } from '@ccdd/core';
5
+ let text = '';
6
+ for await (const chunk of process.stdin) text += chunk;
7
+ const { version, context } = JSON.parse(text);
8
+ if (version !== 1) throw new Error('Unsupported request version.');
9
+ const names = ['theme/theme.png', 'preview/preview.png'];
10
+ if (randomInt(2)) names.reverse();
11
+ const content = [];
12
+ for (const [index, name] of names.entries()) {
13
+ const resolved = resolveScopePath(context.scope, context.artifactId, name);
14
+ const bytes = await readFile(join(context.scope[resolved.artifactId].path, resolved.path));
15
+ content.push({ type: 'text', text: index === 0 ? 'A' : 'B' }, { type: 'image', data: bytes.toString('base64'), mimeType: 'image/png' });
16
+ }
17
+ // Keep the mapping for the requester outside the input; never return it to the reviewer.
18
+ await writeFile(join(context.outputDir, 'pair-map.json'), JSON.stringify(names));
19
+ process.stdout.write(JSON.stringify({ content, observation: { kind: 'content' } }));
package/examples/artifact-folders/explosion/ccdd.json ADDED
@@ -0,0 +1,220 @@
1
+ {
2
+ "name": "explosion",
3
+ "views": {
4
+ "agentTools": {
5
+ "read": {
6
+ "metadata": {
7
+ "description": "Inspect {artifactName} with read.",
8
+ "inputSchema": {
9
+ "type": "object",
10
+ "properties": {
11
+ "path": {
12
+ "type": "string"
13
+ }
14
+ },
15
+ "additionalProperties": false,
16
+ "required": [
17
+ "path"
18
+ ]
19
+ },
20
+ "resultKinds": [
21
+ "json"
22
+ ],
23
+ "observation": "content",
24
+ "executionPaths": [
25
+ "node_modules/@ccdd/core/dist",
26
+ "node_modules/@ccdd/default-tools/dist"
27
+ ]
28
+ },
29
+ "script": {
30
+ "command": "ccdd-view",
31
+ "args": [
32
+ "read"
33
+ ]
34
+ }
35
+ },
36
+ "list": {
37
+ "metadata": {
38
+ "description": "Inspect {artifactName} with list.",
39
+ "inputSchema": {
40
+ "type": "object",
41
+ "properties": {
42
+ "path": {
43
+ "type": "string"
44
+ }
45
+ },
46
+ "additionalProperties": false
47
+ },
48
+ "resultKinds": [
49
+ "json"
50
+ ],
51
+ "observation": "none",
52
+ "executionPaths": [
53
+ "node_modules/@ccdd/core/dist",
54
+ "node_modules/@ccdd/default-tools/dist"
55
+ ]
56
+ },
57
+ "script": {
58
+ "command": "ccdd-view",
59
+ "args": [
60
+ "list"
61
+ ]
62
+ }
63
+ },
64
+ "image": {
65
+ "metadata": {
66
+ "description": "Inspect {artifactName} with image.",
67
+ "inputSchema": {
68
+ "type": "object",
69
+ "properties": {
70
+ "path": {
71
+ "type": "string"
72
+ }
73
+ },
74
+ "additionalProperties": false,
75
+ "required": [
76
+ "path"
77
+ ]
78
+ },
79
+ "resultKinds": [
80
+ "image"
81
+ ],
82
+ "observation": "content",
83
+ "executionPaths": [
84
+ "node_modules/@ccdd/core/dist",
85
+ "node_modules/@ccdd/default-tools/dist"
86
+ ]
87
+ },
88
+ "script": {
89
+ "command": "ccdd-view",
90
+ "args": [
91
+ "image"
92
+ ]
93
+ }
94
+ },
95
+ "blind_pair": {
96
+ "metadata": {
97
+ "description": "Inspect {artifactName} with blind_pair.",
98
+ "inputSchema": {
99
+ "type": "object",
100
+ "properties": {},
101
+ "additionalProperties": false
102
+ },
103
+ "resultKinds": [
104
+ "text",
105
+ "image"
106
+ ],
107
+ "observation": "content",
108
+ "executionPaths": [
109
+ "node_modules/@ccdd/core/dist"
110
+ ]
111
+ },
112
+ "script": {
113
+ "command": "node",
114
+ "args": [
115
+ "blind-pair.mjs"
116
+ ]
117
+ }
118
+ }
119
+ },
120
+ "humanTools": {
121
+ "open": {
122
+ "metadata": {
123
+ "description": "Inspect {artifactName} with open.",
124
+ "inputSchema": {
125
+ "type": "object",
126
+ "properties": {
127
+ "path": {
128
+ "type": "string"
129
+ }
130
+ },
131
+ "additionalProperties": false
132
+ },
133
+ "resultKinds": [
134
+ "launch"
135
+ ],
136
+ "observation": "none",
137
+ "executionPaths": [
138
+ "node_modules/@ccdd/core/dist",
139
+ "node_modules/@ccdd/default-tools/dist"
140
+ ]
141
+ },
142
+ "script": {
143
+ "command": "ccdd-view",
144
+ "args": [
145
+ "open"
146
+ ]
147
+ }
148
+ },
149
+ "blind_pair": {
150
+ "metadata": {
151
+ "description": "Inspect {artifactName} with blind_pair.",
152
+ "inputSchema": {
153
+ "type": "object",
154
+ "properties": {},
155
+ "additionalProperties": false
156
+ },
157
+ "resultKinds": [
158
+ "text",
159
+ "image"
160
+ ],
161
+ "observation": "content",
162
+ "executionPaths": [
163
+ "node_modules/@ccdd/core/dist"
164
+ ]
165
+ },
166
+ "script": {
167
+ "command": "node",
168
+ "args": [
169
+ "blind-pair.mjs"
170
+ ]
171
+ }
172
+ }
173
+ }
174
+ },
175
+ "mounts": {
176
+ "style": "coding-style",
177
+ "theme": "theme-image"
178
+ },
179
+ "critics": [
180
+ {
181
+ "id": "coding-style",
182
+ "title": "Check script conventions",
183
+ "profile": {
184
+ "kind": "agent",
185
+ "provider": "openai-codex",
186
+ "model": "gpt-6-astra",
187
+ "reasoning": "medium"
188
+ },
189
+ "payload": {
190
+ "instruction": "Read the script in {explosion} and the rules in {style}. Decide whether the script follows those rules and keeps the Artifact boundary."
191
+ }
192
+ },
193
+ {
194
+ "id": "appearance",
195
+ "title": "Compare the anonymous theme and preview",
196
+ "profile": {
197
+ "kind": "agent",
198
+ "provider": "openai-codex",
199
+ "model": "gpt-6-astra",
200
+ "reasoning": "medium"
201
+ },
202
+ "payload": {
203
+ "instruction": "Use blind_pair on {explosion}. Compare images A and B without opening named image views. Decide whether their palette and shape match; cite visible differences. Animation and runtime behavior are outside this static review."
204
+ }
205
+ },
206
+ {
207
+ "id": "description",
208
+ "title": "Match the effect description",
209
+ "profile": {
210
+ "kind": "agent",
211
+ "provider": "openai-codex",
212
+ "model": "gpt-6-astra",
213
+ "reasoning": "medium"
214
+ },
215
+ "payload": {
216
+ "instruction": "Inspect {explosion}, {effect} and {preview}; decide whether the static preview matches the description."
217
+ }
218
+ }
219
+ ]
220
+ }
package/examples/artifact-folders/explosion/effect/ccdd.json ADDED
@@ -0,0 +1,128 @@
1
+ {
2
+ "name": "effect",
3
+ "views": {
4
+ "agentTools": {
5
+ "read": {
6
+ "metadata": {
7
+ "description": "Inspect {artifactName} with read.",
8
+ "inputSchema": {
9
+ "type": "object",
10
+ "properties": {
11
+ "path": {
12
+ "type": "string"
13
+ }
14
+ },
15
+ "additionalProperties": false,
16
+ "required": [
17
+ "path"
18
+ ]
19
+ },
20
+ "resultKinds": [
21
+ "json"
22
+ ],
23
+ "observation": "content",
24
+ "executionPaths": [
25
+ "node_modules/@ccdd/core/dist",
26
+ "node_modules/@ccdd/default-tools/dist"
27
+ ]
28
+ },
29
+ "script": {
30
+ "command": "ccdd-view",
31
+ "args": [
32
+ "read"
33
+ ]
34
+ }
35
+ },
36
+ "list": {
37
+ "metadata": {
38
+ "description": "Inspect {artifactName} with list.",
39
+ "inputSchema": {
40
+ "type": "object",
41
+ "properties": {
42
+ "path": {
43
+ "type": "string"
44
+ }
45
+ },
46
+ "additionalProperties": false
47
+ },
48
+ "resultKinds": [
49
+ "json"
50
+ ],
51
+ "observation": "none",
52
+ "executionPaths": [
53
+ "node_modules/@ccdd/core/dist",
54
+ "node_modules/@ccdd/default-tools/dist"
55
+ ]
56
+ },
57
+ "script": {
58
+ "command": "ccdd-view",
59
+ "args": [
60
+ "list"
61
+ ]
62
+ }
63
+ },
64
+ "image": {
65
+ "metadata": {
66
+ "description": "Inspect {artifactName} with image.",
67
+ "inputSchema": {
68
+ "type": "object",
69
+ "properties": {
70
+ "path": {
71
+ "type": "string"
72
+ }
73
+ },
74
+ "additionalProperties": false,
75
+ "required": [
76
+ "path"
77
+ ]
78
+ },
79
+ "resultKinds": [
80
+ "image"
81
+ ],
82
+ "observation": "content",
83
+ "executionPaths": [
84
+ "node_modules/@ccdd/core/dist",
85
+ "node_modules/@ccdd/default-tools/dist"
86
+ ]
87
+ },
88
+ "script": {
89
+ "command": "ccdd-view",
90
+ "args": [
91
+ "image"
92
+ ]
93
+ }
94
+ }
95
+ },
96
+ "humanTools": {
97
+ "open": {
98
+ "metadata": {
99
+ "description": "Inspect {artifactName} with open.",
100
+ "inputSchema": {
101
+ "type": "object",
102
+ "properties": {
103
+ "path": {
104
+ "type": "string"
105
+ }
106
+ },
107
+ "additionalProperties": false
108
+ },
109
+ "resultKinds": [
110
+ "launch"
111
+ ],
112
+ "observation": "none",
113
+ "executionPaths": [
114
+ "node_modules/@ccdd/core/dist",
115
+ "node_modules/@ccdd/default-tools/dist"
116
+ ]
117
+ },
118
+ "script": {
119
+ "command": "ccdd-view",
120
+ "args": [
121
+ "open"
122
+ ]
123
+ }
124
+ }
125
+ }
126
+ },
127
+ "basis": true
128
+ }
package/examples/artifact-folders/explosion/preview/ccdd.json ADDED
@@ -0,0 +1,142 @@
1
+ {
2
+ "name": "preview",
3
+ "views": {
4
+ "agentTools": {
5
+ "read": {
6
+ "metadata": {
7
+ "description": "Inspect {artifactName} with read.",
8
+ "inputSchema": {
9
+ "type": "object",
10
+ "properties": {
11
+ "path": {
12
+ "type": "string"
13
+ }
14
+ },
15
+ "additionalProperties": false,
16
+ "required": [
17
+ "path"
18
+ ]
19
+ },
20
+ "resultKinds": [
21
+ "json"
22
+ ],
23
+ "observation": "content",
24
+ "executionPaths": [
25
+ "node_modules/@ccdd/core/dist",
26
+ "node_modules/@ccdd/default-tools/dist"
27
+ ]
28
+ },
29
+ "script": {
30
+ "command": "ccdd-view",
31
+ "args": [
32
+ "read"
33
+ ]
34
+ }
35
+ },
36
+ "list": {
37
+ "metadata": {
38
+ "description": "Inspect {artifactName} with list.",
39
+ "inputSchema": {
40
+ "type": "object",
41
+ "properties": {
42
+ "path": {
43
+ "type": "string"
44
+ }
45
+ },
46
+ "additionalProperties": false
47
+ },
48
+ "resultKinds": [
49
+ "json"
50
+ ],
51
+ "observation": "none",
52
+ "executionPaths": [
53
+ "node_modules/@ccdd/core/dist",
54
+ "node_modules/@ccdd/default-tools/dist"
55
+ ]
56
+ },
57
+ "script": {
58
+ "command": "ccdd-view",
59
+ "args": [
60
+ "list"
61
+ ]
62
+ }
63
+ },
64
+ "image": {
65
+ "metadata": {
66
+ "description": "Inspect {artifactName} with image.",
67
+ "inputSchema": {
68
+ "type": "object",
69
+ "properties": {
70
+ "path": {
71
+ "type": "string"
72
+ }
73
+ },
74
+ "additionalProperties": false,
75
+ "required": [
76
+ "path"
77
+ ]
78
+ },
79
+ "resultKinds": [
80
+ "image"
81
+ ],
82
+ "observation": "content",
83
+ "executionPaths": [
84
+ "node_modules/@ccdd/core/dist",
85
+ "node_modules/@ccdd/default-tools/dist"
86
+ ]
87
+ },
88
+ "script": {
89
+ "command": "ccdd-view",
90
+ "args": [
91
+ "image"
92
+ ]
93
+ }
94
+ }
95
+ },
96
+ "humanTools": {
97
+ "open": {
98
+ "metadata": {
99
+ "description": "Inspect {artifactName} with open.",
100
+ "inputSchema": {
101
+ "type": "object",
102
+ "properties": {
103
+ "path": {
104
+ "type": "string"
105
+ }
106
+ },
107
+ "additionalProperties": false
108
+ },
109
+ "resultKinds": [
110
+ "launch"
111
+ ],
112
+ "observation": "none",
113
+ "executionPaths": [
114
+ "node_modules/@ccdd/core/dist",
115
+ "node_modules/@ccdd/default-tools/dist"
116
+ ]
117
+ },
118
+ "script": {
119
+ "command": "ccdd-view",
120
+ "args": [
121
+ "open"
122
+ ]
123
+ }
124
+ }
125
+ }
126
+ },
127
+ "critics": [
128
+ {
129
+ "id": "visibility",
130
+ "title": "Image visibility",
131
+ "profile": {
132
+ "kind": "agent",
133
+ "provider": "openai-codex",
134
+ "model": "gpt-6-astra",
135
+ "reasoning": "medium"
136
+ },
137
+ "payload": {
138
+ "instruction": "Inspect {preview}; check for a bright center and an orange ring distinguishable from the dark background."
139
+ }
140
+ }
141
+ ]
142
+ }
package/examples/artifact-folders/theme-image/ccdd.json ADDED
@@ -0,0 +1,128 @@
1
+ {
2
+ "name": "theme-image",
3
+ "views": {
4
+ "agentTools": {
5
+ "read": {
6
+ "metadata": {
7
+ "description": "Inspect {artifactName} with read.",
8
+ "inputSchema": {
9
+ "type": "object",
10
+ "properties": {
11
+ "path": {
12
+ "type": "string"
13
+ }
14
+ },
15
+ "additionalProperties": false,
16
+ "required": [
17
+ "path"
18
+ ]
19
+ },
20
+ "resultKinds": [
21
+ "json"
22
+ ],
23
+ "observation": "content",
24
+ "executionPaths": [
25
+ "node_modules/@ccdd/core/dist",
26
+ "node_modules/@ccdd/default-tools/dist"
27
+ ]
28
+ },
29
+ "script": {
30
+ "command": "ccdd-view",
31
+ "args": [
32
+ "read"
33
+ ]
34
+ }
35
+ },
36
+ "list": {
37
+ "metadata": {
38
+ "description": "Inspect {artifactName} with list.",
39
+ "inputSchema": {
40
+ "type": "object",
41
+ "properties": {
42
+ "path": {
43
+ "type": "string"
44
+ }
45
+ },
46
+ "additionalProperties": false
47
+ },
48
+ "resultKinds": [
49
+ "json"
50
+ ],
51
+ "observation": "none",
52
+ "executionPaths": [
53
+ "node_modules/@ccdd/core/dist",
54
+ "node_modules/@ccdd/default-tools/dist"
55
+ ]
56
+ },
57
+ "script": {
58
+ "command": "ccdd-view",
59
+ "args": [
60
+ "list"
61
+ ]
62
+ }
63
+ },
64
+ "image": {
65
+ "metadata": {
66
+ "description": "Inspect {artifactName} with image.",
67
+ "inputSchema": {
68
+ "type": "object",
69
+ "properties": {
70
+ "path": {
71
+ "type": "string"
72
+ }
73
+ },
74
+ "additionalProperties": false,
75
+ "required": [
76
+ "path"
77
+ ]
78
+ },
79
+ "resultKinds": [
80
+ "image"
81
+ ],
82
+ "observation": "content",
83
+ "executionPaths": [
84
+ "node_modules/@ccdd/core/dist",
85
+ "node_modules/@ccdd/default-tools/dist"
86
+ ]
87
+ },
88
+ "script": {
89
+ "command": "ccdd-view",
90
+ "args": [
91
+ "image"
92
+ ]
93
+ }
94
+ }
95
+ },
96
+ "humanTools": {
97
+ "open": {
98
+ "metadata": {
99
+ "description": "Inspect {artifactName} with open.",
100
+ "inputSchema": {
101
+ "type": "object",
102
+ "properties": {
103
+ "path": {
104
+ "type": "string"
105
+ }
106
+ },
107
+ "additionalProperties": false
108
+ },
109
+ "resultKinds": [
110
+ "launch"
111
+ ],
112
+ "observation": "none",
113
+ "executionPaths": [
114
+ "node_modules/@ccdd/core/dist",
115
+ "node_modules/@ccdd/default-tools/dist"
116
+ ]
117
+ },
118
+ "script": {
119
+ "command": "ccdd-view",
120
+ "args": [
121
+ "open"
122
+ ]
123
+ }
124
+ }
125
+ }
126
+ },
127
+ "basis": true
128
+ }
package/examples/computed-views/README.md ADDED
@@ -0,0 +1,12 @@
1
+ # Computed views
2
+
3
+ Each scenario is an actual Artifact folder with its own `ccdd.json`. `view.mjs` computes an overview or selects one detail when the reviewer calls its registered tool. CCDD does not generate or freeze JSON data during discovery.
4
+
5
+ ```sh
6
+ ccdd-project config check
7
+ ccdd-project tools check --artifact checkout --for human --tool overview --execute
8
+ ccdd-project verify checkout --human-inbox
9
+ ccdd-project monitor
10
+ ```
11
+
12
+ Run these commands from this directory after installing `@ccdd/core` and `@ccdd/project`. Submit the Human verdict explicitly through the monitor. Scenario files, the manifest and the shared script determine input identity. Output belongs in `context.outputDir`, outside the supplied workspace. Parameter combinations that generate Artifact declarations are not supported in version 4.