@getfamiliar/shared 0.1.15 → 0.1.16

package/build/WebStaticAssets.d.ts

@@ -0,0 +1,72 @@
+import type { Context } from "hono";
+/**
+ * Content type for a file name, by extension.
+ *
+ * @param fileName File name or path.
+ * @returns The media type, `application/octet-stream` when unknown.
+ */
+export declare function contentTypeForFile(fileName: string): string;
+/** Options of {@link WebStaticAssets}. */
+export interface WebStaticAssetsOptions {
+    /**
+     * URL prefix the directory is served under (e.g. `/plugins/web-chat/page`);
+     * stripped from the request path before mapping it onto a file.
+     * Default: the site root.
+     */
+    readonly urlPrefix?: string;
+    /**
+     * Answer unknown GET paths without a file extension with `index.html`,
+     * so client-side routes of a single-page app survive a reload.
+     */
+    readonly spaFallback: boolean;
+    /** Hint added to the 500 answer when the directory was never built (e.g. "run `npm run build` in plugins/web-chat"). */
+    readonly missingBuildHint?: string;
+}
+/**
+ * Serve a directory of built web assets (a Vite build output) from a
+ * Hono route, for web UI plugins and plugin pages.
+ *
+ * A request path maps onto a file below the directory; paths escaping it
+ * are refused. Files under `assets/` (content-hashed) are cached forever,
+ * everything else is revalidated (`no-cache`).
+ */
+export declare class WebStaticAssets {
+    private readonly rootDir;
+    private readonly options;
+    /**
+     * @param rootDir Absolute path of the build output.
+     * @param options URL prefix, SPA fallback, build hint.
+     */
+    constructor(rootDir: string, options: WebStaticAssetsOptions);
+    /**
+     * Answer one request.
+     *
+     * @param c Request context.
+     * @returns The file, the SPA fallback, 404, or a 500 page when the
+     *   directory was never built.
+     */
+    handle(c: Context): Promise<Response>;
+    /**
+     * The 500 answer for a directory that was never built.
+     *
+     * @param c Request context.
+     * @returns The response.
+     */
+    private missingBuild;
+    /**
+     * Map a URL path onto a file path below {@link rootDir}.
+     *
+     * @param urlPath Request path.
+     * @returns The absolute file path, or null when it lies outside the
+     *   prefix, escapes the directory or is not decodable.
+     */
+    private resolveRequestPath;
+    /**
+     * Send one file with content type and cache headers.
+     *
+     * @param c Request context.
+     * @param file Absolute file path below the root.
+     * @returns The response.
+     */
+    private sendFile;
+}

package/build/WebStaticAssets.js

