@vrtmrz/livesync-commonlib 0.1.0-rc.0

package/dist/worker/bgWorker.splitting.d.ts

@@ -0,0 +1,27 @@
+import { type ResultPayloadWithSeq, type SplitProcessItem } from "./universalTypes.js";
+/**
+ * Splits data into pieces using a worker.
+ * @param dataSrc The source data to be split.
+ * @param pieceSize The size of each piece.
+ * @param plainSplit Whether to use plain splitting.
+ * @param minimumChunkSize The minimum size of each chunk.
+ * @param filename The name of the file being processed.
+ * @param splitVersion The version of the splitting algorithm to use.
+ * @param useSegmenter Whether to use a segmenter (only works on splitVersion:2)
+ * @returns A generator that yields the split pieces.
+ */
+export declare function _splitPieces2Worker(dataSrc: Blob, pieceSize: number, plainSplit: boolean, minimumChunkSize: number, filename: string | undefined, splitVersion: 1 | 2 | 3, useSegmenter: boolean): () => AsyncGenerator<string, void, unknown>;
+/**
+ * Aborts all in-flight split tasks identified by the given keys.
+ * Called when the background worker that owned these tasks has crashed, so the streams
+ * will never receive any more data and must be torn down to unblock callers.
+ * @param keys The task keys to abort.
+ * @param error The error to report to each stream.
+ */
+export declare function abortSplitTasks(keys: number[], error: Error): void;
+/**
+ * Handles the splitting callback from the worker.
+ * @param process the splitting process item
+ * @param data the data received from the worker
+ */
+export declare function handleTaskSplit(process: SplitProcessItem, data: ResultPayloadWithSeq): void;

package/dist/worker/bgWorker.splitting.js

@@ -0,0 +1,123 @@
+import { LOG_LEVEL_VERBOSE, Logger } from "../common/logger.js";
+import { startWorker, removeTask } from "./bgWorker.js";
+import {} from "./universalTypes.js";
+const SYMBOL_USED = /* @__PURE__ */ Symbol("used");
+const SYMBOL_END_OF_DATA = /* @__PURE__ */ Symbol("endOfData");
+const workerStreams = /* @__PURE__ */ new Map();
+const writers = /* @__PURE__ */ new Map();
+const responseBuf = /* @__PURE__ */ new Map();
+let writerPromise = Promise.resolve();
+function _splitPieces2Worker(dataSrc, pieceSize, plainSplit, minimumChunkSize, filename, splitVersion, useSegmenter) {
+  const process = startWorker({
+    type: "split",
+    dataSrc,
+    pieceSize,
+    plainSplit,
+    minimumChunkSize,
+    filename,
+    useSegmenter,
+    splitVersion
+  });
+  const _key = process.key;
+  const stream = new TransformStream({
+    transform: (chunk, controller) => {
+      if (chunk === null) {
+        controller.terminate();
+        return;
+      }
+      controller.enqueue(chunk);
+    },
+    flush: () => {
+    }
+  });
+  workerStreams.set(_key, stream);
+  const readable = stream.readable;
+  const reader = readable.getReader();
+  const writer = stream.writable.getWriter();
+  writers.set(_key, writer);
+  return async function* () {
+    try {
+      let done = false;
+      do {
+        const results = await reader.read();
+        done = results.done;
+        if (done) {
+          break;
+        }
+        yield results.value;
+      } while (!done);
+    } catch (ex) {
+      Logger(`Error in worker stream for key ${_key}`);
+      Logger(ex, LOG_LEVEL_VERBOSE);
+      throw ex;
+    } finally {
+      process.finalize();
+      workerStreams.delete(_key);
+      writers.delete(_key);
+    }
+  };
+}
+function abortSplitTasks(keys, error) {
+  for (const key of keys) {
+    responseBuf.delete(key);
+    writerPromise = writerPromise.then(async () => {
+      const writer = writers.get(key);
+      if (writer) {
+        await writer.abort(error);
+        writers.delete(key);
+      }
+      workerStreams.delete(key);
+    });
+  }
+}
+function handleTaskSplit(process, data) {
+  const key = data.key;
+  if (!("result" in data)) {
+    responseBuf.delete(key);
+    const reportError = data.error || new Error("Unknown error in background splitting");
+    writerPromise = writerPromise.then(async () => {
+      const writer = writers.get(key);
+      if (writer) {
+        await writer.abort(reportError);
+      }
+    });
+    return;
+  }
+  let thisBuf = responseBuf.get(key);
+  if (!thisBuf) {
+    thisBuf = /* @__PURE__ */ new Map();
+    responseBuf.set(key, thisBuf);
+  }
+  const seq = data.seq;
+  thisBuf.set(seq, data.result === null ? SYMBOL_END_OF_DATA : data.result);
+  responseBuf.set(key, thisBuf);
+  const keys = Array.from(thisBuf.keys()).sort((a, b) => a - b);
+  const max = keys[keys.length - 1];
+  for (let i = 0; i <= max; i++) {
+    const result = thisBuf.get(i);
+    if (result === void 0) {
+      break;
+    }
+    if (result === SYMBOL_USED) {
+      continue;
+    }
+    thisBuf.set(i, SYMBOL_USED);
+    responseBuf.set(key, thisBuf);
+    writerPromise = writerPromise.then(async () => {
+      const writer = writers.get(key);
+      if (!writer) {
+        throw new Error(`Invalid writer for key ${key} in background splitting`);
+      }
+      await writer.write(result === SYMBOL_END_OF_DATA ? null : result);
+      if (result === SYMBOL_END_OF_DATA) {
+        removeTask(key);
+        responseBuf.delete(key);
+      }
+    });
+  }
+}
+export {
+  _splitPieces2Worker,
+  abortSplitTasks,
+  handleTaskSplit
+};

