@jals1212/ci-local-pi 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@ add or change behaviour and a patch version fixes.
 
 ## Unreleased
 
+## 0.5.0
+
+### Added
+
+- The status line of a finished run says when it ended, so an old result is
+  not taken for a new one: how long ago for its first hour
+  (`🚦 ci-local · ✗ failed at lint · 32s · 10m ago`), then the local time it
+  ended (`· 13:10`). (#58)
+
+## 0.4.0
+
+### Added
+
+- Herdr sidebar: in a Herdr pane, the status line is also the pane's `$ci`
+  metadata token while a run is in flight and for 5 minutes after it ends, so
+  a `["$ci"]` row in Herdr's Agents sidebar shows ci-local next to the
+  agent. Display only, refreshed with a 30-second TTL, and cleared when the
+  session ends. (#54)
+
 ## 0.3.1
 
 ### Fixed

package/README.md

@@ -24,8 +24,9 @@ literal `CI_PROJECT=`), it follows the events file of that project; it never
 runs ci-local or Docker itself:
 
 - **Status line**: `🚦 ci-local · ◌ queued · 2 ahead (erp-ci running)`, `🚦 ci-local · ⧗ [3/8] lint · 2m05s`,
-  then `🚦 ci-local · ✓ passed · 4m12s` or `🚦 ci-local · ✗ failed at lint · 2m10s` until
-  the next run. A run already over when a session starts shows only while its
+  then `🚦 ci-local · ✓ passed · 4m12s · 10m ago` or `🚦 ci-local · ✗ failed at lint · 2m10s · just now`
+  until the next run. A result says how long ago it ended for its first hour,
+  then the local time it ended (`· 13:10`). A run already over when a session starts shows only while its
   result is undelivered, like an unread message: it ended with no session of
   the repository open. Once a session has shown it finished, a later session
   (new or resumed) leaves it out, and a reload keeps it out unless that
@@ -35,6 +36,26 @@ runs ci-local or Docker itself:
   shows it where it lists extension statuses: Gentle Shell, for one, under
   **Integrations** in the sidebar's Status card (or in its bottom bar on a
   narrow terminal).
