@jakubmazanec/carson 0.1.0-c5ebb6f → 0.1.0-next.336fe21

package/dist/workspace.js

@@ -1,12 +1,24 @@
 export * from './workspace/Project.js';
 export * from './workspace/ProjectConfig.js';
+export * from './workspace/ProjectCreateOptions.js';
 export * from './workspace/ProjectError.js';
+export * from './workspace/ProjectOptions.js';
+export * from './workspace/ProjectUpdateOptions.js';
 export * from './workspace/saveProjectConfig.js';
 export * from './workspace/saveWorkspaceConfig.js';
 export * from './workspace/Workspace.js';
 export * from './workspace/WorkspaceConfig.js';
+export * from './workspace/WorkspaceCreateOptions.js';
+export * from './workspace/WorkspaceCreateProjectOptions.js';
 export * from './workspace/WorkspaceDependencies.js';
 export * from './workspace/WorkspaceError.js';
+export * from './workspace/WorkspaceFindAndReadOptions.js';
+export * from './workspace/WorkspaceOptions.js';
+export * from './workspace/WorkspaceOptionsProject.js';
+export * from './workspace/WorkspacePackageJson.js';
+export * from './workspace/WorkspaceProjectGlobs.js';
+export * from './workspace/WorkspaceProjects.js';
 export * from './workspace/WorkspaceRepository.js';
+export * from './workspace/WorkspaceUpdateOptions.js';
 
 //# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/workspace.ts"],"sourcesContent":["export * from './workspace/Project.js';\nexport * from './workspace/ProjectConfig.js';\nexport * from './workspace/ProjectError.js';\nexport * from './workspace/saveProjectConfig.js';\nexport * from './workspace/saveWorkspaceConfig.js';\nexport * from './workspace/Workspace.js';\nexport * from './workspace/WorkspaceConfig.js';\nexport * from './workspace/WorkspaceDependencies.js';\nexport * from './workspace/WorkspaceError.js';\nexport * from './workspace/WorkspaceRepository.js';\n"],"names":[],"mappings":"AAAA,cAAc,yBAAyB;AACvC,cAAc,+BAA+B;AAC7C,cAAc,8BAA8B;AAC5C,cAAc,mCAAmC;AACjD,cAAc,qCAAqC;AACnD,cAAc,2BAA2B;AACzC,cAAc,iCAAiC;AAC/C,cAAc,uCAAuC;AACrD,cAAc,gCAAgC;AAC9C,cAAc,qCAAqC"}