@@ -0,0 +1,204 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+/** Content types of the files a Vite build emits. */
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".txt": "text/plain; charset=utf-8",
+    ".wasm": "application/wasm",
+    ".webmanifest": "application/manifest+json",
+    ".avif": "image/avif",
+    ".pdf": "application/pdf",
+    ".csv": "text/csv; charset=utf-8",
+    ".md": "text/markdown; charset=utf-8",
+    ".xml": "application/xml",
+    ".zip": "application/zip",
+    ".mp3": "audio/mpeg",
+    ".ogg": "audio/ogg",
+    ".wav": "audio/wav",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".ics": "text/calendar; charset=utf-8",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+/**
+ * Content type for a file name, by extension.
+ *
+ * @param fileName File name or path.
+ * @returns The media type, `application/octet-stream` when unknown.
+ */
+export function contentTypeForFile(fileName) {
+    return CONTENT_TYPES[path.extname(fileName).toLowerCase()] ?? "application/octet-stream";
+}
+/** Vite puts content-hashed bundles here; they never change under the same name. */
+const HASHED_ASSETS_DIR = "assets/";
+/**
+ * Serve a directory of built web assets (a Vite build output) from a
+ * Hono route, for web UI plugins and plugin pages.
+ *
+ * A request path maps onto a file below the directory; paths escaping it
+ * are refused. Files under `assets/` (content-hashed) are cached forever,
+ * everything else is revalidated (`no-cache`).
+ */
+export class WebStaticAssets {
+    rootDir;
+    options;
+    /**
+     * @param rootDir Absolute path of the build output.
+     * @param options URL prefix, SPA fallback, build hint.
+     */
+    constructor(rootDir, options) {
+        this.rootDir = path.resolve(rootDir);
+        this.options = options;
+    }
+    /**
+     * Answer one request.
+     *
+     * @param c Request context.
+     * @returns The file, the SPA fallback, 404, or a 500 page when the
+     *   directory was never built.
+     */
+    async handle(c) {
+        if (c.req.method !== "GET" && c.req.method !== "HEAD") {
+            return c.notFound();
+        }
+        const requested = this.resolveRequestPath(c.req.path);
+        if (requested === null) {
+            return c.notFound();
+        }
+        if (await isFile(requested)) {
+            return this.sendFile(c, requested);
+        }
+        if (!this.options.spaFallback || path.extname(requested) !== "") {
+            return (await isDirectory(this.rootDir)) ? c.notFound() : this.missingBuild(c);
+        }
+        const indexFile = path.join(this.rootDir, "index.html");
+        if (!(await isFile(indexFile))) {
+            return this.missingBuild(c);
+        }
+        return this.sendFile(c, indexFile);
+    }
+    /**
+     * The 500 answer for a directory that was never built.
+     *
+     * @param c Request context.
+     * @returns The response.
+     */
+    missingBuild(c) {
+        const hint = this.options.missingBuildHint ?? "build the package";
+        return c.text(`the web assets in ${this.rootDir} are missing — ${hint}`, 500);
+    }
+    /**
+     * Map a URL path onto a file path below {@link rootDir}.
+     *
+     * @param urlPath Request path.
+     * @returns The absolute file path, or null when it lies outside the
+     *   prefix, escapes the directory or is not decodable.
+     */
+    resolveRequestPath(urlPath) {
+        const prefix = (this.options.urlPrefix ?? "").replace(/\/+$/, "");
+        if (prefix !== "" && urlPath !== prefix && !urlPath.startsWith(`${prefix}/`)) {
+            return null;
+        }
+        let decoded;
+        try {
+            decoded = decodeURIComponent(urlPath.slice(prefix.length));
+        }
+        catch {
+            return null;
+        }
+        if (decoded.includes("\0")) {
+            return null;
+        }
+        // The root resolves to the directory itself, which takes the SPA fallback.
+        const relative = decoded.replace(/^\/+/, "");
+        const resolved = path.resolve(this.rootDir, relative);
+        if (resolved !== this.rootDir && !resolved.startsWith(this.rootDir + path.sep)) {
+            return null;
+        }
+        return resolved;
+    }
+    /**
+     * Send one file with content type and cache headers.
+     *
+     * @param c Request context.
+     * @param file Absolute file path below the root.
+     * @returns The response.
+     */
+    async sendFile(c, file) {
+        const body = await readFile(file);
+        const relative = path.relative(this.rootDir, file).split(path.sep).join("/");
+        const cacheControl = relative.startsWith(HASHED_ASSETS_DIR)
+            ? "public, max-age=31536000, immutable"
+            : "no-cache";
+        return new Response(c.req.method === "HEAD" ? null : new Uint8Array(body), {
+            status: 200,
+            headers: {
+                "content-type": contentTypeForFile(file),
+                "cache-control": cacheControl,
+            },
+        });
+    }
+}
+/**
+ * Whether `file` exists and is a regular file.
+ *
+ * @param file Absolute path.
+ * @returns True for a regular file.
+ * @throws {Error} For errors other than "does not exist".
+ */
+async function isFile(file) {
+    try {
+        return (await stat(file)).isFile();
+    }
+    catch (err) {
+        if (isMissing(err)) {
+            return false;
+        }
+        throw err;
+    }
+}
+/**
+ * Whether `dir` exists and is a directory.
+ *
+ * @param dir Absolute path.
+ * @returns True for a directory.
+ * @throws {Error} For errors other than "does not exist".
+ */
+async function isDirectory(dir) {
+    try {
+        return (await stat(dir)).isDirectory();
+    }
+    catch (err) {
+        if (isMissing(err)) {
+            return false;
+        }
+        throw err;
+    }
+}
+/**
+ * Whether a fs error means "path does not exist".
+ *
+ * @param err The error.
+ * @returns True for ENOENT / ENOTDIR.
+ */
+function isMissing(err) {
+    const code = err.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}

package/build/index.d.ts

