@pmelab/gtd 23.2.0 → 24.1.0

package/src/workflow/skills.test.ts

@@ -0,0 +1,109 @@
+import { Cause, Effect, Exit } from "effect"
+import { describe, expect, it } from "vitest"
+import { resolveScopeAccess, resolveScopeSkills } from "./skills.js"
+
+const FILE = "/repo/gtd.config.ts"
+
+const failure = async (skills: (vars: Record<string, string>) => unknown): Promise<string> => {
+  const exit = await Effect.runPromiseExit(
+    resolveScopeSkills({ skills: skills as never, configuredSkills: {}, skillsOrigin: FILE }, {}),
+  )
+  expect(Exit.isFailure(exit)).toBe(true)
+  return Exit.isFailure(exit) ? String(Cause.squash(exit.cause)) : ""
+}
+
+describe("resolveScopeSkills", () => {
+  it("wraps a throwing export with the config prefix and file", async () => {
+    const message = await failure(() => {
+      throw new Error("boom")
+    })
+    expect(message).toContain(`gtd config:\n  - ${FILE}: boom`)
+  })
+
+  it("rejects a non-object return", async () => {
+    expect(await failure(() => ["a"])).toContain(
+      `gtd config:\n  - ${FILE}: skills export must return an object of scope -> skill names`,
+    )
+  })
+
+  it("rejects a non-array value", async () => {
+    expect(await failure(() => ({ a: "x" }))).toContain(
+      `gtd config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
+    )
+  })
+
+  it("rejects a non-string entry", async () => {
+    expect(await failure(() => ({ a: ["x", 1] }))).toContain(
+      `gtd config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
+    )
+  })
+
+  it("reports an unknown config key at gtd.config.ts", async () => {
+    const exit = await Effect.runPromiseExit(
+      resolveScopeSkills(
+        { skills: () => ({ a: ["x"] }), configuredSkills: { nope: [] }, skillsOrigin: FILE },
+        {},
+      ),
+    )
+    expect(String(Exit.isFailure(exit) ? Cause.squash(exit.cause) : "")).toContain(
+      `${FILE}: config.skills.nope: "skills.nope" is not a scope that runs a turn — known scopes: a`,
+    )
+  })
+})
+
+describe("resolveScopeAccess", () => {
+  const run = (
+    def: {
+      access: (vars: Record<string, string>) => unknown
+      configuredAccess?: Record<string, object>
+    },
+    skills: Record<string, readonly string[]> = {},
+  ) =>
+    Effect.runPromiseExit(
+      resolveScopeAccess(
+        {
+          access: def.access as never,
+          configuredAccess: def.configuredAccess ?? {},
+          skillsOrigin: FILE,
+        },
+        skills,
+        {},
+      ),
+    )
+  const message = (exit: Awaited<ReturnType<typeof run>>): string =>
+    Exit.isFailure(exit) ? String(Cause.squash(exit.cause)) : ""
+
+  it("returns a well-shaped record", async () => {
+    const exit = await run({ access: () => ({ a: { write: ["x"] }, b: {} }) })
+    expect(Exit.isSuccess(exit) && exit.value).toEqual({ a: { write: ["x"] }, b: {} })
+  })
+
+  it("rejects a malformed export with the file", async () => {
+    expect(message(await run({ access: () => ["a"] }))).toContain(
+      `gtd config:\n  - ${FILE}: access export must return an object`,
+    )
+    expect(message(await run({ access: () => ({ a: { write: "x" } }) }))).toContain(
+      `${FILE}: access export: "a": access.write must be an array`,
+    )
+  })
+
+  it("knows the scopes of both the skills and access exports", async () => {
+    const exit = await run(
+      {
+        access: () => ({ fromAccess: {} }),
+        configuredAccess: { fromSkills: {}, fromAccess: {} },
+      },
+      { fromSkills: ["s"] },
+    )
+    expect(Exit.isSuccess(exit)).toBe(true)
+  })
+
+  it("reports an unknown key with the exact message and known scopes", async () => {
+    const text = message(
+      await run({ access: () => ({ b: {} }), configuredAccess: { nope: {} } }, { a: ["x"] }),
+    )
+    expect(text).toContain(
+      `${FILE}: config.access.nope: "access.nope" is not a scope that runs a turn — known scopes: a, b`,
+    )
+  })
+})

