up
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
This commit is contained in:
master
249
docs/modules/cli/guides/commands/sdk.md
Normal file
249
docs/modules/cli/guides/commands/sdk.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# stella sdk — Command Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The `stella sdk` command group provides SDK management capabilities including update checking, changelog viewing, and deprecation notices.
|
||||
|
||||
## Commands
|
||||
|
||||
### Check for SDK Updates (CLI-SDK-64-001)
|
||||
|
||||
```bash
|
||||
# Check for SDK updates
|
||||
stella sdk update \
|
||||
[--tenant <id>] \
|
||||
[--language <lang>] \
|
||||
[--check-only] \
|
||||
[--changelog] \
|
||||
[--deprecations] \
|
||||
[--json]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--tenant` / `-t` | Tenant context for the operation |
|
||||
| `--language` / `-l` | SDK language filter (typescript, go, csharp, python, java). Omit for all |
|
||||
| `--check-only` | Only check for updates, don't download |
|
||||
| `--changelog` | Show changelog for available updates |
|
||||
| `--deprecations` | Show deprecation notices |
|
||||
| `--json` | Output in JSON format |
|
||||
|
||||
**Output:**
|
||||
- Available SDK updates with version comparison
|
||||
- Changelog entries for each update (when `--changelog` is used)
|
||||
- Deprecation notices with migration guidance (when `--deprecations` is used)
|
||||
|
||||
### List Installed SDKs (CLI-SDK-64-001)
|
||||
|
||||
```bash
|
||||
# List installed SDK versions
|
||||
stella sdk list \
|
||||
[--tenant <id>] \
|
||||
[--language <lang>] \
|
||||
[--json]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--tenant` / `-t` | Tenant context for the operation |
|
||||
| `--language` / `-l` | SDK language filter |
|
||||
| `--json` | Output in JSON format |
|
||||
|
||||
**Output:**
|
||||
- Language/platform
|
||||
- Package name
|
||||
- Installed version
|
||||
- Latest available version
|
||||
- API version compatibility range
|
||||
- Update status
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success |
|
||||
| 1 | Error |
|
||||
| 130 | Operation cancelled by user |
|
||||
|
||||
## JSON Schema: SdkUpdateResponse
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"success": { "type": "boolean" },
|
||||
"updates": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"language": { "type": "string" },
|
||||
"displayName": { "type": "string" },
|
||||
"packageName": { "type": "string" },
|
||||
"installedVersion": { "type": "string" },
|
||||
"latestVersion": { "type": "string" },
|
||||
"updateAvailable": { "type": "boolean" },
|
||||
"minApiVersion": { "type": "string" },
|
||||
"maxApiVersion": { "type": "string" },
|
||||
"releaseDate": { "type": "string", "format": "date-time" },
|
||||
"changelog": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"version": { "type": "string" },
|
||||
"releaseDate": { "type": "string", "format": "date-time" },
|
||||
"type": { "type": "string" },
|
||||
"description": { "type": "string" },
|
||||
"isBreaking": { "type": "boolean" },
|
||||
"link": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"downloadUrl": { "type": "string" },
|
||||
"registryUrl": { "type": "string" },
|
||||
"docsUrl": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"deprecations": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"language": { "type": "string" },
|
||||
"feature": { "type": "string" },
|
||||
"message": { "type": "string" },
|
||||
"deprecatedInVersion": { "type": "string" },
|
||||
"removedInVersion": { "type": "string" },
|
||||
"replacement": { "type": "string" },
|
||||
"migrationGuide": { "type": "string" },
|
||||
"severity": { "type": "string", "enum": ["info", "warning", "critical"] }
|
||||
}
|
||||
}
|
||||
},
|
||||
"checkedAt": { "type": "string", "format": "date-time" },
|
||||
"error": { "type": "string" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Check for all SDK updates
|
||||
|
||||
```bash
|
||||
# Check all SDKs
|
||||
stella sdk update
|
||||
|
||||
# Check with changelog
|
||||
stella sdk update --changelog
|
||||
|
||||
# Check with deprecation notices
|
||||
stella sdk update --deprecations
|
||||
|
||||
# Full check with all details
|
||||
stella sdk update --changelog --deprecations
|
||||
```
|
||||
|
||||
### Check specific language SDK
|
||||
|
||||
```bash
|
||||
# Check TypeScript SDK only
|
||||
stella sdk update --language typescript
|
||||
|
||||
# Check Go SDK with changelog
|
||||
stella sdk update --language go --changelog
|
||||
```
|
||||
|
||||
### List installed SDKs
|
||||
|
||||
```bash
|
||||
# List all installed SDKs
|
||||
stella sdk list
|
||||
|
||||
# List specific language
|
||||
stella sdk list --language python
|
||||
|
||||
# Output as JSON for CI
|
||||
stella sdk list --json
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Check for SDK updates in CI and fail on breaking changes
|
||||
|
||||
stella sdk update --changelog --json > sdk-updates.json
|
||||
|
||||
# Check for breaking changes
|
||||
BREAKING=$(jq '[.updates[].changelog[]? | select(.isBreaking == true)] | length' sdk-updates.json)
|
||||
if [ "$BREAKING" -gt 0 ]; then
|
||||
echo "WARNING: $BREAKING breaking changes detected in available SDK updates"
|
||||
jq '.updates[].changelog[] | select(.isBreaking == true)' sdk-updates.json
|
||||
fi
|
||||
|
||||
# Check for critical deprecations
|
||||
CRITICAL=$(jq '[.deprecations[] | select(.severity == "critical")] | length' sdk-updates.json)
|
||||
if [ "$CRITICAL" -gt 0 ]; then
|
||||
echo "ERROR: $CRITICAL critical deprecations require immediate attention"
|
||||
jq '.deprecations[] | select(.severity == "critical")' sdk-updates.json
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Automated notification script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Send Slack notification when SDK updates are available
|
||||
|
||||
UPDATES=$(stella sdk update --json)
|
||||
UPDATE_COUNT=$(echo "$UPDATES" | jq '[.updates[] | select(.updateAvailable == true)] | length')
|
||||
|
||||
if [ "$UPDATE_COUNT" -gt 0 ]; then
|
||||
curl -X POST -H 'Content-type: application/json' \
|
||||
--data "{\"text\": \"StellaOps SDK Updates Available: $UPDATE_COUNT updates\"}" \
|
||||
"$SLACK_WEBHOOK_URL"
|
||||
fi
|
||||
```
|
||||
|
||||
## Supported SDKs
|
||||
|
||||
| Language | Package Name | Registry |
|
||||
|----------|-------------|----------|
|
||||
| TypeScript | `@stellaops/sdk` | npm |
|
||||
| Go | `github.com/stellaops/sdk-go` | Go modules |
|
||||
| C# | `StellaOps.Sdk` | NuGet |
|
||||
| Python | `stellaops-sdk` | PyPI |
|
||||
| Java | `com.stellaops:sdk` | Maven Central |
|
||||
|
||||
## Changelog Entry Types
|
||||
|
||||
| Type | Icon | Description |
|
||||
|------|------|-------------|
|
||||
| `feature` | + | New feature or capability |
|
||||
| `fix` | ~ | Bug fix |
|
||||
| `breaking` | ! | Breaking change (major version) |
|
||||
| `deprecation` | ? | Deprecation notice |
|
||||
|
||||
## Deprecation Severity Levels
|
||||
|
||||
| Severity | Description |
|
||||
|----------|-------------|
|
||||
| `info` | Informational notice, no immediate action required |
|
||||
| `warning` | Feature will be removed in future version, plan migration |
|
||||
| `critical` | Feature removed or will be removed imminently, immediate action required |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Check for updates regularly** in CI to stay informed about new SDK versions
|
||||
2. **Review changelogs** before upgrading to understand new features and breaking changes
|
||||
3. **Monitor deprecations** to plan migrations before features are removed
|
||||
4. **Use `--check-only`** in automated pipelines to avoid unintended downloads
|
||||
5. **Filter by language** when working on specific platform integrations
|
||||
6. **Integrate with notifications** to alert teams about available updates
|
||||
Reference in New Issue
Block a user