octobus-service-package

name	octobus-service-package
description	Use when creating, reviewing, or fixing OctoBus JavaScript service packages from API docs, request examples, existing implementations, or proto/service manifests. Helps generate npm-compatible service packages with service.json, package.json bin, proto contracts, SDK handlers, config/secret schemas, and tests.

OctoBus Service Package

Purpose

Use this skill to develop OctoBus service packages, especially JavaScript packages built with @chaitin-ai/octobus-sdk. The output should be an importable npm-compatible package, not just loose handler code.

Reference Map

Read only the references needed for the task:

• references/service-package-contract.md: OctoBus package manifest, import/build/runtime rules, long-running vs on-demand behavior.
• references/js-sdk.md: @chaitin-ai/octobus-sdk APIs, runtime commands, handler context, errors, validation, and local development commands.
• references/generation-and-tests.md: workflow for generating packages from API docs/samples and the expected test strategy.

Default Workflow

1. Inspect available context: API docs, request/response examples, existing client code, current package files, or similar examples under examples/.
2. Design the proto first: stable package name, normally unary RPC methods, request/response messages, field names with JSON compatibility, and explicit error behavior.
3. For new JavaScript packages, prefer starting from npx octobus-sdk bootstrap --name ... --out ..., then edit the generated proto, schemas, and handler. Use --runtime-mode long-running only when a persistent gRPC service is required.
4. Create or update the package files:
   • service.json
   • root package.json with bin targets; for multi-service packages, each service root service.json.name must match a root bin key
   • proto/*.proto
   • bin/*.js or TypeScript source plus build output
   • config.schema.json and secret.schema.json when configuration or credentials are required
   • tests beside the package when the package owns meaningful logic
5. Implement handlers with @chaitin-ai/octobus-sdk. Do not reimplement the OctoBus serve / invoke protocol, gRPC health checks, descriptor loading, ProtoJSON rendering, or CLI plumbing unless the user explicitly asks for a non-SDK package.
6. Use mainstream libraries for foundational concerns such as HTTP clients, schema validation, retries, date parsing, OAuth/JWT, and URL construction. Avoid ad hoc protocol clients when an established package exists.
7. Validate locally:
   • npm install or npm ci
   • npx octobus-sdk validate --strict when all declared methods should be implemented
   • npx octobus-sdk client-stub --transport connect or --transport grpc when client generation matters
   • package tests (npm test, node --test, vitest, etc.)
   • node <bin> --runtime dev --port 50051 --config-json '{}' --secret-json '{}' for runtime smoke tests when useful
   • npm pack --dry-run to confirm package contents
   • octobus service import --id <id> <package-dir> for end-to-end import when OctoBus is available

Generation Rules

• Prefer a small, explicit proto surface over mirroring an entire upstream API mechanically.
• Prefer unary RPC methods for agent/tool-facing packages, especially on-demand packages and methods exposed through the generated local CLI. Use streaming only when the service is long-running and real gRPC clients need server, client, or bidirectional streams.
• Keep secrets out of config. Put tokens, passwords, API keys, and private keys in secretSchema.
• Map upstream validation failures to grpcInvalidArgumentError, auth failures to grpcUnauthenticatedError or grpcPermissionDeniedError, missing resources to grpcNotFoundError, and transient upstream failures to grpcUnavailableError.
• Use ctx.getMetadata() / ctx.getMetadataAll() for request metadata and ctx.config / ctx.secret for instance data. OctoBus control metadata (x-octobus-*) is stripped before handlers run; OctoBus-scoped business metadata must use x-octobus-ext-*, for example x-octobus-ext-username.
• Preserve handler keys exactly as <proto.package>.<Service>/<Method>, for example gitlab.v1.GitLabService/GetIssue.
• For on-demand packages, set service.json.runtime.mode to on-demand and keep handlers stateless enough for one-process-per-request execution.
• For long-running packages, assume multiple instances share the package runtime directory but have separate workdirs.

Quality Bar

Generated packages should include tests that cover:

• request mapping from proto-shaped input to upstream calls
• response mapping back to proto-shaped objects
• config and secret handling
• upstream error mapping to gRPC errors
• handler validation against proto methods

For packages with nontrivial upstream integration, isolate business logic from SDK glue so unit tests can mock HTTP/API clients without starting gRPC.

Useful Existing Examples

• Long-running JavaScript example: examples/calculator-js
• On-demand JavaScript example: examples/calculator-on-demand-js
• Streaming JavaScript example: examples/streaming-js
• SDK tests and fixtures: sdk/tests