@codiac.io/codiac-cli 1.2.209 → 1.2.211

package/lib/ops/LocalOps.js

@@ -0,0 +1,3122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalOps = void 0;
+const tslib_1 = require("tslib");
+// Node libs
+const path = require("path");
+const fs = require("fs");
+// Third-party libs
+const inversify_1 = require("inversify");
+const figlet = require("figlet");
+const rimraf = require("rimraf");
+const _ = require("lodash");
+const escapeStringRegexp = require("escape-string-regexp");
+const fse = require("fs-extra");
+// Ours
+const codiac_common_1 = require("@codiac.io/codiac-common");
+const IBetterLogger_1 = require("@codiac.io/codiac-common/IBetterLogger");
+const contracts_1 = require("@codiac.io/codiac-common/contracts");
+const codiac_ops_common_1 = require("@codiac.io/codiac-ops-common");
+const codiac_ops_common_2 = require("@codiac.io/codiac-ops-common");
+const codiac_ops_common_3 = require("@codiac.io/codiac-ops-common");
+const codiac_relay_contracts_1 = require("@codiac.io/codiac-relay-contracts");
+const codiac_relay_contracts_2 = require("@codiac.io/codiac-relay-contracts");
+// Used only by DX
+const branch_1 = require("./entities/branch");
+const cli_context_repo_1 = require("./data/cli-context-repo");
+const npm_config_repo_1 = require("./data/npm-config-repo");
+const dx_constants_1 = require("./dx-constants");
+const _1 = require(".");
+const workspace_versioner_1 = require("./workspace-versioner");
+let LocalOps = class LocalOps {
+    // constructor(private ioc: Container, public codiacVersion: string, private _projectRoot: string, private _cfgRepo: CliContextRepo, private ux: IUserInputProvider, private styler: IOutputStyler, private logger: IBetterLogger) {
+    //   this._cliExec = new CliExec(logger);
+    // }
+    constructor(ioc
+    // , @inject(CliEnviro) public cliEnviro: CliEnviro
+    // , @inject(ProjectEnviro) private projEnviro: ProjectEnviro
+    // , @inject(CliContextRepo) private _cfgRepo: CliContextRepo
+    // , @inject(INTERFACES_OPS.IUserInputProvider) private ux: IUserInputProvider
+    // , @inject(INTERFACES_OPS.IOutputStyler) private styler: IOutputStyler
+    // , @inject(CliExec) private _cliExec: CliExec
+    // , @inject(INTERFACES.IBetterLogger) private logger: IBetterLogger    
+    ) {
+        this.ioc = ioc;
+        this.APP_CONFIG_FILENAME = "app-config.json";
+        /** Array of built-in app config keys that are supported by the api framework. */
+        this.AVAIL_CONFIG_KEYS_FILENAME = "app-config-keys.json";
+    }
+    // ====================================================================
+    //  LAZY-LOADED PROPERTIES
+    // 
+    //  public _cliEnviro: CliEnviro | undefined;
+    //  private _projEnviro: ProjectEnviro | undefined;
+    //  private __cfgRepo: CliContextRepo | undefined;
+    //  private _ux: IUserInputProvider | undefined;
+    //  private _styler: IOutputStyler | undefined;
+    //  private __cliExec: CliExec | undefined;
+    //  private _logger: IBetterLogger | undefined;
+    // 
+    // --------------------------------------------------------------------
+    get _projectRoot() {
+        return this.projEnviro.projectRoot;
+    }
+    get cliEnviro() {
+        if (this._cliEnviro === undefined) {
+            this._cliEnviro = this.ioc.get(_1.CliEnviro);
+        }
+        return this._cliEnviro;
+    }
+    get projEnviro() {
+        if (this._projEnviro === undefined) {
+            this._projEnviro = this.ioc.get(_1.ProjectEnviro);
+        }
+        return this._projEnviro;
+    }
+    get _projCfgRepo() {
+        if (this.__projCfgRepo === undefined) {
+            this.__projCfgRepo = this.ioc.get(cli_context_repo_1.ProjectContextRepo);
+        }
+        return this.__projCfgRepo;
+    }
+    get _projCfg() {
+        if (this.__projCfg === undefined) {
+            this.__projCfg = this.ioc.get(codiac_relay_contracts_2.ProjectConfig);
+        }
+        return this.__projCfg;
+    }
+    get _projUserCfg() {
+        if (this.__projUserCfg === undefined) {
+            this.__projUserCfg = this.ioc.get(codiac_relay_contracts_1.ProjectUserConfig);
+        }
+        return this.__projUserCfg;
+    }
+    get cliConfig() {
+        if (this.__cliConfig === undefined) {
+            this.__cliConfig = this.ioc.get(_1.CliConfig);
+        }
+        return this.__cliConfig;
+    }
+    get ux() {
+        if (this._ux === undefined) {
+            this._ux = this.ioc.get(codiac_ops_common_1.INTERFACES_OPS.IUserInputProvider);
+        }
+        return this._ux;
+    }
+    get styler() {
+        if (this._styler === undefined) {
+            this._styler = this.ioc.get(codiac_ops_common_1.INTERFACES_OPS.IOutputStyler);
+        }
+        return this._styler;
+    }
+    get _cliExec() {
+        if (this.__cliExec === undefined) {
+            this.__cliExec = this.ioc.get(codiac_ops_common_2.CliExec);
+        }
+        return this.__cliExec;
+    }
+    get logger() {
+        if (this._logger === undefined) {
+            this._logger = this.ioc.get(codiac_common_1.INTERFACES.IBetterLogger);
+        }
+        return this._logger;
+    }
+    get _workspaceVersioner() {
+        if (this.__workspaceVersioner === undefined) {
+            this.__workspaceVersioner = this.ioc.get(workspace_versioner_1.WorkspaceVersioner);
+        }
+        return this.__workspaceVersioner;
+    }
+    // --------------------------------------------------------------------
+    //  END LAZY-LOADED PROPERTIES
+    // ====================================================================
+    /** Shows the ascii art product name and the version in the console */
+    renderTitleBlock() {
+        let title = figlet.textSync('Codiac', 'Slant'); // 'Graffiti')
+        let line = '-'.repeat(38);
+        this.logger.notice(this.styler.colorGood(line));
+        this.logger.notice(this.styler.hilite(title));
+        this.logger.notice(`Version ${this.cliEnviro.version} by Codiac LLC`);
+        this.logger.notice(this.styler.colorGood(line));
+    }
+    // /** 
+    //  * Ensures that the current user is logged in against a specific tenant subscription.
+    //  */
+    // public getContext(): void {
+    //   this.logger.debug('Acquiring context...')
+    //   // check to see that user is logged in
+    //   // if (cli.confirm('') tenant
+    // }
+    /**
+     * ***OBSOLETE!!! Use CliPathWalker.getProjectRoot() instead!!***
+     *
+     * Gets the Toyhauler project root folder
+     * that is in scope for the current working directory
+     * or the given folder.
+     * IMPORTANT: Throws by default when no Toyhauler config file exists up the parent folder chain.
+     * @param folder (optional, defaults to current working directory) The folder containing the thaul config file, or any folder underneath that one.
+     * @param errorWhenNotFound Setting to false will return an empty string if folder is not contained in a project root.
+     *
+     * @deprecated Use `CliPathWalker.getProjectRoot()` instead!
+     */
+    getConfigRoot(folder, errorWhenNotFound = true) {
+        return codiac_ops_common_3.CliPathWalker.getProjectRoot(folder, errorWhenNotFound);
+    }
+    // /** Deserializes the global Thaul CLI configuration file. */
+    // public readCliConfig(): CliConfig|undefined {
+    //   this.logger.debug(`Reading cli config from: ${path.join(this.cliConfigDir, CliConfig.FILENAME)}`);
+    //   let config = this.deserializeJsonFile<CliConfig>(path.join(this.cliConfigDir, CliConfig.FILENAME));
+    //   return config;
+    // }
+    // /** Serializes the global Thaul CLI configuration object. */
+    // public writeCliConfig(config: CliConfig): void {
+    //   this.serializeJsonFile(config, path.join(this.cliConfigDir, CliConfig.FILENAME));
+    // }
+    /** Deserializes the Toyhauler config file in scope for the current working directory.
+     * Throws if none is defined up the folder tree. */
+    readCodiacProjectConfig(folder) {
+        let root = folder ? codiac_ops_common_3.CliPathWalker.getProjectRoot(folder) : this._projectRoot; // TODO: consider just "path.join(this._projectRoot, folder)"
+        let targetFile = path.join(root, codiac_ops_common_3.OpsConstants.PROJECT_CONFIG_FILENAME);
+        let contents = fs.readFileSync(targetFile, { encoding: "utf-8" });
+        let raw = JSON.parse(contents); // this doesnt run the ctor.
+        let config = Object.assign(new codiac_relay_contracts_2.ProjectConfig(raw.name, raw.tenantCode, dx_constants_1.DxConstants.DEFAULT_INIT_CODE_VERSION), raw);
+        return config;
+    }
+    // /** Serializes the given config to its file.  Throws if the project root hasnt been initialized. */
+    // public updateToyHaulerProjectConfigFile(config: ProjectConfig): void {
+    //   let pathName = path.join(this._projectRoot, OpsConstants.PROJECT_CONFIG_FILENAME);
+    //   JsonUtils.serializeJsonFile(config, pathName);
+    // }
+    // /** News up a Toyhauler config object and serializes 
+    //  * to a file in the current working directory, 
+    //  * thus establishing it as a project root. */
+    // public writeNewToyhaulerProjectConfig(seed?: ProjectConfig): ProjectConfig {
+    //   let folder = process.cwd();
+    //   let projectName = Case.kebab(path.basename(folder));
+    //   let config = seed || new ProjectConfig(projectName, DxConstants.UNREGISTERED_TENANT_CODE);
+    //   let targetFile = path.join(folder, OpsConstants.PROJECT_CONFIG_FILENAME)
+    //   // try {
+    //   fs.writeFileSync(targetFile, JSON.stringify(config, undefined, '  '))
+    //   // } catch (err) {
+    //   //   this.log(`Error creating ${CONFIG_NAME}: ${err}`)
+    //   // }
+    //   return config;
+    // }
+    // /** Reads the user-specific project config file, if it exists.
+    //  * Otherwise returns a new empty instance. 
+    //  */
+    // public readProjectUserConfig(): ProjectUserConfig {
+    //   let projectRoot = this.getConfigRoot();
+    //   let userConfigFolder = path.join(projectRoot, OpsConstants.PROJECT_USER_CONFIG_FOLDER_NAME);
+    //   let sourceFile = path.join(userConfigFolder, OpsConstants.PROJECT_USER_CONFIG_FILENAME);
+    //   let config = new ProjectUserConfig();
+    //   if (fs.existsSync(sourceFile)) {
+    //     let contents = fs.readFileSync(sourceFile, { encoding: "utf-8"});
+    //     let raw = JSON.parse(contents);  // this doesnt run the ctor.
+    //     config = Object.assign(new ProjectUserConfig(), raw);
+    //   }
+    //   return config;
+    // }
+    // /** Serializes the given config to a file in the project user folder. */
+    // public writeProjectUserConfig(config?: ProjectUserConfig): void {
+    //   let projectRoot = this.getConfigRoot();
+    //   let userConfigFolder = path.join(projectRoot, OpsConstants.PROJECT_USER_CONFIG_FOLDER_NAME);
+    //   let targetFile = path.join(userConfigFolder, OpsConstants.PROJECT_USER_CONFIG_FILENAME);
+    //   // try {
+    //   if (!fs.existsSync(userConfigFolder)) {
+    //     fs.mkdirSync(userConfigFolder, { recursive: true })
+    //   }
+    //   fs.writeFileSync(targetFile, JSON.stringify(config, undefined, '  '))
+    //   // } catch (err) {
+    //   //   this.log(`Error creating ${CONFIG_NAME}: ${err}`)
+    //   // }
+    // }
+    npmSyncIdentitiesWithNpmrc(...identities) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let npmRepo = new npm_config_repo_1.NpmConfigRepo(this._projectRoot);
+                    // ------------------------------------------------------------------------------
+                    // 1) Write the identities to the user npmrc file as before
+                    // Gather up what was in the existing user config
+                    // stripped of any auth tokens or scope variables
+                    let userNpmrcRelPath = path.join(codiac_ops_common_3.OpsConstants.PROJECT_USER_CONFIG_FOLDER_NAME, dx_constants_1.DxConstants.NPM_PROJECT_USER_CONFIG_FILENAME);
+                    let userNpmrcAbsPath = path.join(this._projectRoot, userNpmrcRelPath);
+                    let existing = yield npmRepo.loadNpmrc(userNpmrcAbsPath);
+                    let userNpmrc = npmRepo.scrubRegistriesFrom(existing);
+                    for (let index in identities) {
+                        let identity = identities[index];
+                        let tokenSetting = `${identity.registryUrl}:_authToken`;
+                        let value = identity.token; // The proj user folder doesnt get checked in, so we're gonna keep the token in the file.  Otherwise, we'd use: `\${${identity.tokenName}}`
+                        let exists = (existing[tokenSetting]) ? true : false;
+                        // scope definition
+                        if (identity.scope) {
+                            userNpmrc[`${identity.scope}:always-auth`] = true;
+                            userNpmrc[`${identity.scope}:registry`] = identity.registryUrl;
+                            this.logger.detail(`Wrote ${identity.provider} scope definition [${identity.scope}] as [${identity.registryUrl}] to the .npmrc file for use during the image build.`);
+                        }
+                        // token reference
+                        userNpmrc[tokenSetting] = value;
+                        this.logger.detail(`${(exists) ? "Overwrote" : "Added"} ${identity.provider} token reference [${identity.tokenName}] to the .npmrc file for use during the image build.`);
+                    }
+                    npmRepo.saveNpmrc(userNpmrc, userNpmrcAbsPath);
+                    // ------------------------------------------------------------------------------
+                    // 2) Ensure that the project npmrc redirects the user config to our project user folder
+                    //    If the proj npmrc isnt redirecting the user level npmrc to live in our project-user folder, 
+                    //    then put it there and reconfigure for it.  Involves:  "./.npmrc", "$HOME/.npmrc", "./.codiac-user/.npmrc-user"
+                    //    via `npm config get userconfig`
+                    let projectNpmrcFullPathName = path.join(this._projectRoot, ".npmrc");
+                    let projNpmrc = yield npmRepo.loadNpmrc(projectNpmrcFullPathName);
+                    if (projNpmrc.userconfig != userNpmrcRelPath) {
+                        projNpmrc.userconfig = userNpmrcRelPath;
+                        projNpmrc = npmRepo.scrubRegistriesFrom(projNpmrc);
+                        npmRepo.saveNpmrc(projNpmrc, projectNpmrcFullPathName);
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Deserializes the npm package.json file in the given directory.
+     * Returns undefined if not found.
+     * Throws if no toyhauler project is defined up the folder tree.
+     * @param pkgRoot (Optional: defaults to the thaul project root) Fully qualified path to the folder containing the package.json file. */
+    readNpmPackageJson(pkgRoot, fileName = dx_constants_1.DxConstants.PACKAGE_JSON_FILENAME) {
+        let root = pkgRoot || this.getConfigRoot();
+        let targetFile = path.join(root, fileName);
+        if (fs.existsSync(targetFile)) {
+            this.logger.debug(`Found package json at: ${targetFile}`);
+            let contents = fs.readFileSync(targetFile, { encoding: "utf-8" });
+            let config = JSON.parse(contents);
+            return config;
+        }
+        else {
+            this.logger.debug(`No ${dx_constants_1.DxConstants.PACKAGE_JSON_FILENAME} found at: ${targetFile}.`);
+            return undefined;
+        }
+    }
+    /** Serializes the given object as the package.json for the project.
+     * @param config the npm package.json as an object in memory.
+     * @param projectRoot fully qualified target folder to write the package.json file (optional: defaults to the thaul project root)
+    */
+    writeNpmPackageJson(config, projectRoot) {
+        let root = projectRoot || this.getConfigRoot();
+        let targetFile = path.join(root, dx_constants_1.DxConstants.PACKAGE_JSON_FILENAME);
+        // try {
+        fs.writeFileSync(targetFile, JSON.stringify(config, undefined, '  '));
+        // } catch (err) {
+        //   this.log(`Error creating ${CONFIG_NAME}: ${err}`)
+        // }
+        return config;
+    }
+    /** Deletes the package.json file in the project root. */
+    deleteNpmPackageJson() {
+        this.deleteProjectFile(dx_constants_1.DxConstants.PACKAGE_JSON_FILENAME);
+    }
+    /** Deletes the package.json file in the project root. */
+    clearNpmNodeModulesFolder() {
+        this.clearProjectFolder(`${dx_constants_1.DxConstants.NODE_MODULES_DIR_NAME}/**/*`);
+    }
+    /** Retrieves a list of all production dependencies for the npm project with the given root folder.
+     * @param projectRoot The fully qualified pathg to the folder containing the package.json file.
+    */
+    getNpmDependencies(projectRoot) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let pj = yield this.readNpmPackageJson(projectRoot);
+                    let names = [];
+                    if (pj && pj.dependencies) {
+                        for (let key in pj.dependencies) {
+                            names.push(key);
+                        }
+                    }
+                    if (pj && pj.devDependencies) {
+                        for (let key in pj.devDependencies) {
+                            names.push(key);
+                        }
+                    }
+                    this.logger.debug(JSON.stringify(names));
+                    // COMMENTED OUT BECAUSE this fails when one of the dependencies is sourced
+                    // // Select from the list of dependencies
+                    // let cmd0 = "npm ls --depth 0 --json --prod"
+                    // let result0 = await this._cliExec.execAsync(cmd0, { cwd: projectRoot })
+                    // let doc = JSON.parse(result0.stdout);        
+                    // let names: string[] = [];
+                    // for (let dep in doc.dependencies) {
+                    //   // this.logger.debug(dep);
+                    //   names.push(dep);
+                    // }
+                    resolve(names);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Instantiates the tsconfig.json object from its file in the project root.
+     * NOTE: Returns undefined if no tsconfig.json is found.
+     * @param typescriptRoot (optional: defaults to main project root) Fully qualified path to the folder containing the typescript config file to load.
+    */
+    readTsConfig(typescriptRoot) {
+        let root = typescriptRoot || this._projectRoot;
+        let fullPathName = path.join(root, dx_constants_1.DxConstants.TSCONFIG_JSON_FILENAME);
+        this.logger.debug(`tsconfig.json:  ${fullPathName}`);
+        if (fs.existsSync(fullPathName)) {
+            return codiac_ops_common_3.JsonUtils.deserializeJsonFile(fullPathName, true);
+        }
+        else {
+            return undefined;
+        }
+    }
+    /** Retrieves the fully qualified local path to the root folder
+     * of the source control repository clone
+     * (aka: the folder into which the repo was originally cloned).
+     * Though it is best that this folder coincide with the toyhauler project root,
+     * there are cases where it may not, such as with submodules,
+     * or subfolders that contain their own typescript and npm configs.
+     * @param projectRoot Fully qualified local path to the root of the thaul project (aka: nearest upstream folder containing a .codiac.json) */
+    getRepoRoot(projectRoot) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let cmd = `git rev-parse --show-toplevel`;
+                    let result = yield this._cliExec.execAsync(cmd); //, { cwd: projectRoot })  // commented out bc we actually want it rel to the actual cwd.
+                    if (result.stderr) {
+                        throw new Error(result.stderr);
+                    }
+                    else if (!result.stdout) {
+                        throw new Error(`Git returned nothing when asked for the repo root.  idkwtf... ¯\\_(ツ)_/¯`);
+                    }
+                    let root = result.stdout.trim(); // that trim is IMPORTANT: the output has a trailing linebreak in it.  Removing it allows us to use path.relative() the way it was intended.
+                    resolve(root);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Deserializes the app config file if it exists
+     * @param relFolder The folder relative to the root to read from:
+     * eg: Either the project source folder "./src" or the build output folder "/bin".
+     */
+    loadConfig(relFolder = "./src") {
+        let root = this.getConfigRoot();
+        return codiac_ops_common_3.JsonUtils.deserializeJsonFile(path.join(root, relFolder, this.APP_CONFIG_FILENAME));
+    }
+    /** Serializes the app config object to a file. */
+    writeConfig(appConfig) {
+        codiac_ops_common_3.JsonUtils.serializeJsonFile(appConfig, `./src/${this.APP_CONFIG_FILENAME}`);
+    }
+    deleteConfigFile() {
+        this.deleteProjectFile(`/src/${this.APP_CONFIG_FILENAME}`);
+    }
+    /** Loads the list of names of the built in app-config settings
+     * supported by the framework
+     * (Reads from a json file in the cli executable folder). */
+    loadConfigKeys(
+    /** Path to the folder containing the CLI executable
+     * (from an oclif Command class, use "this.config.root"). */
+    execRoot) {
+        let sourceFile = path.join(execRoot, "assets", this.AVAIL_CONFIG_KEYS_FILENAME);
+        let array = codiac_ops_common_3.JsonUtils.deserializeJsonFile(sourceFile);
+        return array || [];
+    }
+    // /** Returns the instantiated object or array.  
+    //  * Returns undefined for both an empty or missing source file. 
+    //  * Uses JSON.parse and does not perform any explicit casting. Resolves tilde (~) path prefixes.
+    //  * @param pathName Fully qualified or relative path and filename of the json file.  
+    //  * If relative (ie: not starting with / or ~), it is interpreted as relative to the project root 
+    //  * (eg: "src/app-config.json").
+    //  * */
+    // deserializeJsonFile<T>(pathName: string, allowComments: boolean = false): T|undefined {
+    //   try {
+    //     let targetPathName = resolveHomeDir(pathName);
+    //     if (!path.isAbsolute(targetPathName)) { // Relative path (defaults relative to project root)
+    //       let root = this.getConfigRoot();
+    //       targetPathName = path.join(root, pathName);
+    //     }
+    //     if (fs.existsSync(targetPathName)) {
+    //       let json = fs.readFileSync(targetPathName, { encoding: 'utf-8'});
+    //       if (allowComments) {
+    //         let obj = commentJson.parse(json);
+    //         return obj;
+    //       } else {
+    //         let obj = JSON.parse(json);
+    //         return obj;
+    //       }
+    //     } else {
+    //       return undefined;
+    //     }
+    //   } catch (err) {
+    //     // throw err;
+    //     this.logger.debug(err);
+    //     return undefined;
+    //   }
+    // }
+    // /** Uses JSON.stringify() to write the given object to a file. Resolves tilde (~) path prefixes.
+    //  * @param subject The object to serialize.
+    //  * @param pathName Path and filename.  If relative (ie: not starting with / or ~), 
+    //  * it is interpreted as relative to the project root (eg: "src/app-config.json").
+    // */
+    // serializeJsonFile(subject: any, pathName: string): void {
+    //   let targetPathName = resolveHomeDir(pathName);
+    //   if (!path.isAbsolute(targetPathName)) { // Relative path (defaults relative to project root)
+    //     let root = this.getConfigRoot();
+    //     targetPathName = path.join(root, pathName);
+    //   }
+    //   if (!fs.existsSync(path.dirname(targetPathName))) {
+    //     fs.mkdirSync(path.dirname(targetPathName), { recursive: true });
+    //   }
+    //   fs.writeFileSync(targetPathName, JSON.stringify(subject, undefined, '  '))
+    // }
+    /** Synchronously deletes the given file.  Throws any exceptions.
+     * @param relPathName Path and filename of file relative to the project root
+     *  (eg: "src/app-config.json").
+    */
+    deleteProjectFile(relPathName) {
+        let root = this.getConfigRoot();
+        let targetFile = path.join(root, relPathName);
+        if (fs.existsSync(targetFile)) {
+            fs.unlinkSync(targetFile);
+            this.logger.debug(`Deleted file: [${targetFile}]`);
+        }
+    }
+    /** Synchronously deletes all contents of the given folder without deleting the folder itself.
+     * Throws any exceptions.
+     * @param relPathName Path of target folder relative to the project root
+     *  (eg: "src/my-outdated-stuff").
+    */
+    clearProjectFolder(relPathName) {
+        let root = this.getConfigRoot();
+        let targetFolder = path.join(root, relPathName);
+        if (fs.existsSync(targetFolder)) {
+            let targetSpec = (targetFolder.endsWith("*")) ? targetFolder : path.join(targetFolder, "**/*");
+            rimraf.sync(targetSpec, {});
+            this.logger.debug(`Deleted contents of folder: [${targetFolder}]`);
+        }
+    }
+    /** Reads the current version of the main project.
+     * Uses npm's package.json as the system of record for the version. */
+    npmGetCurrentVersion(pkgRoot) {
+        let pkgJson = this.readNpmPackageJson(pkgRoot);
+        // this.logger.debug("Current pkg version: " + pkgJson.version);
+        let thisVersion = pkgJson.version || dx_constants_1.DxConstants.DEFAULT_INIT_PACKAGE_VERSION;
+        // this.logger.debug("This version: " + thisVersion)
+        return thisVersion;
+    }
+    getCodeVersion(pkgRoot) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const cfg = yield this.readCodiacProjectConfig();
+            return cfg.codeVersion;
+        });
+    }
+    /** Loads the source code for the given repo as a git submodule of the project.
+     * DOES NOT interface with npm or any other tool - just git.
+     * @param packageName The official name of the project dependency whose repo is being submoduled (including any scope prefix, eg: "@codiac/").
+     * @param cloneUrl The url of the git repo that will be used to pull the source code.
+     * @param lastPkgVersion The version of its package that the project is currently depending on.
+     * @param nameOverride (optional: defaults to the repo name) The unique identifier for this submodule within the current project.
+     */
+    addSubmodule(cloneUrl, packageName, lastPkgVersion, nameOverride, branch) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let cfg = this.readCodiacProjectConfig();
+                    /*
+                    * NOTE:  Git doesnt like to let go of the remote for the submodule.
+                    * So, if you have changed the repository url for that submodule name,
+                    * Git will still clone from the previous repository.  (!!! wtf !!!)
+                    * Check it by comparing
+                    *    this output (run from the root folder of the submodule):  $ git remote -v
+                    *    to the value in the file:  ".gitmodules" in the root of the parent repo.
+                    * You will need to explicitly tell your local git to do two things:
+                    * 1) sync up with whatever repo url is written into the .gitmodules file,
+                    * 2) refresh from that remote.
+                    * Here's your commands to run on your submodule (eg: toyhauler-auth-contracts)
+                    * 1)  git submodule sync ./submodules/toyhauler-auth-contracts
+                    * 2)  git submodule update --remote ./submodules/toyhauler-auth-contracts
+                    *  ----THEN, you may need to do the following...
+                    * 3)  cd ./submodules/toyhauler-auth-contracts
+                    * 4)  git pull
+                    * 5)  [-- you may need to resolve merge conflicts --]
+                    * 6)  git add -A
+                    * 7)  git commit -m 'Detached stale remote and merged in latest from current remote.'
+                    * 8)  git push
+                    * That should get you the source code from the proper repo.
+                    * For more info see:   https://git-scm.com/docs/git-submodule
+                    * ALSO:  submodule update doesnt really work with SSH keys -
+                    * youll need to give it a url with a username that you have a password for...
+                    *   https://stackoverflow.com/questions/6031494/git-submodules-and-ssh-access
+                    * Alos, git may have something with a "prune" subcommand that helps remove this repo-to-origin cache.
+                    */
+                    // if a submodule already exists from that git repo, tell user to remove it first instead of overwriting it.
+                    if (_.find(cfg.submodules, { cloneUrl: cloneUrl })) {
+                        throw new Error("That repo is already submoduled in this project.");
+                    }
+                    // add the submodule
+                    let folderName = packageName; // nameOverride || fileBaseName(cloneUrl);
+                    let submodule = new codiac_relay_contracts_2.Submodule(cloneUrl, folderName);
+                    if (packageName)
+                        submodule.packageName = packageName;
+                    if (lastPkgVersion)
+                        submodule.lastUsedVersion = lastPkgVersion;
+                    if (branch) {
+                        submodule.branch = branch;
+                    }
+                    // NOTE:  We are being VERY PRECISE in case  projectRoot != repoRoot
+                    //        because Git sees paths rel to repoRoot, 
+                    //        whereas the thaul cli sees paths relative to projectRoot.
+                    let projectRoot = this.getConfigRoot();
+                    let repoRoot = yield this.getRepoRoot(projectRoot);
+                    // let projectPathInRepo = path.relative(repoRoot + "/", projectRoot + "/");  // why does this back out of the "from" directory?  wtf?
+                    let projectPathInRepo = projectRoot.slice(repoRoot.length);
+                    this.logger.debug("resolved: " + path.resolve(repoRoot, projectPathInRepo));
+                    this.logger.debug(`projectRoot: ${projectRoot}`);
+                    this.logger.debug(`repoRoot: ${repoRoot}`);
+                    this.logger.debug(`projectPathInRepo: ${projectPathInRepo}`);
+                    // We're gonna run this relative to the thaul project root (not the repo root)
+                    let targetFolder = path.posix.join(dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, folderName);
+                    // git might do this for us
+                    // let fqTargetFolder = path.posix.join(projectRoot, targetFolder);
+                    // if (!fs.existsSync(fqTargetFolder)) {
+                    //   fs.mkdirSync(fqTargetFolder, { recursive: true });
+                    // }
+                    let argBranch = (submodule.branch) ? ` -b ${submodule.branch}` : "";
+                    let cmd = `git submodule add ${argBranch} --force --name ${submodule.folderName} ${submodule.cloneUrl} ${targetFolder}`;
+                    this.logger.debug(`ABOUT TO: ${cmd}`);
+                    this.logger.debug(`FROM: cwd: ${process.cwd()} projectroot: ${projectRoot}`);
+                    // Ensure the submodules folder exists within the project
+                    // fs.mkdirSync(path.join(projectRoot, DxConstants.SUBMODULES_DIR_NAME));
+                    yield this._cliExec.execAsyncStdOut(cmd, { cwd: projectRoot });
+                    // Write the new submodule to the project context
+                    if (!cfg.submodules)
+                        cfg.submodules = [];
+                    cfg.submodules.push(submodule);
+                    yield this._projCfgRepo.updateProjectConfigFile(cfg);
+                    // commit the change 
+                    // NOTE:  these cmds run from the repo root cuz we're identifying items in the changeset.
+                    let cmd3a = `git update-index --again`; // we were moving too fast for git to see our changes.
+                    this.logger.debug(cmd3a);
+                    yield this._cliExec.execAsync(cmd3a, { cwd: projectRoot });
+                    let cmd3 = `git add ${codiac_ops_common_3.OpsConstants.PROJECT_CONFIG_FILENAME}`; // ${path.posix.join(projectPathInRepo, targetFolder)}`  apparently the submodule folder is already staged
+                    this.logger.debug(cmd3);
+                    yield this._cliExec.execAsync(cmd3, { cwd: projectRoot });
+                    let cmd4 = `git commit -m 'Added submodule: ${submodule.folderName}'`;
+                    this.logger.debug(cmd4);
+                    yield this._cliExec.execAsync(cmd4, { cwd: projectRoot });
+                    resolve(submodule);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Replaces the installed package of the dependency with the local submodule folder as the source of the code references.
+     * ie: allows the developer to debug the submoduled source code instead of the code that was installed from the package.
+     * NOTE:  There is no guarantee that the submodule code being linked
+     *        matches that of the installed dependency.
+     * @param submodule A valid dependency sourced into the project.
+     */
+    symLinkSubmodule(submodule) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let segments = [projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName];
+                    if (submodule.distributionRoot)
+                        segments.push(submodule.distributionRoot);
+                    let linkTargetFolder = path.posix.join(...segments);
+                    // WE'LL PROB NEED TO DO THIS (or perhaps even build)
+                    if (!fs.existsSync(linkTargetFolder)) {
+                        fs.mkdirSync(linkTargetFolder, { recursive: true });
+                    }
+                    // Copy the contents of the existing package folder in node_modules.
+                    // NOTE: In order for the source code to lilne up with the package, 
+                    //       the package needs to have a commit id in it somewhere.
+                    //       and we would need to ask for that commit Id on the addSubmodule() call.
+                    //       For now, we're just going to hope they line up and if not, 
+                    //       the user can pull the right commit on their own, or rebuild on their own 
+                    // Do we always do this?  Maybe only when there's no package.json in the dist folder, or when the dist folder is not the project root?
+                    // (they shouldnt have, but they MAY have included their dist folder contents in their repo - what then?  A: we just use what the repo has)
+                    if (submodule.distributionRoot && !fs.existsSync(path.posix.join(linkTargetFolder, "package.json"))) {
+                        let pkgInstallPath = path.posix.join(this._projectRoot, "node_modules", submodule.packageName);
+                        this.logger.debug(`Copying installed pkg contents into submodule distributionRoot: ${linkTargetFolder}`);
+                        // fse.copyFileSync(path.posix.join(pkgInstallPath, "**", "*.*"), linkTargetFolder);
+                        fse.copySync(pkgInstallPath, linkTargetFolder);
+                    }
+                    let distNodeModulesFolder = path.posix.join(linkTargetFolder, "node_modules");
+                    let removeNodeModules = !fs.existsSync(distNodeModulesFolder);
+                    // cd ./submodules/bidstreak-domain  
+                    // &&  npm link  
+                    yield this._cliExec.execAsyncStdOut(`npm link --no-save`, { cwd: linkTargetFolder });
+                    // &&  cd ../../  
+                    // &&  npm link @extradus/bidstreak-domain --no-save",
+                    yield this._cliExec.execAsyncStdOut(`npm link ${submodule.packageName} --no-save`, { cwd: projectRoot });
+                    if (removeNodeModules && fs.existsSync(distNodeModulesFolder)) {
+                        fse.removeSync(distNodeModulesFolder);
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Reverts a linked submodule reference back to the installed package dependency.
+     * @param name Unique identifier in this project for the submodule (typically the package name).
+     */
+    unSymLinkSubmodule(name) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let cfg = this.readCodiacProjectConfig();
+                    let subm = yield this.chooseSubmodule('remove', name, cfg);
+                    if (subm) {
+                        let projectRoot = this.getConfigRoot();
+                        let segments = [projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, subm.folderName];
+                        if (subm.distributionRoot)
+                            segments.push(subm.distributionRoot);
+                        let submoduleFolder = path.posix.join(...segments);
+                        // npm uninstall @extradus/bidstreak-domain --no-save  
+                        // &&  cd ./submodules/bidstreak-domain  
+                        // &&  npm uninstall  
+                        if (subm.packageName) {
+                            yield this._cliExec.execAsyncStdOut(`npm uninstall ${subm.packageName} --no-save`, { cwd: projectRoot });
+                            yield this._cliExec.execAsyncStdOut(`npm uninstall`, { cwd: submoduleFolder });
+                            // &&  cd ../../  
+                            // &&  npm install @extradus/bidstreak-domain@latest",
+                            if (subm.lastUsedVersion) {
+                                yield this._cliExec.execAsyncStdOut(`npm install ${subm.packageName}@${subm.lastUsedVersion}`, { cwd: projectRoot });
+                            }
+                        }
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /**  Fully exorcises a git submodule from the project.
+     * Returns the submodule object that was removed.
+     * NOTE:  Does NOT remove the project package dependency that corresponds to the submodule.
+     *
+     * @param name Unique identifier in this project for the submodule (typically the package name without any scope prefix).
+     * @param discardChanges Discards all uncommitted changes (staged and unstaged) before unsourcing, and goes back to the previously installed version of the dependency.  Again, uncomitted changes are LOST when this flag is set!
+     */
+    removeSubmodule(name, discardChanges = false) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let cfg = this.readCodiacProjectConfig();
+                    let subm = yield this.chooseSubmodule('remove', name, cfg);
+                    if (subm) {
+                        this.logger.debug(`Removing submodule: ${subm.folderName}...`);
+                        let projectRoot = this.getConfigRoot();
+                        let repoRoot = yield this.getRepoRoot(projectRoot);
+                        // let projectPathInRepo = path.relative(repoRoot + "/", projectRoot + "/");  // why does this back out of the "from" directory?  wtf?
+                        this.logger.debug("projectRoot: " + projectRoot);
+                        this.logger.debug("repoRoot: " + repoRoot);
+                        let projectPathInRepo = projectRoot.slice(repoRoot.length);
+                        let segments = [dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, subm.folderName];
+                        if (subm.distributionRoot)
+                            segments.push(subm.distributionRoot);
+                        let submodulePath = path.posix.join(...segments);
+                        // How do we check to see if it's sym linked? (it should always be, but we should allow for it to have been unlinked)
+                        yield this.unSymLinkSubmodule(subm.folderName);
+                        if (discardChanges) {
+                            // rollback any uncommitted changes
+                            yield this._cliExec.execAsync(`git reset --hard origin`, { cwd: submodulePath });
+                        } // else {
+                        // These need to be run within the context of the submodule folder
+                        // git see-if-they-have-changes
+                        // git add -A
+                        // git commit -m flags.commit || ""  // shall we prompt for this commit message?
+                        // 
+                        // publish:
+                        //   increment
+                        //   build
+                        //     tsc, npm, docker as reqd
+                        //   publish
+                        //     git push, npm, docker as reqd
+                        // }
+                        // Apparently you can use either of these methods, 
+                        // depending on how much you want git to remember.  
+                        // We want it to forget it ever knew anything about our submodule.
+                        // NOTE: It seems, however, that git still remembers the remote address 
+                        //       for the given submodule name, even after you remove it.
+                        //       See the big note in this file under addSubmodule().
+                        let typeOfRemove = "rm";
+                        if (typeOfRemove == "rm") {
+                            // this kills the submodule from the .gitmodules folder altogether
+                            let cmd2 = `git rm -f ${submodulePath}`; // what about this:   git rm --cached ${submodulePath}  (will this remove gits memory of it too?)
+                            this.logger.debug(cmd2);
+                            // HEY!!!  This fails if you do it after a deinit and gives us:
+                            //    git rm -f submodules/toyhauler-auth-contracts
+                            //    Error: ENOENT: no such file or directory, uv_cwd
+                            yield this._cliExec.execAsync(cmd2, { cwd: projectRoot });
+                        }
+                        else {
+                            // deinit the submodule
+                            let cmd = `git submodule deinit -f ${submodulePath}`;
+                            this.logger.debug(cmd);
+                            yield this._cliExec.execAsync(cmd, { cwd: projectRoot });
+                        }
+                        // update the project context file
+                        _.remove(cfg.submodules, { folderName: subm.folderName });
+                        yield this._projCfgRepo.updateProjectConfigFile(cfg);
+                        // COMMIT
+                        // NOTE:  these cmds run from the repo root cuz we're identifying items in the changeset.
+                        let cmd3a = `git update-index --again`; // we were moving too fast for git to see our changes.
+                        this.logger.debug(cmd3a);
+                        yield this._cliExec.execAsync(cmd3a, { cwd: projectRoot });
+                        // let cmd3 = `git add .gitmodules ${path.join(projectPathInRepo, OpsConstants.PROJECT_CONFIG_FILENAME)}`
+                        let cmd3 = `git add ${codiac_ops_common_3.OpsConstants.PROJECT_CONFIG_FILENAME}`;
+                        this.logger.debug(cmd3);
+                        yield this._cliExec.execAsync(cmd3, { cwd: projectRoot });
+                        let cmd4 = `git commit -m 'Removed submodule: ${subm.folderName}'`;
+                        this.logger.debug(cmd4);
+                        yield this._cliExec.execAsync(cmd4, { cwd: projectRoot });
+                        resolve(subm);
+                    }
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Returns a valid submodule object from the given name or prompts for one.
+     * Guarantees a valid submodule reference, an undefined, or throws an exception.
+     * NOTE: The user can also cancel the operation entirely (CTRL-C), which will exit the whole process itself.
+     * @param actionIntended The verb for the process for which the submodule is being selected.  (eg: 'remove' which will get used in user prompt as '...please select the dependency source to remove...')
+     * @param name Unique identifier in this project for the submodule (typically the package name).
+     * @param projectConfig The toyhauler settings for the current project.
+     */
+    chooseSubmodule(actionIntended, name, projectConfig) {
+        return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            try {
+                let cfg = projectConfig || this.readCodiacProjectConfig();
+                let subm = _.find(cfg.submodules, { folderName: name });
+                if (!subm) {
+                    this.ux.userMessage(`There is no dependency sourced as: ${name}.  Please select the dependency source to ${actionIntended}:`);
+                    let names = cfg.submodules.map(sm => sm.folderName);
+                    if (names && names.length > 0) {
+                        let selected = yield this.ux.promptSelect('name', `dependency source to ${actionIntended}: (ctrl-c to cancel)`, names);
+                        // let result = await inquirer.prompt({ type: 'list', name: 'name', message: `dependency source to ${actionIntended}: (ctrl-c to cancel)`, choices: names });
+                        if (!selected) {
+                            this.logger.debug("Operation cancelled by user.");
+                            // cli.exit(0);  // TODO:  Stop and emit a workflow status instead.  (This lib isnt necessarily being used by a TTY/console app)
+                        }
+                        else {
+                            subm = _.find(cfg.submodules, { folderName: selected });
+                        }
+                    }
+                    else {
+                        this.ux.userMessage(`Cancelled: no dependencies are currently sourced.`);
+                    }
+                }
+                resolve(subm);
+            }
+            catch (err) {
+                reject(err);
+            }
+        }));
+    }
+    /** npm sends its warnings down the stderr pipe rather than stdout,
+     * so we have to parse it to find out if it is indeed an error.
+     * Fortunately they prefix them with "npm WARN" or "npm ERR!".
+     */
+    npmStdErrIsJustAWarning(stderr) {
+        let errs = stderr.split("\n");
+        if (errs.find(e => e.startsWith("npm ERR!"))) {
+            return false;
+        }
+        else {
+            return true;
+        }
+    }
+    buildVersionTag(mainVersionNumber, workingFolder) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let branch = yield this.gitCurrentBranchFor(workingFolder);
+                    let buildNumber = codiac_common_1.BuildNumberGenerator.getOne();
+                    let seatCode = "fakeseatcode"; // TODO: Get the seatcode or user info
+                    let tag = `${mainVersionNumber}-${branch}.${buildNumber}.${seatCode}`;
+                    resolve(tag);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Creates and publishes to the npm registry any configured npm packages
+     * for the main project and its sourced dependencies.
+     * NOTE:  Determines whether to publish based on the occurrence of commits since the last package date.
+     * @param force Publishes regardless of whether package contents have changed or not.
+     * */
+    npmPublish(force = false) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let cfg = yield this.readCodiacProjectConfig();
+                    let pj = yield this.readNpmPackageJson();
+                    let tag = yield this.buildVersionTag(pj.version, projectRoot);
+                    let skipReason;
+                    let tagArg = `--tag ${tag}`;
+                    let distFolderArg = "dist"; // TODO:  Consider making distFolder configurable.
+                    let cmd = `npm publish ${distFolderArg} ${tagArg}`;
+                    // SOURCED DEPENDENCIES
+                    // Publish any all sourced dependencies  (only if needed)
+                    for (let index in cfg.submodules) {
+                        let submodule = cfg.submodules[index];
+                        let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                        if (yield this.npmIsPublishable(submoduleFolder, submodule.packageName, tag)) {
+                            // let changes = await this.gitChangesSince(subModuleFolder, submodule.packagedDateUtc);
+                            let changes = { commits: [{ hash: "123" }], stages: [{ filename: "hello.ts" }] };
+                            let isChanged = (changes && (changes.commits.length > 0 || changes.stages.length > 0));
+                            if (force || isChanged) {
+                                this.logger.debug(`pretending to execute the command: "${cmd}" from folder: ${submoduleFolder}`);
+                                // let outputDep = await this._cliExec.execAsyncStdOut(cmd, { cwd: submoduleFolder });
+                                // DO we want to install this into the main?  Im assuming we do...
+                            }
+                        }
+                        else {
+                            // gated; skip it
+                        }
+                    }
+                    // MAIN PROJECT
+                    if (yield this.npmIsPublishable(projectRoot, pj.name, tag)) {
+                        this.logger.debug(`pretending to execute the command: "${cmd}" from folder: ${projectRoot}`);
+                        // let output = await this._cliExec.execAsyncStdOut(cmd, { cwd: projectRoot });
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Determines whether the given npm module has changes
+     *  that require the package to be rebuilt.
+     *  Used to gate the publish of a package to avoid unnecessary processing. */
+    npmIsPublishable(workingFolder, fullPackageName, version) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let isPublishable;
+                    let reason;
+                    // 0)  Validate that the registry itself exists and we can authenticate
+                    //     For more info see:  https://docs.npmjs.com/cli/ping.html
+                    // TODO:  Add support for alternate package registries
+                    // let pingCmd = `npm ping --registry ${registryUrl}`
+                    // try {
+                    //   let pingResult = await this._cliExec.execAsyncStdOut(pingCmd, { cwd: workingFolder });
+                    //   isPublishable = true;
+                    // } catch (err) {
+                    //   reason = `The package registry eiher does not exist or you are not authenticated.`
+                    //   isPublishable = false;  
+                    // }
+                    // 1) if this version has already been published 
+                    // (lets do this some other time - it's practically impossible now that the tag has a build number in it)
+                    isPublishable = yield this.hasYetToBePublished(fullPackageName, version, workingFolder);
+                    if (!isPublishable) {
+                        reason = `The package ${fullPackageName} version ${version} has already been published.`;
+                    }
+                    else {
+                        // 2) if there are uncommitted changes
+                        let uncommittedChanges = yield this.gitHasChanges(workingFolder);
+                        if (uncommittedChanges) {
+                            isPublishable = false;
+                            reason = `Cannot publish with uncommitted changes.  Undo or commit them to source control and try again.`;
+                        }
+                        else {
+                            // 3) if no commits have been made since the last creation of the package on this branch
+                            //    (npm pack and publish are the same UNLESS we decide to go local)
+                            let branch = yield this.gitCurrentBranchFor(workingFolder);
+                            let findCommand = `npm view ${fullPackageName}@'like ${version}-${branch}.*' --json time`;
+                            let lastPublish = new Date("12/19/2019 18:00 -0600");
+                            let logcmd = `git log --since "${lastPublish}" --format=oneline`;
+                            let commits = yield this._cliExec.execAsyncStdOut(logcmd, { cwd: workingFolder });
+                            if (!commits) {
+                                isPublishable = false;
+                                reason = `No source code has been committed since the last publish.`;
+                            }
+                        }
+                    }
+                    if (!isPublishable)
+                        this.logger.debug(`Module should not be published: ${reason}`);
+                    resolve(isPublishable);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Installs any missing dependency packages. */
+    dependencyInstallAll() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let cmd = `npm install`;
+                    let result = yield this._cliExec.execAsync(cmd, { cwd: projectRoot });
+                    if (result.stderr) {
+                        if (this.npmStdErrIsJustAWarning(result.stderr)) {
+                            this.logger.debug(`Warnings found: \n${result.stderr}`);
+                        }
+                        else {
+                            throw new Error(`Error attempting to install missing dependency packages: ${result.stderr}`);
+                        }
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    dependencyInstall(name, version) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let cmd = `npm install --save-prod ${name}`;
+                    if (version) {
+                        cmd = cmd.concat(`@${version}`);
+                    }
+                    let result = yield this._cliExec.execAsync(cmd, { cwd: projectRoot });
+                    if (result.stderr) {
+                        if (this.npmStdErrIsJustAWarning(result.stderr)) {
+                            this.logger.debug(`Warnings found: \n${result.stderr}`);
+                        }
+                        else {
+                            throw new Error(`Error attempting to install npm package [${name}]: ${result.stderr}`);
+                        }
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /**
+     * Sources a new dependency into the project
+     * from an existing repo url,
+     * initializes it with npm if it is not already,
+     * publishes the npm package if it does not already exist,
+     * and sources the dependency.
+     * Uses the version currently specified in its package.json
+     * for the dependency reference in this project.
+     *
+     * @param cloneUrl The official clone url for the repository.
+     * @param branch The source code branch to switch the dependency to.
+     * @param packageName (Optional: defaults to the repo name) The globally unique name to use for the npm package if initializing npm, including any scope prefix, eg: "@codiac/").
+     * @param initVersion (Optional: defaults to the built in initial version number 0.0.0-1) The version number to use if initializing npm for the dependency.
+     */
+    dependencyAuthorNew(cloneUrl, packageName, branch, initVersion) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                let submoduled = false;
+                let folderName = packageName;
+                try {
+                    // if (!folderName) folderName = fileBaseName(cloneUrl);
+                    // 1) Submodule it with source control
+                    let subm = yield this.addSubmodule(cloneUrl, packageName, undefined, undefined, branch); // TODO: consider switching to branch inside this fxn
+                    submoduled = true;
+                    let projectRoot = this.getConfigRoot();
+                    let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, subm.folderName);
+                    let execOptions = { cwd: `${submoduleFolder}` };
+                    // 3) Ensure the packager is initialized in the submodule project.
+                    let pj = yield this.readNpmPackageJson(submoduleFolder);
+                    if (pj == undefined) {
+                        // Prompt the user for a scope and package name
+                        // try to validate that the name doesnt exist, 
+                        // but beware that instead of incurring a 403 or 401 or some kind of authorization failure, 
+                        // private pkgs will appear as "does not exist" 
+                        // but will throw errors if you attempt to author packages with that name.  
+                        // (Thanks, NPM)
+                        this.logger.debug(`This dependency needs to be initialized for packaging.`);
+                        let entered = yield this.ux.prompt("scope", "Package scope prefix (enter for none): ", false, "");
+                        let scope = entered || "";
+                        if (!scope.startsWith("@"))
+                            scope = `@${scope}`;
+                        let pkgName = yield this.ux.prompt("pkgName", "Package name: ", true, subm.folderName);
+                        subm.packageName = `${scope}/${pkgName}`;
+                        subm.lastUsedVersion = initVersion || dx_constants_1.DxConstants.DEFAULT_INIT_PACKAGE_VERSION;
+                        // Havent figured out how to wire up stdin on an execAsync call yet.
+                        // await this.execAndCommit([ `npm init` ], `npm initialization of ${name}`, submoduleFolder);
+                        // await this.execAndCommit([ `npm init -y` ], `npm initialization of ${name}`, submoduleFolder);
+                        yield this._cliExec.execAsyncStdOut(`npm init -y`, { cwd: submoduleFolder });
+                        // This (below) is one way to do it, 
+                        // though npm tags the git branch with the version number,
+                        // which can cause problems if npm and git get out of sync 
+                        // from this thaul command failing or being run a few times.
+                        // await this.execAndCommit([ `npm version ${version} --allow-same-version` ], `set initial npm version to ${version}`, submoduleFolder);
+                        pj = yield this.readNpmPackageJson(submoduleFolder);
+                        pj.name = subm.packageName;
+                        pj.version = subm.lastUsedVersion;
+                        pj.repository = { type: "git", url: subm.cloneUrl }; // we'll need this in order to source it.
+                        yield this.writeNpmPackageJson(pj, submoduleFolder);
+                        let cfg = yield this.readCodiacProjectConfig();
+                        let index = _.findIndex(cfg.submodules, sm => sm.folderName == subm.folderName);
+                        cfg.submodules[index] = subm;
+                        yield this._projCfgRepo.updateProjectConfigFile(cfg);
+                    }
+                    this.logger.debug("package.json: " + JSON.stringify(pj));
+                    // 3a) Should the main (parent) project commit a ref the latest commmit of the dependency (if there are any)?
+                    // 4) Perform the initial publish if reqd
+                    if (yield this.hasYetToBePublished(pj.name, pj.version, submoduleFolder)) {
+                        yield this._cliExec.execAsyncStdOut(`npm publish`, execOptions);
+                        // this might create a package-lock.json that needs to be committed
+                        yield this._cliExec.execAsyncStdOut(`npm view ${pj.name}@${pj.version}`, execOptions);
+                    }
+                    else {
+                        this.logger.debug(`The package ${pj.name}@${pj.version} has already been previously published; it will be used as the dependency.`);
+                    }
+                    // 5) Add the submodule as a dependency of the main project
+                    yield this.dependencyInstall(pj.name, pj.version);
+                    // 6) Reference its source code directly instead of its installed package. 
+                    //    Q: Does it matter if we npm link before or after we add it as a dependency?
+                    yield this.symLinkSubmodule(subm);
+                    // 7) If all is successful, push the changes to the remote source control repo.
+                    // cmd = `git push`;
+                    // this.logger.debug(`Executing: ${cmd}`);
+                    // await this._cliExec.execAsync(cmd, execOptions);
+                    resolve();
+                }
+                catch (err) {
+                    this.logger.debug(err);
+                    if (submoduled && folderName) {
+                        yield this.removeSubmodule(folderName, true);
+                    }
+                    reject(err);
+                }
+            }));
+        });
+    }
+    dependencyUpgrade(dep, version) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    // Verify that the dep exists
+                    let pj = yield this.readNpmPackageJson();
+                    if ((!pj.dependencies || !pj.dependencies[dep]) && (!pj.devDependencies || !pj.devDependencies[dep])) {
+                        throw new Error(`Cannot upgrade [${dep}]: it is not currently a dependency in this project.`);
+                    }
+                    let targetFolder = path.resolve(projectRoot, `./node_modules/`, dep);
+                    if (fs.existsSync(targetFolder)) {
+                        this.logger.debug(`Clearing target folder: ${targetFolder}`);
+                        rimraf.sync(path.join(targetFolder, "**/*"), {});
+                    }
+                    else {
+                        this.logger.debug(`No pre-install-removal to do: npm target folder doesnt exist: ${targetFolder}`);
+                    }
+                    // let cmd = `npm upgrade ${dep}`;
+                    let cmd = `npm install ${dep}@latest`;
+                    if (version) {
+                        cmd = `npm install ${dep}@${version}`;
+                    }
+                    yield this._cliExec.spawnAndLog(cmd, projectRoot);
+                    // let output = await this._cliExec.execAsyncStdOut(cmd, { cwd: projectRoot });
+                    // if (output) this.logger.debug(output);
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Forces local source control to refresh its status
+     * and returns true when uncommitted changes exist
+     * on the local machine (staged AND unstaged)
+     * for the git repo corresponding to the given working directory.
+     * @param workingDirectory The fully qualified path in which to run the git status command.
+     */
+    gitHasChanges(workingDirectory) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    // we were moving too fast for git to see our changes.
+                    let cmdRefresh = `git update-index --again`;
+                    yield this._cliExec.execAsyncStdOut(cmdRefresh, { cwd: workingDirectory });
+                    // let cmd = `git diff --stat`  // returns empty string when no changes exist
+                    let cmd = `git status --short`; // returns empty string when no changes exist
+                    let changes = yield this._cliExec.execAsyncStdOut(cmd, { cwd: workingDirectory });
+                    let isDirty = (changes != undefined && changes != "");
+                    resolve(isDirty);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Returns a distinct list of branch names (without any prefixes such as "remotes/origin/").
+     * @param remotes (optional: defaults to false) Flag to include remote branches.
+     * @param locals (optional: defaults to true) Flag to include local branches.
+     * @param repoRoot (optional: defaults to toyhauler project root) root folder of the repo being queried (used as the working folder for the git commands).
+     */
+    gitListBranches(remotes = false, locals = true, repoRoot) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let workingFolder = repoRoot || this.getConfigRoot();
+                    let branches = [];
+                    let remotesArg = "";
+                    if (remotes) {
+                        remotesArg = (locals) ? "--all" : "--remotes";
+                    }
+                    // Ensures an up-to-date listing of the remotes 
+                    // (otherwise we only see what was there on our last pull)
+                    let cmdRefresh = `git remote update origin --prune`;
+                    yield this._cliExec.execAsyncStdOut(cmdRefresh, { cwd: workingFolder });
+                    let cmd = `git branch --list ${remotesArg}`;
+                    let output = yield this._cliExec.execAsyncStdOut(cmd, { cwd: workingFolder });
+                    branches = output.trim().split("\n")
+                        .map(x => x.trim())
+                        .map(x => x.startsWith("* ") ? x.substr(2) : x) // git prefixes the current branch with "* "
+                        .map(x => x.substring(x.lastIndexOf("/") + 1))
+                        .sort();
+                    branches = _.sortedUniq(branches);
+                    this.logger.trace("branches:");
+                    this.logger.trace(branches.join("\n"));
+                    resolve(branches);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Returns a distinct list of branch names (without any prefixes such as "remotes/origin/").
+     * @param branchName duh.
+     * @param remotes (optional: defaults to false) Flag to include remote branches.
+     * @param locals (optional: defaults to true) Flag to include local branches.
+     * @param repoRoot (optional: defaults to toyhauler project root) root folder of the repo being queried (used as the working directory for the git commands).
+     */
+    gitBranchExists(branchName, remotes = false, locals = true, repoRoot) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let branches = yield this.gitListBranches(remotes, locals, repoRoot);
+                    let exists = branches.includes(branchName);
+                    resolve(exists);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Switches the main project and any sourced dependencies to the given source code branch.
+     * @param branchName duh.
+     * @param autoCreate (optional: defaults to true) Turn this off to prevent creation of the branch in the sourced dependencies (if missing).  CAUTION: This will lead to sourced dependencies on different branches than the main project.
+     * @param track (Optional: defaults to false) If autoCreate is set and branches are created, creates a matching upstream branch at origin.
+    */
+    gitSwitchToBranch(branchName, autoCreate = true, track = false) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let cfg = yield this.readCodiacProjectConfig();
+                    if (yield !this.gitBranchExists(branchName, true, true)) {
+                        if (autoCreate) {
+                            yield this.gitCreateBranch(branchName, track);
+                        }
+                        else {
+                            throw new Error(`Cannot switch to branch [${branchName}]: it does not exist.`);
+                        }
+                    }
+                    this.logger.debug(`Switching to branch [${branchName}] in main project [${cfg.name}]...`);
+                    let cmd = `git checkout ${branchName}`;
+                    let output = yield this._cliExec.execAsync(cmd, { cwd: projectRoot });
+                    // create and switch to branch in each sourced dependency...
+                    // We just switched branches, so we need to reload the config, 
+                    // since this branch mau have diff sourced dependencies.
+                    cfg = yield this.readCodiacProjectConfig();
+                    for (let index in cfg.submodules) {
+                        let submodule = cfg.submodules[index];
+                        let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                        let exists = yield this.gitBranchExists(branchName, true, true, submoduleFolder);
+                        let doit = exists;
+                        if (!exists && autoCreate) {
+                            yield this.gitCreateBranch(branchName, track, submoduleFolder);
+                        }
+                        if (doit) {
+                            this.logger.debug(`Switching to branch [${branchName}] in sourced dependency: ${submodule.folderName}`);
+                            let outputsub = yield this._cliExec.execAsyncStdOut(cmd, { cwd: submoduleFolder });
+                        }
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Creates a new branch in repo rooted in the the given folder.  DOES NOT SWITCH TO IT.
+     * @param branchName duh.
+     * @param track (Optional: defaults to false) Creates a matching upstream branch at origin.
+     * @param repoRoot (optional: defaults to toyhauler project root) root folder of the repo being queried (used as the working directory for the git commands).
+    */
+    gitCreateBranch(branchName, track = false, repoRoot) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let workingFolder = repoRoot || this.getConfigRoot();
+                    let trackFlag = (track) ? " --track" : "";
+                    let cmd = `git branch ${trackFlag} ${branchName}`;
+                    this.logger.debug(`Creating branch [${branchName}] in ${workingFolder}`);
+                    let output = yield this._cliExec.execAsyncStdOut(cmd, { cwd: workingFolder });
+                    if (output)
+                        this.logger.debug(output);
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Returns the current branch for the main proiject and any currently sourced dependencies. */
+    gitEachCurrentBranch() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let currentBranch = yield this.gitCurrentBranchFor(projectRoot);
+                    let cfg = yield this.readCodiacProjectConfig();
+                    let output = {};
+                    output[cfg.name] = currentBranch;
+                    for (let index in cfg.submodules) {
+                        let submodule = cfg.submodules[index];
+                        let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                        let submoduleBranch = yield this.gitCurrentBranchFor(submoduleFolder);
+                        output[submodule.packageName] = submoduleBranch;
+                    }
+                    resolve(output);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Retrieves just the abbreviated name of the current branch. */
+    gitCurrentBranchNameFor(workingFolder) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    // This one will return the branch name without the "refs/heads/" prefix...
+                    let cmd = "git rev-parse --abbrev-ref HEAD";
+                    let branch = yield this._cliExec.execAsyncStdOut(cmd, { cwd: workingFolder });
+                    resolve(branch);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Retrieves the current branch for the given folder.
+     *  (Cuz git somehow makes that nontrivial).
+     * @param workingFolder The folder from which to run the git command.  */
+    gitCurrentBranchFor(workingFolder) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    // COMMENTED OUT: we wanted a branch instance with more info on it. 
+                    // cuz 'git branch' returns a list of all local branches with an asterisk preceding the current one.
+                    // let magicalGitIncantation = `git branch | grep \\* | cut -d ' ' -f2-`;
+                    // return this._cliExec.execAsyncStdOut(magicalGitIncantation, { cwd: workingFolder});
+                    // from:  https://stackoverflow.com/questions/6245570/how-to-get-the-current-branch-name-in-git
+                    // // NOTE:  
+                    // // Using the --show-current argument ensures results despite there being no commits in the current tree.
+                    // // BUT WE CANT USE IT BC: --show-current requires git > 2.22
+                    // let formatArg = `--format "%(refname)|%(upstream)|%(if)%(HEAD)%(then)true%(else)false%(end)"`
+                    // let cmd = `git branch --show-current ${formatArg}`
+                    // let joined = await this._cliExec.execAsyncStdOut(cmd, { cwd: workingFolder });
+                    // let lines = joined.split("\n").filter(s => s.endsWith('|true'));
+                    // let split = lines[0].split('|');
+                    // this.logger.trace('split: ', split);
+                    // let branch = new Branch(split[0], split[2] == "true");
+                    // if (split[1] != "") branch.upstream = split[1];
+                    // So we can use "git symbolic-ref HEAD", which works in both cases (with and without any commits / detached ahead state)
+                    // this will; return a fully qaulified branch name, eg: "refs/heads/master", which we will nbeed to parse.
+                    let cmd = `git symbolic-ref HEAD`;
+                    let fullyQualified = yield this._cliExec.execAsyncStdOut(cmd, { cwd: workingFolder })
+                        .catch((error) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                        // BYG: Added this for CI support inside an agent.  git symbolic-ref HEAD throw even with it checked out.  Somehow the way the branch is detached doesnt allow that call to resolve.
+                        this.logger.warn(`Cannot use 'git symbolic-ref HEAD' /n ${JSON.stringify(error, undefined, 2)}`);
+                        let formatArg = `--format "%(refname)|%(upstream)|%(if)%(HEAD)%(then)true%(else)false%(end)"`;
+                        let cmd = `git branch --show-current`; //${formatArg}
+                        let branchName = yield this._cliExec.execAsyncStdOut(cmd, { cwd: workingFolder })
+                            .catch(error => {
+                            throw new contracts_1.CodiacError(`Cannot find the current branch name /n ${JSON.stringify(error, undefined, 2)}`);
+                        });
+                        return branchName;
+                    }));
+                    let name = fullyQualified.split("/").reverse()[0];
+                    let branch = new branch_1.Branch(name, true);
+                    resolve(branch);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Merges the given branch with the current one
+     * for the main project and all sourced dependencies.
+     * @param branchName The branch to merge into the current one.
+     * @param commit Commits if merge succeeds.  */
+    gitMerge(branchName, commit = false) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let currentBranch = yield this.gitCurrentBranchFor(projectRoot);
+                    let commitArg = (commit) ? "--commit" : "--no-commit";
+                    let cmd = `git merge ${commitArg} ${branchName}`;
+                    if (branchName != currentBranch.name) {
+                        let output = yield this._cliExec.execAsyncStdOut(cmd, { cwd: projectRoot });
+                        if (output)
+                            this.logger.debug(output);
+                    }
+                    else {
+                        this.logger.debug(`Operation cancelled: you attempted to merge branch ${branchName} into itself on the main project.  No work was done on the main project.`);
+                    }
+                    let cfg = yield this.readCodiacProjectConfig();
+                    for (let index in cfg.submodules) {
+                        let submodule = cfg.submodules[index];
+                        let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                        let submoduleBranch = yield this.gitCurrentBranchFor(submoduleFolder);
+                        if (branchName != submoduleBranch.name) {
+                            // 1) check if the branch to merge from even exists for this submodule
+                            // 2) run the merge (take default comments) 
+                            this.logger.debug(`Merging dependency branch ${branchName} into the ${submoduleBranch} branch of ${submodule.folderName}...`);
+                            this.logger.debug(`STUBBED: Not trying this on deps yet:  ${cmd}`);
+                            // let output = await this._cliExec.execAsyncStdOut(cmdsub, { cwd: submoduleFolder });
+                            // if (output) this.logger.debug(output);
+                        }
+                        else {
+                            this.logger.debug(`Operation cancelled: you attempted to merge branch ${branchName} into itself for ${submodule.folderName}.  No work was done on this sourced dependency.`);
+                        }
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Syncs the current branch with the given branch by merging the given branch into it.  */
+    gitSyncWith(branchToPullFrom, includeDependencies = false, targetDependency) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projRoot = this.getConfigRoot();
+                    let repoRoot = yield this.getRepoRoot(projRoot);
+                    let origBranch = yield this.gitCurrentBranchNameFor(projRoot);
+                    let exists = yield this.gitBranchExists(branchToPullFrom, true, true, repoRoot);
+                    if (exists) {
+                        yield this.gitSwitchToBranch(branchToPullFrom, false);
+                        yield this.gitPull();
+                        yield this.gitSwitchToBranch(origBranch, false);
+                        yield this.gitMerge(branchToPullFrom, true);
+                        this.logger.debug(`Synced with latest from ${branchToPullFrom}`);
+                    }
+                    else {
+                        // TODO: this lib may be used outside of a console, so emit a workflow status OR throw new Error(`Branch: ${branchToPullFrom} does not exist.`)
+                        this.logger.error(`Branch: ${branchToPullFrom} does not exist.`);
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Lists uncommitted changed files (staged, unstaged, or both).
+     * All paths are relative to the main project root.
+     * (if both staged and unstaged are ignored, then both are returned)
+     * @param unstaged Include unstaged files.
+     * @param staged Include staged files.
+     * @param repoRoot (optional: defaults to main project root) fully qualified path to the root folder of the cloned repo.
+     */
+    gitListChanges(status, repoRoot) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let workingFolder = repoRoot || projectRoot;
+                    // ---------------------------------------------------------
+                    // It'd be nice if this approach covered it, 
+                    // but git diff can't include newly added files (untracked) 
+                    // cuz they have no history.
+                    // 
+                    // let filterArg: string;
+                    // if ((staged && unstaged)  ||  (staged == unstaged == undefined)) {
+                    //   filterArg = "HEAD"  // includes both staged and unstaged
+                    // } else if (staged) {
+                    //   filterArg = "--staged"  // staged only
+                    // } else {
+                    //   filterArg = ""  // unstaged only
+                    // }
+                    // let cmd = `git diff --name-only ${filterArg}`
+                    // let result = await this._cliExec.execAsyncStdOut(cmd, { cwd: workingFolder });
+                    // let output = (result) ? result.split("\n") : [];
+                    // 
+                    // ...and it seems git status needs us to do our own filtering of its output, 
+                    //    so we're left with the following:
+                    // ---------------------------------------------------------
+                    let cmd = `git status --porcelain=1`; // porcelain is a parseable format that git has committed to keeping backward compatible.
+                    let result = yield this._cliExec.execAsyncStdOut(cmd, { cwd: workingFolder });
+                    let output = (result) ? result.split("\n") : [];
+                    // Now parse the git status porcelain output  
+                    // (character 0 is the staged status, character 1 is unstaged status, character 2 is a space)
+                    switch (status) {
+                        case "staged":
+                            output = output.filter(line => (line.charAt(0) != " ") && (line.charAt(0) != "?"));
+                            break;
+                        case "unstaged":
+                            output = output.filter(line => line.charAt(1) != ' ');
+                            break;
+                    }
+                    output = output.map(x => x.slice(3));
+                    // Recurse sourced dependencies
+                    // (only if the caller asked for the main project)
+                    if (workingFolder == projectRoot) {
+                        let cfg = this.readCodiacProjectConfig();
+                        let repoRoot = yield this.getRepoRoot(projectRoot);
+                        for (let index in cfg.submodules) {
+                            let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, cfg.submodules[index].folderName);
+                            let changes = yield this.gitListChanges(status, submoduleFolder);
+                            let pathPrefix = path.relative(repoRoot, submoduleFolder);
+                            output = output.concat(changes.map(f => path.join(pathPrefix, f)));
+                        }
+                    }
+                    output = output.sort();
+                    resolve(output);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Stages the given files for a commit.
+     * @param files (optional: defaults to "all") the space-delimited list of files to stage
+     */
+    gitStage(files) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return this.gitPerformStaging("stage", files);
+        });
+    }
+    /** Removes the given files from the git commit index.
+     * @param files (optional: defaults to "all") the space-delimited list of files to stage
+     */
+    gitUnstage(files) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return this.gitPerformStaging("unstage", files);
+        });
+    }
+    /** Stages or unstages the given files for/from a commit.
+     * @param files (optional: defaults to "all") the space-delimited list of files to stage
+     */
+    gitPerformStaging(operation, files) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let repoRoot = yield this.getRepoRoot(projectRoot);
+                    let doAll = !(files);
+                    let mainFiles = files;
+                    let doAllArg = (operation == "stage") ? "-A" : "";
+                    // the -f prevents an error/warning when gitignore ignores a file 
+                    // that was staged (this happens for the ref latest commit of a submodule, 
+                    // which is named after the submodule folder path, which is ignored)
+                    // HOWEVER...
+                    // If you do a -f on a stage all, you'll get every file under the entire project folder,
+                    // so don't let those two flags happen together.
+                    let forceArg = (operation == "stage" && files && files.length > 0) ? "-f" : "";
+                    let command = (operation == "stage") ? "git add" : "git reset -q";
+                    // 1) extract the changes for each sourced dependency
+                    let cfg = yield this.readCodiacProjectConfig();
+                    let prefix = path.relative(repoRoot, projectRoot);
+                    for (let index in cfg.submodules) {
+                        let submodule = cfg.submodules[index];
+                        let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                        // This prefix is the path prefix from the main repo to the root of the submodule.
+                        // the inbound files will have it, and it needs to be stripped off for the submodule git calls. 
+                        let subPrefix = path.relative(repoRoot, submoduleFolder) + "/"; // this trailing slash will disinclude the main project change named after the submodule folder itself. 
+                        this.logger.debug(submodule.folderName + "...");
+                        this.logger.debug(`subPrefix ${subPrefix}`);
+                        // 1a) Extract the files belonging to the submodule
+                        let args = undefined;
+                        if (doAll) {
+                            args = doAllArg;
+                        }
+                        else if (mainFiles && mainFiles.length > 0) {
+                            let subFiles;
+                            subFiles = _.filter(mainFiles, f => f.startsWith(subPrefix));
+                            this.logger.debug(JSON.stringify(subFiles));
+                            this.logger.debug("mainFiles: " + JSON.stringify(mainFiles));
+                            if (subFiles.length > 0) {
+                                mainFiles = _.without(mainFiles, ...subFiles);
+                                args = subFiles.map(f => f.slice(subPrefix.length)).join(" ");
+                            }
+                        }
+                        // 1b) Stage em if you got em
+                        this.logger.debug(`args: ${args}`);
+                        if (args) {
+                            this.logger.debug(`Perfoming ${operation} on files from sourced dependency: ${submodule.folderName}...`);
+                            let cmdsub = `${command} ${args}`;
+                            let output = yield this._cliExec.execAsyncStdOut(cmdsub, { cwd: submoduleFolder });
+                            if (output)
+                                this.logger.debug(output);
+                        }
+                    }
+                    // 2) stage the main project changes.
+                    let fileArgs = undefined;
+                    if (doAll) {
+                        fileArgs = doAllArg;
+                    }
+                    else if (mainFiles && mainFiles.length > 0) {
+                        fileArgs = mainFiles.join(" ");
+                    }
+                    if (fileArgs) {
+                        this.logger.debug(`Perfoming ${operation} on files from main project: ${cfg.name}...`);
+                        let cmd = `${command} ${fileArgs}`;
+                        let output = yield this._cliExec.execAsyncStdOut(cmd, { cwd: repoRoot });
+                        if (output)
+                            this.logger.debug(output);
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Standard git clone call
+    * @param url valid git url to clone from.
+    * @param targetFolder relative path to the folder into which the repo is to be cloned.
+    */
+    gitClone(url, targetFolder) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let cmd = `git clone "${url}" ${targetFolder || ""}`;
+                    let responseCode = yield this._cliExec.spawnAndLog(cmd, process.cwd(), undefined, IBetterLogger_1.LogLevel.detail);
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Debug-Logs any failure but doesn't throw errors.
+    * @param directory Absolute folder path to open.
+    */
+    tryOpenVsCode(directory) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let cmd = `code ${directory}`;
+                    let outputsub = yield this._cliExec.execAsyncStdOut(cmd, {});
+                    if (outputsub)
+                        this.logger.debug(outputsub);
+                    resolve();
+                }
+                catch (err) {
+                    // Let this fail silently without killing the command...
+                    this.logger.debug(`Error opening VSCode: ${err.message || err.stderr || ""}`, err);
+                    resolve();
+                }
+            }));
+        });
+    }
+    /** Commits the currently staged changes on the current branch
+     * of the main project and on any sourced dependencies.
+     * @param message The description for this particular commit.
+     */
+    gitCommit(message) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let cfg = yield this.readCodiacProjectConfig();
+                    let cmd = `git commit -m "${message.replace("\"", "\\\"")}"`;
+                    // Commit any staged changes for all sourced dependencies
+                    for (let index in cfg.submodules) {
+                        let submodule = cfg.submodules[index];
+                        let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                        let stagedSub = yield this.gitListChanges("staged", submoduleFolder);
+                        if (stagedSub.length > 0) {
+                            this.logger.debug(`Committing staged changes in sourced dependency: ${submodule.folderName}`);
+                            let outputsub = yield this._cliExec.execAsyncStdOut(cmd, { cwd: submoduleFolder });
+                            if (outputsub)
+                                this.logger.debug(outputsub);
+                            // TODO:  stage the associated change in the main project (it'll be named the same as the submodule name) 
+                            this.logger.debug(`Staging associated change in parent project.`);
+                            let cmd3a = `git update-index --again`; // we were moving too fast for git to see our changes.
+                            this.logger.debug(cmd3a);
+                            yield this._cliExec.execAsync(cmd3a, { cwd: projectRoot });
+                            let submoduleRelPath = path.posix.join(dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                            let cmdStageInMain = `git add ${submoduleRelPath}`;
+                            yield this._cliExec.execAsyncStdOut(cmdStageInMain, { cwd: projectRoot });
+                        }
+                    }
+                    // Commit any staged files in main project
+                    let staged = yield this.gitListChanges("staged");
+                    if (staged.length > 0) {
+                        this.logger.debug(`Committing staged changes in main project [${cfg.name}]...`);
+                        let output = yield this._cliExec.execAsyncStdOut(cmd, { cwd: projectRoot });
+                        if (output)
+                            this.logger.debug(output);
+                    }
+                    this.logger.debug(`COMPLETE!  "${message.replace("\"", "\\\"")}"`);
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Returns the hash in the git log that identifies the most recent commit. */
+    gitReadLatestCommitId() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    // For a list of format tokens, see "Table 1" on https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History 
+                    let cmd = `git log -n 1 --all --pretty=format:"%H"`; // using custom format of "{hash}|{date}|{message}"
+                    // NOTE:  using the --all flag prevents error when no commits exist: "fatal: your current branch 'master' does not have any commits yet"
+                    let output = yield this._cliExec.execAsyncStdOut(cmd, { cwd: this._projectRoot });
+                    let hash = output.trim(); // the output likely has a linebreak in it.
+                    this.logger.debug(`Latest commit:  ${hash}`);
+                    // ALTERNATE WAY (more data)
+                    // If someday we have a requirement for more data out of this...
+                    // let cmd = `git log -n 1 --pretty=format:"%H|%aD|%s"`;  // using custom format of "{hash}|{date}|{message}"
+                    // let output = await this._cliExec.execAsyncStdOut(cmd, { cwd: this._projectRoot });
+                    // this.logger.debug(`Latest commit:  ${output}`)
+                    // // let hash = output.split("|")[0];
+                    // let parts = output.split("|");
+                    // let commit: any = { };
+                    // let commit.hash = parts.shift();
+                    // let commit.commitDate = parts.shift();
+                    // let commit.message = parts.join("|");
+                    // OTHER ALTERNATE WAY (uses built-in format)
+                    // let cmd = `git log -n 1 --pretty=oneline --no-decorate`;  // using built-in format
+                    // let output = await this._cliExec.execAsyncStdOut(cmd, { cwd: this._projectRoot });
+                    // this.logger.debug(`Latest commit:  ${output}`)
+                    // Git's output is in the format "${hash} ${commit message}", with no quotes around the message.
+                    // We'll parse out just the hash
+                    // let hash = output.split(" ")[0];
+                    resolve(hash);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Pushes upstream any local commits on the current branch
+     * of the main project and on any sourced dependencies.
+     * @param only (optional, defaults to "all") The name of a specific sourced dependency to pull instead of everything in the project.  Pulls latest only for the sourced dependency specified by this parameter.
+     */
+    gitPushProject(only = "all") {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let cfg = yield this.readCodiacProjectConfig();
+                    let branches = yield this.gitEachCurrentBranch();
+                    if (only && only != "all") {
+                        let sourcedDep = cfg.submodules.find(sm => sm.folderName == only); // TODO:  verify that this shouldnt be "sm.packageName" instead.
+                        if (sourcedDep) {
+                            let relPath = path.posix.join(dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, sourcedDep.folderName);
+                            yield this.gitPush(relPath, branches[sourcedDep.packageName]);
+                        }
+                        else {
+                            this.logger.debug(`There is no sourced dependency named: ${only}.`);
+                        }
+                    }
+                    else {
+                        yield this.gitPush("./", branches[cfg.name]);
+                        // do so for all sourced dependencies
+                        for (let index in cfg.submodules) {
+                            let sourcedDep = cfg.submodules[index];
+                            let relPath = path.posix.join(dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, sourcedDep.folderName);
+                            yield this.gitPush(relPath, branches[sourcedDep.packageName]);
+                        }
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    gitPush(relFolderPath, branch) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    this.logger.debug(`Pushing local commits (branch: ${branch.name}) for: ${relFolderPath}`);
+                    let projectRoot = this.getConfigRoot();
+                    let sourceFolder = path.join(projectRoot, relFolderPath);
+                    let upstreamArg = (!branch.upstream) ? `--set-upstream origin ${branch.name}` : ``;
+                    let cmd = `git push --porcelain ${upstreamArg}`; // --porcelain keeps output parseable and doesnt write stdout to stderr (instead of --quiet, which simply doesnt report)
+                    let output = yield this._cliExec.execAsyncStdOut(cmd, { cwd: sourceFolder });
+                    if (output)
+                        this.logger.debug(output);
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Retrieves remote changesets on the current branch
+     * of the main project and on any sourced dependencies.
+     * @param only (optional, defaults to "all") The name of a specific sourced dependency to pull instead of everything in the project.  Pulls latest only for the sourced dependency specified by this parameter.
+    */
+    gitPull(only = "all") {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let cfg = yield this.readCodiacProjectConfig();
+                    let cmd = `git pull`;
+                    if (only && only != "all") {
+                        let submodule = cfg.submodules.find(d => d.folderName == only);
+                        if (!submodule) {
+                            let deps = yield this.getNpmDependencies(projectRoot);
+                            if (deps.indexOf(only) >= 0) {
+                                this.logger.warn(`The dependency [${only}] is not currently sourced.  Use "codiac dep:source" to source it.`);
+                            }
+                            else {
+                                this.logger.error(`There is no sourced dependency named: [${only}].`);
+                            }
+                        }
+                        else {
+                            let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                            this.logger.notice(`Pulling remote commits into sourced dependency: [${this.styler.hilite(submodule.folderName)}]...`);
+                            let outputsub = yield this._cliExec.spawnAndLog(cmd, submoduleFolder);
+                        }
+                    }
+                    else {
+                        this.logger.notice(`Pulling any remote commits into main project: [${this.styler.hilite(cfg.name)}]...`);
+                        let output = yield this._cliExec.spawnAndLog(cmd, projectRoot);
+                        // do so for all sourced dependencies
+                        cfg = yield this.readCodiacProjectConfig();
+                        for (let index in cfg.submodules) {
+                            let submodule = cfg.submodules[index];
+                            let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                            this.logger.notice(`Pulling remote commits into sourced dependency: [${this.styler.hilite(submodule.folderName)}]...`);
+                            let outputsub = yield this._cliExec.spawnAndLog(cmd, submoduleFolder);
+                        }
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    // gitStash
+    /** Fails if the branch has pending changes or a pending merge status.
+     * Set the discardChanges argument to ignore any pending status and force the delete.
+     * @param branchName Must be a valid existing branch
+     * @param discardChanges (optional: default = false) Ignores any pending changes or merge status and forces the delete of the branch.
+     */
+    gitDeleteBranch(branchName, discardChanges = false) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let projectRoot = this.getConfigRoot();
+                    let forceArg = (discardChanges) ? "--force" : "";
+                    let cmd = `git branch --delete ${forceArg} ${branchName}`;
+                    let output = yield this._cliExec.execAsync(cmd, { cwd: projectRoot });
+                    let cfg = yield this.readCodiacProjectConfig();
+                    for (let index in cfg.submodules) {
+                        let submodule = cfg.submodules[index];
+                        let submoduleFolder = path.posix.join(projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, submodule.folderName);
+                        // TODO:  If the branch doesnt exist, dont fail on these.
+                        this.logger.debug(`Deleting branch [${branchName}] in sourced dependency: ${submodule.folderName}`);
+                        //let outputsub = await this._cliExec.execAsync(cmd, { cwd: submoduleFolder });
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    hasYetToBePublished(pkgName, version, cwd) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let notYetPublished = false;
+                    let execOptions = { cwd: cwd };
+                    // Honestly, NPM: 
+                    //    npm search is unreliable, 
+                    //    npm view is unreliable, 
+                    //    niether differentiates unauthorized from non-existent,
+                    //    and no systematic standard syntax for formatting output
+                    // WTF.  Why dont we have a simple, reliable existence check?!?!  
+                    // Fuck you, you hacks.
+                    // Check if the npm package name in the registry at all...
+                    // let cmd = `npm search /^${pkgName}$/ --json`  // Why the fuck doesnt search return the listing sometimes (npm view does, but npm search doesnt?  WTF!!!?
+                    // let matches = await this.execAsyncJson<string[]>(cmd, execOptions);
+                    // if (matches.length == 0 || matches.indexOf(pkgName) == 0) {
+                    // NOTE: Isnt this NESTED try block greeaaat?  
+                    //       npm's "view-or-fail" is all we have to work with here 
+                    //       cuz npm search is unreliable.
+                    let cmd = `npm view ${pkgName} name`; // this projects the name (why does it fail sometimes?)
+                    try {
+                        let match = yield this._cliExec.execAsyncStdOut(cmd, execOptions);
+                        // Now check whether this particular version is published...
+                        // NOTE: Oh, and turns out npm view with a VERSION 
+                        //       gives you "view-or-blank" behavior, so we dont have to 
+                        //       nest yet another try block here.  Yay consistency! wait.. no.
+                        cmd = `npm view ${pkgName}@${version} name`; // name  // we were projecting only the name, but got "ReferenceError: name is not defined"  ...WTF?
+                        let nameFound = yield this._cliExec.execAsyncStdOut(cmd, execOptions);
+                        if (nameFound == undefined || nameFound == "") {
+                            notYetPublished = true;
+                            this.logger.debug(`The package version [${pkgName}@${version}] has not been published.`);
+                        }
+                    }
+                    catch (err) {
+                        // npm throws "E404" when missing (or if private and we're unauthorized)
+                        // eg: first line of stdout is   "npm ERR! code E404"
+                        // Can we reliably just parse that exact string?  
+                        // Or is there a more reliable, actually engineered, way to interpret an error response?
+                        notYetPublished = true;
+                        this.logger.debug(`The package name [${pkgName}] does not exist in the registry.`);
+                    }
+                    resolve(notYetPublished);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** OBSOLETE!! Use build() instead. */
+    typescriptBuild(newVersion, buildDef = [], clear) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return this.build(newVersion, buildDef, clear);
+        });
+    }
+    /** Increments the version and builds each sourced dependency
+     * and then the main project.
+     * Returns the build number. */
+    build(increment, buildDef = [], clear) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                try {
+                    let cfg = this.readCodiacProjectConfig();
+                    let buildNumber = codiac_common_1.BuildNumberGenerator.getOne(); // TODO:  Suffix the build number with the seatId or branch or current user
+                    this.logger.notice(`BuildNumber: ${buildNumber}`);
+                    // build each sourced dependency
+                    for (let subm of cfg.submodules) {
+                        yield this.buildSubmodule(subm, clear);
+                    }
+                    // Get the build command and output folder
+                    let cmd = (buildDef && buildDef.length > 0) ? buildDef.join(" && ") : (_a = cfg.buildDef) === null || _a === void 0 ? void 0 : _a.join(" && ");
+                    let outputFolder = /* cfg.outputFolder || */ dx_constants_1.DxConstants.DEFAULT_BUILD_OUTPUT_DIR; // how do we make this accurate?  Hopefully we dont have to make them declare this in the codiac.json...
+                    if (!cmd || cmd.trim() == "") {
+                        throw new contracts_1.CodiacError(`No build command has been declared for this project in ${codiac_ops_common_3.OpsConstants.PROJECT_CONFIG_FILENAME} (set the "buildDef" property to an array of command strings).`);
+                    }
+                    if (cmd) {
+                        this.logger.notice(`Building ${this.styler.hilite(cfg.name)}...`);
+                        if (clear && outputFolder)
+                            this.clearFolder(outputFolder);
+                        yield this._cliExec.spawnAndLog(cmd, this._projectRoot, undefined, IBetterLogger_1.LogLevel.detail);
+                        // Copy in any build includes
+                        if (outputFolder && cfg.buildIncludes && cfg.buildIncludes.length > 0) {
+                            for (const file of cfg.buildIncludes) {
+                                let sourceFile = path.join(this._projectRoot, file);
+                                let targetFile = path.join(this._projectRoot, outputFolder, file);
+                                if (fs.existsSync(sourceFile)) {
+                                    let dirName = path.dirname(targetFile);
+                                    yield fse.ensureDir(dirName);
+                                    yield fse.copy(sourceFile, targetFile);
+                                    // await this._cliExec.cpAsync(sourceFile, targetFile);
+                                }
+                            }
+                        }
+                        // // !!!!!  HACK  !!!!:  copy in the app config
+                        // // TODO:  This should be some less specific copy command
+                        // let sourceFile = path.join(this._projectRoot, "src/app-config.json");
+                        // if (fs.existsSync(sourceFile) && outputFolder) {
+                        //   await this._cliExec.cpAsync(sourceFile, path.join(this._projectRoot, outputFolder, "app-config.json"));
+                        // }
+                        // This is only for bwd compatibility: codeVersion must always exist.
+                        if (!cfg.codeVersion) {
+                            cfg.codeVersion = (_b = (yield this.npmGetCurrentVersion())) !== null && _b !== void 0 ? _b : dx_constants_1.DxConstants.DEFAULT_INIT_CODE_VERSION;
+                        }
+                        if (increment) {
+                            // let cliConfig = await this._cfgRepo.read();  // TODO: Make this a lazy-load.  This is a bad place for a file sys read. 
+                            if (this.cliConfig.addBranchNameToPrereleases === true) {
+                                let currentBranch = yield this.gitCurrentBranchNameFor(this._projectRoot);
+                                if (this.isMainBranch(currentBranch) === false) {
+                                    increment.preId = currentBranch;
+                                    // cfg.codeVersion = this.addPrereleaseId(cfg.codeVersion, currentBranch);
+                                }
+                            }
+                            let codeVersion = yield this._workspaceVersioner.incrementCodeVersion(cfg, increment);
+                            yield this.npmIncrementVersion(increment);
+                        }
+                    }
+                    resolve(buildNumber);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Bumps the version as specified.
+     * NOTE!!!  Currently uses npm for this!
+     *
+     * ***TODO:  Move version persistence to image exports in codiac.json and get off of npm.***
+     */
+    npmIncrementVersion(newVersion) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    // Increment the package version only after the build has succeeded.
+                    // DEV NOTE:  Even if there wasnt a tsc build performed, any images built after this will need the new version stamp. 
+                    // TODO:  Extract the version bump into a seaparate call
+                    if (newVersion) {
+                        let dontCommitIt = " --git-tag-version false"; // Prevents npm from tagging the git branch (which requires all changes to be committed or it fails)
+                        if (newVersion.fullName) {
+                            this.logger.notice(`Applying new version number ${this.styler.hilite(newVersion.fullName)}...`);
+                            yield this._cliExec.execAsyncStdOut(`npm version ${newVersion.fullName} ${dontCommitIt}`, { cwd: this._projectRoot });
+                        }
+                        else if (newVersion.major) {
+                            this.logger.notice(`Incrementing ${"major"} version number...`);
+                            yield this._cliExec.execAsyncStdOut(`npm version major ${dontCommitIt}`, { cwd: this._projectRoot });
+                        }
+                        else if (newVersion.minor) {
+                            this.logger.notice(`Incrementing ${"minor"} version number...`);
+                            yield this._cliExec.execAsyncStdOut(`npm version minor ${dontCommitIt}`, { cwd: this._projectRoot });
+                        }
+                        else if (newVersion.patch) {
+                            this.logger.notice(`Incrementing ${"patch"} version number...`);
+                            yield this._cliExec.execAsyncStdOut(`npm version patch ${dontCommitIt}`, { cwd: this._projectRoot });
+                        }
+                        else if (newVersion.preId) {
+                            this.logger.notice(`Incrementing ${"prerelease"} id and version number...`);
+                            yield this._cliExec.execAsyncStdOut(`npm version prerelease --preid ${newVersion.preId} ${dontCommitIt}`, { cwd: this._projectRoot });
+                        }
+                        else if (newVersion.prerelease) {
+                            this.logger.notice(`Incrementing ${"prerelease"} version number...`);
+                            yield this._cliExec.execAsyncStdOut(`npm version prerelease ${dontCommitIt}`, { cwd: this._projectRoot });
+                        }
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    // /** Increments the project code version number by the given increment.
+    //  *  Retains existing version number if no increment is specified.
+    //  *  Writes changes to the project config (aka: codiac.json).
+    //  *  Throws if existing version is invalid.
+    //  * 
+    //  * @param cfg Project config doc (aka: codiac.json deserialized)
+    //  */
+    // private async incrementCodeVersion(cfg: ProjectConfig, increment: VersionBump): Promise<ProjectConfig> {
+    //   return new Promise<ProjectConfig>(async (resolve, reject) => {
+    //     try {
+    //       let newVersion = this._imageVersioner.incrementVersion(cfg.codeVersion, increment);
+    //       if (newVersion != cfg.codeVersion) {
+    //         cfg.codeVersion = newVersion;
+    //         await this._projCfgRepo.updateProjectConfigFile(cfg);
+    //       }
+    //       resolve(cfg);
+    //     } catch (err) {
+    //       reject(err);
+    //     }
+    //   });
+    // }
+    // /** Increments the version number of the given image export by the given increment.
+    //  *  Retains existing version number if no increment is specified.
+    //  *  Sets to the default init version number if the imageExport doesnt yet have a version declared.
+    //  *  Writes changes to the project config (aka: codiac.json).
+    //  *  Throws if existing version is invalid.
+    //  * 
+    //  * @param cfg Project config doc (aka: codiac.json deserialized)
+    //  */
+    // private async incrementImageVersion(imageExport: ImageExport, cfg: ProjectConfig, increment: VersionBump): Promise<ImageExport> {
+    //   return new Promise<ImageExport>(async (resolve, reject) => {
+    //     try {
+    //       if (!imageExport.version) imageExport.version = DxConstants.DEFAULT_INIT_IMAGE_VERSION;
+    //       let newVersion = this.incrementVersion(imageExport.version, increment);
+    //       if (newVersion != imageExport.version) {
+    //         imageExport.version = newVersion;
+    //         if (!cfg.images) cfg.images = {};
+    //         cfg.images[imageExport.name] = imageExport;
+    //         await this._projCfgRepo.updateProjectConfigFile(cfg);
+    //       }
+    //       resolve(imageExport);
+    //     } catch (err) {
+    //       reject(err);
+    //     }
+    //   });
+    // }
+    // /** Increments the given semantic version nnumber by the given increment.
+    //  *  Returns existing version number if no increment is specified.
+    //  *  Throws if existing version is invalid.
+    //  */
+    // public incrementVersion(existing: string, increment: VersionBump): string {
+    //   try {
+    //     let newVersion: string | null = existing;
+    //     if (increment) {
+    //       if (increment.fullName) {
+    //         this.logger.notice(`Applying new version number ${this.styler.hilite(increment.fullName)}...`);
+    //         newVersion = increment.fullName;
+    //       } else if (increment.major) {
+    //         this.logger.notice(`Incrementing ${"major"} version number...`);
+    //         newVersion = semver.inc(existing, "major");
+    //       } else if (increment.minor) {
+    //         this.logger.notice(`Incrementing ${"minor"} version number...`);
+    //         newVersion = semver.inc(existing, "minor");
+    //       } else if (increment.patch) {
+    //         this.logger.notice(`Incrementing ${"patch"} version number...`);
+    //         newVersion = semver.inc(existing, "patch");
+    //       } else if (increment.prerelease) {
+    //         this.logger.notice(`Incrementing ${"prerelease"} version number...`);
+    //         newVersion = semver.inc(existing, "prerelease");
+    //       }
+    //       if (newVersion == null) throw new CodiacError(`Cannot increment; current version number [${existing}] is not a valid semantic version.`);
+    //     }
+    //     return newVersion;
+    //   } catch (err) {
+    //     throw err;
+    //   }
+    // }
+    /**
+     * @param subm The sourced dependency project to build.
+     * @param clear (Optional: defaults to false) Clears the output folder before build.
+     */
+    buildSubmodule(subm, clear) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let submoduleFolder = path.posix.join(this._projectRoot, dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, subm.folderName);
+                    // TODO: Check for changes and skip the build if there's no need.  
+                    // HACK: git doesnt know whats changes since your last build,
+                    // but you could check the time signature on each changed file
+                    // and compare it to the time signature recorded from the latest build...?
+                    // TODO:  Detect if it's a codiac project, in which case, we just hv to run the build script declared in it.
+                    //        If the current build is a named build, 
+                    //        and there's a matching build for the submodule, 
+                    //        then run the matching build namesake, otherwise, run the default build.
+                    let cmd;
+                    let outputFolder; // fully qualified path to the build output folder.
+                    if (subm.buildScript) {
+                        // We coud try this: the cod below loads the npm script: "build"
+                        // let pj = await this.readNpmPackageJson(submoduleFolder);
+                        // if (pj && pj.scripts && pj.scripts.build) cmd = pj.scripts["build"];
+                        cmd = subm.buildScript;
+                    }
+                    else {
+                        // TODO:  If it's a dependency, it is likel to have the same default platform build command as the main project (eg: tsc)
+                        //        Though if the main project is an angular proj that uses webpack, its main build command will be "webpack.." something, 
+                        //        so perhaps a project needs a default build command/script for its dependencies?  Or we just have to ask the user when they source it.
+                        let tsconfig = this.readTsConfig(submoduleFolder);
+                        if (tsconfig) {
+                            // Typescript project
+                            cmd = "tsc -p .";
+                            outputFolder = this.getTsOutputFolder(submoduleFolder, tsconfig);
+                            this.logger.detail(`Detected typescript for sourced dependency ${subm.packageName} located in ${submoduleFolder}: using default typescript build because no build script is declared for it in ${codiac_ops_common_3.OpsConstants.PROJECT_CONFIG_FILENAME}.`);
+                            // TODO:  DO WE WANT TO KEEP THIS BUILT IN TYPESCRIPT DEFAULT BEHAVIOR? 
+                            //        Or should we simply throw if there's no build explicitly defined for the submodule?
+                        }
+                        else {
+                            this.logger.warn(`Skipping build for sourced dependency ${subm.packageName} located in ${submoduleFolder}: No ${dx_constants_1.DxConstants.TSCONFIG_JSON_FILENAME} was found and no build script is declared in ${codiac_ops_common_3.OpsConstants.PROJECT_CONFIG_FILENAME}.`);
+                            // TODO:  Add remediation instructions to that error message
+                            //        on how to set the buildScript override for that submodule.
+                            // NOTE: We cannot just blindly fire any old npm build script that commes down in a dependency.
+                            //       cuz what a great way to release trojans..
+                            //       WE MUST get their explicit consent to fire a build script that is written into that source code. 
+                        }
+                    }
+                    if (cmd) {
+                        // QUESTION: Can we append the build # without changing the npm version in the package.json?
+                        this.logger.notice(`Building sourced dependency: ${this.styler.hilite(subm.folderName)}...`);
+                        if (clear && outputFolder)
+                            this.clearFolder(outputFolder);
+                        yield this._cliExec.spawnAndLog(cmd, submoduleFolder, undefined, IBetterLogger_1.LogLevel.detail);
+                        // let output = await this._cliExec.execAsyncStdOut(cmd, { cwd: submoduleFolder }, LogLevel.detail);
+                        // if (output) this.logger.debug(output);
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Determines the build output folder as specified in the given tsconfig doc.
+     * @param tsConfigFolder The root folder for the typescript project (contains the tsconfig.json file).
+     * @param tsconfig The typescript configuration documetn for the project.
+    */
+    getTsOutputFolder(tsConfigFolder, tsconfig) {
+        let outDir = tsconfig.compilerOptions.outDir || dx_constants_1.DxConstants.DEFAULT_BUILD_OUTPUT_DIR;
+        let fullPath = path.join(tsConfigFolder, outDir);
+        return fullPath;
+    }
+    clearTsOutputFolder(tsConfigFolder, tsconfig) {
+        let fullPath = this.getTsOutputFolder(tsConfigFolder, tsconfig);
+        this.clearFolder(fullPath);
+    }
+    clearFolder(fullPath) {
+        if (fs.existsSync(fullPath)) {
+            this.logger.detail("Clearing output folder", fullPath);
+            let spec = (fullPath.endsWith("*")) ? fullPath : path.join(fullPath, "**/*");
+            rimraf.sync(fullPath, {});
+            return true;
+        }
+        return false;
+    }
+    /** Builds the container image based on the given container definition file.
+     * @param requestedFrameworkVersion (Optional: defaults to latest) Explicitly sets the version of the codiac base image to use.
+     * @param noCache (Optional: defaults to false) Ignores the local Docker image cache, thereby forcing a fresh download of each image from its container registry layer in the build.
+     * @param identitySet (Optional) The collection of the current user's auth tokens to inject into the build env (eg: for enabling private packages in npm).
+     * @param targetStage (Optional) For images defined with multi-stage builds, the name of the only build stage to be built on this pass.
+     * @param imagesToBuild (Optional) Limits the list of images to build.  Each value must match the name property of an image export defined in the codiac project file (codiac.json).  Ignored if empty.
+     */
+    buildProjectImages(buildNumber, versionBump, requestedFrameworkVersion, noCache = false, identitySet, targetStage, imagesToBuild) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                var _a;
+                try {
+                    this.logger.debug("Container build...");
+                    let cfg = yield this.readCodiacProjectConfig();
+                    cfg.submodules.forEach(submodule => {
+                        this.logger.debug(`Shall we build container(s) for submodule: ${submodule.folderName} ?`);
+                    });
+                    if (cfg.images) {
+                        // let projectVersion = this.npmGetCurrentVersion();
+                        let projectVersion = cfg.codeVersion; // this.npmGetCurrentVersion();
+                        let dockerRoot = this._projectRoot; // this shd be image-specific
+                        let tsconfig = this.readTsConfig();
+                        let distPath = (tsconfig) ? tsconfig.compilerOptions.outDir : undefined || dx_constants_1.DxConstants.DEFAULT_BUILD_OUTPUT_DIR;
+                        // We could just use latest, but we should ensure a full version match from package.json to the image.
+                        let frameworkVersion = requestedFrameworkVersion ? requestedFrameworkVersion : yield this.getInstalledFrameworkVersion();
+                        let buildContext = {
+                            dockerRoot: dockerRoot,
+                            distPath: distPath,
+                            codeVersion: cfg.codeVersion,
+                            buildNumber: buildNumber,
+                            apiFrameworkVersion: frameworkVersion,
+                            identitySet: identitySet
+                        };
+                        let selectedImages;
+                        if (imagesToBuild && imagesToBuild.length > 0) {
+                            selectedImages = [...imagesToBuild];
+                        }
+                        else {
+                            selectedImages = _.keys(cfg.images);
+                        }
+                        // let cliConfig = await this._cfgRepo.read();  // TODO: Make this a lazy-load.  This is a bad place for a file sys read. 
+                        for (let imageName of selectedImages) {
+                            let imageExport = cfg.images[imageName]; //  TODO: get a non-nullable generic dictionary into @codiac.io/codiac-common
+                            if (imageExport == undefined) {
+                                throw new Error(`There is no image named: [${imageName}] declared in the project.`);
+                            }
+                            else {
+                                if (imageExport.readonly) {
+                                    this.logger.debug(`Skipping build of readonly image: ${imageName}`);
+                                }
+                                else {
+                                    if (imageExport.version == undefined)
+                                        imageExport.version = (_a = cfg.codeVersion) !== null && _a !== void 0 ? _a : dx_constants_1.DxConstants.DEFAULT_INIT_IMAGE_VERSION; // 
+                                    if (versionBump && imageExport.version) {
+                                        if (this.cliConfig.addBranchNameToPrereleases === true) {
+                                            let currentBranch = yield this.gitCurrentBranchNameFor(this._projectRoot);
+                                            if (this.isMainBranch(currentBranch) === false) {
+                                                versionBump.preId = currentBranch;
+                                                // imageExport.version = this.addPrereleaseId(imageExport.version, currentBranch);
+                                            }
+                                        }
+                                        imageExport = yield this._workspaceVersioner.incrementImageVersion(imageExport, cfg, versionBump);
+                                    }
+                                    let versionStamp = imageExport.version || projectVersion; // <---- ImageExports can have their own versions, otherwise fall back to project code version.
+                                    yield this.buildSingleImage(imageExport, versionStamp, noCache, buildContext, targetStage);
+                                }
+                            }
+                        }
+                    }
+                    else {
+                        this.logger.notice("This project is not set to export any container images. Use 'codiac images:add' to do so.");
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Currently conventional - check if the branch is main or master.
+     *
+     * TODO: This is too specific.  Make this configurable in the codiac.json, backed by the cli config, backed by this convention..
+     */
+    isMainBranch(branch) {
+        return (branch === "master" || branch === "main");
+    }
+    /**
+     *
+     * @param imageExport
+     * @param thisVersion
+     * @param noCache
+     * @param cntx
+     * @param targetStage (Optional) For an image defined with a multi-stage build, the name of the only build stage to be built on this pass.
+     */
+    buildSingleImage(imageExport, thisVersion, noCache, cntx, targetStage) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    this.logger.notice(`Building Container Image: ${this.styler.hilite(`${imageExport.name}:${thisVersion}`)}`);
+                    let droot = (imageExport.definitionFile) ? path.dirname(imageExport.definitionFile) : ".";
+                    this.logger.trace(`droot: [${droot}]`);
+                    let flatten = false;
+                    let cmdArgs = [];
+                    if (noCache)
+                        cmdArgs.push("--no-cache");
+                    cmdArgs.push(`-t ${imageExport.name}:${thisVersion}`);
+                    cmdArgs.push(`-t ${imageExport.name}:latest`);
+                    // cmdArgs.push(`--squash`);
+                    if (targetStage)
+                        cmdArgs.push(`--target ${targetStage}`);
+                    // Apply labels
+                    let labels = {};
+                    labels["branch"] = (yield this.gitCurrentBranchFor(this._projectRoot)).name;
+                    let lastCommit = (yield this.gitReadLatestCommitId());
+                    if (lastCommit)
+                        labels["commit"] = lastCommit;
+                    labels["codeVersion"] = cntx.codeVersion;
+                    labels["buildNumber"] = cntx.buildNumber;
+                    for (let key in labels) {
+                        cmdArgs.push(`--label "${key}=${labels[key]}"`);
+                    }
+                    let buildEnv = Object.assign({}, process.env);
+                    let cmd;
+                    // NPM TOKEN SUPPORT (using docker secret build parameter)  
+                    // from https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information
+                    // Create a temp npmrc file in the proj user folder, with all token variables resolved.
+                    // then pass it into the build as a secret
+                    // mount that secret for the npm install
+                    // then afterwards, delete the temp file we created in the poject user folder.
+                    buildEnv.DOCKER_BUILDKIT = "1"; // from https://docs.docker.com/engine/reference/builder/#buildkit
+                    // TODO:  Consider merging contents of the project npmrc with the project-user npmrc 
+                    //        or copying them both into the image.
+                    let npmrcFilePath = path.join(this._projectRoot, codiac_ops_common_3.OpsConstants.PROJECT_USER_CONFIG_FOLDER_NAME, dx_constants_1.DxConstants.NPM_PROJECT_USER_CONFIG_FILENAME);
+                    // TODO:  This shd be conditional on existince of identities
+                    // and throw if then the file doesnt exist.
+                    if (fs.existsSync(npmrcFilePath)) {
+                        cmdArgs.push(`--secret id=npmrc,src=${npmrcFilePath}`);
+                    }
+                    // TODO:  Expose this as a build option.
+                    // Renders all the shell output from the build 
+                    // (VERY VERBOSE AND MUCH SLOWER)
+                    // cmdArgs.push("--progress=plain"); 
+                    if (imageExport.buildParams) {
+                        for (let arg in imageExport.buildParams) {
+                            cmdArgs.push(`${arg}${(imageExport.buildParams[arg] !== undefined) ? " " + imageExport.buildParams[arg] : ""}`);
+                        }
+                    }
+                    if (!imageExport.definitionFile) {
+                        // Autogen the def file contents and run the in-memory invocation
+                        let jitDockerFile = this.generateDockerImageDef(cntx.apiFrameworkVersion, cntx.distPath, "", cntx.identitySet, true);
+                        buildEnv.jitDockerFile = jitDockerFile.join("\\n");
+                        this.logger.debug(`JIT (Just-In-Time) docker image definition auto-generated`, jitDockerFile);
+                        cmd = `echo \$jitDockerFile | docker build ${cmdArgs.join(" ")} -f - .`;
+                    }
+                    else {
+                        let regen = false;
+                        let fullDefPath = path.join(this._projectRoot, imageExport.definitionFile);
+                        if (imageExport.overwrite == "always") {
+                            regen = true;
+                        }
+                        else {
+                            let fileExists = fs.existsSync(fullDefPath);
+                            if (!fileExists) {
+                                if (imageExport.overwrite == "never") {
+                                    // never-overwrite AND the file is missing
+                                    throw new Error(`Missing definition file [${fullDefPath}] for image [${imageExport.name}];  either create the definition file manually, unset its 'definitionFile' property altogether, or change its 'overwrite' setting to enable it to be autogenerated.`);
+                                }
+                                else {
+                                    regen = true; // asneeded scenario
+                                }
+                            }
+                        }
+                        if (regen) {
+                            this.logger.detail(`Generating image definition file ${fullDefPath}.`);
+                            let autoContent = this.generateDockerImageDef(cntx.apiFrameworkVersion, cntx.distPath, "", cntx.identitySet);
+                            let targetFolder = path.dirname(fullDefPath);
+                            if (!fs.existsSync(targetFolder)) {
+                                fs.mkdirSync(targetFolder, { recursive: true });
+                            }
+                            fs.writeFileSync(fullDefPath, autoContent);
+                        }
+                        cmd = `docker build ${cmdArgs.join(" ")} -f ${imageExport.definitionFile} .`;
+                    }
+                    yield this._cliExec.spawnAndLog(cmd, cntx.dockerRoot, buildEnv);
+                    // if (flatten) {
+                    //   this.logger.detail(`Flattening image...`);
+                    //   let runCmd = `docker run -d ${imageExport.name}:${thisVersion} /bin/true`;
+                    //   let ctrId = await this._cliExec.execAsyncStdOut(runCmd, { cwd: cntx.dockerRoot });
+                    //   let importCmd = `docker export ${ctrId} | docker import - ${imageExport.name}:${thisVersion}`;
+                    //   await this._cliExec.spawnAndLog(importCmd, cntx.dockerRoot);
+                    //   await this._cliExec.spawnAndLog(`docker tag ${imageExport.name}:${thisVersion} ${imageExport.name}:latest`, cntx.dockerRoot);
+                    // }
+                    // TODO: Consider labeling the git log with the 'imageName:version' being created.  
+                    // Q: Why not? 
+                    // A: Because, according to the "Sharing Tags" section on https://git-scm.com/book/en/v2/Git-Basics-Tagging
+                    //    "By default, the git push command doesn’t transfer tags to remote servers. 
+                    //    You will have to explicitly push tags to a shared server after you have created them."
+                    //    eg:  $ git push origin v1.5
+                    //    eg:  $ git push origin --tags
+                    // 
+                    // let cmdTag = `git tag image-${imageExport.name}:${thisVersion}`
+                    // let commit = await this._cliExec.execAsyncStdOut(cmdTag, { cwd: this._projectRoot });
+                    let details = yield this._cliExec.execAsyncStdOut(`docker inspect ${imageExport.name}:${thisVersion}  &&  docker image ls ${imageExport.name}:${thisVersion}`, { cwd: cntx.dockerRoot }, IBetterLogger_1.LogLevel.trace, false);
+                    this.logger.trace(`Newly minted image ${imageExport.name}:${thisVersion}`, details);
+                    yield this.updateConfigWithImageMetaFromInspection(imageExport.name, thisVersion, cntx);
+                    resolve();
+                }
+                catch (err) {
+                    reject(new contracts_1.CodiacError(`Error building image: ${err.message || ""}`, err));
+                }
+                finally {
+                    let tempNpmrcPathName = path.join(this._projectRoot, codiac_ops_common_3.OpsConstants.PROJECT_USER_CONFIG_FOLDER_NAME, ".npmrc");
+                    if (fs.existsSync(tempNpmrcPathName)) {
+                        try {
+                            fs.unlinkSync(tempNpmrcPathName);
+                        }
+                        catch (_a) { }
+                    }
+                }
+            }));
+        });
+    }
+    /**
+     * Cherry Picking single property output from Docker inspection, and stored in the project > imgs > export cfg for:
+     *    Os - needed to support multi-platform nodepooling
+     *    Architecture - currently dont need it, but I have feeling it wont be long
+     */
+    updateConfigWithImageMetaFromInspection(name, tag, cntx) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    const inspectForOs = yield this._cliExec.execAsyncStdOut(`docker inspect ${name}:${tag} --format="{{json .Os}}"`, { cwd: cntx.dockerRoot }, undefined, false);
+                    const inspectForArch = yield this._cliExec.execAsyncStdOut(`docker inspect ${name}:${tag} --format="{{json .Architecture}}"`, { cwd: cntx.dockerRoot }, undefined, false);
+                    let cfg = yield this.readCodiacProjectConfig();
+                    if (cfg && cfg.images) {
+                        const osRaw = inspectForOs;
+                        this.logger.debug("found os as: ", osRaw);
+                        const os = osRaw.replace(/^"(.+)"$/, '$1');
+                        this.logger.debug("mutated os to: ", os);
+                        if (os)
+                            cfg.images[name].os = inspectForOs.replace(/^"(.+)"$/, '$1').toLowerCase(); // removing the quotes that the cmd sends it back with
+                        if (inspectForArch)
+                            cfg.images[name].architecture = inspectForArch.replace(/^"(.+)"$/, '$1').toLowerCase();
+                        yield this._projCfgRepo.updateProjectConfigFile(cfg);
+                    }
+                    resolve();
+                }
+                catch (error) {
+                    reject(new contracts_1.CodiacError(`Image inspection failed with error: ${error.message || ""}`, error));
+                }
+            }));
+        });
+    }
+    /** Housekeeping method that deletes any untagged images
+     * that get leftover after multiple builds of the same image. */
+    dockerPruneDanglingImages() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    this.logger.detail(`Pruning dangling images...`);
+                    let cmd = `docker images -q --filter 'dangling=true' | xarg docker rmi`;
+                    yield this._cliExec.spawnAndLog(cmd, this._projectRoot);
+                    this.logger.notice(`Complete! Deleted leftover untagged images.`);
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Legacy logic to hydrate the build env and the npmrc file with token values. */
+    npmHydrateTokensInNpmrc(npmrcFilePath, buildEnv, identitySet) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let npmrc = fs.readFileSync(npmrcFilePath, { encoding: "utf-8" });
+                    // We're going to inject the entire identity set (for now).
+                    // Later, we should get the project to tell us which identities it needs,
+                    // to build this image (based on its private dependencies),
+                    // eg:  imageExport.onBuild.requiredTokenNames
+                    for (let tokenName in identitySet) {
+                        let identity = identitySet[tokenName];
+                        if (identity.provider == codiac_relay_contracts_1.IdentityProvider.npm) {
+                            // cmdArgs.push(`--build-arg ${tokenName}=\${${tokenName}}`)
+                            buildEnv[tokenName] = identity.token;
+                            // this.logger.debug(`Injecting ${identity.provider} identity token ${tokenName} as image build arg.`, identity);
+                            // flatten = true;  // If we're ading tokens, we need to make sure we flatten to kill the history
+                            npmrc = npmrc.replace(`\${${tokenName}}`, identity.token);
+                        }
+                    }
+                    fs.writeFileSync(npmrcFilePath, npmrc, { encoding: "utf-8" });
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Retrieves the version of the api framework that is currently installed in the project
+     * from the npm package.json dependencies list.
+     * NOTE:  Removes any version-support prefixes (eg: ^).
+     * NOTE: Returns "latest" when not installed. */
+    getInstalledFrameworkVersion() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let version = "latest";
+                    let pkg = yield this.readNpmPackageJson();
+                    if (pkg && pkg.dependencies) {
+                        let installed = pkg.dependencies[dx_constants_1.DxConstants.API_FRAMEWORK_PACKAGE];
+                        if (installed) {
+                            version = installed.match(/([\w\d].*)/)[0];
+                        }
+                    }
+                    resolve(version);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Constructs from scratch the contents of a dockerfile from which to build an image.
+     * @param frameworkVersion The version of the api framework to use within the image.  That is, the api framework base image will need this version number applied to it.
+     * @param distPath The path to the typescript output folder, relative to the project root (eg: "./dist").
+     * @param prefixToProjRoot path prefix that, when applied to the image def file, resolves to the project root (ie: if using ".temp/jit.docker", this parameter would need to be "../") If this dockerfile exists within the project root itself, then any of "./" or "" or undefined are valid.
+     * @param identities (Optional) The collection of tokenized identities registeed for the current user that are to be put into scope during the image build..
+     */
+    generateDockerImageDef(frameworkVersion, distPath, prefixToProjRoot = "", identities, asArray = false) {
+        let contents = [];
+        // SECTION 1) Init...
+        contents.push("# syntax = docker/dockerfile:1.0-experimental"); // Needed for buildKit and the --mount param we're gonna use on the RUN npm i (type=secret).
+        // contents.push(`FROM letmeaskmydog/toyhauler-base:${frameworkVersion}`);
+        contents.push(`FROM node:latest`);
+        contents.push(`WORKDIR /app`);
+        contents.push(`COPY ${prefixToProjRoot}${distPath} /app`);
+        // Needed for generation of the openApi spec.
+        // Without this openApi doc generation in the api framework will throw the error: "Cant resolve property 'length' on undefined."
+        contents.push(`COPY ./tsconfig.json /app`);
+        // SECTION 2) Package installation (including relevant authentication / identity tokens)...
+        contents.push(`COPY ${prefixToProjRoot}package.json /app`); // shdnt the package.json already be there?  (via build? or publish?)
+        contents.push(`COPY ${prefixToProjRoot}package-lock.json /app`);
+        // contents.push(`RUN if [ -f ${prefixToProjRoot}package.json ]; then echo "ITSTHERE"; fi;`);
+        // contents.push("RUN echo \$ITSTHERE");
+        let injectingNpmTokens = false;
+        if (identities && !_.isEmpty(identities)) {
+            for (let tokenName in identities) {
+                let identity = identities[tokenName];
+                // contents.push(`ARG ${tokenName}`);
+                injectingNpmTokens = injectingNpmTokens || (identity.provider == codiac_relay_contracts_1.IdentityProvider.npm);
+            }
+            if (injectingNpmTokens) {
+                // contents.push(`COPY ${prefixToProjRoot}.npmrc /app`);  // only if it's not copied in already
+                // contents.push(`RUN npm whoami`);
+            }
+        }
+        let npmrcRelPath = path.join(codiac_ops_common_3.OpsConstants.PROJECT_USER_CONFIG_FOLDER_NAME, dx_constants_1.DxConstants.NPM_PROJECT_USER_CONFIG_FILENAME);
+        if (fs.existsSync(path.join(this._projectRoot, npmrcRelPath))) {
+            contents.push("RUN --mount=type=secret,id=npmrc,dst=/app/.npmrc npm i");
+        }
+        else {
+            // throw new Error(`${npmrcRelPath} is missing`);
+            contents.push("RUN npm i");
+        }
+        // if (injectingNpmTokens) {
+        //   contents.push(`RUN if [ -f .npmrc ]; then rm -f .npmrc; echo "Removed .npmrc"; fi;`);
+        //   // contents.push(`RUN rm -f .npmrc`);  // TODO: Remove only if we were the ones who added it (OR if they specified that it should be deleted..?)
+        // }
+        // SECTION 3) Entry point...
+        contents.push(`CMD ["node", "./index.js"]`);
+        return asArray ? contents : contents.join("\n");
+    }
+    declarePackageExport(config, target, sourceFile) {
+        return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            try {
+                if (!sourceFile) {
+                    // TODO:  This dialogue needs to happen in the host project.  Here it needs to stop and return a workflow status.
+                    sourceFile = yield this.ux.prompt("file", "Enter the package definition file (Hit Enter for 'package.json'): ", true, "package.json");
+                }
+                let output = { operation: "add" };
+                if (sourceFile) {
+                    let projRoot = this.getConfigRoot();
+                    let sourcePath = path.join(projRoot, sourceFile);
+                    if (fs.existsSync(sourcePath)) {
+                        let pkgDef = yield this.readNpmPackageJson(projRoot, sourceFile);
+                        let packageName = pkgDef.name;
+                        let pkgExport = new codiac_relay_contracts_2.PackageExport(target, sourceFile);
+                        let operation = "add";
+                        if (!config.packages) {
+                            config.packages = {};
+                        }
+                        else if (config.packages[packageName]) {
+                            let existing = config.packages[packageName];
+                            this.logger.debug(`Package export [${this.styler.hilite(packageName)}] is already registered in this project as [${this.styler.hilite(existing.definitionFile)}]!`);
+                            let confirm = yield this.ux.promptConfirm('reregister-pkg-export', `Re-register it? (y/n) `);
+                            if (confirm) {
+                                output.operation = "overwrite";
+                            }
+                            else {
+                                this.logger.debug("Operation cancelled by user.");
+                                pkgExport = undefined;
+                            }
+                        }
+                        if (pkgExport) {
+                            config.packages[packageName] = pkgExport;
+                            yield this._projCfgRepo.updateProjectConfigFile(config);
+                            output.name = packageName;
+                            output.package = pkgExport;
+                        }
+                    }
+                    else {
+                        // TODO:  Emit a workflow status so the host can ask the user if they want to init up a new one.
+                        this.logger.error(`Your package definition file: [${sourceFile}] does not exist.`);
+                    }
+                }
+                else {
+                    this.logger.debug("Operation cancelled.  No work was done.");
+                }
+                resolve(output);
+            }
+            catch (err) {
+                reject(err);
+            }
+        }));
+    }
+    /** Adds container image specifications to the project,
+     * which will add the image spec into the build, publish, and deploy sequences.
+     */
+    declareImageExport(config, imageName, target, sourceFile, port, buildParams) {
+        return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            try {
+                // TODO:  Validate that sourceFile is not a dirName
+                let imageExport = new codiac_relay_contracts_2.ImageExport(imageName, target, sourceFile, port);
+                if (buildParams)
+                    imageExport.buildParams = buildParams;
+                let operation = "add";
+                if (!config.images) {
+                    config.images = {};
+                }
+                else if (config.images[imageName]) {
+                    // TODO: stop and emit a workflow status instead.
+                    let confirm = yield this.ux.promptConfirm("image-overwrite", `Image export "${imageName}" already exists! Overwrite? `);
+                    if (confirm) {
+                        operation = "overwrite";
+                        this.logger.debug(`Image export "${imageName}" already exists! Overwriting it...`);
+                    }
+                    else {
+                        imageExport = undefined;
+                        this.logger.debug("Operation cancelled.  No work was done.");
+                    }
+                }
+                if (imageExport) {
+                    config.images[imageName] = imageExport;
+                    yield this._projCfgRepo.updateProjectConfigFile(config);
+                }
+                resolve({ image: imageExport, operation: operation });
+            }
+            catch (err) {
+                reject(err);
+            }
+        }));
+    }
+    /** Returns the pedigree of the current branch
+     *  starting with itself, through each parent, up to the root.  */
+    gitBranchLine(startingBranch) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let lineage = [startingBranch];
+                    let repoRoot = yield this.getRepoRoot(this._projectRoot);
+                    // This big stupid border is here because the output from these git branch commands is crazy long.
+                    // this.logger.trace("========================================================================");
+                    // this.logger.trace("|          ============== gitBranchLine() =================            |");
+                    // this.logger.trace("========================================================================");
+                    let nxBranch = startingBranch;
+                    // IMPORTANT!! 
+                    //   This will only ever generate the first two branches in the lineage.
+                    //   The git branch history needs to be walked forward (not from the start each time), 
+                    //   so it needs to be kept in this function's state and passed into gitParent().
+                    //   GitBranchLine relies on stringparsing a garbled git output, so it may not be reliable anyway.
+                    //  CONSIDER NEVER CALLING gitBranchLine().
+                    while (nxBranch != undefined && nxBranch != "") {
+                        let parent = yield this.gitParent(nxBranch);
+                        if (parent) {
+                            if (lineage.indexOf(parent) < 0 && parent != nxBranch) {
+                                if (lineage.indexOf(parent) < 0) {
+                                    lineage.push(parent);
+                                    nxBranch = parent;
+                                }
+                                else {
+                                    nxBranch = undefined;
+                                }
+                            }
+                            else {
+                                nxBranch = undefined;
+                            }
+                        }
+                        else {
+                            nxBranch = undefined;
+                        }
+                    }
+                    this.logger.debug(`Branch lineage: ${lineage.reverse().join(' > ')}`);
+                    resolve(lineage);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Returns the parent source code branch of the given one,
+     * based on the commit history (because apparently git doesnt track branching history).
+     * Returns undefined if the given branch has no parent (eg: master). */
+    gitParent(branch) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let repoRoot = yield this.getRepoRoot(this._projectRoot);
+                    let cmd = `git show-branch -a --no-color ${branch}`;
+                    let raw = (yield this._cliExec.execAsyncStdOut(cmd, { cwd: repoRoot }, IBetterLogger_1.LogLevel.trace, false)); /* Traced cuz its LOOOONG.  Raw git commit history for the branch... */
+                    let parent = undefined;
+                    if (raw || raw == "") {
+                        let pattern = escapeStringRegexp(`${branch}`);
+                        pattern = `\\[(${pattern})[\\^~\\d]*\\]`;
+                        let rows = raw
+                            .split("\n") /* each line becomes an element in a string array... */
+                            .filter(x => x.match(/\*[+-\s]*\[/)) /* we want only lines that start with an asterisk... */
+                            .filter(x => !x.match(new RegExp(pattern))); /* but also don't contain the current branch... */
+                        // .filter(x => !x.match(new RegExp(pattern)));  /* but also don't contain the current branch... */
+                        if (rows.length > 0) {
+                            parent = rows[0] /* and only the first such line... */
+                                // .replace(/.*\[(.*)\].*/, "$1")  /* and just the part of the line between []... */
+                                .match(/\[(.*?)\]/)[1] /* and the first matching string enclosed in square brackets (but without the brackets, so index 1)... */
+                                .replace(/[\^~].*/, "") /* and with any relative refs (^, ~n) removed... */
+                                .trim(); /* and without any leading or trailing spaces */
+                            if (parent == branch) {
+                                parent = undefined;
+                            }
+                        }
+                    }
+                    this.logger.debug(`Parent: ${parent}`);
+                    resolve(parent);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Returns the parent source code branch of the given one,
+     * based on the commit history (because apparently git doesnt track branching history).
+     * Returns undefined if the given branch has no parent (eg: master). */
+    gitParent_LinuxOnly(branch) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    // Getting the parent branch is non-trivial.
+                    // This command was lifted from:  https://stackoverflow.com/questions/3161204/how-to-find-the-nearest-parent-of-a-git-branch
+                    let cmd = `git show-branch -a --no-color ${branch}`;
+                    cmd += " | grep '\\*'                                 "; // we want only lines that contain an asterisk
+                    cmd += " | grep -v `git rev-parse --abbrev-ref HEAD`  "; // but also don't contain the current branch
+                    cmd += " | head -n1                                   "; // and only the first such line
+                    cmd += " | sed 's/.*\\[\\(.*\\)\\].*/\\1/'            "; // really, just the part of the line between []
+                    cmd += " | sed 's/[\\^~].*//'                         "; // and with any relative refs (^, ~n) removed
+                    let projectRoot = this.getConfigRoot();
+                    let repoRoot = yield this.getRepoRoot(projectRoot);
+                    let output = yield this._cliExec.execAsyncStdOut(cmd, { cwd: repoRoot }, IBetterLogger_1.LogLevel.trace); // traced cuz its output is looooooong.
+                    let parent = (output && output != "") ? output.trim() : undefined;
+                    resolve(parent);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** It is possible that a registry target has not been defined for the given params. */
+    getTargetImageRegistry(imageConfig, remoteOrLocal, branch) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    let output = undefined;
+                    if (remoteOrLocal == codiac_relay_contracts_2.PublishingMode.local) {
+                    }
+                    else {
+                        // STEP 1 filter out the local targets
+                        let targets = imageConfig.targets.filter(t => t.environment != codiac_relay_contracts_2.ImageExport.LOCAL_ENVIRONMENT_NAME);
+                        // STEP 2 If there's a wildcard, hold onto it.
+                        let wildcards = _.remove(targets, t => t.environment == codiac_relay_contracts_2.ImageExport.DEFAULT_ENVIRONMENT_NAME);
+                        if (wildcards.length > 0) {
+                            // NOTE: the _.remove() mutated the targets array, so the wildcard isnt in there anymore.
+                            output = wildcards[0];
+                        }
+                        // TODO:  CONSIDER REMOVING THIS.  gitBranchLine() may not be entirely accurate or complete. 
+                        // STEP 3 If there's more than one, walk the branch line 
+                        //        and see if there's anything more specific than the wildcard
+                        let match = imageConfig.targets.find(t => t.environment == branch || t.environment == `=${branch}`); // That "=branch" syntax prevents matching any child branches
+                        let nxBranch = branch;
+                        let branchLine = yield this.gitBranchLine(branch);
+                        let b = 0;
+                        while (!match && nxBranch) {
+                            match = imageConfig.targets.find(t => t.environment == nxBranch);
+                            b++;
+                            nxBranch = (b < branchLine.length) ? branchLine[b] : undefined;
+                        }
+                        if (match)
+                            output = match;
+                    }
+                    resolve(output);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Builds the container image based on the given container definition file.
+     * @param targetRemote If set, publishes to the appropriate remote container registry
+     *        mapped for the current branch, or to the local built-in container registry.  When not set, defaults to the previously set value, or to the system default of "local".
+     * @param only (optional, defaults to "all") The name of a specific sourced dependency to pull instead of everything in the project.  Pulls latest only for the sourced dependency specified by this parameter.
+     */
+    projectPublishImages(targetRemote, only, imagesToPublish, username, password) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    // let cfg = this._projCfg;
+                    // let userCfg = this._projUserCfg;
+                    let publishingTarget = this._projUserCfg.publishingMode || dx_constants_1.DxConstants.DEFAULT_PUBLISHING_TARGET;
+                    if (targetRemote != undefined)
+                        publishingTarget = (targetRemote) ? codiac_relay_contracts_2.PublishingMode.remote : codiac_relay_contracts_2.PublishingMode.local;
+                    let branches = yield this.gitEachCurrentBranch();
+                    if (only && only != "all") {
+                        let sourcedDep = this._projCfg.submodules.find(sm => sm.folderName == only); // TODO:  verify that this shouldnt be "sm.packageName" instead.
+                        if (sourcedDep) {
+                            let relPath = path.posix.join(dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, sourcedDep.folderName);
+                            yield this.publishImages(relPath, branches[sourcedDep.packageName], publishingTarget, imagesToPublish, username, password);
+                        }
+                        else {
+                            this.logger.error(`There is no sourced dependency named: ${only}.`);
+                        }
+                    }
+                    else {
+                        for (let key in this._projCfg.submodules) {
+                            let sourcedDep = this._projCfg.submodules[key];
+                            let relPath = path.posix.join(dx_constants_1.DxConstants.SUBMODULES_DIR_NAME, sourcedDep.folderName);
+                            yield this.publishImages(relPath, branches[sourcedDep.packageName], publishingTarget, imagesToPublish, username, password);
+                        }
+                        yield this.publishImages("./", branches[this._projCfg.name], publishingTarget, imagesToPublish, username, password);
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    this.logger.debug(`If you get a "...interactive login from a non TTY device" failure from the docker login step...`, `\nIt means docker needs to ask you for your creds. EITHER set them using 'codiac images:add' OR do an 'az acr login --name myregistry'. For more info, see https://docs.microsoft.com/en-us/azure/container-registry/container-registry-authentication#individual-login-with-azure-ad`);
+                    reject(err);
+                }
+            }));
+        });
+    }
+    publishImages(relFolderPath, branch, publishingTarget, imagesToPublish, username, password) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                var _a;
+                try {
+                    this.logger.trace(`Running publishImages on [${this.styler.hilite(relFolderPath)}]...`);
+                    let projectRoot = this.getConfigRoot();
+                    let workingDir = path.join(projectRoot, relFolderPath);
+                    // let thisVersion = this.npmGetCurrentVersion(workingDir);
+                    // TODO:  GOtta look for a thaulconfig in the workingDir and if it exists, check for imageExports declared in it.
+                    if (fs.existsSync(path.posix.join(workingDir, codiac_ops_common_3.OpsConstants.PROJECT_CONFIG_FILENAME))) {
+                        let thisProjConfig = yield this.readCodiacProjectConfig(workingDir);
+                        let imageExports = thisProjConfig.images;
+                        if (imageExports) {
+                            let selectedImages;
+                            if (imagesToPublish && imagesToPublish.length > 0) {
+                                selectedImages = [...imagesToPublish];
+                            }
+                            else {
+                                selectedImages = _.keys(thisProjConfig.images);
+                            }
+                            for (let imageName of selectedImages) {
+                                let image = imageExports[imageName];
+                                if (image == undefined) {
+                                    this.logger.detail(`Could not find an imageExport named [${imageName}] in the project config.`);
+                                }
+                                else { // this is stupid - TODO: Get a non-nullable genericDict<T> into @codiac.io/codiac-common
+                                    if (!image.readonly) {
+                                        // let registry = image.targets.find(r => r.environment == targetEnvironment);
+                                        // if (!registry) registry = image.targets.find(r => r.environment == ImageExport.DEFAULT_ENVIRONMENT_NAME);
+                                        let registry = yield this.getTargetImageRegistry(image, publishingTarget, branch.name);
+                                        if (!registry) {
+                                            this.logger.warn(`No ${publishingTarget} registry was declared for the image: [${imageName}] that would apply to your current branch: [${branch.name}], and no default was set.  Operation cancelled.`);
+                                        }
+                                        else {
+                                            let tag = image.version || thisProjConfig.codeVersion; // Images can have their own independent version numbers, but default to the project code version.
+                                            // We're going to let docker hub's registry url stay silent
+                                            let fullImageId = registry.registryUrl ? `${registry.registryUrl}/${imageName}:${tag}` : `${imageName}:${tag}`;
+                                            // Apply the given tag
+                                            let cmd1 = `docker tag ${imageName}:${tag} ${fullImageId}`;
+                                            yield this._cliExec.execAsyncStdOut(cmd1, { cwd: workingDir });
+                                            // NOTE:  If you attempt to log into the local built in registry,
+                                            //        Docker will throw:  "Cannot perform a login from a non TTY device"
+                                            if (registry.registryUrl != codiac_relay_contracts_2.ImageExport.LOCAL_REGISTRY_URL) {
+                                                if (registry.registryUrl.endsWith(`.azurecr.io`)) {
+                                                    let result = yield this.pushToAzure(fullImageId, registry.registryUrl);
+                                                    if (result.error)
+                                                        throw result.error;
+                                                    if (result.success !== true) {
+                                                        this.logger.notice(`Failed without error pushing to Azure: ${(_a = result.message) !== null && _a !== void 0 ? _a : "(no details available)"}`);
+                                                    }
+                                                }
+                                                else {
+                                                    if (username == undefined || password == undefined) {
+                                                        this.ux.userMessage(`Credentials for registry [${this.styler.hilite(registry.registryUrl)}]...`);
+                                                    }
+                                                    let regUser = username !== null && username !== void 0 ? username : (yield this.ux.prompt(`regUser`, `Username: `, true, registry.username));
+                                                    let regSecret = password !== null && password !== void 0 ? password : (yield this.ux.promptPassword(`regUser`, `Password/Token: `, registry.password));
+                                                    ;
+                                                    // login to the registry (unless it's the builtin)
+                                                    this.ux.userMessage(`Logging docker into registry [${this.styler.hilite(registry.registryUrl)}]...`);
+                                                    // let cmd2 = `docker login ${registry.registryUrl} -u ${regUser} -p ${regSecret}`;  
+                                                    // await this._cliExec.spawnAndLog(cmd2, workingDir, { REG_PWD: regSecret }, LogLevel.detail);
+                                                    // NOTE: This execution requires a bash shell
+                                                    let cmd2 = `echo $REG_PWD | docker login ${registry.registryUrl} -u ${regUser} --password-stdin`;
+                                                    yield this._cliExec.execAsync(cmd2, { cwd: workingDir, shell: "bash", env: { REG_PWD: regSecret } });
+                                                    // Push the image
+                                                    this.ux.userMessage(`Pushing [${this.styler.hilite(imageName)}] to ${registry.environment} registry as [${this.styler.hilite(fullImageId)}]...`);
+                                                    let cmd3 = `docker push ${fullImageId}`;
+                                                    yield this._cliExec.spawnAndLog(cmd3, workingDir, undefined, IBetterLogger_1.LogLevel.detail);
+                                                }
+                                            }
+                                            else {
+                                                // Push the image
+                                                this.ux.userMessage(`Pushing [${this.styler.hilite(imageName)}] to ${registry.environment} registry as [${this.styler.hilite(fullImageId)}]...`);
+                                                let cmd4 = `docker push ${fullImageId}`;
+                                                yield this._cliExec.spawnAndLog(cmd4, workingDir, undefined, IBetterLogger_1.LogLevel.detail);
+                                                // let pushResult = await this._cliExec.execAsyncStdOut(cmd3, { cwd: workingDir }, LogLevel.detail);
+                                            }
+                                            // this.logger.trace(`${fullImageId}`);
+                                            this.ux.userMessage(this.styler.colorGood("COMPLETE!"));
+                                        }
+                                    }
+                                    else {
+                                        this.logger.debug(`Skipping publish for readonly image: ${imageName}.`);
+                                    }
+                                }
+                            }
+                        }
+                        else {
+                            this.logger.detail(`No image exports are declared for [${relFolderPath}].`, `Use 'codiac images:add' to do so.`);
+                        }
+                    }
+                    else {
+                        this.logger.detail(`No images to publish in [${relFolderPath}].`, `Did not find a ${codiac_ops_common_3.OpsConstants.PROJECT_CONFIG_FILENAME} in folder: ${workingDir}, in which images must be declared, so no images can be published.  You must initialize the folder as a Codiac project and then use "codiac images:add" to declare image exports for it. `);
+                    }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    pushLegacy() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            try {
+                // // ---Relay-only operations classes---------------------------------------------------------------------------------------------
+                // let clientsFactory = this.ioc.get<ImageRegistryClientsFactory>(ImageRegistryClientsFactory);
+                // var regClient = clientsFactory.createForDomain(registry.registryUrl);
+                // let pushResult = await regClient.push(imageName, tag);
+                // if (pushResult.error) {
+                //   this.logger.error(`Error pushing ${imageName}: ${pushResult.error.name ?? ""} ${pushResult.error.message ?? pushResult.error.stack}`, pushResult.error);
+                // }
+                // // ---Legacy Registry client---------------------------------------------------------------------------------------------
+                // let regClient = new CompositeImageRegistryClient(this.ioc);
+                // await regClient.push(registry.registryUrl, imageName, tag);
+                // // ---Hardcoded for Azure---------------------------------------------------------------------------------------------
+                // let userArg = (registry.username) ? ` -u ${registry.username}` : ``;
+                // let passArg = (registry.password) ? ` -p ${registry.password}` : ``;
+                // let cmdLogin: string;
+                // let loginEnv: { [key: string]: any } = { ...process.env };
+                // if (!userArg && !passArg && registry.registryUrl.endsWith(".azurecr.io")) {
+                //   cmdLogin = `az acr login --name ${registry.registryUrl.split(".")[0]}`
+                // }  else {
+                //   // let regToken = "8c307c0b-e0ae-4945-9567-1da692b99322";
+                //   // userArg = `-u "<token>"`; // nope that only works when using a credentials store.
+                //   loginEnv.registry_pwd = registry.password;
+                //   cmdLogin = `echo $registry_pwd | docker login ${registry.registryUrl} ${userArg} --password-stdin`;
+                // }
+                // this.logger.notice(`Logging in and pushing [${this.styler.hilite(imageName)}] to ${registry.environment} registry as [${this.styler.hilite(fullImageId)}]...`);
+                // let cmdLoginAndPush = cmdLogin.concat(`  &&  docker push ${fullImageId}`);
+                // await this._cliExec.spawnAndLog(cmdLoginAndPush, workingDir, loginEnv, LogLevel.detail);
+                // // let pushResult = await this._cliExec.execAsyncStdOut(cmdLoginAndPush, { cwd: workingDir, env: loginEnv });
+                // // TODO:  allow authentication to fail and prompt the user for creds and then save em down in cfg.  
+                // // ------------------------------------------------------------------------------------------------
+                return;
+            }
+            catch (err) {
+                throw err;
+            }
+        });
+    }
+    /** This was lifted Copy-Paste from AzureContainerRegistryClient in the relay. */
+    pushToAzure(fullImageId, registryDomain) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const result = new contracts_1.Result(false);
+                try {
+                    // if (!Boolean(registryDomain))
+                    //   throw new CodiacError('Registry URL is required for push method of AzureContainerRegistryClient.')
+                    // let fullImageId = `${this.acrConnection.registryDomainName}/${imageName}:${tag}`;
+                    // await this.setRelevantAzSubscription();  // <--- this is no longer doing anything...
+                    // Does this select the right az creds?  How can it?  
+                    // TODO: We need to save the subscription Id with the codiac project, so we can select prevent az account mismatches.
+                    //       Q: When would we gather the subscriptionId?  A: Upon image declaration (and then whenever we mod the registry for it)
+                    let cmdLogin = `az acr login --name ${(registryDomain !== null && registryDomain !== void 0 ? registryDomain : '').split(".")[0]}`;
+                    let loginEnv = Object.assign({}, process.env);
+                    let workingDir = process.cwd();
+                    // this.logger.notice(`Logging in and pushing [${this.styler.hilite(scopedImageName)}] to registry as [${this.styler.hilite(fullImageId)}]...`);
+                    this.logger.notice(`Logging in and pushing [${fullImageId}] to registry...`);
+                    let cmdLoginAndPush = cmdLogin.concat(`  &&  docker push ${fullImageId}`);
+                    yield this._cliExec.spawnAndLog(cmdLoginAndPush, workingDir, loginEnv, IBetterLogger_1.LogLevel.detail);
+                    result.success = true;
+                }
+                catch (error) {
+                    result.error = error;
+                    result.message = `Error pushing image "${fullImageId}" to [${registryDomain}]: ${(_a = error.name) !== null && _a !== void 0 ? _a : ""} ${(_b = error.message) !== null && _b !== void 0 ? _b : ""}.`;
+                }
+                finally {
+                    resolve(result);
+                }
+            }));
+        });
+    }
+    /** Ensures that the current azure subscription matches the one that owns the registry for the given image. */
+    setRelevantAzSubscription() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                try {
+                    // TIP:  When outputting a single value from an az cli command, use "-o tsv" to remove the quotes from the output. 
+                    let whoami = `az account show -o json`; // retrieves current az username
+                    let azTenantUser = yield this._cliExec.execAsyncJson(whoami, { cwd: process.cwd() }, IBetterLogger_1.LogLevel.debug);
+                    this.logger.debug(`Current Azure user subscription: ${azTenantUser.name}, ${azTenantUser.id}`, azTenantUser);
+                    // TODO:  Enforce consistency betw AZ subscriptionId for the project and the current azure account
+                    // if (azTenantUser.id != this.subxIdForRegistry) {
+                    //   // let getMySubs = `az account list --query "[?id == '${subxIdForRegistry}']" -o json`;
+                    //   // let mySubs = await this._cliExec.execAsyncJson<AzureTenantUser[]>(getMySubs, { cwd: process.cwd() }, LogLevel.debug);
+                    //   // if (mySubs.length > 0) {
+                    //   //   // Switch to the relevant account
+                    //   //   let setSubx = `az account set --subscription ${subxIdForRegistry}`;  
+                    //   //   azTenantUser = await this._cliExec.execAsyncJson<AzureTenantUser>(setSubx, { cwd: process.cwd() }, LogLevel.debug);
+                    //   // }
+                    // }
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }));
+        });
+    }
+    /** Fires off the given commands
+   * and commits the changes to source control.
+   * @param commands The list of cli statements to execute
+   * @param desc The comment applied to the commit; should be a description of the overall operation.
+   * @param workingDirectory The fully qualified path from which to run the given commands and the source control commit statements...
+   */
+    execAndCommit(commands, desc, workingDirectory) {
+        return new Promise((resolve, reject) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            try {
+                let execOptions = { cwd: workingDirectory };
+                yield this._cliExec.execMany(commands, desc, execOptions);
+                if (yield this.gitHasChanges(workingDirectory)) {
+                    yield this._cliExec.execAsyncStdOut(`git add -A`, execOptions);
+                    yield this._cliExec.execAsyncStdOut(`git commit -m '${desc}'`, execOptions);
+                }
+                resolve();
+            }
+            catch (err) {
+                reject(err);
+            }
+        }));
+    }
+};
+LocalOps = tslib_1.__decorate([
+    (0, inversify_1.injectable)(),
+    tslib_1.__metadata("design:paramtypes", [inversify_1.Container
+        // , @inject(CliEnviro) public cliEnviro: CliEnviro
+        // , @inject(ProjectEnviro) private projEnviro: ProjectEnviro
+        // , @inject(CliContextRepo) private _cfgRepo: CliContextRepo
+        // , @inject(INTERFACES_OPS.IUserInputProvider) private ux: IUserInputProvider
+        // , @inject(INTERFACES_OPS.IOutputStyler) private styler: IOutputStyler
+        // , @inject(CliExec) private _cliExec: CliExec
+        // , @inject(INTERFACES.IBetterLogger) private logger: IBetterLogger    
+    ])
+], LocalOps);
+exports.LocalOps = LocalOps;
+//# sourceMappingURL=LocalOps.js.map