@paysdoc/devplatform 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Koster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# @paysdoc/devplatform
+
+A TypeScript library of forge-neutral git/worktree primitives plus GitHub, GitLab, and Jira adapters for building dev-workflow automation.
+
+Extracted from [AI_Dev_Workflow](https://github.com/paysdoc/AI_Dev_Workflow) with history.
+Releases are automated by semantic-release on every push to `main`.
+
+## Install
+
+```
+bun add @paysdoc/devplatform
+# or
+npm i @paysdoc/devplatform
+```
+
+The package ships three entry points:
+
+```ts
+import { BoardStatus, type Issue, type RepoContext } from '@paysdoc/devplatform';         // forge ports + domain model
+import { forgeProviders } from '@paysdoc/devplatform/providers';                          // adapter assembly + GitHub/GitLab/Jira adapters
+import { GitContext, consoleLogger } from '@paysdoc/devplatform/git';                     // forge-neutral git/worktree core
+```
+
+## What it does
+
+- **Forge-neutral git executor** — `GitContext.exec()` is the single spawn site, env merge, cwd resolution, and ENOENT rewrap for every git command; no forge semantics leak into it.
+- **Identity-bound context construction** — a `GitContext` is built from a mandatory owner/repo/selfHost/tokenProvider/gitIdentity; incomplete identity fails at construction rather than at first use.
+- **Worktree lifecycle management** — create/ensure, list, remove, probe (health: `healthy`/`locked`/`prunable`/`missing`), and reset (takeover) operations for git worktrees under `.worktrees/`.
+- **Branch, commit, and remote operations** — branch creation/switching, commits, and remote push/fetch helpers layered on the shared executor.
+- **Working-directory guard** — turns a spawn ENOENT caused by a missing cwd into a diagnostic naming the path and repo identity, keyed off the OS-independent error `code`.
+- **Distributed-lock claim primitives** — detached-worktree add/remove, empty-commit nonce marking, and a never-forced push used to implement an atomic winner/loser election (e.g. for upgrade claims).
+- **Process cleanup** — kills processes still running inside a worktree directory before it is removed.
+- **Pluggable credential and logging ports** — `TokenProvider` (credential-purpose-scoped) and `Logger` ports let a consumer supply auth and logging without the core depending on either.
+- **Bootstrap-only git reads** — a narrow, structurally-exempt set of pre-context reads (origin remote URL, env/git-config identity) for use before a full `GitContext` exists.
+- **Forge-neutral provider interfaces** — `IssueTracker`, `CodeHost`, and `BoardManager` ports abstract issue tracking, PR/code hosting, and project boards across platforms.
+- **`forgeProviders()` assembly function** — binds one `RepoIdentifier` to a full provider triple, validating identity, token provider shape, and context binding before constructing any adapter; rejects unknown or wrong-port forge names via `UnknownForgeError`.
+- **GitHub adapter** — issue tracker, code host, and Projects V2 board manager built on the `gh` CLI, including issue/PR read and write operations, label management, GitHub App authentication, and token resolution.
+- **GitLab adapter** — code host implementation backed by a `curl`-based API client with injected configuration (no environment reads).
+- **Jira adapter** — issue tracker backed by the Jira REST API v3, including Markdown ↔ Atlassian Document Format (ADF) conversion.
+- **Board status model** — a canonical, ordered set of board columns (`Blocked`/`Todo`/`In Progress`/`Review`/`Done`) with colors and descriptions shared across board-capable adapters.
+- **Injected configuration everywhere** — GitLab, Jira, and GitHub App adapters take configuration as constructor arguments; none reads `process.env` or files directly, keeping the library embeddable in any host.
+- **Compiled ESM + type declarations** — `bun run build` emits `dist/**/*.js` and `dist/**/*.d.ts` via `tsc`, with a three-entry-point `exports` map (`.`, `./providers`, `./git`) and a `files` allow-list so `npm pack` ships only `dist/`, `README.md`, and `LICENSE`.
+- **CI type-check, git/gh guard, unit-test, and package gate** — GitHub Actions runs `bun install`, `bun run typecheck`, `bun run lint:git-guard`, and `bun run test:unit` on every PR and push to `main`, plus a second job that builds, packs, and smoke-tests the tarball under both Node and Bun.
+- **Automated releases via semantic-release** — a `Release` GitHub Actions job runs semantic-release on every push to `main`, using a commit parser that accepts an optional `<agent-name>: ` prefix before the conventional type (`build-agent: feat: …` → minor, `review-patch-agent: fix: …` → patch, `plan-orchestrator: chore: …` → no release), a PR `release-dry-run` job that prints the computed next version before merge, and npm OIDC trusted publishing with an `NPM_TOKEN` fallback.
+- **Git/gh CI guard** — an AST-based check (`bun run lint:git-guard`, `scripts/checkGitGhGuard.ts` + `scripts/guard/`) that fails CI on a direct `git`/`gh` shell-out outside `src/git/` and `src/providers/github/` (the two structurally-exempt packages), or on ad-hoc provider/`GitContext` construction anywhere outside the one-entry `src/providers/forgeProviders.ts` allowlist.
+- **Claude Code agent guardrails** — a hooked `.claude/settings.json` and `.claude/hooks/*` scripts (pre/post-tool-use, notification, stop, subagent-stop) constrain and observe agent tool use in this repo.
+
+## Setup
+
+1. Install dependencies: `bun install`
+2. Copy the environment template and fill in your own values: `cp .env.sample .env`
+3. Type-check: `bun run typecheck`
+4. Run the unit test suite: `bun run test:unit`
+5. Build: `bun run build`
+
+## Releasing
+
+Releases are computed by [semantic-release](https://semantic-release.gitbook.io/) from commit messages on
+every push to `main` — see `release.config.js`. Commit headers must follow the conventional-commits format,
+optionally preceded by a hyphenated agent name:
+
+```
+[<agent-name>: ]<type>[(<scope>)][!]: <subject>
+```
+
+- `feat: …` / `<agent-name>: feat: …` → minor release
+- `fix: …` / `<agent-name>: fix: …` → patch release
+- `feat!: …`, or any commit with a `BREAKING CHANGE:` footer → major release
+- `chore: …`, `docs: …`, and other non-releasing types → no release
+
+The agent-name prefix must be a lowercase, hyphenated token (e.g. `build-agent`, `plan-orchestrator`) so it
+can never be confused with a conventional type. Every pull request runs a `release-dry-run` CI job that
+prints the version the merge would compute, without publishing anything.
+
+Publishing uses npm OIDC trusted publishing (no long-lived npm credential stored in the repository), falling
+back to an `NPM_TOKEN` secret if one is present. The release baseline is the `v1.0.0` git tag on the commit
+of the first manually published version; the release workflow hard-fails if that tag is not reachable, so it
+can never recompute or republish `1.0.0`.
+
+## Domain glossary
+
+See [UBIQUITOUS_LANGUAGE.md](./UBIQUITOUS_LANGUAGE.md) for the canonical terms used across this codebase (identity, forge, provider, worktree, etc.).
+
+## Project Structure
+
+```
+.adw/                        ADW-generated project docs (project.md, providers.md, commands.md, conditional_docs.md, review_proof.md, scenarios.md)
+.adw-version                  ADW template version marker
+.claude/
+  commands/                   ADW-copied slash commands (gitignored except install.md, prime.md)
+  hooks/                      Claude Code lifecycle hooks (pre/post-tool-use, notification, stop, subagent-stop)
+  skills/                     Agent skills (TDD, PRD authoring, architecture review, ubiquitous language, ...)
+  settings.json                Agent permission/guardrail configuration
+.github/
+  workflows/ci.yml             Typecheck + git/gh guard + unit test CI gate, build/pack/smoke-test package gate, and a PR-only release-dry-run job
+  workflows/release.yml        Release automation: semantic-release on push to main (v1.0.0 baseline guard, OIDC + NPM_TOKEN fallback)
+  adw.yml                      ADW guardrails toggle (outside .adw/, survives regeneration)
+app_docs/                    Per-module documentation owned by conditional_docs.md routing (ADW-generated)
+UBIQUITOUS_LANGUAGE.md       Canonical domain glossary
+features/regression/vocabulary.md   Regression test vocabulary
+specs/                        Per-issue implementation plans (ADW-generated)
+release.config.js             semantic-release configuration: agent-prefix-aware commit parser, branches, plugin list
+scripts/
+  smokePackage.ts             Builds, packs, and smoke-tests the tarball under Node + Bun (`bun run smoke:package`)
+  releaseDryRun.ts             Runs `semantic-release --dry-run` and prints the computed next version (`bun run release:dry-run`)
+  checkGitGhGuard.ts          CI git/gh guard entry point (`bun run lint:git-guard`) — dev-only, excluded from dist/
+  guard/                      Guard rule modules: shell-out exempt-package set, construction allowlist, stdout report
+src/
+  index.ts                    Root entry point ("."): forge ports + domain model only
+  __tests__/                  Import-graph, package-exports, and release-config contract tests
+  git/                        Forge-neutral git/worktree core (GitContext, worktree ops, bootstrap identity, process cleanup) — entry point "./git"
+  providers/                  Forge provider ports and adapters — entry point "./providers"
+    github/                   GitHub adapter (issue tracker, code host, board manager, App auth, gh CLI commands)
+    gitlab/                   GitLab adapter (API client, code host, type mappers)
+    jira/                     Jira adapter (API client, issue tracker, ADF converter)
+    forgeProviders.ts          Provider assembly function
+    types.ts                   Platform-agnostic provider interfaces
+dist/                        Build output (gitignored) — emitted by `bun run build`
+tsconfig.json                 TypeScript strict-mode configuration (NodeNext modules/resolution)
+tsconfig.build.json            Build config: extends tsconfig.json, emits dist/**/*.js + dist/**/*.d.ts
+vitest.config.ts               Vitest configuration (JUnit output via $ADW_UNIT_TEST_REPORT_PATH)
+```

package/dist/git/bootstrapIdentity.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Bootstrap identity resolution — absorbed into the gitContext package (issue #700).
+ *
+ * Pre-context git reads: the one legitimate permanent exception for raw git
+ * before a GitContext exists. Lives inside the structurally-exempt package so
+ * the guard skips it by directory, not by allowlist.
+ *
+ * Generic **git** reads only (issue #793) — no forge vocabulary. GitHub
+ * remote-URL parsing, App bot-identity derivation, and the `gh` CLI
+ * credential read all live in the GitHub forge adapter
+ * (`adws/providers/github/`), which composes these readers rather than
+ * re-implementing them.
+ *
+ * No ADW-global imports. All I/O is behind injectable seams for hermetic testing.
+ */
+import type { GitIdentity } from './types.js';
+export interface GitConfigIdentityDeps {
+    exec?: (cmd: string, opts: {
+        encoding: 'utf-8';
+        cwd?: string;
+        stdio?: unknown;
+    }) => string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Reads the local git remote URL, trimmed. Throws with the raw git failure —
+ * parsing (and the forge-specific error wrapping around it) is the adapter's
+ * job, not the core's.
+ */
+export declare function readOriginRemoteUrl(cwd?: string): string;
+/**
+ * Reads the current branch name, trimmed. Throws with the raw git failure on
+ * a detached HEAD or any other git failure — the caller decides how to
+ * degrade, the core does not guess.
+ */
+export declare function readCurrentBranch(cwd?: string): string;
+/**
+ * `GIT_AUTHOR_*` / `GIT_COMMITTER_*` env reads. Pure. Returns a complete
+ * identity, or null when the author fields are incomplete — the core
+ * supplies no fallback of its own (issue #793: no forge address may
+ * originate here).
+ */
+export declare function readEnvGitIdentity(env: NodeJS.ProcessEnv): GitIdentity | null;
+/**
+ * `git config user.name` / `user.email`. Returns a complete identity, or
+ * null on any git failure or incomplete config — the core supplies no
+ * fallback of its own.
+ */
+export declare function readGitConfigIdentity(deps?: GitConfigIdentityDeps): GitIdentity | null;
+//# sourceMappingURL=bootstrapIdentity.d.ts.map

package/dist/git/bootstrapIdentity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrapIdentity.d.ts","sourceRoot":"","sources":["../../src/git/bootstrapIdentity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM9C,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,MAAM,CAAC;IAC3F,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEtD;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,WAAW,GAAG,IAAI,CAU7E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,qBAA0B,GAAG,WAAW,GAAG,IAAI,CAU1F"}

package/dist/git/bootstrapIdentity.js

@@ -0,0 +1,72 @@
+/**
+ * Bootstrap identity resolution — absorbed into the gitContext package (issue #700).
+ *
+ * Pre-context git reads: the one legitimate permanent exception for raw git
+ * before a GitContext exists. Lives inside the structurally-exempt package so
+ * the guard skips it by directory, not by allowlist.
+ *
+ * Generic **git** reads only (issue #793) — no forge vocabulary. GitHub
+ * remote-URL parsing, App bot-identity derivation, and the `gh` CLI
+ * credential read all live in the GitHub forge adapter
+ * (`adws/providers/github/`), which composes these readers rather than
+ * re-implementing them.
+ *
+ * No ADW-global imports. All I/O is behind injectable seams for hermetic testing.
+ */
+import { execSync } from 'child_process';
+// ---------------------------------------------------------------------------
+// readOriginRemoteUrl
+// ---------------------------------------------------------------------------
+/**
+ * Reads the local git remote URL, trimmed. Throws with the raw git failure —
+ * parsing (and the forge-specific error wrapping around it) is the adapter's
+ * job, not the core's.
+ */
+export function readOriginRemoteUrl(cwd) {
+    return execSync('git remote get-url origin', { encoding: 'utf-8', cwd }).trim();
+}
+/**
+ * Reads the current branch name, trimmed. Throws with the raw git failure on
+ * a detached HEAD or any other git failure — the caller decides how to
+ * degrade, the core does not guess.
+ */
+export function readCurrentBranch(cwd) {
+    return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8', cwd }).trim();
+}
+// ---------------------------------------------------------------------------
+// readEnvGitIdentity / readGitConfigIdentity
+// ---------------------------------------------------------------------------
+/**
+ * `GIT_AUTHOR_*` / `GIT_COMMITTER_*` env reads. Pure. Returns a complete
+ * identity, or null when the author fields are incomplete — the core
+ * supplies no fallback of its own (issue #793: no forge address may
+ * originate here).
+ */
+export function readEnvGitIdentity(env) {
+    const authorName = env['GIT_AUTHOR_NAME'];
+    const authorEmail = env['GIT_AUTHOR_EMAIL'];
+    const committerName = env['GIT_COMMITTER_NAME'] || authorName;
+    const committerEmail = env['GIT_COMMITTER_EMAIL'] || authorEmail;
+    if (authorName && authorEmail && committerName && committerEmail) {
+        return { authorName, authorEmail, committerName, committerEmail };
+    }
+    return null;
+}
+/**
+ * `git config user.name` / `user.email`. Returns a complete identity, or
+ * null on any git failure or incomplete config — the core supplies no
+ * fallback of its own.
+ */
+export function readGitConfigIdentity(deps = {}) {
+    const exec = deps.exec ?? ((cmd, opts) => execSync(cmd, opts));
+    try {
+        const name = exec('git config user.name', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const email = exec('git config user.email', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        if (name && email) {
+            return { authorName: name, authorEmail: email, committerName: name, committerEmail: email };
+        }
+    }
+    catch { /* git config not available */ }
+    return null;
+}
+//# sourceMappingURL=bootstrapIdentity.js.map

package/dist/git/bootstrapIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrapIdentity.js","sourceRoot":"","sources":["../../src/git/bootstrapIdentity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAYzC,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,QAAQ,CAAC,2BAA2B,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAClF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,QAAQ,CAAC,iCAAiC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACxF,CAAC;AAED,8EAA8E;AAC9E,6CAA6C;AAC7C,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,MAAM,UAAU,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC5C,MAAM,aAAa,GAAG,GAAG,CAAC,oBAAoB,CAAC,IAAI,UAAU,CAAC;IAC9D,MAAM,cAAc,GAAG,GAAG,CAAC,qBAAqB,CAAC,IAAI,WAAW,CAAC;IAEjE,IAAI,UAAU,IAAI,WAAW,IAAI,aAAa,IAAI,cAAc,EAAE,CAAC;QACjE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;IACpE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA8B,EAAE;IACpE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAsC,CAAW,CAAC,CAAC;IAC3G,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,sBAAsB,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACzG,MAAM,KAAK,GAAG,IAAI,CAAC,uBAAuB,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC3G,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;YAClB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;QAC9F,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAC,8BAA8B,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/git/branchOps.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Package-private branch operation orchestration for GitContext.
+ * Each function takes an injected runner (cmd, cwd) => string so GitContext
+ * methods stay thin and this module is testable without a real context.
+ */
+export declare const PROTECTED_BRANCHES: readonly ["main", "master", "develop"];
+type Runner = (command: string, cwd: string) => string;
+declare function getCurrentBranch(run: Runner, cwd: string): string;
+declare function mergeLatestFromDefaultBranch(run: Runner, defaultBranch: string, cwd: string): void;
+declare function fetchAndResetToRemote(run: Runner, defaultBranch: string, cwd: string): void;
+declare function deleteLocalBranch(run: Runner, branch: string, cwd: string): boolean;
+declare function deleteRemoteBranch(run: Runner, branch: string, cwd: string): boolean;
+/**
+ * Returns local branch names from `git branch --list`.
+ * Strips the leading `*`/whitespace marker; returns [] on failure.
+ */
+declare function localBranches(run: Runner, cwd: string): string[];
+export declare const branchOps: {
+    getCurrentBranch: typeof getCurrentBranch;
+    mergeLatestFromDefaultBranch: typeof mergeLatestFromDefaultBranch;
+    fetchAndResetToRemote: typeof fetchAndResetToRemote;
+    deleteLocalBranch: typeof deleteLocalBranch;
+    deleteRemoteBranch: typeof deleteRemoteBranch;
+    localBranches: typeof localBranches;
+};
+export {};
+//# sourceMappingURL=branchOps.d.ts.map

package/dist/git/branchOps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branchOps.d.ts","sourceRoot":"","sources":["../../src/git/branchOps.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,kBAAkB,wCAAyC,CAAC;AAEzE,KAAK,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAMvD,iBAAS,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,iBAAS,4BAA4B,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAY3F;AAED,iBAAS,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAWpF;AAED,iBAAS,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ5E;AAED,iBAAS,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;GAGG;AACH,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAYzD;AAED,eAAO,MAAM,SAAS;;;;;;;CAOrB,CAAC"}

package/dist/git/branchOps.js

@@ -0,0 +1,91 @@
+/**
+ * Package-private branch operation orchestration for GitContext.
+ * Each function takes an injected runner (cmd, cwd) => string so GitContext
+ * methods stay thin and this module is testable without a real context.
+ */
+export const PROTECTED_BRANCHES = ['main', 'master', 'develop'];
+function isProtected(branch) {
+    return PROTECTED_BRANCHES.includes(branch);
+}
+function getCurrentBranch(run, cwd) {
+    return run('git branch --show-current', cwd);
+}
+function mergeLatestFromDefaultBranch(run, defaultBranch, cwd) {
+    try {
+        run(`git fetch origin "${defaultBranch}"`, cwd);
+    }
+    catch (_err) {
+        // warn-don't-throw: fetch failure should not abort the workflow
+        return;
+    }
+    try {
+        run(`git merge "origin/${defaultBranch}" --no-edit`, cwd);
+    }
+    catch (_err) {
+        // warn-don't-throw: merge conflicts are non-fatal here
+    }
+}
+function fetchAndResetToRemote(run, defaultBranch, cwd) {
+    try {
+        run(`git fetch origin "${defaultBranch}"`, cwd);
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch origin/${defaultBranch}: ${error}`);
+    }
+    try {
+        run(`git reset --hard "origin/${defaultBranch}"`, cwd);
+    }
+    catch (error) {
+        throw new Error(`Failed to reset to origin/${defaultBranch}: ${error}`);
+    }
+}
+function deleteLocalBranch(run, branch, cwd) {
+    if (isProtected(branch))
+        return false;
+    try {
+        run(`git branch -D "${branch}"`, cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function deleteRemoteBranch(run, branch, cwd) {
+    if (isProtected(branch))
+        return false;
+    try {
+        run(`git push origin --delete "${branch}"`, cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns local branch names from `git branch --list`.
+ * Strips the leading `*`/whitespace marker; returns [] on failure.
+ */
+function localBranches(run, cwd) {
+    try {
+        const output = run('git branch --list', cwd);
+        const branches = [];
+        for (const line of output.split('\n')) {
+            const branch = line.replace(/^\*?\s+/, '').trim();
+            if (branch)
+                branches.push(branch);
+        }
+        return branches;
+    }
+    catch {
+        return [];
+    }
+}
+export const branchOps = {
+    getCurrentBranch,
+    mergeLatestFromDefaultBranch,
+    fetchAndResetToRemote,
+    deleteLocalBranch,
+    deleteRemoteBranch,
+    localBranches,
+};
+//# sourceMappingURL=branchOps.js.map

package/dist/git/branchOps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branchOps.js","sourceRoot":"","sources":["../../src/git/branchOps.ts"],"names":[],"mappings":"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"}

package/dist/git/claimOps.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Package-private op module for the upgrade-claim distributed-lock git verbs.
+ *
+ * These four ops are NOT delegated to the standard GitContext worktree/commit/push
+ * methods — doing so would silently break the winner/loser election:
+ *
+ *   - addDetachedWorktree: standard methods create a named local branch; the claim
+ *     needs DETACHED HEAD at an arbitrary system-temp path with no local branch
+ *     (a leftover named branch causes "already exists" on the next attempt, bypassing
+ *     the loser path).
+ *   - commitAllowEmpty: commitChanges() short-circuits on a clean tree; the claim
+ *     always needs an empty commit carrying the unique nonce.
+ *   - pushHeadToBranch: pushBranch() uses --force-with-lease; the claim push must
+ *     NEVER be forced — the non-fast-forward rejection IS the atomic lock.
+ *   - removeDetachedWorktree: best-effort cleanup that swallows errors (mirrors
+ *     remoteOps.abortMerge).
+ *
+ * All errors except removeDetachedWorktree propagate to the caller.
+ */
+type Runner = (command: string, cwd: string) => string;
+declare function addDetachedWorktree(run: Runner, worktreePath: string, ref: string, cwd: string): void;
+declare function commitAllowEmpty(run: Runner, message: string, cwd: string): void;
+/**
+ * Pushes HEAD to a remote branch ref WITHOUT any force flag.
+ *
+ * CRITICAL: This push MUST NOT carry --force or --force-with-lease.
+ * The non-fast-forward rejection from the remote IS the distributed lock.
+ * A force push would let a second claimant overwrite the winner's branch,
+ * collapsing the exactly-one-winner election into a last-writer-wins race.
+ */
+declare function pushHeadToBranch(run: Runner, branch: string, cwd: string): void;
+declare function removeDetachedWorktree(run: Runner, worktreePath: string, cwd: string): void;
+export declare const claimOps: {
+    addDetachedWorktree: typeof addDetachedWorktree;
+    commitAllowEmpty: typeof commitAllowEmpty;
+    pushHeadToBranch: typeof pushHeadToBranch;
+    removeDetachedWorktree: typeof removeDetachedWorktree;
+};
+export {};
+//# sourceMappingURL=claimOps.d.ts.map

package/dist/git/claimOps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claimOps.d.ts","sourceRoot":"","sources":["../../src/git/claimOps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,KAAK,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAEvD,iBAAS,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9F;AAED,iBAAS,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzE;AAED;;;;;;;GAOG;AACH,iBAAS,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAExE;AAED,iBAAS,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAIpF;AAED,eAAO,MAAM,QAAQ;;;;;CAAsF,CAAC"}

package/dist/git/claimOps.js

@@ -0,0 +1,44 @@
+/**
+ * Package-private op module for the upgrade-claim distributed-lock git verbs.
+ *
+ * These four ops are NOT delegated to the standard GitContext worktree/commit/push
+ * methods — doing so would silently break the winner/loser election:
+ *
+ *   - addDetachedWorktree: standard methods create a named local branch; the claim
+ *     needs DETACHED HEAD at an arbitrary system-temp path with no local branch
+ *     (a leftover named branch causes "already exists" on the next attempt, bypassing
+ *     the loser path).
+ *   - commitAllowEmpty: commitChanges() short-circuits on a clean tree; the claim
+ *     always needs an empty commit carrying the unique nonce.
+ *   - pushHeadToBranch: pushBranch() uses --force-with-lease; the claim push must
+ *     NEVER be forced — the non-fast-forward rejection IS the atomic lock.
+ *   - removeDetachedWorktree: best-effort cleanup that swallows errors (mirrors
+ *     remoteOps.abortMerge).
+ *
+ * All errors except removeDetachedWorktree propagate to the caller.
+ */
+function addDetachedWorktree(run, worktreePath, ref, cwd) {
+    run(`git worktree add --detach "${worktreePath}" "${ref}"`, cwd);
+}
+function commitAllowEmpty(run, message, cwd) {
+    run(`git commit --allow-empty -m "${message.replace(/"/g, '\\"')}"`, cwd);
+}
+/**
+ * Pushes HEAD to a remote branch ref WITHOUT any force flag.
+ *
+ * CRITICAL: This push MUST NOT carry --force or --force-with-lease.
+ * The non-fast-forward rejection from the remote IS the distributed lock.
+ * A force push would let a second claimant overwrite the winner's branch,
+ * collapsing the exactly-one-winner election into a last-writer-wins race.
+ */
+function pushHeadToBranch(run, branch, cwd) {
+    run(`git push origin "HEAD:refs/heads/${branch}"`, cwd);
+}
+function removeDetachedWorktree(run, worktreePath, cwd) {
+    try {
+        run(`git worktree remove --force "${worktreePath}"`, cwd);
+    }
+    catch { /* best-effort cleanup */ }
+}
+export const claimOps = { addDetachedWorktree, commitAllowEmpty, pushHeadToBranch, removeDetachedWorktree };
+//# sourceMappingURL=claimOps.js.map

package/dist/git/claimOps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claimOps.js","sourceRoot":"","sources":["../../src/git/claimOps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,SAAS,mBAAmB,CAAC,GAAW,EAAE,YAAoB,EAAE,GAAW,EAAE,GAAW;IACtF,GAAG,CAAC,8BAA8B,YAAY,MAAM,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAW,EAAE,OAAe,EAAE,GAAW;IACjE,GAAG,CAAC,gCAAgC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,gBAAgB,CAAC,GAAW,EAAE,MAAc,EAAE,GAAW;IAChE,GAAG,CAAC,oCAAoC,MAAM,GAAG,EAAE,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,sBAAsB,CAAC,GAAW,EAAE,YAAoB,EAAE,GAAW;IAC5E,IAAI,CAAC;QACH,GAAG,CAAC,gCAAgC,YAAY,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/git/commitOps.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Package-private commit/push operation orchestration for GitContext.
+ */
+type Runner = (command: string, cwd: string) => string;
+export declare function isLeaseRejection(error: unknown): boolean;
+declare function commitChanges(run: Runner, message: string, cwd: string, opts?: {
+    excludePaths?: readonly string[];
+}): boolean;
+/**
+ * Removes `paths` from the index/working tree and, only if that staged something
+ * for those exact pathspecs, commits scoped to `paths` — unrelated staged/dirty
+ * state elsewhere in the tree is left untouched. `--ignore-unmatch` keeps the
+ * removal idempotent when a path is already absent from the index.
+ */
+declare function removeAndCommitPaths(run: Runner, paths: readonly string[], message: string, cwd: string): boolean;
+/**
+ * Stages and commits `paths` scoped to exactly those pathspecs — the modify
+ * counterpart to `removeAndCommitPaths`. Only commits if `git status --porcelain`
+ * scoped to `paths` reports something staged for them; unrelated dirty state
+ * elsewhere in the tree is never touched (no `git add -A`).
+ */
+declare function addAndCommitPaths(run: Runner, paths: readonly string[], message: string, cwd: string): boolean;
+declare function pushBranch(run: Runner, branch: string, cwd: string): void;
+declare function getHeadTreeHash(run: Runner, cwd: string): string;
+declare function hasUncommittedChanges(run: Runner, cwd: string): boolean;
+export declare const commitOps: {
+    commitChanges: typeof commitChanges;
+    removeAndCommitPaths: typeof removeAndCommitPaths;
+    addAndCommitPaths: typeof addAndCommitPaths;
+    pushBranch: typeof pushBranch;
+    getHeadTreeHash: typeof getHeadTreeHash;
+    hasUncommittedChanges: typeof hasUncommittedChanges;
+};
+export {};
+//# sourceMappingURL=commitOps.d.ts.map

package/dist/git/commitOps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commitOps.d.ts","sourceRoot":"","sources":["../../src/git/commitOps.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,KAAK,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAIvD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMxD;AAkDD,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,OAAO,CAOtH;AAED;;;;;GAKG;AACH,iBAAS,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ1G;AAED;;;;;GAKG;AACH,iBAAS,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQvG;AAED,iBAAS,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAclE;AAED,iBAAS,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,iBAAS,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED,eAAO,MAAM,SAAS;;;;;;;CAOrB,CAAC"}