@foldrun/core 0.2.0

package/dist/src/deploy.js

@@ -0,0 +1,377 @@
+// Deploying a workspace from a directory — the git-push half of the platform.
+//
+// A workspace is markdown, so there is nothing to build. Deploy is "make the
+// files on disk match the commit", which is a copy plus two things a copy
+// cannot do on its own:
+//
+//   1. Check first. Everything here is declarative, so the whole workspace can
+//      be validated before any of it is live — a broken flow is caught at push
+//      time rather than at 3am when its schedule fires. A platform deploying
+//      compiled code cannot do this cheaply. We can, and it is the reason to
+//      route deploys through here instead of writing files directly.
+//
+//   2. Refuse at the wrong moment. Swapping files under a running flow means
+//      step 3 reads agents that step 1 never saw.
+//
+// What a deploy must NOT touch is already settled by saveWorkspace: runs/,
+// state/, secrets.json, and any memory an agent wrote that the push doesn't
+// mention. Those are the platform's, not git's. This module decides whether a
+// deploy happens at all; saveWorkspace decides what survives it.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { saveWorkspace, workspaceDir, listRuns, parseFlow, WORKSPACE_DIRS, assertSafeName, } from "./store.js";
+import { conformanceIssues } from "./okf.js";
+import { repoDir } from "./gitrepo.js";
+/** Directories a deploy never reads out of a source tree. */
+const NOT_SOURCE = new Set([".git", "node_modules", "runs", "outputs", ".foldrun", ".results"]);
+/** Files that are never part of a workspace, whatever directory they sit in. */
+const NOT_SOURCE_FILE = new Set([".DS_Store", "secrets.json"]);
+const IN_WORKSPACE_DIR = new RegExp(`^(${WORKSPACE_DIRS.join("|")})/`);
+/**
+ * Read a directory into the file list a deploy ships.
+ *
+ * Only what a workspace is made of: AGENTS.md and the tracked directories.
+ * Everything else in the repo — a README, .github/, a package.json — is
+ * skipped rather than rejected, because a workspace living in a repo alongside
+ * other things is the normal case, not an error.
+ */
+// Where single-file subagents authored by other tools are found, in
+// precedence order: the vendor-neutral cross-client location first, then any
+// tool-specific one for pragmatic compatibility. Extend the tail, never the
+// head. Shared by the deploy import (readTree) and the CLI checker so the two
+// agree on what counts as an agent.
+export const SUBAGENT_IMPORT_DIRS = [".agents/agents", ".claude/agents"];
+export function readTree(dir) {
+    const root = path.resolve(dir);
+    const out = [];
+    const walk = (abs, rel) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(abs).sort();
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (NOT_SOURCE.has(entry) || NOT_SOURCE_FILE.has(entry))
+                continue;
+            const full = path.join(abs, entry);
+            const next = rel ? `${rel}/${entry}` : entry;
+            // Never follow a link out of the tree — the same rule the file listing
+            // uses, for the same reason.
+            let stat;
+            try {
+                if (fs.lstatSync(full).isSymbolicLink())
+                    continue;
+                stat = fs.statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                walk(full, next);
+            }
+            else if (next === "AGENTS.md" || next === "project.md" || IN_WORKSPACE_DIR.test(next)) {
+                out.push({ path: next, content: fs.readFileSync(full, "utf8") });
+            }
+        }
+    };
+    walk(root, "");
+    // Bridge single-file subagents authored by ANY coding tool into the folder
+    // shape the runtime expects. The cross-client, vendor-neutral location is
+    // `.agents/agents/<name>.md` — the same `.agents/` root as `.agents/skills/`
+    // — and it is scanned first. A tool's own location (only `.claude/agents/`
+    // so far, as the one that ships single-file subagents) is scanned after, for
+    // pragmatic compatibility; add another vendor here when one appears, never
+    // ahead of the neutral location. A subagent's frontmatter — name,
+    // description, tools, model, effort, skills, mcpServers, disallowedTools — is
+    // already what a foldrun agent reads, so each maps to agents/<name>/agent.md
+    // with its content unchanged. A native agents/<name>/agent.md always wins,
+    // and the neutral location wins over a vendor one; the import only fills a
+    // gap, so authoring elsewhere and deploying here needs no rewrite. Unknown
+    // vendor-only keys (permissionMode, hooks, …) are ignored, as every other
+    // frontmatter reader here ignores what it does not use.
+    const nativeAgent = new Set(out.filter((fEntry) => /^agents\/[^/]+\/agent\.md$/.test(fEntry.path)).map((fEntry) => fEntry.path));
+    for (const importDir of SUBAGENT_IMPORT_DIRS) {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(root, importDir)).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith(".md"))
+                continue;
+            const name = entry.replace(/\.md$/, "");
+            const target = `agents/${name}/agent.md`;
+            // Native wins; and .claude/agents beats .agents/agents on a name clash
+            // (it is scanned first and this skips a path already imported).
+            if (nativeAgent.has(target) || out.some((fEntry) => fEntry.path === target))
+                continue;
+            const full = path.join(root, importDir, entry);
+            try {
+                if (fs.lstatSync(full).isSymbolicLink())
+                    continue;
+                out.push({ path: target, content: fs.readFileSync(full, "utf8") });
+            }
+            catch {
+                // an unreadable import is skipped, not fatal
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Everything wrong with an incoming workspace, before any of it is live.
+ *
+ * Deliberately the same questions `foldrun check` asks, against files that are
+ * not on disk yet. A deploy that would leave the workspace failing its own
+ * checker should not be a deploy.
+ */
+export function deployIssues(files) {
+    const issues = [];
+    const at = (where, message) => issues.push({ where, message });
+    if (files.length === 0)
+        at("/", "nothing to deploy — no workspace files in this tree");
+    if (files.length > 500)
+        at("/", `${files.length} files — a workspace is capped at 500`);
+    // Path safety, as questions rather than exceptions: a push should report
+    // everything wrong with it at once, not fail on the first bad path.
+    for (const f of files) {
+        const norm = path.normalize(f.path);
+        if (norm.startsWith("..") || path.isAbsolute(norm) || norm.startsWith("runs")) {
+            at(f.path, "illegal path");
+        }
+        const base = norm.split("/").pop() ?? norm;
+        for (const want of ["AGENTS.md", "SKILL.md"]) {
+            if (base !== want && base.toLowerCase() === want.toLowerCase()) {
+                at(f.path, `must be spelled exactly "${want}" — the case is part of the standard`);
+            }
+        }
+    }
+    const agents = new Set();
+    for (const f of files) {
+        const m = f.path.match(/^agents\/([^/]+)\/agent\.md$/);
+        if (m)
+            agents.add(m[1]);
+    }
+    if (agents.size === 0) {
+        at("agents/", "no agents — a workspace needs at least one agents/<name>/agent.md");
+    }
+    // Flows, parsed from the incoming text rather than from disk. A step naming
+    // an agent that this push does not ship is the single most common way a
+    // deploy breaks a schedule, and it is free to catch here.
+    const flows = files.filter((f) => /^flows\/[^/]+\.md$/.test(f.path));
+    const flowNames = new Set();
+    for (const f of flows) {
+        try {
+            flowNames.add(parseFlow(path.basename(f.path), f.content).name);
+        }
+        catch {
+            // reported below, when it is parsed for real
+        }
+    }
+    for (const f of flows) {
+        let parsed;
+        try {
+            parsed = parseFlow(path.basename(f.path), f.content);
+        }
+        catch (err) {
+            at(f.path, err instanceof Error ? err.message : String(err));
+            continue;
+        }
+        if (parsed.steps.length === 0)
+            at(f.path, "no steps");
+        for (const s of parsed.steps) {
+            const target = s.subflow ?? s.agent;
+            const known = s.subflow ? flowNames.has(target) : agents.has(target);
+            if (!known) {
+                at(`${f.path}${s.line ? `:${s.line}` : ""}`, `[[${s.subflow ? "flow:" : ""}${target}]] does not exist in this deploy`);
+            }
+        }
+    }
+    // OKF conformance, which needs the files as a tree. Staged in a temp
+    // directory and thrown away — nothing touches the live workspace until every
+    // check above has passed.
+    const staged = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-stage-"));
+    try {
+        for (const f of files) {
+            const norm = path.normalize(f.path);
+            if (norm.startsWith("..") || path.isAbsolute(norm))
+                continue;
+            const target = path.join(staged, norm);
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, f.content);
+        }
+        for (const bundle of ["memory", "knowledge"]) {
+            for (const { file, issue } of conformanceIssues(path.join(staged, bundle))) {
+                at(`${bundle}/${file}`, issue);
+            }
+        }
+        for (const agent of agents) {
+            for (const bundle of ["memory", "knowledge"]) {
+                const dir = path.join(staged, "agents", agent, bundle);
+                for (const { file, issue } of conformanceIssues(dir)) {
+                    at(`agents/${agent}/${bundle}/${file}`, issue);
+                }
+            }
+        }
+    }
+    finally {
+        fs.rmSync(staged, { recursive: true, force: true });
+    }
+    return issues;
+}
+/**
+ * Runs that make this a bad moment to swap the files under them.
+ *
+ * A flow reads its agents step by step. Replacing them mid-run means step 3
+ * runs against a definition step 1 never saw, and the trace becomes a record
+ * of two different workspaces. A run waiting on a person counts too: they are
+ * about to approve work that the deploy would silently redefine.
+ */
+export function runsInFlight(tenant, workspace) {
+    if (!fs.existsSync(workspaceDir(tenant, workspace)))
+        return [];
+    return listRuns(tenant, workspace)
+        .filter((r) => r.status === "queued" || r.status === "running" || r.status === "awaiting-approval")
+        .map((r) => r.id);
+}
+/** What a deploy would do, without doing it. */
+export function planDeploy(tenant, workspace, files) {
+    const dir = workspaceDir(tenant, workspace);
+    const shipped = new Map(files.map((f) => [path.normalize(f.path), f.content]));
+    const present = new Set();
+    if (fs.existsSync(dir)) {
+        for (const entry of fs.readdirSync(dir, { recursive: true })) {
+            const rel = String(entry).split(path.sep).join("/");
+            if (NOT_SOURCE.has(rel.split("/")[0]))
+                continue;
+            if (/(^|\/)(runs|outputs|\.results)\//.test(rel))
+                continue;
+            if (rel === "secrets.json")
+                continue;
+            try {
+                if (!fs.statSync(path.join(dir, rel)).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            present.add(rel);
+        }
+    }
+    const added = [];
+    const updated = [];
+    for (const [rel, content] of shipped) {
+        if (!present.has(rel)) {
+            added.push(rel);
+            continue;
+        }
+        try {
+            if (fs.readFileSync(path.join(dir, rel), "utf8") !== content)
+                updated.push(rel);
+        }
+        catch {
+            updated.push(rel);
+        }
+    }
+    // What saveWorkspace will keep regardless — reporting these as removals
+    // would be a lie, and the alarming kind.
+    const kept = (rel) => /(^|\/)state\//.test(rel) || /(^|\/)memory\/[^/]+\.md$/.test(rel);
+    const removed = [...present].filter((rel) => !shipped.has(rel) && !kept(rel));
+    return {
+        files,
+        added: added.sort(),
+        updated: updated.sort(),
+        removed: removed.sort(),
+        issues: deployIssues(files),
+        blockedBy: runsInFlight(tenant, workspace),
+    };
+}
+export const pushNotePath = (tenant, workspace) => path.join(repoDir(tenant, workspace), "foldrun-last-push.json");
+export function readPushNote(tenant, workspace) {
+    try {
+        return JSON.parse(fs.readFileSync(pushNotePath(tenant, workspace), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writePushNote(tenant, workspace, note) {
+    try {
+        fs.writeFileSync(pushNotePath(tenant, workspace), JSON.stringify(note));
+    }
+    catch {
+        // The note is a record, not the deploy. Losing it must not fail a push.
+    }
+}
+/**
+ * A push whose deploy was refused only because a run was in flight is not a
+ * failure — it is a deploy that has not happened yet. Git already said the
+ * push succeeded (the deploy happens after the client is gone), so nothing
+ * would ever tell anyone the workspace on disk is behind `main`. This applies
+ * it once the runs are done.
+ *
+ * Only `blockedBy`: a push refused for `issues` is a broken workspace and
+ * wants a person, not a retry.
+ */
+export function applyPendingPush(tenant, workspace, filesAt) {
+    const note = readPushNote(tenant, workspace);
+    if (!note || note.applied)
+        return null;
+    if (!note.blockedBy?.length || (note.issues?.length ?? 0) > 0)
+        return null;
+    if (runsInFlight(tenant, workspace).length > 0)
+        return null;
+    // Only the commit the note names, and only while it is still what main
+    // points at — a newer push supersedes it and wrote its own note.
+    const result = deployWorkspace(tenant, workspace, filesAt(tenant, workspace, note.commit), {
+        commit: note.commit,
+        force: false,
+    });
+    writePushNote(tenant, workspace, {
+        ...note,
+        applied: result.applied,
+        issues: result.issues ?? [],
+        blockedBy: result.blockedBy ?? [],
+        ...(result.applied ? { appliedAt: new Date().toISOString() } : {}),
+    });
+    return result.applied ? { commit: note.commit } : null;
+}
+export function deployWorkspace(tenant, workspace, files, opts = {}) {
+    assertSafeName(tenant, "tenant");
+    assertSafeName(workspace, "workspace");
+    const plan = planDeploy(tenant, workspace, files);
+    const blocked = plan.blockedBy.length > 0 && !opts.force;
+    if (plan.issues.length > 0 || blocked) {
+        return { ...plan, applied: false, commit: null, preserved: 0 };
+    }
+    const { preserved } = saveWorkspace(tenant, workspace, files, { commit: opts.commit ?? null, by: opts.by ?? "deploy", message: opts.message });
+    const commit = opts.commit ?? null;
+    if (commit)
+        writeDeployedCommit(tenant, workspace, commit);
+    return { ...plan, applied: true, commit, preserved };
+}
+// Which commit a workspace is running.
+//
+// Outside the workspace directory on purpose: saveWorkspace replaces that
+// directory wholesale, so a marker written inside it would be deleted by the
+// very deploy it describes. It also is not a workspace file — nobody should
+// see it in the file tree or be able to edit it.
+const commitFile = (tenant, workspace) => path.join(workspaceDir(tenant, workspace), "..", `.${workspace}.deployed`);
+export function writeDeployedCommit(tenant, workspace, commit) {
+    const f = commitFile(tenant, workspace);
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, `${JSON.stringify({ commit, at: new Date().toISOString() })}\n`);
+}
+export function deployedCommit(tenant, workspace) {
+    try {
+        return JSON.parse(fs.readFileSync(commitFile(tenant, workspace), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/egress.d.ts

@@ -0,0 +1,75 @@
+/** `${NAME}` — the shape a secret reference takes everywhere in foldrun. */
+export declare const PLACEHOLDER: RegExp;
+/** The env var the pod reads to know it should send through a proxy. */
+export declare const EGRESS_ENV = "FOLDRUN_EGRESS";
+/** The placeholder name the platform's own model key travels under. */
+export declare const MODEL_KEY_NAME = "FOLDRUN_MODEL_KEY";
+/**
+ * The address a request to `target` should actually be sent to. With no
+ * proxy configured, the target itself — every caller works unchanged on a
+ * machine with no worker, which is the CLI and every test.
+ */
+export declare function viaEgress(egress: string | undefined | null, target: string): string;
+/** The names referenced by placeholders in a string. */
+export declare function placeholderNames(text: string): string[];
+/** Replace the placeholders in `text` whose names `values` knows. Unknown
+ *  names stay literal, so a wrong grant fails loudly at the provider
+ *  instead of silently sending nothing. */
+export declare function substitutePlaceholders(text: string, values: Record<string, string>): string;
+/** The host a granted secret may be sent to. Compared case-insensitively;
+ *  a port is part of the host. */
+export declare function hostOf(url: string): string | null;
+/**
+ * What one step is allowed to send, and where. The runner builds this
+ * from the step's declared secrets and the hosts its tools and provider
+ * name; the proxy enforces it per request.
+ */
+export interface EgressGrant {
+    /** Secret name → the hosts that secret may be substituted for. */
+    secrets: Record<string, {
+        value: string;
+        hosts: string[];
+    }>;
+}
+export interface EgressLease {
+    /** The base the pod sends through: `http://…/e/<token>`. */
+    url: string;
+    /** The grant is finished being built — publish it. The runner keeps
+     *  adding grants after the lease exists (the model key's host needs the
+     *  lease URL first), so a store that is not this process's memory has
+     *  to be told when the grant is complete. Call before every attempt. */
+    commit(): Promise<void>;
+    /** One line per request, for the run trace. Drained by the runner. */
+    drainLog(): Promise<string[]>;
+    /** The step is over: the lease is void and its values are dropped. */
+    release(): Promise<void>;
+}
+/**
+ * The seam the platform fills. `null` from `lease` (or no `egress` at all)
+ * means "no proxy here" and the runner falls back to materialising, exactly
+ * as it always did.
+ */
+export interface EgressHooks {
+    lease(args: {
+        tenant: string;
+        runId: string;
+        grant: EgressGrant;
+    }): Promise<EgressLease | null>;
+}
+/** Strip a header set of the proxy's own and hop-by-hop headers. */
+export declare const HOP_BY_HOP: Set<string>;
+/**
+ * A model env (the SDK's ANTHROPIC_* variables) rewritten to send through
+ * a lease: the base URL goes via the proxy, and whichever credential is
+ * set becomes the `${FOLDRUN_MODEL_KEY}` placeholder — the SDK only ever
+ * puts it in a header, and the proxy fills it for that one host. Provider
+ * headers that carried a secret's value get the value swapped back for
+ * its `${NAME}`, so the pod holds the name and the proxy holds the value.
+ * Adds the grants it needs to `grant`. Pure apart from that.
+ */
+export declare function proxyModelEnv(env: Record<string, string | undefined>, leaseUrl: string, grant: EgressGrant, knownSecrets?: Record<string, string>, name?: string): Record<string, string | undefined>;
+/** Put the `${NAME}` back where a known secret's value sits in `text`,
+ *  granting the name to `host`. Longest values first, so one that contains
+ *  another is replaced whole. */
+export declare function unsubstitute(text: string, knownSecrets: Record<string, string>, host: string, grant: EgressGrant): string;
+export declare function addGrant(grant: EgressGrant, name: string, value: string, host: string): void;

package/dist/src/egress.js

@@ -0,0 +1,133 @@
+// Egress: the run sandbox never holds a credential it only ever puts in a
+// header.
+//
+// Until now a step's secrets were decrypted host-side and copied into the
+// sandbox as environment variables. The model never saw a value — only the
+// names — but every program in the pod could read them: a script tool, a
+// bash grant, a dependency `runtime:` installed. The pod was the blast
+// radius, and the credential was inside it.
+//
+// The egress proxy moves the credential to the boundary. The pod is handed
+// a per-step address (`http://<worker>/e/<lease>`) and a set of
+// placeholders (`${RESEND_API_KEY}`), and sends every API request through
+// that address with the placeholder still in the header. The worker holds
+// the lease, swaps the placeholder for the value on the way out — for the
+// host that secret was granted to, and no other — forwards the request, and
+// streams the answer back. The value exists in the worker's memory and on
+// the wire to the provider. Never in the pod.
+//
+// Three consumers, in the pod:
+//   - the http tools (api-tools.ts): every declared API
+//   - the translator (translator.ts): the model key, for Chat Completions
+//     and Responses providers
+//   - the Agent SDK itself, for Anthropic-shaped providers: its base URL is
+//     pointed through the proxy and its key IS the placeholder
+//
+// Script tools are the exception, on purpose: a script reads secrets from
+// its environment and may need the real value in process (a browser seeding
+// cookies, an ssh key). A step that grants such a script materialises its
+// secrets into the pod as before, and the run record says so. A script that
+// declares `secrets: proxied` in its tool file gets the placeholders and
+// `FOLDRUN_EGRESS` instead, and sends through the proxy like everything
+// else.
+//
+// This file is the vocabulary both sides share. The server is the
+// platform's (it needs a long-lived process and a Service); the pod side is
+// here in core, because it is what the runner image runs.
+/** `${NAME}` — the shape a secret reference takes everywhere in foldrun. */
+export const PLACEHOLDER = /\$\{([A-Z][A-Z0-9_]*)\}/g;
+/** The env var the pod reads to know it should send through a proxy. */
+export const EGRESS_ENV = "FOLDRUN_EGRESS";
+/** The placeholder name the platform's own model key travels under. */
+export const MODEL_KEY_NAME = "FOLDRUN_MODEL_KEY";
+/**
+ * The address a request to `target` should actually be sent to. With no
+ * proxy configured, the target itself — every caller works unchanged on a
+ * machine with no worker, which is the CLI and every test.
+ */
+export function viaEgress(egress, target) {
+    if (!egress)
+        return target;
+    return `${egress.replace(/\/+$/, "")}/${target}`;
+}
+/** The names referenced by placeholders in a string. */
+export function placeholderNames(text) {
+    const out = new Set();
+    for (const m of text.matchAll(PLACEHOLDER))
+        out.add(m[1]);
+    return [...out];
+}
+/** Replace the placeholders in `text` whose names `values` knows. Unknown
+ *  names stay literal, so a wrong grant fails loudly at the provider
+ *  instead of silently sending nothing. */
+export function substitutePlaceholders(text, values) {
+    return text.replace(PLACEHOLDER, (whole, name) => (name in values ? values[name] : whole));
+}
+/** The host a granted secret may be sent to. Compared case-insensitively;
+ *  a port is part of the host. */
+export function hostOf(url) {
+    try {
+        return new URL(url).host.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+/** Strip a header set of the proxy's own and hop-by-hop headers. */
+export const HOP_BY_HOP = new Set([
+    "connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer",
+    "transfer-encoding", "upgrade", "host", "content-length",
+]);
+const ANTHROPIC_DEFAULT_BASE = "https://api.anthropic.com";
+/**
+ * A model env (the SDK's ANTHROPIC_* variables) rewritten to send through
+ * a lease: the base URL goes via the proxy, and whichever credential is
+ * set becomes the `${FOLDRUN_MODEL_KEY}` placeholder — the SDK only ever
+ * puts it in a header, and the proxy fills it for that one host. Provider
+ * headers that carried a secret's value get the value swapped back for
+ * its `${NAME}`, so the pod holds the name and the proxy holds the value.
+ * Adds the grants it needs to `grant`. Pure apart from that.
+ */
+export function proxyModelEnv(env, leaseUrl, grant, knownSecrets = {}, name = MODEL_KEY_NAME) {
+    const base = env.ANTHROPIC_BASE_URL || ANTHROPIC_DEFAULT_BASE;
+    const host = hostOf(base);
+    if (!host)
+        return env;
+    const out = { ...env, ANTHROPIC_BASE_URL: viaEgress(leaseUrl, base) };
+    const credentialKeys = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"];
+    for (const key of credentialKeys) {
+        const value = env[key];
+        if (typeof value === "string" && value.length) {
+            addGrant(grant, name, value, host);
+            out[key] = `\${${name}}`;
+        }
+    }
+    if (typeof env.ANTHROPIC_CUSTOM_HEADERS === "string") {
+        out.ANTHROPIC_CUSTOM_HEADERS = unsubstitute(env.ANTHROPIC_CUSTOM_HEADERS, knownSecrets, host, grant);
+    }
+    return out;
+}
+/** Put the `${NAME}` back where a known secret's value sits in `text`,
+ *  granting the name to `host`. Longest values first, so one that contains
+ *  another is replaced whole. */
+export function unsubstitute(text, knownSecrets, host, grant) {
+    let out = text;
+    const entries = Object.entries(knownSecrets).filter(([, v]) => v.length >= 8).sort((a, b) => b[1].length - a[1].length);
+    for (const [name, value] of entries) {
+        if (!out.includes(value))
+            continue;
+        out = out.split(value).join(`\${${name}}`);
+        addGrant(grant, name, value, host);
+    }
+    return out;
+}
+export function addGrant(grant, name, value, host) {
+    const h = host.toLowerCase();
+    const existing = grant.secrets[name];
+    if (existing) {
+        if (!existing.hosts.includes(h))
+            existing.hosts.push(h);
+    }
+    else
+        grant.secrets[name] = { value, hosts: [h] };
+}