usepaso 0.1.0

package/src/types.ts

@@ -0,0 +1,67 @@
+export interface PasoDeclaration {
+  version: string;
+  service: PasoService;
+  capabilities: PasoCapability[];
+  permissions?: PasoPermissions;
+}
+
+export interface PasoService {
+  name: string;
+  description: string;
+  base_url: string;
+  version?: string;
+  auth?: PasoAuth;
+}
+
+export interface PasoAuth {
+  type: 'api_key' | 'bearer' | 'oauth2' | 'none';
+  header?: string;
+  prefix?: string;
+}
+
+export interface PasoCapability {
+  name: string;
+  description: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  permission: 'read' | 'write' | 'admin';
+  consent_required?: boolean;
+  inputs?: Record<string, PasoInput>;
+  output?: Record<string, PasoOutput>;
+  constraints?: PasoConstraint[];
+}
+
+export interface PasoInput {
+  type: 'string' | 'integer' | 'number' | 'boolean' | 'enum' | 'array' | 'object';
+  required?: boolean;
+  description: string;
+  values?: (string | number)[];
+  default?: unknown;
+  in?: 'query' | 'path' | 'body' | 'header';
+}
+
+export interface PasoOutput {
+  type: 'string' | 'integer' | 'number' | 'boolean' | 'object' | 'array';
+  description?: string;
+}
+
+export interface PasoConstraint {
+  max_per_hour?: number;
+  max_per_request?: number;
+  max_value?: number;
+  allowed_values?: unknown[];
+  requires_field?: string;
+  description?: string;
+}
+
+export interface PasoPermissions {
+  read?: string[];
+  write?: string[];
+  admin?: string[];
+  forbidden?: string[];
+}
+
+export interface ValidationError {
+  path: string;
+  message: string;
+}

package/src/validator.ts

