@fastagent-sh/fastagent 0.20.0 → 0.21.0

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,25 +1,21 @@
-/** The deploy targets, as a value: {@link HOST_ONLY_FLAGS} is checked against this list by a test, and
- *  a type alone cannot be enumerated at runtime. NOT the only copy — `cli/program.ts` repeats it as the
- *  `<host>` argument's `choices`, because that file may not import a command module at load time (its
- *  per-command imports are lazy). Adding a host means editing both; the type there rides in on a
- *  `import type`, which costs nothing at runtime. */
-export declare const DEPLOY_HOSTS: readonly ["docker", "fly", "railway", "agentcore"];
-export type DeployHost = (typeof DEPLOY_HOSTS)[number];
-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 {@link DEPLOY_HOSTS} cannot silently lose its line. */
+ *  non-owners, so a host added to `DEPLOY_HOSTS` cannot silently lose its line. */
 interface HostOnlyFlag<Owner extends DeployHost> {
     flag: string;
     owner: Owner;
@@ -43,31 +39,3 @@ export declare const HOST_ONLY_FLAGS: (HostOnlyFlag<"fly"> | HostOnlyFlag<"railw
  *  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>;
-/**
- * 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[];
-}): Promise<void>;
-export {};