@shiplens/cli 1.2.7

package/lib/commands/init.js

@@ -0,0 +1,244 @@
+const readline = require('readline');
+const { detectProject, detectExistingApp, injectSDK, injectSkill, installSDKDependency, getGitEmail, autoGitCommit } = require('../injector');
+const { saveLocalConfig } = require('../config');
+const { saveDeviceEnv } = require('../device-env');
+const { resolveTaxonomyFromIDs, formatTaxonomySummary } = require('../taxonomy');
+
+async function handleInit(args, flags, ctx) {
+  const start = Date.now();
+  const wd = process.cwd();
+  const detected = detectProject(wd);
+
+  const projectName = flags.name || detected.project_name || 'My App';
+  const description = flags.description || detected.description || '';
+  const framework = flags.framework || detected.framework;
+
+  // Taxonomy resolution
+  let taxonomy = detected.taxonomy;
+  if (flags.genre || flags.subgenre || flags.tags) {
+    const rawTags = flags.tags ? (Array.isArray(flags.tags) ? flags.tags : flags.tags.split(',').map((t) => t.trim())) : (taxonomy ? taxonomy.feature_tag_ids : []);
+    taxonomy = resolveTaxonomyFromIDs(flags.genre, flags.subgenre, rawTags);
+  }
+
+  const genreId = taxonomy?.genre?.id || 'utilities';
+  const subgenreId = taxonomy?.subgenre?.id || 'browser_web_utility';
+  const featureTagIds = taxonomy?.feature_tag_ids || [];
+  if (featureTagIds.length > 10) {
+    throw new Error('Maximum 10 feature tags allowed.');
+  }
+  const industry = flags.industry || subgenreId || 'saas';
+
+  // 1. Safety check for existing project configuration
+  const existing = detectExistingApp(wd);
+  if (existing.has_existing && !flags.force) {
+    if (ctx.isJSON) {
+      const result = {
+        ok: false,
+        code: 'PROJECT_EXISTS_LOCALLY',
+        message: `Existing Shiplens configuration detected (App ID: ${existing.app_id}) in ${existing.source_file}. Use --force to overwrite.`,
+        existing_app_id: existing.app_id,
+        source_file: existing.source_file,
+        project_name: existing.project_name || projectName,
+        dashboard_url: `${ctx.client.baseURL}/dashboard/${existing.app_id}`,
+      };
+      ctx.output(result);
+      process.exitCode = 1;
+      return;
+    } else {
+      console.log(`\n⚠️  Existing Shiplens project detected!`);
+      console.log(`📌 App ID: ${existing.app_id} (Source: ${existing.source_file})`);
+      console.log(`📊 Dashboard: ${ctx.client.baseURL}/dashboard/${existing.app_id}`);
+      console.log(`\n💡 Option 1 [Recommended]: Keep existing setup and reuse App ID.`);
+      console.log(`💡 Option 2: Run with --force to overwrite and create a new project:`);
+      console.log(`   npx shiplens-cli init --force\n`);
+
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const confirmed = await new Promise((resolve) => {
+        rl.question('Overwrite and create a new project? (y/N): ', (ans) => {
+          rl.close();
+          resolve(ans.trim().toLowerCase() === 'y' || ans.trim().toLowerCase() === 'yes');
+        });
+      });
+      if (!confirmed) {
+        console.log('🛑 Operation cancelled. Existing configuration preserved.');
+        return;
+      }
+    }
+  }
+
+  // 2. Inject AI Skill (.agents/skills/shiplens/SKILL.md & Cursor rules)
+  const skillFile = injectSkill(wd);
+
+  // 3. Register project on cloud
+  let appId = '';
+  let dashboardUrl = '';
+  let accountStatus = 'not_logged_in_unlinked';
+  let accountStatusText = 'Not Logged In (Project unlinked)';
+
+  try {
+    const connResp = await ctx.client.connect({
+      project_name: projectName,
+      description,
+      industry,
+      genre_id: genreId,
+      subgenre_id: subgenreId,
+      feature_tags: featureTagIds.join(','),
+      platform: framework,
+    });
+    appId = connResp.app_id;
+    dashboardUrl = connResp.dashboard_url || `${ctx.client.baseURL}/dashboard/${appId}`;
+
+    if (ctx.resolvedAuth && ctx.resolvedAuth.is_present) {
+      if (connResp.account_linked !== false && connResp.linked !== false && !connResp.unlinked) {
+        accountStatus = 'logged_in_linked';
+        accountStatusText = 'Logged In (Project linked to account)';
+      } else {
+        accountStatus = 'logged_in_unlinked';
+        accountStatusText = 'Logged In (Project not linked to account)';
+      }
+    } else {
+      accountStatus = 'not_logged_in_unlinked';
+      accountStatusText = 'Not Logged In (Project unlinked)';
+    }
+  } catch (netErr) {
+    netErr.code = netErr.code || 'CONNECT_FAILED';
+    throw netErr;
+  }
+
+  // 4. Inject SDK code
+  const injectedFile = injectSDK(wd, framework, appId);
+
+  // 5. Save local configuration
+  saveLocalConfig(wd, {
+    app_id: appId,
+    project_name: projectName,
+    description,
+    industry,
+    genre_id: genreId,
+    subgenre_id: subgenreId,
+    feature_tags: featureTagIds,
+    api_url: ctx.client.baseURL,
+    last_synced_at: new Date().toISOString(),
+  });
+
+  // 6. Install SDK dependency
+  let installResult = { success: true, manager: 'skipped' };
+  if (!flags['no-install'] && detected.package_manager) {
+    installResult = installSDKDependency(wd, detected.package_manager);
+    if (!installResult.success) {
+      const errMsg = `SDK installation failed: Unable to download @shiplens/sdk from npm registry, GitHub mirror, or Shiplens CDN mirror.\n` +
+        `Troubleshooting steps:\n` +
+        `  1. Check your local network connection or HTTP proxy / VPN settings;\n` +
+        `  2. Try running manually: npm install @shiplens/sdk;\n` +
+        `  3. Visit https://shiplens.com for latest SDK status and installation guides.`;
+
+      if (ctx.isJSON) {
+        ctx.output({
+          ok: false,
+          code: 'SDK_INSTALL_FAILED',
+          message: errMsg,
+          error_detail: installResult.error,
+          app_id: appId,
+        });
+      } else {
+        console.error(`\n❌ ${errMsg}\n`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // 7. Bind email if specified
+  let targetEmail = flags.email;
+  if (targetEmail === 'auto') {
+    targetEmail = getGitEmail();
+  }
+  let authStatus = 'pending';
+  if (targetEmail) {
+    try {
+      const emailResponse = await ctx.client.startEmail({
+        email: targetEmail,
+        project_id: appId,
+        project_name: projectName,
+        client_name: 'Shiplens CLI',
+        device_os: process.platform,
+        device_name: require('os').hostname(),
+      });
+      saveDeviceEnv(emailResponse.shiplens_env, wd);
+      authStatus = 'magic_link_sent';
+    } catch (e) {
+      authStatus = 'failed';
+    }
+  }
+
+  // 8. Auto Git commit
+  let gitCommitResult = { committed: false };
+  if (!flags['no-commit']) {
+    gitCommitResult = autoGitCommit(wd, 'feat: Integrate Shiplens SDK and configure dashboard');
+  }
+
+  const elapsed = Date.now() - start;
+  const taxonomyFormatted = formatTaxonomySummary(taxonomy);
+
+  const result = {
+    ok: true,
+    app_id: appId,
+    project_name: projectName,
+    description: description || undefined,
+    taxonomy,
+    dashboard_url: dashboardUrl,
+    framework_detected: framework,
+    injected_file: injectedFile,
+    user_account_status: accountStatus,
+    user_account_text: accountStatusText,
+    sdk_installed: installResult.success,
+    sdk_manager: installResult.manager,
+    skill_injected: true,
+    skill_file: skillFile,
+    package_manager: detected.package_manager,
+    auth_status: authStatus,
+    shiplens_env_written: authStatus === 'magic_link_sent',
+    activation_required: authStatus === 'pending',
+    free_tier_info: '50,000 free events/month (~5,000 unique visitors)',
+    bound_email: targetEmail || undefined,
+    git_committed: gitCommitResult.committed,
+    git_commit_hash: gitCommitResult.hash || undefined,
+    elapsed_ms: elapsed,
+    atomic_completed: true,
+  };
+
+  ctx.output(result, () => {
+    console.log(`\n==================================================`);
+    console.log(`✅ Shiplens SDK successfully integrated (${elapsed} ms)\n`);
+    console.log(`📦 Project & Dashboard Information`);
+    console.log(`Project Name: ${projectName}`);
+    if (description) {
+      console.log(`Description: ${description}`);
+    }
+    if (taxonomyFormatted) {
+      console.log(`Taxonomy:`);
+      console.log(taxonomyFormatted);
+    }
+    console.log(`App ID: ${appId}`);
+    console.log(`Code Injection: Automatically configured in ${injectedFile} (Framework: ${framework})`);
+    console.log(`Live Dashboard / Activation URL: 🔗 ${dashboardUrl}`);
+    console.log(`User Account: ${accountStatusText}`);
+    if (gitCommitResult.committed) {
+      console.log(`Git Commit: Automatically committed changes (Commit: ${gitCommitResult.hash})`);
+    }
+    console.log(`🧠 AI Skill Ready: ${skillFile}`);
+    console.log(`🔒 [SHIPLENS_ATOMIC_COMPLETED] Setup completed atomically. No extra commands needed.`);
+    console.log(`==================================================\n`);
+
+    if (authStatus === 'magic_link_sent' && targetEmail) {
+      console.log(`📧 Activation email sent to: ${targetEmail}`);
+      console.log(`👉 Click the link in your email to activate your 50,000 monthly free events quota and authorize this device.`);
+    } else {
+      console.log(`> [!IMPORTANT]`);
+      console.log(`> **Project Pending Activation (Analytics not active yet)**`);
+      console.log(`> **Please share your email**: Click the link in the email to complete registration, activate 50,000 free monthly events (~5,000 visitors), and bind your project to your account. Once activated, you can chat directly with me to query and analyze product data.`);
+    }
+  });
+}
+
+module.exports = { handleInit };

package/lib/commands/mcp.js

@@ -0,0 +1,65 @@
+const https = require('https');
+const http = require('http');
+const { getDeviceEnv } = require('../config');
+
+function postMcp(url, token, body, sessionId) {
+  const target = new URL(url);
+  const transport = target.protocol === 'https:' ? https : http;
+  return new Promise((resolve, reject) => {
+    const request = transport.request(target, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+        ...(sessionId ? { 'Mcp-Session-Id': sessionId } : {}),
+      },
+    }, (response) => {
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => resolve({
+        status: response.statusCode || 500,
+        contentType: String(response.headers['content-type'] || ''),
+        sessionId: String(response.headers['mcp-session-id'] || sessionId || ''),
+        body: Buffer.concat(chunks).toString('utf8'),
+      }));
+    });
+    request.on('error', reject);
+    request.end(body);
+  });
+}
+
+function emitResponse(result) {
+  const lines = result.contentType.includes('text/event-stream')
+    ? result.body.split(/\r?\n/).filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trim())
+    : [result.body];
+  for (const line of lines) {
+    if (line) process.stdout.write(`${line}\n`);
+  }
+}
+
+async function handleMcp(subcommand) {
+  if (subcommand !== 'serve') throw new Error('Supported mcp subcommand: serve');
+  const deviceEnv = getDeviceEnv();
+  if (!deviceEnv) throw new Error('shiplens.env not found. Run shiplens auth bind and complete email activation first.');
+  let buffer = '';
+  let sessionId = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', async (chunk) => {
+    buffer += chunk;
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() || '';
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const result = await postMcp(deviceEnv.SHIPLENS_MCP_URL, deviceEnv.SHIPLENS_MCP_TOKEN, line, sessionId);
+        sessionId = result.sessionId;
+        emitResponse(result);
+      } catch (error) {
+        process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', error: { code: -32000, message: `Shiplens MCP proxy error: ${error.message}` }, id: null })}\n`);
+      }
+    }
+  });
+}
+
+module.exports = { handleMcp, postMcp, emitResponse };

