Skip to content

Commit 632be91

Browse files
author
DavidQ
committed
Add reusable control, service, logger, and batch contracts for first-class tools - PR_26126_064-tool-control-service-contracts
1 parent 4264ae6 commit 632be91

3 files changed

Lines changed: 199 additions & 1 deletion

File tree

‎docs/dev/reports/tool_control_service_contracts.txt‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# PR_26126_064 Tool Control Service Contracts
2+
3+
Scope:
4+
- Added reusable first-class tool contracts under tools/templates.
5+
- Updated the first-class tool starter README to reference the contracts.
6+
- No live tool runtime, sample, schema, roadmap, or start_of_day files were modified.
7+
8+
Contract document added:
9+
- tools/templates/first-class-tool-starter/docs/CONTROL_SERVICE_CONTRACTS.md
10+
11+
Contracts defined:
12+
- Control contract: one control or section per class, owns DOM references, owns event binding, exposes clear methods such as init/mount, bindEvents, getValue, setValue, validate, and does not reach into sibling controls directly.
13+
- Service contract: services contain non-DOM logic, do not manipulate UI directly, and return data/errors for controls, app/root, or logger to display.
14+
- App/root contract: coordinator only, wires controls and services, and does not own DOM logic or business logic.
15+
- Logger contract: single writer for status/log output with OK, WARN, FAIL, SKIP, and INFO levels.
16+
- Batch Processor contract: processes real discovered inputs only, logs per item, summarizes written/failed/skipped/warnings, and continues item processing unless the failure is global.
17+
18+
README update:
19+
- tools/templates/first-class-tool-starter/README.md now lists docs/CONTROL_SERVICE_CONTRACTS.md in the folder structure and required files.
20+
- README now has a Required Contracts section and summarizes the contract categories.
21+
22+
Validation:
23+
- Playwright impacted: No
24+
- No Playwright impact. This PR is docs/template-contract only and changes no active runtime behavior.
25+
- Confirmed the contract document contains the required contract sections and logger levels.
26+
- Confirmed the template README references the contract document.
27+
- Confirmed no roadmap, sample, schema, start_of_day, tools/shared, package, src, or games files changed.
28+
- npm run test:workspace-v2 was not run because this is documentation-only for the starter contract.
29+
30+
Manual test notes:
31+
- Read tools/templates/first-class-tool-starter/docs/CONTROL_SERVICE_CONTRACTS.md and confirm the control/service/app/logger/batch boundaries are clear.
32+
- Read tools/templates/first-class-tool-starter/README.md and confirm it directs new tool authors to the contracts before creating a tool.

‎tools/templates/first-class-tool-starter/README.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ Copy this folder to `tools/<tool-id>/`, then rename the class prefixes, visible
1010
tools/<tool-id>/
1111
index.html
1212
README.md
13+
docs/
14+
CONTROL_SERVICE_CONTRACTS.md
1315
styles/
1416
toolStarter.css
1517
js/
@@ -34,15 +36,30 @@ tools/<tool-id>/
3436
- `js/ToolStarterApp.js`: app/root coordinator only.
3537
- `js/controls/*.js`: one class per UI control or section.
3638
- `js/services/*.js`: focused non-UI helper classes when needed.
39+
- `docs/CONTROL_SERVICE_CONTRACTS.md`: required control, service, app/root, logger, and batch processor contracts.
3740
- `README.md`: tool-specific usage, contracts, and validation notes.
3841

42+
## Required Contracts
43+
44+
Read `docs/CONTROL_SERVICE_CONTRACTS.md` before creating or modifying a first-class tool from this starter.
45+
46+
The contracts define:
47+
48+
- Control responsibilities and method expectations.
49+
- Service boundaries and result/error return expectations.
50+
- App/root coordinator boundaries.
51+
- Logger level requirements: OK, WARN, FAIL, SKIP, INFO.
52+
- Batch processor discovery, per-item logging, and summary requirements.
53+
3954
## Architecture Rules
4055

4156
- One class per file.
4257
- One control or section per class.
4358
- App/root class coordinates only and must not own DOM logic or business logic.
4459
- Controls own their DOM and their events.
4560
- Controls communicate through injected callbacks or the app coordinator.
61+
- Services contain non-DOM logic and return results/errors for the app, controls, or logger to display.
62+
- Logger is the single writer for status/log output.
4663
- Reusable UI behavior must live in reusable classes such as `AccordionSection`.
4764
- Do not depend on `tools/shared`.
4865
- Do not use inline event handlers such as `onclick`, `onchange`, or `oninput`.
@@ -83,4 +100,3 @@ Every PR that creates or changes a first-class tool must produce:
83100
- `docs/dev/reports/codex_changed_files.txt`
84101
- a PR-specific report under `docs/dev/reports/`
85102
- a repo-structured delta ZIP under `tmp/`
86-

