@timqi/pier 0.0.1

package/dist/boards/pier.css

@@ -0,0 +1,445 @@
+/* pier.css — the one stylesheet every Board can link, served at
+   /boards/_assets/pier.css. Classless on purpose: plain semantic HTML must
+   look finished, so a board needs no build step and no framework. A handful of
+   named helpers cover the shapes a report actually asks for. */
+
+:root {
+  --bg: #fbfbfa;
+  --fg: #1f2328;
+  --muted: #6a737d;
+  --line: #e4e4e2;
+  --card: #ffffff;
+  --accent: #4f46e5;
+  --code-bg: #f4f4f3;
+  /* Semantic palette: colour encodes meaning (good / attention / problem),
+     never decoration. Boards are presentations, so these are first-class. */
+  --good: #0f7b4f;
+  --warn: #a25b00;
+  --bad: #b42318;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #16181c;
+    --fg: #e6e7e9;
+    --muted: #9aa0a6;
+    --line: #2c2f36;
+    --card: #1c1f24;
+    --accent: #8b87f7;
+    --code-bg: #22262c;
+    --good: #4ade80;
+    --warn: #fbbf24;
+    --bad: #f87171;
+  }
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+}
+
+/* The page fills a desktop window and reflows down to a phone: the canvas
+   widens with the viewport so tables, KPI rows and split layouts get room,
+   while running prose keeps a readable measure (--measure) instead of
+   stretching into 150-character lines. */
+body {
+  --measure: 46rem;
+  margin: 0 auto;
+  max-width: 46rem;
+  padding: 2rem 1.15rem 5rem;
+  background: var(--bg);
+  color: var(--fg);
+  font: 16px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans",
+    "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif;
+}
+
+@media (min-width: 64rem) {
+  body {
+    max-width: 62rem;
+    padding: 2.5rem 2rem 5rem;
+  }
+}
+
+@media (min-width: 100rem) {
+  body {
+    max-width: 76rem;
+  }
+}
+
+/* Top-level prose only — inside a card, callout or column the box is the
+   measure already. */
+body > p,
+body > ul,
+body > ol,
+body > dl,
+body > blockquote {
+  max-width: var(--measure);
+}
+
+.hero .lede,
+.hero > p {
+  max-width: var(--measure);
+}
+
+h1,
+h2,
+h3,
+h4 {
+  line-height: 1.25;
+  margin: 2.2rem 0 0.6rem;
+  font-weight: 640;
+  letter-spacing: -0.01em;
+}
+
+h1 {
+  margin-top: 0;
+  font-size: 1.75rem;
+}
+h2 {
+  font-size: 1.3rem;
+}
+h3 {
+  font-size: 1.08rem;
+}
+h4 {
+  font-size: 1rem;
+  color: var(--muted);
+}
+
+p,
+ul,
+ol,
+dl,
+pre,
+table,
+blockquote,
+figure {
+  margin: 0 0 1rem;
+}
+
+ul,
+ol {
+  padding-left: 1.35rem;
+}
+li + li {
+  margin-top: 0.25rem;
+}
+
+a {
+  color: var(--accent);
+  text-underline-offset: 2px;
+}
+
+strong {
+  font-weight: 640;
+}
+
+hr {
+  height: 0;
+  margin: 2rem 0;
+  border: 0;
+  border-top: 1px solid var(--line);
+}
+
+blockquote {
+  padding: 0.15rem 0 0.15rem 0.9rem;
+  border-left: 3px solid var(--line);
+  color: var(--muted);
+}
+
+code,
+kbd,
+samp {
+  padding: 0.1em 0.32em;
+  border-radius: 4px;
+  background: var(--code-bg);
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+  font-size: 0.875em;
+}
+
+pre {
+  overflow-x: auto;
+  padding: 0.85rem 1rem;
+  border-radius: 8px;
+  background: var(--code-bg);
+  line-height: 1.5;
+}
+
+pre code {
+  padding: 0;
+  background: none;
+  font-size: 0.85rem;
+}
+
+/* Tables scroll inside themselves rather than widening the page on a phone. */
+table {
+  display: block;
+  width: 100%;
+  overflow-x: auto;
+  border-collapse: collapse;
+  font-size: 0.94rem;
+}
+
+th,
+td {
+  padding: 0.45rem 0.7rem;
+  border-bottom: 1px solid var(--line);
+  text-align: left;
+  vertical-align: top;
+}
+
+th {
+  font-size: 0.78rem;
+  font-weight: 620;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--muted);
+  white-space: nowrap;
+}
+
+/* Zebra rows: a comparison table is the most common board content, and this
+   is what makes a long one scannable. */
+tbody tr:nth-child(even) {
+  background: color-mix(in oklab, var(--fg) 3.5%, transparent);
+}
+
+tbody tr:last-child td {
+  border-bottom: 0;
+}
+
+td:has(+ td:last-child),
+td:last-child {
+  font-variant-numeric: tabular-nums;
+}
+
+img,
+svg,
+video {
+  max-width: 100%;
+  height: auto;
+}
+
+details {
+  margin: 0 0 1rem;
+  padding: 0.7rem 0.9rem;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--card);
+}
+
+summary {
+  cursor: pointer;
+  font-weight: 560;
+}
+
+details[open] summary {
+  margin-bottom: 0.6rem;
+}
+
+footer {
+  margin-top: 3rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--line);
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
+/* --- helpers: the shapes a report keeps needing ------------------------- */
+
+.muted {
+  color: var(--muted);
+}
+
+/* One-sentence answer under the title, before any detail. */
+.lede {
+  font-size: 1.08rem;
+  line-height: 1.5;
+  color: var(--muted);
+}
+
+.good {
+  color: var(--good);
+}
+.warn {
+  color: var(--warn);
+}
+.bad {
+  color: var(--bad);
+}
+
+/* Right-align and tabulate a numeric column: `<td class="num">`. */
+.num {
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+
+.card {
+  padding: 0.9rem 1.1rem;
+  margin: 0 0 1rem;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: var(--card);
+}
+
+/* A status card reads at a glance from across the room. */
+.card.good,
+.card.warn,
+.card.bad,
+.card.info {
+  border-left: 3px solid var(--c);
+  background: color-mix(in oklab, var(--c) 7%, var(--card));
+}
+.card.good {
+  --c: var(--good);
+}
+.card.warn {
+  --c: var(--warn);
+}
+.card.bad {
+  --c: var(--bad);
+}
+.card.info {
+  --c: var(--accent);
+}
+
+/* Opening block: title, one-line answer, and the numbers that matter. */
+.hero {
+  margin: 0 0 1.75rem;
+  padding: 1.4rem 1.5rem;
+  border-radius: 14px;
+  background: color-mix(in oklab, var(--accent) 9%, var(--card));
+}
+.hero h1 {
+  margin-bottom: 0.4rem;
+}
+.hero > :last-child {
+  margin-bottom: 0;
+}
+
+/* Two columns that become one on a phone — before/after, text + aside. */
+.split {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr));
+  margin: 0 0 1rem;
+}
+
+/* Auto-fitting so a KPI row reflows to one column on a phone with no query. */
+.grid {
+  display: grid;
+  gap: 0.75rem;
+  grid-template-columns: repeat(auto-fit, minmax(11rem, 1fr));
+  margin: 0 0 1rem;
+}
+
+.kpi {
+  display: block;
+  font-size: 1.65rem;
+  font-weight: 650;
+  line-height: 1.15;
+  letter-spacing: -0.02em;
+  font-variant-numeric: tabular-nums;
+}
+
+.tag {
+  display: inline-block;
+  padding: 0.08em 0.5em;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: var(--card);
+  font-size: 0.78rem;
+  color: var(--muted);
+  white-space: nowrap;
+}
+
+/* Status colour on tags, cards and callouts. Pair it with a word — colour
+   alone fails in print, in dark mode and for colour-blind readers. */
+.tag.good,
+.tag.warn,
+.tag.bad,
+.tag.info {
+  border-color: currentColor;
+  color: var(--c);
+  background: color-mix(in oklab, var(--c) 12%, transparent);
+}
+.tag.good {
+  --c: var(--good);
+}
+.tag.warn {
+  --c: var(--warn);
+}
+.tag.bad {
+  --c: var(--bad);
+}
+.tag.info {
+  --c: var(--accent);
+}
+
+/* The takeaway box: what the reader must not miss. */
+.callout {
+  --c: var(--accent);
+  margin: 0 0 1rem;
+  padding: 0.75rem 1rem;
+  border-left: 3px solid var(--c);
+  border-radius: 0 8px 8px 0;
+  background: color-mix(in oklab, var(--c) 8%, transparent);
+}
+.callout > :last-child {
+  margin-bottom: 0;
+}
+.callout.good {
+  --c: var(--good);
+}
+.callout.warn {
+  --c: var(--warn);
+}
+.callout.bad {
+  --c: var(--bad);
+}
+
+/* Proportion bar — the honest chart for "share of total" inside a table,
+   with no library and no SVG: `<span class="bar" style="--v:62%"></span>`. */
+.bar {
+  display: block;
+  min-width: 3rem;
+  height: 0.45rem;
+  border-radius: 999px;
+  background: color-mix(in oklab, var(--fg) 10%, transparent);
+}
+.bar::after {
+  content: "";
+  display: block;
+  width: var(--v, 0);
+  height: 100%;
+  border-radius: inherit;
+  background: var(--c, var(--accent));
+}
+.bar.good {
+  --c: var(--good);
+}
+.bar.warn {
+  --c: var(--warn);
+}
+.bar.bad {
+  --c: var(--bad);
+}
+
+@media print {
+  body {
+    max-width: none;
+    padding: 0;
+    background: #fff;
+  }
+  details {
+    break-inside: avoid;
+  }
+  details:not([open]) > *:not(summary) {
+    display: revert;
+  }
+}

