diff --git a/.agents/journal/scribe-journal.md b/.agents/journal/scribe-journal.md index bb8c730..a60abbb 100644 --- a/.agents/journal/scribe-journal.md +++ b/.agents/journal/scribe-journal.md @@ -7,13 +7,18 @@ This journal is used to track documentation debt and planned improvements for th - [x] Add a "Troubleshooting" section to the root `README.md`. - [x] Reconcile CLI documentation with actual source code. - [x] Document missing `skill` and `clean` commands. -- [ ] Add more detailed examples to the Starlight documentation. +- [x] Add more detailed examples to the Starlight documentation. - [ ] Create a "Recipes" section in the Starlight documentation for common use cases. +- [x] Document `doctor` and `status` commands in `cli.mdx`. +- [x] Create `.agents/AGENTS.md` as the single source of truth. +- [x] Add project overview and mono-repo structure to root `README.md`. +- [x] Document all build, lint, test, and release commands in root `README.md`. ## Planned Improvements - [x] Improve `getting-started.mdx` with Node.js package manager installation. - [x] Document mono-repo structure and cross-stack workflow in `contributing.mdx` and `workspaces.mdx`. +- [x] Fix download instructions with version placeholders in docs. - [ ] Create a more comprehensive guide to the `agentsync.toml` configuration file. - [ ] Add a guide for creating custom `agentsync` agents. - [ ] Create a video tutorial for getting started with `agentsync`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8278489..a2ee6fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,8 +11,9 @@ Thank you for your interest in contributing to AgentSync! To maintain high code - If it's documentation, it goes in `website/docs/src/content/docs/`. 3. **Verify your changes**: - **Full Suite**: Run `make verify-all` from the root. This runs all tests, linters, and builds the documentation. - - For Rust: `make rust-test`, `cargo fmt`, and `cargo clippy`. - - For TypeScript: `make js-test`, `make js-build` and `make fmt`. + - For Rust: `make rust-test`, `make rust-build`, and `cargo clippy`. + - For TypeScript: `make js-test` and `make js-build`. + - Formatting: `make fmt` (formats both Rust and TypeScript). 4. **Open a Pull Request** with a clear description of the changes and why they are needed. ## Code Style diff --git a/README.md b/README.md index 1743511..ee80adb 100644 --- a/README.md +++ b/README.md @@ -239,6 +239,7 @@ agentsync doctor [--project-root ] agentsync skill install agentsync skill update agentsync skill uninstall +# agentsync skill list (Currently under development) ``` ### Status @@ -435,62 +436,65 @@ If you need agentsync in CI, you can download the latest version automatically u ## Getting Started (Development) -This project is a monorepo containing a Rust core and a JavaScript/TypeScript wrapper. +This project is a monorepo containing a Rust core and a JavaScript/TypeScript distribution layer. -### Repository Structure +### Monorepo Structure - `src/`: Core logic and CLI implementation in **Rust**. - `npm/agentsync/`: **TypeScript** wrapper used for NPM distribution. - `website/docs/`: Documentation site built with **Starlight**. -- `tests/`: Integration tests for the CLI. +- `.agents/`: Single source of truth for agent configurations and skills. +- `tests/`: Integration and E2E tests for the CLI. ### Prerequisites -- [**Rust**](https://www.rust-lang.org/tools/install) (1.89+ recommended) -- [**Node.js**](https://nodejs.org/) (v24.13.0+ recommended for development) +- [**Rust**](https://www.rust-lang.org/tools/install) (1.89+ recommended, Edition 2024) +- [**Node.js**](https://nodejs.org/) (v24.13.0+ recommended) - [**pnpm**](https://pnpm.io/installation) ### Setup -1. **Install JavaScript dependencies:** - - ```bash - pnpm install - ``` - -2. **Build the Rust binary:** - - ```bash - cargo build - ``` - -### Common Commands - -This project uses a `Makefile` to orchestrate common tasks. - -- **Run Rust tests:** - - ```bash - make rust-test - ``` - -- **Run JavaScript tests:** - - ```bash - make js-test - ``` - -- **Build all components:** - - ```bash - make all - ``` - -- **Format the code:** - - ```bash - make fmt - ``` +1. **Clone the repository**: + ```bash + git clone https://github.com/dallay/agentsync.git + cd agentsync + ``` + +2. **Install all dependencies**: + ```bash + make install + # This runs pnpm install and cargo build + ``` + +### Development Workflow + +#### Rust (Core) +- **Build**: `make rust-build` (or `cargo build`) +- **Test**: `make rust-test` (or `cargo test`) +- **Run**: `make rust-run` (or `cargo run -- `) +- **Lint**: `cargo clippy` + +#### JavaScript / TypeScript (Wrapper & Docs) +- **Build**: `make js-build` (builds the `@dallay/agentsync` package) +- **Test**: `make js-test` (runs type checks and tests) +- **Docs (Dev)**: `make docs-dev` (starts Starlight dev server) + +### Common Commands (Makefile) + +We use a `Makefile` to orchestrate tasks across both stacks: + +| Command | Description | +| :--- | :--- | +| `make all` | Install dependencies and build all components | +| `make verify-all` | **Recommended before PRs**: Runs all builds, tests, and linters | +| `make install` | Install JS dependencies and build Rust core | +| `make fmt` | Format both Rust (rustfmt) and JS/TS (biome) | +| `make rust-test` | Run all Rust unit and integration tests | +| `make rust-run` | Build and run the Rust CLI project | +| `make js-test` | Run all JavaScript tests and type checks | +| `make e2e-test` | Run end-to-end tests using Docker | +| `make docs-build` | Build the documentation site | +| `make clean` | Remove build artifacts and temporary files | ## Troubleshooting diff --git a/npm/agentsync/README.md b/npm/agentsync/README.md index b587a7f..3358b07 100644 --- a/npm/agentsync/README.md +++ b/npm/agentsync/README.md @@ -76,6 +76,18 @@ Remove previously created symbolic links: agentsync clean ``` +#### Status and Diagnostics: + +Check the status of managed symlinks or run a diagnostic health check: + +```bash +# Verify the state of symlinks and report drift +agentsync status + +# Run a comprehensive diagnostic and health check +agentsync doctor +``` + ๐ŸŽฏ **Example Workflows**: - **Programmatic Usage in Node.js**: @@ -107,56 +119,47 @@ agentsync clean ## MCP & Skills - AgentSync supports MCP generation for multiple agents (Claude, Copilot, Gemini, Cursor, VS Code, OpenCode). The canonical list and file locations live in the repo README and in the docs site (guides/mcp). -- Skills live under `.agents/skills/` in the project. +- Skills live under `.agents/skills/` in the project. +- **Manage skills via CLI**: + ```bash + agentsync skill install + agentsync skill update + agentsync skill uninstall + ``` --- ## ๐Ÿ‘ท Development -This package is part of the [AgentSync mono-repo](https://github.com/dallay/agentsync). It serves as a Node.js wrapper for the high-performance Rust core. +This package is part of the [AgentSync mono-repo](https://github.com/dallay/agentsync). It serves as a Node.js distribution layer for the high-performance Rust core. ### Prerequisites -- [pnpm](https://pnpm.io/): Dependency manager. -- [Node.js](https://nodejs.org/) >= 24.13.0 (for development). -- [Rust](https://www.rust-lang.org/): For building the core CLI. - -### Steps - -1. Clone the repository: +- [**pnpm**](https://pnpm.io/): Dependency manager. +- [**Node.js**](https://nodejs.org/) >= 24.13.0. +- [**Rust**](https://www.rust-lang.org/): For building the core CLI (1.89+). - ```bash - git clone https://github.com/dallay/agentsync.git - cd agentsync - ``` +### Setup and Build -2. Install dependencies: +From the monorepo root: +1. **Install dependencies and build core**: ```bash - pnpm install + make install ``` -3. Build: - +2. **Build the NPM package**: ```bash make js-build - # or - pnpm run build ``` -4. Run tests and type checks: - - ```bash - make js-test - # or - pnpm run typecheck - ``` +### Common Commands -5. Format: +- **Run tests and type checks**: `make js-test` +- **Format code**: `make fmt` +- **Full verification**: `make verify-all` - ```bash - make fmt - ``` +For more details on the Rust core development, see the [main README](https://github.com/dallay/agentsync/blob/main/README.md). --- diff --git a/website/docs/src/content/docs/guides/contributing.mdx b/website/docs/src/content/docs/guides/contributing.mdx index 80bf8a9..fd4eeab 100644 --- a/website/docs/src/content/docs/guides/contributing.mdx +++ b/website/docs/src/content/docs/guides/contributing.mdx @@ -3,7 +3,7 @@ title: Contributing description: Guidelines for contributing to the agentsync project. --- -Thank you for your interest in contributing to AgentSync. To maintain high code quality and consistency, please follow these guidelines. +Thank you for your interest in contributing to AgentSync! To maintain high code quality and consistency, please follow these guidelines. ## Development Workflow @@ -14,8 +14,9 @@ Thank you for your interest in contributing to AgentSync. To maintain high code - If it's documentation, it goes in `website/docs/src/content/docs/`. 3. **Verify your changes**: - **Full Suite**: Run `make verify-all` from the root. This runs all tests, linters, and builds the documentation. - - For Rust: `make rust-test`, `cargo fmt`, and `cargo clippy`. - - For TypeScript: `make js-test`, `make js-build` and `make fmt`. + - For Rust: `make rust-test`, `make rust-build`, and `cargo clippy`. + - For TypeScript: `make js-test` and `make js-build`. + - Formatting: `make fmt` (formats both Rust and TypeScript). 4. **Open a Pull Request** with a clear description of the changes and why they are needed. ## Code Style diff --git a/website/docs/src/content/docs/guides/getting-started.mdx b/website/docs/src/content/docs/guides/getting-started.mdx index 74e6f47..b6afef5 100644 --- a/website/docs/src/content/docs/guides/getting-started.mdx +++ b/website/docs/src/content/docs/guides/getting-started.mdx @@ -57,21 +57,25 @@ bunx @dallay/agentsync apply ### From GitHub Releases -Download the latest release for your platform: +Download the latest release for your platform from the [GitHub Releases](https://github.com/dallay/agentsync/releases) page. + +> **Note:** In the examples below, replace `` with the actual version tag you wish to download (e.g., `1.28.0`). #### macOS (Apple Silicon) ```bash -curl -LO https://github.com/dallay/agentsync/releases/latest/download/agentsync-aarch64-apple-darwin.tar.gz -tar xzf agentsync-aarch64-apple-darwin.tar.gz +# Replace with the actual version number +curl -LO https://github.com/dallay/agentsync/releases/download/v/agentsync--aarch64-apple-darwin.tar.gz +tar xzf agentsync--aarch64-apple-darwin.tar.gz sudo mv agentsync-*/agentsync /usr/local/bin/ ``` #### Linux (x86_64) ```bash -curl -LO https://github.com/dallay/agentsync/releases/latest/download/agentsync-x86_64-unknown-linux-gnu.tar.gz -tar xzf agentsync-x86_64-unknown-linux-gnu.tar.gz +# Replace with the actual version number +curl -LO https://github.com/dallay/agentsync/releases/download/v/agentsync--x86_64-unknown-linux-gnu.tar.gz +tar xzf agentsync--x86_64-unknown-linux-gnu.tar.gz sudo mv agentsync-*/agentsync /usr/local/bin/ ``` diff --git a/website/docs/src/content/docs/index.mdx b/website/docs/src/content/docs/index.mdx index ef6b6ed..51f0d44 100644 --- a/website/docs/src/content/docs/index.mdx +++ b/website/docs/src/content/docs/index.mdx @@ -70,9 +70,9 @@ import { Code } from '@astrojs/starlight/components'; ## Quick Start - with the actual version (e.g., 1.28.0) +curl -LO https://github.com/dallay/agentsync/releases/download/v/agentsync--aarch64-apple-darwin.tar.gz +tar xzf agentsync--aarch64-apple-darwin.tar.gz sudo mv agentsync-*/agentsync /usr/local/bin/ # Initialize and apply diff --git a/website/docs/src/content/docs/reference/cli.mdx b/website/docs/src/content/docs/reference/cli.mdx index 7ca9444..32e3a36 100644 --- a/website/docs/src/content/docs/reference/cli.mdx +++ b/website/docs/src/content/docs/reference/cli.mdx @@ -191,14 +191,36 @@ Human-friendly output uses colors and statuses: - `! Missing` โ€” destination does not exist - `ยท Exists but not a symlink` โ€” a regular file or directory exists at the destination -Exit codes +Exit codes: - `0` โ€” no problems detected - `1` โ€” one or more issues found (suitable to fail CI builds) -Examples -- Human readable: - - `agentsync status` -- JSON for CI: - - `agentsync status --json` -- With custom project root: - - `agentsync status --project-root /path/to/repo --json` +Examples: +- Human readable: `agentsync status` +- JSON for CI: `agentsync status --json` +- With custom project root: `agentsync status --project-root /path/to/repo --json` + +--- + +### `doctor` + +Run diagnostic and health checks for the AgentSync environment. + +```bash +agentsync doctor [FLAGS] +``` + +**Flags**: +- `--project-root `: Project root directory (defaults to current directory). + +**Diagnostics performed**: +1. **Config Loading**: Verifies that `agentsync.toml` can be found and parsed correctly. +2. **Source Directory**: Checks if the configured `source_dir` exists. +3. **Target Sources**: Verifies that all files/directories referenced as `source` in the config actually exist. +4. **Destination Conflicts**: Detects duplicate destinations or overlapping paths (where one destination is a parent of another). +5. **MCP Servers**: Audits configured MCP servers to ensure their `command` executables are available in the system `PATH`. +6. **Gitignore Audit**: Verifies if the `.gitignore` file has the managed AgentSync section and if it is up to date with all required entries. + +**Exit codes**: +- `0` โ€” all checks passed +- `1` โ€” one or more issues detected diff --git a/website/docs/src/content/docs/reference/workspaces.mdx b/website/docs/src/content/docs/reference/workspaces.mdx index 30a2d64..9ad1dcd 100644 --- a/website/docs/src/content/docs/reference/workspaces.mdx +++ b/website/docs/src/content/docs/reference/workspaces.mdx @@ -10,8 +10,8 @@ description: Detailed guide to the repository structure and polyglot development - `src/`: Core logic and CLI implementation in **Rust**. - `npm/agentsync/`: **TypeScript** wrapper used for NPM distribution. - `website/docs/`: Documentation site built with **Starlight**. -- `website/`: Main project website. -- `tests/`: Integration tests for the CLI. +- `.agents/`: Single source of truth for agent configurations and skills. +- `tests/`: Integration and E2E tests for the CLI. --- @@ -24,9 +24,9 @@ The core logic is written in Rust for speed, safety, and easy distribution as a - **Key Commands**: ```bash - cargo build # Build debug binary - cargo test # Run unit and integration tests - cargo run # Run the CLI locally + make rust-build # Build core binary + make rust-test # Run unit and integration tests + make rust-run # Run the CLI locally ``` - **Error Handling**: Uses `thiserror` for custom errors and `anyhow` for application-level error handling. @@ -35,15 +35,15 @@ The core logic is written in Rust for speed, safety, and easy distribution as a ## JavaScript Workspace (Distribution) -The JS workspace acts as a wrapper to provide an easy installation path via `pnpm/npm`. It manages platform-specific binary downloads. +The JS workspace provides a Node.js distribution layer and managed binary downloads for different platforms. - **Tools**: pnpm, TypeScript, Make - **Location**: `npm/agentsync/` - **Key Commands**: ```bash - pnpm run typecheck # Verify types - pnpm run build # Compile TypeScript to JS + make js-test # Verify types and run JS tests + make js-build # Compile TypeScript to JS ``` - **Strictness**: We enforce strict TypeScript configurations. Avoid `any` at all costs.