@vetala/vetala 0.1.0-beta

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@vetala/vetala",
+  "version": "0.1.0-beta",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Terminal-first AI coding CLI with tools, memory, and local skills.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bymehul/vetala.git"
+  },
+  "homepage": "https://github.com/bymehul/vetala#readme",
+  "bugs": {
+    "url": "https://github.com/bymehul/vetala/issues"
+  },
+  "bin": {
+    "vetala": "./dist/src/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/src",
+    "skill",
+    "README.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "THIRD_PARTY_LICENSES.md",
+    "terminal.png"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "prepare": "npm run build",
+    "test": "node --test --import tsx test/**/*.ts"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^14.0.0",
+    "gradient-string": "^3.0.0",
+    "ink": "^6.8.0",
+    "ink-select-input": "^6.2.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "ora": "^9.3.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.12",
+    "tsx": "^4.20.5",
+    "typescript": "^5.8.2"
+  }
+}

package/skill/agents-md-generator/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: agents-md-generator
+description: Analyze repository structure and generate or update standardized AGENTS.md files that serve as contributor guides for AI agents. Supports both single-repo and monorepo structures. Measures LOC to determine character limits and produces structured documents covering overview, folder structure, patterns, conventions, and working agreements. Update mode refreshes only the standard sections while preserving user-defined custom sections. Use when setting up a new repository, onboarding AI agents to an existing codebase, updating an existing AGENTS.md, or when the user mentions AGENTS.md.
+---
+
+# AGENTS.md Generation Capability
+
+This skill enables the agent to generate `AGENTS.md` files that serve as contributor guides for AI agents working on a codebase.
+
+## Core Capability
+
+- **Function**: Analyze repository structure and generate or update a standardized `AGENTS.md` document
+- **Output Format**: Markdown file with structured sections
+- **Character Limit**: Dynamic, based on repository LOC (Lines of Code)
+- **Monorepo Support**: Automatically detects monorepo structures and generates hierarchical documentation (Root + Packages)
+- **Update Support**: Refreshes only standard sections in an existing `AGENTS.md`, preserving user-defined custom sections
+
+## Output Sections
+
+### Single Repo / Package Document (5 Sections)
+For single repositories or individual packages in a monorepo:
+
+- **Overview**: 1-2 sentence project description (abstract, no tool/framework lists)
+- **Folder Structure**: Key directories and their contents
+- **Core Behaviors & Patterns**: Logging, error handling, control flow, module structure patterns observed in code
+- **Conventions**: Naming, comments, code style derived from analysis
+- **Working Agreements**: Rules for agent behavior and communication
+
+### Monorepo Root Document (3 Sections)
+For the root of a monorepo structure:
+
+- **Overview**: 1-2 sentences describing the monorepo's purpose
+- **Folder Structure**: High-level map of apps, packages, and shared configs
+- **Working Agreements**: Common working agreements applicable to all packages
+
+## Operation Modes
+
+### Generate vs Update
+
+- **Generate**: Creates a new `AGENTS.md` from scratch (default when no `AGENTS.md` exists)
+- **Update**: Refreshes standard sections in an existing `AGENTS.md` while preserving custom sections. See [./references/update_strategy.md](./references/update_strategy.md) for detailed workflow and section matching rules.
+
+The agent automatically selects the appropriate mode based on whether an `AGENTS.md` file already exists at the target location.
+
+### Generation Modes (Monorepo)
+
+Supports three modes: **All** (root + all packages, default), **Root Only**, and **Single Package**. See [./references/monorepo_strategy.md](./references/monorepo_strategy.md) for detailed strategy and mode selection criteria.
+
+## Tools
+
+This skill uses the following read-only tools for repository analysis. See [./references/read_only_commands.md](./references/read_only_commands.md) for detailed usage patterns.
+
+- **`tokei`**: LOC measurement (required)
+- **`rg` (ripgrep)**: Content search (preferred)
+- **`grep` / `Select-String`**: Content search (fallback per OS)
+- **`sed -n` / `Get-Content \| Select-Object`**: Paginated file reading per OS
+- **`tree`**: Directory structure visualization
+- **`find`**: File and directory discovery (Linux / macOS)
+- **`ls`, `pwd`**: Basic directory navigation
+
+## Domain Knowledge
+
+- **LOC Measurement**: Capability to measure repository size and determine character limits. See [./references/loc_measurement.md](./references/loc_measurement.md)
+- **Repository Analysis**: Capability to inspect and understand codebase structure. See [./references/read_only_commands.md](./references/read_only_commands.md)
+- **Output Template**: Standardized AGENTS.md structure specification. See [./references/agents_md_template.md](./references/agents_md_template.md)
+- **Working Agreements**: Agent behavior rules for generated documents. See [./references/working_agreements.md](./references/working_agreements.md)
+- **Monorepo Detection**: Capability to identify monorepo structures. See [./references/monorepo_detection.md](./references/monorepo_detection.md)
+- **Monorepo Strategy**: Strategy for generating documentation in monorepos. See [./references/monorepo_strategy.md](./references/monorepo_strategy.md)
+- **Update Strategy**: Strategy for updating existing AGENTS.md files with selective section refresh. See [./references/update_strategy.md](./references/update_strategy.md)
+
+## Scope Boundaries
+
+- **Read-Only Analysis**: Supports non-destructive commands for repository inspection
+- **Output Scope**: Produces documentation content only; excludes run/test/build/deploy instructions
+- **Excluded Inputs**: Lock files (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, etc.) are outside analysis scope

