Ai docs

CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Plasma Compose** is a dependency composition tool that operates as a plugin for the Launchr CLI framework. It enables developers to manage project dependencies through a declarative `plasma-compose.yaml` file, fetching and merging dependencies from Git repositories and HTTP archives with sophisticated conflict resolution strategies.
+
+## Development Commands
+
+### Build and Test
+```bash
+# Install dependencies
+make deps
+
+# Run tests
+make test
+
+# Build application
+make build
+
+# Run linter
+make lint
+
+# Complete build process (deps + test + build)
+make all
+
+# Install to GOPATH
+make install
+```
+
+### Debug Builds
+Set `DEBUG=1` environment variable for development builds with debug symbols.
+
+## Architecture
+
+### Core Components
+
+1. **Plugin Integration** (`plugin.go`): Launchr CLI plugin that registers four actions: `compose`, `compose:add`, `compose:update`, `compose:delete`
+
+2. **Composition Engine** (`compose/compose.go`): Main orchestrator managing working directories (`.compose/packages`, `.compose/build`) and cleanup
+
+3. **Download Manager** (`compose/downloadManager.go`): Handles Git and HTTP sources with recursive dependency resolution and keyring authentication
+
+4. **Builder** (`compose/builder.go`): Implements filesystem merging with topological sorting for dependency ordering and multiple merge strategies
+
+5. **Configuration** (`compose/yaml.go`): Parses `plasma-compose.yaml` files and defines data structures
+
+### Key Dependencies
+
+- **Launchr framework**: CLI framework integration
+- **go-git**: Git repository operations
+- **huh**: Interactive TUI forms
+- **keyring**: Secure credential management
+- **topsort**: Dependency ordering
+- **yaml.v3**: Configuration parsing
+
+### Merge Strategies
+
+Four conflict resolution strategies:
+- `overwrite-local-file`: Package files override local files
+- `remove-extra-local-files`: Remove local files not in packages
+- `ignore-extra-package-files`: Skip package files not present locally
+- `filter-package-files`: Include only specific paths from packages
+
+### Working Directories
+
+- `.compose/packages`: Downloaded packages storage
+- `.compose/build`: Final composed filesystem output
+- `plasma-compose.yaml`: Project dependency configuration
+
+## Configuration Structure
+
+```yaml
+name: project-name
+dependencies:
+  - name: package-name
+    source:
+      type: git|http
+      url: https://github.com/user/repo.git
+      ref: branch-or-tag
+      strategy:
+        - name: overwrite-local-file
+          path: ["specific/paths"]
+```
+
+## Requirements
+
+- Go 1.24.0+
+- golangci-lint v1.64.5 for linting
+- CGO disabled for static builds

GEMINI.md

@@ -0,0 +1,89 @@
+# Gemini Code Assistant Project Overview
+
+## Project Description
+
+**Plasma Compose** is a dependency composition tool that operates as a plugin for the Launchr CLI framework. It enables developers to manage project dependencies through a declarative `plasma-compose.yaml` file, fetching and merging dependencies from Git repositories and HTTP archives with sophisticated conflict resolution strategies.
+
+## Development Commands
+
+### Build and Test
+```bash
+# Install dependencies
+make deps
+
+# Run tests
+make test
+
+# Build application
+make build
+
+# Run linter
+make lint
+
+# Complete build process (deps + test + build)
+make all
+
+# Install to GOPATH
+make install
+```
+
+### Debug Builds
+Set `DEBUG=1` environment variable for development builds with debug symbols.
+
+## Architecture
+
+### Core Components
+
+1. **Plugin Integration** (`plugin.go`): Launchr CLI plugin that registers four actions: `compose`, `compose:add`, `compose:update`, `compose:delete`
+
+2. **Composition Engine** (`internal/composer/composer.go`): Main orchestrator managing working directories (`.compose/packages`, `.compose/build`) and cleanup
+
+3. **Download Manager** (`internal/downloader/downloader.go`): Handles Git and HTTP sources with recursive dependency resolution and keyring authentication
+
+4. **Builder** (`internal/builder/builder.go`): Implements filesystem merging with topological sorting for dependency ordering and multiple merge strategies
+
+5. **Configuration** (`internal/config/yaml.go`): Parses `plasma-compose.yaml` files and defines data structures
+
+### Key Dependencies
+
+- **Launchr framework**: CLI framework integration
+- **go-git**: Git repository operations
+- **huh**: Interactive TUI forms
+- **keyring**: Secure credential management
+- **topsort**: Dependency ordering
+- **yaml.v3**: Configuration parsing
+
+### Merge Strategies
+
+Four conflict resolution strategies:
+- `overwrite-local-file`: Package files override local files
+- `remove-extra-local-files`: Remove local files not in packages
+- `ignore-extra-package-files`: Skip package files not present locally
+- `filter-package-files`: Include only specific paths from packages
+
+### Working Directories
+
+- `.compose/packages`: Downloaded packages storage
+- `.compose/build`: Final composed filesystem output
+- `plasma-compose.yaml`: Project dependency configuration
+
+## Configuration Structure
+
+```yaml
+name: project-name
+dependencies:
+  - name: package-name
+    source:
+      type: git|http
+      url: https://github.com/user/repo.git
+      ref: branch-or-tag
+      strategy:
+        - name: overwrite-local-file
+          path: ["specific/paths"]
+```
+
+## Requirements
+
+- Go 1.24.0+
+- golangci-lint v1.64.5 for linting
+- CGO disabled for static builds