@shiplens/cli 1.2.7

package/lib/auth.js

@@ -0,0 +1,107 @@
+const fs = require('fs');
+const path = require('path');
+const { getGlobalConfig, saveGlobalConfig } = require('./config');
+
+function maskSecret(secret) {
+  if (!secret || secret.length <= 8) {
+    return '******';
+  }
+  const prefixLen = secret.length < 12 ? 3 : 7;
+  const suffixLen = 4;
+  if (secret.length < prefixLen + suffixLen) {
+    return secret.slice(0, 3) + '...' + secret.slice(-2);
+  }
+  return secret.slice(0, prefixLen) + '...' + secret.slice(-suffixLen);
+}
+
+function readDotEnvSecret(dir = process.cwd()) {
+  const envFiles = [path.join(dir, '.shiplens.env'), path.join(dir, '.env')];
+  for (const f of envFiles) {
+    if (fs.existsSync(f)) {
+      try {
+        const content = fs.readFileSync(f, 'utf8');
+        const lines = content.split('\n');
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (trimmed.startsWith('#') || !trimmed.includes('=')) continue;
+          const [k, ...v] = trimmed.split('=');
+          const key = k.trim();
+          const val = v.join('=').trim().replace(/^["']|["']$/g, '');
+          if (key === 'SHIPLENS_ACCESS_SECRET' || key === 'SHIPLENS_MCP_TOKEN') {
+            return val;
+          }
+        }
+      } catch (e) {}
+    }
+  }
+  return '';
+}
+
+function resolveSecret(explicitSecret) {
+  if (explicitSecret) {
+    return {
+      secret: explicitSecret,
+      masked_secret: maskSecret(explicitSecret),
+      source: 'flag',
+      is_present: true,
+    };
+  }
+
+  const envSec = process.env.SHIPLENS_ACCESS_SECRET || process.env.SHIPLENS_MCP_TOKEN;
+  if (envSec) {
+    return {
+      secret: envSec,
+      masked_secret: maskSecret(envSec),
+      source: 'environment',
+      is_present: true,
+    };
+  }
+
+  const dotEnvSec = readDotEnvSecret();
+  if (dotEnvSec) {
+    return {
+      secret: dotEnvSec,
+      masked_secret: maskSecret(dotEnvSec),
+      source: 'dotenv',
+      is_present: true,
+    };
+  }
+
+  const gCfg = getGlobalConfig();
+  if (gCfg && gCfg.secret) {
+    return {
+      secret: gCfg.secret,
+      masked_secret: maskSecret(gCfg.secret),
+      source: 'config',
+      is_present: true,
+    };
+  }
+
+  return {
+    secret: '',
+    masked_secret: '',
+    source: 'none',
+    is_present: false,
+  };
+}
+
+function saveSecretToGlobal(secret, email = '', userId = '') {
+  const gCfg = getGlobalConfig();
+  gCfg.secret = secret;
+  if (email) gCfg.email = email;
+  if (userId) gCfg.user_id = userId;
+  saveGlobalConfig(gCfg);
+}
+
+function clearGlobalSecret() {
+  const gCfg = getGlobalConfig();
+  gCfg.secret = '';
+  saveGlobalConfig(gCfg);
+}
+
+module.exports = {
+  maskSecret,
+  resolveSecret,
+  saveSecretToGlobal,
+  clearGlobalSecret,
+};

package/lib/cli.js

@@ -0,0 +1,258 @@
+const { APIClient } = require('./api');
+const { resolveSecret } = require('./auth');
+const { getLocalConfig } = require('./config');
+
+const { handleInit } = require('./commands/init');
+const { handleAuth } = require('./commands/auth');
+const { handleProjects } = require('./commands/projects');
+const { handleQuery } = require('./commands/query');
+const { handleSQL } = require('./commands/sql');
+const { handleSummary } = require('./commands/summary');
+const { handlePages, handlePaths, handleCanvas } = require('./commands/pages');
+const { handleHeatmap } = require('./commands/heatmap');
+const { handleDashboards } = require('./commands/dashboards');
+const { handleDoctor } = require('./commands/doctor');
+const { handleContext } = require('./commands/context');
+const { handleMcp } = require('./commands/mcp');
+
+const VERSION = '1.2.7';
+
+function parseArgs(argv) {
+  const flags = {};
+  const args = [];
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const equalIndex = arg.indexOf('=');
+      if (equalIndex !== -1) {
+        const key = arg.slice(2, equalIndex);
+        const val = arg.slice(equalIndex + 1);
+        if (flags[key]) {
+          if (Array.isArray(flags[key])) flags[key].push(val);
+          else flags[key] = [flags[key], val];
+        } else {
+          flags[key] = val;
+        }
+      } else {
+        const key = arg.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith('-')) {
+          if (flags[key]) {
+            if (Array.isArray(flags[key])) flags[key].push(next);
+            else flags[key] = [flags[key], next];
+          } else {
+            flags[key] = next;
+          }
+          i++;
+        } else {
+          flags[key] = true;
+        }
+      }
+    } else if (arg.startsWith('-')) {
+      const key = arg.slice(1);
+      if (key === 'v') flags.version = true;
+      else if (key === 'h') flags.help = true;
+      else flags[key] = true;
+    } else {
+      args.push(arg);
+    }
+    i++;
+  }
+
+  return { args, flags };
+}
+
+function printHelp() {
+  console.log(`Shiplens CLI - High-Speed User Telemetry & SDK Management Tool (v${VERSION})
+
+Usage:
+  shiplens <command> [subcommand] [options]
+  npx.cmd --yes shiplens-cli <command> [subcommand] [options]   (Windows)
+  npx --yes shiplens-cli <command> [subcommand] [options]        (macOS/Linux)
+
+Core Commands:
+  init          15-second zero-config analytics initialization & dashboard setup
+  auth          Authentication & credentials (status, set, secret, whoami, logout, bind, mcp-config, configure)
+  projects      Project management (list, bind, delete)
+  query         Multi-dimensional metrics and conversion funnel queries
+  sql           Execute secure read-only SQL queries on ClickHouse
+  summary       Retrieve product overview (traffic, bounce rates, geos, devices)
+  pages         Inspect page-level visits and average dwell times
+  paths         Analyze user flow journeys and Sankey transition paths
+  canvas        Retrieve global user behavior canvas topology
+  heatmap       Retrieve click heatmaps and skeleton wireframes
+  dashboards    AI dashboard management and one-click creation (list, create [--ai])
+  doctor        Run full end-to-end diagnostics on SDK, credentials, and network
+  context       Manage business context dictionary (push, pull, show)
+  mcp serve     Run local MCP proxy server with device credentials
+
+auth Subcommands:
+  auth status                          Check credential validity
+  auth set [--secret-stdin]            Save Access Secret
+  auth secret list                     List Access Secrets (masked)
+  auth secret create [--scopes ...]    Create scoped offline Access Secret
+  auth secret revoke --key-id <id>     Revoke offline Access Secret
+  auth whoami                          Display current authenticated user
+  auth logout                          Clear local credentials
+  auth bind --email <email> [--json]   Send Magic Link email for account binding
+  auth mcp-config [--client <client>]  Print MCP configuration (cursor/codex/claude/antigravity/manual)
+  auth configure --client <client>     Write MCP configuration into target client
+  auth configure --client manual       Output standard MCP JSON configuration
+
+init Dedicated Options:
+  --name <string>        Project name (default: auto-read from package.json)
+  --description <string> Project functional description & positioning
+  --genre <id>           Level 1 category ID (e.g. utilities, finance, casual_games)
+  --subgenre <id>        Level 2 subcategory ID (e.g. developer_tools, financial_tools)
+  --tags <ids>           Level 4 feature tags (comma-separated tag_ids)
+  --industry <string>    Compatibility industry category field
+  --email <email|auto>   Auto or manual binding email
+
+Global Options:
+  --json             Output in standard JSON format (required for AI Agents)
+  --force            Force overwrite existing local configuration and project ID
+  --no-commit        Skip automatic Git commit after initialization
+  --app-id <id>      Explicitly specify target project app_id
+  --env <env>        Target environment (production / staging, default: production)
+  --secret <key>     Pass Access Secret explicitly
+  --api-url <url>    Custom backend API base URL (default: http://120.26.230.33)
+  -v, --version      Display CLI version
+  -h, --help         Display help information
+`);
+}
+
+async function runCLI(argv = process.argv.slice(2)) {
+  const { args, flags } = parseArgs(argv);
+
+  if (flags.version || (args.length === 0 && flags.v)) {
+    if (flags.json) {
+      console.log(JSON.stringify({ ok: true, version: VERSION }));
+    } else {
+      console.log(`shiplens v${VERSION}`);
+    }
+    return;
+  }
+
+  if (flags.help || args.length === 0 || args[0] === 'help') {
+    printHelp();
+    return;
+  }
+
+  const isJSON = Boolean(flags.json);
+
+  const output = (data, textFormatter) => {
+    if (isJSON) {
+      console.log(JSON.stringify(data, null, 2));
+    } else if (textFormatter) {
+      textFormatter();
+    } else {
+      console.log(JSON.stringify(data, null, 2));
+    }
+  };
+
+  const outputError = (err) => {
+    const code = err.code || 'INTERNAL_ERROR';
+    if (isJSON) {
+      console.log(JSON.stringify({
+        ok: false,
+        code,
+        message: err.message,
+        status: err.status,
+      }, null, 2));
+    } else {
+      console.error(`❌ Error [${code}]: ${err.message}`);
+    }
+    process.exitCode = 1;
+  };
+
+  // Resolve credentials and API client
+  const resolvedAuth = resolveSecret(flags.secret);
+  let apiUrl = flags['api-url'] || process.env.SHIPLENS_API_URL;
+  if (!apiUrl) {
+    const localCfg = getLocalConfig();
+    if (localCfg && localCfg.api_url) apiUrl = localCfg.api_url;
+  }
+  if (!apiUrl) apiUrl = 'http://120.26.230.33';
+
+  const client = new APIClient(apiUrl, resolvedAuth.secret);
+
+  const resolveAppId = () => {
+    if (flags['app-id']) return flags['app-id'];
+    const localCfg = getLocalConfig();
+    if (localCfg && localCfg.app_id) return localCfg.app_id;
+    const err = new Error('Target app_id not found. Provide --app-id or run inside an initialized project directory.');
+    err.code = 'APP_NOT_FOUND';
+    throw err;
+  };
+
+  const ctx = {
+    client,
+    resolvedAuth,
+    resolveAppId,
+    output,
+    isJSON,
+  };
+
+  const command = args[0];
+  const subcommand = args[1];
+  const cmdArgs = args.slice(1);
+
+  try {
+    switch (command) {
+      case 'init':
+        await handleInit(cmdArgs, flags, ctx);
+        break;
+      case 'auth':
+        await handleAuth(subcommand || 'status', args.slice(2), flags, ctx);
+        break;
+      case 'projects':
+        await handleProjects(subcommand || 'list', args.slice(2), flags, ctx);
+        break;
+      case 'query':
+        await handleQuery(cmdArgs, flags, ctx);
+        break;
+      case 'sql':
+        await handleSQL(cmdArgs, flags, ctx);
+        break;
+      case 'summary':
+        await handleSummary(cmdArgs, flags, ctx);
+        break;
+      case 'pages':
+        await handlePages(cmdArgs, flags, ctx);
+        break;
+      case 'paths':
+        await handlePaths(cmdArgs, flags, ctx);
+        break;
+      case 'canvas':
+        await handleCanvas(cmdArgs, flags, ctx);
+        break;
+      case 'heatmap':
+        await handleHeatmap(cmdArgs, flags, ctx);
+        break;
+      case 'dashboards':
+        await handleDashboards(subcommand || 'list', args.slice(2), flags, ctx);
+        break;
+      case 'doctor':
+        await handleDoctor(cmdArgs, flags, ctx);
+        break;
+      case 'context':
+        await handleContext(subcommand || 'show', args.slice(2), flags, ctx);
+        break;
+      case 'mcp':
+        await handleMcp(subcommand || 'serve');
+        break;
+      default:
+        throw new Error(`Unknown command: ${command}. Use shiplens --help to view supported commands.`);
+    }
+  } catch (err) {
+    outputError(err);
+  }
+}
+
+module.exports = {
+  runCLI,
+  parseArgs,
+  VERSION,
+};

