@cero-base/tools 0.8.4 → 0.8.5

package/bin/cero-tools.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { dial } from '../src/transport.js'
 import { connect } from '../src/connect.js'
-import { formatHandles, formatState, formatEvent, formatStats } from '../src/format.js'
+import { formatHandles, formatState, formatError, formatEvent, formatStats } from '../src/format.js'
 
 const arg = process.argv[2]
 if (!arg) {
@@ -14,12 +14,25 @@ const host = hostPart
 const port = Number(portPart)
 
 const socket = dial({ host, port })
+socket.on('error', (err) => {
+  console.error(
+    err.code === 'ECONNREFUSED'
+      ? `no tap on ${host ?? '127.0.0.1'}:${port} — is the app running with devtools()?`
+      : `connection error: ${err.message}`
+  )
+  process.exit(1)
+})
+
 const session = await connect(socket)
 
 console.log(formatHandles(await session.handles()))
 
 for (const ref of process.argv.slice(3)) {
-  console.log(formatState(ref, await session.get(ref)))
+  try {
+    console.log(formatState(ref, await session.get(ref)))
+  } catch (err) {
+    console.log(formatError(ref, err)) // a bad ref shouldn't kill the session
+  }
 }
 
 const events = session.events()

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@cero-base/tools",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Passive devtools for cero — observe data, events, and p2p/replication stats over a local out-of-band pipe.",
   "type": "module",
   "main": "./src/index.js",
+  "types": "./types/index.d.ts",
   "bin": {
     "cero-tools": "./bin/cero-tools.js"
   },
@@ -15,6 +16,7 @@
   },
   "files": [
     "src",
+    "types",
     "bin",
     "README.md",
     "LICENSE"
@@ -23,16 +25,27 @@
     "access": "public"
   },
   "exports": {
-    ".": "./src/index.js",
-    "./connect": "./src/connect.js",
-    "./stats": "./src/stats.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./connect": {
+      "types": "./types/connect.d.ts",
+      "default": "./src/connect.js"
+    },
+    "./stats": {
+      "types": "./types/stats.d.ts",
+      "default": "./src/stats.js"
+    }
   },
   "scripts": {
+    "build:types": "rm -rf types && tsc -p .",
+    "prepublishOnly": "npm run build:types",
     "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/cero": "^0.8.4",
-    "@cero-base/core": "^0.8.4",
+    "@cero-base/cero": "^0.8.5",
+    "@cero-base/core": "^0.8.5",
     "b4a": "^1.8.1",
     "bare-net": "^2.3.1",
     "compact-encoding": "^3.1.0",

package/src/format.js

@@ -1,6 +1,19 @@
 import b4a from 'b4a'
 
 const ROW_MAX = 80
+const E = '\x1b['
+const COLOR = !process.env.NO_COLOR && !!(process.stdout && process.stdout.isTTY)
+const paint = (code) => (s) => (COLOR ? `${E}${code}m${s}${E}0m` : String(s))
+const c = {
+  bold: paint(1),
+  dim: paint(2),
+  red: paint(31),
+  green: paint(32),
+  yellow: paint(33),
+  cyan: paint(36),
+  magenta: paint(35),
+  gray: paint(90)
+}
 
 function shortRow(row) {
   if (row == null) return ''
@@ -15,15 +28,15 @@ function shortKey(key) {
 }
 
 /**
- * Render a handle tree (`[{ id, type }]`) as a short list.
+ * Render a handle tree (`[{ id, type }]`) as a short colored list.
  *
  * @param {Array<{ id: string, type: string | null }>} tree
  * @returns {string}
  */
 export function formatHandles(tree) {
-  if (!tree || !tree.length) return 'handles: (none)'
-  const lines = tree.map((h) => `  ${h.type || 'root'} ${h.id}`)
-  return `handles (${tree.length}):\n${lines.join('\n')}`
+  if (!tree || !tree.length) return c.dim('handles: (none)')
+  const lines = tree.map((h) => `  ${c.cyan(h.type || 'root')} ${c.gray(h.id)}`)
+  return `${c.bold(`handles (${tree.length})`)}\n${lines.join('\n')}`
 }
 
 /**
@@ -38,26 +51,40 @@ export function formatState(ref, result) {
   const data = result?.data
   if (Array.isArray(data)) {
     const total = result.total ?? data.length
-    const head = data.slice(0, 3).map(shortRow)
-    return `${ref} (${total}):\n${head.map((r) => '  ' + r).join('\n')}`
+    const head = data.slice(0, 3).map((r) => '  ' + c.dim(shortRow(r)))
+    return `${c.cyan(ref)} ${c.gray(`(${total})`)}\n${head.join('\n')}`
   }
-  return `${ref}: ${shortRow(data)}`
+  return `${c.cyan(ref)} ${c.dim(shortRow(data))}`
 }
 
 /**
- * Render one applied-op event as a single line.
+ * Render a failed ref lookup as one line (so the CLI keeps going).
+ *
+ * @param {string} ref
+ * @param {{ message?: string }} err
+ * @returns {string}
+ */
+export function formatError(ref, err) {
+  return `${c.red('✗')} ${c.cyan(ref)}  ${c.dim(err.message || String(err))}`
+}
+
+const OP_COLOR = { add: c.green, set: c.yellow, del: c.red, claim: c.magenta }
+
+/**
+ * Render one applied-op event as a single colored line.
  *
  * @param {{ op: string, name: string, row: any, writerKey?: any, seq?: number }} e
  * @returns {string}
  */
 export function formatEvent(e) {
   const writer = shortKey(e.writerKey)
-  const tail = writer ? ` (${writer})` : ''
-  return `#${e.seq ?? '?'} ${e.op} ${e.name} ${shortRow(e.row)}${tail}`
+  const tail = writer ? c.gray(` ${writer}`) : ''
+  const op = (OP_COLOR[e.op] || c.cyan)(e.op)
+  return `${c.gray('#' + (e.seq ?? '?'))} ${op} ${c.cyan(e.name)} ${c.dim(shortRow(e.row))}${tail}`
 }
 
 /**
- * Render a stats snapshot as a single line.
+ * Render a stats snapshot as a single colored line.
  *
  * @param {{ network?: { connections: number, peers: number }, bee?: { local: number }, cores?: any[] }} s
  * @returns {string}
@@ -67,5 +94,5 @@ export function formatStats(s) {
   const peers = s?.network?.peers ?? 0
   const local = s?.bee?.local ?? 0
   const cores = s?.cores?.length ?? 0
-  return `net ${conns}c/${peers}p · bee ${local} · cores ${cores}`
+  return `${c.gray('net')} ${c.cyan(conns + 'c')}/${c.cyan(peers + 'p')}  ${c.gray('bee')} ${c.cyan(local)}  ${c.gray('cores')} ${c.cyan(cores)}`
 }

package/src/tap.js

@@ -1,14 +1,16 @@
 import { stats } from './stats.js'
 import { serve } from './server.js'
 import { redact } from './redact.js'
+import { loopback } from './transport.js'
 
 /**
  * `cero.use(devtools())` tap extension. Bound to the root handle's lifecycle,
  * it feeds every applied op into a bounded ring buffer, samples `stats(me)` on
- * an interval, and — if given a `transport` — serves a read-only inspection
- * surface to out-of-band consumers. Nothing here touches the app swarm.
+ * an interval, and serves a read-only inspection surface to out-of-band
+ * consumers. By default it serves a loopback TCP server on `port` (9111); pass
+ * a custom `transport` to serve it some other way. Nothing touches the app swarm.
  *
- * @param {{ bufferSize?: number, sampleInterval?: number, redact?: ((ref: string, row: any) => any) | { fields?: string[], match?: Function, deny?: RegExp | false }, transport?: { accept(handler: (stream: any) => void): void } }} [opts]
+ * @param {{ port?: number, host?: string, bufferSize?: number, sampleInterval?: number, redact?: ((ref: string, row: any) => any) | { fields?: string[], match?: Function, deny?: RegExp | false }, transport?: { accept(handler: (stream: any) => void): void } }} [opts]
  * @returns {{ setup(me: any): () => void }}
  */
 export function devtools(opts = {}) {
@@ -17,6 +19,7 @@ export function devtools(opts = {}) {
       const events = new Ring(opts.bufferSize ?? 1000)
       const sampler = new Sampler(me, opts.sampleInterval ?? 1000)
       const redactor = makeRedactor(opts.redact)
+      const transport = opts.transport || loopback({ port: opts.port ?? 9111, host: opts.host })
       const offs = []
       const servers = new Set()
 
@@ -32,19 +35,18 @@ export function devtools(opts = {}) {
       for (const child of me.children) follow(child)
       me.on('handle', (child) => follow(child), { signal: me.signal })
 
-      if (opts.transport) {
-        opts.transport.accept((stream) => {
-          const server = serve(stream, me, { events, stats: sampler, redact: redactor })
-          servers.add(server)
-          stream.on('close', () => servers.delete(server))
-        })
-      }
+      transport.accept((stream) => {
+        const server = serve(stream, me, { events, stats: sampler, redact: redactor })
+        servers.add(server)
+        stream.on('close', () => servers.delete(server))
+      })
 
       return () => {
         sampler.stop()
         for (const off of offs) off()
         for (const server of servers) server.close()
         servers.clear()
+        if (!opts.transport && transport.close) transport.close() // close the loopback we opened
       }
     }
   }

package/src/transport.js

@@ -10,18 +10,27 @@ import net from 'net'
  */
 export function loopback(opts = {}) {
   const host = opts.host ?? '127.0.0.1'
+  const base = opts.port ?? 0
   let server = null
   return {
     accept(handler) {
       server = net.createServer((socket) => handler(socket))
-      server.listen(opts.port ?? 0, host)
+      let port = base
+      let tries = 0
+      // A taken port (e.g. a second app instance) bumps to the next one rather
+      // than crashing the app — devtools is never essential.
+      server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE' && base && tries++ < 10) server.listen(++port, host)
+        else console.error(`[devtools] tap could not start: ${err.message}`)
+      })
+      server.on('listening', () => console.log(banner(host, server.address().port)))
+      server.listen(port, host)
     },
     ready() {
       return new Promise((resolve, reject) => {
         if (!server) return reject(new Error('accept() not called'))
         if (server.listening) return resolve({ port: server.address().port })
         server.once('listening', () => resolve({ port: server.address().port }))
-        server.once('error', reject)
       })
     },
     get port() {
@@ -43,3 +52,18 @@ export function loopback(opts = {}) {
 export function dial(opts = {}) {
   return net.connect(opts.port, opts.host ?? '127.0.0.1')
 }
+
+// VITE-style startup banner printed when the tap starts listening.
+function banner(host, port) {
+  const e = '\x1b['
+  const r = `${e}0m`
+  const dim = `${e}2m`
+  const bold = `${e}1m`
+  const cyan = `${e}36m`
+  const green = `${e}32m`
+  return (
+    `\n  ${bold}${cyan}cero devtools${r}  ${dim}tap ready${r}\n\n` +
+    `  ${green}➜${r}  ${bold}Listening${r}:  ${cyan}${host}:${port}${r}\n` +
+    `  ${green}➜${r}  ${bold}Connect${r}:    ${dim}cero-tools ${port}${r}\n`
+  )
+}

package/types/connect.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Consumer SDK for a tap server reached over a local Duplex `stream`. Returns
+ * a session exposing read methods (`handles`/`get`/`count`) and stream methods
+ * (`watch`/`events`/`stats`). Stream methods return a streamx Readable that
+ * cancels its server-side source when destroyed.
+ *
+ * @param {any} stream  A streamx Duplex connected to a tap server.
+ * @returns {Promise<{ handles(): Promise<any>, get(ref: string, query?: any, handleId?: string): Promise<any>, count(ref: string, query?: any, handleId?: string): Promise<any>, watch(ref: string, query?: any, handleId?: string): import('streamx').Readable, events(): import('streamx').Readable, stats(): import('streamx').Readable, close(): void }>}
+ */
+export function connect(stream: any): Promise<{
+    handles(): Promise<any>;
+    get(ref: string, query?: any, handleId?: string): Promise<any>;
+    count(ref: string, query?: any, handleId?: string): Promise<any>;
+    watch(ref: string, query?: any, handleId?: string): any;
+    events(): any;
+    stats(): any;
+    close(): void;
+}>;
+export class Session {
+    constructor(stream: any);
+    stream: any;
+    pending: Map<any, any>;
+    streams: Map<any, any>;
+    seq: number;
+    wire: Framed;
+    _onMessage(msg: any): void;
+    _newId(): number;
+    _request(method: any, fields: any): Promise<any>;
+    _stream(method: any, fields: any): any;
+    handles(): Promise<any>;
+    get(ref: any, query: any, handleId: any): Promise<any>;
+    count(ref: any, query: any, handleId: any): Promise<any>;
+    watch(ref: any, query: any, handleId: any): any;
+    events(): any;
+    stats(): any;
+    close(): void;
+}
+import { Framed } from './protocol.js';

package/types/format.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Render a handle tree (`[{ id, type }]`) as a short colored list.
+ *
+ * @param {Array<{ id: string, type: string | null }>} tree
+ * @returns {string}
+ */
+export function formatHandles(tree: Array<{
+    id: string;
+    type: string | null;
+}>): string;
+/**
+ * Render a `get()` reply — `{ data, total, size }` for collections or
+ * `{ data }` for single refs — as a compact summary.
+ *
+ * @param {string} ref
+ * @param {{ data: any, total?: number, size?: number }} result
+ * @returns {string}
+ */
+export function formatState(ref: string, result: {
+    data: any;
+    total?: number;
+    size?: number;
+}): string;
+/**
+ * Render a failed ref lookup as one line (so the CLI keeps going).
+ *
+ * @param {string} ref
+ * @param {{ message?: string }} err
+ * @returns {string}
+ */
+export function formatError(ref: string, err: {
+    message?: string;
+}): string;
+/**
+ * Render one applied-op event as a single colored line.
+ *
+ * @param {{ op: string, name: string, row: any, writerKey?: any, seq?: number }} e
+ * @returns {string}
+ */
+export function formatEvent(e: {
+    op: string;
+    name: string;
+    row: any;
+    writerKey?: any;
+    seq?: number;
+}): string;
+/**
+ * Render a stats snapshot as a single colored line.
+ *
+ * @param {{ network?: { connections: number, peers: number }, bee?: { local: number }, cores?: any[] }} s
+ * @returns {string}
+ */
+export function formatStats(s: {
+    network?: {
+        connections: number;
+        peers: number;
+    };
+    bee?: {
+        local: number;
+    };
+    cores?: any[];
+}): string;

package/types/index.d.ts

@@ -0,0 +1,6 @@
+export { stats } from "./stats.js";
+export { redact } from "./redact.js";
+export { devtools } from "./tap.js";
+export { serve } from "./server.js";
+export { connect } from "./connect.js";
+export { loopback, dial } from "./transport.js";

package/types/protocol.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Length-prefixed JSON framing over a Duplex `stream`. Buffers incoming chunks
+ * and delivers each decoded frame to `onMessage`; `send` writes a framed frame.
+ */
+export class Framed {
+    constructor(stream: any, onMessage: any);
+    stream: any;
+    onMessage: any;
+    buf: any;
+    _onData(chunk: any): void;
+    send(obj: any): void;
+}

package/types/redact.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Build a row masker for devtools. A field is masked when its dotted path is in
+ * `fields`, its name matches `deny` (default denylist above), or `match(key,
+ * value, path)` returns true. Masked values become a typed placeholder —
+ * `‹redacted:bytes(32)›` / `‹redacted:string›` — so the shape stays visible but
+ * the content is hidden. Everything else passes through untouched.
+ *
+ * @param {{ fields?: string[], deny?: RegExp | false, match?: (key: string, value: any, path: string) => boolean }} [config]
+ * @returns {(ref: string, row: any) => any}
+ */
+export function redact(config?: {
+    fields?: string[];
+    deny?: RegExp | false;
+    match?: (key: string, value: any, path: string) => boolean;
+}): (ref: string, row: any) => any;

package/types/server.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Read-only inspection server over a local Duplex `stream`. Serves the live
+ * handle tree rooted at `me`, exposing only MAIN refs declared in each
+ * handle's `spec.meta.refs` — local secret refs (master/keypair/
+ * handle-keypairs) are never reachable, since they live in `meta.local.refs`.
+ *
+ * @param {any} stream  A streamx Duplex carrying length-prefixed JSON frames.
+ * @param {any} me  The live root cero handle.
+ * @param {{ events?: { snapshot(): any, subscribe(fn: (e: any) => void): () => void }, stats?: { snapshot(): any, subscribe(fn: (s: any) => void): () => void }, redact?: (ref: string, row: any) => any }} [opts]
+ * @returns {{ close(): void }}
+ */
+export function serve(stream: any, me: any, opts?: {
+    events?: {
+        snapshot(): any;
+        subscribe(fn: (e: any) => void): () => void;
+    };
+    stats?: {
+        snapshot(): any;
+        subscribe(fn: (s: any) => void): () => void;
+    };
+    redact?: (ref: string, row: any) => any;
+}): {
+    close(): void;
+};
+export class TapServer {
+    constructor(stream: any, me: any, opts?: {});
+    stream: any;
+    me: any;
+    redact: any;
+    opts: {};
+    tracked: Map<any, any>;
+    wire: Framed;
+    _cleanup: () => void;
+    onRequest(req: any): Promise<void>;
+    handles(req: any): void;
+    get(req: any): Promise<void>;
+    count(req: any): Promise<void>;
+    watch(req: any): void;
+    events(req: any): void;
+    stats(req: any): void;
+    cancel(req: any): void;
+    _resolveRef(req: any): any;
+    _source(req: any, src: any): void;
+    _track(id: any, off: any): void;
+    _drop(id: any): void;
+    _send(obj: any): void;
+    _teardown(): void;
+    close(): void;
+}
+import { Framed } from './protocol.js';

package/types/stats.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Read-only snapshot of a handle's existing p2p/storage counters. Pure: no
+ * listeners, no mutation, never reads a secret. `dht.stats` and the corestore
+ * `cores` map are undocumented internals, so they are guarded — a fresh handle
+ * (pre-ready) yields zeros rather than throwing.
+ *
+ * @param {any} handle  A cero root or child handle.
+ * @param {number} [at]  Sample timestamp, stamped by the caller.
+ * @returns {{ handleId: string, network: { connections: number, peers: number, dht: any }, bee: { local: number }, cores: Array<{ length: number, byteLength: number, peers: number }>, at: number }}
+ */
+export function stats(handle: any, at?: number): {
+    handleId: string;
+    network: {
+        connections: number;
+        peers: number;
+        dht: any;
+    };
+    bee: {
+        local: number;
+    };
+    cores: Array<{
+        length: number;
+        byteLength: number;
+        peers: number;
+    }>;
+    at: number;
+};

package/types/tap.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `cero.use(devtools())` tap extension. Bound to the root handle's lifecycle,
+ * it feeds every applied op into a bounded ring buffer, samples `stats(me)` on
+ * an interval, and serves a read-only inspection surface to out-of-band
+ * consumers. By default it serves a loopback TCP server on `port` (9111); pass
+ * a custom `transport` to serve it some other way. Nothing touches the app swarm.
+ *
+ * @param {{ port?: number, host?: string, bufferSize?: number, sampleInterval?: number, redact?: ((ref: string, row: any) => any) | { fields?: string[], match?: Function, deny?: RegExp | false }, transport?: { accept(handler: (stream: any) => void): void } }} [opts]
+ * @returns {{ setup(me: any): () => void }}
+ */
+export function devtools(opts?: {
+    port?: number;
+    host?: string;
+    bufferSize?: number;
+    sampleInterval?: number;
+    redact?: ((ref: string, row: any) => any) | {
+        fields?: string[];
+        match?: Function;
+        deny?: RegExp | false;
+    };
+    transport?: {
+        accept(handler: (stream: any) => void): void;
+    };
+}): {
+    setup(me: any): () => void;
+};

package/types/transport.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Loopback TCP transport implementing the tap `{ accept(handler) }` contract
+ * plus lifecycle. Each inbound connection's socket is a streamx-compatible
+ * Duplex, ready to pass straight to `serve()`.
+ *
+ * @param {{ port?: number, host?: string }} [opts]
+ * @returns {{ accept(handler: (socket: any) => void): void, ready(): Promise<{ port: number }>, port: number | null, close(): void }}
+ */
+export function loopback(opts?: {
+    port?: number;
+    host?: string;
+}): {
+    accept(handler: (socket: any) => void): void;
+    ready(): Promise<{
+        port: number;
+    }>;
+    port: number | null;
+    close(): void;
+};
+/**
+ * Dial a loopback tap server and return the connected socket, ready for
+ * `connect()`.
+ *
+ * @param {{ port: number, host?: string }} [opts]
+ * @returns {any} A streamx-compatible Duplex socket.
+ */
+export function dial(opts?: {
+    port: number;
+    host?: string;
+}): any;