@apifuse/provider-sdk 2.2.0-beta.51 → 2.2.0-beta.53

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.53
+
+- Release candidate for main commit 40a916bac16bb2b2bbda7fc4a96132d10ca103bf.
+
+## 2.2.0-beta.52
+
+- Release candidate for main commit 6e64ae0ad2e735b3de0c115f5ea29517efcf4ff2.
+
 ## 2.2.0-beta.51
 
 - Release candidate for main commit a1269b0a7161618e5fc25e532aaa45de0efd632f.

package/dist/cli/migrate-operation-declaration.d.ts

@@ -1,4 +1,4 @@
-export type OperationDeclarationRefusalReason = "no_safety" | "safety_conflict" | "locale_key_conflict" | "connection_mode_conflict" | "execution_conflict" | "approval_conflict" | "non_literal" | "unsupported_member" | "factory_composed_operations" | "source_syntax" | "codemod_syntax" | "missing_english_locale" | "operation_id_unresolved" | "examples_conflict" | "locale_todo_conflict";
+export type OperationDeclarationRefusalReason = "no_safety" | "safety_conflict" | "locale_key_conflict" | "connection_mode_conflict" | "execution_conflict" | "approval_conflict" | "non_literal" | "unsupported_member" | "factory_composed_operations" | "source_syntax" | "codemod_syntax" | "missing_english_locale" | "operation_id_unresolved" | "examples_conflict" | "invalid_locale_key" | "locale_todo_conflict";
 export type OperationDeclarationRefusal = {
     readonly file: string;
     readonly operationKey: string;

package/dist/cli/migrate-operation-declaration.js

@@ -1,5 +1,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, relative, resolve } from "node:path";
+import { assertProviderLocaleKey } from "../i18n/keys.js";
+import { operationIdToLocaleNamespace } from "../i18n/operation-locale-namespace.js";
 const ts = await loadTypeScript();
 async function loadTypeScript() {
     try {
@@ -81,6 +83,10 @@ export function migrateOperationDeclaration(sourceText, fileName, options = {})
     }
     if (refusals.length > 0)
         return { status: "refused", refusals };
+    const invalidLocaleKey = findInvalidLocaleTodo(todos, fileName);
+    if (invalidLocaleKey !== undefined) {
+        return { status: "refused", refusals: [invalidLocaleKey] };
+    }
     if (edits.length === 0) {
         return {
             status: "unchanged",
@@ -221,7 +227,20 @@ function planOperationMigration(source, fileName, site, constObjects, constArray
         if (merged.insert !== undefined)
             addInsertion(insertions, "docs", merged.insert);
     }
-    const examples = planExamples(top.byName.get("inputExamples"), top.byName.get("examples"), fileName, site, source, constArrays, localeFiles);
+    const title = planTitleLocale(top.byName.get("title"), top.byName.get("titleKey"), docs.get("titleKey"), fileName, site, localeFiles);
+    if ("refusal" in title)
+        return title;
+    const localeNamespace = top.byName.get("inputExamples") === undefined
+        ? { namespace: site.operationKey }
+        : resolveOperationLocaleNamespace([
+            top.byName.get("titleKey"),
+            docs.get("titleKey"),
+            top.byName.get("descriptionKey"),
+            docs.get("descriptionKey"),
+        ], fileName, site);
+    if ("refusal" in localeNamespace)
+        return localeNamespace;
+    const examples = planExamples(top.byName.get("inputExamples"), top.byName.get("examples"), fileName, site, source, constArrays, localeFiles, localeNamespace.namespace);
     if ("refusal" in examples)
         return examples;
     const edits = [...examples.edits];
@@ -245,7 +264,66 @@ function planOperationMigration(source, fileName, site, constObjects, constArray
         if (!edits.some((existing) => rangesOverlap(existing, edit)))
             edits.push(edit);
     }
-    return { edits, localeTodos: examples.localeTodos };
+    return { edits, localeTodos: [...title.localeTodos, ...examples.localeTodos] };
+}
+function planTitleLocale(title, flatTitleKey, nestedTitleKey, fileName, site, localeFiles) {
+    if (title === undefined)
+        return { localeTodos: [] };
+    const originalProse = literalString(title.initializer);
+    if (originalProse === undefined) {
+        return nonLiteral(fileName, site.operationKey, "title must be a string literal so its authored prose can be preserved in the English locale catalog.");
+    }
+    if (!site.operationIdProven) {
+        return {
+            refusal: refusal(fileName, site.operationKey, "operation_id_unresolved", "title requires an exact operation id proven from a static operations map."),
+        };
+    }
+    if (!localeFiles.includes("locales/en.json")) {
+        return {
+            refusal: refusal(fileName, site.operationKey, "missing_english_locale", "title cannot be migrated because locales/en.json does not exist."),
+        };
+    }
+    let selectedTitleKey = flatTitleKey ?? nestedTitleKey;
+    if (flatTitleKey !== undefined && nestedTitleKey !== undefined) {
+        const same = equivalentLiteral(flatTitleKey.initializer, nestedTitleKey.initializer);
+        if (same === undefined) {
+            return nonLiteral(fileName, site.operationKey, "titleKey must be literal when both top-level and nested declarations exist.");
+        }
+        if (!same) {
+            return {
+                refusal: refusal(fileName, site.operationKey, "locale_key_conflict", "Top-level titleKey conflicts with nested titleKey."),
+            };
+        }
+        selectedTitleKey = flatTitleKey;
+    }
+    const explicitTitleKey = selectedTitleKey === undefined ? undefined : literalString(selectedTitleKey.initializer);
+    if (selectedTitleKey !== undefined && explicitTitleKey === undefined) {
+        return nonLiteral(fileName, site.operationKey, "titleKey must be a string literal so the title locale destination is provable.");
+    }
+    let selectedTitleLocaleKey;
+    if (explicitTitleKey !== undefined) {
+        selectedTitleLocaleKey = explicitTitleKey;
+    }
+    else {
+        try {
+            selectedTitleLocaleKey = `operations.${operationIdToLocaleNamespace(site.operationKey)}.title`;
+        }
+        catch (error) {
+            return {
+                refusal: invalidLocaleKeyRefusal(fileName, site.operationKey, `operations.${site.operationKey}.title`, error),
+            };
+        }
+    }
+    return {
+        localeTodos: [
+            {
+                localeFile: "locales/en.json",
+                operationKey: site.operationKey,
+                key: selectedTitleLocaleKey,
+                originalProse,
+            },
+        ],
+    };
 }
 function resolveRiskClass(top, annotations, toolRouter, fileName, operationKey) {
     const topRisk = top.get("riskClass");
@@ -381,7 +459,7 @@ function mergeFlatAndNested(field, flat, nested, fileName, operationKey, source,
     }
     return {};
 }
-function planExamples(inputExamples, existingExamples, fileName, site, source, constArrays, localeFiles) {
+function planExamples(inputExamples, existingExamples, fileName, site, source, constArrays, localeFiles, localeNamespace) {
     if (inputExamples === undefined)
         return { edits: [], localeTodos: [] };
     if (existingExamples !== undefined) {
@@ -440,7 +518,7 @@ function planExamples(inputExamples, existingExamples, fileName, site, source, c
         if (scenarioProse === undefined) {
             return nonLiteral(fileName, site.operationKey, `inputExamples[${index}].scenario must be a string literal.`);
         }
-        const scenarioKey = `operations.${site.operationKey}.examples.${index}.scenario`;
+        const scenarioKey = `operations.${localeNamespace}.examples.${index}.scenario`;
         edits.push(replaceExampleLocaleMember(scenario, "scenarioKey", scenarioKey, source));
         for (const localeFile of localeFiles) {
             todos.push({
@@ -456,7 +534,7 @@ function planExamples(inputExamples, existingExamples, fileName, site, source, c
             if (rationaleProse === undefined) {
                 return nonLiteral(fileName, site.operationKey, `inputExamples[${index}].rationale must be a string literal.`);
             }
-            const rationaleKey = `operations.${site.operationKey}.examples.${index}.rationale`;
+            const rationaleKey = `operations.${localeNamespace}.examples.${index}.rationale`;
             edits.push(replaceExampleLocaleMember(rationale, "rationaleKey", rationaleKey, source));
             for (const localeFile of localeFiles) {
                 todos.push({
@@ -470,6 +548,34 @@ function planExamples(inputExamples, existingExamples, fileName, site, source, c
     }
     return { edits, localeTodos: todos };
 }
+function resolveOperationLocaleNamespace(members, fileName, site) {
+    const authoredNamespaces = new Set();
+    for (const member of members) {
+        const localeKey = literalString(member?.initializer);
+        if (localeKey === undefined)
+            continue;
+        const segments = localeKey.split(".");
+        if (segments[0] === "operations" && segments[1] !== undefined) {
+            authoredNamespaces.add(segments[1]);
+        }
+    }
+    if (authoredNamespaces.size > 1) {
+        return {
+            refusal: refusal(fileName, site.operationKey, "locale_key_conflict", `Operation titleKey and descriptionKey declarations use different locale namespaces: ${[...authoredNamespaces].join(", ")}.`),
+        };
+    }
+    const authored = authoredNamespaces.values().next().value;
+    if (authored !== undefined)
+        return { namespace: authored };
+    try {
+        return { namespace: operationIdToLocaleNamespace(site.operationKey) };
+    }
+    catch (error) {
+        return {
+            refusal: invalidLocaleKeyRefusal(fileName, site.operationKey, `operations.${site.operationKey}.examples`, error),
+        };
+    }
+}
 function replaceExampleLocaleMember(member, newName, localeKey, source) {
     return {
         start: member.property.getStart(source),
@@ -1049,6 +1155,21 @@ function firstSyntaxError(source) {
 function refusal(file, operationKey, reason, detail) {
     return { file, operationKey, reason, detail };
 }
+function findInvalidLocaleTodo(todos, fileName) {
+    for (const todo of todos) {
+        try {
+            assertProviderLocaleKey(todo.key);
+        }
+        catch (error) {
+            return invalidLocaleKeyRefusal(fileName, todo.operationKey, todo.key, error);
+        }
+    }
+    return undefined;
+}
+function invalidLocaleKeyRefusal(fileName, operationKey, localeKey, error) {
+    const validatorDetail = error instanceof Error ? error.message : String(error);
+    return refusal(fileName, operationKey, "invalid_locale_key", `Refusing to write invalid provider locale key ${JSON.stringify(localeKey)}: ${validatorDetail}`);
+}
 function nonLiteral(fileName, operationKey, detail) {
     return {
         refusal: refusal(fileName, operationKey, "non_literal", detail),
@@ -1088,6 +1209,9 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
     if (refusals.length > 0) {
         return { status: "refused", providerRoot, refusals };
     }
+    for (const [path, code] of renderLocaleCatalogWrites(providerRoot, todos)) {
+        pendingWrites.set(path, code);
+    }
     if (pendingWrites.size === 0) {
         return {
             status: "unchanged",
@@ -1122,6 +1246,89 @@ export function renderLocaleTodoSidecar(todos) {
     }
     return `${JSON.stringify({ schemaVersion: 1, localeFiles }, null, 2)}\n`;
 }
+function renderLocaleCatalogWrites(providerRoot, todos) {
+    const todosByFile = new Map();
+    for (const todo of todos) {
+        const fileTodos = todosByFile.get(todo.localeFile) ?? [];
+        fileTodos.push(todo);
+        todosByFile.set(todo.localeFile, fileTodos);
+    }
+    const englishPath = "locales/en.json";
+    const englishTodos = todosByFile.get(englishPath);
+    if (englishTodos === undefined)
+        return new Map();
+    const english = readLocaleCatalog(join(providerRoot, englishPath));
+    applyLocaleTodos(english, englishTodos);
+    const writes = new Map([
+        [join(providerRoot, englishPath), renderCanonicalLocaleCatalog(english)],
+    ]);
+    for (const [localeFile, fileTodos] of todosByFile) {
+        if (localeFile === englishPath)
+            continue;
+        const catalog = readLocaleCatalog(join(providerRoot, localeFile));
+        applyLocaleTodos(catalog, fileTodos);
+        writes.set(join(providerRoot, localeFile), renderCanonicalLocaleCatalog(reorderLikeReference(english, catalog)));
+    }
+    return writes;
+}
+function readLocaleCatalog(path) {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    if (!isRecord(value))
+        throw new Error(`${path} must contain a JSON object.`);
+    return value;
+}
+function applyLocaleTodos(catalog, todos) {
+    for (const todo of todos) {
+        const segments = todo.key.split(".");
+        const leaf = segments.pop();
+        if (leaf === undefined)
+            continue;
+        let cursor = catalog;
+        for (const segment of segments) {
+            const child = cursor[segment];
+            if (isRecord(child)) {
+                cursor = child;
+                continue;
+            }
+            const created = {};
+            cursor[segment] = created;
+            cursor = created;
+        }
+        cursor[leaf] = todo.originalProse;
+    }
+}
+/** Match provider-contract's canonical locale serialization exactly. */
+function renderCanonicalLocaleCatalog(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/**
+ * Put shared keys first in English order, then retain locale-only authored order.
+ * Arrays keep their shape and use the English item at the same index as a reference.
+ */
+function reorderLikeReference(reference, value) {
+    if (Array.isArray(value)) {
+        const referenceArray = Array.isArray(reference) ? reference : [];
+        return value.map((item, index) => reorderLikeReference(referenceArray[index], item));
+    }
+    if (!isRecord(value))
+        return value;
+    const referenceRecord = isRecord(reference) ? reference : {};
+    const ordered = {};
+    for (const key of Object.keys(referenceRecord)) {
+        if (Object.hasOwn(value, key)) {
+            ordered[key] = reorderLikeReference(referenceRecord[key], value[key]);
+        }
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (!Object.hasOwn(ordered, key)) {
+            ordered[key] = reorderLikeReference(Object.hasOwn(referenceRecord, key) ? referenceRecord[key] : undefined, child);
+        }
+    }
+    return ordered;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function findLocaleTodoConflict(todos) {
     const values = new Map();
     for (const todo of todos) {
@@ -1170,6 +1377,8 @@ function collectLocaleFiles(root) {
 }
 function buildOperationIdIndex(sourceFiles) {
     const result = new Map();
+    const idsByPath = new Map();
+    const ambiguousBindingsByPath = new Map();
     const sources = new Map();
     for (const path of sourceFiles) {
         const source = parseSource(path, readFileSync(path, "utf8"));
@@ -1178,12 +1387,38 @@ function buildOperationIdIndex(sourceFiles) {
     }
     const record = (path, binding, operationId) => {
         const map = result.get(path) ?? new Map();
-        const previous = map.get(binding);
-        if (previous === undefined || previous === operationId)
-            map.set(binding, operationId);
-        else
+        const ids = idsByPath.get(path) ?? new Map();
+        const ambiguousBindings = ambiguousBindingsByPath.get(path) ?? new Set();
+        // An operation id is usable only when it identifies exactly one binding.
+        // Keep an explicit null marker for an ambiguous id so a later occurrence
+        // cannot accidentally make it usable again.
+        const previousBinding = ids.get(operationId);
+        if (ids.has(operationId)) {
+            if (previousBinding !== undefined &&
+                previousBinding !== null &&
+                previousBinding !== binding) {
+                map.delete(previousBinding);
+                map.delete(binding);
+                ambiguousBindings.add(previousBinding);
+                ambiguousBindings.add(binding);
+                ids.set(operationId, null);
+            }
+        }
+        else {
+            ids.set(operationId, binding);
+        }
+        // A binding registered under two different ids is likewise ambiguous.
+        const previousId = map.get(binding);
+        if (previousId !== undefined && previousId !== operationId) {
             map.delete(binding);
+            ambiguousBindings.add(binding);
+        }
+        else if (!ambiguousBindings.has(binding) && ids.get(operationId) === binding) {
+            map.set(binding, operationId);
+        }
         result.set(path, map);
+        idsByPath.set(path, ids);
+        ambiguousBindingsByPath.set(path, ambiguousBindings);
     };
     for (const [path, source] of sources) {
         const imports = collectImports(source, path, sources);
@@ -1206,9 +1441,92 @@ function buildOperationIdIndex(sourceFiles) {
                     record(imported.path, imported.exportedName, operationId);
             }
         }
+        // Some providers keep their operation registry in a same-file const with
+        // an arbitrary name (for example, `companionsOperations`). This scan is
+        // deliberately ID-only: it accepts only static object members whose value
+        // is a same-file operation binding, and never evaluates spreads, factories,
+        // or imported values.
+        const operationBindings = collectModuleOperationBindings(source);
+        const importedBindings = collectImportedBindingNames(source);
+        for (const entry of collectStaticOperationRegistryEntries(source, operationBindings)) {
+            if (importedBindings.has(entry.binding))
+                continue;
+            record(path, entry.binding, entry.operationId);
+        }
     }
     return result;
 }
+function collectModuleOperationBindings(source) {
+    const bindings = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined)
+                continue;
+            const initializer = unwrapExpression(declaration.initializer);
+            if (initializer !== undefined &&
+                ts.isCallExpression(initializer) &&
+                isOperationHelperCall(initializer)) {
+                bindings.add(declaration.name.text);
+            }
+        }
+    }
+    return bindings;
+}
+function collectImportedBindingNames(source) {
+    const bindings = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const clause = statement.importClause;
+        if (clause?.name !== undefined)
+            bindings.add(clause.name.text);
+        const named = clause?.namedBindings;
+        if (named === undefined)
+            continue;
+        if (ts.isNamespaceImport(named)) {
+            bindings.add(named.name.text);
+            continue;
+        }
+        for (const element of named.elements)
+            bindings.add(element.name.text);
+    }
+    return bindings;
+}
+function collectStaticOperationRegistryEntries(source, operationBindings) {
+    const entries = [];
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined)
+                continue;
+            const object = unwrapExpression(declaration.initializer);
+            if (object === undefined || !ts.isObjectLiteralExpression(object))
+                continue;
+            for (const property of object.properties) {
+                if (ts.isSpreadAssignment(property))
+                    continue;
+                const name = property.name;
+                if (name === undefined || (!ts.isIdentifier(name) && !ts.isStringLiteral(name)))
+                    continue;
+                const value = propertyValue(property);
+                const binding = unwrapExpression(value);
+                if (binding === undefined || !ts.isIdentifier(binding))
+                    continue;
+                if (!operationBindings.has(binding.text))
+                    continue;
+                entries.push({ operationId: name.text, binding: binding.text });
+            }
+        }
+    }
+    return entries;
+}
 function collectImports(source, containingPath, sources) {
     const imports = new Map();
     for (const statement of source.statements) {

package/dist/i18n/operation-locale-namespace.d.ts

@@ -0,0 +1,2 @@
+/** Canonical locale-catalog namespace for a URL-safe provider operation id. */
+export declare function operationIdToLocaleNamespace(operationId: string): string;

package/dist/i18n/operation-locale-namespace.js

@@ -0,0 +1,7 @@
+import { assertProviderLocaleKey } from "./keys.js";
+/** Canonical locale-catalog namespace for a URL-safe provider operation id. */
+export function operationIdToLocaleNamespace(operationId) {
+    const namespace = operationId.replace(/[-_]([a-z0-9])/g, (_separator, character) => character.toUpperCase());
+    assertProviderLocaleKey(`operations.${namespace}.description`);
+    return namespace;
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.51",
+	"version": "2.2.0-beta.53",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-kebab-operation-id.ts.txt

@@ -0,0 +1,17 @@
+const listHospitalsOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [
+		{
+			scenario: "List nearby hospitals",
+			input: { latitude: 37.5665, longitude: 126.978 },
+			rationale: "Exercises a kebab-case operation id.",
+		},
+	],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+export default buildProvider({
+	operations: { "list-hospitals": listHospitalsOperation },
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-snake-operation-id.ts.txt

@@ -0,0 +1,21 @@
+const listRecentEarthquakesOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	docs: {
+		titleKey: "operations.listRecentEarthquakes.title",
+		descriptionKey: "operations.listRecentEarthquakes.description",
+	},
+	inputExamples: [
+		{
+			scenario: "List recent earthquakes",
+			input: { limit: 10 },
+			rationale: "Exercises a snake-case operation id.",
+		},
+	],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+export default buildProvider({
+	operations: { list_recent_earthquakes: listRecentEarthquakesOperation },
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-canonical-en.json

@@ -0,0 +1 @@
+{"meta":{"displayName":"Canonical fixture"},"operations":{"alpha":{"title":"Alpha"},"search":{"description":"English description","title":"English title","steps":[{"first":"one","second":"two"}]},"omega":{"title":"Omega"}},"tail":"English tail","enOnly":"Keep this last"}

package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-canonical-ja.json

@@ -0,0 +1 @@
+{"jaOnlyFirst":"最初","operations":{"search":{"steps":[{"second":"二","first":"一"}],"title":"検索","jaOnly":"順序を保持","description":"日本語の説明"},"omega":{"title":"オメガ"},"jaOnlyOperation":{"title":"日本語のみ"},"alpha":{"title":"アルファ"}},"tail":"日本語の末尾","meta":{"displayName":"正規 fixture"},"jaOnlyLast":"最後"}

package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-canonical-ko.json

@@ -0,0 +1 @@
+{"koOnlyFirst":"첫 번째","tail":"한국어 꼬리말","operations":{"omega":{"title":"오메가"},"search":{"title":"검색","steps":[{"second":"둘","first":"하나"}],"description":"한국어 설명","koOnly":"순서 유지"},"alpha":{"title":"알파"},"koOnlyOperation":{"title":"한국어 전용"}},"meta":{"displayName":"정규 fixture"},"koOnlyLast":"마지막"}

package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-existing-operation-namespace-en.json

@@ -0,0 +1,8 @@
+{
+	"operations": {
+		"listRecentEarthquakes": {
+			"title": "Recent earthquakes",
+			"description": "Lists recent earthquakes."
+		}
+	}
+}

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-binding-ambiguous.ts.txt

@@ -0,0 +1,12 @@
+const operation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Ambiguous", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+const registry = {
+	first: operation,
+	second: operation,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-imported-other.ts.txt

@@ -0,0 +1,7 @@
+export const importedOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Imported", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-imported.ts.txt

@@ -0,0 +1,5 @@
+import { importedOperation } from "./other";
+
+const registry = {
+	imported: importedOperation,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-key-ambiguous.ts.txt

@@ -0,0 +1,19 @@
+const firstOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "First", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+const secondOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Second", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+const registry = {
+	shared: firstOperation,
+	"shared": secondOperation,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-shorthand.ts.txt

@@ -0,0 +1,9 @@
+const searchOperation = defineStreamOperation({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Search", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+const arbitraryRegistry = { searchOperation };

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-typed.ts.txt

@@ -0,0 +1,11 @@
+const permissionsRevoke = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Revoke permissions", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+export const companionsOperations: Record<string, OperationDefinition> = {
+	"permissions-revoke": permissionsRevoke,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-unrelated.ts.txt

@@ -0,0 +1,13 @@
+const detailOperation = defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Detail", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});
+
+const unrelated = {
+	detail: detailOperation,
+	count: 42,
+	created: makeValue(),
+};

package/src/cli/migrate-operation-declaration.ts

@@ -3,6 +3,9 @@ import { dirname, extname, join, relative, resolve } from "node:path";
 
 import type TS from "typescript";
 
+import { assertProviderLocaleKey } from "../i18n/keys.js";
+import { operationIdToLocaleNamespace } from "../i18n/operation-locale-namespace.js";
+
 const ts: typeof import("typescript") = await loadTypeScript();
 
 async function loadTypeScript(): Promise<typeof import("typescript")> {
@@ -67,6 +70,7 @@ export type OperationDeclarationRefusalReason =
 	| "missing_english_locale"
 	| "operation_id_unresolved"
 	| "examples_conflict"
+	| "invalid_locale_key"
 	| "locale_todo_conflict";
 
 export type OperationDeclarationRefusal = {
@@ -180,6 +184,10 @@ export function migrateOperationDeclaration(
 		todos.push(...plan.localeTodos);
 	}
 	if (refusals.length > 0) return { status: "refused", refusals };
+	const invalidLocaleKey = findInvalidLocaleTodo(todos, fileName);
+	if (invalidLocaleKey !== undefined) {
+		return { status: "refused", refusals: [invalidLocaleKey] };
+	}
 
 	if (edits.length === 0) {
 		return {
@@ -400,6 +408,30 @@ function planOperationMigration(
 		if (merged.insert !== undefined) addInsertion(insertions, "docs", merged.insert);
 	}
 
+	const title = planTitleLocale(
+		top.byName.get("title"),
+		top.byName.get("titleKey"),
+		docs.get("titleKey"),
+		fileName,
+		site,
+		localeFiles,
+	);
+	if ("refusal" in title) return title;
+	const localeNamespace =
+		top.byName.get("inputExamples") === undefined
+			? { namespace: site.operationKey }
+			: resolveOperationLocaleNamespace(
+					[
+						top.byName.get("titleKey"),
+						docs.get("titleKey"),
+						top.byName.get("descriptionKey"),
+						docs.get("descriptionKey"),
+					],
+					fileName,
+					site,
+				);
+	if ("refusal" in localeNamespace) return localeNamespace;
+
 	const examples = planExamples(
 		top.byName.get("inputExamples"),
 		top.byName.get("examples"),
@@ -408,6 +440,7 @@ function planOperationMigration(
 		source,
 		constArrays,
 		localeFiles,
+		localeNamespace.namespace,
 	);
 	if ("refusal" in examples) return examples;
 
@@ -431,7 +464,107 @@ function planOperationMigration(
 		if (!edits.some((existing) => rangesOverlap(existing, edit))) edits.push(edit);
 	}
 
-	return { edits, localeTodos: examples.localeTodos };
+	return { edits, localeTodos: [...title.localeTodos, ...examples.localeTodos] };
+}
+
+function planTitleLocale(
+	title: ResolvedMember | undefined,
+	flatTitleKey: ResolvedMember | undefined,
+	nestedTitleKey: ResolvedMember | undefined,
+	fileName: string,
+	site: OperationSite,
+	localeFiles: readonly string[],
+):
+	| { readonly localeTodos: readonly LocaleTodo[] }
+	| { readonly refusal: OperationDeclarationRefusal } {
+	if (title === undefined) return { localeTodos: [] };
+	const originalProse = literalString(title.initializer);
+	if (originalProse === undefined) {
+		return nonLiteral(
+			fileName,
+			site.operationKey,
+			"title must be a string literal so its authored prose can be preserved in the English locale catalog.",
+		);
+	}
+	if (!site.operationIdProven) {
+		return {
+			refusal: refusal(
+				fileName,
+				site.operationKey,
+				"operation_id_unresolved",
+				"title requires an exact operation id proven from a static operations map.",
+			),
+		};
+	}
+	if (!localeFiles.includes("locales/en.json")) {
+		return {
+			refusal: refusal(
+				fileName,
+				site.operationKey,
+				"missing_english_locale",
+				"title cannot be migrated because locales/en.json does not exist.",
+			),
+		};
+	}
+
+	let selectedTitleKey = flatTitleKey ?? nestedTitleKey;
+	if (flatTitleKey !== undefined && nestedTitleKey !== undefined) {
+		const same = equivalentLiteral(flatTitleKey.initializer, nestedTitleKey.initializer);
+		if (same === undefined) {
+			return nonLiteral(
+				fileName,
+				site.operationKey,
+				"titleKey must be literal when both top-level and nested declarations exist.",
+			);
+		}
+		if (!same) {
+			return {
+				refusal: refusal(
+					fileName,
+					site.operationKey,
+					"locale_key_conflict",
+					"Top-level titleKey conflicts with nested titleKey.",
+				),
+			};
+		}
+		selectedTitleKey = flatTitleKey;
+	}
+	const explicitTitleKey =
+		selectedTitleKey === undefined ? undefined : literalString(selectedTitleKey.initializer);
+	if (selectedTitleKey !== undefined && explicitTitleKey === undefined) {
+		return nonLiteral(
+			fileName,
+			site.operationKey,
+			"titleKey must be a string literal so the title locale destination is provable.",
+		);
+	}
+	let selectedTitleLocaleKey: string;
+	if (explicitTitleKey !== undefined) {
+		selectedTitleLocaleKey = explicitTitleKey;
+	} else {
+		try {
+			selectedTitleLocaleKey = `operations.${operationIdToLocaleNamespace(site.operationKey)}.title`;
+		} catch (error) {
+			return {
+				refusal: invalidLocaleKeyRefusal(
+					fileName,
+					site.operationKey,
+					`operations.${site.operationKey}.title`,
+					error,
+				),
+			};
+		}
+	}
+	return {
+		localeTodos: [
+			{
+				localeFile: "locales/en.json",
+				operationKey: site.operationKey,
+				key: selectedTitleLocaleKey,
+				originalProse,
+			},
+		],
+	};
 }
 
 function resolveRiskClass(
@@ -664,6 +797,7 @@ function planExamples(
 	source: TS.SourceFile,
 	constArrays: ReadonlyMap<string, TS.ArrayLiteralExpression>,
 	localeFiles: readonly string[],
+	localeNamespace: string,
 ):
 	| { readonly edits: readonly TextEdit[]; readonly localeTodos: readonly LocaleTodo[] }
 	| { readonly refusal: OperationDeclarationRefusal } {
@@ -760,7 +894,7 @@ function planExamples(
 				`inputExamples[${index}].scenario must be a string literal.`,
 			);
 		}
-		const scenarioKey = `operations.${site.operationKey}.examples.${index}.scenario`;
+		const scenarioKey = `operations.${localeNamespace}.examples.${index}.scenario`;
 		edits.push(replaceExampleLocaleMember(scenario, "scenarioKey", scenarioKey, source));
 		for (const localeFile of localeFiles) {
 			todos.push({
@@ -781,7 +915,7 @@ function planExamples(
 					`inputExamples[${index}].rationale must be a string literal.`,
 				);
 			}
-			const rationaleKey = `operations.${site.operationKey}.examples.${index}.rationale`;
+			const rationaleKey = `operations.${localeNamespace}.examples.${index}.rationale`;
 			edits.push(replaceExampleLocaleMember(rationale, "rationaleKey", rationaleKey, source));
 			for (const localeFile of localeFiles) {
 				todos.push({
@@ -796,6 +930,47 @@ function planExamples(
 	return { edits, localeTodos: todos };
 }
 
+function resolveOperationLocaleNamespace(
+	members: readonly (ResolvedMember | undefined)[],
+	fileName: string,
+	site: OperationSite,
+): { readonly namespace: string } | { readonly refusal: OperationDeclarationRefusal } {
+	const authoredNamespaces = new Set<string>();
+	for (const member of members) {
+		const localeKey = literalString(member?.initializer);
+		if (localeKey === undefined) continue;
+		const segments = localeKey.split(".");
+		if (segments[0] === "operations" && segments[1] !== undefined) {
+			authoredNamespaces.add(segments[1]);
+		}
+	}
+	if (authoredNamespaces.size > 1) {
+		return {
+			refusal: refusal(
+				fileName,
+				site.operationKey,
+				"locale_key_conflict",
+				`Operation titleKey and descriptionKey declarations use different locale namespaces: ${[...authoredNamespaces].join(", ")}.`,
+			),
+		};
+	}
+	const authored = authoredNamespaces.values().next().value;
+	if (authored !== undefined) return { namespace: authored };
+
+	try {
+		return { namespace: operationIdToLocaleNamespace(site.operationKey) };
+	} catch (error) {
+		return {
+			refusal: invalidLocaleKeyRefusal(
+				fileName,
+				site.operationKey,
+				`operations.${site.operationKey}.examples`,
+				error,
+			),
+		};
+	}
+}
+
 function replaceExampleLocaleMember(
 	member: ResolvedMember,
 	newName: string,
@@ -984,9 +1159,7 @@ function isProviderOperationsProperty(
 	// (a) The initializer (direct or via same-file const) mentions
 	// defineOperation / defineStreamOperation — the strongest signal.
 	const target = ts.isIdentifier(unwrapExpression(node.initializer) ?? node.initializer)
-		? constObjects.get(
-				(unwrapExpression(node.initializer) as TS.Identifier).text,
-			)
+		? constObjects.get((unwrapExpression(node.initializer) as TS.Identifier).text)
 		: undefined;
 	const initializerText = (target ?? node.initializer).getText();
 	if (/\bdefine(?:Stream)?Operation\b/.test(initializerText)) return true;
@@ -1513,6 +1686,35 @@ function refusal(
 	return { file, operationKey, reason, detail };
 }
 
+function findInvalidLocaleTodo(
+	todos: readonly LocaleTodo[],
+	fileName: string,
+): OperationDeclarationRefusal | undefined {
+	for (const todo of todos) {
+		try {
+			assertProviderLocaleKey(todo.key);
+		} catch (error) {
+			return invalidLocaleKeyRefusal(fileName, todo.operationKey, todo.key, error);
+		}
+	}
+	return undefined;
+}
+
+function invalidLocaleKeyRefusal(
+	fileName: string,
+	operationKey: string,
+	localeKey: string,
+	error: unknown,
+): OperationDeclarationRefusal {
+	const validatorDetail = error instanceof Error ? error.message : String(error);
+	return refusal(
+		fileName,
+		operationKey,
+		"invalid_locale_key",
+		`Refusing to write invalid provider locale key ${JSON.stringify(localeKey)}: ${validatorDetail}`,
+	);
+}
+
 function nonLiteral(
 	fileName: string,
 	operationKey: string,
@@ -1576,6 +1778,9 @@ export function migrateOperationDeclarationRepository(
 	if (refusals.length > 0) {
 		return { status: "refused", providerRoot, refusals };
 	}
+	for (const [path, code] of renderLocaleCatalogWrites(providerRoot, todos)) {
+		pendingWrites.set(path, code);
+	}
 
 	if (pendingWrites.size === 0) {
 		return {
@@ -1616,6 +1821,103 @@ export function renderLocaleTodoSidecar(todos: readonly LocaleTodo[]): string {
 	return `${JSON.stringify({ schemaVersion: 1, localeFiles }, null, 2)}\n`;
 }
 
+function renderLocaleCatalogWrites(
+	providerRoot: string,
+	todos: readonly LocaleTodo[],
+): Map<string, string> {
+	const todosByFile = new Map<string, LocaleTodo[]>();
+	for (const todo of todos) {
+		const fileTodos = todosByFile.get(todo.localeFile) ?? [];
+		fileTodos.push(todo);
+		todosByFile.set(todo.localeFile, fileTodos);
+	}
+
+	const englishPath = "locales/en.json";
+	const englishTodos = todosByFile.get(englishPath);
+	if (englishTodos === undefined) return new Map();
+
+	const english = readLocaleCatalog(join(providerRoot, englishPath));
+	applyLocaleTodos(english, englishTodos);
+	const writes = new Map<string, string>([
+		[join(providerRoot, englishPath), renderCanonicalLocaleCatalog(english)],
+	]);
+
+	for (const [localeFile, fileTodos] of todosByFile) {
+		if (localeFile === englishPath) continue;
+		const catalog = readLocaleCatalog(join(providerRoot, localeFile));
+		applyLocaleTodos(catalog, fileTodos);
+		writes.set(
+			join(providerRoot, localeFile),
+			renderCanonicalLocaleCatalog(reorderLikeReference(english, catalog)),
+		);
+	}
+	return writes;
+}
+
+function readLocaleCatalog(path: string): Record<string, unknown> {
+	const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+	if (!isRecord(value)) throw new Error(`${path} must contain a JSON object.`);
+	return value;
+}
+
+function applyLocaleTodos(catalog: Record<string, unknown>, todos: readonly LocaleTodo[]): void {
+	for (const todo of todos) {
+		const segments = todo.key.split(".");
+		const leaf = segments.pop();
+		if (leaf === undefined) continue;
+		let cursor = catalog;
+		for (const segment of segments) {
+			const child = cursor[segment];
+			if (isRecord(child)) {
+				cursor = child;
+				continue;
+			}
+			const created: Record<string, unknown> = {};
+			cursor[segment] = created;
+			cursor = created;
+		}
+		cursor[leaf] = todo.originalProse;
+	}
+}
+
+/** Match provider-contract's canonical locale serialization exactly. */
+function renderCanonicalLocaleCatalog(value: unknown): string {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+/**
+ * Put shared keys first in English order, then retain locale-only authored order.
+ * Arrays keep their shape and use the English item at the same index as a reference.
+ */
+function reorderLikeReference(reference: unknown, value: unknown): unknown {
+	if (Array.isArray(value)) {
+		const referenceArray = Array.isArray(reference) ? reference : [];
+		return value.map((item, index) => reorderLikeReference(referenceArray[index], item));
+	}
+	if (!isRecord(value)) return value;
+
+	const referenceRecord = isRecord(reference) ? reference : {};
+	const ordered: Record<string, unknown> = {};
+	for (const key of Object.keys(referenceRecord)) {
+		if (Object.hasOwn(value, key)) {
+			ordered[key] = reorderLikeReference(referenceRecord[key], value[key]);
+		}
+	}
+	for (const [key, child] of Object.entries(value)) {
+		if (!Object.hasOwn(ordered, key)) {
+			ordered[key] = reorderLikeReference(
+				Object.hasOwn(referenceRecord, key) ? referenceRecord[key] : undefined,
+				child,
+			);
+		}
+	}
+	return ordered;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function findLocaleTodoConflict(
 	todos: readonly LocaleTodo[],
 ): OperationDeclarationRefusal | undefined {
@@ -1668,6 +1970,8 @@ function collectLocaleFiles(root: string): string[] {
 
 function buildOperationIdIndex(sourceFiles: readonly string[]): Map<string, Map<string, string>> {
 	const result = new Map<string, Map<string, string>>();
+	const idsByPath = new Map<string, Map<string, string | null>>();
+	const ambiguousBindingsByPath = new Map<string, Set<string>>();
 	const sources = new Map<string, TS.SourceFile>();
 	for (const path of sourceFiles) {
 		const source = parseSource(path, readFileSync(path, "utf8"));
@@ -1676,10 +1980,40 @@ function buildOperationIdIndex(sourceFiles: readonly string[]): Map<string, Map<
 
 	const record = (path: string, binding: string, operationId: string): void => {
 		const map = result.get(path) ?? new Map<string, string>();
-		const previous = map.get(binding);
-		if (previous === undefined || previous === operationId) map.set(binding, operationId);
-		else map.delete(binding);
+		const ids = idsByPath.get(path) ?? new Map<string, string | null>();
+		const ambiguousBindings = ambiguousBindingsByPath.get(path) ?? new Set<string>();
+
+		// An operation id is usable only when it identifies exactly one binding.
+		// Keep an explicit null marker for an ambiguous id so a later occurrence
+		// cannot accidentally make it usable again.
+		const previousBinding = ids.get(operationId);
+		if (ids.has(operationId)) {
+			if (
+				previousBinding !== undefined &&
+				previousBinding !== null &&
+				previousBinding !== binding
+			) {
+				map.delete(previousBinding);
+				map.delete(binding);
+				ambiguousBindings.add(previousBinding);
+				ambiguousBindings.add(binding);
+				ids.set(operationId, null);
+			}
+		} else {
+			ids.set(operationId, binding);
+		}
+
+		// A binding registered under two different ids is likewise ambiguous.
+		const previousId = map.get(binding);
+		if (previousId !== undefined && previousId !== operationId) {
+			map.delete(binding);
+			ambiguousBindings.add(binding);
+		} else if (!ambiguousBindings.has(binding) && ids.get(operationId) === binding) {
+			map.set(binding, operationId);
+		}
 		result.set(path, map);
+		idsByPath.set(path, ids);
+		ambiguousBindingsByPath.set(path, ambiguousBindings);
 	};
 
 	for (const [path, source] of sources) {
@@ -1700,10 +2034,91 @@ function buildOperationIdIndex(sourceFiles: readonly string[]): Map<string, Map<
 				else record(imported.path, imported.exportedName, operationId);
 			}
 		}
+
+		// Some providers keep their operation registry in a same-file const with
+		// an arbitrary name (for example, `companionsOperations`). This scan is
+		// deliberately ID-only: it accepts only static object members whose value
+		// is a same-file operation binding, and never evaluates spreads, factories,
+		// or imported values.
+		const operationBindings = collectModuleOperationBindings(source);
+		const importedBindings = collectImportedBindingNames(source);
+		for (const entry of collectStaticOperationRegistryEntries(source, operationBindings)) {
+			if (importedBindings.has(entry.binding)) continue;
+			record(path, entry.binding, entry.operationId);
+		}
 	}
 	return result;
 }
 
+type StaticOperationRegistryEntry = {
+	readonly operationId: string;
+	readonly binding: string;
+};
+
+function collectModuleOperationBindings(source: TS.SourceFile): ReadonlySet<string> {
+	const bindings = new Set<string>();
+	for (const statement of source.statements) {
+		if (!ts.isVariableStatement(statement)) continue;
+		if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+		for (const declaration of statement.declarationList.declarations) {
+			if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined) continue;
+			const initializer = unwrapExpression(declaration.initializer);
+			if (
+				initializer !== undefined &&
+				ts.isCallExpression(initializer) &&
+				isOperationHelperCall(initializer)
+			) {
+				bindings.add(declaration.name.text);
+			}
+		}
+	}
+	return bindings;
+}
+
+function collectImportedBindingNames(source: TS.SourceFile): ReadonlySet<string> {
+	const bindings = new Set<string>();
+	for (const statement of source.statements) {
+		if (!ts.isImportDeclaration(statement)) continue;
+		const clause = statement.importClause;
+		if (clause?.name !== undefined) bindings.add(clause.name.text);
+		const named = clause?.namedBindings;
+		if (named === undefined) continue;
+		if (ts.isNamespaceImport(named)) {
+			bindings.add(named.name.text);
+			continue;
+		}
+		for (const element of named.elements) bindings.add(element.name.text);
+	}
+	return bindings;
+}
+
+function collectStaticOperationRegistryEntries(
+	source: TS.SourceFile,
+	operationBindings: ReadonlySet<string>,
+): StaticOperationRegistryEntry[] {
+	const entries: StaticOperationRegistryEntry[] = [];
+	for (const statement of source.statements) {
+		if (!ts.isVariableStatement(statement)) continue;
+		if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+		for (const declaration of statement.declarationList.declarations) {
+			if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined) continue;
+			const object = unwrapExpression(declaration.initializer);
+			if (object === undefined || !ts.isObjectLiteralExpression(object)) continue;
+			for (const property of object.properties) {
+				if (ts.isSpreadAssignment(property)) continue;
+				const name = property.name;
+				if (name === undefined || (!ts.isIdentifier(name) && !ts.isStringLiteral(name))) continue;
+				const value = propertyValue(property);
+				const binding = unwrapExpression(value);
+				if (binding === undefined || !ts.isIdentifier(binding)) continue;
+				if (!operationBindings.has(binding.text)) continue;
+				entries.push({ operationId: name.text, binding: binding.text });
+			}
+		}
+	}
+	return entries;
+}
+
 function collectImports(
 	source: TS.SourceFile,
 	containingPath: string,

package/src/i18n/operation-locale-namespace.ts

@@ -0,0 +1,10 @@
+import { assertProviderLocaleKey } from "./keys.js";
+
+/** Canonical locale-catalog namespace for a URL-safe provider operation id. */
+export function operationIdToLocaleNamespace(operationId: string): string {
+	const namespace = operationId.replace(/[-_]([a-z0-9])/g, (_separator, character: string) =>
+		character.toUpperCase(),
+	);
+	assertProviderLocaleKey(`operations.${namespace}.description`);
+	return namespace;
+}