package/lib/commands/auth.js

@@ -0,0 +1,242 @@
+const readline = require('readline');
+const { getDeviceEnv } = require('../config');
+const { saveDeviceEnv } = require('../device-env');
+const { CLIENTS, getMcpConfig, configureMcpClient } = require('../mcp-config');
+const { saveSecretToGlobal, clearGlobalSecret, maskSecret } = require('../auth');
+const { APIClient } = require('../api');
+
+async function handleAuth(subcommand, args, flags, ctx) {
+  switch (subcommand) {
+    case 'status': {
+      const deviceEnv = getDeviceEnv();
+      if (deviceEnv) {
+        return ctx.output({ ok: true, authenticated: false, device_env: 'present', mcp_url: deviceEnv.SHIPLENS_MCP_URL, next: 'Use shiplens auth mcp-config, then complete OAuth in your Agent.' }, () => {
+          console.log(`✅ shiplens.env detected; MCP: ${deviceEnv.SHIPLENS_MCP_URL}`);
+          console.log('Complete OAuth login in your Agent before using MCP.');
+        });
+      }
+      if (!ctx.resolvedAuth.is_present) {
+        return ctx.output({
+          ok: false,
+          authenticated: false,
+          message: 'No credentials detected. Configure via shiplens auth set.',
+        }, () => {
+          console.log('⚠️ No valid credentials configured. Run: shiplens auth set');
+        });
+      }
+
+      try {
+        const meResp = await ctx.client.me();
+        ctx.output({
+          ok: true,
+          authenticated: true,
+          source: ctx.resolvedAuth.source,
+          masked_secret: ctx.resolvedAuth.masked_secret,
+          user_id: meResp.user_id,
+          email: meResp.email,
+          last_verified_at: new Date().toISOString(),
+        }, () => {
+          console.log('✅ Authentication valid');
+          console.log(`👤 User ID: ${meResp.user_id} | Email: ${meResp.email}`);
+          console.log(`🔑 Secret Source: ${ctx.resolvedAuth.source} (${ctx.resolvedAuth.masked_secret})`);
+        });
+      } catch (err) {
+        ctx.output({
+          ok: false,
+          authenticated: false,
+          source: ctx.resolvedAuth.source,
+          masked_secret: ctx.resolvedAuth.masked_secret,
+          error: err.message,
+        }, () => {
+          console.log(`❌ Credential verification failed: ${err.message}`);
+        });
+      }
+      break;
+    }
+
+    case 'mcp-config': {
+      const deviceEnv = getDeviceEnv();
+      if (!deviceEnv) throw new Error('shiplens.env not found. Run shiplens auth bind and complete email activation first.');
+      const client = flags.client || 'manual';
+      if (!CLIENTS.includes(client)) throw new Error(`Unsupported MCP client: ${client}. Supported: ${CLIENTS.join(', ')}`);
+      const config = getMcpConfig(client, deviceEnv.SHIPLENS_MCP_URL);
+      ctx.output({ ok: true, mcp_config: config, oauth_required: true }, () => console.log(JSON.stringify(config, null, 2)));
+      break;
+    }
+
+    case 'configure': {
+      const deviceEnv = getDeviceEnv();
+      if (!deviceEnv) throw new Error('shiplens.env not found. Run shiplens auth bind and complete email activation first.');
+      const client = flags.client || args[0];
+      if (!CLIENTS.includes(client)) throw new Error(`Specify target MCP client via --client: ${CLIENTS.join(', ')}`);
+      const result = configureMcpClient(client, deviceEnv.SHIPLENS_MCP_URL);
+      ctx.output({ ok: true, client, oauth_required: true, ...result }, () => {
+        if (client === 'manual') {
+          console.log(JSON.stringify(result.config, null, 2));
+          return;
+        }
+        console.log(result.written ? `✅ Shiplens MCP configuration written to ${client}.` : 'ℹ️ Shiplens MCP config already exists, unchanged.');
+        console.log('Complete OAuth login in your Agent MCP panel.');
+      });
+      break;
+    }
+
+    case 'set': {
+      let secret = '';
+      if (flags['secret-stdin']) {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+          chunks.push(chunk);
+        }
+        secret = Buffer.concat(chunks).toString('utf8').trim();
+      } else if (args.length > 0) {
+        secret = args[0].trim();
+      } else if (flags.secret) {
+        secret = flags.secret.trim();
+      } else {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        secret = await new Promise((resolve) => {
+          rl.question('Enter Shiplens Access Secret: ', (ans) => {
+            rl.close();
+            resolve(ans.trim());
+          });
+        });
+      }
+
+      if (!secret) {
+        throw new Error('Access Secret cannot be empty.');
+      }
+
+      const tempClient = new APIClient(ctx.client.baseURL, secret);
+      let email = '';
+      let userId = '';
+      try {
+        const meResp = await tempClient.me();
+        email = meResp.email || '';
+        userId = meResp.user_id || '';
+      } catch (e) {}
+
+      saveSecretToGlobal(secret, email, userId);
+
+      ctx.output({
+        ok: true,
+        masked_secret: maskSecret(secret),
+        email: email || undefined,
+        user_id: userId || undefined,
+        message: 'Access Secret saved securely to ~/.shiplens/config.json',
+      }, () => {
+        console.log(`✅ Access Secret saved: ${maskSecret(secret)}`);
+        if (email) console.log(`👤 Bound User: ${email} (${userId})`);
+      });
+      break;
+    }
+
+    case 'secret': {
+      const action = args[0] || 'list';
+      if (!ctx.resolvedAuth.is_present) throw new Error('Run auth set first to configure an Access Secret with administrative rights.');
+      if (action === 'list') {
+        const response = await ctx.client.listAccessSecrets();
+        return ctx.output({ ok: true, access_secrets: response.api_keys || [] }, () => console.log(JSON.stringify(response.api_keys || [], null, 2)));
+      }
+      if (action === 'create') {
+        const scopes = flags.scopes ? String(flags.scopes).split(',').map((scope) => scope.trim()).filter(Boolean) : undefined;
+        const response = await ctx.client.createAccessSecret({ app_id: flags['app-id'], scopes, expires_at: flags.expires });
+        saveSecretToGlobal(response.api_key);
+        return ctx.output({ ok: true, api_key_id: response.api_key_id, api_key_preview: response.api_key_preview, app_id: response.app_id, scopes: response.scopes, expires_at: response.expires_at, saved_to_global_config: true }, () => {
+          console.log(`✅ Offline Access Secret created and saved (${response.api_key_preview}).`);
+        });
+      }
+      if (action === 'revoke') {
+        const apiKeyId = flags['key-id'] || args[1];
+        if (!apiKeyId) throw new Error('Provide --key-id <api_key_id>.');
+        const response = await ctx.client.revokeAccessSecret(apiKeyId);
+        return ctx.output({ ok: true, ...response }, () => console.log(`✅ Revoked Access Secret: ${response.api_key_id}`));
+      }
+      throw new Error('Supported auth secret subcommands: list, create, revoke');
+    }
+
+    case 'whoami': {
+      const meResp = await ctx.client.me();
+      ctx.output(meResp, () => {
+        console.log(`👤 User ID: ${meResp.user_id}`);
+        console.log(`📧 Email: ${meResp.email}`);
+        if (meResp.project_count) {
+          console.log(`📦 Projects Count: ${meResp.project_count}`);
+        }
+      });
+      break;
+    }
+
+    case 'logout': {
+      clearGlobalSecret();
+      ctx.output({
+        ok: true,
+        message: 'Logged out successfully. Local credentials cleared.',
+      }, () => {
+        console.log('🚪 Logged out successfully. Local credentials cleared.');
+      });
+      break;
+    }
+
+    case 'bind': {
+      const email = flags.email || args[0];
+      if (!email || !email.includes('@')) {
+        const err = new Error('Provide a valid email address, e.g.: shiplens auth bind --email you@company.com');
+        err.code = 'INVALID_EMAIL';
+        throw err;
+      }
+
+      const { getLocalConfig } = require('../config');
+      const localCfg = getLocalConfig() || {};
+      const appId = flags['app-id'] || localCfg.app_id || '';
+      const projectName = localCfg.project_name || '';
+
+      let resp;
+      try {
+        resp = await ctx.client.startEmailWithRetry({
+          email,
+          project_id: appId || undefined,
+          project_name: projectName || undefined,
+          client_name: 'Shiplens CLI',
+          device_os: process.platform,
+          device_name: require('os').hostname(),
+        });
+      } catch (err) {
+        ctx.output({
+          ok: false,
+          magic_link_sent: false,
+          email,
+          app_id: appId || undefined,
+          code: err.code || 'NETWORK_FAILED',
+          message: err.message,
+        }, () => {
+          console.error(`❌ Failed to send email [${err.code || 'NETWORK_FAILED'}]: ${err.message}`);
+        });
+        process.exitCode = 1;
+        return;
+      }
+
+      const envPath = saveDeviceEnv(resp.shiplens_env);
+
+      ctx.output({
+        ok: true,
+        magic_link_sent: true,
+        email,
+        app_id: appId || undefined,
+        project_name: projectName || undefined,
+        shiplens_env_written: Boolean(envPath),
+        message: `Activation email sent to ${email}. Click the link to complete registration.`,
+      }, () => {
+        console.log(`📧 Activation email sent to: ${email}`);
+        if (appId) console.log(`📦 Bound App ID: ${appId}`);
+        console.log('👉 Click the link in your email to activate your 50,000 monthly free events quota.');
+      });
+      break;
+    }
+
+    default:
+      throw new Error(`Unknown auth subcommand: ${subcommand}. Supported: status, set, secret, whoami, logout, bind, mcp-config, configure`);
+  }
+}
+
+module.exports = { handleAuth };