@w5s/configurator-core 1.0.0-alpha.1

package/src/block.ts

@@ -0,0 +1,153 @@
+import { type FileOptions, file, fileSync } from './file.js';
+
+export interface BlockOptions {
+  /**
+   * The marker builder function that will take either `markerBegin` or `markerEnd`
+   *
+   * @default '# ${mark} MANAGED BLOCK'
+   */
+  marker?: (mark: 'Begin' | 'End') => string;
+
+  /**
+   * File path
+   */
+  path: string;
+
+  /**
+   * Block content to insert
+   */
+  block: string;
+
+  /**
+   * Insert position
+   */
+  insertPosition?: ['before', 'BeginningOfFile' | RegExp] | ['after', 'EndOfFile' | RegExp];
+
+  /**
+   * Block target state
+   */
+  state?: 'present' | 'absent';
+}
+
+const EOF = 'EndOfFile';
+const BOF = 'BeginningOfFile';
+const insertAt = (str: string, index: number, toInsert: string) => str.slice(0, index) + toInsert + str.slice(index);
+const matchLast = (string: string, regexp: RegExp) => {
+  const matcher = new RegExp(regexp.source, `${regexp.flags}g`);
+  let firstIndex = -1;
+  let lastIndex = -1;
+  let matches;
+
+  while (true) {
+    matches = matcher.exec(string);
+    if (matches == null) {
+      break;
+    }
+    firstIndex = matches.index;
+    lastIndex = matcher.lastIndex;
+  }
+  return { firstIndex, lastIndex };
+};
+
+function toFileOptions(options: BlockOptions): FileOptions {
+  const {
+    marker = (mark) => `# ${mark.toUpperCase()} MANAGED BLOCK`,
+    path,
+    block: blockName,
+    insertPosition = ['after', EOF],
+    state = 'present',
+  } = options;
+
+  const EOL = '\n';
+  const beginBlock = marker('Begin');
+  const endBlock = marker('End');
+
+  /**
+   * @param content
+   */
+  function findBlock(content: string) {
+    const startIndex = content.indexOf(beginBlock);
+    const endIndex = content.indexOf(endBlock) + endBlock.length;
+
+    return {
+      endIndex,
+      exists: startIndex !== -1 && endIndex >= 0,
+      startIndex,
+    };
+  }
+
+  function apply(fullContent: string, blockContent: string) {
+    const found = findBlock(fullContent);
+    const remove = state === 'absent';
+    const replaceBlock = remove ? '' : beginBlock + EOL + blockContent + EOL + endBlock;
+    const [positionDirection, positionAnchor] = insertPosition;
+
+    if (found.exists) {
+      return fullContent.slice(0, found.startIndex) + replaceBlock + fullContent.slice(found.endIndex);
+    }
+    if (remove) {
+      return fullContent;
+    }
+    switch (positionDirection) {
+      case 'before': {
+        if (positionAnchor !== BOF) {
+          const { firstIndex } = matchLast(fullContent, positionAnchor);
+          if (firstIndex >= 0) {
+            return insertAt(fullContent, firstIndex, replaceBlock + EOL);
+          }
+        }
+
+        // Beginning of file
+        return replaceBlock + EOL + fullContent;
+      }
+      case 'after': {
+        // insert
+        if (positionAnchor !== EOF) {
+          const { lastIndex } = matchLast(fullContent, positionAnchor);
+          if (lastIndex >= 0) {
+            return insertAt(fullContent, lastIndex, EOL + replaceBlock);
+          }
+        }
+
+        // end of file
+        return fullContent + EOL + replaceBlock;
+      }
+
+      default: {
+        throw new Error(`Unsupported position ${String(positionDirection)}`);
+      }
+    }
+  }
+
+  return {
+    path,
+    state: 'present',
+    update: (sourceContent) => apply(sourceContent, blockName),
+  };
+}
+
+/**
+ * Replace asynchronously a block in file that follows pattern :
+ *
+ * marker(markerBegin)
+ * ...
+ * marker(markerEnd)
+ *
+ * @param options
+ */
+export function block(options: BlockOptions) {
+  return file(toFileOptions(options));
+}
+
+/**
+ * Replace synchronously a block in file that follows pattern :
+ *
+ * marker(markerBegin)
+ * ...
+ * marker(markerEnd)
+ *
+ * @param options
+ */
+export function blockSync(options: BlockOptions) {
+  return fileSync(toFileOptions(options));
+}

