@foldrun/core 0.3.0 → 0.5.0

package/dist/src/web-actions.d.ts

@@ -0,0 +1,91 @@
+import { WEB_ACTIONS, type WebAction } from "./providers.ts";
+export { WEB_ACTIONS, type WebAction };
+/** What the browse action can return — its `mode`. Kept equal to the tool's own
+ *  MODES by the platform's gallery test. */
+export declare const BROWSE_MODES: readonly ["text", "markdown", "html", "links", "meta", "table", "network", "screenshot", "pdf", "capture", "aria", "map", "crawl", "console", "vitals", "a11y", "diff", "feed", "webmcp", "react"];
+/** What the browse action can do in a page — its `actions` steps. Kept equal to
+ *  the tool's own ACTIONS by the platform's gallery test. */
+export declare const BROWSE_STEPS: readonly ["click", "dblclick", "rightclick", "hover", "check", "uncheck", "drag", "fill", "type", "press", "select", "wait", "goto", "screenshot", "pdf", "scroll", "paste", "upload", "download", "extract", "frame", "tab", "back", "forward", "reload", "focus", "clear", "highlight", "keyboard", "keydown", "keyup", "mouse", "wheel", "tap", "swipe", "clipboard", "eval", "get", "expect", "if", "mock", "unmock", "offline", "cookie", "localstorage", "sessionstorage", "viewport", "dialog", "solve", "pushstate", "insert", "webmcp", "login"];
+export interface ActionSupport {
+    /** live: callable today. planned: agreed and not built — naming it is an
+     *  error that says so, rather than a tool that does nothing. */
+    status: "live" | "planned";
+    /** How: which tool serves it, and for foldrun's own, with what. */
+    how: string;
+    /** Browse only. cdp: our code drives the browser, so every step and mode
+     *  works unless listed in `lacks`. api: the vendor runs the steps, and
+     *  `steps`/`modes` list what it has. */
+    via?: "cdp" | "api";
+    steps?: readonly string[];
+    modes?: readonly string[];
+    lacks?: readonly string[];
+    /** The vendor page the adapter was built from, and the day it was last
+     *  matched to it (YYYY-MM-DD). Absent on foldrun's own. */
+    docs?: string;
+    checked?: string;
+}
+export interface WebProvider {
+    name: string;
+    title: string;
+    actions: Partial<Record<WebAction, ActionSupport>>;
+}
+/** Ours: every action, and none of them with a second model in it. */
+export declare const FOLDRUN: WebProvider;
+/** Every provider and what it can do, foldrun first. Built from the vendor
+ *  lists so a vendor added there is here without a second edit. */
+export declare function webProviders(): WebProvider[];
+export declare function findWebProvider(name: string): WebProvider | undefined;
+/** The live providers for an action, foldrun first — for "these do" lines. */
+export declare function providersFor(action: WebAction): string[];
+export type ActionChoice = {
+    provider: WebProvider;
+    support: ActionSupport;
+    error?: undefined;
+} | {
+    provider?: undefined;
+    support?: undefined;
+    error: string;
+};
+/**
+ * Who does `action`. Unset is foldrun. A named provider must have the action
+ * live; anything else is an error naming the providers that do — the rule is
+ * "fix the file", never "we used ours instead".
+ */
+export declare function resolveWebAction(action: WebAction, name?: string | null): ActionChoice;
+/** Can this browser run this step, or return this mode? */
+export declare function browseSupports(support: ActionSupport, stepOrMode: string): boolean;
+/** The browsers that can run a step or mode — for the error when one cannot. */
+export declare function browsersFor(stepOrMode: string): string[];
+/** Vendor actions whose adapter has not been matched to the vendor's docs
+ *  within `days` — each as "provider action (checked …)". Empty is healthy.
+ *  The test that calls this is the rule "integrations follow the latest
+ *  docs" in a form CI can fail on. */
+export declare function staleIntegrations(today: string, days?: number): string[];
+/** The actions after search, fetch and browse. Those three are resolved by
+ *  providers.ts, which also knows the model providers that search. */
+export declare const NEWER_ACTIONS: readonly ["crawl", "map", "extract", "answer", "monitor"];
+type NewerAction = (typeof NEWER_ACTIONS)[number];
+export type ActionApiChoice = {
+    provider: null;
+    error?: undefined;
+} | {
+    provider: string;
+    secret: string;
+    host: string;
+    error?: undefined;
+} | {
+    provider: null;
+    error: string;
+};
+/**
+ * Who does one of the newer actions, and with which key: unset (or
+ * "foldrun") is ours and needs none; a name, or `{name, key: ${VAULT_NAME}}`
+ * for a key stored under another name, is that provider — if it has the
+ * action. The runner turns a provider into FOLDRUN_WEB_<ACTION>_VIA, the
+ * secret the step holds, and the one host that secret may reach.
+ */
+export declare function resolveActionApi(action: NewerAction, raw: unknown): ActionApiChoice;
+/** Every newer action in the agent's web: block that names a provider unable
+ *  to do it — the sentences resolveActionApi gives. Empty when all are unset
+ *  or answerable. */
+export declare function actionProblems(front: Record<string, unknown>): string[];

