@qotaq/lalphgram 0.1.0

package/src/Events.ts

@@ -0,0 +1,98 @@
+/**
+ * Event types for the notification system
+ * @since 1.0.0
+ */
+import { Data } from "effect"
+import type { GitHubComment, GitHubPullRequest } from "./schemas/GitHubSchemas.js"
+import type { TrackerIssue } from "./schemas/TrackerSchemas.js"
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export class TaskCreated extends Data.TaggedClass("TaskCreated")<{
+  readonly issue: TrackerIssue
+}> {}
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export class TaskUpdated extends Data.TaggedClass("TaskUpdated")<{
+  readonly issue: TrackerIssue
+  readonly previousState: string
+}> {}
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export class PROpened extends Data.TaggedClass("PROpened")<{
+  readonly pr: GitHubPullRequest
+}> {}
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export class PRConflictDetected extends Data.TaggedClass("PRConflictDetected")<{
+  readonly pr: GitHubPullRequest
+}> {}
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export class PRCommentAdded extends Data.TaggedClass("PRCommentAdded")<{
+  readonly pr: GitHubPullRequest
+  readonly comment: GitHubComment
+}> {}
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export class PRAutoMerged extends Data.TaggedClass("PRAutoMerged")<{
+  readonly pr: GitHubPullRequest
+}> {}
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export class PRCIFailed extends Data.TaggedClass("PRCIFailed")<{
+  readonly pr: GitHubPullRequest
+  readonly failedChecks: ReadonlyArray<{
+    readonly name: string
+    readonly html_url: string
+    readonly conclusion: string
+  }>
+}> {}
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export type AutoMergeEvent = PRAutoMerged
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export type PullRequestEvent =
+  | PROpened
+  | PRConflictDetected
+  | PRCommentAdded
+  | PRCIFailed
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export type TaskTrackerEvent = TaskCreated | TaskUpdated
+
+/**
+ * @since 1.0.0
+ * @category events
+ */
+export type AppEvent = PullRequestEvent | AutoMergeEvent | TaskTrackerEvent

package/src/Main.ts

