symlx 0.1.8 → 0.1.11

package/README.md

@@ -1,4 +1,4 @@
-# Quick Start
+# tl:dr
 
 In a CLI project with:
 
@@ -46,6 +46,9 @@ Core guarantees:
 - Links are session-scoped and cleaned on exit.
 - Collision behavior is explicit (`prompt`, `skip`, `fail`, `overwrite`).
 - Option resolution is deterministic.
+- Target execution is hybrid by default:
+  - shebang present -> direct link
+  - no shebang -> launcher inference by target type
 - PATH setup for `~/.symlx/bin` is automated on install (with opt-out).
 
 ## Install
@@ -97,7 +100,7 @@ symlx serve --bin-resolution-strategy merge
 
 Links commands from resolved bin mappings and exits immediately.
 
-It uses the exact same options and resolution behavior as `symlx serve`, but it does not keep a live session.
+It uses the exact same options and resolution behavior as `symlx serve`, _but it does not keep a live session_.
 
 Examples:
 
@@ -121,7 +124,7 @@ Scalar fields (`collision`, `binDir`, `nonInteractive`, `binResolutionStrategy`)
 
 `bin` uses strategy mode:
 
-- `replace` (default): first non-empty wins by priority`inline > config > package.json > default`
+- `replace` (default): first non-empty wins by priority `inline > config > package.json > default`
 - `merge`: combines all
   `package.json + config + inline` (right-most source overrides key collisions)
 
@@ -165,7 +168,7 @@ If `bin` is a string, `name` is required so command name can be inferred.
 
 Notes:
 
-- In case of invalid config values, `symlx` fallback to defaults (with warnings).
+- In case of invalid non-critical config values, `symlx` falls back to defaults (with warnings).
 - `binDir` is treated as critical and must pass validation.
 
 ## Inline Flags
@@ -189,6 +192,25 @@ symlx serve \
 - must be relative (for example `dist/cli.js` or `./dist/cli.js`)
 - absolute paths are rejected
 
+## Target Execution Model (Hybrid by Default)
+
+For each resolved target file:
+
+- if target has a shebang, symlx links it directly
+- if target has no shebang, symlx infers launcher by file type
+
+Current launcher inference:
+
+- `.js`, `.mjs`, `.cjs` -> Node launcher
+- `.ts`, `.tsx`, `.mts`, `.cts` -> `tsx` launcher
+
+TypeScript runtime resolution order is:
+
+1. project-local `node_modules/.bin/tsx`
+2. `tsx` on `PATH`
+
+If target has no shebang and launcher support is unavailable, symlx fails with a clear message that this is not supported yet without shebang and asks you to manually add shebang.
+
 ## Collision Policies
 
 - `prompt`: ask per conflict (interactive TTY only)
@@ -200,7 +222,7 @@ If `prompt` is requested in non-interactive mode, symlx falls back to `skip` and
 
 ## Install-Time PATH Setup
 
-On install, `symlx` updates shell profile PATH block
+On install, `symlx` updates shell profile PATH block.
 
 Managed path:
 
@@ -214,7 +236,7 @@ Opt out:
 SYMLX_SKIP_PATH_SETUP=1 npm i -g symlx
 ```
 
-To set a custome bin PATH:
+To set a custom bin directory:
 
 ```bash
 symlx serve --bin-dir ~/.symlx/bin
@@ -226,9 +248,10 @@ Before linking, symlx prepares each resolved bin target:
 
 - file exists
 - target is not a directory
-- target is made executable automatically on unix-like systems when possible
+- shebang path: direct link + executable permission repair when possible
+- no-shebang path: launcher inference + runtime availability checks
 
-Missing targets, directories, and permission-update failures still fail early with actionable messages.
+Missing targets, directories, unsupported no-shebang target types, missing launcher runtimes, and permission-update failures fail early with actionable messages.
 
 ## Exit Behavior
 
@@ -238,6 +261,10 @@ Missing targets, directories, and permission-update failures still fail early wi
 
 ## Troubleshooting
 
+## "not supported yet without shebang"
+
+- add a shebang to the target file to declare its runner explicitly
+
 ## "no bin entries found"
 
 Add a bin mapping in at least one place:
