@catalyst-cloud/cli 0.15.2 → 0.15.4

package/dist/onboard-values.js

@@ -0,0 +1,47 @@
+import { loadConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { selectedOnboardTeam } from "./onboard-existing.js";
+import { valuesFacts } from "./ready-copy.js";
+const waiting = (reason, evidence) => ({
+    state: "waiting",
+    reason,
+    ...(evidence ? { evidence } : {}),
+});
+/** The selected team's `required_values` readiness check decides this step. It passes when the
+ * selected repositories declare no required value, or every one has a value. Nothing here reads,
+ * imports or prints a value: a missing one is named, with the page where it is set. A stale, absent
+ * or unknown check waits, so the step never claims values it could not see. */
+export function onboardValuesAdapter() {
+    return {
+        check: async (ctx, journal, signal) => {
+            const cfg = loadConfig(ctx.home);
+            const teamId = selectedOnboardTeam(journal);
+            if (!cfg || !teamId)
+                return waiting("required_values_unverified");
+            let loaded;
+            try {
+                loaded = await loadContract(ctx, cfg, { refresh: true, signal });
+            }
+            catch {
+                return waiting(signal?.aborted ? "interrupted" : "required_values_unverified");
+            }
+            if (loaded.source === "cache")
+                return waiting("required_values_unverified");
+            const readiness = loaded.doc.teams.find((team) => team.id === teamId)?.readiness;
+            const fresh = readiness?.checkedAt != null &&
+                readiness.expiresAt != null &&
+                readiness.expiresAt > ctx.now().getTime();
+            const check = fresh
+                ? readiness.checks.find((row) => row.id === "required_values")
+                : undefined;
+            if (check?.state === "pass")
+                return { state: "done", evidence: { team: teamId } };
+            if (check?.state !== "fail")
+                return waiting("required_values_unverified");
+            return waiting("required_values_missing", {
+                team: teamId,
+                requiredValues: JSON.stringify(valuesFacts(check)),
+            });
+        },
+    };
+}

package/dist/onboard.js

@@ -10,7 +10,7 @@ import { onboardJsonView, TIMED_OUT_REASONS } from "./setup-onboard-copy.js";
 import { standalonePlan, standalonePlanNotes, } from "./onboard-standalone-copy.js";
 import { CliError, UsageError } from "./errors.js";
 import { onboardFileSnapshot } from "./onboard-file-snapshot.js";
-import { onboardReasonText, onboardTeamKey, savedOnboardBaseUrl, } from "./onboard-next.js";
+import { dispatchStageName, onboardReasonText, onboardTeamKey, savedOnboardBaseUrl, } from "./onboard-next.js";
 import { parseBootstrapPlan, bootstrapPlanHash, bootstrapPlanLines, } from "./onboard-bootstrap.js";
 export const ONBOARD_STEPS = [
     "machine",
@@ -37,16 +37,33 @@ export const ONBOARD_STEPS = [
     "first-ticket",
     "ready",
 ];
+function dailyUpdateChoice(value) {
+    const row = object(value);
+    if (row?.state === "on" || row?.state === "off")
+        return { state: row.state };
+    if (row?.state === "skipped" && row.reason === "no_scheduler")
+        return { state: "skipped", reason: "no_scheduler" };
+    return undefined;
+}
+const identityLabel = (text) => text
+    .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 180);
+/** CTC-4680: who and where for the lines beside setup's mark, "user: …" and "workspace: …". */
+export function onboardHeaderIdentity(identity) {
+    const display = identity.display;
+    return {
+        user: identityLabel(display?.email || display?.personLabel || identity.membershipId),
+        workspace: identityLabel(display?.workspaceName || identity.account),
+    };
+}
 export function onboardIdentityLines(identity) {
     if (!identity)
         return [
             "Use an existing Catalyst account or accept your invitation before approving sign-in.",
         ];
-    const label = (text) => text
-        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ")
-        .replace(/\s+/g, " ")
-        .trim()
-        .slice(0, 180);
+    const label = identityLabel;
     const display = identity.display;
     const person = label(display?.personLabel || identity.membershipId);
     const email = display?.email ? label(display.email) : "";
@@ -104,7 +121,8 @@ export const ONBOARD_DEPENDENCIES = {
     projects: ["linear.team", "github.repos"],
     accounts: ["signin"],
     settings: ["projects"],
-    values: ["settings"],
+    // The cloud's required-values check reads the registered repositories, not a local checkout.
+    values: ["projects"],
     capacity: ["projects"],
     // The join token names the selected team's pool.
     runner: ["linear.team"],
@@ -127,7 +145,7 @@ const ADMIN_STEPS = new Set([
     "github.repos",
     "projects",
     "settings",
-    "values",
+    // `values` is not here: its check only reads, so a member's run finds missing values too.
     "capacity",
     "runner",
     "first-ticket",
@@ -147,9 +165,9 @@ export const ONBOARD_TITLES = {
     "github.personal": "Connect your GitHub account",
     "github.repos": "Choose repositories",
     projects: "Register your projects",
-    accounts: "Check coding accounts",
+    accounts: "Check AI accounts",
     settings: "Review repository settings",
-    values: "Import selected local values",
+    values: "Check the repository's values",
     capacity: "Check runner capacity",
     runner: "Run Catalyst's work on this machine",
     daemon: "Check optional local sync",
@@ -251,6 +269,10 @@ function normalizeStep(value, fallbackAt) {
         "repository",
         "installation",
         "ticket",
+        // The team's dispatch stage name, as the contract gave it.
+        "stage",
+        // Admin-owned step ids a member's run found unfinished.
+        "admin",
         "cursor",
         "lag",
         "heartbeatAgeMs",
@@ -288,6 +310,8 @@ function normalizeStep(value, fallbackAt) {
         "org",
         "url",
         "actor",
+        // CTC-4716: which AI accounts the workspace may add, so the step's text offers only those.
+        "aiAccountKinds",
     ]) {
         const item = evidence?.[key];
         if (item === null ||
@@ -323,6 +347,7 @@ export function readOnboardJournal(path, cliVersion = "0.13.1", now = new Date()
         : typeof value.exitCode === "number"
             ? value.exitCode
             : null;
+    const dailyUpdate = dailyUpdateChoice(value.dailyUpdate);
     return {
         schema: 1,
         runId: typeof value.runId === "string" ? value.runId : randomUUID(),
@@ -354,6 +379,7 @@ export function readOnboardJournal(path, cliVersion = "0.13.1", now = new Date()
         ...(typeof value.localSync === "boolean"
             ? { localSync: value.localSync }
             : {}),
+        ...(dailyUpdate ? { dailyUpdate } : {}),
         operations: Object.fromEntries(Object.entries(object(value.operations) ?? {}).filter(([key, v]) => ONBOARD_STEPS.includes(key) &&
             typeof v === "string" &&
             /^[a-zA-Z0-9_.:-]{1,160}$/.test(v))),
@@ -573,7 +599,8 @@ function printPlan(ctx, journal, identity, options) {
         for (const line of onboardIdentityLines(identity))
             ctx.stdout(line);
     let group;
-    for (const row of standalonePlan(journal, options?.scope, options?.runner)) {
+    // Beside --json and headless output: the numbers JSON actions carry (CTC-4680).
+    for (const row of standalonePlan(journal, options?.scope, options?.runner, "json")) {
         if (row.group !== group) {
             ctx.stdout("");
             ctx.stdout(row.group);
@@ -629,14 +656,28 @@ export function stepSatisfied(step) {
     return (step?.state === "done" ||
         (step?.state === "skipped" &&
             (step.id === "legacy" ||
+                // Optional: a computer without the daily update still runs work.
+                step.id === "housekeeping" ||
                 step.reason === "member_scope" ||
                 (step.id === "daemon" && step.reason === "local_sync_not_selected") ||
                 (step.id === "runner" && step.reason === "runner_not_selected") ||
+                (step.id === "first-ticket" && step.reason === "first_ticket_skipped") ||
                 (step.id === "linear.automations" &&
                     step.reason === "automation_management_unavailable"))));
 }
+/** Optional work this computer or checkout cannot do. Work runs without it, so its wait never holds
+ * a complete setup. */
+const OPTIONAL_WAITS = new Set([
+    "settings_checkout_unverified",
+    "settings_approval_unverified",
+]);
+/** Satisfied, or an optional wait. What a complete setup needs of every step. */
+export function stepSettled(step) {
+    return (stepSatisfied(step) ||
+        (step?.state === "waiting" && OPTIONAL_WAITS.has(step.reason ?? "")));
+}
 /** Steps whose wait does not hold a full run's exit code: work runs without them. A failure still
- * fails the run, and the receipt's `complete` still needs them satisfied. Never used for gating. */
+ * fails the run, and the receipt's `complete` still needs them settled. Never used for gating. */
 export const ONBOARD_DEFERRED_STEPS = new Set([
     "settings",
     "values",
@@ -677,8 +718,11 @@ export function onboardNextActions(journal, baseUrl, only) {
         .filter((step) => (!only || step.id === only) && !stepSatisfied(step))
         .sort((a, b) => ONBOARD_STEPS.indexOf(a.id) - ONBOARD_STEPS.indexOf(b.id))
         .map((step) => `${ONBOARD_TITLES[step.id]}: ${onboardStepAction(journal, step, baseUrl)}`);
-    if (["projects", "accounts", "linear.adopt", "capacity"].every((id) => journalStep(journal, id)?.state === "done"))
-        lines.push(`Move a ticket in ${onboardTeamKey(journal) ?? "<TEAM KEY>"} to Todo; \`catalyst explain <ticket>\` says why it is or is not starting.`);
+    // A waiting first ticket already says to move a ticket, in its own line.
+    const firstTicket = journalStep(journal, "first-ticket");
+    if (["projects", "accounts", "linear.adopt", "capacity"].every((id) => journalStep(journal, id)?.state === "done") &&
+        firstTicket?.state !== "waiting")
+        lines.push(`Move a ticket in ${onboardTeamKey(journal) ?? "<TEAM KEY>"} to ${dispatchStageName(firstTicket?.evidence?.stage)}; \`catalyst explain <ticket>\` says why it is or is not starting.`);
     return lines;
 }
 function requireMatchingIdentity(journal, identity) {
@@ -727,9 +771,10 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
     const only = typeof args.flags.only === "string"
         ? args.flags.only
         : undefined;
+    // A member's values check reads the selected team, so without --team it waits on the same skip.
     const memberScopeSkips = (id) => ADMIN_STEPS.has(id) ||
-        (id === "linear.team" &&
-            only !== "linear.team" &&
+        ((id === "linear.team" || id === "values") &&
+            only !== id &&
             typeof args.flags.team !== "string");
     const resume = typeof args.flags["resume-from"] === "string"
         ? args.flags["resume-from"]
@@ -1069,7 +1114,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         journal.complete =
             !only &&
                 code === 0 &&
-                ONBOARD_STEPS.every((id) => stepSatisfied(journalStep(journal, id)));
+                ONBOARD_STEPS.every((id) => stepSettled(journalStep(journal, id)));
         writeOnboardJournal(statePath, journal);
         if (args.json)
             ctx.stdout(JSON.stringify(journal));
@@ -1442,7 +1487,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
             journal.complete =
                 !only &&
                     code === 0 &&
-                    ONBOARD_STEPS.every((id) => stepSatisfied(journalStep(journal, id)));
+                    ONBOARD_STEPS.every((id) => stepSettled(journalStep(journal, id)));
             const unfinished = journal.steps.filter((step) => !stepSatisfied(step));
             if (!only &&
                 !refused &&

package/dist/ready-copy.js

@@ -65,6 +65,93 @@ function slotList(slots) {
 function origin(baseUrl) {
     return baseUrl.replace(/\/+$/, "");
 }
+const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const REPOSITORY = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
+const identifiers = (value) => Array.isArray(value)
+    ? value.filter((name) => typeof name === "string" && NAME.test(name))
+    : [];
+const unresolvedFacts = (value) => Array.isArray(value)
+    ? value.flatMap((row) => typeof row?.name === "string" && NAME.test(row.name) && identifiers(row.references).length
+        ? [{ name: row.name, references: identifiers(row.references) }]
+        : [])
+    : [];
+/** The declared names a failing check carries, kept in the receipt for the fix line: which variables
+ * need a value, which refer to a secret with no value, and the same for the team's other
+ * repositories. Identifiers and repository names only. */
+export function valuesFacts(value) {
+    const row = (value ?? {});
+    return {
+        names: identifiers(row.names),
+        unresolved: unresolvedFacts(row.unresolved),
+        repos: Array.isArray(row.repos)
+            ? row.repos.flatMap((note) => typeof note?.repo === "string" && REPOSITORY.test(note.repo)
+                ? [{ repo: note.repo, names: identifiers(note.names), unresolved: unresolvedFacts(note.unresolved) }]
+                : [])
+            : [],
+    };
+}
+/** Where the named variables get their values. Names only: nothing here reads or prints a value. */
+function setValuesFix(baseUrl, names) {
+    return baseUrl
+        ? `set ${names.join(", ")} on the repository's Environment page: open ${origin(baseUrl)}/settings/projects, then the project, then the repository`
+        : `set ${names.join(", ")} on the repository's Environment page in Catalyst's project settings`;
+}
+function nameList(v) {
+    return Array.isArray(v)
+        ? v.filter((n) => typeof n === "string" && n.length > 0)
+        : [];
+}
+/** Entries whose name and references are both present; anything malformed is dropped, not guessed. */
+function unresolvedList(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.flatMap((u) => {
+        if (typeof u !== "object" || u === null)
+            return [];
+        const { name, references } = u;
+        const refs = nameList(references);
+        return typeof name === "string" && name.length > 0 && refs.length > 0
+            ? [{ name, references: refs }]
+            : [];
+    });
+}
+function unresolvedLine(u) {
+    const which = u.references.length === 1 ? "which has" : "which have";
+    return `${u.name} refers to ${u.references.join(", ")}, ${which} no value, so Catalyst can't start work there`;
+}
+/** A team check's fix line. A check that carries `names` (CTC-3561: `required_values`, contract
+ *  1.24.0) names them and where to set them. CTC-3606: it also names each `unresolved` variable and
+ *  the reference with no value, and each other repository's missing names from `repos[]`. `unresolved`
+ *  is a subset of `names` (the variable exists; its reference does not), so those are not told to be
+ *  "set". Every field is optional so an older cloud still works. Everything printed is a declared
+ *  identifier or a repository name, never a value, and nothing here reads a value. Any other check
+ *  keeps the generic line. Shared with setup's values step, which has no web address when the
+ *  saved login has none. */
+export function valuesFix(base, c) {
+    const unresolved = unresolvedList(c.unresolved);
+    const unresolvedNames = new Set(unresolved.map((u) => u.name));
+    const names = nameList(c.names).filter((n) => !unresolvedNames.has(n));
+    const parts = [];
+    if (names.length > 0)
+        parts.push(setValuesFix(base, names));
+    for (const u of unresolved)
+        parts.push(unresolvedLine(u));
+    for (const note of Array.isArray(c.repos) ? c.repos : []) {
+        if (typeof note !== "object" ||
+            note === null ||
+            typeof note.repo !== "string" ||
+            note.repo.length === 0)
+            continue;
+        const repoUnresolved = unresolvedList(note.unresolved);
+        const skip = new Set(repoUnresolved.map((u) => u.name));
+        const missing = nameList(note.names).filter((n) => !skip.has(n));
+        if (missing.length > 0)
+            parts.push(`${note.repo} is missing ${missing.join(", ")}`);
+        for (const u of repoUnresolved)
+            parts.push(`in ${note.repo}, ${unresolvedLine(u)}`);
+    }
+    return parts.length === 0 ? null : parts.join(". ");
+}
 /** The team's own page in Catalyst settings, optionally one of its sub-pages (`map`, `adopt`). */
 export function teamPage(baseUrl, key, sub) {
     return `${origin(baseUrl)}/settings/linear-teams/${encodeURIComponent(key)}${sub ? `/${sub}` : ""}`;

package/dist/ready.js

@@ -15,7 +15,7 @@ import { FIRST_STAMPED_VERSION } from "./skill-shape.js";
 import { installedBundleVersion } from "./skills.js";
 import { onboardingReadyReport, observeCloudOnboarding, } from "./onboard-ready.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
-import { dispatchGateCopy, teamCheckCopy, teamPage, whoFixes } from "./ready-copy.js";
+import { dispatchGateCopy, teamCheckCopy, teamPage, valuesFix, whoFixes } from "./ready-copy.js";
 import { onboardStatePath, readOnboardJournal } from "./onboard.js";
 export { semverOlder };
 /** `ready`'s own wording for the replica. It never recommends adopting the replica — until the
@@ -112,62 +112,6 @@ export function catalystCommandCheck(env, platform = process.platform) {
             "Keep using catalyst-skills on this machine, or put the npm global bin directory ahead of that one on PATH.",
     };
 }
-function nameList(v) {
-    return Array.isArray(v)
-        ? v.filter((n) => typeof n === "string" && n.length > 0)
-        : [];
-}
-/** Entries whose name and references are both present; anything malformed is dropped, not guessed. */
-function unresolvedList(v) {
-    if (!Array.isArray(v))
-        return [];
-    return v.flatMap((u) => {
-        if (typeof u !== "object" || u === null)
-            return [];
-        const { name, references } = u;
-        const refs = nameList(references);
-        return typeof name === "string" && name.length > 0 && refs.length > 0
-            ? [{ name, references: refs }]
-            : [];
-    });
-}
-function unresolvedLine(u) {
-    const which = u.references.length === 1 ? "which has" : "which have";
-    return `${u.name} refers to ${u.references.join(", ")}, ${which} no value, so Catalyst can't start work there`;
-}
-/** A team check's fix line. A check that carries `names` (CTC-3561: `required_values`, contract
- *  1.24.0) names them and where to set them. CTC-3606: it also names each `unresolved` variable and
- *  the reference with no value, and each other repository's missing names from `repos[]`. `unresolved`
- *  is a subset of `names` (the variable exists; its reference does not), so those are not told to be
- *  "set". Every field is optional so an older cloud still works. Everything printed is a declared
- *  identifier or a repository name, never a value, and nothing here reads a value. Any other check
- *  keeps the generic line. */
-function valuesFix(base, c) {
-    const unresolved = unresolvedList(c.unresolved);
-    const unresolvedNames = new Set(unresolved.map((u) => u.name));
-    const names = nameList(c.names).filter((n) => !unresolvedNames.has(n));
-    const parts = [];
-    if (names.length > 0) {
-        parts.push(`set ${names.join(", ")} on the repository's Environment page: open ${base}/settings/projects, then the project, then the repository`);
-    }
-    for (const u of unresolved)
-        parts.push(unresolvedLine(u));
-    for (const note of Array.isArray(c.repos) ? c.repos : []) {
-        if (typeof note !== "object" ||
-            note === null ||
-            typeof note.repo !== "string" ||
-            note.repo.length === 0)
-            continue;
-        const repoUnresolved = unresolvedList(note.unresolved);
-        const skip = new Set(repoUnresolved.map((u) => u.name));
-        const missing = nameList(note.names).filter((n) => !skip.has(n));
-        if (missing.length > 0)
-            parts.push(`${note.repo} is missing ${missing.join(", ")}`);
-        for (const u of repoUnresolved)
-            parts.push(`in ${note.repo}, ${unresolvedLine(u)}`);
-    }
-    return parts.length === 0 ? null : parts.join(". ");
-}
 export async function readyReport(ctx, deps) {
     const checks = [];
     const facts = deps.runtime ?? detectRuntime();

package/dist/setup-brand.js

@@ -0,0 +1,202 @@
+/** Ring order runs from the top tip, round the back, to the bottom tip, as in the brand script. */
+export const RING = [
+    [3, 0],
+    [2, 0],
+    [1, 0],
+    [0, 1],
+    [0, 2],
+    [1, 3],
+    [2, 3],
+    [3, 3],
+];
+export const CORE = [
+    [1, 1],
+    [2, 1],
+    [1, 2],
+    [2, 2],
+];
+export const MARK_SIZE = { dot: 3, gap: 1 };
+export const markSpan = (size = MARK_SIZE) => 4 * size.dot + 3 * size.gap;
+export const markLines = (size = MARK_SIZE) => Math.ceil(markSpan(size) / 2);
+const paintOf = (col, row) => RING.some(([c, r]) => c === col && r === row)
+    ? "ring"
+    : CORE.some(([c, r]) => c === col && r === row)
+        ? "core"
+        : null;
+/** The mark as a grid of square units, `markSpan` rows of half lines by `markSpan` columns. */
+export function markUnits(size = MARK_SIZE) {
+    const span = markSpan(size);
+    const pitch = size.dot + size.gap;
+    return Array.from({ length: span }, (_, y) => Array.from({ length: span }, (_, x) => x % pitch >= size.dot || y % pitch >= size.dot
+        ? null
+        : paintOf(Math.floor(x / pitch), Math.floor(y / pitch))));
+}
+const BRAND = {
+    ink: "#11100e",
+    cream: "#f1ebe2",
+    copper: "#d28e63",
+    rust: "#a9512f",
+};
+/** The brand rules: a cream C and copper core on dark, an ink C and rust core on light. */
+const PALETTES = {
+    dark: { ring: BRAND.cream, core: BRAND.copper },
+    light: { ring: BRAND.ink, core: BRAND.rust },
+};
+export function colourLevel(env, terminal) {
+    if (terminal.noColor)
+        return "none";
+    const force = env.FORCE_COLOR;
+    if (force !== undefined) {
+        if (force === "0" || force === "false")
+            return "none";
+        if (force === "" || force === "1" || force === "true")
+            return "16";
+        if (force === "2")
+            return "256";
+        if (force === "3")
+            return "truecolor";
+    }
+    if (env.NO_COLOR !== undefined || !terminal.tty)
+        return "none";
+    if (!env.TERM || env.TERM === "dumb")
+        return "none";
+    if (/^(truecolor|24bit)$/i.test(env.COLORTERM ?? ""))
+        return "truecolor";
+    return /256/.test(env.TERM) ? "256" : "16";
+}
+/** CI as most tools read it: set, and not "", "0" or "false". */
+export function inCi(env) {
+    return ![undefined, "", "0", "false"].includes(env.CI);
+}
+export const MARK_MIN_COLUMNS = 60;
+/**
+ * Why the mark is left off, or null to draw it. Off for every verb but setup, without a terminal,
+ * in CI, with --no-color or NO_COLOR or no colour at all, without UTF-8 (the blocks are UTF-8), and
+ * below 60 columns. The text lines are printed either way.
+ */
+export function markSkipped(options) {
+    const { env } = options;
+    if (!options.setup)
+        return "not catalyst setup";
+    if (!options.tty)
+        return "not a terminal";
+    if (inCi(env))
+        return "CI";
+    if (options.noColor)
+        return "--no-color";
+    if (env.NO_COLOR !== undefined)
+        return "NO_COLOR";
+    if (colourLevel(env, options) === "none")
+        return "no colour";
+    if (!/utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || ""))
+        return "not UTF-8";
+    if (options.columns < MARK_MIN_COLUMNS)
+        return "narrow";
+    return null;
+}
+const rgb = (hex) => [
+    Number.parseInt(hex.slice(1, 3), 16),
+    Number.parseInt(hex.slice(3, 5), 16),
+    Number.parseInt(hex.slice(5, 7), 16),
+];
+const distance = (a, b) => (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2;
+/** The nearest xterm-256 colour: the 6×6×6 cube or the 24-step grey ramp, whichever is closer. */
+export function nearest256(hex) {
+    const colour = rgb(hex);
+    const levels = [0, 95, 135, 175, 215, 255];
+    const step = (v) => levels.reduce((best, l, i) => (Math.abs(l - v) < Math.abs(levels[best] - v) ? i : best), 0);
+    const [ri, gi, bi] = colour.map(step);
+    const avg = (colour[0] + colour[1] + colour[2]) / 3;
+    const greyIndex = Math.min(23, Math.max(0, Math.round((avg - 8) / 10)));
+    const grey = 8 + 10 * greyIndex;
+    return distance([levels[ri], levels[gi], levels[bi]], colour) <=
+        distance([grey, grey, grey], colour)
+        ? 16 + 36 * ri + 6 * gi + bi
+        : 232 + greyIndex;
+}
+/** xterm's default 16 colours, as SGR foreground codes. */
+const XTERM16 = [
+    [30, [0, 0, 0]],
+    [31, [205, 0, 0]],
+    [32, [0, 205, 0]],
+    [33, [205, 205, 0]],
+    [34, [0, 0, 238]],
+    [35, [205, 0, 205]],
+    [36, [0, 205, 205]],
+    [37, [229, 229, 229]],
+    [90, [127, 127, 127]],
+    [91, [255, 0, 0]],
+    [92, [0, 255, 0]],
+    [93, [255, 255, 0]],
+    [94, [92, 92, 255]],
+    [95, [255, 0, 255]],
+    [96, [0, 255, 255]],
+    [97, [255, 255, 255]],
+];
+/**
+ * The nearest of xterm's 16 default colours. Plain distance puts copper nearest grey (90), and the
+ * core is the mark's one accent, so the core picks from the coloured entries only: copper is then
+ * yellow (33) and rust red (31). The ring takes plain distance: cream is white (37), ink black (30).
+ */
+export function nearest16(hex, accent = false) {
+    const colour = rgb(hex);
+    const greys = [30, 37, 90, 97];
+    return XTERM16.filter(([code]) => !accent || !greys.includes(code)).reduce((best, entry) => distance(entry[1], colour) < distance(best[1], colour) ? entry : best)[0];
+}
+/**
+ * The SGR parameters for one of the mark's colours on a `theme` background, as a foreground or a
+ * background. With 16 colours the core is also bold, which most terminals draw brighter.
+ */
+export function markColour(paint, theme, level, layer = "fg") {
+    const hex = PALETTES[theme][paint];
+    const lead = layer === "fg" ? 38 : 48;
+    if (level === "truecolor")
+        return `${lead};2;${rgb(hex).join(";")}`;
+    if (level === "256")
+        return `${lead};5;${nearest256(hex)}`;
+    const code = nearest16(hex, paint === "core") + (layer === "fg" ? 0 : 10);
+    return paint === "core" && layer === "fg" ? `1;${code}` : String(code);
+}
+/**
+ * Units to terminal lines, two unit rows per line: both halves set is a full block (or an upper
+ * half block on the lower colour's background when they differ), one half is a half block, neither
+ * is a space. Each run of one glyph colour is closed with a reset.
+ */
+export function unitLines(units, theme, level) {
+    const lines = [];
+    for (let y = 0; y < units.length; y += 2) {
+        const upper = units[y];
+        const lower = units[y + 1] ?? [];
+        let out = "";
+        let open = "";
+        for (let x = 0; x < upper.length; x++) {
+            const [top, bottom] = [upper[x] ?? null, lower[x] ?? null];
+            const sgr = top && bottom && top !== bottom
+                ? `${markColour(top, theme, level)};${markColour(bottom, theme, level, "bg")}`
+                : top || bottom
+                    ? markColour((top ?? bottom), theme, level)
+                    : "";
+            if (sgr !== open) {
+                if (open)
+                    out += "\u001b[0m";
+                if (sgr)
+                    out += `\u001b[${sgr}m`;
+                open = sgr;
+            }
+            out +=
+                !top && !bottom
+                    ? " "
+                    : top && bottom && top === bottom
+                        ? "█"
+                        : top
+                            ? "▀"
+                            : "▄";
+        }
+        lines.push(open ? `${out}\u001b[0m` : out);
+    }
+    return lines;
+}
+/** The mark, one string per terminal line: `markLines` lines of `markSpan` columns. */
+export function pixelNucleusLines(theme, level, size = MARK_SIZE) {
+    return unitLines(markUnits(size), theme, level);
+}