forgelens 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- `AI_FOCUS_MAP.md` to rank the highest-value files and areas before editing.
+- `AI_COMPACT_CONTEXT.md` for context-limit situations.
+- `ENV_REPORT.md` for env file names, referenced env key names, missing example keys, and public env risk hints without printing secret values.
+- `UI_UX_REPORT.md` for pages, components, forms, loading/empty/error states, responsive signals, and accessibility risk hints.
+- `PERFORMANCE_RISK_REPORT.md` for large files, client components, image usage, fetch calls, uncached fetch hints, and external API failure points.
+- `REPO_REPORT.json` with `--format json` or `--format all` for tool-readable output.
+- File-level focus scores with reasons and priority.
+- `forgelens drift` to compare two `REPO_REPORT.json` files and flag stale context around auth, routes, server actions, database, env, security, and focus files.
+- `forgelens baseline save` to save named baseline reports.
+- `forgelens drift --from <name>` and `forgelens drift --git base..head` workflows.
+- `DRIFT_REPORT.md` and `DRIFT_REPORT.json` when drift output is written to a folder.
+- Grouped env key sections in `ENV_REPORT.md`.
+- Static landing page under `site/` for product demos.
+- Project-specific `AGENTS.md` and `docs/PROJECT_MAP.md` for faster future agent work.
+
+### Changed
+
+- `forgelens prompt codex` now starts with `AI_COMPACT_CONTEXT.md` for tight context and includes the new reports.
+- `FORGE_CONTEXT.md`, `ARCHITECTURE_MAP.md`, and `RISK_REPORT.md` include the new focus, env, UI/UX, and performance signals.
+- Detector scans ignore test fixtures by default and avoid treating detector/test text as real app provider evidence.
+- Generated Workbox, sourcemap, and generated-code artifacts are ignored by default.
+
 ## 0.1.0 - 2026-05-18
 
 Initial CLI MVP release-readiness baseline.

package/README.md

@@ -1,84 +1,102 @@
 # ForgeLens
 
-ForgeLens is a local-first CLI that scans a codebase and generates clean repository context files for AI coding agents.
-
-## Status
-
-- ForgeLens is currently `v0.1.0`.
-- It is a local-first CLI for deterministic static analysis.
-- It is useful for generating AI repo context before edits.
-- It is not a full semantic analyzer.
-- It is not a security audit.
-
-## Why this tool exists
-
-AI coding agents work better when repo structure, auth boundaries, routes, and risk areas are explicit.
-Without clean context, agents guess more, make riskier edits, and miss architecture rules.
-
-ForgeLens solves this by producing deterministic Markdown context from static analysis.
-
-## Who this is for
-
-- Developers using Codex, Claude Code, Cursor, OpenCode, and similar tools
-- Teams that want shared repo understanding before AI-assisted edits
-
-## What ForgeLens does
-
-- Scans repository in read-only mode
-- Detects project signals (framework, routes, server actions, database, auth, middleware, env files)
-- Classifies database/auth detections with confidence (`high`, `medium`, `low`)
-- Shows evidence files for each detected signal
-- Writes context files to output folder only (default `.forgelens/`)
-
-## Supported signals/providers
-
-Database/provider signals:
-- Supabase
-- Prisma
-- Drizzle
-- TypeORM
-- Mongoose/MongoDB
-- Firebase/Firestore
-- PostgreSQL clients
-- MySQL clients
-- SQLite
-- SQL migrations
-- custom database layer
-- unknown
-
-Auth/provider signals:
-- Clerk
-- NextAuth/Auth.js
-- Supabase Auth
-- Firebase Auth
-- Lucia
-- Better Auth
-- JWT custom auth
-- cookie/session custom auth
-- middleware-based auth
-- custom auth
-- unknown
-
-## Requirements
-
-- Node.js 18+
-- Works with npm, pnpm, yarn, and bun projects where package metadata is available
+<p align="center">
+  <img src="assets/forgelens-hero.png" alt="ForgeLens hero" width="100%" />
+</p>
+
+<p align="center"><strong>AI coding workflow tracking for safer AI-assisted code changes.</strong></p>
+<p align="center">ForgeLens maps your repo, tracks drift, and generates AI-ready context before coding agents edit your project.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/forgelens"><img alt="npm package" src="https://img.shields.io/npm/v/forgelens?label=npm%20package" /></a>
+  <img alt="MIT license" src="https://img.shields.io/badge/license-MIT-black" />
+  <img alt="Local-first" src="https://img.shields.io/badge/local--first-yes-1f6feb" />
+  <img alt="No telemetry" src="https://img.shields.io/badge/telemetry-none-2da44e" />
+  <img alt="Codex" src="https://img.shields.io/badge/Codex-supported-111111" />
+  <img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-supported-111111" />
+  <img alt="Cursor" src="https://img.shields.io/badge/Cursor-supported-111111" />
+  <img alt="Copilot" src="https://img.shields.io/badge/Copilot-supported-111111" />
+  <img alt="Gemini CLI" src="https://img.shields.io/badge/Gemini%20CLI-supported-111111" />
+  <img alt="OpenCode" src="https://img.shields.io/badge/OpenCode-supported-111111" />
+  <img alt="Astro docs" src="https://img.shields.io/badge/Astro%20docs-included-6f42c1" />
+</p>
+
+## Why ForgeLens?
+
+AI coding agents often start in the wrong files. That creates slow edits, wasted context, and risky changes.
+
+Common problems:
+- Agents miss auth boundaries and session rules.
+- Agents skip database/schema risk and server action risk.
+- Agents ignore route exposure and env/config risk.
+- Project rules drift over time, while old context is still used.
+
+ForgeLens solves this with a local-first workflow:
+- Scan the repo and generate compact AI-ready context.
+- Highlight risky files and boundaries first.
+- Save a baseline snapshot.
+- Detect drift between baseline and current reports.
+- Compare drift across git refs with `main..HEAD`.
+
+## Quick Start
+
+```bash
+npx forgelens scan
+npx forgelens baseline save --name current
+npx forgelens drift --from current
+npx forgelens drift --git main..HEAD
+```
+
+## What ForgeLens Generates
+
+```text
+AI_COMPACT_CONTEXT.md
+AI_FOCUS_MAP.md
+FORGE_CONTEXT.md
+ARCHITECTURE_MAP.md
+ROUTES_MAP.md
+DATABASE_MAP.md
+SERVER_ACTIONS_MAP.md
+SECURITY_RULES.md
+ENV_REPORT.md
+RISK_REPORT.md
+DRIFT_REPORT.md
+REPO_REPORT.json
+```
+
+## Workflow Map
+
+```mermaid
+flowchart TD
+  A[Scan repo] --> B[Generate AI context]
+  B --> C[Risk reports]
+  C --> D[Save baseline]
+  D --> E[Detect drift]
+  E --> F[Git drift]
+  F --> G[AI agent reads focused context]
+  G --> H[Safer code changes]
+```
+
+## Works With
+
+ForgeLens is built for Codex, Claude Code, Cursor, Copilot, Gemini CLI, OpenCode, and other AI coding agents.
 
 ## Install
 
