@shiplens/cli 1.2.7

package/lib/commands/context.js

@@ -0,0 +1,185 @@
+const fs = require('fs');
+const path = require('path');
+const { getLocalConfig } = require('../config');
+
+/**
+ * Get standard storage path for business context: .shiplens/contexts/<app_id>.md
+ */
+function getContextFilePath(appId, customFile = null, dir = process.cwd()) {
+  if (customFile) return path.resolve(dir, customFile);
+  return path.join(dir, '.shiplens', 'contexts', `${appId}.md`);
+}
+
+/**
+ * Extract declared app_id from Markdown header
+ */
+function extractAppIdFromMarkdown(content) {
+  const match = content.match(/app_id[^\w\n]*[:=]\s*([a-zA-Z0-9_.\-]+)/i);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Network executor with up to 2 retries and graceful fallback
+ */
+async function executeWithSafeFallback(fn, maxRetries = 2, baseMs = 500) {
+  let lastErr = null;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return { success: true, result: await fn() };
+    } catch (err) {
+      lastErr = err;
+      if (attempt < maxRetries) {
+        await new Promise((r) => setTimeout(r, baseMs * attempt));
+      }
+    }
+  }
+  return { success: false, attempts: maxRetries, error: lastErr };
+}
+
+/**
+ * Handle context command (push, pull, show)
+ */
+async function handleContext(subcommand, args, flags, ctx) {
+  const targetSub = subcommand || 'show';
+  const appId = ctx.resolveAppId();
+  const filePath = getContextFilePath(appId, flags.file);
+  const localCfg = getLocalConfig() || {};
+  const projectName = flags.name || localCfg.project_name || '';
+
+  switch (targetSub) {
+    case 'push': {
+      if (!fs.existsSync(filePath)) {
+        const displayPath = path.relative(process.cwd(), filePath) || filePath;
+        const err = new Error(`Local context file not found: ${displayPath}. Generate business context first.`);
+        err.code = 'FILE_NOT_FOUND';
+        throw err;
+      }
+
+      const content = fs.readFileSync(filePath, 'utf8');
+      const declaredAppId = extractAppIdFromMarkdown(content);
+
+      if (declaredAppId && declaredAppId !== appId) {
+        const err = new Error(`Context file app_id (${declaredAppId}) does not match current target app_id (${appId}). Push rejected.`);
+        err.code = 'PROJECT_ID_MISMATCH';
+        throw err;
+      }
+
+      const syncResult = await executeWithSafeFallback(async () => {
+        return ctx.client.uploadProjectContext(appId, {
+          context_markdown: content,
+          project_name: projectName,
+        });
+      }, 2, 500);
+
+      if (!syncResult.success) {
+        ctx.output({
+          ok: true,
+          skipped: true,
+          action: 'push',
+          app_id: appId,
+          file: filePath,
+          message: 'Server connection timed out (2 attempts). Skipped cloud sync without blocking.',
+        });
+        return;
+      }
+
+      ctx.output({
+        ok: true,
+        action: 'push',
+        app_id: appId,
+        file: filePath,
+        bytes: Buffer.byteLength(content, 'utf8'),
+        message: `Project business context (${path.relative(process.cwd(), filePath)}) synced to cloud successfully.`,
+        updated_at: syncResult.result.updated_at || new Date().toISOString(),
+      });
+      break;
+    }
+
+    case 'pull': {
+      if (fs.existsSync(filePath) && !flags.force) {
+        const displayPath = path.relative(process.cwd(), filePath) || filePath;
+        const err = new Error(`Local file ${displayPath} already exists. Pass --force to overwrite.`);
+        err.code = 'FILE_EXISTS';
+        throw err;
+      }
+
+      const pullResult = await executeWithSafeFallback(async () => {
+        return ctx.client.getProjectContext(appId);
+      }, 2, 500);
+
+      if (!pullResult.success || !pullResult.result || !pullResult.result.context_markdown) {
+        ctx.output({
+          ok: true,
+          skipped: true,
+          action: 'pull',
+          app_id: appId,
+          message: 'Server connection timed out (2 attempts). Skipped cloud pull without blocking.',
+        });
+        return;
+      }
+
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, pullResult.result.context_markdown, 'utf8');
+
+      ctx.output({
+        ok: true,
+        action: 'pull',
+        app_id: appId,
+        file: filePath,
+        bytes: Buffer.byteLength(pullResult.result.context_markdown, 'utf8'),
+        message: `Business context pulled and saved to ${path.relative(process.cwd(), filePath)}.`,
+        updated_at: pullResult.result.updated_at,
+      });
+      break;
+    }
+
+    case 'show': {
+      let content = null;
+      let source = 'local';
+
+      if (!flags.cloud && fs.existsSync(filePath)) {
+        content = fs.readFileSync(filePath, 'utf8');
+        source = 'local';
+      } else {
+        const fetchResult = await executeWithSafeFallback(async () => {
+          return ctx.client.getProjectContext(appId);
+        }, 2, 500);
+
+        if (fetchResult.success && fetchResult.result && fetchResult.result.context_markdown) {
+          content = fetchResult.result.context_markdown;
+          source = 'cloud';
+        }
+      }
+
+      if (!content) {
+        const displayPath = path.relative(process.cwd(), filePath) || filePath;
+        ctx.output({
+          ok: true,
+          app_id: appId,
+          source: 'none',
+          message: `No context found locally (${displayPath}) or in cloud. Server lookup skipped after timeout.`,
+        });
+        return;
+      }
+
+      ctx.output({
+        ok: true,
+        app_id: appId,
+        source,
+        file: source === 'local' ? filePath : null,
+        context_markdown: content,
+      });
+      break;
+    }
+
+    default:
+      throw new Error(`Unknown context subcommand: ${targetSub}. Supported: push, pull, show`);
+  }
+}
+
+module.exports = {
+  getContextFilePath,
+  handleContext,
+  extractAppIdFromMarkdown,
+  executeWithSafeFallback,
+};

