@fastagent-sh/fastagent 0.13.0 → 0.14.0

package/dist/deploy/docker/plan.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `fastagent deploy docker` — the local-Docker plan. The application image stays ingress-neutral:
+ * this target generates only the shared Dockerfile plus a small Compose service for the FastAgent
+ * process, its loopback port, exact environment-variable names, and one persistent state volume.
+ * `--tunnel` can add an ephemeral Cloudflare Quick Tunnel service; durable ingress remains operator-owned.
+ */
+import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import { type Artifact, type ContainerInput } from "../container.ts";
+export interface DockerPlanInput extends ContainerInput {
+    /** Stable Compose project name, sanitized by {@link toDockerProjectName}. */
+    projectName: string;
+    /** Container + default host port. The host binding is loopback-only by default. */
+    port: number;
+    /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
+    modelAuth: string | undefined;
+    /** Known channels contribute their environment-variable names and webhook registration. */
+    channels: ChannelKind[];
+    /** Generate an optional Cloudflare Quick Tunnel service in Compose. Generation only; `--run` starts it. */
+    tunnel: boolean;
+    /** Extra environment-variable names declared in config.deploy.secrets. */
+    extraSecrets?: string[];
+}
+export interface DockerPlan {
+    /** fastagent.compose.yml + the shared Dockerfile/ignore artifacts. */
+    artifacts: Artifact[];
+    /** Compose file path relative to the workspace root (namespaced for agentDir layouts). */
+    composePath: string;
+    /** Ordered local build/run/operate instructions. */
+    runbook: string[];
+}
+export declare const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
+export declare const GENERATED_COMPOSE_MARKER = "# Generated by `fastagent deploy docker`";
+export declare const MIN_DOCKER_COMPOSE_VERSION = "2.3.3";
+/** Pinned: generated deployment artifacts must not silently move when Cloudflare publishes `latest`. */
+export declare const CLOUDFLARED_IMAGE = "cloudflare/cloudflared:2026.7.1";
+/** Whether a Compose file still opts into generated-drift warnings (drop the marker after taking ownership). */
+export declare function isGeneratedCompose(content: string): boolean;
+/** Whether an authoritative Compose file already carries the generated tunnel service contract. */
+export declare function composeHasTunnelService(content: string): boolean;
+/** Compose project names are lowercase [a-z0-9_-] and must start with an alphanumeric character. */
+export declare function toDockerProjectName(directoryName: string): string;
+/** Default first-party webhook paths. Workspace glue may remap them, so guidance labels them defaults. */
+export declare function dockerWebhookPaths(channels: ChannelKind[]): string[];
+/** Compute local-Docker artifacts + the runbook; no Docker process is touched here. */
+export declare function planDockerDeploy(input: DockerPlanInput): DockerPlan;

package/dist/deploy/docker/plan.js

