omakit 0.1.0

package/tools/marketplace/usage.mjs

@@ -0,0 +1,191 @@
+// The help text, as data rather than one painted string.
+//
+// Kept as structure so it can be coloured without pattern-matching a paragraph,
+// and so the same words serve a terminal and a pipe. A signature is coloured by
+// token: what you type is cyan, what you replace is yellow, the brackets that
+// merely group them stay out of the way.
+
+import { UNAUTHENTICATED_LIMIT } from "./github.mjs"
+import { MARKETPLACE_PIN } from "./pin.mjs"
+import { colourEnabled, paintProse, STEP, styler } from "./style.mjs"
+
+/**
+ * "Safe" means one thing, everywhere it appears: this runs on your own
+ * machine, posts nothing, opens no issue and spends nobody's attention. It is
+ * never a claim about the security of a plugin or a submission; the baseline's
+ * outcome is reported verbatim and is never restated as one.
+ */
+export const TAGLINE = "the safe place to find out"
+
+/** The shells `omakit setup` installs tab completion for; completion.mjs holds the scripts. */
+export const COMPLETION_SHELLS = Object.freeze(["bash", "zsh", "fish"])
+
+export const COMMANDS = Object.freeze([
+  {
+    signature: "omakit setup",
+    lines: [
+      "First run, in one command: check the environment, fetch the pinned",
+      "marketplace checkout, and say what to try first. Idempotent.",
+    ],
+  },
+  {
+    signature: "omakit pin",
+    lines: [
+      "Fetch or verify the pinned marketplace checkout in the user cache:",
+      "$XDG_CACHE_HOME/omakit/marketplace, or ~/.cache/omakit/marketplace.",
+      `Read-only, exact commit ${MARKETPLACE_PIN.commit}.`,
+    ],
+  },
+  {
+    signature: [
+      "omakit submit <target> --category <c> --tags <a,b> [--notes <text>]",
+      "                      [--suggest-tag <t>] [--name <n>] [--offline]",
+      "                      [--allow-dirty] [--json] [--out <file>]",
+    ],
+    lines: [
+      "Every check that is knowable before submitting, the resolved commit, and",
+      "the exact issue title and body. Prints them. Never posts anything.",
+    ],
+  },
+  {
+    signature: "omakit watch <issue-url> [--json]",
+    lines: [
+      "Compare the commit the marketplace validated on a submission issue with",
+      "the plugin repository's current default-branch HEAD, and say what makes",
+      "it validate a newer one. Read-only.",
+    ],
+  },
+  {
+    signature: "omakit verify <target> [--allow-dirty] [--out <file>]",
+    lines: [
+      "The official marketplace security baseline over the local Git transport,",
+      "reported verbatim beside the pin identity.",
+    ],
+  },
+  {
+    signature: "omakit help --agent",
+    lines: [
+      "The operating instructions for a coding agent, printed from skills/, so an",
+      "agent can read the contract out of the tool instead of the repository.",
+    ],
+  },
+  {
+    signature: "omakit upgrade [--dry-run]",
+    lines: [
+      "Fast-forward this checkout of omakit itself. Refuses a dirty tree, an",
+      "unexpected remote and anything that is not a fast-forward. Never moves",
+      "the marketplace pin.",
+    ],
+  },
+  {
+    signature: "omakit doctor [--offline] [--json]",
+    lines: [
+      "What is installed, what is pinned, and what has moved since. Reads and",
+      "prints; it installs nothing and never moves the pin.",
+    ],
+  },
+  {
+    signature: "omakit parity [--count <n>] [--offset <n>] [--out <file>]",
+    lines: [
+      "The official baseline over GitHub versus the local transport on real",
+      "listed repositories; a packaged install requires --out for evidence.",
+    ],
+  },
+])
+
+// A command sits one STEP in from the heading; what it does sits one STEP in
+// from the command's name, which starts after "omakit ".
+const INDENT = " ".repeat(STEP)
+const DESCRIPTION = " ".repeat(STEP * 3)
+
+export const TARGET_NOTE = "<target> is a local Git repository path, or <https url>@<40-char sha>."
+
+/**
+ * The answer to "what do I have to set up?" is "nothing", and it is said in
+ * so many words. There is no environment section because omakit reads no
+ * credential variable of its own: `gh` is the one credential source and honours
+ * GH_TOKEN and GITHUB_TOKEN itself, the pin follows XDG unless explicitly overridden, and
+ * the terminal's own conventions (a pipe, TERM=dumb, NO_COLOR) are what turn
+ * colour and motion off.
+ */
+export const AUTHENTICATION = Object.freeze([
+  "Read-only, and optional. omakit uses your `gh` login if you have one, and",
+  "otherwise goes unauthenticated. `submit` and `verify` need no network at",
+  `all; \`watch\` and \`parity\` are capped at ${UNAUTHENTICATED_LIMIT} requests an hour without a`,
+  "login. omakit never writes a credential anywhere.",
+])
+
+/**
+ * Colour a signature by token: what you type is cyan, what you replace is
+ * yellow, the subcommand is bold because that is the word you are scanning for,
+ * and the brackets that merely group things stay out of the way.
+ *
+ * One pass, deliberately. Two passes would let the second one find the escape
+ * sequences the first inserted and colour the `[` inside them, which corrupts
+ * every sequence downstream of it.
+ */
+const TOKEN = /(^\s*omakit +[a-z][a-z-]*)|(<[^>]+>)|(--[a-z-]+)|(\bomakit\b)|(\b[a-z]+(?:\|[a-z]+)+\b)|([[\]])/g
+
+export function paintSignature(signature, c) {
+  return signature.replace(TOKEN, (token, lead, placeholder, flag, bare, choice, bracket) => {
+    if (lead) {
+      const [, indent, name, gap, subcommand] = lead.match(/^(\s*)(omakit)( +)([a-z][a-z-]*)$/)
+      return `${indent}${c("typeable.bold", name)}${gap}${c("name", subcommand)}`
+    }
+    if (placeholder) return c("placeholder", placeholder)
+    if (flag) return c("typeable", flag)
+    if (bare) return c("typeable.bold", bare)
+    // A choice like bash|zsh|fish: each word is one you could type, and the
+    // bar between them is grouping.
+    if (choice) return choice.split("|").map((word) => c("typeable", word)).join(c("punctuation", "|"))
+    return c("punctuation", bracket)
+  })
+}
+
+/**
+ * The front door: the commands and nothing else.
+ *
+ * The measured reason this exists. The full reference is 53 lines and a
+ * terminal is not 60 rows tall, so a bare `omakit` scrolled its own first
+ * lines off the top of the screen before anyone could read them. A list of
+ * what you can run fits, and the reference is one command away.
+ *
+ * @param {{ colour?: boolean, heading?: boolean }} [options]
+ */
+export function renderSummary({ colour = colourEnabled(), heading = true } = {}) {
+  const c = styler(colour)
+  const out = heading ? [`${c("typeable.bold", "omakit")}${c("punctuation", ":")} ${TAGLINE}`, ""] : []
+  for (const command of COMMANDS) {
+    out.push(`${INDENT}${paintSignature([].concat(command.signature)[0], c)}`)
+  }
+  out.push("")
+  out.push(`${INDENT}${paintProse("`omakit help` is the same list with what each command does, and", c)}`)
+  out.push(`${INDENT}${paintProse("what it reads. `omakit setup` is the one to run first.", c)}`)
+  return `${out.join("\n")}\n`
+}
+
+/**
+ * @param {{ colour?: boolean, heading?: boolean }} [options] `heading: false`
+ *   when the line above has already named the tool, as under an unknown
+ *   command, so the same sentence is not printed twice.
+ */
+export function renderUsage({ colour = colourEnabled(), heading = true } = {}) {
+  const c = styler(colour)
+  const out = heading ? [`${c("typeable.bold", "omakit")}${c("punctuation", ":")} ${TAGLINE}`, ""] : []
+
+  for (const command of COMMANDS) {
+    for (const line of [].concat(command.signature)) {
+      out.push(`${INDENT}${paintSignature(line, c)}`)
+    }
+    for (const line of command.lines) {
+      out.push(`${DESCRIPTION}${paintProse(line, c)}`)
+    }
+    out.push("")
+  }
+
+  out.push(`${INDENT}${paintSignature(TARGET_NOTE, c)}`)
+  out.push("")
+  out.push(c("heading", "GitHub access:"))
+  for (const line of AUTHENTICATION) out.push(`${INDENT}${paintProse(line, c)}`)
+  return `${out.join("\n")}\n`
+}

