@prasenjeet/shipli 1.0.0 → 1.1.0

package/README.md

@@ -1,33 +1,36 @@
-# 🛡️ Shipli
+# Shipli
 
-Store rejections cost days of development time. **Shipli** is a local CLI tool that statically analyzes your Flutter source code against the latest **Apple App Store** and **Google Play** guidelines using an LLM.
+[![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)
 
-Catch missing permissions, policy violations, and compliance issues *before* you submit.
+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.
 
-## ✨ Features
+Catch missing permissions, policy violations, and compliance issues before you submit.
 
-* **Dual Store Support:** Audit against **Apple App Store** and **Google Play** — or both at once.
-* **Two Audit Modes:** `--mode store` for compliance, `--mode code` for quality, or both (default).
-* **Live Guidelines:** Fetches the latest store policies at runtime and caches them locally.
-* **Auto-Detection:** Detects project type (app/package) and platform (ios/android) automatically.
-* **Multi-Provider:** Choose between **Google Gemini** or **Anthropic Claude** as your AI backend.
-* **Zero-Setup Artifacts:** No `.ipa` or `.apk` needed — reads `lib/`, `pubspec.yaml`, `Info.plist`, and `AndroidManifest.xml` directly.
-* **CI-Friendly:** Exit code `1` on FAIL, `0` on PASS/WARNING.
+## Features
 
-## 🚀 Installation
+- **Dual Store Support** — Audit against Apple App Store and Google Play, together or individually.
+- **Two Audit Modes** — Store compliance, code quality, or both in a single run.
+- **AI-Powered** — Choose between Google Gemini or Anthropic Claude. Bring your own API key.
+- **Up-to-Date Policies** — Ships with the latest Apple and Google Play store policies. Works offline.
+- **Auto-Detection** — Automatically detects project type and target platform from your project structure.
+- **Zero Setup** — No compiled artifacts needed. Point it at your Flutter project and run.
+- **CI-Ready** — Designed for automation. Integrates with any CI/CD pipeline.
+
+## Installation
 
 ```bash
-npm install -g shipli
+npm install -g @prasenjeet/shipli
 ```
 
-Requires **Node.js 18+**.
+Requires Node.js 18 or later.
 
-## 🛠️ Usage
+## Usage
 
 ### Quick Start
 
 ```bash
-# One-time setup
+# One-time setup — select provider, model, and enter API key
 shipli init
 
 # Run full audit (auto-detects platform)
@@ -39,10 +42,18 @@ shipli --dir ./ --platform ios --mode store
 # Google Play only
 shipli --dir ./ --platform android --mode store
 
-# Code quality only (platform-agnostic)
+# Code quality only
 shipli --dir ./ --mode code
 ```
 
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `shipli init` | Create a `.shipli` config file interactively |
+| `shipli config` | Update provider, model, or API key |
+| `shipli --dir <path>` | Run the audit (default command) |
+
 ### Options
 
 | Flag | Description | Default |
@@ -50,12 +61,12 @@ shipli --dir ./ --mode code
 | `--dir <path>` | Path to Flutter project root | *required* |
 | `--key <key>` | API key | `.shipli` / env var |
 | `--provider <name>` | `gemini` or `claude` | `gemini` |
-| `--model <model>` | Model override | `gemini-2.5-flash` / `claude-sonnet-4-6` |
-| `--type <type>` | `app` or `package` | auto-detected from pubspec |
+| `--model <model>` | Model override | per provider |
+| `--type <type>` | `app` or `package` | auto-detected |
 | `--mode <mode>` | `store`, `code`, or `both` | `both` |
-| `--platform <platform>` | `ios`, `android`, or `both` | auto-detected from project |
+| `--platform <platform>` | `ios`, `android`, or `both` | auto-detected |
 
-### Configuration: `.shipli`
+### Configuration
 
 Run `shipli init` to create a `.shipli` config file, or create one manually:
 
@@ -69,74 +80,122 @@ Run `shipli init` to create a `.shipli` config file, or create one manually:
 ```
 
 The CLI looks for `.shipli` in two places:
+
 1. **Project-level** — in the `--dir` path (highest priority)
 2. **Global** — in your home directory `~/.shipli`
 
-**Resolution order:** CLI flags > project `.shipli` > global `~/.shipli` > env vars > defaults
+Resolution order: CLI flags > project `.shipli` > global `~/.shipli` > env vars > defaults.
 
-> **Note:** Add `.shipli` to your `.gitignore` — it contains your API key.
+> Add `.shipli` to your `.gitignore` — it contains your API key.
 
-## 🧠 How it Works
+Use `shipli config` to update settings anytime.
 
-1. **Detects Project & Platform:** Auto-detects app vs package from `pubspec.yaml`, and iOS/Android from project structure.
-2. **Extracts Evidence:** Scans `lib/` for Dart files, keeping only the architectural skeleton. For packages, also scans `example/`.
-3. **Gathers Metadata:** Reads `Info.plist` (iOS) and/or `AndroidManifest.xml` (Android) permissions.
-4. **Fetches Live Guidelines:** Downloads the latest Apple App Store Review Guidelines and/or Google Play Developer Policies (cached for 7 days).
-5. **AI Audit:** Sends evidence + live guidelines to the LLM with a tailored system prompt.
-6. **Actionable Report:** Outputs a Pass/Warning/Fail checklist with specific guideline citations.
+### Supported Models
 
-## 📱 App Store Audit Categories (iOS)
+| Provider | Models |
+|----------|--------|
+| Claude | opus-4-6, sonnet-4-6, opus-4-5, sonnet-4-5, haiku-4-5, opus-4-1, opus-4, sonnet-4, sonnet-3-7, haiku-3-5, sonnet-3-5 |
+| Gemini | 3.1-pro, 3.1-flash-lite, 3-flash, 2.5-flash, 2.5-pro, 2.5-flash-lite, 1.5-pro, 1.5-flash |
+
+## Audit Categories
+
+### App Store (iOS)
 
 | Category | Examples |
 |----------|---------|
-| **Privacy & Permissions** | Missing Info.plist usage descriptions, undeclared APIs |
-| **Data Collection & Tracking** | ATT requirements, analytics SDKs |
-| **Content & Design** | Webview-only apps, minimum functionality |
-| **In-App Purchases** | StoreKit/IAP vs third-party payment |
-| **Legal & Compliance** | Privacy policy, encryption export, COPPA |
-| **Forbidden Patterns** | Code push, dynamic code loading |
+| Privacy & Permissions | Undeclared sensitive APIs, missing usage descriptions |
+| Data Collection & Tracking | Tracking transparency, analytics disclosure |
+| Content & Design | Minimum functionality, UI compliance |
+| In-App Purchases | Payment method compliance |
+| Legal & Compliance | Privacy policy, export compliance |
+| Prohibited Behaviors | Dynamic code loading, hot-patching |
 
-## 🤖 Play Store Audit Categories (Android)
+### Play Store (Android)
 
 | Category | Examples |
 |----------|---------|
-| **Permissions & Data Safety** | Unnecessary permissions, Data Safety compliance |
-| **Data Collection & Privacy** | Privacy policy, User Data policy |
-| **Content & Behavior** | Restricted content, deceptive behavior |
-| **Billing & Monetization** | Google Play Billing Library requirements |
-| **Target API & Compatibility** | Minimum API level, Android version issues |
-| **Malware & Abuse** | Stalkerware, abusive notifications |
+| Permissions & Data Safety | Unnecessary permissions, data safety declarations |
+| Data Collection & Privacy | Privacy policy, user data handling |
+| Content & Behavior | Restricted content, deceptive behavior |
+| Billing & Monetization | Payment method compliance |
+| API Level & Compatibility | Target API requirements, version compatibility |
+| Security & Abuse | Malware patterns, abusive behavior |
 
-## 🔧 Code Quality Categories
+### Code Quality
 
 | Category | Examples |
 |----------|---------|
-| **Security** | Hardcoded keys, insecure HTTP, injection |
-| **Architecture** | State management, separation of concerns |
-| **Error Handling** | try/catch, crash handling |
-| **Performance** | Widget rebuilds, memory leaks |
-| **Best Practices** | Dispose/lifecycle, null safety |
-| **Dependencies** | Outdated packages, version constraints |
+| Security | Hardcoded credentials, insecure connections |
+| Architecture | State management, separation of concerns |
+| Error Handling | Exception coverage, crash handling |
+| Performance | Memory leaks, unnecessary rebuilds |
+| Best Practices | Lifecycle handling, null safety |
+| Dependencies | Outdated packages, version constraints |
 
-## 📦 Package Audit Categories
+### Package Auditing
 
 | Category | Examples |
 |----------|---------|
-| **API Surface & Documentation** | Export hygiene, clear entry points |
-| **Platform Declarations** | MethodChannel consistency |
-| **Consumer Permissions Guidance** | Undocumented permission requirements |
-| **Dependency Hygiene** | Constraint quality, misplaced deps |
-| **Example App Quality** | Missing example/, incomplete demos |
+| API Surface & Documentation | Export hygiene, entry points |
+| Platform Declarations | Channel consistency, missing platforms |
+| Consumer Guidance | Undocumented permission requirements |
+| Dependency Hygiene | Constraint quality, misplaced dependencies |
+| Example App Quality | Missing or incomplete examples |
+
+## MCP Server
+
+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
+
+Add to your MCP config (e.g. `~/.claude/.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "shipli": {
+      "command": "shipli-mcp",
+      "env": {
+        "SHIPLI_PROVIDER": "claude",
+        "SHIPLI_MODEL": "claude-haiku-4-5",
+        "ANTHROPIC_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+For Gemini, use `SHIPLI_PROVIDER: "gemini"` and set `GEMINI_API_KEY` instead.
+
+### Available Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `shipli_store_audit` | Run store compliance audit against Apple App Store and/or Google Play guidelines | `projectDir` (required), `platform` (optional: `ios`, `android`, `both`) |
+| `shipli_code_review` | Run code quality and security review | `projectDir` (required) |
+
+Both tools return structured JSON with PASS/WARNING/FAIL scores and specific guideline citations.
+
+### Usage
+
+Once configured, ask your AI assistant:
+
+```
+"Run a store audit on /path/to/my-flutter-app"
+"Review the code quality of this Flutter project"
+```
+
+The assistant will call the appropriate Shipli MCP tool and return the results inline.
 
-## 🔄 CI Integration
+## CI Integration
 
 ```yaml
-# GitHub Actions example
+# GitHub Actions
 - name: Shipli Audit
-  run: npx shipli --dir ./ --platform both --provider claude --key ${{ secrets.ANTHROPIC_API_KEY }}
+  run: npx @prasenjeet/shipli --dir ./ --provider claude --key ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
-The CLI exits with code `1` if the audit result is **FAIL**, making it easy to gate deployments.
+The CLI exits with code `1` on failure, making it easy to gate deployments.
 
 ## License
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@prasenjeet/shipli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AI-powered App Store review audit for Flutter projects. Catch rejections before you submit.",
   "type": "module",
   "bin": {
-    "shipli": "src/index.js"
+    "shipli": "src/index.js",
+    "shipli-mcp": "src/mcp-server.js"
   },
   "files": [
     "src",
@@ -32,11 +33,13 @@
     "url": ""
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "fast-glob": "^3.3.3",
     "js-yaml": "^4.1.0",
     "ora": "^8.2.0",
-    "plist": "^3.1.0"
+    "plist": "^3.1.0",
+    "zod": "^4.3.6"
   }
 }

package/src/defaults.js

@@ -0,0 +1,16 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const PROVIDER_DEFAULTS = {
+  gemini: { model: 'gemini-2.5-flash', envKey: 'GEMINI_API_KEY' },
+  claude: { model: 'claude-sonnet-4-6', envKey: 'ANTHROPIC_API_KEY' },
+};
+
+export function detectPlatform(projectDir) {
+  const hasIos = existsSync(join(projectDir, 'ios'));
+  const hasAndroid = existsSync(join(projectDir, 'android'));
+  if (hasIos && hasAndroid) return 'both';
+  if (hasIos) return 'ios';
+  if (hasAndroid) return 'android';
+  return 'both';
+}

package/src/index.js

@@ -17,25 +17,12 @@ import { read as readPubspec } from './pubspec-reader.js';
 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';
 
 // Read package version
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
 
-const DEFAULTS = {
-  gemini: { model: 'gemini-2.5-flash', envKey: 'GEMINI_API_KEY' },
-  claude: { model: 'claude-sonnet-4-6', envKey: 'ANTHROPIC_API_KEY' },
-};
-
-function detectPlatform(projectDir) {
-  const hasIos = existsSync(join(projectDir, 'ios'));
-  const hasAndroid = existsSync(join(projectDir, 'android'));
-  if (hasIos && hasAndroid) return 'both';
-  if (hasIos) return 'ios';
-  if (hasAndroid) return 'android';
-  return 'both'; // default
-}
-
 const program = new Command();
 
 program

package/src/mcp-server.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { scan } from './scanner.js';
+import { read as readPubspec } from './pubspec-reader.js';
+import { read as readPlist } from './plist-reader.js';
+import { read as readManifest } from './manifest-reader.js';
+import { fetchGuidelines } from './guidelines.js';
+import { audit } from './auditor.js';
+import { loadConfig } from './config.js';
+import { PROVIDER_DEFAULTS, detectPlatform } from './defaults.js';
+
+// ── Read package version ──
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
+
+// ── Resolve provider config from env vars at startup ──
+
+function resolveConfig(projectDir) {
+  const provider = (process.env.SHIPLI_PROVIDER || 'gemini').toLowerCase();
+  const defaults = PROVIDER_DEFAULTS[provider];
+  if (!defaults) {
+    throw new Error(`Unknown provider "${provider}". Set SHIPLI_PROVIDER to "gemini" or "claude".`);
+  }
+
+  const model = process.env.SHIPLI_MODEL || defaults.model;
+  const apiKey = process.env[defaults.envKey];
+
+  if (!apiKey) {
+    throw new Error(
+      `No API key found. Set ${defaults.envKey} in your MCP server env config.`
+    );
+  }
+
+  return { provider, model, apiKey };
+}
+
+// ── Validate project directory ──
+
+function validateProject(projectDir) {
+  const resolved = resolve(projectDir);
+  if (!existsSync(resolved)) {
+    throw new Error(`Directory not found: ${resolved}`);
+  }
+  if (!existsSync(join(resolved, 'lib'))) {
+    throw new Error(`No lib/ directory found in ${resolved}. Is this a Flutter project?`);
+  }
+  return resolved;
+}
+
+// ── Create server ──
+
+const server = new McpServer({
+  name: 'shipli',
+  version: pkg.version,
+});
+
+// ── Tool: shipli_store_audit ──
+
+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.',
+  {
+    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.'),
+  },
+  async ({ projectDir, platform }) => {
+    try {
+      const dir = validateProject(projectDir);
+      const { provider, model, apiKey } = resolveConfig(dir);
+
+      const pubspec = await readPubspec(dir);
+      const projectType = pubspec.projectType;
+      const resolvedPlatform = platform || detectPlatform(dir);
+
+      const { files } = await scan(dir);
+
+      let exampleFiles = [];
+      if (projectType === 'package' && existsSync(join(dir, 'example', 'lib'))) {
+        const exampleResult = await scan(join(dir, 'example'));
+        exampleFiles = exampleResult.files;
+      }
+
+      let plistData = { found: false, permissions: {}, bundleId: null };
+      let manifestData = { found: false, permissions: [], packageName: null };
+
+      if (projectType === 'app' && (resolvedPlatform === 'ios' || resolvedPlatform === 'both')) {
+        plistData = await readPlist(dir);
+      }
+      if (projectType === 'app' && (resolvedPlatform === 'android' || resolvedPlatform === 'both')) {
+        manifestData = await readManifest(dir);
+      }
+
+      let appleGuidelines = null;
+      let googleGuidelines = null;
+
+      if (resolvedPlatform === 'ios' || resolvedPlatform === 'both') {
+        appleGuidelines = await fetchGuidelines('apple');
+      }
+      if (resolvedPlatform === 'android' || resolvedPlatform === 'both') {
+        googleGuidelines = await fetchGuidelines('google');
+      }
+
+      const result = await audit(
+        {
+          files,
+          exampleFiles,
+          permissions: plistData.permissions,
+          androidPermissions: manifestData.permissions,
+          pubspec,
+          plistFound: (resolvedPlatform === 'ios' || resolvedPlatform === 'both') ? plistData.found : undefined,
+          androidManifestFound: (resolvedPlatform === 'android' || resolvedPlatform === 'both') ? manifestData.found : undefined,
+          projectType,
+          appleGuidelines,
+          googleGuidelines,
+        },
+        { apiKey, model, provider, mode: 'store', platform: resolvedPlatform },
+      );
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Error: ${err.message}` }],
+        isError: true,
+      };
+    }
+  },
+);
+
+// ── Tool: shipli_code_review ──
+
+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.',
+  {
+    projectDir: z.string().describe('Absolute path to the Flutter project root directory'),
+  },
+  async ({ projectDir }) => {
+    try {
+      const dir = validateProject(projectDir);
+      const { provider, model, apiKey } = resolveConfig(dir);
+
+      const pubspec = await readPubspec(dir);
+      const projectType = pubspec.projectType;
+
+      const { files } = await scan(dir);
+
+      let exampleFiles = [];
+      if (projectType === 'package' && existsSync(join(dir, 'example', 'lib'))) {
+        const exampleResult = await scan(join(dir, 'example'));
+        exampleFiles = exampleResult.files;
+      }
+
+      const result = await audit(
+        {
+          files,
+          exampleFiles,
+          permissions: {},
+          androidPermissions: [],
+          pubspec,
+          plistFound: undefined,
+          androidManifestFound: undefined,
+          projectType,
+          appleGuidelines: null,
+          googleGuidelines: null,
+        },
+        { apiKey, model, provider, mode: 'code', platform: 'both' },
+      );
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Error: ${err.message}` }],
+        isError: true,
+      };
+    }
+  },
+);
+
+// ── Start server ──
+
+const transport = new StdioServerTransport();
+await server.connect(transport);