omakit 0.1.0

package/tools/marketplace/cli.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+// The single entry point.
+//
+//   omakit pin                       fetch or verify the pinned marketplace checkout
+//   omakit submit <target> ...       everything knowable before submitting; prints, never posts
+//   omakit watch <issue-url>         is this submission's validated commit still current?
+//   omakit verify <target>           the official baseline over the local transport, verbatim
+//   omakit parity [--count n]        prove the local transport equals the GitHub transport
+//
+// Nothing here writes to the marketplace. There is no POST, PATCH, PUT or
+// DELETE anywhere in this repository, and `tests/unit/read-only.test.mjs`
+// proves it.
+
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { ensurePin, MARKETPLACE_PIN } from "./pin.mjs"
+import { marketplaceBaselineSection } from "./verify.mjs"
+import { resolveSubject, SubjectError } from "../subject/resolve.mjs"
+import { submitPreflight } from "./submit.mjs"
+import { validationWatch } from "./watch.mjs"
+import { renderSubmit, renderWatch, renderDoctor } from "./report.mjs"
+import { doctor } from "./doctor.mjs"
+import { setup } from "./setup.mjs"
+import { upgrade } from "./upgrade.mjs"
+import { progress } from "./progress.mjs"
+import { banner, bannerEnabled } from "./banner.mjs"
+import { COMMANDS, renderSummary, renderUsage, TAGLINE } from "./usage.mjs"
+import { action, colourEnabled, GUTTER, mark, styler, wrap } from "./style.mjs"
+import { omakitCacheDir } from "./paths.mjs"
+import { parityOutput } from "./parity-output.mjs"
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
+
+/**
+ * The one action for each way a command can stop. A failure state says what
+ * happened (the code), what it means (the message the module raised) and the
+ * single command that fixes it, in that order, every time. A code with no
+ * entry here gets the first two and no arrow, which is the honest rendering of
+ * a state nobody has written a fix for yet.
+ */
+const REMEDY = Object.freeze({
+  "usage": "omakit help",
+  "marketplace-unavailable": "omakit pin",
+  "dirty-worktree": "Commit the changes, or pass --allow-dirty to check the tree as it is.",
+  "subject-not-found": "Pass a local Git repository path, or <https url>@<40-char sha>.",
+  "not-a-git-repository": "Pass a local Git repository path, or <https url>@<40-char sha>.",
+  "commit-not-found": "Commit first; the checks read the tree at an exact commit, never the working copy.",
+  "network-unavailable": "Connect to the network, then run it again.",
+  "github-unavailable": "Wait for GitHub, then run it again. `gh auth login` raises the rate limit if that is what ran out.",
+  "not-found": "Check the issue URL: it has to be an existing issue on the marketplace repository.",
+  "head-unreadable": "Check that the plugin repository is public and its URL is right.",
+})
+
+/**
+ * Every failure, in one register, on stderr. `usage` errors carry the
+ * signature that was expected, so the remedy is the reference and not a
+ * restatement of the message.
+ */
+function fail(code, message, exit = 1, remedy = REMEDY[code]) {
+  const c = styler(colourEnabled(process.stderr))
+  const lines = [`${mark("fail", c)}${c("name", code)}`, ...wrap(message, { indent: GUTTER }, c)]
+  if (remedy) lines.push(...action(remedy, c))
+  process.stderr.write(`${lines.join("\n")}\n`)
+  process.exit(exit)
+}
+
+/** A thrown error becomes a failure state when it carries a code; anything else is a bug and keeps its stack. */
+function failFrom(error) {
+  if (error?.code && typeof error.code === "string") fail(error.code, error.message, error.code === "usage" ? 2 : 1, error.remedy || REMEDY[error.code])
+  throw error
+}
+
+function option(args, name) {
+  const index = args.indexOf(name)
+  return index >= 0 ? args[index + 1] : undefined
+}
+
+function positionals(args) {
+  const valued = new Set(["--profile", "--plugin", "--out", "--category", "--tags", "--notes", "--suggest-tag", "--name", "--count", "--offset"])
+  return args.filter((value, index) => !value.startsWith("--") && !valued.has(args[index - 1]))
+}
+
+function emit(args, text) {
+  const out = option(args, "--out")
+  if (out) {
+    mkdirSync(dirname(resolve(out)), { recursive: true })
+    writeFileSync(resolve(out), text.endsWith("\n") ? text : `${text}\n`)
+    const c = styler(colourEnabled())
+    process.stdout.write(`${mark("pass", c)}wrote ${resolve(out)}\n`)
+  } else {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`)
+  }
+}
+
+async function cmdSubmit(args) {
+  const target = positionals(args)[0]
+  if (!target) fail("usage", "submit needs a target: `omakit submit <target> --category <c> --tags <a,b>`", 2)
+  const spinner = args.includes("--json") ? { phase: () => {}, done: () => {} } : progress()
+  let result
+  try {
+    result = await submitPreflight({
+      repoRoot: ROOT,
+      target,
+      onPhase: spinner.phase,
+      category: option(args, "--category"),
+      tags: option(args, "--tags"),
+      notes: option(args, "--notes"),
+      suggestedTag: option(args, "--suggest-tag"),
+      pluginName: option(args, "--name"),
+      allowDirty: args.includes("--allow-dirty"),
+      offline: args.includes("--offline"),
+    })
+  } catch (error) {
+    spinner.done()
+    failFrom(error)
+  }
+  spinner.done()
+  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderSubmit(result))
+  process.exit(result.ready ? 0 : 1)
+}
+
+async function cmdWatch(args) {
+  const issueUrl = positionals(args)[0]
+  if (!issueUrl) fail("usage", "watch needs an issue: `omakit watch <issue-url>`", 2)
+  const spinner = args.includes("--json") ? { phase: () => {}, done: () => {} } : progress()
+  let result
+  try {
+    result = await validationWatch({ repoRoot: ROOT, issueUrl, onPhase: spinner.phase })
+  } catch (error) {
+    spinner.done()
+    failFrom(error)
+  }
+  spinner.done()
+  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderWatch(result))
+  process.exit(result.verdict.state === "unknown" ? 2 : 0)
+}
+
+async function cmdFrontDoor() {
+  // A bare `omakit` is the front door: the wordmark, through `ttfx` when it is
+  // there, then the short list, which fits under it on any screen. The banner
+  // already says the name and the tagline, so the heading would repeat it.
+  const drew = bannerEnabled()
+  await banner({ tagline: TAGLINE, effect: true })
+  process.stdout.write(renderSummary({ heading: !drew }))
+}
+
+async function cmdSetup() {
+  const result = await setup({ repoRoot: ROOT, entryPoint: resolve(ROOT, "bin/omakit") })
+  process.exit(result.ok ? 0 : 1)
+}
+
+async function cmdUpgrade(args) {
+  const result = await upgrade({ repoRoot: ROOT, dryRun: args.includes("--dry-run") })
+  process.exit(result.ok ? 0 : 1)
+}
+
+async function cmdDoctor(args) {
+  const spinner = args.includes("--json") ? { phase: () => {}, done: () => {} } : progress()
+  const result = await doctor({ repoRoot: ROOT, offline: args.includes("--offline"), onPhase: spinner.phase })
+  spinner.done()
+  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderDoctor(result))
+  process.exit(result.problems ? 1 : 0)
+}
+
+async function cmdVerify(args) {
+  const target = positionals(args)[0]
+  if (!target) fail("usage", "verify needs a target: `omakit verify <path | https-url@sha>`", 2)
+  let subject
+  try {
+    subject = resolveSubject(target, { cacheRoot: omakitCacheDir(), allowDirty: args.includes("--allow-dirty") })
+  } catch (error) {
+    if (error instanceof SubjectError) fail(error.code, error.message, error.code === "usage" ? 2 : 1)
+    throw error
+  }
+  const spinner = progress()
+  let section
+  try {
+    spinner.phase("running the official security baseline over a local snapshot")
+    section = await marketplaceBaselineSection({ repoRoot: ROOT, subject })
+  } catch (error) {
+    spinner.done()
+    fail(error?.code === "marketplace-unavailable" ? error.code : "baseline-unavailable", error.message)
+  }
+  spinner.done()
+  emit(args, `${JSON.stringify({
+    subject: {
+      repository: subject.repository,
+      commit: subject.commit,
+      cleanTree: { clean: subject.clean, proof: "git-status-porcelain-empty" },
+      mode: subject.mode,
+    },
+    marketplaceBaseline: section,
+  }, null, 2)}\n`)
+}
+
+async function cmdParity(args) {
+  const count = option(args, "--count")
+  const offset = option(args, "--offset")
+  if (count) process.env.PARITY_COUNT = count
+  if (offset) process.env.PARITY_OFFSET = offset
+  try {
+    const out = option(args, "--out")
+    process.env.PARITY_OUT = parityOutput({ repoRoot: ROOT, out })
+    if (out) process.env.PARITY_OUT_EXPLICIT = "1"
+  } catch (error) {
+    failFrom(error)
+  }
+  process.env.OMAKIT_ROOT = ROOT
+  try {
+    await import("../../tests/parity/run.mjs")
+  } catch (error) {
+    failFrom(error)
+  }
+}
+
+const [command, ...rest] = process.argv.slice(2)
+if (command === "setup") {
+  await cmdSetup()
+} else if (command === "pin" || command === "marketplace-pin") {
+  const c = styler(colourEnabled())
+  const spinner = progress()
+  try {
+    ensurePin(ROOT, (line) => {
+      // ensurePin narrates: a state line to keep, then a fetch it is about to
+      // start. The fetch is the slow part, so it gets the progress line.
+      if (line.state === "fetching") spinner.phase(line.text)
+      else process.stdout.write(`${mark(line.state, c)}${wrap(line.text, { indent: GUTTER }, c).join("\n").trimStart()}\n`)
+    })
+  } catch (error) {
+    spinner.done()
+    fail(error?.code || "marketplace-unavailable", error.message, 1, error?.remedy || REMEDY[error?.code])
+  }
+  spinner.done()
+} else if (command === "submit") {
+  await cmdSubmit(rest)
+} else if (command === "upgrade") {
+  await cmdUpgrade(rest)
+} else if (command === "doctor") {
+  await cmdDoctor(rest)
+} else if (command === "watch") {
+  await cmdWatch(rest)
+} else if (command === "verify") {
+  await cmdVerify(rest.filter((value, index) => value !== "marketplace" || rest[index - 1] !== "--profile"))
+} else if (command === "parity") {
+  await cmdParity(rest)
+} else if (command === "help" || command === "--help" || command === "-h" || command === undefined) {
+  if (rest.includes("--agent")) {
+    // The skills ship in the npm package, so this works from a global install
+    // with no repository checked out.
+    const dir = resolve(ROOT, "skills")
+    const parts = []
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const file = entry.isDirectory() ? resolve(dir, entry.name, "SKILL.md") : resolve(dir, entry.name)
+      if (!file.endsWith(".md")) continue
+      try {
+        parts.push(readFileSync(file, "utf8").trim())
+      } catch {
+        // A skill directory without a SKILL.md is not an error worth failing on.
+      }
+    }
+    process.stdout.write(`${parts.join("\n\n---\n\n")}\n`)
+  } else if (command === undefined) {
+    await cmdFrontDoor()
+  } else {
+    // `omakit help` is the reference and gets all of it, under the name and
+    // the tagline as one line of text: 53 lines scroll a wordmark off the top
+    // of the screen before anyone has read it, so it gets none.
+    process.stdout.write(renderUsage())
+  }
+} else {
+  // The short list on a typo, not 53 lines of reference, in the same register
+  // as every other failure: what happened, what it means, what to run.
+  const c = styler(colourEnabled(process.stderr))
+  process.stderr.write([
+    `${mark("fail", c)}${c("name", "unknown command")}`,
+    ...wrap(`\`${command}\` is not something omakit does. The commands it has are listed below.`, { indent: GUTTER }, c),
+    ...action("omakit help", c),
+    "",
+    renderSummary({ colour: colourEnabled(process.stderr), heading: false }),
+  ].join("\n"))
+  process.exit(2)
+}

