cadr-cli 0.0.1

package/bin/cadr.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+// Executable wrapper for cadr-cli
+// This file is the entry point when running 'cadr' command
+
+const { displayWelcome, processStagedFiles } = require('../dist/index.js');
+
+// Display welcome message first
+displayWelcome();
+
+// Then process staged files
+processStagedFiles().catch((error) => {
+  console.error('Failed to process staged files:', error.message);
+  process.exit(1);
+});
+

package/dist/git.d.ts

@@ -0,0 +1,12 @@
+export declare class GitError extends Error {
+    readonly code: 'NOT_GIT_REPO' | 'GIT_NOT_FOUND' | 'GIT_ERROR';
+    readonly originalError?: Error | undefined;
+    constructor(message: string, code: 'NOT_GIT_REPO' | 'GIT_NOT_FOUND' | 'GIT_ERROR', originalError?: Error | undefined);
+}
+/**
+ * Retrieves the list of staged files in the current Git repository
+ * @returns Promise<string[]> Array of staged file paths
+ * @throws GitError When Git is not available or repository is invalid
+ */
+export declare function getStagedFiles(): Promise<string[]>;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAKA,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,EAAE,cAAc,GAAG,eAAe,GAAG,WAAW;aACpD,aAAa,CAAC,EAAE,KAAK;gBAFrC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,cAAc,GAAG,eAAe,GAAG,WAAW,EACpD,aAAa,CAAC,EAAE,KAAK,YAAA;CAKxC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAsCxD"}

