symlx 0.1.4 → 0.1.5

package/README.md

@@ -4,6 +4,7 @@ Temporary command linker for local CLI development.
 
 `symlx serve` links command names from your project into a runnable bin directory for the lifetime of the process.
 When `symlx` stops, those links are cleaned up.
+`symlx link` creates the same links once and exits immediately.
 
 ## Why symlx
 
@@ -42,7 +43,7 @@ In a CLI project with:
 run:
 
 ```bash
-symlx serve
+symlx link
 ```
 
 Then use your CLI normally:
@@ -51,7 +52,7 @@ Then use your CLI normally:
 my-cli --help
 ```
 
-Stop `symlx` with `Ctrl+C` to clean links.
+Use `symlx serve` when you want temporary session-scoped links with auto-cleanup on exit.
 
 ## Alias
 
@@ -61,7 +62,9 @@ Equivalent commands:
 
 ```bash
 symlx serve
+symlx link
 cx serve
+cx link
 ```
 
 ## Command Reference
@@ -88,6 +91,20 @@ symlx serve --bin admin=dist/admin.js --bin worker=dist/worker.js
 symlx serve --bin-resolution-strategy merge
 ```
 
+## `symlx link`
+
+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.
+
+Examples:
+
+```bash
+symlx link
+symlx link --collision overwrite
+symlx link --bin admin=dist/admin.js
+```
+
 ## Bin Resolution Model
 
 `symlx` resolves options from three user sources plus defaults:
@@ -203,13 +220,13 @@ symlx serve --bin-dir ~/.symlx/bin
 
 ## Runtime Safety Checks
 
-Before linking, symlx validates each resolved bin target:
+Before linking, symlx prepares each resolved bin target:
 
 - file exists
 - target is not a directory
-- target is executable on unix-like systems
+- target is made executable automatically on unix-like systems when possible
 
-Invalid targets fail early with actionable messages.
+Missing targets, directories, and permission-update failures still fail early with actionable messages.
 
 ## Exit Behavior
 
@@ -227,12 +244,6 @@ Add a bin mapping in at least one place:
 - `symlx.config.json -> bin`
 - `--bin name=path`
 
-## "target is not executable"
-
-```bash
-chmod +x dist/cli.js # or your target executable
-```
-
 ## "command conflicts at ..."
 
 Use a collision mode:

package/dist/cli.js

@@ -36,11 +36,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const log = __importStar(require("./ui/logger"));
+const link_1 = require("./commands/link");
 const serve_1 = require("./commands/serve");
-function collectBinEntry(value, previous = []) {
-    previous.push(value);
-    return previous;
-}
+const options_1 = require("./options");
 async function main() {
     // Commander orchestrates top-level commands/options and help output.
     const program = new commander_1.Command();
@@ -51,12 +49,21 @@ async function main() {
     program
         .command('serve')
         .description("Link this project's bin commands until symlx exits")
-        .option('--bin-dir <dir>', 'target bin directory (default: ~/.symlx/bin)')
-        .option('--collision <policy>', 'collision mode: prompt|skip|fail|overwrite', 'prompt')
-        .option('--bin-resolution-strategy <strategy>', 'bin precedence strategy: replace|merge', 'replace')
-        .option('--non-interactive', 'disable interactive prompts', false)
-        .option('--bin <name=path>', 'custom bin mapping (repeatable), e.g. --bin my-cli=dist/cli.js', collectBinEntry, [])
+        .option(...options_1.binDirOption)
+        .option(...options_1.collisionOption)
+        .option(...options_1.binResolutionStrategyOption)
+        .option(...options_1.nonInteractiveOption)
+        .option(...options_1.binOption)
         .action(serve_1.serveCommand);
+    program
+        .command('link')
+        .description("Link this project's bin commands once and exit")
+        .option(...options_1.binDirOption)
+        .option(...options_1.collisionOption)
+        .option(...options_1.binResolutionStrategyOption)
+        .option(...options_1.nonInteractiveOption)
+        .option(...options_1.binOption)
+        .action(link_1.linkCommand);
     await program.parseAsync(process.argv);
 }
 // Centralized fatal error boundary for command execution.

package/dist/commands/link.js

@@ -0,0 +1,66 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+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 link_manager_1 = require("../lib/link-manager");
+const session_store_1 = require("../lib/session-store");
+const constants_1 = require("../lib/constants");
+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);
+    (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);
+    (0, link_manager_1.assertLinksCreated)(linkResult);
+    if (options.collision === 'prompt' && internalCollisionOption !== 'prompt') {
+        log.warn(constants_1.PROMPT_FALLBACK_WARNING);
+    }
+    (0, serve_output_1.printLinkOutcome)(options.binDir, linkResult);
+    (0, serve_output_1.printPathHintIfNeeded)(options.binDir, process.env.PATH);
+}

package/dist/commands/serve copy.js

