post-api-sync 0.1.1

package/README.md

@@ -0,0 +1,110 @@
+# api-sync
+
+Sync your API code directly to Postman and Insomnia collections. 
+
+`api-sync` extracts endpoint definitions, parameters, and validation schemas (Zod, Class Validator) from your Hono, Express, or NestJS code and generates ready-to-use collections. It can also push changes directly to Postman Cloud.
+
+## Features
+
+- 🔍 **Auto-Extraction**: Scans your codebase for API routes and definitions.
+- 🛠 **Framework Support**: 
+  - **Hono**: Extract routes and `zValidator` schemas.
+  - **Express**: Extract routes and validation middleware.
+  - **NestJS**: Extract Controllers, DTOs, and `class-validator` decorators.
+- 📦 **Rich Collections**: Generates Postman and Insomnia collections with request bodies, query parameters, and examples.
+- ☁️ **Live Sync**: Push collections directly to the Postman Cloud API.
+- 👀 **Watch Mode**: Automatically sync changes as you code.
+
+## Installation
+
+```bash
+npm install -g api-sync
+# or use via npx
+npx api-sync --help
+```
+
+## Quick Start
+
+1.  **Initialize configuration**:
+    ```bash
+    npx api-sync init
+    ```
+    This will create an `api-sync.config.js` file in your project root.
+
+2.  **Run extraction**:
+    ```bash
+    npx api-sync sync
+    ```
+
+3.  **Watch for changes**:
+    ```bash
+    npx api-sync watch
+    ```
+
+## Configuration
+
+The `api-sync.config.js` file allows you to customize the tool's behavior:
+
+```javascript
+module.exports = {
+  // 'hono', 'express', 'nestjs', or 'auto'
+  framework: 'auto',
+
+  sources: {
+    // Glob patterns to include
+    include: ['src/**/*.ts', 'src/**/*.js'],
+    // Glob patterns to exclude
+    exclude: ['**/*.test.ts'],
+    // Base URL for variables in collections
+    baseUrl: 'http://localhost:3000'
+  },
+
+  output: {
+    postman: {
+      enabled: true,
+      outputPath: './postman_collection.json',
+      // Optional: Default API Key and Collection ID for Cloud Sync
+      apiKey: process.env.POSTMAN_API_KEY,
+      collectionId: process.env.POSTMAN_COLLECTION_ID
+    },
+    insomnia: {
+      enabled: true,
+      outputPath: './insomnia_collection.json'
+    }
+  }
+};
+```
+
+## Postman Cloud Sync
+
+You can push your generated collection directly to Postman without manual importing.
+
+1.  Get your **Postman API Key** from your [Account Settings](https://postman.co/settings/me/api-keys).
+2.  Get your **Collection UID** (Right-click collection -> Info).
+3.  Run the sync command:
+
+```bash
+npx api-sync sync --postman-key <YOUR_KEY> --postman-id <COLLECTION_UID>
+```
+
+Or set them in your config/environment variables to use with `watch` mode.
+
+## Supported Patterns
+
+### Hono
+- `zValidator('json', schema)` -> Request Body
+- `zValidator('query', schema)` -> Query Parameters
+
+### Express
+- Router methods: `router.get`, `router.post`, etc.
+- Validation middleware extraction (mapped to Zod schemas).
+
+### NestJS
+- `@Controller`, `@Get`, `@Post`, etc.
+- DTOs in `@Body()` and `@Query()`.
+- `class-validator` decorators: `@IsString`, `@IsInt`, `@Min`, etc.
+- `@ApiProperty({ example: ... })` for example values.
+
+## License
+
+MIT

package/bin/api-sync.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { initConfig } = require('../src/init');
+const { syncOnce } = require('../src/sync');
+const { watchMode } = require('../src/watch');
+
+program
+  .name('api-sync')
+  .description('Sync Postman and Insomnia collections from API code');
+
+program
+  .command('init')
+  .description('Create api-sync.config.js')
+  .option('--cwd <path>', 'Project root for config')
+  .action(async (opts) => {
+    await initConfig({ baseDir: opts.cwd });
+  });
+
+program
+  .command('sync')
+  .description('One-time collection sync')
+  .option('-c, --config <path>', 'Path to config file OR project directory')
+  .option('--cwd <path>', 'Project root (used for config + globs)')
+  .option('--postman-key <key>', 'Postman API Key')
+  .option('--postman-id <id>', 'Postman Collection UID')
+  .action(async (opts) => {
+    await syncOnce({
+      configPath: opts.config,
+      baseDir: opts.cwd,
+      postmanKey: opts.postmanKey,
+      postmanId: opts.postmanId
+    });
+  });
+
+program
+  .command('watch')
+  .description('Watch for changes and sync collections')
+  .option('-c, --config <path>', 'Path to config file OR project directory')
+  .option('--cwd <path>', 'Project root (used for config + globs)')
+  .option('--postman-key <key>', 'Postman API Key')
+  .option('--postman-id <id>', 'Postman Collection UID')
+  .action(async (opts) => {
+    await watchMode({
+      configPath: opts.config,
+      baseDir: opts.cwd,
+      postmanKey: opts.postmanKey,
+      postmanId: opts.postmanId
+    });
+  });
+
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "post-api-sync",
+  "version": "0.1.1",
+  "description": "Sync Postman and Insomnia collections from API code",
+  "type": "commonjs",
+  "bin": {
+    "api-sync": "bin/api-sync.js"
+  },
+  "scripts": {
+    "sync": "node bin/api-sync.js sync",
+    "watch": "node bin/api-sync.js watch",
+    "init": "node bin/api-sync.js init"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.24.0",
+    "@babel/traverse": "^7.24.0",
+    "chokidar": "^3.6.0",
+    "commander": "^12.0.0",
+    "fast-glob": "^3.3.2",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.0",
+    "kleur": "^4.1.5",
+    "nanoid": "^5.0.7"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "api",
+    "sync",
+    "postman",
+    "insomnia",
+    "hono",
+    "express",
+    "nestjs",
+    "documentation",
+    "automation"
+  ],
+  "author": "",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "license": "MIT"
+}

