omakit 0.4.0 → 0.4.1

package/README.md

@@ -40,6 +40,10 @@ and shows the upgrade command. It installs nothing automatically; scripts
 and JSON stay quiet. `DISABLE_UPDATE_NOTIFIER=1` disables the notice, and
 `omakit doctor` checks explicitly. [Update behaviour](docs/INSTALL.md#updating).
 
+Terminal help and reports adapt to the available width, up to 120 columns
+for readability. Narrow windows wrap sooner; pipes and text files keep the
+stable eighty-column layout. JSON and exact issue bodies remain intact.
+
 ### `submit`
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "The safe place to find out: everything knowable about an Omarchy Quattro plugin submission before you post it, on your own machine. Agent-first, read-only against the marketplace, posts nothing, zero dependencies.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/tools/marketplace/README.md

@@ -81,7 +81,8 @@ side rather than the findings themselves. The GitHub side uses whatever
 credential `github.mjs` resolves (a `gh` login, and only that), read-only.
 
 Two rules about the output, stated as rules because each is an exception to
-a wider one. Everything omakit writes itself stays within 80 columns; text
+a wider one. Pipes use 80 columns; terminals use their available width up to
+120 columns. Text files compose at 80 columns without colour escapes. Text
 that will be posted verbatim, the marketplace's own baseline report and the
 issue body rendered from the pinned form, is never wrapped and may exceed 80,
 because a wrapped body would not be the body. And stdout is the whole result;

package/tools/marketplace/ask.mjs

@@ -15,7 +15,7 @@
 // the report ends with the command line that repeats the run without asking.
 
 import { createInterface } from "node:readline"
-import { colourEnabled, STEP, action, styler, wrap } from "./style.mjs"
+import { colourEnabled, outputColumns, STEP, action, styler, wrap } from "./style.mjs"
 import { resolveCategory, resolveTags } from "./form.mjs"
 import { watchIssueTitle } from "./watch.mjs"
 
@@ -52,10 +52,10 @@ function reader(input) {
 /** Ask one question until an answer resolves; `parse` returns { ok, value } or { ok: false, reason }. */
 async function question(lines, output, c, { name, heading, options, defaultIndexes, parse, wrapOptions = false, eofRemedy }) {
   const step = " ".repeat(STEP)
-  output.write(`${wrap(heading, {}, c).join("\n")}\n`)
+  output.write(`${wrap(heading, { width: outputColumns(output) }, c).join("\n")}\n`)
   for (const [index, option] of options.entries()) {
     output.write(wrapOptions
-      ? `${wrap(`${String(index + 1).padStart(2)} ${option}`, { indent: STEP }, c).join("\n")}\n`
+      ? `${wrap(`${String(index + 1).padStart(2)} ${option}`, { indent: STEP, width: outputColumns(output) }, c).join("\n")}\n`
       : `${step}${c("typeable", String(index + 1).padStart(2))}  ${option}\n`)
   }
   const fallback = defaultIndexes.length ? defaultIndexes.map((index) => index + 1).join(",") : null
@@ -70,7 +70,7 @@ async function question(lines, output, c, { name, heading, options, defaultIndex
     const text = raw.trim() || (fallback ?? "")
     const parsed = parse(text)
     if (parsed.ok) return parsed.value
-    output.write(`${wrap(parsed.reason, {}, c).join("\n")}\n`)
+    output.write(`${wrap(parsed.reason, { width: outputColumns(output) }, c).join("\n")}\n`)
   }
 }
 

package/tools/marketplace/banner.mjs

@@ -49,7 +49,7 @@
 // letters come from the small font below, so renaming the tool is a change to
 // one string and not a redrawing job.
 
-import { code, colourEnabled, DENSITY, motionEnabled, MOTION, rule as floorRule } from "./style.mjs"
+import { code, colourEnabled, DENSITY, motionEnabled, MOTION, outputColumns, rule as floorRule, wrap } from "./style.mjs"
 import { effectAvailable, playEffect } from "./effect.mjs"
 
 const ESC = "\u001b["
@@ -227,6 +227,15 @@ export async function banner(options = {}) {
   // and a piped run should differ from a watched one only in decoration.
   if (!enabled) return
 
+  // Never animate artwork across physical terminal rows: cursor-up would
+  // redraw the wrong row. A narrow terminal gets a compact wordmark instead.
+  if (stream.isTTY && Number.isFinite(stream.columns) && stream.columns > 0 && stream.columns < width) {
+    stream.write(`${c(code("name"), word.toUpperCase())}\n`)
+    if (options.tagline) stream.write(`${wrap(options.tagline, { width: outputColumns(stream) }, (name, text) => c(code(name), text)).join("\n")}\n`)
+    stream.write("\n")
+    return
+  }
+
   // A five-row animation redrawn with cursor-up needs five rows that stay put.
   // In a terminal with no room the screen scrolls under the animation, the
   // cursor-up lands a line off, and a row from an earlier frame is left stranded

package/tools/marketplace/cli.mjs

@@ -34,7 +34,7 @@ import { updateCheckEnabled, updateNotice } from "./update-check.mjs"
 import { progress } from "./progress.mjs"
 import { banner, bannerEnabled } from "./banner.mjs"
 import { COMMANDS, renderSummary, renderUsage, TAGLINE } from "./usage.mjs"
-import { action, AUDIT_VERDICTS, colourEnabled, GUTTER, labelled, mark, styler, verdict, wrap } from "./style.mjs"
+import { action, AUDIT_VERDICTS, colourEnabled, GUTTER, labelled, mark, outputColumns, styler, verdict, withOutputStream, wrap } from "./style.mjs"
 import { omakitCacheDir, withHomeAbbreviated } from "./paths.mjs"
 import { DEFAULTS as WEIGH_DEFAULTS, measureWeigh, planWeigh } from "../weigh/audit.mjs"
 import { confirmationQuestion, renderList, renderWeigh, renderPlan } from "../weigh/report.mjs"
@@ -76,8 +76,10 @@ const REMEDY = Object.freeze({
  */
 function fail(code, message, exit = 1, remedy = REMEDY[code], body = () => []) {
   const c = styler(colourEnabled(process.stderr))
-  const lines = [`${mark("fail", c)}${c("name", code)}`, ...wrap(message, { indent: GUTTER }, c), ...body(c)]
-  if (remedy) lines.push(...action(remedy, c))
+  const lines = withOutputStream(process.stderr, () => [
+    `${mark("fail", c)}${c("name", code)}`, ...wrap(message, { indent: GUTTER }, c), ...body(c),
+    ...(remedy ? action(remedy, c) : []),
+  ])
   process.stderr.write(`${lines.join("\n")}\n`)
   process.exit(exit)
 }
@@ -123,6 +125,12 @@ function emit(args, text) {
   }
 }
 
+function reportText(args, render, result, options = {}) {
+  const out = option(args, "--out")
+  return withOutputStream(out ? { isTTY: false } : process.stdout,
+    () => render(result, { ...options, ...(out ? { colour: false } : {}) }))
+}
+
 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)
@@ -174,7 +182,7 @@ async function cmdSubmit(args) {
     failFrom(error)
   }
   spinner.done()
-  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderSubmit(result))
+  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : reportText(args, renderSubmit, result))
   // Three outcomes, two exit codes: `ready` and `listed` are both healthy
   // states, and only a refusal is a 1.
   process.exit(result.outcome === "refused" ? 1 : 0)
@@ -215,7 +223,7 @@ async function cmdWatch(args) {
   }
   spinner.done()
   const render = result.mode === "list" ? renderWatchList : result.mode === "all" ? renderWatchAll : renderWatch
-  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : render(result))
+  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : reportText(args, render, result))
   process.exit(result.verdict?.state === "unknown" || result.summary?.unknown > 0 ? 2 : 0)
 }
 