@@ -0,0 +1,169 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serveCommand = serveCommand;
+const path_1 = __importDefault(require("path"));
+const node_os_1 = __importDefault(require("node:os"));
+const log = __importStar(require("../ui/logger"));
+const utils_1 = require("../lib/utils");
+const link_manager_1 = require("../lib/link-manager");
+const bin_targets_1 = require("../lib/bin-targets");
+const lifecycle_1 = require("../lib/lifecycle");
+const session_store_1 = require("../lib/session-store");
+const prompts_1 = require("../ui/prompts");
+const options_1 = require("../lib/options");
+const schema_1 = require("../lib/schema");
+// Prompts require an interactive terminal; scripts/CI should avoid prompt mode.
+function isInteractiveSession() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function prepareRuntimeDirectories(binDirectory, sessionDirectory) {
+    (0, session_store_1.ensureSymlxDirectories)(binDirectory, sessionDirectory);
+    (0, session_store_1.cleanupStaleSessions)(sessionDirectory);
+}
+function resolveRuntimeCollisionMode(options) {
+    if (options.collision !== 'prompt') {
+        return { policy: options.collision };
+    }
+    const canPromptForCollision = !options.nonInteractive && isInteractiveSession();
+    if (canPromptForCollision) {
+        return {
+            policy: 'prompt',
+            resolver: prompts_1.promptCollisionDecision,
+        };
+    }
+    log.warn('prompt collision mode requested but session is non-interactive; falling back to skip (use --collision overwrite|fail to avoid skips)');
+    return { policy: 'skip' };
+}
+function buildServeRuntime(options) {
+    const currentWorkingDirectory = process.cwd();
+    const sessionDirectory = path_1.default.join(node_os_1.default.homedir(), '.symlx', 'sessions');
+    prepareRuntimeDirectories(options.binDir, sessionDirectory);
+    (0, bin_targets_1.assertValidBinTargets)(options.bin);
+    return {
+        cwd: currentWorkingDirectory,
+        options,
+        sessionDirectory,
+        bins: new Map(Object.entries(options.bin)),
+        collisionMode: resolveRuntimeCollisionMode(options),
+    };
+}
+async function createRuntimeLinks(runtime) {
+    return (0, link_manager_1.createLinks)({
+        bins: runtime.bins,
+        binDir: runtime.options.binDir,
+        policy: runtime.collisionMode.policy,
+        collisionResolver: runtime.collisionMode.resolver,
+    });
+}
+function formatSkippedLinks(skippedLinks) {
+    const maxVisibleSkips = 5;
+    const visibleSkips = skippedLinks.slice(0, maxVisibleSkips);
+    const visibleSkipLines = visibleSkips
+        .map((skip) => `- ${skip.name}: ${skip.reason}`)
+        .join('\n');
+    const hiddenSkipsCount = skippedLinks.length - maxVisibleSkips;
+    const hiddenSkipsLine = hiddenSkipsCount > 0 ? `\n- ...and ${hiddenSkipsCount} more` : '';
+    return `${visibleSkipLines}${hiddenSkipsLine}`;
+}
+function assertLinkCreationSucceeded(linkResult) {
+    if (linkResult.created.length > 0) {
+        return;
+    }
+    if (linkResult.skipped.length === 0) {
+        throw new Error('no links were created');
+    }
+    throw new Error([
+        'no links were created because all candidate commands were skipped.',
+        formatSkippedLinks(linkResult.skipped),
+        'use --collision overwrite or --collision fail for stricter behavior.',
+    ].join('\n'));
+}
+function persistServeSession(runtime, links) {
+    const sessionPath = (0, session_store_1.createSessionFilePath)(runtime.sessionDirectory);
+    const record = {
+        pid: process.pid,
+        cwd: runtime.cwd,
+        createdAt: new Date().toISOString(),
+        links,
+    };
+    (0, session_store_1.persistSession)(sessionPath, record);
+    return { sessionPath, record };
+}
+function registerServeSessionCleanup(session) {
+    (0, lifecycle_1.registerLifecycleCleanup)(() => {
+        (0, session_store_1.cleanupSession)(session.sessionPath, session.record.links);
+    });
+}
+function reportLinkCreation(runtime, linkResult) {
+    const createdLinks = linkResult.created;
+    log.info(`linked ${createdLinks.length} command${createdLinks.length > 1 ? 's' : ''} into ${runtime.options.binDir}`);
+    for (const link of createdLinks) {
+        log.info(`${link.name} -> ${link.target}`);
+    }
+    for (const skippedLink of linkResult.skipped) {
+        log.warn(`skip "${skippedLink.name}": ${skippedLink.reason} (${skippedLink.linkPath})`);
+    }
+}
+function reportPathHint(binDirectory) {
+    if ((0, utils_1.pathContainsDir)(process.env.PATH, binDirectory)) {
+        return;
+    }
+    log.info(`add this to your shell config if needed:\nexport PATH="${binDirectory}:$PATH"`);
+}
+function waitUntilProcessExit() {
+    return new Promise(() => {
+        setInterval(() => undefined, 60_000);
+    });
+}
+async function run(options) {
+    const runtime = buildServeRuntime(options);
+    const linkResult = await createRuntimeLinks(runtime);
+    assertLinkCreationSucceeded(linkResult);
+    const session = persistServeSession(runtime, linkResult.created);
+    registerServeSessionCleanup(session);
+    reportLinkCreation(runtime, linkResult);
+    reportPathHint(runtime.options.binDir);
+    log.info('running. press Ctrl+C to cleanup links.');
+    await waitUntilProcessExit();
+}
+function serveCommand(inlineOptions) {
+    const currentWorkingDirectory = process.cwd();
+    const options = (0, options_1.resolveOptions)(currentWorkingDirectory, schema_1.serveInlineOptionsSchema, inlineOptions);
+    return run(options);
+}

