@vibe-validate/git 0.17.0-rc4 → 0.17.1-rc.1

package/README.md

@@ -4,7 +4,7 @@ Git utilities for vibe-validate - deterministic tree hash calculation, branch sy
 
 ## Features
 
-- **Deterministic Git Tree Hash**: Content-based hashing using `git write-tree` (no timestamps)
+- **Deterministic Git Tree Hash with Automatic Work Protection**: Content-based hashing using `git write-tree` (no timestamps) - automatically creates recoverable snapshots of all files
 - **Branch Sync Checking**: Safe branch synchronization verification without auto-merging
 - **Post-Merge Cleanup**: Automated cleanup of merged branches after PR completion
 
@@ -114,6 +114,8 @@ git reset                   // Restore index to clean state
 - Enables reliable validation state caching
 - Includes all files (staged, unstaged, untracked)
 - No side effects (index restored after hash)
+- Automatic work protection (all files stored as git objects)
+- Recoverable snapshots of uncommitted work
 
 ### Safe Branch Sync
 
@@ -131,6 +133,56 @@ git reset                   // Restore index to clean state
 - Never deletes main branch
 - Provides clear feedback on all operations
 
+## Automatic Work Protection
+
+A valuable side benefit of the deterministic tree hash calculation is automatic work protection.
+
+### Technical Implementation
+
+When `getGitTreeHash()` runs, it:
+1. Creates temporary index: `.git/vibe-validate-temp-index`
+2. Copies current index to temp index
+3. Runs `git add --all` in temp index (stages everything)
+4. Runs `git write-tree` (creates git objects for all files)
+5. Deletes temp index (your real index remains untouched)
+
+**Critical insight**: Step 4 creates permanent git objects in `.git/objects/` for every file, even though the temp index is deleted. These objects remain accessible via the tree hash.
+
+### What Gets Protected
+
+Every file in your working directory (respecting .gitignore):
+- ✅ Staged changes (in git index)
+- ✅ Unstaged modifications (tracked files)
+- ✅ Untracked files (new files not yet added)
+
+**Not protected** (by design):
+- ❌ Files in .gitignore (secrets, credentials, build artifacts)
+
+### Storage Overhead
+
+**Zero additional overhead**: Git's content-addressable storage automatically deduplicates identical file content. If a file hasn't changed between validations, no additional storage is used.
+
+### Recovery Examples
+
+```bash
+# Scenario: Accidentally deleted file that was never committed
+$ echo "Important work" > new-feature.ts
+$ vv validate  # Tree hash: abc123...
+$ rm new-feature.ts  # Oops!
+
+# Recovery:
+$ git cat-file -p abc123def:new-feature.ts > new-feature.ts
+
+# Scenario: Want to see file content from 2 hours ago
+$ vv history list
+2025-12-02 14:30:15  abc123...  # 2 hours ago
+2025-12-02 16:45:22  def456...  # Current
+
+$ git cat-file -p abc123def:src/feature.ts  # View old version
+```
+
+See [Work Protection Guide](../../docs/work-protection.md) for more examples.
+
 ## License
 
 MIT

