@kitman-sh/software-engineering 0.0.0-stage → 0.10.54

package/src/project-update.ts

@@ -0,0 +1,88 @@
+import { agentWork, defineLoop, draftUpdate, projectActivity, type ProjectActivityResult } from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+
+const Health = Schema.Literals(['on_track', 'at_risk', 'off_track'])
+
+const Input = Schema.Struct({ projectId: Schema.String })
+
+const Output = Schema.Struct({
+  /** Left out when nothing happened since the last Update, so there was nothing to draft. */
+  draftId: Schema.optional(Schema.String),
+  health: Schema.optional(Health)
+})
+
+const Written = Schema.Struct({
+  /** How the Project is going, judged from its Runs and Task changes. */
+  health: Health,
+  /** The Update for people to read: what moved, what is stuck and what comes next. */
+  note: Schema.String,
+  /** Why the health differs from the last Update's, naming the Runs or Tasks that moved it. */
+  healthReason: Schema.optional(Schema.String)
+})
+
+const label = { on_track: 'on track', at_risk: 'at risk', off_track: 'off track' } as const
+
+const day = (iso: string) =>
+  new Date(iso).toLocaleDateString('en-US', { month: 'short', day: 'numeric', timeZone: 'UTC' })
+
+const prompt = (read: ProjectActivityResult) =>
+  [
+    `Write a Project Update for ${read.project.name} from what happened ${read.since === undefined ? 'so far' : `since its last Update on ${day(read.since)}`}.`,
+    '```json',
+    JSON.stringify({ health: read.health, runs: read.runs, taskChanges: read.taskChanges }, null, 2),
+    '```',
+    'Say in a few short paragraphs what moved, what is stuck and what comes next, naming Tasks by key. Suggest a health: on_track, at_risk or off_track.',
+    ...(read.health === undefined
+      ? []
+      : [
+          `The last Update said ${read.health}. If your health differs, give in healthReason one sentence on why, naming the Runs or Tasks that moved it.`
+        ]),
+    'A person reviews and posts it, so claim nothing the Runs and Task changes do not show.'
+  ].join('\n')
+
+/** The note, opening with why the health moved when it did. */
+const noteOf = (read: ProjectActivityResult, written: typeof Written.Type) => {
+  if (read.health === undefined || read.health === written.health) return written.note
+
+  const moved = `Health moved from ${label[read.health]} to ${label[written.health]}`
+
+  return `${written.healthReason === undefined ? `${moved}.` : `${moved}: ${written.healthReason}`}\n\n${written.note}`
+}
+
+/**
+ * Reads a Project's Runs and Task changes since its latest Update, as the person who asked, and drafts the next Update
+ * into that person's Inbox, replacing their unposted draft. It never posts one: only a person can. With nothing new it
+ * drafts nothing. A Team that wants one every week schedules it in its own Kit with the Project's id as input.
+ */
+export default defineLoop({
+  id: 'project-update',
+  version: '2.0.1',
+  title: 'Project update',
+  input: Input,
+  output: Output,
+  agents: { writer: 'writer' },
+  checkout: 'none',
+  capabilities: ['read_project', 'agent_work', 'draft_update'],
+  run: ({ projectId }) =>
+    Effect.gen(function* () {
+      const read = yield* projectActivity('read', { projectId })
+
+      if (read.runs.length === 0 && read.taskChanges.length === 0) return {}
+
+      const written = yield* agentWork('write', { agent: 'writer', prompt: prompt(read), output: Written })
+
+      const draft = yield* draftUpdate('draft', {
+        projectId,
+        health: written.health,
+        note: noteOf(read, written),
+        writtenFrom: {
+          runs: read.runs.length,
+          taskChanges: read.taskChanges.length,
+          ...(read.since === undefined ? undefined : { since: read.since })
+        }
+      })
+
+      return { draftId: draft.id, health: written.health }
+    })
+})

package/src/release.ts

