@every-app/sdk 0.1.14 → 0.3.0-rc.1

package/dist/internal/appSettings.js

@@ -0,0 +1,374 @@
+/**
+ * What an app needs set before it works, and whether it is: the model
+ * behind "needs setup" wherever an app is shown (the gateway's home and
+ * Admin → Apps, `everyapp status`, `everyapp secret list`, the end of
+ * `everyapp deploy`, and what `everyapp configure <app>` walks through).
+ *
+ * A manifest declares three kinds of setting. An AI provider
+ * (`providers`) and a capability (`capabilities`) are the Gateway's: their
+ * keys and clients live on the Gateway Worker, set once for every app
+ * with `everyapp secret set <NAME>`. The app's own secrets (`secrets`)
+ * live on its Worker, set from its directory. Each declaration carries a
+ * need: required (the default; the app doesn't open until it is set),
+ * optional (the app opens, and the feature says what is missing where it
+ * is used), or a member of a named any-of group (the app opens once any
+ * member is set; only for an app that picks among the set members at run
+ * time). Each may say `why` it is needed and where it comes from
+ * (`docs`, an https URL); for providers and capabilities the registries
+ * here supply a default.
+ *
+ * Everything in this module is pure and tenant-neutral: a manifest ships
+ * in a release, and what is set is asked of the caller (`isSet`), which
+ * reads the Gateway's env, cf's secret list, or the registry's record of
+ * the app Worker's secret names.
+ */
+import { CATALOG, capabilitySettings, } from "./capabilities.js";
+import { isInstallOwnedGatewaySetting, isSettableGatewaySetting, } from "./gatewaySettings.js";
+import { remoteMcpAuthLabel, remoteMcpOf, remoteMcpSecretOf, } from "./remoteMcp.js";
+/** The need an entry declares; required unless it says otherwise. */
+export function needOf(entry) {
+    if (!entry)
+        return { kind: "required" };
+    if (typeof entry.anyOf === "string" && entry.anyOf.trim()) {
+        return { kind: "anyOf", group: entry.anyOf.trim() };
+    }
+    if (entry.optional === true)
+        return { kind: "optional" };
+    return { kind: "required" };
+}
+function needFields(entry) {
+    if (!entry || typeof entry !== "object")
+        return {};
+    const record = entry;
+    return {
+        ...(typeof record["why"] === "string" ? { why: record["why"] } : {}),
+        ...(typeof record["docs"] === "string" ? { docs: record["docs"] } : {}),
+        ...(typeof record["optional"] === "boolean"
+            ? { optional: record["optional"] }
+            : {}),
+        ...(typeof record["setup"] === "string" ? { setup: record["setup"] } : {}),
+        ...(typeof record["anyOf"] === "string" ? { anyOf: record["anyOf"] } : {}),
+    };
+}
+/** The providers the manifest lists, each as an entry whatever form it took. */
+export function providerEntries(manifest) {
+    return (manifest.providers ?? []).flatMap((entry) => {
+        if (typeof entry === "string")
+            return [{ id: entry }];
+        if (entry && typeof entry === "object" && typeof entry.id === "string") {
+            return [{ id: entry.id, ...needFields(entry) }];
+        }
+        return [];
+    });
+}
+/** The provider ids the manifest lists, in order. */
+export function providerIds(manifest) {
+    return providerEntries(manifest).map((entry) => entry.id);
+}
+/** The app's own secrets the manifest lists, each as an entry whatever form it took. */
+export function secretEntries(manifest) {
+    return (manifest.secrets ?? []).flatMap((entry) => {
+        if (typeof entry === "string")
+            return [{ name: entry }];
+        if (entry && typeof entry === "object" && typeof entry.name === "string") {
+            return [{ name: entry.name, ...needFields(entry) }];
+        }
+        return [];
+    });
+}
+/** The names of the app's own secrets, in order. */
+export function secretNames(manifest) {
+    return secretEntries(manifest).map((entry) => entry.name);
+}
+/**
+ * The Gateway settings an AI provider needs, the install's left out (set
+ * already). A catalog provider's names are settable by definition; a
+ * registered row's are its own, so they count too.
+ */
+function providerNames(capability) {
+    return capabilitySettings(capability).filter((name) => !isInstallOwnedGatewaySetting(name));
+}
+/** A capability's Gateway settings: what it needs, and what it also reads. */
+function capabilityNames(capability) {
+    const settable = (names) => names.filter((name) => isSettableGatewaySetting(name) && !isInstallOwnedGatewaySetting(name));
+    switch (capability.mode) {
+        case "api_key":
+            return { names: [...capabilitySettings(capability)], alsoReads: [] };
+        case "ai":
+            return { names: providerNames(capability), alsoReads: [] };
+        case "service":
+            return {
+                names: settable(capability.settings),
+                alsoReads: settable(capability.optionalSettings),
+            };
+        case "oauth_client": {
+            const names = [
+                capability.secrets.clientId,
+                ...(capability.secrets.clientSecret
+                    ? [capability.secrets.clientSecret]
+                    : []),
+            ];
+            const host = capability.hostSetting ? [capability.hostSetting] : [];
+            // An instance setting with a default is read when set; without one
+            // the provider has no origin until it is set.
+            return capability.defaultOrigin
+                ? { names, alsoReads: host }
+                : { names: [...names, ...host], alsoReads: [] };
+        }
+    }
+}
+/**
+ * Where a capability's key or client comes from, when the registry knows:
+ * an API-key provider's access page, or an OAuth client's console (a path
+ * on the default instance for a provider with no fixed host).
+ */
+function capabilityDocs(capability) {
+    switch (capability.mode) {
+        case "api_key":
+        case "ai":
+            return capability.docs;
+        case "oauth_client":
+            if (capability.console.startsWith("https://"))
+                return capability.console;
+            return capability.defaultOrigin
+                ? `${capability.defaultOrigin}${capability.console}`
+                : undefined;
+        case "service":
+            return undefined;
+    }
+}
+/** What a provider's entry says about getting its key: its hint, then each setting's own, named when there are several. */
+function providerHint(capability, names) {
+    if (capability.mode === "service" || capability.mode === "oauth_client") {
+        return {};
+    }
+    const details = capability.secrets ?? [];
+    const lines = [
+        ...(capability.hint ? [capability.hint] : []),
+        ...details
+            .filter((detail) => detail.hint && names.includes(detail.name))
+            .map((detail) => names.length > 1 ? `${detail.name}: ${detail.hint}` : detail.hint),
+    ];
+    return lines.length > 0 ? { hint: lines.join(" ") } : {};
+}
+function withNeed(setting, entry, defaults = {}) {
+    const docs = entry?.docs ?? defaults.docs;
+    // The registry's guide for a Gateway setting; the manifest's for the app's own secret.
+    const setup = setting.holder === "gateway" ? defaults.setup : entry?.setup;
+    return {
+        ...setting,
+        need: needOf(entry),
+        ...(entry?.why ? { why: entry.why } : {}),
+        ...(docs ? { docs } : {}),
+        ...(setup ? { setup } : {}),
+        ...(defaults.hint ? { hint: defaults.hint } : {}),
+    };
+}
+/**
+ * Every setting the manifest declares, in manifest order: its AI
+ * providers, its capabilities, the AI proxy's extra routes when `ai.routes`
+ * asks for any, then the app's own secrets. A provider or capability the
+ * gateway doesn't offer contributes nothing (the manifest validator refuses
+ * it elsewhere); so does a capability with nothing to set (`members`),
+ * which is always set. `lookup` is where ids are found: the catalog alone
+ * by default, or a gateway's registry with its registered rows.
+ */
+export function appSettings(manifest, lookup = CATALOG) {
+    const settings = [];
+    for (const entry of providerEntries(manifest)) {
+        const capability = lookup.get(entry.id);
+        if (capability?.mode !== "ai")
+            continue;
+        const names = providerNames(capability);
+        settings.push(withNeed({
+            kind: "provider",
+            id: entry.id,
+            label: capability.label,
+            holder: "gateway",
+            names,
+            alsoReads: [],
+        }, entry, {
+            docs: capability.docs,
+            setup: capability.setup,
+            ...providerHint(capability, names),
+        }));
+    }
+    for (const [id, entry] of Object.entries(manifest.capabilities ?? {})) {
+        const capability = lookup.get(id);
+        // An AI provider under `capabilities` is the validator's to refuse.
+        if (!capability || capability.mode === "ai")
+            continue;
+        const { names, alsoReads } = capabilityNames(capability);
+        settings.push(withNeed({
+            kind: "capability",
+            id,
+            label: capability.label,
+            holder: "gateway",
+            names,
+            alsoReads,
+        }, needFields(entry), {
+            docs: capabilityDocs(capability),
+            setup: capability.setup,
+            ...providerHint(capability, names),
+        }));
+    }
+    if (manifest.ai?.routes?.length) {
+        settings.push({
+            kind: "ai-routes",
+            id: "ai-routes",
+            label: "AI proxy routes",
+            holder: "gateway",
+            names: ["AI_PROXY_EXTRA_ROUTES"],
+            alsoReads: [],
+            need: { kind: "required" },
+            why: `Lets the app call ${manifest.ai.routes.join(", ")} through the AI proxy.`,
+            setup: "setup/openai.md",
+        });
+    }
+    const remote = remoteMcpOf(manifest);
+    if (remote) {
+        const secret = remoteMcpSecretOf(remote.auth);
+        if (secret) {
+            const label = typeof manifest.name === "string" && manifest.name.trim()
+                ? manifest.name.trim()
+                : "the MCP server";
+            settings.push({
+                kind: "remote-mcp",
+                id: secret,
+                label: `${label} credential`,
+                holder: "gateway",
+                names: [secret],
+                alsoReads: [],
+                need: { kind: "required" },
+                why: `What ${label} expects: ${remoteMcpAuthLabel(remote.auth)}. The Gateway sends it to ${remote.url} and nowhere else.`,
+                setup: "setup/remote-mcp.md",
+            });
+        }
+    }
+    for (const entry of secretEntries(manifest)) {
+        settings.push(withNeed({
+            kind: "secret",
+            id: entry.name,
+            label: entry.name,
+            holder: "app",
+            names: [entry.name],
+            alsoReads: [],
+        }, entry));
+    }
+    return settings;
+}
+/** Whether each name of `setting` is set: all → true, one unset → false, else unknown. */
+function settingIsSet(setting, isSet) {
+    let unknown = false;
+    for (const name of setting.names) {
+        const state = isSet(setting.holder, name);
+        if (state === false)
+            return false;
+        if (state === null)
+            unknown = true;
+    }
+    return unknown ? null : true;
+}
+/**
+ * Every setting against what is set. `isSet` answers per holder and name:
+ * true, false, or null when it can't tell (the registry never recorded
+ * the app Worker's secret names), which never blocks. An any-of group is
+ * met once any member is set; while none is and none is unknown, every
+ * member blocks.
+ */
+export function evaluateAppSettings(settings, isSet, options = {}) {
+    const evaluated = settings.map((setting) => {
+        const ready = options.readiness?.(setting);
+        return {
+            ...setting,
+            set: ready === undefined ? settingIsSet(setting, isSet) : ready,
+            blocking: false,
+        };
+    });
+    const groups = [];
+    for (const setting of evaluated) {
+        if (setting.need.kind !== "anyOf")
+            continue;
+        const group = setting.need.group;
+        let found = groups.find((each) => each.group === group);
+        if (!found) {
+            found = { group, members: [], met: false };
+            groups.push(found);
+        }
+        found.members.push(setting);
+    }
+    for (const group of groups) {
+        group.met = group.members.some((member) => member.set === true);
+        const unknown = group.members.some((member) => member.set === null);
+        if (!group.met && !unknown) {
+            for (const member of group.members)
+                member.blocking = true;
+        }
+    }
+    for (const setting of evaluated) {
+        if (setting.need.kind === "required" && setting.set === false) {
+            setting.blocking = true;
+        }
+    }
+    const unmet = evaluated.filter((setting) => setting.blocking);
+    return { ready: unmet.length === 0, settings: evaluated, groups, unmet };
+}
+/**
+ * What to run for an app that needs setup: `everyapp configure <app>`,
+ * which reads the app's manifest (from the registry, so it runs from
+ * anywhere), prompts for each unmet setting (one member of an any-of group
+ * is enough: it asks which) and sets them where they are held. Null when
+ * the app is ready. `cli` is how the operator runs everyapp (`pnpm
+ * everyapp` from a checkout). Scripts that set one name at a time use
+ * `everyapp secret set NAME [--app <id>]` instead.
+ *
+ * A provider app (`provider`: the gateway's own, with no Worker and no
+ * directory; `everyapp mcp on <id>`, an MCP app) has nothing to configure: its
+ * command is the `secret set` of its Gateway key (the first member of an
+ * unmet any-of group), as `mcp list` says it.
+ */
+export function setupCommand(report, { cli, appId, provider = false, }) {
+    if (report.unmet.length === 0)
+        return null;
+    if (!provider)
+        return { command: `${cli} configure ${appId}` };
+    const names = [];
+    const add = (setting) => {
+        for (const name of setting.names)
+            if (!names.includes(name))
+                names.push(name);
+    };
+    for (const setting of report.unmet) {
+        if (setting.need.kind === "required")
+            add(setting);
+    }
+    for (const group of report.groups) {
+        const first = group.members.find((member) => member.blocking);
+        if (first)
+            add(first);
+    }
+    return { command: `${cli} secret set ${names.join(" ")}` };
+}
+export function appSetupOf(report, options) {
+    const strip = ({ alsoReads: _alsoReads, ...setting }) => setting;
+    return {
+        ready: report.ready,
+        settings: report.settings.map(strip),
+        unmet: report.unmet.map(strip),
+        groups: report.groups.map((group) => ({
+            group: group.group,
+            met: group.met,
+            members: group.members.map((member) => member.id),
+        })),
+        command: options.withCommand === false ? null : setupCommand(report, options),
+    };
+}
+/** The provider registry's labels, for anything that names a provider to a person. */
+export function providerLabel(id, lookup = CATALOG) {
+    return lookup.get(id)?.label ?? id;
+}
+/** The capability `id` names in `lookup`, as an API-key provider, or undefined. */
+export function apiKeyCapabilityOf(id, lookup = CATALOG) {
+    const capability = lookup.get(id);
+    return capability?.mode === "api_key" ? capability : undefined;
+}