@regardio/dev 1.13.8 → 1.14.3

package/dist/bin/flow/utils.test.js

@@ -0,0 +1,127 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { bumpVersion, confirm, insertChangelog } from './utils.js';
+describe('bumpVersion', () => {
+    it('bumps patch', () => {
+        expect(bumpVersion('1.2.3', 'patch')).toBe('1.2.4');
+    });
+    it('bumps minor and resets patch', () => {
+        expect(bumpVersion('1.2.3', 'minor')).toBe('1.3.0');
+    });
+    it('bumps major and resets minor + patch', () => {
+        expect(bumpVersion('1.2.3', 'major')).toBe('2.0.0');
+    });
+    it('handles zero components', () => {
+        expect(bumpVersion('0.0.0', 'patch')).toBe('0.0.1');
+        expect(bumpVersion('0.0.0', 'minor')).toBe('0.1.0');
+        expect(bumpVersion('0.0.0', 'major')).toBe('1.0.0');
+    });
+    it('defaults to patch for unknown bump type', () => {
+        expect(bumpVersion('1.2.3', 'unknown')).toBe('1.2.4');
+    });
+    it('throws for invalid semver', () => {
+        expect(() => bumpVersion('not-semver', 'patch')).toThrow('Invalid semver');
+        expect(() => bumpVersion('1.2', 'patch')).toThrow('Invalid semver');
+        expect(() => bumpVersion('1.2.x', 'patch')).toThrow('Invalid semver');
+    });
+});
+describe('insertChangelog', () => {
+    let tmpDir;
+    let changelogPath;
+    beforeEach(() => {
+        tmpDir = join(tmpdir(), `flow-utils-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        mkdirSync(tmpDir, { recursive: true });
+        changelogPath = join(tmpDir, 'CHANGELOG.md');
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { force: true, recursive: true });
+    });
+    it('creates a new file when none exists', () => {
+        insertChangelog(changelogPath, '## [1.0.0] - 2025-01-01\n\n- initial release\n');
+        expect(existsSync(changelogPath)).toBe(true);
+        const content = readFileSync(changelogPath, 'utf-8');
+        expect(content).toContain('# Changelog');
+        expect(content).toContain('## [1.0.0] - 2025-01-01');
+    });
+    it('inserts before the first existing ## section', () => {
+        writeFileSync(changelogPath, '# Changelog\n\n## [1.0.0] - 2025-01-01\n\n- old entry\n');
+        insertChangelog(changelogPath, '## [1.1.0] - 2025-02-01\n\n- new entry\n');
+        const content = readFileSync(changelogPath, 'utf-8');
+        const newIdx = content.indexOf('## [1.1.0]');
+        const oldIdx = content.indexOf('## [1.0.0]');
+        expect(newIdx).toBeLessThan(oldIdx);
+    });
+    it('appends when no ## section exists yet', () => {
+        writeFileSync(changelogPath, '# Changelog\n');
+        insertChangelog(changelogPath, '## [1.0.0] - 2025-01-01\n\n- initial\n');
+        const content = readFileSync(changelogPath, 'utf-8');
+        expect(content).toContain('## [1.0.0]');
+    });
+    it('preserves existing entries when inserting', () => {
+        writeFileSync(changelogPath, '# Changelog\n\n## [1.0.0] - 2025-01-01\n\n- old entry\n');
+        insertChangelog(changelogPath, '## [1.1.0] - 2025-02-01\n\n- new entry\n');
+        const content = readFileSync(changelogPath, 'utf-8');
+        expect(content).toContain('## [1.0.0]');
+        expect(content).toContain('- old entry');
+        expect(content).toContain('## [1.1.0]');
+        expect(content).toContain('- new entry');
+    });
+    it('appends when file exists but has no title line', () => {
+        writeFileSync(changelogPath, '## [1.0.0] - 2025-01-01\n\n- old entry\n');
+        insertChangelog(changelogPath, '## [1.1.0] - 2025-02-01\n\n- new entry\n');
+        const content = readFileSync(changelogPath, 'utf-8');
+        expect(content).toContain('## [1.0.0]');
+        expect(content).toContain('## [1.1.0]');
+    });
+    it('handles multiple existing entries in the correct order', () => {
+        writeFileSync(changelogPath, '# Changelog\n\n## [1.1.0] - 2025-02-01\n\n- second\n\n## [1.0.0] - 2025-01-01\n\n- first\n');
+        insertChangelog(changelogPath, '## [1.2.0] - 2025-03-01\n\n- third\n');
+        const content = readFileSync(changelogPath, 'utf-8');
+        const idx120 = content.indexOf('## [1.2.0]');
+        const idx110 = content.indexOf('## [1.1.0]');
+        const idx100 = content.indexOf('## [1.0.0]');
+        expect(idx120).toBeLessThan(idx110);
+        expect(idx110).toBeLessThan(idx100);
+    });
+});
+describe('confirm', () => {
+    let tmpDir;
+    let inputFile;
+    beforeEach(() => {
+        tmpDir = join(tmpdir(), `confirm-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        mkdirSync(tmpDir, { recursive: true });
+        inputFile = join(tmpDir, 'input');
+        vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { force: true, recursive: true });
+        vi.restoreAllMocks();
+    });
+    it('returns true for "y"', () => {
+        writeFileSync(inputFile, 'y\n');
+        expect(confirm('Continue?', inputFile)).toBe(true);
+    });
+    it('returns true for "Y"', () => {
+        writeFileSync(inputFile, 'Y\n');
+        expect(confirm('Continue?', inputFile)).toBe(true);
+    });
+    it('returns false for "n"', () => {
+        writeFileSync(inputFile, 'n\n');
+        expect(confirm('Continue?', inputFile)).toBe(false);
+    });
+    it('returns false for empty input', () => {
+        writeFileSync(inputFile, '\n');
+        expect(confirm('Continue?', inputFile)).toBe(false);
+    });
+    it('returns false for any other input', () => {
+        writeFileSync(inputFile, 'yes\n');
+        expect(confirm('Continue?', inputFile)).toBe(false);
+    });
+    it('writes the prompt to stdout', () => {
+        writeFileSync(inputFile, 'y\n');
+        confirm('Ship it?', inputFile);
+        expect(process.stdout.write).toHaveBeenCalledWith('Ship it? (y/N) ');
+    });
+});