package/src/directory.ts

@@ -0,0 +1,91 @@
+import { chmodSync, mkdirSync, rmSync } from 'node:fs';
+import { chmod, mkdir, rm } from 'node:fs/promises';
+import { __exists } from './__exists.js';
+import type { FileMode } from './FileMode.js';
+import { __toMode } from './__toMode.js';
+import { __existsSync } from './__existsSync.js';
+
+export interface DirectoryOptions {
+  /**
+   * Directory path
+   */
+  readonly path: string;
+
+  /**
+   * Directory target state
+   */
+  readonly state: 'present' | 'absent';
+
+  /**
+   * File permissions
+   */
+  readonly mode?: FileMode;
+}
+
+/**
+ * Ensure directory is present/absent
+ *
+ * @example
+ * ```ts
+ * await directory({
+ *   path: 'foo/bar',
+ *   state: 'present',
+ *   mode: {
+ *     owner: { read: true, write: true, execute: true },
+ *     group: { read: true, write: true, execute: true },
+ *     other: { read: true, write: true, execute: true },
+ *   },
+ * })
+ * ```
+ *
+ * @param options
+ */
+export async function directory(options: DirectoryOptions): Promise<void> {
+  const { path, state, mode } = options;
+  const isPresent = await __exists(path);
+  if (state === 'present') {
+    const newMode = __toMode(mode);
+    if (!isPresent) {
+      await mkdir(path, { recursive: true, mode: newMode });
+    }
+    if (newMode != null && isPresent) {
+      await chmod(path, newMode);
+    }
+  } else if (isPresent) {
+    await rm(path, { recursive: true });
+  }
+}
+
+/**
+ * Ensure directory is present/absent
+ *
+ * @example
+ * ```ts
+ * directorySync({
+ *   path: 'foo/bar',
+ *   state: 'present',
+ *   mode: {
+ *     owner: { read: true, write: true, execute: true },
+ *     group: { read: true, write: true, execute: true },
+ *     other: { read: true, write: true, execute: true },
+ *   },
+ * })
+ * ```
+ *
+ * @param options
+ */
+export function directorySync(options: DirectoryOptions): void {
+  const { path, state, mode } = options;
+  const isPresent = __existsSync(path);
+  if (state === 'present') {
+    const newMode = __toMode(mode);
+    if (!isPresent) {
+      mkdirSync(path, { recursive: true, mode: newMode });
+    }
+    if (newMode != null && isPresent) {
+      chmodSync(path, newMode);
+    }
+  } else if (isPresent) {
+    rmSync(path, { recursive: true });
+  }
+}

package/src/exec.ts

