@llm4ts/flow 0.7.5 → 0.8.0

package/src/BasecampTool.ts

@@ -0,0 +1,413 @@
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import { Capabilities } from "@llm4ts/core/Capability"
+import type { ProcessExecutorShape, ProcessResult } from "@llm4ts/core/ProcessExecutor"
+import { ColumnNotFound, ProcessError, type FlowError } from "./FlowError.ts"
+import type { FlowEventsShape } from "./FlowEvents.ts"
+import { guarded } from "./CapabilityGuard.ts"
+
+// One tool instance operates one board. `cardTable` is only needed when the
+// project has more than one card table (the CLI resolves the single one).
+export class BasecampProjectRef extends Schema.Class<BasecampProjectRef>("BasecampProjectRef")({
+  project: Schema.String,
+  cardTable: Schema.optionalKey(Schema.String)
+}) {}
+
+export class Column extends Schema.Class<Column>("Column")({
+  id: Schema.Int,
+  title: Schema.String
+}) {}
+
+// Basecamp bodies are rich-text HTML, never Markdown — the field names say so.
+export class Card extends Schema.Class<Card>("Card")({
+  id: Schema.Int,
+  title: Schema.String,
+  contentHtml: Schema.String,
+  column: Column,
+  assignees: Schema.Array(Schema.String),
+  commentsCount: Schema.Int,
+  updatedAt: Schema.String,
+  url: Schema.String
+}) {}
+
+export class CardComment extends Schema.Class<CardComment>("CardComment")({
+  id: Schema.Int,
+  author: Schema.String,
+  contentHtml: Schema.String,
+  createdAt: Schema.String
+}) {}
+
+export class CardStep extends Schema.Class<CardStep>("CardStep")({
+  id: Schema.Int,
+  title: Schema.String,
+  completed: Schema.Boolean
+}) {}
+
+const projectFlags = (board: BasecampProjectRef): ReadonlyArray<string> => [
+  "--project",
+  board.project,
+  ...(board.cardTable === undefined ? [] : ["--card-table", board.cardTable])
+]
+
+const jsonFlags = ["--json", "--quiet"]
+
+export const cardColumnsArgs = (board: BasecampProjectRef): ReadonlyArray<string> => [
+  "cards",
+  "columns",
+  ...projectFlags(board),
+  ...jsonFlags
+]
+
+export const cardListArgs = (board: BasecampProjectRef, column: Column): ReadonlyArray<string> => [
+  "cards",
+  "list",
+  "--column",
+  String(column.id),
+  "--all",
+  ...projectFlags(board),
+  ...jsonFlags
+]
+
+export const cardShowArgs = (board: BasecampProjectRef, cardId: number): ReadonlyArray<string> => [
+  "cards",
+  "show",
+  String(cardId),
+  ...projectFlags(board),
+  ...jsonFlags
+]
+
+export const cardMoveArgs = (
+  board: BasecampProjectRef,
+  cardId: number,
+  column: Column
+): ReadonlyArray<string> => [
+  "cards",
+  "move",
+  String(cardId),
+  "--to",
+  String(column.id),
+  ...projectFlags(board),
+  "--quiet"
+]
+
+export const cardCreateArgs = (
+  board: BasecampProjectRef,
+  column: Column,
+  title: string,
+  content: string,
+  assignee?: string
+): ReadonlyArray<string> => [
+  "cards",
+  "create",
+  title,
+  content,
+  "--column",
+  String(column.id),
+  ...(assignee === undefined ? [] : ["--assignee", assignee]),
+  ...projectFlags(board),
+  ...jsonFlags
+]
+
+export const cardAssignArgs = (
+  board: BasecampProjectRef,
+  cardId: number,
+  assignee: string
+): ReadonlyArray<string> => [
+  "cards",
+  "update",
+  String(cardId),
+  "--assignee",
+  assignee,
+  ...projectFlags(board),
+  "--quiet"
+]
+
+// Comments hang off the card alone; `basecamp comments` rejects --project.
+export const cardCommentsArgs = (cardId: number): ReadonlyArray<string> => [
+  "comments",
+  "list",
+  String(cardId),
+  "--all",
+  ...jsonFlags
+]
+
+export const cardCommentCreateArgs = (cardId: number, body: string): ReadonlyArray<string> => [
+  "comments",
+  "create",
+  String(cardId),
+  body,
+  "--quiet"
+]
+
+export const cardStepsArgs = (board: BasecampProjectRef, cardId: number): ReadonlyArray<string> => [
+  "cards",
+  "steps",
+  String(cardId),
+  ...projectFlags(board),
+  ...jsonFlags
+]
+
+export const cardStepCompleteArgs = (
+  board: BasecampProjectRef,
+  stepId: number
+): ReadonlyArray<string> => [
+  "cards",
+  "step",
+  "complete",
+  String(stepId),
+  ...projectFlags(board),
+  "--quiet"
+]
+
+const decodeJson = <A, S extends Schema.Codec<A, string>>(
+  operation: string,
+  schema: S,
+  json: string
+): Effect.Effect<S["Type"], ProcessError> =>
+  Schema.decodeUnknownEffect(schema)(json).pipe(
+    Effect.mapError((error) =>
+      ProcessError.make({
+        message: operation,
+        detail: String(error)
+      })
+    )
+  )
+
+const columnStruct = Schema.Struct({
+  id: Schema.Int,
+  title: Schema.String
+})
+
+export const parseColumns = (json: string): Effect.Effect<ReadonlyArray<Column>, ProcessError> =>
+  decodeJson(
+    "basecamp parse columns",
+    Schema.fromJsonString(Schema.Array(columnStruct)),
+    json
+  ).pipe(Effect.map((columns) => columns.map((column) => Column.make(column))))
+
+const cardStruct = Schema.Struct({
+  id: Schema.Int,
+  title: Schema.String,
+  content: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  parent: columnStruct,
+  assignees: Schema.optionalKey(
+    Schema.NullOr(Schema.Array(Schema.Struct({ name: Schema.String })))
+  ),
+  comments_count: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+  updated_at: Schema.String,
+  app_url: Schema.String
+})
+
+const toCard = (item: typeof cardStruct.Type): Card =>
+  Card.make({
+    id: item.id,
+    title: item.title,
+    contentHtml: item.content ?? "",
+    column: Column.make(item.parent),
+    assignees: (item.assignees ?? []).map((assignee) => assignee.name),
+    commentsCount: item.comments_count ?? 0,
+    updatedAt: item.updated_at,
+    url: item.app_url
+  })
+
+export const parseCard = (json: string): Effect.Effect<Card, ProcessError> =>
+  decodeJson("basecamp parse card", Schema.fromJsonString(cardStruct), json).pipe(
+    Effect.map(toCard)
+  )
+
+export const parseCards = (json: string): Effect.Effect<ReadonlyArray<Card>, ProcessError> =>
+  decodeJson("basecamp parse cards", Schema.fromJsonString(Schema.Array(cardStruct)), json).pipe(
+    Effect.map((items) => items.map(toCard))
+  )
+
+const commentStruct = Schema.Struct({
+  id: Schema.Int,
+  content: Schema.String,
+  creator: Schema.Struct({ name: Schema.String }),
+  created_at: Schema.String
+})
+
+export const parseCardComments = (
+  json: string
+): Effect.Effect<ReadonlyArray<CardComment>, ProcessError> =>
+  decodeJson(
+    "basecamp parse comments",
+    Schema.fromJsonString(Schema.Array(commentStruct)),
+    json
+  ).pipe(
+    Effect.map((comments) =>
+      comments.map((comment) =>
+        CardComment.make({
+          id: comment.id,
+          author: comment.creator.name,
+          contentHtml: comment.content,
+          createdAt: comment.created_at
+        })
+      )
+    )
+  )
+
+const stepStruct = Schema.Struct({
+  id: Schema.Int,
+  title: Schema.String,
+  completed: Schema.Boolean
+})
+
+// A card without steps prints `null`, not `[]`.
+export const parseCardSteps = (
+  json: string
+): Effect.Effect<ReadonlyArray<CardStep>, ProcessError> =>
+  decodeJson(
+    "basecamp parse steps",
+    Schema.fromJsonString(Schema.NullOr(Schema.Array(stepStruct))),
+    json
+  ).pipe(Effect.map((steps) => (steps ?? []).map((step) => CardStep.make(step))))
+
+export interface BasecampToolShape {
+  readonly listColumns: Effect.Effect<ReadonlyArray<Column>, FlowError>
+  readonly resolveColumn: (title: string) => Effect.Effect<Column, FlowError>
+  readonly listCards: (column: Column) => Effect.Effect<ReadonlyArray<Card>, FlowError>
+  readonly readCard: (cardId: number) => Effect.Effect<Card, FlowError>
+  readonly moveCard: (cardId: number, column: Column) => Effect.Effect<void, FlowError>
+  readonly createCard: (
+    column: Column,
+    title: string,
+    content: string,
+    assignee?: string
+  ) => Effect.Effect<Card, FlowError>
+  readonly assignCard: (cardId: number, assignee: string) => Effect.Effect<void, FlowError>
+  readonly readCardComments: (
+    cardId: number
+  ) => Effect.Effect<ReadonlyArray<CardComment>, FlowError>
+  readonly writeCardComment: (cardId: number, body: string) => Effect.Effect<void, FlowError>
+  readonly listSteps: (cardId: number) => Effect.Effect<ReadonlyArray<CardStep>, FlowError>
+  readonly completeStep: (stepId: number) => Effect.Effect<void, FlowError>
+}
+
+const output = (result: ProcessResult): string => result.stdout.join("\n").trim()
+
+export const makeBasecampTool = Effect.fn("@llm4ts/flow/BasecampTool.make")(function* (
+  process: ProcessExecutorShape,
+  workDir: string,
+  events: FlowEventsShape,
+  board: BasecampProjectRef
+): Effect.fn.Return<BasecampToolShape> {
+  const columnsCache = yield* Ref.make<ReadonlyArray<Column> | undefined>(undefined)
+
+  const run = (args: ReadonlyArray<string>): Effect.Effect<ProcessResult, FlowError> =>
+    process.run(["basecamp", ...args], workDir, {}).pipe(
+      Effect.mapError((error) =>
+        ProcessError.make({
+          message: `basecamp ${args.join(" ")}`,
+          detail: error.message
+        })
+      ),
+      Effect.flatMap((result) =>
+        result.exitCode === 0
+          ? Effect.succeed(result)
+          : Effect.fail(
+              ProcessError.make({
+                message: `basecamp ${args.join(" ")}`,
+                detail:
+                  [...result.stdout, ...result.stderr].join("\n").trim() ||
+                  `exit code ${result.exitCode}`
+              })
+            )
+      )
+    )
+
+  const read = <A>(
+    operation: string,
+    effect: Effect.Effect<A, FlowError>
+  ): Effect.Effect<A, FlowError> => guarded(Capabilities.BasecampRead, operation, events, effect)
+  const write = <A>(
+    operation: string,
+    effect: Effect.Effect<A, FlowError>
+  ): Effect.Effect<A, FlowError> => guarded(Capabilities.BasecampWrite, operation, events, effect)
+
+  // The board's columns barely change within a tool's lifetime; fetch once.
+  const cachedColumns: Effect.Effect<ReadonlyArray<Column>, FlowError> = Ref.get(columnsCache).pipe(
+    Effect.flatMap((cached) =>
+      cached !== undefined
+        ? Effect.succeed(cached)
+        : run(cardColumnsArgs(board)).pipe(
+            Effect.flatMap((result) => parseColumns(output(result))),
+            Effect.tap((columns) => Ref.set(columnsCache, columns))
+          )
+    )
+  )
+
+  return {
+    listColumns: read("basecamp cards columns", cachedColumns),
+    resolveColumn: (title) =>
+      read(
+        "basecamp cards columns",
+        cachedColumns.pipe(
+          Effect.flatMap((columns) => {
+            const match = columns.find(
+              (column) => column.title.toLowerCase() === title.toLowerCase()
+            )
+            return match !== undefined
+              ? Effect.succeed(match)
+              : Effect.fail(
+                  ColumnNotFound.make({
+                    title,
+                    available: columns.map((column) => column.title)
+                  })
+                )
+          })
+        )
+      ),
+    listCards: (column) =>
+      read(
+        "basecamp cards list",
+        run(cardListArgs(board, column)).pipe(
+          Effect.flatMap((result) => parseCards(output(result)))
+        )
+      ),
+    readCard: (cardId) =>
+      read(
+        "basecamp cards show",
+        run(cardShowArgs(board, cardId)).pipe(Effect.flatMap((result) => parseCard(output(result))))
+      ),
+    moveCard: (cardId, column) =>
+      write("basecamp cards move", run(cardMoveArgs(board, cardId, column)).pipe(Effect.asVoid)),
+    createCard: (column, title, content, assignee) =>
+      write(
+        "basecamp cards create",
+        run(cardCreateArgs(board, column, title, content, assignee)).pipe(
+          Effect.flatMap((result) => parseCard(output(result)))
+        )
+      ),
+    assignCard: (cardId, assignee) =>
+      write(
+        "basecamp cards update",
+        run(cardAssignArgs(board, cardId, assignee)).pipe(Effect.asVoid)
+      ),
+    readCardComments: (cardId) =>
+      read(
+        "basecamp comments list",
+        run(cardCommentsArgs(cardId)).pipe(
+          Effect.flatMap((result) => parseCardComments(output(result)))
+        )
+      ),
+    writeCardComment: (cardId, body) =>
+      write(
+        "basecamp comments create",
+        run(cardCommentCreateArgs(cardId, body)).pipe(Effect.asVoid)
+      ),
+    listSteps: (cardId) =>
+      read(
+        "basecamp cards steps",
+        run(cardStepsArgs(board, cardId)).pipe(
+          Effect.flatMap((result) => parseCardSteps(output(result)))
+        )
+      ),
+    completeStep: (stepId) =>
+      write(
+        "basecamp cards step complete",
+        run(cardStepCompleteArgs(board, stepId)).pipe(Effect.asVoid)
+      )
+  }
+})

