@bernierllc/braingrid-cli-wrapper 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { BrainGridProject, BrainGridRequirement, BrainGridTask, RequirementStatus, TaskStatus, BrainGridProjectSchema, BrainGridRequirementSchema, BrainGridTaskSchema, BrainGridCliError } from './models';
+export type { BrainGridCliErrorCode, BrainGridCliErrorOptions } from './models';
 export { createIdea } from './commands/createIdea';
 export { listProjects } from './commands/listProjects';
 export { createProject } from './commands/createProject';

package/dist/models.d.ts

@@ -81,9 +81,17 @@ export declare const BrainGridTaskSchema: z.ZodObject<{
     metadata?: Record<string, unknown> | undefined;
 }>;
 export type BrainGridTask = z.infer<typeof BrainGridTaskSchema>;
+export type BrainGridCliErrorCode = 'BRAINGRID_CLI_ERROR' | 'BRAINGRID_CLI_NOT_FOUND' | 'BRAINGRID_CLI_INVALID_OUTPUT' | 'BRAINGRID_CLI_NONZERO_EXIT';
+export interface BrainGridCliErrorOptions {
+    cause?: Error;
+    code?: BrainGridCliErrorCode;
+    context?: Record<string, unknown>;
+}
 export declare class BrainGridCliError extends Error {
     command: string;
     exitCode: number;
     stderr: string;
-    constructor(message: string, command: string, exitCode: number, stderr: string);
+    readonly code: BrainGridCliErrorCode;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, command: string, exitCode: number, stderr: string, options?: BrainGridCliErrorOptions);
 }

package/dist/models.js

@@ -58,17 +58,23 @@ exports.BrainGridTaskSchema = zod_1.z.object({
     updatedAt: zod_1.z.string().optional(),
     metadata: zod_1.z.record(zod_1.z.unknown()).optional()
 });
-// CLI Error
 class BrainGridCliError extends Error {
     command;
     exitCode;
     stderr;
-    constructor(message, command, exitCode, stderr) {
-        super(message);
+    code;
+    context;
+    constructor(message, command, exitCode, stderr, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
         this.name = 'BrainGridCliError';
         this.command = command;
         this.exitCode = exitCode;
         this.stderr = stderr;
+        this.code = options?.code ?? 'BRAINGRID_CLI_ERROR';
+        if (options?.context !== undefined) {
+            this.context = options.context;
+        }
+        Error.captureStackTrace?.(this, this.constructor);
     }
 }
 exports.BrainGridCliError = BrainGridCliError;

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@bernierllc/braingrid-cli-wrapper",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Type-safe wrapper for BrainGrid CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
     "braingrid",
     "cli",

package/.eslintrc.cjs

@@ -1,29 +0,0 @@
-/*
-Copyright (c) 2025 Bernier LLC
-
-This file is licensed to the client under a limited-use license.
-The client may use and modify this code *only within the scope of the project it was delivered for*.
-Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
-*/
-
-module.exports = {
-  parser: '@typescript-eslint/parser',
-  extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-  ],
-  parserOptions: {
-    ecmaVersion: 2020,
-    sourceType: 'module',
-  },
-  rules: {
-    '@typescript-eslint/no-explicit-any': 'warn',
-    '@typescript-eslint/explicit-module-boundary-types': 'off',
-    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
-  },
-  env: {
-    node: true,
-    jest: true,
-  },
-};
-

package/CHANGELOG.md

