claude-statusline 2.1.2

package/LICENSE

@@ -0,0 +1,203 @@
+                               Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (which shall not include communications that are solely written
+      by You).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based upon (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and derivative works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control
+      systems, and issue tracking systems that are managed by, or on behalf
+      of, the Licensor for the purpose of discussing and improving the Work,
+      but excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to use, reproduce, modify, merge, publish,
+      distribute, sublicense, and/or sell copies of the Work, and to
+      permit persons to whom the Work is furnished to do so, subject to
+      the following conditions:
+
+      The above copyright notice and this permission notice shall be
+      included in all copies or substantial portions of the Work.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, trademark, patent,
+          attribution and other notices from the Source form of the
+          Work, excluding those notices that do not pertain to any
+          part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright notice to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) ON AN "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. You may choose to offer, and to
+      charge a fee for, warranty, support, indemnity or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may act only on Your own behalf and
+      on Your sole responsibility, not on behalf of any other Contributor,
+      and only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against,
+      such Contributor by reason of your accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 shrwnsan
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,362 @@
+# Claude Code Statusline
+
+Simple statusline for Claude Code with project-branch, git indicators, and context usage. Optimized for speed with bun. Just the essentials, none of the bloat.
+
+![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
+![Version](https://img.shields.io/badge/version-2.1.2-green.svg)
+![TypeScript](https://img.shields.io/badge/language-TypeScript-3178C6.svg)
+![Node](https://img.shields.io/badge/node-%3E%3D22.6.0-brightgreen.svg)
+![Bun](https://img.shields.io/badge/runtime-Bun-black.svg)
+
+![Demo](https://github.com/user-attachments/assets/8716dc4e-83da-410b-88f2-c47de7dd5930)
+
+## Quick Start
+
+### Installation
+
+```bash
+# Bun install (recommended - 5x faster than Node.js)
+bun install -g claude-statusline
+
+# Or npm install (works well too)
+npm install -g claude-statusline
+
+# Or pnpm/yarn
+pnpm add -g claude-statusline
+yarn global add claude-statusline
+```
+
+
+### Claude Code Configuration
+
+#### Standard Configuration (Node.js Runtime)
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "claude-statusline"
+  }
+}
+```
+
+#### ⚡ Performance-Optimized Configuration (Bun Runtime)
+For maximum performance (~5ms response time), explicitly use the Bun runtime:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bun claude-statusline"
+  }
+}
+```
+
+> **Why specify "bun claude-statusline"?**
+> Even when installed with `bun install -g`, the executable's shebang defaults to Node.js. Using "bun claude-statusline" ensures you get the full Bun performance benefits.
+
+### Usage
+
+The statusline automatically displays when Claude Code is active and updates based on your git status and environment.
+
+### Default Configuration
+
+claude-statusline works out-of-the-box with these defaults:
+- `envContext`: false (environment versions NOT shown)
+- `truncate`: false (basic truncation at terminal width - 10)
+- `noEmoji`: false (Nerd Font symbols preferred, ASCII fallback)
+- `noGitStatus`: false (git status shown)
+- `noContextWindow`: false (context window usage shown)
+- `noSoftWrap`: false (soft wrapping enabled when truncate=true, set to true to disable)
+- `rightMargin`: 15 (prevents bleeding into Claude Code telemetry)
+- `cacheTTL`: 300 (5-minute cache for environment info)
+- `maxLength`: 1000 (maximum input length for security)
+
+To see environment versions in your statusline, create a configuration file with:
+```json
+{"envContext": true}
+```
+*See the [🎛️ Configuration](#-configuration) section below for how to create and manage config files*
+
+## ⚡ Performance
+
+🚀 **claude-statusline is lightning fast**
+
+- **With Bun runtime**: ~5ms response time (5x faster)
+- **With Node.js runtime**: ~28ms response time (still instant)
+- **Installation**: 19KB (tiny single-file bundle)
+
+### Real-world experience
+```bash
+# Install instantly
+bun install -g claude-statusline  # Downloads 19KB in <1 second
+
+# Add to Claude Code settings for maximum performance
+# ~/.claude/settings.json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bun claude-statusline"
+  }
+}
+
+# Enjoy instant git status updates! (~5ms with Bun vs ~28ms with Node.js)
+```
+
+**Performance Comparison:**
+- With `bun claude-statusline`: ~5ms ⚡
+- With `claude-statusline` (Node.js): ~28ms ✅
+- Both work perfectly - choose based on your preference
+
+### Why so fast?
+- ✅ Native git commands (no slow libraries)
+- ✅ Optimized for Bun runtime
+- ✅ Smart caching (8-hour environment cache)
+- ✅ Single-file bundle (no module resolution overhead)
+
+**Fun fact**: We started with a fast bash script (~60ms), accidentally made it slower with TypeScript (~327ms), then optimized it to be 12x faster than the original (~5ms with Bun)!
+
+*See [Performance Guide](docs/guide-03-performance.md) for the full optimization story*
+
+## Features
+
+### Git Status Indicators
+
+- **Stashed**: ⚑ (stashed changes)
+- **Deleted**: ✘ (files deleted)
+- **Modified**: ! (unstaged changes)
+- **Staged**: + (added to staging area)
+- **Untracked**: ? (new files not tracked)
+- **Renamed**: » (files moved/renamed)
+- **Conflicts**: × (merge conflicts)
+- **Diverged**: ⇕ (both ahead and behind upstream)
+- **Ahead**: ⇡ (commits ahead of upstream)
+- **Behind**: ⇣ (commits behind upstream)
+
+### Context Window Usage (Beta Feature)
+
+**⚠️ Beta Feature:** Context window usage display is currently in beta. The calculation follows the official Claude Code documentation but may show different values compared to Claude Code's built-in `/context` command.
+
+Automatically displays context window usage percentage when available (requires Claude Code to send context window data):
+
+```
+claude-statusline @ main [$!] *Opus #27% (ASCII version)
+```
+
+Shows percentage of context window consumed in the current conversation. The symbol varies by mode:
+- **Nerd Font**: ⚡︎ (lightning bolt)
+- **ASCII**: # (hash symbol)
+
+**Important Notes:**
+- Calculation follows [official Claude Code documentation](https://code.claude.com/docs/en/statusline#context-window-usage)
+- May differ from `/context` command due to different data sources or calculation methods
+- Only shows when Claude Code provides context window data
+- Can be disabled with `"noContextWindow": true` or `CLAUDE_CODE_STATUSLINE_NO_CONTEXT_WINDOW=1`
+
+**Known Discrepancy:**
+Some users have noted differences between the statusline percentage and `/context` command output. This appears to be a difference in how Claude Code internally calculates context usage versus what's provided through the statusline API.
+
+### Environment Context
+
+When enabled with `"envContext": true`, shows development tool versions:
+
+```
+claude-statusline @ main [$!A] *Claude Sonnet 4.5 Node22.17.1 Py3.13.5 Docker28.3.3 (ASCII version)
+```
+
+*Example shows ASCII mode for universal compatibility. With Nerd Fonts enabled, ASCII symbols are replaced with icons/emojis.*
+
+Supported tools:
+- **Node.js**: `node --version` (cached 5 minutes)
+- **Python**: `python3 --version` or `python --version` (cached 5 minutes)
+- **Docker**: `docker --version` (cached 30 minutes)
+
+### Smart Width Management
+
+Two modes available:
+
+1. **Basic Mode** (default):
+   - Simple truncation at `terminal width - 10` characters
+   - Always single-line
+   - Fast and predictable
+
+2. **Smart Truncation Mode** (`CLAUDE_CODE_STATUSLINE_TRUNCATE=1`):
+   - 15-character right margin prevents bleeding into Claude Code telemetry
+   - Branch prioritization: Branch names preserved over project names
+   - Progressive truncation: Project → Branch → Indicators (if absolutely necessary)
+   - Optional soft-wrapping: Can wrap model/environment info to preserve more context
+   - Responsive design: Adapts to terminal width from 60-200+ characters
+   - Disable soft-wrapping with `"noSoftWrap": true` to force single-line
+
+### Width Breakpoints
+
+| Width | Experience | Statusline Behavior |
+|-------|------------|-------------------|
+| **< 60** | Poor | Aggressive truncation |
+| **60-79** | Acceptable | Smart truncation, branch preserved |
+| **80-99** | Good | Ideal balance, minimal truncation |
+| **100-119** | Excellent | Usually no truncation needed |
+| **120+** | Perfect | No constraints, optimal UX |
+
+## Icon Reference & Nerd Font Support
+
+**Nerd Font Support (Optional):** Automatically detects Nerd Fonts and falls back to ASCII equivalents.
+
+For enhanced visual icons, install Nerd Fonts:
+- **macOS:** `font-jetbrains-mono-nerd-font` via Homebrew
+- **Cross-platform:** Download from [nerdfonts.com](https://nerdfonts.com/)
+
+### Icon Comparison
+
+![Icon Comparison Reference](https://github.com/user-attachments/assets/4190fd65-c425-4da7-8659-a7c7a6f15bc0)
+
+### ASCII Mode Display
+
+| Use Case | Default Symbol | ASCII Fallback | Notes |
+|----------|---------------|---------------|-------|
+| **Git Repository** | `@` | `@` | Always ASCII |
+| **Stashed Files** | `⚑` | `$` | ASCII when `"noEmoji": true` |
+| **Staged Changes** | `+` | `+` | Always ASCII |
+| **Modified Files** | `!` | `!` | Always ASCII |
+| **Untracked Files** | `?` | `?` | Always ASCII |
+| **Renamed Files** | `»` | `>` | ASCII when `"noEmoji": true` |
+| **Deleted Files** | `✘` | `X` | ASCII when `"noEmoji": true` |
+| **Merge Conflicts** | `×` | `C` | ASCII when `"noEmoji": true` |
+| **Ahead/Behind** | `⇡⇣` | `A/B` | ASCII when `"noEmoji": true` |
+| **Diverged** | `⇕` | `D` | ASCII when `"noEmoji": true` |
+| **Claude Model** | `🤖` | `*` | ASCII when `"noEmoji": true` |
+| **Context Window** | `⚡︎` | `#` | ASCII when `"noEmoji": true` |
+
+*Note: Examples show ASCII-compatible symbols. Full statusline with Nerd Fonts shows additional symbols: $X!+?>CADAB*
+
+### 🎛️ Configuration
+
+**📖 [Complete Configuration Guide](./docs/guide-01-configuration.md)**
+
+Configure with JSON/YAML files:
+
+```bash
+# Quick setup with minimal example
+cp .claude-statusline.json.example.min ~/.claude/claude-statusline.json
+
+# Or complete example with all options
+cp .claude-statusline.json.example ~/.claude/claude-statusline.json
+
+# Edit your configuration
+nano ~/.claude/claude-statusline.json
+```
+
+**Configuration search order:**
+1. `./claude-statusline.json` or `./claude-statusline.yaml` (project-level)
+2. Parent directories (searches up the tree)
+3. `~/.claude/claude-statusline.{json,yaml}` (global) ← **Recommended**
+4. Environment variables (legacy v1.0 support)
+
+*Only JSON and YAML formats are supported. First configuration file found is used.*
+
+## Examples (ASCII)
+
+### Default Behavior
+```bash
+# Basic truncation (default) - truncated at terminal width minus 10 chars
+claude-statusline @ main [$!A] *Claude Sonnet 4.5 #27%
+
+# With environment context enabled
+# Set "envContext": true in config file
+claude-statusline @ main [$!A] *Claude Sonnet 4.5 Node22.17.1 Py3.13.5 Docker28.3.3 #27%
+```
+
+### ASCII Mode (Fallback)
+```bash
+# With "noEmoji": true in config file
+claude-statusline @ main [$!A] *Claude Sonnet 4.5
+```
+
+## Documentation
+
+📚 **Complete documentation available in the [`docs/`](./docs) directory:**
+
+- **[Configuration Guide](./docs/guide-01-configuration.md)** - Complete configuration options and examples
+- **[Migration Guide](./docs/MIGRATION.md)** - Migrating from bash v1.0 to TypeScript v2.0
+- **[Feature Comparison](./docs/FEATURE_COMPARISON.md)** - Detailed comparison between versions
+- **[Documentation Index](./docs/README.md)** - Overview of all documentation
+
+## Security
+
+Enhanced security with input validation and type safety:
+- **Input Validation**: Comprehensive validation for all inputs
+- **Command Injection Prevention**: Sanitized shell command execution
+- **Path Traversal Protection**: Comprehensive path validation
+- **Type Safety**: TypeScript compile-time and runtime validation
+
+## Dependencies
+
+- **Required**: Node.js >= 22.6.0 or Bun >= 1.0.0, Git (for status parsing)
+- **Runtime**: yaml, zod
+- **Development**: TypeScript, ESLint, Prettier
+
+## Troubleshooting
+
+**Common Issues:**
+- **Build failures**: `npm install && npm run build`
+- **Performance issues**: Clear cache `rm -rf /tmp/.claude-statusline-cache/`
+- **Symbol display**: Force ASCII mode with `"noEmoji": true` in config
+
+## ❓ Frequently Asked Questions
+
+### Performance
+**Q: Is it really fast enough for real-time use?**
+A: Yes! With Bun it runs in ~5ms, which is instantaneous for human perception. Even with Node.js it's only ~28ms.
+
+**Q: Why do some benchmarks show ~136ms?**
+A: Those include system startup overhead. The actual execution time is much faster (~5ms with Bun). What matters is that it feels instant to users.
+
+**Q: Should I use Bun or Node.js?**
+A: Use Bun if you can - it's 5x faster (~5ms vs ~28ms). Configure it as "bun claude-statusline" in your settings.json to get the performance benefits. Node.js is still plenty fast for daily use.
+
+### Installation
+**Q: Why is the download only 19KB?**
+A: We use esbuild to bundle everything into a single optimized file. No downloading 500+ files!
+
+**Q: Do I need Node.js installed?**
+A: Yes, or Bun. We recommend Bun for best performance, but Node.js works perfectly fine.
+
+### Configuration
+**Q: How do I see Node/Python versions?**
+A: Create `~/.claude/claude-statusline.json` with `{"envContext": true}`.
+
+**Q: Can I customize the symbols?**
+A: Yes! Set `"noEmoji": true` for ASCII mode, or use Nerd Fonts for emoji icons.
+
+## Contributing
+
+See our [Contributing Guidelines](./CONTRIBUTING.md) for development setup and pull requests.
+
+## Changelog
+
+View [CHANGELOG.md](./CHANGELOG.md) for detailed version history and updates.
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) file for details.
+
+## 📦 Legacy: Bash v1.0
+
+> **Note:** Version 2.0 (TypeScript) is recommended for all users. Bash v1.0 is maintained for legacy environments only.
+
+For environments where Node.js/npm is not available:
+
+```bash
+curl -L -o claude-statusline.sh https://github.com/shrwnsan/claude-statusline/releases/download/v1.0.0/claude-statusline.sh
+chmod +x claude-statusline.sh
+```
+
+**Limitations of v1.0:**
+- Unix/Linux only (no Windows support)
+- No configuration files
+- No npm distribution
+- Basic width detection only
+
+See [Feature Comparison](./docs/FEATURE_COMPARISON.md) for details.
+

package/bin/claude-statusline

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Statusline - TypeScript v2.0
+ * Executable wrapper for the TypeScript implementation
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Import the main module (prefer bundled version if it exists)
+try {
+  const { main } = await import(join(__dirname, '..', 'dist', 'index.bundle.js'))
+    .catch(() => import(join(__dirname, '..', 'dist', 'index.js')));
+  await main();
+} catch (error) {
+  console.error('[ERROR] Failed to load claude-statusline:', error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/dist/core/cache.d.ts

@@ -0,0 +1,67 @@
+import { Config } from './config.js';
+/**
+ * Simple caching system with TTL support
+ * Ported from bash implementation with Node.js optimizations
+ */
+/**
+ * Cache wrapper that handles TTL and file operations
+ */
+export declare class Cache {
+    private config;
+    constructor(config: Config);
+    /**
+     * Ensure cache directory exists
+     */
+    private ensureCacheDir;
+    /**
+     * Get cache file path for a given key
+     */
+    private getCachePath;
+    /**
+     * Get cache timestamp file path for a given key
+     */
+    private getTimestampPath;
+    /**
+     * Read cached data with TTL validation
+     */
+    get<T = string>(key: string, ttl?: number): Promise<T | null>;
+    /**
+     * Write data to cache with timestamp
+     */
+    set<T = string>(key: string, data: T): Promise<boolean>;
+    /**
+     * Check if cache entry exists and is valid
+     */
+    has(key: string, ttl?: number): Promise<boolean>;
+    /**
+     * Delete cache entry
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all cache entries
+     */
+    clear(): Promise<boolean>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): Promise<{
+        total: number;
+        size: number;
+    }>;
+}
+/**
+ * Cache key generators for common use cases
+ */
+export declare const CacheKeys: {
+    readonly NODE_VERSION: "node_version";
+    readonly PYTHON_VERSION: "python_version";
+    readonly PYTHON3_VERSION: "python3_version";
+    readonly DOCKER_VERSION: "docker_version";
+    readonly GIT_REMOTE_URL: (dir: string) => string;
+    readonly GIT_BRANCH: (dir: string) => string;
+};
+/**
+ * Cached command execution helper
+ * Runs a command and caches the result
+ */
+export declare function cachedCommand(cache: Cache, key: string, command: string, args?: string[], ttl?: number): Promise<string | null>;