package/src/collection/insomnia.js

@@ -0,0 +1,81 @@
+const { nanoid } = require('nanoid');
+
+function buildInsomniaCollection(endpoints, config) {
+  const baseUrl = config.sources.baseUrl || 'http://localhost:3000';
+  const workspaceId = `wrk_${nanoid(10)}`;
+  const envId = `env_${nanoid(10)}`;
+
+  const resources = [
+    {
+      _id: workspaceId,
+      _type: 'workspace',
+      name: (config.output && config.output.insomnia && config.output.insomnia.workspaceName) || 'API Workspace'
+    },
+    {
+      _id: envId,
+      _type: 'environment',
+      parentId: workspaceId,
+      name: 'Base Environment',
+      data: { baseUrl }
+    }
+  ];
+
+  for (const endpoint of endpoints) {
+    resources.push(buildRequest(endpoint, workspaceId));
+  }
+
+  return {
+    _type: 'export',
+    __export_format: 4,
+    __export_date: new Date().toISOString(),
+    __export_source: 'api-sync',
+    resources
+  };
+}
+
+function buildRequest(endpoint, workspaceId) {
+  const bodySchema = endpoint.parameters && endpoint.parameters.body ? endpoint.parameters.body : null;
+  const hasBody = !!bodySchema;
+  const example = hasBody ? exampleFromSchema(bodySchema) : null;
+
+  return {
+    _id: `req_${nanoid(10)}`,
+    _type: 'request',
+    parentId: workspaceId,
+    name: endpoint.description || `${endpoint.method} ${endpoint.path}`,
+    method: endpoint.method,
+    url: `{{ _.baseUrl }}${endpoint.path}`,
+    headers: hasBody ? [{ name: 'Content-Type', value: 'application/json' }] : [],
+    parameters: (endpoint.parameters && endpoint.parameters.query || []).map(q => ({
+      name: q.name,
+      value: '',
+      disabled: !q.required
+    })),
+    body: hasBody
+      ? {
+        mimeType: 'application/json',
+        text: JSON.stringify(example || {}, null, 2)
+      }
+      : {}
+  };
+}
+
+function exampleFromSchema(schema, depth = 0) {
+  if (!schema || depth > 3) return {};
+  if (schema.example !== undefined) return schema.example;
+  if (schema.type === 'string') return '';
+  if (schema.type === 'number') return 0;
+  if (schema.type === 'boolean') return false;
+  if (schema.type === 'array') return [exampleFromSchema(schema.items || {}, depth + 1)];
+  if (schema.type === 'object') {
+    const obj = {};
+    const props = schema.properties || {};
+    for (const key of Object.keys(props)) {
+      obj[key] = exampleFromSchema(props[key], depth + 1);
+    }
+    return obj;
+  }
+  return {};
+}
+
+module.exports = { buildInsomniaCollection };

package/src/collection/postman.js