package/dist/channels/chains.js

@@ -0,0 +1,67 @@
+// Ordering: one promise chain per conversation.
+//
+// Messages from different chats are handled concurrently — a slow download must
+// not stall another group — but messages within one chat strictly in arrival
+// order, because a steer overtaking the message it interrupts reorders the
+// conversation.
+//
+// Two rules live here because both adapters got to write them once and neither
+// should write them twice:
+//
+//  - Every link needs its own `catch`. One rejected handler otherwise poisons
+//    the chain and silences that chat for the life of the process — an ordering
+//    mechanism that fails closed, permanently.
+//  - `drain()` is bounded. `runtime.reload()` runs on the Console's save, so a
+//    stuck handler must not hold that request open.
+export class Chains {
+    log;
+    maxActive;
+    active = new Map();
+    constructor(log, 
+    /**
+     * How many conversations may be in flight before a new one queues behind an
+     * existing chain. Bounds concurrency (open sockets, downloads); a transport
+     * that can also slow its source down should do that separately.
+     */
+    maxActive = Infinity) {
+        this.log = log;
+        this.maxActive = maxActive;
+    }
+    get size() {
+        return this.active.size;
+    }
+    /** Append to a conversation's chain, dropping the entry once it drains. */
+    run(key, task) {
+        const mine = this.active.get(key);
+        // A conversation with a chain already waits on itself; only a new one has
+        // to wait for a slot. `active` is non-empty whenever the cap is hit, so the
+        // race always settles.
+        const start = mine ??
+            (this.active.size >= this.maxActive
+                ? Promise.race(this.active.values()).catch(() => { })
+                : Promise.resolve());
+        const next = start
+            .then(task)
+            .catch((err) => this.log(`handler failed in ${key}: ${String(err)}`));
+        this.active.set(key, next);
+        void next.then(() => {
+            if (this.active.get(key) === next)
+                this.active.delete(key);
+        });
+    }
+    /** Wait for the oldest in-flight chain — the backpressure primitive. */
+    oldest() {
+        return Promise.race(this.active.values()).catch(() => { });
+    }
+    /**
+     * Let in-flight work finish before a replacement adapter starts, but never
+     * wait forever: two adapters handling one message would prompt twice, and a
+     * hung handler holding up a config save is worse than either.
+     */
+    async drain(timeoutMs) {
+        await Promise.race([
+            Promise.allSettled(this.active.values()),
+            new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+        ]);
+    }
+}

