gh-stack 0.18.0 → 0.19.0

package/README.md

@@ -67,6 +67,10 @@ gh-stack status
 gh-stack split feat-12           # feat-12.. → new stack based on feat-11
 # ...later, after the original stack merges to main:
 gh-stack restack --onto main     # re-root the split stack onto main
+
+# Splice a branch (and its open PR) that was cut from main on its own into the stack
+gh-stack join fix-auth --dry-run # preview the resulting stack + each PR's diff
+gh-stack join fix-auth           # make it the new bottom (or --above <branch>)
 ```
 
 ## Commands
@@ -103,12 +107,17 @@ add [branch] [--parent <branch>]
     know about it, and `add` is how you track it without publishing. (When
     you do run `submit`, it auto-tracks too — `add` is the no-push path.)
 
-submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--restack] [--dry-run]
+submit [-d|--draft|--no-draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--restack] [--json] [--dry-run]
     Push all downstack branches to GitHub, create PRs for branches
     that don't have them, number each PR title with its stack position
     `(N/M)`, and update all PR descriptions with stack visualization.
     Idempotent — safe to run repeatedly.
 
+    --draft creates new PRs as drafts; --no-draft creates them ready for
+    review. Draft is create-time only: submit never changes the draft
+    state of an existing PR. A repo can make drafts the default with
+    `[submit] draft = true` in .gh-stack.toml (see Configuration).
+
     --restack: after submitting, restack the branches above the current
     one onto it. submit covers DOWNSTACK (trunk → current); restack covers
     UPSTACK (the children), so together they sync the whole stack from
@@ -131,6 +140,24 @@ submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file
     let an agent or script regenerate a PR's title/description safely.
     --body-file reads the body from a file. In --yes mode without --title,
     titles are auto-generated from branch names.
+
+    --json prints the result as one JSON document on stdout, on every
+    exit, so a script or agent gets the PR it just created without a
+    follow-up `gh pr view`:
+      { stack, current_branch,
+        branches: [{ branch, parent, pr, url, title, action, pushed,
+                     draft, error? }],
+        error: null | { message } }
+    branches is the submit scope (trunk → current) in stack order. action
+    is created (new PR), updated (pushed, or base/title/description
+    edited), unchanged, or failed (see the entry's error). draft is
+    true/false for PRs created this run, null otherwise. The top-level
+    error is set when the run stopped early (bad flags, nothing to
+    submit, a push failure): branches then lists what happened before
+    it, and stack/current_branch may be null. Exits 1 if error is set or
+    any branch failed. Logs go to stderr, plain and uncolored. Implies
+    --no-edit; can't be combined with --dry-run or --restack (run
+    `gh-stack restack` separately).
 ```
 
 ### Stack Navigation
