@tiagojct/subsub 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # Sub-Sub
 
-A Zotero librarian and research assistant that runs in your terminal. It is built on the [pi](https://pi.dev) agent and works with your own Zotero library through Zotero's local API.
+A Zotero librarian and research assistant that runs on your computer, in your browser or in your terminal. It is built on the [pi](https://pi.dev) agent and works with your own Zotero library through Zotero's local API.
 
 > "This mere painstaking burrower and grub-worm of a poor devil of a Sub-Sub appears to have gone through the long Vaticans and street-stalls of the earth, picking up whatever random allusions to whales he could anyways find in any book whatsoever." (Moby-Dick, Extracts)
 
@@ -34,10 +34,13 @@ A profile is your own choice, not a lock.
 
 ## Install
 
+The installers on [subsub.tiagojacinto.eu](https://subsub.tiagojacinto.eu/install/) do all of this, including Node.js and uv. By hand:
+
 1. Type `npm install -g @tiagojct/subsub`. The command is `subsub`.
 2. Type `subsub init`. Answer the questions. Press Enter to keep a default.
 3. Type `subsub doctor`. Fix each line marked FIX.
-4. Type `subsub`. Then type `/login` and choose your model provider.
+4. Type `subsub shortcut` to add a Sub-Sub shortcut (Applications on macOS, the Start menu and the desktop on Windows, the applications menu on Linux).
+5. Open Sub-Sub with the shortcut, or type `subsub web`. Select the model button and connect a provider with an API key (or, in the terminal, type `subsub`, then `/login`).
 
 `subsub init` creates a notes folder with Inbox/ and Systems/, a starter tag list (health sciences, health informatics, or any field) and a file with the note formats (Systems/Zotero agent.md). You can edit both files. It never replaces a file that exists.
 
@@ -45,6 +48,17 @@ If you already use pi, you can also add Sub-Sub to plain pi: `pi install npm:@ti
 
 The Zotero servers (zotero-local-mcp) run from PyPI through uv. To run them from a copy of the repository, add `"serverDir": "/path/to/zotero-local-mcp"` to the settings file.
 
+## Web view
+
+`subsub web` (or `subsub serve`) opens Sub-Sub in your browser. It has the same modes, profiles, tools and approvals as the terminal:
+
+- pi runs in RPC mode with the Sub-Sub extension. Sub-Sub's approval dialog (the server preview) appears in the page, and the change runs only after you select Yes.
+- The server listens only on 127.0.0.1. The address that opens the page carries a random key, which becomes an HttpOnly, SameSite=Strict cookie; other requests need that cookie, the right Host header and a same-origin JSON request. The page has a strict content security policy and shows model output without raw HTML.
+- One server per user: a second `subsub web` opens the running one. Without an open page for 10 minutes (and with nothing waiting for approval), the server stops. `--stay` keeps it running; `--idle N` sets the minutes; `--no-open` does not open a browser; `--librarian` starts in the librarian mode.
+- Labels are in European Portuguese when the language setting is Portuguese, otherwise in English.
+- The model button lists the models you can use and saves an API key for a provider in the same file as `/login`. Sign-ins through a provider's website stay in the terminal (`/login`).
+- A log is kept in `~/.subsub/web.log`.
+
 ## Use
 
 - `subsub` starts in the researcher mode. `subsub --librarian` starts in the librarian mode. `/librarian` and `/researcher` change the mode.

package/dist/cli.js

@@ -12,6 +12,8 @@
  * - `subsub review preview|apply NOTE...` runs zotero-review (tag review notes,
  *   several at a time) with Sub-Sub's server folder and settings.
  * - `subsub init` sets Sub-Sub up; `subsub doctor` checks the setup.
+ * - `subsub web` (or `subsub serve`) opens Sub-Sub in the browser;
+ *   `subsub shortcut` adds a Sub-Sub shortcut that does the same.
  */
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
@@ -156,6 +158,16 @@ export async function run(argv = process.argv.slice(2)) {
         process.exitCode = await initMain(args.slice(1), env);
         return;
     }
+    if (args[0] === "web" || args[0] === "serve") {
+        const { webMain } = await import("./web.js");
+        process.exitCode = await webMain([...args.slice(1), ...(here ? ["--here"] : [])], env);
+        return;
+    }
+    if (args[0] === "shortcut") {
+        const { shortcutMain } = await import("./shortcut.js");
+        process.exitCode = shortcutMain(args.slice(1), env);
+        return;
+    }
     if (args[0] === "doctor") {
         const { doctorMain } = await import("./doctor.js");
         process.exitCode = await doctorMain(env);

package/dist/init.js

@@ -143,8 +143,8 @@ export async function runInit(io, flags, env = process.env, deps = {}) {
         ? "Zotero: reachable."
         : "Zotero: not reachable. Start Zotero 10, then in Zotero open Settings > Advanced and turn on \"Allow other applications on this computer to communicate with Zotero\".");
     if (fmup)
-        io.say("FMUP / U.Porto: the FMUP model service will come in a later version. Until then, choose a model provider with /login.");
-    io.say("Next: type subsub. In Sub-Sub, type /login to connect a model provider. To check the setup, type subsub doctor.");
+        io.say("FMUP / U.Porto: the FMUP model service will come in a later version. Until then, connect a model provider yourself.");
+    io.say("Next: type subsub web to open Sub-Sub in your browser (or subsub for the terminal). Connect a model provider with the model button (or /login in the terminal). To check the setup, type subsub doctor.");
     return { configFile, envFile, notes, created, zotero };
 }
 export function parseFlags(args) {

package/dist/shortcut.js

@@ -0,0 +1,165 @@
+/**
+ * `subsub shortcut`: a Sub-Sub shortcut that opens the web view, so students
+ * can start Sub-Sub without a terminal.
+ *
+ * - macOS: ~/Applications/Sub-Sub.app (a small app bundle that runs `subsub web`;
+ *   no Dock icon, it stops by itself when the page has been closed for a while).
+ * - Windows: Sub-Sub in the Start menu and on the desktop.
+ * - Linux: ~/.local/share/applications/sub-sub.desktop.
+ *
+ * The shortcut runs this copy of Sub-Sub with this Node.js (absolute paths), so
+ * it works without PATH. Run `subsub shortcut` again after moving either.
+ * `subsub shortcut --remove` removes what this command created.
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PACKAGE_DIR, packageVersion } from "./cli.js";
+export function planFor(env = process.env, platform = process.platform, desktop = true) {
+    const home = platform === "win32" ? (env.USERPROFILE ?? homedir()) : (env.HOME ?? homedir());
+    return { platform, node: process.execPath, bin: join(PACKAGE_DIR, "bin", "subsub.js"), home, packageDir: PACKAGE_DIR, desktop };
+}
+/** Single-quote a string for sh. */
+export function shQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/** Quote an argument for the Exec line of a .desktop file. */
+export function desktopQuote(s) {
+    return `"${s.replace(/(["`$\\])/g, "\\$1")}"`;
+}
+/** Single-quote a string for PowerShell. */
+export function psQuote(s) {
+    return `'${s.replace(/'/g, "''")}'`;
+}
+export function macScript(p) {
+    return [
+        "#!/bin/sh",
+        "# Opens Sub-Sub in the browser. Written by: subsub shortcut",
+        'cd "$HOME" || exit 1',
+        `exec ${shQuote(p.node)} ${shQuote(p.bin)} web >/dev/null 2>&1`,
+        "",
+    ].join("\n");
+}
+export function macPlist(version) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleName</key><string>Sub-Sub</string>
+	<key>CFBundleDisplayName</key><string>Sub-Sub</string>
+	<key>CFBundleIdentifier</key><string>eu.tiagojacinto.subsub</string>
+	<key>CFBundleExecutable</key><string>Sub-Sub</string>
+	<key>CFBundleIconFile</key><string>icon</string>
+	<key>CFBundlePackageType</key><string>APPL</string>
+	<key>CFBundleShortVersionString</key><string>${version}</string>
+	<key>CFBundleVersion</key><string>${version}</string>
+	<key>LSUIElement</key><true/>
+</dict>
+</plist>
+`;
+}
+export function desktopEntry(p) {
+    return [
+        "[Desktop Entry]",
+        "Type=Application",
+        "Name=Sub-Sub",
+        "Comment=Zotero librarian and research assistant",
+        `Exec=${desktopQuote(p.node)} ${desktopQuote(p.bin)} web`,
+        `Path=${p.home}`,
+        `Icon=${join(p.packageDir, "assets", "icon.png")}`,
+        "Terminal=false",
+        "Categories=Education;Office;",
+        "",
+    ].join("\n");
+}
+export function windowsScript(p) {
+    const lines = [
+        "$ErrorActionPreference = 'Stop'",
+        "$shell = New-Object -ComObject WScript.Shell",
+        "$places = @([Environment]::GetFolderPath('Programs'))",
+        ...(p.desktop ? ["$places += [Environment]::GetFolderPath('Desktop')"] : []),
+        "foreach ($dir in $places) {",
+        "  $s = $shell.CreateShortcut((Join-Path $dir 'Sub-Sub.lnk'))",
+        `  $s.TargetPath = ${psQuote(p.node)}`,
+        `  $s.Arguments = ${psQuote(`"${p.bin}" web`)}`,
+        `  $s.WorkingDirectory = ${psQuote(p.home)}`,
+        `  $s.IconLocation = ${psQuote(join(p.packageDir, "assets", "icon.ico"))}`,
+        "  $s.Description = 'Sub-Sub: Zotero librarian and research assistant'",
+        "  $s.WindowStyle = 7",
+        "  $s.Save()",
+        "  Write-Output (Join-Path $dir 'Sub-Sub.lnk')",
+        "}",
+    ];
+    return lines.join("\n");
+}
+function runPowerShell(script) {
+    const r = spawnSync("powershell", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { encoding: "utf8", windowsHide: true });
+    return { ok: r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}${r.error ? r.error.message : ""}`.trim() };
+}
+export function createShortcuts(p) {
+    if (p.platform === "darwin") {
+        const app = join(p.home, "Applications", "Sub-Sub.app");
+        mkdirSync(join(app, "Contents", "MacOS"), { recursive: true });
+        mkdirSync(join(app, "Contents", "Resources"), { recursive: true });
+        writeFileSync(join(app, "Contents", "Info.plist"), macPlist(packageVersion(p.packageDir)));
+        const exe = join(app, "Contents", "MacOS", "Sub-Sub");
+        writeFileSync(exe, macScript(p));
+        chmodSync(exe, 0o755);
+        const icns = join(p.packageDir, "assets", "icon.icns");
+        if (existsSync(icns))
+            copyFileSync(icns, join(app, "Contents", "Resources", "icon.icns"));
+        return [app];
+    }
+    if (p.platform === "win32") {
+        const r = runPowerShell(windowsScript(p));
+        if (!r.ok)
+            throw new Error(`could not create the shortcut: ${r.out}`);
+        return r.out.split(/\r?\n/).filter(Boolean);
+    }
+    const dir = join(p.home, ".local", "share", "applications");
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, "sub-sub.desktop");
+    writeFileSync(file, desktopEntry(p));
+    chmodSync(file, 0o755);
+    return [file];
+}
+export function removeShortcuts(p) {
+    if (p.platform === "win32") {
+        const script = [
+            "foreach ($dir in @([Environment]::GetFolderPath('Programs'), [Environment]::GetFolderPath('Desktop'))) {",
+            "  $f = Join-Path $dir 'Sub-Sub.lnk'",
+            "  if (Test-Path $f) { Remove-Item $f; Write-Output $f }",
+            "}",
+        ].join("\n");
+        const r = runPowerShell(script);
+        return r.out.split(/\r?\n/).filter(Boolean);
+    }
+    const target = p.platform === "darwin" ? join(p.home, "Applications", "Sub-Sub.app") : join(p.home, ".local", "share", "applications", "sub-sub.desktop");
+    if (!existsSync(target))
+        return [];
+    rmSync(target, { recursive: true, force: true });
+    return [target];
+}
+export function shortcutMain(args, env = process.env) {
+    const plan = planFor(env, process.platform, !args.includes("--no-desktop"));
+    try {
+        if (args.includes("--remove")) {
+            const gone = removeShortcuts(plan);
+            console.log(gone.length ? `Removed:\n${gone.join("\n")}` : "No Sub-Sub shortcut found.");
+            return 0;
+        }
+        const made = createShortcuts(plan);
+        const where = plan.platform === "darwin"
+            ? "Open Sub-Sub from Applications, Launchpad or Spotlight."
+            : plan.platform === "win32"
+                ? "Open Sub-Sub from the Start menu or the desktop."
+                : "Open Sub-Sub from your applications menu.";
+        console.log(`Shortcut:\n${made.join("\n")}\n${where} It opens Sub-Sub in your browser.`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`Sub-Sub: ${err.message}`);
+        return 1;
+    }
+}

