@getfamiliar/shared 0.1.13 → 0.1.15

package/build/DockerTools.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared bridge network all Familiar containers join. Owned
+ * by the daemon (see `commands/Start.ts`); created once via
+ * {@link ensureNetwork} before any container is started.
+ */
+export declare const SHARED_NETWORK_NAME = "familiar-net";
+/**
+ * Internal (egress-less) bridge network the locked-down agent container
+ * joins. Created with `--internal` so the agent has no route to the
+ * internet; it reaches postgres (dual-homed onto this net) and the host
+ * bastion (via the `familiar-bastion-bridge` socat sidecar, also on this
+ * net) by container name. Owned by the daemon, created via
+ * {@link ensureNetwork} with `{ internal: true }`.
+ */
+export declare const ISOLATED_NETWORK_NAME = "familiar-isolated";
+/** Options shared by {@link dockerExec}. */
+export interface DockerExecOptions {
+    /** If true, non-zero exit codes resolve instead of throwing. */
+    readonly allowFailure?: boolean;
+}
+/** Output of {@link dockerCapture}. */
+export interface DockerCaptureResult {
+    readonly code: number | null;
+    readonly stdout: string;
+}
+/**
+ * Run a docker CLI command and discard its stdio. Resolves on exit
+ * code 0 (or always when `allowFailure` is set); rejects otherwise.
+ */
+export declare function dockerExec(args: readonly string[], options?: DockerExecOptions): Promise<void>;
+/**
+ * Run a docker CLI command and capture stdout. Never throws on non-zero
+ * exit; callers inspect the returned `code`.
+ */
+export declare function dockerCapture(args: readonly string[]): Promise<DockerCaptureResult>;
+/** Whether a container with the given name is currently running. */
+export declare function isContainerRunning(name: string): Promise<boolean>;
+/** Whether a Docker network with the given name already exists. */
+export declare function isNetworkPresent(name: string): Promise<boolean>;
+/**
+ * Whether a Docker image with the given reference is present in the
+ * local image store. Used by the pull-mode image lifecycle to avoid
+ * re-pulling a version-pinned image that's already local.
+ *
+ * @param ref Image reference (tag or registry-qualified `name:tag`).
+ * @returns true if `docker image inspect` succeeds.
+ */
+export declare function isImagePresent(ref: string): Promise<boolean>;
+/** Options for {@link buildNetworkCreateArgs} / {@link ensureNetwork}. */
+export interface NetworkCreateOptions {
+    /**
+     * Create the network with `--internal` so containers on it have no
+     * egress to the host or the internet — only to other containers on
+     * the same network. Used for the agent's `familiar-isolated` net.
+     */
+    readonly internal?: boolean;
+}
+/**
+ * Build the `docker network create` argument vector. Pure (no side
+ * effects) so it can be unit-tested without a daemon.
+ *
+ * @param name Network name to create.
+ * @param options Network creation flags (e.g. `internal`).
+ * @returns The full docker CLI argv, e.g. `["network", "create", "--internal", "familiar-isolated"]`.
+ */
+export declare function buildNetworkCreateArgs(name: string, options?: NetworkCreateOptions): string[];
+/**
+ * Create the named bridge network if it doesn't already exist. Idempotent.
+ *
+ * @param name Network name to ensure.
+ * @param options Network creation flags applied only on first creation
+ *   (an existing network is left as-is).
+ */
+export declare function ensureNetwork(name: string, options?: NetworkCreateOptions): Promise<void>;
+/**
+ * Attach an already-running container to an additional network by name.
+ * Callers recreate their container on every `start()` (via
+ * {@link removeContainer} first), so the attachment is always fresh —
+ * this throws on failure rather than swallowing it, so a genuine
+ * problem (missing network, missing container) surfaces instead of
+ * silently leaving the container unable to reach its peer.
+ *
+ * @param network Network to connect the container to.
+ * @param container Name of the running container to attach.
+ * @throws If the docker command fails (network/container missing, etc.).
+ */
+export declare function connectNetwork(network: string, container: string): Promise<void>;
+/**
+ * Force-remove a container by name. Default `allowFailure: true` because
+ * "remove if it exists" is the common idempotent-cleanup intent.
+ */
+export declare function removeContainer(name: string, options?: DockerExecOptions): Promise<void>;
+/** Send `docker stop` to a container. Ignores already-stopped/missing containers. */
+export declare function stopContainer(name: string): Promise<void>;
+/**
+ * Run a docker CLI command with the parent process's stdin/stdout/
+ * stderr inherited, blocking until the child exits. Used by
+ * subcommands that hand the user's terminal to a foreground docker
+ * process (`familiar psql`'s psql shell, `familiar mcp call`'s
+ * one-shot CLI invocations against an MCP runtime container).
+ *
+ * Returns the child's exit status — `null`-on-signal collapses to
+ * 1 so the caller's `process.exit(...)` always sees a usable
+ * number. A failure to launch docker itself (e.g. binary missing)
+ * surfaces as a thrown {@link Error} the caller can format.
+ *
+ * @throws If the docker binary couldn't be spawned at all.
+ */
+export declare function dockerInteractive(args: readonly string[]): number;
+/**
+ * On Linux, `host.docker.internal` isn't built-in and must be mapped to
+ * the host gateway explicitly. macOS and Windows resolve it natively.
+ *
+ * Used by sidecars that dial a host-side listener (the bastion bridge,
+ * the tailscale plugin's serve proxy to the webserver).
+ *
+ * @returns Extra `docker run` args, or an empty array on macOS/Windows.
+ */
+export declare function hostGatewayArgs(): string[];