@@ -250,7 +258,7 @@ async function cmdDoctor(args) {
   const spinner = spinnerFor(args)
   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))
+  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : reportText(args, renderDoctor, result))
   process.exit(result.problems ? 1 : 0)
 }
 
@@ -293,7 +301,7 @@ async function cmdVerify(args) {
   const blockingRules = section.invoked && section.official && !section.official.error
     ? (await consequence(requirePin(ROOT).dir, section.official)).selectivelyBlockingRules
     : []
-  emit(args, renderVerify(document, { blockingRules }))
+  emit(args, reportText(args, renderVerify, document, { blockingRules }))
 }
 
 async function cmdParity(args) {
@@ -420,7 +428,7 @@ async function cmdWeigh(args) {
   // The confirmation. The plan is printed either way, so the record says
   // what was agreed to; the question is asked only at a terminal on both
   // ends, and --yes is the only other way past it.
-  narrate.write(`${renderPlan(plan, { colour: colourEnabled(narrate) }).join("\n")}\n`)
+  narrate.write(`${withOutputStream(narrate, () => renderPlan(plan, { colour: colourEnabled(narrate) })).join("\n")}\n`)
   if (!parsed.options.has("--yes")) {
     const interactive = !json && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)
     if (!interactive) notWeighed("not-confirmed", `this restarts the shell ${plan.restarts} times and edits shell.json for the duration; a pipe, an agent or --json cannot answer for the person whose shell it is.`, REMEDY["not-confirmed"], 2)
@@ -487,12 +495,15 @@ const [command, ...rest] = process.argv.slice(2)
 // stays empty on success, and never for setup, which is the fix.
 if (updateCheckEnabled({ command, args: rest, stdinTTY: process.stdin.isTTY, stdoutTTY: process.stdout.isTTY, stderrTTY: process.stderr.isTTY })) {
   const notice = await updateNotice({ repoRoot: ROOT, version: VERSION })
-  if (notice) process.stderr.write(`${wrap(notice, {}, styler(colourEnabled(process.stderr))).join("\n")}\n`)
+  if (notice) process.stderr.write(`${wrap(notice, { width: outputColumns(process.stderr) }, styler(colourEnabled(process.stderr))).join("\n")}\n`)
 }
 
 if (command !== "setup" && process.stderr.isTTY) {
   const notice = staleCompletionNotice({ version: VERSION })
-  if (notice) process.stderr.write(`${styler(colourEnabled(process.stderr))("label", notice)}\n`)
+  if (notice) {
+    const c = styler(colourEnabled(process.stderr))
+    process.stderr.write(`${wrap(notice, { width: outputColumns(process.stderr) }).map((line) => c("label", line)).join("\n")}\n`)
+  }
 }
 
 if (command === "setup") {
@@ -556,12 +567,12 @@ if (command === "setup") {
   // 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([
+  process.stderr.write(withOutputStream(process.stderr, () => [
     `${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"))
+    renderSummary({ stream: process.stderr, colour: colourEnabled(process.stderr), heading: false }),
+  ].join("\n")))
   process.exit(2)
 }

package/tools/marketplace/report.mjs

@@ -18,7 +18,7 @@
 // screen, and the last screen is the one a person is looking at.
 
 import {
-  action, colourEnabled, COLUMNS, continuation, field, GUTTER, labelled, mark, section, STEP, styler, verdict, width, wrap,
+  action, colourEnabled, outputColumns, continuation, field, GUTTER, labelled, mark, section, STEP, styler, verdict, width, wrap,
 } from "./style.mjs"
 import { withHomeAbbreviated } from "./paths.mjs"
 import { watchIssueTitle } from "./watch.mjs"
@@ -42,7 +42,11 @@ function stateOf(check) {
 export function head(state, id, source, c) {
   const left = `${mark(state, c)}${c("name", id)}`
   const tag = c("punctuation", `[${source}]`)
-  const gap = Math.max(2, COLUMNS - width(left) - width(tag))
+  const columns = outputColumns()
+  if (width(left) + width(tag) + 2 > columns) {
+    return `${left}\n${wrap(`[${source}]`, { indent: GUTTER }).map((line) => c("punctuation", line)).join("\n")}`
+  }
+  const gap = columns - width(left) - width(tag)
   return `${left}${" ".repeat(gap)}${tag}`
 }
 
@@ -78,7 +82,7 @@ function commandLines(command, c) {
       units.push(word)
     }
   }
-  const room = COLUMNS - STEP - " \\".length
+  const room = outputColumns() - STEP - " \\".length
   const lines = []
   let line = ""
   for (const unit of units) {

package/tools/marketplace/style.mjs

@@ -115,9 +115,8 @@ export function code(role) {
 // --- geometry ---------------------------------------------------------------
 
 /**
- * The width everything is composed for. Eighty columns is the contract: a
- * check's why-paragraph, a remedy, a refusal and the help all wrap inside it,
- * and tests/unit/style.test.mjs renders every report and measures. The one
+ * The stable width for pipes and files. Terminals use their current column
+ * count, up to MAX_COLUMNS so wide windows still have readable prose. The one
  * thing exempt is the marketplace's own baseline report, which is printed
  * verbatim because rewrapping somebody else's attestation would be editing it.
  *
@@ -125,6 +124,23 @@ export function code(role) {
  * `overflows` below is the measurement, and it is the one both test files use.
  */
 export const COLUMNS = 80
+export const MAX_COLUMNS = 120
+
+let compositionStream = null
+
+/** Resolve at rendering time, so a resized terminal's next output uses its new width. */
+export function outputColumns(stream = compositionStream || process.stdout) {
+  return stream?.isTTY && Number.isFinite(stream.columns) && stream.columns >= 1
+    ? Math.min(MAX_COLUMNS, Math.floor(stream.columns))
+    : COLUMNS
+}
+
+/** Scope synchronous composition to its destination, including files and stderr. */
+export function withOutputStream(stream, render) {
+  const previous = compositionStream
+  compositionStream = stream
+  try { return render() } finally { compositionStream = previous }
+}
 
 /**
  * The indent scale, in columns. Three stops, and every line in the tool starts
@@ -327,7 +343,7 @@ export function overflows(line, total = COLUMNS) {
 // --- composition ------------------------------------------------------------
 
 /**
- * Wrap prose to the contract width, and paint it.
+ * Wrap prose to the destination width, and paint it.
  *
  * `indent` is the column the text starts in and is part of the width, which is
  * the bug the earlier version had: it wrapped at 78 and then indented by 7, and
@@ -346,7 +362,7 @@ export function overflows(line, total = COLUMNS) {
  * @param {(name: string, text: string) => string} [c]
  * @returns {string[]} lines, indented and painted
  */
-export function wrap(text, { indent = 0, width: total = COLUMNS, first = indent } = {}, c = styler(false)) {
+export function wrap(text, { indent = 0, width: total = outputColumns(), first = indent } = {}, c = styler(false)) {
   // A word is a run of non-spaces, or a backticked span with whatever
   // punctuation clings to it: "(`omakit pin`)." is one word.
   const words = String(text).match(/[^\s`]*`[^`]*`[^\s`]*|\S+/g) || []
@@ -422,7 +438,7 @@ export function continuation(value, c) {
  * under itself. There is exactly one of these under any failure, and it is the
  * only line in the tool that starts with an arrow, so it can be found by shape.
  */
-export function action(text, c, { indent = GUTTER, width: total = COLUMNS } = {}) {
+export function action(text, c, { indent = GUTTER, width: total = outputColumns() } = {}) {
   // Painted after wrapping, and all of it cyan: the whole line is the thing
   // to do, so a backticked word inside it has nothing to stand out from.
   const lines = wrap(text, { indent: indent + 2, width: total })
@@ -449,11 +465,11 @@ export function labelled(label, text, c, { indent = GUTTER } = {}) {
  * grey. It is the same shape the wordmark uses (the name, then its rule), so a
  * section of a report and the front door of the tool are drawn by one idea.
  */
-export function section(title, c, { width: total = COLUMNS } = {}) {
+export function section(title, c, { width: total = outputColumns() } = {}) {
   return [c("heading", title), c("punctuation", DENSITY.floor.repeat(total))]
 }
 
 /** A rule with no heading, the same floor, for a wordmark or a block that names itself. */
-export function rule(c, { width: total = COLUMNS, tint = "punctuation" } = {}) {
+export function rule(c, { width: total = outputColumns(), tint = "punctuation" } = {}) {
   return c(tint, DENSITY.floor.repeat(total))
 }

package/tools/marketplace/usage.mjs

@@ -7,7 +7,7 @@
 
 import { UNAUTHENTICATED_LIMIT } from "./github.mjs"
 import { MARKETPLACE_PIN } from "./pin.mjs"
-import { colourEnabled, paintProse, STEP, styler } from "./style.mjs"
+import { colourEnabled, paintProse, STEP, styler, withOutputStream, wrap } from "./style.mjs"
 
 /**
  * "Safe" means one thing, everywhere it appears: this runs on your own
@@ -208,16 +208,40 @@ export function paintSignature(signature, c) {
  *
  * @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)}`)
+function commandSignatures(command) {
+  const signatures = []
+  for (const line of [].concat(command.signature)) {
+    if (line.startsWith("omakit ")) signatures.push(line)
+    else signatures[signatures.length - 1] += ` ${line}`
   }
-  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`
+  return signatures
+}
+
+function signatureLines(signature, c) {
+  // A placeholder or bracketed optional argument stays whole, like the
+  // backticked typeable spans used by the shared wrapper.
+  const grouped = signature.replace(/\[[^\]]+\]|<[^>]+>(?:@<[^>]+>)?/g, (part) => `\`${part}\``)
+  return wrap(grouped, { indent: STEP * 3, first: STEP }).map((line) => paintSignature(line, c))
+}
+
+export function renderSummary({ stream = process.stdout, colour = colourEnabled(stream), heading = true } = {}) {
+  return withOutputStream(stream, () => {
+    const c = styler(colour)
+    const out = heading ? [`${c("typeable.bold", "omakit")}${c("punctuation", ":")} ${TAGLINE}`, ""] : []
+    if (stream.isTTY && heading) out.splice(0, 1, ...wrap(out[0]))
+    for (const command of COMMANDS) {
+      if (stream.isTTY) out.push(...signatureLines([].concat(command.signature)[0], c))
+      else out.push(`${INDENT}${paintSignature([].concat(command.signature)[0], c)}`)
+    }
+    out.push("")
+    if (stream.isTTY) {
+      out.push(...wrap("`omakit help` is the same list with what each command does, and what it reads. `omakit setup` is the one to run first.", { indent: STEP }, c))
+    } else {
+      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`
+  })
 }
 
 /**
@@ -225,23 +249,29 @@ export function renderSummary({ colour = colourEnabled(), heading = true } = {})
  *   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}`, ""] : []
+export function renderUsage({ stream = process.stdout, colour = colourEnabled(stream), heading = true } = {}) {
+  return withOutputStream(stream, () => {
+    const c = styler(colour)
+    const out = heading ? [`${c("typeable.bold", "omakit")}${c("punctuation", ":")} ${TAGLINE}`, ""] : []
+    if (stream.isTTY && heading) out.splice(0, 1, ...wrap(out[0]))
 
-  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)}`)
+    for (const command of COMMANDS) {
+      if (stream.isTTY) {
+        for (const signature of commandSignatures(command)) out.push(...signatureLines(signature, c))
+        out.push(...wrap(command.lines.join(" "), { indent: STEP * 3 }, c))
+      } else {
+        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("")
-  }
 
-  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`
+    if (stream.isTTY) out.push(...signatureLines(TARGET_NOTE, c))
+    else out.push(`${INDENT}${paintSignature(TARGET_NOTE, c)}`)
+    out.push("")
+    out.push(c("heading", "GitHub access:"))
+    if (stream.isTTY) out.push(...wrap(AUTHENTICATION.join(" "), { indent: STEP }, c))
+    else for (const line of AUTHENTICATION) out.push(`${INDENT}${paintProse(line, c)}`)
+    return `${out.join("\n")}\n`
+  })
 }

package/tools/weigh/confirm.mjs

@@ -5,7 +5,7 @@
 // typed here is written anywhere.
 
 import { createInterface } from "node:readline"
-import { action, colourEnabled, COLUMNS, styler } from "../marketplace/style.mjs"
+import { action, colourEnabled, outputColumns, styler } from "../marketplace/style.mjs"
 
 /**
  * The question as it is written to the terminal: the arrow line, wrapped
@@ -20,7 +20,7 @@ import { action, colourEnabled, COLUMNS, styler } from "../marketplace/style.mjs
  * @param {{ width?: number }} [options]
  * @returns {string} every line, joined, ending in `[y/N]: `
  */
-export function renderQuestion(question, c, { width = COLUMNS } = {}) {
+export function renderQuestion(question, c, { width = outputColumns() } = {}) {
   return `${action(`${question} [y/N]:`, c, { indent: 0, width }).join("\n")} `
 }
 
@@ -28,7 +28,7 @@ export function renderQuestion(question, c, { width = COLUMNS } = {}) {
  * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream, colour?: boolean, question: string, width?: number }} options
  * @returns {Promise<boolean>} true only for `y` or `yes`, in any case; an empty line and the end of stdin are no
  */
-export function askYes({ input = process.stdin, output = process.stderr, colour = colourEnabled(output), question, width = COLUMNS }) {
+export function askYes({ input = process.stdin, output = process.stderr, colour = colourEnabled(output), question, width = outputColumns(output) }) {
   const c = styler(colour)
   return new Promise((resolve) => {
     const rl = createInterface({ input, terminal: false })