stagent 0.3.5 → 0.4.0

package/src/lib/book/content.ts

@@ -0,0 +1,251 @@
+import type { Book, BookChapter, BookPart } from "./types";
+
+/** Mapping from chapter ID to markdown filename slug (without ch-N- prefix) */
+const CHAPTER_SLUG_MAP: Record<string, string> = {
+  "ch-1": "ch-1-project-management",
+  "ch-2": "ch-2-task-execution",
+  "ch-3": "ch-3-document-processing",
+  "ch-4": "ch-4-workflow-orchestration",
+  "ch-5": "ch-5-scheduled-intelligence",
+  "ch-6": "ch-6-agent-self-improvement",
+  "ch-7": "ch-7-multi-agent-swarms",
+  "ch-8": "ch-8-human-in-the-loop",
+  "ch-9": "ch-9-the-autonomous-organization",
+};
+
+/** The three parts of the AI Native book */
+export const PARTS: BookPart[] = [
+  {
+    number: 1,
+    title: "Foundation",
+    description: "Operations — from manual processes to AI-assisted automation",
+  },
+  {
+    number: 2,
+    title: "Intelligence",
+    description: "Workflows & Learning — adaptive systems that improve over time",
+  },
+  {
+    number: 3,
+    title: "Autonomy",
+    description: "Advanced Patterns — fully delegated business processes",
+  },
+];
+
+/**
+ * Chapter metadata stubs — content is loaded from docs/book/*.md at runtime.
+ * These stubs provide the chapter list for navigation and iteration.
+ * Sections are populated by tryLoadMarkdownChapter().
+ */
+export const CHAPTERS: BookChapter[] = [
+  {
+    id: "ch-1",
+    number: 1,
+    title: "Project Management",
+    subtitle: "From Manual Planning to Autonomous Sprint Planning",
+    part: PARTS[0],
+    readingTime: 12,
+    relatedDocs: ["projects", "home-workspace", "dashboard-kanban"],
+    relatedJourney: "personal-use",
+    sections: [],
+  },
+  {
+    id: "ch-2",
+    number: 2,
+    title: "Task Execution",
+    subtitle: "Single-Agent to Multi-Agent Task Orchestration",
+    part: PARTS[0],
+    readingTime: 15,
+    relatedDocs: ["agent-intelligence", "profiles", "monitoring"],
+    relatedJourney: "work-use",
+    sections: [],
+  },
+  {
+    id: "ch-3",
+    number: 3,
+    title: "Document Processing",
+    subtitle: "Unstructured Input to Structured Knowledge",
+    part: PARTS[0],
+    readingTime: 14,
+    relatedDocs: ["documents", "shared-components"],
+    sections: [],
+  },
+  {
+    id: "ch-4",
+    number: 4,
+    title: "Workflow Orchestration",
+    subtitle: "From Linear Sequences to Adaptive Blueprints",
+    part: PARTS[1],
+    readingTime: 14,
+    relatedDocs: ["workflows", "agent-intelligence"],
+    relatedJourney: "power-user",
+    sections: [],
+  },
+  {
+    id: "ch-5",
+    number: 5,
+    title: "Scheduled Intelligence",
+    subtitle: "Time-Based Automation and Recurring Intelligence Loops",
+    part: PARTS[1],
+    readingTime: 11,
+    relatedDocs: ["schedules", "monitoring"],
+    sections: [],
+  },
+  {
+    id: "ch-6",
+    number: 6,
+    title: "Agent Self-Improvement",
+    subtitle: "Learning from Execution Logs and Feedback",
+    part: PARTS[1],
+    readingTime: 13,
+    relatedDocs: ["agent-intelligence", "profiles"],
+    relatedJourney: "developer",
+    sections: [],
+  },
+  {
+    id: "ch-7",
+    number: 7,
+    title: "Multi-Agent Swarms",
+    subtitle: "Parallel Execution, Consensus, and Specialization",
+    part: PARTS[2],
+    readingTime: 16,
+    relatedDocs: ["profiles", "agent-intelligence"],
+    sections: [],
+  },
+  {
+    id: "ch-8",
+    number: 8,
+    title: "Human-in-the-Loop",
+    subtitle: "Permission Systems and Graceful Escalation",
+    part: PARTS[2],
+    readingTime: 12,
+    relatedDocs: ["inbox-notifications", "tool-permissions", "settings"],
+    sections: [],
+  },
+  {
+    id: "ch-9",
+    number: 9,
+    title: "The Autonomous Organization",
+    subtitle: "Fully Delegated Business Processes",
+    part: PARTS[2],
+    readingTime: 18,
+    relatedDocs: ["workflows", "profiles", "schedules"],
+    sections: [],
+  },
+];
+
+/**
+ * Try to load a chapter from its markdown file in book/chapters/.
+ * Only works server-side (where fs is available). Returns null on client.
+ */
+function tryLoadMarkdownChapter(id: string): BookChapter | null {
+  // Only attempt markdown loading on the server
+  if (typeof window !== "undefined") return null;
+
+  try {
+    const fileSlug = CHAPTER_SLUG_MAP[id];
+    if (!fileSlug) return null;
+
+    // Dynamic require to avoid bundling fs in client builds
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { readFileSync, existsSync } = require("fs") as typeof import("fs");
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { join } = require("path") as typeof import("path");
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { parseMarkdownChapter } = require("./markdown-parser") as { parseMarkdownChapter: (md: string, slug: string) => { sections: Array<{ id: string; title: string; content: import("./types").ContentBlock[] }> } };
+
+    const filePath = join(process.cwd(), "book", "chapters", `${fileSlug}.md`);
+    if (!existsSync(filePath)) return null;
+
+    const content = readFileSync(filePath, "utf-8");
+
+    // Parse frontmatter
+    const fmRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
+    const fmMatch = content.match(fmRegex);
+    const fmBlock = fmMatch ? fmMatch[1] : "";
+    const body = fmMatch ? fmMatch[2] : content;
+
+    const fm: Record<string, unknown> = {};
+    for (const line of fmBlock.split("\n")) {
+      const colonIdx = line.indexOf(":");
+      if (colonIdx === -1) continue;
+      const key = line.slice(0, colonIdx).trim();
+      let value: unknown = line.slice(colonIdx + 1).trim();
+      if (typeof value === "string" && value.startsWith('"') && value.endsWith('"')) {
+        value = value.slice(1, -1);
+      }
+      if (typeof value === "string" && value.startsWith("[") && value.endsWith("]")) {
+        try { value = JSON.parse(value); } catch {
+          value = (value as string).slice(1, -1).split(",").map((s: string) => s.trim()).filter(Boolean);
+        }
+      }
+      fm[key] = value;
+    }
+    const chapterNum = Number(fm.chapter) || 0;
+    const partNum = Number(fm.part) || 1;
+    const part = PARTS[partNum - 1] || PARTS[0];
+
+    const { sections } = parseMarkdownChapter(body, id);
+
+    const relatedDocs = Array.isArray(fm.relatedDocs)
+      ? (fm.relatedDocs as string[])
+      : typeof fm.relatedDocs === "string"
+        ? [fm.relatedDocs]
+        : [];
+
+    const chapter: BookChapter = {
+      id,
+      number: chapterNum,
+      title: (fm.title as string) || "",
+      subtitle: (fm.subtitle as string) || "",
+      part,
+      sections,
+      readingTime: Number(fm.readingTime) || 0,
+    };
+
+    if (relatedDocs.length > 0) chapter.relatedDocs = relatedDocs;
+    if (fm.relatedJourney && fm.relatedJourney !== "null") {
+      chapter.relatedJourney = fm.relatedJourney as string;
+    }
+
+    return chapter;
+  } catch {
+    return null;
+  }
+}
+
+/** Get the full book object */
+export function getBook(): Book {
+  const chapters = CHAPTERS.map((ch) => {
+    const md = tryLoadMarkdownChapter(ch.id);
+    return md || ch;
+  });
+
+  return {
+    title: "AI Native",
+    subtitle: "Building Autonomous Business Systems with AI Agents",
+    description:
+      "A practical guide to building AI-native applications, from single-agent task execution to fully autonomous business processes. Every pattern is demonstrated with working code from Stagent — a tool that built itself.",
+    parts: PARTS,
+    chapters,
+    totalReadingTime: chapters.reduce((sum, ch) => sum + ch.readingTime, 0),
+  };
+}
+
+/** Get a chapter by its ID */
+export function getChapter(id: string): BookChapter | undefined {
+  const mdChapter = tryLoadMarkdownChapter(id);
+  if (mdChapter) return mdChapter;
+  return CHAPTERS.find((ch) => ch.id === id);
+}
+
+/** Get chapters grouped by part */
+export function getChaptersByPart(): Map<number, BookChapter[]> {
+  const grouped = new Map<number, BookChapter[]>();
+  for (const ch of CHAPTERS) {
+    const part = ch.part.number;
+    if (!grouped.has(part)) grouped.set(part, []);
+    grouped.get(part)!.push(ch);
+  }
+  return grouped;
+}

