exec-staged 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Nick Barry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# Exec Staged
+
+Run commands against files staged in git, ignoring unstaged changes and untracked files.
+
+### Use Cases
+
+- 🧵 Lint new changes before commit.
+- 🧪 Test changes in isolation before commit.
+- ✨ ???
+
+### How it Works
+
+1. Unstaged changes and untracked files are hidden in a git stash. This inludes unstaged deletions, which are temporarily restored.
+2. User-configured tasks are run, with staged files passed in according to configuration.
+3. Any changes made by tasks are added to the git index. This includes additions and deletions.
+4. The stashed changes are restored.
+5. If any step fails, the initial state is fully restored.
+
+## Installation
+
+Install from npm, using your preferred package manager:
+
+```bash
+npm install --save-dev exec-staged
+```
+
+## Usage
+
+### Run from the CLI
+
+If an `exec-staged` configuration file is present, it will be loaded by the executable:
+
+```bash
+npx exec-staged
+```
+
+If no configuration is present, the executable can still run tasks passed as arguments:
+
+```bash
+npx exec-staged "npm test"
+```
+
+### Run in a Script
+
+```typescript
+import { execStaged } from 'exec-staged';
+
+const cwd = process.cwd();
+const tasks = [`npm test`];
+const options = { quiet: true };
+
+const result = await execStaged(cwd, tasks, options);
+
+if (!result) {
+  throw new Error('exec-staged task failed');
+}
+```
+
+### Run in a Pre-Commit Hook
+
+[Husky](https://github.com/typicode/husky) is recommended for handling pre-commit hooks.
+
+Install Husky:
+
+```bash
+npm install --save-dev husky
+```
+
+Add a hook to `.husky/pre-commit`:
+
+```bash
+#!/bin/sh
+npx exec-staged
+```
+
+Run husky:
+
+```bash
+npx husky
+```
+
+Add a `package.json` script to run husky whenever your repository is cloned:
+
+```json
+{
+  "scripts": {
+    "prepare": "husky"
+  }
+}
+```
+
+`exec-staged` will do nothing unless configured. See configuration information below.
+
+## Configuration
+
+`exec-staged` configuration consists of a list of commands to execute against the stage. Each command may be formatted as a plain `string`, or as an object containing additional attributes.
+
+All [Cosmiconfig-compatible](https://www.npmjs.com/package/cosmiconfig#searchplaces) configuration files are supported.
+
+Here is an example configuration:
+
+```typescript
+// exec-staged.config.ts
+import type { ExecStagedUserConfig } from 'exec-staged/types';
+
+const config: ExecStagedUserConfig = [
+  'knip',
+  'knip --production',
+  { task: 'prettier --write $FILES', glob: '*.{js,ts,json,md}' },
+];
+
+export default config;
+```
+
+Plain commands are run every time, as-is:
+
+<!-- prettier-ignore-start -->
+```typescript
+'knip --production'
+```
+<!-- prettier-ignore-end -->
+
+Commands which include the `$FILES` token are only run if staged files are found, and those files are interpolated into the command in place of the token.
+
+<!-- prettier-ignore-start -->
+```typescript
+'prettier --write $FILES'
+// => prettier --write new_file.js modified_file.js
+```
+<!-- prettier-ignore-end -->
+
+File filtering can be customized.
+
+To filter files by name, add a `glob` filter (defaults to `'*'`):
+
+```typescript
+{ task: 'prettier --write $FILES', glob: '*.{js,ts,json,md}' }
+```
+
+To filter files by git status, add a `diff` filter (defaults to `'ACMR'`; see [here](https://git-scm.com/docs/git-status#_short_format)):
+
+```typescript
+{ task: 'prettier --write $FILES', diff: 'A' }
+```
+
+Defining `diff` or `glob` on a task that does not include the `$FILES` token has no effect:
+
+```typescript
+{ task: 'knip', diff: 'NO EFFECT', glob: 'NO EFFECT' }
+```
+
+## Safety Features
+
+Before running any potentially destructive scripts, `exec-staged` stores all outstanding changes, including untracked files, in a backup stash. If any task fails, or if `exec-staged` is interrupted by an end-process signal (such as via <kbd>Ctrl + C</kbd>), the repository's original state is restored using this stash. Avoid running any tasks that interact with git, especially those that make commits or modify the stash.
+
+### Recovery
+
+If `exec-staged` fails to exit safely, such as due to power loss or if its process is killed via `SIGKILL`, its backup stash should still be present.
+
+To verify, run `git log` and look for a stash with the message `💾 exec-staged backup stash`. It should be the most recent stash. If it isn't, one of your tasks probably created a stash for some reason. This is very unlikely. Remove any such stashes before proceeding.
+
+`exec-staged` also creates a short-lived temporary commit with the message `💾 exec-staged staged changes`. If it's present, it can be removed with `git reset --hard HEAD~1`.
+
+The following commands should return your repository to its original state:
+
+```bash
+git add -A
+git reset --hard HEAD
+git stash pop --index
+```
+
+To prevent data loss, `exec-staged` will not run if a stash or commit from a previous run is present.
+
+## See Also
+
+- [`lint-staged`](https://github.com/lint-staged/lint-staged): the inspiration for `exec-staged`.
+- [`knip`](https://github.com/webpro-nl/knip): a linter that analyzes interactions between files, which is outside of the designed scope of `lint-staged`.

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,19 @@
+#!/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/dist/index.d.ts

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

package/dist/index.js

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

package/dist/lib/config.d.ts

@@ -0,0 +1,5 @@
+import type { ExecStagedConfig, ExecStagedUserConfig } from '../types.js';
+export declare const loadConfig: (cwd: string) => Promise<ExecStagedUserConfig>;
+export declare const resolveConfig: (userConfig: ExecStagedUserConfig) => ExecStagedConfig;
+/** @internal */
+export declare const validateUserConfig: (userConfig: ExecStagedUserConfig) => void;

package/dist/lib/config.js

@@ -0,0 +1,47 @@
+import pkg from '../../package.json' with { type: 'json' };
+import { DEFAULT_CONFIG_ENTRY } from './constants.js';
+import { cosmiconfig } from 'cosmiconfig';
+export const loadConfig = async (cwd) => {
+    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) => {
+    return userConfig.map((entry) => ({
+        ...DEFAULT_CONFIG_ENTRY,
+        ...(typeof entry === 'string' ? { task: entry } : entry),
+    }));
+};
+/** @internal */
+export const validateUserConfig = (userConfig) => {
+    if (!isValidUserConfig(userConfig)) {
+        throw new Error('invalid config');
+    }
+};
+const isValidUserConfig = (userConfig) => {
+    return (Array.isArray(userConfig) &&
+        userConfig.every((userConfigEntry) => isValidUserConfigEntry(userConfigEntry)));
+};
+const isValidUserConfigEntry = (userConfigEntry) => {
+    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/dist/lib/constants.d.ts

@@ -0,0 +1,13 @@
+import type { ExecStagedConfigEntry } from '../types.js';
+export declare const DEFAULT_CONFIG_ENTRY: Omit<ExecStagedConfigEntry, 'task'>;
+export declare const MERGE_FILES: readonly ["MERGE_HEAD", "MERGE_MODE", "MERGE_MSG"];
+export declare const BACKUP_STASH_MESSAGE: string;
+export declare const STAGED_CHANGES_COMMIT_MESSAGE: string;
+export declare const INTERPOLATION_IDENTIFIER = "$FILES";
+export declare const stageLifecycleMessages: {
+    check: string;
+    prepare: string;
+    run: string;
+    merge: string;
+    revert: string;
+};

package/dist/lib/constants.js

@@ -0,0 +1,17 @@
+import pkg from '../../package.json' with { type: 'json' };
+export const DEFAULT_CONFIG_ENTRY = {
+    glob: '*',
+    diff: 'ACMR',
+};
+export const MERGE_FILES = ['MERGE_HEAD', 'MERGE_MODE', 'MERGE_MSG'];
+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/dist/lib/exec_staged.d.ts

@@ -0,0 +1,2 @@
+import type { ExecStagedUserConfig, StageOptions } from '../types.js';
+export declare const execStaged: (cwd: string, tasks: ExecStagedUserConfig, options?: StageOptions) => Promise<boolean>;

package/dist/lib/exec_staged.js

@@ -0,0 +1,13 @@
+import { resolveConfig } from './config.js';
+import { Stage } from './stage.js';
+export const execStaged = async (cwd, tasks, options = {}) => {
+    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/dist/lib/logger.d.ts

@@ -0,0 +1,7 @@
+export declare class Logger {
+    outFile: string;
+    private quiet;
+    constructor(quiet?: boolean);
+    log(...params: Parameters<typeof console.log>): void;
+    debug(...params: Parameters<typeof console.debug>): void;
+}

package/dist/lib/logger.js

@@ -0,0 +1,23 @@
+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 {
+    outFile;
+    quiet;
+    constructor(quiet = 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()}`);
+    }
+    log(...params) {
+        this.debug(...params);
+        if (!this.quiet) {
+            console.log(...params);
+        }
+    }
+    debug(...params) {
+        fs.appendFileSync(this.outFile, params.join('\n') + '\n');
+    }
+}

package/dist/lib/spawn.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare const spawn: (cwd: string, args: string[]) => Promise<import("execa").Result<{
+    cwd: string;
+    preferLocal: true;
+    stdout: ("pipe" | "inherit")[];
+}>>;
+/**
+ * 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 declare const spawnSync: (cwd: string, args: string[]) => import("execa").SyncResult<{
+    cwd: string;
+}>;

package/dist/lib/spawn.js

@@ -0,0 +1,37 @@
+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, args) => {
+    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, args) => {
+    return execaSync({ cwd })(args[0], args.slice(1));
+};

package/dist/lib/stage.d.ts

@@ -0,0 +1,24 @@
+import type { ExecStagedConfig, StageOptions } from '../types.js';
+import { Logger } from './logger.js';
+export declare class Stage {
+    readonly logger: Logger;
+    protected readonly cwd: string;
+    protected stashed: boolean;
+    private readonly status;
+    private readonly mergeStatus;
+    private head?;
+    private patchPath?;
+    private gitDir?;
+    constructor(cwd: string, options?: StageOptions);
+    exec(tasks: ExecStagedConfig): Promise<void>;
+    protected check(): void;
+    protected prepare(): void;
+    protected run(tasks: ExecStagedConfig): Promise<void>;
+    protected merge(): void;
+    protected revert(): void;
+    protected git(args: string[]): string;
+    private backupMergeStatus;
+    private restoreMergeStatus;
+    private indexOfBackupStash;
+    private findBackupStash;
+}