package/dist/bin/lint/biome.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=biome.d.ts.map

package/dist/bin/lint/biome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"biome.d.ts","sourceRoot":"","sources":["../../../src/bin/lint/biome.ts"],"names":[],"mappings":""}

package/dist/bin/lint/commit.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=commit.d.ts.map

package/dist/bin/lint/commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit.d.ts","sourceRoot":"","sources":["../../../src/bin/lint/commit.ts"],"names":[],"mappings":""}

package/dist/bin/lint/md.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=md.d.ts.map

package/dist/bin/lint/md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"md.d.ts","sourceRoot":"","sources":["../../../src/bin/lint/md.ts"],"names":[],"mappings":""}

package/dist/bin/lint/package.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export declare function reorderConditions(obj: Record<string, unknown>): Record<string, unknown>;
+export declare function fixExportsOrder(filePath: string, fix: boolean): boolean;
+//# sourceMappingURL=package.d.ts.map

package/dist/bin/lint/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../../src/bin/lint/package.ts"],"names":[],"mappings":";AAcA,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBvF;AAMD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAiBvE"}

package/dist/bin/lint/package.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function reorderConditions(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return obj;
+    const processed = {};
+    for (const [key, value] of Object.entries(obj)) {
+        processed[key] =
+            typeof value === 'object' && value !== null && !Array.isArray(value)
+                ? reorderConditions(value)
+                : value;
+    }
+    if ('types' in processed && 'default' in processed) {
+        const keys = Object.keys(processed);
+        if (keys.indexOf('default') < keys.indexOf('types')) {
+            const reordered = { types: processed.types };
+            for (const key of keys) {
+                if (key !== 'types')
+                    reordered[key] = processed[key];
+            }
+            return reordered;
+        }
+    }
+    return processed;
+}
+export function fixExportsOrder(filePath, fix) {
+    const fullPath = resolve(process.cwd(), filePath);
+    if (!existsSync(fullPath))
+        return false;
+    const content = readFileSync(fullPath, 'utf-8');
+    const pkg = JSON.parse(content);
+    if (!pkg.exports || typeof pkg.exports !== 'object')
+        return false;
+    const fixed = reorderConditions(pkg.exports);
+    const changed = JSON.stringify(fixed) !== JSON.stringify(pkg.exports);
+    if (changed && fix) {
+        writeFileSync(fullPath, `${JSON.stringify({ ...pkg, exports: fixed }, null, 2)}\n`);
+    }
+    return changed;
+}
+if (fileURLToPath(import.meta.url) === resolve(process.argv[1] ?? '')) {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const devRoot = resolve(__dirname, '../../..');
+    const sortPkgBin = join(devRoot, 'node_modules/.bin/sort-package-json');
+    const sortPkgBinAlt = join(devRoot, 'node_modules/sort-package-json/cli.js');
+    let bin = '';
+    if (existsSync(sortPkgBin)) {
+        bin = sortPkgBin;
+    }
+    else if (existsSync(sortPkgBinAlt)) {
+        bin = `node ${sortPkgBinAlt}`;
+    }
+    else {
+        bin = 'npx sort-package-json';
+    }
+    const args = process.argv.slice(2);
+    const fixMode = args.includes('--fix');
+    const files = args.filter((arg) => arg !== '--fix');
+    const targets = files.length > 0 ? files : ['package.json'];
+    try {
+        const checkFlag = fixMode ? '' : '--check';
+        execSync(`${bin} ${checkFlag} ${targets.join(' ')}`.trim(), { stdio: 'inherit' });
+    }
+    catch {
+        process.exit(1);
+    }
+    let hasExportsIssues = false;
+    for (const file of targets) {
+        const needsFix = fixExportsOrder(file, fixMode);
+        if (needsFix && !fixMode) {
+            console.error(`${file}: exports condition order is incorrect (types must come before default)`);
+            hasExportsIssues = true;
+        }
+    }
+    if (hasExportsIssues) {
+        process.exit(1);
+    }
+}

