{"id":33601504,"url":"https://github.com/driule/ai-contextor","last_synced_at":"2026-04-19T01:08:26.736Z","repository":{"id":324407730,"uuid":"1097011506","full_name":"driule/ai-contextor","owner":"driule","description":"Project context freshness checker for AI projects. Ensures docs stay current with code changes.","archived":false,"fork":false,"pushed_at":"2025-11-15T16:05:31.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-15T17:34:22.634Z","etag":null,"topics":["ai-assistant","ai-context","cli-tool","documentation","documentation-tool","nodejs","npm-package","productivity"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/driule.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-15T11:20:03.000Z","updated_at":"2025-11-15T16:05:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/driule/ai-contextor","commit_stats":null,"previous_names":["driule/ai-contextor"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/driule/ai-contextor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/driule%2Fai-contextor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/driule%2Fai-contextor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/driule%2Fai-contextor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/driule%2Fai-contextor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/driule","download_url":"https://codeload.github.com/driule/ai-contextor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/driule%2Fai-contextor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31990586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"ssl_error","status_checked_at":"2026-04-18T20:23:29.375Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","ai-context","cli-tool","documentation","documentation-tool","nodejs","npm-package","productivity"],"created_at":"2025-11-30T09:03:33.336Z","updated_at":"2026-04-19T01:08:26.728Z","avatar_url":"https://github.com/driule.png","language":"JavaScript","funding_links":["https://github.com/sponsors/driule"],"categories":[],"sub_categories":[],"readme":"# ai-contextor\n\n\u003e Keep your AI documentation fresh and in sync with code changes.\n\n[![npm version](https://img.shields.io/npm/v/ai-contextor.svg)](https://www.npmjs.com/package/ai-contextor)\n[![npm downloads](https://img.shields.io/npm/dm/ai-contextor.svg)](https://www.npmjs.com/package/ai-contextor)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/driule/ai-contextor.svg?style=social)](https://github.com/driule/ai-contextor)\n\n📦 **npm package**: [ai-contextor](https://www.npmjs.com/package/ai-contextor)  \n⭐ **Star us on GitHub**: [driule/ai-contextor](https://github.com/driule/ai-contextor)  \n💝 **Support this project**: [GitHub Sponsors](https://github.com/sponsors/driule)\n\nCheck documentation freshness for AI assistant projects. Automatically detects when documentation needs updates after code changes. Non-intrusive, git-aware, and highly configurable.\n\n---\n\n## 🚀 Quick Start\n\n### Step 1: Installation\n\nInstall as a development dependency:\n\n```bash\nnpm install --save-dev ai-contextor\n```\n\nOr use it directly with npx (no installation needed):\n\n```bash\nnpx ai-contextor\n```\n\n### Step 2: Initialize Documentation\n\nGenerate initial documentation structure for your project:\n\n```bash\nnpx contextor init\n```\n\nThis command will:\n- 🔍 Analyze your project structure\n- 📊 Detect project type (frontend, backend, fullstack, library, etc.)\n- 🛠️ Identify frameworks and technologies\n- 📄 Create `.ai/INIT.md` with project context for AI assistants\n\n**Example output:**\n```\n🔍 Analyzing project structure...\n\n✅ Documentation initialized!\n\n📄 Created: .ai/INIT.md\n\n📊 Project Type: frontend\n🛠️  Frameworks: React, Next.js\n💻 Languages: TypeScript, JavaScript, CSS\n\n💡 Review and customize .ai/INIT.md as needed.\n```\n\n### Step 3: Configure (Optional)\n\nCreate `.contextor.config.js` in your project root to customize behavior:\n\n```javascript\nmodule.exports = {\n  // Documentation directory\n  docsDir: \".ai\",\n  \n  // Source directories to monitor\n  sourceDirs: [\"src\"],\n  \n  // Mapping: source files → documentation files\n  mappings: {\n    \"src/app.ts\": [\".ai/architecture/system-overview.md\"],\n    \"src/services/**/*.ts\": [\".ai/architecture/components.md\"],\n  },\n  \n  // Cache file location (default: .ai/docs-check-cache.json)\n  cacheFile: \".ai/docs-check-cache.json\",\n  \n  // Check settings\n  check: {\n    lastUpdated: true,  // Check \"Last Updated\" dates\n    version: true,       // Check version numbers\n    links: true,         // Check broken links\n    structure: true,     // Check required sections\n  },\n};\n```\n\n### Step 4: Check Documentation\n\nRun the checker to verify documentation freshness:\n\n```bash\n# Basic check\nnpx contextor\n\n# Force check (ignore cache)\nnpx contextor --force\n\n# Quiet mode (minimal output)\nnpx contextor --quiet\n```\n\n### Step 5: Development Task Workflow (Optional)\n\nUse the task system for managing development documentation:\n\n```bash\n# 1. Create a new task\nnpx contextor task:new \"Add user authentication\"\n\n# 2. Develop and document in .ai/dev/task-0/ folder\n#    - Edit requirements.md\n#    - Add notes to notes.md\n#    - Document implementation in implementation.md\n\n# 3. Generate documentation drafts\nnpx contextor 0\n\n# 4. AI assistant reviews and improves drafts\n#    - Review .ai/dev/task-0/doc-integration-*.md files\n#    - Follow instructions in DOC-INTEGRATION.md\n\n# 5. Integrate improved documentation\nnpx contextor 0 --integrate\n\n# 6. Commit documentation updates\ngit add .ai/\ngit commit -m \"Update documentation for user authentication\"\n```\n\n---\n\n## 📖 Features\n\n- ✅ **Smart Project Analysis** - Automatically detects project type and tech stack\n- ✅ **Documentation Initialization** - Generates `.ai/INIT.md` with project context\n- ✅ **Development Task System** - Manage temporary task documentation with integration workflow\n- ✅ **Freshness Checking** - Detects outdated documentation\n- ✅ **Git Integration** - Only checks when code changes\n- ✅ **Link Validation** - Checks for broken internal links\n- ✅ **Structure Validation** - Ensures required sections exist\n- ✅ **Smart Caching** - Avoids redundant checks\n- ✅ **Safe Defaults** - Won't overwrite existing documentation unless forced\n- ✅ **Configurable** - Works with any project structure\n\n---\n\n## 📝 Usage Guide\n\n### Initializing Documentation\n\nThe `init` command analyzes your project and creates a comprehensive `INIT.md` file:\n\n```bash\nnpx contextor init\n```\n\n**What it does:**\n- Scans project structure (directories, files, dependencies)\n- Detects project type (frontend/backend/fullstack/library/monorepo)\n- Identifies frameworks (React, Vue, Express, NestJS, etc.)\n- Detects build tools (Webpack, Vite, etc.)\n- Identifies test frameworks (Jest, Vitest, Cypress, etc.)\n- Generates `.ai/INIT.md` with:\n  - Project overview and type\n  - Technology stack\n  - Project structure explanation\n  - Development workflow\n  - Documentation guidelines\n  - AI assistant instructions\n\n### Checking Documentation Freshness\n\nRun the checker to ensure documentation stays up-to-date:\n\n```bash\n# Standard check\nnpx contextor\n\n# Force check (bypass cache)\nnpx contextor --force\nnpx contextor -f\n\n# Quiet mode\nnpx contextor --quiet\nnpx contextor -q\n```\n\n**What it checks:**\n- Whether source files were modified after documentation\n- Missing \"Last Updated\" dates\n- Broken internal links\n- Required documentation sections\n- Documentation structure compliance\n\n### Development Task Management\n\nManage temporary development documentation with the task system:\n\n**1. Create a new task:**\n```bash\nnpx contextor task:new \"Add user authentication\"\n```\n\nThis creates `.ai/dev/task-0/` with:\n- `README.md` - Task overview and status\n- `requirements.md` - Detailed requirements template\n- `notes.md` - Development notes template\n- `implementation.md` - Implementation details template\n\n**2. Generate documentation drafts:**\n```bash\n# After committing code changes\nnpx contextor 0\n```\n\nThis generates:\n- `doc-integration-*.md` - Draft documentation files\n- `DOC-INTEGRATION.md` - Instructions for AI assistant\n\n**3. Integrate improved drafts:**\n```bash\n# After AI assistant improves drafts\nnpx contextor 0 --integrate\n```\n\nThis integrates the improved drafts into main documentation (`.ai/` directory).\n\n**Task workflow:**\n1. Create task → Develop → Document in task folder\n2. Commit code → Generate drafts\n3. AI assistant improves drafts\n4. Integrate → Commit documentation\n\n### Configuration\n\nCopy `.contextor.config.js.example` to `.contextor.config.js` and customize:\n\n```bash\ncp .contextor.config.js.example .contextor.config.js\n```\n\nKey configuration options:\n- `docsDir` - Documentation directory (default: `.ai`)\n- `sourceDirs` - Directories to monitor for changes\n- `mappings` - Map source files to documentation files\n- `cacheFile` - Cache file location\n- `check.*` - Enable/disable specific checks\n\n---\n\n## 🎯 Common Workflows\n\n### New Project Setup\n\n```bash\n# 1. Install\nnpm install --save-dev ai-contextor\n\n# 2. Initialize documentation\nnpx contextor init\n\n# 3. Review and customize .ai/INIT.md\n\n# 4. Add to package.json scripts\n# \"scripts\": {\n#   \"docs:check\": \"contextor\"\n# }\n\n# 5. Run checks\nnpm run docs:check\n```\n\n### Existing Project\n\n```bash\n# 1. Initialize documentation\nnpx contextor init\n\n# 2. Configure mappings in .contextor.config.js\n# 3. Create documentation files in .ai/ directory\n# 4. Run checks regularly\nnpx contextor\n```\n\n### CI/CD Integration\n\nAdd to your CI pipeline:\n\n```yaml\n# GitHub Actions example\n- name: Check documentation freshness\n  run: npx contextor\n```\n\n---\n\n## 📁 Project Structure\n\nAfter initialization, your project will have:\n\n```\nyour-project/\n├── .ai/\n│   ├── INIT.md                      # Generated project context\n│   ├── README.md                    # Documentation framework overview\n│   ├── architecture/                # Architecture documentation\n│   ├── api/                         # API documentation\n│   ├── examples/                    # Usage examples\n│   ├── dev/                         # Development tasks (gitignored)\n│   │   ├── README.md                # Task system documentation\n│   │   └── task-N/                  # Individual task directories\n│   └── docs-check-cache.json        # Cache file (gitignored)\n├── .contextor.config.js             # Configuration (optional)\n└── ...\n```\n\n**Note:** The `.ai/dev/` directory is gitignored and contains temporary task documentation.\n\n---\n\n## 🔧 CLI Commands\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `npx contextor` | Check documentation freshness (default) |\n| `npx contextor init` | Initialize documentation structure |\n| `npx contextor init --force` | Initialize and overwrite existing INIT.md |\n| `npx contextor task:new \"description\"` | Create a new development task directory |\n| `npx contextor \u003ctask-list\u003e` | Generate documentation drafts for tasks |\n| `npx contextor \u003ctask-list\u003e --integrate` | Integrate improved drafts into main docs |\n| `npx contextor --help` | Show help message |\n| `npx contextor --version` | Show version number |\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `--force`, `-f` | Force mode (overwrite INIT.md or ignore cache) |\n| `--quiet`, `-q` | Quiet mode (minimal output) |\n\n### Examples\n\n```bash\n# Initialize documentation\nnpx contextor init\n\n# Initialize and overwrite existing INIT.md\nnpx contextor init --force\n\n# Create a new task\nnpx contextor task:new \"Add user authentication\"\n\n# Generate drafts for task-0\nnpx contextor 0\n# or\nnpx contextor task-0\n\n# Generate drafts for multiple tasks\nnpx contextor 0,1,2\n# or\nnpx contextor task-0,task-1,task-2\n\n# Integrate improved drafts\nnpx contextor 0 --integrate\n\n# Check documentation freshness\nnpx contextor\n\n# Force check (ignore cache)\nnpx contextor --force\n\n# Quiet mode\nnpx contextor --quiet\n```\n\n---\n\n## 📚 Documentation Structure\n\nDocumentation files in `.ai/` directory should follow this structure:\n\n```markdown\n# Document Title\n\n**Last Updated**: YYYY-MM-DD\n**Version**: 1.0.0\n\n## Overview\nBrief description...\n\n## Details\nMain content...\n\n## 🔗 Related Documentation\n- [Link to related doc](./other-doc.md)\n```\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) first.\n\n**Ways to contribute:**\n- 🐛 Report bugs\n- 💡 Suggest new features\n- 📝 Improve documentation\n- 🔧 Submit pull requests\n- ⭐ Star the repository\n\n---\n\n## 💝 Support \u0026 Sponsorship\n\nThis project is open source and free to use. If you find it helpful, please consider:\n\n- ⭐ **Starring** the repository on GitHub\n- 🐛 **Reporting** bugs and issues\n- 💬 **Sharing** with your team and community\n- 💝 **Sponsoring** the project to support continued development\n\n### GitHub Sponsors\n\nSupport this project through [GitHub Sponsors](https://github.com/sponsors/driule). Your sponsorship helps:\n\n- 🚀 Maintain and improve the project\n- 🐛 Fix bugs faster\n- ✨ Add new features\n- 📚 Create better documentation\n\n**Sponsorship Tiers:**\n- 🤖 **Assistant** ($5/month) - Thank you! Your name in README supporters list\n- 🚀 **Navigator** ($15/month) - Priority support + your name in README\n- ⚡ **Architect** ($50/month) - All above + feature requests priority\n- 🌟 **Context Master** ($200/month) - All above + custom features consultation\n\n*Note: GitHub Sponsors is free - GitHub doesn't take any fees for personal accounts!*\n\n### Other Ways to Support\n\n- 💼 **Hire me** for consulting or custom development\n- 📧 **Contact**: [GitHub Profile](https://github.com/driule)\n\n---\n\n## 📄 License\n\nMIT © [Andrius](https://github.com/driule)\n\n---\n\n## 📦 Version\n\nCurrent version: **0.5.4**\n\n**Status**: 🚧 Beta - Ready for use, but still in active development\n\n### What's New in v0.5.0\n\n- ✨ **Safe init behavior** - INIT.md is now skipped if exists (prevents overwriting custom docs)\n- ✨ **--force flag** - Allows overwriting INIT.md when needed\n- 🔧 **Refactored generator** - Improved code maintainability and extensibility\n- 📚 **Task system** - Complete development task workflow with draft generation and integration\n\n### Roadmap\n\n- [ ] Unit tests and test coverage\n- [ ] CI/CD pipeline\n- [ ] TypeScript definitions\n- [ ] More project type templates\n- [ ] Enhanced error messages\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdriule%2Fai-contextor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdriule%2Fai-contextor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdriule%2Fai-contextor/lists"}