package/dist/src/web-actions.js

@@ -0,0 +1,199 @@
+// The web, as actions. One question answered in one place: which provider
+// can do which action, and what does foldrun do when none is named?
+//
+// An action is a call with a fixed input and a fixed output — search takes a
+// query and returns URLs, fetch takes a URL and returns the page — whoever
+// answers it. A provider is the list of actions it has an adapter for. foldrun
+// is a provider like any other, and the one used when `web: {<action>: …}` is
+// unset. A provider named for an action it cannot do is an error in `check`,
+// never a quiet fall back to ours: a fallback would bill and behave
+// differently from what the file says.
+//
+// Browse has a second level: inside a page, the steps and modes of
+// the browse action. A browser reached over CDP is driven by our own code, so it
+// takes every step and mode unless it is listed as lacking one; a vendor
+// that runs the steps itself would list the few it has.
+//
+// The vendor facts (endpoint, key, docs page, the date the adapter was last
+// matched to those docs) stay on SEARCH_APIS, FETCH_APIS and BROWSER_APIS in
+// providers.ts; this file reads them rather than restating them.
+import { SEARCH_APIS, FETCH_APIS, BROWSER_APIS, ACTION_APIS, WEB_ACTIONS, webConfig } from "./providers.js";
+export { WEB_ACTIONS };
+/** What the browse action can return — its `mode`. Kept equal to the tool's own
+ *  MODES by the platform's gallery test. */
+export const BROWSE_MODES = [
+    "text", "markdown", "html", "links", "meta", "table", "network", "screenshot", "pdf", "capture",
+    "aria", "map", "crawl", "console", "vitals", "a11y", "diff", "feed", "webmcp", "react",
+];
+/** What the browse action can do in a page — its `actions` steps. Kept equal to
+ *  the tool's own ACTIONS by the platform's gallery test. */
+export const BROWSE_STEPS = [
+    "click", "dblclick", "rightclick", "hover", "check", "uncheck", "drag", "fill", "type", "press", "select",
+    "wait", "goto", "screenshot", "pdf", "scroll", "paste", "upload", "download", "extract", "frame", "tab",
+    "back", "forward", "reload", "focus", "clear", "highlight", "keyboard", "keydown", "keyup", "mouse", "wheel",
+    "tap", "swipe", "clipboard", "eval", "get", "expect", "if", "mock", "unmock", "offline", "cookie",
+    "localstorage", "sessionstorage", "viewport", "dialog", "solve", "pushstate", "insert", "webmcp", "login",
+];
+/** Ours: every action, and none of them with a second model in it. */
+export const FOLDRUN = {
+    name: "foldrun",
+    title: "foldrun",
+    actions: {
+        search: { status: "live", how: "the account's own SearXNG" },
+        fetch: { status: "live", how: "one plain HTTP request in the sandbox" },
+        browse: { status: "live", how: "the account's browser pod", via: "cdp" },
+        crawl: { status: "live", how: "plain HTTP, same site, robots.txt honoured" },
+        map: { status: "live", how: "the site's sitemaps, else its links" },
+        extract: { status: "live", how: "selectors, or the page's own JSON-LD and OpenGraph — no model" },
+        answer: { status: "live", how: "search, read the top pages, rank the passages that answer — no model" },
+        monitor: { status: "live", how: "a page's lines or a query's results, against the last call, in state/" },
+    },
+};
+/** Every provider and what it can do, foldrun first. Built from the vendor
+ *  lists so a vendor added there is here without a second edit. */
+export function webProviders() {
+    const byName = new Map();
+    const add = (f, action, support) => {
+        const p = byName.get(f.name) ?? { name: f.name, title: f.title, actions: {} };
+        p.actions[action] = { ...support, ...(f.docs ? { docs: f.docs } : {}), ...(f.checked ? { checked: f.checked } : {}) };
+        byName.set(f.name, p);
+    };
+    for (const a of SEARCH_APIS)
+        add(a, "search", { status: "live", how: a.title });
+    for (const a of FETCH_APIS)
+        add(a, "fetch", { status: "live", how: a.title });
+    for (const a of BROWSER_APIS) {
+        add(a, "browse", { status: "live", how: a.title, via: "cdp", ...(a.lacks?.length ? { lacks: a.lacks } : {}) });
+    }
+    for (const [action, apis] of Object.entries(ACTION_APIS)) {
+        for (const a of apis)
+            add(a, action, { status: "live", how: a.title });
+    }
+    return [FOLDRUN, ...byName.values()];
+}
+/** The names a provider answers to, for lookups. */
+function aliasesOf(name) {
+    const all = [...SEARCH_APIS, ...FETCH_APIS, ...BROWSER_APIS, ...Object.values(ACTION_APIS).flat()];
+    return all.filter((a) => a.name === name).flatMap((a) => a.aliases ?? []);
+}
+export function findWebProvider(name) {
+    const key = name.trim().toLowerCase();
+    if (key === "" || key === "ours")
+        return FOLDRUN;
+    return webProviders().find((p) => p.name === key || aliasesOf(p.name).includes(key));
+}
+/** The live providers for an action, foldrun first — for "these do" lines. */
+export function providersFor(action) {
+    return webProviders().filter((p) => p.actions[action]?.status === "live").map((p) => p.name);
+}
+/**
+ * Who does `action`. Unset is foldrun. A named provider must have the action
+ * live; anything else is an error naming the providers that do — the rule is
+ * "fix the file", never "we used ours instead".
+ */
+export function resolveWebAction(action, name) {
+    const field = `web.${action}`;
+    const p = name == null ? FOLDRUN : findWebProvider(name);
+    if (!p) {
+        return { error: `${field}: ${name} — no provider by that name. These ${action}: ${providersFor(action).join(", ")}.` };
+    }
+    const s = p.actions[action];
+    if (!s) {
+        const live = providersFor(action);
+        return {
+            error: `${field}: ${p.name} does not ${action} here.` +
+                (live.length ? ` These do: ${live.join(", ")}.` : " No provider has it wired yet.") +
+                (FOLDRUN.actions[action]?.status === "live" ? " Unset uses foldrun." : ""),
+        };
+    }
+    if (s.status === "planned") {
+        const others = providersFor(action).filter((n) => n !== p.name);
+        return {
+            error: `${field}: ${p.title}'s own ${action} is not built yet` +
+                (others.length ? ` — name a provider that has it: ${others.join(", ")}.` : " and no provider has it wired either."),
+        };
+    }
+    return { provider: p, support: s };
+}
+/** Can this browser run this step, or return this mode? */
+export function browseSupports(support, stepOrMode) {
+    if (support.via === "cdp")
+        return !(support.lacks ?? []).includes(stepOrMode);
+    return (support.steps ?? []).includes(stepOrMode) || (support.modes ?? []).includes(stepOrMode);
+}
+/** The browsers that can run a step or mode — for the error when one cannot. */
+export function browsersFor(stepOrMode) {
+    return webProviders()
+        .filter((p) => p.actions.browse?.status === "live" && browseSupports(p.actions.browse, stepOrMode))
+        .map((p) => p.name);
+}
+/** Vendor actions whose adapter has not been matched to the vendor's docs
+ *  within `days` — each as "provider action (checked …)". Empty is healthy.
+ *  The test that calls this is the rule "integrations follow the latest
+ *  docs" in a form CI can fail on. */
+export function staleIntegrations(today, days = 90) {
+    const out = [];
+    const limit = Date.parse(today) - days * 86_400_000;
+    for (const p of webProviders()) {
+        if (p === FOLDRUN)
+            continue;
+        for (const [action, s] of Object.entries(p.actions)) {
+            if (!s || s.status !== "live")
+                continue;
+            if (!s.docs || !s.checked)
+                out.push(`${p.name} ${action} (no docs page or check date recorded)`);
+            else if (Date.parse(s.checked) < limit)
+                out.push(`${p.name} ${action} (checked ${s.checked})`);
+        }
+    }
+    return out;
+}
+/** The actions after search, fetch and browse. Those three are resolved by
+ *  providers.ts, which also knows the model providers that search. */
+export const NEWER_ACTIONS = ["crawl", "map", "extract", "answer", "monitor"];
+/**
+ * Who does one of the newer actions, and with which key: unset (or
+ * "foldrun") is ours and needs none; a name, or `{name, key: ${VAULT_NAME}}`
+ * for a key stored under another name, is that provider — if it has the
+ * action. The runner turns a provider into FOLDRUN_WEB_<ACTION>_VIA, the
+ * secret the step holds, and the one host that secret may reach.
+ */
+export function resolveActionApi(action, raw) {
+    const field = `web.${action}`;
+    if (raw === undefined || raw === null || raw === "")
+        return { provider: null };
+    let name;
+    let secret;
+    if (typeof raw === "string")
+        name = raw;
+    else if (typeof raw === "object" && !Array.isArray(raw) && typeof raw.name === "string") {
+        name = raw.name;
+        const key = raw.key;
+        if (key !== undefined) {
+            const m = typeof key === "string" ? /^\$\{([A-Z][A-Z0-9_]*)\}$/.exec(key.trim()) : null;
+            if (!m)
+                return { provider: null, error: `${field}.key must be a \${NAME} reference to a secret in the vault, not the key itself.` };
+            secret = m[1];
+        }
+    }
+    else {
+        return { provider: null, error: `${field}: takes a provider name, or a block with name: (and key: for your own vault name).` };
+    }
+    const choice = resolveWebAction(action, name);
+    if (choice.error !== undefined)
+        return { provider: null, error: choice.error };
+    if (choice.provider.name === "foldrun")
+        return { provider: null };
+    const api = ACTION_APIS[action].find((a) => a.name === choice.provider.name);
+    return { provider: api.name, secret: secret ?? api.secret, host: api.host };
+}
+/** Every newer action in the agent's web: block that names a provider unable
+ *  to do it — the sentences resolveActionApi gives. Empty when all are unset
+ *  or answerable. */
+export function actionProblems(front) {
+    const { raw } = webConfig(front);
+    return NEWER_ACTIONS.flatMap((a) => {
+        const e = resolveActionApi(a, raw[a]).error;
+        return e ? [e] : [];
+    });
+}