package/lib/commands/pages.js

@@ -0,0 +1,90 @@
+async function handlePages(args, flags, ctx) {
+  const appId = ctx.resolveAppId();
+  const range = flags.range || '7d';
+  const env = flags.env || 'production';
+  const limit = parseInt(flags.limit || '10', 10);
+
+  const resp = await ctx.client.getPages({ app_id: appId, range, env, limit });
+
+  ctx.output(resp, () => {
+    console.log(`📄 Page Telemetry Evidence (Range: ${range}, Top ${limit}):\n`);
+    const pages = Array.isArray(resp.pages) ? resp.pages : (Array.isArray(resp) ? resp : []);
+    if (pages.length === 0) {
+      console.log('(No page data found. Verify SDK reporting.)');
+      return;
+    }
+    console.log('#   | Path / Title                       | PV      | UV      | Avg Dwell(s)');
+    console.log('--- | ---------------------------------- | ------- | ------- | ------------');
+    pages.forEach((p, i) => {
+      const path = (p.path || p.template_id || '-').padEnd(34);
+      const pv = String(p.pv || p.pageviews || 0).padEnd(7);
+      const uv = String(p.uv || p.unique_visitors || 0).padEnd(7);
+      const dur = String(p.avg_duration_s || p.avg_session_duration_s || 0).padEnd(12);
+      console.log(`[${String(i + 1).padEnd(2)}] | ${path} | ${pv} | ${uv} | ${dur}`);
+    });
+  });
+}
+
+async function handlePaths(args, flags, ctx) {
+  const appId = ctx.resolveAppId();
+  const range = flags.range || '7d';
+  const env = flags.env || 'production';
+
+  const resp = await ctx.client.queryPaths({ app_id: appId, range, env });
+
+  ctx.output(resp, () => {
+    console.log(`🔀 User Flow & Path Analysis (Range: ${range}):\n`);
+
+    if (resp.entry_pages && resp.entry_pages.length > 0) {
+      console.log('▶ Top Entry Pages:');
+      resp.entry_pages.slice(0, 5).forEach((e, i) =>
+        console.log(`  [${i + 1}] ${e.path || e.page} - ${e.sessions || e.count || 0} sessions`)
+      );
+    }
+    if (resp.exit_pages && resp.exit_pages.length > 0) {
+      console.log('\n◀ Top Exit Pages:');
+      resp.exit_pages.slice(0, 5).forEach((e, i) =>
+        console.log(`  [${i + 1}] ${e.path || e.page} - Exit Rate ${((e.exit_rate || 0) * 100).toFixed(1)}%`)
+      );
+    }
+    if (resp.paths && resp.paths.length > 0) {
+      console.log('\n↔ High-Frequency Paths:');
+      resp.paths.slice(0, 8).forEach((p, i) =>
+        console.log(`  [${i + 1}] ${p.from || p.source} → ${p.to || p.target}  (${p.count || p.sessions || 0} times)`)
+      );
+    } else {
+      console.log(JSON.stringify(resp, null, 2));
+    }
+  });
+}
+
+async function handleCanvas(args, flags, ctx) {
+  const appId = ctx.resolveAppId();
+  const range = flags.range || '7d';
+  const env = flags.env || 'production';
+
+  const resp = await ctx.client.queryPaths({ app_id: appId, range, env, mode: 'canvas' });
+
+  ctx.output(resp, () => {
+    console.log(`🎨 User Behavior Canvas Topology (Range: ${range}):\n`);
+    const nodeCount = (resp.nodes || []).length;
+    const edgeCount = (resp.edges || resp.links || []).length;
+    if (nodeCount > 0 || edgeCount > 0) {
+      console.log(`📍 ${nodeCount} nodes, ${edgeCount} edges`);
+      if (resp.nodes && resp.nodes.length > 0) {
+        console.log('\nMain Nodes:');
+        resp.nodes.slice(0, 10).forEach((n, i) =>
+          console.log(`  [${i + 1}] ${n.label || n.path || n.id}  (Visits: ${n.value || n.count || 0})`)
+        );
+      }
+    } else {
+      console.log(JSON.stringify(resp, null, 2));
+    }
+  });
+}
+
+module.exports = {
+  handlePages,
+  handlePaths,
+  handleCanvas,
+};