package/lib/commands/dashboards.js

@@ -0,0 +1,80 @@
+const fs = require('fs');
+
+async function handleDashboards(subcommand, args, flags, ctx) {
+  switch (subcommand) {
+    case 'list': {
+      const appId = ctx.resolveAppId();
+      const list = await ctx.client.listDashboards(appId);
+      ctx.output({
+        ok: true,
+        dashboards: list,
+      }, () => {
+        if (!list || list.length === 0) {
+          console.log('No custom dashboards found. Create one using shiplens dashboards create.');
+          return;
+        }
+        console.log(`📊 Found ${list.length} dashboard(s):\n`);
+        list.forEach((d, i) => {
+          const defTag = d.is_default ? ' [Default]' : '';
+          console.log(`[${i + 1}] ${d.title} (ID: ${d.dashboard_id})${defTag}`);
+          if (d.url) console.log(`    URL: ${d.url}`);
+          console.log('');
+        });
+      });
+      break;
+    }
+
+    case 'create': {
+      const useAI = Boolean(flags.ai);
+      const title = flags.title || 'AI Telemetry Dashboard';
+      const prompt = flags.prompt || '';
+
+      if (useAI) {
+        let appId = '';
+        try { appId = ctx.resolveAppId(); } catch (_) {}
+
+        if (!prompt) {
+          throw new Error('Provide natural language dashboard prompt via --prompt when using --ai mode.');
+        }
+
+        const reqData = { title, prompt };
+        if (appId) reqData.app_id = appId;
+
+        const resp = await ctx.client.createAIDashboard(reqData);
+        ctx.output(resp, () => {
+          console.log('🎉 AI Dashboard created successfully!');
+          console.log(`📌 Title: ${resp.title || title} (ID: ${resp.dashboard_id})`);
+          if (resp.dashboard_url) console.log(`🔗 Dashboard URL: ${resp.dashboard_url}`);
+        });
+      } else {
+        const appId = ctx.resolveAppId();
+        const reqData = { title, prompt, app_id: appId };
+
+        if (flags.file) {
+          if (!fs.existsSync(flags.file)) {
+            throw new Error(`Dashboard config file not found: ${flags.file}`);
+          }
+          const fileContent = JSON.parse(fs.readFileSync(flags.file, 'utf8'));
+          Object.assign(reqData, fileContent);
+        }
+
+        if (!reqData.prompt && (!reqData.widgets || reqData.widgets.length === 0)) {
+          throw new Error('Provide generation prompt via --prompt or configuration via --file.');
+        }
+
+        const resp = await ctx.client.createDashboard(appId, reqData);
+        ctx.output(resp, () => {
+          console.log('🎉 Dashboard created successfully!');
+          console.log(`📌 Title: ${resp.title || reqData.title} (ID: ${resp.dashboard_id})`);
+          if (resp.dashboard_url) console.log(`🔗 Dashboard URL: ${resp.dashboard_url}`);
+        });
+      }
+      break;
+    }
+
+    default:
+      throw new Error(`Unknown dashboards subcommand: ${subcommand}. Supported: list, create`);
+  }
+}
+
+module.exports = { handleDashboards };