package/dist/git-commands.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Git Command Utilities
+ *
+ * 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
+ * @returns true if inside a git repository, false otherwise
+ */
+export declare function isGitRepository(): boolean;
+/**
+ * Get the path to the .git directory
+ * @returns The absolute path to the .git directory
+ * @throws Error if not in a git repository
+ */
+export declare function getGitDir(): string;
+/**
+ * Get the root directory of the git repository
+ * @returns The absolute path to the repository root
+ * @throws Error if not in a git repository
+ */
+export declare function getRepositoryRoot(): string;
+/**
+ * Get the current branch name
+ * @returns The name of the current branch
+ * @throws Error if not on a branch (detached HEAD)
+ */
+export declare function getCurrentBranch(): string;
+/**
+ * Get the commit SHA of HEAD
+ * @returns The full SHA of the current commit
+ * @throws Error if not in a git repository or HEAD is invalid
+ */
+export declare function getHeadCommitSha(): string;
+/**
+ * Get the tree hash of the current HEAD commit
+ * @returns The tree hash of HEAD
+ * @throws Error if not in a git repository or HEAD is invalid
+ */
+export declare function getHeadTreeSha(): string;
+/**
+ * Verify that a git reference exists
+ * @param ref - The reference to verify (branch, tag, commit SHA, etc.)
+ * @returns true if the reference exists, false otherwise
+ */
+export declare function verifyRef(ref: string): boolean;
+/**
+ * Verify that a git reference exists (alternate form for backwards compatibility)
+ * @param ref - The reference to verify
+ * @returns The SHA of the reference if it exists
+ * @throws Error if the reference doesn't exist
+ */
+export declare function verifyRefOrThrow(ref: string): string;
+/**
+ * Check if git notes exist for a specific ref
+ * @param notesRef - The notes reference to check (e.g., 'refs/notes/vibe-validate/validate')
+ * @returns true if the notes ref exists, false otherwise
+ */
+export declare function hasNotesRef(notesRef: string): boolean;
+//# sourceMappingURL=git-commands.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,80 @@
+/**
+ * Git Command Utilities
+ *
+ * High-level git operations built on top of the secure git-executor.
+ * These functions provide convenient access to common git commands.
+ */
+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() {
+    return tryGitCommand(['rev-parse', '--is-inside-work-tree']);
+}
+/**
+ * Get the path to the .git directory
+ * @returns The absolute path to the .git directory
+ * @throws Error if not in a git repository
+ */
+export function getGitDir() {
+    return execGitCommand(['rev-parse', '--git-dir']);
+}
+/**
+ * Get the root directory of the git repository
+ * @returns The absolute path to the repository root
+ * @throws Error if not in a git repository
+ */
+export function getRepositoryRoot() {
+    return execGitCommand(['rev-parse', '--show-toplevel']);
+}
+/**
+ * Get the current branch name
+ * @returns The name of the current branch
+ * @throws Error if not on a branch (detached HEAD)
+ */
+export function getCurrentBranch() {
+    return execGitCommand(['rev-parse', '--abbrev-ref', 'HEAD']);
+}
+/**
+ * Get the commit SHA of HEAD
+ * @returns The full SHA of the current commit
+ * @throws Error if not in a git repository or HEAD is invalid
+ */
+export function getHeadCommitSha() {
+    return execGitCommand(['rev-parse', 'HEAD']);
+}
+/**
+ * Get the tree hash of the current HEAD commit
+ * @returns The tree hash of HEAD
+ * @throws Error if not in a git repository or HEAD is invalid
+ */
+export function getHeadTreeSha() {
+    return execGitCommand(['rev-parse', 'HEAD^{tree}']);
+}
+/**
+ * Verify that a git reference exists
+ * @param ref - The reference to verify (branch, tag, commit SHA, etc.)
+ * @returns true if the reference exists, false otherwise
+ */
+export function verifyRef(ref) {
+    return tryGitCommand(['rev-parse', '--verify', ref]);
+}
+/**
+ * Verify that a git reference exists (alternate form for backwards compatibility)
+ * @param ref - The reference to verify
+ * @returns The SHA of the reference if it exists
+ * @throws Error if the reference doesn't exist
+ */
+export function verifyRefOrThrow(ref) {
+    return execGitCommand(['rev-parse', '--verify', ref]);
+}
+/**
+ * Check if git notes exist for a specific ref
+ * @param notesRef - The notes reference to check (e.g., 'refs/notes/vibe-validate/validate')
+ * @returns true if the notes ref exists, false otherwise
+ */
+export function hasNotesRef(notesRef) {
+    return tryGitCommand(['rev-parse', '--verify', notesRef]);
+}
+//# sourceMappingURL=git-commands.js.map

package/dist/git-commands.js.map

@@ -0,0 +1 @@
+{"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":"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"}

package/dist/index.d.ts

