@stellar-agent-services/provider-kit 0.0.0-stage → 0.1.1

package/dist/cli/discovery.js

@@ -0,0 +1,202 @@
+// How agents see you: the provider as agents meet it, printed by `provider-kit check`, with hints that never fail it.
+//
+//   search    stellar-agent-search's find_agent (and 8004 explorers) matches a query against the registration: its name
+//             and description, which `provider-kit launch` (or `register`) publishes from provider.name and
+//             provider.description, and its services' names and endpoints. On testnet, stellar-agent-search 0.2.0
+//             reads agents straight from the registry, and also matches a bound manifest's services [I1]–[I3]: their
+//             names, titles, descriptions and tags. On mainnet the explorer's list has no services, so only the name
+//             and description count there.
+//   ranking   in stellar-agent-search, reviews from distinct paying clients only. Declarations add nothing.
+//   services  an agent picks a service by its description, and an example shows it what to send [§3.4].
+//
+// Words are matched as stellar-agent-search 0.2.0 matches them (src/lib/text-match.ts and src/lib/nlparse.ts): accents
+// and case folded, words of two or more characters that aren't its stopwords, a crude suffix stem, then a substring
+// test on each field.
+import { DEFAULT_MANIFEST_PATH } from "@stellar-agent-services/protocol";
+import { DESCRIPTION_TO_WRITE, PROVIDER_DESCRIPTION_TO_WRITE } from "../gateway/openapi.js";
+import { plain } from "./shared.js";
+/** The stellar-agent-search release whose matching this follows, and whose CLI shows the live profile. */
+export const SEARCH_PACKAGE = "stellar-agent-search@0.2.0";
+/** stellar-agent-search's stopwords: query framing and filter triggers, which it never searches for. */
+const STOPWORDS = new Set([
+    "a", "an", "the", "and", "or", "of", "to", "for", "with", "without", "in", "on", "at", "by", "from", "as", "that",
+    "this", "these", "those", "is", "are", "be", "which", "who", "whose", "whom", "it", "its",
+    "find", "search", "get", "give", "show", "list", "me", "my", "i", "want", "need", "needs", "looking", "look",
+    "please", "some", "any", "agent", "agents", "service", "services", "provider", "providers", "one", "ones",
+    "using", "use", "uses", "used", "via", "through", "can", "should", "must", "supports", "support", "supporting",
+    "has", "have", "having", "offers", "offer", "offering", "provides", "provide", "providing", "does", "do",
+    "x402", "paid", "pay", "payment", "payments", "usdc", "monetized", "monetize", "cheap", "cheapest", "affordable",
+    "micropayment", "micropayments", "microtransaction", "microtransactions", "mpp", "streaming", "invoke",
+    "invocable", "invokable", "callable", "endpoint", "endpoints", "api", "apis",
+    "reputation", "reputation-based", "validation", "validated", "tee", "enclave", "attested", "attestation", "trust",
+    "trusted",
+    "score", "scored", "rated", "rating", "reputable", "highly", "well", "reviewed", "review", "reviews", "high", "top",
+    "best", "excellent", "great", "good", "quality", "above", "over", "least", "minimum", "min", "than", "more",
+    "bir", "bu", "ve", "veya", "icin", "ile", "olan", "bana", "bul", "goster", "listele", "istiyorum", "lazim", "ajan",
+    "ajanlar", "servis", "servisi", "hizmet", "hizmeti", "ucretli", "odemeli", "odeme", "odemeler", "ucuz",
+    "cagrilabilir", "itibar", "puan", "puanli", "yuksek", "iyi", "itibarli", "dogrulama", "dogrulanmis",
+]);
+const SUFFIXES = ["ping", "ning", "ging", "ing", "pers", "per", "ers", "er", "es", "ed", "s"];
+/** Fewer words than this can't say what a service does, when to use it and its limits [§3.4]. */
+const MIN_DESCRIPTION_WORDS = 12;
+const WORDS_SHOWN = 6;
+const SERVICES_SHOWN = 8;
+const WIDTH = 110;
+const PRICE = /\$\s?\d|\b\d+(?:[.,]\d+)?\s?(?:usdc|usd|xlm|dollars?|cents?)\b/i;
+const URL_TEXT = /\bhttps?:\/\/|\bwww\./i;
+/**
+ * The "How agents see you" section of `provider-kit check`. `registered` is the 8004 registration file read from the
+ * registry, when the provider has an agentId and the file could be read: search shows its name and description.
+ */
+export function howAgentsSeeYou(manifest, registered) {
+    const { provider, services } = manifest;
+    const agentId = provider.agentId;
+    const description = provider.description ?? "";
+    const testnet = manifest.payment.accepts[0].network === "stellar:testnet";
+    const shown = registered === undefined ? { name: provider.name, description } : { name: text(registered["name"]), description: text(registered["description"]) };
+    const lines = [
+        "How agents see you",
+        `  Search matches ${testnet ? "" : "only "}this name and description${registered === undefined ? ", which provider-kit launch publishes" : ", as registered"}:`,
+        `    ${plain(shown.name, 100) || "(no name)"}`,
+        `    ${plain(shown.description, 100) || "(no description)"}`,
+    ];
+    if (testnet) {
+        lines.push(...wrap("· On testnet it also matches your services' names, titles, descriptions and tags, once the manifest is live and names the agent [I1]–[I3].", "  ", "    "));
+    }
+    const hints = [];
+    if (registered !== undefined && (shown.name !== provider.name || shown.description !== description)) {
+        hints.push("The registry still has an older name or description: provider-kit launch updates it.");
+    }
+    if (description.trim() === "")
+        hints.push("provider.description is empty, so search matches only your name.");
+    else if (description === PROVIDER_DESCRIPTION_TO_WRITE)
+        hints.push("provider.description is still init's placeholder: say what you offer, in the words buyers type.");
+    // The registration lists the manifest and baseUrl as its services, whose names and endpoints search matches too.
+    const listed = `stellar-agent-services ${new URL(DEFAULT_MANIFEST_PATH, manifest.baseUrl).toString()} web ${manifest.baseUrl}`;
+    const missing = missingWords(`${provider.name} ${description} ${listed}`, services);
+    const notes = [];
+    if (missing.length > 0 && testnet) {
+        notes.push(`On mainnet, search reads no service names, titles or tags: agents searching there for ${wordList(missing)} wouldn't find you. provider-kit check --fix puts those words in provider.description.`);
+    }
+    else if (missing.length > 0) {
+        hints.push(`Search reads no service names, titles or tags on mainnet, so agents searching for ${wordList(missing)} won't find you. Put those words in provider.description: provider-kit check --fix does.`);
+    }
+    const thin = services.flatMap((service) => {
+        const issues = serviceIssues(service);
+        return issues.length === 0 ? [] : [`${plain(service.name, 64)}: ${issues.join(", ")}`];
+    });
+    hints.push(...thin.slice(0, SERVICES_SHOWN));
+    if (thin.length > SERVICES_SHOWN)
+        hints.push(`… and ${thin.length - SERVICES_SHOWN} more services`);
+    for (const hint of hints)
+        lines.push(...wrap(`! ${hint}`, "  ", "    "));
+    if (thin.length > 0) {
+        lines.push(...wrap("An agent picks a service by its description: what it does, when to use it, its limits, with no price or URL [§3.4]. An example shows it what to send, and provider-kit try pays with it.", "    ", "    "));
+    }
+    for (const note of notes)
+        lines.push(...wrap(`· ${note}`, "  ", "    "));
+    lines.push(...wrap("· Ranking counts reviews from distinct paying clients only. Until the first, search lists you as new and unrated.", "  ", "    "));
+    if (agentId === undefined) {
+        lines.push("  · Not registered yet: provider-kit launch publishes this name and description.");
+    }
+    else {
+        lines.push(`  · Live: ${testnet ? "STELLAR_NETWORK=testnet " : ""}npx -y ${SEARCH_PACKAGE} profile ${agentId}`);
+    }
+    return lines;
+}
+/** The most provider.description may hold (the gateway config's schema, and the manifest's). */
+const DESCRIPTION_MAX = 500;
+/**
+ * provider.description with the words search would miss written in, for `provider-kit check --fix`: a sentence naming
+ * the services, then any tag words still missing. Undefined when search already finds every word.
+ */
+export function describedWithServices(manifest) {
+    const { provider, services } = manifest;
+    const description = (provider.description ?? "").trim();
+    if (missingWords(`${provider.name} ${description}`, services).length === 0)
+        return undefined;
+    const base = description === "" || description === PROVIDER_DESCRIPTION_TO_WRITE ? "" : `${description.replace(/([^.!?])$/, "$1.")} `;
+    const titles = services.map((service) => plain(service.title ?? service.name.replace(/[-_]+/g, " "), 60));
+    let text = `${base}Services: ${titles.join(", ")}.`;
+    const still = missingWords(`${provider.name} ${text}`, services);
+    if (still.length > 0)
+        text += ` Keywords: ${still.join(", ")}.`;
+    if (text.length <= DESCRIPTION_MAX)
+        return text;
+    // Too long: as many service titles as fit.
+    const kept = [];
+    for (const title of titles) {
+        if (`${base}Services: ${[...kept, title].join(", ")}, and more.`.length > DESCRIPTION_MAX)
+            break;
+        kept.push(title);
+    }
+    return kept.length === 0 ? undefined : `${base}Services: ${kept.join(", ")}${kept.length < titles.length ? ", and more" : ""}.`;
+}
+/** Words from the services' names, titles and tags that a search for them wouldn't match in `text`. */
+export function missingWords(text, services) {
+    const haystack = fold(text);
+    const missing = new Set();
+    for (const service of services) {
+        for (const word of searchWords([service.name, service.title ?? "", ...(service.tags ?? [])].join(" "))) {
+            if (!haystack.includes(stem(word)))
+                missing.add(word);
+        }
+    }
+    return [...missing];
+}
+/** The words of `text` a search uses: folded, at least two characters, not a number, not a stopword. */
+export function searchWords(text) {
+    return (fold(text).match(/[\p{L}\p{N}]+/gu) ?? []).filter((word) => word.length >= 2 && !/^\d+$/.test(word) && !STOPWORDS.has(word));
+}
+/** stellar-agent-search's stem: one common suffix off, leaving at least three characters. */
+export function stem(word) {
+    const suffix = SUFFIXES.find((candidate) => word.endsWith(candidate) && word.length - candidate.length >= 3);
+    return suffix === undefined ? word : word.slice(0, word.length - suffix.length);
+}
+function serviceIssues(service) {
+    const issues = [];
+    const words = service.description.split(/\s+/).filter(Boolean).length;
+    if (service.description === DESCRIPTION_TO_WRITE)
+        issues.push("the description is still init's placeholder");
+    else if (words < MIN_DESCRIPTION_WORDS)
+        issues.push(`a ${words}-word description`);
+    if (PRICE.test(service.description))
+        issues.push("a price in the description");
+    if (URL_TEXT.test(service.description))
+        issues.push("a URL in the description");
+    if (service.examples === undefined || service.examples.length === 0)
+        issues.push("no example");
+    return issues;
+}
+/** Accents and case folded, as search folds both the query and the text. */
+function fold(value) {
+    return value.normalize("NFKD").replace(/\p{M}+/gu, "").replace(/ı/g, "i").toLowerCase();
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+/** "a", "b" or "c", and how many more. */
+function wordList(words) {
+    const quoted = words.slice(0, WORDS_SHOWN).map((word) => `"${plain(word, 32)}"`);
+    if (words.length > WORDS_SHOWN)
+        return `${quoted.join(", ")} and ${words.length - WORDS_SHOWN} more`;
+    return quoted.length === 1 ? quoted[0] : `${quoted.slice(0, -1).join(", ")} or ${quoted.at(-1)}`;
+}
+/** Breaks `value` into lines of at most WIDTH characters: the first starts with `first`, the rest with `rest`. */
+function wrap(value, first, rest) {
+    const lines = [];
+    let line = first;
+    for (const word of value.split(" ")) {
+        const prefix = lines.length === 0 ? first : rest;
+        if (line.length > prefix.length && line.length + 1 + word.length > WIDTH) {
+            lines.push(line);
+            line = rest + word;
+        }
+        else {
+            line += line.length > prefix.length ? ` ${word}` : word;
+        }
+    }
+    lines.push(line);
+    return lines;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/cli/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/cli/discovery.ts"],"names":[],"mappings":"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"}

package/dist/cli/env-file.d.ts

@@ -0,0 +1,16 @@
+/** The env file the commands read and write when --env-file doesn't name another. */
+export declare const ENV_FILE = ".env";
+/** The values in an env file. {} when there is none. */
+export declare function readEnvFile(path: string): Promise<Record<string, string>>;
+/** Loads an env file into `env`, leaving every variable that is already set as it is. Returns whether the file exists. */
+export declare function loadEnvFile(path: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
+/**
+ * Sets values in an env file, keeping everything else as it was. `undefined` removes a value's line. A new value goes at
+ * the end, after its comment from `comments` when there is one. Without the file, nothing is written and it returns
+ * false, unless `create` is set.
+ */
+export declare function updateEnvFile(path: string, values: Record<string, string | undefined>, options?: {
+    comments?: Record<string, string>;
+    create?: boolean;
+}): Promise<boolean>;
+//# sourceMappingURL=env-file.d.ts.map

package/dist/cli/env-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-file.d.ts","sourceRoot":"","sources":["../../src/cli/env-file.ts"],"names":[],"mappings":"AAWA,qFAAqF;AACrF,eAAO,MAAM,QAAQ,SAAS,CAAC;AAE/B,wDAAwD;AACxD,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAG/E;AAED,0HAA0H;AAC1H,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,OAAO,CAAC,CAMtG;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC1C,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACpE,OAAO,CAAC,OAAO,CAAC,CA6BlB"}

package/dist/cli/env-file.js

@@ -0,0 +1,77 @@
+// .env files: the settings a project keeps out of git (docs/provider-setup-guide.md §1).
+//
+// `provider-kit dev`, `launch` and `status` read the project's .env, as `node --env-file` would: a variable already set
+// in the environment wins. `dev` and `launch` write back the values they settle (PAY_TO, DEV_PAY_TO, AGENT_ID), keeping
+// the file as it was: a value replaces its own line, or a commented-out "# NAME=" line, and a new one goes at the end.
+// Only public values are ever written here. No secret key goes in a .env file, and none comes from one.
+import { existsSync } from "node:fs";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { parseEnv } from "node:util";
+/** The env file the commands read and write when --env-file doesn't name another. */
+export const ENV_FILE = ".env";
+/** The values in an env file. {} when there is none. */
+export async function readEnvFile(path) {
+    if (!existsSync(path))
+        return {};
+    return parseEnv(await readFile(path, "utf8"));
+}
+/** Loads an env file into `env`, leaving every variable that is already set as it is. Returns whether the file exists. */
+export async function loadEnvFile(path, env = process.env) {
+    if (!existsSync(path))
+        return false;
+    for (const [name, value] of Object.entries(await readEnvFile(path))) {
+        if (env[name] === undefined)
+            env[name] = value;
+    }
+    return true;
+}
+/**
+ * Sets values in an env file, keeping everything else as it was. `undefined` removes a value's line. A new value goes at
+ * the end, after its comment from `comments` when there is one. Without the file, nothing is written and it returns
+ * false, unless `create` is set.
+ */
+export async function updateEnvFile(path, values, options = {}) {
+    const exists = existsSync(path);
+    if (!exists && options.create !== true)
+        return false;
+    const lines = exists ? (await readFile(path, "utf8")).replace(/\n$/, "").split("\n") : [];
+    for (const [name, value] of Object.entries(values)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            throw new Error(`${name} is not an environment variable name`);
+        const set = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=`);
+        const commented = new RegExp(`^\\s*#\\s*${name}\\s*=`);
+        let index = lines.findIndex((line) => set.test(line));
+        if (value === undefined) {
+            if (index !== -1)
+                lines.splice(index, 1);
+            continue;
+        }
+        if (index === -1)
+            index = lines.findIndex((line) => commented.test(line));
+        const line = `${name}=${envValue(value)}`;
+        if (index !== -1) {
+            lines[index] = line;
+            continue;
+        }
+        const comment = options.comments?.[name];
+        if (lines.length > 0 && lines.at(-1) !== "" && comment !== undefined)
+            lines.push("");
+        if (comment !== undefined)
+            lines.push(...comment.split("\n").map((text) => `# ${text}`));
+        lines.push(line);
+    }
+    // Written beside the file, then renamed over it, so an interrupted write never leaves half a file.
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${lines.join("\n")}\n`);
+    await rename(temporary, path);
+    return true;
+}
+/** A value as an env file holds it: bare when it can be, else in double quotes. The values written here are public and plain. */
+function envValue(value) {
+    if (/^[\w@%+=:,./-]*$/.test(value))
+        return value;
+    if (/["\\\n\r]/.test(value))
+        throw new Error(`can't write ${JSON.stringify(value)} to an env file`);
+    return `"${value}"`;
+}
+//# sourceMappingURL=env-file.js.map

package/dist/cli/env-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-file.js","sourceRoot":"","sources":["../../src/cli/env-file.ts"],"names":[],"mappings":"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"}

package/dist/cli/fly.d.ts

@@ -0,0 +1,28 @@
+export declare const FLY_TOML = "fly.toml";
+export interface FlyApp {
+    /** fly.toml's path. */
+    path: string;
+    app: string;
+    /** https://<app>.fly.dev */
+    origin: string;
+}
+/** Runs flyctl. `inherit` shows it in this terminal, so it can ask the developer things; `input` goes to its standard input. */
+export type FlyRunner = (args: string[], options?: {
+    inherit?: boolean;
+    input?: string;
+}) => Promise<{
+    code: number;
+    output: string;
+}>;
+/** The app fly.toml names, or undefined when there is no fly.toml or it names none. */
+export declare function flyApp(path?: string): Promise<FlyApp | undefined>;
+/** Sets values in fly.toml's [env] table, keeping the rest of the file as it was. The table is added when missing. */
+export declare function setFlyEnv(path: string, values: Record<string, string>): Promise<void>;
+/** Stages secrets for the app's next deploy, read by flyctl from its standard input so they never show in a process list. */
+export declare function flySecrets(fly: FlyRunner, app: string, secrets: Record<string, string>): Promise<boolean>;
+/**
+ * Deploys the app: flyctl must be installed and logged in. The app is created the first time. Returns why it couldn't,
+ * or undefined once `fly deploy` succeeded.
+ */
+export declare function flyDeploy(fly: FlyRunner, app: FlyApp, log: (line: string) => void): Promise<string | undefined>;
+//# sourceMappingURL=fly.d.ts.map

package/dist/cli/fly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fly.d.ts","sourceRoot":"","sources":["../../src/cli/fly.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,QAAQ,aAAa,CAAC;AAEnC,MAAM,WAAW,MAAM;IACrB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gIAAgI;AAChI,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvI,uFAAuF;AACvF,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAiB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAIjF;AAED,sHAAsH;AACtH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3F;AAQD,6HAA6H;AAC7H,wBAAsB,UAAU,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAI/G;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiBrH"}

package/dist/cli/fly.js

@@ -0,0 +1,92 @@
+// Fly.io, where `npm create stellar-service` sets a project up to run. fly.toml names the app, so the service's public
+// address is known before its first deploy (https://<app>.fly.dev). That lets `provider-kit launch` register first and
+// deploy once, with the agent id in place.
+//
+// - flyApp(): the app and its public origin, from fly.toml.
+// - setFlyEnv(): writes public settings (PUBLIC_ORIGIN, PAY_TO, AGENT_ID) into fly.toml's [env], so every deploy has
+//   them. Only public values: an API's key goes in Fly's secrets (flySecrets()), never in fly.toml.
+// - flyDeploy(): creates the app the first time, then `fly deploy` with a single machine. The job database is SQLite on
+//   a volume, which one machine holds; fly.toml's [[mounts]] has Fly make that volume on the first deploy.
+import { existsSync } from "node:fs";
+import { readFile, rename, writeFile } from "node:fs/promises";
+export const FLY_TOML = "fly.toml";
+/** The app fly.toml names, or undefined when there is no fly.toml or it names none. */
+export async function flyApp(path = FLY_TOML) {
+    if (!existsSync(path))
+        return undefined;
+    const app = /^\s*app\s*=\s*["']([a-z0-9][a-z0-9-]*)["']\s*(?:#.*)?$/m.exec(await readFile(path, "utf8"))?.[1];
+    return app === undefined ? undefined : { path, app, origin: `https://${app}.fly.dev` };
+}
+/** Sets values in fly.toml's [env] table, keeping the rest of the file as it was. The table is added when missing. */
+export async function setFlyEnv(path, values) {
+    const lines = (await readFile(path, "utf8")).replace(/\n$/, "").split("\n");
+    let header = lines.findIndex((line) => /^\s*\[env\]\s*(?:#.*)?$/.test(line));
+    if (header === -1) {
+        lines.push("", "[env]");
+        header = lines.length - 1;
+    }
+    let end = lines.findIndex((line, index) => index > header && /^\s*\[/.test(line));
+    if (end === -1)
+        end = lines.length;
+    for (const [name, setting] of Object.entries(named(values))) {
+        const entry = `  ${name} = ${JSON.stringify(setting)}`;
+        const index = lines.findIndex((line, at) => at > header && at < end && new RegExp(`^\\s*${name}\\s*=`).test(line));
+        if (index !== -1) {
+            lines[index] = entry;
+            continue;
+        }
+        // After the table's last entry, before the blank lines that end it.
+        let at = end;
+        while (at - 1 > header && lines[at - 1].trim() === "")
+            at -= 1;
+        lines.splice(at, 0, entry);
+        end += 1;
+    }
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${lines.join("\n")}\n`);
+    await rename(temporary, path);
+}
+/** The values, once each name is checked to be an environment variable's. */
+function named(values) {
+    for (const name of Object.keys(values))
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(name))
+            throw new Error(`${name} is not an environment variable name`);
+    return values;
+}
+/** Stages secrets for the app's next deploy, read by flyctl from its standard input so they never show in a process list. */
+export async function flySecrets(fly, app, secrets) {
+    if (Object.keys(secrets).length === 0)
+        return true;
+    const input = Object.entries(named(secrets)).map(([name, secret]) => `${name}=${secret}`).join("\n");
+    return (await fly(["secrets", "import", "--stage", "--app", app], { input })).code === 0;
+}
+/**
+ * Deploys the app: flyctl must be installed and logged in. The app is created the first time. Returns why it couldn't,
+ * or undefined once `fly deploy` succeeded.
+ */
+export async function flyDeploy(fly, app, log) {
+    if ((await fly(["version"])).code !== 0)
+        return "flyctl isn't installed: https://fly.io/docs/flyctl/install/";
+    if ((await fly(["auth", "whoami"])).code !== 0) {
+        log("  … Log in to Fly.io (flyctl opens your browser)");
+        if ((await fly(["auth", "login"], { inherit: true })).code !== 0)
+            return "flyctl isn't logged in: run fly auth login";
+    }
+    const status = await fly(["status", "--app", app.app]);
+    if (status.code !== 0) {
+        if (!/could not find app|not found/i.test(status.output))
+            return `fly status failed: ${lastLine(status.output)}`;
+        log(`  … Creating the Fly.io app ${app.app}`);
+        if ((await fly(["apps", "create", app.app], { inherit: true })).code !== 0) {
+            return `the app ${app.app} couldn't be created (its name may be taken: change "app" in fly.toml, then launch again)`;
+        }
+    }
+    log(`  … Deploying ${app.app} (fly deploy)`);
+    if ((await fly(["deploy", "--config", app.path, "--app", app.app, "--ha=false"], { inherit: true })).code !== 0)
+        return "fly deploy failed: see its output above";
+    return undefined;
+}
+function lastLine(output) {
+    return output.trim().split("\n").at(-1) ?? "no output";
+}
+//# sourceMappingURL=fly.js.map

package/dist/cli/fly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fly.js","sourceRoot":"","sources":["../../src/cli/fly.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// The provider-kit command. It only silences Node's notice that node:sqlite is experimental (the job
+// store uses it, deliberately) and then loads the CLI, which is in main.ts.
+process.removeAllListeners("warning").on("warning", (warning) => {
+    if (warning.name === "ExperimentalWarning" && warning.message.includes("SQLite"))
+        return;
+    console.warn(`${warning.name}: ${warning.message}`);
+});
+await import("./main.js");
+export {};
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,qGAAqG;AACrG,4EAA4E;AAE5E,OAAO,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;IAC9D,IAAI,OAAO,CAAC,IAAI,KAAK,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO;IACzF,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;AACtD,CAAC,CAAC,CAAC;AAEH,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC"}

package/dist/cli/init.d.ts

@@ -0,0 +1,3 @@
+import { type CliFlags } from "./shared.js";
+export declare function init(flags: CliFlags): Promise<number>;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAS,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAMnD,wBAAsB,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC3D"}