@shiplens/cli 1.4.4 → 1.4.5

package/lib/assets/actions.json

@@ -649,9 +649,9 @@
       "title": "Shiplens CLI One-Click Setup & Analytics Initialization",
       "suffix": "None",
       "category": "Initial Setup",
-      "prompt": "Set up Shiplens analytics: extract project description, install SDK, create the project, and retrieve the live dashboard URL.",
+      "prompt": "Set up Shiplens analytics: install SDK, create the project, and retrieve the live dashboard URL.",
       "steps": [
-        "1. Run CLI initialization command:\n- Windows: npx.cmd --yes @shiplens/cli init\n- macOS/Linux: npx --yes @shiplens/cli init",
+        "1. Run CLI initialization command:\n- Windows: npx.cmd --yes @shiplens/cli init --json\n- macOS/Linux: npx --yes @shiplens/cli init --json",
         "2. Present the standard project & dashboard summary (including: Project Name, App ID, Code Injection file, User Account Status, Live Dashboard / Activation URL);",
         "3. Immediately prompt the user for their email address (informing them that you will register on their behalf and Shiplens will send an activation email for 50,000 monthly free events and project binding);",
         "4. Upon receiving the user's email, run: npx.cmd --yes @shiplens/cli auth bind --email <email> --json."
@@ -660,12 +660,27 @@
       "foundation": "",
       "source": ""
     },
