@sap/cds-dk 4.6.4 → 4.8.0

package/lib/init/template/xsuaa/files/mta.yaml.hbs

@@ -0,0 +1,17 @@
+---
+modules:
+  - name: {{cap.appName}}-srv
+    type: {{cap.pLanguage}}
+    requires:
+      - name: {{cap.appName}}-uaa
+
+resources:
+  - name: {{cap.appName}}-uaa{{#cap.isMultitenant}}-mt{{/cap.isMultitenant}}
+    type: org.cloudfoundry.managed-service
+    parameters:
+      service: xsuaa
+      service-plan: application
+      path: ./xs-security.json
+      config:
+        xsappname: {{cap.appName}}-${org}-${space}
+        tenant-mode: {{#cap.isMultitenant}}shared{{/cap.isMultitenant}}{{^cap.isMultitenant}}dedicated{{/cap.isMultitenant}}

package/lib/init/template/xsuaa/index.js

@@ -0,0 +1,75 @@
+const TemplateBase = require('../templateBase')
+const ProjectReader = require('../../util/projectReader')
+const { fse } = require('@sap/cds-foss')
+const path = require('path')
+const { srvNode, srvJava, xsuaa } = require('../_merging/existences');
+
+module.exports = class XsuaaTemplate extends TemplateBase {
+    constructor(projectPath, generator) {
+        super(projectPath, generator, __dirname)
+        this.projectReader = new ProjectReader(this)
+    }
+
+    async runMTAMerging() {
+        const projectDescriptor = await this.projectReader.read(this.options)
+        const {projectPath} = this
+        const mtaYAMLPath = path.join(projectPath, 'mta.yaml')
+        if (!fse.existsSync(mtaYAMLPath)) {
+            console.warn(`There is no MTA file in your project. Run \`cds add mta\` to add an MTA file or create the XSUAA services yourself.`)
+            return
+        }
+        const srv = projectDescriptor.cap.isNodejs ? srvNode : srvJava
+        await this.templateUtil.mergeYAML(
+            mtaYAMLPath,
+            `${__dirname}/files/mta.yaml.hbs`,
+            projectDescriptor,
+            {
+                existences: [srv, xsuaa],
+                relationships: [{
+                    in: srv.ref,
+                    inKeyPath: ["requires"],
+                    into: "name",
+                    existences: [xsuaa.ref],
+                    existenceKeyPath: ["name"],
+                }],
+            }
+        )
+
+        // Re-applying the merging part of `cds add mtx` because cds.compile.to.xsuaa
+        // has overwritten the existing `xs-security.json`.
+        // TODO: Find a generic solution for situation like these.
+        if (projectDescriptor.cap.isMultitenant) {
+            const MtxTemplate = require(`../mtx`)
+            const mtxTemplate = new MtxTemplate(this.projectPath, this.generator)
+            await mtxTemplate.runMTAMerging()
+        }
+    }
+
+    async run() {
+        const {projectPath} = this
+        const templatePath = path.join(__dirname, 'files')
+        const packageJSONPath = path.join(projectPath, 'package.json')
+        await this.templateUtil.mergeJSON(packageJSONPath, `${templatePath}/cds.package.json`)
+        await this.templateUtil.mergeJSON(packageJSONPath, `${templatePath}/dependencies.package.json`)
+        const xsSecurityPath = path.join(projectPath, 'xs-security.json')
+        const cds = require('../../../../lib/compile')
+        const xsuaa = await (async () => { try {
+            const models = await cds.load(`${projectPath}/srv`)
+            return cds.compile.to.xsuaa(models)
+        } catch (error) { /* ignore */ }
+        })() || { scopes: [], attributes: [], 'role-templates': [] }
+        const projectDescriptor = await this.projectReader.read(this.options)
+        await this.fsUtil.writeJSON(xsSecurityPath, xsuaa)
+
+        // TODO: Get rid of this by auto-creating a merging definition from
+        // the current xs-security.json. This should also solve role-templates
+        // being thrown out
+        if (projectDescriptor.cap.isMultitenant) {
+            const MtxTemplate = require(`../mtx`)
+            const mtxTemplate = new MtxTemplate(this.projectPath, this.generator)
+            await mtxTemplate.runXSSecurityMerging()
+        }
+
+        await this.runMTAMerging()
+    }
+}

package/lib/init/util/fsUtil.js

@@ -1,6 +1,6 @@
 const path = require('path');
 
-const {fse} = require('@sap/cds-foss')
+const {fse, yaml} = require('@sap/cds-foss')
 const JSONC = require('../../util/jsonc');
 
 const UTF_8 = 'utf-8';
@@ -18,13 +18,17 @@ module.exports = class FsUtil {
         await fse.outputFile(filepath, content, UTF_8);
     }
 
-    async writeJSON(filepath, object, options = { spaces: 4 }, skipFileLog = false) {
+    async writeJSON(filepath, object, options = { spaces: 2 }, skipFileLog = false) {
         if (!skipFileLog) {
             this._addTouchedFile(filepath);
         }
         await fse.outputJSON(filepath, object, options);
     }
 
+    async writeYAML(filepath, yaml, skipFileLog = false) {
+        await this.writeFile(filepath, String(yaml), skipFileLog);
+    }
+
     async readFile(src) {
         return await fse.readFile(src, UTF_8);
     }
@@ -34,8 +38,18 @@ module.exports = class FsUtil {
     }
 
     async readJSONC(src) {
-        const fileConents = await this.readFile(src);
-        return JSONC.parse(fileConents);
+        const fileContents = await this.readFile(src);
+        return JSONC.parse(fileContents);
+    }
+
+    async readYAML(src, projectDescriptor) {
+        const file = await this.readFile(src);
+        if (projectDescriptor) {
+            const Mustache = require('mustache');
+            const renderedFile = Mustache.render(file, projectDescriptor);
+            return yaml.parseDocument(renderedFile);
+        }
+        return yaml.parseDocument(file);
     }
 
     async copy(source, destination, options = {}, skipFileLog = false) {

package/lib/init/util/logger.js

@@ -12,7 +12,9 @@ const defaultLogger = {
     },
 
     log: (message = '') => {
-        LOG.log(message);
+        if (typeof LOG.level !== 'number' || LOG.level > 0) {
+            console.log(message);
+        }
     },
 
     warn: (message = '') => {

package/lib/init/util/mvnArchetypeUtil.js

@@ -31,7 +31,9 @@ class MvnArchetypeUtil {
 
         params.set('-B');
 
-        defaultLogger.isDebug && params.set('-X');
+        if (defaultLogger.isDebug) {
+            params.set('-X'); params.set('-e');
+        }
 
         return Array.from(params, (e) => {
             let result = e[0];

package/lib/init/{template/mta → util}/projectReader.js

@@ -1,5 +1,5 @@
 const path = require('path')
-const { nullLogger } = require('../../util/logger')
+const { nullLogger } = require('../util/logger')
 const { BuildTaskFactory } = require('@sap/cds/bin/build')
 const P_LANGUAGE_JAVA = 'java'
 const P_LANGUAGE_NODEJS = 'nodejs'
@@ -41,11 +41,11 @@ module.exports = class ProjectReader {
         return this.template.projectPath
     }
 
-    async read() {
+    async read(options) {
         const env = await this.getEnv();
         this.logger.isDebug && this.logger.debug(JSON.stringify(env, null, 1))
 
-        const capDescriptor = await this._getCapDescriptor(env)
+        const capDescriptor = await this._getCapDescriptor(env, options)
         const uiDescriptor = await this._getUiDescriptor(env)
         const projectDescriptor = {
             cap: capDescriptor,
@@ -58,14 +58,14 @@ module.exports = class ProjectReader {
         return projectDescriptor
     }
 
-    async _getCapDescriptor(env) {
+    async _getCapDescriptor(env, options) {
         let capDescriptor = {
             pLanguage: DEFAULT_P_LANGUAGE,
             srv: {},
             db: [],
             requires: [],
             get isMultitenant() {
-                return env.requires.multitenancy || env.requires.db && env.requires.db.multiTenant || false
+                return options && options.add.has('mtx') || env.requires.multitenancy || env.requires.db && env.requires.db.multiTenant || false
             },
             get isNodejs() {
                 return this.pLanguage === P_LANGUAGE_NODEJS
@@ -79,10 +79,15 @@ module.exports = class ProjectReader {
             get hasRequiresDb() {
                 return this.db.length > 0
             },
-            get needsSidecar() {
-                // {{#if (and (gt cap.db.length 0) (or (eq cap.pLanguage 'java') (ne cap.isMultitenant true) ) ) }}
-                return this.db.length > 0 && (this.isJava || !this.isMultitenant)
+            get hasHana() {
+                return this.requires.some(({resource}) => resource.isHana)
+            },
+            get hasXsuaa() {
+                return this.requires.some(({resource}) => resource.isXsuaa)
             },
+            get needsSidecar() {
+                return (options && options.add.has('hana') || this.db.length > 0) && (this.isJava || !this.isMultitenant)
+            }
         }
 
         // setting the effective env as it might have changed by already executed 'add' commands, e.g. cds init foo --add hana,mta
@@ -169,9 +174,19 @@ module.exports = class ProjectReader {
             appPath: null
         }
 
-        if (await this.fsUtil.pathExists(path.join(this.projectPath, env.folders.app))) {
+        const absoluteAppPath = path.join(this.projectPath, env.folders.app)
+        if (await this.fsUtil.pathExists(absoluteAppPath)) {
             uiDescriptor.appPath = env.folders.app
         }
+
+        const packageJson = await (async () => { try {
+            return await this.fsUtil.readFile(absoluteAppPath+'package.json')
+        } catch(error) { /* ignore */ }
+        })()
+
+        if (packageJson && packageJson.dependencies) {
+            uiDescriptor.appRouterEnabled = packageJson.dependencies['@sap/approuter'] !== undefined
+        }
         return uiDescriptor
     }
 
@@ -366,7 +381,7 @@ module.exports = class ProjectReader {
                 // use different service name to avoid conflicts when switching from single tenant to multitenant
                 // otherwise we would enforce that users have to delete the db container first
                 if (resource.isMultitenant) {
-                    resource.name += '-mt'
+                    //resource.name += '-mt'
                     resource.service = 'service-manager'
                     resource.vcap.plan = 'container'
                 } else {
@@ -459,7 +474,7 @@ module.exports = class ProjectReader {
                 }))
             }
         } else {
-            this.logger.warn(`No SAP HANA service binding defined in the requires section of the project's package.json. Database module omitted`) //NOSONAR
+            //this.logger.warn(`No SAP HANA service binding defined in the requires section of the project's package.json. Database module omitted`) //NOSONAR
         }
     }
 

package/lib/init/util/templateUtil.js

@@ -1,5 +1,5 @@
 const path = require('path');
-
+const YAML = require('@sap/cds-foss')('yaml');
 const Mustache = require('mustache');
 
 const TEMPLATE_EXTENSION = '.hbs';
@@ -41,7 +41,7 @@ module.exports = class TemplateUtil {
     }
 
     async _processTemplateFile(src, templateValues) {
-        let content = await this.fsUtil.readFile(src);
+        const content = await this.fsUtil.readFile(src);
         return Mustache.render(content, templateValues);
     }
 
@@ -52,4 +52,268 @@ module.exports = class TemplateUtil {
     _isTemplateFile(filename) {
         return path.extname(filename) === TEMPLATE_EXTENSION;
     }
-}
+
+    /*
+    Will do a syntactic merge when `semantics` is undefined.
+    Syntactic merges are sufficient in some cases,
+    e.g merging dependencies in a package.json, as they are
+    just maps where you can do a key-value replacement.
+    */
+    _deepMerge(target, source) {
+        if (this._isObject(target) && this._isObject(source)) {
+            for (const key in source) {
+                if (this._isObject(source[key])) {
+                    if (!target[key]) Object.assign(target, { [key]: source[key] });
+                    if ('#overwrite' in source[key]) Object.assign(target, { [key]: source[key]["#overwrite"] })
+                    else this._deepMerge(target[key], source[key]);
+                } else if (Array.isArray(source[key]) && Array.isArray(target[key])) {
+                    const unique = array => [...new Set(array.map(JSON.stringify))].map(JSON.parse);
+                    target[key] = unique([...source[key], ...target[key]])
+                } else {
+                    Object.assign(target, { [key]: target[key] || source[key] });
+                }
+            }
+        } else if (Array.isArray(target) && Array.isArray(source)) {
+            const unique = array => [...new Set(array.map(JSON.stringify))].map(JSON.parse);
+            target = unique([...source, ...target])
+        }
+        return target || source;
+    }
+
+    async mergeJSON(targetPath, sourcePath, projectDescriptor, semantics) {
+        const source = await this.fsUtil.readJSON(sourcePath, projectDescriptor)
+
+        if (! await this.fsUtil.pathExists(targetPath)) {
+            await this.fsUtil.writeJSON(targetPath, source);
+        } else if (semantics) {
+            const target = await this.fsUtil.readJSON(targetPath)
+
+            if (!target) return // Has no JSON file
+
+            const targetYAML = await YAML.parseDocument(YAML.stringify(target))
+            const sourceYAML = await YAML.parseDocument(YAML.stringify(source))
+            const resultYAML = await this.mergeYAML(targetYAML, sourceYAML, projectDescriptor, semantics)
+            const result = YAML.parse(YAML.stringify(resultYAML))
+            await this.fsUtil.writeJSON(targetPath, result)
+        } else {
+            const target = await this.fsUtil.readJSON(targetPath);
+            const sourceFile = await this._processTemplateFile(sourcePath, projectDescriptor);
+            const source = JSON.parse(sourceFile);
+            const result = target && source ? this._deepMerge(target, source) : target || source;
+            await this.fsUtil.writeJSON(targetPath, result);
+        }
+    }
+
+    async mergeYAML(into, from, projectDescriptor, semantics) {
+        const target = typeof into === 'string' ? await this.fsUtil.readYAML(into) : into
+        const source = typeof from === 'string' ? await this.fsUtil.readYAML(from, projectDescriptor) : from
+
+        if (!target || !target.contents) return // Has no YAML file
+
+        const existenceMap = new Map()
+        const templateExistenceMap = new Map()
+
+        const existences = semantics.existences && semantics.existences.filter(e => e)
+
+        existences && existences.forEach(existence => {
+            existenceMap.set(existence.ref, undefined)
+            templateExistenceMap.set(existence.ref, undefined)
+        });
+
+        const missingRelationshipsMap = new Map()
+
+        const relationships = semantics.relationships && semantics.relationships.filter(r => r)
+        relationships && relationships.forEach(relationship =>
+            missingRelationshipsMap.set(relationship.in, undefined)
+        )
+
+        let collectionStack = [target.contents]
+
+        const _getProperty = (object, keyPath) => keyPath.reduce((p, n) => p && p[n], object)
+        const _getYAMLProperty = (object, keyPath) => keyPath.reduce((p, n) => p && p.get(n), object)
+
+        const _validateConstraints = (node, dict, index) => {
+            existences.forEach(existence => {
+                const json = JSON.parse(String(node))
+                const constraintsFulfilled = existence.constraints.every(constraint =>
+                    constraint.value === _getProperty(json, constraint.comparisonKeyPath)
+                )
+                if (constraintsFulfilled) dict.set(existence.ref, { json, node, index })
+            })
+        }
+
+        function _traverseYAMLNode(node, index, actions, templateNode) {
+            let shifted = false
+            switch (node.type) {
+                case 'MAP':
+                    actions && actions.visitMap && actions.visitMap(node, index)
+                    if (collectionStack[0] && collectionStack[0].type === 'SEQ') { collectionStack.unshift(node); shifted = true}
+                    break;
+                case 'SEQ':
+                    break;
+                case 'PAIR':
+                    if (node.value && node.value.items) collectionStack.unshift(node.value)
+                    break;
+                case 'PLAIN':
+                    break;
+            }
+
+            if (node.items) {
+                if ((node.type === 'SEQ' || node.type === 'FLOW_SEQ') && templateNode && templateNode.items) {
+                    actions.mergeCollection && actions.mergeCollection(node, templateNode)
+                    node.type === 'SEQ' && _traverseYAMLCollection(node, actions, templateNode)
+                } else {
+                    _traverseYAMLCollection(node, actions, templateNode)
+                }
+            } else if (node.value && node.value.items) {
+                _traverseYAMLNode(node.value, index, actions, templateNode && templateNode.value)
+            }
+
+            if (node.value && node.value.items || shifted) {
+                collectionStack.shift()
+            }
+        }
+        _traverseYAMLNode.bind(this)
+
+        const _traverseYAMLCollection = (collection, actions, templateCollection) => {
+            if (!collection) return
+
+            const keyIndexMap = new Map()
+            const templateIndexMap = new Map()
+
+            // Map collection items to their semantic counterpart(s)
+            collection.items.forEach((node, i) => {
+                if (node.key) keyIndexMap.set(node.key.value, i)
+                const existence = [...existenceMap.entries()].find(([,value]) => value && value.node === node)
+                if (existence) {
+                    const [existenceKey] = existence
+                    const templateExistence = existenceKey && templateExistenceMap.get(existenceKey)
+                    const templateIndex = templateExistence && templateExistence.index
+                    if (templateIndex !== undefined) templateIndexMap.set(templateIndex, i)
+                }
+                if (!templateCollection) _traverseYAMLNode(node, i, actions)
+            });
+
+            if (!templateCollection) return
+
+            templateCollection.items.forEach((templateNode, templateIndex) => {
+                if (templateNode.type === 'PAIR') {
+                    const i = keyIndexMap.get(templateNode.key.value)
+                    const [collection] = collectionStack
+                    const targetNode = collection.items && collection.items[i]
+                    if (targetNode) {
+                        _traverseYAMLNode(targetNode, templateIndex, actions, templateNode)
+                    } else if (actions.mergePair) {
+                        actions.mergePair(collection, templateNode)
+                    }
+                } else if (templateNode.type === 'MAP') {
+                    const targetNode = collection.items[templateIndexMap.get(templateIndex)]
+                    if (actions.mergeCollection) actions.mergeCollection(targetNode, templateNode)
+                    if (targetNode) {
+                        _traverseYAMLNode(targetNode, templateIndex, actions, templateNode);
+                    } else if (!actions.mergeCollection) {
+                        collection.add(YAML.createNode(templateNode))
+                        //this.fsUtil.writeYAML(targetPath, target)
+                    }
+                }
+            })
+        }
+        _traverseYAMLCollection.bind(this)
+
+        // 1. Validate the existences in the template
+        _traverseYAMLNode(source.contents, null, {
+            visitMap: (node, index) => {
+                _validateConstraints(node, templateExistenceMap, index)
+            }
+        })
+
+        // 2. Validate the existences in the project
+        _traverseYAMLNode(target.contents, null, {
+            visitMap: (node, index) => {
+                _validateConstraints(node, existenceMap, index)
+            }
+        })
+
+        // 3. Apply overwrites to already found existences
+        semantics.overwrites && semantics.overwrites.forEach(({ in: ref, keyPath, replacement }) => {
+            const existence = existenceMap.get(ref)
+            if (existence) {
+                _getYAMLProperty(existence.node, keyPath.slice(0, keyPath.length - 1))
+                    .set(keyPath[keyPath.length - 1], replacement)
+            }
+        })
+
+        // 4. Create missing existences and pairs
+        _traverseYAMLNode(target.contents, null, {
+            mergePair: (collection, templateNode) => {
+                const childIsArray = false//templateNode.value.type !== 'MAP' && !!templateNode.value.items
+                if (collection.type === 'MAP' && !childIsArray) {
+                    collection.add(YAML.createNode(templateNode))
+                    //this.fsUtil.writeYAML(targetPath, target)
+                }
+            },
+            mergeCollection: (targetNode, templateNode) => {
+                if (templateNode.type === 'SEQ' || templateNode.type === 'FLOW_SEQ') {
+                    const [,parent] = collectionStack
+                    const missingExistences = semantics.existences
+                        .filter(e => e)
+                        .filter(existence =>
+                            parent.get(existence.keyPath[0]) === targetNode
+                        ).filter(existence =>
+                            !existenceMap.get(existence.ref)
+                        )
+                    missingExistences.forEach(existence => {
+                        const templateExistence = YAML.createNode(templateExistenceMap.get(existence.ref).node)
+                        templateExistence.spaceBefore = existence.spaceBefore
+                        targetNode.add(templateExistence)
+                        existenceMap.set(existence.ref, templateExistence)
+                        //this.fsUtil.writeYAML(targetPath, target)
+                    })
+                }
+            },
+        }, source.contents)
+
+        // 5. Re-validate the existences in the project
+        _traverseYAMLNode(target.contents, null, {
+            visitMap: (node, index) => {
+                _validateConstraints(node, existenceMap, index)
+            }
+        })
+
+        // 6. Create missing relationships
+        _traverseYAMLNode(target.contents, null, {
+            mergeCollection: (targetNode, templateNode) => {
+                if (templateNode.type === 'SEQ') {
+                    const targetJSON = YAML.parse(String(targetNode))
+                    const relationship = semantics.relationships && semantics.relationships
+                        .filter(r => r)
+                        .find(relationship => {
+                            const existingNode = _getYAMLProperty(existenceMap.get(relationship.in).node, relationship.inKeyPath)
+                            return targetNode === existingNode
+                    })
+                    if (!relationship) return
+
+                    const missingPairs = relationship.existences
+                        .filter(existenceKey =>
+                            !targetJSON.some(item =>
+                                _getProperty(existenceMap.get(existenceKey).json, relationship.existenceKeyPath) === item[relationship.into]
+                            )
+                        )
+                        .map(existenceKey => existenceMap.get(existenceKey).node.get(relationship.into))
+                    missingPairs.forEach(pair => {
+                        targetNode.add(YAML.createNode({ [relationship.into]: pair }))
+                        //await this.fsUtil.writeYAML(targetPath, target)
+                    })
+                }
+            }
+        }, source.contents)
+
+        typeof into === 'string' && await this.fsUtil.writeYAML(into, target)
+        return target
+    }
+
+    _isObject(item) {
+        return item && typeof item === 'object' && !Array.isArray(item)
+    }
+};
+

package/lib/lint/Linter.js

@@ -23,7 +23,6 @@ class Linter {
     this.eslintCmdOpts = {};
     this.eslintCmdOptsIndex = 0;
     this.eslintCmdFileExpr = "";
-    this.formatter = false;
     this.isFile = false;
     this.help = "";
     this.debug = "";
@@ -141,7 +140,7 @@ class Linter {
 
   _addExtensions() {
     // Add CDS file extensions to lint
-    const extensions = ALLOWED_FILE_EXTENSIONS.map((ext) => ext.replace('*.', '.'));
+    const extensions = ALLOWED_FILE_EXTENSIONS.map((ext) => path.extname(ext));
     this.eslintCmdOpts = io.mergeWithUserOpts(
       this.eslintCmdOpts,
       "ext",

package/lib/lint/io.js

@@ -22,7 +22,7 @@ module.exports = {
       case ".eslintrc.js":
       case ".eslintrc.cjs":
         try {
-          config = JSON.parse(configString.replace(/^module\.exports =/, ""));
+          config = JSONC.parse((configString.replace(/^module\.exports =/, "")));
         } catch (err) {
           config = {};
         }
@@ -33,7 +33,7 @@ module.exports = {
         break;
       case ".eslintrc.json":
       case ".eslintrc":
-        config = JSON.parse(await fsp.readFile(configPath, "utf8"));
+        config = await fsUtil.readJSONC(configPath);
         break;
       case "package.json":
         config = JSON.parse(await fsp.readFile(configPath, "utf8"));
@@ -201,18 +201,9 @@ module.exports = {
    * (3) "Global" case adds configFile and removes rulePaths
    * @param {*} settingsPath VS Code settings file
    */
-  async sanitizeVscodeSettings(projectPath, settingsPath, lintType, customRuleExample = false) {
+  async sanitizeVscodeSettings(projectPath, settingsPath, lintType, lintFileTypes, customRuleExample = false) {
     let settings = (await this.readVscodeSettings(settingsPath)) || {};
-    const lintFileTypes = ["cds", "csn"];
     const rulePaths = [path.join(".eslint/rules")];
-    const configFile = path.join(__dirname, ".eslintrc.js");
-
-    function _addArrayOrString(array) {
-      if (array.length === 1) {
-        return array[0];
-      }
-      return array;
-    }
 
     if (settings["eslint.validate"]) {
       settings["eslint.validate"] = this.mergeArrays(settings["eslint.validate"], lintFileTypes);

package/lib/util/exec.d.ts

@@ -0,0 +1,54 @@
+/*
+ * Typings only for common use cases
+ */
+
+interface AdditionalExecOptions {
+    acceptStatuses? : Array<Number> | '*',
+    appendEnv?: {[key: string]: string},
+    log?: object
+}
+
+interface SpawnReturns {
+    status : number,
+    stdout? : string,
+    stderr? : string
+}
+
+import { SpawnOptions, SpawnSyncOptions, SpawnSyncReturns } from "child_process";
+
+type execTemplate<T> = (template: TemplateStringsArray, ...args : any[]) => T;
+
+/**
+ * Execute commands with template strings asynchronously.
+ *
+ * @example
+ *
+ * await exec `ls -l .`
+ * await exec `ls -l ${'spaces are safe in expressions'}` => spawn('ls', [ '-l', 'spaces are safe in expressions' ])
+ * await exec `ls -l "dir ${'with spaces'}"
+ * await exec `ls -l ${['db', 'srv']}`
+ * const out = (await exec({stdio: ['inherit', 'pipe', 'inherit']}) `ls -l`).stdout
+ * const out = await exec({result: 'stdout}) `ls -l`
+ */
+export function exec( template : TemplateStringsArray, ...args : any[] ) : Promise<SpawnReturns>
+export function exec( options : { result: 'stdout' | 'stderr' } & SpawnOptions & AdditionalExecOptions) : execTemplate<Promise<string>>;
+export function exec( options : SpawnOptions & AdditionalExecOptions) : execTemplate<Promise<SpawnReturns>>;
+
+/**
+ * Execute commands with template strings synchronously.
+ *
+ * @example
+ *
+ * execSync `ls -l .`
+ * execSync `ls -l ${'spaces are safe in expressions'}` => spawn('ls', [ '-l', 'spaces are safe in expressions' ])
+ * execSync `ls -l "dir ${'with spaces'}"
+ * execSync `ls -l ${['db', 'srv']}`
+ * const out = (execSync({stdio: ['inherit', 'pipe', 'inherit']}) `ls -l`).stdout
+ * const out = execSync({result: 'stdout}) `ls -l`
+ */
+export function execSync( template : TemplateStringsArray, ...args : any[] ) : SpawnSyncReturns<string>;
+export function execSync( options : { result: 'stdout' | 'stderr' } & SpawnSyncOptions & AdditionalExecOptions) : execTemplate<string>;
+export function execSync( options : { encoding : 'buffer' | null } & SpawnOptions & AdditionalExecOptions) : execTemplate<SpawnSyncReturns<Buffer>>;
+export function execSync( options : SpawnOptions & AdditionalExecOptions) : execTemplate<SpawnSyncReturns<string>>;
+
+export { execSync as $ };