package/src/FlowError.ts

@@ -105,6 +105,15 @@ export class FlowCapabilityDenied extends Schema.TaggedErrorClass<FlowCapability
   }
 }
 
+export class ColumnNotFound extends Schema.TaggedErrorClass<ColumnNotFound>()("ColumnNotFound", {
+  title: Schema.String,
+  available: Schema.Array(Schema.String)
+}) {
+  get message(): string {
+    return `column "${this.title}" not found on the card table; available: ${this.available.join(", ")}`
+  }
+}
+
 export class BudgetExceeded extends Schema.TaggedErrorClass<BudgetExceeded>()("BudgetExceeded", {
   metric: Schema.Literals(["tokens", "costUsd"]),
   limit: Schema.Number,
@@ -126,6 +135,7 @@ export const FlowError = Schema.Union([
   ProcessError,
   FlowLlmError,
   FlowCapabilityDenied,
+  ColumnNotFound,
   BudgetExceeded
 ])
 export type FlowError = typeof FlowError.Type

package/src/GitHubTool.ts

@@ -153,6 +153,22 @@ export const issueCommentEditArgs = (
   `body=${body}`
 ]
 
+export class IssueComment extends Schema.Class<IssueComment>("IssueComment")({
+  author: Schema.String,
+  body: Schema.String,
+  createdAt: Schema.String
+}) {}
+
+export const issueCommentsArgs = (ref: IssueRef): ReadonlyArray<string> => [
+  "issue",
+  "view",
+  String(ref.number),
+  "--repo",
+  `${ref.owner}/${ref.repo}`,
+  "--json",
+  "comments"
+]
+
 export const issueCommentArgs = (ref: IssueRef, body: string): ReadonlyArray<string> => [
   "issue",
   "comment",
@@ -317,6 +333,18 @@ class GhIssueSummary extends Schema.Class<GhIssueSummary>("GhIssueSummary")({
   updatedAt: Schema.String
 }) {}
 
+class GhComment extends Schema.Class<GhComment>("GhComment")({
+  author: GhAuthor,
+  body: Schema.String,
+  createdAt: Schema.String
+}) {}
+
+class GhComments extends Schema.Class<GhComments>("GhComments")({
+  comments: Schema.Array(GhComment).pipe(
+    Schema.withConstructorDefault(Effect.succeed(Object.freeze([])))
+  )
+}) {}
+
 class GhCheck extends Schema.Class<GhCheck>("GhCheck")({
   status: Schema.optionalKey(Schema.String),
   conclusion: Schema.optionalKey(Schema.String),
@@ -372,6 +400,28 @@ export const parseIssueList = (
     )
   )
 
+export const parseIssueComments = (
+  json: string
+): Effect.Effect<ReadonlyArray<IssueComment>, ProcessError> =>
+  Schema.decodeUnknownEffect(Schema.fromJsonString(GhComments))(json).pipe(
+    Effect.map((parsed) =>
+      parsed.comments.map(
+        (comment) =>
+          new IssueComment({
+            author: comment.author.login,
+            body: comment.body,
+            createdAt: comment.createdAt
+          })
+      )
+    ),
+    Effect.mapError((error) =>
+      ProcessError.make({
+        message: "gh issue view comments",
+        detail: `invalid comments JSON: ${String(error)}`
+      })
+    )
+  )
+
 export const outcomeFromChecksJson = (json: string): Effect.Effect<BuildOutcome, ProcessError> =>
   Schema.decodeUnknownEffect(Schema.fromJsonString(GhChecks))(json).pipe(
     Effect.map((parsed) => {
@@ -404,6 +454,9 @@ export interface GitHubToolShape {
     draft?: boolean
   ) => Effect.Effect<PullRequest, FlowError>
   readonly readIssue: (ref: IssueRef) => Effect.Effect<Issue, FlowError>
+  readonly readIssueComments: (
+    ref: IssueRef
+  ) => Effect.Effect<ReadonlyArray<IssueComment>, FlowError>
   // Returns the created comment's reference when the gh output carries it
   // (undefined otherwise), so callers can edit the comment later — e.g. a
   // plan checklist kept up to date as tasks complete.
@@ -531,6 +584,13 @@ export const makeGitHubTool = (
         "gh issue view",
         run(issueViewArgs(ref)).pipe(Effect.flatMap((result) => parseIssue(output(result))))
       ),
+    readIssueComments: (ref) =>
+      read(
+        "gh issue view comments",
+        run(issueCommentsArgs(ref)).pipe(
+          Effect.flatMap((result) => parseIssueComments(output(result)))
+        )
+      ),
     writeIssueComment: (ref, body) =>
       write(
         "gh issue comment",