‎tools/templates/first-class-tool-starter/docs/CONTROL_SERVICE_CONTRACTS.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Tool Control And Service Contracts
2+
3+
These contracts define the required structure for first-class tool code created from this starter.
4+
5+
## Control Contract
6+
7+
Controls own one UI control or one UI section.
8+
9+
Required rules:
10+
11+
- One control or section per class.
12+
- One class per file.
13+
- A control owns its DOM references.
14+
- A control owns its event binding.
15+
- A control must not reach into sibling controls directly.
16+
- A control must not perform unrelated business logic.
17+
- A control exposes clear methods that match its responsibility.
18+
19+
Common methods:
20+
21+
- `init()` or `mount()` prepares the control.
22+
- `bindEvents()` wires DOM events when event wiring is separate from initialization.
23+
- `getValue()` returns the current control value when applicable.
24+
- `setValue(value)` updates the control value when applicable.
25+
- `validate()` returns validation status and messages when applicable.
26+
- `setEnabled(isEnabled)` updates enabled state when applicable.
27+
- `clear()` clears visible state when applicable.
28+
29+
Controls communicate through injected callbacks, injected services, or the app/root coordinator. A control must not directly edit another control's DOM or internal state.
30+
31+
## Service Contract
32+
33+
Services contain non-DOM logic.
34+
35+
Required rules:
36+
37+
- Services must not query or manipulate UI directly.
38+
- Services must not write to status text, textareas, headers, buttons, or panels.
39+
- Services return data, status objects, or errors for controls, the app/root coordinator, or logger to display.
40+
- Services must avoid hidden defaults and silent fallback data.
41+
- Services should be deterministic for the same input unless they explicitly own I/O.
42+
43+
Recommended result shape:
44+
45+
```js
46+
{
47+
ok: true,
48+
value: {},
49+
warnings: []
50+
}
51+
```
52+
53+
Recommended error shape:
54+
55+
```js
56+
{
57+
ok: false,
58+
code: "VALIDATION_FAILED",
59+
message: "Explain the actionable failure.",
60+
details: {}
61+
}
62+
```
63+
64+
## App/Root Contract
65+
66+
The app/root class is a coordinator only.
67+
68+
Required rules:
69+
70+
- The app/root class wires controls and services.
71+
- The app/root class coordinates flows between controls and services.
72+
- The app/root class does not own DOM references except for constructing controls when unavoidable.
73+
- The app/root class does not own business logic.
74+
- The app/root class does not write directly to log/status UI.
75+
- The app/root class does not reach into control internals.
76+
77+
Allowed responsibilities:
78+
79+
- instantiate controls and services
80+
- inject dependencies
81+
- connect callbacks
82+
- coordinate high-level flows such as load, validate, render, export
83+
- route service results to the owning control or logger
84+
85+
## Logger Contract
86+
87+
Each tool has one status/log writer.
88+
89+
Required rules:
90+
91+
- Logger is the single writer for status/log output.
92+
- Controls, services, and app/root code must route log output through the logger.
93+
- Logger owns status/log DOM writes.
94+
- Logger supports these levels:
95+
- `OK`
96+
- `WARN`
97+
- `FAIL`
98+
- `SKIP`
99+
- `INFO`
100+
- Logger entries must be clear and actionable.
101+
- Batch operations must include the item identifier in per-item log lines.
102+
103+
Recommended logger methods:
104+
105+
- `ok(message)`
106+
- `warn(message)`
107+
- `fail(message)`
108+
- `skip(message)`
109+
- `info(message)`
110+
- `clear()`
111+
112+
## Batch Processor Contract
113+
114+
Batch processors handle repeated work across discovered inputs.
115+
116+
Required rules:
117+
118+
- Process real discovered inputs only.
119+
- Never assume numeric sequences.
120+
- Log every item through the logger.
121+
- One item failure must not stop the batch unless the failure is global.
122+
- Missing inputs are `SKIP` during batch processing.
123+
- Batch failures identify the exact item and underlying error.
124+
- Batch summaries include written, failed, skipped, and warnings.
125+
126+
Recommended summary shape:
127+
128+
```js
129+
{
130+
written: 0,
131+
failed: 0,
132+
skipped: 0,
133+
warnings: 0,
134+
items: []
135+
}
136+
```
137+
138+
## Review Checklist
139+
140+
Before a first-class tool PR is ready:
141+
142+
- Every control or section has its own class.
143+
- Every service is DOM-free.
144+
- The app/root class coordinates only.
145+
- All logging goes through the logger.
146+
- Batch work logs per item and summarizes counts.
147+
- No inline event handlers exist in HTML.
148+
- No inline `<script>` or `<style>` blocks exist in HTML.
149+
- No `tools/shared` dependency exists.
150+

0 commit comments

Comments
 (0)