package/dist/src/webhook.d.ts

@@ -1,6 +1,13 @@
 /**
- * The install's secret key. Every derived token — flow hooks, git secrets —
- * hangs off this one value, so rotating it invalidates all of them together.
+ * The install's secret key. Every derived token — flow hooks, git secrets,
+ * approval links — hangs off this one value, so rotating it invalidates all
+ * of them together.
+ *
+ * The same material the vault encrypts with, created on first use. This used
+ * to fall back to the constant "foldrun-dev-install" until the vault lazily
+ * wrote `.secret-key`, which meant two things nobody wanted: every hook and
+ * approval token on a fresh install was computable from the source, and all
+ * of them silently changed the first time a secret was stored.
  */
 export declare function installKey(): string;
 export declare function hookGeneration(tenant: string, workspace: string, flow: string): number;
@@ -38,10 +45,19 @@ export declare function publicUrl(): string | null;
 export interface HookDelivery {
     t: string;
     flow: string;
-    outcome: "accepted" | "invalid-token" | "invalid-signature" | "not-webhook" | "no-flow" | "error";
+    /** `dropped` is a delivery that arrived, was authentic, and did not
+     *  become a run because the flow's own gates said one was enough —
+     *  a duplicate, a throttled burst, a quarantined flow. Distinct from
+     *  `accepted` so "why did nothing run" has an answer in the log, and
+     *  distinct from the refusals so nobody hunts for a bad token. */
+    outcome: "accepted" | "invalid-token" | "invalid-signature" | "not-webhook" | "no-flow" | "error" | "dropped";
     runId?: string;
     bytes?: number;
     detail?: string;
+    /** A run of refusals, collapsed: how many, and when the first came.
+     *  `t` is the latest. Absent means one. */
+    count?: number;
+    first?: string;
 }
 export declare function recordDelivery(tenant: string, workspace: string, delivery: HookDelivery): void;
 export declare function readDeliveries(tenant: string, workspace: string, limit?: number): HookDelivery[];

