@tiagojct/subsub 0.5.0 → 0.6.0

package/docs/Subsub.md

@@ -52,6 +52,17 @@ Templates (type the name, then the argument):
 - Librarian: `/tag-batch [size]`, `/clean-tags`, `/import-queue [note path]`
 - Researcher: `/lit-note <citekey>`, `/synthesis <topic>`, `/gaps <topic>`, `/manuscript <path>`, `/alert`
 
+## Web view
+
+1. Type `subsub web`. Sub-Sub opens in the browser, with the same modes, profiles, tools and approvals. The approval dialog shows the server preview; the change runs only after Yes.
+2. To add a shortcut (Applications on macOS), type `subsub shortcut`. To remove it, type `subsub shortcut --remove`.
+3. The server listens only on 127.0.0.1 and needs the random key in the address that `subsub web` opens. A second `subsub web` opens the running one.
+4. The server stops 10 minutes after the last page closes. `subsub web --stay` keeps it running.
+5. The labels are in European Portuguese when the language setting is Portuguese.
+6. The model button lists the models and saves an API key for a provider (the same auth.json as `/login`).
+
+The log is in ~/.subsub/web.log.
+
 ## Profiles
 
 The profile sets how much Sub-Sub does. To see the profile, type `/profile`. To change it, type `/profile reader` (or scholar, author, editor). The change is saved.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiagojct/subsub",
-  "version": "0.5.0",
-  "description": "Sub-Sub: a Zotero librarian and research assistant in the terminal, built on pi",
+  "version": "0.6.0",
+  "description": "Sub-Sub: a Zotero librarian and research assistant in the browser or the terminal, built on pi",
   "type": "module",
   "license": "MIT",
   "author": "Tiago Jacinto",
@@ -44,6 +44,7 @@
   },
   "files": [
     "README.md",
+    "assets",
     "bin",
     "dist",
     "docs",
@@ -53,7 +54,8 @@
     "scripts",
     "src",
     "templates",
-    "themes"
+    "themes",
+    "web"
   ],
   "devDependencies": {
     "@types/node": "^24.19.0",

package/src/cli.ts

@@ -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.
  */
 
 import { spawnSync } from "node:child_process";
@@ -148,6 +150,16 @@ export async function run(argv: string[] = process.argv.slice(2)): Promise<void>
 		process.exitCode = await initMain(args.slice(1), env);
 		return;
 	}
+	if (args[0] === "web" || args[0] === "serve") {
+		const { webMain } = await import("./web.ts");
+		process.exitCode = await webMain([...args.slice(1), ...(here ? ["--here"] : [])], env);
+		return;
+	}
+	if (args[0] === "shortcut") {
+		const { shortcutMain } = await import("./shortcut.ts");
+		process.exitCode = shortcutMain(args.slice(1), env);
+		return;
+	}
 	if (args[0] === "doctor") {
 		const { doctorMain } = await import("./doctor.ts");
 		process.exitCode = await doctorMain(env);

package/src/init.ts

@@ -184,8 +184,8 @@ export async function runInit(
 			? "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.");
+	if (fmup) 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 };
 }
 

package/src/shortcut.ts

@@ -0,0 +1,184 @@
+/**
+ * `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.ts";
+
+export interface ShortcutPlan {
+	platform: NodeJS.Platform;
+	node: string;
+	bin: string;
+	home: string;
+	packageDir: string;
+	desktop: boolean;
+}
+
+export function planFor(env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform, desktop = true): ShortcutPlan {
+	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: string): string {
+	return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Quote an argument for the Exec line of a .desktop file. */
+export function desktopQuote(s: string): string {
+	return `"${s.replace(/(["`$\\])/g, "\\$1")}"`;
+}
+
+/** Single-quote a string for PowerShell. */
+export function psQuote(s: string): string {
+	return `'${s.replace(/'/g, "''")}'`;
+}
+
+export function macScript(p: ShortcutPlan): string {
+	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: string): string {
+	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: ShortcutPlan): string {
+	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: ShortcutPlan): string {
+	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: string): { ok: boolean; out: string } {
+	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: ShortcutPlan): string[] {
+	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: ShortcutPlan): string[] {
+	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: string[], env: NodeJS.ProcessEnv = process.env): number {
+	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 as Error).message}`);
+		return 1;
+	}
+}

package/src/subsub.ts

@@ -108,6 +108,30 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	const library: LibraryState = { zotero: "checking" };
 	const quote = cfg.quotes === false ? undefined : QUOTES[Math.floor(Math.random() * QUOTES.length)];
 	const lookOn = (ctx: ExtensionContext) => 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: ExtensionContext | undefined;
+	function emitWeb(): void {
+		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: ExtensionContext): void {
 		if (!lookOn(ctx) || cfg.themes === false) return;
@@ -145,6 +169,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			library.zotero = "down";
 		}
 		headerTui?.requestRender();
+		emitWeb();
 	}
 
 	function setHeader(ctx: ExtensionContext): void {
@@ -183,6 +208,8 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		ctx.ui.setStatus("subsub", `Sub-Sub: ${mode} | ${profileSpec(profile).label} | ${modelId}${down.length ? ` | not running: ${down.join(", ")}` : ""}`);
 		if (standalone) ctx.ui.setTitle(`Sub-Sub: ${mode}`);
 		headerTui?.requestRender();
+		webCtx = ctx;
+		emitWeb();
 	}
 
 	async function applyMode(ctx: ExtensionContext, next: Mode, remember: boolean): Promise<void> {
@@ -218,6 +245,8 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		if (lookOn(ctx)) {
 			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");
@@ -382,10 +411,19 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 				}
 			}
 			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) => {