+    {
+      "id": "setup_bind_project",
+      "title": "Use Shiplens CLI to Install Analytics SDK & Link to Existing Account",
+      "suffix": "None",
+      "category": "Initial Setup",
+      "prompt": "Use Shiplens CLI to install the analytics SDK in this new project and link it to the user's existing Shiplens account:",
+      "steps": [
+        "1. Run the project setup & initialization command:\n- Windows: npx.cmd --yes @shiplens/cli init --json\n- macOS/Linux: npx --yes @shiplens/cli init --json",
+        "2. Inspect returned `user_account_status` and credential states:\n- [Branch A: Logged in & linked] (`logged_in_linked`):\n- [Branch B: No local credentials detected] (`not_logged_in_unlinked` or `activation_required=true`):\n- [Branch C: Account quota / project limit reached] (Error `QUOTA_EXCEEDED` / `PLAN_LIMIT` / unable to link):",
+        "3. Output the final project summary and dashboard link, confirming the project is ready for analytics queries."
+      ],
+      "commands": [],
+      "foundation": "",
+      "source": ""
+    },
     {
       "id": "remove_sdk",
-      "title": "Remove Shiplens SDK & Analytics Data",
+      "title": "Delete Shiplens Project Analytics Data & SDK (No Longer Needed)",
       "suffix": "None",
       "category": "Initial Setup",
-      "prompt": "Remove Shiplens SDK integration and analytics data:",
+      "prompt": "Delete Shiplens project analytics data and SDK integration (analytics no longer needed):",
       "steps": [
         "1. Read `.shiplens.json` in the project root to get project name, app_id, and instrumented file paths.",
         "2. Clearly display the project name and app_id to be deleted, warn the user that historical events and hosted data will be permanently purged, and pause for explicit user confirmation (\"Confirm deleting this project\").",
@@ -678,7 +693,7 @@
     },
     {
       "id": "uninstall_cli",
-      "title": "Uninstall Shiplens CLI",
+      "title": "Delete Shiplens CLI",
       "suffix": "None",
       "category": "Initial Setup",
       "prompt": "Please prioritize calling Shiplens CLI (Action: uninstall_cli) to execute the above requirements. - Windows: npm.cmd uninstall -g @shiplens/cli - macOS/Linux: npm uninstall -g @shiplens/cli",
@@ -689,10 +704,10 @@
     },
     {
       "id": "generate_context",
-      "title": "Generate Context Descriptions for All Pages and Buttons",
+      "title": "Use Shiplens CLI to Generate Context Descriptions for All Pages and Buttons",
       "suffix": "None",
       "category": "Initial Setup",
-      "prompt": "Map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can map numbers and IDs to concrete functionality:",
+      "prompt": "Use Shiplens CLI to map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can understand the business context behind each metric:",
       "steps": [
         "1. Check `./.shiplens.json` for current app_id and project name.",
         "2. Inspect frontend code and routes to extract feature descriptions, user-facing copy, and button texts, locations, and actions.",

package/lib/commands/init.js

@@ -30,49 +30,29 @@ async function handleInit(args, flags, ctx) {
 
   // 1. Safety check for existing project configuration
   const existing = detectExistingApp(wd);
+  let isReusedExisting = false;
+
   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}. ` +
-          `Option 1 [Recommended]: Keep existing statistics and project ID. ` +
-          `Option 2: Use --force to overwrite and request a new App ID from cloud (Note: Old dashboard stops receiving new data).`,
-        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 if (!process.stdin.isTTY) {
-      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(`🛑 Non-interactive terminal detected (CI/Agent). Existing configuration preserved.`);
-      console.log(`💡 Option 1 [Recommended]: Keep existing setup, retain App ID and historical statistics;`);
-      console.log(`💡 Option 2: Overwrite with --force to create a new project:`);
-      console.log(`   npx.cmd --yes @shiplens/cli init --force\n`);
-      return;
+    if (ctx.isJSON || !process.stdin.isTTY) {
+      // Non-interactive or JSON mode (Agent/CI): Fast-forward / Idempotent reuse of existing config
+      isReusedExisting = true;
     } 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, retain App ID and historical statistics;`);
-      console.log(`💡 Option 2: Overwrite with --force to request a brand new App ID from cloud (Note: Old dashboard stops receiving new data, old and new data cannot be merged):`);
+      console.log(`\n💡 Option 1 [Recommended]: Keep existing setup, retain App ID and historical statistics (Press Enter or N);`);
+      console.log(`💡 Option 2: Overwrite with --force to request a brand new App ID from cloud (y):`);
       console.log(`   npx.cmd --yes @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.question('Overwrite and create a brand 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;
+        isReusedExisting = true;
       }
     }
   }
@@ -80,40 +60,52 @@ async function handleInit(args, flags, ctx) {
   // 2. Inject AI Skill (.agents/skills/shiplens/SKILL.md & Agent rules)
   const skillFile = injectSkill(wd);
 
-  // 3. Register project on cloud
+  // 3. Register project on cloud (or reuse existing)
   let appId = '';
   let dashboardUrl = '';
   let accountStatus = 'not_logged_in_unlinked';
   let accountStatusText = 'Not Logged In (Default state after first installation or no valid local credentials)';
 
-  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 (isReusedExisting) {
+    appId = existing.app_id;
+    dashboardUrl = `${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)';
-      }
+      accountStatus = 'logged_in_linked';
+      accountStatusText = 'Logged In (Project linked to account)';
     } else {
       accountStatus = 'not_logged_in_unlinked';
       accountStatusText = 'Not Logged In (Default state after first installation or no valid local credentials)';
     }
-  } catch (netErr) {
-    netErr.code = netErr.code || 'CONNECT_FAILED';
-    throw netErr;
+  } else {
+    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 (Default state after first installation or no valid local credentials)';
+      }
+    } catch (netErr) {
+      netErr.code = netErr.code || 'CONNECT_FAILED';
+      throw netErr;
+    }
   }
 
   // 4. Inject SDK code
