@codewithagents/openapi-react-query 0.1.0

package/src/__tests__/config.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { loadConfig, validateConfigPath, validateOutputPath, validateInputPath } from '../config.js'
+
+describe('loadConfig', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'openapi-react-query-config-'))
+  })
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  function writeConfig(content: unknown) {
+    writeFileSync(join(tmpDir, 'openapi-react-query.config.json'), JSON.stringify(content))
+  }
+
+  it('loads a valid minimal config', async () => {
+    writeConfig({ input_openapi: 'openapi.json', output: 'src/hooks' })
+    const config = await loadConfig(tmpDir)
+    expect(config.input_openapi).toBe('openapi.json')
+    expect(config.output).toBe('src/hooks')
+    expect(config.stale_time).toBeUndefined()
+    expect(config.gc_time).toBeUndefined()
+  })
+
+  it('loads a full config with all fields', async () => {
+    writeConfig({
+      input_openapi: 'api/openapi.json',
+      output: 'src/generated',
+      stale_time: 5000,
+      gc_time: 600000,
+    })
+    const config = await loadConfig(tmpDir)
+    expect(config.input_openapi).toBe('api/openapi.json')
+    expect(config.output).toBe('src/generated')
+    expect(config.stale_time).toBe(5000)
+    expect(config.gc_time).toBe(600000)
+  })
+
+  it('throws when config file is missing', async () => {
+    await expect(loadConfig(tmpDir)).rejects.toThrow('Config file not found')
+  })
+
+  it('throws when config is not valid JSON', async () => {
+    writeFileSync(join(tmpDir, 'openapi-react-query.config.json'), 'not json {{{')
+    await expect(loadConfig(tmpDir)).rejects.toThrow('not valid JSON')
+  })
+
+  it('throws when config is not an object', async () => {
+    writeFileSync(join(tmpDir, 'openapi-react-query.config.json'), '"just a string"')
+    await expect(loadConfig(tmpDir)).rejects.toThrow('JSON object')
+  })
+
+  it('throws when input_openapi is missing', async () => {
+    writeConfig({ output: 'src/hooks' })
+    await expect(loadConfig(tmpDir)).rejects.toThrow('input_openapi')
+  })
+
+  it('throws when output is missing', async () => {
+    writeConfig({ input_openapi: 'openapi.json' })
+    await expect(loadConfig(tmpDir)).rejects.toThrow('output')
+  })
+
+  it('throws when stale_time is not a number', async () => {
+    writeConfig({ input_openapi: 'openapi.json', output: 'src/hooks', stale_time: 'fast' })
+    await expect(loadConfig(tmpDir)).rejects.toThrow('stale_time')
+  })
+
+  it('throws when gc_time is not a number', async () => {
+    writeConfig({ input_openapi: 'openapi.json', output: 'src/hooks', gc_time: true })
+    await expect(loadConfig(tmpDir)).rejects.toThrow('gc_time')
+  })
+
+  it('ignores unknown config fields', async () => {
+    writeConfig({ input_openapi: 'openapi.json', output: 'src/hooks', unknown_field: 'ignored' })
+    const config = await loadConfig(tmpDir)
+    expect(config.input_openapi).toBe('openapi.json')
+  })
+
+  it('accepts a config loaded via explicit configPath', async () => {
+    const configFile = join(tmpDir, 'custom.config.json')
+    writeFileSync(configFile, JSON.stringify({ input_openapi: 'openapi.json', output: 'src/hooks' }))
+    const config = await loadConfig(tmpDir, configFile)
+    expect(config.input_openapi).toBe('openapi.json')
+    expect(config.output).toBe('src/hooks')
+  })
+
+  it('rejects explicit configPath that is not .json', async () => {
+    const configFile = join(tmpDir, 'config.ts')
+    writeFileSync(configFile, JSON.stringify({ input_openapi: 'openapi.json', output: 'src/hooks' }))
+    await expect(loadConfig(tmpDir, configFile)).rejects.toThrow('Config file must be a .json file')
+  })
+})
+
+describe('config security validation', () => {
+  describe('validateConfigPath', () => {
+    it('rejects non-.json config file extension', () => {
+      expect(() => validateConfigPath('/project/config.ts')).toThrow('Config file must be a .json file')
+    })
+
+    it('rejects .yaml extension', () => {
+      expect(() => validateConfigPath('/project/config.yaml')).toThrow('Config file must be a .json file')
+    })
+
+    it('accepts .json extension', () => {
+      expect(() => validateConfigPath('/project/config.json')).not.toThrow()
+    })
+
+    it('accepts nested .json path', () => {
+      expect(() => validateConfigPath('/Users/someone/project/my-tool.config.json')).not.toThrow()
+    })
+  })
+
+  describe('validateOutputPath', () => {
+    it('rejects output path in /etc', () => {
+      expect(() => validateOutputPath('/etc/generated')).toThrow('system directory')
+    })
+
+    it('rejects output path in /usr', () => {
+      expect(() => validateOutputPath('/usr/local/generated')).toThrow('system directory')
+    })
+
+    it('rejects output path in /bin', () => {
+      expect(() => validateOutputPath('/bin/generated')).toThrow('system directory')
+    })
+
+    it('rejects output path in /sys', () => {
+      expect(() => validateOutputPath('/sys/something')).toThrow('system directory')
+    })
+
+    it('rejects output path in /proc', () => {
+      expect(() => validateOutputPath('/proc/1/generated')).toThrow('system directory')
+    })
+
+    it('rejects output path in /dev', () => {
+      expect(() => validateOutputPath('/dev/null')).toThrow('system directory')
+    })
+
+    it('rejects output path in /boot', () => {
+      expect(() => validateOutputPath('/boot/generated')).toThrow('system directory')
+    })
+
+    it('accepts normal project-relative resolved path', () => {
+      expect(() => validateOutputPath('/Users/someone/project/generated')).not.toThrow()
+    })
+
+    it('accepts absolute path within home directory', () => {
+      expect(() => validateOutputPath('/Users/someone/myproject/src/hooks')).not.toThrow()
+    })
+
+    it('accepts dist/api style path', () => {
+      expect(() => validateOutputPath('/home/user/project/dist/hooks')).not.toThrow()
+    })
+  })
+
+  describe('validateInputPath', () => {
+    it('rejects input spec from /proc', () => {
+      expect(() => validateInputPath('/proc/1/fd/0')).toThrow('system directory')
+    })
+
+    it('rejects input spec from /etc', () => {
+      expect(() => validateInputPath('/etc/passwd')).toThrow('system directory')
+    })
+
+    it('rejects input spec from /dev', () => {
+      expect(() => validateInputPath('/dev/random')).toThrow('system directory')
+    })
+
+    it('rejects input spec from /usr', () => {
+      expect(() => validateInputPath('/usr/share/openapi.json')).toThrow('system directory')
+    })
+
+    it('accepts input spec in home directory', () => {
+      expect(() => validateInputPath('/Users/someone/project/openapi.json')).not.toThrow()
+    })
+
+    it('accepts input spec in /tmp', () => {
+      expect(() => validateInputPath('/tmp/openapi.json')).not.toThrow()
+    })
+  })
+})