package/dist/src/webhook.js

@@ -3,22 +3,22 @@
 // per flow, and rotating FOLDRUN_SECRET_KEY invalidates every hook at once.
 import fs from "node:fs";
 import path from "node:path";
-import { dataRoot } from "./paths.js";
 import { workspaceDir } from "./store.js";
+import { installKeyMaterial } from "./secrets.js";
 import crypto from "node:crypto";
-const keyFile = () => path.join(dataRoot(), ".secret-key");
 /**
- * The install's secret key. Every derived token — flow hooks, git secrets —
- * hangs off this one value, so rotating it invalidates all of them together.
+ * The install's secret key. Every derived token — flow hooks, git secrets,
+ * approval links — hangs off this one value, so rotating it invalidates all
+ * of them together.
+ *
+ * The same material the vault encrypts with, created on first use. This used
+ * to fall back to the constant "foldrun-dev-install" until the vault lazily
+ * wrote `.secret-key`, which meant two things nobody wanted: every hook and
+ * approval token on a fresh install was computable from the source, and all
+ * of them silently changed the first time a secret was stored.
  */
 export function installKey() {
-    if (process.env.FOLDRUN_SECRET_KEY)
-        return process.env.FOLDRUN_SECRET_KEY;
-    if (fs.existsSync(keyFile()))
-        return fs.readFileSync(keyFile(), "utf8");
-    // secrets.ts creates this on first use; fall back to a fixed dev value so
-    // hook URLs stay stable before any secret has been set.
-    return "foldrun-dev-install";
+    return installKeyMaterial();
 }
 function hooksFile(tenant, workspace) {
     return path.join(workspaceDir(tenant, workspace), "hooks.json");
@@ -103,6 +103,10 @@ export function publicUrl() {
         return null;
     return raw.replace(/\/+$/, "");
 }
+/** What anyone can produce without the token or the signing secret. A run
+ *  of these collapses into one line, so a stranger's flood costs the log a
+ *  single entry and can never push an owner's real deliveries out of it. */
+const UNAUTHENTICATED = ["invalid-token", "invalid-signature"];
 function deliveriesFile(tenant, workspace) {
     return path.join(workspaceDir(tenant, workspace), "hook-deliveries.jsonl");
 }
@@ -111,6 +115,8 @@ export function recordDelivery(tenant, workspace, delivery) {
     const file = deliveriesFile(tenant, workspace);
     if (!fs.existsSync(path.dirname(file)))
         return; // no workspace, nothing to log against
+    if (UNAUTHENTICATED.includes(delivery.outcome) && collapseInto(file, delivery))
+        return;
     fs.appendFileSync(file, JSON.stringify(delivery) + "\n");
     // Bounded: compact to the newest KEEP when it doubles. Amortised cheap,
     // and a log that grows forever is a disk-full incident with a delay.
@@ -126,6 +132,39 @@ export function recordDelivery(tenant, workspace, delivery) {
         // compaction is best-effort; the append already landed
     }
 }
+/** Fold a refusal into the log's last line when that line is a refusal
+ *  too. The flow name is not part of the match: it comes from the URL, so
+ *  a flood that varies it would otherwise never collapse. True when folded. */
+function collapseInto(file, delivery) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const end = text.trimEnd();
+    const cut = end.lastIndexOf("\n") + 1;
+    let last;
+    try {
+        last = JSON.parse(end.slice(cut));
+    }
+    catch {
+        return false;
+    }
+    if (!UNAUTHENTICATED.includes(last.outcome))
+        return false;
+    const merged = {
+        ...delivery,
+        count: (last.count ?? 1) + 1,
+        first: last.first ?? last.t,
+        ...(last.detail === "more than one flow name" || last.flow !== delivery.flow ? { detail: "more than one flow name" } : {}),
+    };
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, end.slice(0, cut) + JSON.stringify(merged) + "\n");
+    fs.renameSync(tmp, file);
+    return true;
+}
 export function readDeliveries(tenant, workspace, limit = 20) {
     const file = deliveriesFile(tenant, workspace);
     if (!fs.existsSync(file))

package/index.ts

@@ -10,6 +10,7 @@
 // database, previews, share links, tenancy — lives in its own private package
 // and plugs in through platform.ts. Nothing here imports it.
 
+export * from "./src/layout.ts";
 export * from "./src/paths.ts";
 export * from "./src/store.ts";
 export * from "./src/starter.ts";
@@ -22,6 +23,7 @@ export * from "./src/model-probe.ts";
 export * from "./src/providers.ts";
 export * from "./src/translator.ts";
 export * from "./src/arrange.ts";
+export * from "./src/flow-patterns.ts";
 export * from "./src/completions.ts";
 export * from "./src/confine.ts";
 export * from "./src/platform.ts";
@@ -40,5 +42,6 @@ export * from "./src/notify.ts";
 export * from "./src/webhook.ts";
 export * from "./src/approvals.ts";
 export * from "./src/deploy.ts";
+export * from "./src/account.ts";
 export * from "./src/tar.ts";
 export * from "./src/git.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "Apache-2.0",
   "type": "module",
@@ -26,7 +26,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepare": "npm run build",
+    "prepare": "npm run build && (test ! -f .githooks/install.sh || sh .githooks/install.sh)",
     "prepublishOnly": "npm run build",
     "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test *.test.ts $(ls tests/*.test.ts | grep -v e2e)",
     "container": "FOLDRUN_CONTAINER_E2E=1 node scripts/ts-test.mjs tests/container-e2e.test.ts --test-timeout=600000",
@@ -36,13 +36,13 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.220",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.285",
     "gray-matter": "^4.0.3",
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22",
-    "typescript": "^5"
+    "@types/node": "^26",
+    "typescript": "^7"
   },
   "repository": {
     "type": "git",

package/src/account.ts

@@ -0,0 +1,149 @@
+// An account folder, read as the thing a deploy pushes.
+//
+// `readTree` answers the same question for one workspace: what, of the files
+// on disk, is source? This is that question one scope up — the account's own
+// AGENTS.md, the shared `library/`, and every workspace under `workspaces/` —
+// so `foldrun deploy` at an account root has one list to walk and one shape to
+// report, rather than three special cases written at the call site.
+//
+// Nothing here talks to a platform. It reads a directory and says what is in
+// it; who gets sent where is the CLI's business, because the endpoints differ
+// per part (a workspace deploys whole, a library file writes one at a time)
+// and that asymmetry belongs next to the fetch calls, not in here.
+
+import fs from "node:fs";
+import path from "node:path";
+import { readTree } from "./deploy.ts";
+import { LIBRARY_KINDS, type LibraryKind } from "./library.ts";
+import { detectLayout, listWorkspaceDirs, type Layout } from "./layout.ts";
+import type { DeployFile } from "./store.ts";
+
+export interface AccountWorkspace {
+  name: string;
+  dir: string;
+  files: DeployFile[];
+}
+
+export interface LibraryFile {
+  kind: LibraryKind;
+  /** Relative to the kind's directory — what the library API calls `path`. */
+  path: string;
+  content: string;
+}
+
+export interface AccountTree {
+  root: string;
+  /** The account-scope AGENTS.md, or null when there is none. */
+  agentsMd: string | null;
+  library: LibraryFile[];
+  workspaces: AccountWorkspace[];
+}
+
+/** Anything that is bookkeeping rather than source, at either scope. */
+const NOT_SOURCE = new Set([".foldrun", ".git", "node_modules", "runs", "outputs", ".DS_Store"]);
+
+function walkFiles(root: string, rel = ""): { path: string; content: string }[] {
+  const out: { path: string; content: string }[] = [];
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(root).sort();
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (NOT_SOURCE.has(entry)) continue;
+    const full = path.join(root, entry);
+    const next = rel ? `${rel}/${entry}` : entry;
+    try {
+      if (fs.lstatSync(full).isSymbolicLink()) continue;
+      if (fs.statSync(full).isDirectory()) out.push(...walkFiles(full, next));
+      else out.push({ path: next, content: fs.readFileSync(full, "utf8") });
+    } catch {
+      /* unreadable: not source */
+    }
+  }
+  return out;
+}
+
+/** The shared library under an account root, flattened to one list. */
+export function readLibraryTree(accountRoot: string): LibraryFile[] {
+  const out: LibraryFile[] = [];
+  for (const kind of LIBRARY_KINDS) {
+    const dir = path.join(accountRoot, "library", kind);
+    for (const f of walkFiles(dir)) {
+      // `.gitkeep` and friends keep an empty library directory in git and are
+      // not library entries: the write endpoint refuses a path with no known
+      // extension, so shipping one would fail the deploy over a placeholder.
+      if (f.path.split("/").some((seg) => seg.startsWith("."))) continue;
+      out.push({ kind, path: f.path, content: f.content });
+    }
+  }
+  return out;
+}
+
+/**
+ * Everything an account folder would push: its AGENTS.md, its library, and
+ * every workspace under it.
+ *
+ * `only` narrows it to one workspace — `foldrun deploy <name>` — and still
+ * carries the account scope, because a workspace deployed without the library
+ * its agents name is a workspace that fails on its first run.
+ */
+export function readAccountTree(accountRoot: string, only?: string): AccountTree {
+  const root = path.resolve(accountRoot);
+  const agentsMdFile = path.join(root, "AGENTS.md");
+  let agentsMd: string | null = null;
+  try {
+    agentsMd = fs.readFileSync(agentsMdFile, "utf8");
+  } catch {
+    /* an account with no AGENTS.md pushes none */
+  }
+  const names = listWorkspaceDirs(root).filter((n) => (only ? n === only : true));
+  if (only && names.length === 0) {
+    throw new Error(`no workspace "${only}" in ${root} — have: ${listWorkspaceDirs(root).join(", ") || "none"}`);
+  }
+  const wsRoot = path.join(root, "workspaces");
+  const legacy = path.join(root, "projects");
+  const base = fs.existsSync(wsRoot) ? wsRoot : legacy;
+  return {
+    root,
+    agentsMd,
+    library: readLibraryTree(root),
+    workspaces: names.map((name) => {
+      const dir = path.join(base, name);
+      return { name, dir, files: readTree(dir) };
+    }),
+  };
+}
+
+/**
+ * The account tree for wherever you are standing — an account root, a
+ * workspace inside one, or a flat workspace.
+ *
+ * A flat workspace is reported as an account of one whose root is its parent,
+ * which is exactly what `accountDir` and `libraryDir` already believe about
+ * it. So the deploy path has no branch for the old layout: it pushes one
+ * workspace and whatever library sits beside it, which is what it did before.
+ */
+export function accountTreeFrom(from: string, only?: string): { layout: Layout; tree: AccountTree } {
+  const layout = detectLayout(from);
+  if (layout.kind === "flat" || layout.kind === "empty") {
+    const dir = layout.workspaceDir!;
+    const name = path.basename(dir);
+    if (only && only !== name) throw new Error(`${dir} is a single workspace called "${name}", not "${only}"`);
+    return {
+      layout,
+      tree: {
+        root: layout.accountRoot,
+        // A flat workspace's AGENTS.md belongs to the workspace, not the
+        // account — pushing it as account scope would apply one desk's rules
+        // to every other desk in the installation.
+        agentsMd: null,
+        library: readLibraryTree(layout.accountRoot),
+        workspaces: [{ name, dir, files: readTree(dir) }],
+      },
+    };
+  }
+  const only2 = only ?? (layout.kind === "workspace-in-account" ? layout.workspace! : undefined);
+  return { layout, tree: readAccountTree(layout.accountRoot, only2) };
+}