package/dist/worker/universalTypes.d.ts

@@ -0,0 +1,63 @@
+import type { PromiseWithResolvers } from "octagonal-wheels/promises";
+export type EncryptArguments = {
+    key: number;
+    type: "encrypt" | "decrypt";
+    input: string;
+    passphrase: string;
+    autoCalculateIterations: boolean;
+};
+export type EncryptHKDFArguments = {
+    key: number;
+    type: "encryptHKDF" | "decryptHKDF";
+    input: string;
+    passphrase: string;
+    pbkdf2Salt: Uint8Array<ArrayBuffer>;
+};
+export type SplitArguments = {
+    key: number;
+    type: "split";
+    dataSrc: Blob;
+    pieceSize: number;
+    plainSplit: boolean;
+    minimumChunkSize: number;
+    filename?: string;
+    useSegmenter: boolean;
+    splitVersion: 1 | 2 | 3;
+};
+export type SplitProcessItem = {
+    key: number;
+    type: SplitArguments["type"];
+    finalize: () => void;
+};
+export type EncryptProcessItem = {
+    key: number;
+    task: PromiseWithResolvers<string>;
+    type: EncryptArguments["type"];
+    finalize: () => void;
+};
+export type EncryptHKDFProcessItem = {
+    key: number;
+    task: PromiseWithResolvers<string>;
+    type: EncryptHKDFArguments["type"];
+    finalize: () => void;
+};
+export type ProcessItem = SplitProcessItem | EncryptProcessItem | EncryptHKDFProcessItem;
+export declare const END_OF_DATA: null;
+export type END_OF_DATA = typeof END_OF_DATA;
+export type ResultPayloadBase = {
+    key: number;
+};
+export type ResultPayloadWithResult = ResultPayloadBase & {
+    result: string;
+};
+export type ResultPayloadWithError = ResultPayloadBase & {
+    error: unknown;
+};
+export type ResultPayload = ResultPayloadWithResult | ResultPayloadWithError;
+export type ResultPayloadWithSeqBase = ResultPayload & {
+    seq: number;
+};
+export type ResultPayloadPiece = ResultPayloadWithSeqBase & {
+    result: string | END_OF_DATA;
+};
+export type ResultPayloadWithSeq = ResultPayloadPiece | ResultPayloadWithError;

package/dist/worker/universalTypes.js

@@ -0,0 +1,4 @@
+const END_OF_DATA = null;
+export {
+  END_OF_DATA
+};

package/docs/development.md

