Component Development

Full guide: docs/development/component-development.mdx

Quick Reference

File Location

code

worker/src/components/<category>/<component-name>.ts

Categories: security/, core/, ai/, notification/, manual-action/

ID Pattern

code

<namespace>.<tool>.<action>

Examples: shipsec.dnsx.run, core.http.request, ai.llm.generate

Minimal Component

typescript

import { z } from 'zod';
import { defineComponent, inputs, outputs, port } from '@shipsec/component-sdk';

export default defineComponent({
  id: 'category.tool.action',
  label: 'My Component',
  category: 'security',  // or: core, ai, notification, manual_action
  runner: { kind: 'inline' },  // or: docker
  
  inputs: inputs({
    target: port(z.string(), { label: 'Target Host' }),
  }),

  outputs: outputs({
    success: port(z.boolean(), { label: 'Success' }),
  }),

  async execute({ inputs }, context) { 
    // ... logic ...
    return { success: true };
  }
});

Agent Instructions

When Creating a New Component

•
Check existing components in same category for patterns
bash
```
ls worker/src/components/<category>/
```
•
Copy structure from similar component — don't start from scratch
•
Always use defineComponent helper with separated schemas:
- •inputs() + port()
- •outputs() + port()
- •parameters() + param() (optional)
- •Unit test in __tests__/<component>.test.ts
•
For Docker components:
- •MUST use shell wrapper: entrypoint: 'sh', command: ['-c', 'tool "$@"', '--']
- •MUST use IsolatedContainerVolume for file I/O
- •Reference: worker/src/components/security/dnsx.ts

Quick Component Checklist

code

□ ID follows pattern: namespace.tool.action
□ File in correct category folder
□ inputs/outputs/parameters defined with port()/param() helpers
□ execute() receives { inputs, params }
□ Docker: shell wrapper pattern used
□ Docker with files: IsolatedContainerVolume used
□ Unit test created
□ Exported as default (componentRegistry.register is handled by defineComponent)

Key Patterns (Quick Look)

Inline Component

typescript

runner: { kind: 'inline' }
// Just write TypeScript in execute()

Docker Component

typescript

runner: {
  kind: 'docker',
  image: 'tool:latest',
  entrypoint: 'sh',
  command: ['-c', 'tool "$@"', '--'],
  network: 'bridge',
}
// ⚠️ Shell wrapper required for PTY

→ See: docs/development/component-development.mdx#docker-component-requirements

File I/O (Docker)

typescript

import { IsolatedContainerVolume } from '../../utils/isolated-volume';
const volume = new IsolatedContainerVolume(tenantId, context.runId);
try {
  await volume.initialize({ 'input.txt': data });
  // volumes: [volume.getVolumeConfig('/path', true)]
  // Note: Permissions are auto-set for nonroot containers
} finally {
  await volume.cleanup();
}

→ See: docs/development/isolated-volumes.mdx

Entry Point Runtime Inputs

typescript

// Supported types: text, number, file, json, array, secret
const runtimeInputs = [
  { id: 'apiKey', label: 'API Key', type: 'secret', required: true },
  { id: 'targets', label: 'Targets', type: 'array', required: true },
];
// Secret type renders as password field in UI

→ See: docs/development/component-development.mdx#entry-point-runtime-input-types

Inputs vs. Parameters

Type	Function	UI Location	Use Case
Inputs	`inputs()` + `port()`	Canvas handles	Runtime data (target, apiKey, fileId)
Parameters	`parameters()` + `param()`	Sidebar form	Static config (model, timeout, enum)

Note on Inputs: You can set valuePriority: 'manual-first' in port metadata to prioritize manual overrides over connected data.

Defining Parameters

typescript

parameters: parameters({
  model: param(z.string().default('gpt-4'), {
    label: 'Model Name',
    editor: 'select',
    options: [{ label: 'GPT-4', value: 'gpt-4' }],
  }),
  timeout: param(z.number().min(1), { 
    label: 'Timeout', 
    editor: 'number' 
  }),
})

Editors: text, textarea, number, boolean, select, multi-select, json, secret.

Context Services

typescript

async execute({ inputs, params }, context) {
  context.logger.info('...');           // Logs to UI timeline
  context.emitProgress('...');          // Progress events
  await context.secrets?.get('KEY');    // Encrypted secrets
  await context.storage?.downloadFile(inputs.fileId);  // MinIO files
  await context.artifacts?.upload({...});   // Save artifacts
}

Error Handling

typescript

import { ValidationError, AuthenticationError, ServiceError } from '@shipsec/component-sdk';

// Non-retryable (immediate fail)
throw new ValidationError('Bad input', { fieldErrors: {...} });
throw new AuthenticationError('Invalid API key');

// Retryable (Temporal will retry)
throw new ServiceError('API down', { statusCode: 503 });

→ See: docs/development/component-development.mdx#error-handling

Testing Commands

bash

# Unit tests (mocked, fast)
bun --cwd worker test

# Integration tests (real Docker)
ENABLE_DOCKER_TESTS=true bun --cwd worker test

# E2E tests (full stack - requires `just dev`)
RUN_E2E=true bun --cwd e2e-tests test

Common Mistakes to Avoid

Mistake	Fix
Docker without shell wrapper	Use `entrypoint: 'sh', command: ['-c', 'tool "$@"', '--']`
Direct file mounts in Docker	Use `IsolatedContainerVolume`
Missing `finally` for volume cleanup	Always `await volume.cleanup()` in finally
Missing `port()` wrapper	All input/output schemas must use `port()`
Mixing inputs and parameters	Use `inputs()` for runtime ports and `parameters()` for design-time config
Throwing plain Error	Use SDK errors: `ValidationError`, `ServiceError`, etc.

Reference Files

What	Where
Full docs	`docs/development/component-development.mdx`
Isolated volumes	`docs/development/isolated-volumes.mdx`
SDK source	`packages/component-sdk/src/`
Good example (Docker)	`worker/src/components/security/dnsx.ts`
Good example (inline)	`worker/src/components/core/http-request.ts`
E2E tests	`e2e-tests/`