elrh-cosca 0.2.7 → 0.3.0

package/README.md

@@ -25,7 +25,7 @@ Gets a file definition from given `templateFile` and will create a fresh copy in
 
 Path to `templateFile` must be prefixed with the package name to allow proper resolution, e.g. `your-package:path/to/template`. The package name can be scoped.
 
-Path to `targetFile` is relative to `process.cwd()` which allows consumers to run `npx your-script` in their project roots during development.
+Path to `targetFile` is relative to `process.cwd()` which allows consumers to run `npx your-script` in their project roots during development.  Several checks are in place to prevent accidental and malicious paths being passed in. Path traversal outside of CWD or providing absolute paths is disallowed. If the target directory does not exist, it will be automatically created.
 
 By default the function asks for confirmation before attempting to create the file and if the file with the same name as `targetFile` is detected. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts. Passsing a custom `prompt` allows tailoring your own question to the user.
 
@@ -41,7 +41,7 @@ Gets a file definition from given `url` and will create a fresh copy in target p
 
 Contents of `url` must be accessible via `node:https.get` function and will be fetched as raw text data.
 
-Path to `targetFile` is relative to `process.cwd()` which allows consumers to run `npx your-script` in their project roots during development.
+Path to `targetFile` is relative to `process.cwd()` which allows consumers to run `npx your-script` in their project roots during development.  Several checks are in place to prevent accidental and malicious paths being passed in. Path traversal outside of CWD or providing absolute paths is disallowed. If the target directory does not exist, it will be automatically created.
 
 By default the function asks for confirmation before attempting to create the file and if the file with the same name as `targetFile` is detected. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts. Passsing a custom `prompt` allows tailoring your own question to the user.
 
@@ -49,14 +49,14 @@ By default the function asks for confirmation before attempting to create the fi
 
 ```ts
 async function updateConfigFile(
-  pathToFile: string, newConfig: Record<string | number | symbol, any>, 
+  targetFile: string, newConfig: Record<string | number | symbol, any>, 
   force: boolean = false, prompt: string = ''
 ): Promise<void>
 ```
 
 Takes a path to a configuration file and updates it with the provided `newConfig` object. 
 
-Path to `targetFile` is relative to `process.cwd()`. The file currently must use ESM format with either `default` or named export of **exactly one** configuration object or function call with a configuration object as its argument.
+Path to `targetFile` is relative to `process.cwd()`. Several checks are in place to prevent accidental and malicious paths being passed in. Path traversal outside of CWD or providing absolute paths is disallowed. The file currently must use ESM format with either `default` or named export of **exactly one** configuration object or function call with a configuration object as its argument.
 
 The merger is performed using [unjs/magicast](https://github.com/unjs/magicast). It should:
 - preserve comments
@@ -66,20 +66,36 @@ The merger is performed using [unjs/magicast](https://github.com/unjs/magicast).
 - create a unique-union in case of arrays
 Please [report](https://github.com/AloisSeckar/elrh-cosca/issues) any logical flaws and issues of the process.
 
+**Warning**: The function will fail, if the extracted object is proxied (e.g. when created using `defu`). In such case, the error would be:
+
+```
+TypeError: 'set' on proxy: trap returned falsish for property '<YOUR_PROPERTY>'
+```
+
+If possible, you need to alter your logic, e.g. by creating a new object via the spread operator.
+
+
 By default the function asks for confirmation before attempting to alter the `targetFile`. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts. Passsing a custom `prompt` allows tailoring your own question to the user.
 
 #### `updateJsonFile`
 
 ```ts
 async function updateJsonFile(
-  pathToFile: string, jsonKey: string, newValues: Record<string | number | symbol, any>, 
+  targetFile: string, jsonKey: string, patch: JsonValue, 
   force: boolean = false, prompt: string = ''
 ): Promise<void>
 ```
 
-Takes a path to a JSON file and injects `newValues` under `jsonKey` key.
+Takes a path to a JSON file and injects `patch` under `jsonKey` key. A `patch` is of `JsonValue` - a custom type defined as follows:
+
+```ts
+type JsonPrimitive = string | number | boolean | null
+type JsonObject = { [key: string]: JsonValue }
+type JsonArray = JsonValue[]
+type JsonValue = JsonPrimitive | JsonObject | JsonArray
+```
 
-Path to `targetFile` is relative to `process.cwd()`. The file must be a valid JSON file. It is parsed using plain `JSON.parse`.
+Path to `targetFile` is relative to `process.cwd()`. Several checks are in place to prevent accidental and malicious paths being passed in. Path traversal outside of CWD or providing absolute paths is disallowed. The file must be a valid JSON file. It is parsed using plain `JSON.parse`.
 
 Currently it only allows adding new values under top-level keys. If the `jsonKey` exists, new values are merged into existing ones. Otherwise, new key is added. The function tracks if any real change was made and notifies the user if not.
 
@@ -89,14 +105,46 @@ By default the function asks for confirmation before attempting to alter the `ta
 
 ```ts
 async function updateTextFile(
-    pathToFile: string, rowsToAdd: string[], force: boolean = false, prompt: string = ''
+    targetFile: string, rowsToAdd: string[], force: boolean = false, prompt: string = ''
 ): Promise<void>
 ```
 
 Takes a path to a plain text file and injects `rowsToAdd` at the end of the file, **providing they are not already present in the file**. The function tracks if any real change was made and notifies the user if not.
 
+Path to `targetFile` is relative to `process.cwd()`. Several checks are in place to prevent accidental and malicious paths being passed in. Path traversal outside of CWD or providing absolute paths is disallowed. 
+
+By default the function asks for confirmation before attempting to alter the `targetFile`. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts. Passsing a custom `prompt` allows tailoring your own question to the user.
+
+#### `removeFromJsonFile`
+
+```ts
+async function removeFromJsonFile(
+  targetFile: string, jsonKey: string, force: boolean = false, prompt: string = ''
+): Promise<void>
+```
+
+Takes a path to a JSON file and removes the specified `jsonKey`.
+
+Path to `targetFile` is relative to `process.cwd()`. Several checks are in place to prevent accidental and malicious paths being passed in. Path traversal outside of CWD or providing absolute paths is disallowed. The file must be a valid JSON file. It is parsed using plain `JSON.parse`.
+
+Given `jsonKey` might point to a nested key using dot notation, e.g. `a.b.c`. If the key is not present, the function does nothing.
+
 By default the function asks for confirmation before attempting to alter the `targetFile`. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts. Passsing a custom `prompt` allows tailoring your own question to the user.
 
+#### `deletePath`
+
+```ts
+async function deletePath(
+  targetPath: string, force: boolean = false, prompt: string = ''
+): Promise<void>
+```
+
+Deletes given `targetPath` from FS. Path is resolved relatively to `process.cwd()`. Several checks are in place to prevent accidental and malicious paths being passed in. Path traversal outside of CWD or providing absolute paths is disallowed.
+
+If the `targetPath` does not exist, the function does nothing.
+
+By default the function asks for confirmation before attempting to delete the `targetPath`. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts. Passsing a custom `prompt` allows tailoring your own question to the user.
+
 ### List of terminal helpers
 
 #### `promptUser`