Fix/gitclone local checkout outputs (#196)

* fix(GitClone): produce the same outputs from a local checkout as from a clone

Two ways a local checkout silently came up short of the clone path's outputs,
leaving downstream blocks stuck on "Waiting for outputs from: … (repo_owner,
org_id, repo_name, repo_id)".

Remote resolution only ever looked at `origin` (GitClient.getInfo). A checkout
that names its remote something else — a fork whose upstream is the interesting
one, a repo re-pointed after `git init` — yielded no remote at all, so there was
no repo_owner/repo_name, and no org_id/repo_id either, since those are looked up
from the owner and name. inspectLocalRepo now falls back to whichever remote the
repo does have. `origin` is still preferred, so remote order decides nothing in
the common case.

The org/repo ids are resolved once, at confirm time, from the session token.
Because selecting a checkout deliberately didn't wait on the linked auth block,
confirming before authenticating produced a block permanently missing org_id and
repo_id. Confirming now waits for the auth block exactly as cloning does; the
path field, the folder picker, and the inline "is this a git repo?" check stay
usable while it's pending, since none of those need credentials.

Docs updated: the local source no longer claims to need no credentials, and the
no-remote caution now names the outputs that go missing with it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(GitClone): stop the local-checkout preview from reading as a finished block

The "is this a git repo?" check rendered in the same green success styling as
the completed state — check icon, root, remote, branch, file count — so a
checked directory looked like a block that had run. It hasn't: nothing is
registered and no outputs exist until "Use This Repo" is confirmed, and a block
that has produced no outputs leaves every consumer reporting each referenced
name as missing ("Waiting for outputs from: clone_repo (repo_owner, org_id,
repo_name, repo_id)") — which reads as the outputs being unsupported rather than
the block being unfinished.

The preview is now informational rather than success-styled, green being
reserved for the completed state, and says outright that the directory is not in
use yet. The no-remote warning names the outputs that go missing with it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* uptick to 0.21.1

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(GitClone): address review — docs contradictions and interrupt-safe git queries

Three findings from the review of #195.

The docs said choosing a directory "reads it only" and in the same sentence that
it "registers the repo exactly as a clone would" — the contradiction at the
heart of the reported bug. Inspection and confirmation are now described as the
separate steps they are, including that a block which hasn't been confirmed has
produced nothing and leaves its consumers reporting missing outputs.

The integration paragraph still said a pull request opens against the checkout's
`origin` remote, which contradicts the new fallback two paragraphs below it. It
now says "the checkout's remote".

firstRemoteUrl spawned git without ever killing the child, so an interrupted
fiber would orphan it. Rather than plumbing a Scope through inspectLocalRepo and
the handler — which would leave this helper inconsistent with countFiles three
lines away, which has the same property and is shared with the clone path —
the shared readGitLines helper wraps its drain in Effect.ensuring(kill). Same
guarantee, no signature change, no interruption path exists today anyway: on the
normal path the process has already exited and the signal is a no-op.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Add a bootstrap for new repositories with no commits

* uptick to 0.21.2

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(GitClone): address review — spellcheck, best-effort hasCommits, unique input id

- docs: "colour" → "color" in GitClone.mdx. cspell runs US English and it
  was the only occurrence, so the whole Documentation Tests job failed
  before build or linkcheck ran.

- electron/main/ipc/git.ts: wrap the clone flow's hasCommits query in
  Effect.orElseSucceed(() => true), as every other caller already does.
  Bare, a failed query failed the whole git:clone program after the clone
  had already landed on disk — the user saw an error, the worktree was
  never registered, and the outputs were lost. Defaulting to true also
  matches the domain rule that an unreadable repo counts as having
  history, so nobody is offered a seeded branch by mistake.

- EmptyRepoWarning: derive the branch input's id from useId() instead of
  the literal "empty-repo-branch". Two GitClone blocks on empty repos in
  one runbook produced duplicate ids, so both labels pointed at the first
  input.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: odgrim

docs/src/content/docs/authoring/blocks/GitClone.mdx

@@ -128,6 +128,24 @@ Set `showFileTree={false}` if you don't want the cloned repository to appear in
 
 A local checkout registers with the workspace the same way. Note that the **Changed** tab then shows any uncommitted changes the checkout already had, not just the ones the runbook makes.
 
+### Repositories With No Commits
+
+A repository that was created but never pushed to has no branches at all. Nothing downstream can open a pull request against it: the base branch a pull request needs does not exist, and the provider rejects the request as invalid — after the runbook has already committed and pushed its work.
+
+GitClone detects this case for both sources. When the repo has no commits, the block:
+
+- renders in the warning color rather than reporting a plain success,
+- withholds its outputs (including `clone_path`) and does not register the repository with the workspace, so blocks that depend on it stay blocked,
+- offers a **Create default branch** button that pushes a single empty commit to the branch the remote advertises as its default. The name is editable before you press it.
+
+Once the branch exists, the block releases its outputs and registers the workspace exactly as it would have for a repository that already had commits, and the runbook continues.
+
+The seeded commit is deliberately empty. It gives the default branch something to point at, so the branch the runbook pushes later shares an ancestor with it and opens as a reviewable diff instead of an unrelated root commit. Files already written into the work tree are left untracked, not swept into it.
+
+<Aside type="note">
+  Seeding requires a linked auth block, since it pushes to the remote. The branch is created locally, committed, and pushed to `origin` in one step.
+</Aside>
+
 ### Accepted Git URL Formats
 
 The GitClone block accepts the following URL formats:

electron/main/ipc/git.ts

@@ -17,6 +17,8 @@ import {
   deleteBranch,
   createPullRequest,
   createMergeRequest,
+  seedDefaultBranch,
+  unbornBranchName,
   isValidGitURL,
   parseOwnerRepoFromURL,
   type CreatePullRequestParams,
@@ -368,6 +370,29 @@ export function registerGitHandlers(): void {
           // Count tracked files using `git ls-files` (fast, ~10ms)
           const fileCount = yield* countFiles(paths.absolutePath)
 
+          // Report the ref the clone actually landed on rather than letting the
+          // renderer assume one. Cloning without an explicit `ref` follows the
+          // remote's default branch, which is not always "main" — and that ref
+          // becomes the base branch of any pull request opened against this
+          // checkout, so guessing it wrong fails the PR at the very last step.
+          const gitClient = yield* GitClient
+          // Best-effort, like every other caller: a failed query must not fail
+          // the whole clone after it already landed on disk, which would lose
+          // the outputs and skip worktree registration. A repo we cannot read
+          // counts as having history, so nobody is offered a seeded branch by
+          // mistake.
+          const hasCommits = yield* gitClient
+            .hasCommits(paths.absolutePath)
+            .pipe(Effect.orElseSucceed(() => true))
+          const clonedRef = hasCommits
+            ? (yield* gitClient
+                .getCurrentBranch(paths.absolutePath)
+                .pipe(Effect.orElseSucceed(() => "")))
+            : // An empty repo has no branch yet; HEAD still names the one the
+              // remote advertised, which is what a seeded first commit should
+              // become.
+              ((yield* unbornBranchName(paths.absolutePath)) ?? "")
+
           // Register the worktree path
           sessionManager.registerWorkTreePath(paths.absolutePath)
           log.debug("registered worktree, returning result")
@@ -401,6 +426,8 @@ export function registerGitHandlers(): void {
             absolutePath: paths.absolutePath,
             relativePath: paths.relativePath,
             fileCount,
+            ref: clonedRef,
+            hasCommits,
             status: "success" as const,
             outputs,
           }
@@ -476,6 +503,7 @@ export function registerGitHandlers(): void {
           ref: info.branch,
           refType: info.refType,
           commitSha: info.commitSha,
+          hasCommits: info.hasCommits,
           outputs,
         }
       })
@@ -553,6 +581,58 @@ export function registerGitHandlers(): void {
     },
   )
 
+  // Seed an empty repository with its default branch. Offered by <GitClone>
+  // when it clones (or is pointed at) a repo that has no commits: without a
+  // branch on the remote there is nothing for a later pull request to target,
+  // and the failure would otherwise surface only after the runbook's work had
+  // been committed and pushed.
+  ipcMain.handle(
+    "git:init-default-branch",
+    async (
+      event,
+      params: {
+        worktreePath: string
+        branch: string
+        provider?: "github" | "gitlab"
+      },
+    ) => {
+      const sendLog = makeSendLog(event)
+
+      const program = Effect.gen(function* () {
+        const repoPath = yield* validateSessionPath(params.worktreePath)
+        const provider = params.provider ?? "github"
+        const token = yield* getSessionTokenForProvider(
+          provider,
+          () =>
+            new GitError({
+              command: "resolve git token",
+              stderr: `No ${provider} token available in session. Authenticate with the matching Git Auth block before creating the default branch.`,
+              exitCode: 1,
+            }),
+        )
+
+        const branch = params.branch.trim() || "main"
+        return yield* seedDefaultBranch(token, { repoPath, branch, provider }, sendLog)
+      })
+
+      const exit = await runtime.runPromiseExit(program)
+
+      if (Exit.isSuccess(exit)) {
+        event.sender.send("git:status", { status: "success", exitCode: 0 })
+        return { branch: exit.value.branch }
+      }
+
+      const failure = Cause.failureOption(exit.cause)
+      const message =
+        failure._tag === "Some"
+          ? errorMessage(failure.value)
+          : Cause.pretty(exit.cause)
+      event.sender.send("git:error", { message })
+      event.sender.send("git:status", { status: "fail", exitCode: 1 })
+      return { error: message }
+    },
+  )
+
   ipcMain.handle("git:pull-request", async (event, params: GitPrParams) => {
     const sendLog = makeSendLog(event)
 

electron/preload/index.ts

@@ -19,7 +19,7 @@ const ALLOWED_INVOKE_CHANNELS: Set<string> = new Set<InvokeChannel>([
   "gitlab:validate", "gitlab:env-credentials", "gitlab:cli-credentials", "gitlab:labels", "gitlab:enumerate-hosts",
   "gitlab:host-picked",
   "vcs:cli-status", "vcs:invalidate-cache", "vcs:apply-git-schannel",
-  "git:clone", "git:local-repo", "git:push", "git:pull-request", "git:merge-request", "git:delete-branch",
+  "git:clone", "git:local-repo", "git:push", "git:init-default-branch", "git:pull-request", "git:merge-request", "git:delete-branch",
   "workspace:tree", "workspace:dirs", "workspace:file", "workspace:changes",
   "workspace:register", "workspace:set-active",
   "generated-files:check", "generated-files:delete",

electron/shared/channels.ts

@@ -491,13 +491,28 @@ export interface IpcChannelMap {
   // Git Operations
   "git:clone": {
     params: GitCloneRequest
-    result: { status: string; error?: string; fileCount?: number; absolutePath?: string; relativePath?: string; outputs?: Record<string, string> }
+    result: {
+      status: string
+      error?: string
+      fileCount?: number
+      absolutePath?: string
+      relativePath?: string
+      /** Branch the clone landed on — the base branch of any PR opened against it. */
+      ref?: string
+      /** False for a repo with no commits: it has no branch a PR could target. */
+      hasCommits?: boolean
+      outputs?: Record<string, string>
+    }
   }
   "git:local-repo": {
     params: GitLocalRepoRequest
     result: GitLocalRepoResponse
   }
   "git:push": { params: { worktreePath: string; branchName: string; provider?: "github" | "gitlab" }; result: { ok: true } | { error: string } }
+  "git:init-default-branch": {
+    params: { worktreePath: string; branch: string; provider?: "github" | "gitlab" }
+    result: { branch: string } | { error: string }
+  }
   "git:pull-request": { params: PullRequestRequest; result: { url: string; number: number } | { error: string } }
   "git:merge-request": { params: PullRequestRequest; result: { url: string; number: number } | { error: string } }
   "git:delete-branch": { params: { worktreePath: string; branch: string }; result: { ok: true } }
@@ -852,6 +867,8 @@ export interface GitLocalRepoResponse {
   ref?: string
   refType?: "branch" | "tag" | "detached"
   commitSha?: string
+  /** False for a repo with no commits: it has no branch a PR could target. */
+  hasCommits?: boolean
   outputs?: Record<string, string>
 }
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "runbooks",
-  "version": "0.21.1",
+  "version": "0.21.2",
   "private": true,
   "description": "Gruntwork Runbooks",
   "author": {

src/domain/git/local-repo.test.ts

@@ -122,7 +122,7 @@ describe("inspectLocalRepo", () => {
     expect(info.relativePath).toBe("checkouts/infra")
   })
 
-  it("succeeds for a repo with no commits yet", async () => {
+  it("succeeds for a repo with no commits yet, and says so", async () => {
     const info = await inspect("/home/me/fresh", {
       dirs: ["/home/me/fresh"],
       commands: [lsFiles([])],
@@ -132,12 +132,60 @@ describe("inspectLocalRepo", () => {
           Effect.fail(
             new GitError({ command: "git rev-parse", stderr: "no HEAD", exitCode: 128 }),
           ),
+        hasCommits: () => Effect.succeed(false),
       },
     })
 
     expect(info.branch).toBe("")
     expect(info.fileCount).toBe(0)
     expect(info.owner).toBeUndefined()
+    // The empty branch alone can't be trusted to mean "empty repo" — callers
+    // need this flag to know a base branch has to be seeded before a PR.
+    expect(info.hasCommits).toBe(false)
+  })
+
+  it("treats a repo it can't query as having history, never as empty", async () => {
+    const info = await inspect("/home/me/odd", {
+      dirs: ["/home/me/odd"],
+      commands: [lsFiles([])],
+      git: {
+        getRepoRoot: () => Effect.succeed("/home/me/odd"),
+        getInfo: () => Effect.succeed({ branch: "main", refType: "branch" as const }),
+        hasCommits: () =>
+          Effect.fail(
+            new GitError({ command: "git rev-parse", stderr: "boom", exitCode: 1 }),
+          ),
+      },
+    })
+
+    // Guessing "empty" here would offer to seed a branch over a repo whose
+    // state we simply failed to read.
+    expect(info.hasCommits).toBe(true)
+  })
+
+  it("falls back to a non-origin remote when there is no origin", async () => {
+    const info = await inspect("/home/me/fork", {
+      dirs: ["/home/me/fork"],
+      commands: [
+        { command: "git", args: ["remote"], outputLines: ["upstream"], exitCode: 0 },
+        {
+          command: "git",
+          args: ["remote", "get-url", "upstream"],
+          outputLines: ["git@github.com:acme/infra.git"],
+          exitCode: 0,
+        },
+        lsFiles(["main.tf"]),
+      ],
+      git: {
+        getRepoRoot: () => Effect.succeed("/home/me/fork"),
+        // getInfo only looks at origin, which this checkout doesn't have.
+        getInfo: () => Effect.succeed({ branch: "main", refType: "branch" as const }),
+      },
+    })
+
+    expect(info.remoteUrl).toBe("git@github.com:acme/infra.git")
+    expect(info.owner).toBe("acme")
+    expect(info.repo).toBe("infra")
   })
 
   it("falls back to a non-origin remote when there is no origin", async () => {

src/domain/git/local-repo.ts

@@ -32,6 +32,12 @@ export interface LocalRepoInfo {
   readonly branch: string
   readonly refType: GitInfo["refType"]
   readonly commitSha?: string
+  /**
+   * False when the repo has no commits yet (unborn HEAD). Such a repo has no
+   * branch to open a pull request against, so blocks that need a base ref have
+   * to seed one before they can do anything useful.
+   */
+  readonly hasCommits: boolean
   /** Owner/repo parsed from the remote URL, when parseable. */
   readonly owner?: string
   readonly repo?: string
@@ -128,6 +134,15 @@ export const inspectLocalRepo = (
 
     const fileCount = yield* countFiles(absolutePath)
     const parsed = remoteUrl ? parseOwnerRepoFromURL(remoteUrl) : undefined
+    // Distinguishes "empty repo" from "getInfo failed for some other reason":
+    // both leave `branch` empty above, but only the former is recoverable by
+    // seeding a first commit.
+    // orElseSucceed keeps this best-effort, like the getInfo lookup above: a
+    // repo we can't query is treated as having history, so an unreadable git
+    // never gets mistaken for an empty one and offered a seeded branch.
+    const hasCommits = yield* git
+      .hasCommits(absolutePath)
+      .pipe(Effect.orElseSucceed(() => true))
 
     return {
       absolutePath,
@@ -137,6 +152,7 @@ export const inspectLocalRepo = (
       branch: info.branch,
       refType: info.refType,
       commitSha: info.commitSha,
+      hasCommits,
       owner: parsed?.owner,
       repo: parsed?.repo,
     } satisfies LocalRepoInfo