package/src/workflow/skills.ts

@@ -0,0 +1,90 @@
+import { Effect } from "effect"
+import { GtdError } from "../platform/index.js"
+import type { WorkflowDefinition } from "./Workflow.js"
+import { accessShapeFault } from "../replay/index.js"
+import type { ScopeAccess } from "../flows/index.js"
+import type { Diagnostic } from "./Diagnostic.js"
+import { failOnErrors } from "./load.js"
+
+const fail = (origin: string, message: string): GtdError =>
+  new GtdError(`gtd config:\n  - ${origin}: ${message}`)
+
+const checkShape = (value: unknown): Record<string, readonly string[]> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("skills export must return an object of scope -> skill names")
+  }
+  for (const [scope, names] of Object.entries(value)) {
+    if (!Array.isArray(names) || names.some((n) => typeof n !== "string")) {
+      throw new Error(`skills export: "${scope}" must be an array of skill names`)
+    }
+  }
+  return value as Record<string, readonly string[]>
+}
+
+/** Every `config` key that names no known scope is a load error. */
+const checkKeys = (
+  configured: Readonly<Record<string, unknown>>,
+  origin: string,
+  known: readonly string[],
+  section: "skills" | "access",
+): Effect.Effect<void, GtdError> => {
+  const sorted = [...known].sort()
+  const diagnostics: Diagnostic[] = Object.keys(configured)
+    .filter((key) => !sorted.includes(key))
+    .sort()
+    .map((key) => ({
+      severity: "error" as const,
+      path: ["config", section, key],
+      message: `"${section}.${key}" is not a scope that runs a turn — known scopes: ${sorted.join(", ")}`,
+      origin,
+    }))
+  return failOnErrors(diagnostics)
+}
+
+/**
+ * Skill lists for the settings actually in use. `config.skills` keys are
+ * judged here, not at config load: only now are the pinned/entry vars known.
+ */
+export const resolveScopeSkills = (
+  def: Pick<WorkflowDefinition, "skills" | "configuredSkills" | "skillsOrigin">,
+  vars: Readonly<Record<string, string>>,
+): Effect.Effect<Record<string, readonly string[]>, GtdError> =>
+  Effect.gen(function* () {
+    const skills = yield* Effect.try({
+      try: () => checkShape(def.skills(vars)),
+      catch: (e) => fail(def.skillsOrigin, e instanceof Error ? e.message : String(e)),
+    })
+    const known = Object.keys(skills)
+    yield* checkKeys(def.configuredSkills, def.skillsOrigin, known, "skills")
+    return skills
+  })
+
+const checkAccessShape = (value: unknown): Record<string, ScopeAccess> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("access export must return an object of scope -> { read?, write? }")
+  }
+  for (const [scope, access] of Object.entries(value)) {
+    const fault = accessShapeFault(access)
+    if (fault !== undefined) throw new Error(`access export: "${scope}": ${fault}`)
+  }
+  return value as Record<string, ScopeAccess>
+}
+
+/**
+ * Access for the settings actually in use. A `config.access` key may name
+ * any scope the workflow gives skills or access to.
+ */
+export const resolveScopeAccess = (
+  def: Pick<WorkflowDefinition, "access" | "configuredAccess" | "skillsOrigin">,
+  skills: Readonly<Record<string, readonly string[]>>,
+  vars: Readonly<Record<string, string>>,
+): Effect.Effect<Record<string, ScopeAccess>, GtdError> =>
+  Effect.gen(function* () {
+    const access = yield* Effect.try({
+      try: () => checkAccessShape(def.access(vars)),
+      catch: (e) => fail(def.skillsOrigin, e instanceof Error ? e.message : String(e)),
+    })
+    const known = [...new Set([...Object.keys(skills), ...Object.keys(access)])]
+    yield* checkKeys(def.configuredAccess, def.skillsOrigin, known, "access")
+    return access
+  })

package/src/workflow/vars.ts