package/build/DockerTools.js

@@ -0,0 +1,175 @@
+import { spawn, spawnSync } from "node:child_process";
+import os from "node:os";
+/**
+ * Shared bridge network all Familiar containers join. Owned
+ * by the daemon (see `commands/Start.ts`); created once via
+ * {@link ensureNetwork} before any container is started.
+ */
+export const SHARED_NETWORK_NAME = "familiar-net";
+/**
+ * Internal (egress-less) bridge network the locked-down agent container
+ * joins. Created with `--internal` so the agent has no route to the
+ * internet; it reaches postgres (dual-homed onto this net) and the host
+ * bastion (via the `familiar-bastion-bridge` socat sidecar, also on this
+ * net) by container name. Owned by the daemon, created via
+ * {@link ensureNetwork} with `{ internal: true }`.
+ */
+export const ISOLATED_NETWORK_NAME = "familiar-isolated";
+/**
+ * Run a docker CLI command and discard its stdio. Resolves on exit
+ * code 0 (or always when `allowFailure` is set); rejects otherwise.
+ */
+export function dockerExec(args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("docker", [...args], { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        proc.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on("close", (code) => {
+            if (code === 0 || options.allowFailure) {
+                resolve();
+                return;
+            }
+            const trimmed = stderr.trim();
+            const suffix = trimmed.length > 0 ? `: ${trimmed}` : "";
+            reject(new Error(`docker ${args.join(" ")} exited with code ${code}${suffix}`));
+        });
+        proc.on("error", reject);
+    });
+}
+/**
+ * Run a docker CLI command and capture stdout. Never throws on non-zero
+ * exit; callers inspect the returned `code`.
+ */
+export function dockerCapture(args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("docker", [...args], { stdio: ["ignore", "pipe", "ignore"] });
+        let stdout = "";
+        proc.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        proc.on("close", (code) => {
+            resolve({ code, stdout });
+        });
+        proc.on("error", reject);
+    });
+}
+/** Whether a container with the given name is currently running. */
+export async function isContainerRunning(name) {
+    const { code, stdout } = await dockerCapture([
+        "container",
+        "inspect",
+        "-f",
+        "{{.State.Running}}",
+        name,
+    ]);
+    return code === 0 && stdout.trim() === "true";
+}
+/** Whether a Docker network with the given name already exists. */
+export async function isNetworkPresent(name) {
+    const { code } = await dockerCapture(["network", "inspect", name]);
+    return code === 0;
+}
+/**
+ * Whether a Docker image with the given reference is present in the
+ * local image store. Used by the pull-mode image lifecycle to avoid
+ * re-pulling a version-pinned image that's already local.
+ *
+ * @param ref Image reference (tag or registry-qualified `name:tag`).
+ * @returns true if `docker image inspect` succeeds.
+ */
+export async function isImagePresent(ref) {
+    const { code } = await dockerCapture(["image", "inspect", ref]);
+    return code === 0;
+}
+/**
+ * Build the `docker network create` argument vector. Pure (no side
+ * effects) so it can be unit-tested without a daemon.
+ *
+ * @param name Network name to create.
+ * @param options Network creation flags (e.g. `internal`).
+ * @returns The full docker CLI argv, e.g. `["network", "create", "--internal", "familiar-isolated"]`.
+ */
+export function buildNetworkCreateArgs(name, options = {}) {
+    const args = ["network", "create"];
+    if (options.internal) {
+        args.push("--internal");
+    }
+    args.push(name);
+    return args;
+}
+/**
+ * Create the named bridge network if it doesn't already exist. Idempotent.
+ *
+ * @param name Network name to ensure.
+ * @param options Network creation flags applied only on first creation
+ *   (an existing network is left as-is).
+ */
+export async function ensureNetwork(name, options = {}) {
+    if (!(await isNetworkPresent(name))) {
+        await dockerExec(buildNetworkCreateArgs(name, options));
+    }
+}
+/**
+ * Attach an already-running container to an additional network by name.
+ * Callers recreate their container on every `start()` (via
+ * {@link removeContainer} first), so the attachment is always fresh —
+ * this throws on failure rather than swallowing it, so a genuine
+ * problem (missing network, missing container) surfaces instead of
+ * silently leaving the container unable to reach its peer.
+ *
+ * @param network Network to connect the container to.
+ * @param container Name of the running container to attach.
+ * @throws If the docker command fails (network/container missing, etc.).
+ */
+export function connectNetwork(network, container) {
+    return dockerExec(["network", "connect", network, container]);
+}
+/**
+ * Force-remove a container by name. Default `allowFailure: true` because
+ * "remove if it exists" is the common idempotent-cleanup intent.
+ */
+export function removeContainer(name, options = { allowFailure: true }) {
+    return dockerExec(["rm", "-f", name], options);
+}
+/** Send `docker stop` to a container. Ignores already-stopped/missing containers. */
+export function stopContainer(name) {
+    return dockerExec(["stop", name], { allowFailure: true });
+}
+/**
+ * Run a docker CLI command with the parent process's stdin/stdout/
+ * stderr inherited, blocking until the child exits. Used by
+ * subcommands that hand the user's terminal to a foreground docker
+ * process (`familiar psql`'s psql shell, `familiar mcp call`'s
+ * one-shot CLI invocations against an MCP runtime container).
+ *
+ * Returns the child's exit status — `null`-on-signal collapses to
+ * 1 so the caller's `process.exit(...)` always sees a usable
+ * number. A failure to launch docker itself (e.g. binary missing)
+ * surfaces as a thrown {@link Error} the caller can format.
+ *
+ * @throws If the docker binary couldn't be spawned at all.
+ */
+export function dockerInteractive(args) {
+    const result = spawnSync("docker", [...args], { stdio: "inherit" });
+    if (result.error) {
+        throw new Error(`failed to launch docker: ${result.error.message}`);
+    }
+    return result.status ?? 1;
+}
+/**
+ * On Linux, `host.docker.internal` isn't built-in and must be mapped to
+ * the host gateway explicitly. macOS and Windows resolve it natively.
+ *
+ * Used by sidecars that dial a host-side listener (the bastion bridge,
+ * the tailscale plugin's serve proxy to the webserver).
+ *
+ * @returns Extra `docker run` args, or an empty array on macOS/Windows.
+ */
+export function hostGatewayArgs() {
+    if (os.platform() === "linux") {
+        return ["--add-host=host.docker.internal:host-gateway"];
+    }
+    return [];
+}