@@ -0,0 +1,188 @@
+import { PasoDeclaration, PasoCapability, ValidationError } from './types';
+
+const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const VALID_PERMISSIONS = ['read', 'write', 'admin'];
+const VALID_INPUT_TYPES = ['string', 'integer', 'number', 'boolean', 'enum', 'array', 'object'];
+const VALID_OUTPUT_TYPES = ['string', 'integer', 'number', 'boolean', 'object', 'array'];
+const VALID_AUTH_TYPES = ['api_key', 'bearer', 'oauth2', 'none'];
+const VALID_IN_VALUES = ['query', 'path', 'body', 'header'];
+const SNAKE_CASE_RE = /^[a-z][a-z0-9_]*$/;
+
+/**
+ * Validate a parsed PasoDeclaration against the spec.
+ * Returns an array of errors. Empty array = valid.
+ */
+export function validate(decl: PasoDeclaration): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // Version
+  if (!decl.version) {
+    errors.push({ path: 'version', message: 'version is required' });
+  } else if (decl.version !== '1.0') {
+    errors.push({ path: 'version', message: 'version must be "1.0"' });
+  }
+
+  // Service
+  if (!decl.service) {
+    errors.push({ path: 'service', message: 'service is required' });
+  } else {
+    if (!decl.service.name) {
+      errors.push({ path: 'service.name', message: 'service.name is required' });
+    }
+    if (!decl.service.description) {
+      errors.push({ path: 'service.description', message: 'service.description is required' });
+    }
+    if (!decl.service.base_url) {
+      errors.push({ path: 'service.base_url', message: 'service.base_url is required' });
+    } else {
+      try {
+        new URL(decl.service.base_url);
+      } catch {
+        errors.push({ path: 'service.base_url', message: 'service.base_url must be a valid URL' });
+      }
+    }
+    if (decl.service.auth) {
+      if (!VALID_AUTH_TYPES.includes(decl.service.auth.type)) {
+        errors.push({ path: 'service.auth.type', message: `auth.type must be one of: ${VALID_AUTH_TYPES.join(', ')}` });
+      }
+    }
+  }
+
+  // Capabilities
+  if (!decl.capabilities) {
+    errors.push({ path: 'capabilities', message: 'capabilities is required' });
+  } else if (!Array.isArray(decl.capabilities)) {
+    errors.push({ path: 'capabilities', message: 'capabilities must be an array' });
+  } else {
+    const names = new Set<string>();
+    decl.capabilities.forEach((cap, i) => {
+      const prefix = `capabilities[${i}]`;
+      errors.push(...validateCapability(cap, prefix, names));
+    });
+  }
+
+  // Permissions
+  if (decl.permissions) {
+    const capNames = new Set((decl.capabilities || []).map(c => c.name));
+    const allReferenced = new Set<string>();
+
+    for (const tier of ['read', 'write', 'admin', 'forbidden'] as const) {
+      const list = decl.permissions[tier];
+      if (list) {
+        for (const name of list) {
+          // forbidden can reference capabilities not declared (to explicitly block API endpoints)
+          if (tier !== 'forbidden' && !capNames.has(name)) {
+            errors.push({ path: `permissions.${tier}`, message: `references unknown capability "${name}"` });
+          }
+          if (tier !== 'forbidden' && allReferenced.has(name)) {
+            // Check if it's in forbidden
+          }
+          allReferenced.add(name);
+        }
+      }
+    }
+
+    // Check forbidden doesn't overlap with tiers
+    if (decl.permissions.forbidden) {
+      const tiered = new Set([
+        ...(decl.permissions.read || []),
+        ...(decl.permissions.write || []),
+        ...(decl.permissions.admin || []),
+      ]);
+      for (const name of decl.permissions.forbidden) {
+        if (tiered.has(name)) {
+          errors.push({ path: 'permissions.forbidden', message: `"${name}" cannot be both in a permission tier and forbidden` });
+        }
+      }
+    }
+  }
+
+  return errors;
+}
+
+function validateCapability(cap: PasoCapability, prefix: string, names: Set<string>): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  if (!cap.name) {
+    errors.push({ path: `${prefix}.name`, message: 'name is required' });
+  } else {
+    if (!SNAKE_CASE_RE.test(cap.name)) {
+      errors.push({ path: `${prefix}.name`, message: `"${cap.name}" must be snake_case` });
+    }
+    if (names.has(cap.name)) {
+      errors.push({ path: `${prefix}.name`, message: `duplicate capability name "${cap.name}"` });
+    }
+    names.add(cap.name);
+  }
+
+  if (!cap.description) {
+    errors.push({ path: `${prefix}.description`, message: 'description is required' });
+  }
+
+  if (!cap.method) {
+    errors.push({ path: `${prefix}.method`, message: 'method is required' });
+  } else if (!VALID_METHODS.includes(cap.method)) {
+    errors.push({ path: `${prefix}.method`, message: `method must be one of: ${VALID_METHODS.join(', ')}` });
+  }
+
+  if (!cap.path) {
+    errors.push({ path: `${prefix}.path`, message: 'path is required' });
+  } else if (!cap.path.startsWith('/')) {
+    errors.push({ path: `${prefix}.path`, message: 'path must start with /' });
+  }
+
+  if (!cap.permission) {
+    errors.push({ path: `${prefix}.permission`, message: 'permission is required' });
+  } else if (!VALID_PERMISSIONS.includes(cap.permission)) {
+    errors.push({ path: `${prefix}.permission`, message: `permission must be one of: ${VALID_PERMISSIONS.join(', ')}` });
+  }
+
+  // Validate inputs
+  if (cap.inputs) {
+    for (const [inputName, input] of Object.entries(cap.inputs)) {
+      const inputPrefix = `${prefix}.inputs.${inputName}`;
+      if (!input.type) {
+        errors.push({ path: inputPrefix, message: 'type is required' });
+      } else if (!VALID_INPUT_TYPES.includes(input.type)) {
+        errors.push({ path: inputPrefix, message: `type must be one of: ${VALID_INPUT_TYPES.join(', ')}` });
+      }
+      if (input.type === 'enum' && (!input.values || input.values.length === 0)) {
+        errors.push({ path: inputPrefix, message: 'enum type must have values defined' });
+      }
+      if (!input.description) {
+        errors.push({ path: inputPrefix, message: 'description is required' });
+      }
+      if (input.in && !VALID_IN_VALUES.includes(input.in)) {
+        errors.push({ path: `${inputPrefix}.in`, message: `in must be one of: ${VALID_IN_VALUES.join(', ')}` });
+      }
+    }
+  }
+
+  // Validate path params exist in inputs
+  if (cap.path && cap.inputs) {
+    const pathParams = cap.path.match(/\{([^}]+)\}/g);
+    if (pathParams) {
+      for (const param of pathParams) {
+        const paramName = param.slice(1, -1);
+        if (!cap.inputs[paramName]) {
+          errors.push({ path: `${prefix}.path`, message: `path parameter "{${paramName}}" not found in inputs` });
+        } else if (cap.inputs[paramName].in && cap.inputs[paramName].in !== 'path') {
+          errors.push({ path: `${prefix}.inputs.${paramName}`, message: `path parameter must have in: path` });
+        }
+      }
+    }
+  }
+
+  // Validate output
+  if (cap.output) {
+    for (const [fieldName, output] of Object.entries(cap.output)) {
+      if (!output.type) {
+        errors.push({ path: `${prefix}.output.${fieldName}`, message: 'type is required' });
+      } else if (!VALID_OUTPUT_TYPES.includes(output.type)) {
+        errors.push({ path: `${prefix}.output.${fieldName}`, message: `type must be one of: ${VALID_OUTPUT_TYPES.join(', ')}` });
+      }
+    }
+  }
+
+  return errors;
+}

