feat: Add ensureFileFrom helper (#6)

* feat: Add ensureFileFrom helper

* Run prettier

Author: kingston

.changeset/add-ensure-file-from-helper.md

@@ -0,0 +1,5 @@
+---
+'workspace-meta': patch
+---
+
+Add ensureFileFrom helper and configDirectory to PluginContext. The ensureFileFrom helper allows copying template files from the config directory, and all plugins now have access to the configDirectory path (inferred as `${workspacePath}/.workspace-meta`) in the plugin context.

src/helpers/ensure-file-from.test.ts

@@ -0,0 +1,122 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ensureFileFrom } from './ensure-file-from.js';
+
+vi.mock('node:fs/promises', () => ({
+  readFile: vi.fn(),
+}));
+
+describe('ensureFileFrom', () => {
+  it('should read template file from config directory and write to package', async () => {
+    const mockReadFile = vi.mocked(readFile);
+    const mockWriteFile = vi.fn();
+    const templateContent = 'This is template content';
+
+    mockReadFile.mockResolvedValue(templateContent);
+
+    const plugin = ensureFileFrom('.eslintrc.json', 'templates/eslintrc.json');
+
+    const ctx = {
+      workspacePath: '/workspace',
+      packagePath: '/workspace/packages/test',
+      packageName: 'test',
+      packageJson: { name: 'test' },
+      configDirectory: '/workspace/config',
+      isCheckMode: false,
+      readFile: vi.fn(),
+      writeFile: mockWriteFile,
+    };
+
+    await plugin(ctx);
+
+    expect(mockReadFile).toHaveBeenCalledWith(
+      path.resolve('/workspace/config', 'templates/eslintrc.json'),
+      'utf8',
+    );
+    expect(mockWriteFile).toHaveBeenCalledWith(
+      '.eslintrc.json',
+      templateContent,
+    );
+  });
+
+  it('should handle absolute template paths correctly', async () => {
+    const mockReadFile = vi.mocked(readFile);
+    const mockWriteFile = vi.fn();
+    const templateContent = 'Template content';
+
+    mockReadFile.mockResolvedValue(templateContent);
+
+    const plugin = ensureFileFrom('config.json', '../shared/config.json');
+
+    const ctx = {
+      workspacePath: '/workspace',
+      packagePath: '/workspace/packages/test',
+      packageName: 'test',
+      packageJson: { name: 'test' },
+      configDirectory: '/workspace/.config',
+      isCheckMode: false,
+      readFile: vi.fn(),
+      writeFile: mockWriteFile,
+    };
+
+    await plugin(ctx);
+
+    expect(mockReadFile).toHaveBeenCalledWith(
+      path.resolve('/workspace/.config', '../shared/config.json'),
+      'utf8',
+    );
+    expect(mockWriteFile).toHaveBeenCalledWith('config.json', templateContent);
+  });
+
+  it('should throw error if template file cannot be read', async () => {
+    const mockReadFile = vi.mocked(readFile);
+    const mockWriteFile = vi.fn();
+
+    mockReadFile.mockRejectedValue(new Error('File not found'));
+
+    const plugin = ensureFileFrom('output.txt', 'templates/missing.txt');
+
+    const ctx = {
+      workspacePath: '/workspace',
+      packagePath: '/workspace/packages/test',
+      packageName: 'test',
+      packageJson: { name: 'test' },
+      configDirectory: '/workspace/config',
+      isCheckMode: false,
+      readFile: vi.fn(),
+      writeFile: mockWriteFile,
+    };
+
+    await expect(plugin(ctx)).rejects.toThrow(
+      'Failed to read template file "templates/missing.txt" from config directory: File not found',
+    );
+
+    expect(mockWriteFile).not.toHaveBeenCalled();
+  });
+
+  it('should handle non-Error exceptions when reading template', async () => {
+    const mockReadFile = vi.mocked(readFile);
+    const mockWriteFile = vi.fn();
+
+    mockReadFile.mockRejectedValue('Unknown error');
+
+    const plugin = ensureFileFrom('output.txt', 'template.txt');
+
+    const ctx = {
+      workspacePath: '/workspace',
+      packagePath: '/workspace/packages/test',
+      packageName: 'test',
+      packageJson: { name: 'test' },
+      configDirectory: '/workspace/config',
+      isCheckMode: false,
+      readFile: vi.fn(),
+      writeFile: mockWriteFile,
+    };
+
+    await expect(plugin(ctx)).rejects.toThrow(
+      'Failed to read template file "template.txt" from config directory: Unknown error',
+    );
+  });
+});