package/src/__tests__/hooks.test.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { OpenAPIV3_1 } from 'openapi-types'
+import { generateHooks } from '../plugins/hooks.js'
+
+// Load fixture directly (no parseSpec — avoids needing openapi-gen dist built)
+const fixturePath = join(import.meta.dirname, '../../__fixtures__/specs/task-hooks.json')
+const spec = JSON.parse(readFileSync(fixturePath, 'utf-8')) as OpenAPIV3_1.Document
+
+const { filename, content } = generateHooks(spec, { staleTime: 30_000, gcTime: 300_000 })
+
+describe('generateHooks — task-hooks.json fixture', () => {
+  it('filename is hooks.ts', () => {
+    expect(filename).toBe('hooks.ts')
+  })
+
+  it('contains auto-generated header comment', () => {
+    expect(content).toContain(
+      '// This file is auto-generated by @codewithagents/openapi-react-query — do not edit',
+    )
+  })
+
+  it('imports useQuery and useMutation from @tanstack/react-query', () => {
+    expect(content).toContain("from '@tanstack/react-query'")
+    expect(content).toContain('useQuery')
+    expect(content).toContain('useMutation')
+  })
+
+  it('imports all client functions and ApiError from ./client.js', () => {
+    expect(content).toContain("from './client.js'")
+    expect(content).toContain('listTasks')
+    expect(content).toContain('getTask')
+    expect(content).toContain('createTask')
+    expect(content).toContain('updateTask')
+    expect(content).toContain('deleteTask')
+    expect(content).toContain('type ApiError')
+  })
+
+  it('generates taskKeys factory with all(), list(), and detail() entries', () => {
+    expect(content).toContain('export const taskKeys')
+    expect(content).toContain("all: () => ['tasks'] as const")
+    expect(content).toContain("list:")
+    expect(content).toContain("detail:")
+  })
+
+  it('useListTasks uses taskKeys.list(params) as queryKey', () => {
+    expect(content).toContain('useListTasks')
+    expect(content).toContain('queryKey: taskKeys.list(params)')
+  })
+
+  it('useListTasks has staleTime: 30_000', () => {
+    expect(content).toContain('staleTime: 30000,')
+  })
+
+  it('useListTasks has gcTime: 300_000', () => {
+    expect(content).toContain('gcTime: 300000,')
+  })
+
+  it('useGetTask accepts id as positional arg and uses taskKeys.detail(id)', () => {
+    expect(content).toContain('useGetTask')
+    expect(content).toContain('id: string')
+    expect(content).toContain('queryKey: taskKeys.detail(id)')
+  })
+
+  it('useCreateTask variables type is Parameters<typeof createTask>[0]', () => {
+    expect(content).toContain('useCreateTask')
+    expect(content).toContain('Parameters<typeof createTask>[0]')
+  })
+
+  it('useUpdateTask variables type has { id: string; body: Parameters<typeof updateTask>[1] }', () => {
+    expect(content).toContain('useUpdateTask')
+    expect(content).toContain('{ id: string; body: Parameters<typeof updateTask>[1] }')
+  })
+
+  it('useUpdateTask mutationFn destructures { id, body }', () => {
+    expect(content).toContain('({ id, body }) => updateTask(id, body)')
+  })
+
+  it('useDeleteTask variables type is string', () => {
+    // deleteTask has one path param and no body → variables type is string
+    expect(content).toContain('useDeleteTask')
+    // The mutation signature should include 'string' as variables type for deleteTask
+    // We check that the mutationFn destructures id directly
+    expect(content).toContain('(id) => deleteTask(id)')
+  })
+
+  it('useDeleteTask mutationFn is (id) => deleteTask(id)', () => {
+    expect(content).toContain('mutationFn: (id) => deleteTask(id)')
+  })
+
+  it('staleTime and gcTime are overridable via options spread', () => {
+    // ...options must appear AFTER staleTime and gcTime in the useQuery call
+    const staleTimeIdx = content.indexOf('staleTime: 30000,')
+    const gcTimeIdx = content.indexOf('gcTime: 300000,')
+    const spreadIdx = content.indexOf('...options,', gcTimeIdx)
+    expect(staleTimeIdx).toBeGreaterThan(-1)
+    expect(gcTimeIdx).toBeGreaterThan(staleTimeIdx)
+    expect(spreadIdx).toBeGreaterThan(gcTimeIdx)
+  })
+})

