timeline-truth 0.1.0 → 0.1.1

package/README.md

@@ -1,7 +1,6 @@
 # Timeline Truth
 
-Status: v0.2 adoption release in progress. MIT licensed. Requires Node.js
-22 or newer.
+Status: v0.1.0 public release. MIT licensed. Requires Node.js 22 or newer.
 
 Timeline Truth is a local MCP server for AI-agent TPM workflows: paste PRD/Jira/status notes,
 CSV exports, launch checklists, or rough planning text; get timeline JSON,
@@ -34,6 +33,32 @@ the mermaid_gantt output. Do not infer missing dates or owners.
 The server returns normalized items, gaps such as missing start/end dates, the
 default assumption that dates were not inferred, and portable Mermaid output.
 
+For larger Markdown notes, `create_timeline` can parse only selected headings
+and ignore the rest:
+
+```json
+{
+  "sources": [
+    {
+      "id": "program-note",
+      "type": "markdown",
+      "path": "docs/program.md",
+      "content": "..."
+    }
+  ],
+  "markdown": {
+    "sections": ["Timeline", "Follow-Ups"],
+    "ignoreFrontmatter": true
+  }
+}
+```
+
+Markdown tables under those headings are parsed into items. Fuzzy targets such
+as `W3-W4 May 2026` are preserved as `time_window`/`date_text` and flagged with
+an `exact_date` gap instead of being converted into invented dates. The response
+also includes `noise_report.ignored` counts for skipped frontmatter, prose, and
+table rows without target dates.
+
 ## Why This Exists
 
 Most timeline tools assume the plan is already structured. Real planning inputs
