@fastagent-sh/fastagent 0.12.0

package/dist/tunnel.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `--tunnel`: expose the local dev server on a public HTTPS URL via a Cloudflare quick tunnel, then
+ * auto-register the first-party webhook channels against it (telegram setWebhook; github prints the
+ * URL to paste into repo settings). This closes the "local dev → public URL" gap webhooks need.
+ *
+ * Process orchestration, not assembly — lives outside the engine, beside dev-supervisor.ts.
+ */
+import { type ChildProcess } from "node:child_process";
+export interface Tunnel {
+    url: string;
+    close(): void;
+}
+/** Extract a Cloudflare quick-tunnel URL from a chunk of cloudflared output, if present. */
+export declare function parseTunnelUrl(chunk: string): string | undefined;
+/** How cloudflared is launched; injectable so tests can drive the child without a real process. */
+type SpawnCloudflared = (port: number) => ChildProcess;
+/**
+ * Start a Cloudflare quick tunnel to localhost:`port`, resolving once its public URL appears.
+ * cloudflared sometimes exits before printing a URL (a transient trycloudflare API error), so retry a
+ * few times. ALWAYS resolves to undefined WITH an operator log saying why — missing binary, the exit
+ * reason, or "gave up after retries" — never silently; serving continues without a tunnel either way.
+ * (Edge warmup AFTER the URL appears is handled downstream: the telegram registrar polls /health before
+ * it calls setWebhook, so a not-yet-routable tunnel just delays registration rather than failing it.)
+ */
+export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloudflared): Promise<Tunnel | undefined>;
+/**
+ * Print the public URL and wire up the first-party webhook channels found under `dir`: telegram is
+ * auto-registered via setWebhook (using .env tokens); github prints the URL to add in repo settings.
+ */
+export declare function announceWebhooks(dir: string, baseUrl: string): Promise<void>;
+export {};

package/dist/tunnel.js

