9bd6a73926
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Added IPackRunIncidentModeService interface for managing incident mode activation, deactivation, and status retrieval. - Created PackRunIncidentModeService class implementing the service interface with methods for activating, deactivating, and escalating incident modes. - Introduced incident mode status model (PackRunIncidentModeStatus) and related enums for escalation levels and activation sources. - Developed retention policy, telemetry settings, and debug capture settings models to manage incident mode configurations. - Implemented SLO breach notification handling to activate incident mode based on severity. - Added in-memory store (InMemoryPackRunIncidentModeStore) for testing purposes. - Created comprehensive unit tests for incident mode service, covering activation, deactivation, status retrieval, and SLO breach handling.
499 lines
15 KiB
JSON
499 lines
15 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://stella-ops.org/schemas/sdk-generator-samples.schema.json",
|
|
"title": "StellaOps SDK Generator Samples Schema",
|
|
"description": "Schema for SDK generator output samples, snippet packs, and language bindings. Unblocks DEVPORT-63-002, DOCS-SDK-62-001 (2+ tasks).",
|
|
"type": "object",
|
|
"definitions": {
|
|
"SdkLanguage": {
|
|
"type": "string",
|
|
"enum": ["typescript", "python", "go", "java", "csharp", "ruby", "php", "rust"],
|
|
"description": "Supported SDK target languages"
|
|
},
|
|
"SdkSample": {
|
|
"type": "object",
|
|
"description": "Individual SDK code sample",
|
|
"required": ["sample_id", "language", "operation", "code"],
|
|
"properties": {
|
|
"sample_id": {
|
|
"type": "string",
|
|
"pattern": "^[a-z][a-z0-9-]*$",
|
|
"description": "Unique sample identifier"
|
|
},
|
|
"language": {
|
|
"$ref": "#/definitions/SdkLanguage"
|
|
},
|
|
"operation": {
|
|
"type": "string",
|
|
"description": "API operation this sample demonstrates"
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Human-readable title"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "Explanation of what the sample demonstrates"
|
|
},
|
|
"code": {
|
|
"type": "string",
|
|
"description": "The actual code sample"
|
|
},
|
|
"imports": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Required imports/dependencies"
|
|
},
|
|
"prerequisites": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Setup steps before running"
|
|
},
|
|
"expected_output": {
|
|
"type": "string",
|
|
"description": "Expected console output or result"
|
|
},
|
|
"tags": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Categorization tags (auth, scanning, vex, etc.)"
|
|
},
|
|
"digest": {
|
|
"type": "string",
|
|
"pattern": "^sha256:[a-f0-9]{64}$",
|
|
"description": "SHA-256 hash of code content for verification"
|
|
}
|
|
}
|
|
},
|
|
"SnippetPack": {
|
|
"type": "object",
|
|
"description": "Collection of SDK samples for a specific language",
|
|
"required": ["pack_id", "language", "version", "samples"],
|
|
"properties": {
|
|
"pack_id": {
|
|
"type": "string",
|
|
"description": "Unique pack identifier"
|
|
},
|
|
"language": {
|
|
"$ref": "#/definitions/SdkLanguage"
|
|
},
|
|
"version": {
|
|
"type": "string",
|
|
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
|
|
"description": "Pack version (semver)"
|
|
},
|
|
"sdk_version": {
|
|
"type": "string",
|
|
"description": "Target SDK version these samples work with"
|
|
},
|
|
"api_version": {
|
|
"type": "string",
|
|
"description": "API version (e.g., v1, v2)"
|
|
},
|
|
"generated_at": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
},
|
|
"samples": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/SdkSample"
|
|
}
|
|
},
|
|
"aggregate_digest": {
|
|
"type": "string",
|
|
"pattern": "^sha256:[a-f0-9]{64}$",
|
|
"description": "Hash of all sample digests combined"
|
|
},
|
|
"package_info": {
|
|
"$ref": "#/definitions/PackageInfo"
|
|
}
|
|
}
|
|
},
|
|
"PackageInfo": {
|
|
"type": "object",
|
|
"description": "Language-specific package information",
|
|
"properties": {
|
|
"package_name": {
|
|
"type": "string",
|
|
"description": "Package name (e.g., @stellaops/sdk, stellaops-sdk)"
|
|
},
|
|
"registry_url": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"description": "Package registry URL"
|
|
},
|
|
"install_command": {
|
|
"type": "string",
|
|
"description": "Command to install the SDK"
|
|
},
|
|
"min_runtime_version": {
|
|
"type": "string",
|
|
"description": "Minimum runtime version required"
|
|
},
|
|
"dependencies": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/Dependency"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Dependency": {
|
|
"type": "object",
|
|
"description": "SDK dependency",
|
|
"required": ["name", "version"],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"version": {
|
|
"type": "string"
|
|
},
|
|
"optional": {
|
|
"type": "boolean",
|
|
"default": false
|
|
}
|
|
}
|
|
},
|
|
"SdkGeneratorConfig": {
|
|
"type": "object",
|
|
"description": "SDK generator configuration",
|
|
"required": ["generator_id", "openapi_source"],
|
|
"properties": {
|
|
"generator_id": {
|
|
"type": "string"
|
|
},
|
|
"openapi_source": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"description": "OpenAPI spec URL or path"
|
|
},
|
|
"target_languages": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/SdkLanguage"
|
|
}
|
|
},
|
|
"output_dir": {
|
|
"type": "string"
|
|
},
|
|
"templates": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
},
|
|
"description": "Custom templates per language"
|
|
},
|
|
"options": {
|
|
"$ref": "#/definitions/GeneratorOptions"
|
|
}
|
|
}
|
|
},
|
|
"GeneratorOptions": {
|
|
"type": "object",
|
|
"description": "SDK generation options",
|
|
"properties": {
|
|
"include_samples": {
|
|
"type": "boolean",
|
|
"default": true,
|
|
"description": "Generate usage samples"
|
|
},
|
|
"include_tests": {
|
|
"type": "boolean",
|
|
"default": true,
|
|
"description": "Generate test stubs"
|
|
},
|
|
"include_docs": {
|
|
"type": "boolean",
|
|
"default": true,
|
|
"description": "Generate API documentation"
|
|
},
|
|
"async_style": {
|
|
"type": "string",
|
|
"enum": ["async_await", "promises", "callbacks", "sync"],
|
|
"default": "async_await"
|
|
},
|
|
"error_handling": {
|
|
"type": "string",
|
|
"enum": ["exceptions", "result_types", "error_codes"],
|
|
"default": "exceptions"
|
|
},
|
|
"naming_convention": {
|
|
"type": "string",
|
|
"enum": ["camelCase", "snake_case", "PascalCase"],
|
|
"description": "Override default for language"
|
|
}
|
|
}
|
|
},
|
|
"SdkGeneratorOutput": {
|
|
"type": "object",
|
|
"description": "Output from SDK generation",
|
|
"required": ["output_id", "generator_id", "generated_at", "files"],
|
|
"properties": {
|
|
"output_id": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"generator_id": {
|
|
"type": "string"
|
|
},
|
|
"generated_at": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
},
|
|
"language": {
|
|
"$ref": "#/definitions/SdkLanguage"
|
|
},
|
|
"sdk_version": {
|
|
"type": "string"
|
|
},
|
|
"api_version": {
|
|
"type": "string"
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/GeneratedFile"
|
|
}
|
|
},
|
|
"stats": {
|
|
"$ref": "#/definitions/GenerationStats"
|
|
},
|
|
"manifest_digest": {
|
|
"type": "string",
|
|
"pattern": "^sha256:[a-f0-9]{64}$"
|
|
}
|
|
}
|
|
},
|
|
"GeneratedFile": {
|
|
"type": "object",
|
|
"description": "Generated SDK file",
|
|
"required": ["path", "digest"],
|
|
"properties": {
|
|
"path": {
|
|
"type": "string"
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"enum": ["source", "test", "sample", "docs", "config"]
|
|
},
|
|
"size_bytes": {
|
|
"type": "integer"
|
|
},
|
|
"digest": {
|
|
"type": "string",
|
|
"pattern": "^sha256:[a-f0-9]{64}$"
|
|
}
|
|
}
|
|
},
|
|
"GenerationStats": {
|
|
"type": "object",
|
|
"description": "SDK generation statistics",
|
|
"properties": {
|
|
"total_files": {
|
|
"type": "integer"
|
|
},
|
|
"source_files": {
|
|
"type": "integer"
|
|
},
|
|
"test_files": {
|
|
"type": "integer"
|
|
},
|
|
"sample_files": {
|
|
"type": "integer"
|
|
},
|
|
"total_lines": {
|
|
"type": "integer"
|
|
},
|
|
"endpoints_covered": {
|
|
"type": "integer"
|
|
},
|
|
"models_generated": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
},
|
|
"SampleCategory": {
|
|
"type": "object",
|
|
"description": "Category grouping for samples",
|
|
"required": ["category_id", "name"],
|
|
"properties": {
|
|
"category_id": {
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"description": {
|
|
"type": "string"
|
|
},
|
|
"samples": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Sample IDs in this category"
|
|
},
|
|
"order": {
|
|
"type": "integer",
|
|
"description": "Display order"
|
|
}
|
|
}
|
|
},
|
|
"SdkDocumentation": {
|
|
"type": "object",
|
|
"description": "SDK documentation structure",
|
|
"properties": {
|
|
"overview": {
|
|
"type": "string",
|
|
"description": "SDK overview markdown"
|
|
},
|
|
"quickstart": {
|
|
"type": "string",
|
|
"description": "Quickstart guide markdown"
|
|
},
|
|
"authentication": {
|
|
"type": "string",
|
|
"description": "Authentication guide"
|
|
},
|
|
"error_handling": {
|
|
"type": "string",
|
|
"description": "Error handling guide"
|
|
},
|
|
"changelog": {
|
|
"type": "string",
|
|
"description": "SDK changelog"
|
|
},
|
|
"api_reference_url": {
|
|
"type": "string",
|
|
"format": "uri"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"properties": {
|
|
"snippet_packs": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/SnippetPack"
|
|
}
|
|
},
|
|
"categories": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/SampleCategory"
|
|
}
|
|
},
|
|
"generator_outputs": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/SdkGeneratorOutput"
|
|
}
|
|
}
|
|
},
|
|
"examples": [
|
|
{
|
|
"snippet_packs": [
|
|
{
|
|
"pack_id": "stellaops-typescript-samples",
|
|
"language": "typescript",
|
|
"version": "1.0.0",
|
|
"sdk_version": "2025.10.0",
|
|
"api_version": "v1",
|
|
"generated_at": "2025-12-06T10:00:00Z",
|
|
"samples": [
|
|
{
|
|
"sample_id": "auth-token-exchange",
|
|
"language": "typescript",
|
|
"operation": "POST /oauth/token",
|
|
"title": "Token Exchange",
|
|
"description": "Exchange client credentials for an access token",
|
|
"code": "import { StellaOpsClient } from '@stellaops/sdk';\n\nconst client = new StellaOpsClient({\n clientId: process.env.STELLAOPS_CLIENT_ID,\n clientSecret: process.env.STELLAOPS_CLIENT_SECRET,\n});\n\nconst token = await client.auth.getToken();\nconsole.log('Token expires at:', token.expiresAt);",
|
|
"imports": ["@stellaops/sdk"],
|
|
"prerequisites": [
|
|
"Set STELLAOPS_CLIENT_ID environment variable",
|
|
"Set STELLAOPS_CLIENT_SECRET environment variable"
|
|
],
|
|
"expected_output": "Token expires at: 2025-12-06T11:00:00Z",
|
|
"tags": ["authentication", "oauth"],
|
|
"digest": "sha256:abc123def456789012345678901234567890123456789012345678901234abcd"
|
|
},
|
|
{
|
|
"sample_id": "scan-container-image",
|
|
"language": "typescript",
|
|
"operation": "POST /api/v1/scanner/scan",
|
|
"title": "Scan Container Image",
|
|
"description": "Scan a container image for vulnerabilities",
|
|
"code": "import { StellaOpsClient } from '@stellaops/sdk';\n\nconst client = new StellaOpsClient();\nconst result = await client.scanner.scanImage({\n image: 'nginx:1.25',\n generateSbom: true,\n format: 'cyclonedx',\n});\n\nconsole.log(`Found ${result.vulnerabilities.length} vulnerabilities`);",
|
|
"imports": ["@stellaops/sdk"],
|
|
"tags": ["scanning", "sbom", "vulnerabilities"],
|
|
"digest": "sha256:def456abc789012345678901234567890123456789012345678901234defabc"
|
|
}
|
|
],
|
|
"aggregate_digest": "sha256:agg123def456789012345678901234567890123456789012345678901234agg",
|
|
"package_info": {
|
|
"package_name": "@stellaops/sdk",
|
|
"registry_url": "https://registry.npmjs.org",
|
|
"install_command": "npm install @stellaops/sdk",
|
|
"min_runtime_version": "18.0.0",
|
|
"dependencies": [
|
|
{ "name": "axios", "version": "^1.6.0" },
|
|
{ "name": "jose", "version": "^5.0.0" }
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"pack_id": "stellaops-python-samples",
|
|
"language": "python",
|
|
"version": "1.0.0",
|
|
"sdk_version": "2025.10.0",
|
|
"api_version": "v1",
|
|
"generated_at": "2025-12-06T10:00:00Z",
|
|
"samples": [
|
|
{
|
|
"sample_id": "auth-token-exchange-py",
|
|
"language": "python",
|
|
"operation": "POST /oauth/token",
|
|
"title": "Token Exchange",
|
|
"description": "Exchange client credentials for an access token",
|
|
"code": "from stellaops import StellaOpsClient\nimport os\n\nclient = StellaOpsClient(\n client_id=os.environ['STELLAOPS_CLIENT_ID'],\n client_secret=os.environ['STELLAOPS_CLIENT_SECRET'],\n)\n\ntoken = client.auth.get_token()\nprint(f'Token expires at: {token.expires_at}')",
|
|
"imports": ["stellaops"],
|
|
"tags": ["authentication", "oauth"],
|
|
"digest": "sha256:py123def456789012345678901234567890123456789012345678901234pyth"
|
|
}
|
|
],
|
|
"package_info": {
|
|
"package_name": "stellaops-sdk",
|
|
"registry_url": "https://pypi.org/project/stellaops-sdk/",
|
|
"install_command": "pip install stellaops-sdk",
|
|
"min_runtime_version": "3.10"
|
|
}
|
|
}
|
|
],
|
|
"categories": [
|
|
{
|
|
"category_id": "authentication",
|
|
"name": "Authentication",
|
|
"description": "Token exchange and authentication samples",
|
|
"samples": ["auth-token-exchange", "auth-token-exchange-py"],
|
|
"order": 1
|
|
},
|
|
{
|
|
"category_id": "scanning",
|
|
"name": "Container Scanning",
|
|
"description": "Container image scanning and SBOM generation",
|
|
"samples": ["scan-container-image"],
|
|
"order": 2
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|