@amodalai/amodal 0.1.2

package/src/fixtures/incident-response.ts

@@ -0,0 +1,232 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Fixture data for the incident response e2e test.
+ *
+ * Four content types:
+ * 1. Connection: statuspage API (mock)
+ * 2. Skill: incident triage methodology
+ * 3. Knowledge: oncall runbook
+ * 4. Automation: daily health check
+ *
+ * The mock API returns deterministic data so we can assert on the
+ * agent's response content.
+ */
+
+import http from 'node:http';
+
+// ---------------------------------------------------------------------------
+// amodal.json
+// ---------------------------------------------------------------------------
+
+export const CONFIG = {
+  name: 'incident-response-agent',
+  version: '1.0.0',
+  description: 'Monitors services and triages incidents',
+  models: {
+    main: {provider: 'anthropic', model: 'claude-sonnet-4-20250514'},
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Connection: statuspage
+// ---------------------------------------------------------------------------
+
+export const STATUSPAGE_SPEC = {
+  source: 'https://statuspage.example.com/api/v1/openapi.json',
+  format: 'openapi' as const,
+  auth: {
+    type: 'bearer',
+    header: 'Authorization',
+    prefix: 'Bearer',
+    token: 'env:STATUSPAGE_TOKEN',
+  },
+};
+
+export const STATUSPAGE_ACCESS = {
+  endpoints: {
+    'GET /components': {returns: ['id', 'name', 'status', 'updated_at']},
+    'GET /incidents': {returns: ['id', 'name', 'status', 'impact', 'created_at']},
+    'GET /incidents/:id': {returns: ['id', 'name', 'status', 'impact', 'body', 'components']},
+    'POST /incidents': {returns: ['id'], confirm: 'review' as const},
+  },
+};
+
+export const STATUSPAGE_SURFACE = `## Included
+
+### GET /components
+List all monitored components and their current status
+
+### GET /incidents
+List recent incidents
+
+### GET /incidents/:id
+Get incident details
+
+## Excluded
+
+### POST /incidents
+Create a new incident (requires confirmation)
+`;
+
+// ---------------------------------------------------------------------------
+// Skill: incident-triage
+// ---------------------------------------------------------------------------
+
+export const TRIAGE_SKILL = `---
+name: incident-triage
+description: Methodology for triaging service incidents based on component status
+trigger: When the user asks about service health, incidents, or outages
+---
+
+## Incident Triage
+
+Follow this methodology when assessing service health:
+
+1. **Check component status** — Query GET /components to see current state of all services
+2. **Identify degraded components** — Any component not in "operational" status needs attention
+3. **Assess severity** — Use the severity matrix from the oncall runbook
+4. **Check recent incidents** — Query GET /incidents for correlated issues
+5. **Recommend action** — Based on severity, recommend the appropriate response from the runbook
+
+Always report the exact component names and their statuses. Never fabricate status data.
+`;
+
+// ---------------------------------------------------------------------------
+// Knowledge: oncall-runbook
+// ---------------------------------------------------------------------------
+
+export const ONCALL_RUNBOOK = `# On-Call Runbook
+
+## Severity Matrix
+
+| Level | Criteria | Response Time | Escalation |
+|-------|----------|---------------|------------|
+| SEV1 | Multiple components down | 5 min | Page on-call lead immediately |
+| SEV2 | Single component degraded | 15 min | Notify #incidents channel |
+| SEV3 | Performance degradation | 1 hour | Create ticket |
+| SEV4 | Cosmetic or minor | Next business day | Log for review |
+
+## Key Contacts
+
+- **On-call lead**: Alice (alice@example.com)
+- **Platform team**: Bob (bob@example.com)
+- **Database team**: Charlie (charlie@example.com)
+
+## Components
+
+- **api-gateway**: Main API entry point. SEV1 if down.
+- **auth-service**: Authentication. SEV1 if down.
+- **database-primary**: Primary Postgres. SEV1 if down.
+- **worker-pool**: Background jobs. SEV2 if degraded.
+- **cdn**: Static assets. SEV3 if degraded.
+`;
+
+// ---------------------------------------------------------------------------
+// Automation: health-check
+// ---------------------------------------------------------------------------
+
+export const HEALTH_CHECK_AUTOMATION = `# Automation: Daily Health Check
+
+Schedule: 0 8 * * *
+
+## Check
+Query the statuspage API for current component status. Report any components not in "operational" state.
+
+## Output
+Summary of component statuses with severity assessment per the oncall runbook.
+
+## Delivery
+Post to #ops-daily channel.
+`;
+
+// ---------------------------------------------------------------------------
+// Mock StatusPage API
+// ---------------------------------------------------------------------------
+
+/** Deterministic mock data the API returns. */
+export const MOCK_COMPONENTS = [
+  {id: 'comp-1', name: 'api-gateway', status: 'operational', updated_at: '2026-03-18T08:00:00Z'},
+  {id: 'comp-2', name: 'auth-service', status: 'operational', updated_at: '2026-03-18T08:00:00Z'},
+  {id: 'comp-3', name: 'database-primary', status: 'degraded_performance', updated_at: '2026-03-18T09:15:00Z'},
+  {id: 'comp-4', name: 'worker-pool', status: 'operational', updated_at: '2026-03-18T08:00:00Z'},
+  {id: 'comp-5', name: 'cdn', status: 'operational', updated_at: '2026-03-18T08:00:00Z'},
+];
+
+export const MOCK_INCIDENTS = [
+  {
+    id: 'inc-42',
+    name: 'Database latency spike',
+    status: 'investigating',
+    impact: 'minor',
+    created_at: '2026-03-18T09:10:00Z',
+    body: 'We are investigating elevated query latency on the primary database cluster.',
+    components: ['database-primary'],
+  },
+];
+
+/**
+ * Create a mock StatusPage API server that returns deterministic data.
+ * Returns a handle with start/stop methods.
+ */
+export function createMockStatusPageApi() {
+  const requests: Array<{method: string; url: string}> = [];
+
+  const server = http.createServer((req, res) => {
+    const url = req.url ?? '';
+    const method = req.method ?? '';
+    requests.push({method, url});
+
+    const json = (data: unknown) => {
+      res.writeHead(200, {'Content-Type': 'application/json'});
+      res.end(JSON.stringify(data));
+    };
+
+    if (method === 'GET' && url === '/components') {
+      json(MOCK_COMPONENTS);
+      return;
+    }
+
+    if (method === 'GET' && url === '/incidents') {
+      json(MOCK_INCIDENTS);
+      return;
+    }
+
+    const incidentMatch = /^\/incidents\/([^/]+)$/.exec(url);
+    if (method === 'GET' && incidentMatch) {
+      const incident = MOCK_INCIDENTS.find((i) => i.id === incidentMatch[1]);
+      if (incident) {
+        json(incident);
+      } else {
+        res.writeHead(404);
+        res.end(JSON.stringify({error: 'Not found'}));
+      }
+      return;
+    }
+
+    res.writeHead(404);
+    res.end(JSON.stringify({error: 'Not found'}));
+  });
+
+  let port = 0;
+
+  return {
+    server,
+    requests,
+    get port() { return port; },
+    start: () => new Promise<number>((resolve) => {
+      server.listen(0, '127.0.0.1', () => {
+        const addr = server.address();
+        port = typeof addr === 'object' && addr ? addr.port : 0;
+        resolve(port);
+      });
+    }),
+    stop: () => new Promise<void>((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    }),
+  };
+}

package/src/main.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {readFileSync} from 'node:fs';
+import yargs from 'yargs';
+import {hideBin} from 'yargs/helpers';
+import {amodalCommands} from './commands/index.js';
+
+const raw: unknown = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'));
+if (typeof raw !== 'object' || raw === null || !('version' in raw) || typeof raw.version !== 'string') {
+  throw new Error('Failed to read version from package.json');
+}
+const pkgVersion = raw.version;
+
+const cli = yargs(hideBin(process.argv))
+  .scriptName('amodal')
+  .usage('$0 <command> [options]');
+
+for (const cmd of amodalCommands) {
+  cli.command(cmd);
+}
+
+cli
+  .demandCommand(1, 'Run amodal <command> --help for usage')
+  .strict()
+  .help()
+  .alias('h', 'help')
+  .version(process.env['CLI_VERSION'] ?? pkgVersion)
+  .alias('v', 'version');
+
+void cli.parse();

package/src/shared/platform-client.test.ts

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {PlatformClient} from './platform-client.js';
+
+describe('PlatformClient', () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('throws if PLATFORM_API_URL not set', () => {
+    const origUrl = process.env['PLATFORM_API_URL'];
+    const origKey = process.env['PLATFORM_API_KEY'];
+    delete process.env['PLATFORM_API_URL'];
+    delete process.env['PLATFORM_API_KEY'];
+
+    try {
+      expect(() => new PlatformClient()).toThrow('Platform URL not found');
+    } finally {
+      if (origUrl) process.env['PLATFORM_API_URL'] = origUrl;
+      if (origKey) process.env['PLATFORM_API_KEY'] = origKey;
+    }
+  });
+
+  it('throws if PLATFORM_API_KEY not set', () => {
+    expect(() => new PlatformClient({url: 'http://localhost:4000'})).toThrow('Platform auth not found');
+  });
+
+  it('creates client with explicit options', () => {
+    const client = new PlatformClient({url: 'http://localhost:4000', apiKey: 'test-key'});
+    expect(client).toBeDefined();
+  });
+
+  it('uploads snapshot via POST', async () => {
+    const mockResponse = {
+      id: 'deploy-abc1234',
+      environment: 'production',
+      isActive: true,
+      createdAt: new Date().toISOString(),
+      createdBy: 'test',
+      source: 'cli',
+      snapshotSize: 1024,
+    };
+
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(mockResponse),
+    });
+
+    const client = new PlatformClient({url: 'http://localhost:4000', apiKey: 'key'});
+    const result = await client.uploadSnapshot({
+      deployId: 'deploy-abc1234',
+      createdAt: new Date().toISOString(),
+      createdBy: 'test',
+      source: 'cli',
+      config: {name: 'test', version: '1.0', models: {main: {provider: 'a', model: 'b'}}},
+      connections: {},
+      skills: [],
+      automations: [],
+      knowledge: [],
+    });
+
+    expect(result.id).toBe('deploy-abc1234');
+     
+    const fetchCall = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [string, RequestInit];
+    expect(fetchCall[0]).toBe('http://localhost:4000/api/snapshot-deployments');
+    expect(fetchCall[1].method).toBe('POST');
+  });
+
+  it('lists deployments via GET', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    });
+
+    const client = new PlatformClient({url: 'http://localhost:4000', apiKey: 'key'});
+    const result = await client.listDeployments({environment: 'staging', limit: 5});
+
+    expect(result).toEqual([]);
+     
+    const fetchCall = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [string];
+    expect(fetchCall[0]).toContain('environment=staging');
+    expect(fetchCall[0]).toContain('limit=5');
+  });
+
+  it('throws on non-ok response', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 401,
+      json: () => Promise.resolve({error: 'Unauthorized'}),
+    });
+
+    const client = new PlatformClient({url: 'http://localhost:4000', apiKey: 'bad-key'});
+    await expect(client.listDeployments()).rejects.toThrow('failed (401)');
+  });
+});