package/tools/marketplace/verify.mjs

@@ -0,0 +1,70 @@
+// `omakit verify <target>`: the pinned official baseline over the local Git
+// transport, reported verbatim beside the pin identity. `omakit submit` builds on
+// this; `verify` exists on its own so the raw official result can be inspected
+// without any Omakit check around it.
+import { runBaseline } from "./run-baseline.mjs"
+import { MARKETPLACE_PIN } from "./pin.mjs"
+import { ASSUMED_BY_ADAPTER } from "./local-transport.mjs"
+
+const MARKETPLACE_STATEMENT =
+  "Official baseline preview over a local snapshot. The marketplace rescans the public commit itself. This is not approval, listing, verification or a security audit."
+
+/**
+ * @param {{ repoRoot: string, subject: { dir: string, commit: string, repository: { url: string|null } }, listedPlugins?: Array }} options
+ * @returns the `marketplaceBaseline` section: pin, transport, adapter
+ *   assumptions, the official result verbatim, and the statement.
+ */
+export async function marketplaceBaselineSection({ repoRoot, subject, listedPlugins }) {
+  const pin = {
+    repository: MARKETPLACE_PIN.repository,
+    commit: MARKETPLACE_PIN.commit,
+    baselineVersion: MARKETPLACE_PIN.baselineVersion,
+    enforcementMode: MARKETPLACE_PIN.enforcementMode,
+  }
+  if (!subject.repository.url) {
+    return {
+      pin,
+      transport: "none",
+      assumedByAdapter: [],
+      invoked: false,
+      skipReason: "no declared GitHub repository URL",
+      official: null,
+      statement: MARKETPLACE_STATEMENT,
+    }
+  }
+  let run
+  try {
+    run = await runBaseline({
+      repoRoot,
+      repoUrl: subject.repository.url,
+      commitSha: subject.commit,
+      transport: "local",
+      repoDir: subject.dir,
+      listedPlugins,
+    })
+  } catch (error) {
+    if (error && typeof error.code === "string" && error.code.startsWith("security-baseline-")) {
+      // The official code refused the snapshot (scan limit, unreadable file):
+      // that refusal is the official result and is reported verbatim.
+      return {
+        pin,
+        transport: "local-git",
+        assumedByAdapter: [...ASSUMED_BY_ADAPTER],
+        invoked: true,
+        skipReason: null,
+        official: { error: { code: error.code, message: error.message, ...(error.details || {}) } },
+        statement: MARKETPLACE_STATEMENT,
+      }
+    }
+    throw error
+  }
+  return {
+    pin: { ...pin, commit: run.pin.commit, baselineVersion: run.pin.baselineVersion, enforcementMode: run.pin.enforcementMode },
+    transport: "local-git",
+    assumedByAdapter: [...run.adapter.assumedByAdapter],
+    invoked: true,
+    skipReason: null,
+    official: run.result,
+    statement: MARKETPLACE_STATEMENT,
+  }
+}

