@qearlyao/familiar 0.1.0 → 0.1.2

package/dist/runtime.js

@@ -223,7 +223,7 @@ export class ConversationRuntime {
             return undefined;
         const [rawCommand = "", ...argParts] = normalized.split(" ");
         const command = rawCommand.replace(/^\//, "").toLowerCase();
-        if (!["stop", "status", "new", "reload", "compact", "model", "thinking", "channel-trigger"].includes(command)) {
+        if (!["stop", "status", "new", "reload", "restart", "compact", "model", "thinking", "channel-trigger"].includes(command)) {
             return undefined;
         }
         return {

package/dist/scheduler.js

@@ -193,7 +193,9 @@ export function isHeartbeatDue(options) {
     if (idleDurationMs < options.idleThresholdMs)
         return false;
     const lastHeartbeatAt = options.lastHeartbeatAt ? Date.parse(options.lastHeartbeatAt) : undefined;
-    if (lastHeartbeatAt == null || !Number.isFinite(lastHeartbeatAt) || lastHeartbeatAt <= options.lastUserInteractionAt) {
+    if (lastHeartbeatAt == null ||
+        !Number.isFinite(lastHeartbeatAt) ||
+        lastHeartbeatAt <= options.lastUserInteractionAt) {
         return true;
     }
     return options.now - lastHeartbeatAt >= Math.max(0, options.intervalMs);

package/dist/service.js

@@ -0,0 +1,284 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, platform, userInfo } from "node:os";
+import { dirname, resolve } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const SERVICE_LABEL = "com.qearlyao.familiar";
+const SYSTEMD_SERVICE = "familiar.service";
+function servicePaths(workspacePath, input) {
+    const logDir = resolve(workspacePath, "logs");
+    return {
+        servicePath: input.platform === "darwin"
+            ? resolve(input.homeDir, "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`)
+            : resolve(input.homeDir, ".config", "systemd", "user", SYSTEMD_SERVICE),
+        logDir,
+        stdoutPath: resolve(logDir, "familiar.out.log"),
+        stderrPath: resolve(logDir, "familiar.err.log"),
+    };
+}
+function buildSpec(workspacePath, options = {}) {
+    const currentPlatform = options.platform ?? platform();
+    const cliPath = options.cliPath ?? currentCliPath();
+    const resolvedWorkspacePath = resolve(workspacePath);
+    return {
+        platform: currentPlatform,
+        workspacePath: resolvedWorkspacePath,
+        nodePath: options.nodePath ?? process.execPath,
+        cliPath,
+        paths: servicePaths(resolvedWorkspacePath, {
+            platform: currentPlatform,
+            homeDir: options.homeDir ?? homedir(),
+        }),
+    };
+}
+function currentCliPath() {
+    if (!process.argv[1])
+        throw new Error("Cannot determine familiar CLI path for service installation.");
+    return resolve(process.argv[1]);
+}
+function versionManagedPathWarning(spec) {
+    const joined = `${spec.nodePath}\n${spec.cliPath}`;
+    const marker = ["/.nvm/", "/.asdf/", "/.fnm/", "/.volta/"].find((candidate) => joined.includes(candidate));
+    if (!marker)
+        return undefined;
+    return `warning: service uses a version-manager path (${marker}); reinstall the service after changing Node versions.`;
+}
+function xmlEscape(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+function systemdQuote(value) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value))
+        return value;
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("$", "\\$").replaceAll("`", "\\`")}"`;
+}
+function launchdPlist(spec) {
+    const args = [spec.nodePath, spec.cliPath, "run", spec.workspacePath]
+        .map((value) => `\t\t<string>${xmlEscape(value)}</string>`)
+        .join("\n");
+    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>
+\t<key>Label</key>
+\t<string>${SERVICE_LABEL}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+${args}
+\t</array>
+\t<key>WorkingDirectory</key>
+\t<string>${xmlEscape(spec.workspacePath)}</string>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>KeepAlive</key>
+\t<true/>
+\t<key>ThrottleInterval</key>
+\t<integer>30</integer>
+\t<key>ExitTimeOut</key>
+\t<integer>20</integer>
+\t<key>StandardOutPath</key>
+\t<string>${xmlEscape(spec.paths.stdoutPath)}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${xmlEscape(spec.paths.stderrPath)}</string>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+\t\t<key>NODE_ENV</key>
+\t\t<string>production</string>
+\t</dict>
+</dict>
+</plist>
+`;
+}
+function systemdUnit(spec) {
+    const execStart = [spec.nodePath, spec.cliPath, "run", spec.workspacePath].map(systemdQuote).join(" ");
+    return `[Unit]
+Description=Familiar companion agent
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
+
+[Service]
+Type=simple
+WorkingDirectory=${systemdQuote(spec.workspacePath)}
+ExecStart=${execStart}
+Restart=on-failure
+RestartSec=5
+SuccessExitStatus=75
+RestartForceExitStatus=75
+Environment=NODE_ENV=production
+StandardOutput=append:${spec.paths.stdoutPath}
+StandardError=append:${spec.paths.stderrPath}
+
+[Install]
+WantedBy=default.target
+`;
+}
+async function commandExists(command) {
+    try {
+        await execFileAsync(command, ["--version"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function hasCommand(command, options) {
+    return options.commandExists ? options.commandExists(command) : commandExists(command);
+}
+async function run(command, args, options) {
+    if (options.runCommand) {
+        await options.runCommand(command, args);
+        return;
+    }
+    await execFileAsync(command, args);
+}
+async function capture(command, args, options) {
+    if (options.captureCommand)
+        return options.captureCommand(command, args);
+    const { stdout } = await execFileAsync(command, args);
+    return stdout;
+}
+async function runOptional(command, args, options) {
+    try {
+        await run(command, args, options);
+    }
+    catch {
+        // Best-effort cleanup for stale service registrations.
+    }
+}
+function guiDomain() {
+    return `gui/${userInfo().uid}`;
+}
+function unsupported(platformName) {
+    return {
+        title: "Service management is not supported on this platform yet.",
+        details: [
+            `platform: ${platformName}`,
+            "Windows users should keep Familiar running in a foreground terminal for now.",
+        ],
+    };
+}
+export async function installService(workspacePath, options = {}) {
+    const spec = buildSpec(workspacePath, options);
+    if (spec.platform !== "darwin" && spec.platform !== "linux")
+        return unsupported(spec.platform);
+    await mkdir(dirname(spec.paths.servicePath), { recursive: true });
+    await mkdir(spec.paths.logDir, { recursive: true });
+    const serviceText = spec.platform === "darwin" ? launchdPlist(spec) : systemdUnit(spec);
+    await writeFile(spec.paths.servicePath, serviceText, "utf8");
+    if (spec.platform === "darwin") {
+        await runOptional("launchctl", ["bootout", guiDomain(), spec.paths.servicePath], options);
+        await run("launchctl", ["bootstrap", guiDomain(), spec.paths.servicePath], options);
+        await run("launchctl", ["kickstart", "-k", `${guiDomain()}/${SERVICE_LABEL}`], options);
+    }
+    else {
+        if (!(await hasCommand("systemctl", options))) {
+            throw new Error("systemctl is required to install the Linux user service.");
+        }
+        await run("systemctl", ["--user", "daemon-reload"], options);
+        await run("systemctl", ["--user", "enable", "--now", SYSTEMD_SERVICE], options);
+    }
+    const details = [
+        `workspace: ${spec.workspacePath}`,
+        `service: ${spec.paths.servicePath}`,
+        `stdout: ${spec.paths.stdoutPath}`,
+        `stderr: ${spec.paths.stderrPath}`,
+    ];
+    const pathWarning = versionManagedPathWarning(spec);
+    if (pathWarning)
+        details.push(pathWarning);
+    return {
+        title: "Familiar service installed.",
+        details,
+    };
+}
+export async function uninstallService(workspacePath, options = {}) {
+    const spec = buildSpec(workspacePath, options);
+    if (spec.platform !== "darwin" && spec.platform !== "linux")
+        return unsupported(spec.platform);
+    if (spec.platform === "darwin") {
+        await runOptional("launchctl", ["bootout", guiDomain(), spec.paths.servicePath], options);
+    }
+    else {
+        if (await hasCommand("systemctl", options)) {
+            await runOptional("systemctl", ["--user", "disable", "--now", SYSTEMD_SERVICE], options);
+        }
+    }
+    if (existsSync(spec.paths.servicePath))
+        await rm(spec.paths.servicePath);
+    if (spec.platform === "linux" && (await hasCommand("systemctl", options))) {
+        await runOptional("systemctl", ["--user", "daemon-reload"], options);
+    }
+    return {
+        title: "Familiar service uninstalled.",
+        details: [`service: ${spec.paths.servicePath}`],
+    };
+}
+export async function serviceStatus(workspacePath, options = {}) {
+    const spec = buildSpec(workspacePath, options);
+    if (spec.platform !== "darwin" && spec.platform !== "linux")
+        return unsupported(spec.platform);
+    const details = [
+        `workspace: ${spec.workspacePath}`,
+        `service: ${spec.paths.servicePath}`,
+        `service_file: ${existsSync(spec.paths.servicePath) ? "present" : "missing"}`,
+        `supervisor_state: ${await supervisorState(spec, options)}`,
+        `stdout: ${spec.paths.stdoutPath}`,
+        `stderr: ${spec.paths.stderrPath}`,
+    ];
+    if (existsSync(spec.paths.servicePath)) {
+        const serviceFile = await stat(spec.paths.servicePath);
+        details.push(`service_file_mtime: ${serviceFile.mtime.toISOString()}`);
+    }
+    return { title: "Familiar service status.", details };
+}
+async function supervisorState(spec, options) {
+    try {
+        if (spec.platform === "darwin") {
+            await capture("launchctl", ["print", `${guiDomain()}/${SERVICE_LABEL}`], options);
+            return "loaded";
+        }
+        const state = (await capture("systemctl", ["--user", "is-active", SYSTEMD_SERVICE], options)).trim();
+        return state || "unknown";
+    }
+    catch {
+        return "not-loaded";
+    }
+}
+export async function upgradeFamiliar(options = {}) {
+    const currentPlatform = options.platform ?? platform();
+    const npmCommand = currentPlatform === "win32" ? "npm.cmd" : "npm";
+    await new Promise((resolveUpgrade, rejectUpgrade) => {
+        const child = spawn(npmCommand, ["install", "-g", "@qearlyao/familiar@latest"], {
+            shell: currentPlatform === "win32",
+            stdio: "inherit",
+        });
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolveUpgrade();
+            else
+                rejectUpgrade(new Error(`npm upgrade failed with exit code ${code ?? "unknown"}`));
+        });
+        child.on("error", rejectUpgrade);
+    });
+}
+export function formatServiceResult(result) {
+    return [result.title, ...result.details].join("\n");
+}
+export const __serviceTest = {
+    SERVICE_LABEL,
+    SYSTEMD_SERVICE,
+    buildSpec,
+    launchdPlist,
+    systemdUnit,
+    systemdQuote,
+    xmlEscape,
+    versionManagedPathWarning,
+};

package/dist/web-auth.js

@@ -16,7 +16,10 @@ function parseCookies(header) {
     return cookies;
 }
 function decodeTotpSecret(secret) {
-    const normalized = secret.replace(/\s+/g, "").replace(/=+$/g, "").toUpperCase();
+    const normalized = secret
+        .replace(/\s/g, "")
+        .replace(/={1,8}$/, "")
+        .toUpperCase();
     if (!/^[A-Z2-7]+$/.test(normalized))
         return Buffer.from(secret, "utf8");
     const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
@@ -58,7 +61,7 @@ function readBearerToken(request) {
     const header = request.headers.authorization;
     if (!header)
         return undefined;
-    const match = header.match(/^Bearer\s+(.+)$/i);
+    const match = header.match(/^Bearer (.+)$/i);
     return match?.[1];
 }
 export function createAuth(config) {

package/dist/web.js

@@ -322,7 +322,7 @@ function sessionDto(session) {
         isDefault: session.isDefault,
     };
 }
-export async function startWebDaemon(config, familiarAgent, discordDaemon) {
+export async function startWebDaemon(config, familiarAgent, discordDaemon, options = {}) {
     const persona = await loadPersona(config);
     const personaName = parsePersonaName(persona.soul);
     const auth = createAuth(config);
@@ -565,6 +565,11 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon) {
         if (control.command === "reload") {
             return familiarAgent.reload();
         }
+        if (control.command === "restart") {
+            return options.restart
+                ? await options.restart()
+                : "Restart requested, but no restart handler is configured. Please restart the Familiar process manually.";
+        }
         if (control.command === "model") {
             return control.args
                 ? await familiarAgent.setModel(runtime.channelKey, control.args)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@qearlyao/familiar",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"license": "MIT",
 	"type": "module",
 	"repository": {
@@ -19,6 +19,9 @@
 		"USER.md",
 		"MEMORY.md",
 		"HEARTBEAT.md",
+		"skills/**",
+		"scripts/install.sh",
+		"scripts/install.ps1",
 		"README.md",
 		"LICENSE"
 	],
@@ -29,6 +32,7 @@
 		"clean": "node -e \"const fs=require('node:fs'); for (const p of ['dist','web/dist']) fs.rmSync(p,{recursive:true,force:true});\"",
 		"dev": "tsx watch src/cli.ts run",
 		"build": "npm run clean && tsc -p tsconfig.build.json && npm --prefix web run build",
+		"prepack": "npm run build",
 		"lint": "biome check",
 		"format": "biome format --write",
 		"payload:pretty": "tsx scripts/pretty-payload.ts",
@@ -39,7 +43,7 @@
 		"@earendil-works/pi-agent-core": "^0.74.1",
 		"@earendil-works/pi-ai": "^0.74.1",
 		"@earendil-works/pi-coding-agent": "^0.74.1",
-		"better-sqlite3": "^12.9.0",
+		"better-sqlite3": "^12.10.0",
 		"discord.js": "^14.26.3",
 		"dotenv": "^16.4.5",
 		"sharp": "^0.34.5",
@@ -48,10 +52,10 @@
 		"typebox": "^1.1.38"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.3.5",
+		"@biomejs/biome": "2.4.15",
 		"@types/better-sqlite3": "^7.6.13",
-		"@types/node": "^24.3.0",
-		"tsx": "^4.20.3",
+		"@types/node": "^25.8.0",
+		"tsx": "^4.22.1",
 		"typescript": "^5.9.2"
 	},
 	"engines": {

package/scripts/install.ps1

@@ -0,0 +1,185 @@
+param(
+	[string]$Workspace = (Join-Path $HOME ".familiar"),
+	[string]$Package = "@qearlyao/familiar@latest",
+	[string]$BrowserHarnessDir = (Join-Path (Join-Path $HOME "Developer") "browser-harness"),
+	[switch]$WithBrowser,
+	[switch]$InstallBrowserDeps,
+	[switch]$SkipInit
+)
+
+$ErrorActionPreference = "Stop"
+
+function Require-Command($Name) {
+	if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
+		throw "Missing required command: $Name"
+	}
+}
+
+function Update-BrowserDepPath {
+	$candidates = @((Join-Path $HOME ".local\bin"), (Join-Path $HOME ".cargo\bin"))
+	foreach ($candidate in $candidates) {
+		if ((Test-Path $candidate) -and (($env:PATH -split [IO.Path]::PathSeparator) -notcontains $candidate)) {
+			$env:PATH = "$candidate$([IO.Path]::PathSeparator)$env:PATH"
+		}
+	}
+}
+
+function Confirm-BrowserDepInstall($Message) {
+	if ($InstallBrowserDeps) {
+		return $true
+	}
+	try {
+		$answer = Read-Host "$Message Install it now? [y/N]"
+		return $answer -match '^(y|yes)$'
+	} catch {
+		return $false
+	}
+}
+
+function Install-Uv {
+	Write-Host "Installing uv for browser-harness..."
+	irm https://astral.sh/uv/install.ps1 | iex
+	Update-BrowserDepPath
+	if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
+		throw "uv installer finished, but uv is not on PATH. Open a new terminal or add $HOME\.local\bin to PATH."
+	}
+}
+
+function Ensure-Uv {
+	if (Get-Command uv -ErrorAction SilentlyContinue) {
+		return
+	}
+	if (Confirm-BrowserDepInstall "uv is required for browser-harness but was not found.") {
+		Install-Uv
+		return
+	}
+	throw "Missing required command: uv. Rerun with -WithBrowser -InstallBrowserDeps to install uv and Python 3.11 automatically."
+}
+
+function Test-Python311($Command, $PythonArgs = @()) {
+	& $Command @PythonArgs -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)" *> $null
+	return $LASTEXITCODE -eq 0
+}
+
+function Resolve-Python311 {
+	$python = Get-Command python -ErrorAction SilentlyContinue
+	if ($python -and (Test-Python311 $python.Source)) {
+		return @{ Command = $python.Source; Args = @(); UvPython = $python.Source }
+	}
+	$python3 = Get-Command python3 -ErrorAction SilentlyContinue
+	if ($python3 -and (Test-Python311 $python3.Source)) {
+		return @{ Command = $python3.Source; Args = @(); UvPython = $python3.Source }
+	}
+	$py = Get-Command py -ErrorAction SilentlyContinue
+	if ($py -and (Test-Python311 $py.Source @("-3.11"))) {
+		return @{ Command = $py.Source; Args = @("-3.11"); UvPython = "3.11" }
+	}
+	return $null
+}
+
+function Ensure-Python311 {
+	$python311 = Resolve-Python311
+	if ($python311) {
+		return $python311
+	}
+	if (Confirm-BrowserDepInstall "Python 3.11+ is required for browser-harness but was not found.") {
+		Write-Host "Installing Python 3.11 with uv for browser-harness..."
+		& uv python install 3.11
+		if ($LASTEXITCODE -ne 0) {
+			throw "Python 3.11 install failed."
+		}
+		return @{ Command = "uv"; Args = @("python", "find", "3.11"); UvPython = "3.11" }
+	}
+	throw "browser-harness requires Python 3.11 or newer. Rerun with -WithBrowser -InstallBrowserDeps to install uv-managed Python 3.11 automatically."
+}
+
+Require-Command node
+Require-Command npm
+if ($WithBrowser) {
+	Require-Command git
+	Ensure-Uv
+	$Python311 = Ensure-Python311
+}
+
+$nodeVersion = (& node -p "process.versions.node").Trim()
+$nodeMajor = [int](& node -p "Number(process.versions.node.split('.')[0])")
+if ($nodeMajor -lt 22) {
+	throw "Familiar requires Node.js 22 or newer. Found Node.js $nodeVersion. Node.js 24 LTS is recommended."
+}
+if ($nodeMajor -lt 24) {
+	Write-Host "Found Node.js $nodeVersion. Familiar supports Node.js 22+, but Node.js 24 LTS is recommended."
+}
+
+Write-Host "Installing $Package globally..."
+& npm install -g $Package
+if ($LASTEXITCODE -ne 0) {
+	throw "npm install failed."
+}
+
+if ($WithBrowser) {
+	Write-Host "Installing optional OpenCLI browser helper..."
+	& npm install -g "@jackwener/opencli"
+	if ($LASTEXITCODE -ne 0) {
+		throw "browser helper install failed."
+	}
+
+	Write-Host "Installing optional browser-harness helper into $BrowserHarnessDir..."
+	$gitDir = Join-Path $BrowserHarnessDir ".git"
+	if (Test-Path $gitDir) {
+		& git -C $BrowserHarnessDir pull --ff-only
+		if ($LASTEXITCODE -ne 0) {
+			throw "browser-harness update failed."
+		}
+	} elseif (Test-Path $BrowserHarnessDir) {
+		throw "Cannot install browser-harness: $BrowserHarnessDir already exists and is not a git checkout."
+	} else {
+		$parentDir = Split-Path -Parent $BrowserHarnessDir
+		New-Item -ItemType Directory -Force -Path $parentDir | Out-Null
+		& git clone https://github.com/browser-use/browser-harness $BrowserHarnessDir
+		if ($LASTEXITCODE -ne 0) {
+			throw "browser-harness clone failed."
+		}
+	}
+	Push-Location $BrowserHarnessDir
+	$previousUvPython = $env:UV_PYTHON
+	try {
+		$env:UV_PYTHON = $Python311.UvPython
+		& uv tool install -e .
+		if ($LASTEXITCODE -ne 0) {
+			throw "browser-harness install failed."
+		}
+	} finally {
+		if ($null -eq $previousUvPython) {
+			Remove-Item Env:\UV_PYTHON -ErrorAction SilentlyContinue
+		} else {
+			$env:UV_PYTHON = $previousUvPython
+		}
+		Pop-Location
+	}
+}
+
+if (-not (Get-Command familiar -ErrorAction SilentlyContinue)) {
+	throw "Installed package, but familiar is not on PATH. Check your npm global bin directory and rerun: familiar init `"$Workspace`""
+}
+
+if (-not $SkipInit) {
+	Write-Host "Initializing or refreshing workspace defaults at $Workspace..."
+	& familiar init $Workspace
+	if ($LASTEXITCODE -ne 0) {
+		throw "familiar init failed."
+	}
+}
+
+Write-Host ""
+Write-Host "Familiar is installed."
+Write-Host ""
+Write-Host "Next steps:"
+Write-Host "  1. Edit $Workspace\.env"
+Write-Host "  2. Edit $Workspace\config.toml"
+Write-Host "  3. Run: familiar run `"$Workspace`""
+Write-Host ""
+Write-Host "Optional browser helpers:"
+Write-Host "  & ([scriptblock]::Create((irm https://raw.githubusercontent.com/qearlyao/familiar/main/scripts/install.ps1))) -WithBrowser"
+Write-Host ""
+Write-Host "browser-harness checkout:"
+Write-Host "  $BrowserHarnessDir"