@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/cli/commands/deploy/fly.js

@@ -0,0 +1,131 @@
+/**
+ * `deploy fly`: fly.toml + a state volume. KEEP (no --force): an existing fly.toml is authoritative;
+ * --force: the template is. `--run` drives flyctl to completion (idempotent, resumable).
+ */
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { isGeneratedFlyToml, parseFlyAppName, parseFlyMinMachines, parseFlyRegion, planFlyDeploy, toFlyAppName, } from "../../../deploy/fly/plan.js";
+import { deployFlyRun } from "../../../deploy/fly/run.js";
+import { spawnRunner } from "../../../deploy/runner.js";
+import { readTextIfExists } from "../../../paths.js";
+import { failStartup } from "../../fail.js";
+import { carryCredentials, gateOnModelCredential, registrarsFor } from "./shared.js";
+export const flyHost = {
+    isOurs: (path, content) => path.endsWith("fly.toml") && isGeneratedFlyToml(content),
+    async deploy(ctx) {
+        const { opts, agentDir, workspace, channels, longConnectionChannels, pre, write } = ctx;
+        const { hasTimeTriggers, modelAuth, modelKeyInDefinition, authPath, container, port, extraSecrets } = pre;
+        // The replay floor that makes scale-to-zero safe is Telegram-only (its L1 turn store). GitHub turns
+        // are fire-and-forget (no replay), so the generated fly.toml keeps one machine running for them —
+        // a note, not a warn, since the plan already did the safe thing (definition-aware autostop).
+        if (channels.some((channel) => channel.name === "github")) {
+            console.error(`[fastagent] note: github turns have no replay — the generated fly.toml uses min_machines_running=1 ` +
+                `(no scale-to-zero) so autostop can't drop an in-flight review. Set it to 0 to accept that trade.`);
+        }
+        // Two consistent modes. KEEP (no --force): an existing fly.toml is authoritative — not rewritten,
+        // and the runbook reads its `app=` (Fly app names are globally unique, so the basename guess may be
+        // taken and the user renamed it). --force: the template is authoritative — the WHOLE fly.toml resets
+        // (app→basename, region→iad, vm→defaults), so we do NOT round-trip `app` and warn that hand edits go.
+        // fly.toml lives in the agent dir (fastagent/fly.toml) — the workspace's own
+        // fly.toml (if any) belongs to the host's product deploy and is never read or written here.
+        const flyTomlPath = join(agentDir, "fly.toml");
+        const flyToml = await readTextIfExists(flyTomlPath).catch(failStartup);
+        // Every decision below turns on ONE question — will `writeArtifacts` keep this file? — and the answer is
+        // OWNERSHIP, not the flag: `--force` resets a fly.toml we generated and leaves a hand-written one alone.
+        // Keying these on `--force` alone meant a forced deploy of a hand-owned fly.toml took the app name from
+        // the directory basename (shipping that file at a DIFFERENT app than it declares) and skipped the
+        // scale-to-zero gate below (a schedules deploy that silently sleeps). Read once, decide once.
+        const flyTomlKept = flyToml !== undefined && (!opts.force || !isGeneratedFlyToml(flyToml));
+        const keptApp = flyTomlKept ? parseFlyAppName(flyToml) : undefined;
+        const appName = keptApp ?? toFlyAppName(basename(workspace));
+        if (keptApp)
+            console.error(`[fastagent] app: ${keptApp} (from fly.toml)`);
+        if (flyToml !== undefined && !flyTomlKept) {
+            console.error(`[fastagent] warn: --force resets fly.toml to defaults (app, region, vm) — re-apply any hand edits`);
+        }
+        // Autostop flags shape the GENERATED fly.toml only. In KEEP mode (fly.toml exists, no --force) it is
+        // not rewritten, so the flags would silently do nothing — surface that instead of a confusing no-op.
+        if (flyTomlKept && (opts.stop || opts.scaleToZero === false)) {
+            console.error(`[fastagent] warn: --stop/--no-scale-to-zero only shape a freshly generated fly.toml — yours exists and ` +
+                `was kept. Edit auto_stop_machines/min_machines_running in fly.toml, or pass --force to regenerate.`);
+        }
+        // KEEP mode + time triggers: the kept fly.toml may still scale to zero — which would sleep through every
+        // cron instant / wake-up. The generated plan can't fix a kept file, so surface it instead of the preflight
+        // note silently not applying (the author who deployed FIRST and added schedules LATER hits exactly this).
+        // Under `--run` this is a GATE (same discipline as the model-travel gate): a full deploy whose schedules
+        // silently never fire is worse than a crash-loop — nothing fails visibly when a cron instant passes on a
+        // sleeping machine, and unlike github's min=0 there is no legitimate trade to accept here.
+        if (flyTomlKept && (hasTimeTriggers || longConnectionChannels.length > 0)) {
+            const min = parseFlyMinMachines(flyToml);
+            if ((min ?? 0) === 0) {
+                // undefined = the line is absent — Fly's platform default for min_machines_running is 0, so a
+                // hand-written fly.toml without the line scales to zero exactly like an explicit 0.
+                const reason = hasTimeTriggers
+                    ? `schedules/self-scheduling need a running machine (no external wake-up)`
+                    : `long-connection channel (${longConnectionChannels.map((c) => c.name).join(", ")}) needs an always-on outbound connection`;
+                const msg = `your kept fly.toml scales to zero (min_machines_running = ${min ?? "absent → platform default 0"}), but ` +
+                    `${reason}. Set min_machines_running = 1, or pass --force to regenerate.`;
+                if (opts.run)
+                    failStartup(new Error(`deploy stopped: ${msg}`));
+                console.error(`[fastagent] warn: ${msg}`);
+            }
+        }
+        const plan = planFlyDeploy({
+            appName,
+            port,
+            modelAuth,
+            channels,
+            extraSecrets,
+            hasTimeTriggers,
+            ...container,
+            autostop: opts.stop ? "stop" : "suspend",
+            scaleToZero: opts.scaleToZero !== false,
+        });
+        await write(plan.artifacts, { force: !!opts.force });
+        if (opts.run) {
+            return runDeployFly({
+                agentDir,
+                workspace,
+                agentPrefix: container.agentPrefix,
+                appName,
+                modelAuth,
+                modelKeyInDefinition,
+                authPath,
+                channels,
+                flyTomlPath,
+                extraSecrets,
+            });
+        }
+        console.log(plan.runbook.join("\n"));
+    },
+};
+/**
+ * `deploy fly --run`: drive flyctl to completion (idempotent, resumable). Gathers the secret VALUES
+ * from the local env — the model key (env auth) or the whole auth.json as a `FASTAGENT_AUTH_SEED` seed
+ * (OAuth/stored auth: the deployed box materializes it onto the /data volume on first boot, so a
+ * personal deploy runs on the SAME subscription) plus channel secrets — then runs the flyctl steps
+ * behind the shared {@link spawnRunner} seam (spawned `fly`, cwd = the workspace so the build context is the whole workspace).
+ */
+async function runDeployFly(params) {
+    const { agentDir, workspace, agentPrefix, appName, channels, flyTomlPath } = params;
+    const fly = spawnRunner("fly", workspace);
+    // Fail fast if flyctl is absent (spawn ENOENT → 127), with the install link — not a confusing auth gate.
+    if ((await fly(["version"], { capture: true })).code === 127) {
+        failStartup(new Error(`flyctl not found — install it: https://fly.io/docs/flyctl/install, then re-run`));
+    }
+    const region = parseFlyRegion(await readFile(flyTomlPath, "utf8")) ?? "iad";
+    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
+    gateOnModelCredential(needsModelCredential);
+    const outcome = await deployFlyRun({
+        appName,
+        region,
+        secrets,
+        missingSecrets,
+        channels,
+        flyConfig: `${agentPrefix}fly.toml`,
+        dockerfile: `${agentPrefix}Dockerfile`,
+    }, fly, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir));
+    if (!outcome.ok)
+        failStartup(new Error(`deploy stopped: ${outcome.gate}`));
+    console.error(`[fastagent] deployed → https://${appName}.fly.dev`);
+}

