@redstone-md/mapr 0.0.1-alpha

package/LICENSE

@@ -0,0 +1,45 @@
+Mapr Closed Source-Available License
+
+Copyright (c) 2026 redstone-md
+All rights reserved.
+
+1. Grant of Limited Use
+
+Permission is granted to download, run, and use this software for personal, internal, evaluation, research, and contribution purposes only, subject to the conditions below.
+
+2. Restrictions
+
+You may not:
+
+- sell, sublicense, lease, distribute, publish, or commercially exploit this software or any derivative work;
+- offer this software as a hosted service or as part of a paid or revenue-generating product or service;
+- remove or alter copyright, attribution, or license notices;
+- claim this software or any substantial portion of it as your own work.
+
+3. Contribution-Only Modification Rights
+
+You may modify the software only for your own internal use or for the purpose of preparing contributions back to the original project repository or maintainer.
+
+You may not distribute modified versions, forks, or derivative works to any third party without prior written permission from the copyright holder.
+
+4. Contributions
+
+If you submit code, documentation, ideas, fixes, or other materials to the project, you grant the copyright holder a perpetual, worldwide, irrevocable, sublicensable, transferable, royalty-free right to use, copy, modify, distribute, relicense, and commercialize those contributions in any form.
+
+Unless explicitly agreed in writing, you receive no ownership interest in the project by contributing.
+
+5. No Trademark Rights
+
+This license does not grant any right to use project names, brands, or logos except as required for accurate attribution.
+
+6. Termination
+
+Any use of the software outside these terms automatically terminates the rights granted by this license.
+
+7. Warranty Disclaimer
+
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+8. Limitation of Liability
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS 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,109 @@
+# Mapr
+
+Mapr is a Bun-native CLI/TUI for reverse-engineering frontend websites and build outputs. It crawls a target site, downloads related code artifacts, formats them for readability, runs a communicating AI swarm over chunked artifact content, and produces a Markdown analysis report with entry points, initialization flow, inferred call graph edges, restored names, investigation tips, and artifact summaries.
+
+## What It Analyzes
+
+- HTML entry pages and linked same-origin pages
+- JavaScript bundles and imported chunks
+- Service workers and worker scripts
+- Stylesheets and manifests
+- Referenced WASM modules through binary summaries
+- Cross-linked website artifacts discovered from page code
+- Optional local lexical RAG for oversized artifacts such as multi-megabyte bundles
+
+## Runtime
+
+- Bun only
+- TypeScript in strict mode
+- Interactive terminal UX with `@clack/prompts`
+- AI analysis through Vercel AI SDK using OpenAI or OpenAI-compatible providers
+- Headless CLI mode for automation
+- Live swarm progress with agent-level tracking and progress bars
+
+## Workflow
+
+1. Load or configure AI provider settings from `~/.mapr/config.json`
+2. Discover models from the provider `/models` endpoint
+3. Let the user search and select a model, then save the model context size
+4. Crawl the target website and fetch related artifacts
+5. Format analyzable content where possible
+6. Optionally build a local lexical RAG index for oversized artifacts
+7. Run a communicating swarm of analysis agents over chunked artifact content
+8. Generate a Markdown report in the current working directory
+
+## Quick Start
+
+```bash
+bun install
+bun run index.ts
+```
+
+If the package is published and Bun is installed locally:
+
+```bash
+npx @redstone-md/mapr --help
+```
+
+## Headless Examples
+
+```bash
+npx @redstone-md/mapr \
+  --headless \
+  --url http://localhost:5178 \
+  --provider-type openai-compatible \
+  --provider-name "Local vLLM" \
+  --api-key secret \
+  --base-url http://localhost:8000/v1 \
+  --model qwen2.5-coder \
+  --context-size 512000 \
+  --local-rag
+```
+
+```bash
+npx @redstone-md/mapr --list-models --headless --provider-type openai-compatible --api-key secret --base-url http://localhost:8000/v1
+```
+
+## Swarm Design
+
+Mapr uses a communicating agent swarm per chunk:
+
+- `scout`: maps artifact surface area and runtime clues
+- `runtime`: reconstructs initialization flow and call relationships
+- `naming`: restores variable and function names from context
+- `security`: identifies risks, persistence, caching, and operator tips
+- `synthesizer`: merges the upstream notes into the final chunk analysis
+
+Progress is shown as a task progress bar plus agent/chunk status updates.
+
+## Large Bundle Handling
+
+- Mapr stores the selected model context size and derives a larger chunk budget from it.
+- Optional `--local-rag` mode builds a local lexical retrieval index so very large artifacts such as 5 MB bundles can feed more relevant sibling segments into the swarm without forcing the whole file into one prompt.
+- Formatting no longer has a hard artifact-size cutoff. If formatting fails, Mapr falls back to raw content instead of skipping by size.
+
+## Output
+
+Each run writes a file named like:
+
+```text
+report-example.com-2026-03-15T12-34-56-789Z.md
+```
+
+## Disclaimer
+
+- Mapr produces assisted reverse-engineering output, not a formal proof of program behavior.
+- AI-generated call graphs, renamed symbols, summaries, and tips are inference-based and may be incomplete or wrong.
+- Website analysis may include proprietary or sensitive code. Use Mapr only when you are authorized to inspect the target.
+- WASM support is summary-based unless you extend the project with deeper binary lifting or disassembly.
+
+## Contribution Terms
+
+- This project is source-available and closed-license, not open source.
+- Contributions are accepted only under the repository owner’s terms.
+- By submitting a contribution, you agree that the maintainer may use, modify, relicense, and redistribute your contribution as part of Mapr without compensation.
+- Do not submit code unless you have the rights to contribute it.
+
+## License
+
+Use of this project is governed by the custom license in [LICENSE](./LICENSE).

