npm - @adrrr/tarmac - Versions diffs - 0.8.0 → 0.9.0 - Mend

@adrrr/tarmac 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/dist/render.js CHANGED Viewed

@@ -192,6 +192,10 @@ export function renderTable({ rows, health }) {
         warns.push(`! ${health.snapshotsUnreadable} snapshot file(s) present but unreadable — schema may have moved, check for a newer tarmac`);
     if ((health.snapshotsDuplicates ?? 0) > 0)
         warns.push(`! ${health.snapshotsDuplicates} snapshot file(s) claim a session id another file already claims — the freshest was kept`);
+    // Not folded into the line above: a name that is not a file is a directory somebody put
+    // something in, and sending them to look for a newer tarmac would be advice for the schema.
+    if ((health.snapshotsNotFiles ?? 0) > 0)
+        warns.push(`! ${health.snapshotsNotFiles} name(s) in the snapshot directory are not regular files — stepped over unread, never opened`);
     // Covers both "not allowed to look" and "there is nothing there to look at", so the words
     // have to fit an errno as well as a path that points nowhere.
     if (health.snapshotsError)
@@ -365,6 +369,9 @@ export function renderLive(fleet) {
     if ((health.snapshotsDuplicates ?? 0) > 0) {
         warnings.push(`${health.snapshotsDuplicates} snapshot file(s) claim a session id another file already claims — the freshest reading was kept and the other ignored. Two wrappers may be writing into the same directory.`);
     }
+    if ((health.snapshotsNotFiles ?? 0) > 0) {
+        warnings.push(`${health.snapshotsNotFiles} name(s) in the snapshot directory are not regular files — a directory, a link or a named pipe wearing a snapshot's name is stepped over rather than opened, because reading one can wait for ever. Whatever else is there was read as usual.`);
+    }
     if (health.snapshotsError) {
         // A permission error is ours to report, not the user's to be blamed for.
         warnings.push(`The snapshot directory could not be used — ${health.snapshotsError}. Context readings are unavailable, and this is not an install problem.`);
@@ -576,7 +583,7 @@ function ago(ms) {
     const m = Math.round(s / 60);
     return m < 60 ? `${m}m` : `${Math.round(m / 60)}h`;
 }
-export function renderPage(fleet, view = 'table', { historyEnabled = false } = {}) {
+export function renderPage(fleet, view = 'table', { historyEnabled = false, demo = false } = {}) {
     // The header's copy. `renderLive` below renders its own, out of this same fleet and through
     // this same function — two calls of one pure renderer over one reading, which is what keeps
     // the pair the reader sees and the pair the script will copy up from being two accounts.
@@ -598,7 +605,15 @@ export function renderPage(fleet, view = 'table', { historyEnabled = false } = {
          font:14px/1.5 ui-sans-serif,-apple-system,"Segoe UI",sans-serif; }
   header { display:flex; align-items:baseline; gap:1rem; flex-wrap:wrap; margin-bottom:1rem; }
   h1 { font-size:1.1rem; margin:0; letter-spacing:.02em; }
-  .meta { color:var(--dim); font-size:.85rem; }
+  .meta { color:var(--dim); font-size:.85rem; }${demo
+        ? `
+  /* The demo marker. It borrows the warning's hues rather than the dim chrome the tabs use:
+     what it says is not chrome, and a badge a reader's eye files with the furniture is a badge
+     that is not in the screenshot as far as anybody looking at the screenshot is concerned.
+     Shipped only on a demo, so a plain serve is byte-for-byte the page it always was. */
+  .demo-tag { background:var(--warnbg); color:var(--warn); border:1px solid currentColor; border-radius:99px;
+              padding:.05rem .55rem; font-size:.75rem; font-weight:600; letter-spacing:.02em; white-space:nowrap; }`
+        : ''}
   /* Honest, and out of the way of the fleet: three of these stacked at full padding pushed
      the table below the fold on a laptop, which is its own kind of hidden. */
   .warn { background:var(--warnbg); color:var(--warn); border:1px solid currentColor; border-radius:6px;
@@ -1077,7 +1092,13 @@ ${HISTORY_PHONE_CSS}  }
 </style>
 </head><body data-view="${view}">
 <header>
-  <h1>tarmac</h1>
+  <h1>tarmac</h1>${demo
+        ? `
+  <!-- Beside the title, in the shell, and never quiet. The one thing a screenshot of this page
+       must not be able to do is pass for a real fleet, and the reader who can be misled is not
+       the one running the serve — it is whoever is sent the picture afterwards. -->
+  <span class="demo-tag" role="status">demo data &mdash; an invented fleet</span>`
+        : ''}
   <!-- Links, not buttons: the view survives a reload, a bookmark and a browser with
        JavaScript off — the state of a page whose own noscript banner promises it is still
        readable. Both views are in the fragment below either way, so switching costs the
@@ -1137,7 +1158,7 @@ ${HISTORY_PHONE_CSS}  }
   <input type="range" id="scrub" min="0" max="0" step="1" value="0" disabled aria-label="Replay position">
   <div class="covers" id="covers"></div>
 </div>
-${view === 'history' ? renderHistoryView({ historyEnabled }) : ''}
+${view === 'history' ? renderHistoryView({ historyEnabled, demo }) : ''}
 <script>${pageScript(view)}</script>${view === 'history' ? `\n<script>${historyScript()}</script>` : ''}
 </body></html>
 `;

package/dist/server.js CHANGED Viewed

@@ -6,7 +6,7 @@ import http from 'node:http';
 import { reason, renderLive, renderPage } from './render.js';
 import { hostName, SOURCE_PHRASE } from './config.js';
 import { createHistory, HISTORY_CADENCE_MS } from './history.js';
-import { HISTORY_RANGES, readRange } from './history-range.js';
+import { HISTORY_RANGES } from './history-range.js';
 /**
  * On every answer, including the refusals and the 500s. The page swaps what this port returns
  * into `innerHTML`, and loopback proves where an answer came from, never who wrote it: a
@@ -16,13 +16,21 @@ import { HISTORY_RANGES, readRange } from './history-range.js';
  * failures carry it too: their text is what it quotes as the reason.
  */
 const IDENTITY = { 'x-tarmac': '1' };
+/**
+ * A range read that never came back, kept apart from a range read that failed: one is a journal
+ * that answered with a broken file, the other a directory nothing came out of at all. The
+ * handler answers 500 for the first and 504 for the second, and a reader is sent to two
+ * different places by them.
+ */
+class JournalTimeout extends Error {
+}
 /** The addresses that serve the shell, and which view each one opens on. */
 const PAGES = new Map([
     ['/', 'table'],
     ['/map', 'map'],
     ['/history', 'history'],
 ]);
-export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS, trustedHosts = [], store = null, rangeCacheMs = 60_000, report = (line) => console.error(line), }) {
+export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS, trustedHosts = [], store = null, rangeCacheMs = 60_000, readJournal = (s, range, now) => s.read(range, now), rangeDeadlineMs = 30_000, report = (line) => console.error(line), history = createHistory({ since: Date.now(), cadence: sampleEveryMs }), demo = false, }) {
     // Normalised HERE rather than trusted to arrive that way. This is the last thing between a
     // foreign origin and the fleet, so it owns both sides of its own comparison — the config
     // parser cuts a name the same way, and neither leans on the other having done it.
@@ -33,17 +41,23 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
     // reachable from a flag, a variable or a file gets here empty; that is the parser's promise,
     // and this is the guard not resting on it.
     const trusted = new Set(trustedHosts.map((h) => hostName(h.trim()).toLowerCase()).filter((h) => h !== ''));
+    // The page wears a badge; this is the same fact for machines. The HTML shell is one of four
+    // surfaces this port answers, and the other three are JSON and a fragment a consumer may
+    // archive or forward — where an invented fleet with nothing on it saying so becomes a real
+    // one the moment the response body travels alone. On every answer for the same reason
+    // IDENTITY is: the refusals and the 500s of a demo serve are the demo's too.
+    const identity = demo ? { ...IDENTITY, 'x-tarmac-demo': '1' } : IDENTITY;
     // Which rule refused, decided once. With hosts named, "loopback hosts only" would read as a
     // flag that never took; with none, this is the sentence it has always been, to the byte. The
     // Host itself is never quoted back: it is the one string on the request the caller wrote.
     const refusal = trusted.size === 0
         ? 'tarmac serves loopback hosts only\n'
         : 'tarmac serves loopback and trusted hosts only\n';
-    // What this serve has already read, kept for a day and never written down. `since` is the
-    // moment this server was made, not the first sample that landed: the span it covers is how
-    // long the process has been up, and an hour of it with nothing in it is a fact worth
-    // showing rather than an empty record pretending to be a young one.
-    const history = createHistory({ since: Date.now(), cadence: sampleEveryMs });
+    // What this serve has already read, kept for a day and never written down, is the ring above
+    // — its `since` is the moment it was made, not the first sample that landed, so the span it
+    // covers is how long the process has been up and an hour of it with nothing in it is a fact
+    // worth showing rather than an empty record pretending to be a young one.
+    //
     // One at a time. `claude agents --json` has a 15s deadline of its own, and a fleet slower
     // than a slot would otherwise be answered with a queue of processes instead of one missed
     // minute — the tick that finds a read still running counts the slot and stands down.
@@ -89,10 +103,15 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
         if (held !== undefined && (held.at === null || now - held.at < rangeCacheMs))
             return held.reading;
         const entry = { at: null, reading: undefined };
-        // Read once per range per minute rather than per request: `stats()` walks the directory, and
-        // a journal that stopped at its cap stays stopped for hours, so a minute-old answer to that
-        // question is the same answer.
-        entry.reading = readRange({ dir: store.dir, range, now, capped: store.stats().capped }).then((answer) => {
+        // Asked of the STORE, which owns both ends of its own journal: this route never learns where
+        // the days come from, so the invented week `serve --demo` carries arrives here as an ordinary
+        // range read and the demo gets no rendering path of its own (#156). Seeded past the store
+        // only by the suite, whose stuck read no real directory can produce (#136).
+        //
+        // Read once per range per minute rather than per request: the store walks its directory to
+        // answer, and a journal that stopped at its cap stays stopped for hours, so a minute-old
+        // answer to that question is the same answer.
+        entry.reading = readJournal(store, range, now).then((answer) => {
             entry.at = Date.now();
             return answer;
         }, (e) => {
@@ -106,6 +125,36 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
         ranges.set(range, entry);
         return entry.reading;
     };
+    /**
+     * The same read, with a deadline on the REQUEST rather than on the read.
+     *
+     * A read that does not come back is not a read that can be taken back: nothing cancels a
+     * blocked `open`, and the thread it holds is held until the kernel hands it over. So the entry
+     * stays in the cache, and every request that arrives while it is out gives up on its own clock
+     * instead of starting a second read of a directory that is already not answering. If it ever
+     * does land, it is served — to whoever is asking then. The price is written down rather than
+     * hidden: an entry that never settles is never dated, so that range answers 504 for the life
+     * of the process, and a restart is what reads it again.
+     *
+     * What this bounds is the WAIT. `rangeOf` measures the directory synchronously before the read
+     * begins (`readdirSync`, then a `statSync` a file), so a volume that has stopped answering
+     * stops the event loop this timer would have to fire on. A deadline cannot save a thread that
+     * is not running; only asynchronous work is bounded here, and that is the whole of the claim.
+     */
+    const answerRange = (store, range) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new JournalTimeout(`nothing came back from ${store.dir} in ${rangeDeadlineMs}ms`)), rangeDeadlineMs);
+        // The nominal path pays one timer and no latency: the answer clears it on the way past.
+        // The unref is the belt, and a narrow one worth naming rather than overselling: while the
+        // request is out its own socket holds the loop, so the only window this covers is a
+        // deadline still counting after the socket has gone. `bounded.ts` carries the same line
+        // for a case that IS reachable in a test, and has one; this one has no test of its own.
+        timer.unref();
+        // Attached, rather than raced with `Promise.race`: this is what marks the shared read's own
+        // failure handled when it arrives after the request that started it has already given up.
+        rangeOf(store, range)
+            .then(resolve, reject)
+            .finally(() => clearTimeout(timer));
+    });
     const sample = async () => {
         // First, and outside the try: the journal's lock says this process is alive, which is a
         // fact about the tick and not about the reading. A collector that has been throwing for
@@ -135,7 +184,7 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
         // reader trusted on top of that is a name, exactly: matched whole, never as a prefix, a
         // suffix or a pattern, so trusting one host can never be trusting a family of them.
         if (!isLoopbackHost(req.headers.host) && !isTrustedHost(req.headers.host, trusted)) {
-            res.writeHead(403, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+            res.writeHead(403, { ...identity, 'content-type': 'text/plain; charset=utf-8' });
             res.end(refusal);
             return;
         }
@@ -146,7 +195,7 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
         // spawned; a client that sends no label (curl, a script) is left alone.
         const site = req.headers['sec-fetch-site'];
         if (typeof site === 'string' && site !== 'same-origin' && site !== 'none') {
-            res.writeHead(403, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+            res.writeHead(403, { ...identity, 'content-type': 'text/plain; charset=utf-8' });
             res.end('tarmac serves same-origin requests only\n');
             return;
         }
@@ -163,7 +212,7 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
             url.pathname !== '/live' &&
             url.pathname !== '/api/fleet' &&
             url.pathname !== '/api/history') {
-            res.writeHead(404, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+            res.writeHead(404, { ...identity, 'content-type': 'text/plain; charset=utf-8' });
             res.end('not found\n');
             return;
         }
@@ -179,7 +228,7 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
                 if (!isRange(asked)) {
                     // The value is not quoted back, for the reason the refused Host is not: it is a string
                     // the caller wrote, and the page swaps a refusal's text into `innerHTML` as its reason.
-                    res.writeHead(400, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+                    res.writeHead(400, { ...identity, 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
                     res.end(`tarmac serves /api/history for 24h, ${HISTORY_RANGES.join(' and ')}; no range is the last 24h\n`);
                     return;
                 }
@@ -187,17 +236,22 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
                 // would draw a flat line over a month the fleet was busy for.
                 let body;
                 try {
-                    body = store === null ? { enabled: false, range: asked } : { enabled: true, ...(await rangeOf(store, asked)) };
+                    body = store === null ? { enabled: false, range: asked } : { enabled: true, ...(await answerRange(store, asked)) };
                 }
                 catch (e) {
                     // Nothing in `readRange` is allowed to throw, and this is the seam that keeps a day
                     // when something does from being a request that hangs instead of an answer.
-                    res.writeHead(500, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+                    //
+                    // A read that has not come back is the other failure, and it is not the same news: 500
+                    // is a read that came back with a failure, 504 is a read that did not come back at all
+                    // — the first sends a reader to the file, the second to the directory. The page prints
+                    // whichever sentence arrives as the reason the charts are empty.
+                    res.writeHead(e instanceof JournalTimeout ? 504 : 500, { ...identity, 'content-type': 'text/plain; charset=utf-8' });
                     res.end(`tarmac could not read the fleet journal:\n${reason(e)}\n`);
                     return;
                 }
                 res.writeHead(200, {
-                    ...IDENTITY,
+                    ...identity,
                     'content-type': 'application/json; charset=utf-8',
                     'cache-control': 'no-store',
                 });
@@ -207,7 +261,7 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
         }
         if (url.pathname === '/api/history') {
             res.writeHead(200, {
-                ...IDENTITY,
+                ...identity,
                 'content-type': 'application/json; charset=utf-8',
                 'cache-control': 'no-store',
             });
@@ -239,18 +293,18 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
                 body =
                     url.pathname === '/live'
                         ? renderLive(fleet)
-                        : renderPage(fleet, PAGES.get(url.pathname), { historyEnabled: store !== null });
+                        : renderPage(fleet, PAGES.get(url.pathname), { historyEnabled: store !== null, demo });
             }
         }
         catch (e) {
             // Say why. A dashboard that goes blank when its source breaks teaches nothing.
-            res.writeHead(500, { ...IDENTITY, 'content-type': 'text/plain; charset=utf-8' });
+            res.writeHead(500, { ...identity, 'content-type': 'text/plain; charset=utf-8' });
             res.end(`tarmac could not read the fleet:\n${reason(e)}\n`);
             return;
         }
         // A page whose entire claim is freshness must not be served from a cache: a restored tab
         // re-running the script over stale HTML would re-stamp it "updated just now".
-        res.writeHead(200, { ...IDENTITY, 'content-type': type, 'cache-control': 'no-store' });
+        res.writeHead(200, { ...identity, 'content-type': type, 'cache-control': 'no-store' });
         res.end(body);
     });
     // The sampler lives exactly as long as the serving does. Started at construction it kept
@@ -266,6 +320,13 @@ export function createFleetServer({ collect, sampleEveryMs = HISTORY_CADENCE_MS,
     server.on('listening', () => {
         if (sampler !== null)
             return;
+        // A demo does not sample. Its collector answers one frozen minute, so every tick would
+        // record that same minute into the ring and push a minute of the invented day off the far
+        // end: one slot a minute, until a serve left up overnight is showing 1440 copies of one
+        // reading. That is the flat chart this whole feature exists to replace. The record it was
+        // handed is the record it keeps, and the live view stays honestly dated either way.
+        if (demo)
+            return;
         // The journal's retention, applied before the first line of this run is written and once a
         // local day after that (the store keeps that half itself). Here rather than in the CLI so
         // that the store `serve` prunes with is, provably, the store `serve` writes with: a `serve`

package/dist/sessions.js CHANGED Viewed

@@ -55,8 +55,14 @@ export function parseAgents(text) {
             health.noSessionId += 1;
             continue;
         }
-        const sessionId = typeof entry.sessionId === 'string' ? entry.sessionId : null;
-        if (!sessionId)
+        // The empty string is not an id, and it is a `string`, so the type check alone let it
+        // through: counted as missing here, then carried as `''` to every reader and written to
+        // the journal as `sid: ''`. Each reader neutralises that value its own way (#137) —
+        // normalising at the source says it once, and stops counting the same nameless entry
+        // both here and as unfilable downstream. Absent reads `null` like every field here;
+        // sessionId alone also folds `''` into absent, an empty id being no id at all.
+        const sessionId = typeof entry.sessionId === 'string' && entry.sessionId !== '' ? entry.sessionId : null;
+        if (sessionId === null)
             health.noSessionId += 1;
         // A background agent carries no `status` at all — its word is under `state`. `status`
         // still wins where both are present: it comes from the agent's own process, and `state`

package/dist/snapshots.js CHANGED Viewed

@@ -86,11 +86,13 @@ export function readSnapshots(dir, { now = Date.now() } = {}) {
             snapshots,
             dirError: code === 'ENOENT' ? null : `${code}: ${dir}`,
             unreadable: 0,
+            notFiles: 0,
             duplicates: 0,
             dirMissing: code === 'ENOENT',
         };
     }
     let unreadable = 0;
+    let notFiles = 0;
     let duplicates = 0;
     for (const name of entries) {
         if (!name.endsWith('.json') || name.startsWith('.'))
@@ -99,7 +101,27 @@ export function readSnapshots(dir, { now = Date.now() } = {}) {
         let payload;
         let mtimeMs;
         try {
-            mtimeMs = fs.statSync(file).mtimeMs;
+            // The kind is asked BEFORE the open, and only a regular file is opened. What wears a
+            // snapshot's name is not this reader's to assume: the directory belongs to whoever owns
+            // the machine and a wrapper can be pointed at any of them, while `readFileSync` on a FIFO
+            // waits for someone to write to the other end — a wait with nothing to end it, on the
+            // loop under every surface tarmac has (#160).
+            //
+            // `lstat`, not `stat`, and not for the pipe: `stat` refuses a link to one exactly as this
+            // does. The one shape the two disagree about is a link to an ordinary file, and refusing
+            // that is the choice — a snapshot is what the wrapper wrote, and a link is a name someone
+            // else put there, aimed at something nobody told this reader about. The journal reader
+            // decides the same way for the same reason (#159); this is the hotter path.
+            //
+            // A check before an open is a race, and it stays one: nothing stops the name being
+            // replaced between the two. What that costs is bounded — one blocked read, on a directory
+            // somebody is racing — where reading the kind off the open would cost every read.
+            const stat = fs.lstatSync(file);
+            if (!stat.isFile()) {
+                notFiles += 1;
+                continue;
+            }
+            mtimeMs = stat.mtimeMs;
             payload = JSON.parse(fs.readFileSync(file, 'utf8'));
         }
         catch (e) {
@@ -108,15 +130,9 @@ export function readSnapshots(dir, { now = Date.now() } = {}) {
             // and a race with our own housekeeping rather than a payload we failed to parse.
             // Counting it made tarmac drive its own format-drift warning (up to 2675 phantom
             // unreadable on one read of a 20k directory, and `list --watch` and `serve` redraw
-            // often enough to be inside that window).
-            //
-            // The cost, said out loud: `statSync` follows symlinks, so a DANGLING one named like a
-            // snapshot is ENOENT too, and it goes silent forever — a permanent state skipped as if
-            // it were a passing race. Deliberate. There is no payload behind a dead link either,
-            // and telling the two apart (an `lstat` first) buys a warning about a file `ls` already
-            // shows. Note it is the opposite call from `reap.ts:75`, which lstats PRECISELY so a
-            // dead link is not ENOENT: it deletes, and `unlink` takes a link away just fine. Reader
-            // and reaper ask different questions of the same shape.
+            // often enough to be inside that window). A dead link named like a snapshot used to land
+            // here too, `statSync` having followed it — a permanent state skipped as a passing race;
+            // the kind check above refuses it by name now, and counts it.
             //
             // ENOENT only. A file we were not ALLOWED to open still counts, and must.
             if (e.code !== 'ENOENT')
@@ -134,7 +150,7 @@ export function readSnapshots(dir, { now = Date.now() } = {}) {
             duplicates += 1;
         snapshots.set(t.sessionId, already ? preferred(already, snapshot) : snapshot);
     }
-    return { snapshots, dirError: null, unreadable, duplicates, dirMissing: false };
+    return { snapshots, dirError: null, unreadable, notFiles, duplicates, dirMissing: false };
 }
 /**
  * Which of two snapshots claiming one session a reader is shown.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@adrrr/tarmac",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Fleet observability for Claude Code — reads documented surfaces only, never an internal format",
   "keywords": [
     "claude",
@@ -13,7 +13,7 @@
     "context-window"
   ],
   "license": "MIT",
-  "author": "Adrien Leboeuf",
+  "author": "adrrr",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/adrrr/tarmac.git"