package/lib/commands/projects.js

@@ -0,0 +1,76 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+async function handleProjects(subcommand, args, flags, ctx) {
+  switch (subcommand) {
+    case 'list': {
+      const resp = await ctx.client.listProjects();
+      ctx.output(resp, () => {
+        const projects = resp.projects || [];
+        if (projects.length === 0) {
+          console.log('No associated projects found. Use shiplens init to create a new project.');
+          return;
+        }
+        console.log(`📦 Found ${projects.length} project(s):\n`);
+        projects.forEach((p, i) => {
+          console.log(`[${i + 1}] ${p.project_name || p.app_name || 'Untitled'} (${p.app_id})`);
+          if (p.description) console.log(`    Description: ${p.description}`);
+          if (p.taxonomy?.subgenre?.name) {
+            const tags = (p.taxonomy.feature_tags || []).map((tag) => tag.name).join(', ');
+            console.log(`    Taxonomy: ${p.taxonomy.genre?.name || '-'} / ${p.taxonomy.subgenre.name}${tags ? ` - ${tags}` : ''}`);
+          }
+          console.log(`    Industry: ${p.industry || '-'} | Status: ${p.status || 'active'} | Schema Timestamp: ${p.schema_last_modified_at || 0}`);
+          if (p.created_at) console.log(`    Created: ${p.created_at}`);
+          console.log('');
+        });
+      });
+      break;
+    }
+
+    case 'bind': {
+      const appId = ctx.resolveAppId();
+      const res = await ctx.client.bindProject(appId, flags.name);
+      ctx.output(res, () => {
+        console.log(`✅ Project ${appId} bound to current account successfully.`);
+      });
+      break;
+    }
+
+    case 'delete': {
+      const appId = ctx.resolveAppId();
+      if (!flags.force) {
+        console.log(`⚠️ Warning: Deleting project ${appId} and all historical event data. This action cannot be undone!`);
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const confirmed = await new Promise((resolve) => {
+          rl.question(`Enter App ID or 'yes' to confirm deletion: `, (ans) => {
+            rl.close();
+            resolve(ans.trim() === 'yes' || ans.trim() === appId);
+          });
+        });
+        if (!confirmed) {
+          console.log('🛑 Operation cancelled.');
+          return;
+        }
+      }
+
+      const res = await ctx.client.deleteProject(appId);
+
+      // Clean up local business context file
+      const localContextPath = path.join(process.cwd(), '.shiplens', 'contexts', `${appId}.md`);
+      if (fs.existsSync(localContextPath)) {
+        try { fs.unlinkSync(localContextPath); } catch {}
+      }
+
+      ctx.output(res, () => {
+        console.log(`🗑️ Project ${appId} deleted successfully.`);
+      });
+      break;
+    }
+
+    default:
+      throw new Error(`Unknown projects subcommand: ${subcommand}. Supported: list, bind, delete`);
+  }
+}
+
+module.exports = { handleProjects };