@@ -11,4 +11,9 @@ export { BranchSyncChecker, checkBranchSync, type SyncCheckResult, type SyncChec
 export { PostPRMergeCleanup, cleanupMergedBranches, type CleanupResult, type CleanupOptions } from './post-merge-cleanup.js';
 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';
+export { getPartiallyStagedFiles } from './staging.js';
+export { isCurrentBranchBehindTracking } from './tracking-branch.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"}
+{"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;AAGxB,OAAO,EACL,uBAAuB,EACxB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,6BAA6B,EAC9B,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -16,4 +16,14 @@ export { PostPRMergeCleanup, cleanupMergedBranches } from './post-merge-cleanup.
 export { encodeRunCacheKey } from './cache-key.js';
 // YAML output detection
 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';
+// Git staging detection (prevent partially staged files in pre-commit)
+export { getPartiallyStagedFiles } from './staging.js';
+// Git tracking branch detection (check if current branch is behind remote)
+export { isCurrentBranchBehindTracking } from './tracking-branch.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"}
+{"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;AAExB,uEAAuE;AACvE,OAAO,EACL,uBAAuB,EACxB,MAAM,cAAc,CAAC;AAEtB,2EAA2E;AAC3E,OAAO,EACL,6BAA6B,EAC9B,MAAM,sBAAsB,CAAC"}

package/dist/staging.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Git Staging Detection
+ *
+ * Detects partially staged files to prevent validation mismatches.
+ *
+ * ## The Problem
+ *
+ * If a file has BOTH staged and unstaged changes:
+ * 1. vibe-validate validates the FULL working tree state (staged + unstaged)
+ * 2. git commit only commits the STAGED portion
+ * 3. Result: Validated code != committed code
+ *
+ * ## Solution
+ *
+ * Pre-commit hook must detect and block partially staged files.
+ * Users can:
+ * - Stage all changes: `git add <file>`
+ * - Unstage all changes: `git restore --staged <file>`
+ * - Skip validation: `git commit --no-verify` (not recommended)
+ */
+/**
+ * Get list of files with partially staged changes
+ *
+ * A file is "partially staged" if it has BOTH:
+ * - Changes in the staging area (git diff --cached)
+ * - Changes in the working tree (git diff)
+ *
+ * This indicates the user staged some changes but not others,
+ * which is incompatible with validation.
+ *
+ * @returns Array of file paths with partially staged changes, empty if none
+ *
+ * @example
+ * ```typescript
+ * const files = getPartiallyStagedFiles();
+ * if (files.length > 0) {
+ *   console.error('Partially staged files detected:', files);
+ *   console.error('Stage all changes with: git add ' + files.join(' '));
+ * }
+ * ```
+ */
+export declare function getPartiallyStagedFiles(): string[];
+//# sourceMappingURL=staging.d.ts.map

package/dist/staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../src/staging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAkClD"}

package/dist/staging.js

@@ -0,0 +1,77 @@
+/**
+ * Git Staging Detection
+ *
+ * Detects partially staged files to prevent validation mismatches.
+ *
+ * ## The Problem
+ *
+ * If a file has BOTH staged and unstaged changes:
+ * 1. vibe-validate validates the FULL working tree state (staged + unstaged)
+ * 2. git commit only commits the STAGED portion
+ * 3. Result: Validated code != committed code
+ *
+ * ## Solution
+ *
+ * Pre-commit hook must detect and block partially staged files.
+ * Users can:
+ * - Stage all changes: `git add <file>`
+ * - Unstage all changes: `git restore --staged <file>`
+ * - Skip validation: `git commit --no-verify` (not recommended)
+ */
+import { execSync } from 'node:child_process';
+const GIT_TIMEOUT = 30000;
+const GIT_OPTIONS = {
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT,
+    stdio: ['pipe', 'pipe', 'ignore'],
+};
+/**
+ * Get list of files with partially staged changes
+ *
+ * A file is "partially staged" if it has BOTH:
+ * - Changes in the staging area (git diff --cached)
+ * - Changes in the working tree (git diff)
+ *
+ * This indicates the user staged some changes but not others,
+ * which is incompatible with validation.
+ *
+ * @returns Array of file paths with partially staged changes, empty if none
+ *
+ * @example
+ * ```typescript
+ * const files = getPartiallyStagedFiles();
+ * if (files.length > 0) {
+ *   console.error('Partially staged files detected:', files);
+ *   console.error('Stage all changes with: git add ' + files.join(' '));
+ * }
+ * ```
+ */
+export function getPartiallyStagedFiles() {
+    try {
+        // Get list of files with staged changes
+        const stagedOutput = execSync('git diff --name-only --cached', GIT_OPTIONS);
+        const stagedFiles = stagedOutput
+            .trim()
+            .split('\n')
+            .filter(Boolean);
+        // No staged files = no partially staged files
+        if (stagedFiles.length === 0) {
+            return [];
+        }
+        // Get list of files with unstaged changes
+        const unstagedOutput = execSync('git diff --name-only', GIT_OPTIONS);
+        const unstagedFiles = new Set(unstagedOutput
+            .trim()
+            .split('\n')
+            .filter(Boolean));
+        // Find intersection: files that appear in BOTH staged and unstaged
+        const partiallyStagedFiles = stagedFiles.filter((file) => unstagedFiles.has(file));
+        return partiallyStagedFiles;
+    }
+    catch {
+        // Not a git repository, or git command failed
+        // Return empty array - let pre-commit continue and fail elsewhere if needed
+        return [];
+    }
+}
+//# sourceMappingURL=staging.js.map

package/dist/staging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging.js","sourceRoot":"","sources":["../src/staging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,MAAM,WAAW,GAAG,KAAK,CAAC;AAC1B,MAAM,WAAW,GAAG;IAClB,QAAQ,EAAE,MAAe;IACzB,OAAO,EAAE,WAAW;IACpB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAA+B;CAChE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,uBAAuB;IACrC,IAAI,CAAC;QACH,wCAAwC;QACxC,MAAM,YAAY,GAAG,QAAQ,CAAC,+BAA+B,EAAE,WAAW,CAAC,CAAC;QAC5E,MAAM,WAAW,GAAG,YAAY;aAC7B,IAAI,EAAE;aACN,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,OAAO,CAAC,CAAC;QAEnB,8CAA8C;QAC9C,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,0CAA0C;QAC1C,MAAM,cAAc,GAAG,QAAQ,CAAC,sBAAsB,EAAE,WAAW,CAAC,CAAC;QACrE,MAAM,aAAa,GAAG,IAAI,GAAG,CAC3B,cAAc;aACX,IAAI,EAAE;aACN,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,OAAO,CAAC,CACnB,CAAC;QAEF,mEAAmE;QACnE,MAAM,oBAAoB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CACvD,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CACxB,CAAC;QAEF,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,8CAA8C;QAC9C,4EAA4E;QAC5E,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/tracking-branch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Git Tracking Branch Detection
+ *
+ * Detects if current branch is behind its remote tracking branch.
+ *
+ * ## The Problem
+ *
+ * If you're working on local `fix-issue-X` and someone else pushes to `origin/fix-issue-X`:
+ * 1. Your local branch is now behind the remote tracking branch
+ * 2. If you commit and push, you may create conflicts or lose their changes
+ * 3. You should pull/merge before committing
+ *
+ * ## Solution
+ *
+ * Pre-commit hook should detect and warn when current branch is behind its tracking branch.
+ */
+/**
+ * Check if current branch is behind its remote tracking branch
+ *
+ * @returns Number of commits behind (0 = up to date), or null if no tracking branch
+ *
+ * @example
+ * ```typescript
+ * const behindBy = isCurrentBranchBehindTracking();
+ * if (behindBy === null) {
+ *   console.log('No remote tracking branch');
+ * } else if (behindBy > 0) {
+ *   console.error(`Behind by ${behindBy} commit(s)`);
+ *   console.error('Pull changes with: git pull');
+ * }
+ * ```
+ */
+export declare function isCurrentBranchBehindTracking(): number | null;
+//# sourceMappingURL=tracking-branch.d.ts.map

package/dist/tracking-branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-branch.d.ts","sourceRoot":"","sources":["../src/tracking-branch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,GAAG,IAAI,CAmC7D"}

package/dist/tracking-branch.js

@@ -0,0 +1,66 @@
+/**
+ * Git Tracking Branch Detection
+ *
+ * Detects if current branch is behind its remote tracking branch.
+ *
+ * ## The Problem
+ *
+ * If you're working on local `fix-issue-X` and someone else pushes to `origin/fix-issue-X`:
+ * 1. Your local branch is now behind the remote tracking branch
+ * 2. If you commit and push, you may create conflicts or lose their changes
+ * 3. You should pull/merge before committing
+ *
+ * ## Solution
+ *
+ * Pre-commit hook should detect and warn when current branch is behind its tracking branch.
+ */
+import { execSync } from 'node:child_process';
+const GIT_TIMEOUT = 30000;
+const GIT_OPTIONS = {
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT,
+    stdio: ['pipe', 'pipe', 'ignore'],
+};
+/**
+ * Check if current branch is behind its remote tracking branch
+ *
+ * @returns Number of commits behind (0 = up to date), or null if no tracking branch
+ *
+ * @example
+ * ```typescript
+ * const behindBy = isCurrentBranchBehindTracking();
+ * if (behindBy === null) {
+ *   console.log('No remote tracking branch');
+ * } else if (behindBy > 0) {
+ *   console.error(`Behind by ${behindBy} commit(s)`);
+ *   console.error('Pull changes with: git pull');
+ * }
+ * ```
+ */
+export function isCurrentBranchBehindTracking() {
+    try {
+        // Get the upstream tracking branch for current branch
+        // Example output: "origin/fix-issue-X"
+        // Throws error if no upstream configured
+        const trackingBranch = execSync('git rev-parse --abbrev-ref --symbolic-full-name @{u}', GIT_OPTIONS).trim();
+        if (!trackingBranch) {
+            // No tracking branch
+            return null;
+        }
+        // Count commits behind: HEAD..@{u}
+        // This shows commits in tracking branch that are not in HEAD
+        const behindOutput = execSync('git rev-list --count HEAD..@{u}', GIT_OPTIONS).trim();
+        const behindCount = Number.parseInt(behindOutput, 10);
+        // Return 0 if parsing failed (defensive)
+        return Number.isNaN(behindCount) ? 0 : behindCount;
+    }
+    catch (error) {
+        // Check if error is "no upstream configured" (expected for new branches)
+        if (error instanceof Error && error.message.includes('no upstream')) {
+            return null;
+        }
+        // Other errors (not in git repo, etc.) - return null
+        return null;
+    }
+}
+//# sourceMappingURL=tracking-branch.js.map

package/dist/tracking-branch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-branch.js","sourceRoot":"","sources":["../src/tracking-branch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,MAAM,WAAW,GAAG,KAAK,CAAC;AAC1B,MAAM,WAAW,GAAG;IAClB,QAAQ,EAAE,MAAe;IACzB,OAAO,EAAE,WAAW;IACpB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAA+B;CAChE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,6BAA6B;IAC3C,IAAI,CAAC;QACH,sDAAsD;QACtD,uCAAuC;QACvC,yCAAyC;QACzC,MAAM,cAAc,GAAG,QAAQ,CAC7B,sDAAsD,EACtD,WAAW,CACZ,CAAC,IAAI,EAAE,CAAC;QAET,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,qBAAqB;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mCAAmC;QACnC,6DAA6D;QAC7D,MAAM,YAAY,GAAG,QAAQ,CAC3B,iCAAiC,EACjC,WAAW,CACZ,CAAC,IAAI,EAAE,CAAC;QAET,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAEtD,yCAAyC;QACzC,OAAO,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yEAAyE;QACzE,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;YACpE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,qDAAqD;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/yaml-detection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"yaml-detection.d.ts","sourceRoot":"","sources":["../src/yaml-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA+BH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAWjG"}
+{"version":3,"file":"yaml-detection.d.ts","sourceRoot":"","sources":["../src/yaml-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgCH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAWjG"}

package/dist/yaml-detection.js

@@ -43,6 +43,7 @@
  * - `"---\ntitle: Post\n---\nContent"` → matches, captures `"---\ntitle: Post\n"` (stops at trailing `---`)
  * - `"no yaml"` → no match
  */
+// eslint-disable-next-line security/detect-unsafe-regex -- Safe: Parses controlled YAML frontmatter from command output (not user input), no ReDoS risk
 const YAML_OUTPUT_PATTERN = /(?:^|\r?\n)(---\r?\n(?:(?!---(?:\r?\n|$))[\s\S])*)/;
 /**
  * Extract YAML output content from command output

package/dist/yaml-detection.js.map

@@ -1 +1 @@
-{"version":3,"file":"yaml-detection.js","sourceRoot":"","sources":["../src/yaml-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,mBAAmB,GAAG,oDAAoD,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,IAAI,EAAE,CAAC;IAE5D,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AACzC,CAAC"}
+{"version":3,"file":"yaml-detection.js","sourceRoot":"","sources":["../src/yaml-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wJAAwJ;AACxJ,MAAM,mBAAmB,GAAG,oDAAoD,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,IAAI,EAAE,CAAC;IAE5D,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AACzC,CAAC"}

package/package.json

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