@prasenjeet/shipli 1.1.0 → 1.2.1

package/README.md

@@ -3,6 +3,8 @@
 [![npm version](https://img.shields.io/npm/v/@prasenjeet/shipli)](https://www.npmjs.com/package/@prasenjeet/shipli)
 [![license](https://img.shields.io/npm/l/@prasenjeet/shipli)](LICENSE)
 
+**Website:** [https://prasenjeet-symon.github.io/shipli-ai/](https://prasenjeet-symon.github.io/shipli-ai/)
+
 Store rejections cost days of development time. **Shipli** is a CLI tool that audits your Flutter source code against **Apple App Store** and **Google Play** guidelines using AI.
 
 Catch missing permissions, policy violations, and compliance issues before you submit.
@@ -146,9 +148,41 @@ Use `shipli config` to update settings anytime.
 
 Shipli includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI coding assistants like Claude Code, Cursor, and Windsurf can run audits directly inside your editor.
 
-### Setup
+### Step 1 — Install globally
+
+```bash
+npm install -g @prasenjeet/shipli
+```
+
+Verify: `shipli --version` and `which shipli-mcp`.
+
+### Step 2 — Add the MCP server
+
+**Option A: Claude Code CLI (recommended)**
+
+```bash
+# Using Claude as the AI provider
+claude mcp add shipli \
+  --transport stdio \
+  --env SHIPLI_PROVIDER=claude \
+  --env SHIPLI_MODEL=claude-haiku-4-5 \
+  --env ANTHROPIC_API_KEY=your-api-key \
+  -- shipli-mcp
+```
+
+```bash
+# Using Gemini as the AI provider
+claude mcp add shipli \
+  --transport stdio \
+  --env SHIPLI_PROVIDER=gemini \
+  --env SHIPLI_MODEL=gemini-2.5-flash \
+  --env GEMINI_API_KEY=your-api-key \
+  -- shipli-mcp
+```
+
+**Option B: Manual JSON config**
 
-Add to your MCP config (e.g. `~/.claude/.mcp.json`):
+Add to `~/.claude/.mcp.json`:
 
 ```json
 {
@@ -165,7 +199,11 @@ Add to your MCP config (e.g. `~/.claude/.mcp.json`):
 }
 ```
 
-For Gemini, use `SHIPLI_PROVIDER: "gemini"` and set `GEMINI_API_KEY` instead.
+For Cursor/Windsurf, add the same config to your editor's MCP settings.
+
+### Step 3 — Restart and verify
+
+Restart Claude Code (or run `/mcp` in chat) to pick up the new server. You should see `shipli` listed with its two tools.
 
 ### Available Tools
 
@@ -197,6 +235,24 @@ The assistant will call the appropriate Shipli MCP tool and return the results i
 
 The CLI exits with code `1` on failure, making it easy to gate deployments.
 
+## Telemetry
+
+Shipli collects anonymous usage metrics to help improve the tool. No project data, file contents, API keys, or personally identifiable information is ever collected.
+
+**What's collected:** audit mode, platform, provider, model, pass/fail score, duration, token counts, OS, and CLI version.
+
+**Opt out** using any of these methods:
+
+```bash
+# Environment variable
+export SHIPLI_TELEMETRY=off
+
+# Or use the Do Not Track standard
+export DO_NOT_TRACK=1
+```
+
+Or add `"telemetry": false` to your `~/.shipli` config file.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prasenjeet/shipli",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "AI-powered App Store review audit for Flutter projects. Catch rejections before you submit.",
   "type": "module",
   "bin": {
@@ -28,9 +28,10 @@
   ],
   "author": "",
   "license": "MIT",
+  "homepage": "https://prasenjeet-symon.github.io/shipli-ai/",
   "repository": {
     "type": "git",
-    "url": ""
+    "url": "https://github.com/prasenjeet-symon/shipli-ai"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",

package/src/index.js

@@ -18,6 +18,7 @@ import { audit } from './auditor.js';
 import { fetchGuidelines } from './guidelines.js';
 import { print as printReport } from './reporter.js';
 import { PROVIDER_DEFAULTS as DEFAULTS, detectPlatform } from './defaults.js';
+import { trackEvent } from './telemetry.js';
 
 // Read package version
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -113,6 +114,7 @@ program
 
     const platformLabel = { ios: 'iOS', android: 'Android', both: 'iOS + Android' }[platform];
     let spinner = ora({ text: `Scanning Flutter project (${platformLabel})...`, color: 'cyan' }).start();
+    const startTime = Date.now();
 
     try {
       // 1. Read pubspec.yaml first (needed for type detection)
@@ -205,11 +207,23 @@ program
         platform,
       });
 
-      // 9. Exit with appropriate code
-      process.exit(result.score === 'FAIL' ? 1 : 0);
+      // 9. Track and exit
+      trackEvent('audit_completed', {
+        source: 'cli', mode, platform, provider, model,
+        project_type: projectType, score: result.score,
+        duration_ms: Date.now() - startTime,
+        tokens_input: result._tokens?.actual?.input ?? null,
+        tokens_output: result._tokens?.actual?.output ?? null,
+      });
+      process.exitCode = result.score === 'FAIL' ? 1 : 0;
     } catch (err) {
       spinner.fail(chalk.red(err.message));
-      process.exit(1);
+      trackEvent('audit_error', {
+        source: 'cli', mode, platform, provider, model,
+        duration_ms: Date.now() - startTime,
+        error_message: err.message.slice(0, 200),
+      });
+      process.exitCode = 1;
     }
   });
 

package/src/mcp-server.js

@@ -15,6 +15,7 @@ import { fetchGuidelines } from './guidelines.js';
 import { audit } from './auditor.js';
 import { loadConfig } from './config.js';
 import { PROVIDER_DEFAULTS, detectPlatform } from './defaults.js';
+import { trackEvent } from './telemetry.js';
 
 // ── Read package version ──
 
@@ -66,12 +67,13 @@ const server = new McpServer({
 
 server.tool(
   'shipli_store_audit',
-  'Run a store compliance audit on a Flutter project against Apple App Store and/or Google Play guidelines. Returns structured findings with PASS/WARNING/FAIL scores and specific guideline citations.',
+  'Run a store compliance audit on a Flutter project against Apple App Store and/or Google Play guidelines. Scans Dart source files, pubspec.yaml, Info.plist (iOS), and AndroidManifest.xml (Android). Returns structured JSON with PASS/WARNING/FAIL scores, specific guideline citations, and actionable fix suggestions. Supports both Flutter apps and packages.',
   {
-    projectDir: z.string().describe('Absolute path to the Flutter project root directory'),
-    platform: z.enum(['ios', 'android', 'both']).optional().describe('Target platform. Auto-detected from project structure if omitted.'),
+    projectDir: z.string().describe('Absolute path to the Flutter project root directory. Must contain a pubspec.yaml and a lib/ folder. Example: "/Users/you/projects/my-flutter-app"'),
+    platform: z.enum(['ios', 'android', 'both']).optional().describe('Target platform: "ios" (App Store only), "android" (Play Store only), or "both" (both stores). Auto-detected from ios/ and android/ directory presence if omitted.'),
   },
   async ({ projectDir, platform }) => {
+    const startTime = Date.now();
     try {
       const dir = validateProject(projectDir);
       const { provider, model, apiKey } = resolveConfig(dir);
@@ -124,10 +126,23 @@ server.tool(
         { apiKey, model, provider, mode: 'store', platform: resolvedPlatform },
       );
 
+      trackEvent('audit_completed', {
+        source: 'mcp', mode: 'store', platform: resolvedPlatform,
+        provider, model, project_type: projectType, score: result.score,
+        duration_ms: Date.now() - startTime,
+        tokens_input: result._tokens?.actual?.input ?? null,
+        tokens_output: result._tokens?.actual?.output ?? null,
+      });
+
       return {
         content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
       };
     } catch (err) {
+      trackEvent('audit_error', {
+        source: 'mcp', mode: 'store',
+        duration_ms: Date.now() - startTime,
+        error_message: err.message.slice(0, 200),
+      });
       return {
         content: [{ type: 'text', text: `Error: ${err.message}` }],
         isError: true,
@@ -140,11 +155,12 @@ server.tool(
 
 server.tool(
   'shipli_code_review',
-  'Run a code quality and security review on a Flutter project. Checks architecture, error handling, performance, dependencies, and security vulnerabilities.',
+  'Run a code quality and security review on a Flutter project. Scans all Dart source files and pubspec.yaml. Checks architecture patterns, error handling, performance issues, dependency hygiene, and security vulnerabilities. Returns structured JSON with findings, severity levels, and fix suggestions. Supports both Flutter apps and packages (including example/ directories).',
   {
-    projectDir: z.string().describe('Absolute path to the Flutter project root directory'),
+    projectDir: z.string().describe('Absolute path to the Flutter project root directory. Must contain a pubspec.yaml and a lib/ folder. Example: "/Users/you/projects/my-flutter-app"'),
   },
   async ({ projectDir }) => {
+    const startTime = Date.now();
     try {
       const dir = validateProject(projectDir);
       const { provider, model, apiKey } = resolveConfig(dir);
@@ -176,10 +192,23 @@ server.tool(
         { apiKey, model, provider, mode: 'code', platform: 'both' },
       );
 
+      trackEvent('audit_completed', {
+        source: 'mcp', mode: 'code', platform: 'both',
+        provider, model, project_type: projectType, score: result.score,
+        duration_ms: Date.now() - startTime,
+        tokens_input: result._tokens?.actual?.input ?? null,
+        tokens_output: result._tokens?.actual?.output ?? null,
+      });
+
       return {
         content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
       };
     } catch (err) {
+      trackEvent('audit_error', {
+        source: 'mcp', mode: 'code',
+        duration_ms: Date.now() - startTime,
+        error_message: err.message.slice(0, 200),
+      });
       return {
         content: [{ type: 'text', text: `Error: ${err.message}` }],
         isError: true,

package/src/telemetry.js

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+import { hostname, userInfo, platform, arch } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+
+const POSTHOG_ENDPOINT = 'https://us.i.posthog.com/capture';
+const POSTHOG_API_KEY = 'phc_JcSoYrxMXvJjCtlePCFI6UuhNbwq33WXNeUKmDB6Msz';
+
+// ── Opt-out check (lazy, cached) ──
+
+let _disabled = null;
+
+function isDisabled() {
+  if (_disabled !== null) return _disabled;
+
+  const envVal = (process.env.SHIPLI_TELEMETRY || '').toLowerCase();
+  if (['off', 'false', '0', 'no'].includes(envVal)) {
+    _disabled = true;
+    return true;
+  }
+
+  if (process.env.DO_NOT_TRACK === '1') {
+    _disabled = true;
+    return true;
+  }
+
+  try {
+    const raw = readFileSync(join(homedir(), '.shipli'), 'utf-8');
+    const config = JSON.parse(raw);
+    if (config.telemetry === false) {
+      _disabled = true;
+      return true;
+    }
+  } catch {
+    // No config file or invalid JSON — telemetry stays on
+  }
+
+  _disabled = false;
+  return false;
+}
+
+// ── Anonymous device ID ──
+
+function getAnonymousId() {
+  try {
+    const raw = `${hostname()}:${userInfo().username}`;
+    return createHash('sha256').update(raw).digest('hex').slice(0, 16);
+  } catch {
+    return createHash('sha256').update(hostname()).digest('hex').slice(0, 16);
+  }
+}
+
+// ── Fire-and-forget event dispatch ──
+
+export function trackEvent(name, properties = {}) {
+  if (isDisabled()) return;
+
+  const payload = {
+    api_key: POSTHOG_API_KEY,
+    event: name,
+    distinct_id: getAnonymousId(),
+    properties: {
+      ...properties,
+      cli_version: pkg.version,
+      node_version: process.version,
+      os: platform(),
+      arch: arch(),
+    },
+  };
+
+  fetch(POSTHOG_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(3000),
+  }).catch(() => {});
+}