@mygo-plugins/watch 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyGo contributors
+
+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

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @mygo-plugins/watch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Changes to files for [MyGo](https://github.com/egoist/mygo) apps' pages, in
+the directories and files the app lets them watch, such as a project open
+in an editor.
+
+Use the plugin in Go with the directories pages may watch, each under a
+name:
+
+```go
+import "github.com/egoist/mygo/plugins/watch"
+
+mygo.Use(watch.New(watch.Options{
+	Roots: map[string]watch.Root{
+		"project": {Path: projectDir, Recursive: true},
+	},
+}))
+```
+
+and watch one by its name in the frontend:
+
+```ts
+import { watch } from "@mygo-plugins/watch";
+
+const watcher = await watch("project", { recursive: true });
+for await (const events of watcher) {
+  for (const event of events) console.log(event.op, event.path); // "write", "src/main.ts"
+}
+```
+
+Each batch has the events of `create`, `write`, `remove` and `rename` (with
+`oldPath`) found once changes stopped for 50 ms (`debounceMs`), with paths
+relative to what is watched, `path` in the root or the root itself. They say
+what is different, not every step: treat them as hints to read the files
+again. `watcher.close()`, breaking out of the loop, an
+`AbortSignal` (`signal`) or the page navigating stop the watch.
+
+[The documentation](https://github.com/egoist/mygo/blob/main/docs/plugins/watch.md)
+covers the options of the Go side, errors and how each platform watches.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/** The kind of a {@link FileEvent}. */
+export type FileOp = "create" | "write" | "remove" | "rename";
+/**
+ * A change in a watched directory or file. Events say what is different
+ * once changes stop, not every step that made it so: treat them as hints
+ * to read the files again.
+ */
+export interface FileEvent {
+    op: FileOp;
+    /** The path relative to what is watched, separated by slashes; "." is what is watched itself. */
+    path: string;
+    /** Where a rename moved from. */
+    oldPath?: string;
+    isDir: boolean;
+}
+/** Options of {@link watch}. */
+export interface WatchOptions {
+    /** What to watch in the root, a directory or a file, relative to it and separated by slashes: the root itself by default. */
+    path?: string;
+    /** Watch the directories in the directory too, if the app allows it. */
+    recursive?: boolean;
+    /** How long changes must stop before they are reported: 50 ms when 0 or omitted, right away when negative. */
+    debounceMs?: number;
+    /** Stops the watch when aborted. */
+    signal?: AbortSignal;
+}
+/** Why a watch failed or stopped; see {@link WatchError}. */
+export type WatchErrorCode = "denied" | "limit" | "not-found" | "unsupported" | "path-encoding" | "io";
+/** A watch that failed to start or stopped, with the reason as its code. */
+export declare class WatchError extends Error {
+    readonly code: WatchErrorCode;
+    constructor(code: WatchErrorCode, message: string);
+}
+/**
+ * A running watch: iterate it for the changes, a batch of events each time
+ * they stop. Go doesn't look again until the page has taken a batch, so
+ * nothing is lost while the page is busy.
+ */
+export interface Watcher extends AsyncIterable<FileEvent[]> {
+    /** Settles once Go has stopped the watch, rejecting with the error that stopped it. */
+    readonly closed: Promise<void>;
+    /** Stops the watch; it resolves once Go has. */
+    close(): Promise<void>;
+}
+/**
+ * Watches the directory or file the app named `root`, or `path` in it, and
+ * resolves once everything is watched. What is already there is not
+ * reported. When it is removed, renamed or replaced, the last batch has a
+ * "remove" of ".", and the iteration ends.
+ */
+export declare function watch(root: string, options?: WatchOptions): Promise<Watcher>;

package/dist/index.js

@@ -0,0 +1,109 @@
+// src/index.ts
+import { Channel, call } from "mygo-runtime";
+
+class WatchError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "WatchError";
+  }
+}
+var codes = ["denied", "limit", "not-found", "unsupported", "path-encoding", "io"];
+async function watch(root, options = {}) {
+  const debounceMs = options.debounceMs ?? 0;
+  if (!Number.isInteger(debounceMs) || debounceMs > 60000) {
+    throw new TypeError("debounceMs must be an integer up to 60000");
+  }
+  const path = options.path ?? ".";
+  if (typeof path !== "string")
+    throw new TypeError("path must be a string");
+  if (options.signal?.aborted)
+    throw options.signal.reason;
+  const parts = new Channel;
+  const stream = parts[Symbol.asyncIterator]();
+  let terminal;
+  let closing = false;
+  let finished = false;
+  let iterating = false;
+  const record = (error) => {
+    terminal ??= { error };
+  };
+  const abort = () => {
+    if (finished || closing)
+      return;
+    record(options.signal.reason);
+    closing = true;
+    parts.close();
+  };
+  options.signal?.addEventListener("abort", abort, { once: true });
+  const closed = call("plugin:watch.Watch", { root, path, recursive: options.recursive ?? false, debounceMs }, parts).then((outcome) => {
+    if (outcome?.code) {
+      record(codes.includes(outcome.code) ? new WatchError(outcome.code, outcome.message ?? "filesystem watch failed") : new Error("Invalid watch outcome"));
+    }
+    if (terminal)
+      throw terminal.error;
+  }, (err) => {
+    record(err);
+    throw terminal.error;
+  }).finally(() => {
+    finished = true;
+    options.signal?.removeEventListener("abort", abort);
+  });
+  closed.catch(() => {});
+  const close = async () => {
+    if (!closing && !finished) {
+      closing = true;
+      parts.close();
+    }
+    await closed.catch(() => {});
+  };
+  try {
+    const first = await stream.next();
+    if (first.done) {
+      await closed;
+      throw new Error("Watch ended before ready");
+    }
+    if (first.value.type !== "ready") {
+      parts.close();
+      await closed;
+      throw new Error("Invalid watch ready response");
+    }
+    if (terminal) {
+      await closed;
+      throw terminal.error;
+    }
+  } catch (err) {
+    parts.close();
+    options.signal?.removeEventListener("abort", abort);
+    throw err;
+  }
+  return {
+    closed,
+    close,
+    [Symbol.asyncIterator]() {
+      if (iterating)
+        throw new Error("A watch supports one iterator");
+      iterating = true;
+      return async function* () {
+        try {
+          while (!closing) {
+            const next = await stream.next();
+            if (next.done)
+              break;
+            if (next.value.events?.length && !closing)
+              yield next.value.events;
+          }
+          await closed;
+        } finally {
+          await close();
+          iterating = false;
+        }
+      }();
+    }
+  };
+}
+export {
+  WatchError,
+  watch
+};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@mygo-plugins/watch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Watches for changes to files in the directories a MyGo desktop app lets its pages watch",
+  "keywords": [
+    "mygo",
+    "desktop",
+    "webview",
+    "go",
+    "watch",
+    "filesystem"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egoist/mygo.git",
+    "directory": "plugins/watch"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run ../build.ts",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "mygo-runtime": "^0.5.0"
+  },
+  "devDependencies": {
+    "mygo-runtime": "^0.5.0"
+  }
+}