src/helpers/ensure-file-from.ts

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import type { Plugin, PluginContext } from '#src/types/config.js';
+
+/**
+ * Ensures that a file exists with content loaded from a template file.
+ *
+ * @param filePath - The path to the file to ensure in the package.
+ * @param templatePath - The path to the template file relative to the config directory.
+ * @returns A plugin that ensures the file exists with the content from the template.
+ */
+export function ensureFileFrom(filePath: string, templatePath: string): Plugin {
+  return async (ctx: PluginContext): Promise<void> => {
+    const absoluteTemplatePath = path.resolve(
+      ctx.configDirectory,
+      templatePath,
+    );
+
+    try {
+      const content = await readFile(absoluteTemplatePath, 'utf8');
+      await ctx.writeFile(filePath, content);
+    } catch (error) {
+      throw new Error(
+        `Failed to read template file "${templatePath}" from config directory: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  };
+}

src/helpers/ensure-file.test.ts

@@ -57,4 +57,12 @@ describe('ensureFile', () => {
       'output.txt': 'Config: {"theme": "dark"}',
     });
   });
+
+  it('should not write file when content function returns undefined', async () => {
+    const content = vi.fn(() => undefined);
+    const result = await runPluginTestWrapper(ensureFile('test.txt', content));
+
+    expect(content).toHaveBeenCalledWith(result.context);
+    expect(result.files).toEqual({});
+  });
 });

src/helpers/ensure-file.ts

@@ -1,5 +1,12 @@
 import type { Plugin, PluginContext } from '#src/types/config.js';
 
+/**
+ * Ensures that a file exists with the given content.
+ *
+ * @param filePath - The path to the file to ensure.
+ * @param content - The content to write to the file. If a function is provided, it will be called with the plugin context.
+ * @returns A plugin that ensures the file exists with the given content.
+ */
 export function ensureFile(
   filePath: string,
   content:

src/helpers/ensure-package-json.test.ts

@@ -27,6 +27,7 @@ describe('ensurePackageJson', () => {
         name: 'test-package',
         version: '1.0.0',
       }),
+      result.context,
     );
 
     const packageJsonContents = result.files['package.json'] ?? '';

src/helpers/ensure-package-json.ts

@@ -9,10 +9,13 @@ import type { Plugin, PluginContext } from '#src/types/config.js';
  * @returns A plugin that ensures a package.json file exists and updates it with the provided updater
  */
 export function ensurePackageJson(
-  updater: (packageJson: PackageJson) => PackageJson | undefined,
+  updater: (
+    packageJson: PackageJson,
+    ctx: PluginContext,
+  ) => Promise<PackageJson | undefined> | PackageJson | undefined,
 ): Plugin {
   return async (ctx: PluginContext): Promise<void> => {
-    const result = updater(ctx.packageJson);
+    const result = await updater(ctx.packageJson, ctx);
     const finalPackageJson = result ?? ctx.packageJson;
 
     const content = `${JSON.stringify(finalPackageJson, null, 2)}\n`;

src/helpers/index.ts

@@ -1,5 +1,6 @@
 export * from './conditional-file.js';
 export * from './define-workspace-meta-config.js';
+export * from './ensure-file-from.js';
 export * from './ensure-file.js';
 export * from './ensure-package-json.js';
 export * from './prettier-formatter.js';

src/services/plugin-runner.test.ts

@@ -45,6 +45,7 @@ describe('PluginRunner', () => {
           packagePath: mockPackage.path,
           packageName: mockPackage.name,
           packageJson: mockPackage.packageJson,
+          configDirectory: '/workspace/.workspace-meta',
           isCheckMode: false,
         }),
       );

src/services/plugin-runner.ts

@@ -73,6 +73,7 @@ export class PluginRunner {
       packagePath: pkg.path,
       packageName: pkg.name,
       packageJson: pkg.packageJson,
+      configDirectory: path.join(this.workspacePath, '.workspace-meta'),
       isCheckMode: options.isCheckMode,
       readFile: this.createReadFile(pkg.path),
       writeFile: this.createWriteFile(