@qotaq/lalphgram 0.1.0

package/src/lib/TelegraphMarkdown.ts

@@ -0,0 +1,305 @@
+/**
+ * Converts markdown directly to Telegraph Node array.
+ * Two-phase parser: block-level state machine + recursive inline scanner.
+ * Skips the lossy HTML intermediate step for better fidelity.
+ * @since 1.0.0
+ */
+import type { Node } from "better-telegraph"
+import { deflateSync } from "node:zlib"
+import { mermaidToPlantUml } from "./MermaidToPlantUml.js"
+import type { SpecFile } from "./SpecHtmlGenerator.js"
+
+// ---------------------------------------------------------------------------
+// Block types
+// ---------------------------------------------------------------------------
+
+type Block =
+  | { readonly _tag: "codeBlock"; readonly lang: string | undefined; readonly code: string }
+  | { readonly _tag: "heading"; readonly level: number; readonly text: string }
+  | { readonly _tag: "hr" }
+  | { readonly _tag: "unorderedList"; readonly items: ReadonlyArray<string> }
+  | { readonly _tag: "orderedList"; readonly items: ReadonlyArray<string> }
+  | { readonly _tag: "blockquote"; readonly text: string }
+  | { readonly _tag: "paragraph"; readonly text: string }
+
+// ---------------------------------------------------------------------------
+// Block-level parser
+// ---------------------------------------------------------------------------
+
+const isBlockStart = (line: string): boolean =>
+  /^#{1,6}\s/.test(line) ||
+  /^[-*]\s+/.test(line) ||
+  /^\d+\.\s+/.test(line) ||
+  /^>/.test(line) ||
+  /^```/.test(line) ||
+  /^(?:---+|\*\*\*+|___+)\s*$/.test(line)
+
+const parseBlocks = (markdown: string): ReadonlyArray<Block> => {
+  const lines = markdown.split("\n")
+  const blocks: Array<Block> = []
+  let i = 0
+
+  while (i < lines.length) {
+    const line = lines[i] ?? ""
+
+    // Code fence
+    const fenceMatch = /^```(\w*)/.exec(line)
+    if (fenceMatch) {
+      const lang = fenceMatch[1] || undefined
+      const codeLines: Array<string> = []
+      i++
+      while (i < lines.length) {
+        const codeLine = lines[i] ?? ""
+        if (/^```\s*$/.test(codeLine)) break
+        codeLines.push(codeLine)
+        i++
+      }
+      blocks.push({ _tag: "codeBlock", lang, code: codeLines.join("\n") })
+      if (i < lines.length) i++ // skip closing ```
+      continue
+    }
+
+    // Heading
+    const headingMatch = /^(#{1,6})\s+(.+)$/.exec(line)
+    if (headingMatch) {
+      const hashes = headingMatch[1] ?? "#"
+      const text = headingMatch[2] ?? ""
+      blocks.push({ _tag: "heading", level: hashes.length, text })
+      i++
+      continue
+    }
+
+    // HR (must come before list check since *** could look like a list start)
+    if (/^(?:---+|\*\*\*+|___+)\s*$/.test(line)) {
+      blocks.push({ _tag: "hr" })
+      i++
+      continue
+    }
+
+    // Unordered list
+    const ulMatch = /^[-*]\s+(.+)$/.exec(line)
+    if (ulMatch) {
+      const items: Array<string> = [ulMatch[1] ?? ""]
+      i++
+      while (i < lines.length) {
+        const nextLine = lines[i] ?? ""
+        const nextMatch = /^[-*]\s+(.+)$/.exec(nextLine)
+        if (!nextMatch) break
+        items.push(nextMatch[1] ?? "")
+        i++
+      }
+      blocks.push({ _tag: "unorderedList", items })
+      continue
+    }
+
+    // Ordered list
+    const olMatch = /^\d+\.\s+(.+)$/.exec(line)
+    if (olMatch) {
+      const items: Array<string> = [olMatch[1] ?? ""]
+      i++
+      while (i < lines.length) {
+        const nextLine = lines[i] ?? ""
+        const nextMatch = /^\d+\.\s+(.+)$/.exec(nextLine)
+        if (!nextMatch) break
+        items.push(nextMatch[1] ?? "")
+        i++
+      }
+      blocks.push({ _tag: "orderedList", items })
+      continue
+    }
+
+    // Blockquote
+    const bqMatch = /^>\s?(.*)$/.exec(line)
+    if (bqMatch) {
+      const bqLines: Array<string> = [bqMatch[1] ?? ""]
+      i++
+      while (i < lines.length) {
+        const nextLine = lines[i] ?? ""
+        const nextBq = /^>\s?(.*)$/.exec(nextLine)
+        if (!nextBq) break
+        bqLines.push(nextBq[1] ?? "")
+        i++
+      }
+      blocks.push({ _tag: "blockquote", text: bqLines.join(" ") })
+      continue
+    }
+
+    // Blank line — skip
+    if (line.trim() === "") {
+      i++
+      continue
+    }
+
+    // Paragraph — accumulate non-blank, non-block-start lines
+    const paraLines: Array<string> = [line]
+    i++
+    while (i < lines.length) {
+      const nextLine = lines[i] ?? ""
+      if (nextLine.trim() === "" || isBlockStart(nextLine)) break
+      paraLines.push(nextLine)
+      i++
+    }
+    blocks.push({ _tag: "paragraph", text: paraLines.join(" ") })
+  }
+
+  return blocks
+}
+
+// ---------------------------------------------------------------------------
+// Inline parser — "find earliest match" recursive scanner
+// ---------------------------------------------------------------------------
+
+const inlinePatterns = [
+  { type: "code", regex: /`([^`]+)`/ },
+  { type: "link", regex: /\[([^\]]+)\]\(([^)]+)\)/ },
+  { type: "bold_star", regex: /\*\*(.+?)\*\*/ },
+  { type: "bold_under", regex: /__(.+?)__/ },
+  { type: "strike", regex: /~~(.+?)~~/ },
+  { type: "italic_star", regex: /(?<![*])\*(?!\*)(.+?)(?<![*])\*(?!\*)/ },
+  { type: "italic_under", regex: /(?<!\w)_(.+?)_(?!\w)/ }
+] as const
+
+const parseInline = (text: string): Array<Node> => {
+  if (text === "") return []
+
+  const nodes: Array<Node> = []
+  let remaining = text
+
+  while (remaining.length > 0) {
+    let earliestIndex = remaining.length
+    let earliestType: string | undefined
+    let earliestMatch: RegExpExecArray | undefined
+
+    for (const { regex, type } of inlinePatterns) {
+      const match = regex.exec(remaining)
+      if (match && match.index < earliestIndex) {
+        earliestIndex = match.index
+        earliestType = type
+        earliestMatch = match
+      }
+    }
+
+    if (!earliestMatch || !earliestType) {
+      nodes.push(remaining)
+      break
+    }
+
+    // Text before the match
+    if (earliestIndex > 0) {
+      nodes.push(remaining.slice(0, earliestIndex))
+    }
+
+    const group1 = earliestMatch[1] ?? ""
+    const group2 = earliestMatch[2] ?? ""
+
+    switch (earliestType) {
+      case "code":
+        nodes.push({ tag: "code", children: [group1] })
+        break
+      case "link":
+        nodes.push({ tag: "a", attrs: { href: group2 }, children: parseInline(group1) })
+        break
+      case "bold_star":
+      case "bold_under":
+        nodes.push({ tag: "strong", children: parseInline(group1) })
+        break
+      case "italic_star":
+      case "italic_under":
+        nodes.push({ tag: "em", children: parseInline(group1) })
+        break
+      case "strike":
+        nodes.push({ tag: "s", children: parseInline(group1) })
+        break
+    }
+
+    remaining = remaining.slice(earliestIndex + earliestMatch[0].length)
+  }
+
+  return nodes
+}
+
+// ---------------------------------------------------------------------------
+// Block → Node conversion
+// ---------------------------------------------------------------------------
+
+const codeToChildren = (code: string): Array<Node> => {
+  const lines = code.split("\n")
+  const children: Array<Node> = []
+  for (let i = 0; i < lines.length; i++) {
+    if (i > 0) children.push({ tag: "br" })
+    children.push(lines[i] ?? "")
+  }
+  return children
+}
+
+const blockToNodes = (block: Block): Array<Node> => {
+  switch (block._tag) {
+    case "codeBlock":
+      return [{ tag: "pre", children: codeToChildren(block.code) }]
+    case "heading": {
+      const tag = block.level <= 2 ? "h3" : "h4"
+      return [{ tag, children: parseInline(block.text) }]
+    }
+    case "hr":
+      return [{ tag: "hr" }]
+    case "unorderedList":
+      return [{ tag: "ul", children: block.items.map((item) => ({ tag: "li" as const, children: parseInline(item) })) }]
+    case "orderedList":
+      return [{ tag: "ol", children: block.items.map((item) => ({ tag: "li" as const, children: parseInline(item) })) }]
+    case "blockquote":
+      return [{ tag: "blockquote", children: parseInline(block.text) }]
+    case "paragraph":
+      return [{ tag: "p", children: parseInline(block.text) }]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a markdown string directly to Telegraph Node array.
+ * @since 1.0.0
+ */
+export const markdownToTelegraphNodes = (md: string): ReadonlyArray<Node> => parseBlocks(md).flatMap(blockToNodes)
+
+/**
+ * Encode a PlantUML diagram for the kroki.io API.
+ * Uses zlib deflate + base64url encoding.
+ */
+const encodeForKroki = (plantuml: string): string => {
+  const compressed = deflateSync(Buffer.from(plantuml, "utf-8"))
+  return compressed.toString("base64url")
+}
+
+/**
+ * Build a kroki.io PlantUML SVG URL from a Mermaid class diagram string.
+ */
+const mermaidToKrokiUrl = (mermaidContent: string): string => {
+  const plantuml = mermaidToPlantUml(mermaidContent)
+  const encoded = encodeForKroki(plantuml)
+  return `https://kroki.io/plantuml/svg/${encoded}`
+}
+
+/**
+ * Convert spec files to Telegraph Node array.
+ * Adds file name as h3 heading per file.
+ * Mermaid files become kroki.io PlantUML SVG images.
+ * @since 1.0.0
+ */
+export const specFilesToTelegraphNodes = (files: ReadonlyArray<SpecFile>): ReadonlyArray<Node> => {
+  const nodes: Array<Node> = []
+  for (const file of files) {
+    nodes.push({ tag: "h3", children: [file.name] })
+
+    if (file.mermaid) {
+      const url = mermaidToKrokiUrl(file.content)
+      nodes.push({ tag: "img", attrs: { src: url } })
+    } else {
+      for (const node of markdownToTelegraphNodes(file.content)) {
+        nodes.push(node)
+      }
+    }
+  }
+  return nodes
+}