@@ -0,0 +1,51 @@
+# Commonlib development
+
+This document is for Commonlib developers. Package consumers should begin with the root README and the focused platform guide.
+
+## Local validation
+
+```bash
+npm ci
+npm run check:types
+npm test
+npm run test:contracts
+npm run test:boundary
+npm run test:package
+```
+
+`test:package` builds the compiled package, packs it, installs the tarball into a clean consumer fixture, exercises Node imports, type-checks public entry points, and creates representative browser bundles. It also verifies that browser and context entry points do not pull in Node-only code, Svelte, or the complete language catalogue unintentionally.
+
+`test:contracts` runs the host-neutral result contracts which are intended to be reusable while implementations move:
+
+- `test:contract:context` verifies event delivery, default instance isolation, translation results, and host extension of `ServiceContextContract`; and
+- `test:contract:platform-storage` runs one result table against Node storage and browser File System Access storage, including missing paths, text and binary round trips, append, listing, removal, root handling, and traversal rejection.
+
+These scripts are deliberately available independently of CI. Add a focused result contract before moving another platform API; do not infer compatibility from matching TypeScript shapes alone. Platform-specific behaviour, such as timestamp fidelity, must remain documented outside the shared result set.
+
+Self-hosted LiveSync remains the principal downstream consumer. A Commonlib change is not ready for publication until the exact packed artefact has also passed the applicable LiveSync type checks, unit and integration tests, application builds, CLI E2E, and focused real-Obsidian E2E.
+
+## Translation catalogue
+
+Human-edited translations live under `src/common/messagesYAML`. Regenerate derived JSON and TypeScript resources with:
+
+```bash
+npm run i18n:bake
+```
+
+The generated catalogue remains an optional dependency surface. Core and context imports must not load it.
+
+## Public API documentation
+
+New reviewed public entry points require TSDoc describing ownership, lifecycle, platform constraints, errors, and disposal. Hand-written guides explain cross-entry composition and operational constraints.
+
+Generated API reference is deferred until the compatibility export surface has been narrowed. Generating documentation for every current `compat/*` path would make migration-only implementation paths look like stable public API.
+
+TODO: introduce generated API reference for a reviewed allow-list of public entry points once the high-level client façade and its lifecycle contract have been accepted.
+
+## Compatibility exports
+
+The package build records each compatibility path explicitly. Do not add a wildcard export. A new compatibility path requires a real downstream import, a packed-consumer or downstream test, and a migration plan towards a focused public entry or the owning package.
+
+TODO: classify and document compatibility paths whose purpose is still unclear before stabilising the first public release. Remove obsolete paths rather than documenting accidental layout as API.
+
+Release preparation and staged-publication checks are documented in [the maintainer runbook](releasing.md).

package/docs/platform-storage.md

@@ -0,0 +1,60 @@
+# Platform storage
+
+Commonlib supplies paired rooted-storage implementations for Node and the browser File System Access API. Both implement the same LiveSync storage contract, but the platform entry points remain deliberately separate.
+
+## Ownership boundary
+
+The host owns root acquisition and lifecycle:
+
+- a Node or CLI host decides which directory becomes `rootPath`;
+- a browser host presents any directory picker, obtains permission, and supplies an authorised `FileSystemDirectoryHandle` as `rootHandle`;
+- the host decides whether and how a browser handle is persisted and re-authorised; and
+- the host disposes any surrounding application resources.
+
+The storage factories only bind operations to the supplied root. They do not inspect the current process, call `showDirectoryPicker()`, request permission, or store credentials or handles.
+
+## Browser File System Access API
+
+```ts
+import { createFileSystemAccessStorage } from '@vrtmrz/livesync-commonlib/browser';
+
+const rootHandle = await window.showDirectoryPicker();
+const storage = createFileSystemAccessStorage({ rootHandle });
+
+await storage.mkdir('notes');
+await storage.write('notes/example.md', '# Example');
+const content = await storage.read('notes/example.md');
+```
+
+Calling `showDirectoryPicker()` is only an example of host composition. Availability, secure-context requirements, user activation, permission prompts, handle persistence, and re-authorisation are browser concerns and are outside the adapter contract.
+
+## Node
+
+```ts
+import { createNodeStorage } from '@vrtmrz/livesync-commonlib/node';
+
+const storage = createNodeStorage({ rootPath: '/srv/livesync' });
+await storage.write('notes/example.md', '# Example');
+```
+
+`rootPath` may be absolute or process-relative. The host should normally resolve and validate configuration before constructing the adapter.
+
+## Shared path contract
+
+Adapter paths are relative to the injected root and use forward slashes. The empty path refers to the root for root-safe operations such as `exists`, `stat`, `list`, and `mkdir`.
+
+The adapters reject:
+
+- absolute paths;
+- Windows drive-qualified paths;
+- backslash-separated paths;
+- `.` and `..` traversal segments; and
+- the empty path for entry operations such as `read`, `write`, `append`, and `remove`.
+
+Writes create missing parent directories. Listing returns direct child paths relative to the configured root. Text, binary, append, metadata, listing, removal, and containment behaviour are exercised by the same contract suite against both implementations.
+
+The File System Access API does not expose portable creation times or permit setting file times. Consumers must not rely on identical timestamp fidelity across the two adapters.
+
+## Bundling boundary
+
+Browser consumers import only `@vrtmrz/livesync-commonlib/browser`. Packed-package tests build that entry with browser conditions and verify that the Node implementation is absent. Node consumers import `@vrtmrz/livesync-commonlib/node`; the root and context entries do not load Node built-ins.