@@ -188,6 +180,8 @@ async function handleInit(args, flags, ctx) {
 
   const result = {
     ok: true,
+    reconnected: isReusedExisting,
+    reused_existing: isReusedExisting,
     app_id: appId,
     project_name: projectName,
     description: description || undefined,
@@ -209,12 +203,17 @@ async function handleInit(args, flags, ctx) {
     bound_email: targetEmail || undefined,
     elapsed_ms: elapsed,
     atomic_completed: true,
+    message: isReusedExisting
+      ? `Existing Shiplens project detected and successfully verified (App ID: ${appId}).`
+      : `Shiplens SDK successfully integrated and project created.`,
   };
 
   ctx.output(result, () => {
     console.log(`\n==================================================`);
-    console.log(`✅ Shiplens SDK successfully integrated (${elapsed} ms)\n`);
-    console.log(`📦 Project & Dashboard Information`);
+    console.log(isReusedExisting
+      ? `✅ Shiplens SDK verified & reconnected (${elapsed} ms)\n`
+      : `✅ Shiplens SDK successfully integrated (${elapsed} ms)\n`);
+    console.log(`📦 Project & Dashboard Information` + (isReusedExisting ? ` (Existing setup preserved)` : ''));
     console.log(`Project Name: ${projectName}`);
     if (description) {
       console.log(`Description: ${description}`);

package/lib/injector.js

@@ -394,7 +394,7 @@ async function installSDKDependency(dir, pkgManager = 'npm') {
     },
   ];
 
-  const TIER1_DELAY_MS = 20 * 1000; // 20s
+  const TIER1_DELAY_MS = 5 * 1000; // 5s (fast-forward backup mirrors on high latency)
   const TOTAL_TIMEOUT_MS = 5 * 60 * 1000; // 5min
 
   return new Promise((resolve) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shiplens/cli",
-  "version": "1.4.4",
+  "version": "1.4.5",
   "description": "Shiplens CLI — Automated Web User Analytics & AI Agent Analysis Engine",
   "main": "lib/index.js",
   "bin": {

package/prompts/prompts_cli_en-US.md

@@ -2,7 +2,7 @@
 
 ---
 
-## Scenario Outline (42 Scenarios)
+## Scenario Outline (43 Scenarios)
 
 > **How to use**: Scan this outline to find the matching scenario, then jump to its full section below for deterministic CLI commands and analysis steps.
 
@@ -61,16 +61,17 @@
 34. [Track and Measure User Aha Moment](#track-and-measure-user-aha-moment)
 35. [Track Subscription Revenue & Build Daily Subscription Dashboard](#track-subscription-revenue--build-daily-subscription-dashboard)
 
-### Initial Setup (4)
-36. [Shiplens CLI One-Click Setup & Analytics Initialization](#shiplens-cli-one-click-setup--analytics-initialization)
-37. [Remove Shiplens SDK & Analytics Data](#remove-shiplens-sdk--analytics-data)
-38. [Uninstall Shiplens CLI](#uninstall-shiplens-cli)
-39. [Generate Context Descriptions for All Pages and Buttons](#generate-context-descriptions-for-all-pages-and-buttons)
+### Initial Setup (5)
+36. [Shiplens CLI One-Click Setup & Analytics Initialization](#shiplens-cli-one-click-setup-analytics-initialization)
+37. [Use Shiplens CLI to Install Analytics SDK & Link to Existing Account](#use-shiplens-cli-to-install-analytics-sdk-link-to-existing-account)
+38. [Delete Shiplens Project Analytics Data & SDK (No Longer Needed)](#delete-shiplens-project-analytics-data-sdk-no-longer-needed)
+39. [Delete Shiplens CLI](#delete-shiplens-cli)
+40. [Use Shiplens CLI to Generate Context Descriptions for All Pages and Buttons](#use-shiplens-cli-to-generate-context-descriptions-for-all-pages-and-buttons)
 
 ### Troubleshooting & Diagnostics (3)
-40. [Test Shiplens Telemetry Pipeline and Environment](#test-shiplens-telemetry-pipeline-and-environment)
-41. [Enable Local Debug Mode and Verify Event Reporting](#enable-local-debug-mode-and-verify-event-reporting)
-42. [Test Event Reporting in Production Build & Release Environments](#test-event-reporting-in-production-build--release-environments)
+41. [Test Shiplens Telemetry Pipeline and Environment](#test-shiplens-telemetry-pipeline-and-environment)
+42. [Enable Local Debug Mode and Verify Event Reporting](#enable-local-debug-mode-and-verify-event-reporting)
+43. [Test Event Reporting in Production Build & Release Environments](#test-event-reporting-in-production-build--release-environments)
 
 ---
 
@@ -734,18 +735,44 @@ Sources:
 
 #### [setup_init] Shiplens CLI One-Click Setup & Analytics Initialization (Suffix: None)
 ```text
-Set up Shiplens analytics: extract project description, install SDK, create the project, and retrieve the live dashboard URL.
+Set up Shiplens analytics: install SDK, create the project, and retrieve the live dashboard URL.
 1. Run CLI initialization command:
-   - Windows: npx.cmd --yes @shiplens/cli init
-   - macOS/Linux: npx --yes @shiplens/cli init
+   - Windows: npx.cmd --yes @shiplens/cli init --json
+   - macOS/Linux: npx --yes @shiplens/cli init --json
 2. Present the standard project & dashboard summary (including: Project Name, App ID, Code Injection file, User Account Status, Live Dashboard / Activation URL);
 3. Immediately prompt the user for their email address (informing them that you will register on their behalf and Shiplens will send an activation email for 50,000 monthly free events and project binding);
 4. Upon receiving the user's email, run: npx.cmd --yes @shiplens/cli auth bind --email <email> --json.
 ```
 
-#### [remove_sdk] Remove Shiplens SDK & Analytics Data (Suffix: None)
+#### [setup_bind_project] Use Shiplens CLI to Install Analytics SDK & Link to Existing Account (Suffix: None)
 ```text
-Remove Shiplens SDK integration and analytics data:
+Use Shiplens CLI to install the analytics SDK in this new project and link it to the user's existing Shiplens account:
+
+1. Run the project setup & initialization command:
+   - Windows: npx.cmd --yes @shiplens/cli init --json
+   - macOS/Linux: npx --yes @shiplens/cli init --json
+   (Automatically detects framework, installs SDK dependency, injects code entry, and creates cloud project)
+
+2. Inspect returned `user_account_status` and credential states:
+   - [Branch A: Logged in & linked] (`logged_in_linked`):
+     No extra step needed; present the project summary card containing App ID, Project Name, Injected file, and Live Dashboard URL (`dashboard_url`).
+   - [Branch B: No local credentials detected] (`not_logged_in_unlinked` or `activation_required=true`):
+     Prompt the user for their registered Shiplens account email, and upon reply run:
+     `npx.cmd --yes @shiplens/cli auth bind --email <email> --json`
+     Instruct the user to click the Magic Link in the email to authorize and complete project binding.
+   - [Branch C: Account quota / project limit reached] (Error `QUOTA_EXCEEDED` / `PLAN_LIMIT` / unable to link):
+     Clearly notify the user that their current free/existing tier project limit or monthly event quota is full;
+     Provide upgrade instructions: recommend upgrading to Pro / Team tier (URL: https://shiplens.dev/pricing or console settings) for expanded project limits and advanced analytics;
+     Note that once upgraded, re-running the bind command will activate immediately without modifying code.
+
+3. Output the final project summary and dashboard link, confirming the project is ready for analytics queries.
+
+Please prioritize calling Shiplens CLI (Action: setup_bind_project) to execute the above requirements.
+```
+
+#### [remove_sdk] Delete Shiplens Project Analytics Data & SDK (No Longer Needed) (Suffix: None)
+```text
+Delete Shiplens project analytics data and SDK integration (analytics no longer needed):
 1. Read `.shiplens.json` in the project root to get project name, app_id, and instrumented file paths.
 2. Clearly display the project name and app_id to be deleted, warn the user that historical events and hosted data will be permanently purged, and pause for explicit user confirmation ("Confirm deleting this project").
 3. Upon confirmation, remove SDK imports/instrumentation code from local frontend files, and delete `./.shiplens.json` and `.shiplens/contexts/<app_id>.md`.
@@ -754,16 +781,16 @@ Remove Shiplens SDK integration and analytics data:
 Please prioritize calling Shiplens CLI (Action: remove_sdk) to execute the above requirements.
 ```
 
-#### [uninstall_cli] Uninstall Shiplens CLI (Suffix: None)
+#### [uninstall_cli] Delete Shiplens CLI (Suffix: None)
 ```text
 Please prioritize calling Shiplens CLI (Action: uninstall_cli) to execute the above requirements.
  - Windows: npm.cmd uninstall -g @shiplens/cli
  - macOS/Linux: npm uninstall -g @shiplens/cli
 ```
 
-#### [generate_context] Generate Context Descriptions for All Pages and Buttons (Suffix: None)
+#### [generate_context] Use Shiplens CLI to Generate Context Descriptions for All Pages and Buttons (Suffix: None)
 ```text
-Map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can map numbers and IDs to concrete functionality:
+Use Shiplens CLI to map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can understand the business context behind each metric:
 1. Check `./.shiplens.json` for current app_id and project name.
 2. Inspect frontend code and routes to extract feature descriptions, user-facing copy, and button texts, locations, and actions.
 3. Write structured details into `.shiplens/contexts/<app_id>.md`, binding app_id and project name in the header.