@@ -0,0 +1,139 @@
+/**
+ * `--tunnel`: expose the local dev server on a public HTTPS URL via a Cloudflare quick tunnel, then
+ * auto-register the first-party webhook channels against it (telegram setWebhook; github prints the
+ * URL to paste into repo settings). This closes the "local dev → public URL" gap webhooks need.
+ *
+ * Process orchestration, not assembly — lives outside the engine, beside dev-supervisor.ts.
+ */
+import { spawn } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { registerTelegramWebhook } from "./channels/telegram/register-webhook.js";
+import { loadDotEnv } from "./env.js";
+import { log } from "./log.js";
+// `(?!api\.)`: cloudflared's ERROR lines mention its request endpoint (`https://api.trycloudflare.com/tunnel`,
+// e.g. "failed to request quick Tunnel: Post ... timeout" under a flaky proxy) — without the exclusion a
+// transient error line parses as the assigned URL and the webhook gets registered against Cloudflare's
+// API host instead of the tunnel.
+const TUNNEL_URL_RE = /https:\/\/(?!api\.)[a-z0-9-]+\.trycloudflare\.com/i;
+/** Extract a Cloudflare quick-tunnel URL from a chunk of cloudflared output, if present. */
+export function parseTunnelUrl(chunk) {
+    return chunk.match(TUNNEL_URL_RE)?.[0];
+}
+const TUNNEL_ATTEMPTS = 3;
+const TUNNEL_RETRY_MS = 2000;
+const spawnCloudflared = (port) => spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], { stdio: ["ignore", "pipe", "pipe"] });
+/**
+ * Start a Cloudflare quick tunnel to localhost:`port`, resolving once its public URL appears.
+ * cloudflared sometimes exits before printing a URL (a transient trycloudflare API error), so retry a
+ * few times. ALWAYS resolves to undefined WITH an operator log saying why — missing binary, the exit
+ * reason, or "gave up after retries" — never silently; serving continues without a tunnel either way.
+ * (Edge warmup AFTER the URL appears is handled downstream: the telegram registrar polls /health before
+ * it calls setWebhook, so a not-yet-routable tunnel just delays registration rather than failing it.)
+ */
+export async function startCloudflareTunnel(port, spawnFn = spawnCloudflared) {
+    for (let attempt = 1; attempt <= TUNNEL_ATTEMPTS; attempt++) {
+        const r = await spawnTunnelOnce(port, spawnFn);
+        if (r.tunnel)
+            return r.tunnel;
+        if (r.fatal) {
+            log.error(r.message); // missing binary — retrying cannot help
+            return undefined;
+        }
+        const more = attempt < TUNNEL_ATTEMPTS;
+        log.warn(`[fastagent] --tunnel: cloudflared exited before a public URL appeared${r.detail ? ` (${r.detail})` : ""}` +
+            (more ? ` — retrying (${attempt}/${TUNNEL_ATTEMPTS - 1})…` : ". Serving without a tunnel."));
+        if (more)
+            await sleep(TUNNEL_RETRY_MS);
+    }
+    return undefined;
+}
+/** One cloudflared launch: a Tunnel on the first URL, or a failure (missing binary / exit before a URL). */
+function spawnTunnelOnce(port, spawnFn) {
+    return new Promise((resolve) => {
+        const child = spawnFn(port);
+        let settled = false;
+        let tail = ""; // recent output, surfaced as the failure reason
+        const onChunk = (buf) => {
+            tail = (tail + String(buf)).slice(-600);
+            if (settled)
+                return;
+            const url = parseTunnelUrl(String(buf));
+            if (url) {
+                settled = true;
+                resolve({ tunnel: { url, close: () => child.kill("SIGTERM") } });
+            }
+        };
+        child.stdout?.on("data", onChunk);
+        child.stderr?.on("data", onChunk); // cloudflared prints the URL (and its errors) on stderr
+        child.on("error", (e) => {
+            if (settled)
+                return;
+            settled = true;
+            if (e.code === "ENOENT") {
+                resolve({
+                    fatal: true,
+                    message: "[fastagent] --tunnel needs cloudflared — install it (e.g. `brew install cloudflared`), then re-run. Serving without a tunnel.",
+                });
+            }
+            else {
+                resolve({ fatal: false, detail: e.message });
+            }
+        });
+        child.on("exit", () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ fatal: false, detail: lastErrorLine(tail) });
+        });
+    });
+}
+/** The most informative line of cloudflared's output tail (prefer an error line) for a failure log. */
+function lastErrorLine(tail) {
+    const lines = tail
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    return ([...lines].reverse().find((l) => /err|error|failed/i.test(l)) ?? lines.at(-1) ?? "").slice(0, 200);
+}
+/** Channel basenames present in `<dir>/channels/`. */
+function channelBasenames(dir) {
+    try {
+        return readdirSync(join(dir, "channels"))
+            .filter((n) => /\.(ts|js|mjs)$/.test(n) && !n.endsWith(".d.ts"))
+            .map((n) => n.replace(/\.(ts|js|mjs)$/, ""));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Print the public URL and wire up the first-party webhook channels found under `dir`: telegram is
+ * auto-registered via setWebhook (using .env tokens); github prints the URL to add in repo settings.
+ */
+export async function announceWebhooks(dir, baseUrl) {
+    log.info(`[fastagent] public URL: ${baseUrl}`);
+    try {
+        loadDotEnv(dir); // telegram registration reads tokens from .env
+    }
+    catch (error) {
+        // best-effort boundary: a MISSING .env is already tolerated by loadDotEnv; an unreadable one (EACCES,
+        // or .env is a directory) must NOT crash the long-running dev/start server — announceWebhooks is
+        // void-called with no unhandledRejection handler, so a throw here would terminate the process. Warn
+        // (surface it, rule 8) and continue best-effort; telegram registration then degrades to its manual
+        // instruction if the token is absent. loadDotEnv keeps throwing for the synchronous command callers.
+        log.warn(`[fastagent] could not read ${join(dir, ".env")}: ${error.message} — continuing without it`);
+    }
+    const channels = channelBasenames(dir);
+    if (channels.length === 0)
+        return;
+    // Readiness is the registrar's job now: a fresh quick tunnel returns Cloudflare 530 for ~20-30s before
+    // its origin connects, and registerTelegramWebhook polls /health until it serves before setWebhook (the
+    // same wait the deploy runners rely on). github needs no wait — the operator adds that webhook by hand.
+    if (channels.includes("telegram"))
+        await registerTelegramWebhook(baseUrl);
+    if (channels.includes("github")) {
+        log.info(`[fastagent] github: add a webhook in your repo (Settings → Webhooks): Payload URL = ${baseUrl}/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * This build's own @fastagent-sh/fastagent version. THROWS if unreadable — the version is load-bearing for
+ * the scaffolded dependency range (`^${version}`), so init must never scaffold an uninstallable `^0.0.0`.
+ */
+export declare function fastagentVersion(): Promise<string>;

package/dist/version.js

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+/**
+ * This build's own @fastagent-sh/fastagent version. THROWS if unreadable — the version is load-bearing for
+ * the scaffolded dependency range (`^${version}`), so init must never scaffold an uninstallable `^0.0.0`.
+ */
+export async function fastagentVersion() {
+    const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+    const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    if (typeof pkg.version !== "string" || pkg.version === "")
+        throw new Error(`no version in ${pkgPath}`);
+    return pkg.version;
+}

package/dist/workspace.d.ts

@@ -0,0 +1,9 @@
+import { type Ignore } from "ignore";
+/**
+ * Guard that `<workspaceDir>/<name>` resolves INSIDE the workspace — a symlink that escapes (or an
+ * absolute target) is rejected, so discovery/scaffolding never reaches out of the definition directory.
+ * A missing target is fine (nothing to guard yet).
+ */
+export declare function assertInsideWorkspace(workspaceDir: string, name: string): Promise<void>;
+/** Load `.gitignore` + `.fastagentignore` from `dir` into one matcher (case-sensitive), or undefined if none. */
+export declare function loadRootIgnore(dir: string): Promise<Ignore | undefined>;

package/dist/workspace.js

@@ -0,0 +1,45 @@
+/**
+ * Workspace path/ignore utilities — engine-neutral (pure fs/path + the `ignore` matcher). Shared by the
+ * scaffold (init/add) and the engine's channel discovery, so they live here, not under engines/pi.
+ */
+import { readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import ignore, {} from "ignore";
+/**
+ * Guard that `<workspaceDir>/<name>` resolves INSIDE the workspace — a symlink that escapes (or an
+ * absolute target) is rejected, so discovery/scaffolding never reaches out of the definition directory.
+ * A missing target is fine (nothing to guard yet).
+ */
+export async function assertInsideWorkspace(workspaceDir, name) {
+    const target = join(workspaceDir, name);
+    const real = await realpath(target).catch((e) => {
+        if (e.code === "ENOENT" || e.code === "not_found")
+            return undefined;
+        throw e;
+    });
+    if (real === undefined)
+        return;
+    const root = await realpath(workspaceDir).catch(() => resolve(workspaceDir));
+    const rel = relative(root, real);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`${target} resolves outside the workspace (${real}) — it must live inside the definition directory; ` +
+            `use a real directory or a symlink that stays within it`);
+    }
+}
+/** Load `.gitignore` + `.fastagentignore` from `dir` into one matcher (case-sensitive), or undefined if none. */
+export async function loadRootIgnore(dir) {
+    let rules = "";
+    for (const name of [".gitignore", ".fastagentignore"]) {
+        try {
+            rules += `\n${await readFile(join(dir, name), "utf8")}`;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw new Error(`cannot read ${join(dir, name)}: ${error.message}`);
+            }
+        }
+    }
+    // ignorecase:false — the library defaults to case-INSENSITIVE, which would make a rule `README.md`
+    // also drop an authored `readme.md`. Match git on a case-sensitive filesystem, reproducibly.
+    return rules.trim() === "" ? undefined : ignore({ ignorecase: false }).add(rules);
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@fastagent-sh/fastagent",
+  "version": "0.12.0",
+  "description": "Vibe first. Then FastAgent: turn a local agent directory into a running service in your app, on GitHub, in Telegram, or behind any channel.",
+  "keywords": [
+    "agent",
+    "ai-agent",
+    "llm",
+    "agents.md",
+    "agent-skills",
+    "agent-serving",
+    "sse",
+    "pi",
+    "fastagent"
+  ],
+  "license": "MIT",
+  "author": "the fastagent authors (https://github.com/fastagent-sh/fastagent)",
+  "homepage": "https://github.com/fastagent-sh/fastagent#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fastagent-sh/fastagent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fastagent-sh/fastagent/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    },
+    "./pi": {
+      "types": "./dist/pi.d.ts",
+      "default": "./dist/pi.js"
+    },
+    "./github": {
+      "types": "./dist/github.d.ts",
+      "default": "./dist/github.js"
+    },
+    "./telegram": {
+      "types": "./dist/telegram.d.ts",
+      "default": "./dist/telegram.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "fastagent": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src test && node scripts/check-doc-links.mjs",
+    "format": "biome check --write src test",
+    "postbuild": "node scripts/copy-scaffold-assets.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.6.0",
+    "@earendil-works/pi-agent-core": "^0.80.3",
+    "@earendil-works/pi-ai": "^0.80.3",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@octokit/webhooks-methods": "^6.0.0",
+    "@octokit/webhooks-types": "^7.6.1",
+    "chokidar": "^5.0.0",
+    "croner": "^9.1.0",
+    "giget": "^3.3.0",
+    "ignore": "^7.0.5",
+    "undici": "^8.6.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}