@@ -160,20 +187,69 @@ ls
 ### Stack Management
 
 ```
-restack [--resume] [--dry-run] [--no-push] [--verbose]
+restack [--resume | --fresh] [--dry-run] [--no-push|--push] [--overwrite-remote] [--verbose]
     Rebase the current branch and all descendants onto their parents.
     Uses metadata snapshots to recover the correct rebase base even
     after a parent's history has been rewritten.
 
-    --no-push (or GH_STACK_NO_PUSH=1): rebase locally only, and list
-    the refs left ahead of origin. It overrides --yes for pushes, so
-    an agent can restack unattended without publishing anything. An
-    interrupted --no-push run stays local-only on --resume.
+    --no-push (or GH_STACK_NO_PUSH=1, or `[restack] push = false` in
+    config): rebase locally only, and list the refs left ahead of
+    origin. It overrides --yes for pushes, so an agent can restack
+    unattended without publishing anything. --push pushes even when the
+    env var or a config default says not to. --resume keeps the push
+    decision of the run it resumes (an interrupted local-only run stays
+    local) unless the resume itself passes --push or --no-push.
 
     On conflict:
         git rebase --continue
         gh-stack restack --resume
 
+    Interrupted runs: restack and sync save their progress (and a log
+    of every rebase and push) in .git/.gh-stack/restack-state.json
+    after each step, until the last push. `--resume` continues from
+    there: after a conflict, a kill, or failed pushes. If the run had
+    already finished, it prints the run's log and exits 0. A bare
+    `restack` or `sync` with an interrupted run pending asks whether to
+    resume it (with --yes it resumes) instead of starting a different
+    run on top of it. `--fresh` discards the interrupted run and starts
+    over. `git rebase --abort` ends the rebase, not the run: a resume
+    runs that rebase again (so does one killed before git started it),
+    and earlier branches' failed or held pushes stay queued. To abandon
+    the run, use `--fresh`. A state file from an older gh-stack is
+    refused with that same pointer, never upgraded. `merge` and `join`
+    refuse to run while a restack/sync is pending, and `undo` discards
+    the run it rolls back.
+
+    A branch is never pushed onto a parent that isn't on origin at the
+    commit the branch sits on (the parent's push failed or was declined,
+    or it has unpushed commits): its PR would be diffed against the
+    parent's old history. It's held back, the run exits 1 listing the
+    refs that aren't in sync, and `--resume` retries the pushes, parents
+    first.
+
+    Commits only on origin: before rewriting anything, restack and sync
+    check each branch's copy on origin. If it has commits the local
+    branch never had, e.g. the squash commit `merge --collapse` adds to
+    a parent PR's branch on GitHub, rewriting would drop them from the
+    PR, so the run stops, names them, and prints the pull or
+    cherry-pick that brings them in. Earlier versions of local commits
+    left on origin by a --no-push or interrupted run (found in the
+    branch's reflog or a snapshot, or patch-equivalent) don't count, and
+    neither do commits from origin's main (GitHub's "Update branch").
+    A branch whose origin copy couldn't be checked at all (not fetched,
+    or git failed) is treated the same way, never as clean. Interactive
+    runs ask; --yes stops. --overwrite-remote rewrites anyway, dropping
+    them. Sync skips bottom branches whose PRs already merged: it
+    advances past them rather than rewriting them. When an advance past
+    a merged bottom can't push the new bottom, its PR keeps its old base
+    until a later push of that branch lands, which retargets it.
+
+    Every gh-stack force-push (restack, sync, merge, submit, join) uses
+    --force-with-lease --force-if-includes: git refuses to overwrite an
+    origin tip you fetched but never brought into the local branch, and
+    gh-stack explains the refusal. A tip the check above cleared is
+    pushed with an explicit lease on exactly that commit instead.
+
     (alias: rebase)
 
 restack --onto <ref>
@@ -182,9 +258,9 @@ restack --onto <ref>
     onto main once the parent stack has merged — only the stack's own
     commits replay onto the new base.
 
-sync [--dry-run] [--no-push]
-    Fetch main, rebase the base branch onto main, then restack all
-    children. Snapshots every branch's pre-sync tip so children can be
+sync [--dry-run] [--no-push|--push] [--resume | --fresh] [--overwrite-remote]
+    Fetch main, rebase the base branch onto main, push it, then restack
+    all children (every branch above it, in one resumable run). Snapshots every branch's pre-sync tip so children can be
     correctly rebased even though their parent's history was rewritten.
     If the bottom PR(s) already merged on main outside gh-stack (e.g.
     the GitHub web UI), sync detects this and advances the stack past
@@ -192,11 +268,13 @@ sync [--dry-run] [--no-push]
     own commits replay — instead of replaying the now-squashed commits
     and conflicting.
 
-    --no-push (or GH_STACK_NO_PUSH=1): as for restack. Also skips
+    --no-push / --push (and their defaults): as for restack. Also skips
     retargeting a PR's base after advancing past a merged bottom;
-    the next `submit` pushes and retargets together.
+    the next `submit` pushes and retargets together. --resume and
+    --fresh: as for restack (`sync --resume` is `restack --resume`).
+    Commits only on origin / --overwrite-remote: as for restack.
 
-merge [--dry-run] [-d|--delete-branch] [--collapse]
+merge [--dry-run] [-d|--delete-branch] [--collapse] [--skip-collapse-check]
 merge --approved [--collapse] [--dry-run] [-d|--delete-branch]
 merge --base [--dry-run] [-d|--delete-branch]
     Default (top-down collapse): squash-merge the whole stack top-down
@@ -212,6 +290,26 @@ merge --base [--dry-run] [-d|--delete-branch]
     resolve with `gh-stack sync`, then re-run), while merely waiting on
     pending checks is fine (auto-merge gates on them).
 
+    Collapse check: before the base PR goes to main (and at the end of
+    --collapse), merge checks that each collapsed child's squash commit
+    is still in what it was squashed into: the base branch on origin,
+    or the parent PR's head when it merged. A rebased copy (same
+    patch-id) counts, and so does a base tree holding every file the
+    squash commit wrote. It fails closed:
+      - proven missing (the base has every file the squash commit
+        touched exactly as before it): merge stops (exit 2), names the
+        PR, and prints how to put the commit back (via its patch from
+        GitHub when the commit itself can't be fetched);
+      - anything it can't establish (a GitHub or fetch failure, a
+        shallow clone, content that matches neither version): the PR is
+        UNVERIFIED, not called missing. Interactive runs ask (default
+        stop, with a retry when the failure looks transient); --yes
+        stops (exit 2) with the checks to run by hand.
+    `merge --base` runs the same check when the base PR carries PRs
+    collapsed into it by an earlier `merge --collapse` (found from
+    GitHub: merged PRs whose base was their stack parent).
+    --skip-collapse-check turns the check off.
+
     --approved  Collapse only the approved run. Walks approval from the
                 BASE up and stops at the first PR that isn't approved
                 (contiguous — an unapproved PR4 caps the run at PR3 even
@@ -246,6 +344,59 @@ split [<branch>] [--name <name>]
     tip. Once the original stack merges, re-root the new stack with
     `gh-stack restack --onto main`.
 
+join <branch> [--above <branch>] [--dry-run] [--push|--no-push] [--verbose]
+    Splice an existing branch — usually one that already has a PR —
+    into a stack. Without --above it becomes the new bottom of the
+    current stack; with --above <branch> it goes between <branch> and
+    its children (--above main = the bottom). The <branch> named by
+    --above picks the stack, so that form works from anywhere.
+
+    The incoming branch is synced FIRST: only its own commits (those
+    above its fork point with main) replay onto the current tip of its
+    new parent. Otherwise a branch that's behind main would carry the
+    main commits it was missing into every child's diff once they're
+    restacked onto it. Then the branches above it are restacked onto it
+    (restack's own loop), each branch is pushed with --force-with-lease,
+    and the PR bases are retargeted on GitHub (the incoming PR onto its
+    new parent, each re-parented child PR onto the incoming branch).
+    Pushing follows the same setting as restack: --no-push,
+    GH_STACK_NO_PUSH, or `[restack] push = false` in .gh-stack.toml or
+    the user config keeps the join local; --push overrides them.
+    An open PR for the incoming branch is adopted into the metadata.
+
+    A stack named after its old bottom branch is renamed after the new
+    bottom (the old stack file is tombstoned under deleted/); a custom
+    name, or a name already used by another active or archived stack,
+    is kept. A branch alone in its own one-branch stack (what `submit`
+    makes of a standalone PR) is absorbed; a branch in a larger stack
+    is refused.
+
+    Without --no-push the incoming branch must already be on origin
+    (`git push -u origin <branch>` first), and if its push is declined
+    or rejected, join stops before touching anything above it. A branch
+    above the insertion point that was cut from an older, since-
+    rewritten version of the incoming branch is refused, with the
+    `git rebase --onto` that drops its stale copies. (A child cut from
+    an earlier tip that was only appended to is handled automatically.)
+    Unknown options are an error.
+
+    --dry-run   Show the resulting stack and, for every affected PR,
+                its projected commits / files changed vs its new parent,
+                plus how far the incoming branch is behind main. Changes
+                nothing (uses the last fetch of origin/main).
+    --no-push   As for restack: rebase and update metadata locally, and
+                leave origin and the PR bases alone. The next `submit`
+                pushes and retargets together.
+
+    Takes a snapshot first (`gh-stack undo` restores every branch,
+    including the incoming one). Refuses on a dirty tree, and when the
+    branches above the insertion point need a restack first. On a
+    conflict syncing the incoming branch the stack is left unchanged:
+    resolve, `git rebase --continue`, and re-run the same join (or
+    `git rebase --abort`). A conflict restacking the branches above it
+    resumes like restack: `git rebase --continue`, then
+    `gh-stack restack --resume`.
+
 rename [<old-name>] <new-name>
     Rename a tracked branch (runs `git branch -m`) and re-key the stack
     topology so it stays tracked, re-parenting any children that pointed
@@ -313,6 +464,13 @@ undo
 archive [--restore <name>]
     List archived stacks by default, or restore one by name.
 
+config [--json]
+    Show every configurable flag default, its resolved value, and where
+    it came from (flag/env/repo config/user config/built-in), plus the
+    config file paths. Answers "why did this PR open as a draft?" in
+    one command. Works outside a git repo too (user and env layers
+    only). Read-only; edit the TOML files directly.
+
 doctor
     Migrate old (v2) metadata to the v3 layout, reconcile git branch
     config against the topology files, and flag stacks whose base
@@ -327,9 +485,21 @@ learn [--skill] [--harness <name>] [--global] [--force]
       Claude Code  <root>/.claude/skills/using-gh-stack/SKILL.md
       Codex        <root>/.codex/skills/using-gh-stack/SKILL.md
       Cursor       <root>/.cursor/skills/using-gh-stack/SKILL.md
-    --harness  claude | codex | cursor (skips the interactive prompt)
+    --harness  claude | codex | cursor | all, or a comma list such as
+               claude,codex (skips the interactive prompt). Each target
+               is checked and installed on its own.
     --global   Install under ~/.<harness>/ instead of the project root
-    --force    Overwrite an existing skill file without confirming
+    --force    Overwrite an existing skill file without confirming, and
+               write through a symlinked skill dir or SKILL.md
+    If the skill dir or SKILL.md is a symlink (say, into a skills repo
+    you keep under version control), the install refuses and names the
+    link target. Only --force writes through it; --yes / GH_STACK_YES
+    does not. A dangling link is never written through: remove it to
+    install there. Harnesses that resolve to the same SKILL.md (a linked
+    skill dir or a shared skills/ dir) are written once and reported as
+    installed via the first. Cancelling an overwrite prompt lists what
+    was installed and what was not attempted, and exits non-zero. The
+    closing refresh hint repeats the --global and --harness you used.
 ```
 
 ## Global Options
