Seed a cline memory-bank

.clinerules/memory-bank.md

@@ -0,0 +1,167 @@
+# Cline's Memory Bank
+
+I am Cline, an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional.
+
+## Memory Bank Structure
+
+The Memory Bank consists of core files and optional context files, all in Markdown format. Files build upon each other in a clear hierarchy:
+
+```mermaid
+flowchart TD
+    PB[projectbrief.md] --> PC[productContext.md]
+    PB --> SP[systemPatterns.md]
+    PB --> TC[techContext.md]
+
+    PC --> AC[activeContext.md]
+    SP --> AC
+    TC --> AC
+
+    AC --> P[progress.md]
+```
+
+### Core Files (Required)
+
+1. `projectbrief.md`
+
+    - Foundation document that shapes all other files
+    - Created at project start if it doesn't exist
+    - Defines core requirements and goals
+    - Source of truth for project scope
+
+2. `productContext.md`
+
+    - Why this project exists
+    - Problems it solves
+    - How it should work
+    - User experience goals
+
+3. `activeContext.md`
+
+    - Current work focus
+    - Recent changes
+    - Next steps
+    - Active decisions and considerations
+    - Important patterns and preferences
+    - Learnings and project insights
+
+4. `systemPatterns.md`
+
+    - System architecture
+    - Key technical decisions
+    - Design patterns in use
+    - Component relationships
+    - Critical implementation paths
+
+5. `techContext.md`
+
+    - Technologies used
+    - Development setup
+    - Technical constraints
+    - Dependencies
+    - Tool usage patterns
+
+6. `progress.md`
+    - What works
+    - What's left to build
+    - Current status
+    - Known issues
+    - Evolution of project decisions
+
+### Per-component documentation (Optional)
+
+The `memory-bank/components` directory contains detailed documentation about each component in this project. With regards to maintaining and updating it, treat it just like any other part of the memory-bank.
+
+Key elements:
+
+-   Component-specific documentation is stored in `memory-bank/components/` directory
+-   Each component gets its own markdown file with detailed information about its purpose, architecture, and implementation
+-   Component documentation should focus on both service components that implement business logic and API components that define interfaces
+-   Documentation follows a consistent structure with sections for Overview, Purpose, Architecture, Key Features, etc.
+-   API component documentation should include a "Code Generation and Building" section that explains:
+    -   How to regenerate code from protobuf definitions
+    -   The implementation details of the generation process
+    -   How to build components that depend on the API after regeneration
+
+### Additional Context
+
+Create additional files/folders within memory-bank/ when they help organize:
+
+-   Complex feature documentation
+-   Integration specifications
+-   API documentation
+-   Testing strategies
+-   Deployment procedures
+
+## Core Workflows
+
+### Plan Mode
+
+```mermaid
+flowchart TD
+    Start[Start] --> ReadFiles[Read Memory Bank]
+    ReadFiles --> CheckFiles{Files Complete?}
+
+    CheckFiles -->|No| Plan[Create Plan]
+    Plan --> Document[Document in Chat]
+
+    CheckFiles -->|Yes| Verify[Verify Context]
+    Verify --> Strategy[Develop Strategy]
+    Strategy --> Present[Present Approach]
+```
+
+### Act Mode
+
+```mermaid
+flowchart TD
+    Start[Start] --> Context[Check Memory Bank]
+    Context --> Update[Update Documentation]
+    Update --> Execute[Execute Task]
+    Execute --> Document[Document Changes]
+```
+
+## Documentation Updates
+
+Memory Bank updates occur when:
+
+1. Discovering new project patterns
+2. After implementing significant changes
+3. When user requests with **update memory bank** (MUST review ALL files)
+4. When context needs clarification
+
+```mermaid
+flowchart TD
+    Start[Update Process]
+
+    subgraph Process
+        P1[Review ALL Files]
+        P2[Document Current State]
+        P3[Clarify Next Steps]
+        P4[Document Insights & Patterns]
+
+        P1 --> P2 --> P3 --> P4
+    end
+
+    Start --> Process
+```
+
+Note: When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on activeContext.md and progress.md as they track current state.
+
+## Memory Management
+
+-   Be mindful of space in memory bank files
+-   Deleting irrelevant memories is a good thing
+-   Follow short-term vs. long-term memory strategy:
+    -   Short-term memory (activeContext.md, progress.md): Detailed, recent, specific
+    -   Long-term memory (systemPatterns.md, techContext.md, projectbrief.md): Compressed, patterns, principles
+-   Apply this strategy on every interaction with the memory bank
+-   Use "compress memory bank" trigger to perform a compression run
+
+When compressing memory bank files:
+
+1. Focus on patterns over instances
+2. Use tables and summaries instead of exhaustive lists
+3. Keep only the most relevant and recent information in short-term memory
+4. Distill important insights into long-term memory
+5. Delete outdated or redundant information
+
+REMEMBER: After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy.

memory-bank/activeContext.md