package/src/cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { resolve, dirname } from 'node:path'
+import { generate } from './generator.js'
+
+const args = process.argv.slice(2)
+const configIdx = args.indexOf('--config')
+
+let cwd = process.cwd()
+let configFile: string | undefined
+
+if (configIdx !== -1) {
+  const next = args[configIdx + 1]
+  if (next === undefined || next.startsWith('--')) {
+    console.error('Error: --config requires a file path argument')
+    console.error('Usage: openapi-react-query [--config <path-to-config.json>]')
+    process.exit(1)
+  }
+  configFile = resolve(cwd, next)
+  // Relative paths inside the config resolve from the config file's directory,
+  // not from the shell's CWD. This matches how most tooling works.
+  cwd = dirname(configFile)
+}
+
+generate(cwd, configFile).catch((err: Error) => {
+  console.error(`Error: ${err.message}`)
+  process.exit(1)
+})

package/src/config.ts

@@ -0,0 +1,111 @@
+import { readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+export interface ReactQueryConfig {
+  /** Path to OpenAPI 3.1 spec file (JSON or YAML) */
+  input_openapi: string
+  /** Directory to write generated files */
+  output: string
+  /** staleTime in ms for all useQuery hooks (default: 0) */
+  stale_time?: number
+  /** gcTime in ms for all useQuery hooks (default: 300000) */
+  gc_time?: number
+}
+
+const FORBIDDEN_OUTPUT_PREFIXES = [
+  '/etc', '/usr', '/bin', '/sbin', '/lib', '/lib64',
+  '/sys', '/proc', '/dev', '/boot', '/run',
+  'C:\\Windows', 'C:\\Program Files',
+]
+
+const FORBIDDEN_INPUT_PREFIXES = [
+  '/etc', '/usr', '/bin', '/sbin', '/lib', '/lib64',
+  '/sys', '/proc', '/dev',
+  'C:\\Windows', 'C:\\Program Files',
+]
+
+export function validateConfigPath(configPath: string): void {
+  // Must end in .json — prevents accidentally loading non-config files
+  if (!configPath.endsWith('.json')) {
+    throw new Error(`Config file must be a .json file, got: ${configPath}`)
+  }
+}
+
+export function validateOutputPath(resolvedOutput: string): void {
+  const normalized = resolvedOutput.replace(/\\/g, '/')
+  for (const forbidden of FORBIDDEN_OUTPUT_PREFIXES) {
+    if (normalized.startsWith(forbidden.replace(/\\/g, '/'))) {
+      throw new Error(
+        `Output path resolves to a system directory: "${resolvedOutput}". ` +
+        `This looks like a misconfiguration — please check your config file.`
+      )
+    }
+  }
+}
+
+export function validateInputPath(resolvedInput: string): void {
+  const normalized = resolvedInput.replace(/\\/g, '/')
+  for (const forbidden of FORBIDDEN_INPUT_PREFIXES) {
+    if (normalized.startsWith(forbidden.replace(/\\/g, '/'))) {
+      throw new Error(
+        `Input spec path resolves to a system directory: "${resolvedInput}". ` +
+        `This looks like a misconfiguration — please check your config file.`
+      )
+    }
+  }
+}
+
+export async function loadConfig(cwd: string, configPath?: string): Promise<ReactQueryConfig> {
+  const resolvedConfigPath = configPath ?? join(cwd, 'openapi-react-query.config.json')
+
+  // Security: validate config path extension when explicitly provided
+  if (configPath !== undefined) {
+    validateConfigPath(configPath)
+  }
+
+  let raw: string
+  try {
+    raw = await readFile(resolvedConfigPath, 'utf-8')
+  } catch {
+    throw new Error(`Config file not found: ${resolvedConfigPath}`)
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error(`Config file is not valid JSON: ${resolvedConfigPath}`)
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw new Error('Config must be a JSON object')
+  }
+
+  const config = parsed as Record<string, unknown>
+
+  if (typeof config['input_openapi'] !== 'string' || !config['input_openapi']) {
+    throw new Error('Config missing required field: "input_openapi" (path to OpenAPI 3.1 spec)')
+  }
+  if (typeof config['output'] !== 'string' || !config['output']) {
+    throw new Error('Config missing required field: "output" (output directory)')
+  }
+  if (config['stale_time'] !== undefined && typeof config['stale_time'] !== 'number') {
+    throw new Error('"stale_time" must be a number (milliseconds)')
+  }
+  if (config['gc_time'] !== undefined && typeof config['gc_time'] !== 'number') {
+    throw new Error('"gc_time" must be a number (milliseconds)')
+  }
+
+  // Security: validate resolved input and output paths
+  const resolvedInput = resolve(cwd, config['input_openapi'] as string)
+  const resolvedOutput = resolve(cwd, config['output'] as string)
+  validateInputPath(resolvedInput)
+  validateOutputPath(resolvedOutput)
+
+  return {
+    input_openapi: config['input_openapi'] as string,
+    output: config['output'] as string,
+    stale_time: config['stale_time'] as number | undefined,
+    gc_time: config['gc_time'] as number | undefined,
+  }
+}

package/src/generator.ts

@@ -0,0 +1,20 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { parseSpec } from '@codewithagents/openapi-gen'
+import { loadConfig } from './config.js'
+import { generateHooks } from './plugins/hooks.js'
+
+export async function generate(cwd: string, configPath?: string): Promise<void> {
+  const config = await loadConfig(cwd, configPath)
+  const inputPath = resolve(cwd, config.input_openapi)
+  const outputDir = resolve(cwd, config.output)
+  const spec = await parseSpec(inputPath)
+  const file = generateHooks(spec, {
+    staleTime: config.stale_time ?? 0,
+    gcTime: config.gc_time ?? 300_000,
+  })
+  await mkdir(outputDir, { recursive: true })
+  const filePath = join(outputDir, file.filename)
+  await writeFile(filePath, file.content, 'utf-8')
+  console.log(`✓ ${file.filename}`)
+}