package/lib/commands/query.js

@@ -0,0 +1,81 @@
+const fs = require('fs');
+
+async function handleQuery(args, flags, ctx) {
+  const appId = ctx.resolveAppId();
+  const range = flags.range || '7d';
+  const grain = flags.grain || 'day';
+  const groupBy = flags['group-by'] || '';
+  const limit = parseInt(flags.limit || '30', 10);
+  const chartType = flags['chart-type'] || 'line';
+  const env = flags.env || 'production';
+
+  let queryReq;
+
+  // Support --file: read full AnalyticsQueryRequest from JSON file
+  if (flags.file) {
+    if (!fs.existsSync(flags.file)) {
+      const err = new Error(`Query config file not found: ${flags.file}`);
+      err.code = 'INVALID_ARGS';
+      throw err;
+    }
+    try {
+      queryReq = JSON.parse(fs.readFileSync(flags.file, 'utf8'));
+    } catch (e) {
+      const err = new Error(`Failed to parse query config file (${flags.file}): ${e.message}`);
+      err.code = 'INVALID_ARGS';
+      throw err;
+    }
+    if (!queryReq.range) queryReq.range = range;
+    if (!queryReq.env) queryReq.env = env;
+  } else {
+    // Support --metrics (comma-separated) or --metric
+    const metricsRaw = flags.metrics || flags.metric || 'pageviews';
+    const metricList = String(metricsRaw).split(',').map((m) => m.trim()).filter(Boolean);
+
+    // Parse --filter key=val
+    const filters = {};
+    const filterList = Array.isArray(flags.filter)
+      ? flags.filter
+      : flags.filter ? [flags.filter] : [];
+    for (const f of filterList) {
+      const [k, ...v] = f.split('=');
+      if (k && v.length > 0) filters[k.trim()] = v.join('=').trim();
+    }
+
+    queryReq = {
+      env,
+      range,
+      panels: metricList.map((metric, idx) => ({
+        panel_id: `panel_cli_${idx}`,
+        title: `${metric} Trend`,
+        metric,
+        chart_type: chartType,
+        time_grain: grain,
+        group_by: groupBy || undefined,
+        filters: Object.keys(filters).length > 0 ? filters : undefined,
+        limit,
+      })),
+    };
+  }
+
+  const resp = await ctx.client.query(appId, queryReq);
+
+  ctx.output(resp, () => {
+    const metricNames = (queryReq.panels || []).map((p) => p.metric).join(', ');
+    console.log(`📊 Query Metrics: ${metricNames} | Range: ${queryReq.range}`);
+    if (resp.data && resp.data.length > 0) {
+      resp.data.forEach((row) => console.log('•', JSON.stringify(row)));
+    } else if (resp.panels && resp.panels.length > 0) {
+      resp.panels.forEach((p) => {
+        console.log(`\n📈 Panel: ${p.title || p.panel_id}`);
+        if (Array.isArray(p.data)) {
+          p.data.forEach((row) => console.log('  •', JSON.stringify(row)));
+        }
+      });
+    } else {
+      console.log('(No matching data found)');
+    }
+  });
+}
+
+module.exports = { handleQuery };

