cli4ai 0.8.0

package/src/core/manifest.test.ts

@@ -0,0 +1,327 @@
+/**
+ * Tests for manifest.ts
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import {
+  validateManifest,
+  loadManifestOrThrow,
+  tryLoadManifest,
+  findManifest,
+  createManifest,
+  MANIFEST_FILENAME,
+  ManifestValidationError,
+  ManifestNotFoundError,
+  ManifestParseError
+} from './manifest.js';
+
+describe('manifest', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'cli4ai-manifest-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('validateManifest', () => {
+    test('accepts valid minimal manifest', () => {
+      const manifest = validateManifest({
+        name: 'my-tool',
+        version: '1.0.0',
+        entry: 'run.ts'
+      });
+
+      expect(manifest.name).toBe('my-tool');
+      expect(manifest.version).toBe('1.0.0');
+      expect(manifest.entry).toBe('run.ts');
+    });
+
+    test('accepts valid full manifest', () => {
+      const manifest = validateManifest({
+        name: 'github',
+        version: '2.1.0',
+        entry: 'run.ts',
+        description: 'GitHub CLI wrapper',
+        author: 'cliforai',
+        license: 'MIT',
+        runtime: 'bun',
+        commands: {
+          notifs: { description: 'Your notifications' },
+          repos: {
+            description: 'List repos',
+            args: [{ name: 'user', required: false }]
+          }
+        },
+        env: {
+          GITHUB_TOKEN: { required: false, description: 'Token' }
+        },
+        mcp: { enabled: true }
+      });
+
+      expect(manifest.name).toBe('github');
+      expect(manifest.commands?.notifs.description).toBe('Your notifications');
+      expect(manifest.mcp?.enabled).toBe(true);
+    });
+
+    test('accepts prerelease versions', () => {
+      const manifest = validateManifest({
+        name: 'tool',
+        version: '1.0.0-beta.1',
+        entry: 'run.ts'
+      });
+
+      expect(manifest.version).toBe('1.0.0-beta.1');
+    });
+
+    test('accepts all valid runtimes', () => {
+      for (const runtime of ['bun', 'node'] as const) {
+        const manifest = validateManifest({
+          name: 'tool',
+          version: '1.0.0',
+          entry: 'run.ts',
+          runtime
+        });
+        expect(manifest.runtime).toBe(runtime);
+      }
+    });
+
+    test('rejects null manifest', () => {
+      expect(() => validateManifest(null)).toThrow();
+    });
+
+    test('rejects non-object manifest', () => {
+      expect(() => validateManifest('string')).toThrow();
+      expect(() => validateManifest(123)).toThrow();
+      expect(() => validateManifest([])).toThrow();
+    });
+
+    test('rejects missing name', () => {
+      expect(() => validateManifest({
+        version: '1.0.0',
+        entry: 'run.ts'
+      })).toThrow();
+    });
+
+    test('rejects invalid name format', () => {
+      expect(() => validateManifest({
+        name: 'Invalid-Name',
+        version: '1.0.0',
+        entry: 'run.ts'
+      })).toThrow();
+
+      expect(() => validateManifest({
+        name: '123invalid',
+        version: '1.0.0',
+        entry: 'run.ts'
+      })).toThrow();
+
+      expect(() => validateManifest({
+        name: 'has_underscore',
+        version: '1.0.0',
+        entry: 'run.ts'
+      })).toThrow();
+    });
+
+    test('rejects missing version', () => {
+      expect(() => validateManifest({
+        name: 'tool',
+        entry: 'run.ts'
+      })).toThrow();
+    });
+
+    test('rejects invalid version format', () => {
+      expect(() => validateManifest({
+        name: 'tool',
+        version: 'invalid',
+        entry: 'run.ts'
+      })).toThrow();
+
+      expect(() => validateManifest({
+        name: 'tool',
+        version: '1.0',
+        entry: 'run.ts'
+      })).toThrow();
+    });
+
+    test('rejects missing entry', () => {
+      expect(() => validateManifest({
+        name: 'tool',
+        version: '1.0.0'
+      })).toThrow();
+    });
+
+    test('rejects empty entry', () => {
+      expect(() => validateManifest({
+        name: 'tool',
+        version: '1.0.0',
+        entry: ''
+      })).toThrow();
+    });
+
+    test('rejects invalid runtime', () => {
+      expect(() => validateManifest({
+        name: 'tool',
+        version: '1.0.0',
+        entry: 'run.ts',
+        runtime: 'python'
+      })).toThrow();
+    });
+
+    test('rejects commands without description', () => {
+      expect(() => validateManifest({
+        name: 'tool',
+        version: '1.0.0',
+        entry: 'run.ts',
+        commands: {
+          mycommand: {}
+        }
+      })).toThrow();
+    });
+  });
+
+  describe('loadManifestOrThrow', () => {
+    test('loads valid manifest from directory', () => {
+      writeFileSync(
+        join(tempDir, MANIFEST_FILENAME),
+        JSON.stringify({
+          name: 'test-tool',
+          version: '1.0.0',
+          entry: 'run.ts'
+        })
+      );
+
+      const manifest = loadManifestOrThrow(tempDir);
+      expect(manifest.name).toBe('test-tool');
+    });
+
+    test('throws ManifestNotFoundError when manifest not found', () => {
+      expect(() => loadManifestOrThrow(tempDir)).toThrow(ManifestNotFoundError);
+    });
+
+    test('throws ManifestParseError on invalid JSON', () => {
+      writeFileSync(join(tempDir, MANIFEST_FILENAME), 'not json');
+      expect(() => loadManifestOrThrow(tempDir)).toThrow(ManifestParseError);
+    });
+
+    test('throws ManifestValidationError on invalid manifest content', () => {
+      writeFileSync(
+        join(tempDir, MANIFEST_FILENAME),
+        JSON.stringify({ name: 'Invalid' }) // Missing version, entry
+      );
+      expect(() => loadManifestOrThrow(tempDir)).toThrow(ManifestValidationError);
+    });
+  });
+
+  describe('tryLoadManifest', () => {
+    test('returns manifest when valid', () => {
+      writeFileSync(
+        join(tempDir, MANIFEST_FILENAME),
+        JSON.stringify({
+          name: 'test-tool',
+          version: '1.0.0',
+          entry: 'run.ts'
+        })
+      );
+
+      const manifest = tryLoadManifest(tempDir);
+      expect(manifest).not.toBeNull();
+      expect(manifest?.name).toBe('test-tool');
+    });
+
+    test('returns null when not found', () => {
+      const manifest = tryLoadManifest(tempDir);
+      expect(manifest).toBeNull();
+    });
+
+    test('returns null on invalid JSON', () => {
+      writeFileSync(join(tempDir, MANIFEST_FILENAME), 'not json');
+      const manifest = tryLoadManifest(tempDir);
+      expect(manifest).toBeNull();
+    });
+
+    test('returns null on invalid manifest', () => {
+      writeFileSync(
+        join(tempDir, MANIFEST_FILENAME),
+        JSON.stringify({ name: 'Invalid' })
+      );
+      const manifest = tryLoadManifest(tempDir);
+      expect(manifest).toBeNull();
+    });
+  });
+
+  describe('findManifest', () => {
+    test('finds manifest in current directory', () => {
+      writeFileSync(
+        join(tempDir, MANIFEST_FILENAME),
+        JSON.stringify({
+          name: 'found-tool',
+          version: '1.0.0',
+          entry: 'run.ts'
+        })
+      );
+
+      const result = findManifest(tempDir);
+      expect(result).not.toBeNull();
+      expect(result?.manifest.name).toBe('found-tool');
+      expect(result?.dir).toBe(tempDir);
+    });
+
+    test('finds manifest in parent directory', () => {
+      const childDir = join(tempDir, 'child');
+      mkdirSync(childDir);
+
+      writeFileSync(
+        join(tempDir, MANIFEST_FILENAME),
+        JSON.stringify({
+          name: 'parent-tool',
+          version: '1.0.0',
+          entry: 'run.ts'
+        })
+      );
+
+      const result = findManifest(childDir);
+      expect(result).not.toBeNull();
+      expect(result?.manifest.name).toBe('parent-tool');
+      expect(result?.dir).toBe(tempDir);
+    });
+
+    test('returns null when no manifest found', () => {
+      const result = findManifest(tempDir);
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('createManifest', () => {
+    test('creates minimal manifest', () => {
+      const manifest = createManifest('my-tool');
+
+      expect(manifest.name).toBe('my-tool');
+      expect(manifest.version).toBe('1.0.0');
+      expect(manifest.entry).toBe('run.ts');
+      expect(manifest.runtime).toBe('bun');
+    });
+
+    test('normalizes name', () => {
+      const manifest = createManifest('My Tool Name');
+      expect(manifest.name).toBe('my-tool-name');
+    });
+
+    test('accepts options', () => {
+      const manifest = createManifest('tool', {
+        version: '2.0.0',
+        description: 'Custom description',
+        runtime: 'node'
+      });
+
+      expect(manifest.version).toBe('2.0.0');
+      expect(manifest.description).toBe('Custom description');
+      expect(manifest.runtime).toBe('node');
+    });
+  });
+});

package/src/core/manifest.ts

@@ -0,0 +1,319 @@
+/**
+ * cli4ai.json manifest validation and parsing
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname, basename } from 'path';
+import { outputError } from '../lib/cli.js';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ERRORS
+// ═══════════════════════════════════════════════════════════════════════════
+
+export class ManifestValidationError extends Error {
+  constructor(
+    message: string,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'ManifestValidationError';
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface CommandArg {
+  name: string;
+  description?: string;
+  required?: boolean;
+  type?: 'string' | 'number' | 'boolean';
+  default?: string | number | boolean;
+}
+
+export interface CommandOption {
+  name: string;
+  short?: string;
+  description?: string;
+  type?: 'string' | 'number' | 'boolean';
+  default?: string | number | boolean;
+}
+
+export interface CommandDef {
+  description: string;
+  args?: CommandArg[];
+  options?: CommandOption[];
+}
+
+export interface EnvDef {
+  required?: boolean;
+  description?: string;
+  default?: string;
+  secret?: boolean;
+}
+
+export interface McpConfig {
+  enabled?: boolean;
+  transport?: 'stdio' | 'http';
+  port?: number;
+}
+
+export interface Manifest {
+  // Required fields
+  name: string;
+  version: string;
+  entry: string;
+
+  // Optional metadata
+  description?: string;
+  author?: string;
+  license?: string;
+  repository?: string;
+  homepage?: string;
+  keywords?: string[];
+
+  // Runtime (bun or node only - deno not supported)
+  runtime?: 'bun' | 'node';
+
+  // Commands (for MCP generation)
+  commands?: Record<string, CommandDef>;
+
+  // Environment variables
+  env?: Record<string, EnvDef>;
+
+  // Dependencies
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+
+  // MCP configuration
+  mcp?: McpConfig;
+
+  // Scripts
+  scripts?: Record<string, string>;
+
+  // Files to include when publishing
+  files?: string[];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/;
+
+export function validateManifest(manifest: unknown, source?: string): Manifest {
+  if (!manifest || typeof manifest !== 'object') {
+    throw new ManifestValidationError('Manifest must be an object', { source });
+  }
+
+  const m = manifest as Record<string, unknown>;
+
+  // Required: name
+  if (typeof m.name !== 'string' || !NAME_PATTERN.test(m.name)) {
+    throw new ManifestValidationError('Invalid or missing "name" (lowercase letters, numbers, hyphens)', {
+      source,
+      got: m.name
+    });
+  }
+
+  // Required: version
+  if (typeof m.version !== 'string' || !VERSION_PATTERN.test(m.version)) {
+    throw new ManifestValidationError('Invalid or missing "version" (semver format: x.y.z)', {
+      source,
+      got: m.version
+    });
+  }
+
+  // Required: entry
+  if (typeof m.entry !== 'string' || m.entry.length === 0) {
+    throw new ManifestValidationError('Invalid or missing "entry" (path to main file)', {
+      source,
+      got: m.entry
+    });
+  }
+
+  // Optional: runtime (deno not supported)
+  if (m.runtime !== undefined && !['bun', 'node'].includes(m.runtime as string)) {
+    throw new ManifestValidationError('Invalid "runtime" (must be bun or node)', {
+      source,
+      got: m.runtime
+    });
+  }
+
+  // Optional: commands
+  if (m.commands !== undefined) {
+    if (typeof m.commands !== 'object' || m.commands === null) {
+      throw new ManifestValidationError('Invalid "commands" (must be an object)', { source });
+    }
+    for (const [cmdName, cmdDef] of Object.entries(m.commands as object)) {
+      if (typeof cmdDef !== 'object' || cmdDef === null) {
+        throw new ManifestValidationError(`Invalid command definition for "${cmdName}"`, { source });
+      }
+      const def = cmdDef as Record<string, unknown>;
+      if (typeof def.description !== 'string') {
+        throw new ManifestValidationError(`Command "${cmdName}" missing description`, { source });
+      }
+    }
+  }
+
+  return manifest as Manifest;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LOADING
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const MANIFEST_FILENAME = 'cli4ai.json';
+
+export class ManifestNotFoundError extends Error {
+  constructor(public path: string) {
+    super(`No ${MANIFEST_FILENAME} found at ${path}`);
+    this.name = 'ManifestNotFoundError';
+  }
+}
+
+export class ManifestParseError extends Error {
+  constructor(public path: string, message: string) {
+    super(message);
+    this.name = 'ManifestParseError';
+  }
+}
+
+/**
+ * Load and validate cli4ai.json from a directory (throws on error)
+ * Use this for programmatic/testable usage
+ */
+export function loadManifestOrThrow(dir: string): Manifest {
+  const manifestPath = resolve(dir, MANIFEST_FILENAME);
+
+  if (!existsSync(manifestPath)) {
+    throw new ManifestNotFoundError(manifestPath);
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(manifestPath, 'utf-8');
+  } catch (err) {
+    throw new ManifestParseError(manifestPath, `Failed to read: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  let data: unknown;
+  try {
+    data = JSON.parse(content);
+  } catch {
+    throw new ManifestParseError(manifestPath, 'Invalid JSON');
+  }
+
+  return validateManifest(data, manifestPath);
+}
+
+/**
+ * Load manifest from package.json (fallback for npm packages)
+ */
+export function loadFromPackageJson(dir: string): Manifest | null {
+  const pkgJsonPath = resolve(dir, 'package.json');
+  if (!existsSync(pkgJsonPath)) return null;
+
+  try {
+    const content = readFileSync(pkgJsonPath, 'utf-8');
+    const pkg = JSON.parse(content);
+
+    // Extract name without @cli4ai/ scope
+    const name = pkg.name?.replace('@cli4ai/', '') || basename(dir);
+
+    return {
+      name,
+      version: pkg.version || '1.0.0',
+      entry: pkg.main || 'run.ts',
+      description: pkg.description,
+      author: pkg.author,
+      license: pkg.license,
+      runtime: 'bun',
+      keywords: pkg.keywords
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load and validate cli4ai.json from a directory
+ * Falls back to package.json for npm packages
+ * Exits with error on failure (for CLI usage)
+ */
+export function loadManifest(dir: string): Manifest {
+  // Try cli4ai.json first
+  try {
+    return loadManifestOrThrow(dir);
+  } catch (err) {
+    if (err instanceof ManifestNotFoundError) {
+      // Fallback to package.json
+      const fromPkgJson = loadFromPackageJson(dir);
+      if (fromPkgJson) return fromPkgJson;
+
+      outputError('NOT_FOUND', `No ${MANIFEST_FILENAME} found`, {
+        path: err.path,
+        hint: 'Run "cli4ai init" to create one'
+      });
+    }
+    if (err instanceof ManifestParseError) {
+      outputError('PARSE_ERROR', err.message, { path: err.path });
+    }
+    if (err instanceof ManifestValidationError) {
+      outputError('MANIFEST_ERROR', err.message, err.details);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Try to load manifest, return null if not found
+ */
+export function tryLoadManifest(dir: string): Manifest | null {
+  const manifestPath = resolve(dir, MANIFEST_FILENAME);
+  if (!existsSync(manifestPath)) return null;
+
+  try {
+    const content = readFileSync(manifestPath, 'utf-8');
+    const data = JSON.parse(content);
+    return validateManifest(data, manifestPath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find manifest by walking up directory tree
+ */
+export function findManifest(startDir?: string): { manifest: Manifest; dir: string } | null {
+  let dir = startDir || process.cwd();
+
+  for (let i = 0; i < 10; i++) {
+    const manifest = tryLoadManifest(dir);
+    if (manifest) {
+      return { manifest, dir };
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Create a minimal manifest
+ */
+export function createManifest(name: string, options: Partial<Manifest> = {}): Manifest {
+  return {
+    name: name.toLowerCase().replace(/[^a-z0-9-]/g, '-'),
+    version: '1.0.0',
+    entry: 'run.ts',
+    runtime: 'bun',
+    description: options.description || `${name} tool`,
+    ...options
+  };
+}