feat(linkedin-studio): trends store — research-engine inventory (§5 slice 1)

[skip-docs] internal plumbing — standalone store, no command/agent/pipeline
surface change until slice 2 wiring (mirrors specifics-bank slice 2). CLAUDE.md
"Telling"/counts untouched; lint stays 84/0/0.

Research-engine §5 (foundation layer) slice 1: the deterministic STORE half of
the persistent trend store — a topic-tagged, provenance-bearing inventory of
trend signals captured over time, so the research engine accumulates HISTORY
instead of starting amnesiac each session. Trend-side twin of the lived-specifics
bank (same store/dedup/query discipline; dedupe key is normalized title+URL, not
free-text content). Generic by architecture: nothing niche-specific lives here —
topics and source are free-form, decided upstream via config/profile.

scripts/trends/ (sibling to specifics-bank, same tsx convention):
- src/types.ts — TrendRecord/TrendStore schema (schemaVersion 1), minimal
  generic core: title, url, source, capturedAt, topics[], optional summary
- src/store.ts — pure store: normalizeField, title+url-hash id (= dedupe key),
  load/save, addTrend (dedupe + topic union on re-capture; first-sighting
  source/capturedAt kept), queryByTopic (overlap-ranked then recency), history
  (time-scoped, since/limit)
- src/cli.ts — add / query / list; default store under
  ${LINKEDIN_STUDIO_DATA:-~/.claude/linkedin-studio}/trends/ so trend history
  survives plugin upgrades/reinstalls (M0 data-path seam)
- tests/store.test.ts — 21/21 green; tsc clean
- README + .gitignore for node_modules/build

Capture/scoring agent + MCP-first routing land in slice 2; the CI binding guard
is deferred to wiring, mirroring the specifics-bank timeline.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