package/dist/subsub.js

@@ -93,6 +93,32 @@ export async function createSubsub(pi, deps = {}) {
     const library = { zotero: "checking" };
     const quote = cfg.quotes === false ? undefined : QUOTES[Math.floor(Math.random() * QUOTES.length)];
     const lookOn = (ctx) => standalone && cfg.look !== false && ctx.mode === "tui";
+    /** True under `subsub web`: pi runs in RPC mode and the web view shows the state that the terminal header shows. */
+    const webView = process.env.SUBSUB_WEB === "1";
+    let webCtx;
+    function emitWeb() {
+        const ctx = webCtx;
+        if (!webView || !ctx || ctx.mode !== "rpc")
+            return;
+        const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
+        const state = {
+            mode,
+            profile,
+            profileLabel: profileSpec(profile).label,
+            model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : null,
+            down,
+            library,
+            language: cfg.language,
+            userName: cfg.userName ?? null,
+            vault: cfg.vault ?? null,
+        };
+        try {
+            ctx.ui.setStatus("subsub.web", JSON.stringify(state));
+        }
+        catch {
+            /* the context is gone after shutdown */
+        }
+    }
     function applyTheme(ctx) {
         if (!lookOn(ctx) || cfg.themes === false)
             return;
@@ -125,6 +151,7 @@ export async function createSubsub(pi, deps = {}) {
             library.zotero = "down";
         }
         headerTui?.requestRender();
+        emitWeb();
     }
     function setHeader(ctx) {
         if (!lookOn(ctx))
@@ -163,6 +190,8 @@ export async function createSubsub(pi, deps = {}) {
         if (standalone)
             ctx.ui.setTitle(`Sub-Sub: ${mode}`);
         headerTui?.requestRender();
+        webCtx = ctx;
+        emitWeb();
     }
     async function applyMode(ctx, next, remember) {
         mode = next;
@@ -201,6 +230,9 @@ export async function createSubsub(pi, deps = {}) {
             setHeader(ctx);
             void refreshLibrary();
         }
+        else if (webView) {
+            void refreshLibrary();
+        }
         for (const [name, err] of Object.entries(bridge.errors)) {
             ctx.ui.notify(`Sub-Sub: the ${name} server did not start: ${err.split("\n")[0]}`, "error");
         }
@@ -362,9 +394,17 @@ export async function createSubsub(pi, deps = {}) {
                 }
             }
             headerTui?.requestRender();
+            emitWeb();
             ctx.ui.notify(lines.join("\n"), "info");
         },
     });
+    pi.registerCommand("subsub-refresh", {
+        description: "Sub-Sub: refresh the library counts shown in the web view",
+        handler: async (_args, ctx) => {
+            webCtx = ctx;
+            await refreshLibrary();
+        },
+    });
     pi.registerCommand("history", {
         description: "Sub-Sub: recent library changes",
         handler: async (_args, ctx) => {