mdat 2.2.0 → 2.3.0

package/dist/bin/cli.js

@@ -42,7 +42,7 @@ function deepMergeDefined(...objects) {
 //#endregion
 //#region package.json
 var name = "mdat";
-var version = "2.2.0";
+var version = "2.3.0";
 
 //#endregion
 //#region src/lib/log.ts
@@ -101,6 +101,7 @@ async function getContextMetadata() {
 	metascopeMetadata = await getMetadata({
 		absolute: false,
 		offline: true,
+		recursive: false,
 		sources: [
 			"arduinoLibraryProperties",
 			"cinderCinderblockXml",
@@ -143,17 +144,52 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 	const licenseFileData = helpers.firstOf(licenseFile);
 	const ciActionFilePath = helpers.ensureArray(githubActions).find((entry) => entry.data.name.toLowerCase() === "ci")?.source;
 	const repositoryUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
+	const bin = (() => {
+		if (nodePackage === void 0) return;
+		const binField = nodePackage.bin;
+		if (binField === void 0) return;
+		if (typeof binField === "string") return [nodePackage.name];
+		const names = Object.keys(binField);
+		return names.length > 0 ? names : void 0;
+	})();
+	const engines = (() => {
+		const raw = nodePackage?.engines;
+		if (raw === void 0) return;
+		const entries = Object.entries(raw).filter((entry) => entry[1] !== void 0);
+		return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+	})();
+	const peerDependencies = (() => {
+		if (nodePackage === void 0) return;
+		const peers = nodePackage.peerDependencies;
+		if (peers === void 0) return;
+		const entries = Object.entries(peers).filter((entry) => entry[1] !== void 0);
+		if (entries.length === 0) return;
+		const meta = nodePackage.peerDependenciesMeta;
+		return entries.map(([name, version]) => ({
+			name,
+			optional: meta?.[name]?.optional === true,
+			version
+		}));
+	})();
+	const firstAuthor = helpers.firstOf(helpers.ensureArray(codemeta.author));
 	return {
 		author: helpers.firstOf(helpers.mixedStringsToArray(helpers.toBasicNames(codemeta.author))),
+		authorUrl: firstAuthor?.url,
+		bin,
 		ciActionFileName: ciActionFilePath ? path.basename(ciActionFilePath) : void 0,
 		description: codemeta.description,
-		isPublicNpmPackage: !nodePackage?.name.startsWith("@") || nodePackage.publishConfig?.access === "public",
+		engines,
+		isPublicNpmPackage: nodePackage?.private !== true && (nodePackage?.name.startsWith("@") && nodePackage.publishConfig?.access === "public" || true),
 		issuesUrl: codemeta.issueTracker,
 		license: helpers.toBasicLicense(helpers.firstOf(helpers.ensureArray(codemeta.license))),
 		licenseFilePath: licenseFileData?.source,
 		name: codemeta.name,
+		operatingSystem: codemeta.operatingSystem,
+		peerDependencies,
 		projectDirectory: metascope?.data.options.path === void 0 ? void 0 : `file://${metascope.data.options.path}`,
-		repositoryUrl
+		repositoryUrl,
+		runtimePlatform: codemeta.runtimePlatform,
+		usesPnpm: helpers.usesPnpm(nodePackageJson)
 	};
 });
 let readmeMetadata;
@@ -277,7 +313,85 @@ var code_default = { code: { async content(options) {
 var contributing_default = { contributing: { async content() {
 	const { issuesUrl } = await getReadmeMetadata();
 	if (issuesUrl === void 0) throw new Error("Could not find \"bugs.url\" entry in package.json");
-	return `## Contributing\n[Issues](${issuesUrl}) and pull requests are welcome.`;
+	return [
+		"## Contributing",
+		"",
+		`[Issues](${issuesUrl}) are welcome and appreciated.`,
+		"",
+		"Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.",
+		"",
+		"This repository uses [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) (via its `ksc` CLI) for linting and formatting, plus [MDAT](https://github.com/kitschpatrol/mdat) for readme placeholder expansion."
+	].join("\n");
+} } };
+
+//#endregion
+//#region src/lib/readme/rules/dependencies.ts
+const PLATFORM_INFO = {
+	bun: {
+		display: "Bun",
+		url: "https://bun.sh/"
+	},
+	deno: {
+		display: "Deno",
+		url: "https://deno.land/"
+	},
+	go: {
+		display: "Go",
+		url: "https://go.dev/"
+	},
+	java: {
+		display: "Java",
+		url: "https://www.java.com/"
+	},
+	node: {
+		display: "Node.js",
+		url: "https://nodejs.org/"
+	},
+	python: {
+		display: "Python",
+		url: "https://www.python.org/"
+	},
+	ruby: {
+		display: "Ruby",
+		url: "https://www.ruby-lang.org/"
+	},
+	rust: {
+		display: "Rust",
+		url: "https://www.rust-lang.org/"
+	}
+};
+var dependencies_default = { dependencies: { async content() {
+	const { engines, operatingSystem, peerDependencies, runtimePlatform } = await getReadmeMetadata();
+	const platformItems = [];
+	if (engines !== void 0) for (const [name, version] of Object.entries(engines)) {
+		const info = PLATFORM_INFO[name.toLowerCase()];
+		const display = info ? `[${info.display}](${info.url})` : name;
+		platformItems.push(`- ${display} ${version}`);
+	}
+	if (runtimePlatform !== void 0) for (const entry of runtimePlatform) {
+		const spaceIndex = entry.indexOf(" ");
+		const platformKey = spaceIndex > 0 ? entry.slice(0, spaceIndex) : entry;
+		const version = spaceIndex > 0 ? entry.slice(spaceIndex + 1) : void 0;
+		if (engines?.[platformKey] !== void 0) continue;
+		const info = PLATFORM_INFO[platformKey.toLowerCase()];
+		const display = info ? `[${info.display}](${info.url})` : platformKey;
+		platformItems.push(version ? `- ${display} ${version}` : `- ${display}`);
+	}
+	if (operatingSystem !== void 0 && operatingSystem.length > 0) platformItems.push(`- Supported platforms: ${operatingSystem.join(", ")}`);
+	const peerItems = [];
+	if (peerDependencies !== void 0) for (const { name, optional, version } of peerDependencies) {
+		const npmUrl = `https://www.npmjs.com/package/${name}`;
+		const optionalSuffix = optional ? " _(optional)_" : "";
+		peerItems.push(`- [${name}](${npmUrl}) ${version}${optionalSuffix}`);
+	}
+	const hasPlatform = platformItems.length > 0;
+	const hasPeers = peerItems.length > 0;
+	if (!hasPlatform && !hasPeers) return "";
+	const sections = ["## Dependencies"];
+	if (hasPlatform && hasPeers) sections.push("", "### Platform", "", ...platformItems, "", "### Peer Dependencies", "", ...peerItems);
+	else if (hasPlatform) sections.push("", ...platformItems);
+	else sections.push("", ...peerItems);
+	return sections.join("\n");
 } } };
 
 //#endregion
@@ -294,10 +408,10 @@ var description_default = { description: { async content() {
 //#endregion
 //#region src/lib/readme/rules/license.ts
 var license_default = { license: { async content() {
-	const { author, license, licenseFilePath } = await getReadmeMetadata();
+	const { author, authorUrl, license, licenseFilePath } = await getReadmeMetadata();
 	if (author === void 0) throw new Error("Could not find author name in project");
 	if (license === void 0 || licenseFilePath === void 0) throw new Error("Could not find license for project");
-	return `## License\n[${license}](${licenseFilePath}) © ${author}`;
+	return `## License\n[${license}](${licenseFilePath}) © ${authorUrl === void 0 ? author : `[${author}](${authorUrl})`}`;
 } } };
 
 //#endregion
@@ -345,6 +459,25 @@ var header_default = { header: {
 	order: 2
 } };
 
+//#endregion
+//#region src/lib/readme/rules/install.ts
+var install_default = { install: { async content() {
+	const { bin, engines, isPublicNpmPackage, name, runtimePlatform, usesPnpm } = await getReadmeMetadata();
+	if (name === void 0) throw new Error("Could not find project name");
+	const lines = ["## Install"];
+	if (isPublicNpmPackage || engines?.node !== void 0 || runtimePlatform?.includes("node")) {
+		const pmAdd = usesPnpm ? "pnpm add" : "npm install";
+		const pmx = usesPnpm ? "pnpx" : "npx";
+		lines.push("", "```sh", `${pmAdd} ${name}`, "```");
+		if (bin !== void 0 && bin.length > 0) lines.push("", "Or run it directly:", "", "```sh", `${pmx} ${name}`, "```");
+	} else if (runtimePlatform?.some((p) => p.startsWith("python"))) lines.push("", "```sh", `pip install ${name}`, "```");
+	else if (runtimePlatform?.some((p) => p.startsWith("rust"))) lines.push("", "```sh", `cargo install ${name}`, "```");
+	else if (runtimePlatform?.some((p) => p.startsWith("go"))) lines.push("", "```sh", `go install ${name}@latest`, "```");
+	else if (runtimePlatform?.some((p) => p.startsWith("ruby"))) lines.push("", "```sh", `gem install ${name}`, "```");
+	else throw new Error("Could not determine project ecosystem for install instructions");
+	return lines.join("\n");
+} } };
+
 //#endregion
 //#region src/lib/readme/rules/utilities/size/size-report.ts
 const brotliCompressAsync = promisify(brotliCompress);
@@ -503,9 +636,11 @@ var rules_default = {
 	...banner_default,
 	...code_default,
 	...contributing_default,
+	...dependencies_default,
 	...description_default,
 	...footer_default,
 	...header_default,
+	...install_default,
 	...license_default,
 	...short_description_default,
 	...size_default,
@@ -531,9 +666,9 @@ function getAdditionalConfigExplorer() {
 	return _additionalConfigExplorer;
 }
 /**
-* Load and validate mdat configuration.
-* Uses cosmiconfig to search in the usual places.
-* Merge precedence: Base Defaults < Defaults < Searched Config < Additional Config
+* Load and validate mdat configuration. Uses cosmiconfig to search in the usual
+* places. Merge precedence: Base Defaults < Defaults < Searched Config <
+* Additional Config
 */
 async function loadConfig(options) {
 	const { additionalConfig, defaults = rules_default, searchFrom } = options ?? {};

package/dist/lib/index.d.ts

@@ -6,39 +6,43 @@ import { VFile } from "vfile";
 
 //#region src/lib/config.d.ts
 /**
- * An mdat configuration is a record of expansion rules.
- * Keys become comment keywords, values define the expansion content.
+ * An mdat configuration is a record of expansion rules. Keys become comment
+ * keywords, values define the expansion content.
  */
 type Config = Record<string, Rule$1>;
 /**
- * Generously accept either string paths to .ts, .js, or .json config files,
- * or inline Config objects.
+ * Generously accept either string paths to .ts, .js, or .json config files, or
+ * inline Config objects.
  */
 type ConfigToLoad = Array<Config | string> | Config | string;
 /**
- * Load and validate mdat configuration.
- * Uses cosmiconfig to search in the usual places.
- * Merge precedence: Base Defaults < Defaults < Searched Config < Additional Config
+ * Load and validate mdat configuration. Uses cosmiconfig to search in the usual
+ * places. Merge precedence: Base Defaults < Defaults < Searched Config <
+ * Additional Config
  */
 declare function loadConfig(options?: {
   /**
    * Additional Config objects to merge.
    *
-   * Strings are treated as paths to `ts`, `js`, or `json` config files.
-   * These will be dynamically loaded by Cosmiconfig.
-   * Accepts an individual item, or an array. Objects in the array will be merged right to left.
+   * Strings are treated as paths to `ts`, `js`, or `json` config files. These
+   * will be dynamically loaded by Cosmiconfig. Accepts an individual item, or
+   * an array. Objects in the array will be merged right to left.
    */
   additionalConfig?: ConfigToLoad;
   /**
-   * Default rules that have higher priority than base defaults but lower than searched config.
-   * Defaults to the built-in readme rules. Pass `{}` to disable.
+   * Default rules that have higher priority than base defaults but lower than
+   * searched config. Defaults to the built-in readme rules. Pass `{}` to
+   * disable.
+   */
+  defaults?: Config;
+  /**
+   * Search for config in specific directories, mainly useful for testing.
+   * Cosmiconfig default search paths used if unset.
    */
-  defaults?: Config; /** Search for config in specific directories, mainly useful for testing. Cosmiconfig default search paths used if unset. */
   searchFrom?: string;
 }): Promise<Config>;
 /**
- * Convenience function for merging configs.
- * Rightmost config takes precedence.
+ * Convenience function for merging configs. Rightmost config takes precedence.
  */
 declare function mergeConfig(a: Config, b: Config): Config;
 /**
@@ -148,15 +152,28 @@ declare function checkString(markdown: string, config?: ConfigToLoad, options?:
 declare function getContextMetadata(): Promise<MetadataContext>;
 declare const readmeMetadataTemplate: _$metascope.Template<{
   author: string | undefined;
+  authorUrl: string | undefined;
+  bin: string[] | undefined;
   ciActionFileName: string | undefined;
   description: string | undefined;
+  engines: {
+    [k: string]: string;
+  } | undefined;
   isPublicNpmPackage: boolean;
   issuesUrl: string | undefined;
   license: string | undefined;
   licenseFilePath: string | undefined;
   name: string | undefined;
+  operatingSystem: string[] | undefined;
+  peerDependencies: {
+    name: string;
+    optional: boolean;
+    version: string;
+  }[] | undefined;
   projectDirectory: string | undefined;
   repositoryUrl: string | undefined;
+  runtimePlatform: string[] | undefined;
+  usesPnpm: boolean;
 }>;
 type ReadmeMetadata = ReturnType<typeof readmeMetadataTemplate>;
 /**
@@ -166,15 +183,28 @@ type ReadmeMetadata = ReturnType<typeof readmeMetadataTemplate>;
  */
 declare function getReadmeMetadata(): Promise<{
   author: string | undefined;
+  authorUrl: string | undefined;
+  bin: string[] | undefined;
   ciActionFileName: string | undefined;
   description: string | undefined;
+  engines: {
+    [k: string]: string;
+  } | undefined;
   isPublicNpmPackage: boolean;
   issuesUrl: string | undefined;
   license: string | undefined;
   licenseFilePath: string | undefined;
   name: string | undefined;
+  operatingSystem: string[] | undefined;
+  peerDependencies: {
+    name: string;
+    optional: boolean;
+    version: string;
+  }[] | undefined;
   projectDirectory: string | undefined;
   repositoryUrl: string | undefined;
+  runtimePlatform: string[] | undefined;
+  usesPnpm: boolean;
 }>;
 /**
  * Reset all cached metadata. Call between tests or when the underlying project
@@ -188,6 +218,6 @@ declare function resetMetadataCaches(): void;
  * Export this for library consumers to inject their own logger.
  * @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
  */
-declare function setLogger(logger?: ILogBasic | ILogLayer): void;
+declare function setLogger(logger?: ILogBasic | ILogLayer<unknown>): void;
 //#endregion
 export { type Config, type ReadmeMetadata, type Rule, check, checkString, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger, strip, stripString };

package/dist/lib/index.js

@@ -88,6 +88,7 @@ async function getContextMetadata() {
 	metascopeMetadata = await getMetadata({
 		absolute: false,
 		offline: true,
+		recursive: false,
 		sources: [
 			"arduinoLibraryProperties",
 			"cinderCinderblockXml",
@@ -139,17 +140,52 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 	const licenseFileData = helpers.firstOf(licenseFile);
 	const ciActionFilePath = helpers.ensureArray(githubActions).find((entry) => entry.data.name.toLowerCase() === "ci")?.source;
 	const repositoryUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
+	const bin = (() => {
+		if (nodePackage === void 0) return;
+		const binField = nodePackage.bin;
+		if (binField === void 0) return;
+		if (typeof binField === "string") return [nodePackage.name];
+		const names = Object.keys(binField);
+		return names.length > 0 ? names : void 0;
+	})();
+	const engines = (() => {
+		const raw = nodePackage?.engines;
+		if (raw === void 0) return;
+		const entries = Object.entries(raw).filter((entry) => entry[1] !== void 0);
+		return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+	})();
+	const peerDependencies = (() => {
+		if (nodePackage === void 0) return;
+		const peers = nodePackage.peerDependencies;
+		if (peers === void 0) return;
+		const entries = Object.entries(peers).filter((entry) => entry[1] !== void 0);
+		if (entries.length === 0) return;
+		const meta = nodePackage.peerDependenciesMeta;
+		return entries.map(([name, version]) => ({
+			name,
+			optional: meta?.[name]?.optional === true,
+			version
+		}));
+	})();
+	const firstAuthor = helpers.firstOf(helpers.ensureArray(codemeta.author));
 	return {
 		author: helpers.firstOf(helpers.mixedStringsToArray(helpers.toBasicNames(codemeta.author))),
+		authorUrl: firstAuthor?.url,
+		bin,
 		ciActionFileName: ciActionFilePath ? path.basename(ciActionFilePath) : void 0,
 		description: codemeta.description,
-		isPublicNpmPackage: !nodePackage?.name.startsWith("@") || nodePackage.publishConfig?.access === "public",
+		engines,
+		isPublicNpmPackage: nodePackage?.private !== true && (nodePackage?.name.startsWith("@") && nodePackage.publishConfig?.access === "public" || true),
 		issuesUrl: codemeta.issueTracker,
 		license: helpers.toBasicLicense(helpers.firstOf(helpers.ensureArray(codemeta.license))),
 		licenseFilePath: licenseFileData?.source,
 		name: codemeta.name,
+		operatingSystem: codemeta.operatingSystem,
+		peerDependencies,
 		projectDirectory: metascope?.data.options.path === void 0 ? void 0 : `file://${metascope.data.options.path}`,
-		repositoryUrl
+		repositoryUrl,
+		runtimePlatform: codemeta.runtimePlatform,
+		usesPnpm: helpers.usesPnpm(nodePackageJson)
 	};
 });
 let readmeMetadata;
@@ -286,7 +322,84 @@ var code_default = { code: { async content(options) {
 var contributing_default = { contributing: { async content() {
 	const { issuesUrl } = await getReadmeMetadata();
 	if (issuesUrl === void 0) throw new Error("Could not find \"bugs.url\" entry in package.json");
-	return `## Contributing\n[Issues](${issuesUrl}) and pull requests are welcome.`;
+	return [
+		"## Contributing",
+		"",
+		`[Issues](${issuesUrl}) are welcome and appreciated.`,
+		"",
+		"Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.",
+		"",
+		"This repository uses [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) (via its `ksc` CLI) for linting and formatting, plus [MDAT](https://github.com/kitschpatrol/mdat) for readme placeholder expansion."
+	].join("\n");
+} } };
+//#endregion
+//#region src/lib/readme/rules/dependencies.ts
+const PLATFORM_INFO = {
+	bun: {
+		display: "Bun",
+		url: "https://bun.sh/"
+	},
+	deno: {
+		display: "Deno",
+		url: "https://deno.land/"
+	},
+	go: {
+		display: "Go",
+		url: "https://go.dev/"
+	},
+	java: {
+		display: "Java",
+		url: "https://www.java.com/"
+	},
+	node: {
+		display: "Node.js",
+		url: "https://nodejs.org/"
+	},
+	python: {
+		display: "Python",
+		url: "https://www.python.org/"
+	},
+	ruby: {
+		display: "Ruby",
+		url: "https://www.ruby-lang.org/"
+	},
+	rust: {
+		display: "Rust",
+		url: "https://www.rust-lang.org/"
+	}
+};
+var dependencies_default = { dependencies: { async content() {
+	const { engines, operatingSystem, peerDependencies, runtimePlatform } = await getReadmeMetadata();
+	const platformItems = [];
+	if (engines !== void 0) for (const [name, version] of Object.entries(engines)) {
+		const info = PLATFORM_INFO[name.toLowerCase()];
+		const display = info ? `[${info.display}](${info.url})` : name;
+		platformItems.push(`- ${display} ${version}`);
+	}
+	if (runtimePlatform !== void 0) for (const entry of runtimePlatform) {
+		const spaceIndex = entry.indexOf(" ");
+		const platformKey = spaceIndex > 0 ? entry.slice(0, spaceIndex) : entry;
+		const version = spaceIndex > 0 ? entry.slice(spaceIndex + 1) : void 0;
+		if (engines?.[platformKey] !== void 0) continue;
+		const info = PLATFORM_INFO[platformKey.toLowerCase()];
+		const display = info ? `[${info.display}](${info.url})` : platformKey;
+		platformItems.push(version ? `- ${display} ${version}` : `- ${display}`);
+	}
+	if (operatingSystem !== void 0 && operatingSystem.length > 0) platformItems.push(`- Supported platforms: ${operatingSystem.join(", ")}`);
+	const peerItems = [];
+	if (peerDependencies !== void 0) for (const { name, optional, version } of peerDependencies) {
+		const npmUrl = `https://www.npmjs.com/package/${name}`;
+		const optionalSuffix = optional ? " _(optional)_" : "";
+		peerItems.push(`- [${name}](${npmUrl}) ${version}${optionalSuffix}`);
+	}
+	const hasPlatform = platformItems.length > 0;
+	const hasPeers = peerItems.length > 0;
+	if (!hasPlatform && !hasPeers) return "";
+	const sections = ["## Dependencies"];
+	if (hasPlatform && hasPeers) sections.push("", "### Platform", "", ...platformItems, "", "### Peer Dependencies", "", ...peerItems);
+	else if (hasPlatform) sections.push("", ...platformItems);
+	else sections.push("", ...peerItems);
+	return sections.join("\n");
 } } };
 //#endregion
 //#region src/lib/readme/rules/description.ts
@@ -301,10 +414,10 @@ var description_default = { description: { async content() {
 //#endregion
 //#region src/lib/readme/rules/license.ts
 var license_default = { license: { async content() {
-	const { author, license, licenseFilePath } = await getReadmeMetadata();
+	const { author, authorUrl, license, licenseFilePath } = await getReadmeMetadata();
 	if (author === void 0) throw new Error("Could not find author name in project");
 	if (license === void 0 || licenseFilePath === void 0) throw new Error("Could not find license for project");
-	return `## License\n[${license}](${licenseFilePath}) © ${author}`;
+	return `## License\n[${license}](${licenseFilePath}) © ${authorUrl === void 0 ? author : `[${author}](${authorUrl})`}`;
 } } };
 //#endregion
 //#region src/lib/readme/rules/footer.ts
@@ -348,6 +461,24 @@ var header_default = { header: {
 	order: 2
 } };
 //#endregion
+//#region src/lib/readme/rules/install.ts
+var install_default = { install: { async content() {
+	const { bin, engines, isPublicNpmPackage, name, runtimePlatform, usesPnpm } = await getReadmeMetadata();
+	if (name === void 0) throw new Error("Could not find project name");
+	const lines = ["## Install"];
+	if (isPublicNpmPackage || engines?.node !== void 0 || runtimePlatform?.includes("node")) {
+		const pmAdd = usesPnpm ? "pnpm add" : "npm install";
+		const pmx = usesPnpm ? "pnpx" : "npx";
+		lines.push("", "```sh", `${pmAdd} ${name}`, "```");
+		if (bin !== void 0 && bin.length > 0) lines.push("", "Or run it directly:", "", "```sh", `${pmx} ${name}`, "```");
+	} else if (runtimePlatform?.some((p) => p.startsWith("python"))) lines.push("", "```sh", `pip install ${name}`, "```");
+	else if (runtimePlatform?.some((p) => p.startsWith("rust"))) lines.push("", "```sh", `cargo install ${name}`, "```");
+	else if (runtimePlatform?.some((p) => p.startsWith("go"))) lines.push("", "```sh", `go install ${name}@latest`, "```");
+	else if (runtimePlatform?.some((p) => p.startsWith("ruby"))) lines.push("", "```sh", `gem install ${name}`, "```");
+	else throw new Error("Could not determine project ecosystem for install instructions");
+	return lines.join("\n");
+} } };
+//#endregion
 //#region src/lib/readme/rules/utilities/size/size-report.ts
 const brotliCompressAsync = promisify(brotliCompress);
 const gzipCompressAsync = promisify(gzip);
@@ -500,9 +631,11 @@ var rules_default = {
 	...banner_default,
 	...code_default,
 	...contributing_default,
+	...dependencies_default,
 	...description_default,
 	...footer_default,
 	...header_default,
+	...install_default,
 	...license_default,
 	...short_description_default,
 	...size_default,
@@ -527,9 +660,9 @@ function getAdditionalConfigExplorer() {
 	return _additionalConfigExplorer;
 }
 /**
-* Load and validate mdat configuration.
-* Uses cosmiconfig to search in the usual places.
-* Merge precedence: Base Defaults < Defaults < Searched Config < Additional Config
+* Load and validate mdat configuration. Uses cosmiconfig to search in the usual
+* places. Merge precedence: Base Defaults < Defaults < Searched Config <
+* Additional Config
 */
 async function loadConfig(options) {
 	const { additionalConfig, defaults = rules_default, searchFrom } = options ?? {};
@@ -580,8 +713,7 @@ function validateConfig(value) {
 	log.warn(`Config has the wrong shape. Ignoring and using default configuration:\n${JSON.stringify(value, void 0, 2)}`);
 }
 /**
-* Convenience function for merging configs.
-* Rightmost config takes precedence.
+* Convenience function for merging configs. Rightmost config takes precedence.
 */
 function mergeConfig(a, b) {
 	return deepMergeDefined(a, b);
@@ -774,46 +906,28 @@ function getStripProcessor(_config, ambientRemarkConfig) {
 	});
 }
 //#endregion
-//#region src/lib/readme/templates/mdat-readme-compound.md?raw
-var mdat_readme_compound_default = "<!-- header -->\n\n<!-- table-of-contents -->\n\n## Overview\n\n## Getting started\n\n### Dependencies\n\n### Installation\n\n## Usage\n\n### Library\n\n#### API\n\n#### Examples\n\n### CLI\n\n#### Commands\n\n#### Examples\n\n## Background\n\n### Motivation\n\n### Implementation notes\n\n### Similar projects\n\n## The future\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Acknowledgments\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- footer -->\n";
-//#endregion
-//#region src/lib/readme/templates/mdat-readme.md?raw
-var mdat_readme_default = "<!-- title -->\n\n<!-- banner -->\n\n<!-- badges -->\n\n<!-- short-description -->\n\n<!-- table-of-contents -->\n\n## Overview\n\n## Getting started\n\n### Dependencies\n\n### Installation\n\n## Usage\n\n### Library\n\n#### API\n\n#### Examples\n\n### CLI\n\n#### Commands\n\n#### Examples\n\n## Background\n\n### Motivation\n\n### Implementation notes\n\n### Similar projects\n\n## The future\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Acknowledgments\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- contributing -->\n\n<!-- license -->\n";
-//#endregion
-//#region src/lib/readme/templates/standard-readme-basic-compound.md?raw
-var standard_readme_basic_compound_default = "<!-- header -->\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" }) --> comment as well.\n```\n\n<!-- footer -->\n";
-//#endregion
-//#region src/lib/readme/templates/standard-readme-basic.md?raw
-var standard_readme_basic_default = "<!-- title -->\n\n<!-- short-description -->\n\n<!-- table-of-contents -->\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n<!-- contributing -->\n\n<!-- license -->\n";
-//#endregion
-//#region src/lib/readme/templates/standard-readme-full-compound.md?raw
-var standard_readme_full_compound_default = "<!-- header -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n### Dependencies\n\n_Required if there are unusual dependencies or dependencies that must be manually installed._\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- footer -->\n";
-//#endregion
-//#region src/lib/readme/templates/standard-readme-full.md?raw
-var standard_readme_full_default = "<!-- title -->\n\n<!-- banner -->\n\n<!-- badges -->\n\n<!-- short-description -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n### Dependencies\n\n_Required if there are unusual dependencies or dependencies that must be manually installed._\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- contributing -->\n\n<!-- license -->\n";
-//#endregion
 //#region src/lib/readme/templates/index.ts
 var templates_default = {
 	"MDAT Readme": {
 		content: {
-			compound: mdat_readme_compound_default,
-			explicit: mdat_readme_default
+			compound: "<!-- header -->\n\n<!-- table-of-contents -->\n\n## Overview\n\n## Getting started\n\n### Dependencies\n\n### Installation\n\n## Usage\n\n### Library\n\n#### API\n\n#### Examples\n\n### CLI\n\n#### Commands\n\n#### Examples\n\n## Background\n\n### Motivation\n\n### Implementation notes\n\n### Similar projects\n\n## The future\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Acknowledgments\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- footer -->\n",
+			explicit: "<!-- title -->\n\n<!-- banner -->\n\n<!-- badges -->\n\n<!-- short-description -->\n\n<!-- table-of-contents -->\n\n## Overview\n\n## Getting started\n\n### Dependencies\n\n### Installation\n\n## Usage\n\n### Library\n\n#### API\n\n#### Examples\n\n### CLI\n\n#### Commands\n\n#### Examples\n\n## Background\n\n### Motivation\n\n### Implementation notes\n\n### Similar projects\n\n## The future\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Acknowledgments\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- contributing -->\n\n<!-- license -->\n"
 		},
 		description: "The house style. An expansive starting point. Prune to your context and taste.",
 		exampleLink: "https://github.com/kitschpatrol/mdat/blob/main/readme.md"
 	},
 	"Standard Readme Basic": {
 		content: {
-			compound: standard_readme_basic_compound_default,
-			explicit: standard_readme_basic_default
+			compound: "<!-- header -->\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" }) --> comment as well.\n```\n\n<!-- footer -->\n",
+			explicit: "<!-- title -->\n\n<!-- short-description -->\n\n<!-- table-of-contents -->\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n<!-- contributing -->\n\n<!-- license -->\n"
 		},
 		description: "Includes only the \"required\" sections from the Standard Readme specification.",
 		exampleLink: "https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/minimal-readme.md"
 	},
 	"Standard Readme Full": {
 		content: {
-			compound: standard_readme_full_compound_default,
-			explicit: standard_readme_full_default
+			compound: "<!-- header -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n### Dependencies\n\n_Required if there are unusual dependencies or dependencies that must be manually installed._\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- footer -->\n",
+			explicit: "<!-- title -->\n\n<!-- banner -->\n\n<!-- badges -->\n\n<!-- short-description -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n### Dependencies\n\n_Required if there are unusual dependencies or dependencies that must be manually installed._\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- contributing -->\n\n<!-- license -->\n"
 		},
 		description: "Includes all sections from the Standard Readme specification.",
 		exampleLink: "https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/maximal-readme.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "CLI tool and TypeScript library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.",
   "keywords": [
     "mdat",
@@ -45,12 +45,12 @@
   "dependencies": {
     "@clack/prompts": "^1.2.0",
     "cosmiconfig": "^9.0.1",
-    "cosmiconfig-typescript-loader": "^6.2.0",
+    "cosmiconfig-typescript-loader": "^6.3.0",
     "deepmerge-ts": "^7.1.5",
     "globby": "^16.2.0",
-    "lognow": "^0.6.0",
+    "lognow": "^0.6.1",
     "mdast-util-toc": "^7.1.0",
-    "metascope": "^0.6.0",
+    "metascope": "^0.7.0",
     "path-type": "^6.0.0",
     "picocolors": "^1.1.1",
     "plur": "^6.0.0",
@@ -58,9 +58,9 @@
     "pretty-ms": "^9.3.0",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
-    "remark-mdat": "^2.2.0",
+    "remark-mdat": "^2.2.1",
     "to-vfile": "^8.0.0",
-    "type-fest": "^5.5.0",
+    "type-fest": "^5.6.0",
     "unified-engine": "^11.2.2",
     "untildify": "^6.0.0",
     "vfile": "^6.0.3",
@@ -69,7 +69,7 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@kitschpatrol/shared-config": "^7.0.1",
+    "@kitschpatrol/shared-config": "^7.4.1",
     "@types/mdast": "^4.0.4",
     "@types/node": "~22.17.2",
     "@types/unist": "^3.0.3",
@@ -77,16 +77,17 @@
     "@vitest/coverage-v8": "4.1.2",
     "bumpp": "^11.0.1",
     "execa": "^9.6.1",
-    "mdat-plugin-cli-help": "^2.0.2",
+    "mdat-plugin-cli-help": "^2.1.2",
     "mdat-plugin-example": "^2.0.0",
     "mdat-plugin-tldraw": "^2.0.1",
-    "nanoid": "^5.1.7",
-    "prettier": "^3.8.1",
+    "nanoid": "^5.1.9",
+    "prettier": "^3.8.3",
     "publint": "^0.3.18",
-    "tsdown": "^0.21.7",
-    "typescript": "~5.9.3",
+    "shx": "^0.4.0",
+    "tsdown": "^0.21.9",
+    "typescript": "~6.0.3",
     "unplugin-raw": "^0.7.0",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.5"
   },
   "peerDependencies": {
     "prettier": "^3.0.0"
@@ -109,11 +110,11 @@
     "bench": "vitest bench --run --compare test/benchmarks/baseline.json",
     "bench:baseline": "vitest bench --run --outputJson test/benchmarks/baseline.json",
     "build": "tsdown",
-    "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
+    "clean": "shx rm -f pnpm-lock.yaml && git clean -fdX -e !.claude/",
     "coverage": "vitest --coverage --run",
     "fix": "ksc fix",
     "lint": "ksc lint",
-    "release": "bumpp --commit 'Release: %s' && pnpm run build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish",
+    "release": "bumpp --commit 'Release: %s' && pnpm build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish",
     "test": "vitest run"
   }
 }

package/readme.md

@@ -572,6 +572,14 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
   The project description. Also aliased as `<!-- short-description -->` for [standard-readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md) compatibility.
 
+- ##### `<!-- install -->`
+
+  Ecosystem-aware install instructions derived from project metadata. Emits `pnpm add` / `npm install` for Node packages (plus a `pnpx` / `npx` hint when the project exposes a binary), and falls back to `pip`, `cargo`, `gem`, or `go install` for Python, Rust, Ruby, and Go projects.
+
+- ##### `<!-- dependencies -->`
+
+  Documents platform requirements and peer dependencies. Lists runtime platforms (Node, Python, Rust, Go, Ruby, etc.) with version constraints from `engines` or equivalent metadata, supported operating systems, and peer dependencies with links to npm.
+
 - ##### `<!-- table-of-contents -->`
 
   Auto-generated via [mdast-util-toc](https://github.com/syntax-tree/mdast-util-toc). Also aliased as `<!-- toc -->`.
@@ -600,7 +608,7 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
   | File        | Original | Gzip  | Brotli |
   | ----------- | -------- | ----- | ------ |
-  | .gitignore  | 305 B    | 245 B | 216 B  |
+  | .gitignore  | 318 B    | 252 B | 237 B  |
   | license.txt | 1 kB     | 659 B | 468 B  |
 
   <!-- /size-table -->
@@ -794,13 +802,17 @@ There's quite a bit of prior art and similar explorations of this problem space:
 
 - VitePress' [Markdown file inclusion](https://vitepress.dev/guide/markdown#markdown-file-inclusion)
 
+- Hiroki Osame's [comment-mark](https://github.com/privatenumber/comment-mark)
+
+- Hiroki Osame's [mdeval](https://github.com/privatenumber/mdeval)
+
 ### Implementation notes
 
 This project was split from a monorepo containing both `mdat` and `remark-mdat` into separate repos in July 2024.
 
 ## Maintainers
 
-[@kitschpatrol](https://github.com/kitschpatrol)
+[kitschpatrol](https://github.com/kitschpatrol)
 
 ## Acknowledgments