Skip to content

AGENTS.bak.md

Latest commit

 

History

History
299 lines (205 loc) · 11.2 KB

AGENTS.bak.md

File metadata and controls

299 lines (205 loc) · 11.2 KB

MInd Rig

MInd Rig is an editor companion that helps to work on, test (in a playground and using evals) defined in source code. Right now it's in progress, so now all features planned are implemented.

Project Structure

This is a monorepo managed by Turborepo and pnpm with the following packages:

vscode/extension

VS Code extension package containing the main extension logic and webview provider.

Stack:

  • TypeScript
  • VS Code Extension API
  • Vite as the bundler
  • vscode-test (extension integration tests)

Available commands:

  • pnpm turbo build --filter vscode - Build the extension
  • pnpm turbo watch --filter vscode - Watch and rebuild on changes
  • pnpm turbo package --filter vscode - Package for production
  • pnpm turbo test --filter vscode - Run e2e tests
  • pnpm turbo lint --filter vscode - Lint TypeScript code
  • pnpm turbo pack --filter vscode - Create VSIX package
  • pnpm turbo publish --filter vscode - Publish to marketplace

vscode/webview

React webview application that provides the UI for the MInd Rig panel.

Stack:

  • TypeScript
  • React 18
  • Vite as the bundler
  • Tailwind CSS
  • PostCSS

Available commands:

  • pnpm turbo build --filter @mindcontrol/vscode-webview - Build the webview
  • pnpm turbo watch --filter @mindcontrol/vscode-webview - Watch and rebuild on changes
  • pnpm turbo package --filter @mindcontrol/vscode-webview - Package for production
  • pnpm turbo serve --filter @mindcontrol/vscode-webview - Development server
  • pnpm turbo lint --filter @mindcontrol/vscode-webview - Lint TypeScript/React code

vscode/sync

VS Code synchronization package for managing state and communication between the extension and webview. It includes common types and utilities.

vscode/types

VS Code types package containing common type definitions for the extension and webview.

types

Shared type definitions using the Genotype programming language for cross-language type safety between TypeScript and Rust packages.

Stack:

  • Genotype programming language for type definitions
  • Generates TypeScript types in types/pkgs/ts
  • Generates Rust types in types/pkgs/rs
  • Automatically included in both pnpm (pkg/ts) and Rust (pkg/rs) workspaces

Available commands:

  • gt build - Generate TypeScript and Rust types from Genotype definitions
  • IMPORTANT: Never manually edit the generated types/pkgs/ directories

Language Guide: Reference the Genotype language guide and syntax examples

parser

Rust-based parser crate that compiles to WebAssembly to power JS/TS code parsing in the extension.

Stack:

  • Rust (edition 2024)
  • wasm-bindgen for JS interop
  • serde for serialization
  • Compiles to WebAssembly module consumed by the extension
  • insta for snapshot testing (with inline snapshots preferred)
  • watchexec for watching Rust tests

Available commands:

  • pnpm turbo build --filter @mindcontrol/code-parser - Compile Rust to WebAssembly
  • pnpm test:rs - Run Rust tests (from workspace root)
  • pnpm test:rs:watch - Watch Rust tests with watchexec (from workspace root)
  • pnpm test:rs:review - Review insta snapshots (from workspace root)

Parser-specific commands (from parser/ directory):

  • pnpm run build - Build WebAssembly module
  • pnpm run test - Run Rust tests
  • pnpm run test:watch - Watch Rust tests with watchexec
  • pnpm run test:review - Review insta snapshots

Important Notes:

  • The parser/pkg/ directory is automatically generated by wasm-bindgen during the build process and should never be manually edited. TypeScript definitions and JavaScript bindings are automatically generated from the Rust source code.
  • We use insta for snapshot testing and prefer storing snapshots inline for easier test readability
  • Never accept insta snapshots yourself - always prompt the developer to run pnpm test:rs:review or pnpm run test:review to accept snapshots
  • Always run nextest with --no-fail-fast - This ensures all snapshot tests run and generate diffs, allowing you to review all changes at once instead of one by one

Build Architecture

The project uses a Turborepo-orchestrated multi-package architecture with isolated dependencies:

  • Extension package: Builds Node.js/CommonJS code for VS Code extension host
  • Webview package: Builds React app as ES modules for webview display
  • Parser package: Rust crate compiled to WebAssembly, consumed by extension
  • Build output: Webview builds into extension/dist/webview/, extension builds into extension/dist/extension/
  • Distribution: Extension package contains both webview and parser outputs for VS Code marketplace

Rust Toolchain

The parser package requires:

Build Commands

From the root directory using Turborepo:

  • Build all packages: pnpm turbo build
  • Build specific package: pnpm turbo build --filter @mindcontrol/code-vscode
  • Build webview: pnpm turbo build --filter @mindcontrol/code-webview
  • Build parser: pnpm turbo build --filter @mindcontrol/code-parser
  • Watch extension: pnpm turbo watch --filter @mindcontrol/code-vscode
  • Watch webview: pnpm turbo watch --filter @mindcontrol/code-webview

Or use VS Code tasks:

  • Ctrl+Shift+P → Tasks: Run Task → build:extension or build:webview
  • Ctrl+Shift+P → Tasks: Run Task → watch:extension or watch:webview

Testing Commands

From the root directory:

  • Run extension e2e tests: pnpm turbo test --filter vscode

The e2e tests use @vscode/test-cli and Playwright to test the extension in an actual VS Code instance. The tests connect to VS Code using Chromium DevTools protocol and use Playwright's expect API combined with Mocha test framework.

Note: Run the e2e tests whenever the extension setup has changed. For now, webview tests should be skipped until explicitly requested.

Development Plan

  • MVP with playground for prompts defined in source code
  • Prompts explorer that allows to find all prompts and quickly navigate
  • Prompt evals to automatically test project prompts

Claude Code Instructions

React Component Code Style

Use the following pattern for React components:

export namespace ComponentName {
  export interface Props {
    // Component props interface
  }
}

export function ComponentName(props: ComponentName.Props) {
  const {
    /* Destructure props here */
  } = props;

  return <div>...</div>;
}

Simplification rules:

  • If component has no props, omit the Props interface and namespace
  • If props are not destructured, omit the destructuring assignment
  • Only include what is actually needed
// Simple component with no props
export function SimpleComponent() {
  return <div>Simple content</div>;
}

This approach provides:

  • Clear namespace organization when needed
  • Type safety with props interface
  • Consistent destructuring pattern
  • Explicit function component definition
  • Minimal boilerplate for simple cases

TypeScript Class Code Style

Use the following patterns for TypeScript classes:

  • Use #privateName instead of the private keyword when possible
  • Don't add explicit public keyword - methods and properties are public by default
  • Exception: Static members cannot use # syntax, so use private static for those
export class ExampleClass {
  static readonly CONSTANTS = ["value1", "value2"]; // public static (default)
  private static hiddenValue = "secret"; // private static (can't use #)

  #privateProperty: string;
  regularProperty: number; // public by default

  constructor(value: string) {
    this.#privateProperty = value;
    this.regularProperty = 42;
  }

  #privateMethod(): void {
    // private method implementation
  }

  regularMethod(): string {
    // public by default
    return this.#privateProperty;
  }
}

Benefits:

  • Modern JavaScript/TypeScript syntax
  • True privacy (not just TypeScript compile-time)
  • Cleaner code without redundant public keywords
  • Consistent with current JavaScript standards

Package Manager

  • Use pnpm as the package manager for this project
  • Always use pnpm commands instead of npm or npx
  • Example: pnpm run watch, pnpm install, pnpm run build

Code Formatting

  • Use Prettier with default settings (configured in .prettierrc)
  • When executing multi-step plans, format code once after the entire plan is executed rather than on each individual step
  • This improves efficiency and reduces unnecessary intermediate formatting operations
  • Always run pnpm turbo format after completing a plan to ensure consistent code formatting across the entire codebase

Debugging and Logging

Console Logging Best Practices

  • Always use JSON.stringify() for object logging in both webview and extension code
  • This ensures objects are fully expanded in the console without needing manual expansion
  • Example: console.log("Debug info", JSON.stringify({ property: value })) instead of console.log("Debug info", { property: value })
  • This is especially important for VS Code extension development where console object inspection can be limited

Specification Documents

Planning with Specifications

  • Always consult relevant specs when planning work in any monorepo package
  • Check both the package-level ./specs directory and the root ./specs directory for applicable specifications
  • Use the 000-index.md file in each specs directory to quickly find relevant specifications
  • Specifications contain detailed requirements, implementation decisions, and technical context

Spec Management

  • Keep 000-index.md files updated when adding or modifying specifications
  • Each monorepo package has its own specs directory: parser/specs, vscode/extension/specs, vscode/webview/specs
  • Follow established naming conventions: 001-feature.md, 002-component.md, etc.
  • ALWAYS update the corresponding 000-index.md file when creating new specifications to maintain consistency

CLAUDE.md Style

Markdown Code Style

  • Use links for file references instead of plain text
  • Example: package.json instead of package.json
  • This makes files clickable and easier to navigate in IDEs

Task Lists

  • Use checkbox syntax for tasks and future plans: - [ ] for incomplete, - [x] for completed
  • This provides clear visual status and allows for easy tracking of progress

Content Guidelines

  • When adding new instructions, ensure they are not redundant with existing content
  • Check that new guidelines do not contradict previous instructions
  • Keep examples consistent with established patterns and naming conventions
  • Remove or update conflicting information when making changes