package/dist/bin/lint/package.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=package.test.d.ts.map

package/dist/bin/lint/package.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.test.d.ts","sourceRoot":"","sources":["../../../src/bin/lint/package.test.ts"],"names":[],"mappings":""}

package/dist/bin/lint/package.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { reorderConditions } from './package.js';
+describe('lint-package', () => {
+    describe('reorderConditions', () => {
+        it('reorders types before default when default comes first', () => {
+            const input = {
+                './foo': {
+                    default: './dist/foo.js',
+                    types: './dist/foo.d.ts',
+                },
+            };
+            const result = reorderConditions(input);
+            expect(Object.keys(result['./foo'])).toEqual(['types', 'default']);
+        });
+        it('does not modify when types already comes before default', () => {
+            const input = {
+                './foo': {
+                    default: './dist/foo.js',
+                    types: './dist/foo.d.ts',
+                },
+            };
+            const result = reorderConditions(input);
+            expect(Object.keys(result['./foo'])).toEqual(['types', 'default']);
+        });
+        it('handles multiple exports with mixed order', () => {
+            const input = {
+                './a': { default: './dist/a.js', types: './dist/a.d.ts' },
+                './b': { default: './dist/b.js', types: './dist/b.d.ts' },
+            };
+            const result = reorderConditions(input);
+            expect(Object.keys(result['./a'])[0]).toBe('types');
+            expect(Object.keys(result['./b'])[0]).toBe('types');
+        });
+        it('preserves other keys after types', () => {
+            const input = {
+                './foo': {
+                    default: './dist/foo.js',
+                    import: './dist/foo.mjs',
+                    require: './dist/foo.cjs',
+                    types: './dist/foo.d.ts',
+                },
+            };
+            const result = reorderConditions(input);
+            const keys = Object.keys(result['./foo']);
+            expect(keys[0]).toBe('types');
+            expect(keys.slice(1)).toEqual(['default', 'import', 'require']);
+        });
+        it('handles exports without types or default', () => {
+            const input = { './styles.css': './dist/styles.css' };
+            expect(reorderConditions(input)).toEqual(input);
+        });
+        it('handles deeply nested condition objects', () => {
+            const input = {
+                './foo': {
+                    browser: { default: './dist/foo.browser.js', types: './dist/foo.browser.d.ts' },
+                    node: { default: './dist/foo.node.js', types: './dist/foo.node.d.ts' },
+                },
+            };
+            const result = reorderConditions(input);
+            const foo = result['./foo'];
+            expect(Object.keys(foo.node)[0]).toBe('types');
+            expect(Object.keys(foo.browser)[0]).toBe('types');
+        });
+    });
+});

