@farming-labs/docs 0.2.120 → 0.2.121

package/dist/agent-skills-archive.mjs

@@ -0,0 +1,86 @@
+//#region src/agent-skills-archive.ts
+const TAR_BLOCK_BYTES = 512;
+const TAR_NAME_BYTES = 100;
+const TAR_PREFIX_OFFSET = 345;
+const TAR_PREFIX_BYTES = 155;
+const AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES = 10 * 1024 * 1024;
+const AGENT_SKILL_DOCUMENT_MAX_BYTES = 1024 * 1024;
+function isZeroBlock(block) {
+	return block.every((byte) => byte === 0);
+}
+function readTarText(header, offset, length, field) {
+	const bytes = header.subarray(offset, offset + length);
+	const terminator = bytes.indexOf(0);
+	const value = terminator < 0 ? bytes : bytes.subarray(0, terminator);
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(value);
+	} catch {
+		throw new Error(`Agent Skill archive has invalid UTF-8 in its ${field}.`);
+	}
+}
+function readTarOctal(header, offset, length, field) {
+	const value = readTarText(header, offset, length, field).trim();
+	if (!/^[0-7]+$/u.test(value)) throw new Error(`Agent Skill archive has an invalid ${field}.`);
+	const parsed = Number.parseInt(value, 8);
+	if (!Number.isSafeInteger(parsed) || parsed < 0) throw new Error(`Agent Skill archive has an unsafe ${field}.`);
+	return parsed;
+}
+function validateTarChecksum(header) {
+	const expected = readTarOctal(header, 148, 8, "header checksum");
+	if (header.reduce((sum, byte, index) => {
+		return sum + (index >= 148 && index < 156 ? 32 : byte);
+	}, 0) !== expected) throw new Error("Agent Skill archive has an invalid tar header checksum.");
+}
+/**
+* Extract the root SKILL.md from an uncompressed Agent Skill tar archive.
+*
+* Only the regular-file payload is returned; duplicate, oversized, malformed,
+* or non-UTF-8 documents are rejected before frontmatter validation.
+*/
+function readAgentSkillDocumentFromTar(archive) {
+	if (archive.byteLength > AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES) throw new Error(`Agent Skill archive exceeds ${AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES} uncompressed bytes.`);
+	let skillDocument;
+	let offset = 0;
+	let foundEndOfArchive = false;
+	while (offset < archive.byteLength) {
+		if (offset + TAR_BLOCK_BYTES > archive.byteLength) throw new Error("Agent Skill archive contains a truncated tar header.");
+		const header = archive.subarray(offset, offset + TAR_BLOCK_BYTES);
+		if (isZeroBlock(header)) {
+			const secondZeroBlockStart = offset + TAR_BLOCK_BYTES;
+			const secondZeroBlockEnd = secondZeroBlockStart + TAR_BLOCK_BYTES;
+			if (secondZeroBlockEnd > archive.byteLength) throw new Error("Agent Skill archive contains a truncated end-of-archive marker.");
+			if (!isZeroBlock(archive.subarray(secondZeroBlockStart, secondZeroBlockEnd))) throw new Error("Agent Skill archive is missing the second end-of-archive block.");
+			if (!archive.subarray(secondZeroBlockEnd).every((byte) => byte === 0)) throw new Error("Agent Skill archive contains non-zero bytes after its end marker.");
+			foundEndOfArchive = true;
+			break;
+		}
+		validateTarChecksum(header);
+		const name = readTarText(header, 0, TAR_NAME_BYTES, "file name");
+		const prefix = readTarText(header, TAR_PREFIX_OFFSET, TAR_PREFIX_BYTES, "file prefix");
+		const path = prefix ? `${prefix}/${name}` : name;
+		const size = readTarOctal(header, 124, 12, "file size");
+		const contentStart = offset + TAR_BLOCK_BYTES;
+		const contentEnd = contentStart + size;
+		if (contentEnd > archive.byteLength) throw new Error(`Agent Skill archive entry ${JSON.stringify(path)} is truncated.`);
+		const typeFlag = header[156];
+		if (path === "SKILL.md") {
+			if (typeFlag !== 0 && typeFlag !== "0".charCodeAt(0)) throw new Error("Agent Skill archive root SKILL.md must be a regular file.");
+			if (skillDocument) throw new Error("Agent Skill archive contains more than one root SKILL.md.");
+			if (size > AGENT_SKILL_DOCUMENT_MAX_BYTES) throw new Error(`Agent Skill archive SKILL.md exceeds ${AGENT_SKILL_DOCUMENT_MAX_BYTES} bytes.`);
+			skillDocument = archive.subarray(contentStart, contentEnd);
+		}
+		const nextOffset = contentStart + Math.ceil(size / TAR_BLOCK_BYTES) * TAR_BLOCK_BYTES;
+		if (nextOffset > archive.byteLength) throw new Error(`Agent Skill archive entry ${JSON.stringify(path)} has truncated padding.`);
+		offset = nextOffset;
+	}
+	if (!foundEndOfArchive) throw new Error("Agent Skill archive is missing its end-of-archive marker.");
+	if (!skillDocument) throw new Error("Agent Skill archive does not contain a root SKILL.md.");
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(skillDocument);
+	} catch {
+		throw new Error("Agent Skill archive SKILL.md is not valid UTF-8.");
+	}
+}
+
+//#endregion
+export { AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES, readAgentSkillDocumentFromTar };

