@vibe-validate/git 0.17.0-rc.6 → 0.17.0-rc.7

package/dist/git-commands.d.ts

@@ -1,8 +1,8 @@
 /**
  * Git Command Utilities
  *
- * Standardized git command execution with consistent options and error handling.
- * Consolidates scattered git rev-parse usage across packages.
+ * High-level git operations built on top of the secure git-executor.
+ * These functions provide convenient access to common git commands.
  */
 /**
  * Check if the current directory is inside a git repository

package/dist/git-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-commands.d.ts","sourceRoot":"","sources":["../src/git-commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6BH;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAOzC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO9C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWrD"}
+{"version":3,"file":"git-commands.d.ts","sourceRoot":"","sources":["../src/git-commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/git-commands.js

@@ -1,46 +1,16 @@
 /**
  * Git Command Utilities
  *
- * Standardized git command execution with consistent options and error handling.
- * Consolidates scattered git rev-parse usage across packages.
+ * High-level git operations built on top of the secure git-executor.
+ * These functions provide convenient access to common git commands.
  */
-import { execSync } from 'node:child_process';
-/**
- * Standard options for git command execution
- */
-const GIT_OPTIONS = {
-    encoding: 'utf8',
-    timeout: 30000, // 30 seconds
-    stdio: 'pipe',
-};
-/**
- * Execute a git command with standard options
- * @param command - The git command to execute
- * @param options - Optional overrides for execution options
- * @returns The command output, trimmed of whitespace
- * @throws Error if the command fails
- */
-function execGitCommand(command, options) {
-    try {
-        const result = execSync(command, { ...GIT_OPTIONS, ...options });
-        return result.trim();
-    }
-    catch (error) {
-        throw new Error(`Git command failed: ${command}`, { cause: error });
-    }
-}
+import { execGitCommand, tryGitCommand } from './git-executor.js';
 /**
  * Check if the current directory is inside a git repository
  * @returns true if inside a git repository, false otherwise
  */
 export function isGitRepository() {
-    try {
-        execGitCommand('git rev-parse --is-inside-work-tree');
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return tryGitCommand(['rev-parse', '--is-inside-work-tree']);
 }
 /**
  * Get the path to the .git directory
@@ -48,7 +18,7 @@ export function isGitRepository() {
  * @throws Error if not in a git repository
  */
 export function getGitDir() {
-    return execGitCommand('git rev-parse --git-dir');
+    return execGitCommand(['rev-parse', '--git-dir']);
 }
 /**
  * Get the root directory of the git repository
@@ -56,7 +26,7 @@ export function getGitDir() {
  * @throws Error if not in a git repository
  */
 export function getRepositoryRoot() {
-    return execGitCommand('git rev-parse --show-toplevel');
+    return execGitCommand(['rev-parse', '--show-toplevel']);
 }
 /**
  * Get the current branch name
@@ -64,7 +34,7 @@ export function getRepositoryRoot() {
  * @throws Error if not on a branch (detached HEAD)
  */
 export function getCurrentBranch() {
-    return execGitCommand('git rev-parse --abbrev-ref HEAD');
+    return execGitCommand(['rev-parse', '--abbrev-ref', 'HEAD']);
 }
 /**
  * Get the commit SHA of HEAD
@@ -72,7 +42,7 @@ export function getCurrentBranch() {
  * @throws Error if not in a git repository or HEAD is invalid
  */
 export function getHeadCommitSha() {
-    return execGitCommand('git rev-parse HEAD');
+    return execGitCommand(['rev-parse', 'HEAD']);
 }
 /**
  * Get the tree hash of the current HEAD commit
@@ -80,7 +50,7 @@ export function getHeadCommitSha() {
  * @throws Error if not in a git repository or HEAD is invalid
  */
 export function getHeadTreeSha() {
-    return execGitCommand('git rev-parse HEAD^{tree}');
+    return execGitCommand(['rev-parse', 'HEAD^{tree}']);
 }
 /**
  * Verify that a git reference exists
@@ -88,13 +58,7 @@ export function getHeadTreeSha() {
  * @returns true if the reference exists, false otherwise
  */
 export function verifyRef(ref) {
-    try {
-        execGitCommand(`git rev-parse --verify ${ref}`);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return tryGitCommand(['rev-parse', '--verify', ref]);
 }
 /**
  * Verify that a git reference exists (alternate form for backwards compatibility)
@@ -103,7 +67,7 @@ export function verifyRef(ref) {
  * @throws Error if the reference doesn't exist
  */
 export function verifyRefOrThrow(ref) {
-    return execGitCommand(`git rev-parse --verify ${ref}`);
+    return execGitCommand(['rev-parse', '--verify', ref]);
 }
 /**
  * Check if git notes exist for a specific ref
@@ -111,16 +75,6 @@ export function verifyRefOrThrow(ref) {
  * @returns true if the notes ref exists, false otherwise
  */
 export function hasNotesRef(notesRef) {
-    try {
-        // Use || true to prevent error when notes don't exist
-        const result = execSync(`git rev-parse --verify ${notesRef} 2>/dev/null || true`, {
-            encoding: 'utf8',
-            timeout: GIT_OPTIONS.timeout,
-        }).trim();
-        return result.length > 0;
-    }
-    catch {
-        return false;
-    }
+    return tryGitCommand(['rev-parse', '--verify', notesRef]);
 }
 //# sourceMappingURL=git-commands.js.map

package/dist/git-commands.js.map

@@ -1 +1 @@
-{"version":3,"file":"git-commands.js","sourceRoot":"","sources":["../src/git-commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,QAAQ,EAAE,MAAe;IACzB,OAAO,EAAE,KAAK,EAAE,aAAa;IAC7B,KAAK,EAAE,MAAe;CACd,CAAC;AAEX;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,OAAe,EAAE,OAAqC;IAC5E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,GAAG,WAAW,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QACjE,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,uBAAuB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC;QACH,cAAc,CAAC,qCAAqC,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,cAAc,CAAC,yBAAyB,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,cAAc,CAAC,+BAA+B,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,CAAC,iCAAiC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,CAAC,oBAAoB,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,cAAc,CAAC,2BAA2B,CAAC,CAAC;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAI,CAAC;QACH,cAAc,CAAC,0BAA0B,GAAG,EAAE,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,cAAc,CAAC,0BAA0B,GAAG,EAAE,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,IAAI,CAAC;QACH,sDAAsD;QACtD,MAAM,MAAM,GAAG,QAAQ,CAAC,0BAA0B,QAAQ,sBAAsB,EAAE;YAChF,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,WAAW,CAAC,OAAO;SAC7B,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"git-commands.js","sourceRoot":"","sources":["../src/git-commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElE;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,aAAa,CAAC,CAAC,WAAW,EAAE,uBAAuB,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,cAAc,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,cAAc,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,CAAC,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,cAAc,CAAC,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,aAAa,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,cAAc,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,OAAO,aAAa,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/git-executor.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Secure Git Command Execution
+ *
+ * This module provides a centralized, secure way to execute git commands.
+ * ALL git command execution in vibe-validate MUST go through this module.
+ *
+ * Security principles:
+ * 1. Use spawnSync with array arguments (never string interpolation)
+ * 2. Validate all user-controlled inputs
+ * 3. No shell piping or heredocs
+ * 4. Explicit argument construction
+ *
+ * @packageDocumentation
+ */
+export interface GitExecutionOptions {
+    /**
+     * Maximum time to wait for git command (ms)
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Encoding for stdout/stderr
+     * @default 'utf8'
+     */
+    encoding?: BufferEncoding;
+    /**
+     * Standard input to pass to command
+     */
+    stdin?: string;
+    /**
+     * Whether to ignore errors (return empty string instead of throwing)
+     * @default false
+     */
+    ignoreErrors?: boolean;
+    /**
+     * Whether to suppress stderr
+     * @default false
+     */
+    suppressStderr?: boolean;
+}
+/**
+ * Result of a git command execution
+ */
+export interface GitExecutionResult {
+    /** Standard output from the command */
+    stdout: string;
+    /** Standard error from the command */
+    stderr: string;
+    /** Exit code (0 for success) */
+    exitCode: number;
+    /** Whether the command succeeded */
+    success: boolean;
+}
+/**
+ * Error thrown when a git command fails
+ */
+export interface GitCommandError extends Error {
+    /** Exit code from the git command */
+    exitCode: number;
+    /** Standard error output */
+    stderr: string;
+    /** Standard output */
+    stdout: string;
+}
+/**
+ * Execute a git command securely using spawnSync with array arguments
+ *
+ * This is the ONLY function that should execute git commands. All other
+ * git operations must go through this function or higher-level abstractions.
+ *
+ * @param args - Git command arguments (e.g., ['rev-parse', '--git-dir'])
+ * @param options - Execution options
+ * @returns Execution result
+ * @throws Error if command fails and ignoreErrors is false
+ *
+ * @example
+ * ```typescript
+ * // Get git directory
+ * const result = executeGitCommand(['rev-parse', '--git-dir']);
+ * console.log(result.stdout); // ".git"
+ *
+ * // Add note with stdin
+ * executeGitCommand(
+ *   ['notes', '--ref=vibe-validate/validate', 'add', '-f', '-F', '-', treeHash],
+ *   { stdin: noteContent }
+ * );
+ * ```
+ */
+export declare function executeGitCommand(args: string[], options?: GitExecutionOptions): GitExecutionResult;
+/**
+ * Execute a git command and return stdout, throwing on error
+ *
+ * Convenience wrapper for the common case of executing a git command
+ * and only caring about the stdout result.
+ *
+ * @param args - Git command arguments
+ * @param options - Execution options
+ * @returns Command stdout, trimmed
+ * @throws Error if command fails
+ */
+export declare function execGitCommand(args: string[], options?: GitExecutionOptions): string;
+/**
+ * Execute a git command and return success status (no throw)
+ *
+ * Useful for checking if a git operation would succeed without
+ * handling exceptions.
+ *
+ * @param args - Git command arguments
+ * @param options - Execution options
+ * @returns true if command succeeded, false otherwise
+ */
+export declare function tryGitCommand(args: string[], options?: GitExecutionOptions): boolean;
+/**
+ * Validate that a string is safe to use as a git ref
+ *
+ * Git refs must:
+ * - Not contain special shell characters
+ * - Not start with a dash (looks like an option)
+ * - Not contain path traversal sequences
+ * - Match git's ref format rules
+ *
+ * @param ref - The ref to validate
+ * @throws Error if ref is invalid
+ */
+export declare function validateGitRef(ref: string): void;
+/**
+ * Validate that a string is safe to use as a git notes ref
+ *
+ * Notes refs have additional restrictions beyond normal refs.
+ *
+ * @param notesRef - The notes ref to validate
+ * @throws Error if notes ref is invalid
+ */
+export declare function validateNotesRef(notesRef: string): void;
+/**
+ * Validate that a string is safe to use as a tree hash
+ *
+ * Tree hashes must be valid git object IDs (40-char hex or abbreviated).
+ *
+ * @param treeHash - The tree hash to validate
+ * @throws Error if tree hash is invalid
+ */
+export declare function validateTreeHash(treeHash: string): void;
+//# sourceMappingURL=git-executor.d.ts.map

package/dist/git-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-executor.d.ts","sourceRoot":"","sources":["../src/git-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAE1B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,KAAK;IAC5C,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAqDpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAGxF;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAGxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA6BhD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAWvD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAcvD"}

package/dist/git-executor.js

@@ -0,0 +1,192 @@
+/**
+ * Secure Git Command Execution
+ *
+ * This module provides a centralized, secure way to execute git commands.
+ * ALL git command execution in vibe-validate MUST go through this module.
+ *
+ * Security principles:
+ * 1. Use spawnSync with array arguments (never string interpolation)
+ * 2. Validate all user-controlled inputs
+ * 3. No shell piping or heredocs
+ * 4. Explicit argument construction
+ *
+ * @packageDocumentation
+ */
+import { spawnSync } from 'node:child_process';
+/**
+ * Standard options for git command execution
+ */
+const GIT_TIMEOUT = 30000; // 30 seconds
+/**
+ * Execute a git command securely using spawnSync with array arguments
+ *
+ * This is the ONLY function that should execute git commands. All other
+ * git operations must go through this function or higher-level abstractions.
+ *
+ * @param args - Git command arguments (e.g., ['rev-parse', '--git-dir'])
+ * @param options - Execution options
+ * @returns Execution result
+ * @throws Error if command fails and ignoreErrors is false
+ *
+ * @example
+ * ```typescript
+ * // Get git directory
+ * const result = executeGitCommand(['rev-parse', '--git-dir']);
+ * console.log(result.stdout); // ".git"
+ *
+ * // Add note with stdin
+ * executeGitCommand(
+ *   ['notes', '--ref=vibe-validate/validate', 'add', '-f', '-F', '-', treeHash],
+ *   { stdin: noteContent }
+ * );
+ * ```
+ */
+export function executeGitCommand(args, options = {}) {
+    const { timeout = GIT_TIMEOUT, encoding = 'utf8', stdin, ignoreErrors = false, suppressStderr = false, } = options;
+    // Validate arguments
+    if (!Array.isArray(args) || args.length === 0) {
+        throw new Error('Git command arguments must be a non-empty array');
+    }
+    // Build spawn options
+    const spawnOptions = {
+        encoding,
+        timeout,
+        maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+    };
+    // Configure stdio
+    if (stdin !== undefined) {
+        spawnOptions.input = stdin;
+        spawnOptions.stdio = ['pipe', 'pipe', suppressStderr ? 'ignore' : 'pipe'];
+    }
+    else {
+        spawnOptions.stdio = ['ignore', 'pipe', suppressStderr ? 'ignore' : 'pipe'];
+    }
+    // Execute command
+    const result = spawnSync('git', args, spawnOptions);
+    const stdout = (result.stdout?.toString() || '').trim();
+    const stderr = (result.stderr?.toString() || '').trim();
+    const exitCode = result.status ?? 1;
+    const success = exitCode === 0;
+    // Handle errors
+    if (success || ignoreErrors) {
+        return {
+            stdout,
+            stderr,
+            exitCode,
+            success,
+        };
+    }
+    const errorMessage = stderr || stdout || 'Git command failed';
+    const error = new Error(`Git command failed: git ${args.join(' ')}\n${errorMessage}`);
+    error.exitCode = exitCode;
+    error.stderr = stderr;
+    error.stdout = stdout;
+    throw error;
+}
+/**
+ * Execute a git command and return stdout, throwing on error
+ *
+ * Convenience wrapper for the common case of executing a git command
+ * and only caring about the stdout result.
+ *
+ * @param args - Git command arguments
+ * @param options - Execution options
+ * @returns Command stdout, trimmed
+ * @throws Error if command fails
+ */
+export function execGitCommand(args, options = {}) {
+    const result = executeGitCommand(args, options);
+    return result.stdout;
+}
+/**
+ * Execute a git command and return success status (no throw)
+ *
+ * Useful for checking if a git operation would succeed without
+ * handling exceptions.
+ *
+ * @param args - Git command arguments
+ * @param options - Execution options
+ * @returns true if command succeeded, false otherwise
+ */
+export function tryGitCommand(args, options = {}) {
+    const result = executeGitCommand(args, { ...options, ignoreErrors: true });
+    return result.success;
+}
+/**
+ * Validate that a string is safe to use as a git ref
+ *
+ * Git refs must:
+ * - Not contain special shell characters
+ * - Not start with a dash (looks like an option)
+ * - Not contain path traversal sequences
+ * - Match git's ref format rules
+ *
+ * @param ref - The ref to validate
+ * @throws Error if ref is invalid
+ */
+export function validateGitRef(ref) {
+    if (typeof ref !== 'string' || ref.length === 0) {
+        throw new Error('Git ref must be a non-empty string');
+    }
+    // Check for shell special characters
+    if (/[;&|`$(){}[\]<>!\\"]/.test(ref)) {
+        throw new Error(`Invalid git ref: contains shell special characters: ${ref}`);
+    }
+    // Check for leading dash (looks like an option)
+    if (ref.startsWith('-')) {
+        throw new Error(`Invalid git ref: starts with dash: ${ref}`);
+    }
+    // Check for path traversal
+    if (ref.includes('..') || ref.includes('//')) {
+        throw new Error(`Invalid git ref: contains path traversal: ${ref}`);
+    }
+    // Check for null bytes
+    if (ref.includes('\0')) {
+        throw new Error('Invalid git ref: contains null byte');
+    }
+    // Check for newlines (could break command)
+    if (ref.includes('\n') || ref.includes('\r')) {
+        throw new Error('Invalid git ref: contains newline');
+    }
+}
+/**
+ * Validate that a string is safe to use as a git notes ref
+ *
+ * Notes refs have additional restrictions beyond normal refs.
+ *
+ * @param notesRef - The notes ref to validate
+ * @throws Error if notes ref is invalid
+ */
+export function validateNotesRef(notesRef) {
+    validateGitRef(notesRef);
+    // Notes refs should follow refs/notes/* pattern or short form
+    // Short form: 'vibe-validate/validate' → 'refs/notes/vibe-validate/validate'
+    if (!notesRef.startsWith('refs/notes/') && notesRef.includes('/')) {
+        // Short form is valid, but must not contain spaces
+        if (/\s/.test(notesRef)) {
+            throw new Error(`Invalid notes ref: contains whitespace: ${notesRef}`);
+        }
+    }
+}
+/**
+ * Validate that a string is safe to use as a tree hash
+ *
+ * Tree hashes must be valid git object IDs (40-char hex or abbreviated).
+ *
+ * @param treeHash - The tree hash to validate
+ * @throws Error if tree hash is invalid
+ */
+export function validateTreeHash(treeHash) {
+    if (typeof treeHash !== 'string' || treeHash.length === 0) {
+        throw new Error('Tree hash must be a non-empty string');
+    }
+    // Must be hex characters only
+    if (!/^[0-9a-f]+$/.test(treeHash)) {
+        throw new Error(`Invalid tree hash: must be hexadecimal: ${treeHash}`);
+    }
+    // Must be reasonable length (4-40 chars for abbreviated or full hash)
+    if (treeHash.length < 4 || treeHash.length > 40) {
+        throw new Error(`Invalid tree hash: invalid length: ${treeHash}`);
+    }
+}
+//# sourceMappingURL=git-executor.js.map

package/dist/git-executor.js.map

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

package/dist/git-notes.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Git Notes Operations
+ *
+ * High-level abstraction for git notes operations. All notes-related
+ * commands in vibe-validate must use these functions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Add or update a git note
+ *
+ * @param notesRef - The notes reference (e.g., 'vibe-validate/validate')
+ * @param object - The git object to attach the note to (tree hash, commit SHA, etc.)
+ * @param content - The note content
+ * @param force - Whether to overwrite existing note
+ * @returns true if note was added successfully
+ *
+ * @example
+ * ```typescript
+ * addNote('vibe-validate/validate', treeHash, noteContent, true);
+ * ```
+ */
+export declare function addNote(notesRef: string, object: string, content: string, force?: boolean): boolean;
+/**
+ * Read a git note
+ *
+ * @param notesRef - The notes reference
+ * @param object - The git object to read the note from
+ * @returns The note content, or null if no note exists
+ *
+ * @example
+ * ```typescript
+ * const note = readNote('vibe-validate/validate', treeHash);
+ * if (note) {
+ *   console.log('Note content:', note);
+ * }
+ * ```
+ */
+export declare function readNote(notesRef: string, object: string): string | null;
+/**
+ * Remove a git note
+ *
+ * @param notesRef - The notes reference
+ * @param object - The git object to remove the note from
+ * @returns true if note was removed, false if it didn't exist
+ *
+ * @example
+ * ```typescript
+ * const removed = removeNote('vibe-validate/validate', treeHash);
+ * console.log(removed ? 'Removed' : 'Did not exist');
+ * ```
+ */
+export declare function removeNote(notesRef: string, object: string): boolean;
+/**
+ * List all notes in a notes reference
+ *
+ * @param notesRef - The notes reference
+ * @returns Array of [object, content] pairs, or empty array if no notes
+ *
+ * @example
+ * ```typescript
+ * const notes = listNotes('vibe-validate/validate');
+ * for (const [treeHash, content] of notes) {
+ *   console.log(`${treeHash}: ${content}`);
+ * }
+ * ```
+ */
+export declare function listNotes(notesRef: string): Array<[string, string]>;
+/**
+ * Check if a note exists
+ *
+ * @param notesRef - The notes reference
+ * @param object - The git object to check
+ * @returns true if note exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (hasNote('vibe-validate/validate', treeHash)) {
+ *   console.log('Note exists');
+ * }
+ * ```
+ */
+export declare function hasNote(notesRef: string, object: string): boolean;
+/**
+ * List all refs under a notes namespace
+ *
+ * This is useful for finding all notes under a particular path,
+ * such as all run cache entries under refs/notes/vibe-validate/run/
+ *
+ * @param notesPath - The notes path (e.g., 'refs/notes/vibe-validate/run')
+ * @returns Array of full ref names
+ *
+ * @example
+ * ```typescript
+ * const refs = listNotesRefs('refs/notes/vibe-validate/run');
+ * for (const ref of refs) {
+ *   console.log('Found note ref:', ref);
+ * }
+ * ```
+ */
+export declare function listNotesRefs(notesPath: string): string[];
+/**
+ * Remove all notes refs under a namespace
+ *
+ * This is used for bulk cleanup operations, such as pruning all
+ * run cache entries under a tree hash.
+ *
+ * SECURITY: This function validates each ref before deletion to prevent
+ * accidental deletion of non-notes refs.
+ *
+ * @param notesPath - The notes path (e.g., 'refs/notes/vibe-validate/run/abc123')
+ * @returns Number of refs deleted
+ *
+ * @example
+ * ```typescript
+ * const deleted = removeNotesRefs('refs/notes/vibe-validate/run/abc123');
+ * console.log(`Deleted ${deleted} refs`);
+ * ```
+ */
+export declare function removeNotesRefs(notesPath: string): number;
+/**
+ * Check if a notes ref exists
+ *
+ * @param notesRef - The notes reference
+ * @returns true if the notes ref exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (hasNotesRef('vibe-validate/validate')) {
+ *   console.log('Notes ref exists');
+ * }
+ * ```
+ */
+export declare function hasNotesRef(notesRef: string): boolean;
+/**
+ * Get the commit SHA that a notes ref points to
+ *
+ * @param notesRef - The notes reference
+ * @returns The commit SHA, or null if ref doesn't exist
+ */
+export declare function getNotesRefSha(notesRef: string): string | null;
+//# sourceMappingURL=git-notes.d.ts.map

package/dist/git-notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-notes.d.ts","sourceRoot":"","sources":["../src/git-notes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,OAAe,GACrB,OAAO,CAiBT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAOpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA4BnE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAOjE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAczD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAgCzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWrD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAa9D"}

package/dist/git-notes.js

@@ -0,0 +1,251 @@
+/**
+ * Git Notes Operations
+ *
+ * High-level abstraction for git notes operations. All notes-related
+ * commands in vibe-validate must use these functions.
+ *
+ * @packageDocumentation
+ */
+import { executeGitCommand, tryGitCommand, validateNotesRef, validateTreeHash, } from './git-executor.js';
+/**
+ * Add or update a git note
+ *
+ * @param notesRef - The notes reference (e.g., 'vibe-validate/validate')
+ * @param object - The git object to attach the note to (tree hash, commit SHA, etc.)
+ * @param content - The note content
+ * @param force - Whether to overwrite existing note
+ * @returns true if note was added successfully
+ *
+ * @example
+ * ```typescript
+ * addNote('vibe-validate/validate', treeHash, noteContent, true);
+ * ```
+ */
+export function addNote(notesRef, object, content, force = false) {
+    validateNotesRef(notesRef);
+    validateTreeHash(object);
+    const args = ['notes', `--ref=${notesRef}`, 'add'];
+    if (force) {
+        args.push('-f');
+    }
+    args.push('-F', '-', object);
+    const result = executeGitCommand(args, {
+        stdin: content,
+        ignoreErrors: true,
+        suppressStderr: true,
+    });
+    return result.success;
+}
+/**
+ * Read a git note
+ *
+ * @param notesRef - The notes reference
+ * @param object - The git object to read the note from
+ * @returns The note content, or null if no note exists
+ *
+ * @example
+ * ```typescript
+ * const note = readNote('vibe-validate/validate', treeHash);
+ * if (note) {
+ *   console.log('Note content:', note);
+ * }
+ * ```
+ */
+export function readNote(notesRef, object) {
+    validateNotesRef(notesRef);
+    validateTreeHash(object);
+    const result = executeGitCommand(['notes', `--ref=${notesRef}`, 'show', object], {
+        ignoreErrors: true,
+        suppressStderr: true,
+    });
+    return result.success ? result.stdout : null;
+}
+/**
+ * Remove a git note
+ *
+ * @param notesRef - The notes reference
+ * @param object - The git object to remove the note from
+ * @returns true if note was removed, false if it didn't exist
+ *
+ * @example
+ * ```typescript
+ * const removed = removeNote('vibe-validate/validate', treeHash);
+ * console.log(removed ? 'Removed' : 'Did not exist');
+ * ```
+ */
+export function removeNote(notesRef, object) {
+    validateNotesRef(notesRef);
+    validateTreeHash(object);
+    return tryGitCommand(['notes', `--ref=${notesRef}`, 'remove', object], {
+        suppressStderr: true,
+    });
+}
+/**
+ * List all notes in a notes reference
+ *
+ * @param notesRef - The notes reference
+ * @returns Array of [object, content] pairs, or empty array if no notes
+ *
+ * @example
+ * ```typescript
+ * const notes = listNotes('vibe-validate/validate');
+ * for (const [treeHash, content] of notes) {
+ *   console.log(`${treeHash}: ${content}`);
+ * }
+ * ```
+ */
+export function listNotes(notesRef) {
+    validateNotesRef(notesRef);
+    // Get list of objects that have notes
+    const objectsResult = executeGitCommand(['notes', `--ref=${notesRef}`, 'list'], {
+        ignoreErrors: true,
+        suppressStderr: true,
+    });
+    if (!objectsResult.success || !objectsResult.stdout) {
+        return [];
+    }
+    const notes = [];
+    // Parse "note_sha object_sha" pairs
+    for (const line of objectsResult.stdout.split('\n')) {
+        const [, objectSha] = line.split(/\s+/);
+        if (!objectSha)
+            continue;
+        // Read the note content
+        const content = readNote(notesRef, objectSha);
+        if (content !== null) {
+            notes.push([objectSha, content]);
+        }
+    }
+    return notes;
+}
+/**
+ * Check if a note exists
+ *
+ * @param notesRef - The notes reference
+ * @param object - The git object to check
+ * @returns true if note exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (hasNote('vibe-validate/validate', treeHash)) {
+ *   console.log('Note exists');
+ * }
+ * ```
+ */
+export function hasNote(notesRef, object) {
+    validateNotesRef(notesRef);
+    validateTreeHash(object);
+    return tryGitCommand(['notes', `--ref=${notesRef}`, 'show', object], {
+        suppressStderr: true,
+    });
+}
+/**
+ * List all refs under a notes namespace
+ *
+ * This is useful for finding all notes under a particular path,
+ * such as all run cache entries under refs/notes/vibe-validate/run/
+ *
+ * @param notesPath - The notes path (e.g., 'refs/notes/vibe-validate/run')
+ * @returns Array of full ref names
+ *
+ * @example
+ * ```typescript
+ * const refs = listNotesRefs('refs/notes/vibe-validate/run');
+ * for (const ref of refs) {
+ *   console.log('Found note ref:', ref);
+ * }
+ * ```
+ */
+export function listNotesRefs(notesPath) {
+    // Normalize path
+    const fullPath = notesPath.startsWith('refs/') ? notesPath : `refs/notes/${notesPath}`;
+    const result = executeGitCommand(['for-each-ref', '--format=%(refname)', fullPath], { ignoreErrors: true, suppressStderr: true });
+    if (!result.success || !result.stdout) {
+        return [];
+    }
+    return result.stdout.split('\n').filter(Boolean);
+}
+/**
+ * Remove all notes refs under a namespace
+ *
+ * This is used for bulk cleanup operations, such as pruning all
+ * run cache entries under a tree hash.
+ *
+ * SECURITY: This function validates each ref before deletion to prevent
+ * accidental deletion of non-notes refs.
+ *
+ * @param notesPath - The notes path (e.g., 'refs/notes/vibe-validate/run/abc123')
+ * @returns Number of refs deleted
+ *
+ * @example
+ * ```typescript
+ * const deleted = removeNotesRefs('refs/notes/vibe-validate/run/abc123');
+ * console.log(`Deleted ${deleted} refs`);
+ * ```
+ */
+export function removeNotesRefs(notesPath) {
+    // Normalize path
+    const fullPath = notesPath.startsWith('refs/') ? notesPath : `refs/notes/${notesPath}`;
+    // Security: Only allow deletion under refs/notes/vibe-validate/
+    if (!fullPath.startsWith('refs/notes/vibe-validate/')) {
+        throw new Error(`Refusing to delete refs outside vibe-validate namespace: ${fullPath}`);
+    }
+    // Get list of refs
+    const refs = listNotesRefs(fullPath);
+    let deleted = 0;
+    for (const ref of refs) {
+        // Double-check each ref is under the expected namespace
+        if (!ref.startsWith('refs/notes/vibe-validate/')) {
+            console.warn(`Skipping ref outside vibe-validate namespace: ${ref}`);
+            continue;
+        }
+        const success = tryGitCommand(['update-ref', '-d', ref], {
+            suppressStderr: true,
+        });
+        if (success) {
+            deleted++;
+        }
+    }
+    return deleted;
+}
+/**
+ * Check if a notes ref exists
+ *
+ * @param notesRef - The notes reference
+ * @returns true if the notes ref exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (hasNotesRef('vibe-validate/validate')) {
+ *   console.log('Notes ref exists');
+ * }
+ * ```
+ */
+export function hasNotesRef(notesRef) {
+    validateNotesRef(notesRef);
+    // Convert short form to full form if needed
+    const fullRef = notesRef.startsWith('refs/')
+        ? notesRef
+        : `refs/notes/${notesRef}`;
+    return tryGitCommand(['rev-parse', '--verify', fullRef], {
+        suppressStderr: true,
+    });
+}
+/**
+ * Get the commit SHA that a notes ref points to
+ *
+ * @param notesRef - The notes reference
+ * @returns The commit SHA, or null if ref doesn't exist
+ */
+export function getNotesRefSha(notesRef) {
+    validateNotesRef(notesRef);
+    const fullRef = notesRef.startsWith('refs/')
+        ? notesRef
+        : `refs/notes/${notesRef}`;
+    const result = executeGitCommand(['rev-parse', '--verify', fullRef], {
+        ignoreErrors: true,
+        suppressStderr: true,
+    });
+    return result.success ? result.stdout : null;
+}
+//# sourceMappingURL=git-notes.js.map

package/dist/git-notes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-notes.js","sourceRoot":"","sources":["../src/git-notes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO,CACrB,QAAgB,EAChB,MAAc,EACd,OAAe,EACf,QAAiB,KAAK;IAEtB,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC3B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEzB,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;IACnD,IAAI,KAAK,EAAE,CAAC;QACV,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAE7B,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,EAAE;QACrC,KAAK,EAAE,OAAO;QACd,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,MAAc;IACvD,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC3B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEzB,MAAM,MAAM,GAAG,iBAAiB,CAAC,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;QAC/E,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,MAAc;IACzD,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC3B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEzB,OAAO,aAAa,CAAC,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE;QACrE,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE3B,sCAAsC;IACtC,MAAM,aAAa,GAAG,iBAAiB,CAAC,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,CAAC,EAAE;QAC9E,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;IAEH,IAAI,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC;QACpD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAA4B,EAAE,CAAC;IAE1C,oCAAoC;IACpC,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,SAAS;YAAE,SAAS;QAEzB,wBAAwB;QACxB,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC9C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO,CAAC,QAAgB,EAAE,MAAc;IACtD,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC3B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEzB,OAAO,aAAa,CAAC,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;QACnE,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,iBAAiB;IACjB,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,SAAS,EAAE,CAAC;IAEvF,MAAM,MAAM,GAAG,iBAAiB,CAC9B,CAAC,cAAc,EAAE,qBAAqB,EAAE,QAAQ,CAAC,EACjD,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAC7C,CAAC;IAEF,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,iBAAiB;IACjB,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,SAAS,EAAE,CAAC;IAEvF,gEAAgE;IAChE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,2BAA2B,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CACb,4DAA4D,QAAQ,EAAE,CACvE,CAAC;IACJ,CAAC;IAED,mBAAmB;IACnB,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAErC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,wDAAwD;QACxD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,2BAA2B,CAAC,EAAE,CAAC;YACjD,OAAO,CAAC,IAAI,CAAC,iDAAiD,GAAG,EAAE,CAAC,CAAC;YACrE,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,aAAa,CAAC,CAAC,YAAY,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE;YACvD,cAAc,EAAE,IAAI;SACrB,CAAC,CAAC;QAEH,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE3B,4CAA4C;IAC5C,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC;QAC1C,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,cAAc,QAAQ,EAAE,CAAC;IAE7B,OAAO,aAAa,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE;QACvD,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE3B,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC;QAC1C,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,cAAc,QAAQ,EAAE,CAAC;IAE7B,MAAM,MAAM,GAAG,iBAAiB,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE;QACnE,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC"}

package/dist/index.d.ts

@@ -12,4 +12,6 @@ export { PostPRMergeCleanup, cleanupMergedBranches, type CleanupResult, type Cle
 export { encodeRunCacheKey } from './cache-key.js';
 export { extractYamlContent, extractYamlWithPreamble } from './yaml-detection.js';
 export { isGitRepository, getGitDir, getRepositoryRoot, getCurrentBranch, getHeadCommitSha, getHeadTreeSha, verifyRef, verifyRefOrThrow, hasNotesRef } from './git-commands.js';
+export { executeGitCommand, execGitCommand, tryGitCommand, validateGitRef, validateNotesRef, validateTreeHash, type GitExecutionOptions, type GitExecutionResult } from './git-executor.js';
+export { addNote, readNote, removeNote, listNotes, hasNote, listNotesRefs, removeNotesRefs, getNotesRefSha } from './git-notes.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,OAAO,EACP,QAAQ,EACR,UAAU,EACV,SAAS,EACT,OAAO,EACP,aAAa,EACb,eAAe,EACf,cAAc,EACf,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -18,4 +18,8 @@ export { encodeRunCacheKey } from './cache-key.js';
 export { extractYamlContent, extractYamlWithPreamble } from './yaml-detection.js';
 // Git command utilities (standardized rev-parse operations)
 export { isGitRepository, getGitDir, getRepositoryRoot, getCurrentBranch, getHeadCommitSha, getHeadTreeSha, verifyRef, verifyRefOrThrow, hasNotesRef } from './git-commands.js';
+// Secure git command execution (low-level - use high-level APIs when possible)
+export { executeGitCommand, execGitCommand, tryGitCommand, validateGitRef, validateNotesRef, validateTreeHash } from './git-executor.js';
+// Git notes operations (high-level abstraction)
+export { addNote, readNote, removeNote, listNotes, hasNote, listNotesRefs, removeNotesRefs, getNotesRefSha } from './git-notes.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uDAAuD;AACvD,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAExB,6CAA6C;AAC7C,OAAO,EACL,iBAAiB,EACjB,eAAe,EAGhB,MAAM,kBAAkB,CAAC;AAE1B,8CAA8C;AAC9C,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EAGtB,MAAM,yBAAyB,CAAC;AAEjC,qCAAqC;AACrC,OAAO,EACL,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,4DAA4D;AAC5D,OAAO,EACL,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uDAAuD;AACvD,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAExB,6CAA6C;AAC7C,OAAO,EACL,iBAAiB,EACjB,eAAe,EAGhB,MAAM,kBAAkB,CAAC;AAE1B,8CAA8C;AAC9C,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EAGtB,MAAM,yBAAyB,CAAC;AAEjC,qCAAqC;AACrC,OAAO,EACL,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,4DAA4D;AAC5D,OAAO,EACL,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,+EAA+E;AAC/E,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAGjB,MAAM,mBAAmB,CAAC;AAE3B,gDAAgD;AAChD,OAAO,EACL,OAAO,EACP,QAAQ,EACR,UAAU,EACV,SAAS,EACT,OAAO,EACP,aAAa,EACb,eAAe,EACf,cAAc,EACf,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-validate/git",
-  "version": "0.17.0-rc.6",
+  "version": "0.17.0-rc.7",
   "description": "Git utilities for vibe-validate - tree hash calculation, branch sync, and post-merge cleanup",
   "type": "module",
   "main": "./dist/index.js",