feat: add workspace management endpoints to OpenAPI spec

[feloy]

Add /init, /init/verbose, and /remove endpoints to support programmatic workspace management from UIs. Include comprehensive scenario documentation in README demonstrating the complete workflow with JSON output examples and error handling.

Related to openkaiden/kortex-cli#54

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3e53b457-17d0-4f6b-9141-2d30fbf9257b

📥 Commits

Reviewing files that changed from the base of the PR and between 4851824 and 9be0fb3.

📒 Files selected for processing (2)

• cli/README.md
• cli/openapi.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• cli/openapi.yaml

---

📝 Walkthrough

Walkthrough

Adds documentation examples and OpenAPI definitions for three workspace management endpoints (/init, /init/verbose, /remove) and introduces two response schemas: Error and WorkspaceId.

Changes

Cohort / File(s)	Summary
Documentation cli/README.md	Added "Scenarios" section with multiple JSON output examples for listing, initializing (minimal and verbose), post-init listing, removing, and error cases.
API Specification cli/openapi.yaml	Added GET endpoints /init, /init/verbose, /remove with 200/400 responses and introduced Error and WorkspaceId component schemas; /init/verbose returns a Workspace object reference.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat: list content #9 — Adds Workspace/WorkspacesList/WorkspacePaths schema definitions that overlap with the new /init/verbose response schema references.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding workspace management endpoints to the OpenAPI specification.
Description check	✅ Passed	The description is directly related to the changeset, providing relevant details about the endpoints being added and the documentation included.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

cli/openapi.yaml (1)

6-25: Missing parameters for the /init endpoint.

The /init endpoint doesn't specify any parameters, but the error example references a source directory path (/tmp/not-found), and the README shows kortex-cli init -o json /tmp/not-found. Consider adding a query parameter to document the optional source path argument.

📝 Proposed addition for the source path parameter

   /init:
     get:
       summary: Initialize a new workspace
+      parameters:
+        - name: source
+          in: query
+          description: Path to the source directory (optional)
+          required: false
+          schema:
+            type: string
       responses:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@cli/openapi.yaml` around lines 6 - 25, The /init GET operation is missing a
parameter for the optional source path shown in examples; add an optional query
parameter (e.g., name: source or path, in: query, schema: type: string) to the
/init get operation so the OpenAPI docs document the CLI argument (refer to the
/init get operation and the Error response example that mentions the source
directory); ensure the parameter is marked required: false and include a brief
description like "optional source directory path".

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@cli/openapi.yaml`:
- Around line 72-91: The /remove GET operation is missing a workspace identifier
parameter; update the OpenAPI path (e.g., change /remove to /remove/{id}) and
add a required path parameter named id (type: string, description: "Workspace
id") for the get operation that references the existing WorkspaceId schema in
responses and adjust the example values accordingly; ensure the parameter is
marked required and included in the operation's parameters block so the CLI's
`workspace remove <id>` behavior is documented.

In `@cli/README.md`:
- Around line 98-105: Update the example under the "Workspace not found" section
so the error message matches the command argument by replacing the hard-coded
"Error: workspace not found: aze" string with "Error: workspace not found:
unknown-id" (look for the example containing the command "kortex-cli workspace
remove unknown-id -o json" and the error JSON). Also make the same change in the
OpenAPI doc entry that currently contains the "Error: workspace not found: aze"
example (search for that exact error string in the openapi.yaml and replace it
with the matching "unknown-id").

---

Nitpick comments:
In `@cli/openapi.yaml`:
- Around line 6-25: The /init GET operation is missing a parameter for the
optional source path shown in examples; add an optional query parameter (e.g.,
name: source or path, in: query, schema: type: string) to the /init get
operation so the OpenAPI docs document the CLI argument (refer to the /init get
operation and the Error response example that mentions the source directory);
ensure the parameter is marked required: false and include a brief description
like "optional source directory path".

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b14073b3-ad72-4e78-9145-5f5bf365513c

📥 Commits

Reviewing files that changed from the base of the PR and between 10653d0 and 4851824.

📒 Files selected for processing (2)

• cli/README.md
• cli/openapi.yaml

[MarsKubeX]

LGTM