@farmslot/capabilities 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@farmslot/capabilities` are tracked here.
 
 ## Unreleased
 
+- Active-development baseline; add user-facing changes here before release or package publication.
+
+## 0.1.3 - 2026-10-09
+
+- Publish with protocol 0.35.0 so consumers share one protocol copy. No code change.
+
+## 0.1.2 - 2026-09-20
+
+- Publishable manifest: MIT license file and metadata, an explicit `files` list (source only, no tests) and public access, so the package ships through the shared npm release group.
+
+## 0.1.1 - 2026-08-21
+
+- Keep `fs-watch` attached across atomic file replacements so remote checklist progress
+  continues after the first marked step.
+
+## 0.1.0 - 2026-07-01
+
 - 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Breton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,6 +3,8 @@
 Machine-local capability primitives shared by the **node** (`services/node`) and the
 **gateway** (`services/gateway`).
 
+Reference: <https://farmslot.io/docs/reference/capabilities>.
+
 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,
@@ -26,11 +28,11 @@ import { encodeNodeFrame, decodeNodeFrame } from '@farmslot/capabilities/screen-
 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.                                      |
+| Import                                                     | What it is                                                                                                                                                                 |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fs-watch` — `watchFile()`                                 | Native parent-directory `fs.watch` that survives atomic file replacement, filters to the target filename, deduplicates content, and expands tildes. 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
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@farmslot/capabilities",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "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.",
+  "license": "MIT",
   "type": "module",
   "main": "src/index.ts",
   "exports": {
@@ -10,15 +11,35 @@
     "./screen-frame": "./src/screen-frame.ts",
     "./screen-h264": "./src/screen-h264.ts"
   },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
+    "test": "node ../../scripts/quality/run-tsx-tests.mjs --cwd . --tsconfig tsconfig.json src",
     "typecheck": "tsc --noEmit --project tsconfig.json",
-    "quality": "yarn typecheck"
+    "quality": "yarn test && yarn typecheck"
   },
   "dependencies": {
-    "@farmslot/protocol": "0.7.2"
+    "@farmslot/protocol": "0.35.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.6.0"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deeeed/farmslot.git",
+    "directory": "packages/capabilities"
+  },
+  "bugs": {
+    "url": "https://github.com/deeeed/farmslot/issues"
+  },
+  "homepage": "https://farmslot.io/docs/reference/capabilities"
 }

package/src/fs-watch.ts

@@ -1,5 +1,5 @@
-// 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
+// Shared file-watch primitive (ADR-046). Native parent-directory `fs.watch`
+// survives atomic file replacement and expands tilde paths. 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.
 
@@ -22,62 +22,44 @@ export interface FileWatchHandle {
 
 /**
  * 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.
+ * content on every write. The parent directory remains watched so atomic file
+ * replacement does not detach the watcher from subsequent updates. 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;
+  let lastContent: string | null = null;
 
   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}`);
-          }
+    // Watch the parent directory even when the file already exists. Checklist markers,
+    // git, and many editors update files through atomic rename; watching the file inode
+    // sees the first replacement and then silently follows the orphaned inode.
+    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 != null && filename.toString() !== target) return;
+      if (!existsSync(targetPath)) return;
+      try {
+        const content = await readFile(targetPath, 'utf-8');
+        if (content === lastContent) return;
+        lastContent = content;
+        onChange(content);
+      } catch (err) {
+        // Atomic replacement can briefly remove the target between the directory
+        // event and the read. The following event will read the replacement.
+        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();

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "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"]
-}