summer-engine 4.0.0 → 4.3.0

package/dist/core/library-search.d.ts

@@ -98,12 +98,12 @@ export declare const searchLibraryInputSchema: z.ZodObject<{
     include_preview: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     query: string;
-    kinds?: ("template" | "tool" | "reference" | "skill" | "example" | "collection")[] | undefined;
+    kinds?: ("template" | "tool" | "skill" | "reference" | "example" | "collection")[] | undefined;
     limit?: number | undefined;
     include_preview?: boolean | undefined;
 }, {
     query: string;
-    kinds?: ("template" | "tool" | "reference" | "skill" | "example" | "collection")[] | undefined;
+    kinds?: ("template" | "tool" | "skill" | "reference" | "example" | "collection")[] | undefined;
     limit?: number | undefined;
     include_preview?: boolean | undefined;
 }>;

package/dist/core/ops/areas.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Where operations live and run, the part scripts/ needs too. No imports:
+ * scripts/validate-library loads this file as plain TypeScript to write the
+ * shell command of each tool a skill names.
+ */
+/**
+ * Areas with operations today: each is one `summer <area> <action>` command
+ * (src/cli/commands/ops.ts). CLI command words stay out of this list.
+ */
+export declare const CLI_AREAS: readonly ["team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing", "analytics", "experiments", "marketing", "content", "players", "economy", "inbox", "apps", "studio", "chats", "stories", "plugins", "engine", "account"];
+export declare function isLocalOp(op: string): boolean;

package/dist/core/ops/areas.js

@@ -0,0 +1,24 @@
+/**
+ * Where operations live and run, the part scripts/ needs too. No imports:
+ * scripts/validate-library loads this file as plain TypeScript to write the
+ * shell command of each tool a skill names.
+ */
+/**
+ * Areas with operations today: each is one `summer <area> <action>` command
+ * (src/cli/commands/ops.ts). CLI command words stay out of this list.
+ */
+export const CLI_AREAS = [
+    "team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing",
+    "analytics", "experiments", "marketing", "content", "players", "economy", "inbox", "apps", "studio", "chats", "stories",
+    "plugins", "engine", "account",
+];
+/**
+ * Operations that run in this package: everything in `engine`, the library
+ * (`docs`, apart from the Studio workflows, which are cloud), opening a
+ * page or an editor surface, docking an App in the editor, and uploading a
+ * local export. Everything else runs on the hosted server.
+ */
+const LOCAL_OPS = new Set(["docs.search", "docs.read", "docs.feedback", "docs.plan", "docs.engine_api", "studio.open", "apps.dock", "apps.publish_folder", "store.upload_file"]);
+export function isLocalOp(op) {
+    return op.startsWith("engine.") || LOCAL_OPS.has(op);
+}

package/dist/core/ops/catalog.d.ts

@@ -18,6 +18,10 @@ export interface CatalogEntry {
     legacy?: string[];
     /** The exact input JSON Schema (search results and describe carry it). */
     input?: Record<string, unknown>;
+    /** A cloud operation listed from the shipped catalog while no one is signed in: it runs after `summer login`. */
+    needsSignIn?: true;
+    /** Search words only, never printed: the library's topics for docs.search ("add multiplayer" is a how-to). */
+    topics?: string[];
 }
 /**
  * The operations this package runs (engine and local), from the shipped
@@ -32,6 +36,13 @@ export declare function localInputSchema(op: string): Record<string, unknown> |
  * A local operation in the contract's wire form (registry/schemas/operation.schema.json):
  * what ops.describe answers and what the contract test validates.
  */
