diff --git a/00_STATE.md b/00_STATE.md new file mode 100644 index 0000000..2842dc2 --- /dev/null +++ b/00_STATE.md @@ -0,0 +1,64 @@ +# 00_STATE.md — agentmail-cli + +## Repository Status + +| Field | Value | +| ----- | ----- | +| **Upstream** | agentmail-to/agentmail-cli | +| **Fork** | okwn/agentmail-cli (cloned to /root/oss-pr-campaign/repos/agentmail-cli) | +| **Archived** | false | +| **License** | Apache-2.0 | +| **Language** | Go | +| **Default Branch** | main | +| **Stars** | 21 | +| **Forks** | 7 | +| **Open Issues** | 3 | +| **Open PRs** | 2 | + +## Current Branch + +- Local: `main` +- Upstream: `upstream/main` +- All remotes: `origin/*` (fork), `upstream/*` + +## CI Status + +- `.github/workflows/ci.yml` — lint, build, test jobs on push/PR +- `.github/workflows/publish-release.yml` +- `.github/workflows/release-doctor.yml` +- `.github/workflows/auto-merge-release.yml` +- Go 1.25, depot-ubuntu-24.04 or ubuntu-latest + +## Key Scripts + +- `./scripts/bootstrap` — installs Go deps (needs `go` binary) +- `./scripts/lint` — runs lints +- `./scripts/test` — runs `go test ./...` + Windows cross-compile test +- `./scripts/build` — runs goreleaser +- `./scripts/format`, `./scripts/run`, `./scripts/link`, `./scripts/unlink` + +## Go Module + +- Module: `github.com/agentmail-to/agentmail-cli` +- Go version: `1.25` +- Private deps: `github.com/agentmail-to/agentmail-go`, `github.com/stainless-sdks/agentmail-go` +- NPM package: `agentmail-cli@0.4.1` (published to npm) + +## Release + +- Release-please configured (`release-please-config.json`) +- Goreleaser configured (`.goreleaser.yml`) +- Version tracked in: `pkg/cmd/version.go`, `README.md` +- Extra files for release-please: `pkg/cmd/version.go`, `README.md` + +## Build/Release Notes + +- Bootstrap requires `go` binary in PATH (not available in this environment) +- npm `postinstall` script present at `npm/scripts/postinstall.js` +- Binary published via npm (`./npm/bin/agentmail`) + +## Environment + +- `go` binary NOT available in this environment — cannot run tests/bootstrap +- GitHub CLI (`gh`) available for API queries +- Python not noted as required diff --git a/01_REPO_MAP.md b/01_REPO_MAP.md new file mode 100644 index 0000000..0faeb54 --- /dev/null +++ b/01_REPO_MAP.md @@ -0,0 +1,126 @@ +# 01_REPO_MAP.md — agentmail-cli + +## Repository Structure + +``` +agentmail-cli/ +├── cmd/agentmail/ +│ ├── main.go # Entry point +│ └── banner.go # CLI banner +├── pkg/cmd/ # All CLI commands (generated from OpenAPI) +│ ├── cmd.go # Root command, flag definitions, all subcommands +│ ├── version.go # Version constant +│ ├── cmdutil.go # Utility functions +│ ├── flagoptions.go # Flag option handling +│ ├── agent.go / agent_test.go +│ ├── apikey.go / apikey_test.go +│ ├── domain.go / domain_test.go +│ ├── draft.go / draft_test.go +│ ├── inbox.go / inbox_test.go +│ ├── list.go / list_test.go +│ ├── metric.go / metric_test.go +│ ├── organization.go / organization_test.go +│ ├── pod.go / pod_test.go +│ ├── podapikey.go / podapikey_test.go +│ ├── poddomain.go / poddomain_test.go +│ ├── poddraft.go / poddraft_test.go +│ ├── podinbox.go / podinbox_test.go +│ ├── podlist.go / podlist_test.go +│ ├── podmetric.go / podmetric_test.go +│ ├── podthread.go / podthread_test.go +│ ├── thread.go / thread_test.go +│ ├── webhook.go / webhook_test.go +│ └── flagoptions_test.go +├── internal/ +│ ├── apiform/ # Form encoding for requests +│ ├── apiquery/ # Query encoding +│ ├── autocomplete/ # Shell completion scripts +│ │ └── shellscripts/ # bash, zsh, fish, pwsh completions +│ ├── binaryparam/ # Binary file parameter handling +│ ├── debugmiddleware/ # Debug HTTP middleware +│ ├── jsonview/ # JSON explorer/viewer +│ ├── mocktest/ # Mock testing utilities +│ └── requestflag/ # Core flag parsing (handles @file, YAML, etc.) +│ ├── requestflag.go # Flag[T] generic type, parsing logic +│ ├── requestflag_test.go +│ ├── innerflag.go # Inner flags for nested objects +│ └── innerflag_test.go +├── npm/ # NPM package for distribution +│ ├── package.json # 0.4.1, agentmail-cli +│ ├── bin/agentmail +│ ├── scripts/postinstall.js +│ └── README.md +├── .github/ +│ ├── actions/setup-go/ +│ └── workflows/ +│ ├── ci.yml +│ ├── publish-release.yml +│ ├── release-doctor.yml +│ └── auto-merge-release.yml +├── scripts/ +│ ├── bootstrap +│ ├── lint +│ ├── test +│ ├── build +│ ├── format +│ ├── run +│ ├── link +│ ├── unlink +│ └── utils/upload-artifact.sh +├── .goreleaser.yml # Build config (macos, linux, windows; nfpms) +├── release-please-config.json +├── go.mod / go.sum +├── .stats.yml # 94 configured endpoints +├── SKILL.md # Skill documentation +├── README.md +├── CHANGELOG.md +├── LICENSE +├── SECURITY.md +└── .release-please-manifest.json +``` + +## API Resources (from cmd.go) + +| Resource Group | Commands | +|---|---| +| `agent` | sign-up, verify | +| `inboxes` | create, update, list, delete, get, list-metrics | +| `inboxes:drafts` | create, update, list, delete, get, get-attachment, send | +| `inboxes:messages` | update, list, forward, get, get-attachment, get-raw, reply, reply-all, send | +| `inboxes:threads` | list, delete, get, get-attachment | +| `inboxes:lists` | create, list, delete, get | +| `inboxes:api-keys` | create, list, delete | +| `pods` | create, list, delete, get | +| `pods:domains` | create, update, list, delete, get, get-zone-file, verify | +| `pods:drafts` | list, get, get-attachment | +| `pods:inboxes` | create, update, list, delete, get | +| `pods:threads` | list, delete, get, get-attachment | +| `pods:lists` | create, list, delete, get | +| `pods:api-keys` | create, list, delete | +| `pods:metrics` | query | +| `webhooks` | create, update, list, delete, get | +| `api-keys` | create, list, delete | +| `domains` | create, update, list, delete, get, get-zone-file, verify | +| `drafts` | list, get, get-attachment | +| `lists` | create, list, delete, get | +| `metrics` | list | +| `organizations` | get | +| `threads` | list, delete, get, get-attachment | + +## Key Dependencies + +- `github.com/agentmail-to/agentmail-go v0.14.0` — API client +- `github.com/urfave/cli/v3 v3.3.2` — CLI framework +- `github.com/charmbracelet/bubbletea v1.3.6` — TUI +- `github.com/goccy/go-yaml v1.18.0` — YAML parsing +- `github.com/tidwall/gjson v1.18.0` — JSON query/transform + +## Branches + +| Branch | Description | +|---|---| +| `main` | Primary branch | +| `next` | Next version branch | +| `improve-readme` | Upstream branch for README improvement | +| `jarvis/improve-readme` | Another upstream branch (PR #20) | +| `generated` | Codegen output branch | diff --git a/05_PR_CANDIDATES.md b/05_PR_CANDIDATES.md new file mode 100644 index 0000000..1a9da97 --- /dev/null +++ b/05_PR_CANDIDATES.md @@ -0,0 +1,49 @@ +# 05_PR_CANDIDATES.md — agentmail-cli + +## Open Issues + +### Issue #13 — "fix: change goreleaser nfpms bindir to /usr/bin" +- **Severity**: Low (packaging fix) +- **Effort**: Very low (1-line change in `.goreleaser.yml`) +- **PR exists**: Yes — PR #13 from mtzanidakis (open) +- **Status**: Straightforward. Change `bindir: /usr` → `bindir: /usr/bin` in `.goreleaser.yml` line 71. +- **Risk**: Very low — only affects Linux package install path +- **Blocker**: None + +### Issue #17 — "CLI parses string flags containing colons as YAML objects" +- **Severity**: High (functional bug — causes 400 API errors) +- **Effort**: Medium (requires understanding `requestflag.go` parsing logic) +- **PR exists**: No +- **Root cause**: In `internal/requestflag/requestflag.go`, the `parseCLIArg` function falls through to `yaml.Unmarshal` for flags typed as `any`. Valid YAML strings like `"S4: test"` get deserialized as `map[string]any{"S4": "test"}` instead of being kept as plain strings. The `allowAsLiteralString` fallback only triggers when YAML parsing *fails*. +- **Affected**: any string flag value containing a colon (`:), e.g., `--subject "S4: test"`, `--subject "BCC test"` +- **Fix approach**: Check if the YAML-parsed result is a map with a single string key before treating it as an object; if so, treat it as a literal string. +- **Risk**: Low — targeted change in parsing fallback +- **Blocker**: None + +### Issue #20 — "Improve README — add badge, Homebrew install, links" +- **Severity**: Low (documentation) +- **Effort**: Very low +- **PR exists**: Yes — PR #20 from `agentmail-to:jarvis/improve-readme` (open) +- **Status**: PR already exists on upstream. README is already fairly complete with npm install instructions and usage examples. +- **Blocker**: None (already addressed by upstream PR) + +## Open Pull Requests + +### PR #13 — "fix: change goreleaser nfpms bindir to /usr/bin" +- From: `mtzanidakis/agentmail-cli` (fork) +- Target: `agentmail-to:main` +- Head: `main` (ff159d828d4e1c1116c461202acaa0ce35d0e287) +- Mergeable: Unknown (needs CI check) +- Status: Needs review/merge + +### PR #20 — "Improve README — add badge, Homebrew install, links" +- From: `agentmail-to:jarvis/improve-readme` +- Target: `agentmail-to:main` +- Head: `187b67d10664f774f5666ae18372449274b080a9` +- Mergeable: Unknown +- Status: Needs review/merge + +## Notes + +- The `internal/requestflag/` code is generated from Stainless API spec (`stainless-api/stainless-api-cli`), so any fix to #17 may need to be applied upstream in the generator as well. +- Bootstrap script requires `go` binary — not available in this environment, so tests cannot be run locally. diff --git a/06_SELECTED_5_PR_PLAN.md b/06_SELECTED_5_PR_PLAN.md new file mode 100644 index 0000000..b745637 --- /dev/null +++ b/06_SELECTED_5_PR_PLAN.md @@ -0,0 +1,42 @@ +# 06_SELECTED_5_PR_PLAN.md — agentmail-cli + +## Selected Candidates (Top 5) + +Given the available issues and PRs, the following are ranked by impact and ease: + +### 1. Issue #13 — Fix goreleaser nfpms bindir (`/usr` → `/usr/bin`) +- **File**: `.goreleaser.yml` line 71 +- **Change**: `bindir: /usr` → `bindir: /usr/bin` +- **Why**: Straightforward, low-risk, already has PR #13 from mtzanidakis that can be reviewed/merged +- **Impact**: Ensures Linux packages (deb/rpm/apk) install binary to `/usr/bin` instead of `/usr` + +### 2. Issue #17 — Fix colon-in-string YAML parsing bug +- **File**: `internal/requestflag/requestflag.go` +- **Change**: In `parseCLIArg`, detect when a YAML-parsed map has a single string key and treat as literal string instead of object +- **Why**: High severity bug causing API 400 errors for legitimate subject lines and other string fields +- **Impact**: Fixes CLI usability for any user whose data contains colons (e.g., "Re: S4: test", "BCC:", etc.) +- **Note**: Generated code may need corresponding fix upstream in Stainless CLI generator + +### 3. PR #20 Review — README improvement +- **Action**: Review and potentially merge existing upstream PR #20 (`jarvis/improve-readme`) +- **Changes**: npm badge, better description, Homebrew install, links +- **Why**: Low effort, improves first-impression and installation options +- **Note**: Already exists as upstream PR — no new PR needed, just needs review/merge from maintainers + +## What Was Not Selected + +- **Issue #20 (as new PR)**: Already addressed by existing PR #20 from upstream branch. Not worth duplicating effort. +- **Codegen/generated code**: The repository is auto-generated from OpenAPI via Stainless. Direct modifications to generated files (`pkg/cmd/*.go`) would be overwritten by codegen. Changes should go through the Stainless pipeline. +- **NPM packaging**: Works correctly; no issues filed. + +## Execution Plan + +1. **For Issue #13**: Apply 1-line fix to `.goreleaser.yml` locally, commit, push to `okwn/agentmail-cli`, open PR targeting `agentmail-to:main` +2. **For Issue #17**: Study `parseCLIArg` fallback logic in `internal/requestflag/requestflag.go`, implement fix, add test case in `requestflag_test.go`, commit, push, open PR +3. **For PR #20**: Since it's already an upstream PR, assist by reviewing/testing the existing changes rather than duplicating + +## Environment Notes + +- `go` binary NOT available — cannot run `bootstrap`, `test`, or `lint` locally +- Tests must be validated via CI after PR is opened (CI runs on fork PRs) +- All Go code is syntactically parseable at least diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..64fbdbd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# Contributing to AgentMail CLI + +Thank you for your interest in contributing to AgentMail CLI! + +## Getting Started + +1. Clone the repository +2. Install dependencies: `npm install` +3. Set your API key: `export AGENTMAIL_API_KEY=your_key` + +## Development + +```sh +# Run locally +npm link +agentmail [command] + +# Run tests +npm test +``` + +## Submitting Changes + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature/my-feature` +3. Make your changes +4. Run tests: `npm test` +5. Submit a pull request + +## Style Guide + +- Use clear, descriptive commit messages +- Add tests for new functionality +- Update documentation as needed \ No newline at end of file