@theunwalked/cardigantime 0.0.21 → 0.0.23

package/README.md

@@ -6,7 +6,7 @@ A robust TypeScript library for configuration management in command-line applica
 
 Cardigantime is a configuration management library designed to solve the common problem of handling configuration in CLI applications. It provides a unified way to:
 
-- **Read configuration from YAML files** with intelligent file discovery
+- **Read configuration from multiple formats** (YAML, JSON, JavaScript, TypeScript) with intelligent file discovery
 - **Validate configuration** using Zod schemas for type safety
 - **Integrate with CLI frameworks** like Commander.js seamlessly
 - **Merge configuration sources** (files, CLI args, defaults) with proper precedence
@@ -24,6 +24,35 @@ Without Cardigantime, you need to manually handle:
 
 Cardigantime provides a complete, battle-tested solution for all of this complexity.
 
+### One Schema, Multiple Formats
+
+Define your configuration schema once with Zod, and Cardigantime automatically supports:
+- **YAML** (`.yaml`, `.yml`) - Human-readable, great for hand-edited configs
+- **JSON** (`.json`) - Strict syntax, ideal for programmatic generation
+- **JavaScript** (`.js`, `.mjs`, `.cjs`) - Dynamic configs with environment logic
+- **TypeScript** (`.ts`, `.mts`, `.cts`) - Type-safe configs with IDE support
+
+No additional code or schema definitions needed per format. Your users choose their preferred format, and Cardigantime handles parsing, validation, and merging automatically.
+
+## Who Uses Cardigantime?
+
+Cardigantime serves two distinct audiences:
+
+### Tool Developers
+Developers building CLI applications who want robust configuration management without the boilerplate. You integrate Cardigantime once, define your Zod schema, and get:
+- Multi-format config file support out of the box
+- Automatic CLI option generation
+- Deep merging with proper precedence
+- Hierarchical config discovery (like `.eslintrc` or `.gitignore`)
+- Type safety throughout your codebase
+
+### End Users
+Users of tools built with Cardigantime benefit from a consistent, powerful configuration experience without needing to know Cardigantime exists. They get:
+- Freedom to use their preferred config format (YAML, JSON, JS, or TS)
+- Consistent CLI options across tools
+- Clear, actionable error messages
+- Built-in config generation (`--init-config`) and analysis (`--check-config`)
+
 ## Installation
 
 ```bash
@@ -102,8 +131,84 @@ async function main() {
 main().catch(console.error);
 ```
 
-### Example Configuration File (`config/myapp.yaml`)
+### Version Information with Git Details
+
+Cardigantime exports its own version information including git commit details. You can also set up the same pattern in your own project.
+
+#### Using Cardigantime's Version
+
+```typescript
+import { VERSION, PROGRAM_NAME } from '@theunwalked/cardigantime';
+
+console.log(`Using ${PROGRAM_NAME}: ${VERSION}`);
+// Output: Using cardigantime: 0.0.22-dev.0 (working/a1b2c3d  2026-01-27 11:11:46 -0800) darwin arm64 v24.8.0
+```
+
+#### Setting Up Version Info in Your Own Project
+
+To add the same detailed version format to your own CLI application, add this to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import replace from '@rollup/plugin-replace';
+import { execSync } from 'node:child_process';
+
+// Extract git information at build time
+let gitInfo = {
+    branch: '',
+    commit: '',
+    tags: '',
+    commitDate: '',
+};
+
+try {
+    gitInfo = {
+        branch: execSync('git rev-parse --abbrev-ref HEAD').toString().trim(),
+        commit: execSync('git rev-parse --short HEAD').toString().trim(),
+        tags: '',
+        commitDate: execSync('git log -1 --format=%cd --date=iso').toString().trim(),
+    };
+    
+    try {
+        gitInfo.tags = execSync('git tag --points-at HEAD | paste -sd "," -').toString().trim();
+    } catch {
+        gitInfo.tags = '';
+    }
+} catch {
+    console.log('Directory does not have a Git repository, skipping git info');
+}
+
+export default defineConfig({
+    plugins: [
+        replace({
+            '__VERSION__': process.env.npm_package_version,
+            '__GIT_BRANCH__': gitInfo.branch,
+            '__GIT_COMMIT__': gitInfo.commit,
+            '__GIT_TAGS__': gitInfo.tags === '' ? '' : `T:${gitInfo.tags}`,
+            '__GIT_COMMIT_DATE__': gitInfo.commitDate,
+            '__SYSTEM_INFO__': `${process.platform} ${process.arch} ${process.version}`,
+            preventAssignment: true,
+        }),
+        // ... your other plugins
+    ],
+    // ... rest of your config
+});
+```
+
+Then in your constants file:
+
+```typescript
+export const VERSION = '__VERSION__ (__GIT_BRANCH__/__GIT_COMMIT__ __GIT_TAGS__ __GIT_COMMIT_DATE__) __SYSTEM_INFO__';
+export const PROGRAM_NAME = 'myapp';
+```
+
+The placeholders will be replaced at build time with actual values. This is particularly useful for CLI applications where you need visibility into exactly which build is running.
+
+### Configuration File Examples
 
+Cardigantime supports multiple configuration formats. Choose the one that best fits your workflow:
+
+#### YAML (`config/myapp.yaml`)
 ```yaml
 apiKey: "your-secret-api-key"
 timeout: 10000
