@flaid/devmap 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Fadil
+
+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,168 @@
+# DevMap
+
+Understand any codebase in minutes, not days.
+
+DevMap is a CLI that combines static analysis with optional AI-powered
+interpretation. It maps project structure and generates reusable context
+without sending an entire repository to an AI model.
+
+Version `0.2.0` classifies full workspaces (multiple project types at once),
+centralizes detection vocabulary, and ships `map`, `flow`, and `explain`.
+
+## Install
+
+```bash
+npm install --global @flaid/devmap
+```
+
+Or run without a global install:
+
+```bash
+npx @flaid/devmap --help
+```
+
+## Requirements
+
+- Node.js 22.12 or newer
+- A Groq or OpenRouter API key for AI-powered analysis and answers
+
+Static analysis still works when AI is not configured.
+
+## Quick Start
+
+Run these commands from the root of the project you want to understand:
+
+```bash
+devmap init
+devmap analyze
+devmap onboarding
+devmap doctor
+```
+
+`devmap init` selects a provider, validates its key, stores configuration locally, prepares
+`.devmap/`, generates `DEVMAP.md`, and integrates with `AGENTS.md` safely.
+
+## AI Provider Setup
+
+Choose Groq or OpenRouter with the arrow keys during:
+
+```bash
+devmap init
+```
+
+Groq keys are available at https://console.groq.com/keys. OpenRouter keys are
+available at https://openrouter.ai/keys.
+
+For OpenRouter, DevMap prompts:
+
+```txt
+OpenRouter model [openrouter/free]:
+```
+
+Press Enter to use the free router, or type any free or paid OpenRouter model
+ID. The selected model is saved and used as the primary choice.
+
+For non-interactive Groq setup:
+
+```bash
+GROQ_API_KEY="your-key" devmap init
+```
+
+On PowerShell:
+
+```powershell
+$env:GROQ_API_KEY="your-key"
+devmap init
+Remove-Item Env:GROQ_API_KEY
+```
+
+For non-interactive OpenRouter setup:
+
+```bash
+OPENROUTER_API_KEY="your-key" devmap init
+```
+
+The key is stored locally in `~/.devmap/config.json`. Requests go directly from
+your machine to the selected provider. DevMap does not send the key to a
+DevMap-owned server.
+
+## Commands
+
+```bash
+devmap init
+devmap analyze
+devmap analyze --fresh
+devmap map                    # full project map
+devmap map <feature-or-file>  # scoped to one feature or file
+devmap flow                   # curated top flows
+devmap flow <feature-or-route>
+devmap explain <target>       # file, feature, or function
+devmap onboarding --write
+devmap onboarding --write --language id
+devmap doctor
+devmap config model auto
+```
+
+Groq and OpenRouter use the model selected during init. Change either
+provider's model with:
+
+```bash
+devmap config model <model-id>
+devmap config model auto
+```
+
+## Generated Context
+
+DevMap generates:
+
+- `.devmap/index.json` for lightweight AI-agent navigation
+- `.devmap/features/*.json` for focused feature maps and source priority
+- `.devmap/snapshot.json` for the full structured project analysis archive
+- `DEVMAP.md` for human and AI-agent usage guidance
+- a small DevMap block in `AGENTS.md` only after confirmation when the file
+  already exists
+
+Existing `AGENTS.md` and `DEVMAP.md` files are never overwritten.
+
+## For AI Agents
+
+Read `.devmap/index.json` first, open the relevant feature map, and inspect its
+`sourcePriority` files. Use `.devmap/snapshot.json` only when the lightweight
+navigation layer is insufficient.
+
+Use `--json` for scripts, editors, CI, or AI agents:
+
+```bash
+devmap analyze --json
+devmap onboarding --json
+devmap doctor --json
+```
+
+JSON mode writes one parseable JSON document to stdout without ANSI colors,
+terminal decoration, or streamed partial output.
+
+## Supported Stacks
+
+- Frontend: Next.js, Astro, SvelteKit, Nuxt, React, Vue, Svelte
+- Backend: Express, NestJS, Fastify, Koa
+
+Detection covers the full list above; Next.js and Express receive the deepest
+analysis. Multi-package workspaces are classified per project type, so a
+monorepo containing a CLI and a web app is reported as both.
+
+## Privacy
+
+- Project analysis runs locally before AI interpretation.
+- Full repository source is not sent to the selected provider.
+- `.env` files and common generated directories are ignored.
+- API keys are stored locally and should never be committed.
+
+## Links
+
+- Repository: https://github.com/itsflaid/devmap
+- Issues: https://github.com/itsflaid/devmap/issues
+- Changelog: https://github.com/itsflaid/devmap/blob/main/CHANGELOG.md
+
+## License
+
+MIT