@@ -0,0 +1,139 @@
+import { containerArtifacts } from "../container.js";
+import { deploymentSecrets, isEnvKey } from "../secrets.js";
+const MOUNT = "/data";
+export const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
+export const GENERATED_COMPOSE_MARKER = "# Generated by `fastagent deploy docker`";
+export const MIN_DOCKER_COMPOSE_VERSION = "2.3.3";
+/** Pinned: generated deployment artifacts must not silently move when Cloudflare publishes `latest`. */
+export const CLOUDFLARED_IMAGE = "cloudflare/cloudflared:2026.7.1";
+/** Whether a Compose file still opts into generated-drift warnings (drop the marker after taking ownership). */
+export function isGeneratedCompose(content) {
+    return content.startsWith(GENERATED_COMPOSE_MARKER);
+}
+/** Whether an authoritative Compose file already carries the generated tunnel service contract. */
+export function composeHasTunnelService(content) {
+    return /^[ \t]+tunnel:\s*(?:#.*)?$/m.test(content);
+}
+/** Compose project names are lowercase [a-z0-9_-] and must start with an alphanumeric character. */
+export function toDockerProjectName(directoryName) {
+    const slug = directoryName
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "")
+        .slice(0, 54)
+        .replace(/[-_]+$/g, "");
+    return `fastagent-${slug || "agent"}`;
+}
+/** Default first-party webhook paths. Workspace glue may remap them, so guidance labels them defaults. */
+export function dockerWebhookPaths(channels) {
+    const path = {
+        github: "/webhook",
+        telegram: "/telegram",
+        feishu: "/feishu",
+        lark: "/lark",
+    };
+    return channels.map((kind) => path[kind]);
+}
+/** `${NAME:-}` without making JavaScript treat it as interpolation. */
+function composeInterpolation(name) {
+    return `\${${name}:-}`;
+}
+/** Relative path from the namespaced Compose file's directory back to the workspace/build root. */
+function buildContext(kitDir) {
+    if (!kitDir)
+        return ".";
+    return kitDir
+        .split("/")
+        .map(() => "..")
+        .join("/");
+}
+function composeYaml(input) {
+    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
+    // Always leave the auth-seed seam in the committed topology. `--run` uses it for OAuth/stored auth;
+    // it is empty otherwise. Values never land in this file — Compose interpolates them at invocation.
+    const envNames = [...new Set([...secrets.map((secret) => secret.name), "FASTAGENT_AUTH_SEED"])];
+    const secretEnv = envNames.map((name) => `      ${name}: "${composeInterpolation(name)}"`).join("\n");
+    const context = buildContext(input.kitDir);
+    const dockerfile = input.kitDir ? `${input.kitDir}/Dockerfile` : "Dockerfile";
+    const tunnelService = input.tunnel
+        ? `
+  # Cloudflare Quick Tunnel: ephemeral URL, generated only with \`deploy docker --tunnel\`.
+  # No restart policy on purpose: a new process gets a new URL and needs webhook re-registration.
+  tunnel:
+    image: ${CLOUDFLARED_IMAGE}
+    command:
+      - tunnel
+      - --no-autoupdate
+      - --url
+      - http://agent:${input.port}
+    depends_on:
+      - agent
+    environment:
+      # Docker Desktop may inject HTTP(S)_PROXY into containers. The origin is Docker-internal and must
+      # bypass it; preserve any operator NO_PROXY entries after the required service/loopback names.
+      NO_PROXY: "agent,localhost,127.0.0.1,${composeInterpolation("NO_PROXY")}"
+      no_proxy: "agent,localhost,127.0.0.1,${composeInterpolation("no_proxy")}"
+    restart: "no"
+`
+        : "";
+    return `${GENERATED_COMPOSE_MARKER}. Edit freely — it is kept unless you pass --force.
+# Durable/public ingress remains yours; --tunnel optionally adds an ephemeral Quick Tunnel service.
+name: ${input.projectName}
+
+services:
+  agent:
+    build:
+      context: ${context}
+      dockerfile: ${dockerfile}
+    ports:
+      - "127.0.0.1:${input.port}:${input.port}"
+    environment:
+      PORT: "${input.port}"
+      FASTAGENT_STATE_DIR: "${MOUNT}"
+${secretEnv}
+    volumes:
+      - state:${MOUNT}
+    restart: unless-stopped
+${tunnelService}
+volumes:
+  state:
+`;
+}
+/** Compute local-Docker artifacts + the runbook; no Docker process is touched here. */
+export function planDockerDeploy(input) {
+    const composePath = input.kitDir ? `${input.kitDir}/${DOCKER_COMPOSE_FILE}` : DOCKER_COMPOSE_FILE;
+    const artifacts = [{ path: composePath, content: composeYaml(input) }, ...containerArtifacts(input)];
+    const compose = `docker compose -f ${composePath}`;
+    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
+    const required = secrets.filter((secret) => secret.required);
+    const optional = secrets.filter((secret) => !secret.required);
+    const paths = dockerWebhookPaths(input.channels);
+    const runbook = [
+        `# Run FastAgent in local Docker. ${composePath} / Dockerfile(.dockerignore) are generated above.`,
+        `# Existing artifacts are authoritative and kept; edit Dockerfile or ${composePath} freely.`,
+        `# Prereqs: Docker Engine/Desktop with Compose >= ${MIN_DOCKER_COMPOSE_VERSION} (\`docker compose version\`).`,
+    ];
+    if (required.length > 0) {
+        runbook.push(`# Required environment values (put them in the workspace .env or export them):`, ...required.map((secret) => `#   ${secret.name}: ${secret.hint}`));
+    }
+    if (optional.length > 0) {
+        runbook.push(`# Optional environment values:`, ...optional.map((secret) => `#   ${secret.name}: ${secret.hint}`));
+    }
+    if (!isEnvKey(input.modelAuth)) {
+        runbook.push(input.modelAuth === undefined
+            ? `# Model auth: none found locally — run \`fastagent login\` or set a provider API key before --run.`
+            : `# Model auth: local source is "${input.modelAuth}" — \`--run\` carries auth.json as FASTAGENT_AUTH_SEED.`, `# For a manual Compose run, provide a provider API key or set FASTAGENT_AUTH_SEED yourself.`);
+    }
+    if (input.kitDir) {
+        runbook.push(`# Repo-as-workspace: run from the REPO ROOT. Compose lives under ${input.kitDir}/ but builds`, `# the whole repository; only the kit's dependencies are installed by ${input.kitDir}/Dockerfile.`);
+    }
+    runbook.push(``, `# Build/create/reconcile the service. Re-running this is the complete local redeploy; state stays`, `# in the Compose volume mounted at ${MOUNT}.`, `${compose} up -d --build`, `curl --fail http://127.0.0.1:${input.port}/health`, ``, `# Operate it:`, `${compose} logs -f agent`, `${compose} ps`, `${compose} down        # stops containers; keeps the state volume`, `# ${compose} down -v   # DESTRUCTIVE: also deletes auth, sessions, and channel state`);
+    if (input.tunnel) {
+        runbook.push(``, `# Quick Tunnel: \`--run\` starts the Compose tunnel service and reads its ephemeral public URL.`, `# Detected Telegram/Feishu/Lark channels auto-register; GitHub prints the URL. Re-run after the`, `# tunnel container/Docker daemon restarts: a new Quick Tunnel URL must replace the old webhook URL.`, `${compose} logs -f tunnel`);
+    }
+    else if (paths.length > 0) {
+        runbook.push(``, `# Public ingress is operator-owned: add your tunnel/proxy/DNS/TLS, then configure the`, `# detected default endpoint(s): ${paths.map((path) => `https://<your-domain>${path}`).join(", ")}.`, `# If your channels/*.ts glue remaps a route, use that path instead.`);
+    }
+    runbook.push(`# Keep one agent replica: the local state volume is single-process; multiple replicas split/corrupt state.`);
+    return { artifacts, composePath, runbook };
+}

package/dist/deploy/docker/run.d.ts

@@ -0,0 +1,40 @@
+import type { CliRunner } from "../runner.ts";
+export interface DockerRunPlan {
+    /** Compose file relative to the runner cwd (the workspace root). */
+    composeFile: string;
+    /** Container port from config; used to ask Compose for the effective published host port. */
+    port: number;
+    /** Values interpolated by Compose. Keys/values are passed in the child environment, never argv. */
+    secrets: Record<string, string>;
+    /** Required names with no local value; gate before build/create. */
+    missingSecrets: string[];
+    /** Neither an env-key credential nor a readable auth.json is available. */
+    needsModelCredential: boolean;
+    /** `--tunnel` was requested for this run; a kept Compose file must actually contain that service. */
+    requireTunnel: boolean;
+}
+export type DockerRunOutcome = {
+    ok: true;
+    url?: string;
+    tunnelUrl?: string;
+} | {
+    ok: false;
+    gate: string;
+};
+export type DockerHealthProbe = (healthUrl: string) => Promise<boolean>;
+export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv) => Promise<string | undefined>;
+/** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
+export declare function localUrlFromComposePort(stdout: string): string | undefined;
+/** Poll the detached cloudflared service's logs until its assigned Quick Tunnel URL appears. */
+export declare function waitForComposeTunnelUrl(docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv, options?: {
+    attempts?: number;
+    intervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<string | undefined>;
+/**
+ * Drive Docker Compose. A custom Compose file remains authoritative: the driver invokes it as-is and
+ * only assumes the generated service contract (`agent`, config's container port) for optional URL/
+ * readiness reporting. If the service intentionally has no host-published port, a successful running
+ * service is still success (an operator-owned sidecar/reverse proxy may be its only ingress).
+ */
+export declare function deployDockerRun(plan: DockerRunPlan, docker: CliRunner, log: (message: string) => void, healthProbe?: DockerHealthProbe, tunnelUrlProbe?: DockerTunnelUrlProbe): Promise<DockerRunOutcome>;

package/dist/deploy/docker/run.js

@@ -0,0 +1,126 @@
+/**
+ * `fastagent deploy docker --run` — reconcile the generated/user-owned Compose application locally.
+ * Compose owns container/network/volume lifecycle; this driver owns only actionable gates, secret/auth
+ * carry through the child environment (never argv), and a readiness check on the published loopback port.
+ */
+import { waitForHealth } from "../../channels/wait-health.js";
+import { parseTunnelUrl } from "../../tunnel.js";
+import { MIN_DOCKER_COMPOSE_VERSION } from "./plan.js";
+/** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
+export function localUrlFromComposePort(stdout) {
+    const line = stdout
+        .split("\n")
+        .map((value) => value.trim())
+        .find(Boolean);
+    const port = line?.match(/:(\d+)$/)?.[1];
+    return port ? `http://127.0.0.1:${port}` : undefined;
+}
+const defaultHealthProbe = (healthUrl) => waitForHealth(healthUrl, 30_000, 500);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Poll the detached cloudflared service's logs until its assigned Quick Tunnel URL appears. */
+export async function waitForComposeTunnelUrl(docker, composeFile, env, options = {}) {
+    const compose = ["compose", "-f", composeFile];
+    const attempts = options.attempts ?? 60;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const logs = await docker([...compose, "logs", "--no-color", "tunnel"], { capture: true, env });
+        const url = logs.code === 0 ? parseTunnelUrl(logs.stdout) : undefined;
+        if (url)
+            return url;
+        if (attempt + 1 < attempts)
+            await (options.sleep ?? sleep)(options.intervalMs ?? 500);
+    }
+    return undefined;
+}
+const defaultTunnelUrlProbe = (docker, composeFile, env) => waitForComposeTunnelUrl(docker, composeFile, env);
+/**
+ * Drive Docker Compose. A custom Compose file remains authoritative: the driver invokes it as-is and
+ * only assumes the generated service contract (`agent`, config's container port) for optional URL/
+ * readiness reporting. If the service intentionally has no host-published port, a successful running
+ * service is still success (an operator-owned sidecar/reverse proxy may be its only ingress).
+ */
+export async function deployDockerRun(plan, docker, log, healthProbe = defaultHealthProbe, tunnelUrlProbe = defaultTunnelUrlProbe) {
+    const gate = (message) => ({ ok: false, gate: message });
+    const compose = ["compose", "-f", plan.composeFile];
+    const env = plan.secrets;
+    // CLI/plugin gate first: unlike a daemon error, spawn ENOENT becomes 127 at the shared runner seam.
+    const version = await docker(["compose", "version"], { capture: true });
+    if (version.code === 127) {
+        return gate("Docker CLI not found — install Docker Engine/Desktop, then re-run");
+    }
+    if (version.code !== 0) {
+        return gate("Docker Compose plugin is unavailable — install/enable `docker compose`, then re-run");
+    }
+    // Credential gates precede the first side effect (build/create), with distinct remediation.
+    if (plan.needsModelCredential) {
+        return gate("no model credential — run `fastagent login`, or set a provider API key in .env, then re-run");
+    }
+    if (plan.missingSecrets.length > 0) {
+        return gate(`no local value for: ${plan.missingSecrets.join(", ")} — set them in .env (or the environment) and re-run`);
+    }
+    if ((await docker(["info"], { capture: true })).code !== 0) {
+        return gate("Docker daemon is unavailable — start Docker Engine/Desktop, then re-run");
+    }
+    // The file on disk is authoritative. Inspect its actual services before any build/create side effect,
+    // both to protect the `agent` run contract and to catch `--tunnel` against a kept non-tunnel topology.
+    const configured = await docker([...compose, "config", "--services"], { capture: true, env });
+    if (configured.code !== 0) {
+        return gate(`could not load ${plan.composeFile} — generated files require Docker Compose >= ` +
+            `${MIN_DOCKER_COMPOSE_VERSION}; upgrade Compose or fix the file, then re-run`);
+    }
+    const services = configured.stdout.split(/\s+/).filter(Boolean);
+    if (!services.includes("agent")) {
+        return gate(`Compose file must keep the "agent" service for \`fastagent deploy docker --run\``);
+    }
+    const hasTunnel = services.includes("tunnel");
+    if (plan.requireTunnel && !hasTunnel) {
+        return gate(`--tunnel was requested but the kept ${plan.composeFile} has no "tunnel" service — ` +
+            `edit it, delete it and regenerate, or pass --force`);
+    }
+    // Quick Tunnel logs are the control-plane output (the assigned URL). Remove its old container first so
+    // a rerun cannot read a stale URL from accumulated logs; `up` below creates one fresh tunnel, then the
+    // CLI registers that URL. The app container/volume are untouched.
+    if (hasTunnel) {
+        log("recreating the ephemeral tunnel service…");
+        if ((await docker([...compose, "rm", "-s", "-f", "tunnel"], { env })).code !== 0) {
+            return gate(`could not recreate the tunnel service — inspect \`docker compose -f ${plan.composeFile} ps\``);
+        }
+    }
+    log(`building and reconciling ${plan.composeFile}…`);
+    if ((await docker([...compose, "up", "-d", "--build"], { env })).code !== 0) {
+        return gate(`\`docker compose up\` failed — see the Docker output above; fix ${plan.composeFile} and re-run`);
+    }
+    // Detached `up` can return 0 just before a bad command exits. Verify the expected service is actually
+    // running so a broken custom Dockerfile/CMD cannot look deployed. Compose restart loops are excluded.
+    const running = await docker([...compose, "ps", "--status", "running", "--services"], {
+        capture: true,
+        env,
+    });
+    const runningServices = running.stdout.split(/\s+/).filter(Boolean);
+    if (running.code !== 0 || !runningServices.includes("agent")) {
+        return gate(`the Compose service "agent" is not running — inspect with \`docker compose -f ${plan.composeFile} logs agent\``);
+    }
+    if (hasTunnel && !runningServices.includes("tunnel")) {
+        return gate(`the Compose service "tunnel" is not running — inspect with \`docker compose -f ${plan.composeFile} logs tunnel\``);
+    }
+    // A user-owned topology may deliberately remove the host port and expose only through its own ingress.
+    // In that case Compose `port` is absent/non-zero: service-running is the available readiness floor.
+    const published = await docker([...compose, "port", "agent", String(plan.port)], { capture: true, env });
+    const url = published.code === 0 ? localUrlFromComposePort(published.stdout) : undefined;
+    if (!url) {
+        log("agent is running (no host-published port found; using the Compose ingress readiness floor)");
+    }
+    else {
+        const healthUrl = `${url}/health`;
+        if (!(await healthProbe(healthUrl))) {
+            return gate(`agent did not become healthy at ${healthUrl} — inspect \`docker compose -f ${plan.composeFile} logs agent\``);
+        }
+    }
+    if (!hasTunnel)
+        return { ok: true, url };
+    log("waiting for the Compose tunnel service to publish its Quick Tunnel URL…");
+    const tunnelUrl = await tunnelUrlProbe(docker, plan.composeFile, env);
+    if (!tunnelUrl) {
+        return gate(`tunnel did not publish a Quick Tunnel URL — inspect \`docker compose -f ${plan.composeFile} logs tunnel\``);
+    }
+    return { ok: true, url, tunnelUrl };
+}

package/dist/deploy/preflight.js

@@ -1,6 +1,6 @@
 /**
  * The host-NEUTRAL deploy pre-flight: everything `fastagent deploy <host>` computes and checks BEFORE
- * the host branch (fly.ts / railway.ts). Model-travel gate, channel discovery, model-auth probe, the
+ * the target branch (Docker / Fly / Railway). Model-travel gate, channel discovery, model-auth probe, the
  * container facts + their warnings, and the hand-written-Dockerfile apt warning are identical on every
  * host — so they live here, out of the CLI dispatcher, testable in isolation (call it against a temp dir
  * and assert the gate / messages / facts). The CLI stays thin: run this, print the messages, branch by host.
@@ -68,8 +68,9 @@ export async function preflightDeploy(input) {
     const kitDir = agentDir === target ? undefined : relative(target, agentDir).split(sep).join("/");
     const factsDir = kitDir ? agentDir : target;
     if (kitDir && run) {
-        // Generate + runbook fully support the layout; the fly/railway --run drivers do not yet (their
-        // command sequences assume root artifacts). Fail at the gate, not mid-drive.
+        // The repo-as-workspace deployment shape remains experimental for every target. Generation +
+        // runbook are supported; automated runners stay gated until an explicit end-to-end smoke validates
+        // context packing, ignore rules, installed deps, state, and write-back for this layout.
         return {
             ok: false,
             gate: `--run is not yet supported for the agentDir layout — run the same deploy without --run and follow the printed runbook`,

package/dist/deploy/runner.d.ts

@@ -5,10 +5,13 @@ export interface RunResult {
     stdout: string;
 }
 /** Run `bin args`: `capture` collects stdout (for `--json` queries), else the command streams to the
- *  terminal (create/deploy) and stdout is empty; `input` is fed to stdin (secrets over stdin, never argv). */
+ *  terminal (create/deploy) and stdout is empty; `input` is fed to stdin (secrets over stdin, never argv).
+ *  `env` adds child-only environment values — Docker Compose interpolates secrets from it without putting
+ *  values in argv or mutating the long-lived CLI process. */
 export type CliRunner = (args: string[], opts?: {
     capture?: boolean;
     input?: string;
+    env?: NodeJS.ProcessEnv;
 }) => Promise<RunResult>;
 /**
  * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the

package/dist/deploy/runner.js

@@ -13,6 +13,7 @@ export function spawnRunner(bin, cwd) {
     return (args, opts) => new Promise((res) => {
         const child = spawn(bin, args, {
             cwd,
+            env: opts?.env ? { ...process.env, ...opts.env } : process.env,
             stdio: [opts?.input ? "pipe" : "inherit", opts?.capture ? "pipe" : "inherit", "inherit"],
         });
         let out = "";