@appium/docutils 0.1.6 → 0.2.1

package/build/lib/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../lib/logger.js"],"names":[],"mappings":";;AAAA,6CAAuC;AAEvC,kBAAe,gBAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../lib/logger.ts"],"names":[],"mappings":"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"}

package/build/lib/mike.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @deprecated Use the `deploy` export from `@appium/docutils`
+ */
 export class Mike {
     constructor(opts: MikeOpts);
     /** @type {string} */ remote: string;

package/build/lib/mike.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mike.d.ts","sourceRoot":"","sources":["../../lib/mike.js"],"names":[],"mappings":"AAOA;IAOE,kBAAsB,QAAQ,EAK7B;IAXD,qBAAqB,CAAC,QAAX,MAAM,CAAY;IAC7B,qBAAqB,CAAC,QAAX,MAAM,CAAY;IAC7B,sBAAsB,CAAC,QAAZ,MAAM,QAAa;IAC9B,qBAAqB,CAAC,YAAX,MAAM,CAAgB;IACjC,sBAAsB,CAAC,eAAZ,OAAO,CAA2B;IAS7C;;;;OAIG;IACH,4BAaC;IAED;;;;;;;;OAQG;IACH,qBALW,MAAM,WACN,MAAM,EAAE,GAEN,MAAM,EAAE,CAepB;IAED;;;;;;;;OAQG;IACH,cANW,MAAM,yEAIJ,QAAQ,OAAO,cAAc,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAS9D;IAED;;;;OAIG;IACH,QAFa,MAAM,EAAE,CAQpB;IAED;;;;OAIG;IACH,kBAFW,MAAM,iBAIhB;IAED;;;;OAIG;IACH,iCAeC;CACF;;;;;;;;;;;;;;;;YAMa,MAAM;;;;gBACN,MAAM"}
+{"version":3,"file":"mike.d.ts","sourceRoot":"","sources":["../../lib/mike.js"],"names":[],"mappings":"AAQA;;GAEG;AACH;IAOE,kBAAsB,QAAQ,EAK7B;IAXD,qBAAqB,CAAC,QAAX,MAAM,CAAY;IAC7B,qBAAqB,CAAC,QAAX,MAAM,CAAY;IAC7B,sBAAsB,CAAC,QAAZ,MAAM,QAAa;IAC9B,qBAAqB,CAAC,YAAX,MAAM,CAAgB;IACjC,sBAAsB,CAAC,eAAZ,OAAO,CAA2B;IAS7C;;;;OAIG;IACH,4BAaC;IAED;;;;;;;;OAQG;IACH,qBALW,MAAM,WACN,MAAM,EAAE,GAEN,MAAM,EAAE,CAepB;IAED;;;;;;;;OAQG;IACH,cANW,MAAM,yEAIJ,QAAQ,OAAO,cAAc,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAS9D;IAED;;;;OAIG;IACH,QAFa,MAAM,EAAE,CAQpB;IAED;;;;OAIG;IACH,kBAFW,MAAM,iBAIhB;IAED;;;;OAIG;IACH,iCAeC;CACF;;;;;;;;;;;;;;;;YAMa,MAAM;;;;gBACN,MAAM"}

package/build/lib/mike.js

@@ -5,10 +5,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Mike = void 0;
 const teen_process_1 = require("teen_process");
+// eslint-disable-next-line import/no-unresolved
 const logger_1 = __importDefault(require("./logger"));
 const DEFAULT_REMOTE = 'origin';
 const DEFAULT_BRANCH = 'gh-pages';
 const MIKE_VER_STRING = 'mike 1.';
+/**
+ * @deprecated Use the `deploy` export from `@appium/docutils`
+ */
 class Mike {
     constructor(/** @type MikeOpts */ opts) {
         /** @type {boolean} */ this._mikeVerified = false;

package/build/lib/mike.js.map

@@ -1 +1 @@
-{"version":3,"file":"mike.js","sourceRoot":"","sources":["../../lib/mike.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"mike.js","sourceRoot":"","sources":["../../lib/mike.js"],"names":[],"mappings":"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"}

package/build/lib/mkdocs.d.ts

@@ -1,19 +1,58 @@
 /**
- * Run a version check on the system-installed mkdocs to make sure it is set up
+ * Functions for running `mkdocs`
+ *
+ * @module
  */
-export function verifyMkdocs(): Promise<void>;
+import { SubProcess, TeenProcessExecOptions } from 'teen_process';
+import { TupleToObject } from './util';
 /**
- * Run 'mkdocs build' on a project
- *
- * @param {string} configPath - path to mkdocs config yml
- * @param {string} outputDir - directory mkdocs should build into
- * @param {string?} theme - theme name
+ * Runs `mkdocs build` or `mkdocs serve`
+ * @param opts
  */
-export function mkdocsBuild(configPath: string, outputDir: string, theme?: string | null): Promise<void>;
+export declare function buildMkDocs({ mkdocsYml: mkdocsYmlPath, siteDir, theme, cwd, serve, serveOpts, execOpts, }?: BuildMkDocsOpts): Promise<void>;
 /**
- * Run 'mkdocs serve' on a project
- *
- * @param {string} configPath - path to mkdocs config yml
+ * Options for {@linkcode buildMkDocs}.
+ */
+export interface BuildMkDocsOpts {
+    /**
+     * Path to `mkdocs.yml`
+     */
+    mkdocsYml?: string;
+    /**
+     * Path to output directory
+     */
+    siteDir?: string;
+    /**
+     * MkDocs theme to use
+     * @defaultValue 'mkdocs'
+     */
+    theme?: string;
+    /**
+     * Current working directory
+     * @defaultValue `process.cwd()`
+     */
+    cwd?: string;
+    /**
+     * Path to `package.json`
+     *
+     * Used to find `mkdocs.yml` if unspecified.
+     */
+    packageJson?: string;
+    /**
+     * If `true`, run `mkdocs serve` instead of `mkdocs build`
+     */
+    serve?: boolean;
+    /**
+     * Extra options for {@linkcode teen_process.exec}
+     */
+    execOpts?: TeenProcessExecOptions;
+    /**
+     * Extra options for {@linkcode teen_process.Subprocess.start}
+     */
+    serveOpts?: TeenProcessSubprocessStartOpts;
+}
+/**
+ * Conversion of the parameters of {@linkcode Subprocess.start} to an object.
  */
-export function mkdocsServe(configPath: string): Promise<void>;
+export declare type TeenProcessSubprocessStartOpts = Partial<TupleToObject<Parameters<SubProcess['start']>, ['startDetector', 'detach', 'timeoutMs']>>;
 //# sourceMappingURL=mkdocs.d.ts.map

package/build/lib/mkdocs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mkdocs.d.ts","sourceRoot":"","sources":["../../lib/mkdocs.js"],"names":[],"mappings":"AAIA;;GAEG;AACH,8CAYC;AAED;;;;;;GAMG;AACH,wCAJW,MAAM,aACN,MAAM,UACN,MAAM,wBAKhB;AAED;;;;GAIG;AACH,wCAFW,MAAM,iBAMhB"}
+{"version":3,"file":"mkdocs.d.ts","sourceRoot":"","sources":["../../lib/mkdocs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAO,UAAU,EAAE,sBAAsB,EAAC,MAAM,cAAc,CAAC;AAItE,OAAO,EAAsB,aAAa,EAAC,MAAM,QAAQ,CAAC;AAyC1D;;;GAGG;AACH,wBAAsB,WAAW,CAAC,EAChC,SAAS,EAAE,aAAa,EACxB,OAAO,EACP,KAAmB,EACnB,GAAmB,EACnB,KAAa,EACb,SAAS,EACT,QAAQ,GACT,GAAE,eAAoB,iBA2BtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAElC;;OAEG;IACH,SAAS,CAAC,EAAE,8BAA8B,CAAC;CAC5C;AAED;;GAEG;AACH,oBAAY,8BAA8B,GAAG,OAAO,CAClD,aAAa,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,eAAe,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CACzF,CAAC"}

package/build/lib/mkdocs.js

@@ -1,45 +1,77 @@
 "use strict";
+/**
+ * Functions for running `mkdocs`
+ *
+ * @module
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mkdocsServe = exports.mkdocsBuild = exports.verifyMkdocs = void 0;
+exports.buildMkDocs = void 0;
 const teen_process_1 = require("teen_process");
-const MKDOCS_VER_STR = 'version 1.';
+const constants_1 = require("./constants");
+const fs_1 = require("./fs");
+const logger_1 = __importDefault(require("./logger"));
+const util_1 = require("./util");
+const error_1 = require("./error");
+const log = logger_1.default.withTag('mkdocs');
 /**
- * Run a version check on the system-installed mkdocs to make sure it is set up
+ * Runs `mkdocs serve`
+ * @param args Extra args to `mkdocs build`
+ * @param opts Extra options for `teen_process.Subprocess.start`
+ * @param mkDocsPath Path to `mkdocs` executable
  */
-async function verifyMkdocs() {
-    try {
-        const { stdout } = await (0, teen_process_1.exec)('mkdocs', ['-V']);
-        if (!stdout.includes(MKDOCS_VER_STR)) {
-            throw new Error('version mismatch');
-        }
-    }
-    catch (err) {
-        throw new Error(`Could not verify mkdocs 1.x is available. Make sure it's installed ` +
-            `and on your path. Specific error: ${err}`);
-    }
+async function doServe(args = [], { startDetector, detach, timeoutMs } = {}, mkDocsPath) {
+    mkDocsPath = mkDocsPath ?? (await (0, fs_1.whichMkDocs)());
+    const finalArgs = ['serve', ...args];
+    log.debug('Launching %s with args: %O', mkDocsPath, finalArgs);
+    const proc = new teen_process_1.SubProcess(mkDocsPath, finalArgs);
+    return await proc.start(startDetector, detach, timeoutMs);
 }
-exports.verifyMkdocs = verifyMkdocs;
 /**
- * Run 'mkdocs build' on a project
- *
- * @param {string} configPath - path to mkdocs config yml
- * @param {string} outputDir - directory mkdocs should build into
- * @param {string?} theme - theme name
+ * Runs `mkdocs build`
+ * @param args Extra args to `mkdocs build`
+ * @param opts Extra options to `teen_process.exec`
+ * @param mkDocsPath Path to `mkdocs` executable
  */
-async function mkdocsBuild(configPath, outputDir, theme = 'mkdocs') {
-    await verifyMkdocs();
-    await (0, teen_process_1.exec)('mkdocs', ['build', '-f', configPath, '-t', theme, '-d', outputDir]);
+async function doBuild(args = [], opts = {}, mkDocsPath) {
+    mkDocsPath = mkDocsPath ?? (await (0, fs_1.whichMkDocs)());
+    const finalArgs = ['build', ...args];
+    log.debug('Launching %s with args: %O', mkDocsPath, finalArgs);
+    return await (0, teen_process_1.exec)(mkDocsPath, finalArgs, opts);
 }
-exports.mkdocsBuild = mkdocsBuild;
 /**
- * Run 'mkdocs serve' on a project
- *
- * @param {string} configPath - path to mkdocs config yml
+ * Runs `mkdocs build` or `mkdocs serve`
+ * @param opts
  */
-async function mkdocsServe(configPath) {
-    await verifyMkdocs();
-    const proc = new teen_process_1.SubProcess('mkdocs', ['serve', '-f', configPath]);
-    await proc.start();
+async function buildMkDocs({ mkdocsYml: mkdocsYmlPath, siteDir, theme = constants_1.NAME_MKDOCS, cwd = process.cwd(), serve = false, serveOpts, execOpts, } = {}) {
+    const stop = (0, util_1.stopwatch)('build-mkdocs');
+    mkdocsYmlPath = mkdocsYmlPath ?? (await (0, fs_1.findMkDocsYml)(cwd));
+    if (!mkdocsYmlPath) {
+        throw new error_1.DocutilsError(`Could not find ${constants_1.NAME_MKDOCS_YML} from ${cwd}; run "${constants_1.NAME_BIN} init" to create it`);
+    }
+    const relativePath = (0, util_1.relative)(cwd);
+    const mkdocsArgs = ['-f', mkdocsYmlPath, '-t', theme];
+    if (siteDir) {
+        mkdocsArgs.push('-d', siteDir);
+    }
+    if (serve) {
+        // unsure about how SIGHUP is handled here
+        await doServe(mkdocsArgs, serveOpts);
+    }
+    else {
+        await doBuild(mkdocsArgs, execOpts);
+        let relSiteDir;
+        if (siteDir) {
+            relSiteDir = relativePath(siteDir);
+        }
+        else {
+            ({ site_dir: siteDir } = await (0, fs_1.readYaml)(mkdocsYmlPath));
+            relSiteDir = relativePath(siteDir);
+        }
+        log.success('MkDocs finished building into %s (%dms)', relSiteDir, stop());
+    }
 }
-exports.mkdocsServe = mkdocsServe;
+exports.buildMkDocs = buildMkDocs;
 //# sourceMappingURL=mkdocs.js.map

package/build/lib/mkdocs.js.map

@@ -1 +1 @@
-{"version":3,"file":"mkdocs.js","sourceRoot":"","sources":["../../lib/mkdocs.js"],"names":[],"mappings":";;;AAAA,+CAA8C;AAE9C,MAAM,cAAc,GAAG,YAAY,CAAC;AAEpC;;GAEG;AACI,KAAK,UAAU,YAAY;IAChC,IAAI;QACF,MAAM,EAAC,MAAM,EAAC,GAAG,MAAM,IAAA,mBAAI,EAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE;YACpC,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;SACrC;KACF;IAAC,OAAO,GAAG,EAAE;QACZ,MAAM,IAAI,KAAK,CACb,qEAAqE;YACnE,qCAAqC,GAAG,EAAE,CAC7C,CAAC;KACH;AACH,CAAC;AAZD,oCAYC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,WAAW,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,GAAG,QAAQ;IACvE,MAAM,YAAY,EAAE,CAAC;IACrB,MAAM,IAAA,mBAAI,EAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;AAClF,CAAC;AAHD,kCAGC;AAED;;;;GAIG;AACI,KAAK,UAAU,WAAW,CAAC,UAAU;IAC1C,MAAM,YAAY,EAAE,CAAC;IACrB,MAAM,IAAI,GAAG,IAAI,yBAAU,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IACnE,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC;AAJD,kCAIC"}
+{"version":3,"file":"mkdocs.js","sourceRoot":"","sources":["../../lib/mkdocs.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;AAEH,+CAAsE;AACtE,2CAAmE;AACnE,6BAA0D;AAC1D,sDAA8B;AAC9B,iCAA0D;AAE1D,mCAAsC;AAEtC,MAAM,GAAG,GAAG,gBAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAErC;;;;;GAKG;AACH,KAAK,UAAU,OAAO,CACpB,OAAiB,EAAE,EACnB,EAAC,aAAa,EAAE,MAAM,EAAE,SAAS,KAAoC,EAAE,EACvE,UAAmB;IAEnB,UAAU,GAAG,UAAU,IAAI,CAAC,MAAM,IAAA,gBAAW,GAAE,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACrC,GAAG,CAAC,KAAK,CAAC,4BAA4B,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,IAAI,yBAAU,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACnD,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,OAAO,CACpB,OAAiB,EAAE,EACnB,OAA+B,EAAE,EACjC,UAAmB;IAEnB,UAAU,GAAG,UAAU,IAAI,CAAC,MAAM,IAAA,gBAAW,GAAE,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACrC,GAAG,CAAC,KAAK,CAAC,4BAA4B,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAC/D,OAAO,MAAM,IAAA,mBAAI,EAAC,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;AACjD,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,WAAW,CAAC,EAChC,SAAS,EAAE,aAAa,EACxB,OAAO,EACP,KAAK,GAAG,uBAAW,EACnB,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,EACnB,KAAK,GAAG,KAAK,EACb,SAAS,EACT,QAAQ,MACW,EAAE;IACrB,MAAM,IAAI,GAAG,IAAA,gBAAS,EAAC,cAAc,CAAC,CAAC;IACvC,aAAa,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,kBAAa,EAAC,GAAG,CAAC,CAAC,CAAC;IAC5D,IAAI,CAAC,aAAa,EAAE;QAClB,MAAM,IAAI,qBAAa,CACrB,kBAAkB,2BAAe,SAAS,GAAG,UAAU,oBAAQ,qBAAqB,CACrF,CAAC;KACH;IACD,MAAM,YAAY,GAAG,IAAA,eAAQ,EAAC,GAAG,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACtD,IAAI,OAAO,EAAE;QACX,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;KAChC;IACD,IAAI,KAAK,EAAE;QACT,0CAA0C;QAC1C,MAAM,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;KACtC;SAAM;QACL,MAAM,OAAO,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QACpC,IAAI,UAAU,CAAC;QACf,IAAI,OAAO,EAAE;YACX,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;SACpC;aAAM;YACL,CAAC,EAAC,QAAQ,EAAE,OAAO,EAAC,GAAG,MAAM,IAAA,aAAQ,EAAC,aAAa,CAAC,CAAC,CAAC;YACtD,UAAU,GAAG,YAAY,CAAC,OAAQ,CAAC,CAAC;SACrC;QACD,GAAG,CAAC,OAAO,CAAC,yCAAyC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;KAC5E;AACH,CAAC;AAnCD,kCAmCC"}

package/build/lib/model.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Various data models, mostly referring to config files
+ *
+ * @module
+ */
+import type { Jsonify, JsonValue, TsConfigJson as TsConfigJsonBase } from 'type-fest';
+import type { TypeDocOptions } from 'typedoc';
+/**
+ * A `tsconfig.json` file w/ `$schema` prop
+ *
+ * Due to some `unknown` types in {@linkcode type-fest.TsConfigJson}, we cannot use that type
+ * directly and need to use `Jsonify`.
+ *
+ */
+export declare type TsConfigJson = Jsonify<TsConfigJsonBase & {
+    $schema?: string;
+}>;
+/**
+ * A `typedoc.json` file w/ `$schema` and `extends` props
+ *
+ * TypeDoc doesn't recognize `$schema` and ignores it; its own config parser expands the value of
+ * `extends` before it reaches its `Options` class. This is why we cannot use `TypeDocOptions` directly.
+ */
+export declare type TypeDocJson = Jsonify<Partial<TypeDocOptions> & {
+    $schema?: string;
+    extends?: string;
+}>;
+/**
+ * The `nav` prop of an `mkdocs.yml` file
+ * @see {@linkcode MkDocsYml}
+ */
+export declare type MkDocsYmlNav = Array<string | Record<string, string> | Record<string, MkDocsYmlNav>>;
+/**
+ * This was built by hand from the MkDocs documentation
+ * @see https://www.mkdocs.org/user-guide/configuration/
+ */
+export declare type MkDocsYml = Jsonify<{
+    copyright?: string;
+    dev_addr?: string;
+    docs_dir?: string;
+    extra_css?: string[];
+    extra_javascript?: string[];
+    extra_templates?: string[];
+    extra?: Record<string, JsonValue>;
+    hooks?: string[];
+    INHERIT?: string;
+    markdown_extensions?: Array<string | Record<string, JsonValue>>;
+    nav?: MkDocsYmlNav;
+    plugins?: Array<string | Record<string, JsonValue>>;
+    repo_name?: string;
+    repo_url?: string;
+    site_dir?: string;
+    /**
+     * This is _actually_ required by mkdocs
+     */
+    site_name?: string;
+    site_description?: string;
+    strict?: boolean;
+    theme?: MkDocsYmlTheme;
+    use_directory_urls?: boolean;
+    watch?: string[];
+}>;
+/**
+ * The `theme` prop of an `mkdocs.yml`
+ * @see {@linkcode MkDocsYml}
+ */
+export declare type MkDocsYmlTheme = string | ({
+    name: string;
+    locale?: string;
+    custom_dir?: string;
+    static_templates?: string[];
+} & Record<string, JsonValue>);
+/**
+ * The data parsed from a `requirements.txt` file, or the output of `pip list --json`
+ */
+export interface PipPackage {
+    name: string;
+    version: string;
+}
+//# sourceMappingURL=model.d.ts.map

package/build/lib/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../lib/model.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,SAAS,EAAE,YAAY,IAAI,gBAAgB,EAAC,MAAM,WAAW,CAAC;AACpF,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAE5C;;;;;;GAMG;AACH,oBAAY,YAAY,GAAG,OAAO,CAChC,gBAAgB,GAAG;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CACF,CAAC;AAEF;;;;;GAKG;AACH,oBAAY,WAAW,GAAG,OAAO,CAC/B,OAAO,CAAC,cAAc,CAAC,GAAG;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CACF,CAAC;AAEF;;;GAGG;AACH,oBAAY,YAAY,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;AAEjG;;;GAGG;AACH,oBAAY,SAAS,GAAG,OAAO,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAChE,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CAAC;AAEH;;;GAGG;AACH,oBAAY,cAAc,GACtB,MAAM,GACN,CAAC;IACC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/build/lib/model.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Various data models, mostly referring to config files
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=model.js.map

package/build/lib/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../lib/model.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/build/lib/nav.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Handles updating/adding the `nav` property of `mkdocs.yml`, based on the output of `typedoc`;
+ * specifically, the command documentation generated by `@appium/typedoc-plugin-appium`.
+ *
+ * @module
+ */
+/**
+ * Update the `nav` property of `mkdocs.yml` with a list of "command" files generated by TypeDoc via `@appium/typedoc-plugin-appium`
+ * @param opts - Options
+ * @todo implement `dryRun` option
+ */
+export declare function updateNav<S extends string>({ cwd, mkdocsYml: mkDocsYmlPath, referenceHeader, noReferenceHeader, typedocJson: typeDocJsonPath, dryRun, }?: UpdateNavOpts<S>): Promise<void>;
+/**
+ * Options for {@linkcode updateNav}
+ */
+export interface UpdateNavOpts<S extends string> {
+    /**
+     * Current working directory
+     */
+    cwd?: string;
+    /**
+     * Path to `mkdocs.yml`
+     */
+    mkdocsYml?: string;
+    /**
+     * Path to `package.json`
+     */
+    packageJson?: string;
+    /**
+     * The name of the header in `nav` to use for reference docs.
+     */
+    referenceHeader?: S;
+    /**
+     * If `true`, do not add a reference header to `nav` if one does not exist
+     */
+    noReferenceHeader?: boolean;
+    /**
+     * Path to `typedoc.json`
+     */
+    typedocJson?: string;
+    /**
+     * If `true`, do not write any files
+     * @remarks Not yet implemented
+     */
+    dryRun?: boolean;
+}
+//# sourceMappingURL=nav.d.ts.map

package/build/lib/nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.d.ts","sourceRoot":"","sources":["../../lib/nav.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,EAChD,GAAmB,EACnB,SAAS,EAAE,aAAa,EACxB,eAA6C,EAC7C,iBAAyB,EACzB,WAAW,EAAE,eAAe,EAC5B,MAAc,GACf,GAAE,aAAa,CAAC,CAAC,CAAM,iBA2HvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM;IAC7C;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,eAAe,CAAC,EAAE,CAAC,CAAC;IACpB;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/build/lib/nav.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Handles updating/adding the `nav` property of `mkdocs.yml`, based on the output of `typedoc`;
+ * specifically, the command documentation generated by `@appium/typedoc-plugin-appium`.
+ *
+ * @module
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateNav = void 0;
+const support_1 = require("@appium/support");
+const lodash_1 = __importDefault(require("lodash"));
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("./constants");
+const error_1 = require("./error");
+const fs_1 = require("./fs");
+const logger_1 = __importDefault(require("./logger"));
+const util_1 = require("./util");
+const DEFAULT_REFERENCE_HEADER = 'Reference';
+const log = logger_1.default.withTag('mkdocs-nav');
+/**
+ * Update the `nav` property of `mkdocs.yml` with a list of "command" files generated by TypeDoc via `@appium/typedoc-plugin-appium`
+ * @param opts - Options
+ * @todo implement `dryRun` option
+ */
+async function updateNav({ cwd = process.cwd(), mkdocsYml: mkDocsYmlPath, referenceHeader = DEFAULT_REFERENCE_HEADER, noReferenceHeader = false, typedocJson: typeDocJsonPath, dryRun = false, } = {}) {
+    [mkDocsYmlPath, typeDocJsonPath] = await Promise.all([
+        mkDocsYmlPath ?? (0, fs_1.findMkDocsYml)(cwd),
+        typeDocJsonPath ?? (0, fs_1.findTypeDocJsonPath)(cwd),
+    ]);
+    if (!mkDocsYmlPath) {
+        throw new error_1.DocutilsError(`Could not find ${constants_1.NAME_MKDOCS_YML} from ${cwd};  run "${constants_1.NAME_BIN} init" to create it`);
+    }
+    if (!typeDocJsonPath) {
+        throw new error_1.DocutilsError(`Could not find ${constants_1.NAME_TYPEDOC_JSON} from ${cwd};  run "${constants_1.NAME_BIN} init" to create it`);
+    }
+    const relativePath = (0, util_1.relative)(cwd);
+    const relMkDocsYmlPath = relativePath(mkDocsYmlPath);
+    const typeDocJson = (0, fs_1.readTypedocJson)(typeDocJsonPath);
+    const mkDocsYml = (await (0, fs_1.readYaml)(mkDocsYmlPath));
+    const findRefDictIndex = lodash_1.default.partial(lodash_1.default.findIndex, lodash_1.default, lodash_1.default.overEvery([lodash_1.default.isObject, lodash_1.default.partial(lodash_1.default.has, lodash_1.default, referenceHeader)]));
+    /**
+     * Absolute path to `typedoc.json`
+     */
+    const absTypeDocJsonPath = node_path_1.default.isAbsolute(typeDocJsonPath)
+        ? typeDocJsonPath
+        : node_path_1.default.resolve(cwd, typeDocJsonPath);
+    /**
+     * Absolute path to TypeDoc's output directory (`out`)
+     */
+    const typeDocOutDir = node_path_1.default.resolve(node_path_1.default.dirname(absTypeDocJsonPath), typeDocJson.out ? typeDocJson.out : constants_1.DEFAULT_REL_TYPEDOC_OUT_PATH);
+    /**
+     * Absolute path to `mkdocs.yml`
+     */
+    const absMkdocsYmlPath = node_path_1.default.isAbsolute(mkDocsYmlPath)
+        ? mkDocsYmlPath
+        : node_path_1.default.resolve(cwd, mkDocsYmlPath);
+    const { docs_dir: docsDir, nav = [] } = mkDocsYml;
+    /**
+     * Absolute path to the directory containing MkDocs input docs
+     */
+    const mkDocsDocsDir = node_path_1.default.resolve(node_path_1.default.dirname(absMkdocsYmlPath), docsDir ?? 'docs');
+    /**
+     * The dir we need to prepend to all entries within `nav`
+     */
+    const relReferenceDir = node_path_1.default.relative(mkDocsDocsDir, typeDocOutDir);
+    const partitionRefArray = lodash_1.default.partialRight(lodash_1.default.partition, lodash_1.default.partialRight(lodash_1.default.startsWith, `${relReferenceDir}/`));
+    const newRefFilepaths = [];
+    // TODO: this doesn't respect the 'commandsDir' option for typedoc-plugin-appium.  in fact,
+    // typeDocJson does not even include it, because it's unknown.  I suppose that will mean we need
+    // to load plugins, but that means bootstrapping TypeDoc entirely just to read a `typedoc.json`
+    // file, which is slow.
+    const commandDir = node_path_1.default.join(typeDocOutDir, 'commands');
+    const relCommandDir = node_path_1.default.relative(mkDocsDocsDir, commandDir);
+    const commandDocFileEnts = await support_1.fs.readdir(commandDir, { withFileTypes: true });
+    if (!commandDocFileEnts.length) {
+        log.warn('No reference API docs were found in %s; skipping navigation update', commandDir);
+        return;
+    }
+    for (const ent of commandDocFileEnts) {
+        if (ent.isFile() && ent.name.endsWith('.md')) {
+            newRefFilepaths.push(node_path_1.default.join(relCommandDir, ent.name));
+        }
+    }
+    log.debug('New reference filepaths: %O', newRefFilepaths);
+    const navUsesHeaders = noReferenceHeader || !(0, util_1.isStringArray)(nav);
+    let shouldWriteMkDocsYml = false;
+    let refFilepaths;
+    let nonRefFilepaths;
+    const refDictIdx = findRefDictIndex(nav);
+    if (refDictIdx >= 0) {
+        const refDict = nav[refDictIdx];
+        const refArray = refDict[referenceHeader];
+        [refFilepaths, nonRefFilepaths] = partitionRefArray(refArray);
+    }
+    else {
+        [refFilepaths, nonRefFilepaths] = partitionRefArray(nav);
+    }
+    const symmetricDiff = lodash_1.default.xor(newRefFilepaths, refFilepaths);
+    if (symmetricDiff.length) {
+        log.debug('Difference in old nav vs new: %O', symmetricDiff);
+        shouldWriteMkDocsYml = true;
+        if (navUsesHeaders) {
+            if (refDictIdx >= 0) {
+                const res = [...nonRefFilepaths, ...newRefFilepaths];
+                mkDocsYml.nav[refDictIdx][referenceHeader] = res;
+                log.debug('Replaced "%s" section with %O', referenceHeader, res);
+            }
+            else {
+                mkDocsYml.nav = [...nonRefFilepaths, { [referenceHeader]: newRefFilepaths }];
+                log.debug('Added "%s" section with %O', referenceHeader, newRefFilepaths);
+            }
+        }
+        else {
+            mkDocsYml.nav = [...nonRefFilepaths, ...newRefFilepaths];
+            log.debug('Replaced nav with %O', mkDocsYml.nav);
+        }
+    }
+    if (shouldWriteMkDocsYml) {
+        const yaml = (0, fs_1.stringifyYaml)(mkDocsYml);
+        log.debug(yaml);
+        await (0, fs_1.safeWriteFile)(mkDocsYmlPath, yaml, true);
+        log.success('Updated navigation for reference documents in %s', relMkDocsYmlPath);
+    }
+    else {
+        log.info('No changes to navigation for reference documents in %s', relMkDocsYmlPath);
+    }
+}
+exports.updateNav = updateNav;
+//# sourceMappingURL=nav.js.map

package/build/lib/nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.js","sourceRoot":"","sources":["../../lib/nav.ts"],"names":[],"mappings":"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"}

package/build/lib/scaffold.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Implementation of a generic "create and/or update some file" task
+ * @module
+ */
+import { NormalizedPackageJson } from 'read-pkg';
+import { JsonValue, JsonObject } from 'type-fest';
+/**
+ * Options for a task which are not the {@link ScaffoldTaskOptions base options}
+ */
+export declare type TaskSpecificOpts<Opts extends ScaffoldTaskOptions> = Omit<Opts, keyof ScaffoldTaskOptions>;
+/**
+ * A function which performs some scaffolding task.
+ *
+ * @see {@linkcode createScaffoldTask}
+ */
+export declare type ScaffoldTask<Opts extends ScaffoldTaskOptions, T extends JsonObject> = (opts: Opts) => Promise<ScaffoldTaskResult<T>>;
+/**
+ * Factory for a {@linkcode ScaffoldTask}.
+ *
+ * @param defaultFilename Default file to create
+ * @param defaultContent Default content to use
+ * @param description Description of task
+ * @param opts Options
+ * @returns A scaffold task
+ */
+export declare function createScaffoldTask<Opts extends ScaffoldTaskOptions, T extends JsonObject>(defaultFilename: string, defaultContent: T, description: string, { transform, deserialize, serialize, }?: CreateScaffoldTaskOptions<Opts, T>): ScaffoldTask<Opts, T>;
+/**
+ * Optional function which can be used to post-process the content of a file. Usually used to merge
+ * various options with existing content
+ */
+export declare type ScaffoldTaskTransformer<Opts extends ScaffoldTaskOptions, T extends JsonValue> = (content: Readonly<T>, opts: TaskSpecificOpts<Opts>, pkg: NormalizedPackageJson) => T;
+/**
+ * A function which deserializes a string into a JS value.
+ */
+export declare type ScaffoldTaskDeserializer<T> = (content: string) => T;
+/**
+ * A function which serializes a JS value into a string.
+ */
+export declare type ScaffoldTaskSerializer<T> = (content: T) => string;
+/**
+ * Options for {@linkcode createScaffoldTask}
+ */
+export interface CreateScaffoldTaskOptions<Opts extends ScaffoldTaskOptions, T extends JsonValue> {
+    /**
+     * Transformer function
+     */
+    transform?: ScaffoldTaskTransformer<Opts, T>;
+    /**
+     * Deserializer function
+     */
+    deserialize?: ScaffoldTaskDeserializer<T>;
+    /**
+     * Serializer function
+     */
+    serialize?: ScaffoldTaskSerializer<T>;
+}
+/**
+ * Base options for all scaffold tasks
+ */
+export interface ScaffoldTaskOptions {
+    /**
+     * Current working directory
+     */
+    cwd?: string;
+    /**
+     * Destination file
+     */
+    dest?: string;
+    /**
+     * If `true` will not write files
+     */
+    dryRun?: boolean;
+    /**
+     * If `true` will overwrite fields in `typedoc.json`
+     */
+    overwrite?: boolean;
+    /**
+     * Path to `package.json`
+     */
+    packageJson?: string;
+}
+/**
+ * The return value of a {@linkcode ScaffoldTask}
+ */
+export interface ScaffoldTaskResult<T> {
+    /**
+     * The content of whatever it wrote or would write
+     */
+    content: T;
+    /**
+     * The filepath of whatever it wrote or would write
+     */
+    path: string;
+}
+//# sourceMappingURL=scaffold.d.ts.map