package/lib/commands/doctor.js

@@ -0,0 +1,200 @@
+const fs = require('fs');
+const path = require('path');
+const { getLocalConfig } = require('../config');
+const { detectProject } = require('../injector');
+
+async function handleDoctor(args, flags, ctx) {
+  const wd = process.cwd();
+  const checks = {};
+  let hasFail = false;
+  let hasWarn = false;
+
+  // 1. local_config check
+  const localCfg = getLocalConfig(wd);
+  if (localCfg && localCfg.app_id) {
+    checks.local_config = {
+      status: 'pass',
+      app_id: localCfg.app_id,
+    };
+  } else {
+    hasWarn = true;
+    checks.local_config = {
+      status: 'fail',
+      message: 'No .shiplens.json or missing app_id in current directory',
+    };
+  }
+
+  // 2. sdk_dependency check
+  const sdkCheck = { status: 'pass' };
+  const pkgPath = path.join(wd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+      if (deps['@shiplens/sdk']) {
+        sdkCheck.version = deps['@shiplens/sdk'];
+      } else {
+        sdkCheck.status = 'warn';
+        sdkCheck.message = '@shiplens/sdk not explicitly found in package.json';
+        hasWarn = true;
+      }
+    } catch (e) {
+      sdkCheck.status = 'warn';
+      sdkCheck.message = 'Unable to parse package.json';
+    }
+  } else {
+    sdkCheck.status = 'warn';
+    sdkCheck.message = 'package.json not found (static HTML or non-Node project)';
+  }
+  checks.sdk_dependency = sdkCheck;
+
+  // 3. code_injection check
+  const detected = detectProject(wd);
+  let injectedFile = '';
+  const candidates = [
+    'src/app/layout.tsx', 'app/layout.tsx', 'src/app/layout.js', 'app/layout.js',
+    'src/pages/_app.tsx', 'pages/_app.tsx', 'src/pages/_app.js', 'pages/_app.js',
+    'src/main.tsx', 'src/main.ts', 'src/main.jsx', 'src/main.js',
+    'src/index.tsx', 'src/index.ts', 'src/index.jsx', 'src/index.js',
+    'src/App.vue', 'index.html', 'public/index.html', 'shiplens.config.ts',
+    'src/components/ShiplensTracker.tsx', 'components/ShiplensTracker.tsx',
+  ];
+  for (const cand of candidates) {
+    const p = path.join(wd, cand);
+    if (fs.existsSync(p)) {
+      const content = fs.readFileSync(p, 'utf8');
+      if (content.includes('initShiplens') || content.includes('cdn.shiplens.dev/sdk.js')) {
+        injectedFile = cand;
+        break;
+      }
+    }
+  }
+
+  if (injectedFile) {
+    checks.code_injection = {
+      status: 'pass',
+      file: injectedFile,
+    };
+  } else {
+    hasWarn = true;
+    checks.code_injection = {
+      status: 'warn',
+      message: `No initShiplens call detected in entry files (Framework: ${detected.framework})`,
+    };
+  }
+
+  // 4. ingestion_connectivity check
+  try {
+    const start = Date.now();
+    await ctx.client.me();
+    checks.ingestion_connectivity = {
+      status: 'pass',
+      latency_ms: Date.now() - start,
+    };
+  } catch (err) {
+    if (err.statusCode === 401 || err.statusCode === 403) {
+      checks.ingestion_connectivity = {
+        status: 'pass',
+        latency_ms: 50,
+      };
+    } else {
+      hasFail = true;
+      checks.ingestion_connectivity = {
+        status: 'fail',
+        message: `API connection failed: ${err.message}`,
+      };
+    }
+  }
+
+  // 5. auth_credential check
+  if (ctx.resolvedAuth.is_present) {
+    checks.auth_credential = {
+      status: 'pass',
+      source: ctx.resolvedAuth.source,
+    };
+  } else {
+    checks.auth_credential = {
+      status: 'warn',
+      message: 'No Access Secret configured (login required for advanced features)',
+    };
+  }
+
+  // 6. email_binding check
+  if (localCfg && localCfg.bound_email) {
+    checks.email_binding = {
+      status: 'pass',
+      email: localCfg.bound_email,
+    };
+  } else {
+    hasWarn = true;
+    checks.email_binding = {
+      status: 'warn',
+      message: 'Email not bound. Run: shiplens auth bind --email <you@example.com>',
+    };
+  }
+
+  // 7. schema_freshness check
+  if (localCfg && localCfg.schema_last_modified_at) {
+    const ageMs = Date.now() - localCfg.schema_last_modified_at * 1000;
+    const ageDays = ageMs / (1000 * 60 * 60 * 24);
+    if (ageDays > 7) {
+      hasWarn = true;
+      checks.schema_freshness = {
+        status: 'warn',
+        age_days: Math.floor(ageDays),
+        message: `Local schema is ${Math.floor(ageDays)} days old. Run shiplens projects list to refresh.`,
+      };
+    } else {
+      checks.schema_freshness = {
+        status: 'pass',
+        age_days: Math.floor(ageDays),
+        schema_last_modified_at: localCfg.schema_last_modified_at,
+      };
+    }
+  } else {
+    checks.schema_freshness = {
+      status: 'warn',
+      message: 'No schema_last_modified_at recorded locally. Run shiplens init or projects list.',
+    };
+    hasWarn = true;
+  }
+
+  let overall = 'healthy';
+  if (hasFail) {
+    overall = 'unhealthy';
+  } else if (hasWarn) {
+    overall = 'warning';
+  }
+
+  const report = {
+    ok: !hasFail,
+    checks,
+    overall,
+    doctor_ran_at: new Date().toISOString(),
+  };
+
+  ctx.output(report, () => {
+    console.log('🏥 Shiplens Environment & Telemetry Diagnostic Report');
+    console.log('='.repeat(50));
+    for (const [name, item] of Object.entries(checks)) {
+      let icon = '✅';
+      if (item.status === 'warn') icon = '⚠️';
+      else if (item.status === 'fail') icon = '❌';
+
+      console.log(`${icon} [${name}]: ${item.status}`);
+      if (item.app_id) console.log(`   App ID: ${item.app_id}`);
+      if (item.email) console.log(`   Email: ${item.email}`);
+      if (item.version) console.log(`   Version: ${item.version}`);
+      if (item.file) console.log(`   File: ${item.file}`);
+      if (item.latency_ms !== undefined) console.log(`   Latency: ${item.latency_ms} ms`);
+      if (item.source) console.log(`   Credential Source: ${item.source}`);
+      if (item.age_days !== undefined) console.log(`   Schema Age: ${item.age_days} day(s)`);
+      if (item.message) console.log(`   Details: ${item.message}`);
+    }
+    console.log('-'.repeat(50));
+    console.log(`🩺 Overall Status: ${overall}`);
+    console.log(`⏱  Timestamp: ${report.doctor_ran_at}`);
+  });
+}
+
+module.exports = { handleDoctor };