@@ -0,0 +1,177 @@
+/**
+ * lalph-notify CLI entry point — zero-config notification service using lalph project config
+ * @since 1.0.0
+ */
+import { Command as CliCommand, Options, Prompt } from "@effect/cli"
+import { Command as PlatformCommand, FetchHttpClient, FileSystem, Path } from "@effect/platform"
+import { NodeContext, NodeRuntime } from "@effect/platform-node"
+import { Config, Console, Effect, Layer, Logger, LogLevel, Option, Stream } from "effect"
+import { fileURLToPath } from "node:url"
+import { AppContext, AppContextLive } from "./services/AppContext.js"
+import { AppRuntimeConfig, RuntimeConfig } from "./services/AppRuntimeConfig.js"
+import { MainLayer, runEventLoop } from "./services/EventLoop.js"
+import { LalphConfig } from "./services/LalphConfig.js"
+import { MessengerAdapter } from "./services/MessengerAdapter/MessengerAdapter.js"
+import { PlanCommandBuilder } from "./services/PlanSession.js"
+import { TelegramConfig, TelegramConfigLive, TelegramConfigSchema } from "./services/TelegramConfig.js"
+
+const lalphNotifyCommand = CliCommand.make(
+  "lalph-notify",
+  {
+    interval: Options.integer("interval").pipe(
+      Options.withDefault(30),
+      Options.withDescription("Poll interval in seconds")
+    ),
+    keyword: Options.text("keyword").pipe(
+      Options.withDefault("urgent"),
+      Options.withDescription("Trigger keyword for comment timer")
+    ),
+    timer: Options.integer("timer").pipe(
+      Options.withDefault(300),
+      Options.withDescription("Comment timer delay in seconds")
+    )
+  },
+  ({ interval, keyword, timer }) =>
+    Effect.gen(function*() {
+      const store = yield* TelegramConfig
+
+      const existingTelegram = yield* store.get
+      const botToken = Option.isSome(existingTelegram)
+        ? existingTelegram.value.botToken
+        : yield* Prompt.text({ message: "Telegram bot token" })
+      const storedChatId = Option.isSome(existingTelegram)
+        ? existingTelegram.value.chatId
+        : null
+
+      if (Option.isNone(existingTelegram)) {
+        yield* store.set(new TelegramConfigSchema({ botToken, chatId: null }))
+      }
+
+      const autoMergeEnabled = yield* Prompt.confirm({ message: "Enable auto-merge?", initial: false })
+      const autoMergeWaitMinutes = autoMergeEnabled
+        ? yield* Prompt.integer({ message: "Maximum minutes to wait after last push before merging", min: 1 })
+        : null
+
+      const runtimeConfig = new RuntimeConfig({
+        pollIntervalSeconds: interval,
+        triggerKeyword: keyword,
+        timerDelaySeconds: timer,
+        autoMergeEnabled,
+        ...(autoMergeWaitMinutes !== null ? { autoMergeWaitMinutes } : {})
+      })
+
+      const planCommandLayer = Layer.effect(
+        PlanCommandBuilder,
+        Effect.gen(function*() {
+          const appContext = yield* AppContext
+          const fs = yield* FileSystem.FileSystem
+          const pathService = yield* Path.Path
+
+          // Resolve the real claude binary path
+          const realClaudePath = yield* PlatformCommand.make("which", "claude").pipe(
+            PlatformCommand.string,
+            Effect.map((s) => s.trim())
+          )
+
+          // Resolve tsx binary for running the TypeScript shim
+          const tsxPath = yield* PlatformCommand.make("which", "tsx").pipe(
+            PlatformCommand.string,
+            Effect.map((s) => s.trim())
+          )
+
+          // Resolve the SDK-based shim entry point relative to this file
+          const shimMainTs = pathService.join(
+            pathService.dirname(fileURLToPath(import.meta.url)),
+            "shim",
+            "bin.ts"
+          )
+
+          yield* Effect.log("Resolved shim paths").pipe(
+            Effect.annotateLogs({ realClaudePath, tsxPath, shimMainTs })
+          )
+
+          // Create shim directory and script that delegates to the SDK-based shim
+          const shimDir = pathService.join(appContext.configDir, "bin")
+          yield* fs.makeDirectory(shimDir, { recursive: true })
+
+          const shimPath = pathService.join(shimDir, "claude")
+          const shimScript = [
+            "#!/bin/bash",
+            `for arg in "$@"; do`,
+            `  if [ "$arg" = "--output-format" ]; then`,
+            `    exec ${JSON.stringify(realClaudePath)} "$@"`,
+            `  fi`,
+            `done`,
+            `REAL_CLAUDE_PATH=${JSON.stringify(realClaudePath)} exec ${JSON.stringify(tsxPath)} ${
+              JSON.stringify(shimMainTs)
+            } "$@"`
+          ].join("\n")
+          yield* fs.writeFileString(shimPath, shimScript)
+          yield* fs.chmod(shimPath, 0o755)
+          yield* Effect.log("Claude SDK shim created").pipe(
+            Effect.annotateLogs({ shimPath })
+          )
+
+          const originalPath = process.env["PATH"] ?? ""
+          const shimmedPath = `${shimDir}:${originalPath}`
+
+          return (tempFile: string) =>
+            PlatformCommand.make("lalph", "plan", "--file", tempFile, "--dangerous").pipe(
+              PlatformCommand.workingDirectory(appContext.projectRoot),
+              PlatformCommand.env({ PATH: shimmedPath }),
+              PlatformCommand.stdout("pipe"),
+              PlatformCommand.stderr("pipe"),
+              PlatformCommand.stdin("pipe")
+            )
+        })
+      )
+
+      const appLayer = Layer.mergeAll(
+        Layer.succeed(AppRuntimeConfig, runtimeConfig),
+        Layer.succeed(TelegramConfig, store),
+        planCommandLayer
+      )
+
+      yield* Effect.gen(function*() {
+        const creds = yield* LalphConfig
+        yield* Console.log(`Issue source: ${creds.issueSource}, repo: ${creds.repoFullName}`)
+
+        if (storedChatId === null) {
+          const messenger = yield* MessengerAdapter
+          yield* Console.log("Send any message to your Telegram bot to continue...")
+          const messages = yield* messenger.incomingMessages.pipe(
+            Stream.take(1),
+            Stream.runCollect
+          )
+          const firstMsg = [...messages][0]!
+          yield* store.set(new TelegramConfigSchema({ botToken, chatId: firstMsg.chatId }))
+          yield* Console.log("Telegram config saved.")
+        }
+
+        yield* runEventLoop
+      }).pipe(
+        Effect.provide(MainLayer.pipe(Layer.provide(appLayer)))
+      )
+    })
+).pipe(CliCommand.withDescription("Zero-config notification service using lalph project config"))
+
+const cli = CliCommand.run(lalphNotifyCommand, {
+  name: "lalph-notify",
+  version: "1.0.0"
+})
+
+const logLevelLayer = Layer.unwrapEffect(
+  Config.logLevel("LOG_LEVEL").pipe(
+    Config.withDefault(LogLevel.Info),
+    Effect.map(Logger.minimumLogLevel)
+  )
+)
+
+Effect.suspend(() => cli(process.argv)).pipe(
+  Effect.provide(TelegramConfigLive),
+  Effect.provide(AppContextLive),
+  Effect.provide(FetchHttpClient.layer),
+  Effect.provide(NodeContext.layer),
+  Effect.provide(logLevelLayer),
+  NodeRuntime.runMain
+)

