@tiangong-ai/cli 0.0.30 → 0.0.31

package/dist/research/workspace/setup.js

@@ -8,10 +8,10 @@ import { CliError } from "../../errors.js";
 import { loadCapabilityDeclarations } from "./capabilities.js";
 import { inspectResearchContext } from "./context.js";
 import { inspectCapabilityCredentialEnvironment, loadCapabilityCredentialMapForIds, reconcileCapabilityCredentialEnvironment, setCapabilityCredentialValue, } from "./credentials.js";
-import { configureExternalSkillProfile, configureTiangongSciCapability, doctorExternalCapabilities, EXTERNAL_SKILL_CONTEXT_PROFILE, EXTERNAL_SKILL_MEDIA_PROFILE, EXTERNAL_SKILL_PROFILE, reconcileSetupManagedCapabilities, } from "./external-skills.js";
+import { configureExternalSkillProfile, configureTiangongDatabaseCapability, doctorExternalCapabilities, EXTERNAL_SKILL_CONTEXT_PROFILE, EXTERNAL_SKILL_MEDIA_PROFILE, EXTERNAL_SKILL_PROFILE, reconcileSetupManagedCapabilities, } from "./external-skills.js";
 import { appendJournalEvent } from "./journal.js";
 import { configuredResearchSecrets, isSensitiveEnvironmentName, sanitizeResearchRecord, sanitizeResearchText, } from "./sanitization.js";
-import { inspectResearchSetupCatalog, RESEARCH_SETUP_CREDENTIALS, RESEARCH_SETUP_INSTALLER, RESEARCH_SETUP_SETTINGS, RESEARCH_SETUP_SKILLS, resolveSetupSkills, setupSkill, setupSource, setupTargetRoot, } from "./setup-catalog.js";
+import { inspectResearchSetupCatalog, RESEARCH_SETUP_CREDENTIALS, RESEARCH_SETUP_INSTALLER, RESEARCH_SETUP_SETTINGS, RESEARCH_SETUP_SKILLS, resolveSetupSkills, setupSkill, setupSource, setupTargetRoot, verifyResearchSetupRuntimeContract, } from "./setup-catalog.js";
 import { acquireFileLock, canonicalJson, ensureDirectory, fileSize, hashRegularTree, isObject, pathExists, REGULAR_TREE_HASH_ALGORITHM, readJsonFile, sha256File, sha256Text, workspacePaths, writeJsonAtomic, writeTextAtomic, } from "./storage.js";
 import { packageVersion } from "./constants.js";
 import { doctorResearchWorkspace, initializeResearchWorkspace, loadWorkspaceConfig, } from "./workspace.js";
@@ -969,22 +969,24 @@ export async function checkResearchSetupUpdates(workspace, environment = process
             });
         }
     }
+    const cliVersionDrift = plan.cli.version === packageVersion()
+        ? null
+        : { planned: plan.cli.version, active: packageVersion() };
+    const updateAvailable = drift.length > 0 || cliVersionDrift !== null;
     return {
         schemaVersion: 1,
         workspace: root,
         checkedAt: new Date().toISOString(),
-        updateAvailable: drift.length > 0 || plan.cli.version !== packageVersion(),
-        cliVersionDrift: plan.cli.version === packageVersion()
-            ? null
-            : { planned: plan.cli.version, active: packageVersion() },
+        updateAvailable,
+        cliVersionDrift,
         drift,
         currentInstaller: RESEARCH_SETUP_INSTALLER,
         catalog,
         policy: {
             automaticUpdate: false,
             floatingUpdate: false,
-            minimumAction: drift.length
-                ? "Use the newer CLI to create and review a replacement immutable plan; upgrade never runs a floating skills update."
+            minimumAction: updateAvailable
+                ? "Use the active exact CLI release to create, review, and apply a replacement immutable plan; upgrade never runs a floating CLI or Skills update."
                 : "No catalog migration is required. Installed tree drift is reported separately by setup status/doctor.",
         },
     };
