@cencivic/runx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cencivic
+
+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,147 @@
+# @cencivic/runx
+
+[![npm version](https://img.shields.io/npm/v/@cencivic/runx.svg)](https://www.npmjs.com/package/@cencivic/runx)
+[![npm downloads](https://img.shields.io/npm/dm/@cencivic/runx.svg)](https://www.npmjs.com/package/@cencivic/runx)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Run TypeScript scripts with inline dependencies.
+
+Inspired by [uv](https://github.com/astral-sh/uv)'s script runner for Python.
+
+## Table of Contents
+
+- [Why runx?](#why-runx)
+- [Installation](#installation)
+- [Usage](#usage)
+- [CLI](#cli)
+- [Contributing](#contributing)
+- [Acknowledgments](#acknowledgments)
+- [License](#license)
+
+## Why runx?
+
+### AI-friendly scripting without side effects
+
+AI coding assistants (Claude, Copilot, Cursor, etc.) are great at generating one-off utility scripts — data migration, file processing, API testing, quick prototyping, and more. But these scripts often need external packages, and that's where things get messy:
+
+- Adding dependencies to the project's `package.json` just for a throwaway script
+- Lock file (`package-lock.json`, `bun.lock`) diffs polluting your git history
+- Risk of version conflicts with your actual project dependencies
+- Forgetting to clean up after the script is no longer needed
+
+**runx solves this.** Each script declares its own dependencies inline, installed into an isolated cache — completely independent from your project.
+
+```typescript
+#!/usr/bin/env runx
+/**
+ * @runx {
+ *   "dependencies": {
+ *     "csv-parse": "^5.5.0",
+ *     "chalk": "^5.3.0"
+ *   }
+ * }
+ */
+
+import { parse } from 'csv-parse/sync';
+import chalk from 'chalk';
+
+// AI-generated one-off migration script
+// Zero impact on your project's package.json or lock file
+const data = parse(await Bun.file('data.csv').text(), { columns: true });
+console.log(chalk.green(`Processed ${data.length} rows`));
+```
+
+Just ask your AI assistant to *"write a runx script that does X"* — you get a single, self-contained `.ts` file that runs anywhere without touching your project configuration. When you're done, simply delete the file. No cleanup needed.
+
+## Installation
+
+```bash
+npm install -g @cencivic/runx
+```
+
+Requires [bun](https://bun.sh) to be installed.
+
+## Usage
+
+Create a TypeScript file with dependencies declared in a `@runx` JSDoc block:
+
+```typescript
+#!/usr/bin/env runx
+/**
+ * @runx {
+ *   "dependencies": {
+ *     "zod": "^3.22.0",
+ *     "chalk": "^5.3.0"
+ *   }
+ * }
+ */
+
+import { z } from 'zod';
+import chalk from 'chalk';
+
+const UserSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+const user = UserSchema.parse({ name: 'Alice', age: 30 });
+console.log(chalk.green(`Hello, ${user.name}!`));
+```
+
+Run it:
+
+```bash
+runx script.ts
+```
+
+On first run, dependencies are installed and cached. Subsequent runs use the cache.
+
+### Metadata Fields
+
+The `@runx` block accepts a JSON object with the following fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `dependencies` | `Record<string, string>` | Package.json-style dependencies (required) |
+| `env` | `Record<string, string>` | Environment variables to set |
+| `engines` | `{ bun?: string; node?: string }` | Runtime version requirements |
+| `args` | `string[]` | Default arguments for the script |
+
+Full example with all fields:
+
+```typescript
+/**
+ * @runx {
+ *   "dependencies": {
+ *     "chalk": "^5.0.0",
+ *     "zod": "~3.22.0",
+ *     "@types/node": "20.0.0"
+ *   },
+ *   "env": { "NODE_ENV": "production", "DEBUG": "true" },
+ *   "engines": { "bun": ">=1.0", "node": ">=18" },
+ *   "args": ["--verbose"]
+ * }
+ */
+```
+
+## CLI
+
+```bash
+runx <script.ts> [args...]   # Run a script
+runx --clean                 # Clear all cached environments
+runx --version               # Show version
+runx --help                  # Show help
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Acknowledgments
+
+- [uv](https://github.com/astral-sh/uv) - The inspiration for this project. uv's inline script dependencies for Python showed how powerful this pattern can be.
+- [bun](https://bun.sh) - Used for fast dependency installation and script execution.
+
+## License
+
+MIT

package/bin/runx.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,92 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseScriptMetadata } from './parser.js';
+import { cleanCache, resolveEnvironment } from './resolver.js';
+import { runScript } from './runner.js';
+import { checkForUpdate, formatUpdateMessage } from './update-check.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { version: VERSION } = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+const HELP = `
+runx - uv-like script runner for TypeScript
+
+Usage:
+  runx <script.ts> [args...]    Run a TypeScript script
+  runx --clean                  Clean all cached environments
+  runx --version                Show version
+  runx --help                   Show this help
+
+Example script:
+  /**
+   * @runx {
+   *     "dependencies": {
+   *       "chalk": "^5.0.0",
+   *       "zod": "~3.22.0"
+   *     }
+   *   }
+   */
+  import chalk from 'chalk';
+  console.log(chalk.green('Hello!'));
+
+Dependency versions (same as package.json):
+  "5.3.0"     Exact version
+  "^5.0.0"    Compatible with 5.x.x (minor/patch updates)
+  "~5.3.0"    Approximately 5.3.x (patch updates only)
+  ">=1.0.0"   Version range
+  "latest"    Latest version
+  "*"         Any version
+`.trim();
+function ensureBun() {
+    try {
+        execFileSync('bun', ['--version'], { stdio: 'ignore' });
+    }
+    catch {
+        console.error('Error: bun is required but not found.');
+        console.error('Install it: https://bun.sh');
+        process.exit(1);
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        console.log(HELP);
+        process.exit(0);
+    }
+    if (args[0] === '--version' || args[0] === '-v') {
+        console.log(VERSION);
+        process.exit(0);
+    }
+    if (args[0] === '--clean') {
+        await cleanCache();
+        process.exit(0);
+    }
+    ensureBun();
+    const scriptPath = args[0];
+    const scriptArgs = args.slice(1);
+    if (!existsSync(scriptPath)) {
+        console.error(`Error: File not found: ${scriptPath}`);
+        process.exit(1);
+    }
+    // Start update check in background (non-blocking)
+    const updatePromise = checkForUpdate(VERSION);
+    try {
+        // Parse script metadata
+        const metadata = await parseScriptMetadata(scriptPath);
+        // Resolve environment (install deps if needed)
+        const nodeModulesPath = await resolveEnvironment(metadata, scriptPath);
+        // Run the script
+        const exitCode = await runScript(scriptPath, nodeModulesPath, scriptArgs);
+        // Show update notification after script finishes
+        const latestVersion = await updatePromise;
+        if (latestVersion) {
+            console.error(formatUpdateMessage(VERSION, latestVersion));
+        }
+        process.exit(exitCode);
+    }
+    catch (err) {
+        console.error('Error:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}
+main();

package/dist/parser.d.ts

@@ -0,0 +1,16 @@
+import type { ScriptMetadata } from './types.js';
+/**
+ * Parse script metadata from @runx JSDoc tag.
+ *
+ * Expected format:
+ * /**
+ *  * @runx {
+ *  *   "dependencies": {
+ *  *     "zod": "^3.22.0",
+ *  *     "chalk": "^5.3.0"
+ *  *   }
+ *  * }
+ *  *\/
+ */
+export declare function parseScriptMetadata(scriptPath: string): Promise<ScriptMetadata>;
+export declare function parseMetadataFromContent(content: string): ScriptMetadata;

package/dist/parser.js

@@ -0,0 +1,77 @@
+import { readFile } from 'node:fs/promises';
+import { parse } from 'comment-parser';
+/**
+ * Parse script metadata from @runx JSDoc tag.
+ *
+ * Expected format:
+ * /**
+ *  * @runx {
+ *  *   "dependencies": {
+ *  *     "zod": "^3.22.0",
+ *  *     "chalk": "^5.3.0"
+ *  *   }
+ *  * }
+ *  *\/
+ */
+export async function parseScriptMetadata(scriptPath) {
+    const content = await readFile(scriptPath, 'utf-8');
+    return parseMetadataFromContent(content);
+}
+export function parseMetadataFromContent(content) {
+    const parsed = parse(content);
+    for (const block of parsed) {
+        for (const tag of block.tags) {
+            if (tag.tag === 'runx') {
+                const jsonStr = extractJsonFromTag(tag);
+                if (jsonStr) {
+                    try {
+                        const metadata = JSON.parse(jsonStr);
+                        return {
+                            dependencies: metadata.dependencies ?? {},
+                        };
+                    }
+                    catch {
+                        throw new Error(`Invalid JSON in @runx tag: ${jsonStr}`);
+                    }
+                }
+            }
+        }
+    }
+    return { dependencies: {} };
+}
+function extractJsonFromTag(tag) {
+    // comment-parser puts { ... } content in the 'type' token
+    // For multiline JSON, we need to reconstruct from all source lines
+    const typeParts = [];
+    for (const sourceLine of tag.source) {
+        const typeToken = sourceLine.tokens.type;
+        if (typeToken) {
+            typeParts.push(typeToken);
+        }
+    }
+    const fullContent = typeParts.join('\n').trim();
+    // Find the JSON object boundaries
+    const startIndex = fullContent.indexOf('{');
+    if (startIndex === -1) {
+        return null;
+    }
+    // Find matching closing brace
+    let braceCount = 0;
+    let endIndex = -1;
+    for (let i = startIndex; i < fullContent.length; i++) {
+        if (fullContent[i] === '{') {
+            braceCount++;
+        }
+        else if (fullContent[i] === '}') {
+            braceCount--;
+            if (braceCount === 0) {
+                endIndex = i;
+                break;
+            }
+        }
+    }
+    if (endIndex === -1) {
+        return null;
+    }
+    return fullContent.slice(startIndex, endIndex + 1);
+}

package/dist/resolver.d.ts

@@ -0,0 +1,22 @@
+import type { ScriptMetadata } from './types.js';
+/**
+ * Generate cache key from dependencies.
+ */
+export declare function generateCacheKey(metadata: ScriptMetadata): string;
+/**
+ * Get cache directory path for given metadata and script path.
+ */
+export declare function getCacheDir(metadata: ScriptMetadata, scriptPath: string): string;
+/**
+ * Check if cache exists for given metadata.
+ */
+export declare function cacheExists(metadata: ScriptMetadata, scriptPath: string): boolean;
+/**
+ * Resolve environment for script metadata.
+ * Creates cache if it doesn't exist.
+ */
+export declare function resolveEnvironment(metadata: ScriptMetadata, scriptPath: string): Promise<string>;
+/**
+ * Clean all cached environments.
+ */
+export declare function cleanCache(): Promise<void>;

package/dist/resolver.js

@@ -0,0 +1,121 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+/**
+ * Get platform-appropriate cache base directory.
+ */
+function getCacheBase() {
+    if (process.platform === 'win32') {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (localAppData) {
+            return join(localAppData, 'runx', 'envs');
+        }
+        return join(homedir(), 'AppData', 'Local', 'runx', 'envs');
+    }
+    // macOS & Linux: XDG_CACHE_HOME or ~/.cache
+    const xdgCacheHome = process.env.XDG_CACHE_HOME;
+    if (xdgCacheHome) {
+        return join(xdgCacheHome, 'runx', 'envs');
+    }
+    return join(homedir(), '.cache', 'runx', 'envs');
+}
+/**
+ * Generate cache key from dependencies.
+ */
+export function generateCacheKey(metadata) {
+    const sortedEntries = Object.entries(metadata.dependencies).sort(([a], [b]) => a.localeCompare(b));
+    const content = JSON.stringify(sortedEntries);
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+/**
+ * Extract script name (without extension) from script path.
+ */
+function getScriptName(scriptPath) {
+    const base = basename(scriptPath);
+    const dotIndex = base.lastIndexOf('.');
+    return dotIndex > 0 ? base.slice(0, dotIndex) : base;
+}
+/**
+ * Get cache directory path for given metadata and script path.
+ */
+export function getCacheDir(metadata, scriptPath) {
+    const key = generateCacheKey(metadata);
+    const scriptName = getScriptName(scriptPath);
+    return join(getCacheBase(), `${scriptName}-${key}`);
+}
+/**
+ * Check if cache exists for given metadata.
+ */
+export function cacheExists(metadata, scriptPath) {
+    const cacheDir = getCacheDir(metadata, scriptPath);
+    return existsSync(join(cacheDir, 'node_modules'));
+}
+/**
+ * Create package.json content for dependencies.
+ */
+function createPackageJson(metadata) {
+    return JSON.stringify({
+        name: 'runx-env',
+        version: '0.0.0',
+        private: true,
+        dependencies: metadata.dependencies,
+    }, null, 2);
+}
+/**
+ * Run bun install in the cache directory.
+ */
+async function runBunInstall(cacheDir) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn('bun', ['install'], {
+            cwd: cacheDir,
+            stdio: 'inherit',
+        });
+        proc.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`bun install failed with code ${code}`));
+            }
+        });
+        proc.on('error', reject);
+    });
+}
+/**
+ * Resolve environment for script metadata.
+ * Creates cache if it doesn't exist.
+ */
+export async function resolveEnvironment(metadata, scriptPath) {
+    if (Object.keys(metadata.dependencies).length === 0) {
+        return '';
+    }
+    const cacheDir = getCacheDir(metadata, scriptPath);
+    if (cacheExists(metadata, scriptPath)) {
+        return join(cacheDir, 'node_modules');
+    }
+    // Create cache directory
+    await mkdir(cacheDir, { recursive: true });
+    // Write package.json
+    const packageJson = createPackageJson(metadata);
+    await writeFile(join(cacheDir, 'package.json'), packageJson);
+    // Run bun install
+    console.error(`Installing dependencies...`);
+    await runBunInstall(cacheDir);
+    return join(cacheDir, 'node_modules');
+}
+/**
+ * Clean all cached environments.
+ */
+export async function cleanCache() {
+    const cacheBase = getCacheBase();
+    if (!existsSync(cacheBase)) {
+        console.log('Cache is already empty.');
+        return;
+    }
+    const entries = await readdir(cacheBase);
+    await rm(cacheBase, { recursive: true, force: true });
+    console.log(`Cleaned ${entries.length} cached environment(s).`);
+}

package/dist/runner.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Run a TypeScript script with bun.
+ */
+export declare function runScript(scriptPath: string, nodeModulesPath: string, args: string[]): Promise<number>;

package/dist/runner.js

@@ -0,0 +1,29 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+/**
+ * Run a TypeScript script with bun.
+ */
+export async function runScript(scriptPath, nodeModulesPath, args) {
+    const absoluteScriptPath = resolve(scriptPath);
+    const env = { ...process.env };
+    if (nodeModulesPath) {
+        // Set NODE_PATH to include the cached node_modules
+        const existingNodePath = env.NODE_PATH || '';
+        const separator = process.platform === 'win32' ? ';' : ':';
+        env.NODE_PATH = existingNodePath
+            ? `${nodeModulesPath}${separator}${existingNodePath}`
+            : nodeModulesPath;
+    }
+    return new Promise((resolve, reject) => {
+        const proc = spawn('bun', ['run', absoluteScriptPath, ...args], {
+            stdio: 'inherit',
+            env,
+        });
+        proc.on('close', (code) => {
+            resolve(code ?? 0);
+        });
+        proc.on('error', (err) => {
+            reject(err);
+        });
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,3 @@
+export interface ScriptMetadata {
+    dependencies: Record<string, string>;
+}

package/dist/types.js

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

package/dist/update-check.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Check npm registry for a newer version of runx.
+ * Caches result for 24 hours. Returns silently on any error.
+ */
+export declare function checkForUpdate(currentVersion: string): Promise<string>;
+/**
+ * Format update notification message.
+ */
+export declare function formatUpdateMessage(currentVersion: string, latestVersion: string): string;

package/dist/update-check.js

@@ -0,0 +1,101 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const REGISTRY_URL = 'https://registry.npmjs.org/@cencivic/runx/latest';
+const CHECK_INTERVAL = 86_400_000; // 24 hours
+/**
+ * Get path for the update check cache file.
+ */
+function getCacheFile() {
+    if (process.platform === 'win32') {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (localAppData) {
+            return join(localAppData, 'runx', 'update-check.json');
+        }
+        return join(homedir(), 'AppData', 'Local', 'runx', 'update-check.json');
+    }
+    const xdgCacheHome = process.env.XDG_CACHE_HOME;
+    if (xdgCacheHome) {
+        return join(xdgCacheHome, 'runx', 'update-check.json');
+    }
+    return join(homedir(), '.cache', 'runx', 'update-check.json');
+}
+/**
+ * Read cached update check result.
+ */
+async function readCache() {
+    try {
+        const cacheFile = getCacheFile();
+        if (!existsSync(cacheFile))
+            return null;
+        const data = await readFile(cacheFile, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write update check result to cache.
+ */
+async function writeCache(result) {
+    const cacheFile = getCacheFile();
+    await mkdir(dirname(cacheFile), { recursive: true });
+    await writeFile(cacheFile, JSON.stringify(result));
+}
+/**
+ * Compare two semver version strings.
+ * Returns true if `latest` is newer than `current`.
+ */
+function isNewer(current, latest) {
+    const a = current.split('.').map(Number);
+    const b = latest.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((b[i] ?? 0) > (a[i] ?? 0))
+            return true;
+        if ((b[i] ?? 0) < (a[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+/**
+ * Check npm registry for a newer version of runx.
+ * Caches result for 24 hours. Returns silently on any error.
+ */
+export async function checkForUpdate(currentVersion) {
+    // Skip in CI
+    if (process.env.CI)
+        return '';
+    try {
+        const cached = await readCache();
+        const now = Date.now();
+        // Use cache if within 24h
+        if (cached && now - cached.time < CHECK_INTERVAL) {
+            return isNewer(currentVersion, cached.latest) ? cached.latest : '';
+        }
+        // Fetch with 1.5s timeout
+        const response = await Promise.race([
+            fetch(REGISTRY_URL),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 1500)),
+        ]);
+        const data = (await response.json());
+        const latest = data.version;
+        await writeCache({ latest, time: now });
+        return isNewer(currentVersion, latest) ? latest : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Format update notification message.
+ */
+export function formatUpdateMessage(currentVersion, latestVersion) {
+    return [
+        '',
+        `  Update available: ${currentVersion} → \x1b[32m${latestVersion}\x1b[0m`,
+        `  Run \x1b[36mbun install -g @cencivic/runx\x1b[0m to update`,
+        '',
+    ].join('\n');
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@cencivic/runx",
+  "version": "0.1.0",
+  "description": "uv-like script runner for TypeScript",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "runx": "./bin/runx.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "lint": "biome check --fix .",
+    "format": "biome format --write .",
+    "check": "biome check .",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@types/node": "^20.0.0",
+    "bun-types": "^1.3.8",
+    "typescript": "^5.0.0",
+    "@types/bun": "latest"
+  },
+  "dependencies": {
+    "comment-parser": "^1.4.5"
+  }
+}