+- **Herdr sidebar**: in a [Herdr](https://herdr.dev) pane (`HERDR_ENV=1`,
+  `HERDR_PANE_ID`, `HERDR_SOCKET_PATH`), the status line is also the pane's
+  `ci` metadata token while a run is queued or running, and its result for 5
+  minutes after it ends. The token is display only: the agent's state in
+  Herdr does not change. It is reported again every 10 seconds with a
+  30-second TTL, so it goes away when Pi does. To show it, add a `$ci` row to
+  the Agents sidebar in Herdr's `config.toml`, then run `herdr server reload-config`:
+
+  ```toml
+  [ui.sidebar.agents]
+  rows = [
+    ["state_icon", "machine", "workspace", "tab"],
+    ["agent"],
+    [{ token = "$ci", rules = [
+      { contains = "✗", fg = "#f38ba8" },
+      { contains = "✓", fg = "#a6e3a1" },
+      { contains = "⧗", fg = "#f9e2af" },
+    ] }],
+  ]
+  ```
 - **Only the session's own runs** get the cards and the notification, and
   reach the agent: runs this session started. A run started from Pi's bash
   tool names its session (ci-local records Pi's `PI_SESSION_ID` as `session`

package/extensions/ci-local.ts

@@ -2,8 +2,9 @@
 // ci-local run in Pi's own UI, so neither the agent nor you write it by hand.
 //
 // - Status line: `🚦 ci-local · ⧗ [3/8] lint · 2m05s`, `🚦 ci-local · ◌ queued ·
-//   2 ahead (erp-ci running)`, then `🚦 ci-local · ✓ passed · 4m12s` / `🚦 ci-local ·
-//   ✗ failed at lint` until the next run (🚦 is ci-local's own emoji, see BRAND).
+//   2 ahead (erp-ci running)`, then `🚦 ci-local · ✓ passed · 4m12s · 10m ago` / `🚦 ci-local ·
+//   ✗ failed at lint · 2m10s · 13:10` (how long ago it ended, then from an
+//   hour on the time it ended) until the next run (🚦 is ci-local's own emoji, see BRAND).
 //   A run already over when a session starts is shown only if no session
 //   showed its result yet, like a message not yet delivered (createStatusLine).
 // - Cards and the agent: only for runs this session started, as Gentle AI's job
@@ -13,6 +14,9 @@
 //   this session's process (a background job, even orphaned). Another
 //   session's run in the same repository, or one started in a terminal, shows
 //   in the status line alone.
+// - Herdr: in a pane Herdr runs, the status line is also the pane's `$ci`
+//   metadata token while a run is in flight and for 5 minutes after it ends,
+//   so a `["$ci"]` row in Herdr's Agents sidebar shows it (display only).
 // - When a run starts: a card in the transcript when it is starting (or
 //   waiting for its turn), another when its steps start; for you only (session
 //   entries, never in the model's context, never repeated after a reload).
@@ -42,6 +46,8 @@ import {
   LAUNCH_WAIT_MS,
   WAKE_TEXT,
   cardContent,
+  createHerdrLine,
+  createHerdrPublisher,
   createDelivery,
   createStatusLine,
   createTracker,
@@ -49,6 +55,8 @@ import {
   eventsFileFor,
   exitCard,
   findProject,
+  herdrPane,
+  herdrSend,
   launchReport,
   launchRun,
   ownsRun,
@@ -98,6 +106,10 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
   // belongs to the session that started it; another session drops it.
   type Launch = ReturnType<typeof launchRun> & { seen: boolean; waiting: boolean; sessionId: string }
   const launches = new Map<number, Launch>()
+  // In a Herdr pane, the footer line is also the pane's `$ci` sidebar token
+  // (see createHerdrLine in core.js); null elsewhere. Read when a session
+  // starts following, so a test or a moved pane gets its own.
+  let herdr: { pane: string; socket: string; publisher: ReturnType<typeof createHerdrPublisher> } | undefined
 
   pi.on('agent_start', async () => {
     runActive = true
@@ -249,6 +261,11 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
     // already showed, and records each finished run it shows (see
     // createStatusLine in core.js).
     const statusLine = createStatusLine({ file, sessionId, reason })
+    const pane = herdrPane(process.env)
+    if (pane && (herdr?.pane !== pane.pane || herdr.socket !== pane.socket)) {
+      herdr = { ...pane, publisher: createHerdrPublisher({ send: herdrSend(pane) }) }
+    }
+    const herdrLine = pane ? createHerdrLine() : undefined
 
     const tick = () => {
       let run
@@ -259,6 +276,7 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
       }
       const { footer, changed } = statusLine.update(run)
       if (changed) ctx.ui.setStatus(KEY, footer)
+      if (herdrLine) herdr?.publisher.update(herdrLine.text(run))
       settleLaunches(run)
       // Only this session's own runs get cards and reach the agent, as Gentle
       // AI's job notices go only to the session that started the job. Another
@@ -336,6 +354,11 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
 
   pi.on('session_shutdown', async () => {
     stop()
+    // The sidebar token goes with the session (its TTL would end it anyway).
+    if (herdr) {
+      herdr.publisher.update(null)
+      await herdr.publisher.idle()
+    }
     startReason = undefined
     delete (globalThis as Record<symbol, unknown>)[FLAG]
   })

package/extensions/core.js

@@ -19,6 +19,7 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs'
+import { createConnection } from 'node:net'
 import { tmpdir } from 'node:os'
 import { dirname, isAbsolute, join } from 'node:path'
 
@@ -284,10 +285,30 @@ export function createStatusLine({ file, sessionId, reason }) {
   }
 }
 
-/** One short line for the footer: `🚦 ci-local · ✓ passed · 4m12s`. */
-export function footerText(state) {
+/**
+ * One short line for the footer: `🚦 ci-local · ✓ passed · 4m12s · 10m ago`. A
+ * finished run says when it ended (from its end event), so an old result is
+ * not taken for a new one: how long ago within the first hour, then the local
+ * HH:MM, which no longer changes. `now` is the time it is said at.
+ */
+export function footerText(state, now = Date.now()) {
   // The state's glyph sits by the state, after the name.
-  return `${BRAND} ci-local · ${GLYPHS[state.state] ?? GLYPHS.stopped} ${stateText(state)}`
+  const line = `${BRAND} ci-local · ${GLYPHS[state.state] ?? GLYPHS.stopped} ${stateText(state)}`
+  const at = FINISHED.has(state.state) ? endedText(state.end?.ts, now) : null
+  return at ? `${line} · ${at}` : line
+}
+
+/** Until then a result says how long ago it ended; after, the time it ended. */
+export const RELATIVE_END_MS = 60 * 60_000
+
+/** When a run ended, as the footer says it, or null without an end time. */
+function endedText(ts, now) {
+  const date = new Date(ts ?? '')
+  if (Number.isNaN(date.getTime())) return null
+  const age = now - date.getTime()
+  if (age < 60_000) return 'just now' // a clock a little ahead says so too
+  if (age < RELATIVE_END_MS) return `${Math.floor(age / 60_000)}m ago`
+  return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`
 }
 
 /** The state of a run in a few words, as the footer says it after its glyph. */
@@ -663,3 +684,153 @@ export function exitCard({ pid, code, signal = null, output, tail = outputTail(o
     },
   }
 }
+
+// Herdr (https://herdr.dev): in a pane Herdr runs, the footer line is also the
+// pane's `$ci` metadata token, so a row `["$ci"]` in Herdr's Agents sidebar
+// shows the run. A token is display only: it never touches the agent's state.
+
+/** The token's name, as a sidebar row names it: `$ci`. */
+export const HERDR_TOKEN = 'ci'
+/** Who reports the token. No sequence numbers: one sender, one report at a time. */
+export const HERDR_SOURCE = 'ci-local'
+/** Herdr drops the token this long after the last report: a Pi gone leaves nothing behind. */
+export const HERDR_TTL_MS = 30_000
+/** A token unchanged is reported again this often, well inside its TTL. */
+export const HERDR_REFRESH_MS = 10_000
+/** How long a run's result stays in the sidebar after the run ends. */
+export const HERDR_RESULT_MS = 5 * 60_000
+/** Herdr keeps at most this many characters of a token. */
+export const HERDR_TOKEN_MAX = 80
+
+/** The pane and socket of the Herdr pane this process runs in, or null outside one. */
+export function herdrPane(env = process.env) {
+  const pane = env.HERDR_PANE_ID?.trim()
+  const socket = env.HERDR_SOCKET_PATH?.trim()
+  return env.HERDR_ENV === '1' && pane && socket ? { pane, socket } : null
+}
+
+function clip(text) {
+  const chars = [...text]
+  return chars.length <= HERDR_TOKEN_MAX ? text : chars.slice(0, HERDR_TOKEN_MAX - 1).join('') + '…'
+}
+
+/**
+ * What the token says for a run: the footer line while it is in flight, and
+ * its result for HERDR_RESULT_MS after it ended (by its end event; a run that
+ * stopped without one, from when this session saw it stop). Null otherwise:
+ * no run, or a result older than that, or a run found already stopped.
+ */
+export function createHerdrLine({ now = Date.now } = {}) {
+  let flying // the key of the last run seen in flight
+  const endedAt = new Map()
+  return {
+    text(run) {
+      if (!run) return null
+      if (!FINISHED.has(run.state.state)) {
+        flying = run.key
+        return clip(footerText(run.state))
+      }
+      if (!endedAt.has(run.key)) {
+        const ended = Date.parse(run.state.end?.ts ?? '')
+        endedAt.clear()
+        endedAt.set(run.key, Number.isFinite(ended) ? ended : run.key === flying ? now() : null)
+      }
+      const ended = endedAt.get(run.key)
+      return ended !== null && now() - ended < HERDR_RESULT_MS ? clip(footerText(run.state, now())) : null
+    },
+  }
+}
+
+/** The socket request that sets the token (with its TTL), or clears it (null). */
+export function herdrReport(pane, value) {
+  const params = { pane_id: pane, source: HERDR_SOURCE, tokens: { [HERDR_TOKEN]: value } }
+  if (value !== null) params.ttl_ms = HERDR_TTL_MS
+  return { method: 'pane.report_metadata', params }
+}
+
+let herdrRequests = 0
+
+/**
+ * A sender of the token to Herdr's socket (one JSON line, one reply): resolves
+ * true when Herdr accepted it, false on any error or after `timeoutMs`.
+ */
+export function herdrSend({ pane, socket }, { timeoutMs = 2000 } = {}) {
+  return (value) =>
+    new Promise((resolve) => {
+      const id = `ci-local-${process.pid}-${++herdrRequests}`
+      let reply = ''
+      let done = false
+      const finish = (ok) => {
+        if (done) return
+        done = true
+        clearTimeout(timer)
+        conn.destroy()
+        resolve(ok)
+      }
+      const conn = createConnection(socket)
+      const timer = setTimeout(() => finish(false), timeoutMs)
+      timer.unref?.()
+      conn.on('connect', () => conn.write(JSON.stringify({ id, ...herdrReport(pane, value) }) + '\n'))
+      conn.on('data', (data) => {
+        reply += data
+        const end = reply.indexOf('\n')
+        if (end < 0) return
+        try {
+          const answer = JSON.parse(reply.slice(0, end))
+          finish(answer.id === id && answer.result?.type === 'ok')
+        } catch {
+          finish(false)
+        }
+      })
+      conn.on('error', () => finish(false))
+      conn.on('close', () => finish(false))
+    })
+}
+
+/**
+ * Keeps Herdr's token in step with `update(value)` (null clears it): a report
+ * when the value changes, again every HERDR_REFRESH_MS while it stays, one
+ * report at a time (the latest value waits for the one on its way). A failed
+ * report is tried again at the next update. `idle()` resolves once nothing is
+ * on its way.
+ */
+export function createHerdrPublisher({ send, now = Date.now, refreshMs = HERDR_REFRESH_MS }) {
+  let shown = null // what Herdr has
+  let sentAt = 0
+  let inFlight = null
+  let pending // the value to report once inFlight is done
+  const update = (value) => {
+    if (inFlight) {
+      pending = value
+      return
+    }
+    const due = value !== shown || (value !== null && now() - sentAt >= refreshMs)
+    if (!due) return
+    let sending
+    try {
+      sending = Promise.resolve(send(value))
+    } catch {
+      sending = Promise.resolve(false)
+    }
+    inFlight = sending
+      .catch(() => false)
+      .then((ok) => {
+        if (ok) {
+          shown = value
+          sentAt = now()
+        }
+        inFlight = null
+        if (pending !== undefined) {
+          const next = pending
+          pending = undefined
+          update(next)
+        }
+      })
+  }
+  return {
+    update,
+    async idle() {
+      while (inFlight) await inFlight
+    },
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/ci-local-pi",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Pi extension and skill for @jals1212/ci-local: the state of this repository's ci-local run in Pi's status line, cards and a read-only tool for the agent.",
   "license": "MIT",
   "author": "jals1212",

package/skills/ci-local/SKILL.md

@@ -4,7 +4,7 @@ description: "Trigger: ci-local, run CI locally, ci-local.config.sh, CI_PROJECT,
 license: MIT
 metadata:
   author: jals1212
-  version: "0.3.1"
+  version: "0.5.0"
 ---
 
 ## Activation Contract
@@ -18,7 +18,7 @@ Use when running, waiting on, reading, or configuring `ci-local` (`npx ci-local`
 - Unwatched runs are quiet: milestones and the summary on stdout, each step's output in its own log. From 0.5.0 that is the default without a terminal; before 0.5.0, add `--quiet`. Never add `--live` to a background run.
 - Do not touch the checkout while a run is in flight (no edits, no branch switch): the steps read it.
 - Never start a second run to "check" the first. Runs queue machine-wide by themselves (one Docker user at a time); a waiting run is normal, not a hang.
-- Read the result from the run itself: `PASSED:` / `FAILED at step:` and `Development stack untouched`. A changed development stack is a failure.
+- Read the result from the run itself: `PASSED:` / `FAILED at step:` / `STOPPED` (stopped on purpose, not a failure) and `Development stack untouched`. A changed development stack is a failure.
 - On failure, read only the failing step's log (named in the failure output or `--status`), not every log.
 - Everything a run creates carries the `$CI_PROJECT` prefix and the `$CI_LABEL` label; never hard-code another name, publish a port, or reuse a development container name. Local compose smokes use `-p <own-name>`.
 
@@ -45,7 +45,7 @@ Use when running, waiting on, reading, or configuring `ci-local` (`npx ci-local`
 
 ## Output Contract
 
-Report: project, commit, result line (`PASSED` / `FAILED at step`), total time, any `DEVIATES` lines, and whether the development stack was untouched.
+Report: project, commit, result line (`PASSED` / `FAILED at step` / `STOPPED`), total time, any `DEVIATES` lines, and whether the development stack was untouched.
 
 ## References