feat: initial commit

Establishes git repo for plumbing. Used to be part of git-cms.

Author: flyingrobots

.editorconfig

@@ -0,0 +1,12 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = false
+insert_final_newline = false

.gitignore

@@ -0,0 +1,168 @@
+# Dependency directories
+node_modules/
+jspm_packages/
+bun.lockb
+node_modules.bun/
+
+# Deno
+.deno/
+deno.lock
+
+# Build outputs
+dist/
+build/
+.next/
+.nuxt/
+.output/
+.cache/
+out/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc documentation
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+public/
+
+# vue-cli dist
+dist/
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Tern JS port file
+.tern-port
+
+# Stores VS Code state
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/code-actions.json
+
+# IntelliJ IDEA
+.idea/
+
+.crush
+.obsidian
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created by macOS
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Other Editors
+*.swp
+*.swo
+*~

README.md

@@ -0,0 +1,55 @@
+# @git-stunts/plumbing
+
+A robust, class-based wrapper for Git binary execution. Designed for "Git Stunts" applications that bypass the porcelain and interact directly with the object database.
+
+## Features
+
+- **Class-based API**: Encapsulates `cwd` and state.
+- **Zero Dependencies**: Uses Node.js standard library.
+- **Plumbing First**: Optimized for `commit-tree`, `hash-object`, and `update-ref`.
+- **Telemetry**: Error messages include `stdout` and `stderr` for easier debugging.
+
+## Installation
+
+```bash
+npm install @git-stunts/plumbing
+```
+
+## Usage
+
+```javascript
+import GitPlumbing from '@git-stunts/plumbing';
+
+const git = new GitPlumbing({ cwd: './my-repo' });
+
+// Create a blob
+const blobOid = git.execute({ 
+  args: ['hash-object', '-w', '--stdin'], 
+  input: 'Hello world' 
+});
+
+// Create a commit pointing to the empty tree
+const commitSha = git.execute({
+  args: ['commit-tree', git.emptyTree, '-m', 'Stunt #1'],
+});
+
+// Update a ref
+git.updateRef({ 
+  ref: 'refs/_blog/stunt', 
+  newSha: commitSha 
+});
+```
+
+## API
+
+### `new GitPlumbing({ cwd })`
+Creates a new instance tied to a specific directory.
+
+### `execute({ args, input })`
+Executes a git command. Throws if the command fails.
+
+### `executeWithStatus({ args })`
+Executes a git command and returns `{ stdout, status }`, allowing you to handle non-zero exit codes (like `git diff`) without throwing.
+
+### `emptyTree`
+Property returning the well-known SHA-1 of the empty tree.

ShellRunner.js

@@ -0,0 +1,32 @@
+import { execFile } from 'node:child_process';
+
+/**
+ * ShellRunner provides a standard CommandRunner implementation using child_process.execFile.
+ */
+export default class ShellRunner {
+  /**
+   * Executes a command.
+   * @param {Object} options
+   * @param {string} options.command
+   * @param {string[]} options.args
+   * @param {string} [options.cwd]
+   * @param {string|Buffer} [options.input]
+   * @returns {Promise<{stdout: string, stderr: string, code: number}>}
+   */
+  static async run({ command, args, cwd, input }) {
+    return new Promise((resolve) => {
+      const child = execFile(command, args, { cwd, encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+        resolve({
+          stdout: stdout || '',
+          stderr: stderr || '',
+          code: error ? error.code : 0
+        });
+      });
+
+      if (input && child.stdin) {
+        child.stdin.write(input);
+        child.stdin.end();
+      }
+    });
+  }
+}

contract.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for the result returned by a CommandRunner.
+ */
+export const RunnerResultSchema = z.object({
+  stdout: z.string(),
+  stderr: z.string(),
+  code: z.number().optional().default(0),
+});
+
+/**
+ * Zod schema for CommandRunner options.
+ */
+export const RunnerOptionsSchema = z.object({
+  command: z.string(),
+  args: z.array(z.string()),
+  cwd: z.string().optional(),
+  input: z.union([z.string(), z.instanceof(Buffer)]).optional(),
+});
+
+/**
+ * @typedef {z.infer<typeof RunnerResultSchema>} RunnerResult
+ * @typedef {z.infer<typeof RunnerOptionsSchema>} RunnerOptions
+ */

eslint.config.js

@@ -0,0 +1,50 @@
+import js from "@eslint/js";
+
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+      globals: {
+        process: "readonly",
+        Buffer: "readonly",
+        console: "readonly",
+        setTimeout: "readonly",
+        clearTimeout: "readonly"
+      }
+    },
+    rules: {
+      // Logic & Complexity
+      "complexity": ["error", 10],
+      "max-depth": ["error", 3],
+      "max-lines-per-function": ["error", 50],
+      "max-params": ["error", 3],
+      "max-nested-callbacks": ["error", 3],
+      
+      // Strictness
+      "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+      "no-console": "error",
+      "eqeqeq": ["error", "always"],
+      "curly": ["error", "all"],
+      "no-eval": "error",
+      "no-implied-eval": "error",
+      "no-new-wrappers": "error",
+      "no-caller": "error",
+      "no-undef-init": "error",
+      "no-var": "error",
+      "prefer-const": "error",
+      "prefer-template": "error",
+      "yoda": ["error", "never"],
+      "no-return-await": "off", // We want explicit returns in some stunts
+      "consistent-return": "error",
+      "no-shadow": "error",
+      "no-use-before-define": ["error", { "functions": false }],
+      
+      // Style (that affects logic)
+      "no-lonely-if": "error",
+      "no-unneeded-ternary": "error",
+      "one-var": ["error", "never"]
+    }
+  }
+];