servicemap 0.1.4 → 0.1.7

package/README.md

@@ -41,7 +41,7 @@ npx servicemap skills install --agent claude
 ```
 
 Agents with known local skill folders get the real `servicemap` skill installed.
-Other selected AI tools get a portable guide pack under `~/.servicemap/model-guides`.
+Other selected AI tools get setup notes under `~/.servicemap/model-guides`.
 
 After a global install, the command is:
 
@@ -61,6 +61,8 @@ CLI options:
 servicemap
 servicemap generate --root <project-path>
 servicemap --root <project-path>
+servicemap generate --root <project-path> --allow-emails founder@example.com,ops@example.com
+servicemap generate --root <project-path> --allow-email founder@example.com --allow-email ops@example.com
 servicemap --mode page
 servicemap --mode desktop
 servicemap --dry-run
@@ -70,7 +72,7 @@ servicemap install-skill --agent codex
 servicemap install-skill --agent claude
 servicemap install-skill --agent grok
 servicemap install-skill --agent all
-servicemap install-skill --targets codex,chatgpt,cursor
+servicemap install-skill --targets codex,gemini,cursor
 servicemap skills install --agent codex
 ```
 
@@ -86,11 +88,11 @@ servicemap skills install --agent codex
 ## Validation
 
 ```bash
-node bin/servicemap.mjs generate --root demo-project --dry-run
+node bin/servicemap.mjs generate --root demo-project --allow-emails founder@example.com,ops@example.com --dry-run
 node bin/servicemap.mjs --root no-website-demo --dry-run
 node bin/servicemap.mjs --dry-run
 node bin/servicemap.mjs install-skill --agent all --dry-run
-node bin/servicemap.mjs install-skill --targets codex,chatgpt,cursor --dry-run
+node bin/servicemap.mjs install-skill --targets codex,gemini,cursor --dry-run
 node bin/servicemap.mjs skills install --agent claude --dry-run
 python3 /Users/dougie/.codex/skills/.system/skill-creator/scripts/quick_validate.py servicemap
 ```

package/bin/servicemap.mjs