package/src/index.ts

@@ -0,0 +1,124 @@
+/**
+ * @since 1.0.0
+ */
+export * from "./schemas/TrackerSchemas.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./schemas/GitHubSchemas.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./schemas/CredentialSchemas.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./schemas/LinearSchemas.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./Events.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./lib/BranchParser.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/TaskTracker/TaskTracker.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/TaskTracker/LinearTracker.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/TaskTracker/GitHubIssueTracker.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/OctokitClient.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/LinearSdkClient.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/GitHubClient.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/EventLoop.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/PullRequestTracker.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/CommentTimer.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/MessengerAdapter/MessengerAdapter.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/MessengerAdapter/TelegramAdapter.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/TrackerLayerMap.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/TelegramConfig.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/AppContext.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/AppRuntimeConfig.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/AutoMerge.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/LalphConfig.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./services/PlanSession.js"
+
+/**
+ * @since 1.0.0
+ */
+export * from "./lib/StreamJsonParser.js"

package/src/lib/AnalysisPrompts.ts

@@ -0,0 +1,54 @@
+/**
+ * Plan-type-specific analysis prompts for spec file follow-ups
+ * @since 1.0.0
+ */
+
+/**
+ * Returns an analysis prompt tailored to the given plan type.
+ * The prompt instructs Claude to write analysis output to `.specs/analysis.md`.
+ * @since 1.0.0
+ * @category prompts
+ */
+export const getAnalysisPrompt = (planType: string): string => {
+  switch (planType) {
+    case "Feature":
+      return `\
+Now analyze the spec you just wrote. Create the following files:
+
+1. \`.specs/analysis.md\` — high-level design summary in plain text:
+   - What services are added or changed and why
+   - Layer composition: what depends on what
+   - Key design decisions and trade-offs
+
+2. \`.specs/services.mmd\` — a Mermaid classDiagram showing all new/changed service interfaces with their methods and return types. Use \`<<interface>>\` annotations. Show dependency arrows between services. Use \`~\` for generics (e.g. \`Effect~void, MyError~\`).
+
+3. \`.specs/test.md\` — detailed test plan using AAA (Arrange/Act/Assert) structure. For each test case:
+   - **Name**: descriptive test name in \`it("...")\` style
+   - **Arrange**: what mocks, layers, and initial state to set up
+   - **Act**: the single effect/function call under test
+   - **Assert**: expected outcome and why this case matters
+
+Do NOT display file contents in your response. The system will send them to the user.`
+    case "Bug":
+      return `\
+Now analyze the spec you just wrote. Write your analysis to \`.specs/analysis.md\` covering:
+- Root cause analysis
+- A failing TDD test case that reproduces the bug
+- Resolution strategy
+- Regression prevention measures`
+    case "Refactor":
+      return `\
+Now analyze the spec you just wrote. Write your analysis to \`.specs/analysis.md\` covering:
+- Current state vs target state
+- Migration steps in order
+- Risk assessment for each step
+- Test impact: which tests need updating?`
+    default:
+      return `\
+Now analyze the spec you just wrote. Write your analysis to \`.specs/analysis.md\` covering:
+- Scope summary
+- Implementation approach
+- Dependencies and prerequisites
+- Test strategy`
+  }
+}

package/src/lib/BranchParser.ts