package/dist/agent-skills-bundle.d.mts

@@ -1,4 +1,4 @@
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-BHPc7YIX.mjs";
+import { DocsPublishedAgentSkill } from "./standards-discovery.mjs";
 
 //#region src/agent-skills-bundle.d.ts
 /**

package/dist/{agent-skills-progressive-disclosure-PjPtTYL-.mjs → agent-skills-progressive-disclosure.mjs}

@@ -1,5 +1,5 @@
 import { validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
-import { n as resolveConfiguredAgentSkillPathsSync } from "./agent-skills-server-BC7md56k.mjs";
+import { resolveConfiguredAgentSkillPathsSync } from "./agent-skills-server.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 
@@ -305,4 +305,4 @@ function analyzeConfiguredAgentSkillsProgressiveDisclosure(input, options = {})
 }
 
 //#endregion
-export { estimateAgentSkillInstructionTokens as n, resolveDocsAgentSkillsProgressiveDisclosureConfig as r, analyzeConfiguredAgentSkillsProgressiveDisclosure as t };
+export { analyzeConfiguredAgentSkillsProgressiveDisclosure, estimateAgentSkillInstructionTokens, resolveDocsAgentSkillsProgressiveDisclosureConfig };

package/dist/{agent-skills-server-D5IuvwM7.d.mts → agent-skills-server.d.mts}

@@ -1,5 +1,5 @@
-import { pt as DocsAgentSkillsInput } from "./types-BJFeMXWZ.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-BHPc7YIX.mjs";
+import { DocsAgentSkillsInput } from "./types.mjs";
+import { DocsPublishedAgentSkill } from "./standards-discovery.mjs";
 
 //#region src/agent-skills-server.d.ts
 interface ResolveConfiguredAgentSkillsOptions {
@@ -11,4 +11,4 @@ declare function resolveConfiguredAgentSkillsSync(input: DocsAgentSkillsInput |
 /** Resolve and package configured skills without blocking runtime filesystem or compression work. */
 declare function resolveConfiguredAgentSkills(input: DocsAgentSkillsInput | undefined, options?: ResolveConfiguredAgentSkillsOptions): Promise<DocsPublishedAgentSkill[]>;
 //#endregion
-export { resolveConfiguredAgentSkills as n, resolveConfiguredAgentSkillsSync as r, ResolveConfiguredAgentSkillsOptions as t };
+export { ResolveConfiguredAgentSkillsOptions, resolveConfiguredAgentSkills, resolveConfiguredAgentSkillsSync };

package/dist/{agent-skills-server-BC7md56k.mjs → agent-skills-server.mjs}

@@ -1,4 +1,4 @@
-import { f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, j as buildDocsPublishedAgentSkill } from "./standards-discovery-sSEojU80.mjs";
+import { DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, buildDocsPublishedAgentSkill } from "./standards-discovery.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { access, lstat, readFile, readdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
@@ -603,4 +603,4 @@ async function resolveConfiguredAgentSkills(input, options = {}) {
 }
 
 //#endregion
-export { resolveConfiguredAgentSkillsSync as i, resolveConfiguredAgentSkillPathsSync as n, resolveConfiguredAgentSkills as r, getDocsAgentSkillsConfiguredPaths as t };
+export { getDocsAgentSkillsConfiguredPaths, resolveConfiguredAgentSkillPathsSync, resolveConfiguredAgentSkills, resolveConfiguredAgentSkillsSync };