+/**
+ * The operation when it is a real one (this package runs it, or the shipped
+ * catalog lists it), else null. Usage lines name an operation only through
+ * this, so a word someone typed (`summer engine my-secret-game`) never
+ * leaves the machine as an operation name.
+ */
+export declare function knownOp(op: string | null | undefined): string | null;
 export declare function localWireForm(op: string): Record<string, unknown> | null;
 /**
  * The first problem a JSON Schema's top level finds in an input: a missing

package/dist/core/ops/catalog.js

@@ -5,6 +5,7 @@ import { loadLibraryIndex } from "../library-search.js";
 import { PACKAGE_ROOT } from "../package-root.js";
 import { CONTRACT_VERSION, isLocalOp, legacyNames, LOCAL_RUNNERS, mcpNameOf, MIN_APPROVAL } from "./contract.js";
 import { ENGINE_SPLIT_OPS, engineOpDef, isSplitOp, splitInputSchema } from "./engine.js";
+import { shippedTitle } from "./public-catalog.js";
 /** A local tool's effect from its registry authority: scene edits and project files are writes. */
 function effectOf(authority) {
     if (authority?.publish)
@@ -26,7 +27,8 @@ function entryFor(op, toolName, tool, legacy) {
     const summary = def?.summary ?? (tool.summary ?? "").slice(0, 300);
     return {
         name: op,
-        title: def?.title ?? titleOf(summary, op),
+        // The hosted catalog's title when it has the op too (docs.search: "Search Summer docs", not "Search").
+        title: def?.title ?? shippedTitle(op) ?? titleOf(summary, op),
         summary,
         effect,
         approval: MIN_APPROVAL[effect],
@@ -67,9 +69,19 @@ export function localEntries() {
             continue;
         out.set(row.op, entryFor(row.op, toolName, tool, name));
     }
+    const docsSearch = out.get("docs.search");
+    if (docsSearch)
+        out.set("docs.search", { ...docsSearch, topics: libraryTopics() });
     entriesCache = [...out.values()];
     return entriesCache;
 }
+/** The words of every skill, template and example slug (multiplayer, fps, lighting...): what the library teaches. */
+function libraryTopics() {
+    const slugs = loadLibraryIndex()
+        .filter((entry) => entry.kind !== "tool" && entry.kind !== "reference")
+        .flatMap((entry) => entry.id.replace(/^[a-z]+\//, "").split("-"));
+    return [...new Set(slugs)].filter((word) => word.length > 2 && !/^\d/.test(word));
+}
 function descriptorSchema(toolName) {
     const record = loadLibraryIndex().find((candidate) => candidate.kind === "tool" && candidate.mcp_tool_name === toolName);
     const slug = record?.id.replace(/^tool\//, "");
@@ -95,6 +107,17 @@ export function localInputSchema(op) {
  * A local operation in the contract's wire form (registry/schemas/operation.schema.json):
  * what ops.describe answers and what the contract test validates.
  */
+/**
+ * The operation when it is a real one (this package runs it, or the shipped
+ * catalog lists it), else null. Usage lines name an operation only through
+ * this, so a word someone typed (`summer engine my-secret-game`) never
+ * leaves the machine as an operation name.
+ */
+export function knownOp(op) {
+    if (!op)
+        return null;
+    return localEntries().some((entry) => entry.name === op) || shippedTitle(op) !== undefined ? op : null;
+}
 export function localWireForm(op) {
     const entry = localEntries().find((candidate) => candidate.name === op);
     if (!entry)

package/dist/core/ops/cloud.d.ts

@@ -42,10 +42,18 @@ export declare function hostedCallFailure(error: unknown, call: {
 export declare function answerOfHosted(result: Record<string, unknown>): Answer;
 /** Runs a tool on the hosted v4 surface: the MCP's mounted client or the CLI's one-shot call. */
 export type HostedCall = (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/**
+ * ops.describe of a cloud operation when Summer's server could not answer it
+ * (no sign-in, no network): the operation from the shipped catalog, with a
+ * warning. Null when the catalog has no such operation; the failure stands.
+ */
+export declare function describeFromShipped(name: string, failure: Answer): Answer | null;
 /**
  * One ranked list of local and cloud operations for a plain-words query.
- * Local hits carry their input schema from the library descriptor. When the
- * hosted server cannot be asked, the local hits come back with a warning.
+ * Every cloud operation comes from the shipped catalog (public-catalog.ts),
+ * so search finds it signed out, marked needsSignIn; signed in, the server's
+ * own search lays its live rows over the shipped ones (and adds newer
+ * operations). Local hits carry their input schema from the library descriptor.
  */
 export declare function searchEverywhere(query: string, filters: {
     area?: string;

package/dist/core/ops/cloud.js

@@ -1,9 +1,10 @@
 import { defaultHostedConnectDependencies, hostedConnectFailure, HostedUnreachableError, httpStatusOf } from "../hosted-mcp.js";
 import { OAuthError, resolveMcpResourceUrl } from "../oauth.js";
 import { localEntries, localInputSchema } from "./catalog.js";
-import { errorAnswer, isLocalOp } from "./contract.js";
+import { errorAnswer, isLocalOp, resolveOpName } from "./contract.js";
+import { shippedCloudEntries, shippedWireForm } from "./public-catalog.js";
 import { withOutField } from "./save-files.js";
-import { scoreEntry, searchEntries } from "./search.js";
+import { searchEntries } from "./search.js";
 /**
  * The hosted Summer server's v4 surface: the same address with `?surface=v4`
  * (it keeps serving 3.x tools to every request that does not ask). Cloud
@@ -139,37 +140,59 @@ export function answerOfHosted(result) {
     }
     return result.isError === true ? errorAnswer("unavailable", first.slice(0, 300) || "The Summer server did not answer.") : { ok: true, status: "done", result: { text: first } };
 }
+/** Failures that mean Summer's server did not describe the operation, so the shipped catalog may. */
+const DID_NOT_ANSWER = new Set(["not_signed_in", "forbidden", "rate_limited", "unavailable"]);
+/**
+ * ops.describe of a cloud operation when Summer's server could not answer it
+ * (no sign-in, no network): the operation from the shipped catalog, with a
+ * warning. Null when the catalog has no such operation; the failure stands.
+ */
+export function describeFromShipped(name, failure) {
+    // The server's own answer stands (not_found: it no longer has the operation).
+    if (failure.ok || !DID_NOT_ANSWER.has(failure.error.code))
+        return null;
+    const operation = shippedWireForm(resolveOpName(name));
+    if (!operation)
+        return null;
+    const warning = failure.error.code === "not_signed_in"
+        ? "Not signed in: this is the catalog in this version; the operation runs after `summer login`."
+        : `Summer's server did not answer (${failure.error.message}); this is the catalog in this version.`;
+    return { ok: true, status: "done", result: { operation }, warnings: [warning] };
+}
+/** The warning when cloud operations come from the shipped catalog, and whether that is because no one is signed in. */
+function shippedReason(answer) {
+    if (!answer.ok && answer.error.code === "not_signed_in") {
+        return { warning: "Not signed in: cloud operations are listed from the catalog in this version and run after `summer login` (needsSignIn).", signedOut: true };
+    }
+    return { warning: `Cloud operations are listed from the catalog in this version; Summer's server did not search: ${answer.ok ? "no answer" : answer.error.message}`, signedOut: false };
+}
 /**
  * One ranked list of local and cloud operations for a plain-words query.
- * Local hits carry their input schema from the library descriptor. When the
- * hosted server cannot be asked, the local hits come back with a warning.
+ * Every cloud operation comes from the shipped catalog (public-catalog.ts),
+ * so search finds it signed out, marked needsSignIn; signed in, the server's
+ * own search lays its live rows over the shipped ones (and adds newer
+ * operations). Local hits carry their input schema from the library descriptor.
  */
 export async function searchEverywhere(query, filters, call, isDirect = () => false) {
-    const local = searchEntries(localEntries(), query, filters).map((entry) => ({
-        ...entry,
-        input: localInputSchema(entry.name) ?? { type: "object" },
-        mcpTool: entry.mcpTool && isDirect(entry.mcpTool) ? entry.mcpTool : undefined,
-    }));
-    let cloud = [];
-    let warning = null;
+    let live = [];
+    let reason = null;
     try {
-        const answer = answerOfHosted(await call("summer_search", { query, ...(filters.area ? { area: filters.area } : {}), limit: filters.limit }));
-        // The operations that save files take `out` here (save-files.ts), so their input shows it.
-        if (answer.ok && answer.status === "done") {
-            cloud = (answer.result.items ?? [])
-                .filter((entry) => !isLocalOp(entry.name))
-                .map((entry) => (entry.input ? { ...entry, input: withOutField(entry.name, entry.input) } : entry));
-        }
-        else if (!answer.ok)
-            warning = `Cloud operations were not searched: ${answer.error.message}`;
+        const answer = answerOfHosted(await call("summer_search", { query, ...(filters.area ? { area: filters.area } : {}), limit: 20 }));
+        if (answer.ok && answer.status === "done")
+            live = (answer.result.items ?? []).filter((entry) => !isLocalOp(entry.name));
+        else
+            reason = shippedReason(answer);
     }
     catch (error) {
-        warning = `Cloud operations were not searched: ${error instanceof Error ? error.message : String(error)}`;
-    }
-    const items = [...local, ...cloud]
-        .map((entry) => ({ entry, score: scoreEntry(entry, query) }))
-        .sort((a, b) => b.score - a.score)
-        .slice(0, filters.limit)
-        .map(({ entry }) => entry);
-    return { items, warning };
+        reason = shippedReason(hostedCallFailure(error, { op: "ops.search", read: true }));
+    }
+    const cloud = new Map(shippedCloudEntries().map((entry) => [entry.name, reason?.signedOut ? { ...entry, needsSignIn: true } : entry]));
+    // The operations that save files take `out` here (save-files.ts), so their input shows it.
+    for (const entry of live) {
+        cloud.set(entry.name, { ...cloud.get(entry.name), ...entry, ...(entry.input ? { input: withOutField(entry.name, entry.input) } : {}) });
+    }
+    const items = searchEntries([...localEntries(), ...cloud.values()], query, filters).map(({ topics: _topics, ...entry }) => isLocalOp(entry.name)
+        ? { ...entry, input: localInputSchema(entry.name) ?? { type: "object" }, mcpTool: entry.mcpTool && isDirect(entry.mcpTool) ? entry.mcpTool : undefined }
+        : entry);
+    return { items, warning: reason?.warning ?? null };
 }

package/dist/core/ops/contract.d.ts

@@ -1,3 +1,4 @@
+import { isLocalOp } from "./areas.js";
 /**
  * The Summer operation catalog, the part this package needs (contract 1).
  * Every Summer operation has one name (`area.action`), one effect, one
@@ -100,7 +101,7 @@ export declare function resolveOpName(name: string): string;
  * (apps.publish_folder reads a folder on disk; apps.publish takes files).
  */
 export declare const LOCAL_RUNNERS: Readonly<Record<string, string>>;
-export declare function isLocalOp(op: string): boolean;
+export { isLocalOp };
 /**
  * The local 3.x tools that run an operation here, first choice first: the
  * tool the op was renamed from before the tools merged into it.

package/dist/core/ops/contract.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { PACKAGE_ROOT } from "../package-root.js";
+import { isLocalOp } from "./areas.js";
 /**
  * The Summer operation catalog, the part this package needs (contract 1).
  * Every Summer operation has one name (`area.action`), one effect, one
@@ -65,22 +66,13 @@ export function resolveOpName(name) {
     const trimmed = name.trim();
     return legacyNames()[trimmed]?.op ?? trimmed;
 }
-/**
- * Operations that run in this package: everything in `engine`, the library
- * (`docs`, apart from the Studio workflows, which are cloud), opening a
- * page or an editor surface, docking an App in the editor, and uploading a
- * local export. Everything else runs on the hosted server.
- */
-const LOCAL_OPS = new Set(["docs.search", "docs.read", "docs.feedback", "docs.plan", "docs.engine_api", "studio.open", "apps.dock", "apps.publish_folder", "store.upload_file"]);
 /**
  * Local operations a 3.x tool runs although legacy-names.json maps that
  * tool to a cloud operation: the local-only input is its own operation
  * (apps.publish_folder reads a folder on disk; apps.publish takes files).
  */
 export const LOCAL_RUNNERS = { "apps.publish_folder": "summer_app_publish" };
-export function isLocalOp(op) {
-    return op.startsWith("engine.") || LOCAL_OPS.has(op);
-}
+export { isLocalOp };
 /**
  * The local 3.x tools that run an operation here, first choice first: the
  * tool the op was renamed from before the tools merged into it.

package/dist/core/ops/public-catalog.d.ts

@@ -0,0 +1,48 @@
+import type { CatalogEntry } from "./catalog.js";
+import { type Approval, type Effect } from "./contract.js";
+export interface PublicOperation {
+    name: string;
+    title: string;
+    summary: string;
+    effect: Effect;
+    approval: Approval;
+    permission: string;
+    provider: "cloud";
+    auth: string;
+    status: "stable" | "preview" | "deprecated";
+    since: string;
+    mcpTool: string;
+    direct: string[];
+    idempotencyKey?: "required" | "optional";
+    job?: {
+        typicalSeconds: number;
+    };
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+    legacy?: string[];
+    tags?: string[];
+    examples: Array<{
+        input: Record<string, unknown>;
+        note: string;
+    }>;
+    deprecated?: {
+        replacedBy: string;
+        after: string;
+    };
+}
+export interface PublicCatalog {
+    contract: number;
+    operations: PublicOperation[];
+    /** The operations the server leaves to this package (engine and local ones), with their 3.x names. */
+    localOperations: Array<{
+        name: string;
+        legacy: string[];
+    }>;
+}
+export declare function publicCatalog(): PublicCatalog;
+/** The cloud operations as search rows; the ones that save files show `out` in their input. */
+export declare function shippedCloudEntries(): CatalogEntry[];
+/** The catalog's title of an operation, for the local ones it lists too. */
+export declare function shippedTitle(op: string): string | undefined;
+/** One cloud operation as ops.describe answers it, from the shipped catalog; null when it has no such row. */
+export declare function shippedWireForm(op: string): Record<string, unknown> | null;

package/dist/core/ops/public-catalog.js

@@ -0,0 +1,56 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../package-root.js";
+import { CONTRACT_VERSION, isLocalOp } from "./contract.js";
+import { withOutField } from "./save-files.js";
+/**
+ * The hosted Summer server's public operation catalog, shipped in this
+ * package: registry/operations/public-catalog.json, a byte copy of the
+ * server's own file (`npm run sync:catalog`; `-- --check` fails when it is
+ * behind). Search and describe list every cloud operation from it with no
+ * sign-in; a signed-in search lays the server's live rows over it.
+ */
+const PUBLIC_CATALOG_FILE = join("registry", "operations", "public-catalog.json");
+let catalogCache = null;
+export function publicCatalog() {
+    if (catalogCache)
+        return catalogCache;
+    try {
+        catalogCache = JSON.parse(readFileSync(join(PACKAGE_ROOT, PUBLIC_CATALOG_FILE), "utf8"));
+    }
+    catch {
+        catalogCache = { contract: CONTRACT_VERSION, operations: [], localOperations: [] };
+    }
+    return catalogCache;
+}
+/** The cloud operations as search rows; the ones that save files show `out` in their input. */
+export function shippedCloudEntries() {
+    return publicCatalog()
+        .operations.filter((op) => !isLocalOp(op.name))
+        .map((op) => ({
+        name: op.name,
+        title: op.title,
+        summary: op.summary,
+        effect: op.effect,
+        approval: op.approval,
+        provider: "cloud",
+        status: op.status,
+        available: true,
+        ...(op.tags?.length ? { tags: op.tags } : {}),
+        ...(op.legacy?.length ? { legacy: op.legacy } : {}),
+        input: withOutField(op.name, op.input),
+    }));
+}
+/** The catalog's title of an operation, for the local ones it lists too. */
+export function shippedTitle(op) {
+    return publicCatalog().operations.find((candidate) => candidate.name === op)?.title;
+}
+/** One cloud operation as ops.describe answers it, from the shipped catalog; null when it has no such row. */
+export function shippedWireForm(op) {
+    const found = publicCatalog().operations.find((candidate) => candidate.name === op);
+    if (!found || isLocalOp(op))
+        return null;
+    // `direct` names the hosted profiles that list it as a tool; it says nothing here.
+    const { direct: _direct, ...wire } = found;
+    return { contract: CONTRACT_VERSION, ...wire, input: withOutField(op, found.input), needsSignIn: true };
+}

package/dist/core/ops/search.d.ts

@@ -1,7 +1,6 @@
 import type { CatalogEntry } from "./catalog.js";
 import type { Effect } from "./contract.js";
 export declare function words(text: string): string[];
-export declare function scoreEntry(entry: CatalogEntry, query: string): number;
 export declare function searchEntries(entries: readonly CatalogEntry[], query: string, filters: {
     area?: string;
     effect?: Effect;