@@ -13,21 +13,10 @@ const pageScript = resolve(packageRoot, 'servicemap/scripts/generate-page.mjs');
 const desktopScript = resolve(packageRoot, 'servicemap/scripts/generate-desktop-app.mjs');
 
 const targetCatalog = [
-  { id: 'codex', label: 'Codex / ChatGPT desktop', kind: 'skill', root: () => resolve(homedir(), '.agents/skills'), recommended: true },
-  { id: 'claude', label: 'Claude Code', kind: 'skill', root: () => resolve(homedir(), '.claude/skills'), recommended: true },
-  { id: 'grok', label: 'Grok', kind: 'skill', root: () => resolve(homedir(), '.grok/skills'), recommended: true },
-  { id: 'chatgpt', label: 'ChatGPT', kind: 'guide' },
-  { id: 'gpt-6-astra', label: 'GPT-6 Astra', kind: 'guide' },
-  { id: 'gpt-6-sol', label: 'GPT-6 Sol', kind: 'guide' },
-  { id: 'gpt-6-luna', label: 'GPT-6 Luna', kind: 'guide' },
-  { id: 'gpt-5.6-sol', label: 'GPT-5.6 Sol', kind: 'guide' },
-  { id: 'gpt-5.6-terra', label: 'GPT-5.6 Terra', kind: 'guide' },
-  { id: 'gpt-5.6-luna', label: 'GPT-5.6 Luna', kind: 'guide' },
-  { id: 'claude-opus', label: 'Claude Opus', kind: 'guide' },
-  { id: 'claude-sonnet', label: 'Claude Sonnet', kind: 'guide' },
-  { id: 'claude-haiku', label: 'Claude Haiku', kind: 'guide' },
-  { id: 'gemini-pro', label: 'Gemini Pro', kind: 'guide' },
-  { id: 'gemini-flash', label: 'Gemini Flash', kind: 'guide' },
+  { id: 'codex', label: 'OpenAI (Codex, ChatGPT, GPT models)', kind: 'skill', root: () => resolve(homedir(), '.agents/skills') },
+  { id: 'claude', label: 'Anthropic (Claude Code, Claude models)', kind: 'skill', root: () => resolve(homedir(), '.claude/skills') },
+  { id: 'grok', label: 'xAI (Grok)', kind: 'skill', root: () => resolve(homedir(), '.grok/skills') },
+  { id: 'gemini', label: 'Google (Gemini, Vertex AI)', kind: 'guide' },
   { id: 'cursor', label: 'Cursor', kind: 'guide' },
   { id: 'windsurf', label: 'Windsurf', kind: 'guide' },
   { id: 'copilot', label: 'GitHub Copilot', kind: 'guide' },
@@ -42,19 +31,14 @@ const targetCatalog = [
   { id: 'bolt', label: 'Bolt', kind: 'guide' },
   { id: 'v0', label: 'v0', kind: 'guide' },
   { id: 'perplexity', label: 'Perplexity', kind: 'guide' },
-  { id: 'mistral', label: 'Mistral Le Chat', kind: 'guide' },
+  { id: 'mistral', label: 'Mistral', kind: 'guide' },
   { id: 'deepseek', label: 'DeepSeek', kind: 'guide' },
   { id: 'qwen', label: 'Qwen', kind: 'guide' },
-  { id: 'llama', label: 'Llama', kind: 'guide' },
-  { id: 'ollama', label: 'Ollama', kind: 'guide' },
-  { id: 'lm-studio', label: 'LM Studio', kind: 'guide' },
+  { id: 'meta', label: 'Meta (Llama)', kind: 'guide' },
+  { id: 'local-models', label: 'Local models (Ollama, LM Studio)', kind: 'guide' },
   { id: 'openrouter', label: 'OpenRouter', kind: 'guide' },
-  { id: 'anthropic-api', label: 'Anthropic API apps', kind: 'guide' },
-  { id: 'openai-api', label: 'OpenAI API apps', kind: 'guide' },
-  { id: 'gemini-api', label: 'Gemini API apps', kind: 'guide' },
   { id: 'bedrock', label: 'Amazon Bedrock', kind: 'guide' },
   { id: 'azure-openai', label: 'Azure OpenAI', kind: 'guide' },
-  { id: 'vertex-ai', label: 'Vertex AI', kind: 'guide' },
   { id: 'poe', label: 'Poe', kind: 'guide' },
   { id: 'you-com', label: 'You.com', kind: 'guide' },
   { id: 'phind', label: 'Phind', kind: 'guide' },
@@ -65,6 +49,32 @@ const targetCatalog = [
   { id: 'custom', label: 'Other custom model or agent', kind: 'guide' },
 ];
 
+const targetAliases = new Map([
+  ['agents', 'codex'],
+  ['chatgpt', 'codex'],
+  ['openai', 'codex'],
+  ['openai-api', 'codex'],
+  ['gpt-6-astra', 'codex'],
+  ['gpt-6-sol', 'codex'],
+  ['gpt-6-luna', 'codex'],
+  ['gpt-5.6-sol', 'codex'],
+  ['gpt-5.6-terra', 'codex'],
+  ['gpt-5.6-luna', 'codex'],
+  ['anthropic', 'claude'],
+  ['anthropic-api', 'claude'],
+  ['claude-opus', 'claude'],
+  ['claude-sonnet', 'claude'],
+  ['claude-haiku', 'claude'],
+  ['google', 'gemini'],
+  ['gemini-pro', 'gemini'],
+  ['gemini-flash', 'gemini'],
+  ['gemini-api', 'gemini'],
+  ['vertex-ai', 'gemini'],
+  ['llama', 'meta'],
+  ['ollama', 'local-models'],
+  ['lm-studio', 'local-models'],
+]);
+
 function parseArgs() {
   const args = process.argv.slice(2);
   const options = {
@@ -75,6 +85,7 @@ function parseArgs() {
     agent: 'codex',
     targets: null,
     skillsDir: null,
+    allowedEmails: [],
     invokedWithoutArgs: args.length === 0,
     explicitCommand: false,
     generationRequested: false,
@@ -102,6 +113,14 @@ function parseArgs() {
     }
     if (arg === '--agent') options.agent = args[++index] ?? options.agent;
     if (arg === '--targets') options.targets = (args[++index] ?? '').split(',').map((target) => target.trim()).filter(Boolean);
+    if (arg === '--allow-email') {
+      options.allowedEmails.push(args[++index] ?? '');
+      options.generationRequested = true;
+    }
+    if (arg === '--allow-emails') {
+      options.allowedEmails.push(...(args[++index] ?? '').split(','));
+      options.generationRequested = true;
+    }
     if (arg === '--skills-dir') options.skillsDir = resolve(args[++index] ?? '.');
     if (arg === '--user') options.user = true;
     if (arg === '--survey') options.survey = true;
@@ -119,14 +138,14 @@ function help() {
 
 Usage:
   servicemap
-  servicemap generate [--root <project>] [--mode auto|page|desktop] [--dry-run]
-  servicemap --root <project> [--mode auto|page|desktop] [--dry-run]
+  servicemap generate [--root <project>] [--mode auto|page|desktop] [--allow-emails <list>] [--dry-run]
+  servicemap --root <project> [--mode auto|page|desktop] [--allow-emails <list>] [--dry-run]
   servicemap install-skill [--survey] [--agent codex|claude|grok|all] [--targets <ids>]
   servicemap skills install [--survey] [--agent codex|claude|grok|all]
 
 Examples:
   npx servicemap
-  npx servicemap generate --root ../my-app
+  npx servicemap generate --root ../my-app --allow-emails founder@example.com,ops@example.com
   npx servicemap -- --root ../my-app
   npx servicemap install-skill
   npx servicemap install-skill --survey
@@ -160,7 +179,7 @@ async function readScan(root) {
 function targetsByIds(ids) {
   const byId = new Map(targetCatalog.map((target) => [target.id, target]));
   return ids.map((id) => {
-    const target = byId.get(id);
+    const target = byId.get(targetAliases.get(id) ?? id);
     if (!target) {
       throw new Error(`Unknown target "${id}". Use --survey to choose from the list.`);
     }
@@ -171,7 +190,6 @@ function targetsByIds(ids) {
 function targetsForOptions(options) {
   if (options.targets?.length) return targetsByIds(options.targets);
   if (options.agent === 'all') return targetCatalog.filter((target) => target.kind === 'skill');
-  if (options.agent === 'agents') return targetsByIds(['codex']);
   return targetsByIds([options.agent]);
 }
 
@@ -193,17 +211,16 @@ function renderSurvey(selected, cursor) {
   targetCatalog.forEach((target, index) => {
     const pointer = index === cursor ? '>' : ' ';
     const checked = selected.has(target.id) ? 'x' : ' ';
-    const detail = target.kind === 'skill' ? 'skill folder' : 'portable guide';
-    console.log(`${pointer} [${checked}] ${target.label} (${detail})`);
+    console.log(`${pointer} [${checked}] ${target.label}`);
   });
 }
 
 function runTargetSurvey() {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    return Promise.resolve(targetCatalog.filter((target) => target.recommended));
+    return Promise.resolve([]);
   }
 
-  const selected = new Set(targetCatalog.filter((target) => target.recommended).map((target) => target.id));
+  const selected = new Set();
   let cursor = 0;
 
   return new Promise((resolvePromise) => {
@@ -242,7 +259,7 @@ function runTargetSurvey() {
 function guideText(target) {
   return `# Servicemap for ${target.label}
 
-Use this instruction with ${target.label} when you want it to create a service map for a software project.
+These setup notes help ${target.label} use Servicemap when you want it to create a service map for a software project.
 
 Invoke: /servicemap
 
@@ -285,11 +302,17 @@ async function installSkill(options) {
     ? await runTargetSurvey()
     : targetsForOptions(options);
   const roots = skillRootsForTargets(options, selectedTargets);
+  const notes = guideTargets(selectedTargets);
 
   if (!existsSync(source)) {
     throw new Error(`Bundled skill folder not found: ${source}`);
   }
 
+  if (roots.length === 0 && notes.length === 0) {
+    console.log('No targets selected. Nothing was installed.');
+    return;
+  }
+
   if (options.dryRun) {
     for (const root of roots) {
       console.log(`Would install Servicemap skill to ${join(root, 'servicemap')}`);
@@ -308,7 +331,9 @@ async function installSkill(options) {
 
   await writeGuidePacks(selectedTargets, options);
 
-  console.log('Restart your AI app if /servicemap does not appear immediately.');
+  if (roots.length > 0) {
+    console.log('Restart your AI app if /servicemap does not appear immediately.');
+  }
 }
 
 async function main() {
@@ -336,7 +361,11 @@ async function main() {
     throw new Error(`Unknown mode "${options.mode}". Use auto, page, or desktop.`);
   }
 
-  await run(process.execPath, [scanScript, '--root', options.root]);
+  const scanArgs = [scanScript, '--root', options.root];
+  for (const email of options.allowedEmails) {
+    scanArgs.push('--allow-email', email);
+  }
+  await run(process.execPath, scanArgs);
   const scan = await readScan(options.root);
   const selectedMode = options.mode === 'auto'
     ? scan.project?.framework === 'static' ? 'desktop' : 'page'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "servicemap",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "Generate an internal service map page or desktop app for a software project.",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node bin/servicemap.mjs generate --root demo-project --dry-run && node bin/servicemap.mjs --root no-website-demo --dry-run && node bin/servicemap.mjs --dry-run && HOME=\"$(mktemp -d)\" node bin/servicemap.mjs && node bin/servicemap.mjs install-skill --agent all --dry-run && node bin/servicemap.mjs install-skill --targets codex,chatgpt,cursor --dry-run && node bin/servicemap.mjs skills install --agent claude --dry-run",
+    "test": "node bin/servicemap.mjs generate --root demo-project --allow-emails founder@example.com,ops@example.com --dry-run && node bin/servicemap.mjs --root no-website-demo --dry-run && node bin/servicemap.mjs --dry-run && HOME=\"$(mktemp -d)\" node bin/servicemap.mjs && node bin/servicemap.mjs install-skill --agent all --dry-run && node bin/servicemap.mjs install-skill --targets codex,gemini,cursor --dry-run && node bin/servicemap.mjs install-skill --targets chatgpt,gpt-6-astra,gemini-flash --dry-run && node bin/servicemap.mjs skills install --agent claude --dry-run",
     "validate:skill": "python3 /Users/dougie/.codex/skills/.system/skill-creator/scripts/quick_validate.py servicemap"
   },
   "keywords": [

package/servicemap/SKILL.md

@@ -14,13 +14,15 @@ If no website can be found, create a desktop app fallback at `servicemap-desktop
 ## Workflow
 
 1. Inspect the project layout and current web framework.
-2. Run `scripts/scan-project.mjs --root <project-root>` to create `.servicemap/internal-servicemap.json`.
-3. Review the scan output for obvious false positives or missing high-confidence services.
-4. If the scan detects a web framework or routeable website, run `scripts/generate-page.mjs --root <project-root>` to create the framework-specific `/internalservicemap` route.
-5. If the scan reports `framework: static` or no website route can be safely attached, run `scripts/generate-desktop-app.mjs --root <project-root>` to create `servicemap-desktop`.
-6. Adapt the generated surface to the project's existing design system only when the route is clear and the edits are low-risk.
-7. Run the project's relevant build, lint, and focused tests.
-8. Report the page or desktop app path, service count, validation run, and any services marked low or medium confidence.
+2. If the user gives a list of emails that may access the generated web page, pass them to the scan command with `--allow-email <email>` for each address or `--allow-emails <comma-separated-list>`.
+3. Run `scripts/scan-project.mjs --root <project-root>` to create `.servicemap/internal-servicemap.json`.
+   Include the access flags from the previous step when relevant.
+4. Review the scan output for obvious false positives or missing high-confidence services.
+5. If the scan detects a web framework or routeable website, run `scripts/generate-page.mjs --root <project-root>` to create the framework-specific `/internalservicemap` route.
+6. If the scan reports `framework: static` or no website route can be safely attached, run `scripts/generate-desktop-app.mjs --root <project-root>` to create `servicemap-desktop`.
+7. Adapt the generated surface to the project's existing design system only when the route is clear and the edits are low-risk.
+8. Run the project's relevant build, lint, and focused tests.
+9. Report the page or desktop app path, service count, validation run, any services marked low or medium confidence, and whether requested email access was enforced.
 
 ## Safety Rules
 
@@ -30,6 +32,9 @@ The scan output may include env var names such as `STRIPE_SECRET_KEY`, but not t
 
 Do not add authentication, deployment, analytics, or external writes unless the user explicitly asks.
 If the repository already has route protection conventions for internal pages, follow them.
+When email access is requested, enforce it only through the app's existing server-side authentication.
+The built-in generator can enforce email allowlists for Next.js App Router projects using Clerk by checking `currentUser()` against the configured emails.
+For unsupported frameworks or static output, report that the allowlist is recorded but not enforced.
 If no website route can be safely attached, create the desktop app fallback instead of forcing website files into an unrelated project.
 
 ## Supporting References

package/servicemap/scripts/generate-page.mjs

@@ -70,6 +70,7 @@ function pageCss() {
     .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; }
+    .access-warning { margin: 0 0 18px; padding: 12px 14px; border: 1px solid #f5c542; border-radius: 8px; background: #fff7d6; color: #614700; font-size: 14px; line-height: 1.45; }
     .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; } }
   `;
@@ -77,6 +78,11 @@ function pageCss() {
 
 function htmlBody(graph) {
   const services = graph.services ?? [];
+  const access = graph.access ?? {};
+  const hasAccessRequest = access.requested && access.allowedEmails?.length;
+  const accessNotice = hasAccessRequest && access.enforced !== true
+    ? '<div class="access-warning">Email access was requested, but this project does not expose a supported server-side auth guard for generated pages. Put this route behind your app auth before sharing it.</div>'
+    : '';
   const serviceCards = services.length
     ? services.map((service) => {
       const evidence = service.evidence?.[0];
@@ -111,6 +117,7 @@ function htmlBody(graph) {
         <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>
+      ${accessNotice}
       <section class="service-grid">
         ${serviceCards}
       </section>
@@ -136,6 +143,36 @@ ${htmlBody(graph)}
 
 function tsxPage(graph) {
   const html = htmlBody(graph);
+  const allowedEmails = graph.access?.allowedEmails ?? [];
+  const usesClerk = (graph.services ?? []).some((service) => service.key === 'clerk');
+  const canEnforce = allowedEmails.length > 0 && usesClerk && graph.project?.framework === 'next-app-router';
+  if (canEnforce) {
+    graph.access.enforced = true;
+    const guardedHtml = htmlBody(graph);
+    return `import { currentUser } from '@clerk/nextjs/server';
+import { notFound } from 'next/navigation';
+
+const css = ${JSON.stringify(pageCss())};
+const html = ${JSON.stringify(guardedHtml)};
+const allowedEmails = ${JSON.stringify(allowedEmails)};
+
+export default async function InternalServiceMapPage() {
+  const user = await currentUser();
+  const userEmails = user?.emailAddresses?.map((email) => email.emailAddress.toLowerCase()) ?? [];
+  const canView = userEmails.some((email) => allowedEmails.includes(email));
+
+  if (!canView) notFound();
+
+  return (
+    <>
+      <style dangerouslySetInnerHTML={{ __html: css }} />
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+    </>
+  );
+}
+`;
+  }
+
   return `const css = ${JSON.stringify(pageCss())};
 const html = ${JSON.stringify(html)};
 

package/servicemap/scripts/scan-project.mjs

@@ -65,16 +65,26 @@ function service(name, key, category, packages, envPrefixes, domains) {
 
 function parseArgs() {
   const args = process.argv.slice(2);
-  const options = { root: process.cwd(), output: defaultOutput };
+  const options = { root: process.cwd(), output: defaultOutput, allowedEmails: [] };
   for (let index = 0; index < args.length; index += 1) {
     if (args[index] === '--root') options.root = args[index + 1] ?? options.root;
     if (args[index] === '--output') options.output = args[index + 1] ?? options.output;
+    if (args[index] === '--allow-email') options.allowedEmails.push(args[index + 1] ?? '');
+    if (args[index] === '--allow-emails') options.allowedEmails.push(...(args[index + 1] ?? '').split(','));
   }
   options.root = resolve(options.root);
   options.output = resolve(options.root, options.output);
+  options.allowedEmails = normalizeEmails(options.allowedEmails);
   return options;
 }
 
+function normalizeEmails(values) {
+  return [...new Set(values
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean)
+    .filter((value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)))];
+}
+
 async function readJson(path) {
   try {
     return JSON.parse(await readFile(path, 'utf8'));
@@ -268,6 +278,10 @@ async function main() {
       root: options.root,
       framework: detectFramework(options.root, packageJson, files),
     },
+    access: {
+      allowedEmails: options.allowedEmails,
+      requested: options.allowedEmails.length > 0,
+    },
     services,
     edges: buildEdges(projectName, services),
     summary: {