@dsh-stack/tweak-share-links 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# tweak-share-links
 
-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.
+Self-hosted read-only session share links: the share route, share settings section, and the dsh share verb.
+
+An extension of the `tweaks` settings surface, split out of the bundled `tweaks` package.

package/bin/share.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * `dsh share <sessionId>` — publish a read-only share link for one session.
+ * Interactive (token-gated) sharing is opt-in: pass `--interactive` and the
+ * `tweaks.share.allowInteractive` setting must be true. Prints the URL.
+ *
+ * Usage: dsh share <sessionId> [--interactive] [--advertised-host <host>]
+ */
+
+import { resolveHome } from "@dsh-stack/tweaks/home";
+import { generateToken, writeShareToken } from "../lib/share.js";
+
+const args = process.argv.slice(2);
+const sessionId = args.find((arg) => !arg.startsWith("--"));
+if (sessionId === undefined) {
+  console.error("usage: dsh share <sessionId> [--interactive] [--advertised-host <host>]");
+  process.exit(1);
+}
+const interactive = args.includes("--interactive");
+const hostIndex = args.indexOf("--advertised-host");
+const advertisedHost = hostIndex >= 0 ? args[hostIndex + 1] : undefined;
+
+const home = await resolveHome();
+const token = interactive ? await generateToken() : undefined;
+if (token !== undefined) await writeShareToken(home, token);
+const host = advertisedHost ?? "127.0.0.1:3080";
+const base = "/share";
+const url = `http://${host}${base}/${sessionId}${token === undefined ? "" : `?token=${token}`}`;
+console.log(url);

package/lib/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `tweak-share-links`: self-hosted read-only share links — the
+ * `<basePath>/<id>` snapshot route on the harness web server plus the
+ * `tweaks-share` settings section. Split out of the bundled `tweaks`
+ * package; plugs into the tweaks settings surface.
+ * @module tweak-share-links
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type z from "@deepseek-ai/schemastery";
+import { type ShareConfig as ShareConfigType } from "./settings.js";
+export { NS_SHARE, ShareConfig } from "./settings.js";
+export type { ShareConfig as ShareConfigType } from "./settings.js";
+export { generateToken, mountShareRoute, writeShareToken } from "./share.js";
+export declare const name = "tweak-share-links";
+export declare const inject: string[];
+/** The share-links extension config: the share section itself. */
+export type Config = ShareConfigType;
+export declare const Config: z<Config>;
+/**
+ * apply implementation.
+ *
+ * The share-links form is the `ShareConfig` this plugin already declares, and its
+ * namespace is this plugin's entry id, so there is nothing to install; what this
+ * plugin must declare is that it ships its own page for that form. The read-only
+ * share route is mounted from the same config, unchanged.
+ *
+ * @param ctx - the calling plugin's context.
+ * @param config - the active profile's projected share-links fields.
+ */
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,37 @@
+/**
+ * `tweak-share-links`: self-hosted read-only share links — the
+ * `<basePath>/<id>` snapshot route on the harness web server plus the
+ * `tweaks-share` settings section. Split out of the bundled `tweaks`
+ * package; plugs into the tweaks settings surface.
+ * @module tweak-share-links
+ */
+import { declareCustomSettingsPage } from "@dsh-stack/plugin-kit";
+import { resolveHome } from "@dsh-stack/tweaks";
+import { mountShareRoute } from "./share.js";
+import { ShareConfig } from "./settings.js";
+export { NS_SHARE, ShareConfig } from "./settings.js";
+export { generateToken, mountShareRoute, writeShareToken } from "./share.js";
+export const name = "tweak-share-links";
+export const inject = [];
+export const Config = ShareConfig;
+/**
+ * apply implementation.
+ *
+ * The share-links form is the `ShareConfig` this plugin already declares, and its
+ * namespace is this plugin's entry id, so there is nothing to install; what this
+ * plugin must declare is that it ships its own page for that form. The read-only
+ * share route is mounted from the same config, unchanged.
+ *
+ * @param ctx - the calling plugin's context.
+ * @param config - the active profile's projected share-links fields.
+ */
+export function apply(ctx, config) {
+    const share = {
+        enabled: config?.enabled ?? true,
+        allowInteractive: config?.allowInteractive ?? false,
+        advertisedHost: config?.advertisedHost ?? "",
+        basePath: config?.basePath ?? "/share",
+    };
+    declareCustomSettingsPage(ctx);
+    mountShareRoute(ctx, resolveHome(), share);
+}

package/lib/settings.d.ts

