@bernierllc/braingrid-cli-wrapper 0.1.1

package/.eslintrc.cjs

@@ -0,0 +1,29 @@
+/*
+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/README.md

@@ -0,0 +1,401 @@
+# @bernierllc/braingrid-cli-wrapper
+
+Type-safe wrapper for the BrainGrid CLI that provides a clean, programmatic interface for interacting with BrainGrid projects, requirements, and tasks.
+
+## Overview
+
+This package provides atomic utilities for interacting with the BrainGrid CLI in a type-safe manner. It wraps BrainGrid CLI commands with Zod schema validation, ensuring type safety and proper error handling.
+
+## Features
+
+- **Type-safe API**: Full TypeScript support with Zod schema validation
+- **Error Handling**: Custom error types with detailed error information
+- **CLI Integration**: Seamless integration with BrainGrid CLI commands
+- **Schema Validation**: Automatic validation of CLI responses using Zod schemas
+- **Minimal Dependencies**: Only depends on `execa` and `zod`
+
+## Installation
+
+```bash
+npm install @bernierllc/braingrid-cli-wrapper
+```
+
+## Quick Start
+
+```typescript
+import { createIdea, listProjects, createTask } from '@bernierllc/braingrid-cli-wrapper';
+
+// Create a new requirement (IDEA)
+const requirement = await createIdea('Add OAuth2 authentication', 'proj-123');
+console.log(`Created requirement ${requirement.id} with status ${requirement.status}`);
+
+// List all projects
+const projects = await listProjects();
+console.log(`Found ${projects.length} projects`);
+
+// Create a task under a requirement
+const task = await createTask('req-456', {
+  title: 'Build login UI',
+  description: 'Create login form component',
+  tags: ['DEV', 'frontend'],
+  dependencies: ['task-100']
+});
+console.log(`Created task ${task.id}`);
+```
+
+## API Reference
+
+### Commands
+
+#### `createIdea(prompt: string, projectId?: string): Promise<BrainGridRequirement>`
+
+Creates a new requirement (IDEA) in BrainGrid.
+
+**Input:**
+- `prompt` (string, required): Description of the requirement/idea
+- `projectId` (string, optional): Project ID to associate with the requirement
+
+**Output:**
+- Returns a `BrainGridRequirement` object with:
+  - `id`: Requirement ID
+  - `projectId`: Associated project ID
+  - `title`: Requirement title
+  - `status`: Requirement status (IDEA, PLANNED, IN_PROGRESS, COMPLETED, CANCELLED, PAUSED)
+  - `description`: Optional description
+  - `createdAt`: Optional creation timestamp
+  - `updatedAt`: Optional update timestamp
+
+**Example:**
+```typescript
+const req = await createIdea('Add user authentication system');
+// { id: 'req-123', projectId: 'proj-456', title: 'Add user authentication system', status: 'IDEA' }
+```
+
+#### `listProjects(): Promise<BrainGridProject[]>`
+
+Lists all projects in BrainGrid.
+
+**Input:** None
+
+**Output:**
+- Returns an array of `BrainGridProject` objects with:
+  - `id`: Project ID
+  - `name`: Project name
+  - `description`: Optional project description
+
+**Example:**
+```typescript
+const projects = await listProjects();
+// [{ id: 'proj-1', name: 'My Project', description: 'Project description' }]
+```
+
+#### `createTask(reqId: string, options: CreateTaskOptions): Promise<BrainGridTask>`
+
+Creates a task under a requirement.
+
+**Input:**
+- `reqId` (string, required): Requirement ID
+- `options` (CreateTaskOptions, required):
+  - `title` (string, required): Task title
+  - `description` (string, optional): Task description
+  - `tags` (string[], optional): Task tags
+  - `dependencies` (string[], optional): Task dependency IDs
+
+**Output:**
+- Returns a `BrainGridTask` object with:
+  - `id`: Task ID
+  - `reqId`: Parent requirement ID
+  - `title`: Task title
+  - `status`: Task status (TODO, READY, BLOCKED, IN_PROGRESS, COMPLETED, FAILED, PAUSED)
+  - `description`: Optional description
+  - `tags`: Optional array of tags
+  - `dependencies`: Optional array of dependency IDs
+  - `assignedTo`: Optional assignee ID
+  - `createdAt`: Optional creation timestamp
+  - `updatedAt`: Optional update timestamp
+  - `metadata`: Optional metadata object
+
+**Example:**
+```typescript
+const task = await createTask('req-123', {
+  title: 'Build login UI',
+  description: 'Create login form component',
+  tags: ['DEV', 'frontend'],
+  dependencies: ['task-100']
+});
+// { id: 'task-456', reqId: 'req-123', title: 'Build login UI', status: 'TODO', ... }
+```
+
+#### `listTasks(options?: ListTasksOptions): Promise<BrainGridTask[]>`
+
+Lists tasks with optional filters.
+
+**Input:**
+- `options` (ListTasksOptions, optional):
+  - `reqId` (string, optional): Filter by requirement ID
+  - `status` (TaskStatus[], optional): Filter by status array
+  - `tags` (string[], optional): Filter by tags array
+
+**Output:**
+- Returns an array of `BrainGridTask` objects
+
+**Example:**
+```typescript
+// List all tasks
+const allTasks = await listTasks();
+
+// List tasks for a specific requirement
+const reqTasks = await listTasks({ reqId: 'req-123' });
+
+// List tasks by status
+const inProgressTasks = await listTasks({ status: ['IN_PROGRESS'] });
+
+// Combine filters
+const filteredTasks = await listTasks({
+  reqId: 'req-123',
+  status: ['TODO', 'READY'],
+  tags: ['DEV']
+});
+```
+
+#### `updateTaskStatus(taskId: string, options: UpdateTaskOptions): Promise<void>`
+
+Updates task status and metadata.
+
+**Input:**
+- `taskId` (string, required): Task ID to update
+- `options` (UpdateTaskOptions, optional):
+  - `status` (TaskStatus, optional): New task status
+  - `assignedTo` (string, optional): Assignee ID
+  - `metadata` (Record<string, unknown>, optional): Metadata object
+
+**Output:** Promise that resolves when update is complete
+
+**Example:**
+```typescript
+// Update task status
+await updateTaskStatus('task-123', { status: 'IN_PROGRESS' });
+
+// Update with assignee
+await updateTaskStatus('task-123', {
+  status: 'IN_PROGRESS',
+  assignedTo: 'user-456'
+});
+
+// Update with metadata
+await updateTaskStatus('task-123', {
+  status: 'IN_PROGRESS',
+  metadata: { progress: 50, notes: 'Half done' }
+});
+```
+
+### Types
+
+#### `BrainGridProject`
+
+```typescript
+interface BrainGridProject {
+  id: string;
+  name: string;
+  description?: string;
+}
+```
+
+#### `BrainGridRequirement`
+
+```typescript
+interface BrainGridRequirement {
+  id: string;
+  projectId: string;
+  title: string;
+  status: RequirementStatus;
+  description?: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+```
+
+#### `BrainGridTask`
+
+```typescript
+interface BrainGridTask {
+  id: string;
+  reqId: string;
+  title: string;
+  status: TaskStatus;
+  description?: string;
+  tags?: string[];
+  dependencies?: string[];
+  assignedTo?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+#### `RequirementStatus`
+
+```typescript
+type RequirementStatus = 'IDEA' | 'PLANNED' | 'IN_PROGRESS' | 'COMPLETED' | 'CANCELLED' | 'PAUSED';
+```
+
+#### `TaskStatus`
+
+```typescript
+type TaskStatus = 'TODO' | 'READY' | 'BLOCKED' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'PAUSED';
+```
+
+### Error Handling
+
+The package throws `BrainGridCliError` when CLI commands fail:
+
+```typescript
+class BrainGridCliError extends Error {
+  command: string;
+  exitCode: number;
+  stderr: string;
+}
+```
+
+**Example:**
+```typescript
+import { createIdea, BrainGridCliError } from '@bernierllc/braingrid-cli-wrapper';
+
+try {
+  const req = await createIdea('Test requirement');
+} catch (error) {
+  if (error instanceof BrainGridCliError) {
+    console.error(`CLI command failed: ${error.command}`);
+    console.error(`Exit code: ${error.exitCode}`);
+    console.error(`Error output: ${error.stderr}`);
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+- `BRAINGRID_CLI_PATH`: Custom path to the BrainGrid CLI executable (defaults to `'braingrid'`)
+
+**Example:**
+```bash
+export BRAINGRID_CLI_PATH=/custom/path/braingrid
+```
+
+## Usage Examples
+
+### Complete Workflow
+
+```typescript
+import {
+  listProjects,
+  createIdea,
+  createTask,
+  listTasks,
+  updateTaskStatus
+} from '@bernierllc/braingrid-cli-wrapper';
+
+async function workflow() {
+  // 1. List projects
+  const projects = await listProjects();
+  const project = projects[0];
+
+  // 2. Create a requirement
+  const requirement = await createIdea(
+    'Build user authentication system',
+    project.id
+  );
+
+  // 3. Create tasks
+  const task1 = await createTask(requirement.id, {
+    title: 'Design authentication flow',
+    tags: ['DESIGN']
+  });
+
+  const task2 = await createTask(requirement.id, {
+    title: 'Implement login endpoint',
+    tags: ['DEV', 'backend'],
+    dependencies: [task1.id]
+  });
+
+  // 4. List tasks
+  const tasks = await listTasks({ reqId: requirement.id });
+  console.log(`Created ${tasks.length} tasks`);
+
+  // 5. Update task status
+  await updateTaskStatus(task1.id, { status: 'COMPLETED' });
+  await updateTaskStatus(task2.id, {
+    status: 'IN_PROGRESS',
+    assignedTo: 'user-123'
+  });
+}
+```
+
+### Error Handling Example
+
+```typescript
+import { createIdea, BrainGridCliError } from '@bernierllc/braingrid-cli-wrapper';
+
+async function createRequirementSafely(prompt: string) {
+  try {
+    const req = await createIdea(prompt);
+    return req;
+  } catch (error) {
+    if (error instanceof BrainGridCliError) {
+      console.error(`BrainGrid CLI error: ${error.message}`);
+      console.error(`Command: ${error.command}`);
+      console.error(`Exit code: ${error.exitCode}`);
+      console.error(`Stderr: ${error.stderr}`);
+      throw new Error('Failed to create requirement');
+    }
+    throw error;
+  }
+}
+```
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## Integration Status
+
+### Logger Integration
+**Status**: not-applicable
+
+This is a pure utility core package with no dependencies. Logging is handled by consuming packages. Does not require @bernierllc/logger integration.
+
+### Docs-Suite Integration
+**Status**: ready
+
+Complete API documentation with TypeScript types and examples available for documentation suite integration.
+
+### NeverHub Integration
+**Status**: not-applicable
+
+Pure utility package with no runtime dependencies. NeverHub integration is handled at the service-level packages that consume this utility. Does not require @bernierllc/neverhub-adapter integration.
+
+## Core Package Compliance
+
+This package follows the core package rules:
+
+- ✅ **Atomic functionality**: Single responsibility - wraps BrainGrid CLI
+- ✅ **No internal dependencies**: Only depends on external packages (`execa`, `zod`)
+- ✅ **Pure functions**: Explicit inputs/outputs with type safety
+- ✅ **Full test coverage**: Comprehensive test suite for all commands
+- ✅ **Single entrypoint**: All exports via `index.ts`
+- ✅ **Strict typing**: TypeScript strict mode enabled, no implicit `any`
+- ✅ **Documentation**: Complete README with purpose, usage, and examples
+
+## License
+
+MIT License - see LICENSE file for details.

package/coverage/base.css

@@ -0,0 +1,224 @@
+body, html {
+  margin:0; padding: 0;
+  height: 100%;
+}
+body {
+    font-family: Helvetica Neue, Helvetica, Arial;
+    font-size: 14px;
+    color:#333;
+}
+.small { font-size: 12px; }
+*, *:after, *:before {
+  -webkit-box-sizing:border-box;
+     -moz-box-sizing:border-box;
+          box-sizing:border-box;
+  }
+h1 { font-size: 20px; margin: 0;}
+h2 { font-size: 14px; }
+pre {
+    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
+    margin: 0;
+    padding: 0;
+    -moz-tab-size: 2;
+    -o-tab-size:  2;
+    tab-size: 2;
+}
+a { color:#0074D9; text-decoration:none; }
+a:hover { text-decoration:underline; }
+.strong { font-weight: bold; }
+.space-top1 { padding: 10px 0 0 0; }
+.pad2y { padding: 20px 0; }
+.pad1y { padding: 10px 0; }
+.pad2x { padding: 0 20px; }
+.pad2 { padding: 20px; }
+.pad1 { padding: 10px; }
+.space-left2 { padding-left:55px; }
+.space-right2 { padding-right:20px; }
+.center { text-align:center; }
+.clearfix { display:block; }
+.clearfix:after {
+  content:'';
+  display:block;
+  height:0;
+  clear:both;
+  visibility:hidden;
+  }
+.fl { float: left; }
+@media only screen and (max-width:640px) {
+  .col3 { width:100%; max-width:100%; }
+  .hide-mobile { display:none!important; }
+}
+
+.quiet {
+  color: #7f7f7f;
+  color: rgba(0,0,0,0.5);
+}
+.quiet a { opacity: 0.7; }
+
+.fraction {
+  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+  font-size: 10px;
+  color: #555;
+  background: #E8E8E8;
+  padding: 4px 5px;
+  border-radius: 3px;
+  vertical-align: middle;
+}
+
+div.path a:link, div.path a:visited { color: #333; }
+table.coverage {
+  border-collapse: collapse;
+  margin: 10px 0 0 0;
+  padding: 0;
+}
+
+table.coverage td {
+  margin: 0;
+  padding: 0;
+  vertical-align: top;
+}
+table.coverage td.line-count {
+    text-align: right;
+    padding: 0 5px 0 20px;
+}
+table.coverage td.line-coverage {
+    text-align: right;
+    padding-right: 10px;
+    min-width:20px;
+}
+
+table.coverage td span.cline-any {
+    display: inline-block;
+    padding: 0 5px;
+    width: 100%;
+}
+.missing-if-branch {
+    display: inline-block;
+    margin-right: 5px;
+    border-radius: 3px;
+    position: relative;
+    padding: 0 4px;
+    background: #333;
+    color: yellow;
+}
+
+.skip-if-branch {
+    display: none;
+    margin-right: 10px;
+    position: relative;
+    padding: 0 4px;
+    background: #ccc;
+    color: white;
+}
+.missing-if-branch .typ, .skip-if-branch .typ {
+    color: inherit !important;
+}
+.coverage-summary {
+  border-collapse: collapse;
+  width: 100%;
+}
+.coverage-summary tr { border-bottom: 1px solid #bbb; }
+.keyline-all { border: 1px solid #ddd; }
+.coverage-summary td, .coverage-summary th { padding: 10px; }
+.coverage-summary tbody { border: 1px solid #bbb; }
+.coverage-summary td { border-right: 1px solid #bbb; }
+.coverage-summary td:last-child { border-right: none; }
+.coverage-summary th {
+  text-align: left;
+  font-weight: normal;
+  white-space: nowrap;
+}
+.coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
+.coverage-summary th.pic,
+.coverage-summary th.abs,
+.coverage-summary td.pct,
+.coverage-summary td.abs { text-align: right; }
+.coverage-summary td.file { white-space: nowrap;  }
+.coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
+
+.coverage-summary .sorter {
+    height: 10px;
+    width: 7px;
+    display: inline-block;
+    margin-left: 0.5em;
+    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
+}
+.coverage-summary .sorted .sorter {
+    background-position: 0 -20px;
+}
+.coverage-summary .sorted-desc .sorter {
+    background-position: 0 -10px;
+}
+.status-line {  height: 10px; }
+/* yellow */
+.cbranch-no { background: yellow !important; color: #111; }
+/* dark red */
+.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
+.low .chart { border:1px solid #C21F39 }
+.highlighted,
+.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
+  background: #C21F39 !important;
+}
+/* medium red */
+.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
+/* light red */
+.low, .cline-no { background:#FCE1E5 }
+/* light green */
+.high, .cline-yes { background:rgb(230,245,208) }
+/* medium green */
+.cstat-yes { background:rgb(161,215,106) }
+/* dark green */
+.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
+.high .chart { border:1px solid rgb(77,146,33) }
+/* dark yellow (gold) */
+.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
+.medium .chart { border:1px solid #f9cd0b; }
+/* light yellow */
+.medium { background: #fff4c2; }
+
+.cstat-skip { background: #ddd; color: #111; }
+.fstat-skip { background: #ddd; color: #111 !important; }
+.cbranch-skip { background: #ddd !important; color: #111; }
+
+span.cline-neutral { background: #eaeaea; }
+
+.coverage-summary td.empty {
+    opacity: .5;
+    padding-top: 4px;
+    padding-bottom: 4px;
+    line-height: 1;
+    color: #888;
+}
+
+.cover-fill, .cover-empty {
+  display:inline-block;
+  height: 12px;
+}
+.chart {
+  line-height: 0;
+}
+.cover-empty {
+    background: white;
+}
+.cover-full {
+    border-right: none !important;
+}
+pre.prettyprint {
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+}
+.com { color: #999 !important; }
+.ignore-none { color: #999; font-weight: normal; }
+
+.wrapper {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+  margin: 0 auto -48px;
+}
+.footer, .push {
+  height: 48px;
+}