docs(design-proposals): propose unified CLI interfaces

[myasnikovdaniil]

What this PR does

Proposes two primary modular command-line interfaces for Cozystack: cozystackctl for platform operators and cozyctl for tenants and managed-service users.

The proposal defines their responsibility boundaries, command organization, shared client/discovery/output foundation, schema-driven application discovery, executable extension model, security constraints, compatibility strategy, testing, and phased rollout. Existing cozypkg and check-readiness binaries remain compatibility entry points backed by the shared implementation during migration.

Key decisions

• Keep operator and tenant workflows in separate binaries while sharing internal modules.
• Discover generic managed-application workflows through Kubernetes API discovery, ApplicationDefinition, and OpenAPI.
• Keep the root user command tree stable instead of generating arbitrary top-level commands from the cluster catalog.
• Require explicit installation for executable plugins; package repositories and cluster metadata never trigger workstation code execution.
• Preserve existing tools for a documented compatibility period.

Testing

• git diff --check
• Verified all required design-proposal template sections are present.
• Verified the commit has a valid GPG signature and DCO signoff.

Downstream repositories

No downstream follow-up is required because this PR records a design proposal and changes no product API or implementation.

NONE

Summary by CodeRabbit

• Documentation
  • Added a proposal for unified Cozystack command-line interfaces for operators and tenants.
  • Documented command structures, application discovery, resource management, configuration, output, compatibility, plugins, security boundaries, and failure handling.
  • Included testing, rollout guidance, open questions, and considered alternatives.
  • Documented continued compatibility for existing command-line entry points.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 565853e9-31af-4d43-a10d-729832d947bc

📥 Commits

Reviewing files that changed from the base of the PR and between c484063 and 303cc00.

📒 Files selected for processing (1)

• design-proposals/cozystack-cli-interfaces/README.md

---

📝 Walkthrough

Walkthrough

The proposal defines cozystackctl for operators and cozyctl for tenants. It specifies shared Kubernetes infrastructure, dynamic application discovery, tenant workflows, plugin behavior, compatibility contracts, security boundaries, testing, rollout, and open questions.

Changes

Unified CLI design

Layer / File(s)	Summary
CLI architecture and contracts design-proposals/cozystack-cli-interfaces/README.md	Defines operator and tenant command trees, shared client and discovery modules, generic application workflows, capability extensions, configuration and output contracts, plugin execution rules, compatibility behavior, security constraints, failure handling, testing, rollout phases, and alternatives.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the proposed unified Cozystack CLI interfaces.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch proposal/cozystack-cli-interfaces

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}