@@ -0,0 +1,19 @@
+# Active Context
+
+*   **Current Focus:** Initializing the memory bank based on the project's `README.md`.
+*   **Recent Changes:**
+    *   Created the `memory-bank` directory.
+    *   Created core memory bank files (`projectbrief.md`, `productContext.md`, `activeContext.md`, `systemPatterns.md`, `techContext.md`, `progress.md`).
+    *   Populated `projectbrief.md` and `productContext.md` with initial content derived from `README.md`.
+    *   Updated `techContext.md` with information about Leeway's GitHub Actions integration.
+*   **Next Steps:**
+    *   Continue exploring and documenting Leeway's CI/CD integration capabilities.
+    *   Populate `systemPatterns.md` with architecture details from `README.md`.
+    *   Populate `progress.md` with the initial project state.
+*   **Active Decisions:** Using the `README.md` as the primary source for initial memory bank population, supplemented by code analysis for specific features.
+*   **Patterns & Preferences:** Following the structure defined in `.clinerules/memory-bank.md`.
+*   **Learnings & Insights:** 
+    *   The `README.md` provides a good overview of the project's purpose, structure, and core features (build system, caching, supported languages, CLI).
+    *   Leeway has built-in GitHub Actions integration via the `--report-github` flag, which writes build success/failure status to GitHub Actions outputs using the format `{pkg.FilesystemSafeName()}={success}`.
+    *   The `FilesystemSafeName()` function converts component:package format to component--package (e.g., `backend:docker` becomes `backend--docker`).
+    *   Currently, Leeway only reports boolean success/failure values to GitHub Actions, not other build artifacts or metadata.

memory-bank/productContext.md

@@ -0,0 +1,5 @@
+# Product Context
+
+*   **Problem Solved:** Traditional build systems can be slow, require manual versioning, and struggle with reproducibility across different environments. Leeway addresses this by providing a fast, automated, and reliable build process specifically for Go, Yarn, and Docker projects. It eliminates manual versioning by using content-based hashing and speeds up builds through aggressive local and remote caching and parallel execution.
+*   **How it Works:** Leeway operates on a three-level structure: Workspace, Components, and Packages. It analyzes source files, dependencies (`BUILD.yaml`, `go.mod`, `yarn.lock`, etc.), and configuration (`WORKSPACE.yaml`) to compute unique, content-based versions for each package. It builds packages in isolation, manages dependencies, and utilizes local and remote caches (GCS/S3) to avoid redundant work. Builds are parallelized based on the dependency graph. It offers specific configurations for Go, Yarn, and Docker package types, along with generic packages and executable scripts. Build arguments allow for parameterization.
+*   **User Experience Goals:** Provide a seamless and efficient build experience for developers. Offer a clear and powerful CLI for inspecting the workspace, managing builds, and understanding dependencies. Ensure builds are fast and reproducible. Simplify the setup and configuration for supported project types.

memory-bank/progress.md

@@ -0,0 +1,29 @@
+# Progress
+
+*   **What Works:**
+    *   Core Leeway build system functionality as described in `README.md`.
+    *   Support for Go, Yarn, Docker, and generic packages.
+    *   Local and remote caching (GCS/S3).
+    *   Parallel builds based on dependency graph.
+    *   Build arguments and constants.
+    *   Component scripts.
+    *   Dynamic package generation (`BUILD.js`).
+    *   Rich CLI for inspection and interaction.
+    *   Basic provenance generation (SLSA v0.2 - Experimental).
+    *   Installation via pre-built binaries.
+*   **What's Left:** (Based on initial assessment - requires deeper code analysis for specifics)
+    *   Further development or refinement of existing features.
+    *   Addressing any potential bugs or limitations not documented in the README.
+    *   Stabilizing experimental features (e.g., Provenance).
+    *   Potential new features or improvements.
+*   **Current Status:** Project appears functional and released (mentions releases on GitHub). The core build system is implemented. Memory bank has just been initialized.
+*   **Known Issues:**
+    *   Windows is not supported.
+    *   Requires GNU `coreutils` on macOS.
+    *   Provenance feature is experimental.
+    *   Potential performance issues with very large provenance bundles.
+*   **Decision Evolution:** (Initial state - no evolution tracked yet)
+    *   Decision to use content-based hashing for versioning.
+    *   Decision to support Go, Yarn, Docker initially.
+    *   Decision to implement two-level caching.
+    *   Decision to use YAML for configuration.

memory-bank/projectbrief.md

@@ -0,0 +1,6 @@
+# Project Brief
+
+*   **Core Requirements:** A heavily caching build system for Go, Yarn, and Docker projects featuring source-dependent versions, two-level caching (local and remote), parallel builds, built-in language support, build arguments, and a rich CLI.
+*   **Goals:** Provide fast, reliable, and reproducible builds by automatically managing package versions based on content and dependencies, leveraging caching, and enabling parallel execution. Simplify the build process for Go, Yarn, and Docker projects.
+*   **Scope:** Focuses on building Go, Yarn, and Docker projects within a defined workspace structure. Manages dependencies between packages within the workspace. Supports Linux and macOS environments. Includes features like build arguments, scripts, provenance generation (experimental), and workspace inspection via CLI. Excludes Windows support (explicitly mentioned).
+*   **Source of Truth:** This document serves as the foundation for project scope and direction.

