@qearlyao/familiar 0.4.2 → 0.4.5

package/README.md

@@ -199,7 +199,8 @@ familiar uninstall-service
 macOS uses `launchd`; Linux uses user `systemd`. Windows users should run
 `familiar run` in a foreground terminal for now. The short
 `start`/`stop`/`restart` commands control the installed user service. Service
-logs are written under `<workspace>/logs`.
+logs are written under `<workspace>/logs`; service installs configure weekly log
+rotation on macOS and on Linux when `logrotate` is available.
 
 Upgrade the global npm package and append missing workspace defaults with:
 

package/dist/conversation/contact-note.js

@@ -26,6 +26,9 @@ export function parseContactNickname(raw, fallback) {
 export async function refreshContactNote() {
     cachedNickname = parseContactNickname(await loadContactNote(), "");
 }
+export function applyContactNoteContent(raw) {
+    cachedNickname = parseContactNickname(raw, "");
+}
 export function getContactNickname(fallback) {
     return cachedNickname || fallback;
 }

package/dist/lifecycle/service.js

@@ -6,16 +6,26 @@ import { dirname, resolve } from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 const SERVICE_LABEL = "com.qearlyao.familiar";
+const LOG_ROTATION_LABEL = `${SERVICE_LABEL}.log-rotation`;
 const SYSTEMD_SERVICE = "familiar.service";
+const SYSTEMD_LOGROTATE_SERVICE = "familiar-logrotate.service";
+const SYSTEMD_LOGROTATE_TIMER = "familiar-logrotate.timer";
 function servicePaths(workspacePath, input) {
     const logDir = input.resolvePath(workspacePath, "logs");
+    const systemdUserDir = input.resolvePath(input.homeDir, ".config", "systemd", "user");
     return {
         servicePath: input.platform === "darwin"
             ? input.resolvePath(input.homeDir, "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`)
-            : input.resolvePath(input.homeDir, ".config", "systemd", "user", SYSTEMD_SERVICE),
+            : input.resolvePath(systemdUserDir, SYSTEMD_SERVICE),
         logDir,
         stdoutPath: input.resolvePath(logDir, "familiar.out.log"),
         stderrPath: input.resolvePath(logDir, "familiar.err.log"),
+        logrotateConfigPath: input.resolvePath(logDir, "familiar.logrotate.conf"),
+        logrotateStatePath: input.resolvePath(logDir, "familiar.logrotate.state"),
+        logRotationScriptPath: input.resolvePath(logDir, "familiar-rotate-logs.sh"),
+        logRotationLaunchdPath: input.resolvePath(input.homeDir, "Library", "LaunchAgents", `${LOG_ROTATION_LABEL}.plist`),
+        logrotateServicePath: input.resolvePath(systemdUserDir, SYSTEMD_LOGROTATE_SERVICE),
+        logrotateTimerPath: input.resolvePath(systemdUserDir, SYSTEMD_LOGROTATE_TIMER),
     };
 }
 function buildSpec(workspacePath, options = {}) {
@@ -60,6 +70,12 @@ function systemdQuote(value) {
         return value;
     return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("$", "\\$").replaceAll("`", "\\`")}"`;
 }
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function logrotateQuote(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
 function launchdPlist(spec) {
     const args = [spec.nodePath, spec.cliPath, "run", spec.workspacePath]
         .map((value) => `\t\t<string>${xmlEscape(value)}</string>`)
@@ -97,6 +113,26 @@ ${args}
 </plist>
 `;
 }
+function launchdLogRotationPlist(spec) {
+    const args = ["/bin/sh", spec.paths.logRotationScriptPath, spec.paths.stdoutPath, spec.paths.stderrPath]
+        .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>${LOG_ROTATION_LABEL}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+${args}
+\t</array>
+\t<key>StartInterval</key>
+\t<integer>604800</integer>
+</dict>
+</plist>
+`;
+}
 function systemdUnit(spec) {
     const execStart = [spec.nodePath, spec.cliPath, "run", spec.workspacePath].map(systemdQuote).join(" ");
     return `[Unit]
@@ -122,6 +158,62 @@ StandardError=append:${spec.paths.stderrPath}
 WantedBy=default.target
 `;
 }
+function logRotationScript() {
+    return `set -eu
+
+for log_path in "$@"; do
+\t[ -s "$log_path" ] || continue
+\trm -f "$log_path.8.gz"
+\tindex=7
+\twhile [ "$index" -ge 1 ]; do
+\t\tnext=$((index + 1))
+\t\tif [ -f "$log_path.$index.gz" ]; then
+\t\t\tmv "$log_path.$index.gz" "$log_path.$next.gz"
+\t\tfi
+\t\tindex=$((index - 1))
+\tdone
+\tcp "$log_path" "$log_path.1"
+\t: > "$log_path"
+\tgzip -f "$log_path.1"
+done
+`;
+}
+function logrotateConfig(spec) {
+    return `${[spec.paths.stdoutPath, spec.paths.stderrPath].map(logrotateQuote).join(" ")} {
+	weekly
+	rotate 8
+	missingok
+	notifempty
+	copytruncate
+	compress
+	delaycompress
+}
+`;
+}
+function logrotateService(spec, logrotatePath) {
+    const execStart = [logrotatePath, "-s", spec.paths.logrotateStatePath, spec.paths.logrotateConfigPath]
+        .map(systemdQuote)
+        .join(" ");
+    return `[Unit]
+Description=Rotate Familiar service logs
+
+[Service]
+Type=oneshot
+ExecStart=${execStart}
+`;
+}
+function logrotateTimer() {
+    return `[Unit]
+Description=Rotate Familiar service logs weekly
+
+[Timer]
+OnCalendar=weekly
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`;
+}
 async function commandExists(command) {
     try {
         await execFileAsync(command, ["--version"]);
@@ -134,6 +226,18 @@ async function commandExists(command) {
 async function hasCommand(command, options) {
     return options.commandExists ? options.commandExists(command) : commandExists(command);
 }
+async function commandPath(command, options) {
+    if (!(await hasCommand(command, options)))
+        return undefined;
+    try {
+        const output = await capture("sh", ["-c", `command -v ${shellQuote(command)}`], options);
+        const [path] = output.trim().split(/\r?\n/);
+        return path || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function run(command, args, options) {
     if (options.runCommand) {
         await options.runCommand(command, args);
@@ -195,6 +299,57 @@ function serviceDetails(spec) {
         `stderr: ${spec.paths.stderrPath}`,
     ];
 }
+async function prepareLogRotation(spec, options) {
+    if (spec.platform === "darwin") {
+        await writeFile(spec.paths.logRotationScriptPath, logRotationScript(), "utf8");
+        await writeFile(spec.paths.logRotationLaunchdPath, launchdLogRotationPlist(spec), "utf8");
+        return { detail: `log_rotation: ${spec.paths.logRotationLaunchdPath}`, installed: true };
+    }
+    if (spec.platform !== "linux")
+        return undefined;
+    const logrotatePath = await commandPath("logrotate", options);
+    if (!logrotatePath) {
+        return {
+            detail: "logrotate: unavailable; install logrotate and rerun familiar install-service",
+            installed: false,
+        };
+    }
+    await writeFile(spec.paths.logrotateConfigPath, logrotateConfig(spec), "utf8");
+    await writeFile(spec.paths.logrotateServicePath, logrotateService(spec, logrotatePath), "utf8");
+    await writeFile(spec.paths.logrotateTimerPath, logrotateTimer(), "utf8");
+    return { detail: `logrotate: ${spec.paths.logrotateConfigPath}`, installed: true };
+}
+async function enableLogRotation(spec, result, options) {
+    if (!result?.installed)
+        return;
+    if (spec.platform === "darwin") {
+        await runOptional("launchctl", ["bootout", guiDomain(options), spec.paths.logRotationLaunchdPath], options);
+        await run("launchctl", ["bootstrap", guiDomain(options), spec.paths.logRotationLaunchdPath], options);
+        return;
+    }
+    if (spec.platform === "linux") {
+        await run("systemctl", ["--user", "enable", "--now", SYSTEMD_LOGROTATE_TIMER], options);
+    }
+}
+async function removeLogRotation(spec, options) {
+    if (spec.platform === "darwin") {
+        await runOptional("launchctl", ["bootout", guiDomain(options), spec.paths.logRotationLaunchdPath], options);
+    }
+    else if (spec.platform === "linux" && (await hasCommand("systemctl", options))) {
+        await runOptional("systemctl", ["--user", "disable", "--now", SYSTEMD_LOGROTATE_TIMER], options);
+    }
+    for (const path of [
+        spec.paths.logRotationLaunchdPath,
+        spec.paths.logRotationScriptPath,
+        spec.paths.logrotateServicePath,
+        spec.paths.logrotateTimerPath,
+        spec.paths.logrotateConfigPath,
+        spec.paths.logrotateStatePath,
+    ]) {
+        if (existsSync(path))
+            await rm(path);
+    }
+}
 function serviceControlTitle(action) {
     if (action === "start")
         return "Familiar service started.";
@@ -246,10 +401,12 @@ export async function installService(workspacePath, options = {}) {
     await mkdir(spec.paths.logDir, { recursive: true });
     const serviceText = spec.platform === "darwin" ? launchdPlist(spec) : systemdUnit(spec);
     await writeFile(spec.paths.servicePath, serviceText, "utf8");
+    const logRotation = await prepareLogRotation(spec, options);
     if (spec.platform === "darwin") {
         await runOptional("launchctl", ["bootout", guiDomain(options), spec.paths.servicePath], options);
         await run("launchctl", ["bootstrap", guiDomain(options), spec.paths.servicePath], options);
         await run("launchctl", ["kickstart", "-k", `${guiDomain(options)}/${SERVICE_LABEL}`], options);
+        await enableLogRotation(spec, logRotation, options);
     }
     else {
         if (!(await hasCommand("systemctl", options))) {
@@ -257,8 +414,11 @@ export async function installService(workspacePath, options = {}) {
         }
         await run("systemctl", ["--user", "daemon-reload"], options);
         await run("systemctl", ["--user", "enable", "--now", SYSTEMD_SERVICE], options);
+        await enableLogRotation(spec, logRotation, options);
     }
     const details = serviceDetails(spec);
+    if (logRotation)
+        details.push(logRotation.detail);
     const pathWarning = versionManagedPathWarning(spec);
     if (pathWarning)
         details.push(pathWarning);
@@ -282,11 +442,13 @@ export async function uninstallService(workspacePath, options = {}) {
         return unsupported(spec.platform);
     if (spec.platform === "darwin") {
         await runOptional("launchctl", ["bootout", guiDomain(options), spec.paths.servicePath], options);
+        await removeLogRotation(spec, options);
     }
     else {
         if (await hasCommand("systemctl", options)) {
             await runOptional("systemctl", ["--user", "disable", "--now", SYSTEMD_SERVICE], options);
         }
+        await removeLogRotation(spec, options);
     }
     if (existsSync(spec.paths.servicePath))
         await rm(spec.paths.servicePath);
@@ -345,8 +507,10 @@ export const __serviceTest = {
     SYSTEMD_SERVICE,
     buildSpec,
     launchdPlist,
+    launchdLogRotationPlist,
     systemdUnit,
     systemdQuote,
+    logRotationScript,
     xmlEscape,
     versionManagedPathWarning,
 };

package/dist/web/daemon.js

@@ -9,6 +9,7 @@ import { registerWebConfigRoutes } from "./config-routes.js";
 import { registerWebConversationRoutes } from "./conversation-routes.js";
 import { registerWebDiaryRoutes } from "./diary-routes.js";
 import { createWebEventHub } from "./event-hub.js";
+import { registerWebFileRoutes } from "./file-routes.js";
 import { HttpError, sendText } from "./http.js";
 import { createWebRouteRegistry } from "./routes.js";
 import { createWebRuntimeActions } from "./runtime-actions.js";
@@ -69,6 +70,7 @@ export async function startWebDaemon(config, familiarAgent, agentCore, options =
     });
     registerWebConfigRoutes(route, config, agentCore);
     registerWebDiaryRoutes(route, config);
+    registerWebFileRoutes(route, config);
     await subscribeKnownRuntimes();
     const server = createServer((request, response) => {
         const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);

package/dist/web/file-routes.js

@@ -0,0 +1,134 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { applyContactNoteContent, setContactNotePath } from "../conversation/contact-note.js";
+import { isEnoent } from "../util/fs.js";
+import { isRecord } from "../util/guards.js";
+import { HttpError, readJsonBody, sendJson } from "./http.js";
+const WEB_FILE_DEFINITIONS = [
+    {
+        id: "soul",
+        name: "SOUL.md",
+        title: "soul",
+        description: "who your companion is trying to be",
+        path: (config) => config.persona.soul,
+    },
+    {
+        id: "user",
+        name: "USER.md",
+        title: "you",
+        description: "what they should remember about you",
+        path: (config) => config.persona.user,
+    },
+    {
+        id: "memory",
+        name: "MEMORY.md",
+        title: "memory",
+        description: "the long thread that should stay close",
+        path: (config) => config.persona.memory,
+    },
+    {
+        id: "heartbeat",
+        name: "HEARTBEAT.md",
+        title: "heartbeat",
+        description: "what they do when the room gets quiet",
+        path: (config) => resolve(config.workspacePath, "HEARTBEAT.md"),
+    },
+    {
+        id: "contact",
+        name: "CONTACT.md",
+        title: "contact",
+        description: "the name you keep for yourself here",
+        path: (config) => config.persona.contact,
+        afterWrite: (path, content) => {
+            setContactNotePath(path);
+            applyContactNoteContent(content);
+        },
+    },
+];
+const WEB_FILES = WEB_FILE_DEFINITIONS;
+const MAX_WEB_FILE_BODY_BYTES = 1024 * 1024;
+export function registerWebFileRoutes(route, config) {
+    route("GET", "/api/web/files", async (_request, response) => {
+        sendJson(response, 200, { files: await listWebFiles(config) });
+    });
+    route("GET", "/api/web/file", async (_request, response, url) => {
+        const id = url.searchParams.get("id") ?? "";
+        sendJson(response, 200, { file: await readWebFile(config, id) });
+    });
+    route("PUT", "/api/web/file", async (request, response) => {
+        const body = await readJsonBody(request, MAX_WEB_FILE_BODY_BYTES);
+        const { id, content } = fileUpdateFromBody(body);
+        sendJson(response, 200, { file: await writeWebFile(config, id, content) });
+    });
+}
+export async function listWebFiles(config) {
+    return Promise.all(WEB_FILES.map((definition) => readFileSummary(config, definition)));
+}
+export async function readWebFile(config, rawId) {
+    const definition = webFileDefinition(rawId);
+    const path = webFilePath(config, definition);
+    const summary = await readFileSummary(config, definition);
+    let content = "";
+    try {
+        content = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            throw error;
+    }
+    return { ...summary, content };
+}
+export async function writeWebFile(config, rawId, content) {
+    const definition = webFileDefinition(rawId);
+    const path = webFilePath(config, definition);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+    definition.afterWrite?.(path, content);
+    return readWebFile(config, definition.id);
+}
+async function readFileSummary(config, definition) {
+    const path = webFilePath(config, definition);
+    try {
+        const fileStat = await stat(path);
+        if (!fileStat.isFile())
+            throw new HttpError(404, `${definition.name} is not a file`);
+        return {
+            id: definition.id,
+            name: definition.name,
+            title: definition.title,
+            description: definition.description,
+            mtimeMs: Math.floor(fileStat.mtimeMs),
+            sizeBytes: fileStat.size,
+            exists: true,
+        };
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            throw error;
+        return {
+            id: definition.id,
+            name: definition.name,
+            title: definition.title,
+            description: definition.description,
+            mtimeMs: null,
+            sizeBytes: 0,
+            exists: false,
+        };
+    }
+}
+function fileUpdateFromBody(body) {
+    if (!isRecord(body) || typeof body.id !== "string")
+        throw new HttpError(400, "file id is required");
+    if (typeof body.content !== "string")
+        throw new HttpError(400, "content is required");
+    return { id: body.id, content: body.content };
+}
+function webFileDefinition(rawId) {
+    const definition = WEB_FILES.find((candidate) => candidate.id === rawId);
+    if (!definition)
+        throw new HttpError(400, `unknown file: ${rawId}`);
+    return definition;
+}
+function webFilePath(config, definition) {
+    return resolve(definition.path(config));
+}

package/dist/web/http.js

@@ -21,13 +21,13 @@ export function sendText(response, status, text) {
     response.writeHead(status, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
     response.end(text);
 }
-export async function readJsonBody(request) {
+export async function readJsonBody(request, maxBytes = MAX_BODY_BYTES) {
     const chunks = [];
     let total = 0;
     for await (const chunk of request) {
         const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         total += buffer.length;
-        if (total > MAX_BODY_BYTES)
+        if (total > maxBytes)
             throw new HttpError(413, "Request body too large");
         chunks.push(buffer);
     }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
 	"name": "@qearlyao/familiar",
-	"version": "0.4.2",
+	"version": "0.4.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@qearlyao/familiar",
-			"version": "0.4.2",
+			"version": "0.4.5",
 			"license": "MIT",
 			"dependencies": {
 				"@earendil-works/pi-agent-core": "0.78.0",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@qearlyao/familiar",
-	"version": "0.4.2",
+	"version": "0.4.5",
 	"license": "MIT",
 	"type": "module",
 	"repository": {