package/tools/marketplace/completion.mjs

@@ -0,0 +1,263 @@
+// Tab completion for bash, zsh and fish, installed by `omakit setup` for the
+// shell it runs from.
+//
+// Everything the script completes is derived, never retyped: the subcommands
+// and their flags from COMMANDS in usage.mjs, so a command added there cannot
+// be missing here, and the categories and tags from the submission form at the
+// marketplace pin, the same source the checks read. Those controlled values are
+// baked into the emitted script rather than fetched on every keypress: node's
+// startup plus a pin read is not something to put behind a TAB. The script says
+// in its own header which pin it came from and how to regenerate it.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+import { tagSlug } from "./form.mjs"
+import { COMMANDS, COMPLETION_SHELLS } from "./usage.mjs"
+
+/**
+ * The completion model, read out of the help data. A subcommand is the word
+ * after `omakit` in its signature; a flag is every `--word` in it, valued when
+ * a `<placeholder>` follows it; `<target>` in the signature means the first
+ * positional is a directory.
+ *
+ * @param {ReadonlyArray<{ signature: string|string[], lines: string[] }>} commands
+ */
+export function subcommandsOf(commands = COMMANDS) {
+  return commands.map((command) => {
+    const signature = [].concat(command.signature).join(" ")
+    const name = signature.match(/^omakit +([a-z][a-z-]*)/)?.[1]
+    if (!name) throw new Error(`completion: no subcommand in signature ${JSON.stringify(signature)}`)
+    const flags = [...signature.matchAll(/(--[a-z][a-z-]*)(?: <([^>]+)>)?/g)].map(([, flag, placeholder]) => ({
+      flag,
+      value: placeholder ? placeholderKind(placeholder) : null,
+    }))
+    const sentence = command.lines.join(" ").replace(/`/g, "").split(/(?<=\.)\s/)[0]
+    return { name, description: sentence, flags, target: /<target>/.test(signature) }
+  })
+}
+
+/** What a valued flag takes, by its placeholder: a controlled value, a file, or free text. */
+function placeholderKind(placeholder) {
+  if (placeholder === "c") return "category"
+  if (placeholder === "a,b") return "tags"
+  if (placeholder === "file") return "file"
+  return "text"
+}
+
+/**
+ * @param {"bash"|"zsh"|"fish"} shell
+ * @param {{ contract: { categories: string[], tagLabels: string[] }, pin: string, commands?: typeof COMMANDS }} options
+ * @returns {string} the script
+ */
+export function renderCompletion(shell, { contract, pin, commands = COMMANDS }) {
+  if (!COMPLETION_SHELLS.includes(shell)) throw new Error(`completion: no script for ${shell}`)
+  const model = {
+    subcommands: subcommandsOf(commands),
+    categories: [...contract.categories],
+    tags: contract.tagLabels.map(tagSlug),
+    pin,
+  }
+  return { bash, zsh, fish }[shell](model)
+}
+
+function header(comment, shell, pin) {
+  return [
+    `${comment} omakit completion for ${shell}. Generated by \`omakit setup\` from`,
+    `${comment} marketplace pin ${pin}; the categories and tags`,
+    `${comment} below are that pin's submission form. Regenerate it by running setup`,
+    `${comment} again.`,
+  ]
+}
+
+const single = (text) => `'${String(text).replace(/'/g, "'\\''")}'`
+
+// --- bash ---------------------------------------------------------------------
+
+function bash({ subcommands, categories, tags, pin }) {
+  const lines = [...header("#", "bash", pin), ""]
+  lines.push("_omakit() {")
+  lines.push("  local cur prev command")
+  lines.push("  cur=${COMP_WORDS[COMP_CWORD]}")
+  lines.push("  prev=${COMP_WORDS[COMP_CWORD-1]}")
+  lines.push(`  local commands=${single(subcommands.map((c) => c.name).join(" "))}`)
+  lines.push(`  local categories=${single(categories.join("\n"))}`)
+  lines.push(`  local tags=${single(tags.join(" "))}`)
+  lines.push("  COMPREPLY=()")
+  lines.push("  if ((COMP_CWORD == 1)); then")
+  lines.push('    COMPREPLY=($(compgen -W "$commands" -- "$cur"))')
+  lines.push("    return")
+  lines.push("  fi")
+  lines.push("  command=${COMP_WORDS[1]}")
+  lines.push('  case "$command" in')
+  for (const sub of subcommands) {
+    lines.push(`  ${sub.name})`)
+    const valued = sub.flags.filter((f) => f.value)
+    if (valued.length) {
+      lines.push('    case "$prev" in')
+      for (const { flag, value } of valued) {
+        if (value === "category") lines.push(`    ${flag}) _omakit_values "$categories" "$cur"; return ;;`)
+        else if (value === "tags") lines.push(`    ${flag}) _omakit_list "$tags" "$cur"; return ;;`)
+        else if (value === "file") lines.push(`    ${flag}) COMPREPLY=($(compgen -f -- "$cur")); compopt -o filenames 2>/dev/null; return ;;`)
+        else lines.push(`    ${flag}) return ;;`)
+      }
+      lines.push("    esac")
+    }
+    if (sub.flags.length) {
+      lines.push('    if [[ "$cur" == -* ]]; then')
+      lines.push(`      COMPREPLY=($(compgen -W ${single(sub.flags.map((f) => f.flag).join(" "))} -- "$cur"))`)
+      lines.push("      return")
+      lines.push("    fi")
+    }
+    if (sub.target) {
+      lines.push('    COMPREPLY=($(compgen -d -- "$cur"))')
+      lines.push("    compopt -o filenames 2>/dev/null")
+    }
+    lines.push("    ;;")
+  }
+  lines.push("  esac")
+  lines.push("}")
+  lines.push("")
+  lines.push("# A controlled value may contain a space, so each match is one line and is")
+  lines.push("# escaped on the way out, the way the shell would have to type it.")
+  lines.push("_omakit_values() {")
+  lines.push("  local IFS=$'\\n' i")
+  lines.push('  COMPREPLY=($(compgen -W "$1" -- "${2//\\\\ / }"))')
+  lines.push('  for i in "${!COMPREPLY[@]}"; do COMPREPLY[i]=$(printf \'%q\' "${COMPREPLY[i]}"); done')
+  lines.push("}")
+  lines.push("")
+  lines.push("# A comma-separated list: complete the segment after the last comma and keep")
+  lines.push("# what came before it.")
+  lines.push("_omakit_list() {")
+  lines.push('  local prefix="" part="$2"')
+  lines.push('  if [[ "$2" == *,* ]]; then prefix="${2%,*},"; part="${2##*,}"; fi')
+  lines.push('  COMPREPLY=($(compgen -P "$prefix" -W "$1" -- "$part"))')
+  lines.push("}")
+  lines.push("")
+  lines.push("complete -F _omakit omakit")
+  return `${lines.join("\n")}\n`
+}
+
+// --- zsh ----------------------------------------------------------------------
+
+const zshDescribe = (name, description) => single(`${name}:${description.replace(/:/g, "\\:")}`)
+
+function zsh({ subcommands, categories, tags, pin }) {
+  const lines = ["#compdef omakit", ...header("#", "zsh", pin), ""]
+  lines.push("_omakit() {")
+  lines.push("  local curcontext=\"$curcontext\" state line")
+  lines.push("  typeset -A opt_args")
+  lines.push("  local -a commands categories tags shells")
+  lines.push("  commands=(")
+  for (const sub of subcommands) lines.push(`    ${zshDescribe(sub.name, sub.description)}`)
+  lines.push("  )")
+  lines.push(`  categories=(${categories.map(single).join(" ")})`)
+  lines.push(`  tags=(${tags.map(single).join(" ")})`)
+  lines.push("  _arguments -C '1:command:->command' '*::arguments:->arguments'")
+  lines.push('  case "$state" in')
+  lines.push("  command)")
+  lines.push("    _describe -t commands 'omakit command' commands")
+  lines.push("    ;;")
+  lines.push("  arguments)")
+  lines.push('    case "$line[1]" in')
+  for (const sub of subcommands) {
+    lines.push(`    ${sub.name})`)
+    const specs = sub.flags.map(({ flag, value }) => {
+      if (value === "category") return single(`${flag}:category:{compadd -a categories}`)
+      if (value === "tags") return single(`${flag}:tags:{_values -s , tag $tags}`)
+      if (value === "file") return single(`${flag}:file:_files`)
+      if (value === "text") return single(`${flag}:text:`)
+      return single(flag)
+    })
+    if (sub.target) specs.push(single("1:target:_directories"))
+    if (specs.length) lines.push(`      _arguments ${specs.join(" ")}`)
+    lines.push("      ;;")
+  }
+  lines.push("    esac")
+  lines.push("    ;;")
+  lines.push("  esac")
+  lines.push("}")
+  lines.push("")
+  lines.push('_omakit "$@"')
+  return `${lines.join("\n")}\n`
+}
+
+// --- fish ---------------------------------------------------------------------
+
+const fishWord = (text) => String(text).replace(/([\\'" ])/g, "\\$1")
+
+function fish({ subcommands, categories, tags, pin }) {
+  const lines = [...header("#", "fish", pin), ""]
+  lines.push("complete -c omakit -f")
+  for (const sub of subcommands) {
+    lines.push(`complete -c omakit -n __fish_use_subcommand -a ${sub.name} -d ${single(sub.description)}`)
+  }
+  for (const sub of subcommands) {
+    const when = `-n ${single(`__fish_seen_subcommand_from ${sub.name}`)}`
+    if (sub.target) lines.push(`complete -c omakit ${when} -a '(__fish_complete_directories)'`)
+    for (const { flag, value } of sub.flags) {
+      const long = `-l ${flag.slice(2)}`
+      if (value === "category") lines.push(`complete -c omakit ${when} ${long} -x -a ${single(categories.map(fishWord).join(" "))}`)
+      else if (value === "tags") lines.push(`complete -c omakit ${when} ${long} -x -a ${single(tags.join(" "))}`)
+      else if (value === "file") lines.push(`complete -c omakit ${when} ${long} -r`)
+      else if (value === "text") lines.push(`complete -c omakit ${when} ${long} -x`)
+      else lines.push(`complete -c omakit ${when} ${long}`)
+    }
+  }
+  return `${lines.join("\n")}\n`
+}
+
+// --- where a shell loads it from --------------------------------------------
+
+/**
+ * Where the user's shell would load the script from, so `omakit setup` can say
+ * how to install it and only when it is not there. bash-completion reads the
+ * XDG data directory; fish reads its config directory; zsh has no user
+ * directory of its own, and `~/.zfunc` is the convention, added to `fpath`.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ shell: string, path: string, display: string, note: string|null } | null}
+ */
+export function completionInstall(env = process.env) {
+  const shell = basename(env.SHELL || "")
+  const home = env.HOME || ""
+  if (!home || !COMPLETION_SHELLS.includes(shell)) return null
+  const tilde = (dir) => (dir.startsWith(home) ? `~${dir.slice(home.length)}` : dir)
+  if (shell === "bash") {
+    const dir = join(env.XDG_DATA_HOME || join(home, ".local/share"), "bash-completion/completions")
+    return { shell, path: join(dir, "omakit"), display: `${tilde(dir)}/omakit`, note: null }
+  }
+  if (shell === "fish") {
+    const dir = join(env.XDG_CONFIG_HOME || join(home, ".config"), "fish/completions")
+    return { shell, path: join(dir, "omakit.fish"), display: `${tilde(dir)}/omakit.fish`, note: null }
+  }
+  const dir = join(env.ZDOTDIR || home, ".zfunc")
+  return { shell, path: join(dir, "_omakit"), display: `${tilde(dir)}/_omakit`, note: "with `fpath+=~/.zfunc` before `compinit` in your .zshrc" }
+}
+
+/**
+ * Install the script where the shell in $SHELL loads it from, so a person
+ * never has to know the path: `omakit setup` calls this. Idempotent: a script
+ * that is already there and names the current pin is left alone; a missing
+ * one, or one from another pin, is written. The only file this writes is
+ * the completion script at the path `completionInstall` names, and
+ * tests/unit/self-containment.test.mjs holds it to that.
+ *
+ * @param {{ contract: { categories: string[], tagLabels: string[] }, pin: string, env?: NodeJS.ProcessEnv }} options
+ * @returns {{ state: "installed"|"updated"|"current"|"unsupported", shell: string|null, display: string|null, note: string|null }}
+ */
+export function installCompletion({ contract, pin, env = process.env }) {
+  const target = completionInstall(env)
+  if (!target) return { state: "unsupported", shell: basename(env.SHELL || "") || null, display: null, note: null }
+  const script = renderCompletion(target.shell, { contract, pin })
+  let existing = null
+  try {
+    existing = readFileSync(target.path, "utf8")
+  } catch {
+    existing = null
+  }
+  if (existing === script) return { state: "current", ...target }
+  mkdirSync(dirname(target.path), { recursive: true })
+  const completionFile = target.path
+  writeFileSync(completionFile, script)
+  return { state: existing === null ? "installed" : "updated", ...target }
+}