@@ -1719,6 +1721,7 @@ async function ensureSetupSourceCheckout(plan, sourceId, runner, environment) {
                 },
             });
         }
+        await verifyResearchSetupRuntimeContract(sourcePath, setupSkill(skill.id));
     }
     return checkout;
 }
@@ -1759,8 +1762,30 @@ async function installSetupSkills(input) {
 }
 async function configureSelectedCapabilities(plan, _environment) {
     const hasBraveProfile = plan.selection.evidenceProfile !== "none";
-    const hasTiangongSci = plan.selection.skillIds.includes("tiangong.kb-sci-search");
-    const codexRoot = hasBraveProfile || hasTiangongSci ? plannedTargetRoot(plan, "codex") : null;
+    const tiangongDatabases = [
+        {
+            kind: "sci",
+            skillId: "tiangong.kb-sci-search",
+            settingPrefix: "tiangong.sci",
+            catalogId: "first-party.tiangong.kb-sci-search",
+            capabilityId: "database.tiangong.sci-search",
+        },
+        {
+            kind: "report",
+            skillId: "tiangong.kb-report-search",
+            settingPrefix: "tiangong.report",
+            catalogId: "first-party.tiangong.kb-report-search",
+            capabilityId: "database.tiangong.report-search",
+        },
+        {
+            kind: "patent",
+            skillId: "tiangong.kb-patent-search",
+            settingPrefix: "tiangong.patent",
+            catalogId: "first-party.tiangong.kb-patent-search",
+            capabilityId: "database.tiangong.patent-search",
+        },
+    ].filter((entry) => plan.selection.skillIds.includes(entry.skillId));
+    const codexRoot = hasBraveProfile || tiangongDatabases.length ? plannedTargetRoot(plan, "codex") : null;
     if (plan.selection.evidenceProfile !== "none") {
         await configureExternalSkillProfile({
             workspace: plan.workspace.path,
@@ -1768,10 +1793,11 @@ async function configureSelectedCapabilities(plan, _environment) {
             skillRoot: codexRoot,
         });
     }
-    if (hasTiangongSci) {
-        const skill = setupSkill("tiangong.kb-sci-search");
+    for (const database of tiangongDatabases) {
+        const skill = setupSkill(database.skillId);
         const source = setupSource(skill.sourceId);
-        await configureTiangongSciCapability({
+        await configureTiangongDatabaseCapability({
+            kind: database.kind,
             workspace: plan.workspace.path,
             skillPath: join(codexRoot, skill.skillName),
             source: {
@@ -1780,19 +1806,19 @@ async function configureSelectedCapabilities(plan, _environment) {
                 immutableRef: source.immutableRef,
                 expectedTreeSha256: skill.expectedTreeSha256,
                 license: "MIT",
-                catalogId: "first-party.tiangong.kb-sci-search",
+                catalogId: database.catalogId,
             },
-            endpoint: plan.settings["tiangong.sci.endpoint"],
-            ...(plan.settings["tiangong.sci.region"] === undefined
+            endpoint: plan.settings[`${database.settingPrefix}.endpoint`],
+            ...(plan.settings[`${database.settingPrefix}.region`] === undefined
                 ? {}
-                : { region: plan.settings["tiangong.sci.region"] }),
+                : { region: plan.settings[`${database.settingPrefix}.region`] }),
         });
     }
     await reconcileSetupManagedCapabilities({
         workspace: plan.workspace.path,
         selectedCapabilityIds: [
             ...BRAVE_PROFILE_SKILLS[plan.selection.evidenceProfile].map(setupManagedCapabilityId),
-            ...(hasTiangongSci ? ["database.tiangong.sci-search"] : []),
+            ...tiangongDatabases.map((database) => database.capabilityId),
         ],
     });
 }
@@ -1887,6 +1913,14 @@ async function assertRequiredCredentialPreflight(plan, environment) {
                 .join(", ")}), then retry this exact step.`,
             retryCommand: `tiangong-ai research setup retry --step credential-preflight --workspace ${plan.workspace.path} --json`,
             exitCode: 3,
+            diagnostics: {
+                executionMode: "setup-preflight",
+                credentialScope: [
+                    ...new Set(failures.map((failure) => definitions.find((definition) => definition.id === failure.id).storage)),
+                ].join("+"),
+                networkAttempted: false,
+                missingCredentialIds: failures.map((failure) => failure.id),
+            },
         });
     }
 }
@@ -2885,7 +2919,7 @@ function commandFailure(step, command, result, root, environment) {
         exitCode: 3,
     });
 }
-async function setupDoctorCheck(checks, id, category, callback) {
+async function setupDoctorCheck(checks, id, category, callback, failureMinimumAction = `Resolve ${id}, then rerun research setup doctor.`) {
     try {
         checks.push({
             id,
@@ -2901,7 +2935,7 @@ async function setupDoctorCheck(checks, id, category, callback) {
             category,
             status: "fail",
             detail: sanitizeResearchText(error instanceof Error ? error.message : String(error)),
-            minimumAction: `Resolve ${id}, then rerun research setup doctor.`,
+            minimumAction: failureMinimumAction,
         });
     }
 }
@@ -2955,35 +2989,12 @@ async function appendDependencyChecks(checks, selected, runner, root, environmen
                 return `${dependency.requirement} is active.`;
             }
             throw new Error(`No automatic dependency check is declared for ${dependency.id}. ${dependency.minimumAction}`);
-        });
+        }, dependency.minimumAction);
     }
 }
 async function appendCompanionLiveChecks(checks, input) {
-    void input.sleeper;
     if (input.selected.some((skill) => skill.id === "tiangong.academic-paper-download")) {
-        await setupDoctorCheck(checks, "live.semantic-scholar", "live-check", async () => {
-            const apiKey = input.adapterCredentials.get("semantic-scholar.api-key");
-            const headers = new Headers({ Accept: "application/json" });
-            if (apiKey)
-                headers.set("x-api-key", apiKey);
-            const response = await input.fetcher("https://api.semanticscholar.org/graph/v1/paper/search?query=reproducible%20research&limit=1&fields=paperId", {
-                method: "GET",
-                headers,
-                redirect: "manual",
-                signal: AbortSignal.timeout(30_000),
-            });
-            if (response.status >= 300 && response.status < 400) {
-                throw new Error("Semantic Scholar returned a redirect; credential-bearing redirects are not followed.");
-            }
-            if (!response.ok) {
-                const detail = await boundedResponseText(response, 2_000, apiKey ? [apiKey] : []);
-                throw new Error(`Semantic Scholar live check returned HTTP ${response.status}${detail ? `: ${detail}` : ""}.`);
-            }
-            await response.body?.cancel().catch(() => undefined);
-            return apiKey
-                ? "Semantic Scholar accepted the configured optional API key."
-                : "Semantic Scholar public API is reachable without an optional API key.";
-        });
+        await appendSemanticScholarLiveCheck(checks, input);
     }
     if (input.selected.some((skill) => skill.id === "tiangong.document-granular-decompose")) {
         if (!input.allowSyntheticUnstructureUpload) {
@@ -3029,6 +3040,116 @@ async function appendCompanionLiveChecks(checks, input) {
         }
     }
 }
+async function appendSemanticScholarLiveCheck(checks, input) {
+    const apiKey = input.adapterCredentials.get("semantic-scholar.api-key");
+    const headers = new Headers({ Accept: "application/json" });
+    if (apiKey)
+        headers.set("x-api-key", apiKey);
+    const url = "https://api.semanticscholar.org/graph/v1/paper/search?query=reproducible%20research&limit=1&fields=paperId";
+    try {
+        let response;
+        let retryAfterSeconds = null;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            response = await input.fetcher(url, {
+                method: "GET",
+                headers,
+                redirect: "manual",
+                signal: AbortSignal.timeout(30_000),
+            });
+            if (response.status !== 429 || attempt === 1)
+                break;
+            retryAfterSeconds = setupRetryAfterSeconds(response.headers.get("retry-after"));
+            await response.body?.cancel().catch(() => undefined);
+            await input.sleeper(Math.min(5, retryAfterSeconds ?? 1) * 1_000);
+        }
+        retryAfterSeconds ??= setupRetryAfterSeconds(response.headers.get("retry-after"));
+        if (response.status >= 300 && response.status < 400) {
+            await response.body?.cancel().catch(() => undefined);
+            checks.push({
+                id: "live.semantic-scholar",
+                category: "live-check",
+                status: "fail",
+                detail: "Semantic Scholar returned a redirect; credential-bearing redirects are not followed.",
+                minimumAction: "Verify the fixed Semantic Scholar endpoint and network policy, then rerun setup doctor; do not fall back to a standalone source wrapper.",
+                diagnostics: {
+                    code: "PROVIDER_REDIRECT_REJECTED",
+                    executionMode: "setup-doctor",
+                    credentialScope: "adapter",
+                    networkAttempted: true,
+                    httpStatus: response.status,
+                },
+            });
+            return;
+        }
+        if (!response.ok) {
+            const authenticationFailure = response.status === 401 || response.status === 403;
+            const rateLimited = response.status === 429;
+            const detail = authenticationFailure
+                ? ""
+                : await boundedResponseText(response, 2_000, apiKey ? [apiKey] : []);
+            checks.push({
+                id: "live.semantic-scholar",
+                category: "live-check",
+                status: "fail",
+                detail: sanitizeResearchText(`Semantic Scholar live check returned HTTP ${response.status}${detail ? `: ${detail}` : ""}.`, apiKey ? [apiKey] : []),
+                minimumAction: rateLimited
+                    ? `Wait for the provider quota window${retryAfterSeconds === null ? "" : ` (Retry-After ${retryAfterSeconds}s)`}, then rerun setup doctor. The production workflow remains blocked and must not downgrade to standalone search.`
+                    : authenticationFailure
+                        ? "Replace or remove the optional Semantic Scholar API key, verify provider entitlement, and rerun setup doctor; do not expose the key in output."
+                        : "Verify Semantic Scholar availability and the fixed API contract, then rerun setup doctor; do not downgrade the research workflow.",
+                diagnostics: {
+                    code: authenticationFailure
+                        ? "PROVIDER_AUTHENTICATION_FAILED"
+                        : rateLimited
+                            ? "PROVIDER_RATE_LIMITED"
+                            : "PROVIDER_REQUEST_FAILED",
+                    executionMode: "setup-doctor",
+                    credentialScope: "adapter",
+                    networkAttempted: true,
+                    httpStatus: response.status,
+                    retryAfterSeconds,
+                },
+            });
+            return;
+        }
+        await response.body?.cancel().catch(() => undefined);
+        checks.push({
+            id: "live.semantic-scholar",
+            category: "live-check",
+            status: "pass",
+            detail: apiKey
+                ? "Semantic Scholar accepted the configured optional API key."
+                : "Semantic Scholar public API is reachable without an optional API key.",
+            minimumAction: null,
+        });
+    }
+    catch (error) {
+        checks.push({
+            id: "live.semantic-scholar",
+            category: "live-check",
+            status: "fail",
+            detail: sanitizeResearchText(error instanceof Error ? error.message : String(error), apiKey ? [apiKey] : []),
+            minimumAction: "Restore provider connectivity, then rerun setup doctor; the production workflow must remain blocked instead of using a standalone fallback.",
+            diagnostics: {
+                code: "PROVIDER_TRANSPORT_FAILED",
+                executionMode: "setup-doctor",
+                credentialScope: "adapter",
+                networkAttempted: true,
+            },
+        });
+    }
+}
+function setupRetryAfterSeconds(value) {
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.ceil(seconds);
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        return null;
+    return Math.max(0, Math.ceil((timestamp - Date.now()) / 1_000));
+}
 async function boundedResponseText(response, maximumBytes, secrets) {
     if (!response.body)
         return "";