@metamask-previews/platform-api-docs 0.0.0-preview-1275d0fda

package/dist/cli.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+function $__filename(fileUrl) {
+    const url = new URL(fileUrl);
+    return url.pathname.replace(/^\/([a-zA-Z]:)/u, "$1");
+}
+function $getDirname(path) {
+    const sanitisedPath = path.toString().replace(/\\/gu, "/").replace(/\/$/u, "");
+    const index = sanitisedPath.lastIndexOf("/");
+    if (index === -1) {
+        return path;
+    }
+    if (index === 0) {
+        return "/";
+    }
+    return sanitisedPath.slice(0, index);
+}
+function $__dirname(url) {
+    return $getDirname($__filename(url));
+}
+function $importDefault(module) {
+    if (module?.__esModule) {
+        return module.default;
+    }
+    return module;
+}
+import $execa from "execa/index.js";
+const execa = $importDefault($execa);
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import $npmWhich from "npm-which";
+const npmWhich = $importDefault($npmWhich);
+import yargs from "yargs";
+import { generate } from "./generate.mjs";
+/**
+ * Locate the Docusaurus binary in this package's `node_modules/.bin`. Using
+ * `npm-which` lets the lookup track wherever the installed Docusaurus puts
+ * its binary, so a future Docusaurus upgrade can't break this path.
+ *
+ * @returns Absolute path to the `docusaurus` executable.
+ */
+function resolveDocusaurus() {
+    return npmWhich($__dirname(import.meta.url)).sync('docusaurus');
+}
+/**
+ * Run a Docusaurus command.
+ *
+ * @param command - The docusaurus command (start, build, serve).
+ * @param cwd - The site directory.
+ * @param extraEnv - Extra environment variables passed through to the
+ * Docusaurus process (e.g. `DOCS_PROJECT_LABEL`, `DOCS_COMMIT_SHA`).
+ */
+async function runDocusaurus(command, cwd, extraEnv = {}) {
+    await execa(resolveDocusaurus(), [command], {
+        cwd,
+        stdio: 'inherit',
+        env: { ...process.env, ...extraEnv },
+    });
+}
+/**
+ * Copy site files into the output directory, skipping `node_modules` and
+ * `docs` (the latter is owned by the doc generator and shouldn't be carried
+ * over from the source `site/` directory).
+ *
+ * @param outDir - The output directory to set up.
+ */
+async function setupSite(outDir) {
+    const siteDir = path.resolve($__dirname(import.meta.url), '..', 'site');
+    const skip = new Set(['node_modules', 'docs']);
+    console.log(`\nSetting up Docusaurus site in ${outDir}...`);
+    // `fs.cp` has been available since Node 16.7 and only got the "stable"
+    // marker in 22.3 — it's functional throughout our supported Node range
+    // (`^18.18 || >=20`), even though the linter flags the older versions.
+    // eslint-disable-next-line n/no-unsupported-features/node-builtins
+    await fs.cp(siteDir, outDir, {
+        recursive: true,
+        filter: (source) => !skip.has(path.basename(source)),
+    });
+    // Write a minimal package.json so Docusaurus doesn't warn about a missing one
+    const pkgJsonPath = path.join(outDir, 'package.json');
+    try {
+        await fs.access(pkgJsonPath);
+    }
+    catch {
+        await fs.writeFile(pkgJsonPath, JSON.stringify({ name: 'platform-api-docs-site', private: true }, null, 2));
+    }
+}
+/**
+ * Resolve the short Git commit SHA the docs are being generated from.
+ * Returns null when the project isn't a git repo or git isn't available.
+ *
+ * @param projectPath - The project root path.
+ * @returns The short SHA, or null on failure.
+ */
+async function resolveCommitSha(projectPath) {
+    try {
+        const { stdout } = await execa('git', ['rev-parse', '--short', 'HEAD'], {
+            cwd: projectPath,
+        });
+        const trimmed = stdout.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Main CLI entry point.
+ */
+async function main() {
+    const argv = await yargs(process.argv.slice(2))
+        .command('$0 [project-path]', 'Produces documentation for the platform API, the set of actions and events available in clients through the message bus.', (yargsInstance) => {
+        yargsInstance.positional('project-path', {
+            type: 'string',
+            description: 'Path to the project to scan',
+            default: '.',
+        });
+    })
+        .option('build', {
+        type: 'boolean',
+        description: 'Generate platform API docs and build a production-ready site',
+        default: false,
+    })
+        .option('serve', {
+        type: 'boolean',
+        description: 'Generate platform API docs and serve a production-ready site',
+        default: false,
+    })
+        .option('dev', {
+        type: 'boolean',
+        description: 'Generate platform API docs and serve a development-only site',
+        default: false,
+    })
+        .option('scan-dir', {
+        type: 'string',
+        array: true,
+        description: 'Additional directories within the project to scan for messenger actions and events (note: may be specified multiple times)',
+        default: [],
+    })
+        .option('output', {
+        type: 'string',
+        description: 'Output directory',
+    })
+        .option('project-label', {
+        type: 'string',
+        description: 'Short label identifying the project (e.g. "Core", "Extension") — stamped on the site title and headings',
+    })
+        .option('site-url', {
+        type: 'string',
+        description: 'Absolute URL the built site will be served from, e.g. https://metamask.github.io',
+    })
+        .option('site-base-url', {
+        type: 'string',
+        description: 'Path prefix the built site will be served under, e.g. /core/platform-api/',
+    })
+        .help().argv;
+    const projectPathArg = argv['project-path'];
+    const resolvedProjectPath = path.resolve(typeof projectPathArg === 'string' ? projectPathArg : '.');
+    const resolvedOutputDir = path.resolve(argv.output ?? path.join(resolvedProjectPath, '.platform-api-docs'));
+    const scanDirs = ['src', ...argv['scan-dir']].filter((dir, index, dirs) => dirs.indexOf(dir) === index);
+    const projectLabel = typeof argv['project-label'] === 'string' &&
+        argv['project-label'].length > 0
+        ? argv['project-label']
+        : null;
+    const commitSha = await resolveCommitSha(resolvedProjectPath);
+    // Step 1: Generate docs
+    await generate({
+        projectPath: resolvedProjectPath,
+        outputDir: resolvedOutputDir,
+        scanDirs,
+        projectLabel,
+        commitSha,
+    });
+    // Step 2: If --build, --serve, or --dev, set up and run Docusaurus
+    if (argv.build || argv.serve || argv.dev) {
+        await setupSite(resolvedOutputDir);
+        // Translate CLI flags into the environment variables Docusaurus's
+        // config reads. Keeping the CLI surface flag-only means consumers
+        // (workflow files, package.json scripts) don't have to know how the
+        // values are plumbed through to Docusaurus.
+        const docusaurusEnv = {};
+        if (projectLabel) {
+            docusaurusEnv.DOCS_PROJECT_LABEL = projectLabel;
+        }
+        if (commitSha) {
+            docusaurusEnv.DOCS_COMMIT_SHA = commitSha;
+        }
+        if (typeof argv['site-url'] === 'string' && argv['site-url'].length > 0) {
+            docusaurusEnv.DOCS_URL = argv['site-url'];
+        }
+        if (typeof argv['site-base-url'] === 'string' &&
+            argv['site-base-url'].length > 0) {
+            docusaurusEnv.DOCS_BASE_URL = argv['site-base-url'];
+        }
+        if (argv.dev) {
+            console.log('\nStarting dev server...');
+            await runDocusaurus('start', resolvedOutputDir, docusaurusEnv);
+        }
+        else if (argv.build || argv.serve) {
+            console.log('\nBuilding static site...');
+            await runDocusaurus('build', resolvedOutputDir, docusaurusEnv);
+            if (argv.serve) {
+                console.log('\nServing static site...');
+                await runDocusaurus('serve', resolvedOutputDir, docusaurusEnv);
+            }
+        }
+    }
+}
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAEA,OAAO,MAAK,uBAAc;;AAC1B,OAAO,KAAK,EAAE,yBAAyB;AACvC,OAAO,KAAK,IAAI,kBAAkB;AAClC,OAAO,SAAQ,kBAAkB;;AACjC,OAAO,KAAK,cAAc;AAE1B,OAAO,EAAE,QAAQ,EAAE,uBAAmB;AAEtC;;;;;;GAMG;AACH,SAAS,iBAAiB;IACxB,OAAO,QAAQ,6BAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,aAAa,CAC1B,OAAe,EACf,GAAW,EACX,WAAmC,EAAE;IAErC,MAAM,KAAK,CAAC,iBAAiB,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE;QAC1C,GAAG;QACH,KAAK,EAAE,SAAS;QAChB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE;KACrC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,SAAS,CAAC,MAAc;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,8BAAY,IAAI,EAAE,MAAM,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC;IAE/C,OAAO,CAAC,GAAG,CAAC,mCAAmC,MAAM,KAAK,CAAC,CAAC;IAE5D,uEAAuE;IACvE,uEAAuE;IACvE,uEAAuE;IACvE,mEAAmE;IACnE,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE;QAC3B,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;KACrD,CAAC,CAAC;IAEH,8EAA8E;IAC9E,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,EAAE,CAAC,SAAS,CAChB,WAAW,EACX,IAAI,CAAC,SAAS,CACZ,EAAE,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,IAAI,EAAE,EACjD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,gBAAgB,CAAC,WAAmB;IACjD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE;YACtE,GAAG,EAAE,WAAW;SACjB,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAC5C,OAAO,CACN,mBAAmB,EACnB,0HAA0H,EAC1H,CAAC,aAAa,EAAE,EAAE;QAChB,aAAa,CAAC,UAAU,CAAC,cAAc,EAAE;YACvC,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,6BAA6B;YAC1C,OAAO,EAAE,GAAG;SACb,CAAC,CAAC;IACL,CAAC,CACF;SACA,MAAM,CAAC,OAAO,EAAE;QACf,IAAI,EAAE,SAAS;QACf,WAAW,EACT,8DAA8D;QAChE,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,OAAO,EAAE;QACf,IAAI,EAAE,SAAS;QACf,WAAW,EACT,8DAA8D;QAChE,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,KAAK,EAAE;QACb,IAAI,EAAE,SAAS;QACf,WAAW,EACT,8DAA8D;QAChE,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,UAAU,EAAE;QAClB,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,IAAI;QACX,WAAW,EACT,4HAA4H;QAC9H,OAAO,EAAE,EAAc;KACxB,CAAC;SACD,MAAM,CAAC,QAAQ,EAAE;QAChB,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,kBAAkB;KAChC,CAAC;SACD,MAAM,CAAC,eAAe,EAAE;QACvB,IAAI,EAAE,QAAQ;QACd,WAAW,EACT,yGAAyG;KAC5G,CAAC;SACD,MAAM,CAAC,UAAU,EAAE;QAClB,IAAI,EAAE,QAAQ;QACd,WAAW,EACT,kFAAkF;KACrF,CAAC;SACD,MAAM,CAAC,eAAe,EAAE;QACvB,IAAI,EAAE,QAAQ;QACd,WAAW,EACT,2EAA2E;KAC9E,CAAC;SACD,IAAI,EAAE,CAAC,IAAI,CAAC;IAEf,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;IAC5C,MAAM,mBAAmB,GAAG,IAAI,CAAC,OAAO,CACtC,OAAO,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAC1D,CAAC;IACF,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,CACpC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CACpE,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAClD,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,CAClD,CAAC;IACF,MAAM,YAAY,GAChB,OAAO,IAAI,CAAC,eAAe,CAAC,KAAK,QAAQ;QACzC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,GAAG,CAAC;QAC9B,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC;QACvB,CAAC,CAAC,IAAI,CAAC;IACX,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;IAE9D,wBAAwB;IACxB,MAAM,QAAQ,CAAC;QACb,WAAW,EAAE,mBAAmB;QAChC,SAAS,EAAE,iBAAiB;QAC5B,QAAQ;QACR,YAAY;QACZ,SAAS;KACV,CAAC,CAAC;IAEH,mEAAmE;IACnE,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACzC,MAAM,SAAS,CAAC,iBAAiB,CAAC,CAAC;QAEnC,kEAAkE;QAClE,kEAAkE;QAClE,oEAAoE;QACpE,4CAA4C;QAC5C,MAAM,aAAa,GAA2B,EAAE,CAAC;QACjD,IAAI,YAAY,EAAE,CAAC;YACjB,aAAa,CAAC,kBAAkB,GAAG,YAAY,CAAC;QAClD,CAAC;QACD,IAAI,SAAS,EAAE,CAAC;YACd,aAAa,CAAC,eAAe,GAAG,SAAS,CAAC;QAC5C,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxE,aAAa,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,CAAC;QACD,IACE,OAAO,IAAI,CAAC,eAAe,CAAC,KAAK,QAAQ;YACzC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,GAAG,CAAC,EAChC,CAAC;YACD,aAAa,CAAC,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;YACxC,MAAM,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAC;QACjE,CAAC;aAAM,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;YACzC,MAAM,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAC;YAE/D,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;gBACxC,MAAM,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACrB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\n\nimport execa from 'execa';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport npmWhich from 'npm-which';\nimport yargs from 'yargs';\n\nimport { generate } from './generate';\n\n/**\n * Locate the Docusaurus binary in this package's `node_modules/.bin`. Using\n * `npm-which` lets the lookup track wherever the installed Docusaurus puts\n * its binary, so a future Docusaurus upgrade can't break this path.\n *\n * @returns Absolute path to the `docusaurus` executable.\n */\nfunction resolveDocusaurus(): string {\n  return npmWhich(__dirname).sync('docusaurus');\n}\n\n/**\n * Run a Docusaurus command.\n *\n * @param command - The docusaurus command (start, build, serve).\n * @param cwd - The site directory.\n * @param extraEnv - Extra environment variables passed through to the\n * Docusaurus process (e.g. `DOCS_PROJECT_LABEL`, `DOCS_COMMIT_SHA`).\n */\nasync function runDocusaurus(\n  command: string,\n  cwd: string,\n  extraEnv: Record<string, string> = {},\n): Promise<void> {\n  await execa(resolveDocusaurus(), [command], {\n    cwd,\n    stdio: 'inherit',\n    env: { ...process.env, ...extraEnv },\n  });\n}\n\n/**\n * Copy site files into the output directory, skipping `node_modules` and\n * `docs` (the latter is owned by the doc generator and shouldn't be carried\n * over from the source `site/` directory).\n *\n * @param outDir - The output directory to set up.\n */\nasync function setupSite(outDir: string): Promise<void> {\n  const siteDir = path.resolve(__dirname, '..', 'site');\n  const skip = new Set(['node_modules', 'docs']);\n\n  console.log(`\\nSetting up Docusaurus site in ${outDir}...`);\n\n  // `fs.cp` has been available since Node 16.7 and only got the \"stable\"\n  // marker in 22.3 — it's functional throughout our supported Node range\n  // (`^18.18 || >=20`), even though the linter flags the older versions.\n  // eslint-disable-next-line n/no-unsupported-features/node-builtins\n  await fs.cp(siteDir, outDir, {\n    recursive: true,\n    filter: (source) => !skip.has(path.basename(source)),\n  });\n\n  // Write a minimal package.json so Docusaurus doesn't warn about a missing one\n  const pkgJsonPath = path.join(outDir, 'package.json');\n  try {\n    await fs.access(pkgJsonPath);\n  } catch {\n    await fs.writeFile(\n      pkgJsonPath,\n      JSON.stringify(\n        { name: 'platform-api-docs-site', private: true },\n        null,\n        2,\n      ),\n    );\n  }\n}\n\n/**\n * Resolve the short Git commit SHA the docs are being generated from.\n * Returns null when the project isn't a git repo or git isn't available.\n *\n * @param projectPath - The project root path.\n * @returns The short SHA, or null on failure.\n */\nasync function resolveCommitSha(projectPath: string): Promise<string | null> {\n  try {\n    const { stdout } = await execa('git', ['rev-parse', '--short', 'HEAD'], {\n      cwd: projectPath,\n    });\n    const trimmed = stdout.trim();\n    return trimmed.length > 0 ? trimmed : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Main CLI entry point.\n */\nasync function main(): Promise<void> {\n  const argv = await yargs(process.argv.slice(2))\n    .command(\n      '$0 [project-path]',\n      'Produces documentation for the platform API, the set of actions and events available in clients through the message bus.',\n      (yargsInstance) => {\n        yargsInstance.positional('project-path', {\n          type: 'string',\n          description: 'Path to the project to scan',\n          default: '.',\n        });\n      },\n    )\n    .option('build', {\n      type: 'boolean',\n      description:\n        'Generate platform API docs and build a production-ready site',\n      default: false,\n    })\n    .option('serve', {\n      type: 'boolean',\n      description:\n        'Generate platform API docs and serve a production-ready site',\n      default: false,\n    })\n    .option('dev', {\n      type: 'boolean',\n      description:\n        'Generate platform API docs and serve a development-only site',\n      default: false,\n    })\n    .option('scan-dir', {\n      type: 'string',\n      array: true,\n      description:\n        'Additional directories within the project to scan for messenger actions and events (note: may be specified multiple times)',\n      default: [] as string[],\n    })\n    .option('output', {\n      type: 'string',\n      description: 'Output directory',\n    })\n    .option('project-label', {\n      type: 'string',\n      description:\n        'Short label identifying the project (e.g. \"Core\", \"Extension\") — stamped on the site title and headings',\n    })\n    .option('site-url', {\n      type: 'string',\n      description:\n        'Absolute URL the built site will be served from, e.g. https://metamask.github.io',\n    })\n    .option('site-base-url', {\n      type: 'string',\n      description:\n        'Path prefix the built site will be served under, e.g. /core/platform-api/',\n    })\n    .help().argv;\n\n  const projectPathArg = argv['project-path'];\n  const resolvedProjectPath = path.resolve(\n    typeof projectPathArg === 'string' ? projectPathArg : '.',\n  );\n  const resolvedOutputDir = path.resolve(\n    argv.output ?? path.join(resolvedProjectPath, '.platform-api-docs'),\n  );\n  const scanDirs = ['src', ...argv['scan-dir']].filter(\n    (dir, index, dirs) => dirs.indexOf(dir) === index,\n  );\n  const projectLabel =\n    typeof argv['project-label'] === 'string' &&\n    argv['project-label'].length > 0\n      ? argv['project-label']\n      : null;\n  const commitSha = await resolveCommitSha(resolvedProjectPath);\n\n  // Step 1: Generate docs\n  await generate({\n    projectPath: resolvedProjectPath,\n    outputDir: resolvedOutputDir,\n    scanDirs,\n    projectLabel,\n    commitSha,\n  });\n\n  // Step 2: If --build, --serve, or --dev, set up and run Docusaurus\n  if (argv.build || argv.serve || argv.dev) {\n    await setupSite(resolvedOutputDir);\n\n    // Translate CLI flags into the environment variables Docusaurus's\n    // config reads. Keeping the CLI surface flag-only means consumers\n    // (workflow files, package.json scripts) don't have to know how the\n    // values are plumbed through to Docusaurus.\n    const docusaurusEnv: Record<string, string> = {};\n    if (projectLabel) {\n      docusaurusEnv.DOCS_PROJECT_LABEL = projectLabel;\n    }\n    if (commitSha) {\n      docusaurusEnv.DOCS_COMMIT_SHA = commitSha;\n    }\n    if (typeof argv['site-url'] === 'string' && argv['site-url'].length > 0) {\n      docusaurusEnv.DOCS_URL = argv['site-url'];\n    }\n    if (\n      typeof argv['site-base-url'] === 'string' &&\n      argv['site-base-url'].length > 0\n    ) {\n      docusaurusEnv.DOCS_BASE_URL = argv['site-base-url'];\n    }\n\n    if (argv.dev) {\n      console.log('\\nStarting dev server...');\n      await runDocusaurus('start', resolvedOutputDir, docusaurusEnv);\n    } else if (argv.build || argv.serve) {\n      console.log('\\nBuilding static site...');\n      await runDocusaurus('build', resolvedOutputDir, docusaurusEnv);\n\n      if (argv.serve) {\n        console.log('\\nServing static site...');\n        await runDocusaurus('serve', resolvedOutputDir, docusaurusEnv);\n      }\n    }\n  }\n}\n\nmain().catch((error) => {\n  console.error(error);\n  process.exitCode = 1;\n});\n"]}

package/dist/discovery.cjs

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findDtsFiles = exports.findTsFiles = void 0;
+const glob_1 = require("glob");
+/**
+ * Find all non-test TypeScript source files in a directory.
+ * Skips node_modules, dist, test directories, and declaration files.
+ *
+ * Results are sorted lexicographically so that downstream consumers
+ * (extraction, deduplication, output ordering) behave deterministically
+ * across filesystems.
+ *
+ * @param dir - The directory to search.
+ * @returns A promise that resolves to a sorted array of absolute file paths.
+ */
+async function findTsFiles(dir) {
+    const matches = await (0, glob_1.glob)('**/*.ts', {
+        cwd: dir,
+        absolute: true,
+        ignore: [
+            '**/node_modules/**',
+            '**/dist/**',
+            '**/__tests__/**',
+            '**/tests/**',
+            '**/test/**',
+            '**/__mocks__/**',
+            '**/*.test.ts',
+            '**/*.test-d.ts',
+            '**/*.spec.ts',
+            '**/*.d.ts',
+        ],
+    });
+    return matches.sort();
+}
+exports.findTsFiles = findTsFiles;
+/**
+ * Find all `.d.cts` declaration files in a directory.
+ * Skips nested node_modules subdirectories. See {@link findTsFiles} for the
+ * note about sorting.
+ *
+ * @param dir - The directory to search.
+ * @returns A promise that resolves to a sorted array of absolute file paths.
+ */
+async function findDtsFiles(dir) {
+    const matches = await (0, glob_1.glob)('**/*.d.cts', {
+        cwd: dir,
+        absolute: true,
+        ignore: ['**/node_modules/**'],
+    });
+    return matches.sort();
+}
+exports.findDtsFiles = findDtsFiles;
+//# sourceMappingURL=discovery.cjs.map

package/dist/discovery.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.cjs","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":";;;AAAA,+BAA4B;AAE5B;;;;;;;;;;GAUG;AACI,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,OAAO,GAAG,MAAM,IAAA,WAAI,EAAC,SAAS,EAAE;QACpC,GAAG,EAAE,GAAG;QACR,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE;YACN,oBAAoB;YACpB,YAAY;YACZ,iBAAiB;YACjB,aAAa;YACb,YAAY;YACZ,iBAAiB;YACjB,cAAc;YACd,gBAAgB;YAChB,cAAc;YACd,WAAW;SACZ;KACF,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC;AAlBD,kCAkBC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,YAAY,CAAC,GAAW;IAC5C,MAAM,OAAO,GAAG,MAAM,IAAA,WAAI,EAAC,YAAY,EAAE;QACvC,GAAG,EAAE,GAAG;QACR,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,CAAC,oBAAoB,CAAC;KAC/B,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC;AAPD,oCAOC","sourcesContent":["import { glob } from 'glob';\n\n/**\n * Find all non-test TypeScript source files in a directory.\n * Skips node_modules, dist, test directories, and declaration files.\n *\n * Results are sorted lexicographically so that downstream consumers\n * (extraction, deduplication, output ordering) behave deterministically\n * across filesystems.\n *\n * @param dir - The directory to search.\n * @returns A promise that resolves to a sorted array of absolute file paths.\n */\nexport async function findTsFiles(dir: string): Promise<string[]> {\n  const matches = await glob('**/*.ts', {\n    cwd: dir,\n    absolute: true,\n    ignore: [\n      '**/node_modules/**',\n      '**/dist/**',\n      '**/__tests__/**',\n      '**/tests/**',\n      '**/test/**',\n      '**/__mocks__/**',\n      '**/*.test.ts',\n      '**/*.test-d.ts',\n      '**/*.spec.ts',\n      '**/*.d.ts',\n    ],\n  });\n  return matches.sort();\n}\n\n/**\n * Find all `.d.cts` declaration files in a directory.\n * Skips nested node_modules subdirectories. See {@link findTsFiles} for the\n * note about sorting.\n *\n * @param dir - The directory to search.\n * @returns A promise that resolves to a sorted array of absolute file paths.\n */\nexport async function findDtsFiles(dir: string): Promise<string[]> {\n  const matches = await glob('**/*.d.cts', {\n    cwd: dir,\n    absolute: true,\n    ignore: ['**/node_modules/**'],\n  });\n  return matches.sort();\n}\n"]}

package/dist/discovery.d.cts

@@ -0,0 +1,22 @@
+/**
+ * Find all non-test TypeScript source files in a directory.
+ * Skips node_modules, dist, test directories, and declaration files.
+ *
+ * Results are sorted lexicographically so that downstream consumers
+ * (extraction, deduplication, output ordering) behave deterministically
+ * across filesystems.
+ *
+ * @param dir - The directory to search.
+ * @returns A promise that resolves to a sorted array of absolute file paths.
+ */
+export declare function findTsFiles(dir: string): Promise<string[]>;
+/**
+ * Find all `.d.cts` declaration files in a directory.
+ * Skips nested node_modules subdirectories. See {@link findTsFiles} for the
+ * note about sorting.
+ *
+ * @param dir - The directory to search.
+ * @returns A promise that resolves to a sorted array of absolute file paths.
+ */
+export declare function findDtsFiles(dir: string): Promise<string[]>;
+//# sourceMappingURL=discovery.d.cts.map

package/dist/discovery.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.cts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBhE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOjE"}

package/dist/discovery.d.mts

@@ -0,0 +1,22 @@
+/**
+ * Find all non-test TypeScript source files in a directory.
+ * Skips node_modules, dist, test directories, and declaration files.
+ *
+ * Results are sorted lexicographically so that downstream consumers
+ * (extraction, deduplication, output ordering) behave deterministically
+ * across filesystems.
+ *
+ * @param dir - The directory to search.
+ * @returns A promise that resolves to a sorted array of absolute file paths.
+ */
+export declare function findTsFiles(dir: string): Promise<string[]>;
+/**
+ * Find all `.d.cts` declaration files in a directory.
+ * Skips nested node_modules subdirectories. See {@link findTsFiles} for the
+ * note about sorting.
+ *
+ * @param dir - The directory to search.
+ * @returns A promise that resolves to a sorted array of absolute file paths.
+ */
+export declare function findDtsFiles(dir: string): Promise<string[]>;
+//# sourceMappingURL=discovery.d.mts.map

package/dist/discovery.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.mts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBhE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOjE"}

package/dist/discovery.mjs

@@ -0,0 +1,48 @@
+import { glob } from "glob";
+/**
+ * Find all non-test TypeScript source files in a directory.
+ * Skips node_modules, dist, test directories, and declaration files.
+ *
+ * Results are sorted lexicographically so that downstream consumers
+ * (extraction, deduplication, output ordering) behave deterministically
+ * across filesystems.
+ *
+ * @param dir - The directory to search.
+ * @returns A promise that resolves to a sorted array of absolute file paths.
+ */
+export async function findTsFiles(dir) {
+    const matches = await glob('**/*.ts', {
+        cwd: dir,
+        absolute: true,
+        ignore: [
+            '**/node_modules/**',
+            '**/dist/**',
+            '**/__tests__/**',
+            '**/tests/**',
+            '**/test/**',
+            '**/__mocks__/**',
+            '**/*.test.ts',
+            '**/*.test-d.ts',
+            '**/*.spec.ts',
+            '**/*.d.ts',
+        ],
+    });
+    return matches.sort();
+}
+/**
+ * Find all `.d.cts` declaration files in a directory.
+ * Skips nested node_modules subdirectories. See {@link findTsFiles} for the
+ * note about sorting.
+ *
+ * @param dir - The directory to search.
+ * @returns A promise that resolves to a sorted array of absolute file paths.
+ */
+export async function findDtsFiles(dir) {
+    const matches = await glob('**/*.d.cts', {
+        cwd: dir,
+        absolute: true,
+        ignore: ['**/node_modules/**'],
+    });
+    return matches.sort();
+}
+//# sourceMappingURL=discovery.mjs.map

package/dist/discovery.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.mjs","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,aAAa;AAE5B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE;QACpC,GAAG,EAAE,GAAG;QACR,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE;YACN,oBAAoB;YACpB,YAAY;YACZ,iBAAiB;YACjB,aAAa;YACb,YAAY;YACZ,iBAAiB;YACjB,cAAc;YACd,gBAAgB;YAChB,cAAc;YACd,WAAW;SACZ;KACF,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAW;IAC5C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE;QACvC,GAAG,EAAE,GAAG;QACR,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,CAAC,oBAAoB,CAAC;KAC/B,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC","sourcesContent":["import { glob } from 'glob';\n\n/**\n * Find all non-test TypeScript source files in a directory.\n * Skips node_modules, dist, test directories, and declaration files.\n *\n * Results are sorted lexicographically so that downstream consumers\n * (extraction, deduplication, output ordering) behave deterministically\n * across filesystems.\n *\n * @param dir - The directory to search.\n * @returns A promise that resolves to a sorted array of absolute file paths.\n */\nexport async function findTsFiles(dir: string): Promise<string[]> {\n  const matches = await glob('**/*.ts', {\n    cwd: dir,\n    absolute: true,\n    ignore: [\n      '**/node_modules/**',\n      '**/dist/**',\n      '**/__tests__/**',\n      '**/tests/**',\n      '**/test/**',\n      '**/__mocks__/**',\n      '**/*.test.ts',\n      '**/*.test-d.ts',\n      '**/*.spec.ts',\n      '**/*.d.ts',\n    ],\n  });\n  return matches.sort();\n}\n\n/**\n * Find all `.d.cts` declaration files in a directory.\n * Skips nested node_modules subdirectories. See {@link findTsFiles} for the\n * note about sorting.\n *\n * @param dir - The directory to search.\n * @returns A promise that resolves to a sorted array of absolute file paths.\n */\nexport async function findDtsFiles(dir: string): Promise<string[]> {\n  const matches = await glob('**/*.d.cts', {\n    cwd: dir,\n    absolute: true,\n    ignore: ['**/node_modules/**'],\n  });\n  return matches.sort();\n}\n"]}