skyffla 1.1.3

package/PUBLISHING.md

@@ -0,0 +1,79 @@
+# Publishing
+
+The Node.js wrapper lives at `wrappers/node` and publishes to npm as `skyffla`.
+
+## Versioning
+
+- Release versions:
+  - the npm package version lives in `wrappers/node/package.json`
+  - the runtime wrapper version also lives in `wrappers/node/src/version.js`
+  - both should track the repo release tag version exactly
+  - a Git tag `vX.Y.Z` should only be pushed after the Node.js package version
+    is set to `X.Y.Z`
+
+- Protocol compatibility is a separate contract. See:
+  - `docs/versioning.md`
+  - `docs/machine-protocol.md`
+
+The wrapper validates machine protocol compatibility from `room_welcome` and
+requires the same machine protocol major version as the published package.
+
+Official packages also probe `skyffla --version` before starting a room and
+reject a CLI binary whose release version does not exactly match the npm
+package version. This is a wrapper packaging policy on top of machine protocol
+compatibility. `SKYFFLA_SKIP_VERSION_CHECK=1` bypasses only the release-version
+pairing check.
+
+## Release Flow
+
+1. Update the release version in:
+   - `Cargo.toml`
+   - `wrappers/node/package.json`
+   - `wrappers/node/src/version.js`
+2. Run the wrapper checks locally:
+
+```sh
+cargo test -p skyffla --test machine_local_end_to_end
+npm test --prefix wrappers/node
+```
+
+3. Push the release tag:
+
+```sh
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+4. GitHub Actions will:
+   - build the local `skyffla` binary needed by the smoke tests
+   - run the Node.js wrapper test suite
+   - pack the npm tarball
+   - verify `package.json` matches the tag version
+   - publish `skyffla` to npm only if the repository variable
+     `PUBLISH_NODE_PACKAGE=1`
+
+By default, tagged releases do not publish the npm package. This keeps normal
+release tags safe until the npm package is claimed and trusted publishing is
+configured.
+
+## npm Setup
+
+The `Node Wrapper` workflow uses npm trusted publishing.
+
+Configure trusted publishing on npm for the GitHub repository that owns
+`.github/workflows/node-package.yml`:
+
+- workflow: `Node Wrapper`
+- workflow file: `.github/workflows/node-package.yml`
+- environment: not required
+
+No npm automation token should be stored once trusted publishing is configured.
+
+## Enable First Publish
+
+When the `skyffla` npm name is ready:
+
+1. Create or claim the `skyffla` package on npm.
+2. Configure trusted publishing for the `Node Wrapper` workflow.
+3. Set the repository variable `PUBLISH_NODE_PACKAGE=1`.
+4. Cut or re-push the intended `vX.Y.Z` release tag.

package/README.md

@@ -0,0 +1,118 @@
+# Skyffla Node.js Wrapper
+
+Use this package to control an installed `skyffla` CLI from Node.js.
+
+`npm install skyffla` installs the Node.js wrapper only. Install the `skyffla`
+binary separately first.
+
+## 1. Install the `skyffla` binary
+
+Add the Homebrew tap once:
+
+```sh
+brew tap skyffla/skyffla
+```
+
+Install the CLI:
+
+```sh
+brew install skyffla
+```
+
+Check that the binary is available:
+
+```sh
+skyffla --version
+```
+
+If you want source code, release notes, or other install paths, see the
+[Skyffla repository on GitHub](https://github.com/skyffla/skyffla).
+
+## 2. Install the Node.js wrapper
+
+```sh
+npm install skyffla
+```
+
+The wrapper expects a `skyffla` binary in `PATH`. Override it with
+`SKYFFLA_BIN` or the `binary` option when starting a room.
+
+## 3. Small example
+
+Save this as `example.mjs`. Start `host` in one terminal, then start `join` in
+another.
+
+```js
+import { Room } from "skyffla";
+
+async function main(role) {
+  const opener = role === "host" ? Room.host : Room.join;
+  const room = await opener("warehouse", { name: role });
+
+  try {
+    await room.waitForWelcome();
+    if (role === "host") {
+      const joined = await room.waitForMemberJoined({ name: "join" });
+      await room.sendChat("all", "hello from node");
+      console.log(await room.waitForChat({ fromName: "join" }));
+      await room.openMachineChannel("node-demo", {
+        to: joined.member.member_id,
+        name: "node-demo",
+      });
+    } else {
+      await room.waitForMemberSnapshot({ minMembers: 2 });
+      console.log(await room.waitForChat({ fromName: "host" }));
+      await room.sendChat("all", "hello from join");
+      const opened = await room.waitForChannelOpened({ channelId: "node-demo" });
+      await room.channel(opened.channel_id).send("hello over machine channel");
+    }
+  } finally {
+    await room.close();
+  }
+}
+
+await main(process.argv[2]);
+```
+
+```sh
+node example.mjs host
+node example.mjs join
+```
+
+## Version checks
+
+Versioning is split across two layers:
+
+- machine protocol compatibility follows the
+  [versioning policy](https://github.com/skyffla/skyffla/blob/main/docs/versioning.md)
+  and
+  [machine protocol reference](https://github.com/skyffla/skyffla/blob/main/docs/machine-protocol.md):
+  the wrapper requires the same machine protocol major version and tolerates
+  additive minor changes
+- release pairing is stricter for published packages: by default, the wrapper
+  also checks that the spawned `skyffla` binary has the exact same release
+  version as the Node.js package
+
+Set `SKYFFLA_SKIP_VERSION_CHECK=1` only if you intentionally want to run the
+wrapper against a different `skyffla` release. This skips the package-to-binary
+release match, but machine protocol compatibility is still enforced.
+
+## More examples
+
+Runnable example apps live under `examples/node` in the GitHub repository:
+
+- [examples/node](https://github.com/skyffla/skyffla/tree/main/examples/node):
+  shared Node.js example project
+- [examples/node/simple-chat](https://github.com/skyffla/skyffla/tree/main/examples/node/simple-chat):
+  minimal interactive chat client for one room
+- [examples/node/sync-chat-and-channel](https://github.com/skyffla/skyffla/tree/main/examples/node/sync-chat-and-channel):
+  chat plus one machine-channel exchange
+
+## Tests
+
+From a repository checkout:
+
+```sh
+cd wrappers/node
+npm test
+```

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "skyffla",
+  "version": "1.1.3",
+  "description": "Node.js wrapper for skyffla peer-to-peer rooms and automation",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "README.md",
+    "PUBLISHING.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "skyffla",
+    "p2p",
+    "rooms",
+    "automation"
+  ],
+  "author": "Skyffla",
+  "license": "MIT",
+  "homepage": "https://github.com/skyffla/skyffla",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skyffla/skyffla.git"
+  },
+  "bugs": {
+    "url": "https://github.com/skyffla/skyffla/issues"
+  }
+}

package/src/errors.js

@@ -0,0 +1,14 @@
+export class SkyfflaError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+export class SkyfflaProtocolError extends SkyfflaError {}
+
+export class SkyfflaMachineProtocolMismatch extends SkyfflaProtocolError {}
+
+export class SkyfflaProcessExited extends SkyfflaError {}
+
+export class SkyfflaVersionMismatch extends SkyfflaError {}

package/src/index.d.ts

@@ -0,0 +1,336 @@
+export const __version__: string;
+
+export interface ProtocolVersion {
+  major: number;
+  minor: number;
+}
+
+export interface BlobRef {
+  hash: string;
+  format: BlobFormatValue;
+}
+
+export interface Member {
+  member_id: string;
+  name: string;
+  fingerprint?: string;
+}
+
+export interface RouteAll {
+  type: "all";
+}
+
+export interface RouteMember {
+  type: "member";
+  member_id: string;
+}
+
+export type Route = RouteAll | RouteMember;
+
+export interface SendChat {
+  type: "send_chat";
+  to: Route;
+  text: string;
+}
+
+export interface SendFile {
+  type: "send_file";
+  channel_id: string;
+  to: Route;
+  path: string;
+  name?: string;
+  mime?: string;
+}
+
+export interface OpenChannel {
+  type: "open_channel";
+  channel_id: string;
+  kind: ChannelKindValue;
+  to: Route;
+  name?: string;
+  size?: number;
+  mime?: string;
+  blob?: BlobRef;
+}
+
+export interface AcceptChannel {
+  type: "accept_channel";
+  channel_id: string;
+}
+
+export interface RejectChannel {
+  type: "reject_channel";
+  channel_id: string;
+  reason?: string;
+}
+
+export interface SendChannelData {
+  type: "send_channel_data";
+  channel_id: string;
+  body: string;
+}
+
+export interface CloseChannel {
+  type: "close_channel";
+  channel_id: string;
+  reason?: string;
+}
+
+export interface ExportChannelFile {
+  type: "export_channel_file";
+  channel_id: string;
+  path: string;
+}
+
+export type MachineCommand =
+  | SendChat
+  | SendFile
+  | OpenChannel
+  | AcceptChannel
+  | RejectChannel
+  | SendChannelData
+  | CloseChannel
+  | ExportChannelFile;
+
+export interface RoomWelcome {
+  type: "room_welcome";
+  protocol_version: ProtocolVersion;
+  room_id: string;
+  self_member: string;
+  host_member: string;
+}
+
+export interface MemberSnapshot {
+  type: "member_snapshot";
+  members: readonly Member[];
+}
+
+export interface MemberJoined {
+  type: "member_joined";
+  member: Member;
+}
+
+export interface MemberLeft {
+  type: "member_left";
+  member_id: string;
+  reason?: string;
+}
+
+export interface Chat {
+  type: "chat";
+  from: string;
+  from_name: string;
+  to: Route;
+  text: string;
+}
+
+export interface ChannelOpened {
+  type: "channel_opened";
+  channel_id: string;
+  kind: ChannelKindValue;
+  from: string;
+  from_name: string;
+  to: Route;
+  name?: string;
+  size?: number;
+  mime?: string;
+  blob?: BlobRef;
+}
+
+export interface ChannelAccepted {
+  type: "channel_accepted";
+  channel_id: string;
+  member_id: string;
+  member_name: string;
+}
+
+export interface ChannelRejected {
+  type: "channel_rejected";
+  channel_id: string;
+  member_id: string;
+  member_name: string;
+  reason?: string;
+}
+
+export interface ChannelData {
+  type: "channel_data";
+  channel_id: string;
+  from: string;
+  from_name: string;
+  body: string;
+}
+
+export interface ChannelClosed {
+  type: "channel_closed";
+  channel_id: string;
+  member_id: string;
+  member_name: string;
+  reason?: string;
+}
+
+export interface ChannelFileReady {
+  type: "channel_file_ready";
+  channel_id: string;
+  blob: BlobRef;
+}
+
+export interface ChannelFileExported {
+  type: "channel_file_exported";
+  channel_id: string;
+  path: string;
+  size: number;
+}
+
+export interface TransferProgress {
+  type: "transfer_progress";
+  channel_id: string;
+  item_kind: TransferItemKindValue;
+  name: string;
+  phase: TransferPhaseValue;
+  bytes_complete: number;
+  bytes_total?: number;
+}
+
+export interface ErrorEvent {
+  type: "error";
+  code: string;
+  message: string;
+  channel_id?: string;
+}
+
+export type MachineEvent =
+  | RoomWelcome
+  | MemberSnapshot
+  | MemberJoined
+  | MemberLeft
+  | Chat
+  | ChannelOpened
+  | ChannelAccepted
+  | ChannelRejected
+  | ChannelData
+  | ChannelClosed
+  | ChannelFileReady
+  | ChannelFileExported
+  | TransferProgress
+  | ErrorEvent;
+
+export type ChannelKindValue = "machine" | "file" | "clipboard";
+export type BlobFormatValue = "blob" | "collection";
+export type TransferItemKindValue = "file" | "folder";
+export type TransferPhaseValue = "preparing" | "downloading" | "exporting";
+
+export const ChannelKind: Readonly<{
+  MACHINE: "machine";
+  FILE: "file";
+  CLIPBOARD: "clipboard";
+}>;
+
+export const BlobFormat: Readonly<{
+  BLOB: "blob";
+  COLLECTION: "collection";
+}>;
+
+export const TransferItemKind: Readonly<{
+  FILE: "file";
+  FOLDER: "folder";
+}>;
+
+export const TransferPhase: Readonly<{
+  PREPARING: "preparing";
+  DOWNLOADING: "downloading";
+  EXPORTING: "exporting";
+}>;
+
+export const MACHINE_PROTOCOL_VERSION: Readonly<ProtocolVersion>;
+
+export class SkyfflaError extends Error {}
+export class SkyfflaProtocolError extends SkyfflaError {}
+export class SkyfflaMachineProtocolMismatch extends SkyfflaProtocolError {}
+export class SkyfflaProcessExited extends SkyfflaError {}
+export class SkyfflaVersionMismatch extends SkyfflaError {}
+
+export interface SpawnOptions {
+  binary?: string;
+  server?: string;
+  name?: string;
+  downloadDir?: string;
+  local?: boolean;
+}
+
+export interface OpenChannelOptions {
+  kind: ChannelKindValue;
+  to: string | Route;
+  name?: string;
+  size?: number;
+  mime?: string;
+  blob?: BlobRef;
+}
+
+export interface OpenMachineChannelOptions {
+  to: string | Route;
+  name?: string;
+}
+
+export class MachineChannel {
+  readonly room: Room;
+  readonly channelId: string;
+  send(body: string): Promise<void>;
+  accept(): Promise<void>;
+  reject(reason?: string): Promise<void>;
+  close(reason?: string): Promise<void>;
+  exportFile(path: string): Promise<void>;
+}
+
+export class Room implements AsyncIterable<MachineEvent> {
+  readonly role: string;
+  readonly roomId: string;
+  readonly argv: readonly string[];
+  static host(roomId: string, options?: SpawnOptions): Promise<Room>;
+  static join(roomId: string, options?: SpawnOptions): Promise<Room>;
+  channel(channelId: string): MachineChannel;
+  send(command: MachineCommand): Promise<void>;
+  sendChat(to: string | Route, text: string): Promise<void>;
+  sendFile(
+    channelId: string,
+    to: string | Route,
+    path: string,
+    options?: { name?: string; mime?: string },
+  ): Promise<void>;
+  openChannel(channelId: string, options: OpenChannelOptions): Promise<MachineChannel>;
+  openMachineChannel(channelId: string, options: OpenMachineChannelOptions): Promise<MachineChannel>;
+  acceptChannel(channelId: string): Promise<void>;
+  rejectChannel(channelId: string, options?: { reason?: string }): Promise<void>;
+  sendChannelData(channelId: string, body: string): Promise<void>;
+  closeChannel(channelId: string, options?: { reason?: string }): Promise<void>;
+  exportChannelFile(channelId: string, path: string): Promise<void>;
+  recv(): Promise<MachineEvent>;
+  recvUntil(
+    predicate: (event: MachineEvent) => boolean,
+    options?: { timeout?: number },
+  ): Promise<MachineEvent>;
+  waitForWelcome(options?: { timeout?: number }): Promise<RoomWelcome>;
+  waitForMemberSnapshot(options?: { minMembers?: number; timeout?: number }): Promise<MemberSnapshot>;
+  waitForMemberJoined(options?: { name?: string; timeout?: number }): Promise<MemberJoined>;
+  waitForChat(options?: { text?: string; fromName?: string; timeout?: number }): Promise<Chat>;
+  waitForChannelOpened(options?: { channelId?: string; timeout?: number }): Promise<ChannelOpened>;
+  waitForChannelData(options?: { channelId?: string; timeout?: number }): Promise<ChannelData>;
+  stderrLines(): readonly string[];
+  wait(): Promise<number>;
+  close(): Promise<void>;
+  [Symbol.asyncIterator](): AsyncIterator<MachineEvent>;
+}
+
+export function routeAll(): RouteAll;
+export function routeMember(memberId: string): RouteMember;
+export function normalizeRoute(route: string | Route): Route;
+export function parseRoute(value: Route): Route;
+export function parseMachineCommand(value: string | MachineCommand): MachineCommand;
+export function parseMachineEvent(value: string | MachineEvent): MachineEvent;
+export function dumpMessage(message: MachineCommand | MachineEvent): Record<string, unknown>;
+export function dumpMessageJson(message: MachineCommand | MachineEvent): string;
+export function parseCliVersion(text: string): string;
+export function isProtocolCompatible(version: ProtocolVersion, other: ProtocolVersion): boolean;
+export function ensureMachineProtocolVersion(version: ProtocolVersion): void;
+export function ensureReleaseVersion(binaryVersion: string): void;
+export function probeBinaryVersion(binary?: string): Promise<string>;
+export function ensureBinaryVersion(binary?: string): Promise<void>;

package/src/index.js

@@ -0,0 +1,33 @@
+export { __version__ } from "./version.js";
+export {
+  BlobFormat,
+  ChannelKind,
+  MACHINE_PROTOCOL_VERSION,
+  TransferItemKind,
+  TransferPhase,
+  dumpMessage,
+  dumpMessageJson,
+  ensureMachineProtocolVersion,
+  ensureReleaseVersion,
+  isProtocolCompatible,
+  normalizeRoute,
+  parseCliVersion,
+  parseMachineCommand,
+  parseMachineEvent,
+  parseRoute,
+  routeAll,
+  routeMember,
+} from "./protocol.js";
+export {
+  SkyfflaError,
+  SkyfflaMachineProtocolMismatch,
+  SkyfflaProcessExited,
+  SkyfflaProtocolError,
+  SkyfflaVersionMismatch,
+} from "./errors.js";
+export {
+  MachineChannel,
+  Room,
+  ensureBinaryVersion,
+  probeBinaryVersion,
+} from "./room.js";