package/dist/cli/commands/deploy/railway.d.ts

@@ -0,0 +1,2 @@
+import { type HostDeploy } from "./shared.ts";
+export declare const railwayHost: HostDeploy;

package/dist/cli/commands/deploy/railway.js

@@ -0,0 +1,71 @@
+/**
+ * `deploy railway`: a thin config file, scale-to-zero is a manual dashboard step, the URL is minted
+ * (see planRailwayDeploy). `--run` drives the railway CLI to completion; otherwise print the runbook.
+ */
+import { basename } from "node:path";
+import { dockerfilePathVar, isGeneratedRailwayJson, planRailwayDeploy, toRailwayName, } from "../../../deploy/railway/plan.js";
+import { deployRailwayRun } from "../../../deploy/railway/run.js";
+import { spawnRunner } from "../../../deploy/runner.js";
+import { failStartup } from "../../fail.js";
+import { carryCredentials, gateOnModelCredential, registrarsFor } from "./shared.js";
+export const railwayHost = {
+    isOurs: (path, content) => path.endsWith("railway.json") && isGeneratedRailwayJson(content),
+    async deploy(ctx) {
+        const { opts, agentDir, workspace, pre, channels, write } = ctx;
+        const { hasTimeTriggers, modelAuth, modelKeyInDefinition, authPath, container, extraSecrets } = pre;
+        const serviceName = toRailwayName(basename(workspace));
+        const plan = planRailwayDeploy({
+            serviceName,
+            modelAuth,
+            channels,
+            extraSecrets,
+            hasTimeTriggers,
+            ...container,
+        });
+        await write(plan.artifacts, { force: !!opts.force });
+        if (opts.run) {
+            // The BUILD entry is guaranteed by the RAILWAY_DOCKERFILE_PATH service variable the runner sets
+            // (Railway's documented non-root-Dockerfile route), and Railway's default restart policy already
+            // equals the file's ON_FAILURE — the dashboard-only Config-as-code pointer only adds the /health
+            // deploy gate (boot-crash visibility), so it is an OPTIONAL note, not a gate.
+            console.error(`[fastagent] note: optional — point the service at fastagent/railway.json (Service → Settings → ` +
+                `Config-as-code, dashboard-only) so the /health healthcheck marks a boot-crashing deploy as FAILED; ` +
+                `the build already uses fastagent/Dockerfile via the RAILWAY_DOCKERFILE_PATH variable`);
+            return runDeployRailway({
+                agentDir,
+                workspace,
+                name: serviceName,
+                modelAuth,
+                modelKeyInDefinition,
+                authPath,
+                channels,
+                extraSecrets,
+                intoLinked: !!opts.intoLinked,
+                dockerfilePath: dockerfilePathVar(pre.container.agentPrefix),
+            });
+        }
+        console.log(plan.runbook.join("\n"));
+        return;
+    },
+};
+/**
+ * `deploy railway --run`: drive the railway CLI to completion. Mirrors the fly driver — same
+ * credential carry (env key OR the OAuth auth.json as `FASTAGENT_AUTH_SEED`) via {@link carryCredentials},
+ * same runner seam (spawned `railway`, cwd = the workspace so `railway up`'s upload is the whole workspace). The
+ * Railway-specific sequence (linked-check → init/add/volume when fresh → variables → up → domain →
+ * webhook) lives in {@link deployRailwayRun}; see there for why Railway differs from Fly.
+ */
+async function runDeployRailway(params) {
+    const { agentDir, workspace, name, channels, intoLinked, dockerfilePath } = params;
+    const railway = spawnRunner("railway", workspace);
+    // Fail fast if the railway CLI is absent (spawn ENOENT → 127), with the install link.
+    if ((await railway(["--version"], { capture: true })).code === 127) {
+        failStartup(new Error(`railway CLI not found — install it: https://docs.railway.com/guides/cli, then re-run`));
+    }
+    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
+    gateOnModelCredential(needsModelCredential);
+    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, intoLinked, dockerfilePath }, railway, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir));
+    if (!outcome.ok)
+        failStartup(new Error(`deploy stopped: ${outcome.gate}`));
+    console.error(`[fastagent] deployed → ${outcome.url}`);
+}