package/src/lib/book/markdown-parser.ts

@@ -0,0 +1,317 @@
+import type {
+  ContentBlock,
+  TextBlock,
+  CodeBlock,
+  CalloutBlock,
+  ImageBlock,
+  InteractiveLinkBlock,
+  InteractiveCollapsibleBlock,
+} from "./types";
+
+interface ParsedSection {
+  id: string;
+  title: string;
+  content: ContentBlock[];
+}
+
+/**
+ * Parse a markdown chapter body (frontmatter already stripped) into structured sections.
+ * Uses a line-by-line state machine to identify content blocks.
+ */
+export function parseMarkdownChapter(
+  markdown: string,
+  chapterSlug: string
+): { sections: ParsedSection[] } {
+  const lines = markdown.split("\n");
+  const sections: ParsedSection[] = [];
+
+  // Split by ## headings
+  const sectionChunks: Array<{ title: string; lines: string[] }> = [];
+  let currentTitle = "Introduction";
+  let currentLines: string[] = [];
+
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      if (currentLines.length > 0 || sectionChunks.length > 0) {
+        sectionChunks.push({ title: currentTitle, lines: currentLines });
+      }
+      currentTitle = line.slice(3).trim();
+      currentLines = [];
+    } else {
+      currentLines.push(line);
+    }
+  }
+  // Push the last section
+  if (currentLines.length > 0 || sectionChunks.length > 0) {
+    sectionChunks.push({ title: currentTitle, lines: currentLines });
+  }
+
+  // If no ## headings were found, treat entire content as one section
+  if (sectionChunks.length === 0 && currentLines.length > 0) {
+    sectionChunks.push({ title: "Introduction", lines: currentLines });
+  }
+
+  for (const chunk of sectionChunks) {
+    const sectionId = generateSectionId(chapterSlug, chunk.title);
+    const content = parseContentBlocks(chunk.lines);
+    sections.push({ id: sectionId, title: chunk.title, content });
+  }
+
+  return { sections };
+}
+
+/** Convert heading text to a section ID */
+function generateSectionId(chapterSlug: string, title: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return `${chapterSlug}-${slug}`;
+}
+
+/** Parse lines within a section into ContentBlock[] */
+function parseContentBlocks(lines: string[]): ContentBlock[] {
+  const blocks: ContentBlock[] = [];
+  let textBuffer: string[] = [];
+  let i = 0;
+
+  function flushText() {
+    if (textBuffer.length === 0) return;
+    const text = textBuffer.join("\n").trim();
+    if (text) {
+      blocks.push({ type: "text", markdown: text } as TextBlock);
+    }
+    textBuffer = [];
+  }
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // --- Fenced code block ---
+    if (line.trimStart().startsWith("```")) {
+      flushText();
+      const indent = line.length - line.trimStart().length;
+      const lang = line.trimStart().slice(3).trim();
+      let filename: string | undefined;
+
+      // Check if previous line was a filename comment
+      if (
+        blocks.length > 0 ||
+        textBuffer.length > 0
+      ) {
+        // Check the last text buffer line or look back
+        const prevLine = i > 0 ? lines[i - 1] : "";
+        const filenameMatch = prevLine.match(
+          /^<!--\s*filename:\s*(.+?)\s*-->$/
+        );
+        if (filenameMatch) {
+          filename = filenameMatch[1];
+          // Remove the filename comment from the last text block if it got flushed
+          if (blocks.length > 0 && blocks[blocks.length - 1].type === "text") {
+            const lastBlock = blocks[blocks.length - 1] as TextBlock;
+            const mdLines = lastBlock.markdown.split("\n");
+            if (
+              mdLines.length > 0 &&
+              mdLines[mdLines.length - 1].match(/^<!--\s*filename:\s*.+\s*-->$/)
+            ) {
+              mdLines.pop();
+              const trimmed = mdLines.join("\n").trim();
+              if (trimmed) {
+                lastBlock.markdown = trimmed;
+              } else {
+                blocks.pop();
+              }
+            }
+          }
+        }
+      } else {
+        // Check previous line directly
+        const prevLine = i > 0 ? lines[i - 1] : "";
+        const filenameMatch = prevLine.match(
+          /^<!--\s*filename:\s*(.+?)\s*-->$/
+        );
+        if (filenameMatch) {
+          filename = filenameMatch[1];
+        }
+      }
+
+      const codeLines: string[] = [];
+      i++;
+      while (i < lines.length) {
+        const codeLine = lines[i];
+        // Match closing fence at same or less indentation
+        if (
+          codeLine.trimStart().startsWith("```") &&
+          codeLine.trimStart() === "```" &&
+          (codeLine.length - codeLine.trimStart().length) <= indent
+        ) {
+          i++;
+          break;
+        }
+        codeLines.push(codeLine);
+        i++;
+      }
+
+      const block: CodeBlock = {
+        type: "code",
+        language: lang || "text",
+        code: codeLines.join("\n"),
+      };
+      if (filename) block.filename = filename;
+      blocks.push(block);
+      continue;
+    }
+
+    // --- Callout blockquote: > [!variant] ---
+    const calloutMatch = line.match(
+      /^>\s*\[!(tip|warning|info|lesson|authors-note)\]\s*$/
+    );
+    if (calloutMatch) {
+      flushText();
+      const variant = calloutMatch[1] as CalloutBlock["variant"];
+      const calloutLines: string[] = [];
+      let title: string | undefined;
+      let imageSrc: string | undefined;
+      let imageAlt: string | undefined;
+      let defaultCollapsed = false;
+
+      i++;
+      // Check for optional title on first line: > **Title**
+      if (i < lines.length) {
+        const titleMatch = lines[i].match(/^>\s*\*\*(.+?)\*\*\s*$/);
+        if (titleMatch) {
+          title = titleMatch[1];
+          i++;
+        }
+      }
+
+      // Collect blockquote content
+      while (i < lines.length) {
+        const bqLine = lines[i];
+        if (bqLine.startsWith("> ") || bqLine === ">") {
+          let content = bqLine === ">" ? "" : bqLine.slice(2);
+
+          // Check for image in callout
+          const imgMatch = content.match(/^!\[([^\]]*)\]\(([^)]+)\)$/);
+          if (imgMatch) {
+            imageAlt = imgMatch[1];
+            imageSrc = imgMatch[2];
+            i++;
+            continue;
+          }
+
+          // Check for collapsed marker
+          if (content.trim() === "[collapsed]") {
+            defaultCollapsed = true;
+            i++;
+            continue;
+          }
+
+          calloutLines.push(content);
+          i++;
+        } else if (bqLine.trim() === "") {
+          // Blank line ends the blockquote
+          i++;
+          break;
+        } else {
+          break;
+        }
+      }
+
+      if (variant === "authors-note") {
+        defaultCollapsed = true;
+      }
+
+      const block: CalloutBlock = {
+        type: "callout",
+        variant,
+        markdown: calloutLines.join("\n").trim(),
+      };
+      if (title) block.title = title;
+      if (imageSrc) block.imageSrc = imageSrc;
+      if (imageAlt) block.imageAlt = imageAlt;
+      if (defaultCollapsed) block.defaultCollapsed = true;
+      blocks.push(block);
+      continue;
+    }
+
+    // --- Image on its own line: ![alt](src "caption") ---
+    const imageMatch = line.match(
+      /^!\[([^\]]*)\]\((\S+?)(?:\s+"([^"]*)")?\)\s*$/
+    );
+    if (imageMatch) {
+      flushText();
+      const block: ImageBlock = {
+        type: "image",
+        src: imageMatch[2],
+        alt: imageMatch[1],
+      };
+      if (imageMatch[3]) block.caption = imageMatch[3];
+      blocks.push(block);
+      i++;
+      continue;
+    }
+
+    // --- Interactive link: [Try: label](href) ---
+    const tryMatch = line.match(/^\[Try:\s*(.+?)\]\((.+?)\)\s*$/);
+    if (tryMatch) {
+      flushText();
+      blocks.push({
+        type: "interactive",
+        interactiveType: "link",
+        label: `Try: ${tryMatch[1]}`,
+        description: "",
+        href: tryMatch[2],
+      } as InteractiveLinkBlock);
+      i++;
+      continue;
+    }
+
+    // --- Details/collapsible: <details><summary>label</summary> ---
+    const detailsMatch = line.match(
+      /^<details>\s*<summary>(.+?)<\/summary>\s*$/
+    );
+    if (detailsMatch) {
+      flushText();
+      const label = detailsMatch[1];
+      const contentLines: string[] = [];
+      i++;
+      while (i < lines.length) {
+        if (lines[i].trim() === "</details>") {
+          i++;
+          break;
+        }
+        contentLines.push(lines[i]);
+        i++;
+      }
+
+      blocks.push({
+        type: "interactive",
+        interactiveType: "collapsible",
+        label,
+        markdown: contentLines.join("\n").trim(),
+      } as InteractiveCollapsibleBlock);
+      continue;
+    }
+
+    // --- Filename comment line (will be consumed by next code block) ---
+    if (line.match(/^<!--\s*filename:\s*.+\s*-->$/)) {
+      // Don't flush yet — peek ahead for a code block
+      if (i + 1 < lines.length && lines[i + 1].trimStart().startsWith("```")) {
+        // Let the code block handler pick it up
+        textBuffer.push(line);
+        i++;
+        continue;
+      }
+    }
+
+    // --- Regular text ---
+    textBuffer.push(line);
+    i++;
+  }
+
+  flushText();
+  return blocks;
+}