package/dist/commands/serve.js

@@ -37,124 +37,46 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.serveCommand = serveCommand;
-const path_1 = __importDefault(require("path"));
 const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
 const log = __importStar(require("../ui/logger"));
-const utils_1 = require("../lib/utils");
-const link_manager_1 = require("../lib/link-manager");
-const bin_targets_1 = require("../lib/bin-targets");
-const lifecycle_1 = require("../lib/lifecycle");
-const session_store_1 = require("../lib/session-store");
-const prompts_1 = require("../ui/prompts");
+const serve_output_1 = require("../ui/serve-output");
 const options_1 = require("../lib/options");
 const schema_1 = require("../lib/schema");
-// Prompts require an interactive terminal; scripts/CI should avoid prompt mode.
-function isInteractiveSession() {
-    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
-}
-function prepareRuntimeDirectories(binDir, sessionDir) {
-    (0, session_store_1.cleanupStaleSessions)(sessionDir);
-    (0, session_store_1.ensureSymlxDirectories)(binDir, sessionDir);
-}
-function resolveCollisionHandling(options) {
-    if (options.collision !== 'prompt') {
-        return { policy: options.collision };
-    }
-    const canPrompt = !options.nonInteractive && isInteractiveSession();
-    if (!canPrompt) {
-        log.warn('prompt collision mode requested but session is non-interactive; falling back to skip (use --collision overwrite|fail to avoid skips)');
-        return { policy: 'skip' };
-    }
-    return {
-        policy: 'prompt',
-        collisionResolver: prompts_1.promptCollisionDecision,
-    };
-}
-async function linkCommands(options, collisionHandling) {
-    return (0, link_manager_1.createLinks)({
-        bins: new Map(Object.entries(options.bin)),
-        binDir: options.binDir,
-        policy: collisionHandling.policy,
-        collisionResolver: collisionHandling.collisionResolver,
-    });
-}
-function ensureLinksWereCreated(linkResult) {
-    if (linkResult.created.length === 0) {
-        if (linkResult.skipped.length === 0) {
-            throw new Error('no links were created');
-        }
-        const details = linkResult.skipped
-            .slice(0, 5)
-            .map((skip) => `- ${skip.name}: ${skip.reason}`)
-            .join('\n');
-        const remainingCount = linkResult.skipped.length - 5;
-        const remaining = remainingCount > 0 ? `\n- ...and ${remainingCount} more` : '';
-        throw new Error([
-            'no links were created because all candidate commands were skipped.',
-            details,
-            `${remaining}\nuse --collision overwrite or --collision fail for stricter behavior.`,
-        ].join('\n'));
-    }
-}
-function persistActiveSession(params) {
-    const { sessionDir, cwd, links } = params;
-    const sessionPath = (0, session_store_1.createSessionFilePath)(sessionDir);
-    const sessionRecord = {
-        pid: process.pid,
-        cwd,
-        createdAt: new Date().toISOString(),
-        links,
-    };
-    (0, session_store_1.persistSession)(sessionPath, sessionRecord);
-    return { sessionPath, sessionRecord };
-}
-function registerSessionCleanup(sessionPath, links) {
-    (0, lifecycle_1.registerLifecycleCleanup)(() => {
-        (0, session_store_1.cleanupSession)(sessionPath, links);
-    });
-}
-function printLinkOutcome(binDir, linkResult) {
-    const createdLinks = linkResult.created;
-    log.info(`linked ${createdLinks.length} command${createdLinks.length > 1 ? 's' : ''} into ${binDir}`);
-    for (const link of createdLinks) {
-        log.info(`${link.name} -> ${link.target}`);
-    }
-    for (const skip of linkResult.skipped) {
-        log.warn(`skip "${skip.name}": ${skip.reason} (${skip.linkPath})`);
-    }
-}
-function printPathHintIfNeeded(binDir) {
-    if ((0, utils_1.pathContainsDir)(process.env.PATH, binDir)) {
-        return;
-    }
-    log.info(`add this to your shell config if needed:\nexport PATH="${binDir}:$PATH"`);
-}
-function waitIndefinitely() {
+const bin_targets_1 = require("../lib/bin-targets");
+const link_manager_1 = require("../lib/link-manager");
+const session_store_1 = require("../lib/session-store");
+const constants_1 = require("../lib/constants");
+function waitUntilStopped() {
     return new Promise(() => {
         setInterval(() => undefined, 60_000);
     });
 }
-async function run(options) {
-    const cwd = process.cwd();
-    const sessionDir = path_1.default.join(node_os_1.default.homedir(), '.symlx', 'sessions');
-    prepareRuntimeDirectories(options.binDir, sessionDir);
-    (0, bin_targets_1.assertValidBinTargets)(options.bin);
-    const collisionHandling = resolveCollisionHandling(options);
-    const linkResult = await linkCommands(options, collisionHandling);
-    ensureLinksWereCreated(linkResult);
-    const { sessionPath, sessionRecord } = persistActiveSession({
-        sessionDir,
-        cwd,
-        links: linkResult.created,
-    });
-    registerSessionCleanup(sessionPath, sessionRecord.links);
-    printLinkOutcome(options.binDir, linkResult);
-    printPathHintIfNeeded(options.binDir);
-    log.info('running. press Ctrl+C to cleanup links.');
-    await waitIndefinitely();
-}
-function serveCommand(inlineOptions) {
+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);
-    return run(options);
+    const internalCollisionOption = (0, options_1.resolveInternalCollisionOption)(options.collision, options.nonInteractive);
+    // prepare
+    (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);
+    (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') {
+        log.warn(constants_1.PROMPT_FALLBACK_WARNING);
+    }
+    (0, serve_output_1.printLinkOutcome)(options.binDir, linkResult);
+    (0, serve_output_1.printPathHintIfNeeded)(options.binDir, process.env.PATH);
+    log.info('running. press Ctrl+C to cleanup links.');
+    await waitUntilStopped();
 }

