mt-signals 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,95 @@
+# mt-signals
+
+CLI for [MetalTorque Research Signals](https://signals.metaltorque.dev) — scored trend intelligence from HN, Reddit, ArXiv, and GitHub.
+
+## Install
+
+```bash
+npx mt-signals signals                   # Run without installing
+npm i -g mt-signals                      # Or install globally
+```
+
+## Quick Start
+
+```bash
+# List all scored signals
+mt-signals signals
+
+# Top 5 hottest signals
+mt-signals top 5
+
+# Breakout trends + hot signals (score 6+)
+mt-signals trending
+
+# Action queue by build-now / monitor / ignore
+mt-signals triage
+
+# Deep dive on a topic
+mt-signals lookup "MCP server"
+
+# Filter by category
+mt-signals signals --category=ai
+```
+
+## Commands
+
+### Discovery
+| Command | Description |
+|---------|-------------|
+| `signals` | List all scored signals (filterable by category, sort, min score) |
+| `top [N]` | Top N signals ranked by score (default: 10) |
+| `trending` | Breakout signals (1.8x+ rolling avg) and hot signals (score 6+) |
+| `triage [N]` | Group signals into `build_now`, `monitor`, and `ignore` with product mapping and recommended action |
+
+### Analysis
+| Command | Description |
+|---------|-------------|
+| `lookup <topic>` | Deep dive — score breakdown, evidence, trend history, actionable-for audience |
+| `category <name>` | All signals in a category (ai, infrastructure, security, devtools, data, business, career, market) |
+| `stats` | Aggregate stats — total signals, category breakdown, top 10 |
+
+### Management
+| Command | Description |
+|---------|-------------|
+| `recalculate` | Force score recalculation (applies time decay, detects new breakouts) |
+| `config` | View current configuration |
+| `config set <key> <value>` | Set config value (keys: `url`, `apiKey`) |
+
+## Agent / CI Usage
+
+Every command supports `--json`:
+
+```bash
+# JSON output for scripting
+mt-signals top 10 --json | jq '.[0].topic'
+
+# Pipe trending breakouts to another tool
+mt-signals trending --json | jq '.breakouts'
+
+# Pull just the build-now queue
+mt-signals triage --json | jq '.build_now'
+
+# Filter high-score AI signals
+mt-signals signals --category=ai --min=7 --json
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output raw JSON (for piping/agents) |
+| `--category=X` | Filter: ai, infrastructure, security, devtools, data, business, career, market |
+| `--sort=X` | Sort: score, urgency, buyer_intent, durability |
+| `--min=N` | Minimum score filter |
+| `--limit=N` | Max results |
+| `--version` | Print version |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MT_SIGNALS_API_KEY` | Access key for the API (overrides saved config) |
+| `MT_SIGNALS_URL` | Server URL (default: `https://signals.metaltorque.dev`) |
+| `NO_COLOR` | Disable colored output |
+
+Configuration is stored in `~/.mt-signals/config.json`.

package/bin/mt-signals.js

@@ -2,7 +2,7 @@
 "use strict";
 
 const { request, loadConfig, saveConfig, getBaseUrl, getApiKey } = require("../lib/client");
-const { fmt, catColor, scoreColor, bar, sparkline } = require("../lib/format");
+const { fmt, catColor, scoreColor, triageColor, bar, sparkline } = require("../lib/format");
 
 const args = process.argv.slice(2);
 const flags = {};
@@ -18,6 +18,12 @@ for (const a of args) {
 const cmd = positional[0];
 const json = flags.json;
 
+if (flags.version || flags.v) {
+  const { version } = require("../package.json");
+  console.log(version);
+  process.exit(0);
+}
+
 function out(data) {
   if (json) return console.log(JSON.stringify(data, null, 2));
   return data;
@@ -60,7 +66,7 @@ async function main() {
           const cat = catColor(s.category).padEnd(22);
           const topic = fmt.bold((s.topic || "").padEnd(35).slice(0, 35));
           const src = fmt.dim((s.source || "").padEnd(8).slice(0, 8));
-          console.log(`  ${sc}  ${cat}  ${topic}  ${src}  U:${bar(s.urgency, 10, 5)} B:${bar(s.buyer_intent, 10, 5)} D:${bar(s.durability, 10, 5)}`);
+          console.log(`  ${sc}  ${cat}  ${topic}  ${src}  ${triageColor(s.triage || "ignore")}  U:${bar(s.urgency, 10, 5)} B:${bar(s.buyer_intent, 10, 5)} D:${bar(s.durability, 10, 5)}`);
         }
         console.log(fmt.dim(`\n  Last recalculated: ${data.last_recalculated || "never"}\n`));
         break;
@@ -78,8 +84,9 @@ async function main() {
           const rank = fmt.dim(`#${String(i + 1).padStart(2)}`);
           const sc = scoreColor(s.score)(String((s.score || 0).toFixed(1)));
           const cat = catColor(s.category);
-          console.log(`  ${rank}  ${sc}  ${fmt.bold(s.topic || "")}  ${cat}`);
+          console.log(`  ${rank}  ${sc}  ${fmt.bold(s.topic || "")}  ${cat}  ${triageColor(s.triage || "ignore")}`);
           if (s.summary) console.log(`       ${fmt.dim(s.summary.slice(0, 90))}`);
+          if (s.recommended_action) console.log(`       ${fmt.dim(s.recommended_action)}`);
         }
         console.log();
         break;
@@ -138,6 +145,13 @@ async function main() {
         console.log(`  ${fmt.cyan("Durability:")}   ${bar(s.durability, 10, 15)} ${(s.durability || 0).toFixed(1)}`);
 
         if (s.summary) console.log(`\n  ${fmt.dim(s.summary)}`);
+        console.log(`\n  ${fmt.cyan("Triage:")}       ${triageColor(s.triage || "ignore")}`);
+        if (s.product_mapping && s.product_mapping.length > 0) {
+          console.log(`  ${fmt.cyan("Products:")}     ${s.product_mapping.join(", ")}`);
+        }
+        if (s.recommended_action) {
+          console.log(`  ${fmt.cyan("Action:")}       ${s.recommended_action}`);
+        }
 
         if (s.actionable_for && s.actionable_for.length > 0) {
           console.log(`\n  ${fmt.cyan("Actionable for:")} ${s.actionable_for.join(", ")}`);
@@ -177,6 +191,25 @@ async function main() {
         break;
       }
 
+      case "triage": {
+        const limit = positional[1] || flags.limit || "15";
+        const data = await request("GET", `/signals/triage?limit=${limit}`);
+        if (json) return out(data);
+
+        console.log(fmt.bold(`\n  Research Signal Triage\n`));
+        for (const bucket of ["build_now", "monitor", "ignore"]) {
+          const items = data[bucket] || [];
+          if (!items.length) continue;
+          console.log(`  ${triageColor(bucket)} (${items.length})\n`);
+          for (const item of items) {
+            console.log(`  ${scoreColor(item.score)(String((item.score || 0).toFixed(1)).padStart(4))}  ${fmt.bold(item.topic || "")}  ${catColor(item.category)}  ${fmt.dim((item.product_mapping || []).join(", "))}`);
+            console.log(`       ${fmt.dim(item.recommended_action || "")}`);
+          }
+          console.log();
+        }
+        break;
+      }
+
       case "stats": {
         const data = await request("GET", "/stats");
         if (json) return out(data);
@@ -261,6 +294,7 @@ ${fmt.bold("COMMANDS")}
   ${fmt.cyan("signals")}     [--category=X] [--sort=X]  List all scored signals
   ${fmt.cyan("top")}         [N]                        Top N signals (default: 10)
   ${fmt.cyan("trending")}                               Breakout signals + hot (score 6+)
+  ${fmt.cyan("triage")}      [N]                        Build-now / monitor / ignore queue
   ${fmt.cyan("lookup")}      <topic>                    Deep dive on a specific signal
   ${fmt.cyan("category")}    <name>                     Signals by category
   ${fmt.cyan("stats")}                                  Category breakdown + top 10
@@ -282,6 +316,7 @@ ${fmt.bold("EXAMPLES")}
   mt-signals signals                       # All signals ranked by score
   mt-signals top 5                         # Top 5 signals
   mt-signals trending                      # Breakouts + hot signals
+  mt-signals triage 12                     # Action queue by build/monitor/ignore
   mt-signals signals --category=ai         # AI signals only
   mt-signals signals --sort=buyer_intent   # Sort by buyer intent
   mt-signals lookup "MCP server"           # Deep dive

package/lib/client.test.js

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { EventEmitter } from 'events';
+import { createRequire } from 'module';
+import fs from 'fs';
+import path from 'path';
+
+function mockRequest(statusCode, body) {
+  return (opts, cb) => {
+    const res = new EventEmitter();
+    res.statusCode = statusCode;
+    const req = new EventEmitter();
+    req.write = vi.fn();
+    req.end = vi.fn(() => {
+      cb(res);
+      res.emit('data', typeof body === 'string' ? body : JSON.stringify(body));
+      res.emit('end');
+    });
+    req.destroy = vi.fn();
+    return req;
+  };
+}
+
+describe('research-signal cli client', () => {
+  const HOME = '/tmp/vitest-home-mt-signals';
+  const CONFIG_DIR = path.join(HOME, '.mt-signals');
+  const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+  beforeEach(() => {
+    vi.resetModules();
+    process.env.HOME = HOME;
+    delete process.env.MT_SIGNALS_URL;
+    delete process.env.MT_SIGNALS_API_KEY;
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify({ url: 'https://example.com', apiKey: 'k' }));
+  });
+
+  it('getBaseUrl and getApiKey read config', () => {
+    const require = createRequire(import.meta.url);
+    delete require.cache[require.resolve('./client.js')];
+    const mod = require('./client.js');
+    expect(mod.getBaseUrl()).toBe('https://example.com');
+    expect(mod.getApiKey()).toBe('k');
+  });
+
+  it('request appends key when provided', async () => {
+    const require = createRequire(import.meta.url);
+    const https = require('https');
+    const originalRequest = https.request;
+    const mockReq = vi.fn(mockRequest(200, { ok: 1 }));
+    https.request = mockReq;
+    delete require.cache[require.resolve('./client.js')];
+    const mod = require('./client.js');
+    await mod.request('GET', '/v1/health');
+    https.request = originalRequest;
+    const opts = mockReq.mock.calls[0][0];
+    expect(opts.path).toContain('key=k');
+  });
+});

package/lib/format.js

@@ -34,6 +34,12 @@ function scoreColor(score) {
   return fmt.dim;
 }
 
+function triageColor(triage) {
+  if (triage === "build_now") return fmt.green(triage);
+  if (triage === "monitor") return fmt.yellow(triage);
+  return fmt.dim(triage || "ignore");
+}
+
 function bar(value, max, width = 10) {
   const filled = Math.round((value / (max || 10)) * width);
   const empty = width - filled;
@@ -47,4 +53,4 @@ function sparkline(values) {
   return values.map((v) => fmt.cyan(chars[Math.min(Math.floor((v / max) * 7), 7)])).join("");
 }
 
-module.exports = { fmt, catColor, scoreColor, bar, sparkline };
+module.exports = { fmt, catColor, scoreColor, triageColor, bar, sparkline };

package/lib/format.test.js

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const fmt = require('./format.js');
+
+describe('research-signal cli format', () => {
+  it('catColor and scoreColor return strings', () => {
+    expect(fmt.catColor('ai')).toContain('ai');
+    expect(fmt.scoreColor(8)('8')).toContain('8');
+    expect(fmt.triageColor('build_now')).toContain('build_now');
+  });
+
+  it('bar and sparkline render', () => {
+    expect(fmt.bar(5, 10, 5)).toBeTypeOf('string');
+    expect(fmt.sparkline([1, 2, 3])).toBeTypeOf('string');
+  });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mt-signals",
-  "version": "1.0.0",
-  "description": "CLI for MetalTorque Research Signals — scored trend intelligence from HN, Reddit, ArXiv, and GitHub.",
+  "version": "1.2.0",
+  "description": "CLI for MetalTorque Research Signals — scored trend intelligence with build/monitor/ignore triage from HN, Reddit, ArXiv, and GitHub.",
   "bin": {
     "mt-signals": "bin/mt-signals.js"
   },