servicemap 0.1.0

package/servicemap/references/desktop-fallback.md

@@ -0,0 +1,29 @@
+# Desktop Fallback
+
+Use the desktop fallback when no website route can be confidently attached.
+
+Run:
+
+```bash
+scripts/generate-desktop-app.mjs --root <project-root>
+```
+
+The generated app is written to:
+
+```text
+servicemap-desktop
+```
+
+It is a Vite React app with Tauri configuration.
+It can run as a web preview with `npm run dev`.
+It can be packaged as a native desktop app with `npm run tauri build` when the local machine has the Tauri/Rust toolchain available.
+
+Validate the generated app with:
+
+```bash
+npm install
+npm run build
+```
+
+Do not install global tooling automatically.
+If native packaging fails because Rust, platform SDKs, or Tauri prerequisites are missing, report that the app source was generated and the web build passed.

package/servicemap/references/framework-routing.md

@@ -0,0 +1,16 @@
+# Framework Routing
+
+Create `/internalservicemap` using the project's existing routing convention.
+
+Preferred route locations:
+- Next.js App Router: `app/internalservicemap/page.tsx` or `src/app/internalservicemap/page.tsx`.
+- Next.js Pages Router: `pages/internalservicemap.tsx` or `src/pages/internalservicemap.tsx`.
+- Astro: `src/pages/internalservicemap.astro`.
+- Remix: `app/routes/internalservicemap.tsx`.
+- Vite apps with an existing router: add a route matching the app's route conventions.
+- Unknown static sites: prefer the desktop fallback app unless the user explicitly wants static website files.
+
+If the project has middleware, auth wrappers, layout conventions, or route metadata, adapt the generated page to match.
+Do not invent a new router or add a new framework.
+
+If a project has no website, run `scripts/generate-desktop-app.mjs --root <project-root>` and report the generated desktop app path.

package/servicemap/references/page-design.md

@@ -0,0 +1,22 @@
+# Page Design
+
+The page should be useful on first load, not a marketing landing page.
+
+Show:
+- Project name.
+- Number of detected services.
+- High-confidence service count.
+- Framework detected.
+- Service cards with logo, name, category, confidence, and strongest evidence.
+
+Keep the text concise.
+Use the host project's design system when it is easy to identify.
+Avoid exposing secrets or internal URLs that are not already present as public hostnames.
+
+Prefer a clean operational interface:
+- compact summary metrics
+- scannable service cards
+- clear confidence labels
+- evidence shown in short form
+
+If the UI looks obviously off after rendering, fix the layout before finishing.

package/servicemap/references/service-detection-rules.md

@@ -0,0 +1,22 @@
+# Service Detection Rules
+
+The scanner should prefer evidence from package dependencies, imports, known config files, environment variable names, and official service domains.
+
+High-confidence evidence:
+- Direct dependency names such as `stripe`, `firebase`, `@supabase/supabase-js`, or `@sentry/nextjs`.
+- Known config files such as `firebase.json`, `vercel.json`, or `wrangler.toml`.
+
+Medium-confidence evidence:
+- Environment variable names such as `STRIPE_SECRET_KEY`, `RESEND_API_KEY`, or `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`.
+- Official domains found in docs or source comments.
+
+Low-confidence evidence:
+- Generic text mentions without package, env, URL, or config evidence.
+
+Never inspect or display secret values.
+Only read the variable name before the equals sign in `.env` files.
+
+False positives to watch:
+- Short generated-database aliases that match ordinary words.
+- Package names that are not SaaS services.
+- Documentation examples that mention services the project does not actually use.