package/dist/cli/commands/deploy/shared.d.ts

@@ -0,0 +1,114 @@
+import type { DeclaredChannel } from "../../../channels/discover.ts";
+import type { Registrars } from "../../../deploy/channel-ingress.ts";
+import type { DeployPreflight } from "../../../deploy/preflight.ts";
+import type { FastagentConfig } from "../../../engines/pi/config.ts";
+export interface DeployOptions {
+    run?: boolean;
+    tunnel?: boolean;
+    force?: boolean;
+    stop?: boolean;
+    /** false ⇔ `--no-scale-to-zero`. */
+    scaleToZero?: boolean;
+    intoLinked?: boolean;
+    model?: string;
+    authPath?: string;
+    /** false ⇔ `--no-input`. */
+    input?: boolean;
+}
+/** What the dispatcher resolved before handing off: the placement, the flags, the config and the
+ *  host-neutral pre-flight, plus the channel lists every host asks about. */
+interface DeployContext {
+    opts: DeployOptions;
+    agentDir: string;
+    workspace: string;
+    config: FastagentConfig;
+    pre: Extract<DeployPreflight, {
+        ok: true;
+    }>;
+    channels: readonly DeclaredChannel[];
+    webhookChannels: readonly DeclaredChannel[];
+    longConnectionChannels: readonly DeclaredChannel[];
+    /** Write this host's planned artifacts into the workspace under the ownership rule. The dispatcher
+     *  binds {@link HostDeploy.isOurs} — a host cannot name a predicate here, because every host's has
+     *  the same type: passing a neighbour's, or forgetting a new host's, type-checks and then silently
+     *  turns `--force` into a no-op for that host's own artifact. */
+    write(artifacts: {
+        path: string;
+        content: string;
+    }[], options: {
+        force: boolean;
+        alwaysWrite?: string[];
+    }): Promise<void>;
+}
+/** One deploy target, as the dispatcher sees it. A new host is a `deploy/<host>/` (plan + driver)
+ *  plus one of these beside it, and a row in `HOSTS` (cli/commands/deploy.ts). */
+export interface HostDeploy {
+    /** Did this host generate the file at `path`? Only the host's OWN artifacts — the container's
+     *  (Dockerfile, .dockerignore) are answered by {@link writeArtifacts} itself. Read only through the
+     *  {@link DeployContext.write} the dispatcher binds from it. */
+    isOurs(path: string, content: string): boolean;
+    /** Plan the artifacts from the pre-flight facts and what is on disk, write them, then either drive
+     *  the host CLI (`--run`) or print the runbook. Exits through `failStartup` on a gate. */
+    deploy(ctx: DeployContext): Promise<void>;
+}
+/** The registrars every host driver gets. One wiring: a channel's credentials are the channel's, not
+ *  the host's, so which of them can run end-to-end never varies by deployment target.
+ *
+ *  All three get {@link DEPLOY_REGISTRATION_ATTEMPTS} rather than the default: a host CLI returns
+ *  before the deployment answers, and a registration that gives up first GATES the deploy — reporting
+ *  a working deployment as one to re-run. `dev --tunnel` keeps the shorter default; it is a resident
+ *  process whose URL is live when it is printed, as does `deploy docker --run` — it reuses that same
+ *  announcer, having already health-probed the container and waited for the Quick Tunnel URL.
+ *
+ *  Accepted cost: pointChannelsAt registers serially, so a deployment whose channels are ALL
+ *  unreachable spends the budget once per channel (3 x 180s) before it gates. Registering in parallel
+ *  would not shorten a single failing channel, and the failing case is the one nobody is waiting on. */
+export declare function registrarsFor(agentDir: string): Registrars;
+/**
+ * The `--run` credential carry, for every host: the local model credential (an env key, or the whole
+ * auth.json as a `FASTAGENT_AUTH_SEED`) plus channel secrets. Four drivers assembled this identically.
+ */
+export declare function carryCredentials(params: {
+    modelAuth: string | undefined;
+    modelKeyInDefinition: boolean;
+    authPath: string;
+    channels: readonly DeclaredChannel[];
+    extraSecrets: string[];
+}): Promise<{
+    secrets: Record<string, string>;
+    missingSecrets: string[];
+    needsModelCredential: boolean;
+}>;
+/** Gate a `--run` that has no model credential to carry. Its remediation is `fastagent login`, which
+ *  is why it is separate from `missingSecrets` (a `.env` fix) rather than folded into it. Docker states
+ *  the same gate inside its driver, where it belongs after the daemon check. */
+export declare function gateOnModelCredential(needsModelCredential: boolean): void;
+/**
+ * Write each generated artifact under `target`, under ONE ownership rule: **deploy only ever overwrites
+ * its own output.** Each generated file opens with a marker, so a file on disk is either OURS (a previous
+ * `deploy` wrote it) or the author's — and `--force` means "my generated artifact is authoritative",
+ * which never licenses clobbering a file we did not write. To hand a path back to fastagent, delete it.
+ *
+ * That single rule replaced a second mechanism (a per-host list of paths exempt from `--force`), which
+ * only described one shape: with the agent inside the workspace, the root `.dockerignore` is the
+ * WORKSPACE's file and was listed; with the agent flat, the list was empty — so `--force` would have
+ * overwritten a hand-written root `Dockerfile` in a repository `init --flat` had explicitly adopted.
+ * Ownership is a property of the file, not of where the agent sits.
+ *
+ * A KEPT file of OURS that no longer matches what deploy would generate now (config/channel/lockfile/
+ * version drift — or the author's edits, which we cannot tell apart) is flagged stale; `--force`
+ * regenerates that one.
+ *
+ * Exported for its own test — this is a four-branch state machine over (exists, ours, force) that used
+ * to be proven by spawning the CLI eight times, which is command LOGIC re-run through a subprocess
+ * (see vitest.config.ts) and the suite's slowest test.
+ */
+export declare function writeArtifacts(target: string, artifacts: {
+    path: string;
+    content: string;
+}[], options: {
+    force: boolean;
+    alwaysWrite?: string[];
+    isOurs: HostDeploy["isOurs"];
+}): Promise<void>;
+export {};

