hyperstack-core 1.2.0 → 1.5.0

package/src/parser.js

@@ -0,0 +1,305 @@
+/**
+ * hyperstack-core parser
+ *
+ * Zero-dependency markdown/text/conversation → HyperStack cards + edges.
+ * No LLM. Pure regex. Preserves document structure as typed graph edges.
+ */
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+function inferCardType(title, body) {
+  const text = `${title} ${body}`.toLowerCase();
+  if (/\b(decided?|chose|picked|selected|agreed|ruling)\b/.test(text)) return "decision";
+  if (/\b(todo|task|sprint|milestone|epic|ticket|backlog)\b/.test(text)) return "project";
+  if (/\b(always|never|prefer|convention|standard|rule|must)\b/.test(text)) return "preference";
+  if (/\b(step|process|how.to|guide|install|setup|deploy|workflow|tutorial)\b/.test(text)) return "workflow";
+  if (/\b(bug|fix|error|issue|patch|regression|incident)\b/.test(text)) return "event";
+  if (/\b(person|team|role|engineer|manager|founder)\b/.test(text)) return "person";
+  return "general";
+}
+
+function extractKeywords(title, body) {
+  const kw = new Set();
+  let m;
+  const backticks = /`([^`]+)`/g;
+  while ((m = backticks.exec(body)) !== null) kw.add(m[1].toLowerCase());
+  const mentions = /@(\w+)/g;
+  while ((m = mentions.exec(body)) !== null) kw.add(m[1].toLowerCase());
+  return [...kw].slice(0, 15);
+}
+
+function extractLinksFromBody(body) {
+  const links = [];
+
+  // Markdown links → related edges for internal refs
+  const mdLink = /\[([^\]]+)\]\(([^)]+)\)/g;
+  let m;
+  while ((m = mdLink.exec(body)) !== null) {
+    const href = m[2];
+    if (href.startsWith("#")) {
+      links.push({ target: slugify(href.slice(1)), relation: "related" });
+    } else if (/\.md(#|$)/.test(href)) {
+      const slug = slugify(href.replace(/\.md.*$/, "").replace(/^.*\//, ""));
+      if (slug) links.push({ target: slug, relation: "related" });
+    }
+  }
+
+  // Semantic patterns → typed edges
+  const patterns = [
+    { re: /depends\s+on\s+["`']?([\w][\w-]*)["`']?/gi, relation: "depends_on" },
+    { re: /blocked?\s+by\s+["`']?([\w][\w-]*)["`']?/gi, relation: "blocked_by" },
+    { re: /blocks?\s+["`']?([\w][\w-]*)["`']?/gi, relation: "blocks" },
+    { re: /decided\s+by\s+@?([\w][\w-]*)/gi, relation: "decided" },
+    { re: /assigned\s+to\s+@?([\w][\w-]*)/gi, relation: "assigned_to" },
+    { re: /owned?\s+by\s+@?([\w][\w-]*)/gi, relation: "owns" },
+  ];
+  for (const { re, relation } of patterns) {
+    while ((m = re.exec(body)) !== null) {
+      const target = slugify(m[1]);
+      if (target && target.length > 1) links.push({ target, relation });
+    }
+  }
+
+  return links;
+}
+
+// ─── Markdown Parser ──────────────────────────────────
+
+function parseMarkdown(content, prefix) {
+  const cards = [];
+  const headingRe = /^(#{1,6})\s+(.+)$/gm;
+  const headings = [];
+  let m;
+
+  while ((m = headingRe.exec(content)) !== null) {
+    headings.push({
+      level: m[1].length,
+      title: m[2].trim(),
+      pos: m.index,
+      contentStart: m.index + m[0].length,
+    });
+  }
+
+  if (headings.length === 0) return parsePlainText(content, prefix);
+
+  const usedSlugs = new Set();
+  function uniqueSlug(base) {
+    let slug = base;
+    let i = 2;
+    while (usedSlugs.has(slug)) { slug = `${base}-${i}`; i++; }
+    usedSlugs.add(slug);
+    return slug;
+  }
+
+  // Preamble before first heading
+  const preamble = content.slice(0, headings[0].pos).trim();
+  if (preamble.length > 30) {
+    const slug = uniqueSlug(prefix ? `${prefix}/intro` : "intro");
+    cards.push({
+      slug,
+      title: prefix ? `${prefix} — Introduction` : "Introduction",
+      body: preamble.slice(0, 1000),
+      cardType: "general",
+      keywords: extractKeywords("intro", preamble),
+      links: [],
+    });
+  }
+
+  // Parent stack for hierarchy: [{level, slug}]
+  const stack = [];
+  let edgeCount = 0;
+
+  for (let i = 0; i < headings.length; i++) {
+    const h = headings[i];
+    const bodyEnd = i + 1 < headings.length ? headings[i + 1].pos : content.length;
+    const body = content.slice(h.contentStart, bodyEnd).trim();
+
+    const baseSlug = slugify(h.title);
+    if (!baseSlug) continue;
+    const slug = uniqueSlug(prefix ? `${prefix}/${baseSlug}` : baseSlug);
+    const links = [];
+
+    // Hierarchy edge
+    while (stack.length > 0 && stack[stack.length - 1].level >= h.level) stack.pop();
+    if (stack.length > 0) {
+      links.push({ target: stack[stack.length - 1].slug, relation: "subtask_of" });
+      edgeCount++;
+    }
+    stack.push({ level: h.level, slug });
+
+    // Content-derived edges
+    const bodyLinks = extractLinksFromBody(body);
+    for (const l of bodyLinks) {
+      const target = prefix && !l.target.includes("/") ? `${prefix}/${l.target}` : l.target;
+      links.push({ target, relation: l.relation });
+      edgeCount++;
+    }
+
+    cards.push({
+      slug,
+      title: h.title,
+      body: body.slice(0, 1000),
+      cardType: inferCardType(h.title, body),
+      keywords: extractKeywords(h.title, body),
+      links,
+    });
+  }
+
+  return { cards, edgeCount, format: "markdown" };
+}
+
+// ─── Conversation Parser ──────────────────────────────
+
+const SPEAKER_RE = /^(User|Human|Assistant|AI|System|Bot)\s*:/i;
+
+function isConversationLog(text) {
+  const lines = text.split("\n");
+  let hits = 0;
+  for (const line of lines) {
+    if (SPEAKER_RE.test(line.trim())) hits++;
+    if (hits >= 2) return true;
+  }
+  return false;
+}
+
+function parseConversation(content, prefix) {
+  const cards = [];
+  const turnRe = /^(User|Human|Assistant|AI|System|Bot)\s*:/gim;
+  const starts = [];
+  let m;
+  while ((m = turnRe.exec(content)) !== null) {
+    starts.push({ index: m.index, speaker: m[1].toLowerCase(), after: m.index + m[0].length });
+  }
+
+  if (starts.length === 0) return parsePlainText(content, prefix);
+
+  let prevSlug = null;
+  let edgeCount = 0;
+
+  for (let i = 0; i < starts.length; i++) {
+    const t = starts[i];
+    const end = i + 1 < starts.length ? starts[i + 1].index : content.length;
+    const message = content.slice(t.after, end).trim();
+    if (!message) continue;
+
+    const idx = i + 1;
+    const slug = prefix ? `${prefix}/turn-${idx}` : `turn-${idx}`;
+    const snippet = message.slice(0, 60) + (message.length > 60 ? "..." : "");
+    const links = [];
+
+    if (prevSlug) {
+      links.push({ target: prevSlug, relation: "related" });
+      edgeCount++;
+    }
+
+    cards.push({
+      slug,
+      title: `[${t.speaker}] ${snippet}`,
+      body: message.slice(0, 1000),
+      cardType: "event",
+      keywords: [t.speaker, `turn-${idx}`],
+      links,
+      meta: { speaker: t.speaker, turnIndex: idx },
+    });
+
+    prevSlug = slug;
+  }
+
+  return { cards, edgeCount, format: "conversation" };
+}
+
+// ─── Plain Text Parser ────────────────────────────────
+
+function parsePlainText(content, prefix) {
+  const cards = [];
+  const paragraphs = content
+    .split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .filter((p) => p.length > 20);
+
+  if (paragraphs.length === 0) {
+    return { cards: [], edgeCount: 0, format: "text" };
+  }
+
+  const usedSlugs = new Set();
+  let prevSlug = null;
+  let edgeCount = 0;
+
+  for (let i = 0; i < paragraphs.length; i++) {
+    const para = paragraphs[i];
+    const firstLine = para.split(/[.\n]/)[0].trim().slice(0, 80) || `Section ${i + 1}`;
+    let slug = slugify(firstLine);
+    if (!slug) slug = `section-${i + 1}`;
+
+    if (prefix) slug = `${prefix}/${slug}`;
+    let unique = slug;
+    let n = 2;
+    while (usedSlugs.has(unique)) { unique = `${slug}-${n}`; n++; }
+    usedSlugs.add(unique);
+    slug = unique;
+
+    const links = [];
+    if (prevSlug) {
+      links.push({ target: prevSlug, relation: "related" });
+      edgeCount++;
+    }
+
+    cards.push({
+      slug,
+      title: firstLine,
+      body: para.slice(0, 1000),
+      cardType: inferCardType(firstLine, para),
+      keywords: extractKeywords(firstLine, para),
+      links,
+    });
+    prevSlug = slug;
+  }
+
+  return { cards, edgeCount, format: "text" };
+}
+
+// ─── Main Entry ───────────────────────────────────────
+
+/**
+ * Parse any text into HyperStack cards + edges.
+ * Auto-detects: markdown, conversation log, or plain text.
+ *
+ * @param {string} content — raw input
+ * @param {object} [opts]
+ * @param {string} [opts.prefix] — slug prefix (e.g. "readme", "docs/api")
+ * @param {string} [opts.defaultType] — override cardType for "general" cards
+ * @returns {{ cards: Array, edgeCount: number, format: string }}
+ */
+function parse(content, opts = {}) {
+  if (!content || typeof content !== "string") {
+    return { cards: [], edgeCount: 0, format: "empty" };
+  }
+
+  const prefix = opts.prefix ? slugify(opts.prefix) : "";
+
+  let result;
+  if (isConversationLog(content)) {
+    result = parseConversation(content, prefix);
+  } else if (/^#{1,6}\s+/m.test(content)) {
+    result = parseMarkdown(content, prefix);
+  } else {
+    result = parsePlainText(content, prefix);
+  }
+
+  if (opts.defaultType) {
+    for (const card of result.cards) {
+      if (card.cardType === "general") card.cardType = opts.defaultType;
+    }
+  }
+
+  return result;
+}
+
+export { parse, parseMarkdown, parseConversation, parsePlainText, slugify, inferCardType };
+export default parse;

package/templates/openclaw-multiagent.json

@@ -1,98 +1,98 @@
-{
-  "name": "openclaw-multiagent",
-  "description": "Pre-configured typed cards and relations for OpenClaw multi-agent coordination. Replaces GOALS.md + DECISIONS.md with structured, queryable graph memory.",
-  "version": "1.0.0",
-
-  "cardTypes": {
-    "task": {
-      "description": "A unit of work assigned to an agent",
-      "fields": ["status", "priority", "assignee", "deadline"],
-      "statuses": ["todo", "in-progress", "blocked", "done", "cancelled"]
-    },
-    "decision": {
-      "description": "A choice made by an agent with rationale",
-      "fields": ["rationale", "alternatives", "decidedBy", "decidedAt"]
-    },
-    "blocker": {
-      "description": "Something preventing progress on a task",
-      "fields": ["severity", "resolvedBy", "resolvedAt"]
-    },
-    "goal": {
-      "description": "A high-level objective (replaces GOALS.md)",
-      "fields": ["deadline", "progress", "owner"]
-    },
-    "agent": {
-      "description": "An agent registration card",
-      "fields": ["role", "model", "capabilities"]
-    },
-    "context": {
-      "description": "Shared context that multiple agents need",
-      "fields": ["scope", "expiresAt"]
-    }
-  },
-
-  "relationTypes": {
-    "owns": "Agent/person owns a task or project",
-    "assigned_to": "Task is assigned to an agent",
-    "blocks": "This card blocks another card",
-    "blocked_by": "This card is blocked by another card",
-    "depends_on": "This card depends on another card",
-    "decided": "Agent/person made this decision",
-    "triggers": "Change to this card triggers effects on target",
-    "subtask_of": "This task is a subtask of a larger task",
-    "related": "General association"
-  },
-
-  "rules": [
-    {
-      "name": "auto-blocked",
-      "description": "If a task has incoming 'blocks' relations, mark it as blocked",
-      "when": "card.cardType === 'task' && card.incomingLinks.some(l => l.relation === 'blocks')",
-      "suggest": "Consider updating task status to 'blocked'"
-    },
-    {
-      "name": "unowned-task",
-      "description": "Tasks without an owner should be flagged",
-      "when": "card.cardType === 'task' && !card.links.some(l => l.relation === 'assigned_to')",
-      "suggest": "This task has no assigned agent"
-    },
-    {
-      "name": "decision-needs-rationale",
-      "description": "Decisions should include rationale",
-      "when": "card.cardType === 'decision' && (!card.body || card.body.length < 20)",
-      "suggest": "Decision lacks rationale — add a body explaining why"
-    }
-  ],
-
-  "starterCards": [
-    {
-      "slug": "project-root",
-      "title": "Project Root",
-      "body": "Root node for the project knowledge graph. All agents, goals, and major decisions link here.",
-      "cardType": "project",
-      "stack": "projects",
-      "keywords": ["project", "root", "main"]
-    }
-  ],
-
-  "agentSetup": {
-    "description": "Recommended agent configuration for multi-agent OpenClaw + HyperStack",
-    "agents": {
-      "coordinator": {
-        "role": "Routes tasks, monitors blockers, ensures no duplicate work",
-        "model": "claude-sonnet-4-20250514",
-        "tools": ["hs_search", "hs_blockers", "hs_graph", "hs_decide"]
-      },
-      "researcher": {
-        "role": "Investigates questions, stores findings as context cards",
-        "model": "claude-sonnet-4-20250514",
-        "tools": ["hs_search", "hs_store", "hs_my_cards"]
-      },
-      "builder": {
-        "role": "Implements code, records technical decisions",
-        "model": "claude-sonnet-4-20250514",
-        "tools": ["hs_search", "hs_store", "hs_decide", "hs_blockers"]
-      }
-    }
-  }
-}
+{
+  "name": "openclaw-multiagent",
+  "description": "Pre-configured typed cards and relations for OpenClaw multi-agent coordination. Replaces GOALS.md + DECISIONS.md with structured, queryable graph memory.",
+  "version": "1.0.0",
+
+  "cardTypes": {
+    "task": {
+      "description": "A unit of work assigned to an agent",
+      "fields": ["status", "priority", "assignee", "deadline"],
+      "statuses": ["todo", "in-progress", "blocked", "done", "cancelled"]
+    },
+    "decision": {
+      "description": "A choice made by an agent with rationale",
+      "fields": ["rationale", "alternatives", "decidedBy", "decidedAt"]
+    },
+    "blocker": {
+      "description": "Something preventing progress on a task",
+      "fields": ["severity", "resolvedBy", "resolvedAt"]
+    },
+    "goal": {
+      "description": "A high-level objective (replaces GOALS.md)",
+      "fields": ["deadline", "progress", "owner"]
+    },
+    "agent": {
+      "description": "An agent registration card",
+      "fields": ["role", "model", "capabilities"]
+    },
+    "context": {
+      "description": "Shared context that multiple agents need",
+      "fields": ["scope", "expiresAt"]
+    }
+  },
+
+  "relationTypes": {
+    "owns": "Agent/person owns a task or project",
+    "assigned_to": "Task is assigned to an agent",
+    "blocks": "This card blocks another card",
+    "blocked_by": "This card is blocked by another card",
+    "depends_on": "This card depends on another card",
+    "decided": "Agent/person made this decision",
+    "triggers": "Change to this card triggers effects on target",
+    "subtask_of": "This task is a subtask of a larger task",
+    "related": "General association"
+  },
+
+  "rules": [
+    {
+      "name": "auto-blocked",
+      "description": "If a task has incoming 'blocks' relations, mark it as blocked",
+      "when": "card.cardType === 'task' && card.incomingLinks.some(l => l.relation === 'blocks')",
+      "suggest": "Consider updating task status to 'blocked'"
+    },
+    {
+      "name": "unowned-task",
+      "description": "Tasks without an owner should be flagged",
+      "when": "card.cardType === 'task' && !card.links.some(l => l.relation === 'assigned_to')",
+      "suggest": "This task has no assigned agent"
+    },
+    {
+      "name": "decision-needs-rationale",
+      "description": "Decisions should include rationale",
+      "when": "card.cardType === 'decision' && (!card.body || card.body.length < 20)",
+      "suggest": "Decision lacks rationale — add a body explaining why"
+    }
+  ],
+
+  "starterCards": [
+    {
+      "slug": "project-root",
+      "title": "Project Root",
+      "body": "Root node for the project knowledge graph. All agents, goals, and major decisions link here.",
+      "cardType": "project",
+      "stack": "projects",
+      "keywords": ["project", "root", "main"]
+    }
+  ],
+
+  "agentSetup": {
+    "description": "Recommended agent configuration for multi-agent OpenClaw + HyperStack",
+    "agents": {
+      "coordinator": {
+        "role": "Routes tasks, monitors blockers, ensures no duplicate work",
+        "model": "claude-sonnet-4-20250514",
+        "tools": ["hs_search", "hs_blockers", "hs_graph", "hs_decide"]
+      },
+      "researcher": {
+        "role": "Investigates questions, stores findings as context cards",
+        "model": "claude-sonnet-4-20250514",
+        "tools": ["hs_search", "hs_store", "hs_my_cards"]
+      },
+      "builder": {
+        "role": "Implements code, records technical decisions",
+        "model": "claude-sonnet-4-20250514",
+        "tools": ["hs_search", "hs_store", "hs_decide", "hs_blockers"]
+      }
+    }
+  }
+}