memory-bank/systemPatterns.md

@@ -0,0 +1,19 @@
+# System Patterns
+
+*   **System Architecture:** Monolithic CLI application (`leeway`) managing builds within a structured workspace. The workspace contains components, and components define packages.
+*   **Key Technical Decisions:**
+    *   **Content-based Versioning:** Package versions are derived from source content, dependencies, and configuration, eliminating manual versioning.
+    *   **Two-Level Caching:** Utilizes both local and remote (GCS/S3) caching to accelerate builds.
+    *   **Dependency Graph:** Builds are parallelized based on the explicit dependency graph defined between packages.
+    *   **Workspace Structure:** Enforces a three-level hierarchy (Workspace -> Component -> Package) marked by `WORKSPACE.yaml` and `BUILD.yaml` files.
+    *   **Environment Manifest:** Captures tool versions and platform info to ensure build reproducibility across environments.
+*   **Design Patterns:**
+    *   **Configuration Files:** Uses YAML (`WORKSPACE.yaml`, `BUILD.yaml`) for defining workspace, components, and packages.
+    *   **Build Scripts:** Supports `BUILD.js` for dynamic package generation.
+    *   **CLI Interface:** Provides a rich command-line interface for interaction and inspection.
+*   **Component Relationships:** Packages within components declare dependencies (`deps`) on other packages. Scripts can depend on packages. Docker packages can depend on other Docker packages, passing image names via build arguments.
+*   **Critical Implementation Paths:**
+    *   **Build Execution:** `leeway build <target>` triggers dependency resolution, cache checking, parallel execution, and caching of results.
+    *   **Versioning:** Hashing sources, dependencies, config, and build arguments to compute a unique package version.
+    *   **Caching:** Checking local and remote caches before building; storing results after successful builds.
+    *   **Provenance Generation (Experimental):** Creating SLSA-compliant attestations during the build process.

memory-bank/techContext.md

@@ -0,0 +1,29 @@
+# Tech Context
+
+*   **Technologies Used:**
+    *   Primary Language: Go
+    *   Build Targets: Go, Yarn (Node.js), Docker
+    *   Configuration: YAML (`WORKSPACE.yaml`, `BUILD.yaml`)
+    *   Scripting: Bash (for `scripts`), JavaScript ES5.1 (via Goja for `BUILD.js`)
+    *   Provenance: SLSA v0.2, in-toto attestation bundles (JSONL)
+*   **Development Setup:**
+    *   OS: Linux or macOS required.
+    *   Installation: Download pre-built release binaries.
+    *   Environment Variables: `LEEWAY_WORKSPACE_ROOT` (required), `LEEWAY_REMOTE_CACHE_STORAGE`, `LEEWAY_REMOTE_CACHE_BUCKET`, `LEEWAY_CACHE_DIR`, `LEEWAY_BUILD_DIR`, `LEEWAY_YARN_MUTEX`, `LEEWAY_PROVENANCE_KEYPATH`, `LEEWAY_EXPERIMENTAL`.
+    *   macOS Specific: Requires GNU `coreutils` (`brew install coreutils`).
+    *   Tooling: Assumes Go, Yarn, Docker, and cloud CLIs (gsutil/aws) are installed and configured.
+*   **Technical Constraints:**
+    *   Windows is not supported.
+    *   Relies on external tools being present in the environment.
+    *   Provenance bundle size can impact memory usage (`LEEWAY_MAX_PROVENANCE_BUNDLE_SIZE`).
+*   **Dependencies:**
+    *   Go: Managed via Go Modules (`go.mod`, `go.sum`).
+    *   Yarn: Managed via `yarn.lock`.
+    *   Remote Cache: Google Cloud Storage (GCS) or AWS S3. Requires respective CLI tools (`gsutil`, `aws`).
+    *   Linting (Go): `golangci-lint` (default).
+*   **Tool Usage Patterns:**
+    *   Configuration: Centralized in `WORKSPACE.yaml` (workspace settings, defaults, variants, env manifest) and `BUILD.yaml` (component constants, packages, scripts). Dynamic config via `BUILD.js`. Overrides via `WORKSPACE.args.yaml`.
+    *   Build Commands: Uses standard tool commands (`go build/test/fmt/generate`, `yarn install/build/test`, `docker build`). Allows command overrides in package configs.
+    *   CLI: `leeway` command is the main entry point for building (`build`), inspecting (`collect`, `describe`), running scripts (`run`), managing provenance (`provenance`), etc.
+    *   GitHub Actions Integration: The `--report-github` flag (automatically enabled when `GITHUB_OUTPUT` env var is present) writes build success/failure status to GitHub Actions outputs. Uses the format `{pkg.FilesystemSafeName()}={success}`, where `FilesystemSafeName()` converts component:package format to component--package (e.g., `backend:docker` becomes `backend--docker`). Currently only reports boolean success/failure values.
+    *   Releasing: Uses GoReleaser triggered by Git tags via GitHub Actions.