package/dist/cli/commands/deploy/shared.js

@@ -0,0 +1,124 @@
+/**
+ * What every host's deploy command shares: the context the dispatcher hands a host, the artifact
+ * writer with its ownership rule, and the `--run` credential carry. Host facts live in
+ * `cli/commands/deploy/<host>.ts`; this file holds nothing that names one.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { registerFeishuWebhook } from "../../../channels/feishu/register-webhook.js";
+import { DEPLOY_REGISTRATION_ATTEMPTS } from "../../../channels/registration.js";
+import { registerSlackWebhook } from "../../../channels/slack/register-webhook.js";
+import { registerTelegramWebhook } from "../../../channels/telegram/register-webhook.js";
+import { isGeneratedDockerfile, isGeneratedDockerignore } from "../../../deploy/container.js";
+import { assembleSecrets } from "../../../deploy/secrets.js";
+import { exists, resolveStateRoot } from "../../../paths.js";
+import { failStartup } from "../../fail.js";
+/** The registrars every host driver gets. One wiring: a channel's credentials are the channel's, not
+ *  the host's, so which of them can run end-to-end never varies by deployment target.
+ *
+ *  All three get {@link DEPLOY_REGISTRATION_ATTEMPTS} rather than the default: a host CLI returns
+ *  before the deployment answers, and a registration that gives up first GATES the deploy — reporting
+ *  a working deployment as one to re-run. `dev --tunnel` keeps the shorter default; it is a resident
+ *  process whose URL is live when it is printed, as does `deploy docker --run` — it reuses that same
+ *  announcer, having already health-probed the container and waited for the Quick Tunnel URL.
+ *
+ *  Accepted cost: pointChannelsAt registers serially, so a deployment whose channels are ALL
+ *  unreachable spends the budget once per channel (3 x 180s) before it gates. Registering in parallel
+ *  would not shorten a single failing channel, and the failing case is the one nobody is waiting on. */
+export function registrarsFor(agentDir) {
+    const attempts = DEPLOY_REGISTRATION_ATTEMPTS;
+    return {
+        telegram: (baseUrl) => registerTelegramWebhook(baseUrl, { attempts }),
+        slack: (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(agentDir), attempts }),
+        feishu: (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind, { attempts }),
+    };
+}
+/**
+ * The `--run` credential carry, for every host: the local model credential (an env key, or the whole
+ * auth.json as a `FASTAGENT_AUTH_SEED`) plus channel secrets. Four drivers assembled this identically.
+ */
+export async function carryCredentials(params) {
+    const { modelAuth, modelKeyInDefinition, authPath, channels, extraSecrets } = params;
+    return assembleSecrets({
+        modelAuth,
+        modelKeyInDefinition,
+        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
+        channels,
+        extraSecrets,
+        env: process.env,
+    });
+}
+/** Gate a `--run` that has no model credential to carry. Its remediation is `fastagent login`, which
+ *  is why it is separate from `missingSecrets` (a `.env` fix) rather than folded into it. Docker states
+ *  the same gate inside its driver, where it belongs after the daemon check. */
+export function gateOnModelCredential(needsModelCredential) {
+    if (!needsModelCredential)
+        return;
+    failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
+}
+/**
+ * Write each generated artifact under `target`, under ONE ownership rule: **deploy only ever overwrites
+ * its own output.** Each generated file opens with a marker, so a file on disk is either OURS (a previous
+ * `deploy` wrote it) or the author's — and `--force` means "my generated artifact is authoritative",
+ * which never licenses clobbering a file we did not write. To hand a path back to fastagent, delete it.
+ *
+ * That single rule replaced a second mechanism (a per-host list of paths exempt from `--force`), which
+ * only described one shape: with the agent inside the workspace, the root `.dockerignore` is the
+ * WORKSPACE's file and was listed; with the agent flat, the list was empty — so `--force` would have
+ * overwritten a hand-written root `Dockerfile` in a repository `init --flat` had explicitly adopted.
+ * Ownership is a property of the file, not of where the agent sits.
+ *
+ * A KEPT file of OURS that no longer matches what deploy would generate now (config/channel/lockfile/
+ * version drift — or the author's edits, which we cannot tell apart) is flagged stale; `--force`
+ * regenerates that one.
+ *
+ * Exported for its own test — this is a four-branch state machine over (exists, ours, force) that used
+ * to be proven by spawning the CLI eight times, which is command LOGIC re-run through a subprocess
+ * (see vitest.config.ts) and the suite's slowest test.
+ */
+export async function writeArtifacts(target, artifacts, options) {
+    for (const a of artifacts) {
+        const abs = join(target, a.path);
+        // Pure build output, not operator-owned configuration. It must track the generated template/runbook.
+        if (options.alwaysWrite?.includes(a.path)) {
+            await mkdir(dirname(abs), { recursive: true });
+            await writeFile(abs, a.content);
+            console.error(`[fastagent] wrote ${a.path}`);
+            continue;
+        }
+        const existing = (await exists(abs)) ? await readFile(abs, "utf8") : undefined;
+        const ours = existing !== undefined && isOurArtifact(a.path, existing, options.isOurs);
+        if (existing !== undefined && !ours) {
+            // Only the `.dockerignore` has content checks in preflight — pointing at "the preflight warnings"
+            // for the other kinds would send the reader looking for output that is never printed.
+            console.error(`[fastagent] kept ${a.path} — not generated by fastagent, so --force does not touch it ` +
+                `(delete it to let deploy own the path)` +
+                (a.path.endsWith(".dockerignore")
+                    ? `; see the preflight warnings for what it must exclude`
+                    : a.path.endsWith("Dockerfile")
+                        ? `; deploy still assumes it listens on $PORT and runs \`fastagent start /app\``
+                        : ``));
+            continue;
+        }
+        if (existing !== undefined && !options.force) {
+            console.error(existing !== a.content
+                ? `[fastagent] kept ${a.path} — it no longer matches what deploy would generate (config changed, or ` +
+                    `you edited it); pass --force to regenerate.`
+                : `[fastagent] kept ${a.path} (unchanged)`);
+            continue;
+        }
+        await mkdir(dirname(abs), { recursive: true }); // artifacts live under fastagent/
+        await writeFile(abs, a.content);
+        console.error(`[fastagent] wrote ${a.path}`);
+    }
+}
+/** Did fastagent generate the file at `path`? The container's two artifacts are every host's; the
+ *  rest is the host's own answer. A kind neither names is permanently classified as the author's,
+ *  which silently turns `--force` into a no-op for that file. */
+function isOurArtifact(path, content, host) {
+    if (path.endsWith("Dockerfile"))
+        return isGeneratedDockerfile(content);
+    if (path.endsWith(".dockerignore"))
+        return isGeneratedDockerignore(content);
+    return host(path, content);
+}