@@ -256,6 +283,10 @@ symlx serve --collision overwrite
 symlx serve --collision fail
 ```
 
+## "tsx runtime could not be resolved for target"
+
+Install `tsx` in the project or make `tsx` available on `PATH`.
+
 ## "package.json not found"
 
 Run in your project root, or pass bins inline/config.

package/dist/commands/link.js

@@ -40,25 +40,25 @@ exports.linkCommand = linkCommand;
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const log = __importStar(require("../ui/logger"));
-const serve_output_1 = require("../ui/serve-output");
-const options_1 = require("../lib/options");
-const schema_1 = require("../lib/schema");
 const bin_targets_1 = require("../lib/bin-targets");
+const constants_1 = require("../lib/constants");
 const link_manager_1 = require("../lib/link-manager");
+const options_1 = require("../lib/options");
+const schema_1 = require("../lib/schema");
 const session_store_1 = require("../lib/session-store");
-const constants_1 = require("../lib/constants");
+const serve_output_1 = require("../ui/serve-output");
 async function linkCommand(inlineOptions) {
     const cwd = process.cwd();
     const homeDirectory = node_os_1.default.homedir();
     const sessionDir = node_path_1.default.join(homeDirectory, '.symlx', 'sessions');
     const options = (0, options_1.resolveOptions)(cwd, schema_1.serveInlineOptionsSchema, inlineOptions);
-    const internalCollisionOption = (0, options_1.resolveInternalCollisionOption)(options.collision, options.nonInteractive);
+    const collisionOption = (0, options_1.resolveInternalCollisionOption)(options.collision, options.nonInteractive);
     (0, session_store_1.cleanupStaleSessions)(sessionDir);
     (0, session_store_1.ensureSymlxDirectories)(options.binDir, sessionDir);
-    (0, bin_targets_1.prepareBinTargets)(options.bin);
-    const linkResult = await (0, link_manager_1.createLinks)(options.bin, options.binDir, internalCollisionOption);
+    const preparedTargets = (0, bin_targets_1.prepareBinTargets)(cwd, options.bin);
+    const linkResult = await (0, link_manager_1.createLinks)(preparedTargets, options.binDir, collisionOption);
     (0, link_manager_1.assertLinksCreated)(linkResult);
-    if (options.collision === 'prompt' && internalCollisionOption !== 'prompt') {
+    if (options.collision === 'prompt' && collisionOption !== 'prompt') {
         log.warn(constants_1.PROMPT_FALLBACK_WARNING);
     }
     (0, serve_output_1.printLinkOutcome)(options.binDir, linkResult);

package/dist/commands/serve.js

@@ -40,13 +40,13 @@ exports.serveCommand = serveCommand;
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const log = __importStar(require("../ui/logger"));
-const serve_output_1 = require("../ui/serve-output");
-const options_1 = require("../lib/options");
-const schema_1 = require("../lib/schema");
 const bin_targets_1 = require("../lib/bin-targets");
+const constants_1 = require("../lib/constants");
 const link_manager_1 = require("../lib/link-manager");
+const options_1 = require("../lib/options");
+const schema_1 = require("../lib/schema");
 const session_store_1 = require("../lib/session-store");
-const constants_1 = require("../lib/constants");
+const serve_output_1 = require("../ui/serve-output");
 function waitUntilStopped() {
     return new Promise(() => {
         setInterval(() => undefined, 60_000);
@@ -56,23 +56,18 @@ async function serveCommand(inlineOptions) {
     const cwd = process.cwd();
     const homeDirectory = node_os_1.default.homedir();
     const sessionDir = node_path_1.default.join(homeDirectory, '.symlx', 'sessions');
-    // resolve options by merge or otherwise and resolve collision based on interactiveness
     const options = (0, options_1.resolveOptions)(cwd, schema_1.serveInlineOptionsSchema, inlineOptions);
-    const internalCollisionOption = (0, options_1.resolveInternalCollisionOption)(options.collision, options.nonInteractive);
-    // prepare
+    const collisionOption = (0, options_1.resolveInternalCollisionOption)(options.collision, options.nonInteractive);
     (0, session_store_1.cleanupStaleSessions)(sessionDir);
     (0, session_store_1.ensureSymlxDirectories)(options.binDir, sessionDir);
-    (0, bin_targets_1.prepareBinTargets)(options.bin);
-    // link creation
-    const linkResult = await (0, link_manager_1.createLinks)(options.bin, options.binDir, internalCollisionOption);
+    const preparedTargets = (0, bin_targets_1.prepareBinTargets)(cwd, options.bin);
+    const linkResult = await (0, link_manager_1.createLinks)(preparedTargets, options.binDir, collisionOption);
     (0, link_manager_1.assertLinksCreated)(linkResult);
-    // session management
     const sessionPath = (0, session_store_1.generateSessionFilePath)(sessionDir);
     const sessionRecord = (0, session_store_1.generateSessionRecord)(cwd, linkResult.created);
     (0, session_store_1.persistSession)(sessionPath, sessionRecord);
     (0, session_store_1.registerLifecycleSessionCleanup)(sessionPath, sessionRecord.links);
-    // logs
-    if (options.collision === 'prompt' && internalCollisionOption !== 'prompt') {
+    if (options.collision === 'prompt' && collisionOption !== 'prompt') {
         log.warn(constants_1.PROMPT_FALLBACK_WARNING);
     }
     (0, serve_output_1.printLinkOutcome)(options.binDir, linkResult);

package/dist/lib/bin-targets.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prepareBinTargets = prepareBinTargets;
 const node_fs_1 = __importDefault(require("node:fs"));
+const launchers_1 = require("./launchers");
+const shebang_1 = require("./shebang");
 function isExecutable(filePath) {
     if (process.platform === 'win32') {
         return true;
@@ -34,43 +36,6 @@ function ensureExecutable(filePath, currentMode) {
     }
     return 'target permissions could not be updated';
 }
-function inspectBinTarget(name, target) {
-    if (!node_fs_1.default.existsSync(target)) {
-        return {
-            name,
-            target,
-            reason: 'target file does not exist',
-        };
-    }
-    let stats;
-    try {
-        stats = node_fs_1.default.statSync(target);
-    }
-    catch (error) {
-        return {
-            name,
-            target,
-            reason: `target cannot be accessed (${String(error)})`,
-        };
-    }
-    if (stats.isDirectory()) {
-        return {
-            name,
-            target,
-            reason: 'target is a directory',
-        };
-    }
-    const executableIssue = ensureExecutable(target, stats.mode);
-    if (executableIssue) {
-        return {
-            name,
-            target,
-            reason: executableIssue,
-            hint: `run: chmod +x ${target}`,
-        };
-    }
-    return undefined;
-}
 function formatIssues(issues) {
     return issues
         .map((issue) => {
@@ -79,20 +44,89 @@ function formatIssues(issues) {
     })
         .join('\n');
 }
-function prepareBinTargets(bin) {
+function addUnsupportedWithoutShebangIssue(issues, name, target, reason) {
+    const detail = reason ? ` (${reason})` : '';
+    issues.push({
+        name,
+        target,
+        reason: `not supported yet without shebang${detail}`,
+        hint: 'explicitly specify a shebang at the top of the target file to declare its runner',
+    });
+}
+function prepareBinTargets(cwd, bin, options = {}) {
+    const currentPath = options.currentPath ?? process.env.PATH;
+    const preparedTargets = [];
     const issues = [];
     for (const [name, target] of Object.entries(bin)) {
-        const issue = inspectBinTarget(name, target);
-        if (issue) {
-            issues.push(issue);
+        if (!node_fs_1.default.existsSync(target)) {
+            issues.push({
+                name,
+                target,
+                reason: 'target file does not exist',
+            });
+            continue;
+        }
+        let stats;
+        try {
+            stats = node_fs_1.default.statSync(target);
+        }
+        catch (error) {
+            issues.push({
+                name,
+                target,
+                reason: `target cannot be accessed (${String(error)})`,
+            });
+            continue;
         }
+        if (stats.isDirectory()) {
+            issues.push({
+                name,
+                target,
+                reason: 'target is a directory',
+            });
+            continue;
+        }
+        if ((0, shebang_1.hasShebang)(target)) {
+            const executableIssue = ensureExecutable(target, stats.mode);
+            if (executableIssue) {
+                issues.push({
+                    name,
+                    target,
+                    reason: executableIssue,
+                    hint: `run: chmod +x ${target}`,
+                });
+                continue;
+            }
+            preparedTargets.push({
+                name,
+                target,
+                kind: 'direct-link',
+            });
+            continue;
+        }
+        const launcher = (0, launchers_1.resolveInferredLauncher)(cwd, target, currentPath);
+        if (!launcher) {
+            addUnsupportedWithoutShebangIssue(issues, name, target);
+            continue;
+        }
+        if ('reason' in launcher) {
+            addUnsupportedWithoutShebangIssue(issues, name, target, launcher.reason);
+            continue;
+        }
+        preparedTargets.push({
+            name,
+            target,
+            kind: 'launcher',
+            launcherKind: launcher.launcherKind,
+            runtimeCommand: launcher.runtimeCommand,
+        });
     }
     if (issues.length === 0) {
-        return;
+        return preparedTargets;
     }
     throw new Error([
         'invalid bin targets:',
         formatIssues(issues),
-        'fix bin paths or file permissions in package.json, symlx.config.json, or inline --bin and run again.',
+        'fix bin paths, launcher support, shebang declarations, or file permissions in package.json, symlx.config.json, or inline --bin and run again.',
     ].join('\n'));
 }

package/dist/lib/launchers.js

@@ -0,0 +1,137 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferLauncherKind = inferLauncherKind;
+exports.resolveInferredLauncher = resolveInferredLauncher;
+exports.writeLauncher = writeLauncher;
+exports.matchesLauncher = matchesLauncher;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const NODE_TARGET_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
+const TYPESCRIPT_TARGET_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+const LAUNCHER_MARKER = '// symlx:launcher';
+function isExecutable(filePath) {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return false;
+    }
+    if (process.platform === 'win32') {
+        return true;
+    }
+    try {
+        node_fs_1.default.accessSync(filePath, node_fs_1.default.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveExecutableOnPath(commandName, currentPath) {
+    if (!currentPath) {
+        return undefined;
+    }
+    for (const directory of currentPath.split(node_path_1.default.delimiter)) {
+        if (!directory) {
+            continue;
+        }
+        const candidate = node_path_1.default.join(directory, commandName);
+        if (isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function createLauncherContent(launcherKind, runtimeCommand, target) {
+    return `#!/usr/bin/env node
+${LAUNCHER_MARKER} kind=${launcherKind}
+const { spawnSync } = require('node:child_process');
+
+const launcherKind = ${JSON.stringify(launcherKind)};
+const runtimeCommand = ${JSON.stringify(runtimeCommand)};
+const targetPath = ${JSON.stringify(target)};
+
+const result = spawnSync(
+  runtimeCommand,
+  [targetPath, ...process.argv.slice(2)],
+  { stdio: 'inherit' },
+);
+
+if (result.error) {
+  process.stderr.write(
+    '[symlx] failed to launch target via ' +
+      launcherKind +
+      ': ' +
+      String(result.error) +
+      '\\n',
+  );
+  process.exit(1);
+}
+
+if (typeof result.status === 'number') {
+  process.exit(result.status);
+}
+
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+
+process.exit(1);
+`;
+}
+const LAUNCHERS = [
+    {
+        kind: 'node',
+        supportsTarget: (target) => NODE_TARGET_EXTENSIONS.has(node_path_1.default.extname(target).toLowerCase()),
+        resolveRuntime: () => process.execPath,
+        missingRuntimeHint: 'node runtime could not be resolved',
+    },
+    {
+        kind: 'tsx',
+        supportsTarget: (target) => TYPESCRIPT_TARGET_EXTENSIONS.has(node_path_1.default.extname(target).toLowerCase()),
+        resolveRuntime: (cwd, currentPath) => {
+            const localCandidate = node_path_1.default.join(cwd, 'node_modules', '.bin', 'tsx');
+            if (isExecutable(localCandidate)) {
+                return localCandidate;
+            }
+            return resolveExecutableOnPath('tsx', currentPath);
+        },
+        missingRuntimeHint: 'install tsx in the project or make tsx available on PATH',
+    },
+];
+function findLauncherDefinition(target) {
+    return LAUNCHERS.find((launcher) => launcher.supportsTarget(target));
+}
+function inferLauncherKind(target) {
+    return findLauncherDefinition(target)?.kind;
+}
+function resolveInferredLauncher(cwd, target, currentPath = process.env.PATH) {
+    const launcher = findLauncherDefinition(target);
+    if (!launcher) {
+        return undefined;
+    }
+    const runtimeCommand = launcher.resolveRuntime(cwd, currentPath);
+    if (runtimeCommand) {
+        return {
+            launcherKind: launcher.kind,
+            runtimeCommand,
+        };
+    }
+    return {
+        reason: `${launcher.kind} runtime could not be resolved for target`,
+        hint: launcher.missingRuntimeHint,
+    };
+}
+function writeLauncher(linkPath, launcherKind, runtimeCommand, target) {
+    node_fs_1.default.writeFileSync(linkPath, createLauncherContent(launcherKind, runtimeCommand, target), 'utf8');
+    node_fs_1.default.chmodSync(linkPath, 0o755);
+}
+function matchesLauncher(linkPath, launcherKind, runtimeCommand, target) {
+    try {
+        const content = node_fs_1.default.readFileSync(linkPath, 'utf8');
+        return (content === createLauncherContent(launcherKind, runtimeCommand, target));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/link-manager.js

@@ -7,6 +7,7 @@ exports.createLinks = createLinks;
 exports.assertLinksCreated = assertLinksCreated;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const launchers_1 = require("./launchers");
 const prompts_1 = require("../ui/prompts");
 // lstat wrapper that treats missing files as "not found" but rethrows real IO errors.
 function tryLstat(filePath) {
@@ -47,6 +48,36 @@ function removeExistingNode(linkPath, node) {
     }
     node_fs_1.default.unlinkSync(linkPath);
 }
+function matchesPreparedTarget(linkPath, entry, existingNode) {
+    if (entry.kind === 'direct-link') {
+        return Boolean(existingNode.existingTarget &&
+            node_path_1.default.resolve(existingNode.existingTarget) === node_path_1.default.resolve(entry.target));
+    }
+    if (existingNode.stats.isSymbolicLink() || !existingNode.stats.isFile()) {
+        return false;
+    }
+    return (0, launchers_1.matchesLauncher)(linkPath, entry.launcherKind, entry.runtimeCommand, entry.target);
+}
+function createCommandEntry(linkPath, entry) {
+    if (entry.kind === 'direct-link') {
+        node_fs_1.default.symlinkSync(entry.target, linkPath);
+        return {
+            name: entry.name,
+            linkPath,
+            target: entry.target,
+            kind: 'direct-link',
+        };
+    }
+    (0, launchers_1.writeLauncher)(linkPath, entry.launcherKind, entry.runtimeCommand, entry.target);
+    return {
+        name: entry.name,
+        linkPath,
+        target: entry.target,
+        kind: 'launcher',
+        launcherKind: entry.launcherKind,
+        runtimeCommand: entry.runtimeCommand,
+    };
+}
 // Normalizes filesystem state into a user-facing collision descriptor.
 function toConflict(name, linkPath, target, node) {
     if (node.stats.isSymbolicLink()) {
@@ -69,51 +100,44 @@ function toConflict(name, linkPath, target, node) {
         isSymlink: false,
     };
 }
-// Creates symlinks for all project bins according to the selected collision strategy.
+// Creates command entries for all prepared bins according to the selected collision strategy.
 // This function is pure with regard to policy: caller decides interactive vs non-interactive.
-async function createLinks(bins, binDir, collisionOption) {
+async function createLinks(preparedTargets, binDir, collisionOption) {
     const created = [];
     const skipped = [];
-    // Link every executable in the bin options
-    for (const [name, target] of Object.entries(bins)) {
-        const linkPath = node_path_1.default.join(binDir, name);
-        // check is there's an existing binary on the device
+    for (const entry of preparedTargets) {
+        const linkPath = node_path_1.default.join(binDir, entry.name);
         const existingNode = inspectExistingNode(linkPath);
-        // If there's a conflicting binary, handle the conflict
         if (existingNode) {
-            const conflict = toConflict(name, linkPath, target, existingNode);
-            // Reusing the exact same link is always a no-op.
-            if (conflict.existingTarget &&
-                node_path_1.default.resolve(conflict.existingTarget) === node_path_1.default.resolve(target)) {
+            const conflict = toConflict(entry.name, linkPath, entry.target, existingNode);
+            if (matchesPreparedTarget(linkPath, entry, existingNode)) {
                 skipped.push({
-                    name,
+                    name: entry.name,
                     linkPath,
                     reason: 'already linked to requested target',
                 });
                 continue;
             }
             if (collisionOption === 'fail') {
-                throw new Error(`command "${name}" conflicts at ${linkPath}: ${conflict.reason}`);
+                throw new Error(`command "${entry.name}" conflicts at ${linkPath}: ${conflict.reason}`);
             }
             let collisionDecision;
             if (collisionOption === 'prompt') {
                 collisionDecision = await (0, prompts_1.promptCollisionResolver)(conflict);
                 if (collisionDecision === 'abort') {
-                    throw new Error(`aborted on collision for command "${name}"`);
+                    throw new Error(`aborted on collision for command "${entry.name}"`);
                 }
             }
             else {
-                // After here, resulting decision can only either be 'skip' or 'overwrite'
                 collisionDecision = collisionOption;
             }
             if (collisionDecision === 'skip') {
-                skipped.push({ name, linkPath, reason: conflict.reason });
+                skipped.push({ name: entry.name, linkPath, reason: conflict.reason });
                 continue;
             }
             removeExistingNode(linkPath, existingNode);
         }
-        node_fs_1.default.symlinkSync(target, linkPath);
-        created.push({ name, linkPath, target });
+        created.push(createCommandEntry(linkPath, entry));
     }
     return { created, skipped };
 }

package/dist/lib/session-store.js

@@ -45,6 +45,7 @@ exports.persistSession = persistSession;
 exports.registerLifecycleSessionCleanup = registerLifecycleSessionCleanup;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const launchers_1 = require("./launchers");
 const log = __importStar(require("../ui/logger"));
 const utils_1 = require("./utils");
 // Checks whether a PID from a previous session is still alive.
@@ -65,20 +66,36 @@ function isProcessAlive(pid) {
         return code !== 'ESRCH';
     }
 }
-// Removes only symlinks that still point to the exact targets we created.
+function cleanupDirectLink(link) {
+    const stats = node_fs_1.default.lstatSync(link.linkPath);
+    if (!stats.isSymbolicLink()) {
+        return;
+    }
+    const linkedTo = node_fs_1.default.readlinkSync(link.linkPath);
+    const absoluteLinkedTo = node_path_1.default.resolve(node_path_1.default.dirname(link.linkPath), linkedTo);
+    if (absoluteLinkedTo === node_path_1.default.resolve(link.target)) {
+        node_fs_1.default.unlinkSync(link.linkPath);
+    }
+}
+function cleanupLauncher(link) {
+    const stats = node_fs_1.default.lstatSync(link.linkPath);
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+        return;
+    }
+    if ((0, launchers_1.matchesLauncher)(link.linkPath, link.launcherKind, link.runtimeCommand, link.target)) {
+        node_fs_1.default.unlinkSync(link.linkPath);
+    }
+}
+// Removes only command entries that still match the exact records we created.
 // This avoids deleting user-managed commands with the same name.
 function cleanupLinks(links) {
     for (const link of links) {
         try {
-            const stats = node_fs_1.default.lstatSync(link.linkPath);
-            if (!stats.isSymbolicLink()) {
+            if (link.kind === 'direct-link') {
+                cleanupDirectLink(link);
                 continue;
             }
-            const linkedTo = node_fs_1.default.readlinkSync(link.linkPath);
-            const absoluteLinkedTo = node_path_1.default.resolve(node_path_1.default.dirname(link.linkPath), linkedTo);
-            if (absoluteLinkedTo === node_path_1.default.resolve(link.target)) {
-                node_fs_1.default.unlinkSync(link.linkPath);
-            }
+            cleanupLauncher(link);
         }
         catch {
             // Best-effort cleanup.
@@ -90,7 +107,7 @@ function ensureSymlxDirectories(binDir, sessionDir) {
     node_fs_1.default.mkdirSync(binDir, { recursive: true });
     node_fs_1.default.mkdirSync(sessionDir, { recursive: true });
 }
-// Reaps stale sessions left behind by crashes/kill -9 and removes their symlinks.
+// Reaps stale sessions left behind by crashes/kill -9 and removes their command entries.
 function cleanupStaleSessions(sessionDir) {
     // If the directory does not exist, return early
     if (!node_fs_1.default.existsSync(sessionDir)) {

package/dist/lib/shebang.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readShebang = readShebang;
+exports.hasShebang = hasShebang;
+const node_fs_1 = __importDefault(require("node:fs"));
+function readShebang(filePath) {
+    const raw = node_fs_1.default.readFileSync(filePath, 'utf8');
+    const firstLine = raw.split(/\r?\n/, 1)[0]?.replace(/^\uFEFF/, '');
+    if (!firstLine?.startsWith('#!')) {
+        return undefined;
+    }
+    return firstLine;
+}
+function hasShebang(filePath) {
+    return Boolean(readShebang(filePath));
+}

package/dist/lib/tsx-runtime.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSX_LAUNCHER_MARKER = void 0;
+exports.isTypeScriptTarget = isTypeScriptTarget;
+exports.resolveTsxRuntime = resolveTsxRuntime;
+exports.createTsxLauncherContent = createTsxLauncherContent;
+exports.writeTsxLauncher = writeTsxLauncher;
+exports.matchesTsxLauncher = matchesTsxLauncher;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const TYPESCRIPT_TARGET_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+const TSX_LAUNCHER_MARKER = '// symlx:tsx-launcher';
+exports.TSX_LAUNCHER_MARKER = TSX_LAUNCHER_MARKER;
+function isExecutable(filePath) {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return false;
+    }
+    if (process.platform === 'win32') {
+        return true;
+    }
+    try {
+        node_fs_1.default.accessSync(filePath, node_fs_1.default.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveExecutableOnPath(commandName, currentPath) {
+    if (!currentPath) {
+        return undefined;
+    }
+    for (const directory of currentPath.split(node_path_1.default.delimiter)) {
+        if (!directory) {
+            continue;
+        }
+        const candidate = node_path_1.default.join(directory, commandName);
+        if (isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function isTypeScriptTarget(target) {
+    return TYPESCRIPT_TARGET_EXTENSIONS.has(node_path_1.default.extname(target).toLowerCase());
+}
+function resolveTsxRuntime(cwd, currentPath = process.env.PATH) {
+    const localCandidate = node_path_1.default.join(cwd, 'node_modules', '.bin', 'tsx');
+    if (isExecutable(localCandidate)) {
+        return localCandidate;
+    }
+    return resolveExecutableOnPath('tsx', currentPath);
+}
+function createTsxLauncherContent(runtimeCommand, target) {
+    return `#!/usr/bin/env node
+${TSX_LAUNCHER_MARKER}
+const { spawnSync } = require('node:child_process');
+
+const runtimeCommand = ${JSON.stringify(runtimeCommand)};
+const targetPath = ${JSON.stringify(target)};
+
+const result = spawnSync(
+  runtimeCommand,
+  [targetPath, ...process.argv.slice(2)],
+  { stdio: 'inherit' },
+);
+
+if (result.error) {
+  process.stderr.write(
+    '[symlx] failed to launch TypeScript target via tsx: ' +
+      String(result.error) +
+      '\\n',
+  );
+  process.exit(1);
+}
+
+if (typeof result.status === 'number') {
+  process.exit(result.status);
+}
+
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+
+process.exit(1);
+`;
+}
+function writeTsxLauncher(linkPath, runtimeCommand, target) {
+    node_fs_1.default.writeFileSync(linkPath, createTsxLauncherContent(runtimeCommand, target), 'utf8');
+    node_fs_1.default.chmodSync(linkPath, 0o755);
+}
+function matchesTsxLauncher(linkPath, runtimeCommand, target) {
+    try {
+        const content = node_fs_1.default.readFileSync(linkPath, 'utf8');
+        return content === createTsxLauncherContent(runtimeCommand, target);
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "symlx",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "description": "Temporary local CLI bin linker",
   "license": "MIT",
   "bin": {