Consolidate workspace tooling: state check + delete-by-id, and document the family

[jirkasemmler]

Replaces #92, #98 and #100, which are closed in favour of this branch.

Adds two commands and documents the whole workspace-deletion family. No existing command is modified.

New commands

manage:check-project-workspaces-state (read-only)

Triage step for a known list of workspaces: reports whether each is still live and whether its configuration is live, trashed or gone, and suggests the follow-up command.

• Configuration state is resolved per branch. Branches hold independent copies of a configuration under the same id, so merging their states misclassifies a config that is live in one branch and trashed in another.
• Reports each configuration's most recent job from the Queue API, which is usually what actually decides whether it is still in use. Runs a sanity query for any job in the project first, so blank lastJob* columns are not misread as "never used".

manage:delete-project-workspaces-by-id

List-driven deletion with layered guards — the intended default for "I have a concrete list of workspaces to remove":

• password-login only unless --any-login-type
• optional expectedSchema verification per row
• configuration deletion only behind --with-configuration, and only when that configuration owns exactly the workspace you listed
• deletes the workspace without touching the configuration by default
• a purge refused with storage.components.cannotDeleteConfiguration is counted as failed, not deleted — in that case the configuration is still in the trash and its workspace and backend user still exist

Documentation

The Workspaces and sandboxes section had drifted from the code and gave no guidance on choosing between commands that all look interchangeable from their names but destroy different things.

• New preamble explaining what each command actually destroys: deleting a workspace removes the workspace record + backend user; deleting a configuration (trash + purge) cascades to its workspaces. Safe for keboola.sandboxes, where the configuration is the sandbox; destructive for transformation components, where it is the user's code.
• "Which command should I use?" table + rules of thumb. The *-orphaned-* and *-ownerless-* pairs are each the same selection logic at project vs. organization scope, and "orphaned" detects nothing — it selects purely by component + age.
• Documents manage:delete-organization-ownerless-workspaces, which existed in code but was missing from the README entirely.
• Removes the storage:delete-project-sandboxes section — that command was deleted in a30168d when sandboxes-api was replaced by editor-service sessions, but its docs stayed behind.
• Fixes signatures that had drifted:
  • storage:delete-orphaned-workspaces — hostname-suffix comes before until-date; matches a single component, not a list; --ignore-backend-errors / --manage-token were undocumented.
  • manage:delete-organization-workspaces — component / cutoff / host suffix are options, not positional arguments; organizationId takes a comma-separated list.
  • manage:describe-organization-workspaces — documented CSV header was missing the activeUser column.
  • manage:mass-delete-project-workspaces — it resolves schemas through editor sessions and purges the parent configuration; it does not queue delete jobs and wait for them. Workspaces without an editor session cannot be found, so its "not found" list is the meaningful output.

Verification

phpcs, phpstan (level 9), phpunit and a CLI boot check all pass. Verified that all 31 registered commands (setName() + #[AsCommand]) are documented and that the README references no command that does not exist.

Not run against any real stack, organization or project — not even in dry-run.

---

Additional notes

Deliberately not included, so this stays reviewable: merging the project/organization command pairs, retiring manage:mass-delete-project-workspaces, and a --drop-from-metadata mode that would let the by-id command reach storage:workspace:drop-failed-workspaces-from-metadata with an explicit list. That last one is the one genuinely missing capability — today the backend-user purge path is only reachable through the component+age heuristic in storage:delete-orphaned-workspaces --ignore-backend-errors.

manage:list-external-buckets was split out into #108 — it is unrelated to workspace tooling.

⚠️ Don't forget to release new version after merge

[martinsifra]

Pryč s tím

[jirkasemmler]

Souhlas, pryč. Odebráno z tohoto PR a přesunuto do #108 jako samostatná změna — s workspace toolingem, který tady konsoliduju, nesouvisí.