package/src/schemas/CredentialSchemas.ts

@@ -0,0 +1,23 @@
+/**
+ * Credential schemas
+ * @since 1.0.0
+ */
+import { Schema } from "effect"
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class LalphGithubToken extends Schema.Class<LalphGithubToken>("LalphGithubToken")({
+  token: Schema.String
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class LalphLinearToken extends Schema.Class<LalphLinearToken>("LalphLinearToken")({
+  token: Schema.String,
+  expiresAt: Schema.String,
+  refreshToken: Schema.String
+}) {}

package/src/schemas/GitHubSchemas.ts

@@ -0,0 +1,50 @@
+/**
+ * GitHub API response schemas
+ * @since 1.0.0
+ */
+import { Schema } from "effect"
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class GitHubRepo extends Schema.Class<GitHubRepo>("GitHubRepo")({
+  id: Schema.Number,
+  name: Schema.String,
+  full_name: Schema.String,
+  owner: Schema.Struct({
+    login: Schema.String
+  }),
+  html_url: Schema.String
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class GitHubPullRequest extends Schema.Class<GitHubPullRequest>("GitHubPullRequest")({
+  id: Schema.Number,
+  number: Schema.Number,
+  title: Schema.String,
+  state: Schema.String,
+  html_url: Schema.String,
+  headRef: Schema.propertySignature(Schema.String).pipe(Schema.fromKey("head_ref")),
+  headSha: Schema.String,
+  hasConflicts: Schema.Boolean,
+  repo: Schema.String
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class GitHubComment extends Schema.Class<GitHubComment>("GitHubComment")({
+  id: Schema.Number,
+  body: Schema.String,
+  user: Schema.Struct({
+    login: Schema.String
+  }),
+  created_at: Schema.String,
+  html_url: Schema.String,
+  repo: Schema.optionalWith(Schema.String, { default: () => "" })
+}) {}

package/src/schemas/LinearSchemas.ts

@@ -0,0 +1,57 @@
+/**
+ * Linear API response schemas
+ * @since 1.0.0
+ */
+import { Schema } from "effect"
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class LinearIssueNode extends Schema.Class<LinearIssueNode>("LinearIssueNode")({
+  id: Schema.String,
+  title: Schema.String,
+  identifier: Schema.String,
+  url: Schema.String,
+  createdAt: Schema.String,
+  updatedAt: Schema.String,
+  state: Schema.Struct({
+    name: Schema.String
+  })
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class LinearIssuesResponse extends Schema.Class<LinearIssuesResponse>("LinearIssuesResponse")({
+  data: Schema.Struct({
+    issues: Schema.Struct({
+      nodes: Schema.Array(LinearIssueNode)
+    })
+  })
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class LinearWorkflowState extends Schema.Class<LinearWorkflowState>("LinearWorkflowState")({
+  id: Schema.String,
+  name: Schema.String,
+  type: Schema.String
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class LinearWorkflowStatesResponse extends Schema.Class<LinearWorkflowStatesResponse>(
+  "LinearWorkflowStatesResponse"
+)({
+  data: Schema.Struct({
+    workflowStates: Schema.Struct({
+      nodes: Schema.Array(LinearWorkflowState)
+    })
+  })
+}) {}

package/src/schemas/ProjectSchemas.ts

@@ -0,0 +1,18 @@
+/**
+ * Project schemas matching lalph's Project domain
+ * @since 1.0.0
+ */
+import { Schema } from "effect"
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class LalphProject extends Schema.Class<LalphProject>("LalphProject")({
+  id: Schema.String,
+  enabled: Schema.Boolean,
+  targetBranch: Schema.Option(Schema.String),
+  concurrency: Schema.Int.pipe(Schema.positive()),
+  gitFlow: Schema.Literal("pr", "commit"),
+  reviewAgent: Schema.Boolean
+}) {}

package/src/schemas/TrackerSchemas.ts

@@ -0,0 +1,27 @@
+/**
+ * Tracker schemas for task tracking events
+ * @since 1.0.0
+ */
+import { Schema } from "effect"
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class TrackerIssue extends Schema.Class<TrackerIssue>("TrackerIssue")({
+  id: Schema.String,
+  title: Schema.String,
+  state: Schema.String,
+  url: Schema.String,
+  createdAt: Schema.String,
+  updatedAt: Schema.String
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class TrackerIssueEvent extends Schema.Class<TrackerIssueEvent>("TrackerIssueEvent")({
+  action: Schema.Literal("created", "updated"),
+  issue: TrackerIssue
+}) {}

package/src/services/AppContext.ts

@@ -0,0 +1,72 @@
+/**
+ * Application context — resolves project root and config directory paths
+ * @since 1.0.0
+ */
+import { FileSystem, Path } from "@effect/platform"
+import { Context, Data, Effect, Layer } from "effect"
+
+/**
+ * @since 1.0.0
+ * @category errors
+ */
+export class AppContextError extends Data.TaggedError("AppContextError")<{
+  message: string
+  cause: unknown
+}> {}
+
+/**
+ * @since 1.0.0
+ * @category services
+ */
+export interface AppContextService {
+  readonly projectRoot: string
+  readonly configDir: string
+}
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export class AppContext extends Context.Tag("AppContext")<
+  AppContext,
+  AppContextService
+>() {}
+
+/**
+ * @since 1.0.0
+ * @category layers
+ */
+export const AppContextLive = Layer.effect(
+  AppContext,
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const pathService = yield* Path.Path
+
+    let current = pathService.resolve(".")
+    let lalphPath: string | undefined
+
+    while (true) {
+      const candidate = pathService.join(current, ".lalph")
+      const exists = yield* fs.exists(candidate)
+      if (exists) {
+        lalphPath = candidate
+        break
+      }
+      const parent = pathService.dirname(current)
+      if (parent === current) break
+      current = parent
+    }
+
+    if (lalphPath === undefined) {
+      return yield* new AppContextError({
+        message: "Could not find .lalph/ directory. Are you inside a lalph project?",
+        cause: null
+      })
+    }
+
+    return AppContext.of({
+      projectRoot: pathService.dirname(lalphPath),
+      configDir: pathService.join(lalphPath, "config")
+    })
+  })
+)

package/src/services/AppRuntimeConfig.ts

@@ -0,0 +1,23 @@
+/**
+ * Runtime configuration schema and service tag
+ * @since 1.0.0
+ */
+import { Context, Schema } from "effect"
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class RuntimeConfig extends Schema.Class<RuntimeConfig>("RuntimeConfig")({
+  pollIntervalSeconds: Schema.Number,
+  triggerKeyword: Schema.String,
+  timerDelaySeconds: Schema.Number,
+  autoMergeEnabled: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  autoMergeWaitMinutes: Schema.optionalWith(Schema.Number, { default: () => 10 })
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export class AppRuntimeConfig extends Context.Tag("AppRuntimeConfig")<AppRuntimeConfig, RuntimeConfig>() {}