@redstone-md/mapr 0.0.1-alpha

package/lib/reporter.ts

@@ -0,0 +1,213 @@
+import { writeFile } from "fs/promises";
+import { resolve } from "path";
+import { z } from "zod";
+
+import { artifactTypeSchema } from "./artifacts";
+import type { BundleAnalysis } from "./ai-analyzer";
+import type { FormattedArtifact } from "./formatter";
+
+const reportInputSchema = z.object({
+  targetUrl: z.string().url(),
+  htmlPages: z.array(z.string().url()),
+  reportStatus: z.enum(["complete", "partial"]).default("complete"),
+  analysisError: z.string().min(1).optional(),
+  artifacts: z.array(
+    z.object({
+      url: z.string().url(),
+      type: artifactTypeSchema,
+      content: z.string(),
+      formattedContent: z.string(),
+      sizeBytes: z.number().int().nonnegative(),
+      discoveredFrom: z.string().min(1),
+      formattingSkipped: z.boolean(),
+      formattingNote: z.string().optional(),
+    }),
+  ),
+  analysis: z.object({
+    overview: z.string(),
+    entryPoints: z.array(
+      z.object({
+        symbol: z.string(),
+        description: z.string(),
+        evidence: z.string(),
+      }),
+    ),
+    initializationFlow: z.array(z.string()),
+    callGraph: z.array(
+      z.object({
+        caller: z.string(),
+        callee: z.string(),
+        rationale: z.string(),
+      }),
+    ),
+    restoredNames: z.array(
+      z.object({
+        originalName: z.string(),
+        suggestedName: z.string(),
+        justification: z.string(),
+      }),
+    ),
+    notableLibraries: z.array(z.string()),
+    investigationTips: z.array(z.string()),
+    risks: z.array(z.string()),
+    artifactSummaries: z.array(
+      z.object({
+        url: z.string().url(),
+        type: artifactTypeSchema,
+        chunkCount: z.number().int().nonnegative(),
+        summary: z.string(),
+      }),
+    ),
+    analyzedChunkCount: z.number().int().nonnegative(),
+  }),
+});
+
+type ReportInput = z.infer<typeof reportInputSchema>;
+
+function formatBulletList(items: string[], emptyState: string): string {
+  return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : `- ${emptyState}`;
+}
+
+function formatArtifactTable(artifacts: FormattedArtifact[]): string {
+  if (artifacts.length === 0) {
+    return "_No artifacts were downloaded._";
+  }
+
+  const lines = [
+    "| Artifact URL | Type | Size (bytes) | Discovered From | Formatting | Note |",
+    "| --- | --- | ---: | --- | --- | --- |",
+  ];
+
+  for (const artifact of artifacts) {
+    lines.push(
+      `| ${artifact.url} | ${artifact.type} | ${artifact.sizeBytes} | ${artifact.discoveredFrom} | ${
+        artifact.formattingSkipped ? "Skipped" : "Applied"
+      } | ${artifact.formattingNote ?? "None"} |`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export class ReportWriter {
+  public generateMarkdown(input: ReportInput): string {
+    const report = reportInputSchema.parse(input);
+
+    const entryPointsSection =
+      report.analysis.entryPoints.length > 0
+        ? report.analysis.entryPoints
+            .map((entryPoint) => `- \`${entryPoint.symbol}\`: ${entryPoint.description} Evidence: ${entryPoint.evidence}`)
+            .join("\n")
+        : "- None identified";
+
+    const callGraphSection =
+      report.analysis.callGraph.length > 0
+        ? report.analysis.callGraph
+            .map((edge) => `- \`${edge.caller}\` -> \`${edge.callee}\`: ${edge.rationale}`)
+            .join("\n")
+        : "- No clear call edges extracted";
+
+    const restoredNamesSection =
+      report.analysis.restoredNames.length > 0
+        ? report.analysis.restoredNames
+            .map((entry) => `- \`${entry.originalName}\` -> \`${entry.suggestedName}\`: ${entry.justification}`)
+            .join("\n")
+        : "- No confident renames proposed";
+
+    const artifactSummarySection =
+      report.analysis.artifactSummaries.length > 0
+        ? report.analysis.artifactSummaries
+            .map(
+              (summary) =>
+                `- ${summary.url} [${summary.type}] (${summary.chunkCount} chunk(s)): ${summary.summary}`,
+            )
+            .join("\n")
+        : "- None";
+
+    return [
+      "# Mapr Reverse-Engineering Report",
+      "",
+      `- Target URL: ${report.targetUrl}`,
+      `- Generated: ${new Date().toISOString()}`,
+      `- Report status: ${report.reportStatus}`,
+      `- HTML pages crawled: ${report.htmlPages.length}`,
+      `- Artifacts analyzed: ${report.artifacts.length}`,
+      `- AI chunks analyzed: ${report.analysis.analyzedChunkCount}`,
+      "",
+      report.analysisError ? "## Analysis Status" : undefined,
+      report.analysisError ? `- Analysis ended early: ${report.analysisError}` : undefined,
+      report.analysisError ? "" : undefined,
+      "## Website Surface",
+      "",
+      formatBulletList(report.htmlPages, "No HTML pages crawled beyond the entry page"),
+      "",
+      "## Executive Summary",
+      "",
+      report.analysis.overview,
+      "",
+      "## Entry Points",
+      "",
+      entryPointsSection,
+      "",
+      "## Initialization Flow",
+      "",
+      formatBulletList(report.analysis.initializationFlow, "No initialization flow extracted"),
+      "",
+      "## Call Graph",
+      "",
+      callGraphSection,
+      "",
+      "## Restored Names",
+      "",
+      restoredNamesSection,
+      "",
+      "## Notable Libraries",
+      "",
+      formatBulletList(report.analysis.notableLibraries, "No notable libraries identified"),
+      "",
+      "## Investigation Tips",
+      "",
+      formatBulletList(report.analysis.investigationTips, "No investigation tips generated"),
+      "",
+      "## Risks And Observations",
+      "",
+      formatBulletList(report.analysis.risks, "No specific risks highlighted"),
+      "",
+      "## Artifact Summaries",
+      "",
+      artifactSummarySection,
+      "",
+      "## Downloaded Artifacts",
+      "",
+      formatArtifactTable(report.artifacts),
+    ]
+      .filter((line): line is string => line !== undefined)
+      .join("\n");
+  }
+
+  public async writeReport(input: {
+    targetUrl: string;
+    htmlPages: string[];
+    reportStatus?: "complete" | "partial";
+    analysisError?: string;
+    artifacts: FormattedArtifact[];
+    analysis: BundleAnalysis;
+    outputPathOverride?: string;
+  }): Promise<string> {
+    const { outputPathOverride, ...reportInput } = input;
+    const validatedInput = reportInputSchema.parse(reportInput);
+    const reportContent = this.generateMarkdown(validatedInput);
+    const outputPath =
+      outputPathOverride !== undefined
+        ? resolve(process.cwd(), outputPathOverride)
+        : resolve(
+            process.cwd(),
+            `report-${new URL(validatedInput.targetUrl).hostname.replace(/[^a-zA-Z0-9.-]/g, "-")}-${new Date()
+              .toISOString()
+              .replace(/[:.]/g, "-")}.md`,
+          );
+
+    await writeFile(outputPath, `${reportContent}\n`, "utf8");
+    return outputPath;
+  }
+}

package/lib/scraper.ts

@@ -0,0 +1,169 @@
+import { Buffer } from "buffer";
+import { z } from "zod";
+
+import {
+  artifactCandidateSchema,
+  discoveredArtifactSchema,
+  extractArtifactCandidates,
+  extractNestedCandidates,
+  type ArtifactCandidate,
+  type DiscoveredArtifact,
+} from "./artifacts";
+import { WasmModuleSummarizer } from "./wasm";
+
+const httpUrlSchema = z
+  .string()
+  .trim()
+  .url("Expected a valid URL.")
+  .refine((value) => /^https?:\/\//.test(value), "Expected an http or https URL.");
+
+const scraperOptionsSchema = z.object({
+  maxPages: z.number().int().positive().default(10),
+  maxArtifacts: z.number().int().positive().default(200),
+});
+
+export interface ScrapeResult {
+  pageUrl: string;
+  artifacts: DiscoveredArtifact[];
+  htmlPages: string[];
+  scriptUrls: string[];
+}
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type ScraperOptions = z.input<typeof scraperOptionsSchema>;
+
+function isPageCandidate(candidate: ArtifactCandidate, rootOrigin: string): boolean {
+  return candidate.type === "html" && new URL(candidate.url).origin === rootOrigin;
+}
+
+function shouldFollowCandidate(candidate: ArtifactCandidate, rootOrigin: string): boolean {
+  if (candidate.type === "html") {
+    return new URL(candidate.url).origin === rootOrigin;
+  }
+
+  return true;
+}
+
+export class BundleScraper {
+  private readonly options: z.infer<typeof scraperOptionsSchema>;
+  private readonly wasmSummarizer = new WasmModuleSummarizer();
+
+  public constructor(
+    private readonly fetcher: FetchLike = fetch,
+    options: ScraperOptions = {},
+  ) {
+    this.options = scraperOptionsSchema.parse(options);
+  }
+
+  public async scrape(pageUrl: string): Promise<ScrapeResult> {
+    const validatedPageUrl = httpUrlSchema.parse(pageUrl);
+    const rootOrigin = new URL(validatedPageUrl).origin;
+    const visitedUrls = new Set<string>();
+    const htmlPages = new Set<string>();
+    const artifacts: DiscoveredArtifact[] = [];
+    const queue: ArtifactCandidate[] = [
+      artifactCandidateSchema.parse({
+        url: validatedPageUrl,
+        type: "html",
+        discoveredFrom: "root",
+      }),
+    ];
+
+    while (queue.length > 0) {
+      if (artifacts.length >= this.options.maxArtifacts) {
+        break;
+      }
+
+      const candidate = queue.shift();
+      if (!candidate || visitedUrls.has(candidate.url)) {
+        continue;
+      }
+
+      if (!shouldFollowCandidate(candidate, rootOrigin)) {
+        continue;
+      }
+
+      if (isPageCandidate(candidate, rootOrigin) && htmlPages.size >= this.options.maxPages && candidate.url !== validatedPageUrl) {
+        continue;
+      }
+
+      visitedUrls.add(candidate.url);
+      const artifact = await this.fetchArtifact(candidate);
+      artifacts.push(artifact);
+
+      if (artifact.type === "html") {
+        htmlPages.add(artifact.url);
+      }
+
+      const nestedCandidates = extractNestedCandidates(artifact);
+      for (const nestedCandidate of nestedCandidates) {
+        if (!visitedUrls.has(nestedCandidate.url)) {
+          queue.push(nestedCandidate);
+        }
+      }
+    }
+
+    return {
+      pageUrl: validatedPageUrl,
+      artifacts,
+      htmlPages: [...htmlPages],
+      scriptUrls: artifacts
+        .filter((artifact) => artifact.type === "script" || artifact.type === "service-worker" || artifact.type === "worker")
+        .map((artifact) => artifact.url),
+    };
+  }
+
+  private async fetchArtifact(candidate: ArtifactCandidate): Promise<DiscoveredArtifact> {
+    const response = await this.fetchResponse(candidate.url, candidate.type);
+    const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+
+    if (candidate.type === "wasm" || contentType.includes("application/wasm")) {
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      return discoveredArtifactSchema.parse({
+        url: candidate.url,
+        type: "wasm",
+        sizeBytes: bytes.byteLength,
+        content: this.wasmSummarizer.summarize({
+          url: candidate.url,
+          bytes,
+        }),
+        discoveredFrom: candidate.discoveredFrom,
+      });
+    }
+
+    const content = await response.text();
+    const resolvedType = contentType.includes("text/html") ? "html" : candidate.type;
+
+    return discoveredArtifactSchema.parse({
+      url: candidate.url,
+      type: resolvedType,
+      sizeBytes: Buffer.byteLength(content, "utf8"),
+      content,
+      discoveredFrom: candidate.discoveredFrom,
+    });
+  }
+
+  private async fetchResponse(url: string, artifactType: ArtifactCandidate["type"]): Promise<Response> {
+    try {
+      const response = await this.fetcher(url, {
+        headers: {
+          "user-agent": "mapr/0.2.0",
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch ${artifactType} from ${url}: ${response.status} ${response.statusText}`);
+      }
+
+      return response;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Unable to fetch ${artifactType} artifact ${url}: ${error.message}`);
+      }
+
+      throw new Error(`Unable to fetch ${artifactType} artifact ${url}.`);
+    }
+  }
+}
+
+export { extractArtifactCandidates };

package/lib/swarm-prompts.ts

@@ -0,0 +1,56 @@
+export const SWARM_AGENT_ORDER = ["scout", "runtime", "naming", "security", "synthesizer"] as const;
+
+export type SwarmAgentName = (typeof SWARM_AGENT_ORDER)[number];
+
+const GLOBAL_MISSION = [
+  "You are part of a senior reverse-engineering swarm focused on frontend delivery artifacts.",
+  "The target may contain minified JavaScript, Vite bundles, service workers, HTML shells, CSS assets, manifests, and WASM summaries.",
+  "Your job is to maximize signal, preserve uncertainty honestly, and infer execution flow with evidence instead of speculation.",
+  "Prefer concrete names, control-flow observations, runtime triggers, network boundaries, storage usage, background execution, and operator-facing investigation tips.",
+  "If code is obfuscated or incomplete, say so explicitly and still extract the strongest defensible conclusions.",
+].join(" ");
+
+export function getGlobalMissionPrompt(): string {
+  return GLOBAL_MISSION;
+}
+
+export function getSwarmAgentPrompt(agent: SwarmAgentName): string {
+  switch (agent) {
+    case "scout":
+      return [
+        GLOBAL_MISSION,
+        "You are the Scout agent.",
+        "Map the surface area of this artifact chunk.",
+        "Identify frameworks, runtime boundaries, imports, exported symbols, bootstrapping clues, worker registration, fetch calls, DOM hooks, storage access, cache usage, and suspected cross-artifact relationships.",
+        "Provide concise notes that other agents can build on.",
+      ].join(" ");
+    case "runtime":
+      return [
+        GLOBAL_MISSION,
+        "You are the Runtime Flow agent.",
+        "Infer initialization order, triggers, lifecycle transitions, event wiring, entry points, and probable call relationships.",
+        "Use prior swarm notes as hard context and add only evidence-backed execution reasoning.",
+      ].join(" ");
+    case "naming":
+      return [
+        GLOBAL_MISSION,
+        "You are the Semantic Naming agent.",
+        "Restore better names for opaque variables, functions, classes, and modules.",
+        "Anchor every rename suggestion in context, data flow, side effects, or call usage.",
+      ].join(" ");
+    case "security":
+      return [
+        GLOBAL_MISSION,
+        "You are the Security and Operations agent.",
+        "Look for service worker risks, caching behavior, persistence, auth/session touchpoints, feature flags, telemetry, dynamic code loading, and WASM trust boundaries.",
+        "Output practical investigation tips that a human engineer should follow next.",
+      ].join(" ");
+    case "synthesizer":
+      return [
+        GLOBAL_MISSION,
+        "You are the Synthesizer agent.",
+        "Merge all upstream swarm notes into a single precise chunk analysis object.",
+        "De-duplicate findings, preserve uncertainty, and optimize for a human reverse-engineer who needs a ready-to-use technical map.",
+      ].join(" ");
+  }
+}

package/lib/wasm.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+const wasmInputSchema = z.object({
+  url: z.string().url(),
+  bytes: z.instanceof(Uint8Array),
+});
+
+function extractPrintableStrings(bytes: Uint8Array): string[] {
+  const matches = new Set<string>();
+  let current = "";
+
+  for (const byte of bytes) {
+    if (byte >= 32 && byte <= 126) {
+      current += String.fromCharCode(byte);
+      continue;
+    }
+
+    if (current.length >= 4) {
+      matches.add(current);
+    }
+
+    current = "";
+  }
+
+  if (current.length >= 4) {
+    matches.add(current);
+  }
+
+  return [...matches].slice(0, 20);
+}
+
+export class WasmModuleSummarizer {
+  public summarize(input: { url: string; bytes: Uint8Array }): string {
+    const validatedInput = wasmInputSchema.parse(input);
+
+    try {
+      const module = new WebAssembly.Module(validatedInput.bytes);
+      const imports = WebAssembly.Module.imports(module);
+      const exports = WebAssembly.Module.exports(module);
+      const embeddedStrings = extractPrintableStrings(validatedInput.bytes);
+
+      return [
+        `WASM module: ${validatedInput.url}`,
+        `Byte size: ${validatedInput.bytes.byteLength}`,
+        `Imports: ${
+          imports.length > 0
+            ? imports.map((entry) => `${entry.module}.${entry.name} (${entry.kind})`).join(", ")
+            : "none"
+        }`,
+        `Exports: ${exports.length > 0 ? exports.map((entry) => `${entry.name} (${entry.kind})`).join(", ") : "none"}`,
+        `Embedded strings: ${embeddedStrings.length > 0 ? embeddedStrings.join(", ") : "none"}`,
+      ].join("\n");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "unknown error";
+      return [
+        `WASM module: ${validatedInput.url}`,
+        `Byte size: ${validatedInput.bytes.byteLength}`,
+        `Binary summary unavailable: ${message}`,
+      ].join("\n");
+    }
+  }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@redstone-md/mapr",
+  "version": "0.0.1-alpha",
+  "type": "module",
+  "description": "Bun-native CLI/TUI for reverse-engineering frontend websites, bundles, WASM, and service workers",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/redstone-md/Mapr.git"
+  },
+  "homepage": "https://github.com/redstone-md/Mapr",
+  "bugs": {
+    "url": "https://github.com/redstone-md/Mapr/issues"
+  },
+  "keywords": [
+    "bun",
+    "cli",
+    "tui",
+    "reverse-engineering",
+    "javascript",
+    "frontend",
+    "wasm",
+    "service-worker",
+    "ai"
+  ],
+  "engines": {
+    "bun": ">=1.3.9"
+  },
+  "bin": {
+    "mapr": "./bin/mapr"
+  },
+  "files": [
+    "bin",
+    "index.ts",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "bun run index.ts",
+    "test": "bun test",
+    "check": "bunx tsc --noEmit",
+    "prepublishOnly": "bun test && bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "3.0.41",
+    "@ai-sdk/openai-compatible": "2.0.35",
+    "@clack/prompts": "1.1.0",
+    "ai": "6.0.116",
+    "cheerio": "1.2.0",
+    "picocolors": "1.1.1",
+    "prettier": "3.8.1",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "bun-types": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}