@moyarich/console-addon-session 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @moyarich/console-addon-session
 
-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.
+Save and restore Console sessions. Work with versioned snapshots of structured messages and terminal entries, including dropped-history counts.
+
+[Documentation and live examples](https://moyarich.github.io/console/)
+
+## Install
+
+```bash
+npm install @moyarich/console @moyarich/console-addon-session
+```
+
+Configure the `@moyarich` scope and authenticate with GitHub Packages as described in the [installation guide](../../../README.md#installation).
+
+Required peer dependencies: `@moyarich/console@^0.2.0`.
+
+## Quick start
+
+```tsx
+import { Console } from "@moyarich/console";
+import { createConsoleSessionAddon } from "@moyarich/console-addon-session";
+
+const addons = [createConsoleSessionAddon()];
+
+// Pass your application's structured messages to Console.
+<Console messages={messages} addons={addons} />;
+```
+
+The addon is optional and can be combined with other Console addons. The host application remains responsible for supplying and retaining messages.
+
+## Learn more
+
+Explore [runnable package examples](./examples) and the [Console documentation](https://moyarich.github.io/console/) for available settings and integration patterns.
+
+Review the [changelog](./CHANGELOG.md) for changes by version and [package metadata](./package.json) for dependency requirements.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const console = require("@moyarich/console");
+const CONSOLE_SESSION_TYPE = "MOYARICH_CONSOLE_SESSION";
+const CONSOLE_SESSION_VERSION = 1;
+function createConsoleSession(input) {
+  const droppedCount = input.droppedCount ?? 0;
+  if (!Number.isSafeInteger(droppedCount) || droppedCount < 0)
+    throw new RangeError("Invalid droppedCount");
+  return input.mode === "console" ? {
+    type: CONSOLE_SESSION_TYPE,
+    version: CONSOLE_SESSION_VERSION,
+    mode: "console",
+    droppedCount,
+    messages: input.messages.map(console.serializeConsoleMessage)
+  } : {
+    type: CONSOLE_SESSION_TYPE,
+    version: CONSOLE_SESSION_VERSION,
+    mode: "terminal",
+    droppedCount,
+    entries: input.entries.map(
+      (entry) => typeof entry === "string" ? entry : {
+        data: entry.data,
+        ...entry.id !== void 0 ? { id: entry.id } : {},
+        ...entry.stream !== void 0 ? { stream: entry.stream } : {},
+        ...entry.metadata !== void 0 ? {
+          metadata: console.serializeConsoleValue(entry.metadata)
+        } : {}
+      }
+    )
+  };
+}
+function stringifyConsoleSession(session) {
+  return JSON.stringify(session);
+}
+function parseConsoleSession(serialized) {
+  const input = typeof serialized === "string" ? JSON.parse(serialized) : serialized;
+  if (!input || typeof input !== "object")
+    throw new TypeError("Invalid console session");
+  const record = input;
+  if (record.type !== CONSOLE_SESSION_TYPE)
+    throw new TypeError("Invalid console session type");
+  if (record.version !== CONSOLE_SESSION_VERSION)
+    throw new RangeError("Unsupported console session version");
+  if (!Number.isSafeInteger(record.droppedCount) || record.droppedCount < 0)
+    throw new TypeError("Invalid dropped history");
+  if (record.mode === "console") {
+    if (!Array.isArray(record.messages))
+      throw new TypeError("Missing console messages");
+    for (const message of record.messages) {
+      if (!message || typeof message !== "object" || typeof message.method !== "string" || !Array.isArray(message.data) || !Number.isSafeInteger(message.depth) || message.depth < 0)
+        throw new TypeError("Invalid console message");
+    }
+    return {
+      type: CONSOLE_SESSION_TYPE,
+      version: 1,
+      mode: "console",
+      droppedCount: record.droppedCount,
+      messages: record.messages.map(console.deserializeConsoleMessage)
+    };
+  }
+  if (record.mode === "terminal") {
+    if (!Array.isArray(record.entries) || !record.entries.every(
+      (entry) => typeof entry === "string" || entry && typeof entry === "object" && typeof entry.data === "string" && (entry.id === void 0 || typeof entry.id === "string") && (entry.stream === void 0 || entry.stream === "stdout" || entry.stream === "stderr") && (entry.metadata === void 0 || entry.metadata !== null && typeof entry.metadata === "object" && !Array.isArray(entry.metadata))
+    ))
+      throw new TypeError("Invalid terminal entries");
+    return {
+      type: CONSOLE_SESSION_TYPE,
+      version: 1,
+      mode: "terminal",
+      droppedCount: record.droppedCount,
+      entries: record.entries.map(
+        (entry) => typeof entry === "string" ? entry : {
+          ...entry,
+          ...entry.metadata !== void 0 ? {
+            metadata: console.deserializeConsoleValue(entry.metadata)
+          } : {}
+        }
+      )
+    };
+  }
+  throw new TypeError("Unsupported console session mode");
+}
+const CONSOLE_SESSION_ADDON_ID = "@moyarich/console-addon-session";
+const consoleSessionService = console.createConsoleServiceToken(
+  CONSOLE_SESSION_ADDON_ID + ".service"
+);
+function createConsoleSessionAddon() {
+  let data;
+  const service = {
+    capture(droppedCount = 0) {
+      const snapshot = data?.getSnapshot();
+      if (!snapshot) throw new Error("Console session addon is not active");
+      return snapshot.mode === "console" ? createConsoleSession({
+        mode: "console",
+        messages: snapshot.all,
+        droppedCount
+      }) : createConsoleSession({
+        mode: "terminal",
+        entries: snapshot.rawEntries,
+        droppedCount
+      });
+    },
+    save(droppedCount = 0) {
+      return stringifyConsoleSession(service.capture(droppedCount));
+    },
+    restore(serialized) {
+      return parseConsoleSession(serialized);
+    }
+  };
+  return {
+    id: CONSOLE_SESSION_ADDON_ID,
+    service,
+    activate(host) {
+      data = host.services.get(console.consoleServices.data);
+      host.services.provide(consoleSessionService, service);
+      return () => {
+        data = void 0;
+      };
+    }
+  };
+}
+exports.CONSOLE_SESSION_ADDON_ID = CONSOLE_SESSION_ADDON_ID;
+exports.CONSOLE_SESSION_TYPE = CONSOLE_SESSION_TYPE;
+exports.CONSOLE_SESSION_VERSION = CONSOLE_SESSION_VERSION;
+exports.consoleSessionService = consoleSessionService;
+exports.createConsoleSession = createConsoleSession;
+exports.createConsoleSessionAddon = createConsoleSessionAddon;
+exports.parseConsoleSession = parseConsoleSession;
+exports.stringifyConsoleSession = stringifyConsoleSession;

package/dist/index.d.cts

@@ -0,0 +1,40 @@
+import { type ConsoleAddon } from "@moyarich/console";
+import { type ConsoleMessageData, type ConsoleStdoutEntry } from "@moyarich/console";
+export declare const CONSOLE_SESSION_TYPE: "MOYARICH_CONSOLE_SESSION";
+export declare const CONSOLE_SESSION_VERSION: 1;
+export type ConsoleSession = {
+    readonly type: typeof CONSOLE_SESSION_TYPE;
+    readonly version: 1;
+    readonly mode: "console";
+    readonly messages: readonly ConsoleMessageData[];
+    readonly droppedCount: number;
+} | {
+    readonly type: typeof CONSOLE_SESSION_TYPE;
+    readonly version: 1;
+    readonly mode: "terminal";
+    readonly entries: readonly (ConsoleStdoutEntry | string)[];
+    readonly droppedCount: number;
+};
+export declare function createConsoleSession(input: {
+    mode: "console";
+    messages: readonly ConsoleMessageData[];
+    droppedCount?: number;
+} | {
+    mode: "terminal";
+    entries: readonly (ConsoleStdoutEntry | string)[];
+    droppedCount?: number;
+}): ConsoleSession;
+export declare function stringifyConsoleSession(session: ConsoleSession): string;
+export declare function parseConsoleSession(serialized: string | unknown): ConsoleSession;
+/** Read-only session snapshot facade exposed while the addon is active. */
+export interface ConsoleSessionService {
+    capture(droppedCount?: number): ConsoleSession;
+    save(droppedCount?: number): string;
+    restore(serialized: string): ConsoleSession;
+}
+export declare const CONSOLE_SESSION_ADDON_ID = "@moyarich/console-addon-session";
+export declare const consoleSessionService: import("@moyarich/console-core").ConsoleServiceToken<ConsoleSessionService>;
+/** The host owns applying a restored session to source messages; the addon never mutates capture state. */
+export declare function createConsoleSessionAddon(): ConsoleAddon & {
+    service: ConsoleSessionService;
+};

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { type ConsoleAddon } from "@moyarich/console";
+import { type ConsoleMessageData, type ConsoleStdoutEntry } from "@moyarich/console";
+export declare const CONSOLE_SESSION_TYPE: "MOYARICH_CONSOLE_SESSION";
+export declare const CONSOLE_SESSION_VERSION: 1;
+export type ConsoleSession = {
+    readonly type: typeof CONSOLE_SESSION_TYPE;
+    readonly version: 1;
+    readonly mode: "console";
+    readonly messages: readonly ConsoleMessageData[];
+    readonly droppedCount: number;
+} | {
+    readonly type: typeof CONSOLE_SESSION_TYPE;
+    readonly version: 1;
+    readonly mode: "terminal";
+    readonly entries: readonly (ConsoleStdoutEntry | string)[];
+    readonly droppedCount: number;
+};
+export declare function createConsoleSession(input: {
+    mode: "console";
+    messages: readonly ConsoleMessageData[];
+    droppedCount?: number;
+} | {
+    mode: "terminal";
+    entries: readonly (ConsoleStdoutEntry | string)[];
+    droppedCount?: number;
+}): ConsoleSession;
+export declare function stringifyConsoleSession(session: ConsoleSession): string;
+export declare function parseConsoleSession(serialized: string | unknown): ConsoleSession;
+/** Read-only session snapshot facade exposed while the addon is active. */
+export interface ConsoleSessionService {
+    capture(droppedCount?: number): ConsoleSession;
+    save(droppedCount?: number): string;
+    restore(serialized: string): ConsoleSession;
+}
+export declare const CONSOLE_SESSION_ADDON_ID = "@moyarich/console-addon-session";
+export declare const consoleSessionService: import("@moyarich/console-core").ConsoleServiceToken<ConsoleSessionService>;
+/** The host owns applying a restored session to source messages; the addon never mutates capture state. */
+export declare function createConsoleSessionAddon(): ConsoleAddon & {
+    service: ConsoleSessionService;
+};

package/dist/index.js

@@ -0,0 +1,130 @@
+import { createConsoleServiceToken, serializeConsoleMessage, serializeConsoleValue, deserializeConsoleMessage, deserializeConsoleValue, consoleServices } from "@moyarich/console";
+const CONSOLE_SESSION_TYPE = "MOYARICH_CONSOLE_SESSION";
+const CONSOLE_SESSION_VERSION = 1;
+function createConsoleSession(input) {
+  const droppedCount = input.droppedCount ?? 0;
+  if (!Number.isSafeInteger(droppedCount) || droppedCount < 0)
+    throw new RangeError("Invalid droppedCount");
+  return input.mode === "console" ? {
+    type: CONSOLE_SESSION_TYPE,
+    version: CONSOLE_SESSION_VERSION,
+    mode: "console",
+    droppedCount,
+    messages: input.messages.map(serializeConsoleMessage)
+  } : {
+    type: CONSOLE_SESSION_TYPE,
+    version: CONSOLE_SESSION_VERSION,
+    mode: "terminal",
+    droppedCount,
+    entries: input.entries.map(
+      (entry) => typeof entry === "string" ? entry : {
+        data: entry.data,
+        ...entry.id !== void 0 ? { id: entry.id } : {},
+        ...entry.stream !== void 0 ? { stream: entry.stream } : {},
+        ...entry.metadata !== void 0 ? {
+          metadata: serializeConsoleValue(entry.metadata)
+        } : {}
+      }
+    )
+  };
+}
+function stringifyConsoleSession(session) {
+  return JSON.stringify(session);
+}
+function parseConsoleSession(serialized) {
+  const input = typeof serialized === "string" ? JSON.parse(serialized) : serialized;
+  if (!input || typeof input !== "object")
+    throw new TypeError("Invalid console session");
+  const record = input;
+  if (record.type !== CONSOLE_SESSION_TYPE)
+    throw new TypeError("Invalid console session type");
+  if (record.version !== CONSOLE_SESSION_VERSION)
+    throw new RangeError("Unsupported console session version");
+  if (!Number.isSafeInteger(record.droppedCount) || record.droppedCount < 0)
+    throw new TypeError("Invalid dropped history");
+  if (record.mode === "console") {
+    if (!Array.isArray(record.messages))
+      throw new TypeError("Missing console messages");
+    for (const message of record.messages) {
+      if (!message || typeof message !== "object" || typeof message.method !== "string" || !Array.isArray(message.data) || !Number.isSafeInteger(message.depth) || message.depth < 0)
+        throw new TypeError("Invalid console message");
+    }
+    return {
+      type: CONSOLE_SESSION_TYPE,
+      version: 1,
+      mode: "console",
+      droppedCount: record.droppedCount,
+      messages: record.messages.map(deserializeConsoleMessage)
+    };
+  }
+  if (record.mode === "terminal") {
+    if (!Array.isArray(record.entries) || !record.entries.every(
+      (entry) => typeof entry === "string" || entry && typeof entry === "object" && typeof entry.data === "string" && (entry.id === void 0 || typeof entry.id === "string") && (entry.stream === void 0 || entry.stream === "stdout" || entry.stream === "stderr") && (entry.metadata === void 0 || entry.metadata !== null && typeof entry.metadata === "object" && !Array.isArray(entry.metadata))
+    ))
+      throw new TypeError("Invalid terminal entries");
+    return {
+      type: CONSOLE_SESSION_TYPE,
+      version: 1,
+      mode: "terminal",
+      droppedCount: record.droppedCount,
+      entries: record.entries.map(
+        (entry) => typeof entry === "string" ? entry : {
+          ...entry,
+          ...entry.metadata !== void 0 ? {
+            metadata: deserializeConsoleValue(entry.metadata)
+          } : {}
+        }
+      )
+    };
+  }
+  throw new TypeError("Unsupported console session mode");
+}
+const CONSOLE_SESSION_ADDON_ID = "@moyarich/console-addon-session";
+const consoleSessionService = createConsoleServiceToken(
+  CONSOLE_SESSION_ADDON_ID + ".service"
+);
+function createConsoleSessionAddon() {
+  let data;
+  const service = {
+    capture(droppedCount = 0) {
+      const snapshot = data?.getSnapshot();
+      if (!snapshot) throw new Error("Console session addon is not active");
+      return snapshot.mode === "console" ? createConsoleSession({
+        mode: "console",
+        messages: snapshot.all,
+        droppedCount
+      }) : createConsoleSession({
+        mode: "terminal",
+        entries: snapshot.rawEntries,
+        droppedCount
+      });
+    },
+    save(droppedCount = 0) {
+      return stringifyConsoleSession(service.capture(droppedCount));
+    },
+    restore(serialized) {
+      return parseConsoleSession(serialized);
+    }
+  };
+  return {
+    id: CONSOLE_SESSION_ADDON_ID,
+    service,
+    activate(host) {
+      data = host.services.get(consoleServices.data);
+      host.services.provide(consoleSessionService, service);
+      return () => {
+        data = void 0;
+      };
+    }
+  };
+}
+export {
+  CONSOLE_SESSION_ADDON_ID,
+  CONSOLE_SESSION_TYPE,
+  CONSOLE_SESSION_VERSION,
+  consoleSessionService,
+  createConsoleSession,
+  createConsoleSessionAddon,
+  parseConsoleSession,
+  stringifyConsoleSession
+};

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@moyarich/console-addon-session",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Versioned Console session snapshot and restore helpers",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json && node ../../../scripts/prepare-cjs-types.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@moyarich/console": "^0.2.0"
+  },
+  "devDependencies": {
+    "@moyarich/console": "0.2.0",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moyarich/console.git",
+    "directory": "packages/addons/session"
+  },
+  "bugs": {
+    "url": "https://github.com/moyarich/console/issues"
+  },
+  "homepage": "https://github.com/moyarich/console#readme",
+  "keywords": [
+    "console",
+    "addon",
+    "session",
+    "persistence"
+  ],
+  "publisher": "moyarich",
+  "author": "Moya Richards",
+  "engines": {
+    "node": ">=24"
+  },
+  "private": false
+}