package/dist/commands/serve_stash.js

@@ -0,0 +1,169 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serveCommand = serveCommand;
+const path_1 = __importDefault(require("path"));
+const node_os_1 = __importDefault(require("node:os"));
+const log = __importStar(require("../ui/logger"));
+const utils_1 = require("../lib/utils");
+const link_manager_1 = require("../lib/link-manager");
+const bin_targets_1 = require("../lib/bin-targets");
+const lifecycle_1 = require("../lib/lifecycle");
+const session_store_1 = require("../lib/session-store");
+const prompts_1 = require("../ui/prompts");
+const options_1 = require("../lib/options");
+const schema_1 = require("../lib/schema");
+// Prompts require an interactive terminal; scripts/CI should avoid prompt mode.
+function isInteractiveSession() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function prepareRuntimeDirectories(binDirectory, sessionDirectory) {
+    (0, session_store_1.ensureSymlxDirectories)(binDirectory, sessionDirectory);
+    (0, session_store_1.cleanupStaleSessions)(sessionDirectory);
+}
+function resolveRuntimeCollisionMode(options) {
+    if (options.collision !== 'prompt') {
+        return { policy: options.collision };
+    }
+    const canPromptForCollision = !options.nonInteractive && isInteractiveSession();
+    if (canPromptForCollision) {
+        return {
+            policy: 'prompt',
+            resolver: prompts_1.promptCollisionDecision,
+        };
+    }
+    log.warn('prompt collision mode requested but session is non-interactive; falling back to skip (use --collision overwrite|fail to avoid skips)');
+    return { policy: 'skip' };
+}
+function buildServeRuntime(options) {
+    const currentWorkingDirectory = process.cwd();
+    const sessionDirectory = path_1.default.join(node_os_1.default.homedir(), '.symlx', 'sessions');
+    prepareRuntimeDirectories(options.binDir, sessionDirectory);
+    (0, bin_targets_1.assertValidBinTargets)(options.bin);
+    return {
+        cwd: currentWorkingDirectory,
+        options,
+        sessionDirectory,
+        bins: new Map(Object.entries(options.bin)),
+        collisionMode: resolveRuntimeCollisionMode(options),
+    };
+}
+async function createRuntimeLinks(runtime) {
+    return (0, link_manager_1.createLinks)({
+        bins: runtime.bins,
+        binDir: runtime.options.binDir,
+        policy: runtime.collisionMode.policy,
+        collisionResolver: runtime.collisionMode.resolver,
+    });
+}
+function formatSkippedLinks(skippedLinks) {
+    const maxVisibleSkips = 5;
+    const visibleSkips = skippedLinks.slice(0, maxVisibleSkips);
+    const visibleSkipLines = visibleSkips
+        .map((skip) => `- ${skip.name}: ${skip.reason}`)
+        .join('\n');
+    const hiddenSkipsCount = skippedLinks.length - maxVisibleSkips;
+    const hiddenSkipsLine = hiddenSkipsCount > 0 ? `\n- ...and ${hiddenSkipsCount} more` : '';
+    return `${visibleSkipLines}${hiddenSkipsLine}`;
+}
+function assertLinkCreationSucceeded(linkResult) {
+    if (linkResult.created.length > 0) {
+        return;
+    }
+    if (linkResult.skipped.length === 0) {
+        throw new Error('no links were created');
+    }
+    throw new Error([
+        'no links were created because all candidate commands were skipped.',
+        formatSkippedLinks(linkResult.skipped),
+        'use --collision overwrite or --collision fail for stricter behavior.',
+    ].join('\n'));
+}
+function persistServeSession(runtime, links) {
+    const sessionPath = (0, session_store_1.createSessionFilePath)(runtime.sessionDirectory);
+    const record = {
+        pid: process.pid,
+        cwd: runtime.cwd,
+        createdAt: new Date().toISOString(),
+        links,
+    };
+    (0, session_store_1.persistSession)(sessionPath, record);
+    return { sessionPath, record };
+}
+function registerServeSessionCleanup(session) {
+    (0, lifecycle_1.registerLifecycleCleanup)(() => {
+        (0, session_store_1.cleanupSession)(session.sessionPath, session.record.links);
+    });
+}
+function reportLinkCreation(runtime, linkResult) {
+    const createdLinks = linkResult.created;
+    log.info(`linked ${createdLinks.length} command${createdLinks.length > 1 ? 's' : ''} into ${runtime.options.binDir}`);
+    for (const link of createdLinks) {
+        log.info(`${link.name} -> ${link.target}`);
+    }
+    for (const skippedLink of linkResult.skipped) {
+        log.warn(`skip "${skippedLink.name}": ${skippedLink.reason} (${skippedLink.linkPath})`);
+    }
+}
+function reportPathHint(binDirectory) {
+    if ((0, utils_1.pathContainsDir)(process.env.PATH, binDirectory)) {
+        return;
+    }
+    log.info(`add this to your shell config if needed:\nexport PATH="${binDirectory}:$PATH"`);
+}
+function waitUntilProcessExit() {
+    return new Promise(() => {
+        setInterval(() => undefined, 60_000);
+    });
+}
+async function run(options) {
+    const runtime = buildServeRuntime(options);
+    const linkResult = await createRuntimeLinks(runtime);
+    assertLinkCreationSucceeded(linkResult);
+    const session = persistServeSession(runtime, linkResult.created);
+    registerServeSessionCleanup(session);
+    reportLinkCreation(runtime, linkResult);
+    reportPathHint(runtime.options.binDir);
+    log.info('running. press Ctrl+C to cleanup links.');
+    await waitUntilProcessExit();
+}
+function serveCommand(inlineOptions) {
+    const currentWorkingDirectory = process.cwd();
+    const options = (0, options_1.resolveOptions)(currentWorkingDirectory, schema_1.serveInlineOptionsSchema, inlineOptions);
+    return run(options);
+}