@@ -0,0 +1,73 @@
+import { spawn, spawnSync } from 'node:child_process';
+
+export interface ExecOptions {
+  /**
+   * Current working directory
+   */
+  cwd?: string;
+
+  /**
+   * Stdio options
+   */
+  stdio?: 'inherit' | 'pipe' | 'ignore';
+}
+
+/**
+ * Runs a command in a shell and returns a promise that resolves with an object
+ * containing the stdout and stderr strings.
+ *
+ * @param command The command to run
+ * @param args The arguments to pass to the command
+ * @param options
+ * @returns A promise that resolves with an object like `{ stdout: string, stderr: string }`
+ */
+export function execSync(
+  command: string,
+  args: ReadonlyArray<string>,
+  options?: ExecOptions,
+): { stdout: string; stderr: string } {
+  const result = spawnSync(command, args, { ...options });
+  const encoding = 'utf8';
+
+  return { stdout: result.stdout.toString(encoding), stderr: result.stderr.toString(encoding) };
+}
+
+/**
+ * Runs a command in a shell and returns a promise that resolves with an object
+ * containing the stdout and stderr strings.
+ *
+ * @param command The command to run
+ * @param args The arguments to pass to the command
+ * @param options
+ */
+export async function exec(
+  command: string,
+  args: ReadonlyArray<string>,
+  options?: ExecOptions,
+): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const encoding = 'utf8';
+    const child = spawn(command, args, { ...options });
+    let stdout = '';
+    let stderr = '';
+
+    // Capture the stdout and stderr streams
+    if (child.stdout != null) {
+      child.stdout.on('data', (data) => {
+        stdout += data.toString(encoding);
+      });
+    }
+    if (child.stderr != null) {
+      child.stderr.on('data', (data) => {
+        stderr += data.toString(encoding);
+      });
+    }
+    // Handle process exit
+    child.on('close', (_code) => {
+      resolve({ stdout, stderr });
+    });
+
+    // Handle errors
+    child.on('error', reject);
+  });
+}

package/src/file.ts