@@ -0,0 +1,20 @@
+/**
+ * tweak-share-links settings: the share-links section schema shared between
+ * the composition entry, the settings document, and the `dsh share` verb.
+ * @module tweak-share-links/settings
+ */
+import z from "@deepseek-ai/schemastery";
+/** Namespace of the share-links section — this plugin's own Loader entry id. */
+export declare const NS_SHARE: import("@dsh-stack/plugin-kit").SettingsNamespace;
+/** One self-hosted share-link configuration. */
+export interface ShareConfig {
+    /** Whether the read-only share route is mounted at all. */
+    enabled: boolean;
+    /** Whether interactive (token-gated) sharing is allowed for this deployment. */
+    allowInteractive: boolean;
+    /** Hosts the share link advertises (Tailscale name etc.); empty = loopback. */
+    advertisedHost?: string;
+    /** Base path the share route mounts under (default `/share`). */
+    basePath: string;
+}
+export declare const ShareConfig: z<ShareConfig>;

package/lib/settings.js

@@ -0,0 +1,15 @@
+/**
+ * tweak-share-links settings: the share-links section schema shared between
+ * the composition entry, the settings document, and the `dsh share` verb.
+ * @module tweak-share-links/settings
+ */
+import z from "@deepseek-ai/schemastery";
+import { settingsNamespace } from "@dsh-stack/plugin-kit";
+/** Namespace of the share-links section — this plugin's own Loader entry id. */
+export const NS_SHARE = settingsNamespace("tweak-share-links");
+export const ShareConfig = z.object({
+    enabled: z.boolean().default(true),
+    allowInteractive: z.boolean().default(false),
+    advertisedHost: z.string().default(""),
+    basePath: z.string().default("/share"),
+});

package/lib/share.d.ts

@@ -0,0 +1,46 @@
+/**
+ * tweaks share links: a self-hosted read-only snapshot route. The plugin
+ * registers `<basePath>/<id>` as a prefix route on the harness web server;
+ * the handler reads the session's durable JSONL log and renders a static,
+ * dependency-free HTML transcript. Interactive mode (opt-in) additionally
+ * requires `?token=<random>` in the URL, checked against the value the
+ * `dsh share` verb wrote to the section. Read-only is the default: without a
+ * token the page is a pure snapshot with no interactive controls.
+ * @module tweak-share-links/share
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Context } from "@deepseek-ai/cordis";
+import type { ShareConfig } from "./settings.js";
+/** One rendered transcript line from a session event. */
+export interface TranscriptLine {
+    role: "user" | "assistant" | "tool" | "system";
+    text: string;
+    time?: string;
+}
+/** Search every workspace segment under `sessions/` for the session's log. */
+export declare function resolveSessionLogPath(home: string, sessionId: string, cwd?: string): Promise<string | undefined>;
+/** Parse a durable JSONL log into transcript lines (stops at the first bad line). */
+export declare function parseLog(text: string): TranscriptLine[];
+/** Render a full share page from transcript lines. */
+export declare function renderSharePage(sessionId: string, lines: TranscriptLine[], interactive: boolean): string;
+/** Constant-time token comparison. */
+export declare function tokensEqual(a: string, b: string): boolean;
+/** Generate a fresh interactive token. */
+export declare function generateToken(): string;
+/** Store a share token beside the home settings (the `dsh share` verb writes this). */
+export declare function writeShareToken(home: string, token: string): Promise<string>;
+/** Read the stored share token, or `undefined` when sharing is read-only. */
+export declare function readShareToken(home: string): Promise<string | undefined>;
+/** List session id directories under a workspace segment. */
+export declare function listSessionIds(home: string, cwd?: string): Promise<string[]>;
+/**
+ * Build the route handler for one share base path. Read-only by default;
+ * interactive only when `allowInteractive` and the request carries the
+ * matching token.
+ */
+export declare function makeShareHandler(home: string, basePath: string, allowInteractive?: boolean): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/**
+ * Mount the share prefix route on the web server (called from `apply`).
+ * Returns the inject fiber.
+ */
+export declare function mountShareRoute(ctx: Context, home: string, config: ShareConfig): unknown;

package/lib/share.js