package/tests/mcp.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest';
+import { generateMcpServer } from '../src/generators/mcp';
+import { parseFile } from '../src/parser';
+import { PasoDeclaration } from '../src/types';
+import { join } from 'path';
+
+function minimal(): PasoDeclaration {
+  return {
+    version: '1.0',
+    service: {
+      name: 'Test',
+      description: 'A test service',
+      base_url: 'https://api.test.com',
+    },
+    capabilities: [
+      {
+        name: 'get_item',
+        description: 'Get an item by ID',
+        method: 'GET',
+        path: '/items/{id}',
+        permission: 'read',
+        inputs: {
+          id: { type: 'string', required: true, description: 'Item ID', in: 'path' },
+        },
+        output: {
+          id: { type: 'string' },
+          name: { type: 'string' },
+        },
+      },
+      {
+        name: 'create_item',
+        description: 'Create a new item',
+        method: 'POST',
+        path: '/items',
+        permission: 'write',
+        consent_required: true,
+        inputs: {
+          name: { type: 'string', required: true, description: 'Item name' },
+          priority: { type: 'enum', description: 'Priority level', values: ['low', 'medium', 'high'] },
+        },
+      },
+    ],
+  };
+}
+
+describe('generateMcpServer', () => {
+  it('creates an MCP server from a minimal declaration', () => {
+    const server = generateMcpServer(minimal());
+    expect(server).toBeDefined();
+    expect(server.server).toBeDefined();
+  });
+
+  it('registers tools for each capability', () => {
+    const server = generateMcpServer(minimal());
+    // The server should have registered 2 tools
+    // We can check via the internal state
+    expect((server as any)._registeredTools).toBeDefined();
+    expect(Object.keys((server as any)._registeredTools)).toHaveLength(2);
+    expect((server as any)._registeredTools['get_item']).toBeDefined();
+    expect((server as any)._registeredTools['create_item']).toBeDefined();
+  });
+
+  it('skips forbidden capabilities', () => {
+    const decl = minimal();
+    decl.permissions = { forbidden: ['create_item'] };
+    const server = generateMcpServer(decl);
+    const tools = Object.keys((server as any)._registeredTools);
+    expect(tools).toHaveLength(1);
+    expect(tools).toContain('get_item');
+    expect(tools).not.toContain('create_item');
+  });
+
+  it('works with Sentry example', () => {
+    const decl = parseFile(join(__dirname, '../../../examples/sentry/paso.yaml'));
+    const server = generateMcpServer(decl);
+    const tools = Object.keys((server as any)._registeredTools);
+    expect(tools.length).toBeGreaterThan(0);
+    expect(tools).toContain('list_issues');
+    expect(tools).toContain('resolve_issue');
+  });
+
+  it('works with Stripe example (respects forbidden)', () => {
+    const decl = parseFile(join(__dirname, '../../../examples/stripe/paso.yaml'));
+    const server = generateMcpServer(decl);
+    const tools = Object.keys((server as any)._registeredTools);
+    expect(tools).toContain('list_customers');
+    expect(tools).toContain('create_payment_intent');
+    // delete_customer is in forbidden but not declared as a capability, so it's just not present
+    expect(tools).not.toContain('delete_customer');
+  });
+
+  it('handles capabilities with no inputs', () => {
+    const decl: PasoDeclaration = {
+      version: '1.0',
+      service: {
+        name: 'Test',
+        description: 'Test',
+        base_url: 'https://api.test.com',
+      },
+      capabilities: [
+        {
+          name: 'health_check',
+          description: 'Check service health',
+          method: 'GET',
+          path: '/health',
+          permission: 'read',
+        },
+      ],
+    };
+    const server = generateMcpServer(decl);
+    expect(Object.keys((server as any)._registeredTools)).toHaveLength(1);
+  });
+
+  it('includes consent warning in tool description', () => {
+    const server = generateMcpServer(minimal());
+    const createTool = (server as any)._registeredTools['create_item'];
+    expect(createTool).toBeDefined();
+  });
+});

