@plurnk/plurnk-execs-sqlite 0.1.0

package/LICENSE

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

@@ -0,0 +1,39 @@
+# @plurnk/plurnk-execs-sqlite
+
+SQLite runtime executor for [plurnk-service](https://github.com/plurnk/plurnk-service)'s `exec` scheme. Runs the `sqlite` runtime tag **in-process** via Node's builtin `node:sqlite` — no subprocess.
+
+A `@plurnk/plurnk-execs-*` sibling built on the [plurnk-execs](https://github.com/plurnk/plurnk-execs) framework.
+
+## Runtime tag
+
+| Tag | Glyph | Engine |
+|---|---|---|
+| `sqlite` | 🗃 | `node:sqlite` (Node 25 builtin) |
+
+## Database target
+
+The EXEC target slot is the database file; with no target it defaults to an ephemeral in-memory db:
+
+```
+<<EXEC[sqlite]:SELECT * FROM users:EXEC            → :memory: (fresh per run)
+<<EXEC[sqlite](./app.db):SELECT * FROM users:EXEC  → ./app.db (persistent)
+```
+
+`:memory:` is ephemeral — state does not persist across EXECs. Pass a file path for persistence.
+
+## Output
+
+Writes to the `results` channel as `application/json`, ready for the jsonpath body-matcher (plurnk-mimetypes' JSON handler):
+
+- **Row-returning statements** (SELECT, RETURNING, PRAGMA) → an array of row objects.
+- **Mutations** (INSERT/UPDATE/DELETE/DDL) → `{ changes, lastInsertRowid }`.
+
+The query/mutation split is decided by the prepared statement's `columns()`, never by parsing the SQL. One statement per EXEC. Errors emit a `TelemetryEvent` (`source: "exec:sqlite"`): `sqlite_open_failed`, `sqlite_error`.
+
+## Availability & proposal gating
+
+`probe()` always reports available (`node:sqlite` is a builtin). `effect()` — which will mark `:memory:` as `pure` (auto-run) and a file-backed db as `host` (propose) — is pending the contract addition in plurnk-service#182 and lands when that does.
+
+## Tests
+
+`test:lint`, `test:unit`.

package/dist/Sqlite.d.ts

@@ -0,0 +1,8 @@
+import { BaseExecutor } from "@plurnk/plurnk-execs";
+import type { ChannelDecl, ExecArgs, ExecResult, RuntimeAvailability } from "@plurnk/plurnk-execs";
+export default class Sqlite extends BaseExecutor {
+    get channels(): Readonly<Record<string, ChannelDecl>>;
+    probe(): Promise<RuntimeAvailability>;
+    run({ command, cwd, write, setState, emit }: ExecArgs): Promise<ExecResult>;
+}
+//# sourceMappingURL=Sqlite.d.ts.map

package/dist/Sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sqlite.d.ts","sourceRoot":"","sources":["../src/Sqlite.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAuBnG,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,YAAY;IAC5C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAEpD;IAGc,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAI9C,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;CA4BpF"}

package/dist/Sqlite.js

@@ -0,0 +1,60 @@
+import { DatabaseSync } from "node:sqlite";
+import { BaseExecutor } from "@plurnk/plurnk-execs";
+const MEMORY = ":memory:";
+// node:sqlite can return bigint for large integers; stringify them so the
+// JSON output is always serializable.
+const jsonReplacer = (_key, value) => (typeof value === "bigint" ? value.toString() : value);
+// In-process SQLite executor (a logical runtime, not subprocess). Runs one SQL
+// statement via node:sqlite against the EXEC target db — defaulting to an
+// ephemeral `:memory:` when no target is given — and writes the result to the
+// `results` channel as application/json, ready for the jsonpath body-matcher.
+//
+//   <<EXEC[sqlite]:SELECT * FROM users:EXEC          → :memory: (ephemeral)
+//   <<EXEC[sqlite](./app.db):SELECT * FROM users:EXEC → ./app.db (persistent)
+//
+// Row-returning statements (SELECT, RETURNING, PRAGMA) write an array of row
+// objects; mutations write `{ changes, lastInsertRowid }`. The query/mutation
+// split is decided by `columns()` — never by parsing the SQL.
+//
+// NOTE: `effect()` (per-runtime proposal gating; :memory:→pure, file→host) is
+// pending the contract addition in plurnk-service#182 and lands when that does.
+export default class Sqlite extends BaseExecutor {
+    get channels() {
+        return { results: { mimetype: "application/json" } };
+    }
+    // Always available — node:sqlite is a Node 25 builtin, in-process.
+    async probe() {
+        return { available: true, detail: "node:sqlite" };
+    }
+    async run({ command, cwd, write, setState, emit }) {
+        const path = cwd && cwd.length > 0 ? cwd : MEMORY;
+        const sql = command.trim();
+        const fail = (kind, message) => {
+            emit({ source: "exec:sqlite", kind, message });
+            setState("results", "errored");
+            return { status: 500 };
+        };
+        let db;
+        try {
+            db = new DatabaseSync(path);
+        }
+        catch (err) {
+            return fail("sqlite_open_failed", `cannot open database '${path}': ${err.message}`);
+        }
+        try {
+            const stmt = db.prepare(sql);
+            // Non-empty columns ⇒ a row-returning statement; empty ⇒ a mutation.
+            const output = stmt.columns().length > 0 ? stmt.all() : stmt.run();
+            write("results", JSON.stringify(output, jsonReplacer));
+            setState("results", "closed");
+            return { status: 200 };
+        }
+        catch (err) {
+            return fail("sqlite_error", `${err.message}; db='${path}'`);
+        }
+        finally {
+            db.close();
+        }
+    }
+}
+//# sourceMappingURL=Sqlite.js.map

package/dist/Sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sqlite.js","sourceRoot":"","sources":["../src/Sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGpD,MAAM,MAAM,GAAG,UAAU,CAAC;AAE1B,0EAA0E;AAC1E,sCAAsC;AACtC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,KAAc,EAAW,EAAE,CAC3D,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAE3D,+EAA+E;AAC/E,0EAA0E;AAC1E,8EAA8E;AAC9E,8EAA8E;AAC9E,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,8DAA8D;AAC9D,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,YAAY;IAC5C,IAAI,QAAQ;QACR,OAAO,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,kBAAkB,EAAE,EAAE,CAAC;IACzD,CAAC;IAED,mEAAmE;IAC1D,KAAK,CAAC,KAAK;QAChB,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAY;QACvD,MAAM,IAAI,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;QAClD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,OAAe,EAAc,EAAE;YACvD,IAAI,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YAC/C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YAC/B,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAC3B,CAAC,CAAC;QAEF,IAAI,EAAgB,CAAC;QACrB,IAAI,CAAC;YACD,EAAE,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,IAAI,CAAC,oBAAoB,EAAE,yBAAyB,IAAI,MAAO,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACnG,CAAC;QACD,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,qEAAqE;YACrE,MAAM,MAAM,GAAY,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAC5E,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;YACvD,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC9B,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,IAAI,CAAC,cAAc,EAAE,GAAI,GAAa,CAAC,OAAO,SAAS,IAAI,GAAG,CAAC,CAAC;QAC3E,CAAC;gBAAS,CAAC;YACP,EAAE,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;IACL,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Sqlite } from "./Sqlite.ts";
+export { default } from "./Sqlite.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default as Sqlite } from "./Sqlite.js";
+export { default } from "./Sqlite.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@plurnk/plurnk-execs-sqlite",
+    "version": "0.1.0",
+    "description": "SQLite runtime executor for plurnk-service's exec scheme — runs the sqlite runtime tag in-process via node:sqlite, results as application/json.",
+    "keywords": ["plurnk", "exec", "runtime", "executor", "sqlite", "sql"],
+    "homepage": "https://github.com/plurnk/plurnk-execs-sqlite#readme",
+    "bugs": {
+        "url": "https://github.com/plurnk/plurnk-execs-sqlite/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plurnk/plurnk-execs-sqlite.git"
+    },
+    "engines": {
+        "node": ">=25"
+    },
+    "license": "MIT",
+    "author": "@wikitopian",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "plurnk": {
+        "kind": "exec",
+        "runtimes": [
+            { "name": "sqlite", "glyph": "🗃" }
+        ]
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "README.md"
+    ],
+    "scripts": {
+        "test:lint": "tsc --noEmit",
+        "test:unit": "node --test src/**/*.test.ts",
+        "test": "npm run test:lint && npm run test:unit",
+        "build:dist": "tsc -p tsconfig.build.json",
+        "build": "npm run build:dist",
+        "prepare": "npm run build"
+    },
+    "dependencies": {
+        "@plurnk/plurnk-execs": "0.3.0"
+    },
+    "devDependencies": {
+        "@types/node": "^25.8.0",
+        "typescript": "^6.0.3"
+    }
+}