@jakubmazanec/carson 0.1.0-2d1145f → 0.1.0-2f12db0

package/README.md

@@ -11,12 +11,26 @@ Tool for managing workspace and project configuration.
 ## Installation
 
 ```sh
-npm install @jakubmazanec/carson -g
+npm install @jakubmazanec/carson
 ```
 
 ⚠️ This is an [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) package!
 It cannot be required from a CommonJS module.
 
+Usually you also need a package containing Carson templates. Until you
+[create your own](#carson-templates), you can use mine:
+
+```sh
+npm install @jakubmazanec/carson-templates
+```
+
+⚠️ If you want to create new workspaces, you need to install both Carson and your template package
+globally:
+
+```sh
+npm install @jakubmazanec/carson @jakubmazanec/carson-templates -g
+```
+
 #### Prerequisites
 
 - Node.js 16 or later
@@ -176,9 +190,9 @@ See [API reference](./docs) for auto-generated documentation.
 
 ### Configuration
 
-Carson configuration files are located in a directory named `.carson` directory. Files named
-`workspace.json` and `project.json` are used to configure the workspace and project respectively (in
-the case of single-project workspace they're both in the same `.carson` directory).
+Carson configuration files are located in a directory named `.carson`. Files named `workspace.json`
+and `project.json` are used to configure the workspace and project respectively (in the case of
+single-project workspace they're both in the same `.carson` directory).
 
 You can add arbitrary data to these JSONs in addition to the options described below. Because
 workspace and project configurations are available as JavaScript variables during the rendering of
@@ -269,6 +283,8 @@ there are 3 templates (for simplicity, each contains only one `*.ejs` file and a
 The package can also export some JavaScript code (defined in the `package.json` as usual); all named
 export are available as global variables during the rendering of the template files.
 
+> ⚠️ Do NOT use asynchronous functions in the template files. Templates are rendered synchronously.
+
 #### Template files
 
 All those `*.ejs` files are parsed and rendered via `@jakubmazanec/template` package; they are
@@ -315,13 +331,15 @@ should be written at all.
 
 | Strategy name | Example `strategy` value | Description                                                                                                                                                                                                                     |
 | ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Create        | `create`                 | The template render is written to the target file, but only when the Carson template is used to create a new workspace or project; when Carson performs an update, the template files with this strategy are not even rendered. |
-| Overwrite     | `overwrite`              | The template render is written to the target file, overwriting its existing content.                                                                                                                                            |
-| Merge         | `merge`                  | The template render is merged with the target file's existing content. Only simple objects, not arrays, are merged recursively. The only supported file formats are JSON and YAML.                                              |
-| Check         | `check`                  | Only the target file's existence is checked, the template render is discarded; when Carson doesn't perform an update, the template files with this strategy are not even rendered.                                              |
-| Insert        | `[insert, foobar]`       | The template render is inserted between the first and last occurrence of an HTML comment containing configured string, e.g. `<!-- foobar -->`. The only supported file format is Markdown.                                      |
+| Create        | `'create'`               | The template render is written to the target file, but only when the Carson template is used to create a new workspace or project; when Carson performs an update, the template files with this strategy are not even rendered. |
+| Ensure        | `'ensure'`               | The template render is written to the target file, but only when the target file doesn't exist; if it does, it is left unchanged.                                                                                               |
+| Overwrite     | `'overwrite'`            | The template render is written to the target file, overwriting its existing content.                                                                                                                                            |
+| Merge         | `'merge'`                | The template render is merged with the target file's existing content. Only simple objects, not arrays, are merged recursively. The only supported file formats are JSON and YAML.                                              |
+| Check         | `'check'`                | Only the target file's existence is checked, the template render is discarded; when Carson doesn't perform an update, the template files with this strategy are not even rendered.                                              |
+| Insert        | `['insert', <string>]`   | The template render is inserted between the first and last occurrence of an HTML comment containing configured string, e.g. `<!-- foobar -->`. The only supported file format is Markdown.                                      |
 
-The rest of the template file after the front matter is the actual EJS template.
+The rest of the template file after the front matter is the actual EJS template. Please read
+[`ejs` documentation](https://ejs.co/#docs) to find out in more detail how they work.
 
 > ⚠️ Because EJS templates can contain arbitrary JavaScript code which Carson will run, you
 > shouldn't use Carson templates from untrusted sources! Only use templates that you've written or
@@ -339,6 +357,43 @@ Global variables available during the rendering:
 
 Currently, the config isn't used for anything yet.
 
+### Carson philosophy
+
+The fact that Carson templates are just JavaScript gives you a lot of freedom, but it may lead you
+to use Carson just as a simple config generator. Because you can add arbitrary data to the workspace
+and project configs, it is tempting to use them as a source of values for "parameters" of
+configurations of various tools.
+
+For example, you can add `"useSwc": true` or `"useSwc": false` to a project config and then use this
+value in a template that generates build configuration for either SWC, or Babel. But this makes
+updates little bit harder, because if you later remove Babel support, you have to remember to remove
+now useless setting from the project config. It also makes the logic of the Carson template more
+complex; it is better to have separate templates for projects that use Babel and for project that
+use SWC.
+
+Another approach that is not recommended is using project config to specify "overrides" for various
+config files:
+
+```json
+{
+  "template": "@jakubmazanec/carson-templates:projects/library",
+
+  "tsconfig": {
+    "compilerOptions": {
+      "strict": false
+    }
+  }
+}
+```
+
+The `tsconfig` object is then recursively merged with the defaults during the template rendering of
+the resulting `tsconfig.json`, thus allowing you to change TypeScript configuration per project.
+This is not ideal, because now the Carson template isn't the only thing that defines the project
+configuration, which makes updates more unpredictable.
+
+Generally, do not push the data onto the templates, let the templates pull the data they need. Since
+you create your own templates, it should be easy to do.
+
 ## Contributing
 
 If you want to contribute, see [CONTRIBUTING](./CONTRIBUTING.md) for details.

package/dist/template/TemplateAttributes.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 export declare const templateAttributesSchema: z.ZodObject<{
-    strategy: z.ZodUnion<[z.ZodLiteral<"create">, z.ZodLiteral<"overwrite">, z.ZodLiteral<"merge">, z.ZodLiteral<"check">, z.ZodTuple<[z.ZodLiteral<"insert">, z.ZodString], null>]>;
+    strategy: z.ZodUnion<[z.ZodLiteral<"create">, z.ZodLiteral<"ensure">, z.ZodLiteral<"overwrite">, z.ZodLiteral<"merge">, z.ZodLiteral<"check">, z.ZodTuple<[z.ZodLiteral<"insert">, z.ZodString], null>]>;
 }, "strict", z.ZodTypeAny, {
-    strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+    strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
 }, {
-    strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+    strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
 }>;
 export type TemplateAttributes = z.infer<typeof templateAttributesSchema>;

package/dist/template/TemplateAttributes.js

@@ -1,6 +1,8 @@
 import { z } from 'zod';
+// TODO: add strategy 'none' so when you using template A that extends template B, you can overwrite template files to no-op
 let strategyTemplateAttributeSchema = z.union([
     z.literal('create'),
+    z.literal('ensure'),
     z.literal('overwrite'),
     z.literal('merge'),
     z.literal('check'),
@@ -10,7 +12,6 @@ let strategyTemplateAttributeSchema = z.union([
     ])
 ]);
 export const templateAttributesSchema = z.object({
-    // TODO: add strategy 'none' so when you using template A that extends template B, you can overwrite template files to no-op
     strategy: strategyTemplateAttributeSchema
 }).strict();
 

package/dist/template/TemplateAttributes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/template/TemplateAttributes.ts"],"sourcesContent":["import {z} from 'zod';\n\nlet strategyTemplateAttributeSchema = z.union([\n  z.literal('create'),\n  z.literal('overwrite'),\n  z.literal('merge'),\n  z.literal('check'),\n  z.tuple([z.literal('insert'), z.string()]),\n]);\n\nexport const templateAttributesSchema = z\n  .object({\n    // TODO: add strategy 'none' so when you using template A that extends template B, you can overwrite template files to no-op\n    strategy: strategyTemplateAttributeSchema,\n  })\n  .strict();\n\nexport type TemplateAttributes = z.infer<typeof templateAttributesSchema>;\n"],"names":["z","strategyTemplateAttributeSchema","union","literal","tuple","string","templateAttributesSchema","object","strategy","strict"],"mappings":"AAAA,SAAQA,CAAC,QAAO,MAAM;AAEtB,IAAIC,kCAAkCD,EAAEE,KAAK,CAAC;IAC5CF,EAAEG,OAAO,CAAC;IACVH,EAAEG,OAAO,CAAC;IACVH,EAAEG,OAAO,CAAC;IACVH,EAAEG,OAAO,CAAC;IACVH,EAAEI,KAAK,CAAC;QAACJ,EAAEG,OAAO,CAAC;QAAWH,EAAEK,MAAM;KAAG;CAC1C;AAED,OAAO,MAAMC,2BAA2BN,EACrCO,MAAM,CAAC;IACN,4HAA4H;IAC5HC,UAAUP;AACZ,GACCQ,MAAM,GAAG"}
+{"version":3,"sources":["../../src/template/TemplateAttributes.ts"],"sourcesContent":["import {z} from 'zod';\n\n// TODO: add strategy 'none' so when you using template A that extends template B, you can overwrite template files to no-op\nlet strategyTemplateAttributeSchema = z.union([\n  z.literal('create'),\n  z.literal('ensure'),\n  z.literal('overwrite'),\n  z.literal('merge'),\n  z.literal('check'),\n  z.tuple([z.literal('insert'), z.string()]),\n]);\n\nexport const templateAttributesSchema = z\n  .object({\n    strategy: strategyTemplateAttributeSchema,\n  })\n  .strict();\n\nexport type TemplateAttributes = z.infer<typeof templateAttributesSchema>;\n"],"names":["z","strategyTemplateAttributeSchema","union","literal","tuple","string","templateAttributesSchema","object","strategy","strict"],"mappings":"AAAA,SAAQA,CAAC,QAAO,MAAM;AAEtB,4HAA4H;AAC5H,IAAIC,kCAAkCD,EAAEE,KAAK,CAAC;IAC5CF,EAAEG,OAAO,CAAC;IACVH,EAAEG,OAAO,CAAC;IACVH,EAAEG,OAAO,CAAC;IACVH,EAAEG,OAAO,CAAC;IACVH,EAAEG,OAAO,CAAC;IACVH,EAAEI,KAAK,CAAC;QAACJ,EAAEG,OAAO,CAAC;QAAWH,EAAEK,MAAM;KAAG;CAC1C;AAED,OAAO,MAAMC,2BAA2BN,EACrCO,MAAM,CAAC;IACNC,UAAUP;AACZ,GACCQ,MAAM,GAAG"}

package/dist/template/applyTemplateRenders.js

@@ -1,4 +1,5 @@
-import fs from 'fs-extra';
+// TODO: can this be fixed?
+/* eslint-disable complexity -- TODO */ import fs from 'fs-extra';
 import path from 'node:path';
 import prettier from 'prettier';
 import { CarsonTemplateError } from './CarsonTemplateError.js';
@@ -9,6 +10,7 @@ import { CARSON_CONFIG_DIRECTORY, SNAPSHOTS_FILENAME } from '../constants.js';
  */ export async function applyTemplateRenders({ templateRenders, path: targetPath, ignoreStrategies }) {
     // we need to clear Prettier cache, because we are changing file system
     prettier.clearConfigCache();
+    // first, we read the existing snapshots and use them to undo previous changes
     let templateRenderSnapshotsPath = path.join(targetPath, CARSON_CONFIG_DIRECTORY, SNAPSHOTS_FILENAME);
     if (await fs.pathExists(templateRenderSnapshotsPath)) {
         let templateRenderSnapshots = await loadTemplateRenderSnapshots(templateRenderSnapshotsPath);
@@ -17,6 +19,11 @@ import { CARSON_CONFIG_DIRECTORY, SNAPSHOTS_FILENAME } from '../constants.js';
             if (ignoreStrategies.includes(strategy)) {
                 continue;
             }
+            if (templateRenderSnapshot.attributes.strategy === 'ensure') {
+                await deleteUsingTemplateRender(templateRenderSnapshot, targetPath, {
+                    onlyDeleteWhenContentsMatch: true
+                });
+            }
             if (templateRenderSnapshot.attributes.strategy === 'overwrite') {
                 await deleteUsingTemplateRender(templateRenderSnapshot, targetPath);
             }
@@ -28,13 +35,24 @@ import { CARSON_CONFIG_DIRECTORY, SNAPSHOTS_FILENAME } from '../constants.js';
             }
         }
     }
-    if (!ignoreStrategies.includes('create')) {
-        for (let templateRender of templateRenders){
-            if (templateRender.attributes.strategy === 'create') {
+    // second, we apply strategies that create files
+    for (let templateRender of templateRenders){
+        let strategy = typeof templateRender.attributes.strategy === 'string' ? templateRender.attributes.strategy : templateRender.attributes.strategy[0];
+        if (ignoreStrategies.includes(strategy)) {
+            continue;
+        }
+        if (templateRender.attributes.strategy === 'create') {
+            await createUsingTemplateRender(templateRender, targetPath);
+        }
+        if (templateRender.attributes.strategy === 'ensure') {
+            let to = path.join(targetPath, templateRender.attributes.to);
+            let doesToExist = await fs.pathExists(to);
+            if (!doesToExist) {
                 await createUsingTemplateRender(templateRender, targetPath);
             }
         }
     }
+    // third, we apply strategies that change files
     for (let templateRender of templateRenders){
         let strategy = typeof templateRender.attributes.strategy === 'string' ? templateRender.attributes.strategy : templateRender.attributes.strategy[0];
         if (ignoreStrategies.includes(strategy)) {

package/dist/template/applyTemplateRenders.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/template/applyTemplateRenders.ts"],"sourcesContent":["import fs from 'fs-extra';\nimport path from 'node:path';\nimport prettier from 'prettier';\n\nimport {CarsonTemplateError} from './CarsonTemplateError.js';\nimport {\n  createUsingTemplateRender,\n  deleteUsingTemplateRender,\n  insertUsingTemplateRender,\n  loadTemplateRenderSnapshots,\n  mergeUsingTemplateRender,\n  overwriteUsingTemplateRender,\n  saveTemplateRenderSnapshots,\n  uninsertUsingTemplateRender,\n  unmergeUsingTemplateRender,\n} from './internals.js';\nimport {type TemplateRenders} from './TemplateRenders.js';\nimport {CARSON_CONFIG_DIRECTORY, SNAPSHOTS_FILENAME} from '../constants.js';\n\nexport type ApplyTemplateRendersOptions = {\n  templateRenders: TemplateRenders;\n  path: string;\n  ignoreStrategies: string[];\n};\n\n/**\n * Applies rendered Carson template to a specified path, i.e. creates and updates files based on the result of rendering each Carson template file.\n */\nexport async function applyTemplateRenders({\n  templateRenders,\n  path: targetPath,\n  ignoreStrategies,\n}: ApplyTemplateRendersOptions) {\n  // we need to clear Prettier cache, because we are changing file system\n  prettier.clearConfigCache();\n\n  let templateRenderSnapshotsPath = path.join(\n    targetPath,\n    CARSON_CONFIG_DIRECTORY,\n    SNAPSHOTS_FILENAME,\n  );\n\n  if (await fs.pathExists(templateRenderSnapshotsPath)) {\n    let templateRenderSnapshots = await loadTemplateRenderSnapshots(templateRenderSnapshotsPath);\n\n    for (let templateRenderSnapshot of templateRenderSnapshots) {\n      let strategy =\n        typeof templateRenderSnapshot.attributes.strategy === 'string'\n          ? templateRenderSnapshot.attributes.strategy\n          : templateRenderSnapshot.attributes.strategy[0];\n\n      if (ignoreStrategies.includes(strategy)) {\n        continue;\n      }\n\n      if (templateRenderSnapshot.attributes.strategy === 'overwrite') {\n        await deleteUsingTemplateRender(templateRenderSnapshot, targetPath);\n      }\n\n      if (templateRenderSnapshot.attributes.strategy === 'merge') {\n        await unmergeUsingTemplateRender(templateRenderSnapshot, targetPath);\n      }\n\n      if (templateRenderSnapshot.attributes.strategy[0] === 'insert') {\n        await uninsertUsingTemplateRender(templateRenderSnapshot, targetPath);\n      }\n    }\n  }\n\n  if (!ignoreStrategies.includes('create')) {\n    for (let templateRender of templateRenders) {\n      if (templateRender.attributes.strategy === 'create') {\n        await createUsingTemplateRender(templateRender, targetPath);\n      }\n    }\n  }\n\n  for (let templateRender of templateRenders) {\n    let strategy =\n      typeof templateRender.attributes.strategy === 'string'\n        ? templateRender.attributes.strategy\n        : templateRender.attributes.strategy[0];\n\n    if (ignoreStrategies.includes(strategy)) {\n      continue;\n    }\n\n    if (templateRender.attributes.strategy === 'overwrite') {\n      await overwriteUsingTemplateRender(templateRender, targetPath);\n    }\n\n    if (templateRender.attributes.strategy === 'merge') {\n      await mergeUsingTemplateRender(templateRender, targetPath);\n    }\n\n    if (templateRender.attributes.strategy[0] === 'insert') {\n      await insertUsingTemplateRender(templateRender, targetPath);\n    }\n\n    if (templateRender.attributes.strategy === 'check') {\n      let to = path.join(targetPath, templateRender.attributes.to);\n      let doesToExist = await fs.pathExists(to);\n\n      if (!doesToExist) {\n        throw new CarsonTemplateError('STRATEGY_MISSING_FILE', {\n          messageParameters: [templateRender.attributes.strategy, templateRender.template.path, to],\n          data: {\n            path: to,\n          },\n        });\n      }\n    }\n  }\n\n  await saveTemplateRenderSnapshots(templateRenders, templateRenderSnapshotsPath);\n}\n"],"names":["fs","path","prettier","CarsonTemplateError","createUsingTemplateRender","deleteUsingTemplateRender","insertUsingTemplateRender","loadTemplateRenderSnapshots","mergeUsingTemplateRender","overwriteUsingTemplateRender","saveTemplateRenderSnapshots","uninsertUsingTemplateRender","unmergeUsingTemplateRender","CARSON_CONFIG_DIRECTORY","SNAPSHOTS_FILENAME","applyTemplateRenders","templateRenders","targetPath","ignoreStrategies","clearConfigCache","templateRenderSnapshotsPath","join","pathExists","templateRenderSnapshots","templateRenderSnapshot","strategy","attributes","includes","templateRender","to","doesToExist","messageParameters","template","data"],"mappings":"AAAA,OAAOA,QAAQ,WAAW;AAC1B,OAAOC,UAAU,YAAY;AAC7B,OAAOC,cAAc,WAAW;AAEhC,SAAQC,mBAAmB,QAAO,2BAA2B;AAC7D,SACEC,yBAAyB,EACzBC,yBAAyB,EACzBC,yBAAyB,EACzBC,2BAA2B,EAC3BC,wBAAwB,EACxBC,4BAA4B,EAC5BC,2BAA2B,EAC3BC,2BAA2B,EAC3BC,0BAA0B,QACrB,iBAAiB;AAExB,SAAQC,uBAAuB,EAAEC,kBAAkB,QAAO,kBAAkB;AAQ5E;;CAEC,GACD,OAAO,eAAeC,qBAAqB,EACzCC,eAAe,EACff,MAAMgB,UAAU,EAChBC,gBAAgB,EACY;IAC5B,uEAAuE;IACvEhB,SAASiB,gBAAgB;IAEzB,IAAIC,8BAA8BnB,KAAKoB,IAAI,CACzCJ,YACAJ,yBACAC;IAGF,IAAI,MAAMd,GAAGsB,UAAU,CAACF,8BAA8B;QACpD,IAAIG,0BAA0B,MAAMhB,4BAA4Ba;QAEhE,KAAK,IAAII,0BAA0BD,wBAAyB;YAC1D,IAAIE,WACF,OAAOD,uBAAuBE,UAAU,CAACD,QAAQ,KAAK,WAClDD,uBAAuBE,UAAU,CAACD,QAAQ,GAC1CD,uBAAuBE,UAAU,CAACD,QAAQ,CAAC,EAAE;YAEnD,IAAIP,iBAAiBS,QAAQ,CAACF,WAAW;gBACvC;YACF;YAEA,IAAID,uBAAuBE,UAAU,CAACD,QAAQ,KAAK,aAAa;gBAC9D,MAAMpB,0BAA0BmB,wBAAwBP;YAC1D;YAEA,IAAIO,uBAAuBE,UAAU,CAACD,QAAQ,KAAK,SAAS;gBAC1D,MAAMb,2BAA2BY,wBAAwBP;YAC3D;YAEA,IAAIO,uBAAuBE,UAAU,CAACD,QAAQ,CAAC,EAAE,KAAK,UAAU;gBAC9D,MAAMd,4BAA4Ba,wBAAwBP;YAC5D;QACF;IACF;IAEA,IAAI,CAACC,iBAAiBS,QAAQ,CAAC,WAAW;QACxC,KAAK,IAAIC,kBAAkBZ,gBAAiB;YAC1C,IAAIY,eAAeF,UAAU,CAACD,QAAQ,KAAK,UAAU;gBACnD,MAAMrB,0BAA0BwB,gBAAgBX;YAClD;QACF;IACF;IAEA,KAAK,IAAIW,kBAAkBZ,gBAAiB;QAC1C,IAAIS,WACF,OAAOG,eAAeF,UAAU,CAACD,QAAQ,KAAK,WAC1CG,eAAeF,UAAU,CAACD,QAAQ,GAClCG,eAAeF,UAAU,CAACD,QAAQ,CAAC,EAAE;QAE3C,IAAIP,iBAAiBS,QAAQ,CAACF,WAAW;YACvC;QACF;QAEA,IAAIG,eAAeF,UAAU,CAACD,QAAQ,KAAK,aAAa;YACtD,MAAMhB,6BAA6BmB,gBAAgBX;QACrD;QAEA,IAAIW,eAAeF,UAAU,CAACD,QAAQ,KAAK,SAAS;YAClD,MAAMjB,yBAAyBoB,gBAAgBX;QACjD;QAEA,IAAIW,eAAeF,UAAU,CAACD,QAAQ,CAAC,EAAE,KAAK,UAAU;YACtD,MAAMnB,0BAA0BsB,gBAAgBX;QAClD;QAEA,IAAIW,eAAeF,UAAU,CAACD,QAAQ,KAAK,SAAS;YAClD,IAAII,KAAK5B,KAAKoB,IAAI,CAACJ,YAAYW,eAAeF,UAAU,CAACG,EAAE;YAC3D,IAAIC,cAAc,MAAM9B,GAAGsB,UAAU,CAACO;YAEtC,IAAI,CAACC,aAAa;gBAChB,MAAM,IAAI3B,oBAAoB,yBAAyB;oBACrD4B,mBAAmB;wBAACH,eAAeF,UAAU,CAACD,QAAQ;wBAAEG,eAAeI,QAAQ,CAAC/B,IAAI;wBAAE4B;qBAAG;oBACzFI,MAAM;wBACJhC,MAAM4B;oBACR;gBACF;YACF;QACF;IACF;IAEA,MAAMnB,4BAA4BM,iBAAiBI;AACrD"}
+{"version":3,"sources":["../../src/template/applyTemplateRenders.ts"],"sourcesContent":["// TODO: can this be fixed?\n/* eslint-disable complexity -- TODO */\nimport fs from 'fs-extra';\nimport path from 'node:path';\nimport prettier from 'prettier';\n\nimport {CarsonTemplateError} from './CarsonTemplateError.js';\nimport {\n  createUsingTemplateRender,\n  deleteUsingTemplateRender,\n  insertUsingTemplateRender,\n  loadTemplateRenderSnapshots,\n  mergeUsingTemplateRender,\n  overwriteUsingTemplateRender,\n  saveTemplateRenderSnapshots,\n  uninsertUsingTemplateRender,\n  unmergeUsingTemplateRender,\n} from './internals.js';\nimport {type TemplateRenders} from './TemplateRenders.js';\nimport {CARSON_CONFIG_DIRECTORY, SNAPSHOTS_FILENAME} from '../constants.js';\n\nexport type ApplyTemplateRendersOptions = {\n  templateRenders: TemplateRenders;\n  path: string;\n  ignoreStrategies: string[];\n};\n\n/**\n * Applies rendered Carson template to a specified path, i.e. creates and updates files based on the result of rendering each Carson template file.\n */\nexport async function applyTemplateRenders({\n  templateRenders,\n  path: targetPath,\n  ignoreStrategies,\n}: ApplyTemplateRendersOptions) {\n  // we need to clear Prettier cache, because we are changing file system\n  prettier.clearConfigCache();\n\n  // first, we read the existing snapshots and use them to undo previous changes\n  let templateRenderSnapshotsPath = path.join(\n    targetPath,\n    CARSON_CONFIG_DIRECTORY,\n    SNAPSHOTS_FILENAME,\n  );\n\n  if (await fs.pathExists(templateRenderSnapshotsPath)) {\n    let templateRenderSnapshots = await loadTemplateRenderSnapshots(templateRenderSnapshotsPath);\n\n    for (let templateRenderSnapshot of templateRenderSnapshots) {\n      let strategy =\n        typeof templateRenderSnapshot.attributes.strategy === 'string'\n          ? templateRenderSnapshot.attributes.strategy\n          : templateRenderSnapshot.attributes.strategy[0];\n\n      if (ignoreStrategies.includes(strategy)) {\n        continue;\n      }\n\n      if (templateRenderSnapshot.attributes.strategy === 'ensure') {\n        await deleteUsingTemplateRender(templateRenderSnapshot, targetPath, {\n          onlyDeleteWhenContentsMatch: true,\n        });\n      }\n\n      if (templateRenderSnapshot.attributes.strategy === 'overwrite') {\n        await deleteUsingTemplateRender(templateRenderSnapshot, targetPath);\n      }\n\n      if (templateRenderSnapshot.attributes.strategy === 'merge') {\n        await unmergeUsingTemplateRender(templateRenderSnapshot, targetPath);\n      }\n\n      if (templateRenderSnapshot.attributes.strategy[0] === 'insert') {\n        await uninsertUsingTemplateRender(templateRenderSnapshot, targetPath);\n      }\n    }\n  }\n\n  // second, we apply strategies that create files\n  for (let templateRender of templateRenders) {\n    let strategy =\n      typeof templateRender.attributes.strategy === 'string'\n        ? templateRender.attributes.strategy\n        : templateRender.attributes.strategy[0];\n\n    if (ignoreStrategies.includes(strategy)) {\n      continue;\n    }\n\n    if (templateRender.attributes.strategy === 'create') {\n      await createUsingTemplateRender(templateRender, targetPath);\n    }\n\n    if (templateRender.attributes.strategy === 'ensure') {\n      let to = path.join(targetPath, templateRender.attributes.to);\n      let doesToExist = await fs.pathExists(to);\n\n      if (!doesToExist) {\n        await createUsingTemplateRender(templateRender, targetPath);\n      }\n    }\n  }\n\n  // third, we apply strategies that change files\n  for (let templateRender of templateRenders) {\n    let strategy =\n      typeof templateRender.attributes.strategy === 'string'\n        ? templateRender.attributes.strategy\n        : templateRender.attributes.strategy[0];\n\n    if (ignoreStrategies.includes(strategy)) {\n      continue;\n    }\n\n    if (templateRender.attributes.strategy === 'overwrite') {\n      await overwriteUsingTemplateRender(templateRender, targetPath);\n    }\n\n    if (templateRender.attributes.strategy === 'merge') {\n      await mergeUsingTemplateRender(templateRender, targetPath);\n    }\n\n    if (templateRender.attributes.strategy[0] === 'insert') {\n      await insertUsingTemplateRender(templateRender, targetPath);\n    }\n\n    if (templateRender.attributes.strategy === 'check') {\n      let to = path.join(targetPath, templateRender.attributes.to);\n      let doesToExist = await fs.pathExists(to);\n\n      if (!doesToExist) {\n        throw new CarsonTemplateError('STRATEGY_MISSING_FILE', {\n          messageParameters: [templateRender.attributes.strategy, templateRender.template.path, to],\n          data: {\n            path: to,\n          },\n        });\n      }\n    }\n  }\n\n  await saveTemplateRenderSnapshots(templateRenders, templateRenderSnapshotsPath);\n}\n"],"names":["fs","path","prettier","CarsonTemplateError","createUsingTemplateRender","deleteUsingTemplateRender","insertUsingTemplateRender","loadTemplateRenderSnapshots","mergeUsingTemplateRender","overwriteUsingTemplateRender","saveTemplateRenderSnapshots","uninsertUsingTemplateRender","unmergeUsingTemplateRender","CARSON_CONFIG_DIRECTORY","SNAPSHOTS_FILENAME","applyTemplateRenders","templateRenders","targetPath","ignoreStrategies","clearConfigCache","templateRenderSnapshotsPath","join","pathExists","templateRenderSnapshots","templateRenderSnapshot","strategy","attributes","includes","onlyDeleteWhenContentsMatch","templateRender","to","doesToExist","messageParameters","template","data"],"mappings":"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"}

package/dist/template/internals/TemplateRenderSnapshot.d.ts

@@ -2,12 +2,12 @@ import { z } from 'zod';
 export declare const templateRenderSnapshotSchema: z.ZodObject<{
     attributes: z.ZodObject<{
         to: z.ZodString;
-        strategy: z.ZodUnion<[z.ZodLiteral<"create">, z.ZodLiteral<"overwrite">, z.ZodLiteral<"merge">, z.ZodLiteral<"check">, z.ZodTuple<[z.ZodLiteral<"insert">, z.ZodString], null>]>;
+        strategy: z.ZodUnion<[z.ZodLiteral<"create">, z.ZodLiteral<"ensure">, z.ZodLiteral<"overwrite">, z.ZodLiteral<"merge">, z.ZodLiteral<"check">, z.ZodTuple<[z.ZodLiteral<"insert">, z.ZodString], null>]>;
     }, "strict", z.ZodTypeAny, {
-        strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+        strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
         to: string;
     }, {
-        strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+        strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
         to: string;
     }>;
     content: z.ZodString;
@@ -23,7 +23,7 @@ export declare const templateRenderSnapshotSchema: z.ZodObject<{
         path: string;
     };
     attributes: {
-        strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+        strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
         to: string;
     };
     content: string;
@@ -32,7 +32,7 @@ export declare const templateRenderSnapshotSchema: z.ZodObject<{
         path: string;
     };
     attributes: {
-        strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+        strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
         to: string;
     };
     content: string;

package/dist/template/internals/TemplateRenderSnapshots.d.ts

@@ -2,12 +2,12 @@ import { type z } from 'zod';
 export declare const templateRenderSnapshotsSchema: z.ZodArray<z.ZodObject<{
     attributes: z.ZodObject<{
         to: z.ZodString;
-        strategy: z.ZodUnion<[z.ZodLiteral<"create">, z.ZodLiteral<"overwrite">, z.ZodLiteral<"merge">, z.ZodLiteral<"check">, z.ZodTuple<[z.ZodLiteral<"insert">, z.ZodString], null>]>;
+        strategy: z.ZodUnion<[z.ZodLiteral<"create">, z.ZodLiteral<"ensure">, z.ZodLiteral<"overwrite">, z.ZodLiteral<"merge">, z.ZodLiteral<"check">, z.ZodTuple<[z.ZodLiteral<"insert">, z.ZodString], null>]>;
     }, "strict", z.ZodTypeAny, {
-        strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+        strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
         to: string;
     }, {
-        strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+        strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
         to: string;
     }>;
     content: z.ZodString;
@@ -23,7 +23,7 @@ export declare const templateRenderSnapshotsSchema: z.ZodArray<z.ZodObject<{
         path: string;
     };
     attributes: {
-        strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+        strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
         to: string;
     };
     content: string;
@@ -32,7 +32,7 @@ export declare const templateRenderSnapshotsSchema: z.ZodArray<z.ZodObject<{
         path: string;
     };
     attributes: {
-        strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+        strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
         to: string;
     };
     content: string;

package/dist/template/internals/deleteUsingTemplateRender.d.ts

@@ -1,3 +1,6 @@
 import { type TemplateRenderSnapshot } from './TemplateRenderSnapshot.js';
 import { type TemplateRender } from '../TemplateRender.js';
-export declare function deleteUsingTemplateRender(templateRender: TemplateRender | TemplateRenderSnapshot, basePath: string): Promise<void>;
+export type DeleteUsingTemplateRenderOptions = {
+    onlyDeleteWhenContentsMatch?: boolean;
+};
+export declare function deleteUsingTemplateRender(templateRender: TemplateRender | TemplateRenderSnapshot, basePath: string, options?: DeleteUsingTemplateRenderOptions): Promise<void>;

package/dist/template/internals/deleteUsingTemplateRender.js

@@ -1,10 +1,23 @@
 import fs from 'fs-extra';
 import path from 'node:path';
-export async function deleteUsingTemplateRender(templateRender, basePath) {
+import { prettify } from './prettify.js';
+export async function deleteUsingTemplateRender(templateRender, basePath, options) {
+    var _options;
     let to = path.join(basePath, templateRender.attributes.to);
-    if (await fs.pathExists(to)) {
-        await fs.rm(to);
+    if (!await fs.pathExists(to)) {
+        return;
     }
+    if ((_options = options) === null || _options === void 0 ? void 0 : _options.onlyDeleteWhenContentsMatch) {
+        let existingContent = await fs.readFile(to, {
+            encoding: 'utf8'
+        });
+        let newContent = await prettify(templateRender.content, to);
+        if (existingContent.trim() === newContent.trim()) {
+            await fs.rm(to);
+        }
+        return;
+    }
+    await fs.rm(to);
 }
 
 //# sourceMappingURL=deleteUsingTemplateRender.js.map

package/dist/template/internals/deleteUsingTemplateRender.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/template/internals/deleteUsingTemplateRender.ts"],"sourcesContent":["import fs from 'fs-extra';\nimport path from 'node:path';\n\nimport {type TemplateRenderSnapshot} from './TemplateRenderSnapshot.js';\nimport {type TemplateRender} from '../TemplateRender.js';\n\nexport async function deleteUsingTemplateRender(\n  templateRender: TemplateRender | TemplateRenderSnapshot,\n  basePath: string,\n) {\n  let to = path.join(basePath, templateRender.attributes.to);\n\n  if (await fs.pathExists(to)) {\n    await fs.rm(to);\n  }\n}\n"],"names":["fs","path","deleteUsingTemplateRender","templateRender","basePath","to","join","attributes","pathExists","rm"],"mappings":"AAAA,OAAOA,QAAQ,WAAW;AAC1B,OAAOC,UAAU,YAAY;AAK7B,OAAO,eAAeC,0BACpBC,cAAuD,EACvDC,QAAgB;IAEhB,IAAIC,KAAKJ,KAAKK,IAAI,CAACF,UAAUD,eAAeI,UAAU,CAACF,EAAE;IAEzD,IAAI,MAAML,GAAGQ,UAAU,CAACH,KAAK;QAC3B,MAAML,GAAGS,EAAE,CAACJ;IACd;AACF"}
+{"version":3,"sources":["../../../src/template/internals/deleteUsingTemplateRender.ts"],"sourcesContent":["import fs from 'fs-extra';\nimport path from 'node:path';\n\nimport {prettify} from './prettify.js';\nimport {type TemplateRenderSnapshot} from './TemplateRenderSnapshot.js';\nimport {type TemplateRender} from '../TemplateRender.js';\n\nexport type DeleteUsingTemplateRenderOptions = {\n  onlyDeleteWhenContentsMatch?: boolean;\n};\n\nexport async function deleteUsingTemplateRender(\n  templateRender: TemplateRender | TemplateRenderSnapshot,\n  basePath: string,\n  options?: DeleteUsingTemplateRenderOptions,\n) {\n  let to = path.join(basePath, templateRender.attributes.to);\n\n  if (!(await fs.pathExists(to))) {\n    return;\n  }\n\n  if (options?.onlyDeleteWhenContentsMatch) {\n    let existingContent = await fs.readFile(to, {encoding: 'utf8'});\n    let newContent = await prettify(templateRender.content, to);\n\n    if (existingContent.trim() === newContent.trim()) {\n      await fs.rm(to);\n    }\n\n    return;\n  }\n\n  await fs.rm(to);\n}\n"],"names":["fs","path","prettify","deleteUsingTemplateRender","templateRender","basePath","options","to","join","attributes","pathExists","onlyDeleteWhenContentsMatch","existingContent","readFile","encoding","newContent","content","trim","rm"],"mappings":"AAAA,OAAOA,QAAQ,WAAW;AAC1B,OAAOC,UAAU,YAAY;AAE7B,SAAQC,QAAQ,QAAO,gBAAgB;AAQvC,OAAO,eAAeC,0BACpBC,cAAuD,EACvDC,QAAgB,EAChBC,OAA0C;QAQtCA;IANJ,IAAIC,KAAKN,KAAKO,IAAI,CAACH,UAAUD,eAAeK,UAAU,CAACF,EAAE;IAEzD,IAAI,CAAE,MAAMP,GAAGU,UAAU,CAACH,KAAM;QAC9B;IACF;IAEA,KAAID,WAAAA,qBAAAA,+BAAAA,SAASK,2BAA2B,EAAE;QACxC,IAAIC,kBAAkB,MAAMZ,GAAGa,QAAQ,CAACN,IAAI;YAACO,UAAU;QAAM;QAC7D,IAAIC,aAAa,MAAMb,SAASE,eAAeY,OAAO,EAAET;QAExD,IAAIK,gBAAgBK,IAAI,OAAOF,WAAWE,IAAI,IAAI;YAChD,MAAMjB,GAAGkB,EAAE,CAACX;QACd;QAEA;IACF;IAEA,MAAMP,GAAGkB,EAAE,CAACX;AACd"}

package/dist/template/internals/loadTemplateRenderSnapshots.d.ts

@@ -3,7 +3,7 @@ export declare function loadTemplateRenderSnapshots(templateRenderSnapshotsPath:
         path: string;
     };
     attributes: {
-        strategy: ("create" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
+        strategy: ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string]) & ("create" | "ensure" | "overwrite" | "merge" | "check" | ["insert", string] | undefined);
         to: string;
     };
     content: string;

package/dist/template/internals/saveTemplateRenderSnapshots.js

@@ -3,7 +3,7 @@ import fs from 'fs-extra';
 export async function saveTemplateRenderSnapshots(templateRenders, templateRenderSnapshotsPath) {
     let templateRendersSnapshots = [];
     for (let templateRender of templateRenders){
-        if (templateRender.attributes.strategy === 'overwrite' || templateRender.attributes.strategy === 'merge' || templateRender.attributes.strategy[0] === 'insert') {
+        if (templateRender.attributes.strategy === 'ensure' || templateRender.attributes.strategy === 'overwrite' || templateRender.attributes.strategy === 'merge' || templateRender.attributes.strategy[0] === 'insert') {
             templateRendersSnapshots.push({
                 attributes: {
                     to: templateRender.attributes.to,

package/dist/template/internals/saveTemplateRenderSnapshots.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/template/internals/saveTemplateRenderSnapshots.ts"],"sourcesContent":["import {deflateSync, strToU8} from 'fflate';\nimport fs from 'fs-extra';\n\nimport {type TemplateRenderSnapshots} from './TemplateRenderSnapshots.js';\nimport {type TemplateRenders} from '../TemplateRenders.js';\n\nexport async function saveTemplateRenderSnapshots(\n  templateRenders: TemplateRenders,\n  templateRenderSnapshotsPath: string,\n) {\n  let templateRendersSnapshots: TemplateRenderSnapshots = [];\n\n  for (let templateRender of templateRenders) {\n    if (\n      templateRender.attributes.strategy === 'overwrite' ||\n      templateRender.attributes.strategy === 'merge' ||\n      templateRender.attributes.strategy[0] === 'insert'\n    ) {\n      templateRendersSnapshots.push({\n        attributes: {\n          to: templateRender.attributes.to,\n          strategy: templateRender.attributes.strategy,\n        },\n        content: templateRender.content,\n        template: templateRender.template,\n      });\n    }\n  }\n\n  await fs.writeFile(\n    templateRenderSnapshotsPath,\n    deflateSync(strToU8(JSON.stringify(templateRendersSnapshots)), {level: 1, mem: 0}),\n  );\n}\n"],"names":["deflateSync","strToU8","fs","saveTemplateRenderSnapshots","templateRenders","templateRenderSnapshotsPath","templateRendersSnapshots","templateRender","attributes","strategy","push","to","content","template","writeFile","JSON","stringify","level","mem"],"mappings":"AAAA,SAAQA,WAAW,EAAEC,OAAO,QAAO,SAAS;AAC5C,OAAOC,QAAQ,WAAW;AAK1B,OAAO,eAAeC,4BACpBC,eAAgC,EAChCC,2BAAmC;IAEnC,IAAIC,2BAAoD,EAAE;IAE1D,KAAK,IAAIC,kBAAkBH,gBAAiB;QAC1C,IACEG,eAAeC,UAAU,CAACC,QAAQ,KAAK,eACvCF,eAAeC,UAAU,CAACC,QAAQ,KAAK,WACvCF,eAAeC,UAAU,CAACC,QAAQ,CAAC,EAAE,KAAK,UAC1C;YACAH,yBAAyBI,IAAI,CAAC;gBAC5BF,YAAY;oBACVG,IAAIJ,eAAeC,UAAU,CAACG,EAAE;oBAChCF,UAAUF,eAAeC,UAAU,CAACC,QAAQ;gBAC9C;gBACAG,SAASL,eAAeK,OAAO;gBAC/BC,UAAUN,eAAeM,QAAQ;YACnC;QACF;IACF;IAEA,MAAMX,GAAGY,SAAS,CAChBT,6BACAL,YAAYC,QAAQc,KAAKC,SAAS,CAACV,4BAA4B;QAACW,OAAO;QAAGC,KAAK;IAAC;AAEpF"}
+{"version":3,"sources":["../../../src/template/internals/saveTemplateRenderSnapshots.ts"],"sourcesContent":["import {deflateSync, strToU8} from 'fflate';\nimport fs from 'fs-extra';\n\nimport {type TemplateRenderSnapshots} from './TemplateRenderSnapshots.js';\nimport {type TemplateRenders} from '../TemplateRenders.js';\n\nexport async function saveTemplateRenderSnapshots(\n  templateRenders: TemplateRenders,\n  templateRenderSnapshotsPath: string,\n) {\n  let templateRendersSnapshots: TemplateRenderSnapshots = [];\n\n  for (let templateRender of templateRenders) {\n    if (\n      templateRender.attributes.strategy === 'ensure' ||\n      templateRender.attributes.strategy === 'overwrite' ||\n      templateRender.attributes.strategy === 'merge' ||\n      templateRender.attributes.strategy[0] === 'insert'\n    ) {\n      templateRendersSnapshots.push({\n        attributes: {\n          to: templateRender.attributes.to,\n          strategy: templateRender.attributes.strategy,\n        },\n        content: templateRender.content,\n        template: templateRender.template,\n      });\n    }\n  }\n\n  await fs.writeFile(\n    templateRenderSnapshotsPath,\n    deflateSync(strToU8(JSON.stringify(templateRendersSnapshots)), {level: 1, mem: 0}),\n  );\n}\n"],"names":["deflateSync","strToU8","fs","saveTemplateRenderSnapshots","templateRenders","templateRenderSnapshotsPath","templateRendersSnapshots","templateRender","attributes","strategy","push","to","content","template","writeFile","JSON","stringify","level","mem"],"mappings":"AAAA,SAAQA,WAAW,EAAEC,OAAO,QAAO,SAAS;AAC5C,OAAOC,QAAQ,WAAW;AAK1B,OAAO,eAAeC,4BACpBC,eAAgC,EAChCC,2BAAmC;IAEnC,IAAIC,2BAAoD,EAAE;IAE1D,KAAK,IAAIC,kBAAkBH,gBAAiB;QAC1C,IACEG,eAAeC,UAAU,CAACC,QAAQ,KAAK,YACvCF,eAAeC,UAAU,CAACC,QAAQ,KAAK,eACvCF,eAAeC,UAAU,CAACC,QAAQ,KAAK,WACvCF,eAAeC,UAAU,CAACC,QAAQ,CAAC,EAAE,KAAK,UAC1C;YACAH,yBAAyBI,IAAI,CAAC;gBAC5BF,YAAY;oBACVG,IAAIJ,eAAeC,UAAU,CAACG,EAAE;oBAChCF,UAAUF,eAAeC,UAAU,CAACC,QAAQ;gBAC9C;gBACAG,SAASL,eAAeK,OAAO;gBAC/BC,UAAUN,eAAeM,QAAQ;YACnC;QACF;IACF;IAEA,MAAMX,GAAGY,SAAS,CAChBT,6BACAL,YAAYC,QAAQc,KAAKC,SAAS,CAACV,4BAA4B;QAACW,OAAO;QAAGC,KAAK;IAAC;AAEpF"}

package/dist/template/renderCarsonTemplate.js

@@ -1,8 +1,12 @@
+import { pathToPosixPath } from '@jakubmazanec/fs-utils';
 import _ from 'lodash';
-import { importCarsonTemplate, readCarsonTemplate } from './internals.js';
+import path from 'node:path';
+import { importCarsonTemplate, parseCarsonTemplateId, readCarsonTemplate, resolveModule } from './internals.js';
 /**
  * Renders a Carson template with provided template data.
  */ export async function renderCarsonTemplate(options) {
+    let [moduleId] = parseCarsonTemplateId(options.templateId);
+    let modulePath = await resolveModule(moduleId);
     let template = await readCarsonTemplate(options.templateId);
     let templateModule = await importCarsonTemplate(options.templateId);
     let templateRenders = [];
@@ -15,7 +19,7 @@ import { importCarsonTemplate, readCarsonTemplate } from './internals.js';
         })).map((templateRender)=>({
                 ...templateRender,
                 template: {
-                    path: file.path ?? ''
+                    path: pathToPosixPath(`${moduleId}/${path.relative(modulePath, file.path ?? modulePath)}`)
                 }
             })));
     }

package/dist/template/renderCarsonTemplate.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/template/renderCarsonTemplate.ts"],"sourcesContent":["import _ from 'lodash';\n\nimport {importCarsonTemplate, readCarsonTemplate} from './internals.js';\nimport {type TemplateData} from './TemplateData.js';\nimport {type TemplateRenders} from './TemplateRenders.js';\n\nexport type RenderCarsonTemplateOptions = {\n  templateId: string;\n  templateData: TemplateData;\n};\n\n/**\n * Renders a Carson template with provided template data.\n */\nexport async function renderCarsonTemplate(\n  options: RenderCarsonTemplateOptions,\n): Promise<TemplateRenders> {\n  let template = await readCarsonTemplate(options.templateId);\n  let templateModule = await importCarsonTemplate(options.templateId);\n  let templateRenders: TemplateRenders = [];\n\n  for (let file of template.files) {\n    templateRenders.push(\n      ...(\n        await file.render(\n          {\n            ...templateModule,\n            ...options.templateData,\n          },\n          {disablePrettier: true},\n        )\n      ).map((templateRender) => ({...templateRender, template: {path: file.path ?? ''}})),\n    );\n  }\n\n  templateRenders = _.sortBy(templateRenders, [\n    (templateRender) => templateRender.attributes.to,\n    (templateRender) => templateRender.attributes.strategy,\n    (templateRender) => templateRender.content,\n  ]);\n\n  return templateRenders;\n}\n"],"names":["_","importCarsonTemplate","readCarsonTemplate","renderCarsonTemplate","options","template","templateId","templateModule","templateRenders","file","files","push","render","templateData","disablePrettier","map","templateRender","path","sortBy","attributes","to","strategy","content"],"mappings":"AAAA,OAAOA,OAAO,SAAS;AAEvB,SAAQC,oBAAoB,EAAEC,kBAAkB,QAAO,iBAAiB;AASxE;;CAEC,GACD,OAAO,eAAeC,qBACpBC,OAAoC;IAEpC,IAAIC,WAAW,MAAMH,mBAAmBE,QAAQE,UAAU;IAC1D,IAAIC,iBAAiB,MAAMN,qBAAqBG,QAAQE,UAAU;IAClE,IAAIE,kBAAmC,EAAE;IAEzC,KAAK,IAAIC,QAAQJ,SAASK,KAAK,CAAE;QAC/BF,gBAAgBG,IAAI,IACf,AACD,CAAA,MAAMF,KAAKG,MAAM,CACf;YACE,GAAGL,cAAc;YACjB,GAAGH,QAAQS,YAAY;QACzB,GACA;YAACC,iBAAiB;QAAI,EACxB,EACAC,GAAG,CAAC,CAACC,iBAAoB,CAAA;gBAAC,GAAGA,cAAc;gBAAEX,UAAU;oBAACY,MAAMR,KAAKQ,IAAI,IAAI;gBAAE;YAAC,CAAA;IAEpF;IAEAT,kBAAkBR,EAAEkB,MAAM,CAACV,iBAAiB;QAC1C,CAACQ,iBAAmBA,eAAeG,UAAU,CAACC,EAAE;QAChD,CAACJ,iBAAmBA,eAAeG,UAAU,CAACE,QAAQ;QACtD,CAACL,iBAAmBA,eAAeM,OAAO;KAC3C;IAED,OAAOd;AACT"}
+{"version":3,"sources":["../../src/template/renderCarsonTemplate.ts"],"sourcesContent":["import {pathToPosixPath} from '@jakubmazanec/fs-utils';\nimport _ from 'lodash';\nimport path from 'node:path';\n\nimport {\n  importCarsonTemplate,\n  parseCarsonTemplateId,\n  readCarsonTemplate,\n  resolveModule,\n} from './internals.js';\nimport {type TemplateData} from './TemplateData.js';\nimport {type TemplateRenders} from './TemplateRenders.js';\n\nexport type RenderCarsonTemplateOptions = {\n  templateId: string;\n  templateData: TemplateData;\n};\n\n/**\n * Renders a Carson template with provided template data.\n */\nexport async function renderCarsonTemplate(\n  options: RenderCarsonTemplateOptions,\n): Promise<TemplateRenders> {\n  let [moduleId] = parseCarsonTemplateId(options.templateId);\n  let modulePath = await resolveModule(moduleId);\n  let template = await readCarsonTemplate(options.templateId);\n  let templateModule = await importCarsonTemplate(options.templateId);\n  let templateRenders: TemplateRenders = [];\n\n  for (let file of template.files) {\n    templateRenders.push(\n      ...(\n        await file.render(\n          {\n            ...templateModule,\n            ...options.templateData,\n          },\n          {disablePrettier: true},\n        )\n      ).map((templateRender) => ({\n        ...templateRender,\n        template: {\n          path: pathToPosixPath(\n            `${moduleId}/${path.relative(modulePath, file.path ?? modulePath)}`,\n          ),\n        },\n      })),\n    );\n  }\n\n  templateRenders = _.sortBy(templateRenders, [\n    (templateRender) => templateRender.attributes.to,\n    (templateRender) => templateRender.attributes.strategy,\n    (templateRender) => templateRender.content,\n  ]);\n\n  return templateRenders;\n}\n"],"names":["pathToPosixPath","_","path","importCarsonTemplate","parseCarsonTemplateId","readCarsonTemplate","resolveModule","renderCarsonTemplate","options","moduleId","templateId","modulePath","template","templateModule","templateRenders","file","files","push","render","templateData","disablePrettier","map","templateRender","relative","sortBy","attributes","to","strategy","content"],"mappings":"AAAA,SAAQA,eAAe,QAAO,yBAAyB;AACvD,OAAOC,OAAO,SAAS;AACvB,OAAOC,UAAU,YAAY;AAE7B,SACEC,oBAAoB,EACpBC,qBAAqB,EACrBC,kBAAkB,EAClBC,aAAa,QACR,iBAAiB;AASxB;;CAEC,GACD,OAAO,eAAeC,qBACpBC,OAAoC;IAEpC,IAAI,CAACC,SAAS,GAAGL,sBAAsBI,QAAQE,UAAU;IACzD,IAAIC,aAAa,MAAML,cAAcG;IACrC,IAAIG,WAAW,MAAMP,mBAAmBG,QAAQE,UAAU;IAC1D,IAAIG,iBAAiB,MAAMV,qBAAqBK,QAAQE,UAAU;IAClE,IAAII,kBAAmC,EAAE;IAEzC,KAAK,IAAIC,QAAQH,SAASI,KAAK,CAAE;QAC/BF,gBAAgBG,IAAI,IACf,AACD,CAAA,MAAMF,KAAKG,MAAM,CACf;YACE,GAAGL,cAAc;YACjB,GAAGL,QAAQW,YAAY;QACzB,GACA;YAACC,iBAAiB;QAAI,EACxB,EACAC,GAAG,CAAC,CAACC,iBAAoB,CAAA;gBACzB,GAAGA,cAAc;gBACjBV,UAAU;oBACRV,MAAMF,gBACJ,CAAC,EAAES,SAAS,CAAC,EAAEP,KAAKqB,QAAQ,CAACZ,YAAYI,KAAKb,IAAI,IAAIS,YAAY,CAAC;gBAEvE;YACF,CAAA;IAEJ;IAEAG,kBAAkBb,EAAEuB,MAAM,CAACV,iBAAiB;QAC1C,CAACQ,iBAAmBA,eAAeG,UAAU,CAACC,EAAE;QAChD,CAACJ,iBAAmBA,eAAeG,UAAU,CAACE,QAAQ;QACtD,CAACL,iBAAmBA,eAAeM,OAAO;KAC3C;IAED,OAAOd;AACT"}

package/dist/workspace/WorkspaceCreateOptions.d.ts

@@ -1,5 +1,5 @@
 /**
- * {@link Workspace.create | Workspace.create} options parameter.
+ * {@link Workspace.create} options parameter.
  */
 export type WorkspaceCreateOptions = {
     path: string;

package/dist/workspace/WorkspaceCreateOptions.js

@@ -1,5 +1,5 @@
 /**
- * {@link Workspace.create | Workspace.create} options parameter.
+ * {@link Workspace.create} options parameter.
  */ export { };
 
 //# sourceMappingURL=WorkspaceCreateOptions.js.map

package/dist/workspace/WorkspaceCreateOptions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/workspace/WorkspaceCreateOptions.ts"],"sourcesContent":["/**\n * {@link Workspace.create | Workspace.create} options parameter.\n */\nexport type WorkspaceCreateOptions = {\n  path: string;\n  templateId: string;\n  args: Record<string, unknown>;\n};\n"],"names":[],"mappings":"AAAA;;CAEC,GACD,WAIE"}
+{"version":3,"sources":["../../src/workspace/WorkspaceCreateOptions.ts"],"sourcesContent":["/**\n * {@link Workspace.create} options parameter.\n */\nexport type WorkspaceCreateOptions = {\n  path: string;\n  templateId: string;\n  args: Record<string, unknown>;\n};\n"],"names":[],"mappings":"AAAA;;CAEC,GACD,WAIE"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@jakubmazanec/carson",
-  "version": "0.1.0-2d1145f",
+  "version": "0.1.0-2f12db0",
   "description": "Tool for managing workspace and project configuration.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jakubmazanec/js-tools",
+    "url": "git@github.com:jakubmazanec/js-tools.git",
     "directory": "packages/carson"
   },
   "license": "AGPL-3.0-only",
@@ -31,13 +31,13 @@
     "typecheck": "tsc --project tsconfig.typecheck.json"
   },
   "dependencies": {
-    "@jakubmazanec/args": "1.0.1-2d1145f",
-    "@jakubmazanec/cli": "0.1.0-2d1145f",
-    "@jakubmazanec/error": "2.0.1-2d1145f",
-    "@jakubmazanec/fs-utils": "0.1.0-2d1145f",
-    "@jakubmazanec/template": "1.0.1-2d1145f",
-    "@jakubmazanec/ts-utils": "2.1.0-2d1145f",
-    "@jakubmazanec/zod-utils": "1.0.0-2d1145f",
+    "@jakubmazanec/args": "1.0.1-2f12db0",
+    "@jakubmazanec/cli": "0.1.0-2f12db0",
+    "@jakubmazanec/error": "2.0.1-2f12db0",
+    "@jakubmazanec/fs-utils": "0.1.0-2f12db0",
+    "@jakubmazanec/template": "1.0.1-2f12db0",
+    "@jakubmazanec/ts-utils": "2.1.0-2f12db0",
+    "@jakubmazanec/zod-utils": "1.0.0-2f12db0",
     "chalk": "^5.2.0",
     "diff": "^5.1.0",
     "fast-glob": "^3.2.11",

package/src/template/TemplateAttributes.ts

@@ -1,7 +1,9 @@
 import {z} from 'zod';
 
+// TODO: add strategy 'none' so when you using template A that extends template B, you can overwrite template files to no-op
 let strategyTemplateAttributeSchema = z.union([
   z.literal('create'),
+  z.literal('ensure'),
   z.literal('overwrite'),
   z.literal('merge'),
   z.literal('check'),
@@ -10,7 +12,6 @@ let strategyTemplateAttributeSchema = z.union([
 
 export const templateAttributesSchema = z
   .object({
-    // TODO: add strategy 'none' so when you using template A that extends template B, you can overwrite template files to no-op
     strategy: strategyTemplateAttributeSchema,
   })
   .strict();

package/src/template/applyTemplateRenders.ts

@@ -1,3 +1,5 @@
+// TODO: can this be fixed?
+/* eslint-disable complexity -- TODO */
 import fs from 'fs-extra';
 import path from 'node:path';
 import prettier from 'prettier';
@@ -34,6 +36,7 @@ export async function applyTemplateRenders({
   // we need to clear Prettier cache, because we are changing file system
   prettier.clearConfigCache();
 
+  // first, we read the existing snapshots and use them to undo previous changes
   let templateRenderSnapshotsPath = path.join(
     targetPath,
     CARSON_CONFIG_DIRECTORY,
@@ -53,6 +56,12 @@ export async function applyTemplateRenders({
         continue;
       }
 
+      if (templateRenderSnapshot.attributes.strategy === 'ensure') {
+        await deleteUsingTemplateRender(templateRenderSnapshot, targetPath, {
+          onlyDeleteWhenContentsMatch: true,
+        });
+      }
+
       if (templateRenderSnapshot.attributes.strategy === 'overwrite') {
         await deleteUsingTemplateRender(templateRenderSnapshot, targetPath);
       }
@@ -67,14 +76,32 @@ export async function applyTemplateRenders({
     }
   }
 
-  if (!ignoreStrategies.includes('create')) {
-    for (let templateRender of templateRenders) {
-      if (templateRender.attributes.strategy === 'create') {
+  // second, we apply strategies that create files
+  for (let templateRender of templateRenders) {
+    let strategy =
+      typeof templateRender.attributes.strategy === 'string'
+        ? templateRender.attributes.strategy
+        : templateRender.attributes.strategy[0];
+
+    if (ignoreStrategies.includes(strategy)) {
+      continue;
+    }
+
+    if (templateRender.attributes.strategy === 'create') {
+      await createUsingTemplateRender(templateRender, targetPath);
+    }
+
+    if (templateRender.attributes.strategy === 'ensure') {
+      let to = path.join(targetPath, templateRender.attributes.to);
+      let doesToExist = await fs.pathExists(to);
+
+      if (!doesToExist) {
         await createUsingTemplateRender(templateRender, targetPath);
       }
     }
   }
 
+  // third, we apply strategies that change files
   for (let templateRender of templateRenders) {
     let strategy =
       typeof templateRender.attributes.strategy === 'string'

package/src/template/internals/deleteUsingTemplateRender.ts

@@ -1,16 +1,35 @@
 import fs from 'fs-extra';
 import path from 'node:path';
 
+import {prettify} from './prettify.js';
 import {type TemplateRenderSnapshot} from './TemplateRenderSnapshot.js';
 import {type TemplateRender} from '../TemplateRender.js';
 
+export type DeleteUsingTemplateRenderOptions = {
+  onlyDeleteWhenContentsMatch?: boolean;
+};
+
 export async function deleteUsingTemplateRender(
   templateRender: TemplateRender | TemplateRenderSnapshot,
   basePath: string,
+  options?: DeleteUsingTemplateRenderOptions,
 ) {
   let to = path.join(basePath, templateRender.attributes.to);
 
-  if (await fs.pathExists(to)) {
-    await fs.rm(to);
+  if (!(await fs.pathExists(to))) {
+    return;
+  }
+
+  if (options?.onlyDeleteWhenContentsMatch) {
+    let existingContent = await fs.readFile(to, {encoding: 'utf8'});
+    let newContent = await prettify(templateRender.content, to);
+
+    if (existingContent.trim() === newContent.trim()) {
+      await fs.rm(to);
+    }
+
+    return;
   }
+
+  await fs.rm(to);
 }

package/src/template/internals/saveTemplateRenderSnapshots.ts

@@ -12,6 +12,7 @@ export async function saveTemplateRenderSnapshots(
 
   for (let templateRender of templateRenders) {
     if (
+      templateRender.attributes.strategy === 'ensure' ||
       templateRender.attributes.strategy === 'overwrite' ||
       templateRender.attributes.strategy === 'merge' ||
       templateRender.attributes.strategy[0] === 'insert'

package/src/template/renderCarsonTemplate.ts

@@ -1,6 +1,13 @@
+import {pathToPosixPath} from '@jakubmazanec/fs-utils';
 import _ from 'lodash';
+import path from 'node:path';
 
-import {importCarsonTemplate, readCarsonTemplate} from './internals.js';
+import {
+  importCarsonTemplate,
+  parseCarsonTemplateId,
+  readCarsonTemplate,
+  resolveModule,
+} from './internals.js';
 import {type TemplateData} from './TemplateData.js';
 import {type TemplateRenders} from './TemplateRenders.js';
 
@@ -15,6 +22,8 @@ export type RenderCarsonTemplateOptions = {
 export async function renderCarsonTemplate(
   options: RenderCarsonTemplateOptions,
 ): Promise<TemplateRenders> {
+  let [moduleId] = parseCarsonTemplateId(options.templateId);
+  let modulePath = await resolveModule(moduleId);
   let template = await readCarsonTemplate(options.templateId);
   let templateModule = await importCarsonTemplate(options.templateId);
   let templateRenders: TemplateRenders = [];
@@ -29,7 +38,14 @@ export async function renderCarsonTemplate(
           },
           {disablePrettier: true},
         )
-      ).map((templateRender) => ({...templateRender, template: {path: file.path ?? ''}})),
+      ).map((templateRender) => ({
+        ...templateRender,
+        template: {
+          path: pathToPosixPath(
+            `${moduleId}/${path.relative(modulePath, file.path ?? modulePath)}`,
+          ),
+        },
+      })),
     );
   }
 

package/src/workspace/WorkspaceCreateOptions.ts

@@ -1,5 +1,5 @@
 /**
- * {@link Workspace.create | Workspace.create} options parameter.
+ * {@link Workspace.create} options parameter.
  */
 export type WorkspaceCreateOptions = {
   path: string;