package/dist/lib/bin-targets.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertValidBinTargets = assertValidBinTargets;
+exports.prepareBinTargets = prepareBinTargets;
 const node_fs_1 = __importDefault(require("node:fs"));
 function isExecutable(filePath) {
     if (process.platform === 'win32') {
@@ -17,6 +17,23 @@ function isExecutable(filePath) {
         return false;
     }
 }
+function ensureExecutable(filePath, currentMode) {
+    if (process.platform === 'win32' || isExecutable(filePath)) {
+        return undefined;
+    }
+    const executeBits = (currentMode & 0o444) >> 2;
+    const nextMode = (currentMode | executeBits) & 0o777;
+    try {
+        node_fs_1.default.chmodSync(filePath, nextMode);
+    }
+    catch (error) {
+        return `target permissions could not be updated (${String(error)})`;
+    }
+    if (isExecutable(filePath)) {
+        return undefined;
+    }
+    return 'target permissions could not be updated';
+}
 function inspectBinTarget(name, target) {
     if (!node_fs_1.default.existsSync(target)) {
         return {
@@ -43,11 +60,12 @@ function inspectBinTarget(name, target) {
             reason: 'target is a directory',
         };
     }
-    if (!isExecutable(target)) {
+    const executableIssue = ensureExecutable(target, stats.mode);
+    if (executableIssue) {
         return {
             name,
             target,
-            reason: 'target is not executable',
+            reason: executableIssue,
             hint: `run: chmod +x ${target}`,
         };
     }
@@ -61,7 +79,7 @@ function formatIssues(issues) {
     })
         .join('\n');
 }
-function assertValidBinTargets(bin) {
+function prepareBinTargets(bin) {
     const issues = [];
     for (const [name, target] of Object.entries(bin)) {
         const issue = inspectBinTarget(name, target);
@@ -75,6 +93,6 @@ function assertValidBinTargets(bin) {
     throw new Error([
         'invalid bin targets:',
         formatIssues(issues),
-        'fix bin paths/permissions in package.json, symlx.config.json, or inline --bin and run again.',
+        'fix bin paths or file permissions in package.json, symlx.config.json, or inline --bin and run again.',
     ].join('\n'));
 }

package/dist/lib/constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT_FALLBACK_WARNING = void 0;
+exports.PROMPT_FALLBACK_WARNING = 'prompt collision mode requested but session is non-interactive; falling back to skip (use --collision overwrite|fail to avoid skips)';

package/dist/lib/link-manager.js

@@ -4,8 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLinks = createLinks;
+exports.assertLinksCreated = assertLinksCreated;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const prompts_1 = require("../ui/prompts");
 // lstat wrapper that treats missing files as "not found" but rethrows real IO errors.
 function tryLstat(filePath) {
     try {
@@ -69,13 +71,15 @@ function toConflict(name, linkPath, target, node) {
 }
 // Creates symlinks for all project bins according to the selected collision strategy.
 // This function is pure with regard to policy: caller decides interactive vs non-interactive.
-async function createLinks(params) {
-    const { bins, binDir, policy, collisionResolver } = params;
+async function createLinks(bins, binDir, collisionOption) {
     const created = [];
     const skipped = [];
-    for (const [name, target] of bins.entries()) {
+    // 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
         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.
@@ -88,25 +92,21 @@ async function createLinks(params) {
                 });
                 continue;
             }
-            let decision;
-            if (policy === 'skip') {
-                decision = 'skip';
-            }
-            else if (policy === 'overwrite') {
-                decision = 'overwrite';
-            }
-            else if (policy === 'fail') {
+            if (collisionOption === 'fail') {
                 throw new Error(`command "${name}" conflicts at ${linkPath}: ${conflict.reason}`);
             }
-            else {
-                decision = collisionResolver
-                    ? await collisionResolver(conflict)
-                    : 'skip';
+            let collisionDecision;
+            if (collisionOption === 'prompt') {
+                collisionDecision = await (0, prompts_1.promptCollisionResolver)(conflict);
+                if (collisionDecision === 'abort') {
+                    throw new Error(`aborted on collision for command "${name}"`);
+                }
             }
-            if (decision === 'abort') {
-                throw new Error(`aborted on collision for command "${name}"`);
+            else {
+                // After here, resulting decision can only either be 'skip' or 'overwrite'
+                collisionDecision = collisionOption;
             }
-            if (decision === 'skip') {
+            if (collisionDecision === 'skip') {
                 skipped.push({ name, linkPath, reason: conflict.reason });
                 continue;
             }
@@ -117,3 +117,22 @@ async function createLinks(params) {
     }
     return { created, skipped };
 }
+function assertLinksCreated(linkResult) {
+    if (linkResult.created.length > 0) {
+        return;
+    }
+    if (linkResult.skipped.length === 0) {
+        throw new Error('no links were created');
+    }
+    const details = linkResult.skipped
+        .slice(0, 5)
+        .map((skip) => `- ${skip.name}: ${skip.reason}`)
+        .join('\n');
+    const remainingCount = linkResult.skipped.length - 5;
+    const remaining = remainingCount > 0 ? `\n- ...and ${remainingCount} more` : '';
+    throw new Error([
+        'no links were created because all candidate commands were skipped.',
+        details,
+        `${remaining}\nuse --collision overwrite or --collision fail for stricter behavior.`,
+    ].join('\n'));
+}

package/dist/lib/link-result.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertLinksCreated = assertLinksCreated;
+function assertLinksCreated(linkResult) {
+    if (linkResult.created.length > 0) {
+        return;
+    }
+    if (linkResult.skipped.length === 0) {
+        throw new Error('no links were created');
+    }
+    const details = linkResult.skipped
+        .slice(0, 5)
+        .map((skip) => `- ${skip.name}: ${skip.reason}`)
+        .join('\n');
+    const remainingCount = linkResult.skipped.length - 5;
+    const remaining = remainingCount > 0 ? `\n- ...and ${remainingCount} more` : '';
+    throw new Error([
+        'no links were created because all candidate commands were skipped.',
+        details,
+        `${remaining}\nuse --collision overwrite or --collision fail for stricter behavior.`,
+    ].join('\n'));
+}

package/dist/lib/options.js

@@ -1,11 +1,46 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveOptions = resolveOptions;
+exports.resolveInternalCollisionOption = resolveInternalCollisionOption;
 const path_1 = __importDefault(require("path"));
 const node_os_1 = __importDefault(require("node:os"));
+const log = __importStar(require("../ui/logger"));
 const utils_1 = require("./utils");
 const validator_1 = require("./validator");
 const DEFAULT_OPTIONS = {
@@ -44,6 +79,9 @@ function withCwdPrefixedBin(cwd, bin) {
         path_1.default.resolve(cwd, target),
     ]));
 }
+function isInteractiveSession() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
 // Function to aggregate all options from different sources in order or priority
 function resolveOptions(cwd, inlineOptionsSchema, inlineOptions) {
     const packageJSONLoadResult = (0, utils_1.loadPackageJSONOptions)(cwd);
@@ -52,14 +90,7 @@ function resolveOptions(cwd, inlineOptionsSchema, inlineOptions) {
         ...packageJSONLoadResult.issues,
         ...validatedPackageJSONOptions.issues,
     ];
-    const fatalPackageIssue = packageJSONIssues.find((issue) => issue.startsWith('invalid package.json'));
-    if (fatalPackageIssue) {
-        throw new Error(fatalPackageIssue);
-    }
     const configFileLoadResult = (0, utils_1.loadConfigFileOptions)(cwd);
-    if (configFileLoadResult.issue) {
-        throw new Error(configFileLoadResult.issue);
-    }
     const validatedConfigFileOptions = (0, validator_1.validateConfigFileOptions)(configFileLoadResult.options);
     const validatedInlineOptions = (0, validator_1.validateInlineOptions)(inlineOptionsSchema, inlineOptions);
     const inlineBin = validatedInlineOptions
@@ -76,8 +107,16 @@ function resolveOptions(cwd, inlineOptionsSchema, inlineOptions) {
         bin: withCwdPrefixedBin(cwd, resolvedBin),
     };
     if (Object.keys(finalOptions.bin).length > 0) {
+        if (finalOptions.binResolutionStrategy === 'merge' &&
+            packageJSONIssues.length > 0) {
+            log.warn([
+                'bin resolution strategy is merge, but could not resolve bin from package.json:',
+                ...packageJSONIssues,
+            ].join('\n'));
+        }
         return finalOptions;
     }
+    // only throw package.json error if no bin was resolved
     const primaryIssue = packageJSONIssues[0];
     if (primaryIssue) {
         throw new Error(primaryIssue);
@@ -90,3 +129,12 @@ function resolveOptions(cwd, inlineOptionsSchema, inlineOptions) {
         '3) inline CLI -> symlx serve --bin my-cli=./cli.js',
     ].join('\n'));
 }
+function resolveInternalCollisionOption(collisionOptions, nonInteractiveOptions) {
+    if (collisionOptions !== 'prompt') {
+        return collisionOptions;
+    }
+    if (nonInteractiveOptions || !isInteractiveSession()) {
+        return 'skip';
+    }
+    return 'prompt';
+}

package/dist/lib/schema.js

@@ -56,6 +56,7 @@ const binEntriesToRecordSchema = zod_1.z
     const [name, target] = entry.split('=', 2);
     return [name, target];
 })));
+const collisionOptionEnum = zod_1.z.enum(['prompt', 'skip', 'fail', 'overwrite']);
 // -------------------------------------------
 // package.json Schema: Just bin for now
 // -------------------------------------------
@@ -71,10 +72,7 @@ const configFileOptionsSchema = zod_1.z.object({
         .string()
         .regex(/(^|[\\/])\.[^\\/]+([\\/]|$)/, 'binDir must include a dotted folder segment')
         .optional(),
-    collision: zod_1.z
-        .enum(['prompt', 'skip', 'fail', 'overwrite'])
-        .optional()
-        .catch(() => {
+    collision: collisionOptionEnum.optional().catch(() => {
         log.warn('invalid "collision" value in config file; using default.');
         return undefined;
     }),

package/dist/lib/serve-runtime.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startServeSession = startServeSession;
+const node_path_1 = __importDefault(require("node:path"));
+function resolveCollisionSummary(options, dependencies) {
+    if (options.collision !== 'prompt') {
+        return {
+            requested: options.collision,
+            effective: options.collision,
+        };
+    }
+    const shouldFallbackToSkip = options.nonInteractive || !dependencies.isInteractiveSession();
+    if (!shouldFallbackToSkip) {
+        return {
+            requested: options.collision,
+            effective: 'prompt',
+        };
+    }
+    return {
+        requested: options.collision,
+        effective: 'skip',
+        warning: 'prompt collision mode requested but session is non-interactive; falling back to skip (use --collision overwrite|fail to avoid skips)',
+    };
+}
+function formatSkippedLinks(skippedLinks) {
+    const visibleSkippedLinks = skippedLinks.slice(0, 5);
+    const details = visibleSkippedLinks
+        .map((skip) => `- ${skip.name}: ${skip.reason}`)
+        .join('\n');
+    const remainingCount = skippedLinks.length - visibleSkippedLinks.length;
+    const remaining = remainingCount > 0 ? `\n- ...and ${remainingCount} more` : '';
+    return `${details}${remaining}`;
+}
+function assertLinksCreated(linkResult) {
+    if (linkResult.created.length > 0) {
+        return;
+    }
+    if (linkResult.skipped.length === 0) {
+        throw new Error('no links were created');
+    }
+    throw new Error([
+        'no links were created because all candidate commands were skipped.',
+        formatSkippedLinks(linkResult.skipped),
+        'use --collision overwrite or --collision fail for stricter behavior.',
+    ].join('\n'));
+}
+async function startServeSession(params) {
+    const { options, dependencies, promptCollisionResolver } = params;
+    const currentWorkingDirectory = dependencies.resolveWorkingDirectory();
+    const homeDirectory = dependencies.resolveHomeDirectory();
+    const sessionDirectory = node_path_1.default.join(homeDirectory, '.symlx', 'sessions');
+    const collision = resolveCollisionSummary(options, dependencies);
+    dependencies.cleanupStaleSessions(sessionDirectory);
+    dependencies.ensureDirectories(options.binDir, sessionDirectory);
+    dependencies.assertValidBinTargets(options.bin);
+    const linkResult = await dependencies.createLinks({
+        bins: options.bin,
+        binDir: options.binDir,
+        policy: collision.effective,
+        collisionResolver: collision.effective === 'prompt' ? promptCollisionResolver : undefined,
+    });
+    assertLinksCreated(linkResult);
+    const sessionPath = dependencies.createSessionFilePath(sessionDirectory);
+    const sessionRecord = {
+        pid: dependencies.resolveProcessId(),
+        cwd: currentWorkingDirectory,
+        createdAt: dependencies.resolveTimestamp(),
+        links: linkResult.created,
+    };
+    dependencies.persistSession(sessionPath, sessionRecord);
+    dependencies.registerLifecycleCleanup(() => {
+        dependencies.cleanupSession(sessionPath, sessionRecord.links);
+    });
+    return {
+        collision,
+        waitUntilStopped: dependencies.waitUntilStopped,
+    };
+}

package/dist/lib/session-store.js

@@ -36,11 +36,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanupLinks = cleanupLinks;
 exports.ensureSymlxDirectories = ensureSymlxDirectories;
 exports.cleanupStaleSessions = cleanupStaleSessions;
+exports.generateSessionFilePath = generateSessionFilePath;
+exports.generateSessionRecord = generateSessionRecord;
 exports.persistSession = persistSession;
-exports.createSessionFilePath = createSessionFilePath;
-exports.cleanupSession = cleanupSession;
+exports.registerLifecycleSessionCleanup = registerLifecycleSessionCleanup;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const log = __importStar(require("../ui/logger"));
@@ -120,17 +122,54 @@ function cleanupStaleSessions(sessionDir) {
         log.info(`cleaned up ${cleanUpCount} expired session${cleanUpCount > 1 ? 's' : ''}`);
     }
 }
-// Persists currently linked commands so future runs can clean stale state.
-function persistSession(sessionPath, record) {
-    node_fs_1.default.writeFileSync(sessionPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
-}
 // Produces unique session file names to avoid collisions across concurrent runs.
-function createSessionFilePath(sessionDir) {
+function generateSessionFilePath(sessionDir) {
     const unique = `${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
     return node_path_1.default.join(sessionDir, `${unique}.json`);
 }
-// Cleanup for the active process/session.
-function cleanupSession(sessionPath, links) {
-    cleanupLinks(links);
-    (0, utils_1.deleteFile)(sessionPath);
+function generateSessionRecord(cwd, links) {
+    return {
+        pid: process.pid,
+        cwd,
+        createdAt: new Date().toISOString(),
+        links,
+    };
+}
+// Persists currently linked commands so future runs can clean stale state.
+function persistSession(sessionPath, record) {
+    node_fs_1.default.writeFileSync(sessionPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+}
+// Registers robust process-exit handling so linked commands are removed reliably.
+// Cleanup is idempotent and can be triggered by normal exit, signals, or fatal errors.
+function registerLifecycleSessionCleanup(sessionPath, links) {
+    let cleaned = false;
+    const runCleanup = () => {
+        if (cleaned) {
+            return;
+        }
+        cleaned = true;
+        cleanupLinks(links);
+        (0, utils_1.deleteFile)(sessionPath);
+    };
+    // Normal termination path.
+    process.on('exit', runCleanup);
+    const onSignal = () => {
+        runCleanup();
+        process.exit(0);
+    };
+    // Common interactive stop signals.
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    process.on('SIGHUP', onSignal);
+    // Fatal process events still attempt cleanup before exiting with failure.
+    process.on('uncaughtException', (error) => {
+        process.stderr.write(`[symlx] uncaught exception: ${String(error)}\n`);
+        runCleanup();
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        process.stderr.write(`[symlx] unhandled rejection: ${String(reason)}\n`);
+        runCleanup();
+        process.exit(1);
+    });
 }

package/dist/lib/utils.js

@@ -43,8 +43,9 @@ function loadConfigFileOptions(cwd) {
         return {};
     }
     const result = readJSONFileWithIssue(configPath, 'symlx.config.json');
+    // throw error if there were file reading issues
     if (result.issue) {
-        return { issue: result.issue };
+        throw new Error(result.issue);
     }
     return { options: result.data };
 }

package/dist/lib/validator.js

@@ -20,6 +20,8 @@ function validatePackageJSONOptions(input) {
     }
     return { ...result.data, issues: [] };
 }
+// it's better ux/dx to throw if there's an error in the config file
+// provided it's available than falling back to defaults and leaving the user guessing
 function validateConfigFileOptions(input, label = 'input') {
     const result = schema_1.configFileOptionsSchema.safeParse(input || {});
     if (!result.success) {

package/dist/options.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.binOption = exports.nonInteractiveOption = exports.binResolutionStrategyOption = exports.collisionOption = exports.binDirOption = void 0;
+function collectBinEntry(value, previous = []) {
+    previous.push(value);
+    return previous;
+}
+const binDirOption = [
+    '--bin-dir <dir>',
+    'target bin directory (default: ~/.symlx/bin)',
+];
+exports.binDirOption = binDirOption;
+const collisionOption = [
+    '--collision <policy>',
+    'collision mode: prompt|skip|fail|overwrite',
+    'prompt',
+];
+exports.collisionOption = collisionOption;
+const binResolutionStrategyOption = [
+    '--bin-resolution-strategy <strategy>',
+    'bin precedence strategy: replace|merge',
+    'replace',
+];
+exports.binResolutionStrategyOption = binResolutionStrategyOption;
+const nonInteractiveOption = [
+    '--non-interactive',
+    'disable interactive prompts',
+    false,
+];
+exports.nonInteractiveOption = nonInteractiveOption;
+const binOption = [
+    '--bin <name=path>',
+    'custom bin mapping (repeatable), e.g. --bin my-cli=dist/cli.js',
+    collectBinEntry,
+    [],
+];
+exports.binOption = binOption;

package/dist/ui/prompts.js

@@ -3,11 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.promptCollisionDecision = promptCollisionDecision;
+exports.promptCollisionResolver = promptCollisionResolver;
 const prompts_1 = __importDefault(require("prompts"));
 // Interactive collision resolver for --collision prompt.
 // Returning "abort" bubbles up as an error to stop the current serve run.
-async function promptCollisionDecision(conflict) {
+async function promptCollisionResolver(conflict) {
     const response = await (0, prompts_1.default)({
         type: 'select',
         name: 'decision',

package/dist/ui/serve-output.js

@@ -0,0 +1,55 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printLinkOutcome = printLinkOutcome;
+exports.printPathHintIfNeeded = printPathHintIfNeeded;
+const utils_1 = require("../lib/utils");
+const log = __importStar(require("./logger"));
+function printLinkOutcome(binDir, linkResult) {
+    const createdLinks = linkResult.created;
+    log.info(`linked ${createdLinks.length} command${createdLinks.length > 1 ? 's' : ''} into ${binDir}`);
+    for (const link of createdLinks) {
+        log.info(`${link.name} -> ${link.target}`);
+    }
+    for (const skip of linkResult.skipped) {
+        log.warn(`skip "${skip.name}": ${skip.reason} (${skip.linkPath})`);
+    }
+}
+function printPathHintIfNeeded(binDir, currentPath) {
+    if ((0, utils_1.pathContainsDir)(currentPath, binDir)) {
+        return;
+    }
+    log.info(`add this to your shell config if needed:\nexport PATH="${binDir}:$PATH"`);
+}

package/package.json

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