@@ -0,0 +1,273 @@
+/**
+ * tweaks share links: a self-hosted read-only snapshot route. The plugin
+ * registers `<basePath>/<id>` as a prefix route on the harness web server;
+ * the handler reads the session's durable JSONL log and renders a static,
+ * dependency-free HTML transcript. Interactive mode (opt-in) additionally
+ * requires `?token=<random>` in the URL, checked against the value the
+ * `dsh share` verb wrote to the section. Read-only is the default: without a
+ * token the page is a pure snapshot with no interactive controls.
+ * @module tweak-share-links/share
+ */
+import { join, dirname, basename } from "node:path";
+import { readFile, readdir, mkdir, writeFile } from "node:fs/promises";
+import { zstdDecompressSync } from "node:zlib";
+import { createHash, randomBytes } from "node:crypto";
+/** Length of the interactive token, in bytes. */
+const TOKEN_BYTES = 24;
+/** The session-log folder name under the home. */
+const SESSIONS_DIR = "sessions";
+/** Map a workspace-cwd segment to the session folder prefix the harness uses. */
+function workspaceSegment(cwd) {
+    const cleaned = cwd.replace(/^\/+|\/+$/g, "").replace(/\//g, "-");
+    return `--${cleaned}--`;
+}
+/** Candidate log paths under one workspace directory. */
+function logCandidates(sessionDir) {
+    return [
+        join(sessionDir, "session.jsonl.zstd"),
+        join(sessionDir, "session.jsonl.ln"),
+        join(sessionDir, "session.jsonl"),
+    ];
+}
+/** Search every workspace segment under `sessions/` for the session's log. */
+export async function resolveSessionLogPath(home, sessionId, cwd = "") {
+    const root = join(home, SESSIONS_DIR);
+    // Accept the id with or without the `session-` prefix.
+    const bare = sessionId.startsWith("session-") ? sessionId.slice("session-".length) : sessionId;
+    // Preferred first: the workspace segment derived from cwd.
+    const preferred = cwd.length > 0 ? cwd : process.cwd();
+    const dirs = [join(root, workspaceSegment(preferred))];
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !entry.name.startsWith("--"))
+                continue;
+            const dir = join(root, entry.name);
+            if (!dirs.includes(dir))
+                dirs.push(dir);
+        }
+    }
+    catch {
+        // sessions/ missing entirely: nothing to find
+    }
+    for (const dir of dirs) {
+        const sessionDir = join(dir, `session-${bare}`);
+        for (const candidate of logCandidates(sessionDir)) {
+            try {
+                const stat = await import("node:fs/promises").then((fs) => fs.stat(candidate));
+                if (stat.isFile())
+                    return candidate;
+            }
+            catch {
+                // try the next candidate
+            }
+        }
+    }
+    return undefined;
+}
+/** Extract role/text from one parsed JSONL event line. */
+function eventToLine(event) {
+    const type = event["type"];
+    const data = event["data"];
+    if (type === "user/message") {
+        const message = data?.["message"];
+        const content = message?.["content"];
+        return { role: "user", text: renderContent(content) };
+    }
+    if (type === "assistant/message") {
+        const message = data?.["message"];
+        const content = message?.["content"];
+        return { role: "assistant", text: renderContent(content) };
+    }
+    if (type === "tool/call") {
+        const name = data?.["name"];
+        return { role: "tool", text: `tool: ${String(name ?? "unknown")}` };
+    }
+    if (type === "tool/result") {
+        const ok = data?.["ok"];
+        return { role: "tool", text: `tool result: ${String(ok ?? "?")}` };
+    }
+    return undefined;
+}
+/** Render message content (string, array of parts, or absent) to plain text. */
+function renderContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => {
+            const p = part;
+            if (typeof p["text"] === "string")
+                return p["text"];
+            if (p["type"] === "image")
+                return "[image]";
+            return "";
+        })
+            .filter(Boolean)
+            .join("\n");
+    }
+    return "";
+}
+/** Parse a durable JSONL log into transcript lines (stops at the first bad line). */
+export function parseLog(text) {
+    const lines = [];
+    for (const raw of text.split("\n")) {
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            break;
+        }
+        const line = eventToLine(event);
+        if (line !== undefined)
+            lines.push(line);
+    }
+    return lines;
+}
+/** Escape a string for safe HTML text emission. */
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** Render a full share page from transcript lines. */
+export function renderSharePage(sessionId, lines, interactive) {
+    const rows = lines
+        .map((line) => {
+        const cls = line.role;
+        const text = escapeHtml(line.text);
+        const time = line.time === undefined ? "" : `<time>${escapeHtml(line.time)}</time>`;
+        return `<div class="row ${cls}"><div class="role">${cls}</div><div class="text">${text}</div>${time}</div>`;
+    })
+        .join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>session ${escapeHtml(sessionId)}</title>
+<style>
+body { font: 14px/1.6 system-ui, sans-serif; margin: 0; padding: 2rem; background: #101418; color: #d6dee8; }
+h1 { font-size: 1rem; color: #8b97a6; }
+.row { display: grid; grid-template-columns: 6rem 1fr auto; gap: .75rem; padding: .5rem 0; border-bottom: 1px solid #222a33; }
+.role { color: #8b97a6; text-transform: uppercase; font-size: .75rem; padding-top: .2rem; }
+.text { white-space: pre-wrap; overflow-wrap: anywhere; }
+time { color: #5b6673; font-size: .75rem; }
+${interactive ? "body { padding-bottom: 5rem; } #live { position: fixed; bottom: 1rem; left: 2rem; right: 2rem; display: flex; gap: .5rem; } #live input { flex: 1; padding: .5rem; } #live button { padding: .5rem 1rem; }" : ""}
+</style>
+</head>
+<body>
+<h1>session ${escapeHtml(sessionId)}</h1>
+${rows}
+</body>
+</html>
+`;
+}
+/** Constant-time token comparison. */
+export function tokensEqual(a, b) {
+    const ha = createHash("sha256").update(a).digest();
+    const hb = createHash("sha256").update(b).digest();
+    return ha.equals(hb);
+}
+/** Generate a fresh interactive token. */
+export function generateToken() {
+    return randomBytes(TOKEN_BYTES).toString("base64url");
+}
+/** Store a share token beside the home settings (the `dsh share` verb writes this). */
+export async function writeShareToken(home, token) {
+    const path = join(home, "share.token");
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${token}\n`, { mode: 0o600 });
+    return path;
+}
+/** Read the stored share token, or `undefined` when sharing is read-only. */
+export async function readShareToken(home) {
+    try {
+        const text = await readFile(join(home, "share.token"), "utf8");
+        return text.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** List session id directories under a workspace segment. */
+export async function listSessionIds(home, cwd = "") {
+    const workspace = cwd.length > 0 ? cwd : process.cwd();
+    const dir = join(home, SESSIONS_DIR, workspaceSegment(workspace));
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith("session-"))
+            .map((entry) => basename(entry.name).slice("session-".length));
+    }
+    catch {
+        return [];
+    }
+}
+/** Read a session log, transparently decompressing a `.zstd` frame. */
+async function readSessionLog(logPath) {
+    const raw = await readFile(logPath);
+    if (logPath.endsWith(".zstd")) {
+        return zstdDecompressSync(raw).toString("utf8");
+    }
+    return raw.toString("utf8");
+}
+/**
+ * Build the route handler for one share base path. Read-only by default;
+ * interactive only when `allowInteractive` and the request carries the
+ * matching token.
+ */
+export function makeShareHandler(home, basePath, allowInteractive = false) {
+    return async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://x");
+        const pathname = url.pathname;
+        const id = pathname.startsWith(`${basePath}/`) ? pathname.slice(basePath.length + 1) : "";
+        if (id.length === 0 || id.includes("/")) {
+            res.writeHead(404);
+            res.end("not found");
+            return;
+        }
+        const logPath = await resolveSessionLogPath(home, id);
+        if (logPath === undefined) {
+            res.writeHead(404);
+            res.end("not found");
+            return;
+        }
+        const interactive = allowInteractive && (await authorizeShare(home, url.searchParams.get("token")));
+        const text = await readSessionLog(logPath);
+        const lines = parseLog(text);
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end(renderSharePage(id, lines, interactive));
+    };
+}
+/** Whether an interactive request is authorized (token matches the stored one). */
+async function authorizeShare(home, token) {
+    if (token === null || token.length === 0)
+        return false;
+    const stored = await readShareToken(home);
+    if (stored === undefined)
+        return false;
+    return tokensEqual(stored, token);
+}
+/**
+ * Mount the share prefix route on the web server (called from `apply`).
+ * Returns the inject fiber.
+ */
+export function mountShareRoute(ctx, home, config) {
+    if (!config.enabled)
+        return undefined;
+    const basePath = config.basePath === "" ? "/share" : config.basePath;
+    return ctx.inject(["webServer"], (httpCtx) => {
+        return httpCtx.webServer.register({
+            kind: "prefix",
+            path: basePath,
+            handler: makeShareHandler(home, basePath, config.allowInteractive),
+        });
+    });
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@dsh-stack/tweak-share-links",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Self-hosted read-only session share links: the share route, share settings section, and the dsh share verb.",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "bin",
+    "README.md",
+    "package.json",
+    "stack.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "stack": {
+    "kind": "plugin",
+    "id": "stack.tweaks.share-links"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node check-plugin.mjs"
+  },
+  "bin": {
+    "share": "bin/share.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "*",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2"
+  },
+  "dependencies": {
+    "@dsh-stack/tweaks": "0.2.1",
+    "@dsh-stack/plugin-kit": "0.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "*",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marius-patrik/dsh-stack.git",
+    "directory": "plugins/tweak-share-links"
+  }
+}

package/stack.json

@@ -0,0 +1,10 @@
+{
+  "id": "stack.tweaks.share-links",
+  "name": "@dsh-stack/tweak-share-links",
+  "version": "0.1.1",
+  "kind": "plugin",
+  "description": "Self-hosted read-only session share links: the share route, share settings section, and the dsh share verb.",
+  "files": ["lib", "bin", "README.md", "package.json", "stack.json"],
+  "dependencies": ["stack.tweaks", "stack.library.plugin-kit"],
+  "optionalDependencies": []
+}