@@ -0,0 +1,406 @@
+import {
+  agentWork,
+  artifact,
+  ask,
+  claim,
+  defineLoop,
+  mergeChangeRequest,
+  pipelineMoved,
+  pipelineStatus,
+  release,
+  rerunPipeline,
+  verify,
+  waitFor
+} from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+
+const Input = Schema.Struct({
+  /** The tag to release; the drafting agent proposes one when left out. */
+  tag: Schema.optional(Schema.String),
+  /** The revision to tag; the Run's base branch head when left out. */
+  revision: Schema.optional(Schema.String),
+  /** A release ChangeRequest to wait for, merge, and tag the merge of. */
+  changeRequestId: Schema.optional(Schema.String),
+  /** What the release deploys to; one Release deploys to it at a time. The deploy Event type when left out. */
+  deployTarget: Schema.optional(Schema.String),
+  /** The Event type the deploy reports; `deploy` when left out. Its payload names the `tag` and a `status`. */
+  deployEvent: Schema.optional(Schema.String),
+  /** How long to wait for the deploy; 60 when left out. */
+  deployTimeoutMinutes: Schema.optional(Schema.Int)
+})
+
+const Drafted = Schema.Struct({
+  /** The next version's tag. */
+  tag: Schema.String,
+  /** The latest release tag before it; left out when there is none. */
+  previousTag: Schema.optional(Schema.String),
+  title: Schema.String,
+  notes: Schema.String,
+  /** The ChangeRequests the notes cover. */
+  changeRequests: Schema.Array(Schema.String)
+})
+
+type Drafted = typeof Drafted.Type
+
+const Output = Schema.Struct({
+  status: Schema.Literals([
+    'gate_failed',
+    'not_mergeable',
+    'rejected',
+    'deployed',
+    'rolled_back',
+    'deploy_failed',
+    'timed_out'
+  ]),
+  /** Why it stopped, or what happened, in a line. */
+  reason: Schema.String,
+  tag: Schema.optional(Schema.String),
+  notesArtifactId: Schema.optional(Schema.String),
+  revision: Schema.optional(Schema.String),
+  url: Schema.optional(Schema.String)
+})
+
+type Output = typeof Output.Type
+
+const draftPrompt = (tag: string | undefined, changeRequestId: string | undefined) =>
+  [
+    'Draft the release notes for the ChangeRequests merged since the last release tag on the base branch, including those with no linked Task.',
+    ...(changeRequestId === undefined ? [] : [`The release ChangeRequest ${changeRequestId} is part of it.`]),
+    'Group them by what a user of the software notices, and name each ChangeRequest you cover.',
+    tag === undefined
+      ? 'Propose the next version tag, following the scheme earlier tags use. With no earlier tag, propose v0.1.0 and say so in the notes.'
+      : `The release is tagged ${tag}.`,
+    'Give the latest earlier release tag as previousTag, or leave it out when there is none.'
+  ].join('\n\n')
+
+const redraftPrompt = (drafted: Drafted, edit: string) =>
+  [
+    'Redraft these release notes as asked, keeping the tag and everything not mentioned.',
+    `Asked: ${edit}`,
+    '```json',
+    JSON.stringify(drafted, null, 2),
+    '```'
+  ].join('\n\n')
+
+const approval = ['Approve', 'Edit notes', 'Reject'] as const
+
+/**
+ * Waits at no model cost until the release ChangeRequest is green, approved and mergeable, and gives the head that
+ * passed; or why it stopped. `round` names a gate run again after the head moved.
+ */
+const readyToMerge = (changeRequestId: string, round = 1) =>
+  Effect.gen(function* () {
+    // A newer head whose pipeline finishes while approval is awaited is gated afresh, up to 10 times.
+    for (let pass = 1; ; pass++) {
+      const at = (name: string) => {
+        const named = pass === 1 ? name : `${name}:moved:${pass}`
+
+        return round === 1 ? named : `${named}:${round}`
+      }
+
+      let read = yield* pipelineStatus(at('gate'), { changeRequestId })
+
+      // Read again after each pipeline Event, on whichever head is newest, so the gate judges what the forge says now.
+      for (let look = 1; look <= 10 && (read.status === 'running' || read.status === 'none'); look++) {
+        const again = (name: string) => at(look === 1 ? name : `${name}:${look}`)
+
+        yield* pipelineMoved(again('gate:pipeline'), changeRequestId, read)
+        read = yield* pipelineStatus(again('gate:after'), { changeRequestId })
+      }
+
+      if (read.status !== 'success') {
+        const failing = read.jobs.filter(job => job.status === 'failed').map(job => job.name)
+
+        return {
+          status: 'gate_failed',
+          reason: `The pipeline at ${read.head} is ${read.status}${failing.length === 0 ? '' : `: ${failing.join(', ')}`}`,
+          revision: read.head
+        } satisfies Output
+      }
+
+      const approved = yield* waitFor(at('approved'), {
+        event: 'change_request.approval',
+        // An approval of an earlier commit does not approve the one whose pipeline passed.
+        filter: { changeRequestId, approved: true, head: read.head },
+        timeout: '7 days',
+        or:
+          read.readAt === undefined
+            ? []
+            : [{ event: 'change_request.pipeline', filter: { changeRequestId }, since: read.readAt }]
+      })
+
+      if (approved.type !== 'change_request.approval') {
+        if (pass >= 10)
+          return {
+            status: 'not_mergeable',
+            reason: `ChangeRequest ${changeRequestId} kept moving while it awaited approval`
+          } satisfies Output
+
+        continue
+      }
+
+      const mergeable = yield* waitFor(at('mergeable'), {
+        event: 'change_request.mergeable',
+        filter: { changeRequestId },
+        timeout: '1 hour'
+      })
+
+      if (mergeable.payload.mergeable === false)
+        return {
+          status: 'not_mergeable',
+          reason: `ChangeRequest ${changeRequestId} does not merge cleanly; bring it up to date first`
+        } satisfies Output
+
+      return { passed: read.head }
+    }
+  }).pipe(
+    Effect.catchTags({
+      WaitTimedOut: timedOut =>
+        Effect.succeed({
+          status: 'not_mergeable',
+          reason: `Nothing happened on ChangeRequest ${changeRequestId} while waiting for ${timedOut.event}`
+        } satisfies Output),
+      ChangeRequestClosed: closed =>
+        Effect.succeed({
+          status: 'not_mergeable',
+          reason: `ChangeRequest ${changeRequestId} was ${closed.merged ? 'merged' : 'closed'} before Kitman released it`
+        } satisfies Output)
+    })
+  )
+
+const recovery = (previous: string | undefined) =>
+  previous === undefined
+    ? (['Retry the deploy', 'Leave it'] as const)
+    : (['Retry the deploy', `Roll back to ${previous}`, 'Leave it'] as const)
+
+/**
+ * Proves the release before anyone is asked: the approved checks pass on the revision to tag, or a release
+ * ChangeRequest is green, approved and mergeable. It then asks once, with no default, whether to release the drafted
+ * notes, which can be edited in place. On approval it merges the ChangeRequest when there is one, tags and publishes
+ * once (a tag already released at the same revision counts as done; one at another is never moved), holds the deploy
+ * target so two Releases never deploy over each other, and waits for the deploy. A failed or late deploy asks whether
+ * to retry (it runs the tag's failed pipeline again and waits), roll back to the previous tag (it runs that
+ * tag's pipeline again in full and waits for its deploy), or leave it, which it does by default.
+ */
+export default defineLoop({
+  id: 'release',
+  version: '2.0.0',
+  title: 'Release',
+  input: Input,
+  output: Output,
+  agents: { releaser: 'releaser' },
+  checkout: 'read',
+  capabilities: [
+    'agent_work',
+    'ask',
+    'verify',
+    'claim',
+    'publish_release',
+    'read_change_request',
+    'merge_change_request'
+  ],
+  run: input =>
+    Effect.gen(function* () {
+      const changeRequestId = input.changeRequestId
+      // The commit the gate proved, and the one tagged or merged: never the branch head read again later.
+      let gated: string
+
+      if (changeRequestId === undefined) {
+        const gate = yield* verify('gate', input.revision === undefined ? {} : { revision: input.revision })
+
+        if (!gate.passed) {
+          const failing = gate.checks.filter(check => check.status !== 'passed').map(check => check.name)
+
+          return {
+            status: 'gate_failed',
+            reason: `The checks fail at ${gate.revision}: ${failing.join(', ')}`,
+            revision: gate.revision
+          } satisfies Output
+        }
+
+        gated = gate.revision
+      } else {
+        const ready = yield* readyToMerge(changeRequestId)
+
+        if (!('passed' in ready)) return ready
+        gated = ready.passed
+      }
+
+      let drafted = yield* agentWork('draft-notes', {
+        agent: 'releaser',
+        prompt: draftPrompt(input.tag, changeRequestId),
+        output: Drafted
+      })
+
+      const tag = input.tag ?? drafted.tag
+
+      // The question has no default: a release goes out only when someone says so.
+      for (let round = 1; ; round++) {
+        const answer = yield* ask(round === 1 ? 'approve' : `approve:${round}`, {
+          prompt: `Release ${tag} with these notes?\n\n${drafted.notes}`,
+          options: [
+            { value: 'Approve', description: 'Tags, publishes and deploys it.' },
+            { value: 'Edit notes', description: 'Say what to change; the notes are redrafted.' },
+            { value: 'Reject', description: 'Keeps the draft and releases nothing.' }
+          ] satisfies { readonly value: (typeof approval)[number]; readonly description: string }[],
+          recommended: 'Approve',
+          recommendationReason:
+            'The release is proved: its checks pass, or its ChangeRequest is green, approved and mergeable.',
+          default: null
+        })
+
+        if (answer === 'Approve') break
+
+        if (answer === 'Reject') {
+          const why = yield* ask('reject-why', {
+            prompt: `Why not release ${tag}? The draft is kept.`,
+            freeText: true,
+            informationOnly: true,
+            recommendationReason: 'Only you know why you rejected it.',
+            default: 'No reason given',
+            timeout: '1 day'
+          })
+
+          const kept = yield* artifact('notes', {
+            kind: 'release_notes',
+            title: drafted.title,
+            text: drafted.notes,
+            data: { tag, changeRequests: drafted.changeRequests }
+          })
+
+          return { status: 'rejected', reason: why, tag, notesArtifactId: kept.artifactId } satisfies Output
+        }
+
+        const edit = yield* ask(`edit:${round}`, {
+          prompt: 'What should change in the notes?',
+          freeText: true,
+          informationOnly: true,
+          recommendationReason: 'You chose to edit them, so only you know what should change.',
+          default: '',
+          timeout: '1 day'
+        })
+
+        if (edit.trim() === '') continue
+
+        drafted = yield* agentWork(`redraft:${round}`, {
+          agent: 'releaser',
+          prompt: redraftPrompt(drafted, edit),
+          output: Drafted
+        })
+      }
+
+      const notes = yield* artifact('notes', {
+        kind: 'release_notes',
+        title: drafted.title,
+        text: drafted.notes,
+        data: { tag, changeRequests: drafted.changeRequests }
+      })
+
+      let revision = gated
+
+      if (changeRequestId !== undefined) {
+        // A head pushed while waiting for approval has passed nothing: it goes through the gate before it merges.
+        for (let round = 1; ; round++) {
+          const merged = yield* mergeChangeRequest(round === 1 ? 'merge' : `merge:${round}`, {
+            changeRequestId,
+            head: gated
+          })
+
+          if (merged.status === 'conflict')
+            return {
+              status: 'not_mergeable',
+              reason: `ChangeRequest ${changeRequestId} no longer merges cleanly`,
+              tag,
+              notesArtifactId: notes.artifactId
+            } satisfies Output
+
+          if (merged.status === 'merged') {
+            revision = merged.revision
+            break
+          }
+
+          if (round >= 3)
+            return {
+              status: 'not_mergeable',
+              reason: `ChangeRequest ${changeRequestId} kept moving while it was gated; it is at ${merged.head}`,
+              tag,
+              notesArtifactId: notes.artifactId
+            } satisfies Output
+
+          const ready = yield* readyToMerge(changeRequestId, round + 1)
+
+          if (!('passed' in ready)) return { ...ready, tag, notesArtifactId: notes.artifactId }
+          gated = ready.passed
+        }
+      }
+
+      const deployEvent = input.deployEvent ?? 'deploy'
+
+      // Held until the Run completes, so the next Release deploys after this one is settled.
+      yield* claim('deploy-target', { resource: `deploy:${input.deployTarget ?? deployEvent}` })
+
+      const released = yield* release('tag', {
+        tag,
+        revision,
+        title: drafted.title,
+        notes: drafted.notes
+      })
+
+      const deployed = (step: string, deployTag: string) =>
+        waitFor(step, {
+          event: deployEvent,
+          filter: { tag: deployTag },
+          timeout: `${input.deployTimeoutMinutes ?? 60} minutes`
+        }).pipe(
+          Effect.map(deploy =>
+            deploy.payload.status === 'failed' ? ('deploy_failed' as const) : ('deployed' as const)
+          ),
+          Effect.catchTag('WaitTimedOut', () => Effect.succeed('timed_out' as const))
+        )
+
+      const settled = { tag, notesArtifactId: notes.artifactId, revision: released.revision, url: released.url }
+      let status = yield* deployed('deploy', tag)
+
+      for (let round = 1; status !== 'deployed'; round++) {
+        const options = recovery(drafted.previousTag)
+
+        const answer = yield* ask(`recover:${round}`, {
+          prompt: `${tag} ${status === 'timed_out' ? 'did not report a deploy in time' : 'failed to deploy'}. What now?`,
+          options,
+          recommended: 'Retry the deploy',
+          recommendationReason:
+            'A failed or late deploy is often passing, and a retry runs only the failed jobs of the same tag.',
+          default: 'Leave it',
+          timeout: '1 hour'
+        })
+
+        if (answer === 'Leave it')
+          return { status, reason: `${tag} at ${released.revision} was left undeployed`, ...settled } satisfies Output
+
+        if (answer === 'Retry the deploy') {
+          yield* rerunPipeline(`deploy:rerun-${round}`, { ref: tag })
+          status = yield* deployed(`deploy:retry-${round}`, tag)
+          continue
+        }
+
+        const previous = drafted.previousTag ?? tag
+
+        yield* rerunPipeline(`deploy:redeploy-${round}`, { ref: previous, all: true })
+        const back = yield* deployed(`deploy:rollback-${round}`, previous)
+
+        if (back === 'deployed')
+          return { status: 'rolled_back', reason: `Rolled back to ${previous}`, ...settled } satisfies Output
+        status = back
+      }
+
+      yield* artifact('report', {
+        kind: 'release_report',
+        title: `${tag} deployed`,
+        text: `${tag} at ${released.revision} deployed. ${released.url}`,
+        data: { tag, status, revision: released.revision, url: released.url }
+      })
+
+      return { status: 'deployed', reason: `${tag} deployed`, ...settled } satisfies Output
+    })
+})