package/package.json

@@ -1,12 +1,11 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/dev",
-  "version": "1.13.8",
+  "version": "1.14.3",
   "private": false,
   "description": "Regardio developer tooling for testing, linting, and build workflows",
   "keywords": [
     "biome",
-    "changesets",
     "commitlint",
     "dev",
     "husky",
@@ -56,43 +55,43 @@
     }
   },
   "bin": {
-    "exec-clean": "dist/bin/exec-clean.js",
-    "exec-husky": "dist/bin/exec-husky.js",
-    "exec-p": "dist/bin/exec-p.js",
-    "exec-s": "dist/bin/exec-s.js",
-    "exec-ts": "dist/bin/exec-ts.js",
-    "exec-tsc": "dist/bin/exec-tsc.js",
-    "flow-changeset": "dist/bin/flow-changeset.js",
-    "flow-release": "dist/bin/flow-release.js",
-    "lint-biome": "dist/bin/lint-biome.js",
-    "lint-commit": "dist/bin/lint-commit.js",
-    "lint-md": "dist/bin/lint-md.js",
-    "lint-package": "dist/bin/lint-package.js"
+    "exec-clean": "dist/bin/exec/clean.js",
+    "exec-husky": "dist/bin/exec/husky.js",
+    "exec-p": "dist/bin/exec/p.js",
+    "exec-s": "dist/bin/exec/s.js",
+    "exec-ts": "dist/bin/exec/ts.js",
+    "exec-tsc": "dist/bin/exec/tsc.js",
+    "flow-hotfix": "dist/bin/flow/hotfix.js",
+    "flow-release": "dist/bin/flow/release.js",
+    "flow-ship": "dist/bin/flow/ship.js",
+    "lint-biome": "dist/bin/lint/biome.js",
+    "lint-commit": "dist/bin/lint/commit.js",
+    "lint-md": "dist/bin/lint/md.js",
+    "lint-package": "dist/bin/lint/package.js"
   },
   "files": ["dist", "src"],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "clean": "tsx src/bin/exec-clean.ts .turbo dist",
+    "clean": "tsx src/bin/exec/clean.ts .turbo dist",
     "fix": "run-s fix:pkg fix:md fix:biome",
     "fix:biome": "biome check --write --unsafe .",
     "fix:md": "markdownlint-cli2 --fix",
-    "fix:pkg": "tsx src/bin/lint-package.ts --fix",
+    "fix:pkg": "tsx src/bin/lint/package.ts --fix",
+    "flow:hotfix": "tsx src/bin/flow/hotfix.ts",
+    "flow:release": "tsx src/bin/flow/release.ts",
+    "flow:ship": "tsx src/bin/flow/ship.ts",
     "lint": "run-s lint:md lint:biome",
     "lint:biome": "biome check .",
     "lint:md": "markdownlint-cli2",