@@ -111,6 +216,47 @@ retries: 5
 debug: true
 ```
 
+#### JSON (`config/myapp.json`)
+```json
+{
+  "apiKey": "your-secret-api-key",
+  "timeout": 10000,
+  "retries": 5,
+  "debug": true
+}
+```
+
+#### JavaScript (`config/myapp.js`)
+```javascript
+module.exports = {
+  apiKey: process.env.API_KEY || "your-secret-api-key",
+  timeout: 10000,
+  retries: 5,
+  debug: process.env.NODE_ENV === 'development'
+};
+```
+
+#### TypeScript (`config/myapp.ts`)
+```typescript
+export default {
+  apiKey: process.env.API_KEY || "your-secret-api-key",
+  timeout: 10000,
+  retries: 5,
+  debug: process.env.NODE_ENV === 'development'
+} as const;
+```
+
+**Format Priority:** When multiple config files exist, Cardigantime uses this priority order:
+1. TypeScript (`.ts`, `.mts`, `.cts`) - Highest priority
+2. JavaScript (`.js`, `.mjs`, `.cjs`)
+3. JSON (`.json`)
+4. YAML (`.yaml`, `.yml`) - Lowest priority
+
+You can override automatic detection with `--config-format`:
+```bash
+./myapp --config-format yaml  # Force YAML even if JSON exists
+```
+
 ### Example Usage
 
 ```bash
@@ -138,12 +284,57 @@ Merges configuration from multiple sources in order of precedence:
 2. **Configuration file(s)** (medium priority)  
 3. **Default values** (lowest priority)
 
-### Flexible YAML Support
-Supports both `.yaml` and `.yml` file extensions with automatic fallback - if `config.yaml` isn't found, Cardigantime automatically tries `config.yml` (and vice versa).
+### Multi-Format Configuration
+Supports YAML (`.yaml`, `.yml`), JSON (`.json`), JavaScript (`.js`, `.mjs`, `.cjs`), and TypeScript (`.ts`, `.mts`, `.cts`) configuration files. When multiple formats exist, Cardigantime uses automatic format detection with configurable priority.
+
+### Configuration Discovery
+
+Cardigantime automatically searches for configuration files using multiple naming conventions, similar to how tools like Vite, ESLint, and TypeScript work:
+
+| Priority | Pattern | Example |
+|----------|---------|---------|
+| 1 | `{app}.config.{ext}` | `myapp.config.yaml` |
+| 2 | `{app}.conf.{ext}` | `myapp.conf.yaml` |
+| 3 | `.{app}/config.{ext}` | `.myapp/config.yaml` |
+| 4 | `.{app}rc.{ext}` | `.myapprc.yaml` |
+| 5 | `.{app}rc` | `.myapprc` |
+
+Modern visible config files (like `myapp.config.yaml`) are checked first for better discoverability.
 
 ### Hierarchical Configuration Discovery
 Supports hierarchical configuration discovery, similar to how `.gitignore`, `.eslintrc`, or `package.json` work - searching up the directory tree for configuration directories.
 
