@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/embed/workspaces.mjs

@@ -0,0 +1,297 @@
+/**
+ * lib/embed/workspaces.mjs — Multi-PM workspace management.
+ *
+ * Workspaces isolate PM workstreams while enabling cross-workspace visibility.
+ * Each workspace has an owner (PM), assigned customers, and product areas.
+ *
+ * Storage:
+ *   ~/.cx/product-intel/workspaces/<workspace-id>.json
+ *   ~/.cx/product-intel/workspaces/index.json — quick lookup
+ *
+ * Intake packets are routed to workspaces based on customer assignment
+ * or product area matching. Cross-workspace signals trigger notifications.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+
+const WORKSPACES_DIR = join(homedir(), '.cx', 'product-intel', 'workspaces');
+const INDEX_FILE = join(WORKSPACES_DIR, 'index.json');
+
+/**
+ * Ensure workspaces directory exists.
+ */
+function ensureDir() {
+  if (!existsSync(WORKSPACES_DIR)) {
+    mkdirSync(WORKSPACES_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Read the index file.
+ * @returns {{ [key: string]: { id: string, name: string, owner: string, status: string } }}
+ */
+function readIndex() {
+  if (!existsSync(INDEX_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(INDEX_FILE, 'utf8'));
+  } catch (err) {
+    process.stderr.write('[workspaces.mjs] readIndex: ' + (err?.message ?? String(err)) + '\n');
+    return {};
+  }
+}
+
+/**
+ * Write the index file.
+ * @param {object} index
+ */
+function writeIndex(index) {
+  ensureDir();
+  writeFileSync(INDEX_FILE, JSON.stringify(index, null, 2) + '\n');
+}
+
+/**
+ * Create a new workspace.
+ *
+ * @param {object} opts
+ * @param {string} opts.name - Workspace name (required)
+ * @param {string} opts.owner - PM or owner name (required)
+ * @param {string} [opts.description] - Workspace description
+ * @param {string[]} [opts.productAreas] - Product areas this workspace covers
+ * @param {string[]} [opts.customerIds] - Customer IDs assigned to this workspace
+ * @returns {{ id: string, workspace: Workspace }}
+ */
+export function createWorkspace({ name, owner, description, productAreas = [], customerIds = [] }) {
+  if (!name || typeof name !== 'string' || !name.trim()) {
+    throw new Error('name is required');
+  }
+  if (!owner || typeof owner !== 'string' || !owner.trim()) {
+    throw new Error('owner is required');
+  }
+
+  ensureDir();
+
+  const id = `ws-${randomUUID().slice(0, 8)}`;
+  const workspace = {
+    id,
+    name: name.trim(),
+    owner,
+    description: description || '',
+    productAreas,
+    customerIds,
+    status: 'active',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+
+  const filePath = join(WORKSPACES_DIR, `${id}.json`);
+  writeFileSync(filePath, JSON.stringify(workspace, null, 2) + '\n');
+
+  // Update index
+  const index = readIndex();
+  index[id] = {
+    id,
+    name: workspace.name,
+    owner: workspace.owner,
+    status: workspace.status,
+  };
+  writeIndex(index);
+
+  return { id, workspace };
+}
+
+/**
+ * Get a workspace by ID.
+ * @param {string} workspaceId
+ * @returns {Workspace | null}
+ */
+export function getWorkspace(workspaceId) {
+  ensureDir();
+
+  const filePath = join(WORKSPACES_DIR, `${workspaceId}.json`);
+  if (!existsSync(filePath)) return null;
+
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    process.stderr.write('[workspaces.mjs] getWorkspace: ' + (err?.message ?? String(err)) + '\n');
+    return null;
+  }
+}
+
+/**
+ * List all workspaces.
+ * @param {object} [opts]
+ * @param {string} [opts.owner] - Filter by owner
+ * @param {string} [opts.status] - Filter by status
+ * @returns {Array<Workspace>}
+ */
+export function listWorkspaces(opts = {}) {
+  ensureDir();
+
+  const index = readIndex();
+  let results = Object.values(index).map(entry => getWorkspace(entry.id)).filter(Boolean);
+
+  if (opts.owner) {
+    results = results.filter(r => r.owner === opts.owner);
+  }
+
+  if (opts.status) {
+    results = results.filter(r => r.status === opts.status);
+  }
+
+  return results.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+/**
+ * Update a workspace.
+ *
+ * @param {string} workspaceId
+ * @param {object} updates
+ * @param {string} [updates.name]
+ * @param {string} [updates.owner]
+ * @param {string} [updates.description]
+ * @param {string[]} [updates.productAreas]
+ * @param {string[]} [updates.customerIds]
+ * @param {string} [updates.status]
+ * @returns {{ success: boolean, updatedAt: string }}
+ */
+export function updateWorkspace(workspaceId, updates) {
+  const workspace = getWorkspace(workspaceId);
+  if (!workspace) {
+    throw new Error(`Workspace not found: ${workspaceId}`);
+  }
+
+  const updated = {
+    ...workspace,
+    ...updates,
+    updatedAt: new Date().toISOString(),
+  };
+
+  const filePath = join(WORKSPACES_DIR, `${workspaceId}.json`);
+  writeFileSync(filePath, JSON.stringify(updated, null, 2) + '\n');
+
+  // Update index
+  const index = readIndex();
+  if (index[workspaceId]) {
+    index[workspaceId] = {
+      id: updated.id,
+      name: updated.name,
+      owner: updated.owner,
+      status: updated.status,
+    };
+    writeIndex(index);
+  }
+
+  return { success: true, updatedAt: updated.updatedAt };
+}
+
+/**
+ * Delete a workspace.
+ * @param {string} workspaceId
+ * @returns {{ success: boolean }}
+ */
+export function deleteWorkspace(workspaceId) {
+  const filePath = join(WORKSPACES_DIR, `${workspaceId}.json`);
+  if (!existsSync(filePath)) {
+    throw new Error(`Workspace not found: ${workspaceId}`);
+  }
+
+  // Remove from filesystem
+  const { unlinkSync } = require('node:fs');
+  unlinkSync(filePath);
+
+  // Remove from index
+  const index = readIndex();
+  delete index[workspaceId];
+  writeIndex(index);
+
+  return { success: true };
+}
+
+/**
+ * Route an intake signal to a workspace based on customer or product area.
+ *
+ * @param {object} signal
+ * @param {string} [signal.customerId] - Customer ID if known
+ * @param {string} [signal.productArea] - Product area mentioned
+ * @param {string} [signal.text] - Signal text for keyword matching
+ * @returns {{ workspaceId: string | null, workspaceName: string | null, isCrossWorkspace: boolean, matchedWorkspaces: string[] }}
+ */
+export function routeSignalToWorkspace(signal) {
+  const workspaces = listWorkspaces({ status: 'active' });
+  const matchedWorkspaces = [];
+
+  // If customer ID is provided, find workspace that owns this customer
+  if (signal.customerId) {
+    for (const ws of workspaces) {
+      if (ws.customerIds?.includes(signal.customerId)) {
+        matchedWorkspaces.push(ws.id);
+      }
+    }
+  }
+
+  // If product area is provided, match workspaces that cover it
+  if (signal.productArea) {
+    for (const ws of workspaces) {
+      if (ws.productAreas?.some(area =>
+        area.toLowerCase().includes(signal.productArea.toLowerCase())
+      )) {
+        if (!matchedWorkspaces.includes(ws.id)) {
+          matchedWorkspaces.push(ws.id);
+        }
+      }
+    }
+  }
+
+  // If text is provided, do keyword matching on product areas
+  if (signal.text && matchedWorkspaces.length === 0) {
+    const textLower = signal.text.toLowerCase();
+    for (const ws of workspaces) {
+      if (ws.productAreas?.some(area => textLower.includes(area.toLowerCase()))) {
+        matchedWorkspaces.push(ws.id);
+      }
+    }
+  }
+
+  // Determine routing
+  if (matchedWorkspaces.length === 0) {
+    // No match — route to default workspace or null
+    const defaultWs = workspaces.find(ws => ws.name === 'default') || workspaces[0];
+    return {
+      workspaceId: defaultWs?.id || null,
+      workspaceName: defaultWs?.name || null,
+      isCrossWorkspace: false,
+      matchedWorkspaces: [],
+    };
+  }
+
+  if (matchedWorkspaces.length === 1) {
+    return {
+      workspaceId: matchedWorkspaces[0],
+      workspaceName: getWorkspace(matchedWorkspaces[0])?.name || null,
+      isCrossWorkspace: false,
+      matchedWorkspaces,
+    };
+  }
+
+  // Multiple matches — this is a cross-workspace signal
+  return {
+    workspaceId: matchedWorkspaces[0], // Route to first match
+    workspaceName: getWorkspace(matchedWorkspaces[0])?.name || null,
+    isCrossWorkspace: true,
+    matchedWorkspaces,
+  };
+}
+
+/**
+ * Get workspace by owner name.
+ * @param {string} ownerName
+ * @returns {Workspace | null}
+ */
+export function getWorkspaceByOwner(ownerName) {
+  const workspaces = listWorkspaces({ status: 'active' });
+  return workspaces.find(ws => ws.owner === ownerName) || null;
+}

package/lib/engine/chunker-headings.mjs

@@ -0,0 +1,110 @@
+/**
+ * lib/engine/chunker-headings.mjs — heading-prefix Chunker plugin.
+ *
+ * Splits a markdown document into chunks at heading boundaries (`#`, `##`,
+ * `###`, …) and prepends each chunk with the chain of ancestor headings so
+ * that each retrieved chunk carries enough doc-relative context to be
+ * understood on its own. This is a zero-dep approximation of contextual
+ * retrieval: instead of a per-chunk LM-generated context (the strongest
+ * available technique), the heading chain provides "where in the document
+ * is this from" context for free.
+ *
+ * Plain-text docs (no headings) collapse to a single chunk; the input is
+ * returned as one chunk with no prefix.
+ *
+ * Plugin contract (Chunker):
+ *   meta: { id }
+ *   chunk(doc) → chunk[]
+ *
+ * `doc` shape:
+ *   { id, title?, body, metadata? } — body is the markdown source.
+ *
+ * Output chunk shape:
+ *   { id, body, title, prefix?, metadata }
+ *
+ * The prefix is the joined heading chain (e.g. "# Auth > ## JWT > ### Refresh").
+ * Callers that embed `prefix + body` will retrieve more accurately than if
+ * they embedded body alone.
+ */
+
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/;
+
+function* iterChunks(body) {
+  const lines = String(body || '').split(/\r?\n/);
+  const stack = [];
+  let buffer = [];
+  let active = null;
+
+  function flush() {
+    const content = buffer.join('\n').trim();
+    if (content || active) {
+      yieldOne({
+        prefix: stack.map((h) => '#'.repeat(h.level) + ' ' + h.text).join(' > '),
+        title: active?.text || '',
+        body: content,
+      });
+    }
+  }
+
+  let queue = [];
+  function yieldOne(chunk) { queue.push(chunk); }
+
+  for (const line of lines) {
+    const m = line.match(HEADING);
+    if (m) {
+      flush();
+      buffer = [];
+      const level = m[1].length;
+      const text = m[2];
+      while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+        stack.pop();
+      }
+      const heading = { level, text };
+      stack.push(heading);
+      active = heading;
+      while (queue.length) yield queue.shift();
+    } else {
+      buffer.push(line);
+    }
+  }
+  flush();
+  while (queue.length) yield queue.shift();
+}
+
+export function create(/* opts */) {
+  return {
+    meta: { id: 'headings-prefix' },
+    async chunk(doc) {
+      const docs = Array.isArray(doc) ? doc : [doc];
+      const out = [];
+      for (const d of docs) {
+        if (!d) continue;
+        const baseId = d.id || '';
+        const body = d.body || '';
+        const sub = [...iterChunks(body)];
+        if (sub.length <= 1) {
+          out.push({
+            id: baseId,
+            title: d.title || sub[0]?.title || '',
+            body,
+            prefix: sub[0]?.prefix || '',
+            metadata: d.metadata || {},
+          });
+          continue;
+        }
+        sub.forEach((chunk, i) => {
+          out.push({
+            id: `${baseId}#${i}`,
+            title: chunk.title,
+            body: chunk.body,
+            prefix: chunk.prefix,
+            metadata: { ...(d.metadata || {}), parentDocId: baseId, headingChainIndex: i },
+          });
+        });
+      }
+      return out;
+    },
+  };
+}
+
+export default create;

package/lib/engine/compressor-heuristic.mjs

@@ -0,0 +1,100 @@
+/**
+ * lib/engine/compressor-heuristic.mjs — TF-IDF Compressor plugin (zero deps).
+ *
+ * Scores every sentence in the input by the mean IDF of its content terms
+ * (over the input itself), keeps the top-N sentences in their original order
+ * until the requested compression ratio is met, and returns the result. This
+ * is a lossy summarizer — fine for context blocks where the model needs the
+ * gist, not exact wording.
+ *
+ * The wider plan calls for a learned compressor (LLMLingua-2 token
+ * classification on ONNX) as a plugin override. That belongs in its own
+ * module so operators can opt into the model download. The default keeps
+ * the contract live, runs on every machine, and gives a measurable win
+ * for context-block compression where exact phrasing is not load-bearing.
+ *
+ * Plugin contract (Compressor):
+ *   meta: { id, ratio }
+ *   compress(text, opts) → text
+ *
+ * `ratio` is the target output / input length (0.5 = halve the text).
+ * `maxTokens` (estimated from text length) acts as a hard ceiling that
+ * overrides ratio when present.
+ */
+
+import { tokenize, buildTermFrequencies, buildIdf } from '../storage/embeddings.mjs';
+
+const SENTENCE_BOUNDARY = /(?<=[.!?])\s+(?=[A-Z(\[])|\n{2,}/;
+
+function splitSentences(text) {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return [];
+  return trimmed.split(SENTENCE_BOUNDARY).map((s) => s.trim()).filter(Boolean);
+}
+
+function scoreSentence(sentence, idf) {
+  const terms = tokenize(sentence);
+  if (terms.length === 0) return 0;
+  let total = 0;
+  let counted = 0;
+  for (const term of terms) {
+    const v = idf.get(term);
+    if (v !== undefined) {
+      total += v;
+      counted += 1;
+    }
+  }
+  return counted === 0 ? 0 : total / counted;
+}
+
+const APPROX_CHARS_PER_TOKEN = 4;
+
+export function create({ ratio = 0.5 } = {}) {
+  return {
+    meta: { id: 'heuristic-tfidf-sentence', ratio },
+    async compress(text, opts = {}) {
+      const ratioEff = Math.max(0.05, Math.min(1, opts.ratio ?? ratio));
+      const input = String(text || '');
+      if (!input.trim()) return '';
+
+      const sentences = splitSentences(input);
+      if (sentences.length <= 1) return input;
+
+      const tfMaps = sentences.map((s) => buildTermFrequencies(s));
+      const idf = buildIdf(tfMaps);
+
+      const scored = sentences.map((sentence, index) => ({
+        index,
+        sentence,
+        score: scoreSentence(sentence, idf),
+        len: sentence.length,
+      }));
+
+      let targetChars = Math.floor(input.length * ratioEff);
+      if (typeof opts.maxTokens === 'number' && opts.maxTokens > 0) {
+        const ceiling = opts.maxTokens * APPROX_CHARS_PER_TOKEN;
+        if (ceiling < targetChars) targetChars = ceiling;
+      }
+
+      const ordered = [...scored].sort((a, b) => b.score - a.score || a.index - b.index);
+      const kept = new Set();
+      let used = 0;
+      for (const candidate of ordered) {
+        if (used + candidate.len > targetChars && kept.size > 0) continue;
+        kept.add(candidate.index);
+        used += candidate.len + 1;
+        if (used >= targetChars) break;
+      }
+
+      if (kept.size === 0) kept.add(ordered[0].index);
+
+      return scored
+        .filter((s) => kept.has(s.index))
+        .sort((a, b) => a.index - b.index)
+        .map((s) => s.sentence)
+        .join(' ');
+    },
+  };
+}
+
+export default create;