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

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.

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/.

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.

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.

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.

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.

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.

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.

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.

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.