mirror of
https://github.com/software-mansion/argent.git
synced 2026-09-14 19:27:14 +08:00
Ignacy Łątka
c5c3f7af11
## Summary
- New top-level CLI commands `argent enable <flag>` / `argent disable
<flag>` / `argent flags`.
- Storage is a small JSON file at `~/.argent/flags.json` by default;
`--scope project` writes to `<project-root>/.argent/flags.json` instead.
- `enable` writes `true`. `disable` removes the entry at the chosen
scope (and deletes the file + empty `.argent/` when it becomes the last
flag).
- `isFlagEnabled` walks project → global, so a project entry shadows the
same key in the global file. To opt a single project out of a
globally-enabled flag, hand-edit `<project>/.argent/flags.json` to
`{"flags":{"name":false}}` — there is no CLI for an explicit override.
- The dispatcher routes the new commands to `@argent/cli` exports;
bundling needs no config changes (only `node:fs|path|os`).
## Behaviour
- `argent enable foo` → writes `{ "flags": { "foo": true } }` to global
file.
- `argent disable foo` → removes `foo` from the global file (clean round
trip with `enable`).
- `argent enable foo --scope project` → writes to
`<project-root>/.argent/flags.json`.
- `argent flags` → lists effective state with the winning scope;
`--json` for scripting.
- Project root is the nearest ancestor with `.argent`, `.git`, or
`package.json` — falls back to cwd when none found.
- POSIX `--` separator: `argent enable -- weird-name` is supported.
- Help (`--help` / `-h`), invalid `--scope`, invalid flag names, missing
arg, unknown flags all produce a clear stderr error and `exit 2`.
- Flag-name validation: `/^[a-zA-Z][a-zA-Z0-9._-]*$/`.
- Writes are atomic (tmp file + rename) so concurrent invocations cannot
tear the JSON.
## Reader API
`isFlagEnabled(name)` is exported from `@argent/cli` for future
consumers; it walks project → global and returns `false` when unset.
## Files
- `packages/argent-cli/src/flags.ts` (new) — storage + CLI handlers
- `packages/argent-cli/src/index.ts` — re-exports `enable` / `disable` /
`flags` / `isFlagEnabled` / `FlagScope`
- `packages/argent-cli/test/flags.test.ts` (new) — 41 tests
- `packages/argent-cli/vitest.config.ts` (new)
- `packages/argent-cli/package.json` — description bump
- `packages/argent/src/cli.ts` — dispatcher routes + help text
- `README.md`, `CONTRIBUTING.md` — command tables
## Test plan
- [x] `npm test --workspaces --if-present` → 1085 tests pass (41 in
`@argent/cli`).
- [x] `npm run typecheck:tests --workspaces --if-present` → clean.
- [x] `npm run build` (root `tsc --build`) → clean.
- [x] `npm run build -w @swmansion/argent` (dispatcher + esbuild
bundles) → clean.
- [x] `npx prettier --check .` → clean.
- [x] End-to-end against the built dispatcher in a tmpdir:
- `argent enable my-feature-flag` (global) writes to
`~/.argent/flags.json`.
- `argent enable proj-only --scope project` writes to
`<proj>/.argent/flags.json`.
- `argent disable my-feature-flag` removes the entry; round trip leaves
a clean tree (file + empty `.argent/` removed when no other state lives
there).
- `argent disable foo` preserves sibling flags in the same file.
- `argent flags` lists each flag with the winning scope.
- `argent enable --` errors cleanly; `argent enable -- name-after`
accepts the literal.
- `argent enable foo --scope project` walks up to `.git` /
`package.json` / `.argent`; stray editor configs (`.claude`, `.cursor`,
…) do NOT count as project roots.
- Error paths (`--scope bogus`, no name, `1bad-name`) exit `2` with a
clear message.
183 lines
7.2 KiB
Markdown
183 lines
7.2 KiB
Markdown
# Contributing to Argent
|
|
|
|
Thank you for your interest in contributing to Argent! This guide covers everything you need to get started.
|
|
|
|
## Table of contents
|
|
|
|
- [Requirements](#requirements)
|
|
- [Setting up the dev environment](#setting-up-the-dev-environment)
|
|
- [Project structure](#project-structure)
|
|
- [Building](#building)
|
|
- [Running the project](#running-the-project)
|
|
- [Running tests](#running-tests)
|
|
- [Code style](#code-style)
|
|
- [Submitting a pull request](#submitting-a-pull-request)
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- **macOS** with Xcode installed (required for `xcrun simctl` and iOS simulator support)
|
|
- **Node.js 18+**
|
|
- The `simulator-server` and `ax-service` binaries in `packages/native-devtools-ios/bin/` (arm64 macOS, installed separately via `npx @swmansion/argent install`)
|
|
|
|
---
|
|
|
|
## Setting up the dev environment
|
|
|
|
1. **Fork and clone** the repository:
|
|
|
|
```bash
|
|
git clone https://github.com/software-mansion/argent.git
|
|
cd argent
|
|
```
|
|
|
|
2. **Install dependencies** (npm workspaces installs all packages at once):
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Start the dev environment:**
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
This builds the native devtools dylibs (if the private submodule is available, otherwise uses pre-built binaries), compiles the MCP TypeScript, patches `~/.claude.json` to point at the local MCP, and starts the tool-server from source via `ts-node`. Press `Ctrl+C` to stop — the script automatically restores your global Argent configuration.
|
|
|
|
To use a different port:
|
|
|
|
```bash
|
|
PORT=4000 npm run dev
|
|
```
|
|
|
|
> **Note:** `packages/argent-private` is a private git submodule that holds the ObjC source for the native devtools dylibs. If you don't have SSH access to it, `npm run dev` will use the pre-built dylibs committed to the repository — everything else works normally.
|
|
|
|
That's it — no separate install steps per package are needed.
|
|
|
|
---
|
|
|
|
## Project structure
|
|
|
|
This is an npm workspaces monorepo. All packages live under `packages/`:
|
|
|
|
| Package | Path | Purpose |
|
|
| ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `@argent/registry` | `packages/registry` | Core library: dependency-aware service lifecycle, blueprints, tools, URNs |
|
|
| `@argent/tool-server` | `packages/tool-server` | HTTP API over the registry (port 3001). Registers all blueprints and tools |
|
|
| `@swmansion/argent` | `packages/argent` | Published bin shell — minimal dispatcher + bundled subcommands + native runtime assets |
|
|
| `@argent/tools-client` | `packages/argent-tools-client` | HTTP client + tool-server launcher shared by `@argent/mcp` and `@argent/cli` |
|
|
| `@argent/mcp` | `packages/argent-mcp` | MCP stdio protocol adapter — proxies Claude/Cursor calls to the tool-server |
|
|
| `@argent/cli` | `packages/argent-cli` | Shell CLI commands: `argent run`, `argent tools`, `argent server`, `argent enable`, `argent disable`, `argent flags` |
|
|
| `@argent/installer` | `packages/argent-installer` | Workspace setup logic: `argent init`, `update`, `uninstall` |
|
|
| `@argent/skills` | `packages/skills` | Markdown skill files (prefixed `argent-*`) that instruct AI agents how to use Argent tools |
|
|
| `@argent/native-devtools-ios` | `packages/native-devtools-ios` | Pre-built dylibs for iOS simulator injection (view hierarchy, network inspection). ObjC source lives in `packages/argent-private` _(private submodule)_ |
|
|
|
|
The `tsconfig.json` at the root uses TypeScript project references; `tsconfig.base.json` holds shared compiler options (`strict`, `ES2022`, etc.).
|
|
|
|
---
|
|
|
|
## Building
|
|
|
|
### Local development (recommended)
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Builds everything and starts the tool-server from source. See [Setting up the dev environment](#setting-up-the-dev-environment) for details.
|
|
|
|
### Full build
|
|
|
|
Build all packages at once using TypeScript project references:
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
To build a specific package:
|
|
|
|
```bash
|
|
npm run build -w @argent/registry
|
|
npm run build -w @argent/tool-server
|
|
```
|
|
|
|
To build and bundle the distributable MCP package:
|
|
|
|
```bash
|
|
npm run build -w @swmansion/argent
|
|
# or, to also produce a .tgz tarball:
|
|
npm run pack:mcp
|
|
```
|
|
|
|
---
|
|
|
|
## Running the project
|
|
|
|
For day-to-day development, use `npm run dev` (see [Setting up the dev environment](#setting-up-the-dev-environment)).
|
|
|
|
**Production-like start** (builds bundles first, then starts from compiled output):
|
|
|
|
```bash
|
|
npm run start
|
|
```
|
|
|
|
This builds the registry, then starts the tools server on port 3001.
|
|
|
|
Verify the tools server is up:
|
|
|
|
```bash
|
|
curl http://localhost:3001/tools
|
|
```
|
|
|
|
---
|
|
|
|
## Running tests
|
|
|
|
Tests are written with [Vitest](https://vitest.dev/). Each package has its own test suite.
|
|
|
|
Run tests for a specific package:
|
|
|
|
```bash
|
|
npm test -w @argent/registry
|
|
npm test -w @argent/tool-server
|
|
```
|
|
|
|
Run tests in watch mode during development:
|
|
|
|
```bash
|
|
npm run test:watch -w @argent/registry
|
|
npm run test:watch -w @argent/tool-server
|
|
```
|
|
|
|
---
|
|
|
|
## Code style
|
|
|
|
- **TypeScript strict mode** is enabled across all packages (`"strict": true` in `tsconfig.base.json`). All code must compile without errors.
|
|
- **Target:** ES2022 with CommonJS modules (except `@swmansion/argent` which uses ESM).
|
|
- Prefer explicit types over `any`. Use Zod schemas for runtime validation where the codebase already does so.
|
|
- Keep commits focused. Prefix commit messages with a type: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`. This feeds the auto-generated changelog on release.
|
|
|
|
---
|
|
|
|
## Submitting a pull request
|
|
|
|
1. **Create a branch** from `main` with a descriptive name (e.g. `feat/add-screenshot-tool`, `fix/session-leak`).
|
|
2. **Make your changes.** Keep the scope of a PR small and focused — it's easier to review.
|
|
3. **Ensure the build passes:**
|
|
```bash
|
|
npm run build
|
|
```
|
|
4. **Ensure tests pass** for the packages you touched.
|
|
5. **Write a clear PR title** — it becomes part of the release changelog. Use the same prefix convention as commit messages (`feat:`, `fix:`, etc.).
|
|
6. **Open the PR** against `main` and fill in the description with context on what changed and why.
|
|
7. A maintainer will review and may request changes. Address feedback with new commits (don't force-push after review starts).
|
|
|
|
---
|
|
|
|
## Questions?
|
|
|
|
If you're unsure about something, open a GitHub Discussion or leave a comment on the relevant issue before spending time on a large change.
|