package/tests/parser.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { parseString, parseFile } from '../src/parser';
+import { join } from 'path';
+
+describe('parseString', () => {
+  it('parses a minimal valid declaration', () => {
+    const yaml = `
+version: "1.0"
+service:
+  name: TestService
+  description: A test service
+  base_url: https://api.test.com
+capabilities:
+  - name: get_item
+    description: Get an item
+    method: GET
+    path: /items/{id}
+    permission: read
+    inputs:
+      id:
+        type: string
+        required: true
+        description: Item ID
+        in: path
+`;
+    const result = parseString(yaml);
+    expect(result.version).toBe('1.0');
+    expect(result.service.name).toBe('TestService');
+    expect(result.capabilities).toHaveLength(1);
+    expect(result.capabilities[0].name).toBe('get_item');
+  });
+
+  it('throws on invalid YAML', () => {
+    expect(() => parseString('{')).toThrow();
+  });
+
+  it('throws on non-object YAML', () => {
+    expect(() => parseString('hello')).toThrow('expected an object');
+  });
+});
+
+describe('parseFile', () => {
+  it('parses the Sentry example', () => {
+    const filePath = join(__dirname, '../../../examples/sentry/paso.yaml');
+    const result = parseFile(filePath);
+    expect(result.service.name).toBe('Sentry');
+    expect(result.capabilities.length).toBeGreaterThan(0);
+  });
+
+  it('parses the Stripe example', () => {
+    const filePath = join(__dirname, '../../../examples/stripe/paso.yaml');
+    const result = parseFile(filePath);
+    expect(result.service.name).toBe('Stripe');
+    expect(result.capabilities.length).toBeGreaterThan(0);
+  });
+
+  it('parses the Linear example', () => {
+    const filePath = join(__dirname, '../../../examples/linear/paso.yaml');
+    const result = parseFile(filePath);
+    expect(result.service.name).toBe('Linear');
+    expect(result.capabilities.length).toBeGreaterThan(0);
+  });
+
+  it('throws on missing file', () => {
+    expect(() => parseFile('/nonexistent/paso.yaml')).toThrow();
+  });
+});

