@pragma-sh/sidecar-kit 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @pragma-sh/sidecar-kit
+
+NDJSON stdin helpers for Pragma host sidecars. Part of [Pragma](https://github.com/pragma-sh/pragma) — a desktop workspace for
+running persistent, worktree-scoped coding agents.
+
+Small shared runtime for a long-lived process a Pragma host supervises over
+standard streams. Used by Pragma's own sidecars and by
+[`@pragma-sh/automations`](https://www.npmjs.com/package/@pragma-sh/automations).
+
+```sh
+bun add @pragma-sh/sidecar-kit
+```
+
+Docs: <https://pragma-app.sh/docs>
+
+## License
+
+AGPL-3.0-only. See [LICENSE](https://github.com/pragma-sh/pragma/blob/main/LICENSE).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pragma-sh/sidecar-kit",
+  "version": "0.1.0",
+  "description": "Shared stdin/NDJSON helpers for Pragma's Bun-compiled host sidecars.",
+  "homepage": "https://github.com/pragma-sh/pragma#readme",
+  "bugs": "https://github.com/pragma-sh/pragma/issues",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pragma-sh/pragma.git",
+    "directory": "packages/sidecar-kit"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun --bun vitest run",
+    "lint": "oxlint ."
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Splits `process.stdin` into trimmed, non-empty NDJSON lines and invokes
+ * `onLine` for each one. Shared by every host sidecar's line-buffered stdin
+ * reader (`pragma-ai`, `pragma-automations`, `pragma-plugins`) so the
+ * buffer-scan logic isn't hand-copied per package.
+ *
+ * `onEnd` runs exactly once when the supervising process closes stdin. A
+ * long-lived sidecar must use it to release its own timers/listeners and exit:
+ * parent death closes the pipe even when the parent cannot run Rust cleanup.
+ */
+export function readStdinLines(onLine: (line: string) => void, onEnd?: () => void): void {
+  let buffer = "";
+  let ended = false;
+  const finish = (): void => {
+    if (ended) return;
+    ended = true;
+    onEnd?.();
+  };
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk: string) => {
+    buffer += chunk;
+    let newline = buffer.indexOf("\n");
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (line) onLine(line);
+      newline = buffer.indexOf("\n");
+    }
+  });
+  process.stdin.once("end", finish);
+  process.stdin.once("close", finish);
+}