@@ -0,0 +1,33 @@
+const PREFIX = "GTD_"
+
+/**
+ * One kind of setting, later wins: the workflow's own defaults, `--var`
+ * overrides (process settings only; environment settings pass `{}`), then
+ * `GTD_<NAME>` for any name an earlier layer declared (a shell variable never
+ * introduces a name).
+ */
+export const resolveVars = (
+  workflowVars: Readonly<Record<string, string>>,
+  entryVars: Readonly<Record<string, string>>,
+  env: Readonly<Record<string, string | undefined>>,
+): Record<string, string> => {
+  const merged = { ...workflowVars, ...entryVars }
+  for (const name of Object.keys(merged)) {
+    const value = env[PREFIX + name.toUpperCase()]
+    if (value !== undefined) merged[name] = value
+  }
+  return merged
+}
+
+/** The first process setting whose value spans lines — a `Gtd-Var:` trailer cannot carry it. */
+export const multilineSetting = (vars: Readonly<Record<string, string>>): string | undefined =>
+  Object.keys(vars)
+    .sort()
+    .find((name) => /[\r\n]/.test(vars[name]!))
+
+const SETTING_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** A name is written verbatim into a `Gtd-Var: <name>=<value>` trailer, so `=` or a newline would corrupt it. */
+export const isSettingName = (name: string): boolean => SETTING_NAME.test(name)
+
+export const SETTING_NAME_RULE = 'a setting name is a letter or "_", then letters, digits or "_"'

package/src/workflow-kit/health.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest"
+import { escalation, untilSettled } from "./health.js"
+
+describe("escalation", () => {
+  it("describes and stops until `limit` rounds are spent, then reports exhaustion", async () => {
+    const log: string[] = []
+    const steps = {
+      limit: 2,
+      describe: async () => void log.push("describe"),
+      stop: async () => void log.push("stop"),
+      exhausted: async () => void log.push("exhausted"),
+    }
+    const count = { rounds: 0 }
+    for (let i = 0; i < 3; i++) await escalation(count, steps)
+    expect(log).toEqual(["describe", "stop", "describe", "stop", "exhausted"])
+    expect(count.rounds).toBe(2)
+  })
+})
+
+describe("untilSettled", () => {
+  it("reruns while pending and resolves the first run that counts", async () => {
+    const results = [false, false, true]
+    let pending = 2
+    const green = await untilSettled(
+      async () => results.shift()!,
+      () => pending-- > 0,
+    )
+    expect(green).toBe(true)
+  })
+})

package/src/workflow-kit/health.ts

@@ -0,0 +1,86 @@
+import { read, scope } from "../flows/index.js"
+
+/** How many escalation rounds a run of red checks has spent — reset once the suite goes green. */
+export interface EscalationCount {
+  rounds: number
+}
+
+export interface EscalationSteps {
+  /** Rounds a person narrows before `exhausted` replaces them. */
+  readonly limit: number
+  readonly describe: () => Promise<void>
+  readonly stop: () => Promise<void>
+  readonly exhausted: () => Promise<void>
+}
+
+/** Hand a red suite that repeated attempts could not fix to a person, until `limit` rounds are spent. */
+export const escalation = async (count: EscalationCount, steps: EscalationSteps): Promise<void> => {
+  if (count.rounds >= steps.limit) return steps.exhausted()
+  count.rounds++
+  await steps.describe()
+  await steps.stop()
+}
+
+/** Run `check` again while `pending()` holds — a run then does not count — and resolve the first run that does. */
+export const untilSettled = async (
+  check: () => Promise<boolean>,
+  pending: () => boolean,
+): Promise<boolean> => {
+  for (;;) {
+    const green = await check()
+    if (!pending()) return green
+  }
+}
+
+export interface Health {
+  /** One counted run of the suite; resolves `true` when green. */
+  readonly check: () => Promise<boolean>
+  /** Where `check` leaves a red run's output. */
+  readonly report: string
+  readonly fixCap: number
+  readonly fixesSoFar?: number
+  /** Whether two consecutive red reports are the same failure; `true` escalates at once. */
+  readonly sameFailure: (previous: string, current: string) => Promise<boolean>
+  /** Shared with other callers in the same run of red checks. */
+  readonly escalations: EscalationCount
+  readonly escalation: EscalationSteps
+}
+
+// check() stamps the report with the commit it ran at, so equal failures differ there.
+const STAMP = /\n<!-- gtd check [0-9a-f]+ -->\n?$/
+const stripStamp = (text: string): string => text.replace(STAMP, "\n")
+
+/**
+ * Loop until the suite is green: check, and on red run `fix` — escalating
+ * first once `fixCap` fixes are spent, or `sameFailure` calls the failure
+ * identical to the previous round's.
+ */
+export const healthy = async (fix: () => Promise<void>, health: Health): Promise<void> => {
+  let fixes = health.fixesSoFar ?? 0
+  let previous: string | undefined
+  for (;;) {
+    if (await health.check()) {
+      health.escalations.rounds = 0
+      return
+    }
+    const current = stripStamp(read(health.report) ?? "")
+    const stuck = previous !== undefined && (await health.sameFailure(previous, current))
+    previous = current
+    if (stuck || fixes >= health.fixCap) {
+      await escalation(health.escalations, health.escalation)
+      fixes = 0
+    }
+    fixes++
+    await fix()
+  }
+}
+
+/** Hold the process in scope `name` until `passes` resolves `true`, resting at `blocked` between tries. */
+export const gate = (
+  name: string,
+  passes: () => Promise<boolean>,
+  blocked: () => Promise<void>,
+): Promise<void> =>
+  scope(name, async () => {
+    while (!(await passes())) await blocked()
+  })

