77 lines
6.7 KiB
Markdown
77 lines
6.7 KiB
Markdown
# Schema Command Execution Issue Fixes
|
|
|
|
This document records issues found while packaging, building, and executing commands from `dws schema`, plus the fixes and verification evidence.
|
|
|
|
## 2026-07-09
|
|
|
|
### Verification summary
|
|
|
|
- Built local CLI with `./scripts/dev/build.sh`.
|
|
- Executed all commands discovered from `dws schema --format json` with `--dry-run --yes --format json`: 359 total, 359 passed.
|
|
- Wrote smoke artifacts to `tmp/schema-command-smoke.jsonl` and `tmp/schema-command-smoke.md`.
|
|
- Ran Go tests: `go test ./internal/cli ./internal/compat ./internal/output ./internal/helpers ./test/contract ./test/scripts -count=1`.
|
|
- Ran full packaging: `make package`; generated platform archives, `dist/dws-skills.zip`, npm package staging, and Homebrew formula staging.
|
|
|
|
### Issue 1: `make package` could not resolve package version
|
|
|
|
- Symptom: `make package` built cross-platform archives, then `scripts/release/post-goreleaser.sh` failed with `could not resolve package version - set DWS_PACKAGE_VERSION or create a git tag`.
|
|
- Cause: `scripts/dev/build-all.sh` defaulted `VERSION` to `0.0.0-SNAPSHOT`, but the Makefile did not pass that version into `post-goreleaser.sh` as `DWS_PACKAGE_VERSION`.
|
|
- Fix: Added `VERSION ?= 0.0.0-SNAPSHOT` to `Makefile` and passed it to both build and post-packaging steps.
|
|
- Verification: `make package` completed successfully and staged release artifacts under `dist/`.
|
|
|
|
### Issue 2: packaging tests used fake Darwin archives with signing enabled
|
|
|
|
- Symptom: `go test ./test/scripts -run TestPostGoreleaser` failed when `post-goreleaser.sh` tried to unpack and sign fake archive fixtures.
|
|
- Cause: tests seed placeholder archive files, while post-packaging now performs Darwin ad-hoc signing that requires real tar archives containing a binary.
|
|
- Fix: Added `DWS_SKIP_DARWIN_SIGNING=1` for controlled packaging tests and set explicit `DWS_PACKAGE_VERSION` in those tests.
|
|
- Verification: `go test ./test/scripts -count=1` passed.
|
|
|
|
### Issue 3: helper schema exposed flags that commands do not accept
|
|
|
|
- Symptom: smoke validation found schema parameters missing from command help, including `dev.create_dev_app --app-type` and `dev.publish_dev_app_version --precheck-only`.
|
|
- Cause: helper-only schema was rendered from live MCP parameters without intersecting those parameters with the actual Cobra command flags.
|
|
- Final fix: helper schema now uses command-registered flags plus versioned metadata and never performs a live `tools/list` query.
|
|
- Verification: full schema smoke passed with no `schema_flag_mismatch` results.
|
|
|
|
### Issue 4: dry-run was not consistently honored through inherited/root flags
|
|
|
|
- Symptom: several commands attempted real execution during smoke even though `--dry-run` was present, notably dynamic command and compat pipeline paths.
|
|
- Cause: dynamic command execution only checked local flags in some paths, and compat pipeline dispatch did not short-circuit dry-run before calling the pipeline runner.
|
|
- Fix: Added inherited/root persistent flag lookup for `--dry-run` and made compat pipeline routes emit a dry-run plan instead of executing.
|
|
- Verification: full schema smoke passed, including previously failing `chat message download-media` and `minutes record` paths.
|
|
|
|
### Issue 5: schema omitted real business `--json` flags
|
|
|
|
- Symptom: aitable view update commands accepted `--json`, but schema omitted it for some commands.
|
|
- Cause: runtime schema filtering treated all `json`/`params` names as generic payload plumbing, which also removed hardcoded business flags named `json`.
|
|
- Fix: Restricted generic payload filtering to exact generic usage text so command-specific `--json` flags remain visible.
|
|
- Verification: `dws schema aitable.view_update_filter --format json` includes `json`, and full schema smoke passed.
|
|
|
|
### Issue 6: required-parameter inference was incomplete or too aggressive
|
|
|
|
- Symptom: dry-run execution failed on commands whose schema did not mark the minimum executable parameter set, while some conditional fields were inferred as unconditionally required.
|
|
- Cause: schema generation relied on usage text only, without enough hints for command-specific minimum payloads or exclusions for conditional phrasing.
|
|
- Fix: Added command-specific schema hints for aitable/calendar/dev/group-chat commands and refined required inference to ignore conditional phrases such as optional, mutually exclusive, and at-least-one wording.
|
|
- Verification: targeted rerun of the 20 previously failing paths passed, then full schema smoke passed 359/359.
|
|
|
|
### Issue 7: smoke harness generated empty payloads for non-empty update commands
|
|
|
|
- Symptom: after schema fixes, a few aitable commands still failed smoke because generated values were syntactically valid but semantically empty, such as `--records []` or `--json {}`.
|
|
- Cause: the smoke harness had generic JSON samples and did not know which commands require non-empty objects or arrays.
|
|
- Fix: Generated non-empty record payloads and command-specific non-empty JSON samples for aitable aggregate/card/field-widths/timebar updates.
|
|
- Verification: targeted smoke for the remaining 20 paths passed 20/20, and the rebuilt CLI passed full smoke 359/359.
|
|
|
|
### Issue 8: mail user smoke depended on bound mailbox auto-detection
|
|
|
|
- Symptom: `mail.search_mail_users` failed in dry-run smoke on accounts without an enterprise mailbox, even after `dws auth login`, because the command attempted mailbox auto-detection when `--email` was omitted.
|
|
- Cause: schema correctly marks `email` as optional for normal use, but the smoke harness used required parameters only; this made dry-run depend on the tester account's mailbox binding.
|
|
- Fix: Added a smoke-only extra flag rule so `mail.search_mail_users` supplies a sample `--email` while leaving the runtime schema unchanged.
|
|
- Verification: `dws mail user search --email user@example.com --keyword keyword-smoke --dry-run --yes --format json` passed; full smoke passed 359/359 after this fix.
|
|
|
|
### Issue 9: newly surfaced attendance schema paths needed smoke-safe minimum payloads
|
|
|
|
- Symptom: full smoke later discovered 375 leaf commands and failed on several attendance commands: one-of IDs, enum fields, JSON schedule items, and update commands requiring at least one changed field.
|
|
- Cause: flat schema cannot express every one-of/at-least-one group, and the smoke value generator used generic string samples for attendance enums and empty JSON arrays for schedules.
|
|
- Fix: Added attendance schema hints for minimum executable update fields; generated valid attendance enum/JSON samples; allowed dotted flag names such as `--param.use-history-group-and-shift` in help validation; removed live helper schema fetches.
|
|
- Verification: targeted smoke for the 9 failing paths passed 9/9, `go test ./internal/cli ./test/contract -count=1` passed, and full schema smoke passed 375/375.
|