@@ -66,7 +91,7 @@ npm install
 node src/mcp-server.js
 ```
 
-Npm package config, after the npm package is published:
+Npm package config:
 
 ```json
 {
@@ -79,9 +104,19 @@ Npm package config, after the npm package is published:
 }
 ```
 
-Important: the npm package install path works only after `timeline-truth` is
-published to npm. Before the npm package is published, use the local checkout
-config in [docs/MCP-SETUP.md](docs/MCP-SETUP.md).
+Optional global install:
+
+```bash
+npm install -g timeline-truth
+timeline-truth-mcp
+```
+
+If your global npm bin directory is on `PATH`, you can also configure the MCP
+server with `"command": "timeline-truth-mcp"`. The `npx --package` config above
+is the most portable option because it does not depend on global shell setup.
+
+For local development, use the checkout config in
+[docs/MCP-SETUP.md](docs/MCP-SETUP.md).
 
 ## MCP Tools
 
@@ -107,9 +142,9 @@ Each example has a compact expected-output JSON file and is covered by tests.
 
 ## Current limitations
 
-- Text and Markdown parsing is heuristic. It works best when each planning item
-  is on its own line.
-- Markdown headings are ignored and task-list markers are stripped, but rich
+- Text parsing is heuristic. It works best when each planning item is on its own
+  line.
+- Markdown parsing supports heading filters and simple pipe tables, but rich
   nested documents are not fully parsed.
 - CSV and JSON are more reliable than free-form notes when exact fields matter.
 - There are no Jira, Confluence, Slack, or hosted imports in this release.

package/docs/MCP-SETUP.md

@@ -26,7 +26,7 @@ npm install
 
 ## Npm Package
 
-Use this after the `timeline-truth` npm package is published:
+Use the published `timeline-truth` package:
 
 ```json
 {
@@ -39,8 +39,32 @@ Use this after the `timeline-truth` npm package is published:
 }
 ```
 
-Before publish, `npx --package=timeline-truth timeline-truth-mcp` will fail
-because the package is not yet available from the public registry.
+This is the recommended package config because it does not require a global npm
+install or depend on the user's global npm bin directory being on `PATH`.
+
+Optional global install:
+
+```bash
+npm install -g timeline-truth
+timeline-truth-mcp
+```
+
+With the global package installed and available on `PATH`, the MCP config can
+call the package binary directly:
+
+```json
+{
+  "mcpServers": {
+    "timeline-truth": {
+      "command": "timeline-truth-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+If you need to test local changes before publishing a new version, use the local
+checkout config above.
 
 ## Agent Prompt
 

package/docs/RELEASE.md

@@ -2,15 +2,22 @@
 
 Use this checklist before publishing a public version of `timeline-truth`.
 
+## Current Release Notes
+
+- Markdown ingestion now ignores frontmatter by default, parses configured
+  headings, supports simple pipe tables, preserves fuzzy time windows, enriches
+  source refs, and reports ignored content through `noise_report`.
+- This release intentionally does not include CLI file mode, TPM validation
+  profiles, or dependency matching by external IDs.
+
 ## Verify Package Name
 
 ```bash
 npm view timeline-truth version
 ```
 
-Expected before first publish: npm returns `404 Not Found`.
-
-Expected after publish: npm returns the latest published version.
+Expected result: npm returns the latest published version. Before publishing a
+new release, confirm whether the version in `package.json` needs to be bumped.
 
 ## Verify Local Quality
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "timeline-truth",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Open-source MCP server for compiling messy project planning inputs into evidence-preserving timelines.",
   "author": "hilmimuktitama",
   "license": "MIT",
@@ -18,7 +18,7 @@
   },
   "files": [
     "src",
-    "docs",
+    "docs/*.md",
     "examples",
     "README.md",
     "LICENSE"

package/src/mcp-tools.js

@@ -6,6 +6,7 @@ const SOURCE_SCHEMA = {
   additionalProperties: true,
   properties: {
     id: { type: "string", description: "Stable source identifier used in source_refs." },
+    path: { type: "string", description: "Optional file path to preserve in source_refs." },
     type: { type: "string", enum: ["text", "markdown", "csv", "json"], default: "text" },
     content: {
       description: "Pasted text/file content. JSON sources may pass a JSON string or object.",
@@ -42,6 +43,23 @@ export function listTimelineTools() {
             type: "array",
             minItems: 1,
             items: SOURCE_SCHEMA
+          },
+          markdown: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              sections: {
+                type: "array",
+                items: { type: "string" },
+                description:
+                  "Markdown headings to parse. Defaults to Timeline, Milestones, Next, Risks And Blockers, and Follow-Ups."
+              },
+              ignoreFrontmatter: {
+                type: "boolean",
+                default: true,
+                description: "Ignore YAML frontmatter before parsing Markdown content."
+              }
+            }
           }
         }
       }
@@ -108,7 +126,7 @@ export function listTimelineTools() {
 export function callTimelineTool(name, args = {}) {
   switch (name) {
     case "create_timeline":
-      return jsonContent(createTimeline({ sources: args.sources }));
+      return jsonContent(createTimeline({ sources: args.sources, markdown: args.markdown }));
     case "validate_timeline":
       return jsonContent(validateTimeline(args.timeline));
     case "render_timeline":

package/src/timeline.js

@@ -1,9 +1,13 @@
 const DATE_PATTERN = /\b\d{4}-\d{2}-\d{2}\b/g;
+const DEFAULT_MARKDOWN_SECTIONS = ["Timeline", "Milestones", "Next", "Risks And Blockers", "Follow-Ups"];
 
 export function createTimeline(input = {}) {
   const sources = Array.isArray(input.sources) ? input.sources : [];
   const importedAssumptions = [];
-  const items = sources.flatMap((source, index) => parseSource(source, index, importedAssumptions));
+  const noiseReport = createNoiseReport();
+  const items = sources.flatMap((source, index) =>
+    parseSource(source, index, importedAssumptions, input, noiseReport)
+  );
   const timeline = normalizeTimeline({
     items,
     assumptions: [
@@ -28,6 +32,7 @@ export function createTimeline(input = {}) {
     assumptions: validatedTimeline.assumptions,
     gaps: validatedTimeline.gaps,
     issues: validation.issues,
+    noise_report: noiseReport,
     renders: {
       mermaid_gantt: renderTimeline(validatedTimeline, { format: "mermaid_gantt" }),
       mermaid_timeline: renderTimeline(validatedTimeline, { format: "mermaid_timeline" }),
@@ -42,11 +47,15 @@ export function validateTimeline(timeline = {}) {
   const issues = [];
 
   for (const item of normalized.items) {
-    if (!item.start) {
+    if (item.exact_date_needed) {
+      gaps.push(makeGap(item, "exact_date", "Exact date needed before rendering this fuzzy time window."));
+    }
+
+    if (!item.start && !item.time_window) {
       gaps.push(makeGap(item, "start", "Missing start date. Ask for the planned start date instead of inferring it."));
     }
 
-    if (!item.end && !item.duration && item.type !== "milestone") {
+    if (!item.end && !item.duration && !item.time_window && item.type !== "milestone") {
       gaps.push(makeGap(item, "end", "Missing end date or duration for a non-milestone item."));
     }
 
@@ -142,11 +151,12 @@ export function refineTimeline(timeline = {}, refinement = {}) {
   };
 }
 
-function parseSource(source, index, importedAssumptions) {
+function parseSource(source, index, importedAssumptions, input, noiseReport) {
   const normalizedSource = {
     id: source?.id || `source-${index + 1}`,
     type: source?.type || "text",
-    content: source?.content ?? ""
+    content: source?.content ?? "",
+    path: source?.path || source?.file_path || source?.filePath
   };
 
   if (normalizedSource.type === "json") {
@@ -157,6 +167,10 @@ function parseSource(source, index, importedAssumptions) {
     return parseCsvSource(normalizedSource);
   }
 
+  if (normalizedSource.type === "markdown") {
+    return parseMarkdownSource(normalizedSource, input?.markdown, noiseReport);
+  }
+
   return parseTextSource(normalizedSource);
 }
 
@@ -197,6 +211,85 @@ function parseTextSource(source) {
     .filter(Boolean);
 }
 
+function parseMarkdownSource(source, markdownOptions = {}, noiseReport = createNoiseReport()) {
+  const lines = String(source.content).split(/\r?\n/);
+  const allowedHeadings = getAllowedMarkdownHeadings(markdownOptions);
+  const hasAllowedHeadings = markdownHasAllowedHeadings(lines, allowedHeadings);
+  const items = [];
+  let currentHeading;
+  let inFrontmatter = markdownOptions?.ignoreFrontmatter === false ? false : lines[0]?.trim() === "---";
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const trimmed = line.trim();
+
+    if (inFrontmatter) {
+      noiseReport.ignored.frontmatter_lines += 1;
+      if (index > 0 && trimmed === "---") inFrontmatter = false;
+      continue;
+    }
+
+    const heading = parseMarkdownHeading(trimmed);
+    if (heading) {
+      currentHeading = heading;
+      continue;
+    }
+
+    if (!trimmed) continue;
+
+    const inAllowedSection = !hasAllowedHeadings || allowedHeadings.has(normalizeHeading(currentHeading));
+    if (!inAllowedSection) {
+      noiseReport.ignored.prose_lines += 1;
+      continue;
+    }
+
+    if (isMarkdownTableLine(trimmed)) {
+      const table = parseMarkdownTable(lines, index);
+      if (!table) {
+        noiseReport.ignored.prose_lines += 1;
+        continue;
+      }
+
+      for (const row of table.rows) {
+        const item = markdownRecordToItem(row.record, currentHeading);
+        if (!item) {
+          noiseReport.ignored.table_rows_without_dates += row.hasDate ? 0 : 1;
+          continue;
+        }
+
+        if (!row.hasDate) noiseReport.ignored.table_rows_without_dates += 1;
+        items.push(
+          normalizeItem(item, [
+            compactObject({
+              sourceId: source.id,
+              path: source.path,
+              heading: currentHeading,
+              tableRow: row.tableRow,
+              line: row.line,
+              text: row.text
+            })
+          ])
+        );
+      }
+
+      index = table.endIndex;
+      continue;
+    }
+
+    const parsedLine = parseTextLine(line, source.id, index + 1);
+    if (parsedLine) {
+      parsedLine.source_refs = parsedLine.source_refs.map((sourceRef) =>
+        compactObject({ ...sourceRef, path: source.path, heading: currentHeading })
+      );
+      items.push(parsedLine);
+    } else {
+      noiseReport.ignored.prose_lines += 1;
+    }
+  }
+
+  return items;
+}
+
 function parseTextLine(line, sourceId, lineNumber) {
   const trimmed = normalizePlanningLine(line);
   if (!trimmed) return null;
@@ -292,6 +385,31 @@ function csvRecordToItem(record) {
   };
 }
 
+function markdownRecordToItem(record, heading) {
+  const title =
+    valueFromRecord(record, ["item", "follow_up", "follow-up", "followup", "task", "milestone", "risk", "blocker"]) ||
+    valueFromRecord(record, ["title", "name"]);
+  if (!title) return null;
+
+  const target = valueFromRecord(record, ["target", "date", "when", "time_window", "window"]);
+  const dates = extractExactDates(target);
+  const fuzzyTarget = target && dates.length === 0 ? target : undefined;
+
+  return {
+    title,
+    type: normalizeHeading(heading) === "milestones" || record.type === "milestone" ? "milestone" : "task",
+    start: dates[0],
+    end: dates[1],
+    owner: valueFromRecord(record, ["owner", "assignee"]),
+    status: valueFromRecord(record, ["status"]) || "planned",
+    dependencies: valueFromRecord(record, ["dependencies", "depends_on", "depends on"]),
+    time_window: fuzzyTarget,
+    date_text: fuzzyTarget,
+    exact_date_needed: Boolean(fuzzyTarget),
+    confidence: target ? 0.7 : 0.55
+  };
+}
+
 function normalizeTimeline(timeline = {}) {
   const items = Array.isArray(timeline.items)
     ? timeline.items.map((item) => normalizeItem(item, item.source_refs))
@@ -321,6 +439,9 @@ function normalizeItem(item = {}, sourceRefs = []) {
     start: blankToUndefined(item.start),
     end: blankToUndefined(item.end),
     duration: blankToUndefined(item.duration),
+    time_window: blankToUndefined(item.time_window),
+    date_text: blankToUndefined(item.date_text),
+    exact_date_needed: Boolean(item.exact_date_needed),
     owner: blankToUndefined(item.owner),
     status: blankToUndefined(item.status) || "unknown",
     dependencies: dependencies.map((dependency) => String(dependency).trim()).filter(Boolean),
@@ -503,6 +624,115 @@ function blankToUndefined(value) {
   return normalized === "" ? undefined : normalized;
 }
 
+function createNoiseReport() {
+  return {
+    ignored: {
+      frontmatter_lines: 0,
+      prose_lines: 0,
+      table_rows_without_dates: 0
+    }
+  };
+}
+
+function getAllowedMarkdownHeadings(options = {}) {
+  const sections = Array.isArray(options?.sections) && options.sections.length > 0
+    ? options.sections
+    : DEFAULT_MARKDOWN_SECTIONS;
+  return new Set(sections.map((section) => normalizeHeading(section)));
+}
+
+function markdownHasAllowedHeadings(lines, allowedHeadings) {
+  return lines.some((line) => {
+    const heading = parseMarkdownHeading(line.trim());
+    return heading && allowedHeadings.has(normalizeHeading(heading));
+  });
+}
+
+function parseMarkdownHeading(line) {
+  const match = line.match(/^#{1,6}\s+(.+?)\s*#*$/);
+  return match ? match[1].trim() : undefined;
+}
+
+function normalizeHeading(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/&/g, "and")
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+function isMarkdownTableLine(line) {
+  return /^\|.*\|\s*$/.test(line);
+}
+
+function parseMarkdownTable(lines, startIndex) {
+  const header = parseMarkdownTableCells(lines[startIndex]);
+  const separator = parseMarkdownTableCells(lines[startIndex + 1]);
+  if (header.length === 0 || !isMarkdownSeparatorRow(separator)) return null;
+
+  const headers = header.map((cell) => normalizeHeader(cell));
+  const rows = [];
+  let index = startIndex + 2;
+  let tableRow = 1;
+
+  while (index < lines.length && isMarkdownTableLine(lines[index].trim())) {
+    const cells = parseMarkdownTableCells(lines[index]);
+    const record = {};
+    headers.forEach((column, columnIndex) => {
+      record[column] = cells[columnIndex] ?? "";
+    });
+
+    const target = valueFromRecord(record, ["target", "date", "when", "time_window", "window"]);
+    rows.push({
+      record,
+      tableRow,
+      line: index + 1,
+      text: lines[index].trim(),
+      hasDate: extractExactDates(target).length > 0 || Boolean(blankToUndefined(target))
+    });
+    tableRow += 1;
+    index += 1;
+  }
+
+  return {
+    rows,
+    endIndex: index - 1
+  };
+}
+
+function parseMarkdownTableCells(line = "") {
+  const trimmed = String(line).trim();
+  if (!isMarkdownTableLine(trimmed)) return [];
+  return trimmed
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((cell) => cell.trim());
+}
+
+function isMarkdownSeparatorRow(cells) {
+  return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell.trim()));
+}
+
+function valueFromRecord(record, names) {
+  for (const name of names) {
+    const normalized = normalizeHeader(name);
+    const value = blankToUndefined(record[normalized]);
+    if (value) return value;
+  }
+
+  return undefined;
+}
+
+function extractExactDates(value) {
+  return [...String(value || "").matchAll(DATE_PATTERN)].map((match) => match[0]);
+}
+
+function compactObject(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+
 function escapeMermaidText(value) {
   return String(value).replace(/[:#;]/g, "-").trim();
 }