forgelens 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 - 2026-05-18
+
+Initial CLI MVP release-readiness baseline.
+
+### Added
+
+- `forgelens scan` command to generate 7 context Markdown files.
+- `forgelens doctor` command for read-only safety/readiness checks.
+- `forgelens clean` command with deletion safety guards and confirmation.
+- `forgelens prompt codex` command for copy-ready Codex context prompt.
+
+### Detection model
+
+- Provider-agnostic signal detection for auth and database layers.
+- Evidence + confidence model (`high`, `medium`, `low`).
+- Unknown/custom fallbacks when signal strength is weak.
+
+### Safety notes
+
+- Source files are not modified by scan/doctor.
+- Output is scoped to selected output folder.
+- Env file names only; secrets are not printed.
+- Static analysis only; not a security audit.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeLens contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software 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 Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# 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
+
+## Install
+
+ForgeLens is not published to npm yet. After npm release, install with:
+
+```bash
+npm install -g forgelens
+```
+
+After npm release, use without global install:
+
+```bash
+npx forgelens scan
+```
+
+Local development usage:
+
+```bash
+pnpm install
+pnpm build
+pnpm link --global
+forgelens scan
+```
+
+## CLI commands
+
+```bash
+forgelens scan
+forgelens doctor
+forgelens clean --yes
+forgelens prompt codex
+```
+
+## Common usage
+
+```bash
+forgelens scan --root . --out .forgelens --format markdown --verbose
+forgelens doctor --root . --out .forgelens
+forgelens clean --root . --out .forgelens --yes
+forgelens prompt codex
+```
+
+## 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
+```
+
+Example from `SECURITY_RULES.md`:
+
+```md
+## Auth providers/signals detected
+- nextauth-authjs (confidence: high)
+  evidence: `lib/auth.ts`
+
+## 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.
+```
+
+## 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.
+
+## Limitations
+
+- 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.
+
+## Important warning
+
+ForgeLens is not a security audit and not a replacement for code review, AppSec review, or penetration testing.