-ForgeLens is not published to npm yet. After npm release, install with:
+Quick run:
 
 ```bash
-npm install -g forgelens
+npx forgelens scan
 ```
 
-After npm release, use without global install:
+Global install:
 
 ```bash
-npx forgelens scan
+npm install -g forgelens
+forgelens scan
 ```
 
-Local development usage:
+Local development:
 
 ```bash
 pnpm install
@@ -87,86 +105,50 @@ pnpm link --global
 forgelens scan
 ```
 
-## CLI commands
+## CLI Commands
 
 ```bash
 forgelens scan
 forgelens doctor
+forgelens baseline save
+forgelens drift
 forgelens clean --yes
 forgelens prompt codex
 ```
 
-## Common usage
+## Developer Shortcuts
 
-```bash
-forgelens scan --root . --out .forgelens --format markdown --verbose
-forgelens doctor --root . --out .forgelens
-forgelens clean --root . --out .forgelens --yes
-forgelens prompt codex
+```text
+make check          Run typecheck, tests, build, and diff check
+make scan           Generate ForgeLens reports
+make baseline       Save current ForgeLens baseline
+make drift          Compare against saved baseline
+make site           Build Astro site
+make release-check  Run all release checks
 ```
 
-## Generated files
-
-Inside `.forgelens/`:
-
-- `FORGE_CONTEXT.md`
-- `ARCHITECTURE_MAP.md`
-- `ROUTES_MAP.md`
-- `DATABASE_MAP.md`
-- `SERVER_ACTIONS_MAP.md`
-- `SECURITY_RULES.md`
-- `RISK_REPORT.md`
-
-## Sample output (short)
-
-Example from `DATABASE_MAP.md`:
-
-```md
-## Detected Providers
-- prisma (confidence: high)
-  evidence: `prisma/schema.prisma`
-  notes: Prisma dependency and schema files
-```
+## Docs
 
-Example from `SECURITY_RULES.md`:
+- Astro product/docs app: [site/](site/)
+- Docs entry page source: [site/src/pages/docs/index.astro](site/src/pages/docs/index.astro)
+- MDX docs content: [site/src/content/docs/](site/src/content/docs/)
 
-```md
-## Auth providers/signals detected
-- nextauth-authjs (confidence: high)
-  evidence: `lib/auth.ts`
+Run docs locally:
 
-## Environment files (names only)
-- `.env.example`
-- `.env.local`
-```
-
-Example from `RISK_REPORT.md`:
-
-```md
-- Server actions detected (2): `app/admin/actions.ts`, `app/orders/actions.ts`. Verify auth and input validation.
-- API routes detected (1): `app/api/health/route.ts`. Verify auth and input validation.
+```bash
+pnpm site:dev
 ```
 
-## Example workflow with AI agents
-
-1. Run `forgelens scan` in your repo.
-2. Open generated `.forgelens/*.md` files.
-3. Paste `forgelens prompt codex` output into Codex (or equivalent prompt in Claude Code/Cursor/OpenCode).
-4. Ask agent to plan and edit with those context files first.
-
-## Safety promise
-
-- Source code is never modified by scan/doctor.
-- ForgeLens writes only in the selected output folder.
-- Env file names can be reported, but secret values are never printed.
-- No network/API calls are required for detection.
+Then open `http://127.0.0.1:4321/docs`.
 
-## Limitations
+## Safety Notes
 
-- Static analysis only; dynamic/runtime behavior is not executed.
-- Confidence is evidence-based, not guaranteed truth.
-- Custom frameworks and unusual repo layouts may require manual review.
+- Scan and doctor do not modify source files.
+- ForgeLens writes only inside the selected output folder (default `.forgelens/`).
+- Env report includes file names and key names only, never secret values.
+- Detection is static and deterministic; no runtime code execution.
 
-## Important warning
+## Limits
 
-ForgeLens is not a security audit and not a replacement for code review, AppSec review, or penetration testing.
+- This is static analysis, not a full semantic or runtime analyzer.
+- It is not a replacement for security review or penetration testing.