logseq/docs/agent-guide/082-logseq-cli-upsert-task-option-cleanup.md

# Logseq CLI `upsert task` Option Surface Cleanup Plan

Goal: simplify `upsert task` into a task-focused command by removing generic tag/property mutation options, adding first-class `--deadline` / `--scheduled` options, and standardizing explicit clear semantics with `--no-status`, `--no-priority`, `--no-scheduled`, and `--no-deadline`.

Architecture: keep the current `logseq-cli -> parse/build -> execute -> transport/invoke -> db-worker-node` flow, and **do not add new thread-api unless strictly necessary**.

Architecture: this change should be implemented entirely in existing CLI command/build/execute logic (`upsert task`) and existing mutation endpoint (`:thread-api/apply-outliner-ops`), with no new db-worker-node API contract.

Tech Stack: ClojureScript, `babashka.cli`, existing command modules under `src/main/logseq/cli/command/*`, existing CLI docs/e2e specs.

Related:
- `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/078-logseq-cli-task-subcommands.md`
- `/Users/rcmerci/gh-repos/logseq/docs/agent-guide/080-logseq-cli-status-option-cleanup.md`
- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`

## Problem statement

Current `upsert task` still exposes generic mutation options:

- `--update-tags`
- `--update-properties`
- `--remove-tags`
- `--remove-properties`

This overlaps with `upsert block`, which already serves as the general-purpose surface for tag/property updates/removals.

At the same time, task-specific scheduling fields are missing as first-class options:

- `--scheduled`
- `--deadline`

The command should become more cohesive:

- task semantics stay in `upsert task` (status, priority, scheduled, deadline, and automatic `#Task` attachment)
- generic tag/property mutations are done via `upsert block`
- set/clear semantics are explicit and paired:
  - set via `--status` / `--priority` / `--scheduled` / `--deadline`
  - clear via `--no-status` / `--no-priority` / `--no-scheduled` / `--no-deadline`

## Current baseline from implementation

### 1) `upsert task` currently includes generic tag/property options

`src/main/logseq/cli/command/upsert.cljs` currently defines these options in `upsert-task-spec`:

- `:update-tags`
- `:update-properties`
- `:remove-tags`
- `:remove-properties`

### 2) `upsert task` execute path currently applies generic tag/property ops

`execute-upsert-task-ops!` currently:

- resolves update/remove tags and properties
- merges task overrides (`status`, `priority`) into update properties
- supports remove operations and guards against removing `#Task`

### 3) Runtime status validation already uses existing `:thread-api/q`

Status validation now relies on:

- `src/main/logseq/cli/command/task_status.cljs`
- query via existing `:thread-api/q`

This should remain unchanged (no new thread-api needed).

### 4) Task list/output already models `scheduled` and `deadline`

Current list/format paths already include:

- `:logseq.property/scheduled`
- `:logseq.property/deadline`

So adding write options in `upsert task` aligns with existing read/output behavior.

## Scope

In scope:

1. Remove from `upsert task` option surface:
   - `--update-tags`
   - `--update-properties`
   - `--remove-tags`
   - `--remove-properties`
2. Add to `upsert task` option surface:
   - `--scheduled`
   - `--deadline`
   - `--no-status`
   - `--no-priority`
   - `--no-scheduled`
   - `--no-deadline`
3. Keep `status` runtime validation behavior as-is for `--status <value>` inputs (graph-derived values via existing `:thread-api/q`).
4. Add explicit clear semantics: `--no-status`, `--no-priority`, `--no-scheduled`, and `--no-deadline` clear corresponding properties.
5. Define and enforce conflict behavior: passing both set and clear for the same field (for example `--status X` + `--no-status`) is invalid and must return a clear validation error.
6. Add migration guidance so removed task options point users to `upsert block`.
7. Update tests/docs/e2e inventory to match the new option contract.

Out of scope:

- Any new thread-api endpoint.
- Any schema/property/class additions.
- Reworking `upsert block` behavior.
- Introducing new date parser/normalizer infrastructure outside `upsert task` needs.

## Design decisions

### Decision A: `upsert task` becomes task-focused only

Keep task-centric options:

- selectors/targets: `--id`, `--uuid`, `--page`, `--content`, `--target-id`, `--target-uuid`, `--target-page`, `--pos`
- task fields: `--status`, `--priority`, `--scheduled`, `--deadline`

Remove generic options (`update/remove tags/properties`) from `upsert task`.

### Decision B: Generic tag/property modifications are delegated to `upsert block`

When users need:

- `--update-tags`
- `--update-properties`
- `--remove-tags`
- `--remove-properties`

they should use `upsert block` on the target block/page id/uuid.

### Decision C: Keep status runtime validation architecture, with explicit `--no-status` clear bypass

`status` should continue using the existing runtime path for `--status <value>`:

- query available status values from current graph via `:thread-api/q`
- resolve/validate in `task_status.cljs`

For `--no-status`, skip value resolution and clear `:logseq.property/status` directly.

No additional thread-api is required.

### Decision D: Paired set/clear options for task fields (`--field` and `--no-field`)

`upsert task` will support direct set semantics:

- `--status <value>` -> `:logseq.property/status` (resolved against graph statuses at runtime)
- `--priority <value>` -> `:logseq.property/priority`
- `--scheduled <value>` -> `:logseq.property/scheduled`
- `--deadline <value>` -> `:logseq.property/deadline`

And explicit clear semantics:

- `--no-status` clears `:logseq.property/status`
- `--no-priority` clears `:logseq.property/priority`
- `--no-scheduled` clears `:logseq.property/scheduled`
- `--no-deadline` clears `:logseq.property/deadline`