package/src/workflow-kit/index.ts

@@ -0,0 +1,7 @@
+// Building blocks the shipped workflows share. Policy-free: every skill list,
+// lens, prompt, step, path and threshold arrives as a parameter, so a new
+// workflow composes these without inheriting the shipped one's choices.
+export * from "./health.js"
+export * from "./quality.js"
+export * from "./scenarios.js"
+export * from "./review.js"

package/src/workflow-kit/quality.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest"
+import { lensesOf, lensScopes } from "./quality.js"
+
+describe("lensesOf", () => {
+  it("splits on commas, trims, drops blanks", () => {
+    expect(lensesOf(" a ,, b,")).toEqual(["a", "b"])
+  })
+})
+
+describe("lensScopes", () => {
+  it("keys one entry per lens under the given scope", () => {
+    expect(lensScopes("x.quality", ["a", "b"], (lens) => [lens])).toEqual({
+      "x.quality.a": ["a"],
+      "x.quality.b": ["b"],
+    })
+  })
+})

package/src/workflow-kit/quality.ts

@@ -0,0 +1,45 @@
+import { read } from "../flows/index.js"
+
+/** Split a comma-separated lens list: trimmed, blanks dropped. */
+export const lensesOf = (value: string): readonly string[] =>
+  value
+    .split(",")
+    .map((lens) => lens.trim())
+    .filter((lens) => lens.length > 0)
+
+/** One `<scope>.<lens>` entry per lens — the per-lens part of a skills or access export. */
+export const lensScopes = <T>(
+  scope: string,
+  lenses: readonly string[],
+  entry: (lens: string) => T,
+): Record<string, T> => Object.fromEntries(lenses.map((lens) => [`${scope}.${lens}`, entry(lens)]))
+
+/** One `review` turn per lens, each appending its findings to `findings`; resolves `"findings"` when that file has any. */
+export const qualityLap = async (
+  lenses: readonly string[],
+  review: (lens: string) => Promise<void>,
+  findings: string,
+): Promise<"clean" | "findings"> => {
+  for (const lens of lenses) await review(lens)
+  return (read(findings) ?? "").length > 0 ? "findings" : "clean"
+}
+
+export interface FindingsFix {
+  /** One fix turn; it removes `findings` once every finding is resolved. */
+  readonly fix: () => Promise<void>
+  readonly findings: string
+  readonly cap: number
+  /** Runs once `cap` turns left findings. */
+  readonly escalate: () => Promise<void>
+}
+
+/** Resolves `true` once `findings` is gone, `false` when `cap` turns escalated instead. */
+export const fixFindings = async (f: FindingsFix): Promise<boolean> => {
+  for (let turns = 0; turns < f.cap; turns++) {
+    await f.fix()
+    // Not `changes()`: a wording gate after the fix would be the last step.
+    if (read(f.findings) === undefined) return true
+  }
+  await f.escalate()
+  return false
+}