-    "lint:pkg": "tsx src/bin/lint-package.ts",
+    "lint:pkg": "tsx src/bin/lint/package.ts",
     "prepare": "husky",
-    "release": "tsx src/bin/flow-release.ts",
     "report": "vitest run --coverage",
     "test": "run-p test:*",
     "test:unit": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "version": "tsx src/bin/flow-changeset.ts version"
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@biomejs/biome": "2.4.4",
-    "@changesets/changelog-github": "0.5.2",
-    "@changesets/cli": "2.29.8",
     "@commitlint/cli": "20.4.2",
     "@commitlint/config-conventional": "20.4.2",
     "@playwright/test": "1.58.2",

package/src/bin/exec/clean.test.ts

@@ -0,0 +1,63 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+import { resolveRimrafBin } from './clean.js';
+
+function makeRequire(pkgPath: string, pkg: unknown): NodeRequire {
+  const req = (id: string): unknown => (id === pkgPath ? pkg : undefined);
+  req.resolve = (_id: string) => pkgPath;
+  return req as unknown as NodeRequire;
+}
+
+describe('resolveRimrafBin', () => {
+  it('resolves when bin is a plain string', () => {
+    const pkgPath = '/node_modules/rimraf/package.json';
+    const req = makeRequire(pkgPath, { bin: './dist/esm/bin.js' });
+
+    const result = resolveRimrafBin(req);
+
+    expect(result).toBe(path.join('/node_modules/rimraf', 'dist/esm/bin.js'));
+  });
+
+  it('strips leading ./ from the bin path', () => {
+    const pkgPath = '/node_modules/rimraf/package.json';
+    const req = makeRequire(pkgPath, { bin: './bin/rimraf' });
+
+    const result = resolveRimrafBin(req);
+
+    expect(result).toBe(path.join('/node_modules/rimraf', 'bin/rimraf'));
+  });
+
+  it('resolves when bin is an object with a rimraf key', () => {
+    const pkgPath = '/node_modules/rimraf/package.json';
+    const req = makeRequire(pkgPath, { bin: { rimraf: './dist/esm/bin.js' } });
+
+    const result = resolveRimrafBin(req);
+
+    expect(result).toBe(path.join('/node_modules/rimraf', 'dist/esm/bin.js'));
+  });
+
+  it('returns null when bin field is missing', () => {
+    const pkgPath = '/node_modules/rimraf/package.json';
+    const req = makeRequire(pkgPath, {});
+
+    expect(resolveRimrafBin(req)).toBeNull();
+  });
+
+  it('returns null when bin object has no rimraf key', () => {
+    const pkgPath = '/node_modules/rimraf/package.json';
+    const req = makeRequire(pkgPath, { bin: { other: './dist/other.js' } });
+
+    expect(resolveRimrafBin(req)).toBeNull();
+  });
+
+  it('resolves against the real rimraf package', () => {
+    const req = createRequire(import.meta.url);
+
+    const result = resolveRimrafBin(req);
+
+    expect(result).not.toBeNull();
+    expect(path.isAbsolute(result ?? '')).toBe(true);
+  });
+});

package/src/bin/exec/clean.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * exec-clean: Thin wrapper around rimraf for cleaning paths.
+ * Usage: exec-clean <path> [morePaths...]
+ */
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Resolve the absolute path to the rimraf binary from its package.json bin field.
+ * Returns the resolved path, or null if it cannot be determined.
+ */
+export function resolveRimrafBin(require: NodeRequire): string | null {
+  const pkgPath = require.resolve('rimraf/package.json');
+  const pkg = require(pkgPath) as { bin?: unknown };
+  const binRel =
+    typeof pkg.bin === 'string' ? pkg.bin : (pkg.bin as Record<string, string>)?.rimraf;
+  if (!binRel) return null;
+  const normalized = binRel.startsWith('./') ? binRel.slice(2) : binRel;
+  return path.join(path.dirname(pkgPath), normalized);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const require = createRequire(import.meta.url);
+  const bin = resolveRimrafBin(require);
+  if (!bin) {
+    console.error('Unable to locate rimraf binary from package.json bin field');
+    process.exit(1);
+  }
+
+  const args = process.argv.slice(2);
+  const child = spawn(process.execPath, [bin, ...args], { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code ?? 0));
+}