package/skill/agents-md-generator/references/agents_md_template.md

@@ -0,0 +1,160 @@
+# AGENTS.md Output Template Specification
+
+Defines the exact structure and content requirements for generated `AGENTS.md` files.
+
+## Table of Contents
+
+- [Monorepo Root Document Structure](#monorepo-root-document-structure-agentsmd)
+- [Standard Document Structure](#standard-document-structure-single-repo--packages)
+- [Section Specifications](#section-specifications)
+- [Format Requirements](#format-requirements)
+- [Anti-Patterns (Excluded Content)](#anti-patterns-excluded-content)
+
+## Monorepo Root Document Structure (`/AGENTS.md`)
+
+Used only when generating the root document for a monorepo.
+
+```markdown
+# AGENTS.md
+
+## 1. Overview
+[1-2 sentences describing the monorepo's purpose]
+
+## 2. Folder Structure
+[High-level map of apps, packages, and shared configs]
+
+## 3. Working Agreements
+[Common working agreements applicable to all packages]
+```
+
+## Standard Document Structure (Single Repo & Packages)
+
+```markdown
+# AGENTS.md
+
+## 1. Overview
+[1-2 sentences describing the project's purpose and role]
+
+## 2. Folder Structure
+[Key directories with brief descriptions]
+
+## 3. Core Behaviors & Patterns
+[Observed patterns from code analysis]
+
+## 4. Conventions
+[Naming, comments, code style rules]
+
+## 5. Working Agreements
+[Agent behavior rules - see working_agreements.md]
+```
+
+## Section Specifications
+
+### Section 1: Overview
+
+- **Length**: 1-2 very short sentences
+- **Content**: Abstract description of project purpose and role
+- **Excludes**: Long lists of tools, frameworks, commands, environment details
+
+### Section 2: Folder Structure
+
+- **Format**: Hierarchical nested bullet list with indentation
+- **Analysis Scope**: Traverse **all depths** of the directory tree during analysis
+- **Output Scope**: Stop at **architecturally significant boundaries** where roles become clear
+- **Content**: Each listed entry should explain the **role and responsibility** concisely
+- **Goal**: Reader should understand where to find/place code for a given concern
+
+**Analysis vs Output Principle**:
+
+- **Analysis**: All depths — Understand full structure and identify architectural boundaries
+- **Output**: Significant levels only — Present only directories where distinct roles and responsibilities exist
+
+**When to Stop Drilling Down**:
+
+- When a directory represents a **single cohesive concern** (e.g., `services`, `models`, `utils`)
+- When further depth would only list individual files, not distinct modules
+- When the role can be summarized in one brief sentence
+
+**Content Requirements**:
+
+- Describe **what** the directory contains and **why** it exists in a brief sentence
+- For source directories, explain the architectural role (e.g., "actions", "services", "models")
+- Mention any conventions (e.g., "mirror main packages if tests are added")
+- Note cross-references to docs if relevant (e.g., "align changes with these when relevant")
+
+**Example Structure**:
+
+```markdown
+- `src/main/kotlin/com/example/app`: core application code.
+    - `actions`: UI actions wiring user interactions to business logic.
+    - `services`: business logic, external integrations, data processing.
+    - `ui`: view components, dialogs, panels, layout scaffolding.
+    - `model`: domain entities, enums, DTOs.
+    - `utils`: shared helpers and utility functions.
+    - `settings`: configuration management and persistent state.
+- `src/main/resources`: configuration files, message bundles, static assets.
+- `src/test/kotlin`: test code; mirror main package structure when adding tests.
+- `docs`: development guides and specifications; keep aligned with implementation.
+- `gradle/` or `config/`: build configuration and tooling setup.
+```
+
+**Anti-patterns**:
+
+- Flat list without hierarchy or context
+- Generic descriptions like "Core plugin implementation" without explaining structure
+- Omitting important subdirectories that define architecture
+- Missing guidance on where to place new code
+
+### Section 3: Core Behaviors & Patterns
+
+Document **cross-cutting patterns** that repeat across the codebase. Focus on patterns that a contributor must follow to keep code consistent — not individual function descriptions.
+
+**Pattern Discovery Approach**:
+
+- Search for **recurring idioms** that appear in 3+ files (e.g., shared error handling wrappers, common logging calls, repeated guard clause shapes)
+- Identify **architectural boundaries** and how data flows across them (e.g., Controller → Service → Repository, Action → Service → UI)
+- Look for **project-specific abstractions** the team has built on top of frameworks (e.g., custom base classes, shared decorators, wrapper utilities)
+- Note **implicit rules** not captured in linter configs (e.g., "all async operations go through a central queue", "state mutations only via specific helpers")
+
+**Pattern Categories** (include only those actually observed):
+
+- **Logging**: Logger initialization pattern, log levels, structured logging conventions
+- **Error Handling**: Error propagation strategy, recovery vs fail-fast, custom error types
+- **Control Flow**: Guard clauses, early returns, null-safety idioms
+- **Concurrency / Threading**: Thread model, async patterns, synchronization approaches
+- **Module Communication**: How modules call each other, dependency direction, event/message patterns
+- **State Management**: Where and how state is held, mutated, and shared
+
+**Anti-patterns**:
+
+- Listing individual functions or classes instead of cross-cutting patterns
+- Describing what a single file does rather than what the codebase does consistently
+- Including patterns that appear only once (not truly cross-cutting)
+
+### Section 4: Conventions
+
+- **Naming**: camelCase, snake_case, PascalCase usage
+- **Prefixes/Suffixes**: `SomethingService`, `useSomething`, `SomethingProps`
+- **Comments**: Tone, language, brevity
+- **Legacy Handling**: TODO, FIXME, NOTE, deprecated markers
+
+### Section 5: Working Agreements
+
+See the working agreements specification referenced from SKILL.md.
+
+## Format Requirements
+
+- **Language**: English only (for the content of the `AGENTS.md` file)
+- **Max Length**: Dynamic based on repository LOC (see LOC measurement specification referenced from SKILL.md)
+- **Format**: Valid Markdown
+- **Tone**: Concise, neutral
+- **Headings**: Short and descriptive
+- **Content Style**: Compact bullet points or short sentences
+
+## Anti-Patterns (Excluded Content)
+
+- "Common Commands" section
+- "How to run" instructions
+- "Testing Strategy" documentation
+- Build/deploy instructions
+- Detailed CI pipeline configuration

package/skill/agents-md-generator/references/loc_measurement.md

@@ -0,0 +1,67 @@
+# LOC Measurement Specification
+
+Defines the method for measuring repository size and determining dynamic character limits for AGENTS.md.
+
+## Measurement Command
+
+```bash
+tokei -e "*.json" -e "*.yaml" -e "*.yml" -e "*.md" -e "*.sh" -e "*.lock" -e "*.map" -e "*.svg" .
+```
+
+**Priority**: This is the **first step** before generating AGENTS.md.
+
+## Tool Installation
+
+If `tokei` is not installed:
+
+```
+tokei is not installed.
+https://github.com/XAMPPRocky/tokei Please install it from here and try again.
+```
+
+## Character Limit by Repository Scale
+
+```yaml
+- scale: Small
+  loc_range: "≤ 10,000"
+  character_limit: 10,000
+- scale: Small-Medium
+  loc_range: "10,001 ~ 50,000"
+  character_limit: 12,000
+- scale: Medium
+  loc_range: "50,001 ~ 100,000"
+  character_limit: 15,000
+- scale: Medium-Large
+  loc_range: "100,001 ~ 500,000"
+  character_limit: 20,000
+- scale: Large
+  loc_range: "500,001 ~ 1,000,000"
+  character_limit: 30,000
+- scale: Extra-Large
+  loc_range: "> 1,000,000"
+  character_limit: 50,000
+```
+
+## Workflow
+
+1. Run `tokei` command to get total LOC
+2. If tokei not installed → display installation guide and stop
+3. Determine repository scale from LOC value
+4. Apply corresponding character limit to AGENTS.md generation
+
+## tokei Output Interpretation
+
+Use the **Total** lines value from tokei output:
+
+```
+===============================================================================
+ Language            Files        Lines         Code     Comments       Blanks
+===============================================================================
+ TypeScript            150        45000        38000         3000         4000
+ JavaScript             30         5000         4200          400          400
+-------------------------------------------------------------------------------
+ Total                 180        50000        42200         3400         4400
+===============================================================================
+```
+
+In this example: Total Lines = 50,000 → Small-Medium → 10,000 chars limit

package/skill/agents-md-generator/references/monorepo_detection.md

@@ -0,0 +1,78 @@
+# Monorepo Detection Specification
+
+Defines the method for identifying if the current repository is a monorepo.
+
+## Detection Logic
+
+A repository is considered a monorepo if **any** of the following marker files or configurations exist in the root directory:
+
+### JavaScript / TypeScript Ecosystem
+
+- **`pnpm-workspace.yaml`**: pnpm workspaces
+- **`lerna.json`**: Lerna
+- **`nx.json`**: Nx
+- **`turbo.json`**: Turborepo
+- **`rush.json`**: Rush
+- **`package.json`** with `workspaces` field: npm/Yarn workspaces
+
+### JVM Ecosystem (Gradle / Maven)
+
+- **`settings.gradle.kts`** or **`settings.gradle`** containing `include(` or `includeBuild(`: Gradle multi-project / composite build
+- **Root `pom.xml`** with `<modules>` section: Maven multi-module project
+
+### Go
+
+- **`go.work`**: Go workspaces (Go 1.18+)
+
+### Rust
+
+- **`Cargo.toml`** with `[workspace]` section: Cargo workspaces
+
+### Python
+
+- **`pyproject.toml`** with `[tool.hatch.envs]` or workspace config: Hatch workspaces
+- Multiple `pyproject.toml` or `setup.py` under a shared root with a top-level orchestration config
+
+### Build Systems (Language-Agnostic)
+
+- **`WORKSPACE`** or **`WORKSPACE.bazel`** or **`MODULE.bazel`**: Bazel
+- **`pants.toml`** or **`pants.ini`**: Pants
+
+## Workspace Package Discovery
+
+After identifying a monorepo, discover packages from the relevant configuration:
+
+### JavaScript / TypeScript
+
+- **`pnpm-workspace.yaml`**: `packages` field
+- **`package.json`**: `workspaces` field
+- **`lerna.json`**: `packages` field
+- **`nx.json`**: `projects` field or scan directories
+
+### JVM (Gradle / Maven)
+
+- **`settings.gradle.kts`** / **`settings.gradle`**: Parse `include()` / `includeBuild()` declarations
+- **`pom.xml`**: Parse `<modules>` entries
+
+### Go
+
+- **`go.work`**: Parse `use` directives
+
+### Rust
+
+- **`Cargo.toml`**: Parse `[workspace] members` field
+
+### Build Systems
+
+- **Bazel**: Scan directories containing `BUILD` or `BUILD.bazel` files
+- **Pants**: Scan directories containing `BUILD` files
+
+## Fallback Discovery
+
+If no configuration explicitly lists packages, scan these common directory patterns:
+
+- `packages/*/`
+- `apps/*/`
+- `libs/*/`
+- `modules/*/`
+- `services/*/`

package/skill/agents-md-generator/references/monorepo_strategy.md

@@ -0,0 +1,60 @@
+# Monorepo Generation Strategy
+
+Defines the strategy for generating AGENTS.md files in a monorepo environment.
+
+## Generation Modes
+
+```yaml
+- mode: All (Default)
+  scope: Root + All Packages
+  when_to_use: Initial setup, full regeneration
+- mode: Root Only
+  scope: Root document only
+  when_to_use: Update shared working agreements
+- mode: Single Package
+  scope: One specific package
+  when_to_use: Package-specific changes
+```
+
+## Document Hierarchy
+
+```yaml
+- document: Root
+  location: /AGENTS.md
+  sections: 3
+  character_limit: Dynamic based on LOC
+- document: Package
+  location: Per-package directories discovered via workspace config (see monorepo_detection.md)
+  sections: 5 (Standard)
+  character_limit: Dynamic based on LOC
+```
+
+## LOC Measurement
+
+- **Root Document**: Run `tokei` in root directory
+- **Package Document**: Run `tokei` inside the package directory
+
+## Working Agreements Inheritance
+
+- **Root**: Full working agreements (master copy)
+- **Package**: "See root `/AGENTS.md`" (reference only, no additions)
+
+**Note**: Package-specific behaviors and conventions belong in **Section 3 (Core Behaviors & Patterns)** and **Section 4 (Conventions)**, not in Working Agreements.
+
+## Section Boundary Rules
+
+Defines what content belongs in which section of a package AGENTS.md.
+
+```yaml
+- content_type: Package-specific implementation patterns
+  target_section: Section 3 (Core Behaviors & Patterns)
+  examples: Logging approach, error handling, control flow
+- content_type: Package-specific naming/style conventions
+  target_section: Section 4 (Conventions)
+  examples: Naming rules, comment style, file organization
+- content_type: Common working principles across all packages
+  target_section: Section 5 (Working Agreements)
+  examples: Response language, code block handling, commit rules, context building
+```
+
+**Anti-pattern**: Do NOT place package-specific technical details (e.g., how a particular package handles errors or structures modules) into Section 5 (Working Agreements). Working Agreements are reserved for shared behavioral rules that apply uniformly across the entire repository.

package/skill/agents-md-generator/references/read_only_commands.md

@@ -0,0 +1,151 @@
+# Read-Only Commands Specification
+
+Defines the allowed commands for repository analysis during AGENTS.md generation.
+
+## Table of Contents
+
+- [Allowed Command Categories](#allowed-command-categories)
+- [ripgrep (`rg`) Usage Patterns](#ripgrep-rg-usage-patterns)
+- [tree Command Usage](#tree-command-usage)
+- [Files to Ignore](#files-to-ignore)
+- [Files Allowed to Read](#files-allowed-to-read)
+- [Source File Analysis Rules](#source-file-analysis-rules)
+
+## Allowed Command Categories
+
+### Basic Inspection
+
+- **`pwd`**: Print working directory
+- **`ls`**: List directory contents
+- **`tree`**: Display directory structure
+- **`find`**: File and directory discovery (Linux / macOS)
+- **`Get-ChildItem`**: File and directory discovery (Windows PowerShell)
+
+### LOC Measurement
+
+- **`tokei`**: Count lines of code — **Required** for determining character limits (see LOC measurement specification referenced from SKILL.md)
+
+### Content Search
+
+```yaml
+- command: rg (ripgrep)
+  platform: All
+  priority: Preferred
+  notes: Check availability first with `rg --version`
+- command: grep
+  platform: Linux / macOS
+  priority: Fallback
+  notes: Use only if `rg` unavailable
+- command: Select-String
+  platform: Windows (PowerShell)
+  priority: Fallback
+  notes: Use only if `rg` unavailable
+```
+
+### Paginated File Reading
+
+When additional context is needed beyond initial search results, read files in incremental ranges:
+
+- **Linux / macOS**: `sed -n 'START,ENDp' FILE` — e.g. `sed -n '1,80p' src/app.js`
+- **Windows (PowerShell)**: `Get-Content FILE | Select-Object -Skip (START-1) -First COUNT` — e.g. `Get-Content src\app.js | Select-Object -Skip 0 -First 80`
+
+**Incremental reading pattern**:
+
+1. Read an initial range (e.g., lines 1–80)
+2. If the context is insufficient, continue from where the previous range ended (e.g., lines 81–160)
+3. Repeat until enough context is collected
+
+**Per-file reading limit**:
+
+- Default upper bound: **800 lines** per file
+- Line budget applies **from the first non-import line**; import/require/using blocks at the top of a file are excluded from the count
+- Extend beyond 800 lines **only** when architecture boundaries (e.g., module exports, class definitions, route registrations) have not yet been identified
+- When extending, read in additional 400-line increments and re-evaluate after each increment
+- **Hard cap: 1600 lines** per file — never read beyond this limit regardless of context needs
+- Collect only the context required for analysis; avoid excessive context collection that may degrade output quality
+
+## ripgrep (`rg`) Usage Patterns
+
+### Scope Filtering
+
+```bash
+rg "pattern" -g "*.js" -g "!*.min.js"  # Target by glob, exclude minified
+rg "pattern" -g "src/**"               # Scope to a directory subtree
+```
+
+### Visibility & Configs
+
+```bash
+rg "pattern" --hidden       # Include hidden files, respect .gitignore
+```
+
+### Context Retrieval
+
+```bash
+rg "pattern" -C 5           # Include 5 surrounding lines
+```
+
+### Output Control
+
+```bash
+rg "pattern" -l             # List files only (discovery)
+rg "pattern" --json         # JSON output for parsing
+```
+
+### Search Safety
+
+```bash
+rg -F "exact.string()"      # Literal search (no regex)
+```
+
+## tree Command Usage
+
+```bash
+tree -I 'node_modules|.git|dist|build|.turbo|.next|out' -L 3
+```
+
+**Purpose**: Ignore large, low-signal directories (node_modules, build artifacts, VCS metadata)
+
+**Note**: `-L 3` is an example depth. Increase depth as needed for full structural analysis (e.g., `-L 5` or `-L 8` for deeper hierarchies).
+
+## Files to Ignore
+
+Lock files must NOT be read:
+
+- `pnpm-lock.yaml`
+- `package-lock.json`
+- `yarn.lock`
+- `poetry.lock`
+- `Pipfile.lock`
+- `Cargo.lock`
+- `Gemfile.lock`
+- `Podfile.lock`
+- Any other dependency lockfile
+
+## Files Allowed to Read
+
+### Documentation
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `docs/` contents
+
+### Style/Tooling Configuration
+
+- `.editorconfig`
+- `.eslintrc*`, `eslint.config.*`
+- `.prettierrc*`
+- `pyproject.toml`, `ruff.toml`, `mypy.ini`
+
+### Package Manifests
+
+- `package.json`
+- `pyproject.toml`
+- `go.mod`
+- `Cargo.toml`
+
+## Source File Analysis Rules
+
+- **Skip**: Import/require/using sections when analyzing patterns
+- **Infer Stack From**: Package manifests, not import statements
+- **Additional Context**: Use paginated file reading to collect more context as needed