package/bin/mapr

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../index.ts";

package/index.ts

@@ -0,0 +1,247 @@
+#!/usr/bin/env bun
+
+import { cancel, confirm, intro, isCancel, log, outro, spinner, text } from "@clack/prompts";
+import pc from "picocolors";
+import packageJson from "./package.json";
+
+import { AiBundleAnalyzer, PartialAnalysisError, buildAnalysisSnapshot, chunkTextByBytes, deriveChunkSizeBytes } from "./lib/ai-analyzer";
+import { parseCliArgs, getConfigOverrides, renderHelpText } from "./lib/cli-args";
+import { ConfigManager } from "./lib/config";
+import { BundleFormatter } from "./lib/formatter";
+import { renderProgressBar } from "./lib/progress";
+import { ReportWriter } from "./lib/reporter";
+import { BundleScraper } from "./lib/scraper";
+import { SWARM_AGENT_ORDER } from "./lib/swarm-prompts";
+
+function exitIfCancelled<T>(value: T): T {
+  if (isCancel(value)) {
+    cancel("Operation cancelled.");
+    process.exit(0);
+  }
+
+  return value;
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : "An unknown error occurred.";
+}
+
+function formatAnalysisProgress(completed: number, total: number, message: string): string {
+  return `${renderProgressBar(completed, total)} ${message}`;
+}
+
+async function resolveTargetUrl(headless: boolean, prefilledUrl?: string): Promise<string> {
+  if (prefilledUrl) {
+    return prefilledUrl;
+  }
+
+  if (headless) {
+    throw new Error("Headless mode requires --url.");
+  }
+
+  return String(
+    exitIfCancelled(
+      await text({
+        message: "Target URL to analyze",
+        placeholder: "http://localhost:5173 or https://example.com",
+        validate(value) {
+          if (!value) {
+            return "Enter a valid URL.";
+          }
+
+          try {
+            const parsed = new URL(value);
+            return /^https?:$/.test(parsed.protocol) ? undefined : "URL must start with http:// or https://.";
+          } catch {
+            return "Enter a valid URL.";
+          }
+        },
+      }),
+    ),
+  );
+}
+
+async function run(): Promise<void> {
+  const args = parseCliArgs(process.argv.slice(2));
+
+  if (args.help) {
+    console.log(renderHelpText());
+    return;
+  }
+
+  if (args.version) {
+    console.log(packageJson.version);
+    return;
+  }
+
+  const headless = args.headless;
+  if (!headless) {
+    intro(`${pc.bgCyan(pc.black(" mapr "))} ${pc.bold("Website reverse-engineering for Bun")}`);
+  }
+
+  const configManager = new ConfigManager();
+  const configOverrides = getConfigOverrides(args);
+  const existingConfig = await configManager.readConfig();
+  let forceReconfigure = args.reconfigure;
+
+  if (!headless && existingConfig && !args.reconfigure && Object.keys(configOverrides).length === 0) {
+    forceReconfigure = Boolean(
+      exitIfCancelled(
+        await confirm({
+          message: `Reconfigure AI provider? Current: ${existingConfig.providerName} / ${existingConfig.model}`,
+          active: "Reconfigure",
+          inactive: "Keep saved config",
+          initialValue: false,
+        }),
+      ),
+    );
+  }
+
+  if (args.listModels) {
+    const models = await configManager.listModels(await configManager.resolveConfigDraft(configOverrides));
+    console.log(models.join("\n"));
+    return;
+  }
+
+  const config = await configManager.ensureConfig({
+    forceReconfigure,
+    headless,
+    overrides: configOverrides,
+  });
+
+  const targetUrl = await resolveTargetUrl(headless, args.url);
+
+  const scrapeStep = spinner({ indicator: "timer" });
+  scrapeStep.start("Crawling HTML, scripts, service workers, WASM, and related website artifacts");
+  const scraper = new BundleScraper(fetch, {
+    maxPages: args.maxPages,
+    maxArtifacts: args.maxArtifacts,
+  });
+  const scrapeResult = await scraper.scrape(targetUrl);
+  scrapeStep.stop(
+    `Discovered ${scrapeResult.artifacts.length} artifact(s) across ${scrapeResult.htmlPages.length} page(s)`,
+  );
+
+  const formatStep = spinner({ indicator: "timer" });
+  formatStep.start("Formatting downloaded artifacts for analysis");
+  const formatter = new BundleFormatter();
+  const formattedArtifacts = await formatter.formatArtifacts(scrapeResult.artifacts);
+  const skippedCount = formattedArtifacts.filter((artifact) => artifact.formattingSkipped).length;
+  formatStep.stop(
+    skippedCount > 0
+      ? `Prepared ${formattedArtifacts.length} artifact(s); formatting fallback used for ${skippedCount} item(s)`
+      : `Prepared ${formattedArtifacts.length} artifact(s) for analysis`,
+  );
+
+  const totalChunks = formattedArtifacts.reduce(
+    (sum, artifact) =>
+      sum + chunkTextByBytes(artifact.formattedContent || artifact.content, deriveChunkSizeBytes(config.modelContextSize)).length,
+    0,
+  );
+  const totalAgentTasks = Math.max(1, totalChunks * SWARM_AGENT_ORDER.length);
+  let completedAgentTasks = 0;
+
+  const analysisStep = spinner({ indicator: "timer" });
+  analysisStep.start(formatAnalysisProgress(0, totalAgentTasks, "Starting swarm analysis"));
+
+  const analyzer = new AiBundleAnalyzer({
+    providerConfig: config,
+    localRag: args.localRag,
+    onProgress(event) {
+      if (event.stage === "agent" && event.state === "completed") {
+        completedAgentTasks += 1;
+      }
+
+      const progressLine = formatAnalysisProgress(completedAgentTasks, totalAgentTasks, event.message);
+      analysisStep.message(progressLine);
+
+      if (args.verboseAgents && event.stage === "agent" && event.state === "completed") {
+        log.step(progressLine);
+      }
+    },
+  });
+
+  let analysisError: string | undefined;
+  let partialReport = false;
+  let analysis = await (async () => {
+    try {
+      const completedAnalysis = await analyzer.analyze({
+        pageUrl: scrapeResult.pageUrl,
+        artifacts: formattedArtifacts,
+      });
+
+      analysisStep.stop(
+        formatAnalysisProgress(
+          totalAgentTasks,
+          totalAgentTasks,
+          `Analyzed ${completedAnalysis.analyzedChunkCount} chunk(s) across ${formattedArtifacts.length} artifact(s)`,
+        ),
+      );
+
+      return completedAnalysis;
+    } catch (error) {
+      analysisError = formatError(error);
+      partialReport = true;
+      analysisStep.error(formatAnalysisProgress(completedAgentTasks, totalAgentTasks, `Analysis interrupted: ${analysisError}`));
+
+      if (error instanceof PartialAnalysisError) {
+        return error.partialAnalysis;
+      }
+
+      return buildAnalysisSnapshot({
+        overview: `Partial report only. Analysis failed before completion: ${analysisError}`,
+      });
+    }
+  })();
+  const reportStatus: "complete" | "partial" = partialReport ? "partial" : "complete";
+
+  const reportStep = spinner({ indicator: "timer" });
+  reportStep.start(reportStatus === "partial" ? "Writing partial Markdown report after analysis error" : "Generating Markdown report");
+  const reportWriter = new ReportWriter();
+  const reportPath = await reportWriter.writeReport({
+    targetUrl: scrapeResult.pageUrl,
+    htmlPages: scrapeResult.htmlPages,
+    reportStatus,
+    ...(analysisError !== undefined ? { analysisError } : {}),
+    artifacts: formattedArtifacts,
+    analysis,
+    ...(args.output !== undefined ? { outputPathOverride: args.output } : {}),
+  });
+  reportStep.stop(reportStatus === "partial" ? "Partial report written to disk" : "Report written to disk");
+
+  const summaryLines = [
+    reportStatus === "partial" ? `${pc.yellow("Analysis incomplete.")}` : `${pc.green("Analysis complete.")}`,
+    `${pc.bold("Status:")} ${reportStatus === "partial" ? "partial report saved after error" : "complete"}`,
+    `${pc.bold("Target:")} ${scrapeResult.pageUrl}`,
+    `${pc.bold("Provider:")} ${config.providerName} (${config.model})`,
+    `${pc.bold("Context size:")} ${config.modelContextSize.toLocaleString()} tokens`,
+    `${pc.bold("Local RAG:")} ${args.localRag ? "enabled" : "disabled"}`,
+    `${pc.bold("Pages:")} ${scrapeResult.htmlPages.length}`,
+    `${pc.bold("Artifacts:")} ${formattedArtifacts.length}`,
+    `${pc.bold("Chunks analyzed:")} ${analysis.analyzedChunkCount}`,
+    ...(analysisError !== undefined ? [`${pc.bold("Analysis error:")} ${analysisError}`] : []),
+    `${pc.bold("Report:")} ${pc.underline(reportPath)}`,
+  ].join("\n");
+
+  if (headless) {
+    if (reportStatus === "partial") {
+      log.error(summaryLines);
+      process.exit(1);
+    }
+
+    log.success(summaryLines);
+    return;
+  }
+
+  if (reportStatus === "partial") {
+    cancel(summaryLines);
+    process.exit(1);
+  }
+
+  outro(summaryLines);
+}
+
+run().catch((error) => {
+  cancel(pc.red(formatError(error)));
+  process.exit(1);
+});