package/src/bin/exec/ts.test.ts

@@ -0,0 +1,54 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+import { resolveTsxBin } from './ts.js';
+
+function makeRequire(pkgPath: string, pkg: unknown): NodeRequire {
+  const req = (id: string): unknown => (id === pkgPath ? pkg : undefined);
+  req.resolve = (_id: string) => pkgPath;
+  return req as unknown as NodeRequire;
+}
+
+describe('resolveTsxBin', () => {
+  it('resolves when bin is a string', () => {
+    const pkgPath = '/node_modules/tsx/package.json';
+    const req = makeRequire(pkgPath, { bin: './dist/cli.mjs' });
+
+    const result = resolveTsxBin(req);
+
+    expect(result).toBe(path.join('/node_modules/tsx', 'dist/cli.mjs'));
+  });
+
+  it('resolves when bin is an object with a tsx key', () => {
+    const pkgPath = '/node_modules/tsx/package.json';
+    const req = makeRequire(pkgPath, { bin: { tsx: './dist/cli.mjs' } });
+
+    const result = resolveTsxBin(req);
+
+    expect(result).toBe(path.join('/node_modules/tsx', 'dist/cli.mjs'));
+  });
+
+  it('returns null when bin field is missing', () => {
+    const pkgPath = '/node_modules/tsx/package.json';
+    const req = makeRequire(pkgPath, {});
+
+    expect(resolveTsxBin(req)).toBeNull();
+  });
+
+  it('returns null when bin object has no tsx key', () => {
+    const pkgPath = '/node_modules/tsx/package.json';
+    const req = makeRequire(pkgPath, { bin: { other: './dist/other.js' } });
+
+    expect(resolveTsxBin(req)).toBeNull();
+  });
+
+  it('resolves against the real tsx package', () => {
+    const req = createRequire(import.meta.url);
+
+    const result = resolveTsxBin(req);
+
+    expect(result).not.toBeNull();
+    expect(path.isAbsolute(result ?? '')).toBe(true);
+  });
+});

package/src/bin/exec/ts.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * exec-ts: Run a local TypeScript file via tsx with TS support.
+ * Usage: exec-ts path/to/script.ts [args...]
+ */
+import { type SpawnOptions, spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Resolve the absolute path to the tsx binary from its package.json bin field.
+ * Returns the resolved path, or null if it cannot be determined.
+ */
+export function resolveTsxBin(require: NodeRequire): string | null {
+  const pkgPath = require.resolve('tsx/package.json');
+  const pkg = require(pkgPath) as { bin?: unknown };
+  const binRel = pkg.bin;
+  const binEntry: string | undefined =
+    typeof binRel === 'string'
+      ? binRel
+      : typeof binRel === 'object' && binRel !== null && 'tsx' in binRel
+        ? (binRel as Record<string, string>).tsx
+        : undefined;
+  if (!binEntry) return null;
+  return path.join(path.dirname(pkgPath), binEntry);
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point — only runs when executed directly
+// ---------------------------------------------------------------------------
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+  const args = process.argv.slice(2);
+  if (args.length === 0) {
+    console.error('Usage: exec-ts <script.ts> [args...]');
+    process.exit(1);
+  }
+
+  const [scriptArg, ...rest] = args;
+  const script = scriptArg ?? '';
+
+  const require = createRequire(import.meta.url);
+  const bin = resolveTsxBin(require);
+  if (!bin) {
+    console.error('Unable to locate tsx binary from package.json bin field');
+    process.exit(1);
+  }
+
+  const spawnOptions: SpawnOptions = { stdio: 'inherit' };
+  const child = spawn(process.execPath, [bin, script, ...rest], spawnOptions);
+  child.on('exit', (code: number | null) => process.exit(code ?? 0));
+}