@shiplens/cli 1.2.7

package/lib/mcp-config.js

@@ -0,0 +1,96 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+const CLIENTS = ['cursor', 'codex', 'claude', 'antigravity', 'manual'];
+
+function makeError(message, code) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function getClientPath(client, homeDir = os.homedir(), platform = process.platform) {
+  switch (client) {
+    case 'cursor':
+      return path.join(homeDir, '.cursor', 'mcp.json');
+    case 'claude':
+      if (platform === 'darwin') return path.join(homeDir, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+      if (platform === 'win32') return path.join(homeDir, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+      return path.join(homeDir, '.config', 'Claude', 'claude_desktop_config.json');
+    case 'antigravity':
+      return path.join(homeDir, '.gemini', 'config', 'mcp_config.json');
+    case 'codex':
+      return path.join(homeDir, '.codex', 'config.toml');
+    default:
+      return null;
+  }
+}
+
+function getMcpServer(client, url) {
+  void client;
+  void url;
+  return {
+    command: process.platform === 'win32' ? 'npx.cmd' : 'npx',
+    args: ['--yes', 'shiplens-cli', 'mcp', 'serve'],
+  };
+}
+
+function getMcpConfig(client, url) {
+  if (!CLIENTS.includes(client)) throw makeError(`Unsupported MCP client: ${client}`, 'UNSUPPORTED_MCP_CLIENT');
+  return { mcpServers: { shiplens: getMcpServer(client, url) } };
+}
+
+function readJsonConfig(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (!value || Array.isArray(value) || typeof value !== 'object') throw new Error('root must be object');
+    return value;
+  } catch (error) {
+    throw makeError(`Failed to read MCP config at ${filePath}: invalid JSON`, 'INVALID_MCP_CONFIG');
+  }
+}
+
+function mergeJsonMcpConfig(client, url, filePath) {
+  const config = readJsonConfig(filePath);
+  config.mcpServers = config.mcpServers || {};
+  const desired = getMcpServer(client, url);
+  const existing = config.mcpServers.shiplens;
+  if (existing) {
+    const matching = JSON.stringify(existing) === JSON.stringify(desired);
+    return { written: false, already_configured: matching, path: filePath, config: getMcpConfig(client, url) };
+  }
+
+  config.mcpServers.shiplens = desired;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  return { written: true, already_configured: false, path: filePath, config: getMcpConfig(client, url) };
+}
+
+function configureMcpClient(client, url, options = {}) {
+  if (!CLIENTS.includes(client)) throw makeError(`Unsupported MCP client: ${client}`, 'UNSUPPORTED_MCP_CLIENT');
+  if (!url) throw makeError('MCP URL is required', 'MCP_URL_REQUIRED');
+
+  if (client === 'manual') {
+    return { written: false, already_configured: false, path: null, config: getMcpConfig('manual', url) };
+  }
+
+  const homeDir = options.homeDir || os.homedir();
+  const platform = options.platform || process.platform;
+  const configPath = getClientPath(client, homeDir, platform);
+  if (client !== 'codex') return mergeJsonMcpConfig(client, url, configPath);
+
+  const exec = options.execFileSync || execFileSync;
+  const bundledCodex = '/Applications/ChatGPT.app/Contents/Resources/codex';
+  const codexCommand = options.codexCommand || process.env.SHIPLENS_CODEX_BIN || (fs.existsSync(bundledCodex) ? bundledCodex : 'codex');
+  try {
+    exec(codexCommand, ['mcp', 'add', 'shiplens', '--', process.platform === 'win32' ? 'npx.cmd' : 'npx', '--yes', 'shiplens-cli', 'mcp', 'serve'], { stdio: 'ignore' });
+  } catch (error) {
+    throw makeError('Failed to configure Codex MCP. Ensure Codex Desktop is installed and codex CLI is available in PATH.', 'CODEX_MCP_CONFIG_FAILED');
+  }
+  return { written: true, already_configured: false, path: configPath, config: getMcpConfig('codex', url) };
+}
+
+module.exports = { CLIENTS, getClientPath, getMcpConfig, configureMcpClient };

package/lib/taxonomy.js

@@ -0,0 +1,354 @@
+const path = require('path');
+const fs = require('fs');
+
+let taxonomyCache = null;
+let indexCache = null;
+
+function loadTaxonomy() {
+  if (taxonomyCache) return taxonomyCache;
+  const filePath = path.join(__dirname, 'assets', 'taxonomy.json');
+  try {
+    if (fs.existsSync(filePath)) {
+      taxonomyCache = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } else {
+      taxonomyCache = { genres: [] };
+    }
+  } catch (e) {
+    taxonomyCache = { genres: [] };
+  }
+  return taxonomyCache;
+}
+
+function buildIndex() {
+  if (indexCache) return indexCache;
+  const data = loadTaxonomy();
+  const genresMap = new Map();
+  const subgenresMap = new Map();
+  const tagsMap = new Map();
+
+  for (const g of data.genres || []) {
+    const genreObj = {
+      id: g.id,
+      name: g.name,
+      type: g.type || 'App',
+      subgenres: new Map(),
+    };
+    genresMap.set(g.id, genreObj);
+
+    for (const sg of g.subgenres || []) {
+      const subObj = {
+        id: sg.id,
+        name: sg.name,
+        genre_id: g.id,
+        genre_name: g.name,
+        genre_type: g.type || 'App',
+        tag_categories: sg.tag_categories || {},
+      };
+      genreObj.subgenres.set(sg.id, subObj);
+      subgenresMap.set(sg.id, subObj);
+
+      if (sg.tag_categories) {
+        for (const [catKey, tagList] of Object.entries(sg.tag_categories)) {
+          if (Array.isArray(tagList)) {
+            for (const t of tagList) {
+              tagsMap.set(t.tag_id, {
+                tag_id: t.tag_id,
+                name: t.name,
+                category: catKey,
+                subgenre_id: sg.id,
+                subgenre_name: sg.name,
+                genre_id: g.id,
+                genre_name: g.name,
+                genre_type: g.type || 'App',
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  indexCache = { genresMap, subgenresMap, tagsMap };
+  return indexCache;
+}
+
+const CATEGORY_DISPLAY_NAMES = {
+  core_features: 'Core Features',
+  monetization: 'Monetization',
+  social_engagement: 'Social & Growth',
+  technical_platform: 'Technical Platform',
+  content_theme: 'Content & Compliance',
+};
+
+/**
+ * Automatically infer 4-level taxonomy and feature tags from project context
+ */
+function inferTaxonomy(projectContext = {}) {
+  const { genresMap, subgenresMap, tagsMap } = buildIndex();
+  const {
+    name = '',
+    description = '',
+    keywords = [],
+    dependencies = {},
+    devDependencies = {},
+    framework = '',
+  } = projectContext;
+
+  const allDeps = Object.assign({}, dependencies, devDependencies);
+  const depKeys = Object.keys(allDeps).map((k) => k.toLowerCase());
+  const combinedText = `${name} ${description} ${(keywords || []).join(' ')} ${framework}`.toLowerCase();
+
+  let matchedGenreId = 'utilities';
+  let matchedSubgenreId = 'developer_tools';
+  const matchedTags = new Set();
+
+  // 1. Game detection
+  const isGame =
+    depKeys.some((d) => ['phaser', 'pixi.js', 'three', 'kaboom', 'melonjs'].includes(d)) ||
+    /\b(game|arcade|rpg|puzzle|casual|roguelike|fps|chess|cards)\b/.test(combinedText);
+
+  if (isGame) {
+    matchedGenreId = 'game_casual_puzzle';
+    matchedSubgenreId = 'merge_mechanic_puzzle';
+  } else {
+    // App branch inference
+    if (/\b(vpn|proxy|shadowsocks|v2ray|wireguard|clash)\b/.test(combinedText)) {
+      matchedGenreId = 'utilities';
+      matchedSubgenreId = 'net_vpn_proxy';
+    } else if (/\b(clean|booster|battery|ram|storage|cache)\b/.test(combinedText)) {
+      matchedGenreId = 'utilities';
+      matchedSubgenreId = 'system_cleaner_optimizer';
+    } else if (/\b(calc|turnip|price|profit|currency|converter|calculator|finance|financial|stock|crypto|accounting|tax|invoice|budget)\b/.test(combinedText)) {
+      matchedGenreId = 'finance_fintech';
+      if (/\b(stock|trading|invest)\b/.test(combinedText)) {
+        matchedSubgenreId = 'stock_trading_investment';
+      } else if (/\b(crypto|wallet|exchange|bitcoin|eth)\b/.test(combinedText)) {
+        matchedSubgenreId = 'crypto_wallet_exchange';
+      } else {
+        matchedSubgenreId = 'personal_budgeting_accounting';
+      }
+    } else if (/\b(shop|store|ecommerce|cart|checkout|product|shopify|order|retail)\b/.test(combinedText)) {
+      matchedGenreId = 'shopping_ecommerce';
+      matchedSubgenreId = 'marketplace_general_retail';
+    } else if (/\b(chat|message|social|community|forum|feed|comment|social_media|dating)\b/.test(combinedText)) {
+      matchedGenreId = 'social';
+      matchedSubgenreId = 'interest_community_forum';
+    } else if (/\b(team|crm|sales|hrm|agile|collaboration|meeting|pipeline)\b/.test(combinedText)) {
+      matchedGenreId = 'business';
+      matchedSubgenreId = 'project_agile_management';
+    } else if (/\b(task|todo|note|docs|editor|kanban|calendar|workflow|productivity|markdown|pomodoro)\b/.test(combinedText)) {
+      matchedGenreId = 'productivity';
+      matchedSubgenreId = 'todo_task_management';
+    } else if (/\b(video|audio|music|media|player|streaming|podcast|stream|record|camera|photo)\b/.test(combinedText)) {
+      matchedGenreId = 'photo_and_video';
+      matchedSubgenreId = 'short_video_creation_editor';
+    } else {
+      matchedGenreId = 'utilities';
+      matchedSubgenreId = 'browser_web_utility';
+    }
+  }
+
+  // Ensure valid genre and subgenre
+  if (!genresMap.has(matchedGenreId)) {
+    matchedGenreId = genresMap.keys().next().value || 'utilities';
+  }
+  const currentGenreObj = genresMap.get(matchedGenreId);
+  if (!currentGenreObj.subgenres.has(matchedSubgenreId)) {
+    matchedSubgenreId = currentGenreObj.subgenres.keys().next().value || 'developer_tools';
+  }
+
+  const currentSubObj = currentGenreObj.subgenres.get(matchedSubgenreId) || subgenresMap.get(matchedSubgenreId);
+
+  // 2. Pick feature tags from categories
+  if (currentSubObj && currentSubObj.tag_categories) {
+    const cats = currentSubObj.tag_categories;
+
+    // A. Core Features (select 2~3)
+    const coreList = cats.core_features || [];
+    if (coreList.length > 0) {
+      let added = 0;
+      for (const tag of coreList) {
+        const tagWords = tag.tag_id.split('_').concat(tag.name.toLowerCase().split(/\s+/));
+        if (tagWords.some((w) => w.length > 3 && combinedText.includes(w))) {
+          matchedTags.add(tag.tag_id);
+          added++;
+          if (added >= 3) break;
+        }
+      }
+      if (added === 0) {
+        for (let i = 0; i < Math.min(2, coreList.length); i++) {
+          matchedTags.add(coreList[i].tag_id);
+        }
+      }
+    }
+
+    // B. Monetization (select 1)
+    const monList = cats.monetization || [];
+    if (monList.length > 0) {
+      let monTag = null;
+      if (depKeys.some((d) => d.includes('stripe') || d.includes('lemon') || d.includes('paddle') || d.includes('paypal'))) {
+        monTag = monList.find((t) => t.tag_id.includes('sub') || t.tag_id.includes('vip') || t.name.toLowerCase().includes('subscription')) || monList[0];
+      } else if (depKeys.some((d) => d.includes('admob') || d.includes('ads') || d.includes('google-ad'))) {
+        monTag = monList.find((t) => t.tag_id.includes('ad') || t.name.toLowerCase().includes('ad')) || monList[0];
+      } else {
+        monTag = monList[0];
+      }
+      if (monTag) matchedTags.add(monTag.tag_id);
+    }
+
+    // C. Technical Platform (select 1)
+    const techList = cats.technical_platform || [];
+    if (techList.length > 0) {
+      let techTag = techList[0];
+      for (const t of techList) {
+        const tWords = t.tag_id.split('_').concat(t.name.toLowerCase().split(/\s+/));
+        if (tWords.some((w) => w.length > 3 && combinedText.includes(w))) {
+          techTag = t;
+          break;
+        }
+      }
+      if (techTag) matchedTags.add(techTag.tag_id);
+    }
+
+    // D. Social Engagement (select 1)
+    const socList = cats.social_engagement || [];
+    if (socList.length > 0) {
+      matchedTags.add(socList[0].tag_id);
+    }
+  }
+
+  // Assemble tag details
+  const tagDetails = [];
+  for (const tagId of matchedTags) {
+    const info = tagsMap.get(tagId);
+    if (info) {
+      tagDetails.push({
+        tag_id: info.tag_id,
+        name: info.name,
+        category: info.category,
+        category_name: CATEGORY_DISPLAY_NAMES[info.category] || info.category,
+      });
+    } else {
+      tagDetails.push({
+        tag_id: tagId,
+        name: tagId.replace(/_/g, ' '),
+        category: 'core_features',
+        category_name: 'Core Features',
+      });
+    }
+  }
+
+  return {
+    genre: {
+      id: currentGenreObj?.id || matchedGenreId,
+      name: currentGenreObj?.name || 'Utilities',
+      type: currentGenreObj?.type || 'App',
+    },
+    subgenre: {
+      id: currentSubObj?.id || matchedSubgenreId,
+      name: currentSubObj?.name || 'Developer Tools',
+    },
+    feature_tags: tagDetails,
+    feature_tag_ids: Array.from(matchedTags),
+  };
+}
+
+/**
+ * Format taxonomy summary into 4-Level structure
+ */
+function formatTaxonomySummary(taxonomy) {
+  if (!taxonomy || !taxonomy.genre) return '';
+
+  const genreStr = `${taxonomy.genre.name} (${taxonomy.genre.type})`;
+  const subgenreStr = taxonomy.subgenre ? taxonomy.subgenre.name : '';
+
+  const categorized = {};
+  for (const t of taxonomy.feature_tags || []) {
+    const cat = t.category || 'core_features';
+    if (!categorized[cat]) categorized[cat] = [];
+    categorized[cat].push(`${t.tag_id} (${t.name})`);
+  }
+
+  const lines = [
+    `  • Genre (L1): ${genreStr}`,
+    `  • Sub-genre (L2): ${subgenreStr}`,
+    `  • Feature Tags:`,
+  ];
+
+  for (const [catKey, items] of Object.entries(categorized)) {
+    const catName = CATEGORY_DISPLAY_NAMES[catKey] || catKey;
+    lines.push(`    - [${catName}]: ${items.join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Resolve taxonomy from genreId, subgenreId, and tagIdList
+ */
+function resolveTaxonomyFromIDs(genreId, subgenreId, tagIdList = []) {
+  const { genresMap, subgenresMap, tagsMap } = buildIndex();
+
+  let genre = null;
+  let subgenre = null;
+
+  if (genreId && genresMap.has(genreId)) {
+    genre = genresMap.get(genreId);
+  }
+  if (subgenreId && subgenresMap.has(subgenreId)) {
+    subgenre = subgenresMap.get(subgenreId);
+    if (!genre && subgenre.genre_id && genresMap.has(subgenre.genre_id)) {
+      genre = genresMap.get(subgenre.genre_id);
+    }
+  }
+
+  if (!genre) {
+    genre = genresMap.get('utilities') || { id: 'utilities', name: 'Utilities', type: 'App' };
+  }
+  if (!subgenre) {
+    subgenre = subgenresMap.get('developer_tools') || { id: 'developer_tools', name: 'Developer Tools' };
+  }
+
+  const feature_tags = [];
+  for (const tid of tagIdList) {
+    if (tagsMap.has(tid)) {
+      const t = tagsMap.get(tid);
+      feature_tags.push({
+        tag_id: t.tag_id,
+        name: t.name,
+        category: t.category,
+        category_name: CATEGORY_DISPLAY_NAMES[t.category] || t.category,
+      });
+    } else {
+      feature_tags.push({
+        tag_id: tid,
+        name: tid.replace(/_/g, ' '),
+        category: 'core_features',
+        category_name: 'Core Features',
+      });
+    }
+  }
+
+  return {
+    genre: {
+      id: genre.id,
+      name: genre.name,
+      type: genre.type || 'App',
+    },
+    subgenre: {
+      id: subgenre.id,
+      name: subgenre.name,
+    },
+    feature_tags,
+    feature_tag_ids: tagIdList,
+  };
+}
+
+module.exports = {
+  loadTaxonomy,
+  buildIndex,
+  inferTaxonomy,
+  formatTaxonomySummary,
+  resolveTaxonomyFromIDs,
+  CATEGORY_DISPLAY_NAMES,
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@shiplens/cli",
+  "version": "1.2.7",
+  "description": "Shiplens CLI (In Development) - 15-second zero-config analytics initialization and full telemetry analysis engine",
+  "main": "lib/index.js",
+  "bin": {
+    "shiplens-cli": "bin/shiplens.js",
+    "shiplens": "bin/shiplens.js"
+  },
+  "keywords": [
+    "shiplens",
+    "analytics",
+    "cli",
+    "telemetry",
+    "heatmap",
+    "dashboard",
+    "growth",
+    "agent",
+    "mcp",
+    "prompts"
+  ],
+  "author": "Shiplens Team",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hyperlong/shiplens-cli.git"
+  },
+  "homepage": "https://shiplens.dev",
+  "scripts": {
+    "test": "node test/cli.test.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "prompts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prompts/README.md

@@ -0,0 +1,21 @@
+# Shiplens Prompt Libraries
+
+This directory hosts the deterministic CLI scenario-based prompt libraries for Shiplens.
+
+---
+
+## 📁 Directory Structure
+
+```text
+prompts/
+├── README.md                 # Multilingual architecture overview
+├── prompts_cli_en.md         # [English - Official] Deterministic CLI execution presets (42 Scenarios)
+└── ...                       # Future language extensions (ja, ko, de, fr, es, etc.)
+```
+
+---
+
+## ⚡ Execution & Dynamic Overrides
+
+1. **Deterministic Execution**: Every scenario in `prompts_cli_en.md` provides explicit, reproducible CLI commands and SQL queries paired with textbook analytical foundations.
+2. **Dynamic Overrides**: Local rules defined in `.shiplens/learnings.md` override default parameters (such as `--range`, `--grain`, or target funnel routes) during AI Agent execution.