package/dist/git.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitError = void 0;
+exports.getStagedFiles = getStagedFiles;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+class GitError extends Error {
+    code;
+    originalError;
+    constructor(message, code, originalError) {
+        super(message);
+        this.code = code;
+        this.originalError = originalError;
+        this.name = 'GitError';
+    }
+}
+exports.GitError = GitError;
+/**
+ * Retrieves the list of staged files in the current Git repository
+ * @returns Promise<string[]> Array of staged file paths
+ * @throws GitError When Git is not available or repository is invalid
+ */
+async function getStagedFiles() {
+    try {
+        const { stdout } = await execAsync('git diff --cached --name-only');
+        // Split by newlines and filter out empty strings
+        const stagedFiles = stdout
+            .split('\n')
+            .map(file => file.trim())
+            .filter(file => file.length > 0);
+        return stagedFiles;
+    }
+    catch (error) {
+        // Handle different Git error scenarios
+        const errorWithCode = error;
+        if (errorWithCode.code === 128) {
+            throw new GitError('Not in a Git repository. Please run \'cadr\' from within a Git repository.', 'NOT_GIT_REPO', error instanceof Error ? error : new Error(String(error)));
+        }
+        if (errorWithCode.code === 127) {
+            throw new GitError('Git is not installed. Please install Git and try again.', 'GIT_NOT_FOUND', error instanceof Error ? error : new Error(String(error)));
+        }
+        // Handle other Git errors (permissions, corruption, etc.)
+        throw new GitError('Unable to read Git repository. Please check repository permissions.', 'GIT_ERROR', error instanceof Error ? error : new Error(String(error)));
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":";;;AAqBA,wCAsCC;AA3DD,iDAAqC;AACrC,+BAAiC;AAEjC,MAAM,SAAS,GAAG,IAAA,gBAAS,EAAC,oBAAI,CAAC,CAAC;AAElC,MAAa,QAAS,SAAQ,KAAK;IAGf;IACA;IAHlB,YACE,OAAe,EACC,IAAoD,EACpD,aAAqB;QAErC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAgD;QACpD,kBAAa,GAAb,aAAa,CAAQ;QAGrC,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AATD,4BASC;AAED;;;;GAIG;AACI,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,+BAA+B,CAAC,CAAC;QAEpE,iDAAiD;QACjD,MAAM,WAAW,GAAG,MAAM;aACvB,KAAK,CAAC,IAAI,CAAC;aACX,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;aACxB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAEnC,OAAO,WAAW,CAAC;IACrB,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,uCAAuC;QACvC,MAAM,aAAa,GAAG,KAA0B,CAAC;QAEjD,IAAI,aAAa,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;YAC/B,MAAM,IAAI,QAAQ,CAChB,4EAA4E,EAC5E,cAAc,EACd,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC1D,CAAC;QACJ,CAAC;QAED,IAAI,aAAa,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;YAC/B,MAAM,IAAI,QAAQ,CAChB,yDAAyD,EACzD,eAAe,EACf,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC1D,CAAC;QACJ,CAAC;QAED,0DAA0D;QAC1D,MAAM,IAAI,QAAQ,CAChB,qEAAqE,EACrE,WAAW,EACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC1D,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export declare function getWelcomeMessage(): string;
+export declare function displayWelcome(): void;
+export declare function processStagedFiles(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,wBAAgB,iBAAiB,IAAI,MAAM,CAY1C;AAED,wBAAgB,cAAc,IAAI,IAAI,CAGrC;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAmCxD"}

package/dist/index.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWelcomeMessage = getWelcomeMessage;
+exports.displayWelcome = displayWelcome;
+exports.processStagedFiles = processStagedFiles;
+const git_1 = require("./git");
+const logger_1 = require("./logger");
+// Version constants
+const CORE_VERSION = '0.0.1';
+const CLI_VERSION = '0.0.1';
+// Parse command line arguments
+const args = process.argv.slice(2);
+const isVerbose = args.includes('--verbose') || args.includes('-v');
+function getWelcomeMessage() {
+    return `🎉 Hello, cADR!
+
+cADR (Continuous Architectural Decision Records) helps you automatically
+capture and document architectural decisions as you code.
+
+Version: ${CLI_VERSION}
+Core: ${CORE_VERSION}
+Learn more: https://github.com/YotpoLtd/cADR
+
+Get started by running 'cadr --verbose' to see detailed logs
+`;
+}
+function displayWelcome() {
+    // Use process.stdout.write instead of console.log (Constitution: no console.log)
+    process.stdout.write(getWelcomeMessage());
+}
+async function processStagedFiles() {
+    try {
+        const stagedFiles = await (0, git_1.getStagedFiles)();
+        // Display staged files to user
+        if (stagedFiles.length > 0) {
+            process.stdout.write(`\n📁 Found ${stagedFiles.length} staged file${stagedFiles.length === 1 ? '' : 's'}:\n`);
+            stagedFiles.forEach((file) => {
+                process.stdout.write(`  • ${file}\n`);
+            });
+        }
+        else {
+            process.stdout.write(`\n📁 No staged files found.\n`);
+        }
+        // Only log for debugging when verbose mode is enabled
+        if (isVerbose) {
+            logger_1.loggerInstance.info('Retrieved staged files', {
+                staged_files: stagedFiles,
+                count: stagedFiles.length
+            });
+        }
+    }
+    catch (error) {
+        if (error instanceof git_1.GitError) {
+            // Display helpful error message to stdout
+            process.stdout.write(`\n❌ ${error.message}\n`);
+            process.exit(1);
+        }
+        else {
+            // Log unexpected errors (always show errors)
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger_1.loggerInstance.error('Unexpected error occurred', {
+                error: errorMessage
+            });
+            process.exit(1);
+        }
+    }
+}
+// Main execution block - run when module is executed directly
+if (require.main === module) {
+    // Display welcome message first
+    displayWelcome();
+    // Then process staged files
+    processStagedFiles().catch((error) => {
+        logger_1.loggerInstance.error('Failed to process staged files', {
+            error: error instanceof Error ? error.message : String(error)
+        });
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAWA,8CAYC;AAED,wCAGC;AAED,gDAmCC;AAjED,+BAAiD;AACjD,qCAA0C;AAE1C,oBAAoB;AACpB,MAAM,YAAY,GAAG,OAAO,CAAC;AAC7B,MAAM,WAAW,GAAG,OAAO,CAAC;AAE5B,+BAA+B;AAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAEpE,SAAgB,iBAAiB;IAC/B,OAAO;;;;;WAKE,WAAW;QACd,YAAY;;;;CAInB,CAAC;AACF,CAAC;AAED,SAAgB,cAAc;IAC5B,iFAAiF;IACjF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,EAAE,CAAC,CAAC;AAC5C,CAAC;AAEM,KAAK,UAAU,kBAAkB;IACtC,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,IAAA,oBAAc,GAAE,CAAC;QAE3C,+BAA+B;QAC/B,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,WAAW,CAAC,MAAM,eAAe,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;YAC9G,WAAW,CAAC,OAAO,CAAC,CAAC,IAAY,EAAE,EAAE;gBACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;YACxC,CAAC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACxD,CAAC;QAED,sDAAsD;QACtD,IAAI,SAAS,EAAE,CAAC;YACd,uBAAc,CAAC,IAAI,CAAC,wBAAwB,EAAE;gBAC5C,YAAY,EAAE,WAAW;gBACzB,KAAK,EAAE,WAAW,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,KAAK,YAAY,cAAQ,EAAE,CAAC;YAC9B,0CAA0C;YAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;YAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,6CAA6C;YAC7C,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5E,uBAAc,CAAC,KAAK,CAAC,2BAA2B,EAAE;gBAChD,KAAK,EAAE,YAAY;aACpB,CAAC,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;AACH,CAAC;AAED,8DAA8D;AAC9D,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,gCAAgC;IAChC,cAAc,EAAE,CAAC;IAEjB,4BAA4B;IAC5B,kBAAkB,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACnC,uBAAc,CAAC,KAAK,CAAC,gCAAgC,EAAE;YACrD,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+export declare class Logger {
+    info(message: string, context?: object): void;
+    warn(message: string, context?: object): void;
+    error(message: string, context?: object): void;
+}
+export declare const loggerInstance: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAWA,qBAAa,MAAM;IACjB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ7C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ7C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;CAO/C;AAGD,eAAO,MAAM,cAAc,QAAe,CAAC"}

package/dist/logger.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loggerInstance = exports.Logger = void 0;
+const pino_1 = __importDefault(require("pino"));
+// Configure Pino to output JSON to stderr
+const logger = (0, pino_1.default)({
+    level: 'info',
+    transport: {
+        target: 'pino/file',
+        options: { destination: 2 } // stderr
+    }
+});
+class Logger {
+    info(message, context) {
+        if (context) {
+            logger.info(context, message);
+        }
+        else {
+            logger.info(message);
+        }
+    }
+    warn(message, context) {
+        if (context) {
+            logger.warn(context, message);
+        }
+        else {
+            logger.warn(message);
+        }
+    }
+    error(message, context) {
+        if (context) {
+            logger.error(context, message);
+        }
+        else {
+            logger.error(message);
+        }
+    }
+}
+exports.Logger = Logger;
+// Export singleton logger instance
+exports.loggerInstance = new Logger();
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AAExB,0CAA0C;AAC1C,MAAM,MAAM,GAAG,IAAA,cAAI,EAAC;IAClB,KAAK,EAAE,MAAM;IACb,SAAS,EAAE;QACT,MAAM,EAAE,WAAW;QACnB,OAAO,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,SAAS;KACtC;CACF,CAAC,CAAC;AAEH,MAAa,MAAM;IACjB,IAAI,CAAC,OAAe,EAAE,OAAgB;QACpC,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,OAAgB;QACpC,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,OAAgB;QACrC,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;CACF;AAxBD,wBAwBC;AAED,mCAAmC;AACtB,QAAA,cAAc,GAAG,IAAI,MAAM,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "cadr-cli",
+  "version": "0.0.1",
+  "description": "Continuous Architectural Decision Records - Automatically capture ADRs as you code",
+  "main": "dist/index.js",
+  "bin": {
+    "cadr": "./bin/cadr.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "keywords": [
+    "adr",
+    "architecture",
+    "cli",
+    "decision-records",
+    "documentation"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YotpoLtd/cADR.git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "pino": "^8.17.2"
+  }
+}

package/src/git.ts

@@ -0,0 +1,60 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+export class GitError extends Error {
+  constructor(
+    message: string,
+    public readonly code: 'NOT_GIT_REPO' | 'GIT_NOT_FOUND' | 'GIT_ERROR',
+    public readonly originalError?: Error
+  ) {
+    super(message);
+    this.name = 'GitError';
+  }
+}
+
+/**
+ * Retrieves the list of staged files in the current Git repository
+ * @returns Promise<string[]> Array of staged file paths
+ * @throws GitError When Git is not available or repository is invalid
+ */
+export async function getStagedFiles(): Promise<string[]> {
+  try {
+    const { stdout } = await execAsync('git diff --cached --name-only');
+    
+    // Split by newlines and filter out empty strings
+    const stagedFiles = stdout
+      .split('\n')
+      .map(file => file.trim())
+      .filter(file => file.length > 0);
+    
+    return stagedFiles;
+  } catch (error: unknown) {
+    // Handle different Git error scenarios
+    const errorWithCode = error as { code?: number };
+    
+    if (errorWithCode.code === 128) {
+      throw new GitError(
+        'Not in a Git repository. Please run \'cadr\' from within a Git repository.',
+        'NOT_GIT_REPO',
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+    
+    if (errorWithCode.code === 127) {
+      throw new GitError(
+        'Git is not installed. Please install Git and try again.',
+        'GIT_NOT_FOUND',
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+    
+    // Handle other Git errors (permissions, corruption, etc.)
+    throw new GitError(
+      'Unable to read Git repository. Please check repository permissions.',
+      'GIT_ERROR',
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+import { getStagedFiles, GitError } from './git';
+import { loggerInstance } from './logger';
+
+// Version constants
+const CORE_VERSION = '0.0.1';
+const CLI_VERSION = '0.0.1';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const isVerbose = args.includes('--verbose') || args.includes('-v');
+
+export function getWelcomeMessage(): string {
+  return `🎉 Hello, cADR!
+
+cADR (Continuous Architectural Decision Records) helps you automatically
+capture and document architectural decisions as you code.
+
+Version: ${CLI_VERSION}
+Core: ${CORE_VERSION}
+Learn more: https://github.com/YotpoLtd/cADR
+
+Get started by running 'cadr --verbose' to see detailed logs
+`;
+}
+
+export function displayWelcome(): void {
+  // Use process.stdout.write instead of console.log (Constitution: no console.log)
+  process.stdout.write(getWelcomeMessage());
+}
+
+export async function processStagedFiles(): Promise<void> {
+  try {
+    const stagedFiles = await getStagedFiles();
+    
+    // Display staged files to user
+    if (stagedFiles.length > 0) {
+      process.stdout.write(`\n📁 Found ${stagedFiles.length} staged file${stagedFiles.length === 1 ? '' : 's'}:\n`);
+      stagedFiles.forEach((file: string) => {
+        process.stdout.write(`  • ${file}\n`);
+      });
+    } else {
+      process.stdout.write(`\n📁 No staged files found.\n`);
+    }
+    
+    // Only log for debugging when verbose mode is enabled
+    if (isVerbose) {
+      loggerInstance.info('Retrieved staged files', {
+        staged_files: stagedFiles,
+        count: stagedFiles.length
+      });
+    }
+  } catch (error: unknown) {
+    if (error instanceof GitError) {
+      // Display helpful error message to stdout
+      process.stdout.write(`\n❌ ${error.message}\n`);
+      process.exit(1);
+    } else {
+      // Log unexpected errors (always show errors)
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      loggerInstance.error('Unexpected error occurred', { 
+        error: errorMessage
+      });
+      process.exit(1);
+    }
+  }
+}
+
+// Main execution block - run when module is executed directly
+if (require.main === module) {
+  // Display welcome message first
+  displayWelcome();
+  
+  // Then process staged files
+  processStagedFiles().catch((error) => {
+    loggerInstance.error('Failed to process staged files', { 
+      error: error instanceof Error ? error.message : String(error)
+    });
+    process.exit(1);
+  });
+}

package/src/logger.ts

@@ -0,0 +1,39 @@
+import pino from 'pino';
+
+// Configure Pino to output JSON to stderr
+const logger = pino({
+  level: 'info',
+  transport: {
+    target: 'pino/file',
+    options: { destination: 2 } // stderr
+  }
+});
+
+export class Logger {
+  info(message: string, context?: object): void {
+    if (context) {
+      logger.info(context, message);
+    } else {
+      logger.info(message);
+    }
+  }
+
+  warn(message: string, context?: object): void {
+    if (context) {
+      logger.warn(context, message);
+    } else {
+      logger.warn(message);
+    }
+  }
+
+  error(message: string, context?: object): void {
+    if (context) {
+      logger.error(context, message);
+    } else {
+      logger.error(message);
+    }
+  }
+}
+
+// Export singleton logger instance
+export const loggerInstance = new Logger();

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "references": []
+}