servicemap 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# Servicemap
+
+Reusable `servicemap` skill package and CLI.
+
+The skill scans a software project for external services, resolves service logos from a bundled database, and creates either an `/internalservicemap` website route or a desktop app fallback.
+
+## Terminal Use
+
+The npm package name `servicemap` is available, so users can run the clean command:
+
+```bash
+npx servicemap
+```
+
+After a global install, the command is:
+
+```bash
+servicemap
+```
+
+Install globally:
+
+```bash
+npm install -g servicemap
+```
+
+CLI options:
+
+```bash
+servicemap --root <project-path>
+servicemap --mode page
+servicemap --mode desktop
+servicemap --dry-run
+```
+
+## Contents
+
+- `servicemap/`: installable skill folder
+- `bin/servicemap.mjs`: npm CLI entrypoint
+- `servicemap/scripts/scan-project.mjs`: scans a project for service evidence
+- `servicemap/scripts/generate-page.mjs`: creates website routes
+- `servicemap/scripts/generate-desktop-app.mjs`: creates the desktop fallback
+- `servicemap/assets/service-logo-database.json`: 1,000 service logo records
+
+## Validation
+
+```bash
+node bin/servicemap.mjs --root demo-project --dry-run
+node bin/servicemap.mjs --root no-website-demo --dry-run
+python3 /Users/dougie/.codex/skills/.system/skill-creator/scripts/quick_validate.py servicemap
+```

package/bin/servicemap.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const scanScript = resolve(packageRoot, 'servicemap/scripts/scan-project.mjs');
+const pageScript = resolve(packageRoot, 'servicemap/scripts/generate-page.mjs');
+const desktopScript = resolve(packageRoot, 'servicemap/scripts/generate-desktop-app.mjs');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    root: process.cwd(),
+    mode: 'auto',
+    dryRun: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--root') options.root = args[++index] ?? options.root;
+    if (arg === '--mode') options.mode = args[++index] ?? options.mode;
+    if (arg === '--dry-run') options.dryRun = true;
+    if (arg === '--help' || arg === '-h') options.help = true;
+  }
+
+  options.root = resolve(options.root);
+  return options;
+}
+
+function help() {
+  console.log(`Servicemap
+
+Usage:
+  servicemap [--root <project>] [--mode auto|page|desktop] [--dry-run]
+
+Examples:
+  npx servicemap
+  npx servicemap -- --root ../my-app
+  servicemap --mode desktop
+`);
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, {
+      stdio: 'inherit',
+      ...options,
+    });
+
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) resolvePromise();
+      else reject(new Error(`${command} ${args.join(' ')} exited with code ${code}`));
+    });
+  });
+}
+
+async function readScan(root) {
+  const scanPath = resolve(root, '.servicemap/internal-servicemap.json');
+  return JSON.parse(await readFile(scanPath, 'utf8'));
+}
+
+async function main() {
+  const options = parseArgs();
+  if (options.help) {
+    help();
+    return;
+  }
+
+  if (!['auto', 'page', 'desktop'].includes(options.mode)) {
+    throw new Error(`Unknown mode "${options.mode}". Use auto, page, or desktop.`);
+  }
+
+  await run(process.execPath, [scanScript, '--root', options.root]);
+  const scan = await readScan(options.root);
+  const selectedMode = options.mode === 'auto'
+    ? scan.project?.framework === 'static' ? 'desktop' : 'page'
+    : options.mode;
+
+  console.log(`Servicemap detected ${scan.summary?.serviceCount ?? 0} services.`);
+  console.log(`Framework: ${scan.project?.framework ?? 'unknown'}`);
+  console.log(`Mode: ${selectedMode}`);
+
+  if (options.dryRun) return;
+
+  if (selectedMode === 'desktop') {
+    await run(process.execPath, [desktopScript, '--root', options.root]);
+  } else {
+    await run(process.execPath, [pageScript, '--root', options.root]);
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "servicemap",
+  "version": "0.1.0",
+  "description": "Generate an internal service map page or desktop app for a software project.",
+  "type": "module",
+  "bin": {
+    "servicemap": "bin/servicemap.mjs"
+  },
+  "files": [
+    "bin",
+    "servicemap",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node bin/servicemap.mjs --root demo-project --dry-run && node bin/servicemap.mjs --root no-website-demo --dry-run",
+    "validate:skill": "python3 /Users/dougie/.codex/skills/.system/skill-creator/scripts/quick_validate.py servicemap"
+  },
+  "keywords": [
+    "ai-skill",
+    "service-map",
+    "servicemap",
+    "developer-tools",
+    "internal-tools"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/douglasbrown11/servicemap.git"
+  },
+  "bugs": {
+    "url": "https://github.com/douglasbrown11/servicemap/issues"
+  },
+  "homepage": "https://github.com/douglasbrown11/servicemap#readme"
+}

package/servicemap/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: servicemap
+description: Create an /internalservicemap page or desktop app for a software project by scanning its codebase for external services, resolving logos, and attaching the map to the existing website when one is present.
+metadata:
+  short-description: Generate an internal servicemap page
+---
+
+# Servicemap
+
+Use this skill when a user invokes `servicemap` or asks to create an internal servicemap for a software project.
+The outcome is a working `/internalservicemap` page attached to the existing website when possible.
+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.
+
+## Safety Rules
+
+Read environment variable names only.
+Never copy, expose, summarize, or commit secret values.
+The scan output may include env var names such as `STRIPE_SECRET_KEY`, but not their values.
+
+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.
+If no website route can be safely attached, create the desktop app fallback instead of forcing website files into an unrelated project.
+
+## Supporting References
+
+- For detection rules and evidence confidence, read [references/service-detection-rules.md](references/service-detection-rules.md).
+- For route placement by framework, read [references/framework-routing.md](references/framework-routing.md).
+- For page quality expectations, read [references/page-design.md](references/page-design.md).
+- For desktop fallback behavior, read [references/desktop-fallback.md](references/desktop-fallback.md).

package/servicemap/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: Servicemap
+short_description: Generate an /internalservicemap page from a project's detected services.
+default_prompt: Create an internal servicemap page for this project.