package/dist/ai/completion.d.ts

@@ -0,0 +1,7 @@
+import type { AiClient, AiCompletionRequest, AiCompletionResult } from "./types.js";
+export type AiCompletionExecution = {
+    result: AiCompletionResult;
+    streamed: boolean;
+};
+export declare function completeWithOptionalStreaming(client: AiClient, request: AiCompletionRequest, enabled: boolean, onStreamStart?: () => void): Promise<AiCompletionExecution>;
+//# sourceMappingURL=completion.d.ts.map

package/dist/ai/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/ai/completion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,QAAQ,EACR,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,MAAM,IAAI,GACzB,OAAO,CAAC,qBAAqB,CAAC,CAwBhC"}

package/dist/ai/completion.js

@@ -0,0 +1,27 @@
+import { output } from "../utils/output.js";
+export async function completeWithOptionalStreaming(client, request, enabled, onStreamStart) {
+    if (!enabled || !client.stream) {
+        return {
+            result: await client.complete(request),
+            streamed: false
+        };
+    }
+    const renderer = output.markdownStream();
+    let started = false;
+    try {
+        const result = await client.stream(request, (delta) => {
+            if (!started) {
+                onStreamStart?.();
+                started = true;
+            }
+            renderer.write(delta);
+        });
+        renderer.end();
+        return { result, streamed: true };
+    }
+    catch (error) {
+        renderer.end();
+        throw error;
+    }
+}
+//# sourceMappingURL=completion.js.map

package/dist/ai/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../src/ai/completion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAY5C,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,MAAgB,EAChB,OAA4B,EAC5B,OAAgB,EAChB,aAA0B;IAE1B,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/B,OAAO;YACL,MAAM,EAAE,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;YACtC,QAAQ,EAAE,KAAK;SAChB,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,EAAE,CAAC;IACzC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACpD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,aAAa,EAAE,EAAE,CAAC;gBAClB,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;YACD,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,GAAG,EAAE,CAAC;QACf,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,QAAQ,CAAC,GAAG,EAAE,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/ai/contextBuilder.d.ts

@@ -0,0 +1,42 @@
+import type { ProjectMap } from "../analyzers/pipeline/index.js";
+declare const INTENT_TERMS: {
+    readonly add_feature: Set<string>;
+    readonly change: Set<string>;
+    readonly debug: Set<string>;
+    readonly explain: Set<string>;
+    readonly navigate: Set<string>;
+};
+export type ContextBuilderOptions = {
+    maxFiles?: number;
+    maxLinesPerFile?: number;
+    expandedTerms?: string[];
+};
+export type ContextFile = {
+    path: string;
+    score: number;
+    reasons: string[];
+    exports: string[];
+    topFunctions: Array<Record<string, unknown>>;
+    purpose?: string;
+    startLine: number;
+    endLine: number;
+    truncated: boolean;
+    content: string;
+};
+export type QuestionContext = {
+    question: string;
+    intent: QueryIntent;
+    keywords: string[];
+    expandedTerms: string[];
+    confidence: RelevanceConfidence;
+    topScore: number;
+    relevantFiles: ContextFile[];
+    files: ContextFile[];
+};
+export type QueryIntent = keyof typeof INTENT_TERMS | "general";
+export type RelevanceConfidence = "high" | "medium" | "low";
+export declare function buildQuestionContext(projectRoot: string, snapshot: ProjectMap, question: string, options?: ContextBuilderOptions): Promise<QuestionContext>;
+export declare function extractContextKeywords(question: string): string[];
+export declare function normalizeExpandedTerms(terms: string[], keywords?: string[]): string[];
+export {};
+//# sourceMappingURL=contextBuilder.d.ts.map

package/dist/ai/contextBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextBuilder.d.ts","sourceRoot":"","sources":["../../src/ai/contextBuilder.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAuDjE,QAAA,MAAM,YAAY;;;;;;CAMR,CAAC;AA2EX,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,mBAAmB,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,GAAG,SAAS,CAAC;AAChE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AA0C5D,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,CAAC,CAwD1B;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBjE;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,GAAE,MAAM,EAAO,GACtB,MAAM,EAAE,CAgCV"}