@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.7

package/bin/apifuse-submit-check.ts

@@ -11,6 +11,10 @@ import * as acorn from "acorn";
 import { z } from "zod";
 
 import packageJson from "../package.json";
+import {
+	formatPromptAssetIssues,
+	verifyPromptAssets,
+} from "../src/cli/prompt-assets.js";
 import type { ProviderDefinition } from "../src/index.js";
 import {
 	loadProviderLocaleCatalogs,
@@ -19,7 +23,7 @@ import {
 } from "../src/i18n/index.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY } from "../src/schema.js";
 import { safeParseSchemaSync } from "../src/schema.js";
-import { type CheckResult, runChecks } from "./apifuse-check.js";
+import { type CheckResult, PROMPT_ASSETS_CHECK_MESSAGE, runChecks } from "./apifuse-check.js";
 import { hasSubstantiveXmlStructure } from "./submit-check-xml.js";
 
 const TIERS = ["bronze", "silver", "gold", "diamond"] as const;
@@ -267,7 +271,15 @@ export async function buildSubmitCheckReport(
 	const baseChecks = await safeRunChecks(providerRoot);
 	const provider = await safeLoadProvider(providerRoot);
 
-	checks.push(...scoreBaseChecks(baseChecks));
+	// Prompt-asset freshness is reported by its own dedicated zero-point
+	// blocker below; filter the base-check duplicate so it is not double
+	// penalized under the definition category.
+	checks.push(
+		...scoreBaseChecks(
+			baseChecks.filter((result) => result.message !== PROMPT_ASSETS_CHECK_MESSAGE),
+		),
+	);
+	checks.push(scorePromptAssetFreshness(providerRoot));
 	checks.push(scoreProviderIdSlug(providerRoot, provider));
 	checks.push(scoreNoVendorShim(providerRoot));
 	checks.push(scoreNoVendorImport(providerRoot));
@@ -283,6 +295,7 @@ export async function buildSubmitCheckReport(
 	if (provider) {
 		const smokeResult = args.smoke ? await runSubmitCheckSmoke(providerRoot, provider) : undefined;
 		checks.push(scoreCredentialUsage(providerRoot, provider));
+		checks.push(scoreSdkOwnedSecretPresence(providerRoot, provider));
 		checks.push(scoreLocaleCatalog(providerRoot, provider));
 		checks.push(scoreOperationMetadata(provider));
 		checks.push(scoreFixtureCoverage(provider));
@@ -1424,6 +1437,159 @@ function scoreCredentialUsage(providerRoot: string, provider: ProviderDefinition
 	);
 }
 
+// ---------------------------------------------------------------------------
+// sdk-owned-secret-presence (warn): provider-local double validation of
+// declared env secrets.
+//
+// The SDK runtime is the single source of truth for secret presence: declared
+// `required: true` secrets are validated before every handler/auth-flow
+// invocation and fail with the canonical structured MISSING_SECRET error
+// (HTTP 400, category credential_unavailable). Provider-local presence guards
+// (requireServiceKey/requireApiKey style) are dead weight that historically
+// diverged into inconsistent shapes (CONFIGURATION_ERROR vs MISSING_SECRET,
+// with/without category), which broke uniform incident attribution when nine
+// providers shipped with unprovisioned secrets (2026-07-22).
+//
+// Heuristic, warn-only: a line reading a declared `required: true` secret via
+// `.env.get(...)` (string literal or a const alias of a declared name)
+// followed within a small window by a falsy presence check plus a `throw`.
+// The rule flags duplication of the SDK gate ONLY: env names that are not
+// declared in defineProvider secrets[], and optional declarations
+// (`required: false`/omitted) that the runtime deliberately does not enforce,
+// are out of scope. Escape hatch:
+// `// @apifuse-allow sdk-owned-secret-presence: <reason>`.
+// ---------------------------------------------------------------------------
+
+const SDK_OWNED_SECRET_PRESENCE_RULE_ID = "sdk-owned-secret-presence";
+const SECRET_PRESENCE_GUARD_LOOKAHEAD_LINES = 10;
+
+const ENV_GET_CALL_PATTERN =
+	/\.env\.get\(\s*(?:"([^"]+)"|'([^']+)'|`([^`$]+)`|([A-Za-z_$][\w$]*))\s*\)/;
+
+const SECRET_ALIAS_CONST_PATTERN =
+	/\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*(?:"([^"]+)"|'([^']+)'|`([^`$]+)`)/g;
+
+const ENV_GET_ASSIGNMENT_PATTERN = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=[^;]*\.env\.get\(/;
+
+// Const aliases of declared secret names (e.g. `const SERVICE_KEY_ENV =
+// "APIFUSE__PROVIDER__X__SERVICE_KEY"`) so aliased `.env.get(SERVICE_KEY_ENV)`
+// guards are detected, not just direct string literals.
+function buildDeclaredSecretAliasMap(
+	providerRoot: string,
+	declaredNames: ReadonlySet<string>,
+): Map<string, string> {
+	const aliases = new Map<string, string>();
+	for (const filePath of listNonTestTypeScriptFiles(providerRoot)) {
+		const content = readFileSync(filePath, "utf8");
+		for (const match of content.matchAll(SECRET_ALIAS_CONST_PATTERN)) {
+			const alias = match[1];
+			const name = match[2] ?? match[3] ?? match[4];
+			if (alias && name && declaredNames.has(name)) {
+				aliases.set(alias, name);
+			}
+		}
+	}
+	return aliases;
+}
+
+function hasLocalSecretPresenceGuard(
+	line: string,
+	remainingLines: readonly string[],
+	declaredNames: ReadonlySet<string>,
+	aliases: ReadonlyMap<string, string>,
+): boolean {
+	const match = ENV_GET_CALL_PATTERN.exec(line);
+	if (!match) {
+		return false;
+	}
+	const literal = match[1] ?? match[2] ?? match[3];
+	const identifier = match[4];
+	const readsDeclaredSecret =
+		literal !== undefined
+			? declaredNames.has(literal)
+			: identifier !== undefined && aliases.has(identifier);
+	if (!readsDeclaredSecret) {
+		return false;
+	}
+
+	const window = [line, ...remainingLines.slice(0, SECRET_PRESENCE_GUARD_LOOKAHEAD_LINES)];
+	if (!window.some((candidate) => /\bthrow\b/.test(candidate))) {
+		return false;
+	}
+
+	// Assigned read (`const key = ctx.env.get(...)`): only a falsy/undefined
+	// check on THAT variable counts as a presence guard. Anchoring on the
+	// assigned identifier avoids false positives from unrelated guards/throws
+	// that merely sit near the env read (mirrors the aliased runtime-guard rule).
+	const assigned = ENV_GET_ASSIGNMENT_PATTERN.exec(line)?.[1];
+	if (assigned) {
+		const escaped = assigned.replace(/\$/g, "\\$");
+		const guardPattern = new RegExp(
+			`(?:!\\s*${escaped}\\b|\\b${escaped}\\s*===?\\s*(?:undefined|null)\\b|\\b${escaped}\\s*==\\s*null\\b|\\b${escaped}(?:\\?\\.|\\.)length\\s*===?\\s*0\\b)`,
+		);
+		return window.some((candidate) => guardPattern.test(candidate));
+	}
+
+	// Un-assigned read: only an inline presence check on the same line counts,
+	// e.g. `if (!ctx.env.get(KEY)) throw ...`.
+	return /(?:if\s*\(\s*!|===?\s*undefined\b|==\s*null\b)/.test(line);
+}
+
+function scoreSdkOwnedSecretPresence(
+	providerRoot: string,
+	provider: ProviderDefinition,
+): SubmitCheck {
+	const passMessage = "Provider relies on SDK-owned secret presence validation.";
+	// Only `required: true` declarations: those are exactly what the runtime
+	// gate enforces. A presence guard over an optional secret is conditional
+	// business logic the SDK will not replace, not double validation.
+	const declaredNames: ReadonlySet<string> = new Set(
+		(provider.secrets ?? [])
+			.filter((secret) => secret.required === true)
+			.map((secret) => secret.name),
+	);
+	if (declaredNames.size === 0) {
+		return pass(SDK_OWNED_SECRET_PRESENCE_RULE_ID, SDK_NATIVE_CATEGORY, passMessage, 0);
+	}
+
+	const aliases = buildDeclaredSecretAliasMap(providerRoot, declaredNames);
+	const findings = findSourceFindings(providerRoot, (line, remainingLines) =>
+		hasLocalSecretPresenceGuard(line, remainingLines, declaredNames, aliases),
+	);
+	if (findings.length === 0) {
+		return pass(SDK_OWNED_SECRET_PRESENCE_RULE_ID, SDK_NATIVE_CATEGORY, passMessage, 0);
+	}
+
+	const { violations, overridden } = partitionAllowOverrides(
+		providerRoot,
+		findings,
+		SDK_OWNED_SECRET_PRESENCE_RULE_ID,
+	);
+	if (violations.length === 0) {
+		return pass(
+			SDK_OWNED_SECRET_PRESENCE_RULE_ID,
+			SDK_NATIVE_CATEGORY,
+			`${passMessage} ${overridden.length} acknowledged @apifuse-allow override(s).`,
+			0,
+			formatSourceFindings(overridden),
+		);
+	}
+
+	return {
+		id: SDK_OWNED_SECRET_PRESENCE_RULE_ID,
+		category: SDK_NATIVE_CATEGORY,
+		level: "warn",
+		status: "warn",
+		points: 0,
+		maxPoints: 0,
+		message:
+			"Provider source re-validates declared env secret presence locally; the SDK owns this check.",
+		remediation:
+			"The provider SDK validates declared required secrets before handlers and auth flows run and returns the canonical MISSING_SECRET error (HTTP 400, category credential_unavailable). Declare the secret with required: true in defineProvider({ secrets: [...] }), delete the provider-local presence guard (requireServiceKey/requireApiKey style), and read the value directly with ctx.env.get(); the guard is dead weight and its divergent CONFIGURATION_ERROR-style shape is deprecated. Acknowledge intentional exceptions with `// @apifuse-allow sdk-owned-secret-presence: <reason>`.",
+		evidence: formatSourceFindings(violations),
+	};
+}
+
 function findSourceLineMatches(
 	providerRoot: string,
 	pattern: RegExp | ((line: string) => boolean),
@@ -1523,6 +1689,10 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
+// `.agents`/`.apifuse` stay IN scope on purpose: managed content there is
+// markdown/JSON (never scannable), while a planted `.ts`/`.sh` under those
+// directories must not become a scan-exempt hiding place for secrets, raw
+// fetch, or vendor imports.
 function shouldScanSourceDirectory(relativePath: string): boolean {
 	return ![".git", "node_modules", "dist", "build", "coverage"].includes(relativePath);
 }
@@ -1545,6 +1715,27 @@ function formatSourceFindings(findings: readonly SourceFinding[]): string[] {
 	return findings.map((finding) => `${finding.file}:${finding.line}`);
 }
 
+function scorePromptAssetFreshness(providerRoot: string): SubmitCheck {
+	const verification = verifyPromptAssets(providerRoot);
+	if (verification.ok) {
+		return pass(
+			"prompt-assets-fresh",
+			"docs",
+			"SDK-managed agent prompt assets match the installed SDK version.",
+			0,
+		);
+	}
+
+	return blocker(
+		"prompt-assets-fresh",
+		"docs",
+		"SDK-managed agent prompt assets are missing, stale, or modified.",
+		"Run `bun run sync-assets` (or `bunx apifuse sync-assets .`) to regenerate AGENTS.md, .agents/skills/**, the CLAUDE.md/.claude/.codex symlinks, and .apifuse/prompt-assets.json for the installed SDK version.",
+		0,
+		formatPromptAssetIssues(verification),
+	);
+}
+
 function scoreRepositoryDx(providerRoot: string): SubmitCheck {
 	const missing: string[] = [];
 	if (!existsSync(resolve(providerRoot, ".gitignore"))) {
@@ -3546,9 +3737,47 @@ function scoreProviderDocs(providerRoot: string): SubmitCheck[] {
 	];
 }
 
+// Splits secret findings into still-active findings and acknowledged
+// `// @apifuse-allow secret-scan` overrides, mirroring partitionAllowOverrides
+// (same pragma placement: the finding line or the line directly above it).
+// Every finding source carries a line number (entropy candidates and located
+// SECRET_PATTERNS matches); a finding that somehow lacks one stays active
+// defensively.
+function partitionSecretScanAllowOverrides(
+	providerRoot: string,
+	findings: readonly SecretFinding[],
+): { active: SecretFinding[]; overridden: SecretFinding[] } {
+	const fileLineCache = new Map<string, string[]>();
+	const active: SecretFinding[] = [];
+	const overridden: SecretFinding[] = [];
+
+	for (const finding of findings) {
+		if (finding.line === undefined) {
+			active.push(finding);
+			continue;
+		}
+		const absolute = resolve(providerRoot, finding.file);
+		let lines = fileLineCache.get(absolute);
+		if (lines === undefined) {
+			lines = existsSync(absolute) ? readFileSync(absolute, "utf8").split(/\r?\n/) : [];
+			fileLineCache.set(absolute, lines);
+		}
+		if (hasAllowOverride(lines, finding.line, "secret-scan")) {
+			overridden.push(finding);
+		} else {
+			active.push(finding);
+		}
+	}
+
+	return { active, overridden };
+}
+
 function scoreSecrets(providerRoot: string, provider?: ProviderDefinition): SubmitCheck {
-	const findings = findSecretFindings(providerRoot, provider?.id);
-	const blockerFindings = findings.filter((finding) => finding.level !== "warn");
+	const { active, overridden } = partitionSecretScanAllowOverrides(
+		providerRoot,
+		findSecretFindings(providerRoot, provider?.id),
+	);
+	const blockerFindings = active.filter((finding) => finding.level !== "warn");
 	if (blockerFindings.length > 0) {
 		return {
 			id: "secret-scan",
@@ -3568,7 +3797,15 @@ function scoreSecrets(providerRoot: string, provider?: ProviderDefinition): Subm
 			),
 		};
 	}
-	if (findings.length > 0) {
+	if (active.length > 0 || overridden.length > 0) {
+		const messageBase =
+			active.length > 0
+				? "High-entropy source strings were found without secret-like identifier context; they may be false positives."
+				: "Potential credential-like strings were found in shareable files.";
+		const message =
+			overridden.length > 0
+				? `${messageBase} ${overridden.length} acknowledged @apifuse-allow override(s).`
+				: messageBase;
 		return {
 			id: "secret-scan",
 			category: "security",
@@ -3576,11 +3813,10 @@ function scoreSecrets(providerRoot: string, provider?: ProviderDefinition): Subm
 			status: "warn",
 			points: 8,
 			maxPoints: CATEGORY_MAX_POINTS.security,
-			message:
-				"High-entropy source strings were found without secret-like identifier context; they may be false positives.",
+			message,
 			remediation:
-				'Review the listed strings. If any are credentials, move them to env vars read via `ctx.env.get("APIFUSE__PROVIDER__<ID>__<NAME>")` and rotate the leaked credential; otherwise keep generated blobs in fixtures/tests or document why they are public.',
-			evidence: findings.map(
+				'Review the listed strings. If any are credentials, move them to env vars read via `ctx.env.get("APIFUSE__PROVIDER__<ID>__<NAME>")` and rotate the leaked credential; otherwise keep generated blobs in fixtures/tests or document why they are public with `// @apifuse-allow secret-scan: <reason>`.',
+			evidence: [...active, ...overridden].map(
 				(finding) =>
 					finding.evidence ??
 					`${finding.file}${finding.line ? `:${finding.line}` : ""}: ${finding.label}`,
@@ -3611,8 +3847,19 @@ function findSecretFindings(providerRoot: string, providerId = "<ID>"): SecretFi
 		if (!existsSync(filePath)) continue;
 		const content = readFileSync(filePath, "utf8");
 		for (const [label, pattern] of SECRET_PATTERNS) {
-			if (pattern.test(content)) {
-				findings.push({ label, file: relativePath });
+			// Locate every match to its line so pattern findings carry the line
+			// information hasAllowOverride needs: `// @apifuse-allow secret-scan`
+			// must behave uniformly across entropy findings and pattern findings.
+			const globalPattern = new RegExp(
+				pattern.source,
+				pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`,
+			);
+			const seenLines = new Set<number>();
+			for (const match of content.matchAll(globalPattern)) {
+				const line = offsetToLine(content, match.index);
+				if (seenLines.has(line)) continue;
+				seenLines.add(line);
+				findings.push({ label, file: relativePath, line });
 			}
 		}
 	}
@@ -3670,7 +3917,7 @@ export function extractStringLiteralCandidates(line: string): string[] {
 				continue;
 			}
 			if (char === quote) {
-				if (cursor - contentStart >= 20) {
+				if (cursor - contentStart >= ENTROPY_CANDIDATE_MIN_LENGTH) {
 					candidates.push(line.slice(contentStart, cursor));
 				}
 				index = cursor;
@@ -3695,6 +3942,25 @@ function classifyEntropyCandidate(input: {
 	if (!charset) return undefined;
 	const entropy = shannonEntropy(value);
 	const secretishContext = SECRETISH_IDENTIFIER_PATTERN.test(input.line);
+	// Word-like SCREAMING_SNAKE values (e.g. error-code constants such as
+	// "AUTH_PASSWORD_LOGIN_CAPTCHA_REQUIRED") may contain secret-ish words
+	// (AUTH/PASSWORD/...) in their own text and would otherwise be permanently
+	// blocker-flagged. They are never skipped — entropy classification always
+	// runs — but when the secret-ish context comes solely from identifier-
+	// constant-shaped literal text (the line with those literals stripped
+	// carries no secret-ish identifier), the finding is capped at a
+	// non-blocking warning instead of a blocker. Stripping constant-shaped
+	// siblings — not just the candidate — matters for lines holding several
+	// constants (e.g. an ERROR_CODES array), while quoted property keys and
+	// header names ("Authorization", "apiKey") stay visible as genuine
+	// external context. Assignments to `apiKey`/`token`/`secret`-style names
+	// still escalate to blockers via the identifier side, and
+	// `// @apifuse-allow secret-scan` remains the reviewed way to silence the
+	// warning.
+	const selfContextOnlyConstant =
+		secretishContext &&
+		isScreamingSnakeConstantValue(value) &&
+		!SECRETISH_IDENTIFIER_PATTERN.test(stripIdentifierConstantLiterals(input.line, value));
 	const threshold = charset === "hex" ? 3.0 : secretishContext ? 4.0 : 4.5;
 	if (entropy < threshold) return undefined;
 
@@ -3705,16 +3971,163 @@ function classifyEntropyCandidate(input: {
 		charset === "hex"
 			? `high-entropy hex string (${entropy.toFixed(2)} bits/char)`
 			: `high-entropy base64-like string (${entropy.toFixed(2)} bits/char)`;
+	const contextNote = selfContextOnlyConstant
+		? "; identifier-like constant (downgraded to warning)"
+		: secretishContext
+			? ""
+			: "; may be a false positive";
 	return {
 		label,
 		file: input.file,
 		line: input.lineNumber,
-		level: secretishContext ? "blocker" : "warn",
+		level: secretishContext && !selfContextOnlyConstant ? "blocker" : "warn",
 		remediation: `Move ${location} to an env var read via \`ctx.env.get("${envName}")\` and rotate the leaked credential.`,
-		evidence: `${location}: ${label}; preview ${preview}${secretishContext ? "" : "; may be a false positive"}`,
+		evidence: `${location}: ${label}; preview ${preview}${contextNote}`,
 	};
 }
 
+// Word-like SCREAMING_SNAKE identifier shape: at least two underscore-
+// separated segments, each essentially pure alphabetic — letters optionally
+// followed by a SHORT digit suffix (at most 2, e.g. version markers like
+// "V2") — and at most 15% digits across the whole value. Dictionary-style
+// constants like "AUTH_PASSWORD_LOGIN_CAPTCHA_REQUIRED" or
+// "PROVIDER_CONTRACT_V2_REQUIRED" match; digit-heavy segmented material
+// (e.g. license/credential shapes like "ABCD1234_EFGH5678_IJKL9012"),
+// uppercase blobs ("XK9J_Q2ZP_M7VN"), and underscore-free hex-like values
+// ("A1B2C3D4...") do not. This shape gate never skips entropy classification;
+// it only decides whether a finding whose secret-ish context comes solely
+// from the literal's own text is downgraded from blocker to warning, so it
+// deliberately stays strict: values that merely contain a secret-ish word but
+// are not word-like constants keep full blocker severity.
+function isScreamingSnakeConstantValue(value: string): boolean {
+	if (!/^[A-Z][A-Z0-9_]*$/.test(value) || !value.includes("_")) return false;
+	const segments = value.split("_");
+	if (segments.length < 2) return false;
+	if (!segments.every((segment) => /^[A-Z]+[0-9]{0,2}$/.test(segment))) return false;
+	const digitCount = value.match(/[0-9]/g)?.length ?? 0;
+	return digitCount / value.length <= 0.15;
+}
+
+type LineStringLiteral = {
+	// Index of the opening quote.
+	start: number;
+	// Index just past the closing quote (line end when unterminated).
+	end: number;
+	content: string;
+	closed: boolean;
+	role: "key" | "value";
+	// Nearest unclosed bracket enclosing the literal's start, if any.
+	container?: { bracket: "[" | "(" | "{"; index: number };
+};
+
+// Stable identity for the container a literal sits in ("top" when the
+// literal is not inside any bracket on the line).
+function literalContainerKey(literal: LineStringLiteral): string {
+	return literal.container
+		? `${literal.container.bracket}${literal.container.index}`
+		: "top";
+}
+
+// Single-pass line tokenizer: extracts every string literal with its span and
+// classifies its syntactic role once. A literal is a KEY when it is preceded
+// (ignoring whitespace) by "{", ",", "(", or the line start AND followed
+// (ignoring whitespace) by ":" — i.e. it names the value next to it. Every
+// other literal is a VALUE: ternary arms (preceded by "?" or ":"), array
+// elements, call arguments, and assignment right-hand sides, even when a
+// ternary's ":" happens to follow them. Uses the same quote/escape walking as
+// extractStringLiteralCandidates.
+function tokenizeLineStringLiterals(line: string): LineStringLiteral[] {
+	const literals: LineStringLiteral[] = [];
+	const bracketStack: Array<{ bracket: "[" | "(" | "{"; index: number }> = [];
+	let index = 0;
+	while (index < line.length) {
+		const char = line[index];
+		if (char !== '"' && char !== "'" && char !== "`") {
+			if (char === "[" || char === "(" || char === "{") {
+				bracketStack.push({ bracket: char, index });
+			} else if (char === "]" || char === ")" || char === "}") {
+				bracketStack.pop();
+			}
+			index += 1;
+			continue;
+		}
+		const quote = char;
+		const start = index;
+		const contentStart = index + 1;
+		let cursor = contentStart;
+		let closed = false;
+		while (cursor < line.length) {
+			const inner = line[cursor];
+			if (inner === "\\") {
+				cursor += 2;
+				continue;
+			}
+			if (inner === quote) {
+				closed = true;
+				break;
+			}
+			cursor += 1;
+		}
+		const contentEnd = Math.min(cursor, line.length);
+		const end = closed ? cursor + 1 : line.length;
+		const before = line.slice(0, start).trimEnd();
+		const keyPreceded = before === "" || /[{,(]$/.test(before);
+		const keyFollowed = closed && /^\s*:/.test(line.slice(end));
+		literals.push({
+			start,
+			end,
+			content: line.slice(contentStart, contentEnd),
+			closed,
+			role: keyPreceded && keyFollowed ? "key" : "value",
+			container: bracketStack[bracketStack.length - 1],
+		});
+		index = end;
+	}
+	return literals;
+}
+
+// Builds the context text used to decide whether a candidate's secret-ish
+// context is genuine. The candidate's own literal is ALWAYS stripped
+// (self-context rule). SIBLING identifier-constant-shaped candidate literals
+// (VALUE role, SCREAMING_SNAKE shape, >= ENTROPY_CANDIDATE_MIN_LENGTH) are
+// stripped only when they share the candidate's non-call container — the same
+// `[...]` array, the same `{...}` object value list, or the bracket-free top
+// level (ternary arms) — so a value list of error codes cannot poison its own
+// members' context. Call-argument siblings (inside `(...)`) always keep their
+// context: in `headers.set("X_LONG_AUTH_TOKEN_NAME", "QWERTY_...")` the first
+// argument genuinely describes the second, so stripping it would erase real
+// auth/token context. KEY-role literals are never stripped.
+function stripIdentifierConstantLiterals(line: string, candidate: string): string {
+	const literals = tokenizeLineStringLiterals(line);
+	const candidateContainers = new Set<string>();
+	for (const literal of literals) {
+		if (literal.content === candidate) {
+			candidateContainers.add(literalContainerKey(literal));
+		}
+	}
+	let result = "";
+	let previousEnd = 0;
+	for (const literal of literals) {
+		result += line.slice(previousEnd, literal.start);
+		const isSelf = literal.content === candidate;
+		const isSameNonCallContainerSibling =
+			literal.role === "value" &&
+			literal.content.length >= ENTROPY_CANDIDATE_MIN_LENGTH &&
+			isScreamingSnakeConstantValue(literal.content) &&
+			literal.container?.bracket !== "(" &&
+			candidateContainers.has(literalContainerKey(literal));
+		if (isSelf || isSameNonCallContainerSibling) {
+			const quote = line[literal.start] ?? "";
+			result += quote + (literal.closed ? quote : "");
+		} else {
+			result += line.slice(literal.start, literal.end);
+		}
+		previousEnd = literal.end;
+	}
+	result += line.slice(previousEnd);
+	return result;
+}
+
 function shouldConsiderEntropyValue(value: string): boolean {
 	const lower = value.toLowerCase();
 	if (/^(?:dev-only|local|example|sample|your-|replace|<)/i.test(value)) {
@@ -3730,7 +4143,7 @@ function shouldConsiderEntropyValue(value: string): boolean {
 	if (lower.includes("/") && /\.[a-z0-9]{1,8}(?:$|[/?#])/i.test(value)) {
 		return false;
 	}
-	return value.length >= 20;
+	return value.length >= ENTROPY_CANDIDATE_MIN_LENGTH;
 }
 
 function classifyEntropyCharset(value: string): "base64" | "hex" | undefined {
@@ -3764,6 +4177,11 @@ function guessSecretName(line: string): string {
 
 const SECRETISH_IDENTIFIER_PATTERN = /key|token|secret|password|credential|auth/i;
 
+// Minimum length for a string literal to be considered an entropy candidate.
+// Shared by candidate extraction, entropy screening, and the context strip so
+// the three stay coherent.
+const ENTROPY_CANDIDATE_MIN_LENGTH = 20;
+
 const SECRET_PATTERNS: Array<[string, RegExp]> = [
 	["JWT-like token", /eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}/],
 	["GitHub token", /gh[pousr]_[A-Za-z0-9_]{30,}/],

package/bin/apifuse-sync-assets.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+
+import {
+	formatPromptAssetIssues,
+	installedSdkVersion,
+	syncPromptAssets,
+	verifyPromptAssets,
+} from "../src/cli/prompt-assets.js";
+import { resolveProviderRoot } from "./apifuse-check.js";
+
+const HELP_TEXT = `Usage: apifuse sync-assets [path] [--check]
+Example: apifuse sync-assets .
+Default: apifuse sync-assets .
+
+Regenerates the SDK-managed agent prompt assets for the installed SDK version:
+AGENTS.md, .agents/skills/**, the CLAUDE.md/.claude/.codex symlinks, and the
+.apifuse/prompt-assets.json manifest. Legacy top-level skills/ layouts are
+migrated. Idempotent.
+
+Options:
+  --check        Verify only; exit 1 with a diff list when assets are stale/missing/modified
+  --help, -h     Show this help`;
+
+export async function main() {
+	const args = normalizeArgs(process.argv.slice(2));
+
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(HELP_TEXT);
+		return;
+	}
+
+	let checkOnly = false;
+	let inputPath: string | undefined;
+	for (const arg of args) {
+		if (arg === "--check") {
+			checkOnly = true;
+			continue;
+		}
+		if (arg.startsWith("-")) {
+			throw new Error(`Unknown option: ${arg}`);
+		}
+		if (inputPath !== undefined) {
+			throw new Error(`Unexpected argument: ${arg}`);
+		}
+		inputPath = arg;
+	}
+
+	const providerRoot = resolveProviderRoot(inputPath ?? ".");
+
+	if (checkOnly) {
+		const verification = verifyPromptAssets(providerRoot);
+		if (verification.ok) {
+			console.log(
+				`Prompt assets are in sync with the installed SDK (${installedSdkVersion()}): ${providerRoot}`,
+			);
+			return;
+		}
+		console.error(`Prompt assets are out of sync in ${providerRoot}:`);
+		for (const issue of formatPromptAssetIssues(verification)) {
+			console.error(`  - ${issue}`);
+		}
+		console.error("\nRun `bun run sync-assets` (or `bunx apifuse sync-assets .`) to regenerate.");
+		process.exit(1);
+	}
+
+	const result = syncPromptAssets(providerRoot);
+
+	// Honesty gate: writes alone never imply success. sync-assets intentionally
+	// PRESERVES (does not delete) unauthorized skills and symlinks under
+	// .agents/skills, so it can return changed:false while verify still fails.
+	// Re-verify AFTER writing and let the true post-sync state drive the exit
+	// code — never claim success while the freshness gate would reject the tree.
+	const verification = verifyPromptAssets(providerRoot);
+
+	if (result.changed) {
+		for (const removed of result.removed) {
+			console.log(`removed  ${removed}`);
+		}
+		for (const wrote of result.wroteFiles) {
+			console.log(`wrote    ${wrote}`);
+		}
+		for (const link of result.createdSymlinks) {
+			console.log(`symlink  ${link}`);
+		}
+		console.log(`manifest ${result.manifestPath} (sdkVersion ${installedSdkVersion()})`);
+	}
+
+	if (!verification.ok) {
+		console.error(`\nPrompt assets are still out of sync in ${providerRoot}:`);
+		for (const issue of formatPromptAssetIssues(verification)) {
+			console.error(`  - ${issue}`);
+		}
+		console.error(
+			"\nsync-assets never deletes unrecognized content: resolve these by hand — remove any unauthorized skill directory or symlink under .agents/skills/, migrate a real .claude/.codex directory into .agents/ — then re-run `apifuse sync-assets .`.",
+		);
+		process.exit(1);
+	}
+
+	if (!result.changed) {
+		console.log(
+			`Prompt assets already in sync with the installed SDK (${installedSdkVersion()}): ${providerRoot}`,
+		);
+		return;
+	}
+	console.log(`\nPrompt assets synced: ${providerRoot}`);
+}
+
+function normalizeArgs(argv: string[]): string[] {
+	return argv[0] === "sync-assets" ? argv.slice(1) : argv;
+}
+
+if (import.meta.main) {
+	await main().catch((error: unknown) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}

package/dist/cli/commands.d.ts

@@ -1,4 +1,4 @@
-export type ApifuseCommandName = "create" | "dev" | "check" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
+export type ApifuseCommandName = "create" | "dev" | "check" | "sync-assets" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
 export type ApifuseCommandManifest = {
     name: ApifuseCommandName;
     summary: string;