+{"version":3,"sources":["../src/workspace.ts"],"sourcesContent":["export * from './workspace/Project.js';\nexport * from './workspace/ProjectConfig.js';\nexport * from './workspace/ProjectCreateOptions.js';\nexport * from './workspace/ProjectError.js';\nexport * from './workspace/ProjectOptions.js';\nexport * from './workspace/ProjectUpdateOptions.js';\nexport * from './workspace/saveProjectConfig.js';\nexport * from './workspace/saveWorkspaceConfig.js';\nexport * from './workspace/Workspace.js';\nexport * from './workspace/WorkspaceConfig.js';\nexport * from './workspace/WorkspaceCreateOptions.js';\nexport * from './workspace/WorkspaceCreateProjectOptions.js';\nexport * from './workspace/WorkspaceDependencies.js';\nexport * from './workspace/WorkspaceError.js';\nexport * from './workspace/WorkspaceFindAndReadOptions.js';\nexport * from './workspace/WorkspaceOptions.js';\nexport * from './workspace/WorkspaceOptionsProject.js';\nexport * from './workspace/WorkspacePackageJson.js';\nexport * from './workspace/WorkspaceProjectGlobs.js';\nexport * from './workspace/WorkspaceProjects.js';\nexport * from './workspace/WorkspaceRepository.js';\nexport * from './workspace/WorkspaceUpdateOptions.js';\n"],"names":[],"mappings":"AAAA,cAAc,yBAAyB;AACvC,cAAc,+BAA+B;AAC7C,cAAc,sCAAsC;AACpD,cAAc,8BAA8B;AAC5C,cAAc,gCAAgC;AAC9C,cAAc,sCAAsC;AACpD,cAAc,mCAAmC;AACjD,cAAc,qCAAqC;AACnD,cAAc,2BAA2B;AACzC,cAAc,iCAAiC;AAC/C,cAAc,wCAAwC;AACtD,cAAc,+CAA+C;AAC7D,cAAc,uCAAuC;AACrD,cAAc,gCAAgC;AAC9C,cAAc,6CAA6C;AAC3D,cAAc,kCAAkC;AAChD,cAAc,yCAAyC;AACvD,cAAc,sCAAsC;AACpD,cAAc,uCAAuC;AACrD,cAAc,mCAAmC;AACjD,cAAc,qCAAqC;AACnD,cAAc,wCAAwC"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@jakubmazanec/carson",
-  "version": "0.1.0-c5ebb6f",
+  "version": "0.1.0-next.336fe21",
   "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",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "build": "swc src -d dist && tsc",
-    "clean": "del-cli dist *.tsbuildinfo",
+    "clean": "del-cli coverage dist *.tsbuildinfo",
     "develop": "swc src -d dist --watch",
     "document": "typedoc --options typedoc.config.cjs",
     "format": "prettier . --write --ignore-unknown --ignore-path ../../.prettierignore",
@@ -31,13 +31,13 @@
     "typecheck": "tsc --project tsconfig.typecheck.json"
   },
   "dependencies": {
-    "@jakubmazanec/args": "1.0.1-c5ebb6f",
-    "@jakubmazanec/cli": "0.1.0-c5ebb6f",
-    "@jakubmazanec/error": "2.0.1-c5ebb6f",
-    "@jakubmazanec/fs-utils": "0.1.0-c5ebb6f",
-    "@jakubmazanec/template": "1.0.1-c5ebb6f",
-    "@jakubmazanec/ts-utils": "2.1.0-c5ebb6f",
-    "@jakubmazanec/zod-utils": "1.0.0-c5ebb6f",
+    "@jakubmazanec/args": "1.0.1-next.336fe21",
+    "@jakubmazanec/cli": "0.1.0-next.336fe21",
+    "@jakubmazanec/error": "2.0.1-next.336fe21",
+    "@jakubmazanec/fs-utils": "0.1.0-next.336fe21",
+    "@jakubmazanec/template": "1.0.1-next.336fe21",
+    "@jakubmazanec/ts-utils": "2.1.0-next.336fe21",
+    "@jakubmazanec/zod-utils": "1.0.0-next.336fe21",
     "chalk": "^5.2.0",
     "diff": "^5.1.0",
     "fast-glob": "^3.2.11",

package/src/commands/create-project/CreateProject.tsx

@@ -8,7 +8,7 @@ import {type createProjectCommand} from './createProjectCommand.js';
 import {CreateProjectInput, type CreateProjectInputResult} from './CreateProjectInput.js';
 import {runCreateProject} from './runCreateProject.js';
 import {type Workspace} from '../../workspace.js';
-import {packageNameToDirectory} from '../internals.js';
+import {packageNameToDirectory, type CommandStatus} from '../internals.js';
 
 const ONLY_ONE_STAR_REGEXP = /^(?!(.*?\*){2,}|.*? |\*$).*?\*.*$/;
 
@@ -18,7 +18,7 @@ export type CreateProjectProps = {
 };
 
 export function CreateProject({args, workspace}: CreateProjectProps) {
-  let [status, setStatus] = useState<'finished' | 'in-progress' | 'not-started'>('not-started');
+  let [status, setStatus] = useState<CommandStatus>('not-started');
   let [subscription, setSubscription] = useState<ZenObservable.Subscription | null>(null);
   let [jobs, setJobs] = useState<string[]>([]);
   let [createProjectInputResult, setCreateProjectInputResult] = useState<CreateProjectInputResult>(

package/src/commands/create-project/CreateProjectInput.ts

@@ -22,7 +22,7 @@ export const CreateProjectInput = createForm({
       validate: (value: string) => {
         if (!PROJECT_NAME_ID_REGEXP.test(value)) {
           throw new Error(
-            'Project name can containg only lowercase letters, numbers, hyphen, @, dot or /.',
+            'Project name can contain only lowercase letters, numbers, hyphen, @, dot or /.',
           );
         }
       },

package/src/commands/create-project/createProjectCommand.tsx

@@ -8,11 +8,7 @@ export const createProjectCommand = new Command(
   'create project',
   async (args, program) => {
     let targetPath = path.resolve(process.cwd(), args.options.path ?? '');
-    let workspace = await Workspace.findAndRead(targetPath);
-
-    if (!workspace) {
-      throw new Error(`No workspace found at "${targetPath}"!`);
-    }
+    let workspace = await Workspace.findAndRead(targetPath, {throwIfNotFound: true});
 
     await program.renderElement(<CreateProject args={args} workspace={workspace} />);
   },

package/src/commands/create-project/runCreateProject.ts

@@ -1,7 +1,4 @@
 import {type CommandArguments} from '@jakubmazanec/cli';
-import {isEmptyDirectory} from '@jakubmazanec/fs-utils';
-import fs from 'fs-extra';
-import path from 'node:path';
 import Observable from 'zen-observable';
 
 import {type createProjectCommand} from './createProjectCommand.js';
@@ -26,27 +23,17 @@ export function runCreateProject({
 }: CreateProjectOptions) {
   return new Observable<CreateProjectStatus>((observer) => {
     (async () => {
-      observer.next('TODO');
+      observer.next('Creating files');
 
-      let resolvedProjectPath = path.resolve(projectPath);
-
-      // check if path is ok
-      await fs.ensureDir(resolvedProjectPath);
-
-      let isProjectPathEmpty = await isEmptyDirectory(resolvedProjectPath);
-
-      if (!isProjectPathEmpty) {
-        throw new Error(`Directory "${resolvedProjectPath}" must be empty`);
-      }
-
-      // create new project
       let project = await workspace.createProject({
-        projectPath: resolvedProjectPath,
+        projectPath,
         projectName,
         templateId,
         args,
       });
 
+      observer.next('Updating the new project');
+
       await project.update({args});
     })()
       .then(() => {

package/src/commands/create-workspace/CreateWorkspace.tsx

@@ -1,19 +1,20 @@
 import {Header, icons, colors, type CommandArguments, useProgram} from '@jakubmazanec/cli';
 import chalk from 'chalk';
 import {Box, Text} from 'ink';
+import path from 'node:path';
 import {useEffect, useState} from 'react';
 
 import {type createWorkspaceCommand} from './createWorkspaceCommand.js';
 import {CreateWorkspaceInput, type CreateWorkspaceInputResult} from './CreateWorkspaceInput.js';
 import {runCreateWorkspace} from './runCreateWorkspace.js';
+import {type CommandStatus} from '../internals.js';
 
 export type CreateWorkspaceProps = {
   args: CommandArguments<typeof createWorkspaceCommand>;
-  path: string;
 };
 
-export function CreateWorkspace({args, path}: CreateWorkspaceProps) {
-  let [status, setStatus] = useState<'finished' | 'in-progress' | 'not-started'>('not-started');
+export function CreateWorkspace({args}: CreateWorkspaceProps) {
+  let [status, setStatus] = useState<CommandStatus>('not-started');
   let [subscription, setSubscription] = useState<ZenObservable.Subscription | null>(null);
   let [jobs, setJobs] = useState<string[]>([]);
   let [createWorkspaceInputResult, setCreateWorkspaceInputResult] =
@@ -21,6 +22,7 @@ export function CreateWorkspace({args, path}: CreateWorkspaceProps) {
       templateId: {value: args.options.template ?? '', isComplete: !!args.options.template},
     }));
   let {exit} = useProgram();
+  let workspacePath = path.resolve(process.cwd(), args.options.path ?? '');
 
   useEffect(() => {
     if (Object.entries(createWorkspaceInputResult).every(([, result]) => result.isComplete)) {
@@ -31,7 +33,7 @@ export function CreateWorkspace({args, path}: CreateWorkspaceProps) {
   useEffect(() => {
     if (status === 'in-progress' && !subscription) {
       let newSubscription = runCreateWorkspace({
-        workspacePath: path,
+        workspacePath,
         templateId: createWorkspaceInputResult.templateId.value,
         args,
       }).subscribe({
@@ -55,11 +57,11 @@ export function CreateWorkspace({args, path}: CreateWorkspaceProps) {
         subscription.unsubscribe();
       }
     };
-  }, [createWorkspaceInputResult, path, status, subscription, args, exit]);
+  }, [createWorkspaceInputResult, status, subscription, args, exit, workspacePath]);
 
   return (
     <Box flexDirection="column">
-      <Text>{`Creating workspace at ${chalk[colors.highlighted](path)}.`}</Text>
+      <Text>{`Creating workspace at ${chalk[colors.info](workspacePath)}.`}</Text>
 
       <CreateWorkspaceInput
         values={createWorkspaceInputResult}

package/src/commands/create-workspace/createWorkspaceCommand.tsx

@@ -1,24 +1,11 @@
 import {Command} from '@jakubmazanec/cli';
-import {isEmptyDirectory} from '@jakubmazanec/fs-utils';
-import fs from 'fs-extra';
-import path from 'node:path';
 
 import {CreateWorkspace} from './CreateWorkspace.js';
 
 export const createWorkspaceCommand = new Command(
   'create workspace',
   async (args, program) => {
-    let workspacePath = path.resolve(process.cwd(), args.options.path ?? '');
-
-    await fs.ensureDir(workspacePath);
-
-    let isWorkspacePathEmpty = await isEmptyDirectory(workspacePath);
-
-    if (!isWorkspacePathEmpty) {
-      throw new Error(`Directory "${workspacePath}" must be empty`);
-    }
-
-    await program.renderElement(<CreateWorkspace args={args} path={workspacePath} />);
+    await program.renderElement(<CreateWorkspace args={args} />);
   },
   {
     description: 'Creates a new workspacee.',

package/src/commands/create-workspace/runCreateWorkspace.ts

@@ -1,7 +1,4 @@
 import {type CommandArguments} from '@jakubmazanec/cli';
-import {isEmptyDirectory} from '@jakubmazanec/fs-utils';
-import fs from 'fs-extra';
-import path from 'node:path';
 import Observable from 'zen-observable';
 
 import {type createWorkspaceCommand} from './createWorkspaceCommand.js';
@@ -18,25 +15,16 @@ export type CreateWorkspaceStatus = string;
 export function runCreateWorkspace({workspacePath, templateId, args}: CreateWorkspaceOptions) {
   return new Observable<CreateWorkspaceStatus>((observer) => {
     (async () => {
-      observer.next('TODO');
+      observer.next('Creating files');
 
-      let resolvedWorkspacePath = path.resolve(workspacePath);
-
-      await fs.ensureDir(resolvedWorkspacePath);
-
-      let isWorkspacePathEmpty = await isEmptyDirectory(resolvedWorkspacePath);
-
-      if (!isWorkspacePathEmpty) {
-        throw new Error(`Directory "${resolvedWorkspacePath}" must be empty`);
-      }
-
-      // create new workspace
       let workspace = await Workspace.create({
         args,
-        path: resolvedWorkspacePath,
+        path: workspacePath,
         templateId,
       });
 
+      observer.next('Updating the new workspace');
+
       await workspace.update({args});
     })()
       .then(() => {

package/src/commands/internals/CommandStatus.ts

@@ -0,0 +1 @@
+export type CommandStatus = 'finished' | 'in-progress' | 'not-started';

package/src/commands/internals.ts

@@ -1 +1,2 @@
+export * from './internals/CommandStatus.js';
 export * from './internals/packageNameToDirectory.js';

package/src/commands/update-workspace/UpdateWorkspace.tsx

@@ -41,7 +41,7 @@ export function UpdateWorkspace({workspace, args}: UpdateWorkspaceProps) {
 
       <Box marginTop={1} flexDirection="column">
         <Header showSpinner={!isFinished} icon={icons.success} marginBottom={1}>
-          <Text>Updating workspace...</Text>
+          <Text>Updating workspace and projects...</Text>
         </Header>
 
         {jobs.map((job) => (

package/src/commands/update-workspace/updateWorkspaceCommand.tsx

@@ -8,11 +8,7 @@ export const updateWorkspaceCommand = new Command(
   'update workspace',
   async (args, program) => {
     let resolvedPath = path.resolve(process.cwd(), args.options.path ?? '');
-    let workspace = await Workspace.findAndRead(resolvedPath);
-
-    if (!workspace) {
-      throw new Error(`No workspace found at "${resolvedPath}"!`);
-    }
+    let workspace = await Workspace.findAndRead(resolvedPath, {throwIfNotFound: true});
 
     await program.renderElement(<UpdateWorkspace workspace={workspace} args={args} />);
   },

package/src/template/CarsonTemplate.ts

@@ -9,12 +9,11 @@ import {type templateDataSchema} from './TemplateData.js';
  */
 export type CarsonTemplate = {
   /** Carson template name. */
-
   name: string;
 
   /** Carson template config. */
   config: CarsonTemplateConfig;
 
-  /** Carson template files, actually instances of {@linkcode Template}. */
+  /** Carson template files, actually instances of {@link Template}. */
   files: Array<Template<typeof templateAttributesSchema, typeof templateDataSchema>>;
 };

package/src/template/CarsonTemplateConfig.ts

@@ -10,6 +10,6 @@ export const carsonTemplateConfigSchema = z
   .strict();
 
 /**
- * Carson teamplate config.
+ * Carson template config.
  */
 export type CarsonTemplateConfig = z.infer<typeof carsonTemplateConfigSchema>;

package/src/template/CarsonTemplateError.ts

@@ -0,0 +1,19 @@
+import {createCustomErrorWithData} from '@jakubmazanec/error';
+
+/**
+ * A subclass of `Error` that indicates a Carson template failure.
+ */
+export const CarsonTemplateError = createCustomErrorWithData(
+  'CarsonTemplateError',
+  {
+    INVALID_CARSON_TEMPLATE_ID:
+      'Invalid Carson template ID "{0}". Carson template ID must consist of a module ID and a template name separated by a colon.',
+    CARSON_TEMPLATE_NOT_FOUND: 'Carson template "{0}" was not found in module "{1}".',
+    STRATEGY_UNSUPPORTED_EXTENSION:
+      'Strategy "{0}" in the template file "{1}" doesn\'t support extension "{2}".',
+    STRATEGY_MISSING_FILE: 'Strategy "{0}" in the template file "{1}" is missing file "{2}".',
+  },
+  class CarsonTemplateErrorData {
+    path?: string;
+  },
+);

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/TemplateRender.ts

@@ -4,9 +4,13 @@ import {type templateAttributesSchema} from './TemplateAttributes.js';
 import {type templateDataSchema} from './TemplateData.js';
 
 /**
- * A template render result.
+ * A result of rendering a Carson template file.
  */
 export type TemplateRender = BaseTemplateRender<
   typeof templateAttributesSchema,
   typeof templateDataSchema
->;
+> & {
+  template: {
+    path: string;
+  };
+};

package/src/template/TemplateRenders.ts

@@ -1,6 +1,6 @@
 import {type TemplateRender} from './TemplateRender.js';
 
 /**
- * A collection of template render results.
+ * A {@link TemplateRender} collection.
  */
 export type TemplateRenders = TemplateRender[];

package/src/template/applyTemplateRenders.ts

@@ -1,7 +1,10 @@
+// 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';
 import {
   createUsingTemplateRender,
   deleteUsingTemplateRender,
@@ -22,6 +25,9 @@ export type ApplyTemplateRendersOptions = {
   ignoreStrategies: string[];
 };
 
+/**
+ * Applies rendered Carson template to a specified path, i.e. creates and updates files based on the result of rendering each Carson template file.
+ */
 export async function applyTemplateRenders({
   templateRenders,
   path: targetPath,
@@ -30,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,
@@ -49,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);
       }
@@ -63,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'
@@ -98,7 +129,12 @@ export async function applyTemplateRenders({
       let doesToExist = await fs.pathExists(to);
 
       if (!doesToExist) {
-        throw new Error(`File "${to}" doesn't exist!`);
+        throw new CarsonTemplateError('STRATEGY_MISSING_FILE', {
+          messageParameters: [templateRender.attributes.strategy, templateRender.template.path, to],
+          data: {
+            path: to,
+          },
+        });
       }
     }
   }

package/src/template/internals/TemplateRenderSnapshot.ts

@@ -7,6 +7,11 @@ export const templateRenderSnapshotSchema = z
   .object({
     attributes: baseTemplateAttributesSchema.pick({to: true}).merge(templateAttributesSchema),
     content: z.string(),
+    template: z
+      .object({
+        path: z.string(),
+      })
+      .strict(),
   })
   .strict();
 

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/insertUsingTemplateRender.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 
 import {prettify} from './prettify.js';
 import {type TemplateRenderSnapshot} from './TemplateRenderSnapshot.js';
+import {CarsonTemplateError} from '../CarsonTemplateError.js';
 import {type TemplateRender} from '../TemplateRender.js';
 
 export async function insertUsingTemplateRender(
@@ -33,7 +34,16 @@ export async function insertUsingTemplateRender(
     }
 
     default: {
-      throw new Error(`File extension "${extension}" is not supported!`);
+      throw new CarsonTemplateError('STRATEGY_UNSUPPORTED_EXTENSION', {
+        messageParameters: [
+          templateRender.attributes.strategy,
+          templateRender.template.path,
+          extension,
+        ],
+        data: {
+          path: templateRender.template.path,
+        },
+      });
     }
   }
 }

package/src/template/internals/mergeUsingTemplateRender.ts

@@ -7,6 +7,7 @@ import yaml from 'yaml';
 import {merge} from './merge.js';
 import {prettify} from './prettify.js';
 import {type TemplateRenderSnapshot} from './TemplateRenderSnapshot.js';
+import {CarsonTemplateError} from '../CarsonTemplateError.js';
 import {type TemplateRender} from '../TemplateRender.js';
 
 export async function mergeUsingTemplateRender(
@@ -38,7 +39,16 @@ export async function mergeUsingTemplateRender(
     }
 
     default: {
-      throw new Error(`File extension "${extension}" is not supported!`);
+      throw new CarsonTemplateError('STRATEGY_UNSUPPORTED_EXTENSION', {
+        messageParameters: [
+          templateRender.attributes.strategy,
+          templateRender.template.path,
+          extension,
+        ],
+        data: {
+          path: templateRender.template.path,
+        },
+      });
     }
   }
 }

package/src/template/internals/parseCarsonTemplateId.ts

@@ -1,8 +1,12 @@
+import {CarsonTemplateError} from '../CarsonTemplateError.js';
+
 export function parseCarsonTemplateId(value: string): [moduleId: string, templateName: string] {
   let parts = value.split(':');
 
   if (!parts[0] || !parts[1]) {
-    throw new Error('Template id is invalid!');
+    throw new CarsonTemplateError('INVALID_CARSON_TEMPLATE_ID', {
+      messageParameters: [value],
+    });
   }
 
   return [parts[0], parts[1]];

package/src/template/internals/readCarsonTemplate.ts

@@ -9,6 +9,7 @@ import {resolveModule} from './resolveModule.js';
 import {TEMPLATES_PATH, TEMPLATE_CONFIG_FILENAME} from '../../constants.js';
 import {type CarsonTemplate} from '../CarsonTemplate.js';
 import {carsonTemplateConfigSchema} from '../CarsonTemplateConfig.js';
+import {CarsonTemplateError} from '../CarsonTemplateError.js';
 import {templateAttributesSchema} from '../TemplateAttributes.js';
 
 export async function readCarsonTemplate(templateId: string): Promise<CarsonTemplate> {
@@ -42,5 +43,7 @@ export async function readCarsonTemplate(templateId: string): Promise<CarsonTemp
     return carsonTemplate;
   }
 
-  throw new Error(`Template ${templateId} was not found in module ${moduleId}!`);
+  throw new CarsonTemplateError('CARSON_TEMPLATE_NOT_FOUND', {
+    messageParameters: [templateId, moduleId],
+  });
 }

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'
@@ -22,13 +23,13 @@ export async function saveTemplateRenderSnapshots(
           strategy: templateRender.attributes.strategy,
         },
         content: templateRender.content,
+        template: templateRender.template,
       });
     }
   }
-  let uncompressedSnapshots = JSON.stringify(templateRendersSnapshots);
 
   await fs.writeFile(
     templateRenderSnapshotsPath,
-    deflateSync(strToU8(uncompressedSnapshots), {level: 1, mem: 0}),
+    deflateSync(strToU8(JSON.stringify(templateRendersSnapshots)), {level: 1, mem: 0}),
   );
 }