package/build/WebServerDefaults.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Defaults of the core `webserver.*` config keys. Shared because both
+ * the host's `WebServer` and plugins that front it (tailscale) must
+ * resolve the same effective port and bind address.
+ */
+/** Port the webserver listens on when `webserver.port` is unset. */
+export declare const DEFAULT_WEBSERVER_PORT = 8080;
+/** Address the webserver binds on when `webserver.host` is unset. */
+export declare const DEFAULT_WEBSERVER_HOST = "0.0.0.0";

package/build/WebServerDefaults.js

@@ -0,0 +1,9 @@
+/**
+ * Defaults of the core `webserver.*` config keys. Shared because both
+ * the host's `WebServer` and plugins that front it (tailscale) must
+ * resolve the same effective port and bind address.
+ */
+/** Port the webserver listens on when `webserver.port` is unset. */
+export const DEFAULT_WEBSERVER_PORT = 8080;
+/** Address the webserver binds on when `webserver.host` is unset. */
+export const DEFAULT_WEBSERVER_HOST = "0.0.0.0";

package/build/index.d.ts

@@ -7,6 +7,7 @@ export { type ChatHandler, ChatMessageBus, type ChatUnsubscribe } from "./ChatMe
 export { type ConfigService, DEFAULT_WRITABLE_PATHS } from "./Config.js";
 export type { ContainerToolInfo } from "./ContainerTool.js";
 export { type ParsedCron, parseCron } from "./CronExpression.js";
