@farming-labs/docs 0.2.52 → 0.2.53

package/dist/{types-XqGLsmOD.d.mts → types-CdKu8KmO.d.mts}

@@ -246,12 +246,62 @@ type DocsRelatedItem = string;
 interface ResolvedDocsRelatedLink {
   href: string;
 }
+interface PageAgentAppliesTo {
+  /** Framework name or names this task applies to, for example `"nextjs"`. */
+  framework?: string | string[];
+  /** Version range or ranges this task applies to, for example `">=16"`. */
+  version?: string | string[];
+  /** Package name or names this task applies to, for example `"@farming-labs/next"`. */
+  package?: string | string[];
+}
+interface PageAgentCommand {
+  /** Exact command an agent may run. */
+  run: string;
+  /** Optional working directory, relative to the project root unless documented otherwise. */
+  cwd?: string;
+  /** Short explanation of what the command does. */
+  description?: string;
+}
+interface PageAgentVerification {
+  /** Human-readable verification step. */
+  description?: string;
+  /** Optional command used to verify the result. */
+  run?: string;
+  /** Observable result that indicates success. */
+  expect?: string;
+}
+interface PageAgentFailureMode {
+  /** Symptom an agent may observe. */
+  symptom: string;
+  /** Recovery guidance for the symptom. */
+  resolution?: string;
+}
 interface PageAgentFrontmatter {
   /**
    * Approximate output token target for machine-readable compaction on this page.
    * Used by `docs agent compact` as a per-page override.
    */
   tokenBudget?: number;
+  /** Concrete task the page helps an agent complete. */
+  task?: string;
+  /** Observable end state the agent should reach. */
+  outcome?: string;
+  /** Framework, version, and package applicability constraints. */
+  appliesTo?: PageAgentAppliesTo;
+  /** Conditions or setup that must already be true. */
+  prerequisites?: string[];
+  /** Files the task is expected to read or change. */
+  files?: string[];
+  /** Commands the task may require. Strings are supported as a concise shorthand. */
+  commands?: Array<string | PageAgentCommand>;
+  /** Material state changes or external effects the task can cause. */
+  sideEffects?: string[];
+  /** Checks that prove the task completed successfully. */
+  verification?: Array<string | PageAgentVerification>;
+  /** Steps that restore the previous state when the task must be undone. */
+  rollback?: string[];
+  /** Common symptoms and optional recovery guidance. */
+  failureModes?: Array<string | PageAgentFailureMode>;
 }
 interface PageSidebarFrontmatter {
   /**
@@ -1133,6 +1183,10 @@ interface DocsMcpToolsConfig {
   listPages?: boolean;
   /** Expose a `read_page` tool that returns a page by slug or URL path. */
   readPage?: boolean;
+  /** Expose a `list_tasks` tool for pages with actionable agent contracts. */
+  listTasks?: boolean;
+  /** Expose a `read_task` tool that returns a page's full agent contract. */
+  readTask?: boolean;
   /** Expose a `search_docs` tool for keyword search over page content. */
   searchDocs?: boolean;
   /** Expose a `get_navigation` tool for the docs tree. */
@@ -1141,6 +1195,65 @@ interface DocsMcpToolsConfig {
   getCodeExamples?: boolean;
   /** Expose a `get_config_schema` tool for docs.config option metadata. */
   getConfigSchema?: boolean;
+  /** Expose deterministic `get_context` retrieval with a conservative UTF-8 byte ceiling. */
+  getContext?: boolean;
+}
+/** Authenticated identity returned by an MCP authentication callback. */
+interface DocsMcpAuthPrincipal {
+  /** Stable identifier for the authenticated user, service, or agent. */
+  id: string;
+  /** Optional authorization scopes that source adapters can inspect. */
+  scopes?: string[];
+  /** Additional application-specific identity claims. */
+  claims?: Record<string, unknown>;
+}
+/** Context passed to an MCP Origin policy callback. */
+interface DocsMcpOriginContext {
+  /** Origin header supplied by the HTTP client. */
+  origin: string;
+  /** Portable Web Request for the incoming MCP request. */
+  request: Request;
+}
+/** Context passed to an opt-in MCP authentication callback. */
+interface DocsMcpAuthenticateContext {
+  /** Portable Web Request for the incoming MCP request. */
+  request: Request;
+  /** Normalized pathname of the MCP endpoint being requested. */
+  pathname: string;
+}
+type DocsMcpAllowedOrigins = "same-origin" | readonly string[] | ((context: DocsMcpOriginContext) => boolean | Promise<boolean>);
+type DocsMcpAuthenticateResult = DocsMcpAuthPrincipal | null | Response;
+type DocsMcpAuthenticate = (context: DocsMcpAuthenticateContext) => DocsMcpAuthenticateResult | Promise<DocsMcpAuthenticateResult>;
+/** Browser CORS response controls for an Origin already accepted by `allowedOrigins`. */
+interface DocsMcpCorsConfig {
+  /** Additional request headers accepted during browser preflight. */
+  allowedHeaders?: readonly string[];
+  /** Additional response headers exposed to browser clients. */
+  exposedHeaders?: readonly string[];
+  /** Emit `Access-Control-Allow-Credentials: true`. Defaults to `false`. */
+  allowCredentials?: boolean;
+  /** Browser preflight cache lifetime in seconds. Defaults to 600. */
+  maxAgeSeconds?: number;
+}
+/** Security controls for the Streamable HTTP MCP transport. */
+interface DocsMcpSecurityConfig {
+  /**
+   * Allowed values for a supplied HTTP Origin header.
+   * Defaults to `"same-origin"`. Requests without Origin remain supported for non-browser clients.
+   */
+  allowedOrigins?: DocsMcpAllowedOrigins;
+  /**
+   * Optional authentication callback. HTTP MCP stays public when omitted. When present,
+   * returning `null` rejects the request with 401 and returning a Response passes it through.
+   */
+  authenticate?: DocsMcpAuthenticate;
+  /** Maximum POST body size in bytes. Defaults to 1 MiB. */
+  maxBodyBytes?: number;
+  /**
+   * CORS responses for accepted browser Origins. Defaults to enabled with exact-Origin responses;
+   * set `false` to suppress CORS headers or use an object for credential/header controls.
+   */
+  cors?: boolean | DocsMcpCorsConfig;
 }
 /**
  * Built-in MCP server configuration.
@@ -1169,6 +1282,8 @@ interface DocsMcpConfig {
   version?: string;
   /** Fine-grained tool toggles. Omitted tools stay enabled. */
   tools?: DocsMcpToolsConfig;
+  /** Streamable HTTP security controls. Authentication is opt-in; stdio is unaffected. */
+  security?: DocsMcpSecurityConfig;
 }
 type DocsSearchResultType = "page" | "heading" | "text";
 interface DocsSearchSourcePage {
@@ -1177,6 +1292,7 @@ interface DocsSearchSourcePage {
   content: string;
   description?: string;
   related?: ResolvedDocsRelatedLink[];
+  agent?: PageAgentFrontmatter;
   sourcePath?: string;
   lastModified?: string;
   lastmod?: string;
@@ -2261,7 +2377,7 @@ interface DocsReviewRulesConfig {
   codeFenceMetadata?: DocsReviewSeverity;
   /** Check runnable command/code fences for package manager context. */
   runnableMetadata?: DocsReviewSeverity;
-  /** Suggest machine-facing context for implementation-heavy pages. */
+  /** Validate structured page agent contracts and suggest context for implementation-heavy pages. */
   agentContext?: DocsReviewSeverity;
 }
 interface DocsReviewScoreConfig {
@@ -2962,4 +3078,4 @@ interface DocsConfig {
   og?: OGConfig;
 }
 //#endregion
-export { DocsObservabilityEvent as $, ReadingTimeFormat as $t, DocsAskAIMcpConfig as A, FeedbackConfig as At, DocsCodeBlocksRunnerProvider as B, OpenDocsConfig as Bt, DocsAnalyticsSource as C, DocsTelemetryConfig as Ct, DocsAskAIFeedbackData as D, DocsTelemetryFeatures as Dt, DocsAskAIFeedbackConfig as E, DocsTelemetryEventType as Et, DocsCloudPublishConfig as F, LlmsTxtMaxCharsConfig as Ft, DocsFeedbackData as G, OpenGraphImage as Gt, DocsCodeBlocksValidationMode as H, OpenDocsProviderConfig as Ht, DocsCodeBlocksConfig as I, LlmsTxtMaxCharsMode as It, DocsMcpConfig as J, PageFrontmatter as Jt, DocsFeedbackValue as K, OrderingItem as Kt, DocsCodeBlocksPlannerConfig as L, LlmsTxtSectionConfig as Lt, DocsCloudConfig as M, GithubConfig as Mt, DocsCloudFeatureConfig as N, LastUpdatedConfig as Nt, DocsAskAIFeedbackMessage as O, DocsTelemetryFramework as Ot, DocsCloudPreviewConfig as P, LlmsTxtConfig as Pt, DocsObservabilityConfig as Q, ReadingTimeConfig as Qt, DocsCodeBlocksPlannerProvider as R, McpDocsSearchConfig as Rt, DocsAnalyticsInput as S, DocsTelemetryAgentSurface as St, DocsAskAIActionType as T, DocsTelemetryEventInput as Tt, DocsCodeBlocksValidationPolicy as U, OpenDocsProviderId as Ut, DocsCodeBlocksValidateConfig as V, OpenDocsProvider as Vt, DocsConfig as W, OpenDocsTarget as Wt, DocsMetadata as X, PageSidebarFrontmatter as Xt, DocsMcpToolsConfig as Y, PageOpenGraph as Yt, DocsNav as Z, PageTwitter as Zt, DocsAgentTraceStatus as _, DocsSearchQuery as _t, ApiReferenceRenderer as a, SidebarNode as an, DocsReviewRulesConfig as at, DocsAnalyticsEventInput as b, DocsSearchSourcePage as bt, ChangelogFrontmatter as c, SimpleDocsSearchConfig as cn, DocsRobotsConfig as ct, CopyMarkdownFormat as d, TypographyConfig as dn, DocsSearchAdapterContext as dt, ResolvedDocsRelatedLink as en, DocsObservabilityEventInput as et, CustomDocsSearchConfig as f, UIConfig as fn, DocsSearchAdapterFactory as ft, DocsAgentTraceEventType as g, DocsSearchEmbeddingsConfig as gt, DocsAgentTraceEventInput as h, DocsSearchDocument as ht, ApiReferenceConfig as i, SidebarFolderNode as in, DocsReviewConfig as it, DocsCloudApiKeyConfig as j, FontStyle as jt, DocsAskAIFeedbackValue as k, DocsTheme as kt, CodeBlockCopyData as l, ThemeToggleConfig as ln, DocsRobotsRule as lt, DocsAgentFeedbackData as m, DocsSearchConfig as mt, AgentFeedbackConfig as n, SidebarConfig as nn, DocsReviewCiConfig as nt, BreadcrumbConfig as o, SidebarPageNode as on, DocsReviewScoreConfig as ot, DocsAgentFeedbackContext as p, DocsSearchChunkingConfig as pt, DocsI18nConfig as q, PageActionsConfig as qt, AlgoliaDocsSearchConfig as r, SidebarFolderIndexBehavior as rn, DocsReviewCiMode as rt, ChangelogConfig as s, SidebarTree as sn, DocsReviewSeverity as st, AIConfig as t, SidebarComponentProps as tn, DocsRelatedItem as tt, CopyMarkdownConfig as u, TypesenseDocsSearchConfig as un, DocsSearchAdapter as ut, DocsAnalyticsConfig as v, DocsSearchResult as vt, DocsAskAIActionData as w, DocsTelemetryEvent as wt, DocsAnalyticsEventType as x, DocsSitemapConfig as xt, DocsAnalyticsEvent as y, DocsSearchResultType as yt, DocsCodeBlocksRunnerConfig as z, OGConfig as zt };
+export { DocsMcpConfig as $, OpenGraphImage as $t, DocsAskAIMcpConfig as A, DocsTelemetryAgentSurface as At, DocsCodeBlocksRunnerProvider as B, GithubConfig as Bt, DocsAnalyticsSource as C, TypesenseDocsSearchConfig as Cn, DocsSearchDocument as Ct, DocsAskAIFeedbackData as D, DocsSearchResultType as Dt, DocsAskAIFeedbackConfig as E, DocsSearchResult as Et, DocsCloudPublishConfig as F, DocsTelemetryFeatures as Ft, DocsFeedbackData as G, LlmsTxtSectionConfig as Gt, DocsCodeBlocksValidationMode as H, LlmsTxtConfig as Ht, DocsCodeBlocksConfig as I, DocsTelemetryFramework as It, DocsMcpAllowedOrigins as J, OpenDocsConfig as Jt, DocsFeedbackValue as K, McpDocsSearchConfig as Kt, DocsCodeBlocksPlannerConfig as L, DocsTheme as Lt, DocsCloudConfig as M, DocsTelemetryEvent as Mt, DocsCloudFeatureConfig as N, DocsTelemetryEventInput as Nt, DocsAskAIFeedbackMessage as O, DocsSearchSourcePage as Ot, DocsCloudPreviewConfig as P, DocsTelemetryEventType as Pt, DocsMcpAuthenticateResult as Q, OpenDocsTarget as Qt, DocsCodeBlocksPlannerProvider as R, FeedbackConfig as Rt, DocsAnalyticsInput as S, ThemeToggleConfig as Sn, DocsSearchConfig as St, DocsAskAIActionType as T, UIConfig as Tn, DocsSearchQuery as Tt, DocsCodeBlocksValidationPolicy as U, LlmsTxtMaxCharsConfig as Ut, DocsCodeBlocksValidateConfig as V, LastUpdatedConfig as Vt, DocsConfig as W, LlmsTxtMaxCharsMode as Wt, DocsMcpAuthenticate as X, OpenDocsProviderConfig as Xt, DocsMcpAuthPrincipal as Y, OpenDocsProvider as Yt, DocsMcpAuthenticateContext as Z, OpenDocsProviderId as Zt, DocsAgentTraceStatus as _, SidebarFolderNode as _n, DocsRobotsRule as _t, ApiReferenceRenderer as a, PageAgentFrontmatter as an, DocsNav as at, DocsAnalyticsEventInput as b, SidebarTree as bn, DocsSearchAdapterFactory as bt, ChangelogFrontmatter as c, PageOpenGraph as cn, DocsObservabilityEventInput as ct, CopyMarkdownFormat as d, ReadingTimeConfig as dn, DocsReviewCiMode as dt, OrderingItem as en, DocsMcpCorsConfig as et, CustomDocsSearchConfig as f, ReadingTimeFormat as fn, DocsReviewConfig as ft, DocsAgentTraceEventType as g, SidebarFolderIndexBehavior as gn, DocsRobotsConfig as gt, DocsAgentTraceEventInput as h, SidebarConfig as hn, DocsReviewSeverity as ht, ApiReferenceConfig as i, PageAgentFailureMode as in, DocsMetadata as it, DocsCloudApiKeyConfig as j, DocsTelemetryConfig as jt, DocsAskAIFeedbackValue as k, DocsSitemapConfig as kt, CodeBlockCopyData as l, PageSidebarFrontmatter as ln, DocsRelatedItem as lt, DocsAgentFeedbackData as m, SidebarComponentProps as mn, DocsReviewScoreConfig as mt, AgentFeedbackConfig as n, PageAgentAppliesTo as nn, DocsMcpSecurityConfig as nt, BreadcrumbConfig as o, PageAgentVerification as on, DocsObservabilityConfig as ot, DocsAgentFeedbackContext as p, ResolvedDocsRelatedLink as pn, DocsReviewRulesConfig as pt, DocsI18nConfig as q, OGConfig as qt, AlgoliaDocsSearchConfig as r, PageAgentCommand as rn, DocsMcpToolsConfig as rt, ChangelogConfig as s, PageFrontmatter as sn, DocsObservabilityEvent as st, AIConfig as t, PageActionsConfig as tn, DocsMcpOriginContext as tt, CopyMarkdownConfig as u, PageTwitter as un, DocsReviewCiConfig as ut, DocsAnalyticsConfig as v, SidebarNode as vn, DocsSearchAdapter as vt, DocsAskAIActionData as w, TypographyConfig as wn, DocsSearchEmbeddingsConfig as wt, DocsAnalyticsEventType as x, SimpleDocsSearchConfig as xn, DocsSearchChunkingConfig as xt, DocsAnalyticsEvent as y, SidebarPageNode as yn, DocsSearchAdapterContext as yt, DocsCodeBlocksRunnerConfig as z, FontStyle as zt };

package/dist/{upgrade-DzQtpgJM.mjs → upgrade-BNdBB9tQ.mjs}

@@ -1,5 +1,5 @@
-import { c as fileExists, o as exec } from "./utils-D-xTRNuh.mjs";
-import { a as getPackagesForFramework, c as resolveDocsPackageManager, i as frameworkFromPreset, l as validateUpgradeVersion, n as PRESETS, o as presetFromFramework, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework, t as PACKAGES_BY_FRAMEWORK } from "./package-version-C8PigBZk.mjs";
+import { c as fileExists, o as exec } from "./utils-CMZTjRQT.mjs";
+import { a as getPackagesForFramework, c as resolveDocsPackageManager, i as frameworkFromPreset, l as validateUpgradeVersion, n as PRESETS, o as presetFromFramework, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework, t as PACKAGES_BY_FRAMEWORK } from "./package-version-DxnTZH4m.mjs";
 import path from "node:path";
 import pc from "picocolors";
 import * as p from "@clack/prompts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.2.52",
+  "version": "0.2.53",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",

package/dist/agent-DXDOMJBw.mjs

@@ -1,9 +0,0 @@
-import "./reading-time-CPAy1SWO.mjs";
-import "./agent-CaOBIVFy.mjs";
-import "./search-BWuU70B0.mjs";
-import "./robots-XVPs9lVz.mjs";
-import "./sitemap-server-xEHtDUDB.mjs";
-import "./config-tiQCZ46q.mjs";
-import { a as readPageTokenBudget, i as printAgentCompactHelp, n as inspectAgentCompactionState, o as scanDocsPageTargets, r as parseAgentCompactArgs, t as compactAgentDocs } from "./codeblocks-z9iT794h.mjs";
-
-export { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp };