@plurnk/plurnk-execs-git 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PossumTech Laboratories
+
+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,31 @@
+# @plurnk/plurnk-execs-git
+
+`git` + GitHub-CLI runtime executor for [plurnk-service](https://github.com/plurnk/plurnk-service)'s `exec` scheme. Drives `EXEC[git]` / `EXEC[gh]` by **shelling the system `git`/`gh` binaries** — no third-party git/gh library; the installed CLIs are the source of truth.
+
+A `@plurnk/plurnk-execs-*` sibling built on the [plurnk-execs](https://github.com/plurnk/plurnk-execs) framework.
+
+## Runtime tags
+
+| Tag | Glyph | Binary | Available when |
+|---|---|---|---|
+| `git` | 🔀 | `git` | `git` on PATH |
+| `gh` | 🐙 | `gh` | `gh` on PATH **and** authenticated (`gh auth status`) |
+
+```
+<<EXEC[git]:status --short:EXEC
+<<EXEC[gh]:pr create --title "Fix the bug" --body "Closes #5":EXEC
+```
+
+The command is tokenized into **real argv** (`tokenizeArgv`) and the tag's binary is run directly — **never** through a shell. That's deliberate: shelling `git commit -m "costs $5"` would expand `$5` and corrupt the message; passing argv preserves `$`, backticks, and other specials literally. Shell metacharacters (`|`, `;`, `>`) are passed as literal args, not interpreted.
+
+## Effect & gating
+
+`effect` is **`host` for every command** (proposal-gated). This is required, not a shortcut: `effect(target)` classifies the target only and must never inspect the command, so `git status` and `git push` are indistinguishable to it. **The service owns all gating** — membership, proposal/confirm, the enable ceiling, and outward-confirm for `push` / `gh pr create`. The executor only runs the command and declares the effect.
+
+## Availability
+
+Correct per-tag availability (e.g. `gh` unauthenticated while `git` works) requires the consumer to probe **per-tag**, not per-package (plurnk-service#185).
+
+## Tests
+
+`test:lint`, `test:unit`. Live tests auto-skip where the binary is absent.

package/dist/Git.d.ts

@@ -0,0 +1,7 @@
+import { SubprocessExecutor } from "@plurnk/plurnk-execs";
+import type { RuntimeAvailability, SpawnArgs } from "@plurnk/plurnk-execs";
+export default class Git extends SubprocessExecutor {
+    protected spawnArgs(runtime: string, command: string): SpawnArgs;
+    probe(): Promise<RuntimeAvailability>;
+}
+//# sourceMappingURL=Git.d.ts.map

package/dist/Git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Git.d.ts","sourceRoot":"","sources":["../src/Git.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAc3E,MAAM,CAAC,OAAO,OAAO,GAAI,SAAQ,kBAAkB;cAC5B,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS;IAQ1D,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;CAOvD"}

package/dist/Git.js

@@ -0,0 +1,42 @@
+import { spawn } from "node:child_process";
+import { SubprocessExecutor } from "@plurnk/plurnk-execs";
+import { tokenizeArgv } from "./tokenizeArgv.js";
+// git + GitHub-CLI executor. Claims the `git` and `gh` tags; the tag IS the
+// binary, so it shells the system `git`/`gh` with the command tokenized into
+// real argv (never a shell line — see tokenizeArgv). No third-party git/gh
+// library: the system binaries are the source of truth.
+//
+// `effect` is `host` for every command (inherited) — proposal-gated. That's not
+// a simplification, it's required: `effect(target)` classifies the TARGET only
+// and must never inspect the command, so `git status` and `git push` are
+// indistinguishable to it. Service owns the proposal/confirm/membership gating
+// (plurnk-execs#5). All run/stream/abort behavior is inherited from
+// SubprocessExecutor.
+export default class Git extends SubprocessExecutor {
+    spawnArgs(runtime, command) {
+        // runtime is "git" or "gh" — the tag is the executable.
+        return { cmd: runtime, args: tokenizeArgv(command), useShell: false };
+    }
+    // Per-tag availability: `git` needs the binary; `gh` needs the binary AND an
+    // authenticated session. (Correct only once the consumer probes per-tag, not
+    // per-package — plurnk-service#185.)
+    async probe() {
+        if (this.runtime === "gh") {
+            return runProbe("gh", ["auth", "status"], "gh authenticated", "gh present but not authenticated — run `gh auth login`", "gh not on PATH");
+        }
+        return runProbe("git", ["--version"], undefined, "git --version failed", "git not on PATH");
+    }
+}
+// Spawn a probe command; resolve availability from its exit. Async so the
+// consumer's per-probe timeout can race it (a hung `gh auth status` mustn't
+// wedge boot).
+const runProbe = (bin, args, okDetail, nonzeroDetail, missingDetail) => new Promise((resolve) => {
+    let out = "";
+    const child = spawn(bin, args, { signal: AbortSignal.timeout(5000) });
+    child.stdout?.on("data", (chunk) => { out += chunk.toString("utf8"); });
+    child.on("error", () => resolve({ available: false, detail: missingDetail }));
+    child.on("close", (code) => resolve(code === 0
+        ? { available: true, detail: okDetail ?? (out.trim().split("\n")[0] || undefined) }
+        : { available: false, detail: nonzeroDetail }));
+});
+//# sourceMappingURL=Git.js.map

package/dist/Git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Git.js","sourceRoot":"","sources":["../src/Git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,wDAAwD;AACxD,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,yEAAyE;AACzE,+EAA+E;AAC/E,oEAAoE;AACpE,sBAAsB;AACtB,MAAM,CAAC,OAAO,OAAO,GAAI,SAAQ,kBAAkB;IAC5B,SAAS,CAAC,OAAe,EAAE,OAAe;QACzD,wDAAwD;QACxD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC1E,CAAC;IAED,6EAA6E;IAC7E,6EAA6E;IAC7E,qCAAqC;IAC5B,KAAK,CAAC,KAAK;QAChB,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YACxB,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,EACxD,wDAAwD,EAAE,gBAAgB,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,EAAE,SAAS,EAAE,sBAAsB,EAAE,iBAAiB,CAAC,CAAC;IAChG,CAAC;CACJ;AAED,0EAA0E;AAC1E,4EAA4E;AAC5E,eAAe;AACf,MAAM,QAAQ,GAAG,CACb,GAAW,EACX,IAAc,EACd,QAA4B,EAC5B,aAAqB,EACrB,aAAqB,EACO,EAAE,CAC9B,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;IACpB,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtE,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,GAAG,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;QAC1C,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,EAAE;QACnF,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;AACxD,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { default as Git } from "./Git.ts";
+export { default } from "./Git.ts";
+export { tokenizeArgv } from "./tokenizeArgv.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { default as Git } from "./Git.js";
+export { default } from "./Git.js";
+export { tokenizeArgv } from "./tokenizeArgv.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/tokenizeArgv.d.ts

@@ -0,0 +1,2 @@
+export declare function tokenizeArgv(input: string): string[];
+//# sourceMappingURL=tokenizeArgv.d.ts.map

package/dist/tokenizeArgv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizeArgv.d.ts","sourceRoot":"","sources":["../src/tokenizeArgv.ts"],"names":[],"mappings":"AAMA,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAoCpD"}

package/dist/tokenizeArgv.js

@@ -0,0 +1,68 @@
+// Split a command string into argv the way a POSIX shell would tokenize words —
+// honoring single quotes, double quotes, and backslash escapes — but WITHOUT
+// any variable/command expansion. That distinction is the whole point: shelling
+// `git commit -m "costs $5"` would expand `$5` and corrupt the message; passing
+// real argv preserves `$`, backticks, etc. literally. No shell, no metacharacter
+// interpretation (pipes/redirects are passed through as literal args).
+export function tokenizeArgv(input) {
+    const args = [];
+    let cur = "";
+    let inArg = false;
+    let i = 0;
+    const n = input.length;
+    while (i < n) {
+        const c = input[i];
+        if (c === "'") {
+            inArg = true;
+            i++;
+            while (i < n && input[i] !== "'") {
+                cur += input[i];
+                i++;
+            }
+            if (i >= n)
+                throw new Error("unterminated single quote");
+            i++;
+        }
+        else if (c === '"') {
+            inArg = true;
+            i++;
+            while (i < n && input[i] !== '"') {
+                if (input[i] === "\\" && i + 1 < n && (input[i + 1] === '"' || input[i + 1] === "\\")) {
+                    cur += input[i + 1];
+                    i += 2;
+                }
+                else {
+                    cur += input[i];
+                    i++;
+                }
+            }
+            if (i >= n)
+                throw new Error("unterminated double quote");
+            i++;
+        }
+        else if (c === "\\") {
+            if (i + 1 >= n)
+                throw new Error("trailing backslash");
+            cur += input[i + 1];
+            inArg = true;
+            i += 2;
+        }
+        else if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+            if (inArg) {
+                args.push(cur);
+                cur = "";
+                inArg = false;
+            }
+            i++;
+        }
+        else {
+            cur += c;
+            inArg = true;
+            i++;
+        }
+    }
+    if (inArg)
+        args.push(cur);
+    return args;
+}
+//# sourceMappingURL=tokenizeArgv.js.map

package/dist/tokenizeArgv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizeArgv.js","sourceRoot":"","sources":["../src/tokenizeArgv.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,gFAAgF;AAChF,iFAAiF;AACjF,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,KAAa;IACtC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;IACvB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACZ,KAAK,GAAG,IAAI,CAAC;YAAC,CAAC,EAAE,CAAC;YAClB,OAAO,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAAC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;gBAAC,CAAC,EAAE,CAAC;YAAC,CAAC;YAC3D,IAAI,CAAC,IAAI,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;YACzD,CAAC,EAAE,CAAC;QACR,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACnB,KAAK,GAAG,IAAI,CAAC;YAAC,CAAC,EAAE,CAAC;YAClB,OAAO,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAC/B,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;oBACpF,GAAG,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;oBAAC,CAAC,IAAI,CAAC,CAAC;gBAChC,CAAC;qBAAM,CAAC;oBACJ,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;oBAAC,CAAC,EAAE,CAAC;gBACzB,CAAC;YACL,CAAC;YACD,IAAI,CAAC,IAAI,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;YACzD,CAAC,EAAE,CAAC;QACR,CAAC;aAAM,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;YACtD,GAAG,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAAC,KAAK,GAAG,IAAI,CAAC;YAAC,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAC7D,IAAI,KAAK,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAAC,GAAG,GAAG,EAAE,CAAC;gBAAC,KAAK,GAAG,KAAK,CAAC;YAAC,CAAC;YACvD,CAAC,EAAE,CAAC;QACR,CAAC;aAAM,CAAC;YACJ,GAAG,IAAI,CAAC,CAAC;YAAC,KAAK,GAAG,IAAI,CAAC;YAAC,CAAC,EAAE,CAAC;QAChC,CAAC;IACL,CAAC;IACD,IAAI,KAAK;QAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@plurnk/plurnk-execs-git",
+    "version": "0.1.0",
+    "description": "git + GitHub-CLI runtime executor for plurnk-service's exec scheme — shells the system git/gh binaries (no third-party lib) for EXEC[git] / EXEC[gh].",
+    "keywords": ["plurnk", "exec", "runtime", "executor", "git", "gh", "github"],
+    "homepage": "https://github.com/plurnk/plurnk-execs-git#readme",
+    "bugs": {
+        "url": "https://github.com/plurnk/plurnk-execs-git/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plurnk/plurnk-execs-git.git"
+    },
+    "engines": {
+        "node": ">=25"
+    },
+    "license": "MIT",
+    "author": "@wikitopian",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "plurnk": {
+        "kind": "exec",
+        "runtimes": [
+            { "name": "git", "glyph": "🔀" },
+            { "name": "gh", "glyph": "🐙" }
+        ]
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "README.md"
+    ],
+    "scripts": {
+        "test:lint": "tsc --noEmit",
+        "test:unit": "node --test \"src/**/*.test.ts\"",
+        "test": "npm run test:lint && npm run test:unit",
+        "build:dist": "tsc -p tsconfig.build.json",
+        "build": "npm run build:dist",
+        "prepare": "npm run build"
+    },
+    "dependencies": {
+        "@plurnk/plurnk-execs": "0.4.1"
+    },
+    "devDependencies": {
+        "@types/node": "^25.8.0",
+        "typescript": "^6.0.3"
+    }
+}