+export { buildNetworkCreateArgs, connectNetwork, type DockerCaptureResult, type DockerExecOptions, dockerCapture, dockerExec, dockerInteractive, ensureNetwork, hostGatewayArgs, ISOLATED_NETWORK_NAME, isContainerRunning, isImagePresent, isNetworkPresent, type NetworkCreateOptions, removeContainer, SHARED_NETWORK_NAME, stopContainer, } from "./DockerTools.js";
 export type { EventFile, EventFilter, EventPatch, EventRow, EventState, NewEvent, } from "./Event.js";
 export { EVENT_PRIORITY } from "./Event.js";
 export { DuplicateIdempotencyKeyError, EventBus } from "./EventBus.js";
@@ -40,3 +41,4 @@ 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 { DEFAULT_WEBSERVER_HOST, DEFAULT_WEBSERVER_PORT } from "./WebServerDefaults.js";

package/build/index.js

@@ -4,6 +4,7 @@ export { buildCalendarEventId, parseCalendarEventId, } from "./Calendar.js";
 export { ChatMessageBus } from "./ChatMessageBus.js";
 export { DEFAULT_WRITABLE_PATHS } from "./Config.js";
 export { parseCron } from "./CronExpression.js";
+export { buildNetworkCreateArgs, connectNetwork, dockerCapture, dockerExec, dockerInteractive, ensureNetwork, hostGatewayArgs, ISOLATED_NETWORK_NAME, isContainerRunning, isImagePresent, isNetworkPresent, removeContainer, SHARED_NETWORK_NAME, stopContainer, } from "./DockerTools.js";
 export { EVENT_PRIORITY } from "./Event.js";
 export { DuplicateIdempotencyKeyError, EventBus } from "./EventBus.js";
 export { estimateTokens } from "./estimateTokens.js";
@@ -30,3 +31,4 @@ 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 { DEFAULT_WEBSERVER_HOST, DEFAULT_WEBSERVER_PORT } from "./WebServerDefaults.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getfamiliar/shared",
   "type": "module",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Familiar — shared types and bus-state client between host and container.",
   "publishConfig": {
     "access": "public"