exec-staged 0.1.0

package/dist/lib/stage.js

@@ -0,0 +1,300 @@
+import { BACKUP_STASH_MESSAGE, INTERPOLATION_IDENTIFIER, MERGE_FILES, STAGED_CHANGES_COMMIT_MESSAGE, stageLifecycleMessages, } from './constants.js';
+import { Logger } from './logger.js';
+import { spawn, spawnSync } from './spawn.js';
+import micromatch from 'micromatch';
+import fs from 'node:fs';
+import path from 'node:path';
+import semver from 'semver';
+import parseArgsStringToArgv from 'string-argv';
+export class Stage {
+    logger;
+    cwd;
+    stashed = false;
+    status = {};
+    mergeStatus = {};
+    head;
+    patchPath;
+    gitDir;
+    constructor(cwd, options = {}) {
+        this.cwd = cwd;
+        this.logger = new Logger(options.quiet);
+        this.logger.debug(`cwd: ${cwd}`);
+    }
+    async exec(tasks) {
+        try {
+            this.check();
+            this.prepare();
+        }
+        catch (error) {
+            this.logger.debug(error);
+            throw error;
+        }
+        try {
+            await this.run(tasks);
+            this.merge();
+        }
+        catch (error) {
+            this.logger.debug(error);
+            try {
+                this.revert();
+            }
+            catch (error) {
+                this.logger.debug(error);
+            }
+            throw error;
+        }
+    }
+    check() {
+        this.logger.log(stageLifecycleMessages.check);
+        let version;
+        if (!fs.existsSync(this.cwd)) {
+            this.logger.log('⚠️ Directory does not exist!');
+            throw new Error('cwd does not exist');
+        }
+        try {
+            version = this.git(['--version']).match(/git version (\d+\.\d+\.\d+)/)?.[1];
+        }
+        catch (error) {
+            this.logger.log('⚠️ Git installation not found!');
+            throw error;
+        }
+        if (!version || semver.lte(version, '2.13.0')) {
+            this.logger.log('⚠️ Unsupported git version!');
+            throw new Error('unsupported git version');
+        }
+        let gitRootDirectory;
+        try {
+            gitRootDirectory = this.git(['rev-parse', '--show-toplevel']).trim();
+        }
+        catch (error) {
+            this.logger.log('⚠️ Not a git repository!');
+            throw new Error('cwd is not a git repository');
+        }
+        if (gitRootDirectory !== this.cwd) {
+            this.logger.log('⚠️ Not in git root directory!');
+            throw new Error('cwd is not a git repository root directory');
+        }
+        if (this.indexOfBackupStash() !== -1) {
+            this.logger.log('⚠️ Found unexpected backup stash!');
+            this.logger.log('It must be left over from a previous failed run.  Remove it before proceeding.');
+            throw new Error('unexpected backup stash');
+        }
+        if (this.git(['log']).includes(STAGED_CHANGES_COMMIT_MESSAGE)) {
+            this.logger.log('⚠️ Found unexpected temporary commit!');
+            this.logger.log('It must be left over from a previous failed run.  Remove it before proceeding.');
+            throw new Error('unexpected temporary commit');
+        }
+    }
+    prepare() {
+        this.logger.log(stageLifecycleMessages.prepare);
+        this.head = this.git(['rev-parse', 'HEAD']);
+        this.gitDir = this.git(['rev-parse', '--absolute-git-dir']);
+        this.patchPath = path.resolve(this.gitDir, 'patch.diff');
+        this.git(['status', '--porcelain'])
+            .split('\n')
+            .filter((f) => f.length)
+            .forEach((f) => (this.status[f.slice(3)] = f.slice(0, 2)));
+        // if there are no files in index or working tree, do not attempt to stash
+        if (Object.keys(this.status).length === 0)
+            return;
+        try {
+            this.logger.debug('➡️ ➡️ Creating patch of unstaged changes...');
+            const unstagedAdditions = Object.entries(this.status)
+                .filter(([, s]) => s.match(/^\?\?/))
+                .map(([f]) => f);
+            if (unstagedAdditions.length) {
+                this.git(['add', '--intent-to-add', '--', ...unstagedAdditions]);
+            }
+            this.git([
+                'diff',
+                '--binary',
+                '--default-prefix',
+                // skip deleted files because patch doesn't apply if they're modified
+                '--diff-filter=d',
+                '--no-color',
+                '--no-ext-diff',
+                '--no-rename-empty',
+                '--patch',
+                '--submodule=short',
+                '--unified=0',
+                '--output',
+                this.patchPath,
+            ]);
+            if (unstagedAdditions.length) {
+                this.git(['reset', '--', ...unstagedAdditions]);
+            }
+        }
+        catch (error) {
+            this.logger.log('⚠️ Error creating patch of unstaged changes!');
+            throw error;
+        }
+        try {
+            this.logger.debug('➡️ ➡️ Backing up merge status...');
+            this.backupMergeStatus();
+        }
+        catch (error) {
+            this.logger.log('⚠️ Error backing up merge status!');
+            throw error;
+        }
+        try {
+            this.logger.debug('➡️ ➡️ Creating backup stash and hiding unstaged changes...');
+            this.git([
+                'stash',
+                'push',
+                '--keep-index',
+                '--include-untracked',
+                '--message',
+                BACKUP_STASH_MESSAGE,
+            ]);
+            this.stashed = true;
+        }
+        catch (error) {
+            this.logger.log('⚠️ Error creating backup stash!');
+            throw error;
+        }
+    }
+    async run(tasks) {
+        this.logger.log(stageLifecycleMessages.run);
+        for (let i = 0; i < tasks.length; i++) {
+            const { task, diff, glob } = tasks[i];
+            try {
+                this.logger.log(`➡️ Running task ${i + 1} of ${tasks.length}: \`${task}\`...`);
+                const taskArgs = parseArgsStringToArgv(task);
+                const interpolationIndex = taskArgs.indexOf(INTERPOLATION_IDENTIFIER);
+                if (interpolationIndex !== -1) {
+                    const files = micromatch(Object.entries(this.status)
+                        .filter(([, s]) => s.match(new RegExp(`^[${diff}]`)))
+                        .map(([f]) => f), glob);
+                    if (files.length === 0) {
+                        this.logger.log(`➡️ No matching files, skipping task...`);
+                        continue;
+                    }
+                    taskArgs.splice(interpolationIndex, 1, ...files);
+                }
+                const { stdout } = await spawn(this.cwd, taskArgs);
+                this.logger.debug(stdout.replaceAll(/^/gm, '> '));
+            }
+            catch (error) {
+                this.logger.log(`⚠️ Error running task: \`${task}\`!`);
+                throw error;
+            }
+        }
+    }
+    merge() {
+        this.logger.log(stageLifecycleMessages.merge);
+        try {
+            this.logger.debug('➡️ ➡️ Adding changes made by tasks...');
+            this.git(['add', '-A']);
+        }
+        catch (error) {
+            this.logger.log('⚠️ Error adding new changes!');
+            throw error;
+        }
+        if (!this.stashed)
+            return;
+        // attempt to retrieve the stash before running any damaging operations
+        const stash = this.findBackupStash();
+        try {
+            this.logger.debug('➡️ ➡️ Restoring unstaged changes from stash...');
+            // commit staged changes to keep them separate from unstaged changes in
+            // patch, because `--3-way` adds unstaged changes to the index
+            this.git([
+                'commit',
+                '--allow-empty',
+                '--no-verify',
+                '-m',
+                STAGED_CHANGES_COMMIT_MESSAGE,
+            ]);
+            // apply patch containing unstaged changes
+            this.git([
+                'apply',
+                '--allow-empty',
+                '--recount',
+                '--unidiff-zero',
+                '--whitespace=nowarn',
+                '--3way',
+                this.patchPath,
+            ]);
+            // unstaged deletions are not included in the patch and must be handled
+            // separately because the patch cannot be applied if such files are
+            // modified by tasks
+            Object.entries(this.status)
+                .filter(([, s]) => s.match(/^.D/))
+                .map(([f]) => f)
+                .forEach((f) => fs.rmSync(path.resolve(this.cwd, f)));
+            // make sure all restored unstaged changes are kept out of the index
+            this.git(['reset']);
+            // undo temporary commit while keeping its changes in the index
+            this.git(['reset', '--soft', this.head]);
+            // clean up
+            fs.rmSync(this.patchPath);
+            this.git(['stash', 'drop', stash]);
+        }
+        catch (error) {
+            this.logger.log('⚠️ Error restoring unstaged changes from stash!');
+            throw error;
+        }
+        this.restoreMergeStatus();
+    }
+    revert() {
+        this.logger.log(stageLifecycleMessages.revert);
+        let stash;
+        if (this.stashed) {
+            // attempt to retrieve the stash before running any damaging operations
+            stash = this.findBackupStash();
+        }
+        try {
+            this.logger.debug('➡️ ➡️ Reverting changes made by tasks...');
+            this.git(['add', '-A']);
+            this.git(['reset', '--hard', this.head]);
+        }
+        catch (error) {
+            this.logger.log('⚠️ Failed to revert changes made by tasks!');
+            throw error;
+        }
+        if (!this.stashed)
+            return;
+        try {
+            this.logger.debug('➡️ ➡️ Restoring state from backup stash...');
+            this.git(['stash', 'apply', '--index', stash]);
+            this.git(['stash', 'drop', stash]);
+            this.restoreMergeStatus();
+        }
+        catch (error) {
+            this.logger.log('⚠️ Failed to restore state from backup stash!');
+            throw error;
+        }
+    }
+    git(args) {
+        this.logger.debug(`git: ${args.map((arg) => `[${arg}]`).join(' ')}`);
+        const { stdout } = spawnSync(this.cwd, ['git', ...args]);
+        this.logger.debug(stdout.replaceAll(/^/gm, '> '));
+        return stdout;
+    }
+    backupMergeStatus() {
+        for (const mergeFile of MERGE_FILES) {
+            const file = path.resolve(this.gitDir, mergeFile);
+            if (fs.existsSync(file)) {
+                this.mergeStatus[mergeFile] = fs.readFileSync(file);
+            }
+        }
+    }
+    restoreMergeStatus() {
+        for (const mergeFile of Object.keys(this.mergeStatus)) {
+            const contents = this.mergeStatus[mergeFile];
+            fs.writeFileSync(path.resolve(this.gitDir, mergeFile), contents);
+        }
+    }
+    indexOfBackupStash() {
+        return this.git(['stash', 'list'])
+            .split('\n')
+            .findIndex((el) => el.includes(BACKUP_STASH_MESSAGE));
+    }
+    findBackupStash() {
+        const index = this.indexOfBackupStash();
+        if (index === -1) {
+            throw new Error('missing backup stash');
+        }
+        return `stash@{${index}}`;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+export type ExecStagedConfigEntry = {
+    task: string;
+    diff: string;
+    glob: string;
+};
+export type ExecStagedConfig = ExecStagedConfigEntry[];
+export type ExecStagedUserConfigEntry = (Pick<ExecStagedConfigEntry, 'task'> & Partial<ExecStagedConfigEntry>) | ExecStagedConfigEntry['task'];
+export type ExecStagedUserConfig = ExecStagedUserConfigEntry[];
+export type StageOptions = {
+    quiet?: boolean;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "exec-staged",
+  "version": "0.1.0",
+  "description": "Run commands against the current git index",
+  "keywords": [
+    "git",
+    "lint",
+    "staged",
+    "lint-staged",
+    "pre-commit",
+    "commit",
+    "hook"
+  ],
+  "repository": "github:ItsNickBarry/exec-staged",
+  "license": "MIT",
+  "author": "Nick Barry",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./types": "./dist/types.js"
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "exec-staged": "./dist/bin/cli.js"
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "dependencies": {
+    "commander": "^14.0.0",
+    "cosmiconfig": "^9.0.0",
+    "env-paths": "^3.0.0",
+    "execa": "^9.6.0",
+    "micromatch": "^4.0.8",
+    "on-process-exit": "^1.0.2",
+    "semver": "^7.7.2",
+    "string-argv": "^0.3.2"
+  },
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "^5.2.2",
+    "@tsconfig/node22": "^22.0.2",
+    "@types/micromatch": "^4.0.9",
+    "@types/node": "^22.15.31",
+    "@types/semver": "^7.7.0",
+    "husky": "^9.1.7",
+    "knip": "^5.60.2",
+    "lint-staged": "github:ItsNickBarry/lint-staged#knip",
+    "prettier": "^3.5.3",
+    "prettier-plugin-packagejson": "^2.5.15",
+    "tsx": "^4.20.1",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "pnpm clean && tsc --build",
+    "clean": "rm -rf dist/",
+    "test": "pnpm build && tsx --test --experimental-test-coverage"
+  }
+}

package/src/bin/cli.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import pkg from '../../package.json' with { type: 'json' };
+import { loadConfig } from '../lib/config.js';
+import { execStaged } from '../lib/exec_staged.js';
+import { program } from 'commander';
+import path from 'node:path';
+
+program.name(pkg.name).version(pkg.version).description(pkg.description);
+program.option('--quiet', 'suppress output');
+program.option('--cwd <cwd>', 'directory in which to run');
+program.argument('[tasks...]');
+
+program.parse(process.argv);
+
+const options = program.opts();
+const args = program.args;
+
+const cwd = path.resolve(options.cwd ?? '');
+
+const tasks = args.length ? args : await loadConfig(cwd);
+
+const result = await execStaged(cwd, tasks, options);
+
+if (!result) {
+  process.exitCode ||= 1;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import { execStaged } from './lib/exec_staged.js';
+
+export default execStaged;

package/src/lib/config.ts

@@ -0,0 +1,71 @@
+import pkg from '../../package.json' with { type: 'json' };
+import type {
+  ExecStagedConfig,
+  ExecStagedUserConfig,
+  ExecStagedUserConfigEntry,
+} from '../types.js';
+import { DEFAULT_CONFIG_ENTRY } from './constants.js';
+import { cosmiconfig } from 'cosmiconfig';
+
+export const loadConfig = async (
+  cwd: string,
+): Promise<ExecStagedUserConfig> => {
+  const configResult = await cosmiconfig(pkg.name).search(cwd);
+
+  if (configResult) {
+    const { config, filepath } = configResult;
+
+    console.log(`Config loaded from ${filepath}`);
+
+    validateUserConfig(config);
+
+    return config;
+  } else {
+    console.log('No config found');
+    return [];
+  }
+};
+
+export const resolveConfig = (
+  userConfig: ExecStagedUserConfig,
+): ExecStagedConfig => {
+  return userConfig.map((entry) => ({
+    ...DEFAULT_CONFIG_ENTRY,
+    ...(typeof entry === 'string' ? { task: entry } : entry),
+  }));
+};
+
+/** @internal */
+export const validateUserConfig = (userConfig: ExecStagedUserConfig) => {
+  if (!isValidUserConfig(userConfig)) {
+    throw new Error('invalid config');
+  }
+};
+
+const isValidUserConfig = (userConfig: ExecStagedUserConfig): boolean => {
+  return (
+    Array.isArray(userConfig) &&
+    userConfig.every((userConfigEntry) =>
+      isValidUserConfigEntry(userConfigEntry),
+    )
+  );
+};
+
+const isValidUserConfigEntry = (
+  userConfigEntry: ExecStagedUserConfigEntry,
+): boolean => {
+  if (typeof userConfigEntry === 'string') return true;
+  if (typeof userConfigEntry !== 'object') return false;
+  if (typeof userConfigEntry.task !== 'string') return false;
+  if (
+    typeof userConfigEntry.diff !== 'string' &&
+    typeof userConfigEntry.diff !== 'undefined'
+  )
+    return false;
+  if (
+    typeof userConfigEntry.glob !== 'string' &&
+    typeof userConfigEntry.glob !== 'undefined'
+  )
+    return false;
+  return true;
+};

package/src/lib/constants.ts

@@ -0,0 +1,24 @@
+import pkg from '../../package.json' with { type: 'json' };
+import type { ExecStagedConfigEntry } from '../types.js';
+
+export const DEFAULT_CONFIG_ENTRY: Omit<ExecStagedConfigEntry, 'task'> = {
+  glob: '*',
+  diff: 'ACMR',
+};
+
+export const MERGE_FILES = ['MERGE_HEAD', 'MERGE_MODE', 'MERGE_MSG'] as const;
+
+export const BACKUP_STASH_MESSAGE = `💾 ${pkg.name} backup stash`;
+export const STAGED_CHANGES_COMMIT_MESSAGE = `💾 ${pkg.name} staged changes`;
+
+export const INTERPOLATION_IDENTIFIER = '$FILES';
+
+const PREFIX = '➡️ ';
+
+export const stageLifecycleMessages = {
+  check: `${PREFIX}Checking environment...`,
+  prepare: `${PREFIX}Preparing repository...`,
+  run: `${PREFIX}Running tasks...`,
+  merge: `${PREFIX}Merging new changes with saved state...`,
+  revert: `${PREFIX}Reverting to saved state...`,
+};

package/src/lib/exec_staged.ts

@@ -0,0 +1,19 @@
+import type { ExecStagedUserConfig, StageOptions } from '../types.js';
+import { resolveConfig } from './config.js';
+import { Stage } from './stage.js';
+
+export const execStaged = async (
+  cwd: string,
+  tasks: ExecStagedUserConfig,
+  options: StageOptions = {},
+): Promise<boolean> => {
+  const stage = new Stage(cwd, options);
+
+  try {
+    await stage.exec(resolveConfig(tasks));
+    return true;
+  } catch (error) {
+    console.log(`🪲 Log saved to: ${stage.logger.outFile}`);
+    return false;
+  }
+};

package/src/lib/logger.ts

@@ -0,0 +1,31 @@
+import pkg from '../../package.json' with { type: 'json' };
+import envPaths from 'env-paths';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export class Logger {
+  public outFile: string;
+  private quiet: boolean;
+
+  constructor(quiet: boolean = false) {
+    this.quiet = quiet;
+    this.outFile = path.resolve(
+      envPaths(pkg.name).temp,
+      `debug-${new Date().getTime().toString()}-${crypto.randomUUID()}.txt`,
+    );
+    fs.mkdirSync(path.dirname(this.outFile), { recursive: true });
+    this.debug(`${pkg.name} log: ${new Date().toLocaleString()}`);
+  }
+
+  public log(...params: Parameters<typeof console.log>): void {
+    this.debug(...params);
+
+    if (!this.quiet) {
+      console.log(...params);
+    }
+  }
+
+  public debug(...params: Parameters<typeof console.debug>): void {
+    fs.appendFileSync(this.outFile, params.join('\n') + '\n');
+  }
+}

package/src/lib/spawn.ts

@@ -0,0 +1,41 @@
+import { execa, execaSync } from 'execa';
+import { registerExitHandler, deregisterExitHandler } from 'on-process-exit';
+
+/**
+ * Spawn a child process asynchronously using the `execa` package.
+ * This is used to run `exec-staged` tasks.  The `execa` package is
+ * required because it provides the `preferLocal` option.
+ *
+ * Child processes are configured to be killed if the main process is stopped.
+ *
+ * @param cwd Directory where command should be executed.
+ * @param args Command string or array of command tokens.
+ * @throws ExecaError
+ * @returns Execa `Result` promise.
+ */
+export const spawn = async (cwd: string, args: string[]) => {
+  const subprocess = execa({
+    cwd,
+    preferLocal: true,
+    stdout: ['pipe', 'inherit'],
+  })(args[0], args.slice(1));
+
+  const id = registerExitHandler(() => subprocess.kill());
+  subprocess.once('close', () => deregisterExitHandler(id));
+
+  return subprocess;
+};
+
+/**
+ * Spawn a child process synchronously using the `execa` package.
+ * This is used to run `git` commands.  A synchronous API is required because
+ * cleanup operations may be run via `on-process-exit`.
+ *
+ * @param cwd Directory where command should be executed.
+ * @param args Command string or array of command tokens.
+ * @throws ExecaSyncError
+ * @returns Execa `SyncResult`.
+ */
+export const spawnSync = (cwd: string, args: string[]) => {
+  return execaSync({ cwd })(args[0], args.slice(1));
+};