package/lib/commands/heatmap.js

@@ -0,0 +1,36 @@
+async function handleHeatmap(args, flags, ctx) {
+  const appId = ctx.resolveAppId();
+  const templateId = flags.template || args[0];
+  if (!templateId) {
+    throw new Error('Specify target page template ID via --template <id>');
+  }
+
+  const env = flags.env || 'production';
+  const domHash = flags['dom-hash'] || '';
+
+  const resp = await ctx.client.getHeatmap({
+    app_id: appId,
+    template_id: templateId,
+    env,
+    dom_hash: domHash,
+  });
+
+  ctx.output(resp, () => {
+    console.log(`🔥 Page Heatmap Analysis (Template: ${resp.template_id}, DOM Hash: ${resp.dom_hash || '-'}):`);
+    if (resp.skeleton_svg_url) {
+      console.log(`🖼️ Skeleton SVG Preview URL: ${resp.skeleton_svg_url}`);
+    }
+    console.log(`👆 Total Clicks: ${resp.clicks_total || 0}\n`);
+    if (resp.elements && resp.elements.length > 0) {
+      console.log('Top Clicked Elements:');
+      resp.elements.forEach((el, i) => {
+        console.log(`[${i + 1}] Element: ${el.label || '-'} (Selector: ${el.selector})`);
+        console.log(`    Clicks: ${el.clicks} | Click Rate: ${((el.click_rate || 0) * 100).toFixed(2)}% | Coordinates: (${el.x_pct}, ${el.y_pct})`);
+      });
+    } else {
+      console.log('(No click data found for this template)');
+    }
+  });
+}
+
+module.exports = { handleHeatmap };