scripts/trends/src/cli.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * CLI for the persistent trend store (research-engine §5, foundation layer).
+ *
+ *   node --import tsx src/cli.ts add   --title "<t>" --url "<u>" --topics <a,b>
+ *                                       [--source <s>] [--summary "<s>"] [--store <path>]
+ *   node --import tsx src/cli.ts query --topics <a,b>  [--store <path>] [--json]
+ *   node --import tsx src/cli.ts list   [--since <YYYY-MM-DD>] [--limit <n>] [--store <path>] [--json]
+ *
+ * The capture agent (research-engine) calls `add` to fold a freshly-polled trend
+ * into the store, and `query`/`list` to reason over accumulated history. The
+ * polling + relevance-scoring itself lives upstream; this is the deterministic store.
+ *
+ * Exit code: 0 on success, 2 on usage error.
+ */
+
+import {
+  addTrend,
+  defaultStorePath,
+  history,
+  loadStore,
+  queryByTopic,
+  saveStore,
+} from "./store.js";
+
+function parseFlags(args: string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        out[key] = "true";
+      } else {
+        out[key] = next;
+        i++;
+      }
+    }
+  }
+  return out;
+}
+
+function splitTopics(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .split(",")
+    .map((t) => t.trim())
+    .filter((t) => t.length > 0);
+}
+
+function usage(msg: string): never {
+  console.error(`error: ${msg}`);
+  console.error(
+    "usage:\n" +
+      '  add --title "<t>" --url "<u>" --topics <a,b> [--source <s>] [--summary "<s>"] [--store <path>]\n' +
+      "  query --topics <a,b> [--store <path>] [--json]\n" +
+      "  list [--since <YYYY-MM-DD>] [--limit <n>] [--store <path>] [--json]",
+  );
+  process.exit(2);
+}
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function main(): void {
+  const [command, ...rest] = process.argv.slice(2);
+  const flags = parseFlags(rest);
+  const storePath = flags.store ?? defaultStorePath();
+  const asJson = flags.json === "true";
+
+  if (command === "add") {
+    const title = flags.title;
+    if (!title || title === "true") usage('add needs --title "<text>"');
+    const url = flags.url;
+    if (!url || url === "true") usage('add needs --url "<url>"');
+    const topics = splitTopics(flags.topics);
+    if (topics.length === 0) usage("add needs --topics <a,b>");
+    const store = loadStore(storePath);
+    const res = addTrend(store, {
+      title,
+      url,
+      source: flags.source && flags.source !== "true" ? flags.source : "manual",
+      capturedAt: today(),
+      topics,
+      ...(flags.summary && flags.summary !== "true" ? { summary: flags.summary } : {}),
+    });
+    saveStore(storePath, res.store);
+    if (res.added) {
+      console.log(`Added: ${title}`);
+    } else {
+      console.log(`Duplicate — already in store${res.merged ? " (topics unioned)" : ""}: ${title}`);
+    }
+    console.log(`Store: ${storePath} (${res.store.trends.length} trends)`);
+    return;
+  }
+
+  if (command === "query") {
+    const topics = splitTopics(flags.topics);
+    if (topics.length === 0) usage("query needs --topics <a,b>");
+    const hits = queryByTopic(loadStore(storePath), topics);
+    if (asJson) {
+      console.log(JSON.stringify(hits, null, 2));
+      return;
+    }
+    if (hits.length === 0) {
+      console.log(`No trends found for topics: ${topics.join(", ")}`);
+      console.log("→ poll fresh signals (research engine), then `add` them.");
+      return;
+    }
+    console.log(`${hits.length} trend(s) for: ${topics.join(", ")}`);
+    for (const { trend, topicOverlap } of hits) {
+      console.log(`\n  · (overlap ${topicOverlap}) ${trend.title}`);
+      console.log(`    ${trend.url}`);
+      console.log(`    topics: ${trend.topics.join(", ")} — ${trend.source}, ${trend.capturedAt}`);
+      if (trend.summary) console.log(`    ${trend.summary}`);
+    }
+    return;
+  }
+
+  if (command === "list") {
+    const opts: { since?: string; limit?: number } = {};
+    if (flags.since && flags.since !== "true") opts.since = flags.since;
+    if (flags.limit && flags.limit !== "true") {
+      const n = Number.parseInt(flags.limit, 10);
+      if (Number.isNaN(n) || n < 0) usage("--limit must be a non-negative integer");
+      opts.limit = n;
+    }
+    const rows = history(loadStore(storePath), opts);
+    if (asJson) {
+      console.log(JSON.stringify(rows, null, 2));
+      return;
+    }
+    const scope = opts.since ? ` since ${opts.since}` : "";
+    console.log(`Store: ${storePath} — ${rows.length} trend(s)${scope}`);
+    for (const t of rows) {
+      console.log(`  · ${t.capturedAt}  ${t.title}  {${t.topics.join(", ")}}`);
+    }
+    return;
+  }
+
+  usage(command ? `unknown command: ${command}` : "no command given");
+}
+
+main();

scripts/trends/src/store.ts

