Files
pipelines/app/notes/S1-draft.md
T

141 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# S1-draft — pure saved-schedule editor draft and validation
Manager integration guard: invalid pipeline IDs and edited records without a
positive exact server identity/revision cannot build save payloads. This prevents
a malformed/historical edit from becoming a create or bypassing CAS. Three new
regressions failed against the original draft and pass after the fail-closed
guard. The original snapshot remains unchanged; no production save was tested.
## What changed
New files only; no existing feature, shell, transport, `main` or pubspec source
edited:
| File | Lines | Responsibility |
| --- | --- | --- |
| `lib/features/schedules/domain/editor/schedule_draft.dart` | 210 | mutable editor draft over `SavedSchedule`/`ScheduleRule`, web-mirrored validation, `save_schedule` record assembly |
| `test/features/schedules/domain/editor/draft_fixtures.dart` | 42 | shared server-record fixture and deep-copy helper |
| `test/features/schedules/domain/editor/schedule_draft_test.dart` | 134 | create/edit record assembly, CAS, unknown fields, workspace, source immutability |
| `test/features/schedules/domain/editor/schedule_draft_validation_test.dart` | 130 | timer/day/timezone/core field validation and invalid-field behavior |
The production file is one cohesive file (below the 220-line slice budget) and
keeps the existing domain pattern: `SavedSchedule` and `ScheduleRule` are
read-only views, `ScheduleDraft` is the separate editable state. Tests are split
by responsibility (record assembly vs. validation) so neither file exceeds the
working agreement's ~250-line aim.
## Review fix — workspace is now written into the record
Review visit 1 found that `build()` validated `workspace` but never wrote it, so
creates were refused by `save_schedule` and workspace edits were dropped. The
fix writes `record['workspace'] = workspace;` beside `name`/`version`/`enabled`,
untrimmed to match `workspace: draft.workspace` in `web/src/schedules.js`
(validation also runs on the untrimmed value). Direct probe against the real
classes:
```
create keys: enabled, id, input, name, notify_mode, pipeline_id, rule, version, workspace
create: {"id":0,...,"workspace":"/srv","rule":{"every":"24h","timezone":"UTC"},"notify_mode":"auto"}
edit workspace: /new (source /old)
edit revision: 13
```
New assertions cover the create record, an unchanged edit, a changed edit and
the untrimmed value.
## Behavior copied from `web/src/schedules.js`
`ScheduleDraft.build()` returns `ScheduleSaveResult(null, errors)` while any
field is invalid, so an invalid draft cannot yield a save payload. Errors are a
field-name → message map using the web editor's exact words:
- name `Enter a schedule name.` (stored trimmed, as the web record is)
- prompt `Enter a prompt.` (stored untrimmed)
- pinned version: digits only, safe integer, at least 1 — `Choose a positive
pinned version, not latest (0).`
- workspace must start with `/` and contain no NUL/CR/LF — `Enter an absolute
workspace path on the server.`
- interval is Go-style compound duration (`24h`, `1h30m`, `.5h`, `1.5m`) whose
matched text covers the whole value and totals at least one minute —
`Interval must be at least 1m (for example 24h or 1h30m).`
- clock times are comma-separated, trimmed, distinct `HH:mm` in 00:00–23:59 —
`Enter distinct 24-hour times, such as 09:00, 17:30.`
- weekday keys must be distinct values from `scheduleDays` —
`Choose valid, distinct weekdays.`
- notification mode is `auto`, `on` or `off` — `Choose a notification mode.`
- timezone is blank, `Local`, a known single-zone alias or a well-formed
`Area/Location` — `Enter a valid IANA timezone.`
Rule assembly mirrors the web editor: the prior rule is copied, `every`,
`times`, `days` and `timezone` are removed, then only the selected timer shape
is written. Empty weekdays mean every day (the key stays absent). A weekday set
that is unchanged keeps the server's original order (the web editor does this
so editing only a prompt does not reorder days). A blank timezone is omitted.
## Losslessness and CAS
- Edits start from `SavedSchedule.toJson()` (a deep copy): unknown top-level,
`input`, `rule` and run-option fields (`model`, `stage_models`, `write_paths`,
`allow_tools`, `title`, `output_format`, `next_due`, timestamps, future
fields) survive untouched.
- `input` keeps every unknown key and replaces only `prompt`.
- **Every build starts from a fresh copy**, so the source snapshot and the
draft are not mutated or aliased by a returned payload.
- The edit record keeps the exact server `revision`; it is never incremented,
invented or defaulted. An edit never rewrites `id`.
- A create has no source: it emits the web sentinel `id: 0`, no `revision`, no
unknown/run-option leftovers, `pipeline_id` from the caller, `enabled`,
`input: {prompt}`, `rule`, and `notify_mode`.
- `notify_mode` and `enabled` default the same way as the web draft when absent
from a malformed older record, but an existing non-default string/boolean is
preserved and validated rather than silently replaced.
## Checks actually run
```
flutter pub get
dart format lib/features/schedules/domain/editor test/features/schedules/domain/editor
flutter analyze # No issues found! (1.1s)
flutter test test/features/schedules/domain/editor # 9 passed
flutter test test/features/schedules # 56 passed
```
Focused coverage maps to the requested acceptance:
- create: sentinel `id: 0`, no revision, pipeline/version/prompt/workspace/rule;
- lossless edit: id 9/revision 13, unknown record/input/rule/run options,
workspace from the source, original map and `SavedSchedule` snapshot
unchanged, returned payload not aliased;
- changed workspace is written untrimmed, matching the web serializer;
- prompt-only edit keeps the server weekday order and clock rule;
- clock ↔ interval switching removes the other timer key and keeps unknown
rule fields;
- invalid timers (`59s`, `NaN`, `-1h`, `1.1x`, `Infinityh`, mixed text) and
valid parity cases (`.5h`, `1h30m`, `24h`);
- invalid clock times, duplicate weekdays, bad notification mode, invalid
timezones, bad name/prompt/version/workspace;
- invalid draft mutates nothing and has no record.
## Honest limits
- **Scope is the core editor slice.** Name, prompt, pinned version, workspace,
timer mode/every/times, weekdays, timezone, enabled and notification mode are
editable. Advanced JSON run options (`otherInput`, `stage models`, write
paths, model, title, output format) and tools are **preserved exactly but not
editable in this slice**; no control or parser for them was invented here.
- **Timezone is structural.** Dart ships no IANA database, so the check accepts
blank/`Local`, known single-zone aliases and a known area plus a well-formed
location (e.g. `Europe/London`, `Etc/GMT+5`). It rejects clearly malformed
values such as `Nowhere/Invalid` and `Europe/`, but cannot prove that every
location in an accepted area exists. The server remains the final validator.
This is documented at the function.
- **No UI, network, CRUD, run dispatch, polling or scheduling engine.** The
draft only assembles a record; the existing repository owns `save_schedule`,
and no server was contacted.
- **No browser capture applies.** This is a nonvisual pure domain item; there
is no rendered change, so no fixture or screenshot was produced.
- **Mobile unverified.** Only web-targeted Flutter tests and analysis ran. No
Android/iOS build, emulator, ADB or device was used; the code is pure Dart.
- **Not committed.** This stage forbids commit, push and deploy, so the
candidate remains in the `flutter/schedule-draft` worktree for the manager.