package/servicemap/scripts/generate-desktop-app.mjs

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+const defaultInput = '.servicemap/internal-servicemap.json';
+const defaultOutput = 'servicemap-desktop';
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = { root: process.cwd(), input: defaultInput, output: defaultOutput };
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === '--root') options.root = args[index + 1] ?? options.root;
+    if (args[index] === '--input') options.input = args[index + 1] ?? options.input;
+    if (args[index] === '--output') options.output = args[index + 1] ?? options.output;
+  }
+  options.root = resolve(options.root);
+  options.input = resolve(options.root, options.input);
+  options.output = resolve(options.root, options.output);
+  return options;
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+async function writeProjectFile(root, path, contents) {
+  const filePath = join(root, path);
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, contents);
+}
+
+function packageJson(graph) {
+  const appName = `${graph.project?.name ?? 'internal'}-servicemap`.replace(/[^a-z0-9-]+/gi, '-').toLowerCase();
+  return `${JSON.stringify({
+    name: appName,
+    private: true,
+    version: '0.1.0',
+    type: 'module',
+    scripts: {
+      dev: 'vite',
+      build: 'vite build',
+      preview: 'vite preview',
+      tauri: 'tauri',
+    },
+    dependencies: {
+      '@vitejs/plugin-react': '^5.0.0',
+      vite: '^7.0.0',
+      typescript: '^5.0.0',
+      react: '^19.0.0',
+      'react-dom': '^19.0.0',
+      '@tauri-apps/api': '^2.0.0',
+    },
+    devDependencies: {
+      '@tauri-apps/cli': '^2.0.0',
+    },
+  }, null, 2)}\n`;
+}
+
+function viteConfig() {
+  return `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    strictPort: false,
+  },
+});
+`;
+}
+
+function indexHtml() {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Internal Servicemap</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>
+`;
+}
+
+function mainJsx() {
+  return `import React from 'react';
+import { createRoot } from 'react-dom/client';
+import graph from '.servicemap-data.json';
+import './styles.css';
+
+function strongestEvidence(service) {
+  const evidence = service.evidence?.[0];
+  return evidence ? \`\${evidence.type}: \${evidence.value}\` : 'No evidence captured';
+}
+
+function App() {
+  const services = graph.services ?? [];
+  const highConfidence = services.filter((service) => service.confidence === 'high').length;
+
+  return (
+    <main className="shell">
+      <header className="topbar">
+        <div>
+          <h1>Internal Servicemap</h1>
+          <p>{graph.project?.name ?? 'This project'} uses these detected services.</p>
+        </div>
+        <span className="stamp">{new Date(graph.generatedAt).toLocaleString()}</span>
+      </header>
+
+      <section className="metrics" aria-label="Service map summary">
+        <div><strong>{services.length}</strong><span>services</span></div>
+        <div><strong>{highConfidence}</strong><span>high confidence</span></div>
+        <div><strong>{graph.project?.framework ?? 'unknown'}</strong><span>source</span></div>
+      </section>
+
+      <section className="grid">
+        {services.length ? services.map((service) => (
+          <article className="card" key={service.id}>
+            <div className="cardTop">
+              <div className="logo" aria-hidden="true">
+                {service.iconUrl ? <img src={service.iconUrl} alt="" /> : service.name.slice(0, 2).toUpperCase()}
+              </div>
+              <div className="nameBlock">
+                <strong>{service.name}</strong>
+                <span>{service.confidence} confidence</span>
+              </div>
+            </div>
+            <span className="category">{service.category}</span>
+            <p>{strongestEvidence(service)}</p>
+          </article>
+        )) : <div className="empty">No external services were detected yet.</div>}
+      </section>
+    </main>
+  );
+}
+
+createRoot(document.getElementById('root')).render(<App />);
+`;
+}
+
+function stylesCss() {
+  return `:root {
+  color: #172033;
+  background: #f7f8fb;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  min-height: 100vh;
+  background: #f7f8fb;
+}
+
+.shell {
+  max-width: 1180px;
+  margin: 0 auto;
+  padding: 40px 24px 56px;
+}
+
+.topbar {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-end;
+  gap: 24px;
+  margin-bottom: 24px;
+}
+
+h1 {
+  margin: 0 0 8px;
+  font-size: 44px;
+  line-height: 1;
+  letter-spacing: 0;
+}
+
+p {
+  margin: 0;
+  color: #5f6b7c;
+  line-height: 1.55;
+}
+
+.stamp {
+  color: #64748b;
+  font-size: 13px;
+  white-space: nowrap;
+}
+
+.metrics {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+  margin: 22px 0;
+}
+
+.metrics div,
+.card {
+  background: #fff;
+  border: 1px solid #e3e8ef;
+  border-radius: 8px;
+  box-shadow: 0 1px 2px rgba(15, 23, 42, 0.04);
+}
+
+.metrics div {
+  padding: 16px;
+}
+
+.metrics strong {
+  display: block;
+  font-size: 26px;
+}
+
+.metrics span {
+  color: #64748b;
+  font-size: 13px;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+  gap: 12px;
+}
+
+.card {
+  min-height: 150px;
+  padding: 14px;
+}
+
+.cardTop {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-bottom: 10px;
+}
+
+.logo {
+  width: 36px;
+  height: 36px;
+  border-radius: 8px;
+  background: #172033;
+  color: #fff;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+  flex: 0 0 auto;
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.logo img {
+  max-width: 22px;
+  max-height: 22px;
+  object-fit: contain;
+}
+
+.nameBlock {
+  min-width: 0;
+}
+
+.nameBlock strong {
+  display: block;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.nameBlock span,
+.card p {
+  color: #64748b;
+  font-size: 12px;
+}
+
+.category {
+  display: inline-flex;
+  align-items: center;
+  height: 22px;
+  padding: 0 8px;
+  border-radius: 999px;
+  background: #edf2ff;
+  color: #334155;
+  font-size: 12px;
+  margin-bottom: 10px;
+}
+
+.empty {
+  background: #fff;
+  border: 1px dashed #cbd5e1;
+  border-radius: 8px;
+  padding: 24px;
+}
+
+@media (max-width: 720px) {
+  .topbar {
+    display: block;
+  }
+
+  h1 {
+    font-size: 34px;
+  }
+
+  .metrics {
+    grid-template-columns: 1fr;
+  }
+}
+`;
+}
+
+function tauriConfig(graph) {
+  return `${JSON.stringify({
+    productName: 'Internal Servicemap',
+    version: '0.1.0',
+    identifier: `com.internal.${(graph.project?.name ?? 'servicemap').replace(/[^a-z0-9]+/gi, '').toLowerCase() || 'servicemap'}`,
+    build: {
+      beforeDevCommand: 'npm run dev',
+      beforeBuildCommand: 'npm run build',
+      devUrl: 'http://localhost:5173',
+      frontendDist: '../dist',
+    },
+    app: {
+      windows: [
+        {
+          title: 'Internal Servicemap',
+          width: 1180,
+          height: 820,
+          minWidth: 860,
+          minHeight: 620,
+        },
+      ],
+    },
+    bundle: {
+      active: true,
+      targets: 'all',
+    },
+  }, null, 2)}\n`;
+}
+
+function cargoToml() {
+  return `[package]
+name = "internal-servicemap"
+version = "0.1.0"
+description = "Internal Servicemap"
+authors = ["Internal"]
+edition = "2021"
+
+[lib]
+name = "internal_service_map_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+`;
+}
+
+function buildRs() {
+  return `fn main() {
+    tauri_build::build()
+}
+`;
+}
+
+function rustLib() {
+  return `#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+`;
+}
+
+function rustMain() {
+  return `fn main() {
+    internal_service_map_lib::run()
+}
+`;
+}
+
+async function main() {
+  const options = parseArgs();
+  const graph = await readJson(options.input);
+
+  await mkdir(options.output, { recursive: true });
+  await writeProjectFile(options.output, 'package.json', packageJson(graph));
+  await writeProjectFile(options.output, 'index.html', indexHtml());
+  await writeProjectFile(options.output, 'vite.config.js', viteConfig());
+  await writeProjectFile(options.output, 'src/main.jsx', mainJsx());
+  await writeProjectFile(options.output, 'src/styles.css', stylesCss());
+  await writeProjectFile(options.output, 'srcservicemap-data.json', `${JSON.stringify(graph, null, 2)}\n`);
+  await writeProjectFile(options.output, 'src-tauri/tauri.conf.json', tauriConfig(graph));
+  await writeProjectFile(options.output, 'src-tauri/Cargo.toml', cargoToml());
+  await writeProjectFile(options.output, 'src-tauri/build.rs', buildRs());
+  await writeProjectFile(options.output, 'src-tauri/src/lib.rs', rustLib());
+  await writeProjectFile(options.output, 'src-tauri/src/main.rs', rustMain());
+
+  console.log(`Wrote desktop servicemap app to ${options.output}`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/servicemap/scripts/generate-page.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+const defaultInput = '.servicemap/internal-servicemap.json';
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = { root: process.cwd(), input: defaultInput };
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === '--root') options.root = args[index + 1] ?? options.root;
+    if (args[index] === '--input') options.input = args[index + 1] ?? options.input;
+  }
+  options.root = resolve(options.root);
+  options.input = resolve(options.root, options.input);
+  return options;
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+function routeFor(root, framework) {
+  if (framework === 'next-app-router') {
+    const base = existsSync(join(root, 'src/app')) ? 'src/app' : 'app';
+    return { path: join(root, base, 'internalservicemap/page.tsx'), kind: 'next-app-router' };
+  }
+  if (framework === 'next-pages-router') {
+    const base = existsSync(join(root, 'src/pages')) ? 'src/pages' : 'pages';
+    return { path: join(root, base, 'internalservicemap.tsx'), kind: 'next-pages-router' };
+  }
+  if (framework === 'astro') {
+    return { path: join(root, 'src/pages/internalservicemap.astro'), kind: 'astro' };
+  }
+  if (framework === 'remix') {
+    return { path: join(root, 'app/routes/internalservicemap.tsx'), kind: 'remix' };
+  }
+  return { path: join(root, 'public/internalservicemap.html'), kind: 'static' };
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function pageCss() {
+  return `
+    :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { margin: 0; background: #f7f8fb; color: #172033; }
+    .servicemap-shell { max-width: 1180px; margin: 0 auto; padding: 40px 24px 56px; }
+    .servicemap-header { display: flex; justify-content: space-between; gap: 24px; align-items: flex-end; margin-bottom: 24px; }
+    h1 { margin: 0 0 8px; font-size: clamp(30px, 4vw, 48px); line-height: 1; letter-spacing: 0; }
+    p { margin: 0; color: #5f6b7c; line-height: 1.55; }
+    .summary { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; margin: 22px 0; }
+    .metric, .service-card { background: #fff; border: 1px solid #e3e8ef; border-radius: 8px; box-shadow: 0 1px 2px rgba(15, 23, 42, 0.04); }
+    .metric { padding: 16px; }
+    .metric strong { display: block; font-size: 26px; }
+    .metric span { color: #64748b; font-size: 13px; }
+    .service-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 12px; }
+    .service-card { padding: 14px; min-height: 150px; }
+    .service-top { display: flex; align-items: center; gap: 10px; margin-bottom: 10px; }
+    .logo { width: 36px; height: 36px; border-radius: 8px; background: #172033; display: grid; place-items: center; overflow: hidden; flex: 0 0 auto; }
+    .logo img { max-width: 22px; max-height: 22px; object-fit: contain; }
+    .service-name { min-width: 0; }
+    .service-name strong { display: block; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .service-name span, .evidence { color: #64748b; font-size: 12px; }
+    .badge { display: inline-flex; align-items: center; height: 22px; padding: 0 8px; border-radius: 999px; background: #edf2ff; color: #334155; font-size: 12px; margin-bottom: 10px; }
+    .evidence { margin-top: 8px; }
+    .empty { background: #fff; border: 1px dashed #cbd5e1; border-radius: 8px; padding: 24px; }
+    @media (max-width: 720px) { .servicemap-header { display: block; } .summary { grid-template-columns: 1fr; } }
+  `;
+}
+
+function htmlBody(graph) {
+  const services = graph.services ?? [];
+  const serviceCards = services.length
+    ? services.map((service) => {
+      const evidence = service.evidence?.[0];
+      const evidenceText = evidence ? `${evidence.type}: ${evidence.value}` : 'No evidence captured';
+      return `
+        <article class="service-card">
+          <div class="service-top">
+            <div class="logo">${service.iconUrl ? `<img src="${escapeHtml(service.iconUrl)}" alt="">` : escapeHtml(service.name.slice(0, 2).toUpperCase())}</div>
+            <div class="service-name">
+              <strong>${escapeHtml(service.name)}</strong>
+              <span>${escapeHtml(service.confidence)} confidence</span>
+            </div>
+          </div>
+          <span class="badge">${escapeHtml(service.category)}</span>
+          <p class="evidence">${escapeHtml(evidenceText)}</p>
+        </article>
+      `;
+    }).join('')
+    : '<div class="empty">No external services were detected yet.</div>';
+
+  return `
+    <main class="servicemap-shell">
+      <section class="servicemap-header">
+        <div>
+          <h1>Internal Servicemap</h1>
+          <p>${escapeHtml(graph.project?.name ?? 'This project')} uses these detected services.</p>
+        </div>
+        <p>Generated ${escapeHtml(new Date(graph.generatedAt).toLocaleString())}</p>
+      </section>
+      <section class="summary" aria-label="Service map summary">
+        <div class="metric"><strong>${services.length}</strong><span>services detected</span></div>
+        <div class="metric"><strong>${graph.summary?.highConfidenceCount ?? 0}</strong><span>high confidence</span></div>
+        <div class="metric"><strong>${escapeHtml(graph.project?.framework ?? 'unknown')}</strong><span>framework</span></div>
+      </section>
+      <section class="service-grid">
+        ${serviceCards}
+      </section>
+    </main>
+  `;
+}
+
+function staticHtml(graph) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Internal Servicemap</title>
+  <style>${pageCss()}</style>
+</head>
+<body>
+${htmlBody(graph)}
+</body>
+</html>
+`;
+}
+
+function tsxPage(graph) {
+  const html = htmlBody(graph);
+  return `const css = ${JSON.stringify(pageCss())};
+const html = ${JSON.stringify(html)};
+
+export default function InternalServiceMapPage() {
+  return (
+    <>
+      <style dangerouslySetInnerHTML={{ __html: css }} />
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+    </>
+  );
+}
+`;
+}
+
+function astroPage(graph) {
+  return `---
+const css = ${JSON.stringify(pageCss())};
+const html = ${JSON.stringify(htmlBody(graph))};
+---
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Internal Servicemap</title>
+    <style set:html={css}></style>
+  </head>
+  <body set:html={html}></body>
+</html>
+`;
+}
+
+async function main() {
+  const options = parseArgs();
+  const graph = await readJson(options.input);
+  const route = routeFor(options.root, graph.project?.framework);
+  const contents = route.kind === 'astro' ? astroPage(graph) : route.kind === 'static' ? staticHtml(graph) : tsxPage(graph);
+
+  await mkdir(dirname(route.path), { recursive: true });
+  await writeFile(route.path, contents);
+  console.log(`Wrote /internalservicemap page to ${route.path}`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});