@@ -1,43 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-## [0.3.1](https://github.com/bernier-llc/tools/compare/@bernierllc/braingrid-cli-wrapper@0.3.0...@bernierllc/braingrid-cli-wrapper@0.3.1) (2026-03-03)
-
-**Note:** Version bump only for package @bernierllc/braingrid-cli-wrapper
-
-
-
-
-
-# 0.3.0 (2025-12-25)
-
-
-### Bug Fixes
-
-* **ci:** add lerna version step before publish ([3d20300](https://github.com/bernier-llc/tools/commit/3d203002143bf353fffafe4f8a78a99009567347))
-* **jest:** move global options to root config and fix typos ([c14710c](https://github.com/bernier-llc/tools/commit/c14710c11e8fc34dd7f773edf01328151564323a))
-* update neverhub-adapter deps to workspace:* and publish 0.1.2 ([f0e3d04](https://github.com/bernier-llc/tools/commit/f0e3d04d8d4f094e3bb899ddf81e93243d16e2c2))
-
-
-### Features
-
-* add 4 more core/integration packages ([dd05b81](https://github.com/bernier-llc/tools/commit/dd05b816c94adcbd99556afbd9e316146654f44c))
-
-
-
-
-
-# 0.2.0 (2025-12-25)
-
-
-### Bug Fixes
-
-* **jest:** move global options to root config and fix typos ([c14710c](https://github.com/bernier-llc/tools/commit/c14710c11e8fc34dd7f773edf01328151564323a))
-* update neverhub-adapter deps to workspace:* and publish 0.1.2 ([f0e3d04](https://github.com/bernier-llc/tools/commit/f0e3d04d8d4f094e3bb899ddf81e93243d16e2c2))
-
-
-### Features
-
-* add 4 more core/integration packages ([dd05b81](https://github.com/bernier-llc/tools/commit/dd05b816c94adcbd99556afbd9e316146654f44c))

package/jest.config.cjs

@@ -1,21 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  // Use fixed environment to handle Node.js v25+ localStorage issue
-  testEnvironment: '<rootDir>/../../../jest-environment-node-fixed.cjs',
-  roots: ['<rootDir>/src'],
-  testMatch: [
-    '**/__tests__/**/*.ts',
-    '**/?(*.)+(spec|test).ts'
-  ],
-  transform: {
-    '^.+\\.ts$': 'ts-jest',
-  },
-  collectCoverageFrom: [
-    'src/**/*.ts',
-    '!src/**/*.d.ts',
-  ],
-  coverageDirectory: 'coverage',
-  moduleFileExtensions: ['ts', 'js', 'json'],
-  setupFilesAfterEnv: [],
-};
-

package/src/__tests__/execa-mock-validation.test.ts

@@ -1,34 +0,0 @@
-/*
-Copyright (c) 2025 Bernier LLC
-
-This file is licensed to the client under a limited-use license.
-The client may use and modify this code *only within the scope of the project it was delivered for*.
-Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
-*/
-
-/**
- * Mock Validation Tests
- *
- * Per CLAUDE.md requirement: "mocks used in tests must always be validated!"
- * These tests verify our execa mock matches the real execa library behavior.
- * 
- * NOTE: This test is skipped because execa is an ESM module and Jest requires
- * additional configuration to handle ESM imports. The mock structure is validated
- * through integration with the actual CLI wrapper functions in other test files.
- */
-describe.skip('Execa Mock Validation', () => {
-  it('should match real execa return structure for successful commands', async () => {
-    // Skipped - execa is ESM and requires additional Jest configuration
-    // Mock structure is validated through CLI wrapper function tests
-  });
-
-  it('should match real execa error structure for failed commands', async () => {
-    // Skipped - execa is ESM and requires additional Jest configuration
-    // Error handling is validated through CLI wrapper function tests
-  });
-
-  it('should handle JSON output correctly', async () => {
-    // Skipped - execa is ESM and requires additional Jest configuration
-    // JSON parsing is validated through CLI wrapper function tests
-  });
-});

package/src/__tests__/index.test.ts

@@ -1,77 +0,0 @@
-/*
-Copyright (c) 2025 Bernier LLC
-
-This file is licensed to the client under a limited-use license.
-The client may use and modify this code *only within the scope of the project it was delivered for*.
-Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
-*/
-
-// Mock CLI module before importing index
-jest.mock('../cli', () => ({
-  runBrainGridCommand: jest.fn()
-}));
-
-// Mock all command modules to avoid loading real execa
-jest.mock('../commands/createIdea', () => ({
-  createIdea: jest.fn()
-}));
-jest.mock('../commands/listProjects', () => ({
-  listProjects: jest.fn()
-}));
-jest.mock('../commands/createProject', () => ({
-  createProject: jest.fn()
-}));
-jest.mock('../commands/listRequirements', () => ({
-  listRequirements: jest.fn()
-}));
-jest.mock('../commands/updateRequirementStatus', () => ({
-  updateRequirementStatus: jest.fn()
-}));
-jest.mock('../commands/createTask', () => ({
-  createTask: jest.fn()
-}));
-jest.mock('../commands/updateTaskStatus', () => ({
-  updateTaskStatus: jest.fn()
-}));
-jest.mock('../commands/listTasks', () => ({
-  listTasks: jest.fn()
-}));
-
-import * as BrainGridWrapper from '../index';
-
-describe('BrainGrid CLI Wrapper - Index Exports', () => {
-  it('should export all type definitions', () => {
-    expect(BrainGridWrapper.BrainGridProjectSchema).toBeDefined();
-    expect(BrainGridWrapper.BrainGridRequirementSchema).toBeDefined();
-    expect(BrainGridWrapper.BrainGridTaskSchema).toBeDefined();
-    expect(BrainGridWrapper.BrainGridCliError).toBeDefined();
-  });
-
-  it('should export all command functions', () => {
-    expect(typeof BrainGridWrapper.createIdea).toBe('function');
-    expect(typeof BrainGridWrapper.listProjects).toBe('function');
-    expect(typeof BrainGridWrapper.createProject).toBe('function');
-    expect(typeof BrainGridWrapper.listRequirements).toBe('function');
-    expect(typeof BrainGridWrapper.updateRequirementStatus).toBe('function');
-    expect(typeof BrainGridWrapper.createTask).toBe('function');
-    expect(typeof BrainGridWrapper.updateTaskStatus).toBe('function');
-    expect(typeof BrainGridWrapper.listTasks).toBe('function');
-  });
-
-  it('should export BrainGridCliError as a class', () => {
-    const error = new BrainGridWrapper.BrainGridCliError(
-      'Test error',
-      'braingrid test',
-      1,
-      'test stderr'
-    );
-
-    expect(error).toBeInstanceOf(Error);
-    expect(error).toBeInstanceOf(BrainGridWrapper.BrainGridCliError);
-    expect(error.name).toBe('BrainGridCliError');
-    expect(error.message).toBe('Test error');
-    expect(error.command).toBe('braingrid test');
-    expect(error.exitCode).toBe(1);
-    expect(error.stderr).toBe('test stderr');
-  });
-});

package/src/cli.test.ts

@@ -1,86 +0,0 @@
-/*
-Copyright (c) 2025 Bernier LLC
-
-This file is licensed to the client under a limited-use license.
-The client may use and modify this code *only within the scope of the project it was delivered for*.
-Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
-*/
-
-import { runBrainGridCommand } from './cli';
-import { BrainGridCliError } from './models';
-
-// Mock execa
-jest.mock('execa', () => ({
-  execa: jest.fn()
-}));
-
-import { execa } from 'execa';
-
-describe('CLI Helper', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  it('should run command successfully', async () => {
-    const mockOutput = { id: 'proj-123', name: 'Test' };
-    (execa as jest.MockedFunction<typeof execa>).mockResolvedValue({
-      stdout: JSON.stringify(mockOutput),
-      stderr: '',
-      exitCode: 0
-    } as any);
-
-    const result = await runBrainGridCommand(['projects', 'list', '--format', 'json']);
-
-    expect(result).toEqual(mockOutput);
-    expect(execa).toHaveBeenCalledWith(
-      'braingrid',
-      ['projects', 'list', '--format', 'json'],
-      expect.any(Object)
-    );
-  });
-
-  it('should handle command with no JSON output', async () => {
-    (execa as jest.MockedFunction<typeof execa>).mockResolvedValue({
-      stdout: 'Success',
-      stderr: '',
-      exitCode: 0
-    } as any);
-
-    const result = await runBrainGridCommand(['task', 'update', 'task-123']);
-
-    expect(result).toBeNull();
-  });
-
-  it('should throw BrainGridCliError on failure', async () => {
-    (execa as jest.MockedFunction<typeof execa>).mockRejectedValue({
-      exitCode: 1,
-      stderr: 'Invalid command',
-      stdout: ''
-    });
-
-    await expect(
-      runBrainGridCommand(['invalid'])
-    ).rejects.toThrow(BrainGridCliError);
-  });
-
-  it('should use custom CLI path from env', async () => {
-    const originalEnv = process.env.BRAINGRID_CLI_PATH;
-    process.env.BRAINGRID_CLI_PATH = '/custom/path/braingrid';
-
-    (execa as jest.MockedFunction<typeof execa>).mockResolvedValue({
-      stdout: '{}',
-      stderr: '',
-      exitCode: 0
-    } as any);
-
-    await runBrainGridCommand(['projects', 'list']);
-
-    expect(execa).toHaveBeenCalledWith(
-      '/custom/path/braingrid',
-      expect.any(Array),
-      expect.any(Object)
-    );
-
-    process.env.BRAINGRID_CLI_PATH = originalEnv;
-  });
-});

package/src/cli.ts

@@ -1,71 +0,0 @@
-/*
-Copyright (c) 2025 Bernier LLC
-
-This file is licensed to the client under a limited-use license.
-The client may use and modify this code *only within the scope of the project it was delivered for*.
-Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
-*/
-
-import { execa } from 'execa';
-import { BrainGridCliError } from './models';
-
-/**
- * Run a BrainGrid CLI command and return parsed JSON output
- */
-export async function runBrainGridCommand(
-  args: string[],
-  options?: {
-    cwd?: string;
-    env?: Record<string, string>;
-  }
-): Promise<unknown> {
-  const cliPath = process.env.BRAINGRID_CLI_PATH || 'braingrid';
-
-  try {
-    const result = await execa(cliPath, args, {
-      cwd: options?.cwd,
-      env: {
-        ...process.env,
-        ...options?.env
-      },
-      timeout: 30000, // 30 second timeout
-      reject: false // Don't throw on non-zero exit
-    });
-
-    // Check for errors
-    if (result.exitCode !== 0) {
-      throw new BrainGridCliError(
-        `BrainGrid CLI command failed: ${args.join(' ')}`,
-        cliPath,
-        result.exitCode,
-        result.stderr
-      );
-    }
-
-    // Try to parse JSON output
-    const stdout = result.stdout.trim();
-    if (!stdout) {
-      return null;
-    }
-
-    try {
-      return JSON.parse(stdout);
-    } catch (e) {
-      // Not JSON output, return as-is
-      return null;
-    }
-  } catch (error) {
-    if (error instanceof BrainGridCliError) {
-      throw error;
-    }
-
-    // Handle execa errors
-    const execaError = error as Error & { exitCode?: number; stderr?: string };
-    throw new BrainGridCliError(
-      `Failed to execute BrainGrid CLI: ${execaError.message}`,
-      cliPath,
-      execaError.exitCode || -1,
-      execaError.stderr || ''
-    );
-  }
-}

package/src/commands/createIdea.test.ts

@@ -1,77 +0,0 @@
-/*
-Copyright (c) 2025 Bernier LLC
-
-This file is licensed to the client under a limited-use license.
-The client may use and modify this code *only within the scope of the project it was delivered for*.
-Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
-*/
-
-import { createIdea } from './createIdea';
-
-jest.mock('../cli', () => ({
-  runBrainGridCommand: jest.fn()
-}));
-
-import { runBrainGridCommand } from '../cli';
-
-describe('createIdea', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  it('should create idea with prompt only', async () => {
-    const mockReq = {
-      id: 'req-123',
-      projectId: 'proj-456',
-      title: 'Add OAuth2',
-      status: 'IDEA'
-    };
-
-    (runBrainGridCommand as jest.MockedFunction<typeof runBrainGridCommand>).mockResolvedValue(mockReq);
-
-    const result = await createIdea('Add OAuth2 authentication');
-
-    expect(runBrainGridCommand).toHaveBeenCalledWith([
-      'specify',
-      'Add OAuth2 authentication',
-      '--format',
-      'json'
-    ]);
-
-    expect(result.id).toBe('req-123');
-    expect(result.status).toBe('IDEA');
-  });
-
-  it('should create idea with project ID', async () => {
-    const mockReq = {
-      id: 'req-123',
-      projectId: 'proj-456',
-      title: 'Add OAuth2',
-      status: 'IDEA'
-    };
-
-    (runBrainGridCommand as jest.MockedFunction<typeof runBrainGridCommand>).mockResolvedValue(mockReq);
-
-    await createIdea('Add OAuth2 authentication', 'proj-456');
-
-    expect(runBrainGridCommand).toHaveBeenCalledWith([
-      'specify',
-      'Add OAuth2 authentication',
-      '--project',
-      'proj-456',
-      '--format',
-      'json'
-    ]);
-  });
-
-  it('should validate response schema', async () => {
-    const invalidReq = {
-      id: 123, // Should be string
-      title: 'Test'
-    };
-
-    (runBrainGridCommand as jest.MockedFunction<typeof runBrainGridCommand>).mockResolvedValue(invalidReq);
-
-    await expect(createIdea('Test')).rejects.toThrow();
-  });
-});

package/src/commands/createIdea.ts

@@ -1,36 +0,0 @@
-/*
-Copyright (c) 2025 Bernier LLC
-
-This file is licensed to the client under a limited-use license.
-The client may use and modify this code *only within the scope of the project it was delivered for*.
-Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
-*/
-
-import { runBrainGridCommand } from '../cli';
-import { BrainGridRequirement, BrainGridRequirementSchema } from '../models';
-
-/**
- * Create a new requirement (IDEA) in BrainGrid
- */
-export async function createIdea(
-  prompt: string,
-  projectId?: string
-): Promise<BrainGridRequirement> {
-  const args = ['specify', prompt];
-
-  if (projectId) {
-    args.push('--project', projectId);
-  }
-
-  args.push('--format', 'json');
-
-  const result = await runBrainGridCommand(args);
-
-  // Validate response
-  const parsed = BrainGridRequirementSchema.safeParse(result);
-  if (!parsed.success) {
-    throw new Error(`Invalid BrainGrid response: ${parsed.error.message}`);
-  }
-
-  return parsed.data;
-}

package/src/commands/createProject.test.ts

@@ -1,75 +0,0 @@
-/*
-Copyright (c) 2025 Bernier LLC
-
-This file is licensed to the client under a limited-use license.
-The client may use and modify this code *only within the scope of the project it was delivered for*.
-Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
-*/
-
-import { createProject } from './createProject';
-
-jest.mock('../cli', () => ({
-  runBrainGridCommand: jest.fn()
-}));
-
-import { runBrainGridCommand } from '../cli';
-
-describe('createProject', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  it('should create project with name only', async () => {
-    (runBrainGridCommand as jest.MockedFunction<typeof runBrainGridCommand>).mockResolvedValue({
-      id: 'proj-123',
-      name: 'Test Project'
-    });
-
-    const result = await createProject('Test Project');
-
-    expect(runBrainGridCommand).toHaveBeenCalledWith([
-      'project',
-      'create',
-      '--name',
-      'Test Project',
-      '--format',
-      'json'
-    ]);
-    expect(result).toEqual({
-      id: 'proj-123',
-      name: 'Test Project'
-    });
-  });
-
-  it('should create project with name and description', async () => {
-    (runBrainGridCommand as jest.MockedFunction<typeof runBrainGridCommand>).mockResolvedValue({
-      id: 'proj-456',
-      name: 'My Project',
-      description: 'Project description'
-    });
-
-    const result = await createProject('My Project', 'Project description');
-
-    expect(runBrainGridCommand).toHaveBeenCalledWith([
-      'project',
-      'create',
-      '--name',
-      'My Project',
-      '--format',
-      'json',
-      '--description',
-      'Project description'
-    ]);
-    expect(result).toEqual({
-      id: 'proj-456',
-      name: 'My Project',
-      description: 'Project description'
-    });
-  });
-
-  it('should throw on invalid response', async () => {
-    (runBrainGridCommand as jest.MockedFunction<typeof runBrainGridCommand>).mockResolvedValue({ invalid: 'data' });
-
-    await expect(createProject('Test')).rejects.toThrow();
-  });
-});

package/src/commands/createProject.ts

@@ -1,37 +0,0 @@
-/*
-Copyright (c) 2025 Bernier LLC
-
-This file is licensed to the client under a limited-use license.
-The client may use and modify this code *only within the scope of the project it was delivered for*.
-Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
-*/
-
-import { runBrainGridCommand } from '../cli';
-import { BrainGridProject, BrainGridProjectSchema } from '../models';
-
-/**
- * Creates a new BrainGrid project
- * @param name - Project name (required)
- * @param description - Project description (optional)
- * @returns Promise resolving to the created project
- */
-export async function createProject(
-  name: string,
-  description?: string
-): Promise<BrainGridProject> {
-  const args = ['project', 'create', '--name', name, '--format', 'json'];
-
-  if (description) {
-    args.push('--description', description);
-  }
-
-  const result = await runBrainGridCommand(args);
-
-  // Validate response
-  const parsed = BrainGridProjectSchema.safeParse(result);
-  if (!parsed.success) {
-    throw new Error(`Invalid BrainGrid response: ${parsed.error.message}`);
-  }
-
-  return parsed.data;
-}