package/src/lib/book/reading-paths.ts

@@ -0,0 +1,82 @@
+import type { UsageStage } from "@/lib/docs/types";
+
+export interface ReadingPath {
+  id: string;
+  name: string;
+  description: string;
+  persona: string;
+  chapterIds: string[];
+  usageStage: UsageStage;
+}
+
+export const READING_PATHS: ReadingPath[] = [
+  {
+    id: "getting-started",
+    name: "Getting Started",
+    description: "Essential chapters for new users learning the basics",
+    persona: "new",
+    chapterIds: ["ch-1", "ch-2", "ch-3"],
+    usageStage: "new",
+  },
+  {
+    id: "team-lead",
+    name: "Team Lead",
+    description: "Chapters focused on team management and workflows",
+    persona: "work",
+    chapterIds: ["ch-1", "ch-4", "ch-5"],
+    usageStage: "early",
+  },
+  {
+    id: "power-user",
+    name: "Power User",
+    description: "Advanced chapters for active users ready to go deeper",
+    persona: "active",
+    chapterIds: ["ch-4", "ch-5", "ch-6", "ch-7", "ch-8"],
+    usageStage: "active",
+  },
+  {
+    id: "developer",
+    name: "Developer",
+    description: "Comprehensive path covering the full technical depth",
+    persona: "developer",
+    chapterIds: ["ch-1", "ch-2", "ch-3", "ch-4", "ch-5", "ch-6", "ch-7", "ch-8", "ch-9"],
+    usageStage: "power",
+  },
+];
+
+/** Recommend a reading path based on the user's usage stage */
+export function recommendPath(stage: UsageStage): string {
+  switch (stage) {
+    case "new":
+      return "getting-started";
+    case "early":
+      return "team-lead";
+    case "active":
+      return "power-user";
+    case "power":
+      return "developer";
+    default:
+      return "getting-started";
+  }
+}
+
+/** Get a reading path by ID */
+export function getReadingPath(id: string): ReadingPath | undefined {
+  return READING_PATHS.find((p) => p.id === id);
+}
+
+/** Get the next chapter ID in a path after the current one, or null if at end */
+export function getNextPathChapter(pathId: string, currentChapterId: string): string | null {
+  const path = getReadingPath(pathId);
+  if (!path) return null;
+  const idx = path.chapterIds.indexOf(currentChapterId);
+  if (idx === -1 || idx >= path.chapterIds.length - 1) return null;
+  return path.chapterIds[idx + 1];
+}
+
+/** Check if a chapter is part of a reading path */
+export function isChapterInPath(pathId: string, chapterId: string): boolean {
+  const path = getReadingPath(pathId);
+  if (!path) return false;
+  return path.chapterIds.includes(chapterId);
+}