package/tools/marketplace/watch.mjs

@@ -0,0 +1,262 @@
+// The validation watch. This is the reason the tool exists.
+//
+// The marketplace validates one exact commit, and the review that follows is
+// of that commit. The only action that makes it validate a newer one is
+// editing the issue body:
+// `route-issue-automation.yml` is the only workflow with a direct `issues`
+// trigger (`opened, edited, reopened, labeled, unlabeled`), there is no
+// `issue_comment` trigger anywhere in the marketplace, and `refresh-catalog.yml`
+// compares branch HEADs only for repositories that are already listed. So
+// pushing a fix does nothing, and commenting "fixed in abc123" does nothing.
+//
+// Measured reason (docs/MEASUREMENTS.md M6): of the 464 submissions parked in
+// the author's court, 73% have a default-branch HEAD ahead of the validated
+// commit. 47% pushed after the maintainer's review without the marketplace ever
+// seeing it, and 82% of those authors also commented, so they are engaged and
+// stuck rather than gone. Of 13 open submissions inspected with no labels left,
+// 9 had passed validation and passed the automated security baseline with zero
+// findings and were blocked solely because their validated commit had fallen
+// behind while they waited. 46% of the maintainer's own requests for a fresh validation never
+// produced one; in the parked group 77% never did. The instruction that would
+// fix this appears 22 times in the failure path of
+// `scripts/submission-feedback.mjs` and zero times in the success path of
+// `scripts/validate-submission.mjs`, which is the path 97 of 100 parked
+// submissions took.
+//
+// This command reads. It never edits the issue, never comments, never labels.
+// The action it names is the author's to take.
+
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { MARKETPLACE_PIN, requirePin } from "./pin.mjs"
+import { defaultBranchHead, issue, issueComments, parseIssueUrl, token, GitHubError } from "./github.mjs"
+
+export class WatchError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = "WatchError"
+    this.code = code
+  }
+}
+
+const MARKETPLACE_SLUG = MARKETPLACE_PIN.repository.replace(/^https:\/\/github\.com\//, "").toLowerCase()
+
+// The one action that re-runs validation, in the register the marketplace itself
+// uses in its own failure feedback.
+export const REFRESH_ACTION =
+  "Edit the issue body. That is the only action that re-runs validation and the security baseline against a new commit: a push does not, and a comment does not."
+
+async function loadRecord(pinDir) {
+  return import(pathToFileURL(join(pinDir, "scripts/security-baseline-record.mjs")).href)
+}
+
+async function loadSubmission(pinDir) {
+  return import(pathToFileURL(join(pinDir, "scripts/submission.mjs")).href)
+}
+
+async function loadVerification(pinDir) {
+  return import(pathToFileURL(join(pinDir, "scripts/plugin-verification-request.mjs")).href)
+}
+
+/**
+ * Which repository an issue is about.
+ *
+ * The marketplace has two issue forms and they are not interchangeable. A
+ * `[Plugin]:` submission is read by `extractRepositoryUrl`; a `[Verify]:` update
+ * request has its own headings, and feeding it to the submission parser fails
+ * in a misleading way, because "Repository URL" is a heading both forms use and
+ * the submission parser then runs the section on until the next heading it
+ * happens to recognise. So each form is read by the parser the marketplace
+ * itself uses for it, and the issue says which one it is.
+ */
+async function repositoryFor(pinDir, subject) {
+  const submission = await loadSubmission(pinDir)
+  const verification = await loadVerification(pinDir)
+  const title = String(subject.title || "")
+  const attempts = title.startsWith("[Verify]")
+    ? [
+      ["verify", () => verification.parsePluginVerificationIssue(subject.body).repoUrl],
+      ["verify-legacy", () => verification.parseLegacyListedSnapshotVerificationIssue(subject.body).repoUrl],
+      ["submission", () => submission.extractRepositoryUrl(subject.body)],
+    ]
+    : [
+      ["submission", () => submission.extractRepositoryUrl(subject.body)],
+      ["verify", () => verification.parsePluginVerificationIssue(subject.body).repoUrl],
+    ]
+  const errors = []
+  for (const [kind, read] of attempts) {
+    try {
+      const url = read()
+      if (url) return { url, kind, error: null }
+    } catch (error) {
+      errors.push(`${kind}: ${error.message}`)
+    }
+  }
+  return { url: null, kind: null, error: errors.join("; ") }
+}
+
+/** The short commit the validation comment reports, as a fallback when no baseline marker exists. */
+export function validationCommentCommit(comments) {
+  const validation = (comments || [])
+    .filter((comment) => String(comment.body || "").includes("<!-- marketplace-validation -->"))
+    .at(-1)
+  if (!validation) return null
+  const short = String(validation.body).match(/passed at commit `([0-9a-f]{7,40})`/i)?.[1]
+  return short ? { short: short.toLowerCase(), createdAt: validation.created_at || null } : null
+}
+
+/**
+ * @param {{ repoRoot: string, issueUrl: string }} options
+ */
+export async function validationWatch({ repoRoot, issueUrl, onPhase }) {
+  // Optional: told the name of the step about to run, so a terminal can say
+  // what is happening while the network answers. Never affects the result.
+  const phase = onPhase || (() => {})
+  const { dir: pinDir } = requirePin(repoRoot)
+  const target = parseIssueUrl(issueUrl)
+  if (`${target.owner}/${target.repository}`.toLowerCase() !== MARKETPLACE_SLUG) {
+    throw new WatchError(
+      "usage",
+      `the watch only reads ${MARKETPLACE_PIN.repository} submissions, got ${target.owner}/${target.repository}`,
+    )
+  }
+
+  const record = await loadRecord(pinDir)
+
+  phase(`reading issue #${target.number}`)
+  const subject = await issue(target.owner, target.repository, target.number)
+  phase(`reading the comments on issue #${target.number}`)
+  const comments = await issueComments(target.owner, target.repository, target.number)
+
+  const read = await repositoryFor(pinDir, subject)
+  const repositoryUrl = read.url
+  const repositoryError = read.error
+  const issueKind = read.kind
+
+  let validated = null
+  let baselineError = null
+  try {
+    const marker = record.findLatestSecurityBaseline(comments)
+    if (marker) {
+      validated = {
+        commit: marker.commitSha,
+        source: "security-baseline-marker",
+        outcome: marker.outcome,
+        findings: marker.findings,
+        capabilities: marker.capabilities,
+        checkedAt: marker.checkedAt,
+        pluginIds: [...marker.pluginIds],
+      }
+    }
+  } catch (error) {
+    baselineError = { code: error.code || "baseline-unreadable", message: error.message }
+  }
+  const fallback = validated ? null : validationCommentCommit(comments)
+
+  const labels = (subject.labels || []).map((label) => (typeof label === "string" ? label : label?.name)).filter(Boolean)
+  const authorComments = comments.filter((comment) => comment?.user?.login === subject.user?.login)
+  const maintainerComments = comments.filter(
+    (comment) => comment?.user?.login && comment.user.login !== subject.user?.login && comment.user.login !== "github-actions[bot]",
+  )
+
+  let head = null
+  let headError = null
+  if (repositoryUrl) {
+    phase("reading the plugin repository's default-branch HEAD")
+    try {
+      head = await defaultBranchHead(repositoryUrl)
+    } catch (error) {
+      headError = { code: error.code || "head-unreadable", message: error.message }
+    }
+  }
+
+  const comparable = Boolean(validated?.commit && head?.commit)
+  const stale = comparable ? validated.commit !== head.commit : null
+  const lastReviewAt = Date.parse(maintainerComments.at(-1)?.created_at || "")
+  const headAt = Date.parse(head?.committedAt || "")
+  const pushedAfterReview = Boolean(
+    stale && Number.isFinite(lastReviewAt) && Number.isFinite(headAt) && headAt > lastReviewAt,
+  )
+
+  return {
+    read: {
+      issue: `${MARKETPLACE_PIN.repository}/issues/${target.number}`,
+      state: subject.state,
+      title: subject.title,
+      // Kept in the JSON for callers that need it, not printed: the text
+      // rendering ends up pasted into issues, reports and screenshots.
+      author: subject.user?.login || null,
+      labels,
+      createdAt: subject.created_at,
+      updatedAt: subject.updated_at,
+      bodyEditedAt: subject.body_edited_at || null,
+      comments: comments.length,
+      authorComments: authorComments.length,
+      maintainerComments: maintainerComments.length,
+      lastMaintainerCommentAt: maintainerComments.at(-1)?.created_at || null,
+      authenticated: Boolean(token()),
+    },
+    plugin: { repository: repositoryUrl, repositoryError, form: issueKind },
+    validated,
+    validationCommentFallback: fallback,
+    baselineError,
+    head,
+    headError,
+    verdict: validationVerdict({ comparable, stale, validated, head, fallback, baselineError, headError, pushedAfterReview }),
+  }
+}
+
+export function validationVerdict({ comparable, stale, validated, head, fallback, baselineError, headError, pushedAfterReview, repositoryUrl = "unknown" }) {
+  if (baselineError) {
+    return {
+      state: "unknown",
+      summary: `The latest automated baseline on this issue did not complete (${baselineError.code}), so there is no validated commit to compare.`,
+      action: REFRESH_ACTION,
+    }
+  }
+  if (!validated) {
+    return {
+      state: "unknown",
+      summary: fallback
+        ? `No security-baseline marker on this issue. Validation reported commit ${fallback.short}, which is too short to compare reliably.`
+        : "No automated validation or security baseline has run on this issue yet, so there is no validated commit.",
+      action: fallback ? REFRESH_ACTION : "Wait for the automated validation to run, or edit the issue body to trigger it.",
+    }
+  }
+  if (!repositoryUrl) {
+    return {
+      state: "unknown",
+      summary: `The validated commit is ${validated.commit}, but no plugin repository could be read from this issue, so there is nothing to compare it with.`,
+      action: null,
+    }
+  }
+  if (headError || !head) {
+    return {
+      state: "unknown",
+      summary: `The validated commit is ${validated.commit}, but the repository's current default-branch HEAD could not be read (${headError?.code || "unknown"}).`,
+      action: null,
+    }
+  }
+  if (!comparable) {
+    return { state: "unknown", summary: "Not enough information to compare the validated commit.", action: null }
+  }
+  if (!stale) {
+    return {
+      state: "current",
+      summary: `The validated commit is ${validated.commit}, which is the current ${head.branch || "default"}-branch HEAD. Nothing needs refreshing.`,
+      action: null,
+    }
+  }
+  return {
+    state: "stale",
+    summary: [
+      `The validated commit is ${validated.commit}.`,
+      `The repository's current ${head.branch || "default"}-branch HEAD is ${head.commit}.`,
+      "The marketplace has not seen the newer commit. Pushing it did not tell the marketplace, and neither did any comment.",
+      pushedAfterReview ? "The newer commit landed after the last human review comment on this issue." : null,
+    ].filter(Boolean).join(" "),
+    action: REFRESH_ACTION,
+  }
+}
+
+export { GitHubError }

package/tools/marketplace/yaml.mjs

@@ -0,0 +1,164 @@
+// A deliberately small YAML reader for GitHub issue-form documents.
+//
+// Omakit has zero runtime dependencies, and the one YAML document it must read
+// is the pinned marketplace issue form. That form uses a narrow subset: block
+// maps, block sequences, plain and quoted scalars, and one literal block
+// scalar. This parser accepts exactly that subset and throws on anything it
+// does not understand, so an unreadable form is a loud failure instead of a
+// silently wrong submission body.
+//
+// Not supported on purpose: flow collections, anchors, aliases, tags,
+// multi-document streams, folded scalars with chomping indicators other than
+// the two below. If the marketplace ever needs them, this file fails and the
+// pin update is the moment to notice.
+
+export class YamlError extends Error {
+  constructor(message, line) {
+    super(line === undefined ? message : `${message} (line ${line + 1})`)
+    this.name = "YamlError"
+    this.code = "form-unreadable"
+    this.line = line
+  }
+}
+
+const KEY = /^([A-Za-z0-9_][A-Za-z0-9_.\- ]*?)\s*:(?:\s+(.*))?$/
+const ITEM = /^-(\s+|$)/
+
+function isBlank(line) {
+  return line.trim() === ""
+}
+
+function isComment(line) {
+  return /^\s*#/.test(line)
+}
+
+function indentOf(line) {
+  return line.length - line.replace(/^ +/, "").length
+}
+
+function skip(lines, i) {
+  while (i < lines.length && (isBlank(lines[i]) || isComment(lines[i]))) i += 1
+  return i
+}
+
+export function parseScalar(token) {
+  const text = String(token).trim()
+  if (text === "" || text === "~" || text === "null") return text === "" ? "" : null
+  if (text === "true") return true
+  if (text === "false") return false
+  if (/^-?\d+$/.test(text)) return Number(text)
+  if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+    return text
+      .slice(1, -1)
+      .replace(/\\n/g, "\n")
+      .replace(/\\t/g, "\t")
+      .replace(/\\"/g, '"')
+      .replace(/\\\\/g, "\\")
+  }
+  if (text.length >= 2 && text.startsWith("'") && text.endsWith("'")) {
+    return text.slice(1, -1).replace(/''/g, "'")
+  }
+  return text
+}
+
+function readBlockScalar(lines, i, parentIndent, chomp) {
+  const out = []
+  let base = null
+  while (i < lines.length) {
+    if (isBlank(lines[i])) {
+      out.push("")
+      i += 1
+      continue
+    }
+    const indent = indentOf(lines[i])
+    if (indent <= parentIndent) break
+    if (base === null) base = indent
+    out.push(lines[i].slice(Math.min(base, indent)))
+    i += 1
+  }
+  while (out.length && out.at(-1) === "") out.pop()
+  const text = out.join("\n")
+  return [chomp === "strip" ? text : `${text}\n`, i]
+}
+
+function parseNode(lines, i, minIndent) {
+  i = skip(lines, i)
+  if (i >= lines.length) return [null, i]
+  const indent = indentOf(lines[i])
+  if (indent < minIndent) return [null, i]
+  const body = lines[i].slice(indent)
+  if (ITEM.test(body)) return parseSequence(lines, i, indent)
+  if (KEY.test(body)) return parseMap(lines, i, indent)
+  throw new YamlError(`unsupported YAML construct: ${body.slice(0, 40)}`, i)
+}
+
+function parseSequence(lines, start, indent) {
+  const out = []
+  let i = start
+  for (;;) {
+    i = skip(lines, i)
+    if (i >= lines.length || indentOf(lines[i]) !== indent) break
+    const body = lines[i].slice(indent)
+    if (!ITEM.test(body)) break
+    const rest = body.replace(ITEM, "")
+    if (rest === "") {
+      const [value, next] = parseNode(lines, i + 1, indent + 1)
+      out.push(value)
+      i = next
+      continue
+    }
+    if (KEY.test(rest)) {
+      // An inline first key: re-present the line at the item's own indentation
+      // so the map parser sees a normal block map. Index arithmetic holds
+      // because entry 0 of the view stands for line i.
+      const itemIndent = indent + (body.length - rest.length)
+      const view = [" ".repeat(itemIndent) + rest, ...lines.slice(i + 1)]
+      const [value, consumed] = parseMap(view, 0, itemIndent)
+      out.push(value)
+      i += consumed
+      continue
+    }
+    out.push(parseScalar(rest))
+    i += 1
+  }
+  return [out, i]
+}
+
+function parseMap(lines, start, indent) {
+  const out = {}
+  let i = start
+  for (;;) {
+    i = skip(lines, i)
+    if (i >= lines.length || indentOf(lines[i]) !== indent) break
+    const body = lines[i].slice(indent)
+    const match = body.match(KEY)
+    if (!match) break
+    const key = match[1].trim()
+    if (Object.hasOwn(out, key)) throw new YamlError(`duplicate key "${key}"`, i)
+    const inline = match[2] === undefined ? "" : match[2].trim()
+    if (inline === "|" || inline === "|-") {
+      const [value, next] = readBlockScalar(lines, i + 1, indent, inline === "|-" ? "strip" : "clip")
+      out[key] = value
+      i = next
+      continue
+    }
+    if (inline === "") {
+      const [value, next] = parseNode(lines, i + 1, indent + 1)
+      out[key] = value
+      i = next
+      continue
+    }
+    out[key] = parseScalar(inline)
+    i += 1
+  }
+  return [out, i]
+}
+
+/** Parse one YAML document in the issue-form subset described above. */
+export function parseYaml(text) {
+  const lines = String(text).replace(/\r\n?/g, "\n").split("\n")
+  const [value, next] = parseNode(lines, 0, 0)
+  const tail = skip(lines, next)
+  if (tail < lines.length) throw new YamlError(`unparsed trailing content: ${lines[tail].slice(0, 40)}`, tail)
+  return value
+}