@@ -0,0 +1,172 @@
+/**
+ * Deterministic store + query for the persistent trend store (research-engine §5).
+ *
+ * Pure where it matters: id derivation, dedupe, topic query, and history are
+ * side-effect-free and fully testable. Only loadStore/saveStore touch the
+ * filesystem. No AI, no network — this module is reliable inventory, not a
+ * creatively-interpreted blob. The capture that POPULATES the store (polling
+ * research MCPs / web search, scoring relevance) lives in the agent/command
+ * layer; this module only stores, dedupes, and serves trend signals.
+ *
+ * Twin of scripts/specifics-bank/src/bank.ts — same discipline, different
+ * dedupe key (normalized title+URL instead of free-text content).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+
+import { SCHEMA_VERSION } from "./types.js";
+import type { TrendStore, TrendRecord, TrendQueryHit } from "./types.js";
+
+export { SCHEMA_VERSION } from "./types.js";
+
+/** What a caller supplies to addTrend — the id is derived, never passed in. */
+export interface TrendInput {
+  title: string;
+  url: string;
+  source: string;
+  capturedAt: string;
+  topics: string[];
+  summary?: string;
+}
+
+export interface AddResult {
+  store: TrendStore;
+  /** true iff a new trend was appended (false = duplicate title+url). */
+  added: boolean;
+  /** true iff an existing duplicate gained new topic tags via union. */
+  merged: boolean;
+}
+
+/** Options for a recency-ordered history slice. */
+export interface HistoryOptions {
+  /** Inclusive lower bound on capturedAt (ISO date); older trends are excluded. */
+  since?: string;
+  /** Cap on the number of returned trends (newest kept). */
+  limit?: number;
+}
+
+/** Lowercase + trim + collapse all whitespace runs to a single space. */
+export function normalizeField(value: string): string {
+  return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+/**
+ * Stable id = first 12 hex of sha256(normalized title + "\n" + normalized url);
+ * also the dedupe key. The URL is folded to lowercase too: host case is
+ * insignificant, and the combined title+url key makes a false merge on a
+ * case-only path difference vanishingly unlikely. Richer URL canonicalization
+ * (trailing-slash / query-param stripping) is deferred to a later slice if
+ * dedup ever proves leaky.
+ */
+export function trendId(title: string, url: string): string {
+  const key = normalizeField(title) + "\n" + normalizeField(url);
+  return createHash("sha256").update(key).digest("hex").slice(0, 12);
+}
+
+export function emptyStore(): TrendStore {
+  return { schemaVersion: SCHEMA_VERSION, trends: [] };
+}
+
+/** Read the store; a missing file is an empty store (never throws on absence). */
+export function loadStore(path: string): TrendStore {
+  if (!existsSync(path)) return emptyStore();
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<TrendStore>;
+  return {
+    schemaVersion: parsed.schemaVersion ?? SCHEMA_VERSION,
+    trends: Array.isArray(parsed.trends) ? parsed.trends : [],
+  };
+}
+
+/** Write the store as pretty JSON, creating the parent dir if needed. */
+export function saveStore(path: string, store: TrendStore): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(store, null, 2) + "\n", "utf8");
+}
+
+/** Union of two tag lists, order-stable on the first list, case-insensitive dedupe. */
+function unionTopics(existing: string[], incoming: string[]): { topics: string[]; changed: boolean } {
+  const seen = new Set(existing.map((t) => t.toLowerCase()));
+  const topics = [...existing];
+  let changed = false;
+  for (const t of incoming) {
+    if (!seen.has(t.toLowerCase())) {
+      seen.add(t.toLowerCase());
+      topics.push(t);
+      changed = true;
+    }
+  }
+  return { topics, changed };
+}
+
+/**
+ * Add a trend, deduping on normalized title+url. A duplicate does not append a
+ * second entry — instead its topic tags are unioned in, so the same trend
+ * re-surfaced under a new edition's topics enriches the existing record. The
+ * FIRST sighting's source + capturedAt are kept (provenance of first sight);
+ * title/url/summary are stored VERBATIM, only the id is normalized.
+ */
+export function addTrend(store: TrendStore, input: TrendInput): AddResult {
+  const id = trendId(input.title, input.url);
+  const existing = store.trends.find((t) => t.id === id);
+  if (existing) {
+    const { topics, changed } = unionTopics(existing.topics, input.topics);
+    existing.topics = topics;
+    return { store, added: false, merged: changed };
+  }
+  const trend: TrendRecord = {
+    id,
+    title: input.title,
+    url: input.url,
+    source: input.source,
+    capturedAt: input.capturedAt,
+    topics: [...input.topics],
+    ...(input.summary !== undefined ? { summary: input.summary } : {}),
+  };
+  store.trends.push(trend);
+  return { store, added: true, merged: false };
+}
+
+/**
+ * Trends whose topics overlap the query, ranked by overlap (desc) then recency
+ * (capturedAt desc). Topic matching is case-insensitive. Non-matches are
+ * excluded.
+ */
+export function queryByTopic(store: TrendStore, topics: string[]): TrendQueryHit[] {
+  const wanted = topics.map((t) => t.toLowerCase());
+  const hits: TrendQueryHit[] = [];
+  for (const trend of store.trends) {
+    const have = new Set(trend.topics.map((t) => t.toLowerCase()));
+    const topicOverlap = wanted.reduce((n, t) => (have.has(t) ? n + 1 : n), 0);
+    if (topicOverlap > 0) hits.push({ trend, topicOverlap });
+  }
+  hits.sort(
+    (a, b) => b.topicOverlap - a.topicOverlap || b.trend.capturedAt.localeCompare(a.trend.capturedAt),
+  );
+  return hits;
+}
+
+/**
+ * Trend history, newest first. Optionally filtered to capturedAt >= `since`
+ * (inclusive) and capped to `limit`. The time-scoped complement to
+ * queryByTopic's topic-scoped view; together they are the "historikk-query".
+ */
+export function history(store: TrendStore, opts: HistoryOptions = {}): TrendRecord[] {
+  let out = [...store.trends];
+  if (opts.since !== undefined) out = out.filter((t) => t.capturedAt >= opts.since!);
+  out.sort((a, b) => b.capturedAt.localeCompare(a.capturedAt));
+  if (opts.limit !== undefined) out = out.slice(0, opts.limit);
+  return out;
+}
+
+/**
+ * Default store path under the per-user data dir (M0 data-path convention), so
+ * the trend history survives plugin upgrades/reinstalls. `LINKEDIN_STUDIO_DATA`
+ * overrides the root; otherwise `~/.claude/linkedin-studio`.
+ */
+export function defaultStorePath(): string {
+  const root = process.env.LINKEDIN_STUDIO_DATA ?? join(homedir(), ".claude", "linkedin-studio");
+  return join(root, "trends", "trends.json");
+}

