feat(cli): promote profile commands to top level

[shiju-nv]

Summary

Profiles are currently split between provider list-profiles and provider profile, with no human-readable view of a single definition. This adds openshell profile for discovery and management, including describe, while retaining the existing nested commands through shared handlers.

Related Issue

Closes #2588.

Related implementation: #3068. Both proposals support the legacy commands.

Changes

• Add top-level profile list, describe, export, import, update, lint, and delete, with a validated --type provider filter for listing.
• Retain provider list-profiles and provider profile …, including their arguments, output options, and workspace/global flags. Both entry points use the same execution handlers.
• Show a flat NAME / TYPE / CATEGORY / SOURCE / SCOPE list and follow the gateway's continuation tokens through full or short pages, preserving same-name entries across scopes.
• Use the gateway's import-only profile catalog and shared catalog loader; document explicit imports and interceptor-managed definitions.
• Describe profile metadata, credential names/authentication, declared endpoint ports and policy settings, binaries, source, and scope. JSON/YAML use the existing complete profile serialization; describing a definition does not retrieve provider-instance credentials.
• Show TLS handling and the uninspected-credential opt-in independently, so raw tunnels are distinguishable from inspected endpoints. Read the current gateway’s typed endpoint modes through the shared conversion helpers, preserving unknown numeric values in descriptions. Show MCP method defaults, tool-name validation, and declared versions, including case-insensitive protocol spellings, alongside explicit rule counts.
• Test argument equivalence, old/new CLI output and scope forwarding, pagination, missing-profile errors, and structured description/export equivalence, using imported example-profile fixtures.
• Update published docs, architecture guidance, public skills, examples, and E2E command invocations to use the top-level form.

Compatibility note: legacy names and flags remain supported, but both list spellings now use the flat human-readable table. The JSON/YAML profile schema is unchanged. Existing import/lint file and directory flags and the update ID/file arguments remain unchanged. No gateway or protobuf API changes are included.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)

Current-main verification: 10 profile library tests and 8 CLI parser tests passed. All 76 tests in the compiled provider integration target passed, including pagination, scope forwarding, structured description/export equivalence, provider readiness, credential refresh, and safe error handling. Pagination coverage includes full terminal pages and multiple short nonterminal pages. Live sandbox E2E was not run for this CLI change.

Tests and the full pre-commit gate passed on main e38d7254e. The final rebase to 903d9a0e7 preserves the exact PR patch; the only intervening Rust change is a copyright comment. License, Python, Helm, Markdown, script syntax, and Rust formatting checks were repeated on the final tree.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[natedemoss]

thanks for the pr, #3068 has been closed as stale fyi

[johntmyers]

gator-agent

Blocked

Gator is blocked because GitHub reports that this branch has merge conflicts with main.

Next action: @shiju-nv, please update the branch from main, resolve the conflicts, and push the resolved head so code review can begin.

Gator metadata

• Head SHA: b9b64f1b916b86c0647bdb265433a2c22e904784
• Gator payload: 9
• Next state: gator:blocked
• Blocked reason: merge_conflict