@farmslot/capabilities 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `@farmslot/capabilities` are tracked here.
+
+## Unreleased
+
+- Initial package (ADR-046): machine-local capability primitives shared by the node
+  (primary owner) and the gateway (local fallback when no node).
+- `fs-watch` — `watchFile()` native file-change watch primitive.
+- `screen-frame` — `encodeNodeFrame()` / `decodeNodeFrame()` node→gateway capture-frame
+  envelope codec.
+- `screen-h264` — `createH264FrameSplitter()` raw H.264 stream frame splitter.

package/README.md

@@ -0,0 +1,55 @@
+# @farmslot/capabilities
+
+Machine-local capability primitives shared by the **node** (`services/node`) and the
+**gateway** (`services/gateway`).
+
+The node owns machine-local capabilities; the gateway keeps a degraded **local fallback**
+for a machine that has no connected node. To provide that fallback without duplicating
+logic, the primitive lives here once and both services import it — node as primary owner,
+gateway as fallback caller.
+
+## Canonical documents
+
+- [ADR-046: Mandatory co-located local node](../../docs/adr/046-mandatory-local-node.md) — why this package exists, what does and does not get a gateway fallback, and the future direction (node as a thin transport over this library).
+
+## Install
+
+```bash
+yarn add @farmslot/capabilities @farmslot/protocol
+```
+
+## Main exports
+
+```ts
+import { watchFile } from '@farmslot/capabilities/fs-watch';
+import { encodeNodeFrame, decodeNodeFrame } from '@farmslot/capabilities/screen-frame';
+import { createH264FrameSplitter } from '@farmslot/capabilities/screen-h264';
+```
+
+| Import                                                     | What it is                                                                                                                          |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `fs-watch` — `watchFile()`                                 | Native `fs.watch` with the "watch the parent directory until the file appears" fallback and tilde expansion. Returns a stop handle. |
+| `screen-frame` — `encodeNodeFrame()` / `decodeNodeFrame()` | The node→gateway capture-frame binary envelope codec (`0xAF` magic). Node encodes, gateway decodes.                                 |
+| `screen-h264` — `createH264FrameSplitter()`                | Splits a raw `adb screenrecord --output-format=h264` byte stream into individual video frames.                                      |
+
+## Source layout
+
+| Path                  | Owns                                                                               |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| `src/index.ts`        | Public package export surface.                                                     |
+| `src/fs-watch.ts`     | `watchFile()` — native file-change watch primitive.                                |
+| `src/screen-frame.ts` | `encodeNodeFrame()` / `decodeNodeFrame()` — the node→gateway frame envelope codec. |
+| `src/screen-h264.ts`  | `createH264FrameSplitter()` — raw H.264 elementary-stream frame splitter.          |
+
+## Maintenance rules
+
+1. **Node-only runtime.** Uses `node:fs` / `node:child_process`; never import DOM or gateway/node-internal modules here.
+2. **Protocol types only.** Shared constants (e.g. the frame magic) come from `@farmslot/protocol`; keep `Buffer`-based helpers out of the UI-shared protocol bundle.
+3. **One implementation, two callers.** A primitive belongs here only when both the node (primary) and the gateway (local fallback) genuinely use it — not as a util grab-bag.
+4. **No hidden shared state.** Each primitive is instance-scoped (a handle/splitter per caller); do not add module-level singletons that leak across callers.
+
+## Local quality
+
+```bash
+yarn workspace @farmslot/capabilities quality
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@farmslot/capabilities",
+  "version": "0.1.0",
+  "description": "Machine-local capability primitives (fs-watch, screen capture) shared by the node (primary owner) and the gateway (local fallback when no node) — ADR-046.",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./fs-watch": "./src/fs-watch.ts",
+    "./screen-frame": "./src/screen-frame.ts",
+    "./screen-h264": "./src/screen-h264.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "quality": "yarn typecheck"
+  },
+  "dependencies": {
+    "@farmslot/protocol": "0.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/fs-watch.ts

@@ -0,0 +1,94 @@
+// Shared file-watch primitive (ADR-046). Native `fs.watch` with the parent-dir
+// "watch until the file appears" fallback and tilde expansion. Used by the node
+// (primary owner of machine-local monitoring) and by the gateway as a local
+// fallback when a machine has no connected node — one implementation, two callers.
+
+import { existsSync, type FSWatcher, watch } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname } from 'node:path';
+
+// Pool configs can declare repos as `~/...`. `~` is a shell token, not a
+// filesystem prefix — node:fs treats it literally. Expand to $HOME first.
+export function expandTilde(p: string): string {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return `${homedir()}/${p.slice(2)}`;
+  return p;
+}
+
+export interface FileWatchHandle {
+  stop(): void;
+}
+
+/**
+ * Watch a single file for content changes. `onChange` receives the file's UTF-8
+ * content on every write. If the file does not exist yet, its parent directory is
+ * watched until the file appears, then the watch switches to the file directly.
+ * Returns a handle the caller stops when done.
+ */
+export function watchFile(filePath: string, onChange: (content: string) => void): FileWatchHandle {
+  const targetPath = expandTilde(filePath);
+  let watcher: FSWatcher | null = null;
+  let stopped = false;
+
+  const start = (): void => {
+    if (stopped) return;
+    if (existsSync(targetPath)) {
+      // File exists — watch it directly.
+      watcher = watch(targetPath, { persistent: false }, async () => {
+        try {
+          const content = await readFile(targetPath, 'utf-8');
+          onChange(content);
+        } catch (err) {
+          // ENOENT is expected: git rewrites HEAD via an atomic rename, so the path is
+          // briefly absent between the watch firing and the read — the next event re-reads.
+          // Anything else (permissions, I/O) is a real fault and is surfaced, not hidden.
+          const code = (err as NodeJS.ErrnoException).code;
+          if (code !== 'ENOENT') {
+            console.warn(`[fs.watch] read failed for ${targetPath}: ${(err as Error).message}`);
+          }
+        }
+      });
+    } else {
+      // File doesn't exist yet — watch the parent directory for its creation.
+      const dir = dirname(targetPath);
+      if (!existsSync(dir)) {
+        console.log(`[fs.watch] parent dir doesn't exist: ${dir} — skipping watch`);
+        return;
+      }
+      const target = basename(targetPath);
+      watcher = watch(dir, { persistent: false }, async (_, filename) => {
+        if (filename !== target) return;
+        if (!existsSync(targetPath)) return;
+        // File appeared — read, notify, then switch to watching it directly.
+        try {
+          const content = await readFile(targetPath, 'utf-8');
+          onChange(content);
+        } catch (err) {
+          // ENOENT is expected: git rewrites HEAD via an atomic rename, so the path is
+          // briefly absent between the watch firing and the read — the next event re-reads.
+          // Anything else (permissions, I/O) is a real fault and is surfaced, not hidden.
+          const code = (err as NodeJS.ErrnoException).code;
+          if (code !== 'ENOENT') {
+            console.warn(`[fs.watch] read failed for ${targetPath}: ${(err as Error).message}`);
+          }
+        }
+        if (watcher) watcher.close();
+        watcher = null;
+        start();
+      });
+    }
+  };
+
+  start();
+
+  return {
+    stop(): void {
+      stopped = true;
+      if (watcher) {
+        watcher.close();
+        watcher = null;
+      }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// @farmslot/capabilities — machine-local capability primitives shared by the node
+// (primary owner) and the gateway (local fallback when no node). ADR-046.
+
+export { expandTilde, type FileWatchHandle, watchFile } from './fs-watch.js';
+export {
+  type DecodedNodeFrame,
+  decodeNodeFrame,
+  encodeNodeFrame,
+  NODE_FRAME_MAGIC,
+} from './screen-frame.js';
+export {
+  createH264FrameSplitter,
+  type H264FrameHandler,
+  type H264FrameSplitter,
+} from './screen-h264.js';

package/src/screen-frame.ts

@@ -0,0 +1,60 @@
+// Shared node→gateway capture-frame codec (ADR-046). Single source of truth for the
+// binary envelope so the node (encode) and the gateway (decode) never drift. The magic
+// byte lives in @farmslot/protocol; the Buffer-based codec lives here (node-only) so it
+// stays out of the UI-shared protocol bundle.
+//
+// Envelope: [0xAF magic][1B flags][2B width BE][2B height BE][1B slotIdLen][slotId…][payload…]
+// flags bit0 = keyframe.
+
+import { NODE_FRAME_MAGIC } from '@farmslot/protocol';
+
+export { NODE_FRAME_MAGIC };
+
+const HEADER_FIXED = 7; // magic + flags + width(2) + height(2) + slotIdLen
+
+export function encodeNodeFrame(
+  slotId: string,
+  payload: Uint8Array,
+  keyFrame: boolean,
+  width: number,
+  height: number,
+): Buffer {
+  const slotBytes = Buffer.from(slotId, 'utf-8');
+  const headerSize = HEADER_FIXED + slotBytes.length;
+  const buf = Buffer.alloc(headerSize + payload.length);
+  buf[0] = NODE_FRAME_MAGIC;
+  buf[1] = keyFrame ? 1 : 0;
+  buf.writeUInt16BE(width, 2);
+  buf.writeUInt16BE(height, 4);
+  buf[6] = slotBytes.length;
+  slotBytes.copy(buf, HEADER_FIXED);
+  buf.set(payload, headerSize);
+  return buf;
+}
+
+export interface DecodedNodeFrame {
+  slotId: string;
+  payload: Uint8Array;
+  keyFrame: boolean;
+  width: number;
+  height: number;
+}
+
+/** Decode a node capture frame. Returns null when the buffer is truncated. Callers
+ *  should have already checked `raw[0] === NODE_FRAME_MAGIC`. */
+export function decodeNodeFrame(raw: Buffer): DecodedNodeFrame | null {
+  if (raw.length < HEADER_FIXED) return null;
+  const flags = raw[1];
+  const keyFrame = (flags & 1) !== 0;
+  const width = raw.readUInt16BE(2);
+  const height = raw.readUInt16BE(4);
+  const slotIdLen = raw[6];
+  if (raw.length < HEADER_FIXED + slotIdLen) return null;
+  const slotId = raw.subarray(HEADER_FIXED, HEADER_FIXED + slotIdLen).toString('utf-8');
+  const payload = new Uint8Array(
+    raw.buffer,
+    raw.byteOffset + HEADER_FIXED + slotIdLen,
+    raw.length - HEADER_FIXED - slotIdLen,
+  );
+  return { slotId, payload, keyFrame, width, height };
+}

package/src/screen-h264.ts

@@ -0,0 +1,101 @@
+// Shared H.264 frame splitter. The node and the gateway both read the raw byte stream
+// from `adb screenrecord --output-format=h264` and slice it into individual video frames
+// the same way: split on the 00 00 00 01 NAL start codes and group the NAL units into
+// frames (SPS + PPS + IDR = a keyframe, a lone slice = a delta frame). This logic was
+// copied verbatim into both services; it now lives in one place.
+
+export type H264FrameHandler = (frame: Uint8Array, keyFrame: boolean) => void;
+
+export interface H264FrameSplitter {
+  /** Feed a raw stdout chunk; emits complete video frames via the handler. */
+  push(chunk: Buffer): void;
+}
+
+function concatBuffers(parts: Buffer[]): Uint8Array {
+  const total = parts.reduce((s, p) => s + p.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+
+export function createH264FrameSplitter(onFrame: H264FrameHandler): H264FrameSplitter {
+  let buffer = Buffer.alloc(0);
+
+  function drain(): void {
+    const buf = buffer;
+    const startCodes: number[] = [];
+
+    // Find all 4-byte start codes.
+    for (let i = 0; i <= buf.length - 4; i++) {
+      if (buf[i] === 0 && buf[i + 1] === 0 && buf[i + 2] === 0 && buf[i + 3] === 1) {
+        startCodes.push(i);
+      }
+    }
+
+    if (startCodes.length < 2) return; // need at least 2 start codes to extract a NAL
+
+    let consumed = 0;
+    let frameStart = -1;
+    let frameIsKey = false;
+    let frameData: Buffer[] = [];
+
+    for (let i = 0; i < startCodes.length - 1; i++) {
+      const nalStart = startCodes[i];
+      const nalEnd = startCodes[i + 1];
+      const nalType = buf[nalStart + 4] & 0x1f;
+
+      if (nalType === 7 || nalType === 8) {
+        // SPS or PPS — start accumulating a keyframe.
+        if (frameStart === -1) frameStart = nalStart;
+        frameIsKey = true;
+        frameData.push(buf.subarray(nalStart, nalEnd));
+      } else if (nalType === 5) {
+        // IDR slice — completes the keyframe.
+        if (frameStart === -1) {
+          frameStart = nalStart;
+          frameIsKey = true;
+        }
+        frameData.push(buf.subarray(nalStart, nalEnd));
+        onFrame(concatBuffers(frameData), true);
+        consumed = nalEnd;
+        frameStart = -1;
+        frameIsKey = false;
+        frameData = [];
+      } else if (nalType === 1) {
+        // P-slice — standalone frame.
+        if (frameData.length > 0) {
+          // Flush accumulated SPS/PPS without IDR (shouldn't happen, but safe).
+          onFrame(concatBuffers(frameData), frameIsKey);
+          frameData = [];
+          frameIsKey = false;
+          frameStart = -1;
+        }
+        onFrame(new Uint8Array(buf.buffer, buf.byteOffset + nalStart, nalEnd - nalStart), false);
+        consumed = nalEnd;
+      } else {
+        // Skip other NAL types (SEI=6, AUD=9, etc.).
+        if (frameStart !== -1) {
+          frameData.push(buf.subarray(nalStart, nalEnd));
+        } else {
+          consumed = nalEnd;
+        }
+      }
+    }
+
+    // Keep unconsumed data (last incomplete NAL + any accumulated frame data).
+    if (consumed > 0) {
+      buffer = Buffer.from(buf.subarray(frameData.length > 0 ? frameStart! : consumed));
+    }
+  }
+
+  return {
+    push(chunk: Buffer): void {
+      buffer = Buffer.concat([buffer, chunk]);
+      drain();
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../apps/command-center/tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "paths": {
+      "@farmslot/protocol": ["../protocol/src/index.ts"],
+      "@farmslot/protocol/*": ["../protocol/src/*"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
+}