package/dist/agent-skills-vite.d.mts

@@ -1,6 +1,6 @@
-import { pt as DocsAgentSkillsInput } from "./types-BJFeMXWZ.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-BHPc7YIX.mjs";
-import { t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-D5IuvwM7.mjs";
+import { DocsAgentSkillsInput } from "./types.mjs";
+import { DocsPublishedAgentSkill } from "./standards-discovery.mjs";
+import { ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server.mjs";
 
 //#region src/agent-skills-vite.d.ts
 declare const DOCS_AGENT_SKILLS_BUNDLE_MODULE = "@farming-labs/docs/agent-skills-bundle";

package/dist/agent-skills-vite.mjs

@@ -1,5 +1,4 @@
-import "./standards-discovery-sSEojU80.mjs";
-import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-BC7md56k.mjs";
+import { resolveConfiguredAgentSkills } from "./agent-skills-server.mjs";
 
 //#region src/agent-skills-vite.ts
 const DOCS_AGENT_SKILLS_BUNDLE_MODULE = "@farming-labs/docs/agent-skills-bundle";

package/dist/agent-surface-drift.mjs

@@ -0,0 +1,236 @@
+//#region src/agent-surface-drift.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeDotPath(value) {
+	const segments = value.trim().replace(/\[\d+\]/gu, "[]").replace(/^\/+|\/+$/g, "").replaceAll("/", ".").split(".").map((segment) => segment.trim()).filter(Boolean);
+	const normalized = [];
+	for (const segment of segments) {
+		if (/^\d+$/u.test(segment) && normalized.length > 0) {
+			normalized[normalized.length - 1] = `${normalized.at(-1)}[]`;
+			continue;
+		}
+		normalized.push(segment);
+	}
+	return normalized.join(".");
+}
+function collectSchemaPaths(options) {
+	const paths = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const visit = (option) => {
+		if (visited.has(option)) return;
+		visited.add(option);
+		const optionPath = normalizeDotPath(option.path);
+		if (optionPath) paths.add(optionPath);
+		for (const child of option.children ?? []) visit(child);
+	};
+	for (const option of options) visit(option);
+	return paths;
+}
+function schemaCoversConfigPath(schemaPaths, configPath) {
+	if (schemaPaths.has(configPath)) return true;
+	if (configPath.endsWith("[]") && schemaPaths.has(configPath.slice(0, -2))) return true;
+	for (const schemaPath of schemaPaths) {
+		if (!schemaPath.endsWith(".*")) continue;
+		const prefix = schemaPath.slice(0, -1);
+		if (configPath.startsWith(prefix) && configPath.length > prefix.length) return true;
+	}
+	return false;
+}
+function readPath(root, dotPath) {
+	const normalized = normalizeDotPath(dotPath);
+	if (!normalized) return {
+		present: true,
+		value: root
+	};
+	let current = root;
+	for (const segment of normalized.split(".")) {
+		if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, segment)) return {
+			present: false,
+			value: void 0
+		};
+		current = current[segment];
+	}
+	return {
+		present: true,
+		value: current
+	};
+}
+function stableJsonValue(value) {
+	if (Array.isArray(value)) return value.map(stableJsonValue);
+	if (!isRecord(value)) return value;
+	return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableJsonValue(value[key])]));
+}
+function displayValue(value, present = true) {
+	if (!present || value === void 0) return "<missing>";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+	try {
+		return JSON.stringify(stableJsonValue(value));
+	} catch {
+		return "<unserializable>";
+	}
+}
+function valuesMatch(actual, expected) {
+	if (!actual.present) return false;
+	if (Object.is(actual.value, expected)) return true;
+	if ((Array.isArray(actual.value) || isRecord(actual.value)) && (Array.isArray(expected) || isRecord(expected))) return displayValue(actual.value) === displayValue(expected);
+	return false;
+}
+function mismatchIssue(code, path, expected, actual, label) {
+	const expectedDisplay = displayValue(expected);
+	const actualDisplay = displayValue(actual.value, actual.present);
+	return {
+		code,
+		path,
+		expected: expectedDisplay,
+		actual: actualDisplay,
+		message: `${label} is ${actualDisplay}; expected ${expectedDisplay}.`
+	};
+}
+function compareExpectedValue(issues, discovery, code, path, expected, label) {
+	const actual = readPath(discovery, path);
+	if (!valuesMatch(actual, expected)) issues.push(mismatchIssue(code, path, expected, actual, label));
+}
+/**
+* Compare independently resolved docs values with the public agent discovery and
+* config-schema surfaces. The helper is intentionally pure so doctor, review,
+* and golden evaluations can use the same deterministic drift rules.
+*/
+function analyzeAgentSurfaceDrift(options) {
+	const issues = [];
+	const schemaPaths = collectSchemaPaths(options.schemaOptions);
+	const configPaths = Array.from(new Set(options.configOptionPaths.map(normalizeDotPath).filter(Boolean))).sort();
+	for (const configPath of configPaths) {
+		if (schemaCoversConfigPath(schemaPaths, configPath)) continue;
+		issues.push({
+			code: "config-schema-omission",
+			path: configPath,
+			expected: "documented schema option",
+			actual: "<missing>",
+			message: `Config option ${JSON.stringify(configPath)} is present but missing from the published config schema.`
+		});
+	}
+	const canonicalFields = Array.from(new Set(options.agentContractFields.map((field) => field.trim()).filter(Boolean))).sort();
+	const discoveredFieldsValue = readPath(options.discovery, "agentContract.fields");
+	const discoveredFields = isRecord(discoveredFieldsValue.value) ? Object.keys(discoveredFieldsValue.value).sort() : [];
+	const canonicalFieldSet = new Set(canonicalFields);
+	const discoveredFieldSet = new Set(discoveredFields);
+	for (const field of canonicalFields) {
+		if (discoveredFieldSet.has(field)) continue;
+		const issuePath = `agentContract.fields.${field}`;
+		issues.push({
+			code: "agent-contract-field-missing",
+			path: issuePath,
+			expected: "canonical field",
+			actual: "<missing>",
+			message: `Discovery agent contract is missing canonical field ${JSON.stringify(field)}.`
+		});
+	}
+	for (const field of discoveredFields) {
+		if (canonicalFieldSet.has(field)) continue;
+		const issuePath = `agentContract.fields.${field}`;
+		issues.push({
+			code: "agent-contract-field-unexpected",
+			path: issuePath,
+			expected: "<absent>",
+			actual: "declared field",
+			message: `Discovery agent contract advertises non-canonical field ${JSON.stringify(field)}.`
+		});
+	}
+	compareExpectedValue(issues, options.discovery, "entry-mismatch", "site.entry", options.expected.entry, "Discovery site.entry");
+	compareExpectedValue(issues, options.discovery, "search-enabled-mismatch", "search.enabled", options.expected.search.enabled, "Discovery search.enabled");
+	compareExpectedValue(issues, options.discovery, "search-capability-mismatch", "capabilities.search", options.expected.search.enabled, "Discovery capabilities.search");
+	compareExpectedValue(issues, options.discovery, "search-route-mismatch", "search.endpoint", options.expected.search.endpoint, "Discovery search.endpoint");
+	const expectedAgentSearchEndpoint = options.expected.search.endpoint === null ? null : `${options.expected.search.endpoint}${options.expected.search.endpoint.includes("?") ? "&" : "?"}audience=agent`;
+	compareExpectedValue(issues, options.discovery, "search-audience-mismatch", "search.agentEndpoint", expectedAgentSearchEndpoint, "Discovery search.agentEndpoint");
+	compareExpectedValue(issues, options.discovery, "search-audience-mismatch", "search.audienceParam", "audience", "Discovery search.audienceParam");
+	compareExpectedValue(issues, options.discovery, "search-audience-mismatch", "search.defaultAudience", "human", "Discovery search.defaultAudience");
+	compareExpectedValue(issues, options.discovery, "search-audience-mismatch", "search.supportedAudiences", ["human", "agent"], "Discovery search.supportedAudiences");
+	const expectedStructuredAgentSearchEndpoint = expectedAgentSearchEndpoint === null ? null : `${expectedAgentSearchEndpoint}&response=structured`;
+	const expectedSearchFacetsEndpoint = expectedAgentSearchEndpoint === null ? null : expectedAgentSearchEndpoint.replace("query={query}&audience=agent", "audience=agent&response=facets");
+	const expectedExplainedAgentSearchEndpoint = expectedStructuredAgentSearchEndpoint === null ? null : `${expectedStructuredAgentSearchEndpoint}&explain=true`;
+	for (const [path, expected] of [
+		["search.structuredAgentEndpoint", expectedStructuredAgentSearchEndpoint],
+		["search.explainedAgentEndpoint", expectedExplainedAgentSearchEndpoint],
+		["search.facetsEndpoint", expectedSearchFacetsEndpoint],
+		["search.responseParam", "response"],
+		["search.structuredResponseValue", "structured"],
+		["search.facetsResponseValue", "facets"],
+		["search.responseFormat", "docs-search.v1"],
+		["search.explainParam", "explain"],
+		["search.explainValue", "true"],
+		["search.explanationField", "explanation"],
+		["search.explanationFormat", "docs-search-explanation.v1"],
+		["search.facetsResponseFormat", "docs-search-facets.v1"],
+		["search.filterParams", {
+			framework: "framework",
+			version: "version",
+			package: "package",
+			tags: "tags"
+		}],
+		["search.repeatedFilterParams", [
+			"framework",
+			"version",
+			"package",
+			"tags"
+		]],
+		["search.warningsField", "warnings"],
+		["search.facetParam", "facet"],
+		["search.limitParam", "limit"],
+		["search.cursorParam", "cursor"],
+		["search.nextCursorField", "nextCursor"],
+		["search.hasMoreField", "hasMore"],
+		["search.totalField", "total"]
+	]) compareExpectedValue(issues, options.discovery, "search-scope-mismatch", path, expected, `Discovery ${path}`);
+	compareExpectedValue(issues, options.discovery, "mcp-enabled-mismatch", "mcp.enabled", options.expected.mcp.enabled, "Discovery mcp.enabled");
+	compareExpectedValue(issues, options.discovery, "mcp-capability-mismatch", "capabilities.mcp", options.expected.mcp.enabled, "Discovery capabilities.mcp");
+	compareExpectedValue(issues, options.discovery, "mcp-route-mismatch", "mcp.endpoint", options.expected.mcp.endpoint, "Discovery mcp.endpoint");
+	if (options.expected.mcp.protectedResource !== void 0) {
+		const expectedProtectedResource = options.expected.mcp.protectedResource;
+		const discoveredProtectedResource = readPath(options.discovery, "mcp.protectedResource");
+		if (expectedProtectedResource === null) {
+			if (discoveredProtectedResource.present) issues.push(mismatchIssue("mcp-protected-resource-mismatch", "mcp.protectedResource", void 0, discoveredProtectedResource, "Discovery mcp.protectedResource"));
+		} else for (const field of [
+			"metadataEndpoints",
+			"authorizationServers",
+			"scopesSupported",
+			"requiredScopes"
+		]) compareExpectedValue(issues, options.discovery, "mcp-protected-resource-mismatch", `mcp.protectedResource.${field}`, expectedProtectedResource[field], `Discovery mcp.protectedResource.${field}`);
+	}
+	const expectedToolNames = Object.keys(options.expected.mcp.tools).sort();
+	const expectedToolSet = new Set(expectedToolNames);
+	const discoveredToolsValue = readPath(options.discovery, "mcp.tools");
+	const discoveredTools = isRecord(discoveredToolsValue.value) ? discoveredToolsValue.value : {};
+	for (const toolName of expectedToolNames) {
+		const expected = options.expected.mcp.tools[toolName];
+		const path = `mcp.tools.${toolName}`;
+		const actual = Object.prototype.hasOwnProperty.call(discoveredTools, toolName) ? {
+			present: true,
+			value: discoveredTools[toolName]
+		} : {
+			present: false,
+			value: void 0
+		};
+		if (!valuesMatch(actual, expected)) issues.push(mismatchIssue("mcp-tool-mismatch", path, expected, actual, `Discovery ${path}`));
+	}
+	for (const toolName of Object.keys(discoveredTools).sort()) {
+		if (expectedToolSet.has(toolName)) continue;
+		const path = `mcp.tools.${toolName}`;
+		issues.push({
+			code: "mcp-tool-unexpected",
+			path,
+			expected: "<absent>",
+			actual: displayValue(discoveredTools[toolName]),
+			message: `Discovery MCP tools advertise unexpected tool flag ${JSON.stringify(toolName)}.`
+		});
+	}
+	for (const routePath of Object.keys(options.expected.routes).sort()) {
+		const expected = options.expected.routes[routePath];
+		compareExpectedValue(issues, options.discovery, "route-mismatch", routePath, expected, `Discovery ${routePath}`);
+	}
+	return issues.sort((left, right) => left.path.localeCompare(right.path) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message));
+}
+
+//#endregion
+export { analyzeAgentSurfaceDrift };