repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/devdocs/src/catalog.ts
Rawexport type FormatId =
| "html"
| "markdown"
| "text"
| "mdx"
| "rst"
| "man"
| "info"
| "help"
| "javadoc"
| "sphinx"
| "doxygen"
| "docset"
| "json"
| "pdf";
/** Format support is independent of publisher identity and source availability. */
export const formatReaders: ReadonlyArray<{
id: FormatId;
available: boolean;
capability: string;
}> = [
{
id: "html",
available: true,
capability:
"Static HTML headings, anchors, prose and code; no scripts, DOM execution or site search.",
},
{
id: "markdown",
available: true,
capability: "Markdown sections and fenced code; no macro execution.",
},
{
id: "text",
available: true,
capability: "Plain text document; no structural symbol index.",
},
{
id: "mdx",
available: true,
capability:
"Static Markdown/MDX; imports and JSX wrappers omitted, macros retained as inert unsupported text.",
},
{
id: "rst",
available: true,
capability:
"Basic reStructuredText headings and literal blocks; directives retained, never executed.",
},
{
id: "man",
available: true,
capability:
"Installed man rendering or static roff headings/prose; macros are never executed by the static reader.",
},
{
id: "info",
available: true,
capability: "Installed Info rendering or static Info nodes.",
},
{
id: "help",
available: true,
capability: "Installed command help through the local adapter.",
},
{
id: "javadoc",
available: true,
capability:
"Rendered HTML, bounded ZIP/JAR pages, and standard generated search indexes; no Java or index-script execution.",
},
{
id: "sphinx",
available: true,
capability:
"Rendered HTML or bounded objects.inv v2 discovery metadata only; inventory has no documentation bodies.",
},
{
id: "doxygen",
available: true,
capability:
"Rendered HTML plus bounded Doxygen index/tag symbol discovery linked to documentation bodies.",
},
{
id: "docset",
available: true,
capability:
"Installed Dash/Zeal bundle HTML via its read-only SQLite symbol index; remote tgz expansion is unavailable.",
},
{
id: "json",
available: true,
capability:
"Structured JSON entries with exact keys, glyphs and compatibility/provenance fields; no schema inference.",
},
{
id: "pdf",
available: true,
capability:
"PDF text via an already installed pdftotext, fixed arguments and deadline/output limits; tool availability is not guaranteed.",
},
];
export type CatalogSource = {
id: string;
aliases: readonly string[];
domain: string;
home: string;
index: string | null;
format: FormatId;
authority: "publisher" | "standards" | "community" | "host" | "installed";
role: "reference" | "supplemental" | "registry" | "host";
adapter: "upstream" | "local" | "devdocs" | "context7" | "unavailable";
versionSupport: string;
description: string;
/** Only operator-provided, verified release identity may populate these. */
version?: string;
evidence?: string;
};
type Row = [
id: string,
aliases: string,
domain: string,
home: string,
description: string,
];
const rows: Row[] = [
[
"mdn",
"web|javascript|css|html",
"web",
"https://developer.mozilla.org/en-US/docs/Web/",
"Web reference prose; browser compatibility is separate structured data.",
],
[
"mdn-content",
"",
"web",
"https://github.com/mdn/content",
"Source Markdown contains macros; repository revisions and macro normalization need dedicated support.",
],
[
"browser-compat-data",
"bcd",
"web",
"https://raw.githubusercontent.com/mdn/browser-compat-data/main/data.json",
"Structured browser and release compatibility, not reference prose.",
],
[
"whatwg",
"html standard",
"standards",
"https://html.spec.whatwg.org/",
"Living HTML standard; retain section anchors and revision identity.",
],
[
"w3c",
"web standards",
"standards",
"https://www.w3.org/TR/",
"Normative status and specification revision differ from implementation support.",
],
[
"rfc",
"rfc editor",
"protocols",
"https://www.rfc-editor.org/",
"RFC status, revisions, obsoletes and supersedes relationships require explicit evidence.",
],
[
"wcag",
"accessibility|wai",
"accessibility",
"https://www.w3.org/WAI/WCAG22/quickref/",
"WCAG requirements differ from WAI supporting techniques and examples.",
],
[
"webdriver-bidi",
"bidi",
"browser automation",
"https://w3c.github.io/webdriver-bidi/",
"Protocol revision is not browser implementation support.",
],
[
"java",
"jdk|java se|javadoc",
"java",
"https://docs.oracle.com/en/java/javase/",
"Java SE API: JDK release, module, package, class and exact member identity.",
],
[
"java-specs",
"jls|jvms",
"java",
"https://docs.oracle.com/javase/specs/",
"Normative language and VM specifications, not tutorials.",
],
[
"dev-java",
"dev.java",
"java",
"https://dev.java/learn/",
"Publisher-authored Java tutorials, not normative specifications.",
],
[
"maven-central",
"maven",
"jvm",
"https://central.sonatype.com/",
"Group/artifact/version discovery; missing -javadoc.jar artifacts remain misses.",
],
[
"javadoc-io",
"javadoc.io",
"jvm",
"https://javadoc.io/",
"Repository-hosted Javadoc; publisher authority depends on artifact identity.",
],
[
"node",
"nodejs|node.js",
"javascript",
"https://nodejs.org/api/",
"Node API reference; runtime release must be verified separately.",
],
[
"node-learn",
"node diagnostics",
"javascript",
"https://nodejs.org/en/learn",
"Learning and operational diagnostics, separate from API reference.",
],
[
"typescript",
"ts",
"typescript",
"https://www.typescriptlang.org/docs/",
"Compiler-version handbook and language reference.",
],
[
"libuv",
"",
"runtime internals",
"https://docs.libuv.org/",
"Implementation-specific event loop and API behavior.",
],
[
"v8",
"",
"runtime internals",
"https://v8.dev/docs",
"Implementation-specific engine behavior and performance.",
],
[
"v8-source",
"",
"runtime internals",
"https://github.com/v8/v8/tree/main/docs",
"Source documentation; repository revision must be explicit.",
],
[
"rust",
"rustdoc",
"rust",
"https://www.rust-lang.org/learn",
"Rust language documentation; installed rustdoc is a separate local source.",
],
[
"docs-rs",
"docs.rs",
"rust",
"https://docs.rs/",
"Crate/version/target identity; rustdoc JSON compatibility and historical availability are not assumed.",
],
[
"go",
"golang",
"go",
"https://go.dev/doc/",
"Language and toolchain documentation; local go doc is a separate source.",
],
[
"pkg-go-dev",
"pkg.go.dev",
"go",
"https://pkg.go.dev/",
"Module/package/version and OS/architecture build context require verification.",
],
[
"python",
"python3",
"python",
"https://docs.python.org/",
"Python language/library releases; rendered Sphinx pages are readable.",
],
[
"readthedocs",
"read the docs",
"python",
"https://about.readthedocs.com/",
"Hosting platform, not publisher authority; configure the actual project root.",
],
[
"cppreference",
"cpp|c++|c",
"c and c++",
"https://en.cppreference.com/",
"Community reference, not normative ISO standard; distinguish implementation and library versions.",
],
[
"gcc",
"compiler manuals",
"c and c++",
"https://gcc.gnu.org/onlinedocs/",
"Compiler manuals are implementation- and release-specific.",
],
[
"glibc",
"libc",
"c and c++",
"https://www.gnu.org/software/libc/manual/",
"C library manual; installed implementation version is separate evidence.",
],
[
"doxygen",
"",
"c and c++",
"https://www.doxygen.nl/manual/",
"Configure upstream project pages; Doxygen is a format, not an authority.",
],
[
"sqlite",
"sqlite3",
"databases",
"https://sqlite.org/docs.html",
"SQLite dialect, library versions, compile options and extensions.",
],
[
"postgresql",
"postgres",
"databases",
"https://www.postgresql.org/docs/",
"Server-version SQL dialect, extensions and platform requirements.",
],
[
"man7",
"linux man|linux",
"linux",
"https://man7.org/linux/man-pages/",
"Linux userspace manuals preserve manual section; kernel and distro identity differ.",
],
[
"gnu",
"gnu manuals",
"linux userspace",
"https://www.gnu.org/manual/manual.html",
"GNU package manuals; package and manual versions need evidence.",
],
[
"kernel",
"linux kernel",
"linux kernel",
"https://docs.kernel.org/",
"Kernel documentation, not userspace or distribution administration.",
],
[
"systemd",
"",
"linux services",
"https://www.freedesktop.org/software/systemd/man/latest/",
"System/user scope and implementation versions; latest is not installed-version evidence.",
],
[
"freedesktop",
"desktop specifications",
"desktop standards",
"https://specifications.freedesktop.org/",
"Desktop specifications differ from installed implementations.",
],
[
"archwiki",
"arch wiki",
"distribution administration",
"https://wiki.archlinux.org/",
"Community Arch-specific administration; not a cross-distribution assumption.",
],
[
"arch-man",
"arch manuals",
"distribution administration",
"https://man.archlinux.org/",
"Arch package manuals and distribution-specific release context.",
],
[
"arch-news",
"arch news",
"distribution administration",
"https://archlinux.org/news/",
"Time-sensitive distribution advisories must retain publication dates.",
],
[
"microsoft-learn",
"microsoft learn|windows|powershell|dotnet",
"windows",
"https://learn.microsoft.com/",
"Microsoft product documentation; OS, .NET and PowerShell versions differ.",
],
[
"win32",
"windows win32",
"windows",
"https://learn.microsoft.com/en-us/windows/win32/",
"Win32 OS support, API variants, headers and libraries.",
],
[
"win32-api",
"windows sdk",
"windows",
"https://learn.microsoft.com/en-us/windows/win32/api/",
"SDK API reference; preserve header, library and minimum supported OS.",
],
[
"windows-paths",
"windows paths",
"paths",
"https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file",
"Filesystem names versus Win32 namespaces and argument conversion.",
],
[
"msys2",
"msys2 paths",
"paths",
"https://www.msys2.org/docs/filesystem-paths/",
"Shell/native path and argument conversion, not Windows filesystem rules.",
],
[
"bash",
"",
"shells",
"https://www.gnu.org/software/bash/manual/",
"Bash syntax and native argument semantics are shell-specific.",
],
[
"git",
"",
"version control",
"https://git-scm.com/docs",
"Command and recovery semantics depend on installed Git version.",
],
[
"jujutsu",
"jj",
"version control",
"https://docs.jj-vcs.dev/latest/",
"Revision syntax, bookmarks, working-copy and recovery semantics.",
],
[
"github-cli",
"gh",
"github",
"https://cli.github.com/manual/",
"CLI command/version and permissions; retrieval never authorizes mutations.",
],
[
"github-rest",
"github api",
"github",
"https://docs.github.com/en/rest",
"API version, scopes and pagination differ from CLI versions.",
],
[
"github",
"",
"github",
"https://docs.github.com/",
"Product documentation, not authorization for account changes.",
],
[
"nushell",
"nu",
"shells",
"https://www.nushell.sh/book/",
"Typed data and installed syntax; command reference and migration intervals differ.",
],
[
"nushell-commands",
"nu commands",
"shells",
"https://www.nushell.sh/commands/",
"Nushell command reference.",
],
[
"nushell-releases",
"nu releases",
"shells",
"https://www.nushell.sh/blog/",
"Dated release notes and syntax migrations.",
],
[
"mise",
"",
"tooling",
"https://mise.jdx.dev/",
"Configuration discovery, trust, CLI, backends and schema.",
],
[
"niri",
"",
"desktop",
"https://niri-wm.github.io/niri/",
"Compositor config, IPC and installed version support.",
],
[
"wezterm",
"",
"terminal",
"https://wezterm.org/config/files.html",
"Lua API, CLI and renderer support are version-specific.",
],
[
"ast-grep",
"sg",
"structural search",
"https://ast-grep.github.io/",
"Structural syntax matching, not semantic references.",
],
[
"d2",
"",
"diagrams",
"https://d2lang.com/",
"Renderer version, syntax, layout and configuration.",
],
[
"d2-source",
"",
"diagrams",
"https://github.com/terrastruct/d2-docs",
"Source fallback for rendered pages; repository revision is explicit.",
],
[
"mermaid",
"",
"diagrams",
"https://mermaid.js.org/",
"Renderer version, syntax, layouts and configuration.",
],
[
"mdbook",
"",
"documentation tooling",
"https://rust-lang.github.io/mdBook/",
"Version-specific book tooling and configuration.",
],
[
"pastel",
"",
"colors",
"https://github.com/sharkdp/pastel",
"Source README and installed help; no guessed color conversion.",
],
[
"nerd-fonts",
"nerdfonts|glyphnames",
"icons",
"https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/glyphnames.json",
"Exact glyph identity, code points and registry revision require a structured JSON reader.",
],
[
"cloudflare",
"",
"hosted platforms",
"https://developers.cloudflare.com/",
"Product-scoped references, API versions and changing service behavior.",
],
[
"google-workspace",
"workspace",
"hosted platforms",
"https://developers.google.com/workspace",
"API methods, schemas, scopes, pagination and versions; no account access needed.",
],
[
"google-discovery",
"google discovery",
"hosted platforms",
"https://discovery.googleapis.com/discovery/v1/apis",
"Structured API discovery metadata; not account data.",
],
[
"microsoft-learn-mcp",
"learn mcp",
"provider retrieval",
"https://learn.microsoft.com/en-us/training/support/mcp",
"Anonymous search/fetch MCP needs runtime schema discovery; generated-answer tools are excluded.",
],
[
"devdocs",
"devdocs.io",
"cross-domain",
"https://devdocs.io/",
"Curated docsets with catalog, indexes, release metadata and offline bundles.",
],
[
"dash-zeal",
"dash|zeal",
"cross-domain",
"https://kapeli.com/docsets",
"Optional feeds/bundles subject to access, attribution and redistribution restrictions.",
],
[
"llms-txt",
"llms.txt",
"cross-domain",
"https://llmstxt.org/",
"Machine-index convention; register each publisher's scoped index separately.",
],
[
"tldr",
"tldr-pages",
"command examples",
"https://github.com/tldr-pages/tldr",
"Supplementary platform/language examples, not complete release-compatible reference coverage.",
],
[
"context7",
"",
"cross-domain",
"https://context7.com/",
"Last-ranked query-scoped fallback; anonymous/keyed mode and version verification are separate.",
],
];
const community = new Set([
"mdn",
"mdn-content",
"browser-compat-data",
"cppreference",
"archwiki",
"tldr",
"nerd-fonts",
]);
const hosts = new Set([
"maven-central",
"javadoc-io",
"docs-rs",
"pkg-go-dev",
"readthedocs",
"dash-zeal",
]);
const registries = new Set([
"browser-compat-data",
"nerd-fonts",
"google-discovery",
]);
const indexes: Record<string, string> = {
mise: "https://mise.jdx.dev/llms.txt",
"ast-grep": "https://ast-grep.github.io/llms.txt",
cloudflare: "https://developers.cloudflare.com/llms.txt",
};
export const sourceCatalog: readonly CatalogSource[] = rows.map(
([id, aliases, domain, home, description]) => ({
id,
aliases: aliases ? aliases.split("|") : [],
domain,
home,
index: indexes[id] ?? null,
format: registries.has(id)
? "json"
: id === "dash-zeal"
? "docset"
: "html",
authority: hosts.has(id)
? "host"
: community.has(id)
? "community"
: [
"whatwg",
"w3c",
"wcag",
"webdriver-bidi",
"rfc",
"freedesktop",
].includes(id)
? "standards"
: "publisher",
role:
id === "tldr"
? "supplemental"
: registries.has(id)
? "registry"
: hosts.has(id)
? "host"
: "reference",
adapter:
id === "devdocs"
? "devdocs"
: id === "context7"
? "context7"
: ["dash-zeal", "microsoft-learn-mcp"].includes(id)
? "unavailable"
: "upstream",
versionSupport:
"Unknown by default; explicit releases require independently verified source identity. URL paths or HTTP success alone are not evidence.",
description,
}),
);
/** Local discovery is deliberately separate from generic HTTP retrieval. */
export const localSourceCatalog: readonly CatalogSource[] = [
[
"installed-man",
"man",
"Installed manual sections and owning package versions.",
],
["installed-info", "info", "Installed GNU Info nodes and package versions."],
[
"installed-help",
"help",
"Built-in/subcommand help and PowerShell help through applicable platform conventions.",
],
[
"installed-package-docs",
"markdown",
"Installed READMEs, manuals, examples and package documentation trees.",
],
[
"installed-javadoc",
"javadoc",
"Existing Javadoc archives and generated JVM API docs; never install or build.",
],
[
"installed-docsets",
"docset",
"Existing Dash/Zeal HTML and symbol indexes; no browser application required.",
],
[
"installed-sdk-docs",
"html",
"Application/SDK documentation including Pi via installation metadata or configured roots.",
],
].map(([id, format, description]) => ({
id: id ?? "",
aliases: [],
domain: "installed documentation",
home: "",
index: null,
format: format as FormatId,
authority: "installed",
role: "reference",
adapter: "local",
versionSupport:
"Requires installation/package metadata; not inferred from host OS.",
description: description ?? "",
}));
export function sourceCapabilities(source: CatalogSource): {
id: string;
available: boolean;
coverage: "supplemental" | "document";
version: string | null;
capability: string | undefined;
} {
const reader = formatReaders.find((item) => item.id === source.format);
return {
id: source.id,
available: source.adapter === "upstream" && reader?.available === true,
coverage: source.role === "supplemental" ? "supplemental" : "document",
version: source.version && source.evidence ? source.version : null,
capability:
source.adapter === "upstream"
? reader?.capability
: `Requires ${source.adapter} adapter; availability is determined by parent configuration.`,
};
}