What Is the Role of the `freebuff/` Workspace in the CodebuffAI/freebuff Repository?

The freebuff/ workspace serves as the dedicated container for the Freebuff CLI product, isolating the command-line interface's TypeScript source code, build pipeline, end-to-end test suite, and release automation from the broader monorepo.

The freebuff/ directory within CodebuffAI/freebuff functions as the autonomous workspace for the Freebuff AI coding assistant's command-line tool. This architectural isolation allows the CLI to maintain its own dependency tree, compilation scripts, and version lifecycle independent of other components. Developers interact with this workspace when compiling platform-specific binaries, validating functionality through integration tests, or publishing new versions to the npm registry.

CLI Source of Truth and Build System

The workspace houses the canonical TypeScript implementation of the CLI and its compilation toolchain. In freebuff/package.json, npm scripts define entry points for development tasks, while freebuff/cli/build.ts contains the logic for transpiling source code into platform-specific executables.

Running the build script produces a binary named freebuff optimized for the host operating system:

# From the repository root

bun freebuff/cli/build.ts 1.0.0

This command invokes the build pipeline defined in freebuff/cli/build.ts, which handles bundling and binary generation for the target platform.

End-to-End Test Infrastructure

The workspace maintains a comprehensive E2E testing suite under freebuff/e2e/tests/ to validate CLI behavior across critical scenarios like startup sequences, version handling, and slash-command processing. These tests verify that the compiled binary performs correctly in real-world usage patterns before any release.

Execute the full test matrix using the workspace's npm scripts:

# Install dependencies first

bun install

# Build the binary and run all E2E tests

bun run e2e

The e2e script defined in freebuff/package.json orchestrates build:binary followed by the test runner, ensuring tests always execute against the latest compilation rather than a stale artifact.

Automated Release Pipeline

Release management is fully automated within the workspace through freebuff/cli/release.ts. This script handles version bumping, binary recompilation, and npm publication in a single atomic operation.

Publish a new version by invoking the release script with the target version number:

# Bump version in the CLI code, then:

bun freebuff/cli/release.ts 1.2.3

The script updates the version field in freebuff/package.json, triggers the build process via cli/build.ts, and publishes the resulting package to the npm registry. This automation ensures users can install the CLI globally via npm install -g freebuff with guaranteed consistency between the source and distributed binary.

Key Files and Directory Structure

Understanding the workspace layout is essential for contributing to CLI development:

• freebuff/package.json – Defines workspace boundaries, npm scripts (release, build:binary, e2e), and dependencies while marking the directory as private to prevent accidental source publication.
• freebuff/cli/build.ts – TypeScript compilation logic that generates the platform-specific binary.
• freebuff/cli/release.ts – Automation script for versioning, building, and npm publication.
• freebuff/e2e/tests/ – Directory containing startup, version, and command integration tests.
• freebuff/README.md – Developer documentation covering installation procedures and the "Building from Source" workflow.

Summary

• The freebuff/ workspace isolates the CLI component from the broader monorepo, providing clean architectural boundaries for independent development.
• Binary generation occurs via bun freebuff/cli/build.ts, producing optimized executables for the host platform.
• E2E testing lives in freebuff/e2e/tests/ and executes through npm scripts like bun run e2e, validating startup, version, and command behaviors.
• Release automation is handled by cli/release.ts, which orchestrates version bumps, rebuilds, and npm publication.
• Configuration in freebuff/package.json marks the workspace as private while exposing public CLI scripts for contributors.

Frequently Asked Questions

How do I build the Freebuff CLI binary from source?

Execute bun freebuff/cli/build.ts <version> from the repository root. This compiles the TypeScript source into a native binary named freebuff for your current platform. The script resides in freebuff/cli/build.ts and handles all bundling operations without requiring global TypeScript installation.

Where are the CLI end-to-end tests located?

All E2E tests are stored in freebuff/e2e/tests/ within the workspace. These files validate critical user flows including startup behavior, version reporting, and slash-command support. Run them via bun run e2e after installing dependencies with bun install, which ensures the binary is freshly built before testing.

What does the release script automate?

The freebuff/cli/release.ts script automates the entire publication workflow. It updates the version string in freebuff/package.json, rebuilds the binary using cli/build.ts, and publishes the package to npm. This ensures that every release is built from a clean, version-locked state and that the distributed binary matches the tagged source code exactly.

Is the freebuff/ workspace itself published to npm?

No, the workspace directory is explicitly marked as private in freebuff/package.json to prevent accidental publication of the source code. Only the compiled CLI binary built within the workspace is published to npm as the freebuff package. The workspace boundary ensures that build tools, test files, and development dependencies remain separate from the lean production artifact that users install.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}