npm package: @kolaystack/agent
Description: Lightweight project-side agent that generates machine-readable project memory for KolayStack
Author: KolayStack
Latest version: 1.0.1

# @kolaystack/agent

A lightweight project-side agent that generates machine-readable project memory for KolayStack to consume.

## Why It Exists

KolayStack Agent scans a project locally, detects its architecture and readiness, and writes standardized memory/status files into a `.kolaystack/` folder. KolayStack central will later read these files instead of deeply parsing every repo on every request.

## Installation

```bash
# Using npx (recommended for quick usage)
npx @kolaystack/agent init

# Or install globally
npm install -g @kolaystack/agent

# Or add to your project
npm install --save-dev @kolaystack/agent
```

## Quick Start

```bash
# Initialize KolayStack in your project
npx kolaystack-agent init

# Scan the project and see what it detects
npx kolaystack-agent scan

# Export results to .kolaystack/ folder
npx kolaystack-agent export

# Check project status
npx kolaystack-agent status

# Validate setup
npx kolaystack-agent doctor
```

## Commands

### init

Creates the `.kolaystack/` directory with:
- `config.json` - Project configuration and metadata
- `README.md` - Documentation

```bash
npx kolaystack-agent init
```

### scan

Scans the local repository and prints a summary to the terminal:
- Detected framework (Next.js, React, Express, etc.)
- Detected backend (Express, FastAPI, NestJS)
- Database (Supabase, PostgreSQL, etc.)
- Auth solution
- AI providers
- Integrations
- Implementation scores

```bash
npx kolaystack-agent scan
```

### export

Writes structured JSON files into `.kolaystack/`:
- `project.json` - Project info
- `status.json` - Current status
- `implementation.json` - Implementation scores
- `interconnectivity.json` - Related apps
- `audit.json` - Audit findings
- `gtm.json` - Go-to-market recommendations
- `evidence.json` - All evidence used for scoring

```bash
npx kolaystack-agent export
```

### status

Prints a compact human-readable summary of the project based on `.kolaystack/*.json` files.

```bash
npx kolaystack-agent status
```

### doctor

Validates whether required data files exist, checks for stale exports, and warns about missing evidence.

```bash
npx kolaystack-agent doctor
```

## Output Files

### `.kolaystack/config.json`

Project metadata (should be committed to git):

```json
{
  "project_name": "my-app",
  "preferred_company": "KolayStack",
  "preferred_customer": "Enterprise",
  "preferred_project_manager": "Technical",
  "tags": ["saas", "b2b"],
  "category": "webapp",
  "importance": "high",
  "output_mode": "full"
}
```

### `.kolaystack/project.json`

Detected project information:

```json
{
  "project_name": "my-app",
  "repo_name": "my-app",
  "detected_framework": "Next.js",
  "detected_language": "TypeScript",
  "app_type": "web",
  "description": "My SaaS application",
  "primary_branch": "main",
  "package_manager": "npm",
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-15T00:00:00.000Z"
}
```

### `.kolaystack/implementation.json`

Implementation and readiness scores:

```json
{
  "frontend_status": { "score": 75, "stage": "progressing", "evidence": [...] },
  "backend_status": { "score": 60, "stage": "progressing", "evidence": [...] },
  "database_status": { "score": 80, "stage": "mature", "evidence": [...] },
  "auth_status": { "score": 90, "stage": "mature", "evidence": [...] },
  "testing_status": { "score": 40, "stage": "early", "evidence": [...] },
  "ci_cd_status": { "score": 70, "stage": "progressing", "evidence": [...] },
  "observability_status": { "score": 50, "stage": "early", "evidence": [...] },
  "implementation_percent": 66,
  "readiness_score": 65,
  "stage": "progressing",
  "generated_at": "2024-01-15T00:00:00.000Z"
}
```

### `.kolaystack/evidence.json`

All evidence used for scoring (critical for debugging):

```json
{
  "found_files": ["package.json", "tsconfig.json", ...],
  "detected_routes": ["/api/users", "/api/posts"],
  "detected_pages": ["/app/page.tsx", "/app/about/page.tsx"],
  "migrations_count": 5,
  "tests_count": 12,
  "docker_present": true,
  "ci_present": true,
  "auth_files": ["src/auth.ts"],
  "ai_provider_files": [],
  "env_keys_present": ["DATABASE_URL", "OPENAI_API_KEY"],
  "integration_markers": {},
  "generated_at": "2024-01-15T00:00:00.000Z"
}
```

## Supported Technologies

### Frameworks
- Next.js
- React
- Vue
- Svelte
- Deno
- Express
- FastAPI
- NestJS
- Fastify

### Databases
- Supabase
- PostgreSQL
- MySQL
- MongoDB
- Prisma
- Drizzle

### Infrastructure
- Docker
- Vercel
- Railway
- Netlify
- GitHub Actions
- GitLab CI

### AI
- OpenAI
- Anthropic
- Gemini
- LangChain
- LlamaIndex

### Auth
- NextAuth.js
- Clerk
- Supabase Auth
- Firebase Auth
- Auth0

### Integrations
- Stripe
- Resend
- SendGrid
- Twilio
- PostHog
- Sentry

## Security

- **Never sends data to remote servers by default**
- **No telemetry**
- **No secret values written to output files**
- Only writes presence/absence of env keys (e.g., `"OPENAI_API_KEY": true`, never the actual value)
- All scanning is local-only

## Architecture

```
src/
  cli.ts              # CLI entry point
  index.ts            # Package exports
  commands/
    init.ts           # Initialize .kolaystack/
    scan.ts           # Scan and detect technologies
    export.ts         # Write JSON files
    status.ts         # Print project status
    doctor.ts         # Validate setup
  core/
    buildReport.ts    # Orchestrate detection + scoring
    detectors/
      framework.ts    # Detect frameworks
      backend.ts      # Detect backends
      database.ts     # Detect databases
      infra.ts        # Detect infra (Docker, CI, etc.)
      ai.ts           # Detect AI providers
      auth.ts         # Detect auth solutions
      integrations.ts # Detect integrations
    scanners/
      fileScanner.ts  # Scan filesystem
      packageScanner.ts # Scan package.json
      envScanner.ts   # Scan env files
      codeScanner.ts  # Scan code patterns
    scoring/
      index.ts        # Calculate scores
    writers/
      index.ts        # Write JSON files
  types/
    index.ts          # TypeScript interfaces
  utils/
    fileSystem.ts     # File operations
    logger.ts         # Console output
    safeJson.ts       # Safe JSON handling
    config.ts         # Config loading
```

## How KolayStack Consumes This

KolayStack central reads the `.kolaystack/` folder:

1. **config.json** - Project metadata (company, customer, tags)
2. **project.json** - Framework, language, app type
3. **implementation.json** - Scores and readiness
4. **evidence.json** - All raw evidence for verification

This allows KolayStack to:
- Skip deep repo parsing on every request
- Get standardized project metadata
- Verify implementation claims against evidence
- Make informed recommendations

## Roadmap

- [ ] Add more framework detections (Laravel, Django, Ruby on Rails)
- [ ] Add Python/PHP/Go scanner support
- [ ] Add custom marker support for project-specific detection
- [ ] Add diff detection for incremental updates
- [ ] Add optional remote sync (disabled by default)

## License

MIT