@parity/product-sdk-terminal 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,261 @@
+# @parity/product-sdk-terminal
+
+> Migrated from `@polkadot-apps/terminal` v0.3.0 (`paritytech/polkadot-apps`).
+
+QR code login, attestation, and transaction signing for CLI/terminal apps via the Polkadot mobile wallet.
+
+Wraps the [`@novasamatech/host-papp`](https://www.npmjs.com/package/@novasamatech/host-papp) SDK with Node.js-compatible adapters (file-based storage, WebSocket transport) so the full SSO protocol works outside the browser.
+
+## Installation
+
+```bash
+pnpm add @parity/product-sdk-terminal
+```
+
+## Setup
+
+**Requires Node ≥21.** The package relies on the global `WebSocket` exposed by Node 21+ (via `@polkadot-api/ws-provider@0.9`). On older Node versions the WebSocket connection fails at runtime with `WebSocket is not defined`.
+
+**Register the WASM loader** — the host-papp SDK depends on `verifiablejs` which uses inline WASM (browser-only). The register hook redirects it to the Node.js WASM build. Pass it via `--import`:
+
+```bash
+node --import @parity/product-sdk-terminal/register app.js
+tsx --import @parity/product-sdk-terminal/register app.ts
+```
+
+Or in your `package.json` scripts:
+
+```json
+{
+    "scripts": {
+        "start": "tsx --import @parity/product-sdk-terminal/register index.ts"
+    }
+}
+```
+
+## Quick Start
+
+```ts
+import { createTerminalAdapter, renderQrCode, waitForSessions } from "@parity/product-sdk-terminal";
+
+// 1. Create the adapter
+const adapter = createTerminalAdapter({
+    appId: "my-terminal-app",
+    metadataUrl: "https://example.com/metadata.json",
+});
+
+// 2. Subscribe to pairing status to show the QR code
+adapter.sso.pairingStatus.subscribe(async (status) => {
+    if (status.step === "pairing") {
+        console.log(await renderQrCode(status.payload));
+        console.log("Scan with the Polkadot mobile app...");
+    }
+});
+
+// 3. Authenticate (QR pairing + on-chain attestation)
+const result = await adapter.sso.authenticate();
+
+result.match(
+    (session) => console.log("Logged in!", session?.id),
+    (error) => console.error("Failed:", error.message),
+);
+
+// 4. Wait for sessions to load (they load asynchronously from disk)
+const sessions = await waitForSessions(adapter, 2000);
+
+// 5. Sign messages via the paired wallet
+if (sessions.length > 0) {
+    const session = sessions[0];
+    const signer = createSessionSigner(session, adapter);
+    // use signer with polkadot-api transactions
+}
+```
+
+## API
+
+### `createTerminalAdapter(options): TerminalAdapter`
+
+Creates a terminal adapter backed by the host-papp SDK.
+
+**Options:**
+- `appId` -- unique app identifier (used as storage namespace)
+- `metadataUrl` -- URL to metadata JSON shown during pairing
+- `endpoints?` -- statement store WebSocket endpoints (defaults to Paseo)
+- `hostMetadata?` -- optional host environment info
+- `storageDir?` -- override the on-disk session directory (defaults to `~/.polkadot-apps/`). Useful in tests and containerised environments.
+
+**Returns** a `TerminalAdapter` with:
+- `appId` -- the value you passed in (re-exposed so `createSessionSigner` can pull the productId from the adapter)
+- `sso` -- auth component (`.authenticate()`, `.abortAuthentication()`, status subscriptions)
+- `sessions` -- session manager (signing, disconnect)
+- `destroy()` -- disconnect the WebSocket and release resources. Idempotent. Suppresses `@novasamatech/statement-store`'s noisy `Statement subscription error` log for ~50 ms after the call.
+
+### `createSessionSigner(session, adapter): PolkadotSigner`
+
+Creates a `PolkadotSigner` backed by a QR-paired mobile wallet session, using the session's **default account** (`derivationIndex: 0`) under the adapter's `appId`. This is the right entry point for ~all CLI flows.
+
+```ts
+const [session] = adapter.sessions.sessions.read();
+const signer = createSessionSigner(session, adapter);
+await contract.publish.tx(domain, cid, { signer, origin });
+```
+
+### `createSessionSignerForAccount(session, ref): PolkadotSigner`
+
+Escape hatch for signing as a non-default sub-account of a paired session, or as a `productId` that differs from the adapter's `appId`. Most callers don't need this.
+
+`ref` is `{ productId: string; derivationIndex: number }`:
+- `productId` -- dotNS-style identifier of the requesting product. In normal usage this equals the adapter's `appId`; pass a different value only if you have an explicit reason.
+- `derivationIndex` -- BIP32-style child-key index. `0` is the default account; non-zero indices reach additional sub-accounts derived from the same root.
+
+```ts
+const subSigner = createSessionSignerForAccount(session, {
+    productId: "my-product",
+    derivationIndex: 3,
+});
+```
+
+> **Wire format note:** `@novasamatech/host-papp` 0.7 expects `productAccountId: [productId, derivationIndex]` in `SigningRawRequest`. Both functions above hide that tuple — pass an adapter for the default case or a named-fields object for the escape hatch.
+
+### `renderQrCode(data, options?): Promise<string>`
+
+Render a string as a QR code using Unicode half-block characters for terminal display.
+
+### `createNodeStorageAdapter(appId, storageDir?): StorageAdapter`
+
+File-based storage adapter for Node.js. Data persists in `storageDir` (defaults to `~/.polkadot-apps/`).
+
+### `waitForSessions(adapter, timeoutMs?): Promise<UserSession[]>`
+
+Waits for the session list to emit at least one entry, or resolves with `[]` after `timeoutMs`.
+
+## Migration from `@polkadot-apps/terminal`
+
+For consumers moving from `@polkadot-apps/terminal` v0.2.0 / v0.3.0. Existing sessions on disk (`~/.polkadot-apps/`) carry over — same `appId`, same path. No re-pairing required for the migration itself.
+
+| Concern | `@polkadot-apps/terminal` | `@parity/product-sdk-terminal` |
+| --- | --- | --- |
+| Package name | `@polkadot-apps/terminal` | `@parity/product-sdk-terminal` |
+| Register import path | `--import @polkadot-apps/terminal/register` | `--import @parity/product-sdk-terminal/register` |
+| `createTerminalAdapter` | `async` — returned `Promise<TerminalAdapter>` | **sync** — returns `TerminalAdapter` directly. Drop the `await`. |
+| Default account signer | `createSessionSigner(session)` | `createSessionSigner(session, adapter)` — pass the adapter as second arg |
+| Non-default sub-account signer | not exposed | `createSessionSignerForAccount(session, { productId, derivationIndex })` |
+| Override session storage dir | not supported (hard-coded `~/.polkadot-apps/`) | `createTerminalAdapter({ ..., storageDir })` option |
+| E2E test helper for sessions | none | `createTestSession` from `@parity/product-sdk-terminal/testing` |
+| Node version | any (bundled `ws`) | **≥21** (uses global `WebSocket`) |
+| `destroy()` shutdown noise | emitted `Statement subscription error` to stderr | suppressed; `console.error` muted for ~50 ms |
+
+### Why the signer API changed
+
+`@novasamatech/host-papp` 0.7 replaced `SigningRawRequest.address` with `productAccountId: [productId, derivationIndex]`. The wire format requires both fields, so a session-only argument is no longer enough — the signer needs to know *which sub-account of which product is asking*. We split that into two functions to keep the common case ergonomic:
+
+- `createSessionSigner(session, adapter)` for the default account (uses `[adapter.appId, 0]`)
+- `createSessionSignerForAccount(session, { productId, derivationIndex })` for everything else
+
+The single-argument `createSessionSigner(session)` from `@polkadot-apps/terminal` no longer works against host-papp 0.7 regardless of which package you use.
+
+### Migration steps
+
+1. **Replace the dep**: `pnpm remove @polkadot-apps/terminal && pnpm add @parity/product-sdk-terminal`
+2. **Update the `--import` flag** in your `node` / `tsx` invocations or `package.json` scripts.
+3. **Drop `await`** in front of `createTerminalAdapter(...)` calls.
+4. **Update each `createSessionSigner` call site**: change `createSessionSigner(session)` → `createSessionSigner(session, adapter)`.
+5. **Verify Node version** is ≥21 (`node --version`).
+
+If your existing sessions don't appear after migrating, double-check that the `appId` is identical to what you used in `@polkadot-apps/terminal` — the on-disk file names depend on it.
+
+## Testing
+
+The `@parity/product-sdk-terminal/testing` subpath exports `createTestSession`, a helper that synthesizes a valid persisted session on disk. E2E tests can inject a known-good session without going through QR pairing + attestation:
+
+```ts
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTerminalAdapter, waitForSessions } from "@parity/product-sdk-terminal";
+import { createTestSession } from "@parity/product-sdk-terminal/testing";
+
+const storageDir = mkdtempSync(join(tmpdir(), "e2e-"));
+const { sessionId } = await createTestSession({
+    appId: "my-terminal-app",
+    storageDir,
+});
+
+const adapter = createTerminalAdapter({
+    appId: "my-terminal-app",
+    metadataUrl: "https://example.com/metadata.json",
+    storageDir,
+});
+const sessions = await waitForSessions(adapter);
+// sessions[0].id === sessionId
+```
+
+**Limits and usage notes.**
+
+- **Signing does not round-trip.** `session.signRaw` goes out over the statement store and expects a real phone to respond. Use this helper for flows that test session discovery, persistence, and logout — not happy-path signing.
+- **Expiry tests still work.** The synthesized local account was never registered on the People chain, so any statement-store write from this session fails with `NoAllowanceError`. That's the same error the CLI sees when a previously valid session's on-chain attestation has expired.
+- **No `expiresAt` option.** The on-disk codec has no expiry field; validity lives on chain.
+- **Corrupted-session cases** don't need a helper — `fs.writeFile("<storageDir>/<appId>_SsoSessions.json", "not-hex")` from the test is enough.
+
+## Signing
+
+After login and attestation, the paired wallet can sign messages via the statement store.
+
+**`signRaw`** works end-to-end: the wallet receives the request, shows a prompt, and returns the signature.
+
+**`signPayload`** (for signing transaction payloads) is not yet functional — the request is submitted but the wallet does not respond. This is a known limitation of the current wallet/protocol version.
+
+## Notes
+
+### WebSocket transport
+
+The adapter uses `@polkadot-api/ws-provider@0.9`, which relies on the global `WebSocket` exposed by Node ≥21. Older Node versions (18, 20) will fail at connect time with `WebSocket is not defined` — upgrade Node, or pass an explicit `websocketClass` from the [`ws`](https://www.npmjs.com/package/ws) package.
+
+The default WebSocket is constructed without `followRedirects: true`, so endpoints behind an HTTP redirect will fail to connect. If you must point at an endpoint that does, supply the resolved URL directly via the `endpoints` option.
+
+### `ExperimentalWarning: Importing WebAssembly module instances`
+
+You'll see this warning at startup:
+
+```
+(node:NNNNN) ExperimentalWarning: Importing WebAssembly module instances is an experimental feature and might change at any time
+```
+
+It's emitted by Node when the loader hook imports the `verifiablejs` WASM. Harmless. To silence it, run with `--no-warnings=ExperimentalWarning`.
+
+## How It Works
+
+1. **QR Pairing** -- generates Sr25519 + P256 keypairs, encodes a `polkadotapp://pair?handshake=0x...` deep link, subscribes to the statement store
+2. **Attestation** -- registers the local account on the People chain so it can publish statements
+3. **Signing** -- sends encrypted signing requests to the wallet via the statement store, receives signed responses
+
+Sessions are persisted to `~/.polkadot-apps/` and survive across restarts. The SDK loads them asynchronously on startup — subscribe to `adapter.sessions.sessions` and wait for the first emission.
+
+## Dependencies
+
+- `@novasamatech/host-papp` -- Polkadot host-product SDK (auth, attestation, signing)
+- `@novasamatech/statement-store` -- statement store client and session management
+- `@novasamatech/storage-adapter` -- storage interface
+- `@polkadot-api/ws-provider` -- WebSocket JSON-RPC provider
+- `neverthrow` -- Result type for error handling
+- `qrcode` -- QR code generation
+
+## Future Work
+
+- **`KvStore`↔`StorageAdapter` bridge.** This package implements its own file-backed `StorageAdapter` for Node.js (`createNodeStorageAdapter`). Once `@parity/product-sdk-storage` grows a file backend with the same `read/write/clear/subscribe` `ResultAsync` shape, replace `node-storage.ts` with a thin adapter over it.
+- **Codec re-exports from `@parity/product-sdk-statement-store`.** `testing.ts` imports session-account codec helpers (`AccountIdCodec`, `LocalSessionAccountCodec`, etc.) directly from `@novasamatech/statement-store`. Re-exporting them through the in-monorepo wrapper would let this package depend only on workspace siblings.
+- **Embedded host runner for allowance / attestation refresh.** Today this package consumes a paired session and signs against it, but cannot renew the on-chain attestation that gates allowance writes — once it expires the user has to re-do the full QR pairing. The proposed fix is a new `./host` sub-export (in addition to `.`, `./register`, `./testing`) exposing roughly:
+  ```ts
+  // proposed shape — not yet implemented
+  export interface AllowanceManager {
+      isExpired(): boolean;
+      refresh(): ResultAsync<void, Error>;
+      currentAttestation(): ResultAsync<Attestation, Error>;
+  }
+  export function createAllowanceManager(
+      adapter: TerminalAdapter,
+      options?: { hostEndpoint?: string },
+  ): AllowanceManager;
+  ```
+  Implementation should sit on top of `@parity/product-sdk-host`'s container/storage primitives so the host runner is shared with browser/desktop hosts rather than being CLI-specific. This is the gap Tarik flagged as "the CLI might also need to run some kind of host to get allowances".
+- **`@noble/*` major version drift.** This package pins `@noble/{ciphers,curves,hashes}: ^2.x` because upstream `@polkadot-apps/terminal` did, and the `testing.ts` codec helpers use the v2 import paths (`@noble/hashes/blake2.js`, `@noble/curves/nist.js`). The rest of the monorepo is on `^1.x`. Both majors coexist in the lockfile; not a runtime problem today but worth a coordinated bump. Either move the whole monorepo to v2, or rewrite `testing.ts` against v1 paths (`@noble/hashes/blake2b.js` etc.).

package/dist/chunk-5MCLSFKQ.js

@@ -0,0 +1,210 @@
+// src/node-storage.ts
+import { createLogger } from "@parity/product-sdk-logger";
+import { fromPromise } from "neverthrow";
+import { join } from "path";
+import { readFile, writeFile, mkdir, unlink } from "fs/promises";
+import { homedir } from "os";
+var log = createLogger("terminal");
+var DEFAULT_STORAGE_DIR = join(homedir(), ".polkadot-apps");
+function sanitizeKey(appId, key) {
+  return `${appId}_${key}`.replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+function toError(e) {
+  return e instanceof Error ? e : new Error(String(e));
+}
+function createNodeStorageAdapter(appId, storageDir) {
+  const dir = storageDir ?? DEFAULT_STORAGE_DIR;
+  let dirCreated = false;
+  const subscribers = /* @__PURE__ */ new Map();
+  function fp(key) {
+    return join(dir, `${sanitizeKey(appId, key)}.json`);
+  }
+  async function ensureDir() {
+    if (dirCreated) return;
+    await mkdir(dir, { recursive: true });
+    dirCreated = true;
+  }
+  function notifySubscribers(key, value) {
+    const subs = subscribers.get(key);
+    if (subs) {
+      for (const cb of subs) {
+        try {
+          cb(value);
+        } catch (e) {
+          log.warn("storage subscriber callback threw", { key, error: e });
+        }
+      }
+    }
+  }
+  return {
+    read(key) {
+      return fromPromise(
+        readFile(fp(key), "utf-8").catch((e) => {
+          if (e.code !== "ENOENT") {
+            log.warn("storage read failed", { key, error: e });
+          } else {
+            log.debug("storage read miss", { key });
+          }
+          return null;
+        }),
+        toError
+      );
+    },
+    write(key, value) {
+      return fromPromise(
+        ensureDir().then(() => writeFile(fp(key), value, "utf-8")).then(() => {
+          notifySubscribers(key, value);
+        }),
+        toError
+      ).map(() => void 0);
+    },
+    clear(key) {
+      return fromPromise(
+        unlink(fp(key)).catch(() => {
+        }).then(() => {
+          notifySubscribers(key, null);
+        }),
+        toError
+      ).map(() => void 0);
+    },
+    subscribe(key, callback) {
+      if (!subscribers.has(key)) {
+        subscribers.set(key, /* @__PURE__ */ new Set());
+      }
+      subscribers.get(key).add(callback);
+      return () => {
+        subscribers.get(key)?.delete(callback);
+      };
+    }
+  };
+}
+if (void 0) {
+  const { describe, test, expect, beforeEach, afterAll } = void 0;
+  const { mkdtemp, rm } = await null;
+  const { tmpdir } = await null;
+  const { configure } = await null;
+  let testDir;
+  beforeEach(async () => {
+    configure({ handler: () => {
+    } });
+    testDir = await mkdtemp(join(tmpdir(), "terminal-storage-test-"));
+  });
+  afterAll(async () => {
+    try {
+      await rm(testDir, { recursive: true });
+    } catch {
+    }
+  });
+  describe("createNodeStorageAdapter", () => {
+    test("read returns null for missing key", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      const result = await store.read("nonexistent");
+      expect(result.isOk()).toBe(true);
+      expect(result._unsafeUnwrap()).toBeNull();
+    });
+    test("write and read round-trip", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      await store.write("key1", "hello");
+      const result = await store.read("key1");
+      expect(result._unsafeUnwrap()).toBe("hello");
+    });
+    test("write overwrites existing value", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      await store.write("key1", "first");
+      await store.write("key1", "second");
+      const result = await store.read("key1");
+      expect(result._unsafeUnwrap()).toBe("second");
+    });
+    test("clear removes key", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      await store.write("key1", "value");
+      await store.clear("key1");
+      const result = await store.read("key1");
+      expect(result._unsafeUnwrap()).toBeNull();
+    });
+    test("clear is safe for missing key", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      const result = await store.clear("nonexistent");
+      expect(result.isOk()).toBe(true);
+    });
+    test("different appIds are isolated", async () => {
+      const storeA = createNodeStorageAdapter("app-a", testDir);
+      const storeB = createNodeStorageAdapter("app-b", testDir);
+      await storeA.write("key", "from-a");
+      await storeB.write("key", "from-b");
+      expect((await storeA.read("key"))._unsafeUnwrap()).toBe("from-a");
+      expect((await storeB.read("key"))._unsafeUnwrap()).toBe("from-b");
+    });
+    test("subscribe notifies on write", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      const values = [];
+      store.subscribe("key1", (v) => values.push(v));
+      await store.write("key1", "hello");
+      expect(values).toEqual(["hello"]);
+    });
+    test("subscribe notifies on clear", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      const values = [];
+      await store.write("key1", "hello");
+      store.subscribe("key1", (v) => values.push(v));
+      await store.clear("key1");
+      expect(values).toEqual([null]);
+    });
+    test("unsubscribe stops notifications", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      const values = [];
+      const unsub = store.subscribe("key1", (v) => values.push(v));
+      await store.write("key1", "first");
+      unsub();
+      await store.write("key1", "second");
+      expect(values).toEqual(["first"]);
+    });
+    test("subscriber errors do not break other subscribers", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      const values = [];
+      store.subscribe("key1", () => {
+        throw new Error("boom");
+      });
+      store.subscribe("key1", (v) => {
+        if (v) values.push(v);
+      });
+      await store.write("key1", "hello");
+      expect(values).toEqual(["hello"]);
+    });
+    test("sanitizes special characters in keys", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      await store.write("key/with:special chars!", "value");
+      const result = await store.read("key/with:special chars!");
+      expect(result._unsafeUnwrap()).toBe("value");
+    });
+    test("handles JSON values", async () => {
+      const store = createNodeStorageAdapter("test", testDir);
+      const obj = { name: "test", count: 42, nested: { ok: true } };
+      await store.write("json", JSON.stringify(obj));
+      const raw = (await store.read("json"))._unsafeUnwrap();
+      expect(JSON.parse(raw)).toEqual(obj);
+    });
+  });
+  describe("toError", () => {
+    test("returns Error instances unchanged", () => {
+      const original = new TypeError("boom");
+      expect(toError(original)).toBe(original);
+    });
+    test("wraps non-Error string values", () => {
+      const result = toError("primitive failure");
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toBe("primitive failure");
+    });
+    test("wraps non-Error nullish values", () => {
+      const result = toError(null);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toBe("null");
+    });
+  });
+}
+
+export {
+  sanitizeKey,
+  createNodeStorageAdapter
+};
+//# sourceMappingURL=chunk-5MCLSFKQ.js.map