@pmelab/gtd 23.2.0 → 24.1.0

package/src/edge/index.ts

@@ -0,0 +1,16 @@
+export {
+  currentRun,
+  summaryRun,
+  restAt,
+  currentRest,
+  startRefusal,
+  reviewBaseFor,
+  type RenderedRest,
+  renderRest,
+  stalledAt,
+  noProcessUnderway,
+  restIsIdle,
+  previewLanding,
+  snapshotFromRest,
+  summaryFor,
+} from "./Edge.js"

package/src/emit/Emit.test.ts

@@ -0,0 +1,425 @@
+import { execFileSync, execSync, spawnSync } from "node:child_process"
+import { existsSync, mkdtempSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+import {
+  binaryGuard,
+  combinedScript,
+  DID_NOT_RUN_COMMENT,
+  emitScripts,
+  extractLeadingBinary,
+  fileExistsGuard,
+  type EmitStep,
+} from "./Emit.js"
+import { commitOutcome, noteOutcome } from "./index.js"
+
+/**
+ * `sh -n` (POSIX syntax check), not `bash -n` — a script that only passes
+ * under `bash -n` could still be using a bashism `dash` rejects (`local`,
+ * `$RANDOM`, `$'...'`, process substitution, …), which is exactly the class
+ * of bug this port is fixing. `sh` on this machine is a real POSIX shell, so
+ * a pass here is evidence the emitted script is portable, not just
+ * bash-flavored.
+ */
+const runShCheckSyntax = (script: string): number => {
+  try {
+    execFileSync("sh", ["-n"], { input: script })
+    return 0
+  } catch (error) {
+    return (error as { status?: number }).status ?? 1
+  }
+}
+
+describe("emitScripts — empty inputs", () => {
+  it("is the empty string when both halves are omitted", () => {
+    const { required, optional } = emitScripts()
+    expect(required).toBe("")
+    expect(optional).toBe("")
+  })
+
+  it("is the empty string when both halves are explicitly []", () => {
+    const { required, optional } = emitScripts([], [])
+    expect(required).toBe("")
+    expect(optional).toBe("")
+  })
+})
+
+describe("emitScripts — required only", () => {
+  const steps: ReadonlyArray<EmitStep> = [
+    { kind: "gitWrite", command: "git commit --allow-empty -m 'gtd(agent): x'" },
+  ]
+  const { required, optional } = emitScripts(steps)
+
+  it("leaves optional empty", () => {
+    expect(optional).toBe("")
+  })
+
+  it("begins with set -eu as the literal first line", () => {
+    expect(required.split("\n")[0]).toBe("set -eu")
+  })
+
+  it("carries no precondition guard — the script is exactly set -eu plus its steps", () => {
+    expect(required).not.toContain("git rev-parse")
+    expect(required.split("\n\n")).toEqual([
+      "set -eu",
+      "git commit --allow-empty -m 'gtd(agent): x'",
+    ])
+  })
+
+  it("is syntactically valid POSIX sh", () => {
+    expect(runShCheckSyntax(required)).toBe(0)
+  })
+})
+
+describe("emitScripts — both halves populated", () => {
+  const required: ReadonlyArray<EmitStep> = [
+    { kind: "gitWrite", command: "git commit --allow-empty -m 'gtd(agent): x'" },
+  ]
+  const optional: ReadonlyArray<EmitStep> = [
+    { kind: "command", command: "some-format-command --check FEEDBACK.md" },
+  ]
+  const result = emitScripts(required, optional)
+
+  it("both halves are non-empty", () => {
+    expect(result.required).not.toBe("")
+    expect(result.optional).not.toBe("")
+  })
+
+  it("both halves independently begin with set -eu", () => {
+    expect(result.required.split("\n")[0]).toBe("set -eu")
+    expect(result.optional.split("\n")[0]).toBe("set -eu")
+  })
+
+  it("both halves are syntactically valid POSIX sh", () => {
+    expect(runShCheckSyntax(result.required)).toBe(0)
+    expect(runShCheckSyntax(result.optional)).toBe(0)
+  })
+
+  it("a plain command step is emitted verbatim", () => {
+    expect(result.optional).toContain("some-format-command --check FEEDBACK.md")
+  })
+
+  it("a gitWrite step is emitted verbatim — no wrapper, so a failing git write fails in the user's shell", () => {
+    expect(result.required).toContain("git commit --allow-empty -m 'gtd(agent): x'")
+  })
+})
+
+describe("emitScripts — outcome steps", () => {
+  it("renders an outcome step verbatim — no preamble, the step carries its own printf", () => {
+    const { required } = emitScripts([{ kind: "outcome", command: commitOutcome("gtd(agent): x") }])
+    expect(required).toContain(commitOutcome("gtd(agent): x"))
+    expect(required.split("\n\n").length).toBe(2)
+  })
+
+  it("is syntactically valid POSIX sh", () => {
+    const { required } = emitScripts([
+      { kind: "outcome", command: noteOutcome('nothing to do at "idle"') },
+    ])
+    expect(runShCheckSyntax(required)).toBe(0)
+  })
+})
+
+describe("emitScripts — POSIX sh portability of the emitted output", () => {
+  const steps: ReadonlyArray<EmitStep> = [
+    { kind: "gitWrite", command: "git commit --allow-empty -m 'gtd(agent): x'" },
+    { kind: "outcome", command: commitOutcome("gtd(agent): x") },
+  ]
+  const { required } = emitScripts(steps)
+
+  it("never contains 'pipefail'", () => {
+    expect(required).not.toContain("pipefail")
+  })
+
+  it("never contains 'RANDOM'", () => {
+    expect(required).not.toContain("RANDOM")
+  })
+
+  it("contains no ' local ' token", () => {
+    expect(required).not.toContain(" local ")
+  })
+})
+
+describe("fileExistsGuard", () => {
+  it("renders a plain OR-list test, never an if/fi block", () => {
+    expect(fileExistsGuard(".gtd/REVIEW.md")).toBe(`[ -f '.gtd/REVIEW.md' ] || exit 0`)
+  })
+
+  it("shell-quotes a file path containing a single quote", () => {
+    expect(fileExistsGuard("it's.md")).toBe(`[ -f 'it'\\''s.md' ] || exit 0`)
+  })
+
+  it("is syntactically valid POSIX sh on its own", () => {
+    expect(runShCheckSyntax(fileExistsGuard(".gtd/REVIEW.md"))).toBe(0)
+  })
+
+  it("exits 0 (not 1) when the guard trips — a missing steering file is not a failure", () => {
+    const result = spawnSync("sh", ["-c", fileExistsGuard("/no/such/file-for-sure")])
+    expect(result.status).toBe(0)
+  })
+})
+
+describe("extractLeadingBinary", () => {
+  it("returns the leading word of a plain command", () => {
+    expect(extractLeadingBinary("adr-lint docs/adr.md")).toBe("adr-lint")
+  })
+
+  it("returns the whole command when it is a single bare word", () => {
+    expect(extractLeadingBinary("true")).toBe("true")
+  })
+
+  it("returns undefined for a VAR=x-prefixed command", () => {
+    expect(extractLeadingBinary("FOO=1 some-tool docs/adr.md")).toBeUndefined()
+  })
+
+  it("returns undefined for a pipeline", () => {
+    expect(extractLeadingBinary("cat docs/adr.md | grep -q Decision")).toBeUndefined()
+  })
+
+  it("returns undefined for a subshell", () => {
+    expect(extractLeadingBinary("(cd docs && adr-lint adr.md)")).toBeUndefined()
+  })
+
+  it("returns undefined for a multi-line command", () => {
+    expect(extractLeadingBinary("adr-lint docs/adr.md\necho done")).toBeUndefined()
+  })
+
+  it("returns undefined for a leading word spelled with characters outside [A-Za-z0-9_./-]", () => {
+    expect(extractLeadingBinary("$(which adr-lint) docs/adr.md")).toBeUndefined()
+  })
+})
+
+describe("binaryGuard", () => {
+  it("renders a command -v probe naming the mode, key, and binary, exiting 127", () => {
+    expect(binaryGuard("adr-lint", "adr", "validate")).toBe(
+      [
+        `command -v 'adr-lint' >/dev/null 2>&1 || {`,
+        `  printf '%s\\n%s\\n' 'gtd: mode "adr": "validate" command not found: adr-lint' '$PATH: '"$PATH"`,
+        `  exit 127`,
+        `}`,
+      ].join("\n"),
+    )
+  })
+
+  it("is syntactically valid POSIX sh", () => {
+    expect(runShCheckSyntax(binaryGuard("adr-lint", "adr", "validate"))).toBe(0)
+  })
+
+  it("$PATH is expanded by the driver's shell, never resolved in-process — a literal '$PATH: ' label plus a double-quoted $PATH survive in the rendered text", () => {
+    expect(binaryGuard("adr-lint", "adr", "validate")).toContain(`'$PATH: '"$PATH"`)
+  })
+
+  it("exits 0 (not 127) when the named binary IS on PATH", () => {
+    const result = spawnSync("sh", ["-c", binaryGuard("true", "adr", "validate")])
+    expect(result.status).toBe(0)
+  })
+
+  it("exits 127 and names the binary plus the resolved $PATH when it is NOT on PATH", () => {
+    const result = spawnSync(
+      "/bin/sh",
+      ["-c", binaryGuard("gtd-nonexistent-tool", "adr", "validate")],
+      {
+        encoding: "utf8",
+        env: { ...process.env, PATH: "/no/such/dir" },
+      },
+    )
+    expect(result.status).toBe(127)
+    expect(result.stdout).toContain(
+      'gtd: mode "adr": "validate" command not found: gtd-nonexistent-tool',
+    )
+    expect(result.stdout).toContain("$PATH: /no/such/dir")
+  })
+})
+
+describe("emitScripts — a command step with onFailure", () => {
+  const initRepo = (): string => {
+    const dir = mkdtempSync(join(tmpdir(), "emit-onfailure-repo-"))
+    execFileSync("git", ["init", "-q"], { cwd: dir })
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: dir })
+    execFileSync("git", ["config", "user.name", "Test"], { cwd: dir })
+    execFileSync("git", ["config", "commit.gpgsign", "false"], { cwd: dir })
+    execFileSync("git", ["commit", "--allow-empty", "-q", "-m", "initial"], { cwd: dir })
+    return dir
+  }
+  const runIn = (dir: string, script: string): { status: number; output: string } => {
+    try {
+      const output = execSync("sh", { input: script, cwd: dir, encoding: "utf8" })
+      return { status: 0, output }
+    } catch (error) {
+      const e = error as { status?: number; stdout?: string }
+      return { status: e.status ?? 1, output: e.stdout ?? "" }
+    }
+  }
+
+  it("is syntactically valid POSIX sh", () => {
+    const steps: ReadonlyArray<EmitStep> = [
+      { kind: "command", command: "true", onFailure: "fix it" },
+    ]
+    const { required } = emitScripts(steps)
+    expect(runShCheckSyntax(required)).toBe(0)
+  })
+
+  it("a succeeding wrapped command exits 0 and prints nothing of its own", () => {
+    const dir = initRepo()
+    const steps: ReadonlyArray<EmitStep> = [
+      { kind: "command", command: "true", onFailure: "fix it" },
+    ]
+    const { required } = emitScripts(steps)
+    const { status, output } = runIn(dir, required)
+    expect(status).toBe(0)
+    expect(output).toBe("")
+  })
+
+  it("a failing command prints the instruction, a blank line, then its combined output, and exits with its own code", () => {
+    const dir = initRepo()
+    const steps: ReadonlyArray<EmitStep> = [
+      {
+        kind: "command",
+        command: "echo boom >&2; exit 3",
+        onFailure: "Fix this violation",
+      },
+    ]
+    const { required } = emitScripts(steps)
+    const { status, output } = runIn(dir, required)
+    expect(status).toBe(3)
+    expect(output).toBe("Fix this violation\n\nboom\n")
+  })
+
+  it("a multi-line inner command round-trips through the { … } group", () => {
+    const dir = initRepo()
+    const steps: ReadonlyArray<EmitStep> = [
+      {
+        kind: "command",
+        command: "echo line1 >&2\necho line2 >&2\nexit 5",
+        onFailure: "Fix multi",
+      },
+    ]
+    const { required } = emitScripts(steps)
+    const { status, output } = runIn(dir, required)
+    expect(status).toBe(5)
+    expect(output).toBe("Fix multi\n\nline1\nline2\n")
+  })
+
+  it("a command step without onFailure is still emitted verbatim", () => {
+    const steps: ReadonlyArray<EmitStep> = [{ kind: "command", command: "some-command --flag" }]
+    const { required } = emitScripts(steps)
+    expect(required).toContain("some-command --flag")
+    expect(required).not.toContain("gtd_validate_status")
+  })
+})
+
+describe("real repo — an assembled script end to end", () => {
+  const initRepo = (): string => {
+    const dir = mkdtempSync(join(tmpdir(), "emit-realrepo-"))
+    execFileSync("git", ["init", "-q"], { cwd: dir })
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: dir })
+    execFileSync("git", ["config", "user.name", "Test"], { cwd: dir })
+    execFileSync("git", ["config", "commit.gpgsign", "false"], { cwd: dir })
+    execFileSync("git", ["commit", "--allow-empty", "-q", "-m", "initial"], { cwd: dir })
+    return dir
+  }
+
+  const commitCount = (dir: string): number =>
+    Number(
+      execFileSync("git", ["rev-list", "--count", "HEAD"], { cwd: dir, encoding: "utf8" }).trim(),
+    )
+
+  it("the git command actually lands", () => {
+    const dir = initRepo()
+    const before = commitCount(dir)
+    const { required } = emitScripts([
+      { kind: "gitWrite", command: "git commit --allow-empty -m 'gtd(agent): landed'" },
+    ])
+    execSync("sh", { input: required, cwd: dir })
+    expect(commitCount(dir)).toBe(before + 1)
+    expect(
+      execFileSync("git", ["log", "-1", "--pretty=%s"], { cwd: dir, encoding: "utf8" }).trim(),
+    ).toBe("gtd(agent): landed")
+  })
+
+  it("a failing git write aborts the script non-zero, leaving later steps unrun", () => {
+    const dir = initRepo()
+    const before = commitCount(dir)
+    const { required } = emitScripts([
+      { kind: "gitWrite", command: "git commit --allow-empty -m 'x' --this-flag-does-not-exist" },
+      { kind: "command", command: "touch later-step-ran" },
+    ])
+    let status = 0
+    try {
+      execSync("sh", { input: required, cwd: dir, stdio: ["pipe", "pipe", "pipe"] })
+    } catch (error) {
+      status = (error as { status?: number }).status ?? 1
+    }
+    expect(status).not.toBe(0)
+    expect(commitCount(dir)).toBe(before)
+    expect(existsSync(join(dir, "later-step-ran"))).toBe(false)
+  })
+})
+
+describe("combinedScript — the plain-text write commands' single pasteable script", () => {
+  it("DID_NOT_RUN_COMMENT points the reader at sh, not bash", () => {
+    expect(DID_NOT_RUN_COMMENT).toBe(
+      "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn",
+    )
+    expect(DID_NOT_RUN_COMMENT).not.toContain("bash")
+  })
+
+  it("is the empty string when required is empty", () => {
+    expect(combinedScript("", "")).toBe("")
+    expect(combinedScript("", "echo optional")).toBe("")
+  })
+
+  it("prepends the leading 'did not run it' comment ahead of required, with no optional block", () => {
+    const script = combinedScript("echo required", "")
+    expect(script.startsWith("# gtd emitted this and did NOT run it")).toBe(true)
+    expect(script).toContain("echo required")
+    expect(script).not.toContain("presentation-only follow-up failed")
+    expect(runShCheckSyntax(script)).toBe(0)
+  })
+
+  it("wraps a non-empty optional in a subshell that never fails the whole script", () => {
+    const script = combinedScript("echo required", "echo optional")
+    expect(script.startsWith("# gtd emitted this and did NOT run it")).toBe(true)
+    expect(script).toContain("echo required")
+    expect(script).toContain("(\necho optional\n) || printf")
+    expect(script).toContain("presentation-only follow-up failed — continuing")
+    expect(runShCheckSyntax(script)).toBe(0)
+  })
+
+  it("the presentation-only failure warning prints via printf, not echo, and its wording is stable", () => {
+    const script = combinedScript("echo required", "echo optional")
+    expect(script).toContain("printf 'gtd: presentation-only follow-up failed — continuing\\n' >&2")
+    expect(script).not.toMatch(/echo\s+["']?gtd: presentation-only/)
+  })
+
+  it("required runs before optional, and a failing required aborts before optional runs", () => {
+    const dir = mkdtempSync(join(tmpdir(), "emit-combined-"))
+    const script = combinedScript("exit 1", "touch optional-ran")
+    let status = 0
+    try {
+      execSync("sh", { input: script, cwd: dir, stdio: ["pipe", "pipe", "pipe"] })
+    } catch (error) {
+      status = (error as { status?: number }).status ?? 1
+    }
+    expect(status).not.toBe(0)
+    expect(existsSync(join(dir, "optional-ran"))).toBe(false)
+  })
+
+  it("a failing optional is swallowed — the whole script still exits 0", () => {
+    const dir = mkdtempSync(join(tmpdir(), "emit-combined-"))
+    const script = combinedScript("touch required-ran", "exit 1")
+    // stderr piped, not inherited: the optional half's own failure warning is
+    // the point of this case, and must not leak into the test run's output.
+    execSync("sh", { input: script, cwd: dir, stdio: ["pipe", "pipe", "pipe"] })
+    expect(existsSync(join(dir, "required-ran"))).toBe(true)
+  })
+
+  it("the discarded-optional-failure warning lands on stderr, never stdout — this channel's own shape, pinned alongside Commentary.test.ts", () => {
+    const dir = mkdtempSync(join(tmpdir(), "emit-combined-"))
+    const script = combinedScript("touch required-ran", "exit 1")
+    const result = spawnSync("sh", [], { input: script, cwd: dir, encoding: "utf8" })
+    expect(result.status).toBe(0)
+    expect(result.stderr).toContain("gtd: presentation-only follow-up failed — continuing")
+    expect(result.stdout).not.toContain("gtd: presentation-only follow-up failed")
+  })
+})

package/src/emit/Emit.ts

@@ -0,0 +1,139 @@
+import { shellQuote } from "./GitScript.js"
+
+export interface EmittedScripts {
+  readonly required: string
+  readonly optional: string
+}
+
+/**
+ * Every kind renders its `command` verbatim (the one exception is a
+ * `command` step carrying an `onFailure` prompt); the discriminant records
+ * WHAT a step is, and nothing else. A failing git write is left to fail in
+ * the user's shell — gtd never writes git itself, so there is nothing to
+ * retry on its behalf — and an `outcome` step carries its own complete
+ * `printf`, so no shared preamble is emitted for it either.
+ */
+export type EmitStep =
+  | { readonly kind: "gitWrite"; readonly command: string }
+  | {
+      readonly kind: "command"
+      readonly command: string
+      /**
+       * Prompt text printed (with the command's captured output) on a
+       * non-zero exit before propagating that exit code. Omitted for a step
+       * that should fail raw — e.g. a `format:` command's own broken-tooling
+       * failure, which an agent can't fix by editing the steering file.
+       */
+      readonly onFailure?: string
+    }
+  | { readonly kind: "outcome"; readonly command: string }
+
+/** Exits 0 when the declared steering file is absent — nothing to format or validate yet. An OR list, not `if`: its left side failing never trips `set -e`. */
+export const fileExistsGuard = (file: string): string => `[ -f ${shellQuote(file)} ] || exit 0`
+
+/** A mode or `ui.format` command finds the file it works on in `$GTD_FILE`. */
+export const withFileVar = (command: string, file: string): string =>
+  `export GTD_FILE=${shellQuote(file)}\n${command}`
+
+const SIMPLE_LEADING_WORD_RE = /^[A-Za-z0-9_./-]+(?=[ \t]|$)/
+const SHELL_METACHARACTER_RE = /[|&;$<>(){}`]/
+// The file variable is an argument, never a second command.
+const FILE_VAR_RE = /"\$GTD_FILE"|"\$\{GTD_FILE\}"|\$GTD_FILE\b|\$\{GTD_FILE\}/g
+
+/** `command` with `file` written in for `$GTD_FILE` — one line an agent can copy, equivalent to running it under `withFileVar`. */
+export const commandForFile = (command: string, file: string): string =>
+  command.replace(FILE_VAR_RE, shellQuote(file))
+
+/**
+ * The leading word of a rendered `format:`/`validate:` command, when the
+ * command has exactly one unambiguous binary to probe — `undefined` for
+ * anything a shell metacharacter could hide a second command behind. A missing
+ * guard degrades to a raw exit; a wrong guard would refuse a working command.
+ */
+export const extractLeadingBinary = (command: string): string | undefined => {
+  if (command.includes("\n")) return undefined
+  if (SHELL_METACHARACTER_RE.test(command.replace(FILE_VAR_RE, ""))) return undefined
+  const match = SIMPLE_LEADING_WORD_RE.exec(command)
+  return match === null ? undefined : match[0]
+}
+
+/**
+ * Names a typo'd or uninstalled binary and the `$PATH` it was looked up on.
+ * `$PATH` is a shell word the DRIVER's shell expands at run time, so gtd never
+ * resolves it in-process. Exits 127, matching bash's "command not found".
+ */
+export const binaryGuard = (binary: string, mode: string, key: "format" | "validate"): string => {
+  const messageQ = shellQuote(`gtd: mode "${mode}": "${key}" command not found: ${binary}`)
+  return [
+    `command -v ${shellQuote(binary)} >/dev/null 2>&1 || {`,
+    `  printf '%s\\n%s\\n' ${messageQ} '$PATH: '"$PATH"`,
+    `  exit 127`,
+    `}`,
+  ].join("\n")
+}
+
+/**
+ * Prints `prompt` plus the captured output on a non-zero exit, then propagates
+ * it. The `{ … }` group inlines a multi-line `command` verbatim; the
+ * assignment sits left of `||` so `set -e` never trips on the failure itself.
+ */
+export const failurePromptWrapper = (command: string, prompt: string): string => {
+  const promptQ = shellQuote(prompt)
+  return [
+    `gtd_validate_status=0`,
+    `gtd_validate_out="$( {`,
+    command,
+    `} 2>&1 )" || gtd_validate_status=$?`,
+    `if [ "$gtd_validate_status" -ne 0 ]; then`,
+    `  printf '%s\\n\\n%s\\n' ${promptQ} "$gtd_validate_out"`,
+    `  exit "$gtd_validate_status"`,
+    `fi`,
+  ].join("\n")
+}
+
+const renderStep = (step: EmitStep): string => {
+  if (step.kind === "command" && step.onFailure !== undefined) {
+    return failurePromptWrapper(step.command, step.onFailure)
+  }
+  return step.command
+}
+
+const assembleScript = (steps: ReadonlyArray<EmitStep>): string =>
+  steps.length === 0 ? "" : ["set -eu", ...steps.map(renderStep)].join("\n\n")
+
+/** Build both halves from already-rendered command strings; an empty (or omitted) array produces the empty-string result, so a driver checking `if [ -n "$required" ]` never has to special-case a bare preamble. */
+export const emitScripts = (
+  required: ReadonlyArray<EmitStep> = [],
+  optional: ReadonlyArray<EmitStep> = [],
+): EmittedScripts => ({
+  required: assembleScript(required),
+  optional: assembleScript(optional),
+})
+
+/** Exported so `src/testkit/EmittedScriptRecognizer.ts` can recognize these by exact string comparison. `printf`, not `echo`, avoids shell-specific backslash-escape quirks. */
+export const DID_NOT_RUN_COMMENT =
+  "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn"
+
+export const PRESENTATION_ONLY_COMMENT = "# presentation only — safe to skip"
+
+export const PRESENTATION_FAILURE_WARNING =
+  "printf 'gtd: presentation-only follow-up failed — continuing\\n' >&2"
+
+/**
+ * A write command's single pasteable script (`gtd abandon | sh`,
+ * `gtd land --json=script`'s own field). `optional`, when non-empty, is
+ * wrapped in a subshell whose failure is swallowed — presentation-only, so it
+ * must never turn a landed turn into a non-zero exit.
+ */
+export const combinedScript = (required: string, optional: string): string => {
+  if (required.length === 0) return ""
+  if (optional.length === 0) return `${DID_NOT_RUN_COMMENT}\n\n${required}`
+  return [
+    DID_NOT_RUN_COMMENT,
+    "",
+    required,
+    "",
+    PRESENTATION_ONLY_COMMENT,
+    `(\n${optional}\n) || ${PRESENTATION_FAILURE_WARNING}`,
+  ].join("\n")
+}