package/dist/cli/commands/deploy.d.ts

@@ -1,28 +1,41 @@
-export type DeployHost = "docker" | "fly" | "railway" | "agentcore";
-export interface DeployOptions {
-    run?: boolean;
-    tunnel?: boolean;
-    force?: boolean;
-    stop?: boolean;
-    /** false ⇔ `--no-scale-to-zero`. */
-    scaleToZero?: boolean;
-    intoLinked?: boolean;
-    model?: string;
-    authPath?: string;
-    /** false ⇔ `--no-input`. */
-    input?: boolean;
+/**
+ * `fastagent deploy <host> [dir]`: generate host artifacts from the resolved definition and print an
+ * ordered deploy runbook. Host-scoped (`docker` | `fly` | `railway` — the extension seam). It does NOT
+ * run the host CLI by default: fastagent owns the definition-aware artifacts and precise runbook;
+ * Docker may opt into a generated ephemeral tunnel, while durable ingress stays operator-owned. The pre-flight
+ * (config/model/channels/container facts) is host-neutral; each host's module (`./deploy/<host>.ts`)
+ * adds its artifacts, its kept-file semantics, its gates and its `--run` drive over the neutral
+ * `deploy/<host>/` plan + driver. Read-only on the definition; the only writes are generated
+ * artifacts (never clobbered without --force). `--run` drives the target CLI instead of printing.
+ */
+import type { DeployHost } from "../../deploy/hosts.ts";
+import { type DeployOptions, type HostDeploy, writeArtifacts } from "./deploy/shared.ts";
+export { writeArtifacts };
+/** Every host, by the name the CLI takes. Typed over {@link DeployHost} so a host added to the list
+ *  without a module here fails to compile. */
+export declare const HOSTS: Record<DeployHost, HostDeploy>;
+/** A flag exactly one host honours, and what the OTHERS do instead. `instead` is exhaustive over the
+ *  non-owners, so a host added to `DEPLOY_HOSTS` cannot silently lose its line. */
+interface HostOnlyFlag<Owner extends DeployHost> {
+    flag: string;
+    owner: Owner;
+    passed: (opts: DeployOptions) => boolean;
+    instead: Record<Exclude<DeployHost, Owner>, string>;
 }
-export declare function runDeploy(host: DeployHost, dirArg: string, opts: DeployOptions): Promise<void>;
 /**
- * Write the plan's artifacts under `target`, honouring the ownership rule: a file we did not generate is
- * never touched, ours is kept unless `--force`. Exported for its own test — this is a four-branch state
- * machine over (exists, ours, force) that used to be proven by spawning the CLI eight times, which is
- * command LOGIC re-run through a subprocess (see vitest.config.ts) and the suite's slowest test.
+ * ONE table for "this flag belongs to that host", because the fact is symmetric and was not stored
+ * that way: each host branch stated the OTHER hosts' flags in its own words, so the same sentence
+ * existed three times per flag and had already drifted (`Railway-only` twice, `railway-only` once).
+ *
+ * Every row is a flag that only WARNS elsewhere. `--tunnel` is host-only too and is deliberately not
+ * here: it is a usage GATE (`failUsage`, exit 2) raised in `runDeploy`, not a warning — moving it in
+ * would downgrade a refusal to a line of advice.
+ *
+ * Exported for the exhaustiveness test: the type stops a missing `instead` line, and the test stops it
+ * from being typed away.
  */
-export declare function writeArtifacts(target: string, artifacts: {
-    path: string;
-    content: string;
-}[], options: {
-    force: boolean;
-    alwaysWrite?: string[];
-}): Promise<void>;
+export declare const HOST_ONLY_FLAGS: (HostOnlyFlag<"fly"> | HostOnlyFlag<"railway">)[];
+/** Exported for its own test: nothing covered these six sentences, which is how three of them came to
+ *  disagree about the spelling of a host name. */
+export declare function warnHostOnlyFlags(host: DeployHost, opts: DeployOptions): void;
+export declare function runDeploy(host: DeployHost, dirArg: string, opts: DeployOptions): Promise<void>;