@@ -350,10 +520,51 @@ If a command needs to prompt but stdin isn't a TTY, it exits 1 with the prompt i
 ```
 GH_STACK_YES=1         Skip all confirmations (same as --yes; also enables --plain)
 GH_STACK_PLAIN=1       Plain output (same as --plain)
-GH_STACK_NO_PUSH=1     restack/sync never push (same as --no-push; wins over --yes)
+GH_STACK_NO_PUSH=1     restack/sync never push (same as --no-push; wins over --yes; 0 = push)
+GH_STACK_DRAFT=1       submit creates new PRs as drafts (same as --draft; 0 = ready)
+                       (both accept 1/0, true/false, yes/no; anything else is an error)
 GH_STACK_NO_COLOR=1    Disable colored output
 ```
 
+## Configuration
+
+Flags that encode a repo's conventions can get a default, so nobody has to
+remember to type them:
+
+```toml
+# .gh-stack.toml at the repo root (commit it), or
+# ~/.config/gh-stack/config.toml for personal defaults (honors XDG_CONFIG_HOME)
+[submit]
+draft = true      # new PRs open as drafts; --no-draft overrides for one PR
+
+[restack]
+push = false      # restack and sync stay local; --push overrides
+```
+
+Precedence, highest first: **CLI flag > env var > repo config > user config >
+built-in default**. `gh-stack config` prints each resolved value and its
+source. When a default (rather than a flag) decides draft or push, the command
+says so in its output.
+
+| Key              | Flags                    | Env                           | Built-in |
+| ---------------- | ------------------------ | ----------------------------- | -------- |
+| `[submit] draft` | `--draft` / `--no-draft` | `GH_STACK_DRAFT`              | `false`  |
+| `[restack] push` | `--push` / `--no-push`   | `GH_STACK_NO_PUSH` (inverted) | `true`   |
+
+`[restack] push` governs `restack` and `sync` only. `merge` and
+`submit --restack` always push the branches they restack: publishing is their
+job, and child PRs left stale on GitHub would be worse than any default. A
+`restack --resume` keeps the push decision of the run it resumes unless you
+pass `--push` or `--no-push`.
+
+Unknown keys print a warning and are ignored. Malformed TOML, an unreadable
+config file, a non-boolean value for a known key, or an env value other than
+`1/0`, `true/false`, `yes/no` is an error naming the file or variable. It is
+reported before the command changes anything, and a command given an explicit
+flag (`--draft`, `--push`, ...) never reads the config for that setting. `--yes` can't be set in a config file:
+auto-confirming destructive operations has to be asked for per run, with
+`--yes` or `GH_STACK_YES=1`.
+
 ## How It Works
 
 ### Smart Init