@@ -0,0 +1,88 @@
+const { nanoid } = require('nanoid');
+const { toPostmanPath, splitPath, extractPathParams } = require('../utils');
+
+function buildPostmanCollection(endpoints, config) {
+  const name = (config.output && config.output.postman && config.output.postman.collectionName) || 'API Collection';
+  const baseUrl = config.sources.baseUrl || 'http://localhost:3000';
+  const groupBy = (config.organization && config.organization.groupBy) || 'tags';
+
+  const items = groupBy === 'tags' ? buildTaggedItems(endpoints) : endpoints.map(buildItem);
+
+  return {
+    info: {
+      name,
+      schema: 'https://schema.getpostman.com/json/collection/v2.1.0/collection.json',
+      _postman_id: nanoid()
+    },
+    item: items,
+    variable: [{ key: 'baseUrl', value: baseUrl }]
+  };
+}
+
+function buildTaggedItems(endpoints) {
+  const groups = new Map();
+  for (const endpoint of endpoints) {
+    const tags = endpoint.tags && endpoint.tags.length ? endpoint.tags : ['General'];
+    const tag = tags[0];
+    if (!groups.has(tag)) groups.set(tag, []);
+    groups.get(tag).push(buildItem(endpoint));
+  }
+  const items = [];
+  for (const [name, groupItems] of groups.entries()) {
+    items.push({ name, item: groupItems });
+  }
+  return items;
+}
+
+function buildItem(endpoint) {
+  const path = toPostmanPath(endpoint.path);
+  const pathParams = extractPathParams(path);
+  const queryParams = (endpoint.parameters && endpoint.parameters.query) || [];
+  const bodySchema = endpoint.parameters && endpoint.parameters.body ? endpoint.parameters.body : null;
+  const hasBody = !!bodySchema;
+
+  const example = hasBody ? exampleFromSchema(bodySchema) : null;
+
+  return {
+    name: endpoint.description || `${endpoint.method} ${endpoint.path}`,
+    request: {
+      method: endpoint.method,
+      header: hasBody ? [{ key: 'Content-Type', value: 'application/json' }] : [],
+      url: {
+        raw: `{{baseUrl}}${path}`,
+        host: ['{{baseUrl}}'],
+        path: splitPath(path),
+        query: queryParams.map((q) => ({ key: q.name, value: '', disabled: !q.required })),
+        variable: pathParams.map((p) => ({ key: p, value: '' }))
+      },
+      body: hasBody
+        ? {
+            mode: 'raw',
+            raw: JSON.stringify(example || {}, null, 2),
+            options: { raw: { language: 'json' } }
+          }
+        : undefined
+    },
+    response: []
+  };
+}
+
+function exampleFromSchema(schema, depth = 0) {
+  if (!schema || depth > 3) return {};
+  if (schema.example !== undefined) return schema.example;
+  if (schema.type === 'string') return '';
+  if (schema.type === 'number') return 0;
+  if (schema.type === 'boolean') return false;
+  if (schema.type === 'array') return [exampleFromSchema(schema.items || {}, depth + 1)];
+  if (schema.type === 'object') {
+    const obj = {};
+    const props = schema.properties || {};
+    for (const key of Object.keys(props)) {
+      obj[key] = exampleFromSchema(props[key], depth + 1);
+    }
+    return obj;
+  }
+  return {};
+}
+
+module.exports = { buildPostmanCollection };

package/src/config.js

