@shiplens/cli 1.4.3 → 1.4.5

package/lib/assets/skill.js

@@ -3,7 +3,7 @@ name: shiplens-analytics
 description: Shiplens Web Analytics — Agent behavior protocol, diagnostics, and data analysis execution.
 ---
 
-# Shiplens Web Analytics Skill (v3.0)
+# Shiplens Web Analytics Skill (v3.1)
 
 Shiplens provides web user behavior analytics via CLI and MCP. This document defines how an AI Agent should diagnose, onboard, and analyze data for any project using Shiplens.
 
@@ -86,43 +86,42 @@ Account status values:
 
 ## 3. Data Analysis Protocol (6 Steps)
 
-When the user asks any data or analytics question:
+When processing any analytics or telemetry request:
 
-**Step 1 — Check overrides**: Read \`.shiplens/learnings.md\` if it exists. Apply user preferences tailored to specific analysis scenarios (date range, metrics, filters).
+**Step 1 — Read Learnings**: Check \`.shiplens/learnings.md\` for project overrides (date range, metrics, cohort intervals).
 
-**Step 2 — Ground in context**: Read \`.shiplens/contexts/<app_id>.md\` (or \`shiplens context show --json\`). Use real page names and button labels, not raw IDs.
+**Step 2 — Read Context**: Read \`.shiplens/contexts/<app_id>.md\` (or run \`shiplens context show --json\`) to ground numbers in real page routes and button labels.
 
-**Step 3 — Find scenario**: Open \`prompts/prompts_cli_en.md\` (or \`_zh.md\`), read the **Scenario Outline** at the top, locate the matching scenario, then read its full execution steps.
+**Step 3 — Route Execution Path (Tri-Route Decision)**:
+- **Route A (Exact Action ID)**: If input contains an \`action_id\` (e.g. \`lifecycle_stage\` or \`Action: <id>\`), run \`shiplens action <id> --json\` to retrieve prescribed steps and commands.
+- **Route B (Scenario Preset Match)**: If input is natural language matching one of the 42 textbook growth/retention scenarios, run \`shiplens action <id> --json\` for that scenario.
+- **Route C (Ad-Hoc Autonomous Composition)**: If input is a custom, open-ended question without a preset action, autonomously select and compose CLI commands from the Atomic Toolset (§4) to query required metrics.
 
-**Step 4 — Execute**: Run the prescribed CLI commands with overrides from Step 1 applied.
+**Step 4 — Execute**: Run selected CLI commands with Step 1 overrides applied. Always include \`--json\`.
 
-**Step 5 — Synthesize**: Translate numbers into actionable business insights, grounded in context from Step 2.
+**Step 5 — Synthesize**: Translate numbers into concrete business conclusions, metric benchmarks, and actionable next steps using UI terminology from Step 2.
 
-**Step 6 — Offer to remember**: If the user corrected your approach (e.g., "always compare 14-day retention for cohorts"), ask: *"Save this preference to \`.shiplens/learnings.md\` for future analyses?"* If yes, write it (§6).
-
-### Priority
-- **Priority 1**: \`.shiplens/learnings.md\` — user's project-specific overrides
-- **Priority 2**: \`prompts/prompts_cli_*.md\` — 42 textbook analysis scenarios
+**Step 6 — Record**: If user clarifies or corrects preferences (e.g., "always use 14d for cohort retention"), ask to persist to \`.shiplens/learnings.md\` (§6).
 
 ---
 
-## 4. CLI Commands
-
-| Command | Purpose |
-|---------|---------|
-| \`shiplens init --json\` | Project onboarding (§2) |
-| \`shiplens doctor --json\` | Diagnose config, SDK, network, credentials |
-| \`shiplens summary --range 7d --json\` | PV, UV, bounce rate, top geos, devices |
-| \`shiplens query --metric <m> --range 7d --json\` | Multi-dimensional metrics and funnels |
-| \`shiplens sql --query "<sql>" --json\` | Read-only SQL on ClickHouse |
-| \`shiplens pages --range 7d --json\` | Page visits and dwell times |
-| \`shiplens paths --range 7d --json\` | User flow and navigation paths |
-| \`shiplens heatmap --template <id> --json\` | Click heatmaps and skeleton wireframes |
-| \`shiplens dashboards create --title "..." --prompt "..." --json\` | AI-generated dashboards |
-| \`shiplens context show --json\` | Show business context |
-| \`shiplens auth bind --email <email> --json\` | Send Magic Link for activation |
-| \`shiplens mcp serve\` | Start local stdio MCP proxy for IDE/Agent |
-| \`shiplens projects delete --app-id <id> --json\` | Delete project (**requires confirmation**, §5) |
+## 4. Atomic CLI Toolset & Composition Matrix
+
+| Command | Capability | Typical Scenarios & Composition |
+|---------|------------|---------------------------------|
+| \`shiplens summary --range 7d --json\` | Macro Overview | Total UV, PV, bounce rates, top geos, device distribution |
+| \`shiplens query --metric <m> --range 7d --json\` | Multidimensional Metrics | Retention matrix (\`daily_retention\`), funnels (\`conversion_funnel\`), pageview trends |
+| \`shiplens pages --range 7d --json\` | Page Performance | Route visit counts, average dwell time, high-traffic pages |
+| \`shiplens paths --range 7d --json\` | User Journeys | Entry-to-exit flow, drop-off routes, navigation transitions |
+| \`shiplens heatmap --template <id> --json\` | UI & Click Patterns | Button click distributions, wireframe skeleton click rates |
+| \`shiplens sql --query "<sql>" --json\` | Custom Slicing | Multi-filter joins, power user segmentation, ad-hoc event queries |
+| \`shiplens dashboards create --title "..." --prompt "..." --json\` | Dashboard Creation | AI-generated 12-column live dashboards |
+| \`shiplens action [id] [--list] --json\` | Action Presets | 42 textbook scenario steps, commands, and theory |
+| \`shiplens doctor --json\` | Diagnostics | Diagnose config, SDK, network, credentials |
+| \`shiplens context show --json\` | Business Context | Inspect mapped page routes and UI button semantics |
+| \`shiplens auth bind --email <email> --json\` | Activation | Send Magic Link email for project binding |
+| \`shiplens mcp serve\` | MCP Server | Start local stdio MCP proxy for IDE/Agent |
+| \`shiplens projects delete --app-id <id> --json\` | Deletion | Delete project (**requires confirmation**, §5) |
 
 ---
 

package/lib/cli.js

@@ -14,8 +14,9 @@ const { handleDashboards } = require('./commands/dashboards');
 const { handleDoctor } = require('./commands/doctor');
 const { handleContext } = require('./commands/context');
 const { handleMcp } = require('./commands/mcp');
+const { handleAction } = require('./commands/action');
 
-let VERSION = '1.3.0';
+let VERSION = '1.4.4';
 try {
   const pkg = require('../package.json');
   if (pkg.version) VERSION = pkg.version;
@@ -90,6 +91,7 @@ Core Commands:
   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)
+  action        Retrieve deterministic steps, commands, and theory for analysis actions (list, <action_id>)
   mcp serve     Run local MCP proxy server with device credentials
 
 auth Subcommands:
@@ -244,6 +246,9 @@ async function runCLI(argv = process.argv.slice(2)) {
       case 'context':
         await handleContext(subcommand || 'show', args.slice(2), flags, ctx);
         break;
+      case 'action':
+        await handleAction(cmdArgs, flags, ctx);
+        break;
       case 'mcp':
         await handleMcp(subcommand || 'serve');
         break;

package/lib/commands/action.js

@@ -0,0 +1,112 @@
+const path = require('path');
+const fs = require('fs');
+
+let actionsCache = null;
+
+function loadActions() {
+  if (actionsCache) return actionsCache;
+  const filePath = path.join(__dirname, '..', 'assets', 'actions.json');
+  try {
+    if (fs.existsSync(filePath)) {
+      const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      actionsCache = data.actions || [];
+    } else {
+      actionsCache = [];
+    }
+  } catch (e) {
+    actionsCache = [];
+  }
+  return actionsCache;
+}
+
+function findSimilarActions(id, allActions) {
+  const normalized = (id || '').toLowerCase().replace(/[-_\s]+/g, '');
+  return allActions
+    .filter((a) => {
+      const aNorm = a.id.toLowerCase().replace(/[-_\s]+/g, '');
+      return aNorm.includes(normalized) || normalized.includes(aNorm) || a.title.toLowerCase().includes(id.toLowerCase());
+    })
+    .slice(0, 3)
+    .map((a) => a.id);
+}
+
+async function handleAction(cmdArgs, flags, ctx) {
+  const actions = loadActions();
+  const rawId = flags.id || (cmdArgs[0] && cmdArgs[0] !== 'list' ? cmdArgs[0] : null);
+  const isList = flags.list || cmdArgs[0] === 'list' || !rawId;
+
+  if (isList) {
+    const listData = {
+      ok: true,
+      total: actions.length,
+      actions: actions.map((a) => ({
+        id: a.id,
+        title: a.title,
+        category: a.category,
+        commands: a.commands,
+      })),
+    };
+
+    ctx.output(listData, () => {
+      console.log(`\n📋 Shiplens Action Preset Library (${actions.length} Scenarios)\n`);
+      const grouped = {};
+      for (const a of actions) {
+        if (!grouped[a.category]) grouped[a.category] = [];
+        grouped[a.category].push(a);
+      }
+      for (const [cat, items] of Object.entries(grouped)) {
+        console.log(`  📂 ${cat}:`);
+        for (const item of items) {
+          console.log(`    • ${item.id.padEnd(28)} - ${item.title}`);
+        }
+        console.log('');
+      }
+      console.log('💡 Usage: shiplens action <action_id> [--json]');
+    });
+    return;
+  }
+
+  const targetId = rawId.toLowerCase().trim();
+  const matched = actions.find((a) => a.id.toLowerCase() === targetId);
+
+  if (!matched) {
+    const suggestions = findSimilarActions(targetId, actions);
+    const err = new Error(`Action preset '${rawId}' not found.` + (suggestions.length > 0 ? ` Did you mean: ${suggestions.join(', ')}?` : ''));
+    err.code = 'ACTION_NOT_FOUND';
+    err.suggestions = suggestions;
+    throw err;
+  }
+
+  const result = {
+    ok: true,
+    action: matched,
+  };
+
+  ctx.output(result, () => {
+    console.log(`\n🎯 [${matched.id}] ${matched.title}`);
+    console.log(`📂 Category: ${matched.category}`);
+    if (matched.suffix) console.log(`🏷️ Suffix: ${matched.suffix}`);
+    console.log(`\n📝 Execution Steps:`);
+    for (const s of matched.steps) {
+      console.log(`  ${s}`);
+    }
+    if (matched.commands && matched.commands.length > 0) {
+      console.log(`\n⚡ Prescribed CLI Commands:`);
+      for (const c of matched.commands) {
+        console.log(`  $ ${c}`);
+      }
+    }
+    if (matched.foundation) {
+      console.log(`\n📚 Analysis Foundation:\n  ${matched.foundation}`);
+    }
+    if (matched.source) {
+      console.log(`\n📖 Source:\n  ${matched.source}`);
+    }
+    console.log('');
+  });
+}
+
+module.exports = {
+  handleAction,
+  loadActions,
+};

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.3",
+  "version": "1.4.5",
   "description": "Shiplens CLI — Automated Web User Analytics & AI Agent Analysis Engine",
   "main": "lib/index.js",
   "bin": {
@@ -28,7 +28,10 @@
   },
   "homepage": "https://shiplens.dev",
   "scripts": {
-    "test": "node test/cli.test.js"
+    "test": "node test/cli.test.js",
+    "sync-prompts": "node scripts/sync-prompts.js",
+    "prepack": "node scripts/sync-prompts.js",
+    "prepublishOnly": "node scripts/sync-prompts.js"
   },
   "files": [
     "bin",

package/prompts/README.md

@@ -8,9 +8,8 @@ This directory hosts the deterministic CLI scenario-based prompt libraries for S
 
 ```text
 prompts/
-├── README.md                 # Multilingual architecture overview
-├── prompts_cli_en.md         # [English] 42 deterministic CLI analysis scenarios
-└── prompts_cli_zh.md         # [中文] 42 个确定性 CLI 分析场景
+├── README.md                 # Prompt architecture overview
+└── prompts_cli_en-US.md      # [English] 42 deterministic CLI analysis scenarios
 ```
 
 ---