jj-octo 0.3.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # jj-octo
 
-A [jj](https://github.com/jj-vcs/jj) subcommand for working with GitHub that supports stacking.
+A [jj](https://github.com/jj-vcs/jj) subcommand for GitHub that supports stacked pull requests and works in Claude Code cloud sessions.
 
 > [!WARNING]
 > `jj-octo` is in early development, and its commands may change. So far it is largely vibe coded.
@@ -11,58 +11,70 @@ Run `jj gh --help` to list the commands.
 
 ## Install
 
-`jj-octo` runs on [bun](https://bun.sh), and calls `jj`. Both must be on `PATH`.
+Each [GitHub release](https://github.com/kkom/jj-octo/releases) has a standalone `jj-octo` for macOS on Apple silicon and Linux on x64 and arm64. Alternatively, run the [npm package](https://www.npmjs.com/package/jj-octo) with [Bun](https://bun.sh). Either way, `jj` must be on `PATH`.
 
-### For one repository
-
-With [mise](https://mise.jdx.dev), in the repository's `mise.toml`, where `A.B.C` is a bun version and `X.Y.Z` a [released version](https://www.npmjs.com/package/jj-octo?activeTab=versions) of `jj-octo`:
+With [mise](https://mise.jdx.dev), add it to one repository's `mise.toml`:
 
 ```toml
 [tools]
-bun = "A.B.C"
-
-[tools."npm:jj-octo"]
-version = "X.Y.Z"
-# mise holds back a package that is new or rarely downloaded, and this approves it.
-allow_low_downloads = true
+"github:kkom/jj-octo" = "X.Y.Z"
 ```
 
-Then set up each checkout, since jj doesn't read config from a committed file:
+Or to every repository:
 
 ```
-jj-octo init
+mise use --global github:kkom/jj-octo@X.Y.Z
 ```
 
-It makes the checkout a jj repository colocated with git, makes GitHub's default branch `trunk()`, and sets the `jj gh` alias.
+Then run `jj-octo init` once in each checkout. It makes the checkout a jj repository colocated with git, makes GitHub's default branch `trunk()`, and sets the `jj gh` alias.
 
-### For every repository
+## GitHub access
 
-```
-bun install --global jj-octo
-jj config set --user aliases.gh '["util", "exec", "--", "jj-octo"]'
-```
+`jj-octo` reads the repository from the `origin` remote.
+
+By default, it reads its token from `GH_TOKEN` or `GITHUB_TOKEN`, and otherwise runs `gh auth token`.
 
-Then run `jj-octo init` once in each checkout, as above.
+With `jj-octo.github-auth` set to `git-proxy`, it sends a placeholder token instead. It sends requests through git's proxy for github.com, and trusts git's certificate authorities for it in place of Bun's own. [In a self-hosted environment](#in-a-self-hosted-environment) describes when to use it.
 
-To update it later:
+## In Claude Code cloud sessions
+
+A Claude Code [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web) runs in an Anthropic-hosted environment, or in your organization's self-hosted environment. Each needs its own setup.
+
+The session's GitHub proxy can append a "Generated by Claude Code" footer to each pull request body that it creates or edits. `jj gh submit` would read the footer as an edit made on GitHub, and write it into the change. To have `submit` leave the footer out when it compares a pull request's body with its change's description, set:
 
 ```
-bun update --global --latest jj-octo
+jj config set --repo jj-octo.ignore-claude-code-footer true
 ```
 
-## GitHub access
+### In an Anthropic-hosted environment
 
-`jj-octo` reads the repository from the `origin` remote. It takes its token from `GH_TOKEN` or `GITHUB_TOKEN`, and otherwise from `gh auth token`.
+There, the [GitHub proxy](https://code.claude.com/docs/en/cloud-environments#github-proxy) carries all GitHub traffic. It serves GitHub API requests only for the repositories attached to the session, and rejects GraphQL requests. That's why `jj-octo` uses only GitHub's REST API, while `gh pr` and other tools that depend on GraphQL fail there.
 
-It uses only GitHub's REST API, so that it works in a [Claude Code](https://claude.com/claude-code) cloud session. There, GitHub is reached through a proxy that allows REST calls for the session's repository and blocks GraphQL, which `gh pr` depends on.
+mise reads this repository's releases through the GitHub API, so it can't install them unless the session has this repository attached. Install the npm package instead:
 
-Where git reaches github.com through a proxy that adds the credentials itself, as in a Claude Code cloud session that keeps the token outside the sandbox, have `jj-octo` use that proxy too:
+```toml
+[tools]
+bun = "A.B.C"
+
+[tools."npm:jj-octo"]
+version = "X.Y.Z"
+# mise holds back a package that is new or rarely downloaded, and this approves it.
+allow_low_downloads = true
+```
+
+The session sets `HTTPS_PROXY`, `NODE_EXTRA_CA_CERTS`, and `GH_TOKEN` to the placeholder `proxy-injected`. The GitHub proxy replaces the placeholder with your real credentials. So `jj-octo` works there with its default settings.
+
+### In a self-hosted environment
+
+A [self-hosted runner](https://code.claude.com/docs/en/self-hosted-environments-deploy#use-the-anthropic-git-proxy) started with `--use-anthropic-git-proxy` sends git through the Anthropic git proxy. That proxy adds the GitHub credentials of the session's creator. The session then holds no GitHub token, and only git's config names the proxy. There, have `jj-octo` use the same proxy:
 
 ```
 jj config set --repo jj-octo.github-auth git-proxy
 ```
 
-`jj-octo` then sends its requests through the `http.proxy` that git uses for `https://github.com`, trusts the certificate authorities in git's `http.sslCAInfo` for it, and sends a placeholder token that the proxy replaces. It reads git's settings on each run, so it follows a proxy that moves to another port. `token`, the default, sends your own token.
+`jj-octo` then sends its requests through the `http.proxy` that git uses for `https://github.com`, and trusts the certificate authorities in git's `http.sslCAInfo` for it. It sends a placeholder token, which the proxy must replace with real credentials. It reads git's settings on each run, so it follows a proxy that moves to another port.
+
+Don't use `git-proxy` with a proxy that only forwards requests. GitHub would get the placeholder token and reject every request. `token`, the default, sends your own token.
 
 ## Development
 
@@ -72,4 +84,4 @@ bun run check    # format, lint, types, tests and build
 bun run fix      # format and lint fixes
 ```
 
-To release, run `bun run release:patch`, `release:minor` or `release:major` in a pull request, which raises `version` in `package.json`. Once it is merged and the checks pass on `main`, the same workflow publishes that version to npm and tags it.
+To release, run `bun run release:patch`, `release:minor` or `release:major` in a pull request, which raises `version` in `package.json`. Once it is merged and the checks pass on `main`, the same workflow publishes that version to npm, and as a GitHub release with the executables.