@@ -0,0 +1,108 @@
+import { chmod, readFile, rm, writeFile } from 'node:fs/promises';
+import { chmodSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { __exists } from './__exists.js';
+import { __existsSync } from './__existsSync.js';
+import type { FileMode } from './FileMode.js';
+import { __toMode } from './__toMode.js';
+
+export interface FileOptions {
+  /**
+   * File path
+   */
+  readonly path: string;
+
+  /**
+   * File target state
+   */
+  readonly state: 'present' | 'absent';
+
+  /**
+   * File content mapping function
+   *
+   */
+  readonly update?: ((content: string) => string | undefined) | undefined;
+
+  /**
+   * File encoding
+   */
+  readonly encoding?: BufferEncoding;
+
+  /**
+   * File permissions
+   */
+  readonly mode?: FileMode;
+}
+
+/**
+ * Ensure file is present/absent with content initialized or modified with `update
+ *
+ * @example
+ * ```ts
+ * await file({
+ *   path: 'foo/bar',
+ *   state: 'present',
+ *   update: (content) => content + '_test', // This will append '_test' after current content
+ *   mode: {
+ *     owner: { read: true, write: true, execute: true },
+ *     group: { read: true, write: true, execute: true },
+ *     other: { read: true, write: true, execute: true },
+ *   },
+ * })
+ * ```
+ *
+ * @param options
+ */
+export async function file(options: FileOptions): Promise<void> {
+  const { path, state, update, encoding = 'utf8', mode } = options;
+  if (state === 'present') {
+    const isPresent = await __exists(path);
+    const previousContent = isPresent ? await readFile(path, encoding) : '';
+    const newContent = update == null ? (isPresent ? undefined : '') : update(previousContent);
+    const newMode = __toMode(mode);
+    if (newContent != null) {
+      await writeFile(path, newContent, { encoding, mode: newMode });
+    }
+    if (newMode != null && (isPresent || newContent != null)) {
+      await chmod(path, newMode);
+    }
+  } else {
+    await rm(path, { force: true });
+  }
+}
+
+/**
+ * Ensure file is present/absent with content initialized or modified with `update
+ *
+ * @example
+ * ```ts
+ * fileSync({
+ *   path: 'foo/bar',
+ *   state: 'present',
+ *   update: (content) => content + '_test', // This will append '_test' after current content
+ *   mode: {
+ *     owner: { read: true, write: true, execute: true },
+ *     group: { read: true, write: true, execute: true },
+ *     other: { read: true, write: true, execute: true },
+ *   },
+ * })
+ * ```
+ *
+ * @param options
+ */
+export function fileSync(options: FileOptions): void {
+  const { path, state, update, encoding = 'utf8', mode } = options;
+  if (state === 'present') {
+    const isPresent = __existsSync(path);
+    const previousContent = isPresent ? readFileSync(path, encoding) : '';
+    const newContent = update == null ? (isPresent ? undefined : '') : update(previousContent);
+    const newMode = __toMode(mode);
+    if (newContent != null) {
+      writeFileSync(path, newContent, { encoding, mode: newMode });
+    }
+    if (newMode != null && (isPresent || newContent != null)) {
+      chmodSync(path, newMode);
+    }
+  } else {
+    rmSync(path, { force: true });
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './directory.js';
+export * from './block.js';
+export * from './file.js';
+export * from './json.js';
+export * from './meta.js';
+export * from './yarnConfig.js';
+export * from './yarnVersion.js';

package/src/json.ts

@@ -0,0 +1,43 @@
+import { type FileOptions, file, fileSync } from './file.js';
+
+export type JSONValue = null | number | string | boolean | JSONValue[] | { [key: string]: JSONValue };
+
+export interface JSONOption<V = JSONValue> extends Omit<FileOptions, 'update'> {
+  /**
+   * File content mapping function
+   */
+  readonly update?: ((content: V | undefined) => V | undefined) | undefined;
+}
+
+function toFileOption<Value>({ update, ...otherOptions }: JSONOption<Value>): FileOptions {
+  return {
+    ...otherOptions,
+
+    update:
+      update == null
+        ? update
+        : (content) => {
+            const jsonValue = content === '' ? undefined : (JSON.parse(content) as Value);
+
+            return JSON.stringify(update(jsonValue));
+          },
+  };
+}
+
+/**
+ * Ensure file is present/absent asynchronously with content value initialized or modified with `update`
+ *
+ * @param options
+ */
+export async function json<Value>(options: JSONOption<Value>): Promise<void> {
+  return file(toFileOption(options));
+}
+
+/**
+ * Ensure file is present/absent synchronously with content value initialized or modified with `update`
+ *
+ * @param options
+ */
+export function jsonSync<Value>(options: JSONOption<Value>): void {
+  return fileSync(toFileOption(options));
+}

package/src/meta.ts

@@ -0,0 +1,8 @@
+export const meta = Object.freeze({
+  // @ts-ignore - these variables are injected at build time
+  name: (typeof __PACKAGE_NAME__ === 'undefined' ? '' : __PACKAGE_NAME__) as string,
+  // @ts-ignore - these variables are injected at build time
+  version: (typeof __PACKAGE_VERSION__ === 'undefined' ? '' : __PACKAGE_VERSION__) as string,
+  // @ts-ignore - these variables are injected at build time
+  buildNumber: 1 as number, // (typeof __PACKAGE_BUILD_NUMBER__ === 'undefined' ? 0 : __PACKAGE_BUILD_NUMBER__) as number,
+});

package/src/testing/getRootPath.ts

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const _dirname = path.dirname(fileURLToPath(import.meta.url));
+let rootPath: string | undefined = undefined;
+
+export function getRootPath() {
+  return rootPath ?? (rootPath = path.resolve(_dirname, '../../../..'));// we use renovate.json to find root
+}

package/src/testing/getTempPath.ts

@@ -0,0 +1,6 @@
+import path from 'node:path';
+import { getRootPath } from './getRootPath.js';
+
+export function getTempPath() {
+  return path.join(getRootPath(), '.temp');
+}

package/src/testing/getTestPath.ts

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { afterAll, beforeAll } from 'vitest';
+import { mkdir, rm } from 'node:fs/promises';
+import { getTempPath } from './getTempPath.js';
+
+export function getTestPath(prefix: string, remove = true) {
+  const returnValue = path.join(getTempPath(), prefix + Math.random().toString(36));
+  if (remove) {
+    afterAll(async () => {
+      try {
+        await rm(returnValue, { recursive: true });
+      } catch {
+      /* empty */
+      }
+    });
+  }
+  beforeAll(async () => {
+    try {
+      await mkdir(returnValue, { recursive: true });
+    } catch {
+      /* empty */
+    }
+  });
+  return returnValue;
+}

package/src/testing/index.ts

@@ -0,0 +1 @@
+export * from './getTestPath.js';

package/src/yarnConfig.ts

@@ -0,0 +1,61 @@
+import { exec, execSync } from './exec.js';
+
+export interface YarnConfigOptions {
+  /**
+   * Configuration key
+   */
+  readonly key: string;
+
+  /**
+   * Option target state
+   */
+  readonly state: 'present' | 'absent';
+
+  /**
+   * File content mapping function
+   *
+   */
+  readonly update?: ((content: string) => string | undefined) | undefined;
+}
+
+/**
+ * Synchronous version of {@link yarnConfig}
+ *
+ * @param options
+ * @example
+ * yarnConfigSync({
+ *   key: 'nodeLinker',
+ *   state: 'present',
+ *   update: (content) => content.replace('node-modules', 'hoisted'),
+ * })
+ */
+export function yarnConfigSync(options: YarnConfigOptions) {
+  const { key, state, update } = options;
+  if (state === 'present') {
+    const { stdout } = execSync('yarn', ['config', 'get', String(key)]);
+    execSync('yarn', ['config', 'set', String(key), `${update == null ? '' : update(stdout)}`]);
+  } else {
+    execSync('yarn', ['config', 'unset']);
+  }
+}
+
+/**
+ * Set/Unset yarn configuration value
+ *
+ * @param options
+ * @example
+ * await yarnConfig({
+ *   key: 'nodeLinker',
+ *   state: 'present',
+ *   update: (content) => content.replace('node-modules', 'hoisted'),
+ * })
+ */
+export async function yarnConfig(options: YarnConfigOptions): Promise<void> {
+  const { key, state, update } = options;
+  if (state === 'present') {
+    const { stdout } = await exec('yarn', ['config', 'get', String(key)]);
+    await exec('yarn', ['config', 'set', String(key), `${update == null ? '' : update(stdout)}`]);
+  } else {
+    await exec('yarn', ['config', 'unset']);
+  }
+}

package/src/yarnVersion.ts

@@ -0,0 +1,56 @@
+import { exec, execSync } from './exec.js';
+
+export type YarnVersionKind = 'berry' | 'classic';
+
+export interface YarnVersionOptions {
+  /**
+   * Option target state
+   */
+  readonly state: 'present' | 'absent';
+
+  /**
+   * Version mapping function
+   *
+   */
+  readonly update?: (() => YarnVersionKind | undefined) | undefined;
+}
+
+/**
+ * Synchronous version of {@link yarnVersion}
+ *
+ * @param options
+ * @example
+ * yarnVersionSync({
+ *   state: 'present',
+ *   update: () => 'berry', // or 'classic'
+ * })
+ */
+export function yarnVersionSync(options: YarnVersionOptions) {
+  const { state, update } = options;
+  if (state === 'present') {
+    execSync('yarn', ['set', 'version', `${update == null ? 'berry' : update()}`]);
+  } else {
+    // TODO: remove yarn.lock
+    throw new Error('Not implemented');
+  }
+}
+
+/**
+ * Set/Unset yarn configuration value
+ *
+ * @param options
+ * @example
+ * await yarnVersion({
+ *   state: 'present',
+ *   update: () => 'berry', // or 'classic'
+ * })
+ */
+export async function yarnVersion(options: YarnVersionOptions): Promise<void> {
+  const { state, update } = options;
+  if (state === 'present') {
+    await exec('yarn', ['set', 'version', `${update == null ? 'berry' : update()}`]);
+  } else {
+    // TODO: remove yarn.lock
+    throw new Error('Not implemented');
+  }
+}