package/dist/channels/chunk.js

@@ -0,0 +1,28 @@
+// Splitting a long turn into sendable messages.
+//
+// Every platform caps a message, and the index arithmetic for "cut at the last
+// blank line that fits, else the last newline, else mid-text" is fiddly enough
+// that having it twice is having it wrong once. The cap and any per-platform
+// repair (Slack re-balances code fences across the cut) stay with the renderer.
+/**
+ * Cut `text` into pieces of at most `max` characters, preferring a blank line,
+ * then a newline, then the hard limit. A cut lands mid-text only when there is
+ * no break in the second half of the window — better a blunt split than a
+ * dropped turn.
+ */
+export function chunkText(text, max) {
+    if (text.length <= max)
+        return [text];
+    const parts = [];
+    let rest = text;
+    while (rest.length > max) {
+        const window = rest.slice(0, max);
+        const cut = Math.max(window.lastIndexOf("\n\n"), window.lastIndexOf("\n"));
+        const at = cut > max / 2 ? cut : max;
+        parts.push(rest.slice(0, at).trimEnd());
+        rest = rest.slice(at).trimStart();
+    }
+    if (rest)
+        parts.push(rest);
+    return parts;
+}

package/dist/channels/commands.js

@@ -0,0 +1,28 @@
+// Slash commands in IM text, parsed once for every platform.
+//
+// Every chat platform types commands the same way and mangles them slightly
+// differently: Telegram appends `@botname` when several bots share a group,
+// clients add stray whitespace, and users capitalise. One parser so an adapter
+// never re-derives "is this a command" and the answer never drifts between
+// platforms.
+/**
+ * Parse a command out of one inbound message. Whitespace on both ends is
+ * dropped first, then a leading `/` is required: anything else is ordinary
+ * text and must reach the agent untouched.
+ */
+export function parseCommand(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("/"))
+        return null;
+    // Args are taken verbatim, not re-joined from split words: a path or a
+    // sentence must survive with its own spacing intact.
+    const match = /^\/(\S+)[ \t]*([\s\S]*)$/.exec(trimmed);
+    const [name = "", target] = (match?.[1] ?? "").split("@");
+    if (!name)
+        return null; // a bare "/" is not a command
+    return {
+        name: name.toLowerCase(),
+        args: match?.[2] ?? "",
+        ...(target ? { target } : {}),
+    };
+}