Conflict rule: passing both set and clear for the same field in one command (for example `--status TODO` with `--no-status`) is invalid and must fail with a clear validation error.

Implementation note: treat `--no-*` flags as explicit clear intent, and keep using existing mutation ops (`:batch-set-property` for set, `:batch-remove-property` for clear) without adding a new thread-api or a new global datetime validation subsystem.

## Proposed implementation plan (TDD-first)

1. Add RED parser tests asserting `upsert task` rejects removed options (`--update-tags`, `--update-properties`, `--remove-tags`, `--remove-properties`) with `:invalid-options`.
2. Add RED parser/build tests asserting `upsert task` accepts `--scheduled` and `--deadline` in create/page/update modes.
3. Add RED parser/build tests for clear semantics: `--no-status`, `--no-priority`, `--no-scheduled`, and `--no-deadline` are accepted and encoded as clear-intent (not invalid-option).
4. Add RED parser/build tests for conflict behavior: set and clear for the same field in one command is invalid (`--status TODO` + `--no-status`, `--priority A` + `--no-priority`, etc.).
5. Add RED execute tests asserting `upsert task`:
   - writes `status`/`priority`/`scheduled`/`deadline` via batch property set ops,
   - clears status/priority/scheduled/deadline via batch property remove ops when corresponding `--no-*` flag is present,
   - still ensures `#Task` tag attachment.
6. Update `upsert-task-spec` in `src/main/logseq/cli/command/upsert.cljs`:
   - remove generic tag/property options
   - add `:scheduled`, `:deadline`, `:no-status`, `:no-priority`, `:no-scheduled`, and `:no-deadline` options
   - refresh examples to include paired set/clear usage.
7. Refactor `build-task-action` in `upsert.cljs`:
   - remove parsing/build wiring for removed generic options
   - parse `--no-*` flags into clear intent for task properties
   - validate set/no conflicts per field
   - include scheduled/deadline in task property overrides map
   - keep existing selector/target conflict validation.
8. Refactor `execute-upsert-task-ops!` in `upsert.cljs`:
   - remove user-driven update/remove tag/property resolution paths tied to removed options
   - keep automatic `#Task` tag set
   - apply only task property writes (`status`, `priority`, `scheduled`, `deadline`)
   - add task property clear ops for `status`/`priority`/`scheduled`/`deadline` when clear intent is present.
9. Update migration guidance in `src/main/logseq/cli/commands.cljs` so unknown upsert-task legacy options map to actionable messages (e.g. use `upsert block --update-properties`).
10. Update completion/spec tests (`completion_generator_test.cljs`) to verify the new `upsert task` option surface.
11. Update command behavior tests (`commands_test.cljs`, `upsert_test.cljs`) to remove old task-option assumptions and add paired set/clear assertions (including conflicts).
12. Update CLI docs (`docs/cli/logseq-cli.md`) to reflect the new `upsert task` contract, explicit `--no-*` clear semantics, conflict behavior, and migration to `upsert block` for generic tag/property mutation.
13. Update CLI e2e inventory/cases (`cli-e2e/spec/non_sync_inventory.edn`, `cli-e2e/spec/non_sync_cases.edn`) to remove deprecated task options and add cases covering `--scheduled` / `--deadline`, the full `--no-*` clear surface, and set/no conflict failures.
14. Run focused tests and then broader checks.

## Files expected to change

Core implementation:

- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs`
- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs`

Tests:

- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs`
- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/upsert_test.cljs`
- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs`

Docs/e2e:

- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`
- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn`
- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn`

Expected non-changes (unless implementation reveals an actual blocker):

- `/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs`
- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs`

## Testing plan

Follow `@test-driven-development` for this feature.

Focused verification commands:

- `bb dev:test -v logseq.cli.commands-test`
- `bb dev:test -v logseq.cli.command.upsert-test`
- `bb dev:test -v logseq.cli.completion-generator-test`
- `bb -f cli-e2e/bb.edn test --skip-build` (if e2e specs changed)
- `bb dev:lint-and-test`

## Risks and mitigations

Risk: existing scripts using removed `upsert task` generic options break.

Mitigation:

- add migration guidance in parse errors
- update docs with explicit `upsert block` replacements
- include e2e coverage for migration-safe paths

Risk: ambiguity of accepted datetime string format for `--scheduled`/`--deadline`.

Mitigation:

- document expected input examples clearly
- keep first implementation pass-through and avoid overfitting parser logic
- add follow-up validation enhancement only if real failures appear

Risk: users may pass both set and clear options for the same field (for example `--status TODO` and `--no-status`) and expect deterministic precedence.

Mitigation:

- define set/no-same-field combinations as explicit validation errors
- add parser/build/execute tests locking conflict detection across all four fields
- include explicit conflict examples in help/docs

Risk: refactor accidentally drops guaranteed `#Task` tag attachment.

Mitigation:

- execute-level tests must assert task tag set op remains present for create/page/update modes

## Acceptance criteria

1. `upsert task` no longer exposes `--update-tags`, `--update-properties`, `--remove-tags`, `--remove-properties`.
2. `upsert task` supports set semantics via `--status`, `--priority`, `--scheduled`, and `--deadline`.
3. `upsert task` supports explicit clear semantics via `--no-status`, `--no-priority`, `--no-scheduled`, and `--no-deadline`.
4. Passing both set and clear options for the same field in one command is rejected with a clear validation error.
5. `upsert task` continues to support status runtime validation using existing `:thread-api/q` flow for `--status <value>` inputs.
6. Generic tag/property modifications for task nodes are clearly migrated to `upsert block` (guidance + docs).
7. No new thread-api is introduced unless a hard blocker is discovered.
8. Unit tests and CLI e2e specs are updated and passing for changed behavior.

## Open question

No blocking question.

---