@@ -2,7 +2,8 @@ export type { AgentRunCallType, AgentRunPatch, AgentRunRow, AgentRunState, NewAg
 export { AgentRunBus, type AgentRunUnsubscribe } from "./AgentRunBus.js";
 export { BASTION_TOKEN_HEADER } from "./BastionAuth.js";
 export { buildCalendarEventId, type CalendarApi, type CalendarAttachmentMeta, type CalendarAttendee, type CalendarChangePayload, type CalendarEventRow, type CalendarEventType, type CalendarImportance, type CalendarProvider, type CalendarResponseStatus, type CalendarRow, type CalendarSensitivity, type CalendarShowAs, type CalendarType, type CreateEventInput, type FindEventsQuery, type NewCalendarEvent, parseCalendarEventId, type UpdateEventInput, type UpsertCalendarInput, } from "./Calendar.js";
-export type { ChatFilter, ChatMessage, ChatRole, NewChatMessage } from "./ChatMessage.js";
+export { type ParsedChatInput, parseChatInput } from "./ChatInput.js";
+export { type ChatFilter, type ChatHistoryQuery, type ChatMessage, type ChatRole, MAX_CHAT_HISTORY_PAGE, type NewChatMessage, } from "./ChatMessage.js";
 export { type ChatHandler, ChatMessageBus, type ChatUnsubscribe } from "./ChatMessageBus.js";
 export { type ConfigService, DEFAULT_WRITABLE_PATHS } from "./Config.js";
 export type { ContainerToolInfo } from "./ContainerTool.js";
@@ -28,9 +29,11 @@ export type { AnyCommandDef, EmitHandle, EmitOptions, EmittedEventDescriptor, Ho
 export { DaemonStoppedError, definePlugin } from "./Plugin.js";
 export { type NotificationHandler, POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, PostgresConnection, type PostgresConnectionConfig, } from "./PostgresConnection.js";
 export { CACHE_MARKER_PLACEHOLDER, CORE_PROMPT_PLACEHOLDERS, isCorePromptPlaceholder, PROMPT_PLACEHOLDER_NAME_PATTERN, PROMPT_TEMPLATE_FILE, PromptPlaceholderConflictError, type PromptPlaceholderDefinition, type PromptPlaceholderKind, } from "./PromptPlaceholders.js";
+export { isSafeIncludePath, MAX_TEMPLATE_DEPTH, type ParsedTemplate, type ParseTemplateOptions, type PlaceholderUse, parseTemplate, type RenderedTemplate, renderTemplate, type TemplateNode, } from "./PromptTemplate.js";
 export type { NewScheduledSubagent, ScheduledSubagentRow } from "./ScheduledSubagent.js";
 export { ScheduledSubagentBus, type ScheduledSubagentNotification, type ScheduledSubagentOp, type ScheduledSubagentUnsubscribe, } from "./ScheduledSubagentBus.js";
 export { AGENTRUNS_CHANNEL, CHATMESSAGES_NEW_CHANNEL, EVENT_TERMINAL_UPDATE_SQL, EVENTS_NEW_CHANNEL, EVENTS_STATE_CHANNEL, SCHEDULED_SUBAGENTS_CHANNEL, SCHEMA_SQL, STEPRESULTS_NEW_CHANNEL, TOPIC_PATTERN, } from "./Schema.js";
+export { isHiddenScratchFile, type ScratchFile, scratchSpillFileName } from "./Scratch.js";
 export type { NewStepResult, StepResultRow } from "./StepResult.js";
 export { StepResultBus, type StepResultUnsubscribe } from "./StepResultBus.js";
 export { type StorageApi, type StorageCapabilities, type StorageConflict, type StorageContentHash, type StorageDownloadResult, type StorageDrive, type StorageDriveKind, StorageError, type StorageErrorCode, type StorageHashAlgo, type StorageItem, type StorageItemKind, type StorageListOrder, type StorageMatchedIn, type StoragePage, type StoragePageOptions, type StorageProvider, type StorageSearchHit, type StorageSearchQuery, type StorageUploadSource, } from "./Storage.js";
@@ -40,5 +43,9 @@ export { ToolCallBus } from "./ToolCallBus.js";
 export { DEFAULT_TOOL_LEVEL, type ToolLevel } from "./ToolLevel.js";
 export { DEFAULT_TOOL_CALL_OFFLOADING_LIMIT, type OffloadedJson, runJsonLinesTool, runJsonTool, runTextTool, ToolError, type ToolRunContext, type ToolRunOptions, truncateUtf8, } from "./ToolRunner.js";
 export { ALL_GROUP_NAME, CORE_PLUGIN_ID, IDENT_PATTERN, MCP_GROUP_NAME, matchesAnyToolPattern, NONE_GROUP_NAME, RESERVED_GROUP_NAMES, toolPatternMatches, validateGroupName, } from "./ToolsExpressionUtils.js";
-export type { WorkspaceFile, WorkspaceFileFilter, WorkspaceWatcherApi, } from "./WorkspaceFile.js";
+export { MIN_PROXY_SECRET_LENGTH, PROXY_SECRET_HEADER, type TrustedProxyRegistration, type WebApi, type WebAuthPageView, type WebPrincipal, type WebUi, type WebUiBindings, type WebUiEnv, } from "./WebAuth.js";
+export { firstMenuRoute, WEB_MENU_ICON_PATTERN, type WebMenuContribution, type WebMenuEntry, type WebMenuItem, type WebMenuSubItem, } from "./WebMenu.js";
+export { type MountWebPage, type WebPageContext, type WebPageEntry, type WebPageModule, type WebPluginSocket, type WebPluginUi, type WebSocketConnectionInfo, type WebSocketPeer, webPluginBasePath, } from "./WebPlugin.js";
 export { DEFAULT_WEBSERVER_HOST, DEFAULT_WEBSERVER_PORT } from "./WebServerDefaults.js";
+export { contentTypeForFile, WebStaticAssets, type WebStaticAssetsOptions, } from "./WebStaticAssets.js";
+export type { WorkspaceFile, WorkspaceFileFilter, WorkspaceWatcherApi, } from "./WorkspaceFile.js";

package/build/index.js

@@ -1,6 +1,8 @@
 export { AgentRunBus } from "./AgentRunBus.js";
 export { BASTION_TOKEN_HEADER } from "./BastionAuth.js";
 export { buildCalendarEventId, parseCalendarEventId, } from "./Calendar.js";
+export { parseChatInput } from "./ChatInput.js";
+export { MAX_CHAT_HISTORY_PAGE, } from "./ChatMessage.js";
 export { ChatMessageBus } from "./ChatMessageBus.js";
 export { DEFAULT_WRITABLE_PATHS } from "./Config.js";
 export { parseCron } from "./CronExpression.js";
@@ -22,8 +24,10 @@ export { matchesAnyGlob, matchesGlob } from "./PathGlob.js";
 export { DaemonStoppedError, definePlugin } from "./Plugin.js";
 export { POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, PostgresConnection, } from "./PostgresConnection.js";
 export { CACHE_MARKER_PLACEHOLDER, CORE_PROMPT_PLACEHOLDERS, isCorePromptPlaceholder, PROMPT_PLACEHOLDER_NAME_PATTERN, PROMPT_TEMPLATE_FILE, PromptPlaceholderConflictError, } from "./PromptPlaceholders.js";
+export { isSafeIncludePath, MAX_TEMPLATE_DEPTH, parseTemplate, renderTemplate, } from "./PromptTemplate.js";
 export { ScheduledSubagentBus, } from "./ScheduledSubagentBus.js";
 export { AGENTRUNS_CHANNEL, CHATMESSAGES_NEW_CHANNEL, EVENT_TERMINAL_UPDATE_SQL, EVENTS_NEW_CHANNEL, EVENTS_STATE_CHANNEL, SCHEDULED_SUBAGENTS_CHANNEL, SCHEMA_SQL, STEPRESULTS_NEW_CHANNEL, TOPIC_PATTERN, } from "./Schema.js";
+export { isHiddenScratchFile, scratchSpillFileName } from "./Scratch.js";
 export { StepResultBus } from "./StepResultBus.js";
 export { StorageError, } from "./Storage.js";
 export { dayBoundsInZone, parseInZone, renderInZone, } from "./Timezone.js";
@@ -31,4 +35,8 @@ export { ToolCallBus } from "./ToolCallBus.js";
 export { DEFAULT_TOOL_LEVEL } from "./ToolLevel.js";
 export { DEFAULT_TOOL_CALL_OFFLOADING_LIMIT, runJsonLinesTool, runJsonTool, runTextTool, ToolError, truncateUtf8, } from "./ToolRunner.js";
 export { ALL_GROUP_NAME, CORE_PLUGIN_ID, IDENT_PATTERN, MCP_GROUP_NAME, matchesAnyToolPattern, NONE_GROUP_NAME, RESERVED_GROUP_NAMES, toolPatternMatches, validateGroupName, } from "./ToolsExpressionUtils.js";
+export { MIN_PROXY_SECRET_LENGTH, PROXY_SECRET_HEADER, } from "./WebAuth.js";
+export { firstMenuRoute, WEB_MENU_ICON_PATTERN, } from "./WebMenu.js";
+export { webPluginBasePath, } from "./WebPlugin.js";
 export { DEFAULT_WEBSERVER_HOST, DEFAULT_WEBSERVER_PORT } from "./WebServerDefaults.js";
+export { contentTypeForFile, WebStaticAssets, } from "./WebStaticAssets.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getfamiliar/shared",
   "type": "module",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Familiar — shared types and bus-state client between host and container.",
   "publishConfig": {
     "access": "public"
@@ -41,6 +41,7 @@
     "cli-table3": "^0.6.5",
     "croner": "^10.0.1",
     "friendly-node-cron": "^1.5.0",
+    "hono": "^4.13.16",
     "luxon": "^3.7.2",
     "marked": "^15.0.12",
     "pg": "^8.13.1",