package/src/shared/platform-client.ts

@@ -0,0 +1,193 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import type {DeploySnapshot} from '@amodalai/core';
+import {readProjectLink} from '../commands/link.js';
+import {readRcFile} from '../commands/login.js';
+
+/**
+ * Metadata returned for a snapshot deployment.
+ */
+export interface SnapshotDeploymentMeta {
+  id: string;
+  environment: string;
+  isActive: boolean;
+  createdAt: string;
+  createdBy: string;
+  source: string;
+  commitSha?: string;
+  branch?: string;
+  message?: string;
+  snapshotSize: number;
+}
+
+/**
+ * Resolve platform URL and API key from multiple sources:
+ * 1. Explicit options (flags)
+ * 2. .amodal/project.json (platformUrl from `amodal link`)
+ * 3. ~/.amodalrc (auth token from `amodal login`)
+ * 4. Env vars (fallback)
+ */
+export async function resolvePlatformConfig(options?: {
+  url?: string;
+  apiKey?: string;
+}): Promise<{url: string; apiKey: string}> {
+  let url = options?.url;
+  let apiKey = options?.apiKey;
+
+  // Try project link for URL
+  if (!url) {
+    const link = await readProjectLink();
+    if (link?.platformUrl) {
+      url = link.platformUrl;
+    }
+  }
+
+  // Try rc file for auth token
+  if (!apiKey) {
+    const rc = await readRcFile();
+    if (rc.platform?.token) {
+      apiKey = rc.platform.token;
+      // Also use the URL from rc if still missing
+      if (!url && rc.platform.url) {
+        url = rc.platform.url;
+      }
+    }
+  }
+
+  // Env vars as fallback
+  if (!url) url = process.env['PLATFORM_API_URL'];
+  if (!apiKey) apiKey = process.env['PLATFORM_API_KEY'];
+
+  if (!url) throw new Error('Platform URL not found. Run `amodal login` + `amodal link`, or set PLATFORM_API_URL.');
+  if (!apiKey) throw new Error('Platform auth not found. Run `amodal login`, or set PLATFORM_API_KEY.');
+
+  return {url: url.replace(/\/$/, ''), apiKey};
+}
+
+/**
+ * Platform API client for snapshot deployments.
+ *
+ * Resolves credentials from: explicit options → project link → rc file → env vars.
+ * Use `PlatformClient.create()` for async auto-discovery, or `new PlatformClient()` for sync usage.
+ */
+export class PlatformClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+
+  constructor(options?: {url?: string; apiKey?: string}) {
+    const url = options?.url ?? process.env['PLATFORM_API_URL'];
+    const apiKey = options?.apiKey ?? process.env['PLATFORM_API_KEY'];
+    if (!url) throw new Error('Platform URL not found. Run `amodal login` + `amodal link`, or set PLATFORM_API_URL.');
+    if (!apiKey) throw new Error('Platform auth not found. Run `amodal login`, or set PLATFORM_API_KEY.');
+    this.baseUrl = url.replace(/\/$/, '');
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Create a PlatformClient with auto-discovery of credentials.
+   * Resolves from: explicit options → project link → rc file → env vars.
+   */
+  static async create(options?: {url?: string; apiKey?: string}): Promise<PlatformClient> {
+    const config = await resolvePlatformConfig(options);
+    return new PlatformClient(config);
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      'Authorization': `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const resp = await fetch(url, {
+      method,
+      headers: this.headers(),
+      ...(body ? {body: JSON.stringify(body)} : {}),
+    });
+
+    if (!resp.ok) {
+      let detail = '';
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        const errBody = await resp.json() as {error?: string};
+        detail = errBody.error ? `: ${errBody.error}` : '';
+      } catch {
+        // ignore parse errors
+      }
+      throw new Error(`Platform API ${method} ${path} failed (${resp.status})${detail}`);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return resp.json() as Promise<T>;
+  }
+
+  /**
+   * Upload a snapshot and deploy it.
+   */
+  async uploadSnapshot(snapshot: DeploySnapshot, options: {
+    environment?: string;
+  } = {}): Promise<SnapshotDeploymentMeta> {
+    return this.request<SnapshotDeploymentMeta>('POST', '/api/snapshot-deployments', {
+      snapshot,
+      environment: options.environment ?? 'production',
+    });
+  }
+
+  /**
+   * List deployments for the authenticated tenant.
+   */
+  async listDeployments(options: {
+    environment?: string;
+    limit?: number;
+  } = {}): Promise<SnapshotDeploymentMeta[]> {
+    const params = new URLSearchParams();
+    if (options.environment) params.set('environment', options.environment);
+    if (options.limit) params.set('limit', String(options.limit));
+    const qs = params.toString();
+    return this.request<SnapshotDeploymentMeta[]>('GET', `/api/snapshot-deployments${qs ? `?${qs}` : ''}`);
+  }
+
+  /**
+   * Rollback to a previous deployment.
+   */
+  async rollback(options: {
+    deployId?: string;
+    environment?: string;
+  } = {}): Promise<SnapshotDeploymentMeta> {
+    return this.request<SnapshotDeploymentMeta>('POST', '/api/snapshot-deployments/rollback', {
+      deployId: options.deployId,
+      environment: options.environment ?? 'production',
+    });
+  }
+
+  /**
+   * Promote a deployment from one environment to another.
+   */
+  async promote(fromEnv: string, toEnv: string = 'production'): Promise<SnapshotDeploymentMeta> {
+    return this.request<SnapshotDeploymentMeta>('POST', '/api/snapshot-deployments/promote', {
+      fromEnvironment: fromEnv,
+      toEnvironment: toEnv,
+    });
+  }
+
+  /**
+   * Get status of a specific deployment.
+   */
+  async getStatus(deployId: string): Promise<SnapshotDeploymentMeta> {
+    return this.request<SnapshotDeploymentMeta>('GET', `/api/snapshot-deployments/${deployId}`);
+  }
+
+  /**
+   * Get the active snapshot for an environment.
+   */
+  async getActiveSnapshot(environment: string = 'production'): Promise<DeploySnapshot> {
+    const params = new URLSearchParams({environment});
+    return this.request<DeploySnapshot>('GET', `/api/snapshot-deployments/active?${params.toString()}`);
+  }
+}

package/src/shared/repo-discovery.test.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {findRepoRoot} from './repo-discovery.js';
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+}));
+
+describe('findRepoRoot', () => {
+  let existsSync: ReturnType<typeof vi.fn>;
+
+  beforeEach(async () => {
+    const fs = await import('node:fs');
+    existsSync = vi.mocked(fs.existsSync);
+    existsSync.mockReset();
+  });
+
+  it('should find repo root when config is in current directory', () => {
+    existsSync.mockImplementation((path: string) =>
+      path === '/projects/myapp/amodal.json',
+    );
+
+    const result = findRepoRoot('/projects/myapp');
+    expect(result).toBe('/projects/myapp');
+  });
+
+  it('should find repo root in parent directory', () => {
+    existsSync.mockImplementation((path: string) =>
+      path === '/projects/myapp/amodal.json',
+    );
+
+    const result = findRepoRoot('/projects/myapp/src/lib');
+    expect(result).toBe('/projects/myapp');
+  });
+
+  it('should throw when config is not found', () => {
+    existsSync.mockReturnValue(false);
+
+    expect(() => findRepoRoot('/some/deep/path')).toThrow(
+      'Could not find amodal.json',
+    );
+  });
+
+  it('should handle root directory without infinite loop', () => {
+    existsSync.mockReturnValue(false);
+
+    expect(() => findRepoRoot('/')).toThrow(
+      'Could not find amodal.json',
+    );
+  });
+});

package/src/shared/repo-discovery.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {existsSync} from 'node:fs';
+import {join, resolve, dirname} from 'node:path';
+
+/**
+ * Walks up from `startDir` (or cwd) looking for a directory containing
+ * `amodal.json`. Throws if not found.
+ */
+export function findRepoRoot(startDir?: string): string {
+  let dir = resolve(startDir ?? process.cwd());
+
+  // Safety limit to prevent infinite loops
+  const maxDepth = 100;
+  let depth = 0;
+
+  while (depth < maxDepth) {
+    const configPath = join(dir, 'amodal.json');
+    if (existsSync(configPath)) {
+      return dir;
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) {
+      // Reached filesystem root
+      break;
+    }
+    dir = parent;
+    depth++;
+  }
+
+  throw new Error(
+    'Could not find amodal.json in any parent directory. ' +
+    'Run `amodal init` to create a new project, or change to a directory containing an amodal.json file.',
+  );
+}

package/src/templates/compose-template.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2025 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Generate a docker-compose.yml for local/staging deployment.
+ */
+export function generateCompose(serviceName: string): string {
+  const safeName = serviceName.replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+  return `# Docker Compose for amodal runtime
+# Generated by: amodal deploy init
+
+services:
+  ${safeName}:
+    build: .
+    ports:
+      - "3847:3847"
+    env_file:
+      - .env.production
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3847/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+`;
+}