package/lib/commands/sql.js

@@ -0,0 +1,61 @@
+async function handleSQL(args, flags, ctx) {
+  const appId = ctx.resolveAppId();
+  let queryStr = flags.query || flags.sql || args.join(' ');
+
+  // Support --stdin for piped SQL execution
+  if (flags.stdin || flags['read-stdin']) {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    const piped = Buffer.concat(chunks).toString('utf8').trim();
+    if (piped) queryStr = piped;
+  }
+
+  if (!queryStr) {
+    const err = new Error('SQL query string cannot be empty. Pass --query "SELECT ..." or pipe via --stdin.');
+    err.code = 'INVALID_SQL';
+    throw err;
+  }
+
+  const resp = await ctx.client.executeSQL({ app_id: appId, query: queryStr });
+
+  ctx.output(resp, () => {
+    const rowCount = resp.row_count !== undefined ? resp.row_count : (resp.rows ? resp.rows.length : 0);
+    console.log(`🔍 SQL executed successfully (${resp.elapsed_ms || 0} ms, ${rowCount} rows returned):\n`);
+
+    if (resp.columns && resp.columns.length > 0) {
+      const colWidths = resp.columns.map((col) => {
+        let maxW = col.length;
+        if (resp.rows) {
+          resp.rows.forEach((row) => {
+            const cell = row[resp.columns.indexOf(col)];
+            const cellStr = cell === null || cell === undefined ? 'NULL' : String(cell);
+            if (cellStr.length > maxW) maxW = cellStr.length;
+          });
+        }
+        return maxW;
+      });
+
+      const header = resp.columns.map((col, i) => col.padEnd(colWidths[i])).join(' | ');
+      const separator = colWidths.map((w) => '-'.repeat(w)).join('-+-');
+      console.log(header);
+      console.log(separator);
+
+      if (resp.rows && resp.rows.length > 0) {
+        resp.rows.forEach((row) => {
+          const line = resp.columns.map((_, i) => {
+            const cell = row[i];
+            const cellStr = cell === null || cell === undefined ? 'NULL' : String(cell);
+            return cellStr.padEnd(colWidths[i]);
+          }).join(' | ');
+          console.log(line);
+        });
+      }
+    } else if (resp.rows && resp.rows.length > 0) {
+      resp.rows.forEach((row) => console.log(row.join('\t|\t')));
+    }
+  });
+}
+
+module.exports = { handleSQL };

package/lib/commands/summary.js

@@ -0,0 +1,23 @@
+async function handleSummary(args, flags, ctx) {
+  const appId = ctx.resolveAppId();
+  const range = flags.range || '7d';
+  const env = flags.env || 'production';
+
+  const resp = await ctx.client.summary(appId, range, env);
+
+  ctx.output(resp, () => {
+    console.log(`📈 Core Product Summary (Range: ${range}):`);
+    console.log(`• Total Pageviews (PV): ${resp.total_pv || 0}`);
+    console.log(`• Unique Visitors (UV): ${resp.total_uv || 0}`);
+    console.log(`• Avg Session Duration: ${resp.avg_session_duration_s || 0} s`);
+    console.log(`• Bounce Rate: ${((resp.bounce_rate || 0) * 100).toFixed(1)}%`);
+    if (resp.top_countries && resp.top_countries.length > 0) {
+      console.log('• Top Countries:', resp.top_countries);
+    }
+    if (resp.top_devices && resp.top_devices.length > 0) {
+      console.log('• Top Devices:', resp.top_devices);
+    }
+  });
+}
+
+module.exports = { handleSummary };