From a5f97f9c91907ec94f098ca64577853cacbbc9d2 Mon Sep 17 00:00:00 2001 From: erish Date: Thu, 23 Apr 2026 01:08:53 +0900 Subject: [PATCH] docs: AEO optimization and v0.3.3 feature documentation (#227) (#228) - Update README with rename, --dry-run, doctor --ai, error codes, policy config, FAQ - Fix docs site: version 0.3.3, downloadUrl, expanded FAQPage (10 Q&A) - Add BreadcrumbList and HowTo schemas to guide/reference pages - Add CHANGELOG.md, sitemap.xml, robots.txt - Add documentation field to Cargo.toml Co-authored-by: Claude Opus 4.6 --- CHANGELOG.md | 120 +++++++++++++++++++++++++ Cargo.toml | 1 + README.md | 104 ++++++++++++++++++++++ docs/guide/index.html | 35 +++++++- docs/index.html | 56 +++++++++++- docs/reference/index.html | 180 ++++++++++++++++++++++++++++++++++++++ docs/robots.txt | 4 + docs/sitemap.xml | 21 +++++ 8 files changed, 513 insertions(+), 8 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/robots.txt create mode 100644 docs/sitemap.xml diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b326ae4 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,120 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.3.3] - 2026-04-22 + +### Added +- Global `--dry-run` flag for all mutating commands (start, ship, clean, sync, merge, rename) +- Policy guard for protected branches and allowed ship targets (`[policy]` config) +- `parsec doctor --ai` — output workflow rules as Markdown for AI agents +- Standard error codes (E001–E013) with structured JSON error format +- PR number stored as first-class field in operation log +- `parsec ship --title` flag for custom PR titles + +### Fixed +- reqwest 0.13 missing `rustls` TLS backend feature +- rustls-webpki vulnerabilities (RUSTSEC-2026-0098/0099/0104) +- `parsec open --pr` fails on GitHub Enterprise (hardcoded github.com) +- Doctor command token handling and GHE support +- `.atlassian-env` parser does not strip shell-style quotes +- `unwrap()` panic paths in tracker and stack sync + +### Changed +- Major dependency upgrades (reqwest 0.13, colored 3, indicatif 0.18, tabled 0.20, toml 1) +- Extracted Jira config boilerplate into helper function +- Ticket ID validation to prevent path traversal and invalid branch names + +## [0.3.2] - 2026-04-21 + +### Fixed +- Windows binary release upload (use bash shell) + +## [0.3.1] - 2026-04-21 + +### Added +- `parsec rename` command to re-ticket a workspace +- `parsec create` and `parsec new-issue` for creating tracker issues from CLI +- `parsec release` command for automated release workflow +- `parsec doctor` for environment validation +- `parsec list --full` with richer worktree metadata +- `parsec init --install` for automatic shell integration setup +- `parsec switch pr:NUMBER` to checkout PR branches +- `parsec start --hook` for post-create automation +- Pre-ship hooks support (`[hooks] pre_ship`) +- `parsec ci` accepts multiple tickets +- `parsec merge --batch` for merging multiple PRs sequentially +- `parsec clean` supports cleaning a specific ticket +- `parsec ship` auto-closes issues on merge +- Automated multi-platform binary releases +- Documentation site with guide and reference pages + +### Fixed +- Jira integration improvements (config token, HTML error, status display) +- Proper error propagation in CI + +### Changed +- Output module refactored with `dispatch_output!` macro +- Split monolithic `commands.rs` into per-command modules +- Unified Create and NewIssue into single command +- Typed response structs replace raw `serde_json::Value` +- HTTP client timeout and retry for transient failures +- Idempotency guarantees for ship/merge re-execution +- Expanded integration test coverage + +## [0.3.0] - 2026-04-16 + +### Added +- `parsec board` — sprint as vertical Kanban board +- `parsec ticket` command for tracker lookup with `--comment` +- `parsec inbox` for viewing assigned tickets +- `parsec init` and `parsec root` for shell integration +- Automatic ticket status transitions +- `parsec ship --base` flag and `default_base` config +- `gh auth token` fallback for GitHub token resolution +- Host-aware GitHub token resolution for GitHub Enterprise + +### Fixed +- Merge/pr-status work with adopted branches +- Conflicts detection with origin fallback +- Prune stale remote-tracking references after merge + +### Security +- Pinned GitHub Actions to SHA hashes +- Added cargo audit job + +## [0.2.4] - 2026-04-15 + +### Added +- `parsec ci` to check CI/CD pipeline status +- `parsec merge` to merge PRs from terminal +- `parsec diff` to view worktree changes +- `parsec stack` for stacked PR dependency tracking +- `parsec start --branch` for existing branches + +## [0.2.3] - 2026-04-15 + +### Added +- `parsec open` to open PR or ticket page in browser +- `parsec pr-status` for CI and review status +- `parsec sync` to rebase/merge base branch +- `parsec adopt` to import existing branches + +## [0.2.0] - 2026-04-14 + +### Added +- Initial release with core commands (start, list, status, ship, clean, conflicts, switch, log, undo) +- Jira and GitHub Issues integration +- `--json` output on all commands +- Sibling and internal worktree layouts + +[0.3.3]: https://github.com/erishforG/git-parsec/compare/v0.3.2...v0.3.3 +[0.3.2]: https://github.com/erishforG/git-parsec/compare/v0.3.1...v0.3.2 +[0.3.1]: https://github.com/erishforG/git-parsec/compare/v0.3.0...v0.3.1 +[0.3.0]: https://github.com/erishforG/git-parsec/compare/v0.2.4...v0.3.0 +[0.2.4]: https://github.com/erishforG/git-parsec/compare/v0.2.3...v0.2.4 +[0.2.3]: https://github.com/erishforG/git-parsec/compare/v0.2.0...v0.2.3 +[0.2.0]: https://github.com/erishforG/git-parsec/releases/tag/v0.2.0 diff --git a/Cargo.toml b/Cargo.toml index 78b5ba0..9f3fc9d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -7,6 +7,7 @@ description = "Git worktree lifecycle manager — ticket to PR in one command. P license = "MIT" repository = "https://github.com/erishforG/git-parsec" homepage = "https://erishforg.github.io/git-parsec/" +documentation = "https://erishforg.github.io/git-parsec/" keywords = ["git", "worktree", "cli", "jira", "github"] categories = ["command-line-utilities", "development-tools"] readme = "README.md" diff --git a/README.md b/README.md index 3dcf0cf..176a0d9 100644 --- a/README.md +++ b/README.md @@ -323,6 +323,7 @@ $ parsec log | [`parsec create`](#parsec-create) | Create a new issue and optionally start a worktree | | [`parsec new-issue`](#parsec-new-issue) | Create a new issue (alias with extra options) | | [`parsec release`](#parsec-release-version) | Merge, tag, and create a GitHub Release | +| [`parsec rename`](#parsec-rename-ticket---new-ticket-id) | Re-ticket a workspace to a different ticket ID | --- @@ -1029,6 +1030,14 @@ $ parsec doctor --json {"checks":[...],"all_ok":false} ``` +**AI agent mode** — output parsec workflow rules as a Markdown document for AI agents to consume: + +```bash +$ parsec doctor --ai +# Outputs structured Markdown with workflow rules, command patterns, +# and best practices for AI agents using parsec +``` + --- ### `parsec create` @@ -1119,12 +1128,38 @@ $ parsec release 0.3.1 --no-github-release --- +### `parsec rename --new ` + +Re-ticket an existing workspace to a different ticket ID. Renames the branch and updates internal state. Useful when a ticket is split or re-assigned. + +``` +parsec rename --new +``` + +| Option | Description | +|--------|-------------| +| `--new ` | New ticket ID to assign (required) | + +```bash +# Re-ticket a workspace +$ parsec rename PROJ-100 --new PROJ-200 +Renamed PROJ-100 → PROJ-200 + Branch: feature/PROJ-100 → feature/PROJ-200 + Path: /home/user/myapp.PROJ-200 + +# JSON output +$ parsec rename PROJ-100 --new PROJ-200 --json +``` + +--- + ## Global Flags These flags work on every command: | Flag | Description | |------|-------------| +| `--dry-run` | Preview what a command would do without making changes | | `--json` | Machine-readable JSON output | | `-q, --quiet` | Suppress non-essential output | | `--repo ` | Target a different repository | @@ -1244,6 +1279,11 @@ pre_ship = ["cargo test", "cargo clippy"] # tag_prefix = "v" # Tag prefix (default: "v") # changelog = true # Generate changelog in release notes +[policy] +# protected_branches = ["main", "develop", "release/*"] # Branches that cannot be shipped to +# allowed_ship_targets = ["develop"] # Restrict PR target branches +# require_ci = false # Require CI pass before merge + [tracker.auto_transition] # on_start = "In Progress" # Transition when `parsec start` runs # on_ship = "In Review" # Transition when `parsec ship` runs @@ -1272,6 +1312,36 @@ Token priority: `PARSEC_*_TOKEN` > platform-specific variables. --- +## Error Codes + +When using `--json`, errors include a structured error code for programmatic handling: + +| Code | Meaning | Exit Code | +|------|---------|-----------| +| E001 | No authentication token configured | 2 | +| E002 | CI checks failing | 4 | +| E003 | Merge conflicts detected | 3 | +| E004 | PR not mergeable | 5 | +| E005 | Workspace not found | 5 | +| E006 | Workspace already exists | 5 | +| E007 | No active workspaces | 5 | +| E008 | Pre-ship hook failed | 1 | +| E009 | Policy violation | 6 | +| E010 | PR not found | 5 | +| E011 | Tracker not configured | 2 | +| E012 | Ship partially completed | 1 | +| E013 | Cannot undo operation | 1 | + +```bash +# JSON error output example +$ parsec ship PROJ-1234 --json 2>&1 +{"error":{"code":"E001","message":"No GitHub token configured","hint":"Set PARSEC_GITHUB_TOKEN or run gh auth login"}} +$ echo $? +2 +``` + +--- + ## Comparison with Alternatives | Feature | parsec | GitButler | worktrunk | git worktree | git-town | @@ -1294,6 +1364,40 @@ Token priority: `PARSEC_*_TOKEN` > platform-specific variables. --- +## FAQ + +**How do I set up parsec with Jira?** +Set `PARSEC_JIRA_TOKEN` (or `JIRA_PAT`) and configure `[tracker.jira]` in `~/.config/parsec/config.toml` with your `base_url` and `project`. Run `parsec config init` for interactive setup, or `parsec doctor` to validate. + +**How do I set up parsec with GitHub Issues?** +Set `provider = "github"` under `[tracker]` in your config. Authentication uses `PARSEC_GITHUB_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token` automatically. + +**Does parsec support GitLab?** +Yes. parsec supports GitLab for both issue tracking and MR creation. Set `provider = "gitlab"` and configure `[tracker.gitlab]` with your `base_url`. Set `PARSEC_GITLAB_TOKEN` for authentication. + +**Can I use parsec without a ticket tracker?** +Yes. Set `provider = "none"` or use `--title` with `parsec start` to skip tracker lookup entirely. + +**How do stacked PRs work?** +Use `parsec start CHILD --on PARENT` to create dependent worktrees. `parsec ship` automatically sets the correct base branch. `parsec stack --sync` rebases the entire chain. + +**What happens if two worktrees modify the same file?** +`parsec conflicts` detects cross-worktree file overlap before you push. It compares changed files across all active worktrees and warns about collisions. + +**Can I undo a ship or clean?** +Yes. `parsec undo` reverses the last operation. For `ship`, it re-creates the worktree from the branch. For `clean`, it restores from the remote branch if still available. + +**How do I protect branches from accidental shipping?** +Add a `[policy]` section to your config with `protected_branches` and `allowed_ship_targets`. parsec will reject operations that violate these rules. + +**Does parsec work with GitHub Enterprise?** +Yes. parsec auto-detects GitHub Enterprise from the remote URL and routes API calls to the correct host. Token resolution is host-aware. + +**How do AI agents use parsec?** +Every command supports `--json` for structured output. Run `parsec doctor --ai` to get a Markdown document with workflow rules and command patterns optimized for AI agent consumption. + +--- + ## License MIT diff --git a/docs/guide/index.html b/docs/guide/index.html index ea4602b..d4ce392 100644 --- a/docs/guide/index.html +++ b/docs/guide/index.html @@ -945,6 +945,33 @@ } .reveal.visible { opacity: 1; transform: translateY(0); } + + + + + @@ -1041,7 +1068,7 @@

Via cargo (recommended)

  # Verify installation $ parsec --version - parsec 0.2.4 + parsec 0.3.3 @@ -1593,10 +1620,10 @@

Release workflow with parsec release

parsec release
-$ parsec release 0.3.0 +$ parsec release 0.3.3 ✓ Merged develop → main -✓ Tagged v0.3.0 -✓ GitHub Release: github.com/org/repo/releases/tag/v0.3.0 +✓ Tagged v0.3.3 +✓ GitHub Release: github.com/org/repo/releases/tag/v0.3.3   # Always preview first with --dry-run $ parsec release 0.4.0 --dry-run diff --git a/docs/index.html b/docs/index.html index a91b22c..88fb60b 100644 --- a/docs/index.html +++ b/docs/index.html @@ -31,8 +31,8 @@ "operatingSystem": "macOS, Linux, Windows", "description": "Git worktree lifecycle manager for parallel AI agent workflows. Create isolated workspaces from ticket IDs (Jira, GitHub Issues, GitLab), work in parallel without lock conflicts, ship with one command (push + PR + cleanup). Supports CI monitoring, stacked PRs, conflict detection, and operation history with undo.", "url": "https://erishforg.github.io/git-parsec/", - "downloadUrl": "https://crates.io/crates/git-parsec", - "softwareVersion": "0.2.4", + "downloadUrl": "https://github.com/erishforG/git-parsec/releases", + "softwareVersion": "0.3.3", "author": { "@type": "Person", "name": "erishforG", @@ -75,7 +75,7 @@ "name": "Can multiple AI agents use parsec on the same repository?", "acceptedAnswer": { "@type": "Answer", - "text": "Yes. Each parsec workspace is a separate git worktree with its own index, so multiple AI agents (or developers) can run git add, commit, and push simultaneously without index.lock conflicts. parsec also detects when multiple workspaces modify the same files." + "text": "Yes. Each parsec workspace is a separate git worktree with its own index, so multiple AI agents (or developers) can run git add, commit, and push simultaneously without index.lock conflicts. Every command supports --json for structured output, and parsec doctor --ai outputs workflow rules optimized for AI consumption." } }, { @@ -83,7 +83,55 @@ "name": "How do I install parsec?", "acceptedAnswer": { "@type": "Answer", - "text": "Install via cargo: cargo install git-parsec. Or build from source: git clone https://github.com/erishforG/git-parsec.git && cd git-parsec && cargo build --release. The binary is at ./target/release/parsec." + "text": "Install via cargo: cargo install git-parsec. Or download pre-built binaries for macOS (Apple Silicon, Intel), Linux, and Windows from the GitHub Releases page. Or build from source: git clone and cargo build --release." + } + }, + { + "@type": "Question", + "name": "Does parsec support GitLab?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Yes. parsec supports GitLab for both issue tracking and merge request creation. Set provider = gitlab in your config and configure the base_url. Authentication uses PARSEC_GITLAB_TOKEN or GITLAB_TOKEN environment variables." + } + }, + { + "@type": "Question", + "name": "How do stacked PRs work in parsec?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Use parsec start CHILD --on PARENT to create dependent worktrees. When you ship, parsec automatically sets the correct base branch for each PR. Use parsec stack to view the dependency graph and parsec stack --sync to rebase the entire chain." + } + }, + { + "@type": "Question", + "name": "Does parsec work with GitHub Enterprise?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Yes. parsec auto-detects GitHub Enterprise from the git remote URL and routes API calls to the correct host. Token resolution is host-aware, supporting both github.com and GitHub Enterprise instances." + } + }, + { + "@type": "Question", + "name": "Can I undo a parsec operation?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Yes. parsec log shows all operations with timestamps, and parsec undo reverses the last one. Undoing a start removes the worktree; undoing a ship or clean re-creates it from the branch if still available." + } + }, + { + "@type": "Question", + "name": "How do I protect branches from accidental shipping?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Add a [policy] section to ~/.config/parsec/config.toml with protected_branches and allowed_ship_targets. parsec will reject ship and merge operations that violate these rules, returning error code E009." + } + }, + { + "@type": "Question", + "name": "What are parsec error codes?", + "acceptedAnswer": { + "@type": "Answer", + "text": "When using --json mode, parsec returns structured error codes (E001 through E013) with specific exit codes for programmatic handling. For example, E001 means no token configured (exit 2), E002 means CI failing (exit 4), E003 means conflicts detected (exit 3). This enables AI agents and scripts to handle errors precisely." } } ] diff --git a/docs/reference/index.html b/docs/reference/index.html index ec6c7a3..3e41bf7 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -852,6 +852,19 @@ transform: translateY(0); } + + + + @@ -896,6 +909,7 @@
  • clean
  • create
  • new-issue
    • +
  • rename
  • release
    • @@ -945,6 +959,15 @@
  • doctor
    • + + +
    +
    Reference
    + +
    @@ -967,6 +990,7 @@

    Global Options — available on every command

    --json machine-readable output
    -q / --quiet suppress non-essential output
    --repo <PATH> target repository path
    +
    --dry-run preview changes without executing
    @@ -2032,6 +2056,7 @@

    Setup

    --jsonOutput results as JSON ({"checks":[...],"all_ok":bool}). + --aiInclude AI-powered diagnostic suggestions for failed checks. @@ -2157,6 +2182,63 @@

    Setup

    + +
    +
    + rename + Re-ticket an existing workspace + # +
    +

    + Reassigns an existing worktree to a different ticket ID. Updates the branch name, directory symlink, and internal state — useful when a ticket is split, renumbered, or moved between trackers. +

    +
    + Usage + parsec rename <OLD-TICKET> <NEW-TICKET> [OPTIONS] +
    + +
    + + + + + + + + +
    ArgumentDescription
    <OLD-TICKET> requiredThe current ticket ID of the workspace to rename.
    <NEW-TICKET> requiredThe new ticket ID to assign to the workspace.
    +
    + +
    + + + + + + + +
    OptionDescription
    --dry-runPreview what would be renamed without making changes.
    +
    + +
    +
    +
    + parsec rename +
    +
    +$ parsec rename PROJ-123 PROJ-456 +✓ Branch renamed: feature/PROJ-123-fix-login → feature/PROJ-456-fix-login +✓ Workspace directory updated +✓ State updated for PROJ-456 +  +# Preview changes first +$ parsec rename OLD-99 NEW-100 --dry-run +Would rename branch feature/OLD-99-… → feature/NEW-100-… +Would update workspace directory and state file +
    +
    +
    +
    @@ -2219,6 +2301,104 @@

    Setup

    + +
    +
    +

    Error Codes

    +
    + +
    +

    + All parsec commands exit with a structured exit code. Use these in scripts to handle failures precisely. JSON output (--json) also includes an "error_code" field on failure. +

    + +
    + + + + + + + + + + + + + + + +
    Exit CodeNameDescription
    0SuccessCommand completed successfully.
    1GeneralErrorUnspecified error — check stderr for details.
    2ConfigErrorMissing or invalid configuration (run parsec config init).
    3TrackerErrorCould not reach or authenticate with the issue tracker.
    4GitErrorGit operation failed (merge conflict, missing remote, etc.).
    5WorktreeErrorWorktree already exists, is missing, or is in a bad state.
    6NotFoundTicket or workspace not found.
    7AuthErrorAPI token missing or insufficient permissions.
    8PolicyViolationOperation blocked by an active policy rule.
    +
    + +
    +
    +
    + exit code in scripts +
    +
    +$ parsec ship PROJ-123 --json +{"error_code":3,"message":"Could not reach Jira: connection refused"} +$ echo $? +3 +
    +
    +
    +
    + + + +
    +
    +

    Policy Config

    +
    + +
    +

    + The [policy] table in ~/.config/parsec/config.toml lets teams enforce guardrails on parsec operations. Violations exit with code 8 (PolicyViolation) and print an actionable message. +

    + +
    + + + + + + + + + + + +
    KeyTypeDescription
    require_ticket_prefixStringAll ticket IDs must match this prefix (e.g., "PROJ-"). Prevents freeform branch names.
    max_open_workspacesu32Block parsec start when open workspace count reaches this limit.
    protected_branches[String]Branches that parsec ship and parsec merge will refuse to target (e.g., ["main", "production"]).
    require_pr_reviewboolWhen true, parsec ship checks that at least one review is approved before merging.
    allow_force_pushboolWhen false (default), parsec ship refuses to push with --force.
    +
    + +
    +
    +
    + ~/.config/parsec/config.toml +
    +
    +[policy] +require_ticket_prefix = "PROJ-" +max_open_workspaces = 5 +protected_branches = ["main", "production"] +require_pr_review = true +allow_force_push = false +  +# Policy violation example +$ parsec start my-feature +✗ Policy violation: ticket ID must start with "PROJ-" +
    +
    +
    +
    + +
    diff --git a/docs/robots.txt b/docs/robots.txt new file mode 100644 index 0000000..4e53dda --- /dev/null +++ b/docs/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://erishforg.github.io/git-parsec/sitemap.xml diff --git a/docs/sitemap.xml b/docs/sitemap.xml new file mode 100644 index 0000000..78151ab --- /dev/null +++ b/docs/sitemap.xml @@ -0,0 +1,21 @@ + + + + https://erishforg.github.io/git-parsec/ + 2026-04-22 + weekly + 1.0 + + + https://erishforg.github.io/git-parsec/guide/ + 2026-04-22 + weekly + 0.8 + + + https://erishforg.github.io/git-parsec/reference/ + 2026-04-22 + weekly + 0.8 + +