@@ -0,0 +1,58 @@
+/**
+ * Branch name parser service to extract and resolve issue IDs
+ * @since 1.0.0
+ */
+import { Context, Layer, Option } from "effect"
+import type { GitHubPullRequest } from "../schemas/GitHubSchemas.js"
+
+const linearPattern = /^([A-Z]+-\d+)\//
+const linearAnywhere = /([A-Z]+-\d+)/
+const githubIssuePattern = /^#?(\d+)\//
+const githubIssueAnywhere = /(?:^|\/)#?(\d+)(?:\/|$)/
+
+const linearIdPattern = /^[A-Z]+-\d+$/
+
+/**
+ * Extract a raw issue ID from a git branch name.
+ *
+ * Tries patterns in order:
+ * 1. Linear-style prefix: `ABC-123/description` → `ABC-123`
+ * 2. Linear-style anywhere: `feature/ABC-123-description` → `ABC-123`
+ * 3. GitHub issue prefix: `#42/description` or `42/description` → `42`
+ * 4. GitHub issue anywhere: `feature/#42/description` → `42`
+ *
+ * @since 1.0.0
+ * @category parsers
+ */
+export const extractIssueId = (branch: string): Option.Option<string> =>
+  Option.fromNullable(linearPattern.exec(branch)?.[1]).pipe(
+    Option.orElse(() => Option.fromNullable(linearAnywhere.exec(branch)?.[1])),
+    Option.orElse(() => Option.fromNullable(githubIssuePattern.exec(branch)?.[1])),
+    Option.orElse(() => Option.fromNullable(githubIssueAnywhere.exec(branch)?.[1]))
+  )
+
+/**
+ * @since 1.0.0
+ * @category services
+ */
+export interface BranchParserService {
+  readonly resolveIssueId: (pr: GitHubPullRequest) => Option.Option<string>
+}
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export class BranchParser extends Context.Tag("BranchParser")<BranchParser, BranchParserService>() {}
+
+/**
+ * @since 1.0.0
+ * @category layers
+ */
+export const BranchParserLive = Layer.succeed(
+  BranchParser,
+  BranchParser.of({
+    resolveIssueId: (pr) =>
+      Option.map(extractIssueId(pr.headRef), (id) => linearIdPattern.test(id) ? id : `${pr.repo}#${id}`)
+  })
+)

package/src/lib/MermaidToPlantUml.ts

@@ -0,0 +1,103 @@
+/**
+ * Converts Mermaid class diagram syntax to PlantUML.
+ * Pure function — no side effects or dependencies.
+ * @since 1.0.0
+ */
+
+/**
+ * Convert a Mermaid class diagram to PlantUML syntax.
+ *
+ * Handles:
+ * - `classDiagram` → `@startuml` / `@enduml`
+ * - `class Foo {` blocks (preserved)
+ * - `<<interface>>` stereotypes (preserved)
+ * - `~Type1, Type2~` generics → `<Type1, Type2>`
+ * - `+method(params) ReturnType` → `+method(params): ReturnType`
+ * - Relationship arrows pass through (`<|--`, `<|..`, `-->`, `..>`)
+ * @since 1.0.0
+ */
+export const mermaidToPlantUml = (mermaid: string): string => {
+  const lines = mermaid.split("\n")
+  const output: Array<string> = []
+  let insideClassBlock = false
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim()
+
+    // Skip empty lines — pass through
+    if (line === "") {
+      output.push("")
+      continue
+    }
+
+    // classDiagram → @startuml
+    if (line === "classDiagram") {
+      output.push("@startuml")
+      continue
+    }
+
+    // Convert generics: ~Type1, Type2~ → <Type1, Type2>
+    const converted = line.replace(/~([^~]+)~/g, "<$1>")
+
+    // Detect class block open: "class Foo {" or "class Foo<T> {"
+    if (/^class\s+\S+.*\{$/.test(converted)) {
+      insideClassBlock = true
+      output.push(converted)
+      continue
+    }
+
+    // Detect class block close
+    if (converted === "}" && insideClassBlock) {
+      insideClassBlock = false
+      output.push("}")
+      continue
+    }
+
+    // Inside a class block: convert member signatures
+    if (insideClassBlock) {
+      output.push(convertMember(converted))
+      continue
+    }
+
+    // Outside class blocks — relationships, annotations, etc. pass through
+    output.push(converted)
+  }
+
+  output.push("@enduml")
+  return output.join("\n")
+}
+
+/**
+ * Convert a single class member line.
+ * Mermaid: `+method(params) ReturnType` → PlantUML: `+method(params): ReturnType`
+ * Mermaid: `+field Type` → PlantUML: `+field: Type`
+ * Stereotypes like `<<interface>>` pass through unchanged.
+ */
+const convertMember = (line: string): string => {
+  // <<interface>> or <<abstract>> — pass through
+  if (/^<<.+>>$/.test(line)) {
+    return line
+  }
+
+  // Method with parentheses: +method(params) ReturnType
+  const methodMatch = /^([+\-#~]?)(\w+)\(([^)]*)\)\s+(.+)$/.exec(line)
+  if (methodMatch) {
+    const [, visibility, name, params, returnType] = methodMatch
+    return `${visibility}${name}(${params}): ${returnType}`
+  }
+
+  // Method with parentheses but no return type: +method(params)
+  const methodNoReturn = /^([+\-#~]?)(\w+)\(([^)]*)\)$/.exec(line)
+  if (methodNoReturn) {
+    return line
+  }
+
+  // Field: +field Type (no parentheses, has a space separating name and type)
+  const fieldMatch = /^([+\-#~]?)(\w+)\s+(.+)$/.exec(line)
+  if (fieldMatch) {
+    const [, visibility, name, type] = fieldMatch
+    return `${visibility}${name}: ${type}`
+  }
+
+  return line
+}