@bastani/atomic-storage-libsql 0.0.0-stage → 0.9.42-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- First-party libSQL / Turso storage adapter for sessions, workflow journals, and Intercom, published to npm as `@bastani/atomic-storage-libsql` with each Atomic release. Install it with `atomic install npm:@bastani/atomic-storage-libsql` and select it with `"storage": { "adapter": "@bastani/atomic-storage-libsql", "options": { "url": "libsql://<db>.turso.io" }, "secrets": { "authToken": { "file": "..." } } }` ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+
+### Fixed
+
+- Credential redaction scans malformed URLs in linear time, preventing long adversarial URLs from stalling database setup ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- The installed SDK entry now works in plain Node without a TypeScript loader. The package ships ESM JavaScript and TypeScript declarations, with no build step ([#3857](https://github.com/bastani-inc/atomic/issues/3857))

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2025 Bastani, Inc.
+
+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.
+
+If your product or service exceeds 100 million monthly active users or $20 million in monthly revenue, 
+you must prominently display 'Atomic' on the user interface of such product or service.
+
+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,53 @@
-# Temporary Holding Version
+# @bastani/atomic-storage-libsql
 
-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.
+A libSQL / [Turso](https://turso.tech) storage adapter for [Atomic](https://github.com/bastani-inc/atomic). It stores sessions, workflow journals, and Intercom multi-node routing in one shared database, so several machines can use the same state. It is a separate package: install it only where you want remote storage.
+
+## Install
+
+```bash
+atomic install npm:@bastani/atomic-storage-libsql
+```
+
+Install in user scope (without `-l`); Atomic only searches user-scope packages for storage adapters.
+
+## Configure
+
+Select the adapter in `~/.atomic/agent/settings.json`:
+
+```json
+{
+  "storage": {
+    "adapter": "@bastani/atomic-storage-libsql",
+    "options": { "url": "libsql://<db>.turso.io" },
+    "secrets": { "authToken": { "file": "turso-token" } }
+  }
+}
+```
+
+```bash
+turso db tokens create <db> > ~/.atomic/turso-token
+chmod 600 ~/.atomic/turso-token
+```
+
+| Option | Required | Description |
+|---|---|---|
+| `url` | yes | A `libsql://`, `https://`, `wss://`, or `file:` URL. |
+| `authToken` | for remote databases | The database token. Pass it through `secrets` (`{ "file": ... }` or `{ "env": ... }`) so it stays out of settings. |
+
+The token is redacted from error messages and diagnostics. Add a `prefix` to the `storage` block to keep projects or teams apart in one database. See [Storage](../coding-agent/docs/storage.md) for selection precedence, per-process overrides, and the other storage options.
+
+## Use from the SDK
+
+```ts
+import { openLibsqlDatabase } from "@bastani/atomic-storage-libsql";
+
+const database = await openLibsqlDatabase({ url: "libsql://<db>.turso.io", authToken });
+```
+
+The returned `SqliteDatabase` can be passed as SDK `sessionStore: { kind: "database", database }` or workflow `journal: { database }`.
+
+The package ships plain ESM JavaScript with TypeScript declarations. This import works in supported Node versions without a TypeScript loader.
+
+## License
+
+MIT

package/libsql.d.ts

@@ -0,0 +1,14 @@
+import type { AdapterOptions, SqliteDatabase } from "@bastani/atomic/storage";
+
+export interface LibsqlDatabaseOptions {
+	url: string;
+	authToken?: string;
+}
+
+export function openLibsqlDatabase(options: LibsqlDatabaseOptions): Promise<SqliteDatabase>;
+
+declare const adapter: {
+	atomicStorageAdapter: 1;
+	openDatabase(options: AdapterOptions): Promise<SqliteDatabase>;
+};
+export default adapter;

package/libsql.js

@@ -0,0 +1,98 @@
+// @ts-check
+import { createSqliteDatabase, redactSecrets, StorageAdapterLoadError } from "@bastani/atomic/storage";
+
+/** @typedef {{ url: string, authToken?: string }} LibsqlDatabaseOptions */
+
+/**
+ * Credentials a libSQL URL can carry: its userinfo and every `authToken` query value.
+ * @param {string} url
+ * @returns {string[]}
+ */
+function urlCredentials(url) {
+	const secrets = [];
+	// Scan each key/value once, including malformed URLs, without retrying a growing suffix at every '?'.
+	for (let index = 0; index < url.length; index++) {
+		if (url[index] !== "?" && url[index] !== "&") continue;
+		const start = ++index;
+		while (index < url.length && !"?&=#".includes(url[index])) index++;
+		if (url[index] === "=") {
+			const valueStart = ++index;
+			while (index < url.length && url[index] !== "&" && url[index] !== "#") index++;
+			const token = new URLSearchParams(url.slice(start, index)).get("authToken");
+			if (token !== null) secrets.push(url.slice(valueStart, index), token);
+		}
+		index--;
+	}
+	const userinfo = url.match(/\/\/([^/?#]*)@/)?.[1];
+	if (userinfo !== undefined) secrets.push(...userinfo.split(":"));
+	return secrets;
+}
+
+/**
+ * @param {() => import("@libsql/client").Client | import("@libsql/client").Transaction} connection
+ * @returns {import("@bastani/atomic/storage").SqliteDriverExecutor}
+ */
+function statements(connection) {
+	return {
+		async execute(sql, params) {
+			const result = await connection().execute({ sql, args: [...params] });
+			return { columns: result.columns, rows: result.rows, changes: result.rowsAffected };
+		},
+		executeMultiple: (sql) => connection().executeMultiple(sql),
+	};
+}
+
+/**
+ * @param {LibsqlDatabaseOptions} options
+ * @returns {Promise<import("@bastani/atomic/storage").SqliteDatabase>}
+ */
+export async function openLibsqlDatabase({ url, authToken }) {
+	/** @type {typeof import("@libsql/client").createClient} */
+	let createClient;
+	try {
+		({ createClient } = await import("@libsql/client"));
+	} catch (cause) {
+		throw new StorageAdapterLoadError("@libsql/client", /** @type {import("@bastani/atomic/storage").StorageFailureCause} */ (cause));
+	}
+	/** @type {import("@libsql/client").Client | undefined} */
+	let client;
+	// Create the client inside a driver call, so the facade redacts credentials from its failures.
+	const connection = () => (client ??= createClient({ url, authToken, intMode: "bigint" }));
+	const database = createSqliteDatabase({
+		descriptor: { adapter: "libsql", location: url },
+		redact: redactSecrets([authToken ?? "", ...urlCredentials(url)]),
+		...statements(connection),
+		async beginTransaction() {
+			const transaction = await connection().transaction("write");
+			return {
+				...statements(() => transaction),
+				commit: () => transaction.commit(),
+				rollback: () => transaction.rollback(),
+				close: () => transaction.close(),
+			};
+		},
+		close: () => client?.close(),
+	});
+	try {
+		await database.exec("PRAGMA foreign_keys = ON");
+		return database;
+	} catch (error) {
+		await database.close().catch(() => {});
+		throw error;
+	}
+}
+
+/** @satisfies {import("@bastani/atomic/storage").StorageAdapterModule} */
+const adapter = {
+	atomicStorageAdapter: 1,
+	openDatabase(options) {
+		if (typeof options.url !== "string" || options.url === "") {
+			throw new TypeError('The libSQL storage adapter requires a non-empty string "url" option');
+		}
+		return openLibsqlDatabase({
+			url: options.url,
+			authToken: typeof options.authToken === "string" ? options.authToken : undefined,
+		});
+	},
+};
+export default adapter;

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@bastani/atomic-storage-libsql",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.42-alpha.1",
+  "description": "libSQL / Turso storage adapter for Atomic sessions, workflow journals, and Intercom.",
+  "contributors": [
+    "Norin Lavaee",
+    "Alex Lavaee"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "main": "./libsql.js",
+  "types": "./libsql.d.ts",
+  "exports": {
+    ".": {
+      "types": "./libsql.d.ts",
+      "import": "./libsql.js",
+      "default": "./libsql.js"
+    }
+  },
+  "files": [
+    "libsql.js",
+    "libsql.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bastani-inc/atomic.git",
+    "directory": "packages/storage-libsql"
+  },
+  "homepage": "https://github.com/bastani-inc/atomic/tree/main/packages/storage-libsql#readme",
+  "bugs": {
+    "url": "https://github.com/bastani-inc/atomic/issues"
+  },
+  "keywords": [
+    "atomic",
+    "storage",
+    "libsql",
+    "turso",
+    "sqlite",
+    "bastani"
+  ],
+  "atomic": {
+    "storageAdapters": [
+      "./libsql.js"
+    ]
+  },
+  "pi": {
+    "storageAdapters": [
+      "./libsql.js"
+    ]
+  },
+  "dependencies": {
+    "@libsql/client": "0.18.0"
+  },
+  "peerDependencies": {
+    "@bastani/atomic": "*"
+  },
+  "peerDependenciesMeta": {
+    "@bastani/atomic": {
+      "optional": true
+    }
+  }
+}