+**Hierarchical Modes:**
+- `enabled` (default) - Merge configs from parent directories
+- `disabled` - Use only the config in the starting directory
+- `root-only` - Find first config, no merging
+- `explicit` - Only merge explicitly referenced configs
+
+```yaml
+# Disable hierarchical for isolated projects
+hierarchical:
+  mode: disabled
+```
+
+### MCP Integration
+First-class support for Model Context Protocol (MCP), enabling AI assistants to configure tools directly through MCP invocations. Includes:
+- **MCP Configuration Priority** - MCP config takes exclusive precedence when provided
+- **File-Based Fallback** - Automatic discovery from target file or working directory
+- **CheckConfig Tool** - Built-in diagnostic tool for all MCP tools
+- **Integration Helpers** - Simple APIs for adding MCP support to your tools
+
+```typescript
+import { createMCPIntegration } from '@theunwalked/cardigantime/mcp';
+
+const integration = createMCPIntegration({
+  appName: 'myapp',
+  configSchema: myConfigSchema,
+});
+
+// CheckConfig tool is automatically available
+// Config resolution handles MCP and file-based sources
+```
+
 ### Type Safety & Validation
 Full TypeScript support with Zod schema validation for robust, type-safe configuration management.
 
@@ -157,6 +348,8 @@ Comprehensive error handling with detailed, actionable error messages to help us
 **Quick Links:**
 - [Getting Started Guide](https://utilarium.github.io/cardigantime/#getting-started) - Detailed setup and basic concepts
 - [Core Concepts](https://utilarium.github.io/cardigantime/#core-concepts) - Configuration sources, hierarchical discovery
+- [MCP Integration](https://utilarium.github.io/cardigantime/#mcp-integration) - Model Context Protocol support for AI assistants
+- [CheckConfig Tool](https://utilarium.github.io/cardigantime/#check-config-tool) - Built-in diagnostic tool
 - [API Reference](https://utilarium.github.io/cardigantime/#api-reference) - Complete API documentation
 - [Configuration Options](https://utilarium.github.io/cardigantime/#configuration-options) - All available options
 - [Debugging & Analysis](https://utilarium.github.io/cardigantime/#debugging-analysis) - Tools for analyzing config

package/dist/cardigantime.cjs

@@ -3,10 +3,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const yaml = require('js-yaml');
-const path = require('path');
-const fs = require('fs');
+const path = require('node:path');
+const fs = require('node:fs');
 const glob = require('glob');
-const crypto = require('crypto');
+const crypto = require('node:crypto');
 const zod = require('zod');
 
 function _interopNamespaceDefault(e) {
@@ -29,6 +29,7 @@ function _interopNamespaceDefault(e) {
 const yaml__namespace = /*#__PURE__*/_interopNamespaceDefault(yaml);
 const path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 const fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
+const crypto__namespace = /*#__PURE__*/_interopNamespaceDefault(crypto);
 
 function _define_property$2(obj, key, value) {
     if (key in obj) {
@@ -180,9 +181,25 @@ function _define_property$2(obj, key, value) {
     retCommand = retCommand.option('--init-config', 'Generate initial configuration file and exit');
     // Add the check config option
     retCommand = retCommand.option('--check-config', 'Display resolved configuration with source tracking and exit');
+    // Add the config format option
+    retCommand = retCommand.option('--config-format <format>', 'Force a specific configuration file format (yaml, json, javascript, typescript)', (value)=>{
+        const validFormats = [
+            'yaml',
+            'json',
+            'javascript',
+            'typescript'
+        ];
+        const normalized = value.toLowerCase();
+        if (!validFormats.includes(normalized)) {
+            throw new ArgumentError('config-format', `Invalid --config-format: must be one of ${validFormats.join(', ')}`);
+        }
+        return normalized;
+    });
     return retCommand;
 };
 
+/** Version string populated at build time with git and system information */ const VERSION = '0.0.23 (HEAD/b3ed796 T:v0.0.23 2026-01-27 14:30:06 -0800) linux x64 v24.13.0';
+/** The program name used in CLI help and error messages */ const PROGRAM_NAME = 'cardigantime';
 /** Default file encoding for reading configuration files */ const DEFAULT_ENCODING = 'utf8';
 /** Default configuration file name to look for in the config directory */ const DEFAULT_CONFIG_FILE = 'config.yaml';
 /**
@@ -273,7 +290,6 @@ function _define_property$1(obj, key, value) {
     }
 }
 
-// eslint-disable-next-line no-restricted-imports
 const create$1 = (params)=>{
     // eslint-disable-next-line no-console
     const log = params.log || console.log;
@@ -385,7 +401,7 @@ const create$1 = (params)=>{
                 nodir: true
             });
             for (const file of files){
-                await callback(path.join(directory, file));
+                await callback(path__namespace.join(directory, file));
             }
         } catch (err) {
             throw FileSystemError.operationFailed(`glob pattern ${options.pattern}`, directory, err);
@@ -396,7 +412,7 @@ const create$1 = (params)=>{
     };
     const hashFile = async (path, length)=>{
         const file = await readFile(path, 'utf8');
-        return crypto.createHash('sha256').update(file).digest('hex').slice(0, length);
+        return crypto__namespace.createHash('sha256').update(file).digest('hex').slice(0, length);
     };
     const listFiles = async (directory)=>{
         return await fs__namespace.promises.readdir(directory);
@@ -482,10 +498,10 @@ function setNestedValue$1(obj, path, value) {
 /**
  * Resolves a single path string relative to the config directory if it's a relative path.
  */ function resolveSinglePath$1(pathStr, configDir) {
-    if (!pathStr || path.isAbsolute(pathStr)) {
+    if (!pathStr || path__namespace.isAbsolute(pathStr)) {
         return pathStr;
     }
-    return path.resolve(configDir, pathStr);
+    return path__namespace.resolve(configDir, pathStr);
 }
 /**
  * Discovers configuration directories by traversing up the directory tree.
@@ -516,19 +532,19 @@ function setNestedValue$1(obj, path, value) {
         log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
     });
     const discoveredDirs = [];
-    let currentDir = path.resolve(startingDir);
+    let currentDir = path__namespace.resolve(startingDir);
     let level = 0;
     const visited = new Set(); // Prevent infinite loops with symlinks
     logger === null || logger === void 0 ? void 0 : logger.debug(`Starting hierarchical discovery from: ${currentDir}`);
     while(level < maxLevels){
         // Prevent infinite loops with symlinks
-        const realPath = path.resolve(currentDir);
+        const realPath = path__namespace.resolve(currentDir);
         if (visited.has(realPath)) {
             logger === null || logger === void 0 ? void 0 : logger.debug(`Already visited ${realPath}, stopping discovery`);
             break;
         }
         visited.add(realPath);
-        const configDirPath = path.join(currentDir, configDirName);
+        const configDirPath = path__namespace.join(currentDir, configDirName);
         logger === null || logger === void 0 ? void 0 : logger.debug(`Checking for config directory: ${configDirPath}`);
         try {
             const exists = await storage.exists(configDirPath);
@@ -546,7 +562,7 @@ function setNestedValue$1(obj, path, value) {
             logger === null || logger === void 0 ? void 0 : logger.debug(`Error checking config directory ${configDirPath}: ${error.message}`);
         }
         // Move up one directory level
-        const parentDir = path.dirname(currentDir);
+        const parentDir = path__namespace.dirname(currentDir);
         // Check if we've reached the root directory
         if (parentDir === currentDir) {
             logger === null || logger === void 0 ? void 0 : logger.debug('Reached filesystem root, stopping discovery');
@@ -567,7 +583,7 @@ function setNestedValue$1(obj, path, value) {
  * @param logger Optional logger for debugging
  * @returns Promise resolving to the found config file path or null if not found
  */ async function findConfigFileWithExtension$1(storage, configDir, configFileName, logger) {
-    const configFilePath = path.join(configDir, configFileName);
+    const configFilePath = path__namespace.join(configDir, configFileName);
     // First try the exact filename as specified
     const exists = await storage.exists(configFilePath);
     if (exists) {
@@ -578,11 +594,11 @@ function setNestedValue$1(obj, path, value) {
     }
     // If the exact filename doesn't exist or isn't readable, try alternative extensions
     // Only do this if the filename has a .yaml or .yml extension
-    const ext = path.extname(configFileName);
+    const ext = path__namespace.extname(configFileName);
     if (ext === '.yaml' || ext === '.yml') {
-        const baseName = path.basename(configFileName, ext);
+        const baseName = path__namespace.basename(configFileName, ext);
         const alternativeExt = ext === '.yaml' ? '.yml' : '.yaml';
-        const alternativePath = path.join(configDir, baseName + alternativeExt);
+        const alternativePath = path__namespace.join(configDir, baseName + alternativeExt);
         logger === null || logger === void 0 ? void 0 : logger.debug(`Config file not found at ${configFilePath}, trying alternative: ${alternativePath}`);
         const altExists = await storage.exists(alternativePath);
         if (altExists) {
@@ -610,11 +626,11 @@ function setNestedValue$1(obj, path, value) {
         log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
     });
     try {
-        logger === null || logger === void 0 ? void 0 : logger.verbose(`Attempting to load config file: ${path.join(configDir, configFileName)}`);
+        logger === null || logger === void 0 ? void 0 : logger.verbose(`Attempting to load config file: ${path__namespace.join(configDir, configFileName)}`);
         // Try to find the config file with alternative extensions
         const configFilePath = await findConfigFileWithExtension$1(storage, configDir, configFileName, logger);
         if (!configFilePath) {
-            logger === null || logger === void 0 ? void 0 : logger.debug(`Config file does not exist: ${path.join(configDir, configFileName)}`);
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Config file does not exist: ${path__namespace.join(configDir, configFileName)}`);
             return null;
         }
         const yamlContent = await storage.readFile(configFilePath, encoding);
@@ -632,7 +648,7 @@ function setNestedValue$1(obj, path, value) {
             return null;
         }
     } catch (error) {
-        logger === null || logger === void 0 ? void 0 : logger.debug(`Error loading config from ${path.join(configDir, configFileName)}: ${error.message}`);
+        logger === null || logger === void 0 ? void 0 : logger.debug(`Error loading config from ${path__namespace.join(configDir, configFileName)}: ${error.message}`);
         return null;
     }
 }
@@ -1540,6 +1556,20 @@ function _define_property(obj, key, value) {
     }
 }
 
+/**
+ * Supported configuration file formats.
+ * 
+ * - 'yaml': YAML format (.yaml, .yml)
+ * - 'json': JSON format (.json)
+ * - 'javascript': JavaScript module (.js, .mjs, .cjs)
+ * - 'typescript': TypeScript module (.ts, .mts, .cts)
+ */ var ConfigFormat = /*#__PURE__*/ function(ConfigFormat) {
+    ConfigFormat["YAML"] = "yaml";
+    ConfigFormat["JSON"] = "json";
+    ConfigFormat["JavaScript"] = "javascript";
+    ConfigFormat["TypeScript"] = "typescript";
+    return ConfigFormat;
+}({});
 /**
  * Base Zod schema for core Cardigantime configuration.
  * Contains the minimum required configuration fields.
@@ -1548,6 +1578,35 @@ function _define_property(obj, key, value) {
     /** Array of all directory paths that were discovered during hierarchical search */ discoveredConfigDirs: zod.z.array(zod.z.string()),
     /** Array of directory paths that actually contained valid configuration files */ resolvedConfigDirs: zod.z.array(zod.z.string())
 });
+/**
+ * Default root markers used when none are specified.
+ * These indicate common project root boundaries.
+ */ const DEFAULT_ROOT_MARKERS = [
+    {
+        type: 'file',
+        name: 'package.json'
+    },
+    {
+        type: 'directory',
+        name: '.git'
+    },
+    {
+        type: 'file',
+        name: 'pnpm-workspace.yaml'
+    },
+    {
+        type: 'file',
+        name: 'lerna.json'
+    },
+    {
+        type: 'file',
+        name: 'nx.json'
+    },
+    {
+        type: 'file',
+        name: 'rush.json'
+    }
+];
 
 /**
  * Recursively extracts all keys from a Zod schema in dot notation.
@@ -2072,10 +2131,39 @@ function _define_property(obj, key, value) {
         checkConfig: (args)=>checkConfig(args, options)
     };
 };
+/**
+ * Type-safe helper for defining configuration in TypeScript/JavaScript files.
+ * 
+ * This is a simple identity function that provides type checking and
+ * autocomplete for configuration objects when using TypeScript config files.
+ * 
+ * @template T - The configuration type
+ * @param config - The configuration object
+ * @returns The same configuration object (identity function)
+ * 
+ * @example
+ * ```typescript
+ * // config.ts
+ * import { defineConfig } from '@theunwalked/cardigantime';
+ * 
+ * export default defineConfig({
+ *   apiKey: process.env.API_KEY || 'default-key',
+ *   timeout: 5000,
+ *   debug: process.env.NODE_ENV === 'development'
+ * });
+ * ```
+ */ function defineConfig(config) {
+    return config;
+}
 
 exports.ArgumentError = ArgumentError;
+exports.ConfigFormat = ConfigFormat;
 exports.ConfigSchema = ConfigSchema;
 exports.ConfigurationError = ConfigurationError;
+exports.DEFAULT_ROOT_MARKERS = DEFAULT_ROOT_MARKERS;
 exports.FileSystemError = FileSystemError;
+exports.PROGRAM_NAME = PROGRAM_NAME;
+exports.VERSION = VERSION;
 exports.create = create;
+exports.defineConfig = defineConfig;
 //# sourceMappingURL=cardigantime.cjs.map