package/tests/validator.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest';
+import { validate } from '../src/validator';
+import { parseFile } from '../src/parser';
+import { PasoDeclaration } from '../src/types';
+import { join } from 'path';
+
+function minimal(): PasoDeclaration {
+  return {
+    version: '1.0',
+    service: {
+      name: 'Test',
+      description: 'A test service',
+      base_url: 'https://api.test.com',
+    },
+    capabilities: [
+      {
+        name: 'get_item',
+        description: 'Get an item',
+        method: 'GET',
+        path: '/items',
+        permission: 'read',
+      },
+    ],
+  };
+}
+
+describe('validate', () => {
+  it('passes a minimal valid declaration', () => {
+    const errors = validate(minimal());
+    expect(errors).toHaveLength(0);
+  });
+
+  it('fails on missing version', () => {
+    const decl = minimal();
+    (decl as any).version = undefined;
+    const errors = validate(decl);
+    expect(errors.some(e => e.path === 'version')).toBe(true);
+  });
+
+  it('fails on wrong version', () => {
+    const decl = minimal();
+    decl.version = '2.0';
+    const errors = validate(decl);
+    expect(errors.some(e => e.message.includes('must be "1.0"'))).toBe(true);
+  });
+
+  it('fails on missing service name', () => {
+    const decl = minimal();
+    (decl.service as any).name = '';
+    const errors = validate(decl);
+    expect(errors.some(e => e.path === 'service.name')).toBe(true);
+  });
+
+  it('fails on invalid base_url', () => {
+    const decl = minimal();
+    decl.service.base_url = 'not-a-url';
+    const errors = validate(decl);
+    expect(errors.some(e => e.path === 'service.base_url')).toBe(true);
+  });
+
+  it('fails on non-snake_case capability name', () => {
+    const decl = minimal();
+    decl.capabilities[0].name = 'GetItem';
+    const errors = validate(decl);
+    expect(errors.some(e => e.message.includes('snake_case'))).toBe(true);
+  });
+
+  it('fails on duplicate capability names', () => {
+    const decl = minimal();
+    decl.capabilities.push({ ...decl.capabilities[0] });
+    const errors = validate(decl);
+    expect(errors.some(e => e.message.includes('duplicate'))).toBe(true);
+  });
+
+  it('fails on invalid HTTP method', () => {
+    const decl = minimal();
+    (decl.capabilities[0] as any).method = 'SEND';
+    const errors = validate(decl);
+    expect(errors.some(e => e.path.includes('method'))).toBe(true);
+  });
+
+  it('fails on path not starting with /', () => {
+    const decl = minimal();
+    decl.capabilities[0].path = 'items';
+    const errors = validate(decl);
+    expect(errors.some(e => e.message.includes('start with /'))).toBe(true);
+  });
+
+  it('fails on enum input without values', () => {
+    const decl = minimal();
+    decl.capabilities[0].inputs = {
+      status: { type: 'enum', description: 'Status' },
+    };
+    const errors = validate(decl);
+    expect(errors.some(e => e.message.includes('enum type must have values'))).toBe(true);
+  });
+
+  it('fails on path parameter missing from inputs', () => {
+    const decl = minimal();
+    decl.capabilities[0].path = '/items/{item_id}';
+    decl.capabilities[0].inputs = {};
+    const errors = validate(decl);
+    expect(errors.some(e => e.message.includes('item_id'))).toBe(true);
+  });
+
+  it('fails when forbidden overlaps with a tier', () => {
+    const decl = minimal();
+    decl.permissions = {
+      read: ['get_item'],
+      forbidden: ['get_item'],
+    };
+    const errors = validate(decl);
+    expect(errors.some(e => e.message.includes('cannot be both'))).toBe(true);
+  });
+
+  it('fails on unknown capability in permissions', () => {
+    const decl = minimal();
+    decl.permissions = {
+      read: ['nonexistent'],
+    };
+    const errors = validate(decl);
+    expect(errors.some(e => e.message.includes('unknown capability'))).toBe(true);
+  });
+
+  it('validates example files without errors', () => {
+    for (const example of ['sentry', 'stripe', 'linear']) {
+      const filePath = join(__dirname, `../../../examples/${example}/paso.yaml`);
+      const decl = parseFile(filePath);
+      const errors = validate(decl);
+      expect(errors, `${example} should have no validation errors: ${JSON.stringify(errors)}`).toHaveLength(0);
+    }
+  });
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}