package/docs/releasing.md

@@ -0,0 +1,69 @@
+# Releasing Commonlib
+
+This document is the developer and maintainer runbook for preparing and publishing `@vrtmrz/livesync-commonlib`. Package-consumer guidance belongs in the root README.
+
+## Release gate
+
+Run the complete owner gate from a clean checkout:
+
+```bash
+npm ci
+npm run verify:package
+```
+
+The gate type-checks Commonlib, runs its complete unit suite, verifies the source boundary, builds the distributable package, installs its exact tarball into a clean consumer, and bundles representative browser and Node entry points. The source `package.json` remains private to prevent publishing the repository root. Only the generated `.package` directory is publishable, and its manifest defaults to public publication on the `next` dist-tag.
+
+Before publication, run the downstream workflow against an exact Self-hosted LiveSync ref which already consumes the package. The workflow installs the tarball produced from the selected Commonlib commit, then runs LiveSync type checks, unit tests, plug-in and application builds, and CLI E2E. Real Obsidian E2E remains local-only and is required when the changed boundary affects actual plug-in composition, storage, UI, or platform behaviour.
+
+## Preparing a release
+
+Choose the version explicitly. Use a prerelease such as `0.1.0-rc.0` when registry installation must be validated before the first stable version. Package-proof versions are local artefacts and cannot be staged.
+
+From a release branch based on `main`:
+
+```bash
+npm ci
+npm version <version> --no-git-tag-version
+npm run verify:package
+npm publish --dry-run .package --tag next --access public
+```
+
+Review `package.json`, `package-lock.json`, the generated manifest, the tarball contents, the test results, and the downstream evidence. Commit only the source manifest and lockfile for the version change; `.package`, `.package-consumer`, and `artifacts` are generated and ignored. Push and open a release pull request only after the usual user checkpoint.
+
+## Initial npm bootstrap
+
+The npm package must exist before Trusted Publishing can be configured. Bootstrap the first reviewed release candidate once from the exact reviewed commit in the draft release pull request, using an interactive npm session with 2FA:
+
+```bash
+npm ci
+npm run verify:package
+npm publish .package --tag next --access public
+```
+
+Confirm the authenticated npm account, `@vrtmrz` scope ownership, package name, version, tarball checksum, packed contents, source commit, and target tag immediately before publication. Treat bootstrap publication as a separate user-authorised operation. npm may assign `latest` to the first published version even when `next` is requested; leave the immutable version in place and replace `latest` only after a stable release has passed consumer validation.
+
+Keep the release pull request in draft while the published artefact is validated in Self-hosted LiveSync. If validation succeeds, merge the exact reviewed commit. If validation fails, leave the published version immutable and prepare a new pre-release version.
+
+## Trusted staged publishing
+
+After bootstrap, configure the npm Trusted Publisher for:
+
+- GitHub owner and repository: `vrtmrz/livesync-commonlib`;
+- workflow file: `publish-npm.yml`;
+- environment: `npm`; and
+- allowed action: staged publishing only.
+
+Protect the GitHub `npm` environment with a required reviewer and permit only the `main` branch. The workflow accepts only the exact commit currently on `main`, runs `verify:package`, validates the requested version and confirmation text, packs that reviewed output, records its checksum, and passes the same tarball to the protected staging job.
+
+Dispatch it with the exact stable or prerelease version and full commit SHA:
+
+```bash
+sha=$(git rev-parse origin/main)
+gh workflow run publish-npm.yml \
+  --ref main \
+  -f version=<version> \
+  -f expected_sha="$sha" \
+  -f confirmation="stage @vrtmrz/livesync-commonlib@<version> from $sha"
+```
+
+The workflow always stages to `next`. Inspect the staged package name, version, access, dist-tag, provenance, checksum, files, and source commit before approving it through npm. Approval and later promotion to `latest` are separate user-authorised operations. Validate the exact registry version in Self-hosted LiveSync before promoting a stable release.