@@ -421,7 +632,7 @@ per-stack files plus git-native branch config, rather than a single JSON blob:
   archived/<stack>.json        merged/closed stacks
   deleted/<stack>.json         tombstones (recoverable)
   snapshots/<ts>__<stack>.json append-only, retained per-stack
-  restack-state.json           in-flight restack/sync resume state
+  restack-state.json           the last restack/sync/join run: resume point + action log
 ```
 
 A single `active/<stack>.json` looks like:
@@ -530,6 +741,7 @@ and gotchas straight from the binary:
 # Teach an agent the current API (always in sync with the installed version)
 gh-stack learn                              # print the skill to stdout
 gh-stack learn --skill --harness claude     # install it for Claude Code
+gh-stack learn --skill -g --harness all     # every harness, in your home dir
 ```
 
 ```bash
@@ -545,7 +757,11 @@ gh-stack restack
 # Rebase without publishing (e.g. before a human approves the push)
 GH_STACK_NO_PUSH=1 gh-stack restack
 
+# Check which defaults apply here (.gh-stack.toml, user config, env)
+gh-stack config
+
 # Structured output
+gh-stack submit --json -t "Title" --body-file body.md   # PR number + URL per branch
 gh-stack status --json
 gh-stack status --current --json
 gh-stack ls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-stack",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",
@@ -33,7 +33,8 @@
   },
   "scripts": {
     "dev": "bun run src/index.ts",
-    "build": "bun build --compile src/index.ts --outfile dist/gh-stack",
+    "build": "bun build --compile src/index.ts --outfile dist/gh-stack && bun run sign",
+    "sign": "[ \"$(uname)\" != Darwin ] || codesign --force --sign - dist/gh-stack",
     "test": "bun test",
     "lint": "oxlint src/",
     "format": "oxfmt --write src/",
@@ -50,17 +51,17 @@
     ]
   },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "1.3.10",
     "husky": "^9.1.7",
-    "lint-staged": "^16.3.3",
-    "oxfmt": "^0.40.0",
-    "oxlint": "^1.55.0"
+    "lint-staged": "^17.6.0",
+    "oxfmt": "^0.74.0",
+    "oxlint": "^1.89.0"
   },
   "peerDependencies": {
     "typescript": "^5"
   },
   "dependencies": {
-    "@clack/prompts": "^1.1.0",
+    "@clack/prompts": "^1.8.1",
     "picocolors": "^1.1.1"
   }
-}
+}

package/src/commands/config.ts

@@ -0,0 +1,133 @@
+// gh-stack config — Show the resolved flag defaults and where each came from.
+//
+// Answers "why did this open as a draft?" in one command. Read-only: it never
+// writes a config file (edit the TOML directly).
+import pc from "picocolors";
+import {
+  SETTINGS,
+  describeSource,
+  loadConfigLayers,
+  resolveSetting,
+  type ConfigFile,
+  type ConfigLayers,
+  type ConfigSource,
+  type SettingName,
+  ConfigError,
+} from "../lib/config.ts";
+
+const HELP = `
+gh-stack config — Show flag defaults and where each value comes from
+
+USAGE
+  gh-stack config [--json]
+
+Prints every configurable default with its resolved value and source. Values
+resolve, highest first: CLI flag > env var > repo config > user config >
+built-in default. Outside a git repo it shows the user and env layers only.
+
+FILES
+  .gh-stack.toml                     Repo root (commit it to share conventions)
+  ~/.config/gh-stack/config.toml     Personal defaults (honors XDG_CONFIG_HOME)
+
+  [submit]
+  draft = true        # new PRs open as drafts       (--draft / --no-draft)
+
+  [restack]
+  push = false        # restack and sync stay local  (--push / --no-push)
+                      # (merge and submit --restack always push)
+
+ENVIRONMENT (1/0, true/false, or yes/no)
+  GH_STACK_DRAFT       submit draft default
+  GH_STACK_NO_PUSH     restack/sync push default (1 = don't push)
+
+--yes is not configurable from a file: auto-confirming destructive operations
+must be asked for per run (--yes or GH_STACK_YES=1).
+
+OPTIONS
+  --json    Output as JSON
+`;
+
+export interface ConfigReport {
+  settings: {
+    key: string;
+    value: boolean;
+    source: ConfigSource;
+    origin: string | null;
+    flags: string[];
+    env: string;
+  }[];
+  files: { repo: FileInfo | null; user: FileInfo | null };
+}
+
+interface FileInfo {
+  path: string;
+  exists: boolean;
+}
+
+function fileInfo(f: ConfigFile | null): FileInfo | null {
+  return f ? { path: f.path, exists: f.exists } : null;
+}
+
+function fileLine(label: string, f: FileInfo | null): string {
+  return f
+    ? `  ${label}  ${f.path} ${f.exists ? "" : pc.dim("(not found)")}`.trimEnd()
+    : `  ${label}  ${pc.dim("(not in a git work tree)")}`;
+}
+
+/** Build the report from loaded layers. Pure, so it's unit-testable. */
+export function buildConfigReport(layers: ConfigLayers): ConfigReport {
+  return {
+    settings: (Object.keys(SETTINGS) as SettingName[]).map((name) => {
+      const spec = SETTINGS[name];
+      const r = resolveSetting(name, [], layers);
+      return {
+        key: name,
+        value: r.value,
+        source: r.source,
+        origin: r.origin ?? null,
+        flags: [...spec.onFlags, ...spec.offFlags],
+        env: spec.env.name,
+      };
+    }),
+    files: { repo: fileInfo(layers.repo), user: fileInfo(layers.user) },
+  };
+}
+
+export default async function config(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(HELP);
+    return;
+  }
+
+  // Both steps can throw ConfigError: loading (bad TOML, wrong-typed value)
+  // and resolving (a non-boolean env var).
+  let report: ConfigReport;
+  try {
+    const loaded = await loadConfigLayers();
+    for (const w of loaded.warnings) console.error(`gh-stack: warning: ${w}`);
+    report = buildConfigReport(loaded.layers);
+  } catch (err) {
+    if (!(err instanceof ConfigError)) throw err;
+    console.error(`gh-stack: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log();
+  const width = Math.max(...report.settings.map((s) => s.key.length));
+  for (const s of report.settings) {
+    const value = s.value ? pc.green("true ") : pc.yellow("false");
+    const source = describeSource({ ...s, origin: s.origin ?? undefined });
+    console.log(`  ${s.key.padEnd(width)}  ${value}  ${pc.dim(source)}`);
+  }
+
+  console.log();
+  console.log(pc.dim("Config files:"));
+  console.log(fileLine("repo", report.files.repo));
+  console.log(fileLine("user", report.files.user));
+  console.log();
+}