@@ -0,0 +1,141 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const ALWAYS_EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/*.d.ts'];
+
+const DEFAULT_CONFIG = {
+  framework: 'auto',
+  sources: {
+    include: ['src/**/*.{ts,js,tsx,jsx}'],
+    exclude: ['**/*.spec.ts', '**/*.test.ts', 'node_modules/**', 'dist/**', 'build/**'],
+    baseUrl: 'http://localhost:3000'
+  },
+  output: {
+    postman: {
+      enabled: true,
+      outputPath: './collections/postman-collection.json'
+    },
+    insomnia: {
+      enabled: true,
+      outputPath: './collections/insomnia-collection.json'
+    }
+  },
+  watch: {
+    enabled: true,
+    debounce: 300
+  },
+  merge: {
+    markDeprecated: true
+  },
+  organization: {
+    groupBy: 'tags'
+  }
+};
+
+async function resolveConfigPath(configPath, baseDir) {
+  let cwd = baseDir ? path.resolve(baseDir) : process.cwd();
+
+  if (configPath) {
+    const abs = path.isAbsolute(configPath) ? configPath : path.resolve(cwd, configPath);
+    if (await fs.pathExists(abs)) {
+      const stat = await fs.stat(abs);
+      if (stat.isDirectory()) {
+        cwd = abs;
+        return { path: path.resolve(cwd, 'api-sync.config.js'), baseDir: cwd };
+      }
+      return { path: abs, baseDir: path.dirname(abs) };
+    }
+    if (!path.extname(abs)) {
+      cwd = abs;
+      return { path: path.resolve(cwd, 'api-sync.config.js'), baseDir: cwd };
+    }
+    return { path: abs, baseDir: cwd };
+  }
+
+  return { path: path.resolve(cwd, 'api-sync.config.js'), baseDir: cwd };
+}
+
+async function loadConfig(configPath, baseDir) {
+  const resolved = await resolveConfigPath(configPath, baseDir);
+  if (await fs.pathExists(resolved.path)) {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    const userConfig = require(resolved.path);
+    return { config: mergeDeep(DEFAULT_CONFIG, userConfig), path: resolved.path, baseDir: resolved.baseDir };
+  }
+  return { config: DEFAULT_CONFIG, path: resolved.path, baseDir: resolved.baseDir };
+}
+
+function mergeDeep(base, override) {
+  if (Array.isArray(base) || Array.isArray(override)) {
+    return override === undefined ? base : override;
+  }
+  if (typeof base === 'object' && base && typeof override === 'object' && override) {
+    const out = { ...base };
+    for (const key of Object.keys(override)) {
+      out[key] = mergeDeep(base[key], override[key]);
+    }
+    return out;
+  }
+  return override === undefined ? base : override;
+}
+
+function ensureAbsolute(pathLike, baseDir) {
+  if (!pathLike) return pathLike;
+  if (path.isAbsolute(pathLike)) return pathLike;
+  const cwd = baseDir ? path.resolve(baseDir) : process.cwd();
+  return path.resolve(cwd, pathLike);
+}
+
+const GLOB_CHARS = /[*?[\]{}!]/;
+
+function looksLikeGlob(pattern) {
+  return GLOB_CHARS.test(pattern);
+}
+
+function normalizePattern(entry, baseDir, isInclude) {
+  if (!entry) return [];
+  const trimmed = entry.trim();
+  if (!trimmed) return [];
+
+  if (looksLikeGlob(trimmed)) return [trimmed];
+
+  const cwd = baseDir ? path.resolve(baseDir) : process.cwd();
+  const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+
+  if (fs.existsSync(abs)) {
+    const stat = fs.statSync(abs);
+    if (stat.isDirectory()) {
+      return [path.join(trimmed, isInclude ? '**/*.{ts,js,tsx,jsx}' : '**')];
+    }
+    return [trimmed];
+  }
+
+  // Treat bare extensions like "ts" or ".ts"
+  if (!trimmed.includes('/') && !trimmed.includes('\\')) {
+    const ext = trimmed.startsWith('.') ? trimmed.slice(1) : trimmed;
+    if (ext) return [isInclude ? `**/*.${ext}` : `**/*.${ext}`];
+  }
+
+  return [trimmed];
+}
+
+function normalizeIncludePatterns(patterns, baseDir) {
+  const list = Array.isArray(patterns) ? patterns : [patterns];
+  return list.flatMap((p) => normalizePattern(p, baseDir, true));
+}
+
+function normalizeExcludePatterns(patterns, baseDir) {
+  const list = Array.isArray(patterns) ? patterns : [patterns];
+  const normalized = list.flatMap((p) => normalizePattern(p, baseDir, false));
+  return Array.from(new Set([...normalized, ...ALWAYS_EXCLUDE]));
+}
+
+module.exports = {
+  DEFAULT_CONFIG,
+  resolveConfigPath,
+  loadConfig,
+  ensureAbsolute,
+  normalizeIncludePatterns,
+  normalizeExcludePatterns,
+  ALWAYS_EXCLUDE
+};

package/src/extract/ast.js

@@ -0,0 +1,32 @@
+const fs = require('fs-extra');
+const parser = require('@babel/parser');
+
+async function parseFile(filePath) {
+  const code = await fs.readFile(filePath, 'utf8');
+  const base = {
+    sourceType: 'module',
+    plugins: [
+      'typescript',
+      'classProperties',
+      'classPrivateProperties',
+      'classPrivateMethods',
+      'jsx',
+      'dynamicImport'
+    ]
+  };
+
+  try {
+    return parser.parse(code, {
+      ...base,
+      plugins: ['decorators-legacy', ...base.plugins]
+    });
+  } catch (err) {
+    // Fallback to stage-3 decorators if legacy parsing fails
+    return parser.parse(code, {
+      ...base,
+      plugins: [['decorators', { decoratorsBeforeExport: true }], ...base.plugins]
+    });
+  }
+}
+
+module.exports = { parseFile };