impact-compass 0.2.1 → 0.2.3

package/README.md

@@ -2,6 +2,11 @@
 
 *grab a compass before you sail soldier*
 
+```bash
+npm i impact-compass
+npx impact-compass idea.json output.json
+```
+
 A purely statistical, deterministic project idea validator and market research CLI.
 
 Impact Compass fetches keyword rankings and engagement signals from real sources like GitHub, npm, Reddit, Stack Exchange, Hacker News, Wikipedia, and the App Store. It checks the *hype* around your project before you waste six months, a billion tokens, and enough coffee to make your keyboard anxious.
@@ -22,25 +27,34 @@ Why? Because you didn't measure the noise. High demand means nothing if the mark
 
 Impact Compass takes your idea and compiles a query bundle (problems, solutions, target audiences, and competitors). It then pulls live data from seven pillars of public evidence and runs an advanced logarithmic scoring algorithm. 
 
+```mermaid
+flowchart TD
+  A["Idea brief JSON"] --> B["Query bundle compiler"]
+  B --> C["35 source adapters"]
+  C --> D["Public APIs: GitHub, Reddit, npm, Hacker News, Stack Exchange, Wikipedia, App Store"]
+  D --> E["Evidence normalizer"]
+  E --> F["Relevance filter: weak keyword match loses 60% signal"]
+  F --> G["Pillar scorers: demand, pain, momentum, activity, competition, channel fit, evidence quality"]
+  G --> H["Weighted score engine"]
+  H --> I["Red ocean saturation penalty"]
+  I --> J["Final score, confidence, interpretation, JSON report"]
+```
+
 It measures:
 - **Demand & Pain:** Are people actually complaining about this, or is the problem minor?
 - **Momentum & Activity:** Are developers and founders actively building in this space right now?
 - **Competition Fit:** If the tool finds 10,000 competitors, your score tanks. Red oceans get penalized heavily.
 
-```math
-\text{Score} =
-\operatorname{clamp}_{0}^{100}
-\left(
-  \frac{\sum_i w_i p_i}{\sum_i w_i}
-  -
-  \begin{cases}
-    0.5(30 - C), & D > 70 \land C < 30 \\
-    0, & \text{otherwise}
-  \end{cases}
-\right)
-```
+The score is intentionally simple to read:
+
+1. Score each pillar from 0 to 100.
+2. Multiply every pillar by its weight.
+3. Add those weighted pillar scores together.
+4. Divide by the total weight.
+5. Clamp the result between 0 and 100.
+6. If demand is above 70 but competition fit is below 30, subtract an extra red-ocean penalty.
 
-Where `p_i` are the pillar scores, `w_i` are the pillar weights, `D` is demand, and `C` is competition fit. Translation: big demand is good, but big demand plus a crushed competition score means you are sailing into a red ocean with a paper boat.
+Translation: big demand is good, but big demand plus a crushed competition score means you are sailing into a red ocean with a paper boat.
 
 The engine spits out a final score out of 100, along with a brutally honest interpretation of whether you should build it, pivot, or drop the idea entirely.
 
@@ -50,11 +64,11 @@ The engine spits out a final score out of 100, along with a brutally honest inte
 
 ## Quickstart
 
-Install dependencies, then run an evaluation:
+Install the published package, then run an evaluation:
 
 ```bash
-npm install
-npm run cli example-react.json output.json
+npm i impact-compass
+npx impact-compass idea.json output.json
 ```
 
 ### The Input Schema
@@ -79,7 +93,7 @@ Give Impact Compass an idea brief and a locked query bundle. The CLI does the di
 }
 ```
 
-## The Math Behind the Score
+## Scoring Logic
 
 We stripped out the generic averages. The engine uses logarithmic scaling, so a GitHub repo with 5,000 stars is weighted accurately against one with 5 stars. It applies relevance penalties. If a search result does not contain your target keywords, it loses 60% of its value instantly.
 

package/bin/impact-compass.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-require-imports */
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const tsxCli = require.resolve("tsx/cli");
+const cliEntry = path.resolve(__dirname, "../src/cli.ts");
+const result = spawnSync(process.execPath, [tsxCli, cliEntry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -1,14 +1,49 @@
 {
   "name": "impact-compass",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Deterministic market research CLI for startup idea validation, demand scoring, and competitive analysis.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/adityachauhan0/impact-compass.git"
   },
+  "homepage": "https://github.com/adityachauhan0/impact-compass#readme",
+  "bugs": {
+    "url": "https://github.com/adityachauhan0/impact-compass/issues"
+  },
   "private": false,
+  "bin": {
+    "impact-compass": "./bin/impact-compass.js"
+  },
+  "keywords": [
+    "market-research",
+    "idea-validation",
+    "startup-validation",
+    "product-validation",
+    "market-validation",
+    "competitive-analysis",
+    "product-market-fit",
+    "demand-validation",
+    "demand-analysis",
+    "market-analysis",
+    "startup",
+    "founder-tools",
+    "indie-hacker",
+    "mvp",
+    "cli",
+    "analytics",
+    "developer-tools",
+    "scoring",
+    "deterministic",
+    "no-ai",
+    "github",
+    "npm",
+    "reddit",
+    "hacker-news",
+    "stackexchange"
+  ],
   "files": [
+    "bin/",
     "src/",
     "DOCUMENTATION.md",
     "SKILLS.md",
@@ -28,7 +63,8 @@
     "lucide-react": "^1.16.0",
     "next": "16.2.6",
     "react": "19.2.4",
-    "react-dom": "19.2.4"
+    "react-dom": "19.2.4",
+    "tsx": "^4.22.3"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
@@ -47,36 +83,5 @@
   },
   "overrides": {
     "postcss": "8.5.15"
-  },
-  "keywords": [
-    "market-research",
-    "idea-validation",
-    "startup-validation",
-    "product-validation",
-    "market-validation",
-    "competitive-analysis",
-    "product-market-fit",
-    "demand-validation",
-    "demand-analysis",
-    "market-analysis",
-    "startup",
-    "founder-tools",
-    "indie-hacker",
-    "mvp",
-    "cli",
-    "analytics",
-    "developer-tools",
-    "scoring",
-    "deterministic",
-    "no-ai",
-    "github",
-    "npm",
-    "reddit",
-    "hacker-news",
-    "stackexchange"
-  ],
-  "homepage": "https://github.com/adityachauhan0/impact-compass#readme",
-  "bugs": {
-    "url": "https://github.com/adityachauhan0/impact-compass/issues"
   }
 }

package/src/cli.ts

@@ -59,7 +59,7 @@ function wrapText(text: string, width: number): string[] {
 async function main() {
   const args = process.argv.slice(2);
   if (args.length < 2) {
-    console.error(`Usage: npm run cli <input.json> <output.json>`);
+    console.error(`Usage: impact-compass <input.json> <output.json>`);
     process.exit(1);
   }