Maintainx Upgrade MigrationSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: maintainx-upgrade-migration
description: 'Migrate MaintainX API versions and handle breaking changes.

  Use when upgrading API versions, handling deprecations,

  or migrating between MaintainX API releases.

  Trigger with phrases like "maintainx upgrade", "maintainx api version",

  "maintainx migration", "maintainx breaking changes", "maintainx deprecation".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
version: 1.11.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- maintainx
- api
- migration
compatibility: Designed for Claude Code
---
# MaintainX Upgrade & Migration

## Current State

!`npm list 2>/dev/null | head -20`

## Overview

Handle MaintainX API version upgrades, deprecations, and breaking changes with a safe, incremental migration strategy.

## Prerequisites

- Existing MaintainX integration
- Test environment with separate API key
- Version control (git) for all integration code

## Instructions

### Step 1: Audit Current API Usage

```typescript
// scripts/audit-api-usage.ts
// Scan your codebase for all MaintainX API calls

import { readFileSync, readdirSync, statSync } from 'fs';
import { join } from 'path';

function findApiCalls(dir: string): Array<{ file: string; line: number; endpoint: string }> {
  const results: Array<{ file: string; line: number; endpoint: string }> = [];

  function scan(d: string) {
    for (const entry of readdirSync(d)) {
      const full = join(d, entry);
      if (statSync(full).isDirectory()) {
        if (!entry.startsWith('.') && entry !== 'node_modules') scan(full);
      } else if (full.endsWith('.ts') || full.endsWith('.js')) {
        const content = readFileSync(full, 'utf-8');
        const lines = content.split('\n');
        for (let i = 0; i < lines.length; i++) {
          // Match API endpoint patterns
          const match = lines[i].match(/'"`[^'"`]*)/);
          if (match) {
            results.push({ file: full, line: i + 1, endpoint: match[1] });
          }
        }
      }
    }
  }

  scan(dir);
  return results;
}

const calls = findApiCalls('./src');
console.log('=== MaintainX API Usage Audit ===');
console.log(`Found ${calls.length} API calls:\n`);

// Group by endpoint
const grouped = new Map<string, typeof calls>();
for (const call of calls) {
  const base = call.endpoint.split('?')[0].replace(/\/\d+/, '/:id');
  const existing = grouped.get(base) || [];
  existing.push(call);
  grouped.set(base, existing);
}

for (const [endpoint, usages] of grouped) {
  console.log(`${endpoint} (${usages.length} calls):`);
  for (const u of usages) {
    console.log(`  ${u.file}:${u.line}`);
  }
}
```

### Step 2: Version Compatibility Layer

```typescript
// src/migration/compat.ts

type ApiVersion = 'v1' | 'v2';

interface VersionAdapter {
  baseUrl: string;
  transformRequest(endpoint: string, data: any): { endpoint: string; data: any };
  transformResponse(endpoint: string, data: any): any;
}

const adapters: Record<ApiVersion, VersionAdapter> = {
  v1: {
    baseUrl: 'https://api.getmaintainx.com/v1',
    transformRequest: (endpoint, data) => ({ endpoint, data }),
    transformResponse: (endpoint, data) => data,
  },
  v2: {
    baseUrl: 'https://api.getmaintainx.com/v2',
    transformRequest: (endpoint, data) => {
      // Handle breaking changes in v2
      if (endpoint.startsWith('/workorders') && data) {
        // Example: v2 renamed 'assignees' to 'assignedTo'
        if (data.assignees) {
          data.assignedTo = data.assignees;
          delete data.assignees;
        }
      }
      return { endpoint, data };
    },
    transformResponse: (endpoint, data) => {
      // Normalize v2 response to v1 shape
      if (data.assignedTo) {
        data.assignees = data.assignedTo;
      }
      return data;
    },
  },
};

class VersionedClient {
  private adapter: VersionAdapter;

  constructor(version: ApiVersion = 'v1') {
    this.adapter = adapters[version];
  }

  async request(method: string, endpoint: string, data?: any) {
    const { endpoint: ep, data: d } = this.adapter.transformRequest(endpoint, data);
    const response = await fetch(`${this.adapter.baseUrl}${ep}`, {
      method,
      headers: {
        Authorization: `Bearer ${process.env.MAINTAINX_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: d ? JSON.stringify(d) : undefined,
    });
    const result = await response.json();
    return this.adapter.transformResponse(ep, result);
  }
}
```

### Step 3: Feature Flag Migration

```typescript
// src/migration/feature-flags.ts

const MIGRATION_FLAGS: Record<string, boolean> = {
  USE_V2_WORKORDERS: false,   // Set to true when ready to switch
  USE_V2_ASSETS: false,
  USE_V2_PAGINATION: false,   // v2 might use offset instead of cursor
};

function getApiVersion(endpoint: string): ApiVersion {
  if (endpoint.startsWith('/workorders') && MIGRATION_FLAGS.USE_V2_WORKORDERS) return 'v2';
  if (endpoint.startsWith('/assets') && MIGRATION_FLAGS.USE_V2_ASSETS) return 'v2';
  return 'v1';
}

// Gradually roll out v2 per-endpoint
async function migratedRequest(method: string, endpoint: string, data?: any) {
  const version = getApiVersion(endpoint);
  const client = new VersionedClient(version);
  return client.request(method, endpoint, data);
}
```

### Step 4: Migration Tests

```typescript
// tests/migration.test.ts
import { describe, it, expect } from 'vitest';

describe('API Version Migration', () => {
  it('v1 and v2 return equivalent work order data', async () => {
    const v1Client = new VersionedClient('v1');
    const v2Client = new VersionedClient('v2');

    const v1Result = await v1Client.request('GET', '/workorders?limit=5');
    const v2Result = await v2Client.request('GET', '/workorders?limit=5');

    // After adapter normalization, shapes should match
    expect(v1Result.workOrders.length).toBe(v2Result.workOrders.length);
    expect(v1Result.workOrders[0]).toHaveProperty('id');
    expect(v1Result.workOrders[0]).

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.