scripts/trends/src/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Types for the persistent trend store (research-engine §5, foundation layer).
+ *
+ * The store is the research engine's accumulating memory: a topic-tagged,
+ * provenance-bearing inventory of trend signals captured over time, so the
+ * engine reasons over HISTORY instead of starting amnesiac each session. It is
+ * the trend-side twin of the lived-specifics bank (scripts/specifics-bank):
+ * same deterministic store/dedup/query discipline, different dedupe key
+ * (normalized title+URL, since a trend is identified by its headline+source,
+ * not by free-text content).
+ *
+ * GENERIC BY ARCHITECTURE (retning §5 — nisje-agnostisk motor): nothing
+ * niche-specific lives in this module. A `TrendRecord` carries free-form
+ * `topics` tags and a free-form `source` string; which topics matter and which
+ * sources to poll are decided upstream (config/profile + the capture agent),
+ * never hard-coded here. The same store serves any niche.
+ *
+ * Forward-compatible with the profile-evolution / "second brain" architecture:
+ * a typed store in the per-user data dir (`${LINKEDIN_STUDIO_DATA}`), so the
+ * trend history survives plugin upgrades/reinstalls via the M0 data-path seam.
+ * The minimal core here (title, url, source, capturedAt, topics, optional
+ * summary) can gain fields (relevance score, first-mover timing, status) in a
+ * later slice without breaking the shape.
+ */
+
+export interface TrendRecord {
+  /** Stable id — a short hash of the normalized title+url; doubles as the dedupe key. */
+  id: string;
+  /** The trend headline, stored VERBATIM (normalized only to derive the id). */
+  title: string;
+  /** The source URL, stored VERBATIM (normalized only to derive the id). */
+  url: string;
+  /** Capture origin: a research-MCP name (e.g. "tavily"), "websearch", or "manual". */
+  source: string;
+  /** ISO-8601 date the trend was captured. Supplied by the caller (CLI edge). */
+  capturedAt: string;
+  /** Topic tags for query-by-topic. Unioned across re-captures of the same trend. */
+  topics: string[];
+  /** Optional short summary of the trend, stored VERBATIM. */
+  summary?: string;
+}
+
+export interface TrendStore {
+  schemaVersion: number;
+  trends: TrendRecord[];
+}
+
+/** A query hit: the trend plus how many of the queried topics it matched. */
+export interface TrendQueryHit {
+  trend: TrendRecord;
+  /** Number of queried topics present on the trend (≥1 for a hit). */
+  topicOverlap: number;
+}
+
+export const SCHEMA_VERSION = 1;