symlx 0.1.2 → 0.1.4

package/README.md

@@ -1,3 +1,270 @@
 # symlx
 
-tomorrow...
+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.
+
+## Why symlx
+
+During CLI development, running `node dist/cli.js` repeatedly is noisy.
+`npm link` has generally been buggy and slow to pick recent code changes.
+`symlx` gives you the real command experience (`my-cli --help`) without a global publish/install cycle.
+
+Core guarantees:
+
+- Links are session-scoped and cleaned on exit.
+- Collision behavior is explicit (`prompt`, `skip`, `fail`, `overwrite`).
+- Option resolution is deterministic.
+- PATH setup for `~/.symlx/bin` is automated on install (with opt-out).
+
+## Install
+
+```bash
+npx symlx serve
+# or
+npm i -g symlx
+```
+
+## Quick Start
+
+In a CLI project with:
+
+```json
+{
+  "name": "my-cli",
+  "bin": {
+    "my-cli": "./dist/cli.js"
+  }
+}
+```
+
+run:
+
+```bash
+symlx serve
+```
+
+Then use your CLI normally:
+
+```bash
+my-cli --help
+```
+
+Stop `symlx` with `Ctrl+C` to clean links.
+
+## Alias
+
+`symlx` can be clackful for power users, hence its alias: `cx`.
+
+Equivalent commands:
+
+```bash
+symlx serve
+cx serve
+```
+
+## Command Reference
+
+## `symlx serve`
+
+Links commands from resolved bin mappings and keeps the process alive until interrupted.
+
+### Options
+
+| Option                                 | Type                                  | Default        | Description                                                           |
+| -------------------------------------- | ------------------------------------- | -------------- | --------------------------------------------------------------------- |
+| `--bin-dir <dir>`                      | string                                | `~/.symlx/bin` | Target directory where command links are created.                     |
+| `--collision <policy>`                 | `prompt \| skip \| fail \| overwrite` | `prompt`       | What to do when a command name already exists in bin dir.             |
+| `--bin-resolution-strategy <strategy>` | `replace \| merge`                    | `replace`      | How to resolve `bin` across `package.json`, config, and inline flags. |
+| `--non-interactive`                    | boolean                               | `false`        | Disable prompts and force non-interactive behavior.                   |
+| `--bin <name=path>` (repeatable)       | string[]                              | `[]`           | Inline bin mapping (for quick overrides/ad-hoc runs).                 |
+
+Examples:
+
+```bash
+symlx serve --collision overwrite
+symlx serve --bin admin=dist/admin.js --bin worker=dist/worker.js
+symlx serve --bin-resolution-strategy merge
+```
+
+## Bin Resolution Model
+
+`symlx` resolves options from three user sources plus defaults:
+
+1. `package.json`
+2. `symlx.config.json`
+3. inline CLI flags
+
+Scalar fields (`collision`, `binDir`, `nonInteractive`, `binResolutionStrategy`) follow normal override order:
+
+`defaults -> package.json-derived -> config -> inline`
+
+`bin` uses strategy mode:
+
+- `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)
+
+## Supported Bin Sources
+
+## `package.json`
+
+`bin` supports both npm-compatible linking:
+
+```json
+{
+  "name": "my-cli",
+  "bin": "./dist/cli.js"
+}
+```
+
+```json
+{
+  "bin": {
+    "my-cli": "./dist/cli.js",
+    "my-admin": "./dist/admin.js"
+  }
+}
+```
+
+If `bin` is a string, `name` is required so command name can be inferred.
+
+## `symlx.config.json`
+
+```json
+{
+  "binDir": "~/.symlx/bin",
+  "collision": "prompt",
+  "nonInteractive": false,
+  "binResolutionStrategy": "replace",
+  "bin": {
+    "my-cli": "./dist/cli.js"
+  }
+}
+```
+
+Notes:
+
+- In case of invalid config values, `symlx` fallback to defaults (with warnings).
+- `binDir` is treated as critical and must pass validation.
+
+## Inline Flags
+
+```bash
+symlx serve --bin my-cli=dist/cli.js
+
+# multiple inline bins
+symlx serve \
+  --bin xin-ping=./cli.js \
+  --bin admin=./scripts/admin.js
+```
+
+`name` rules:
+
+- lowercase letters, digits, `-`
+- no spaces
+
+`path` rules:
+
+- must be relative (for example `dist/cli.js` or `./dist/cli.js`)
+- absolute paths are rejected
+
+## Collision Policies
+
+- `prompt`: ask per conflict (interactive TTY only)
+- `skip`: keep existing command, skip link
+- `fail`: stop on first conflict
+- `overwrite`: replace existing entry
+
+If `prompt` is requested in non-interactive mode, symlx falls back to `skip` and warns.
+
+## Install-Time PATH Setup
+
+On install, `symlx` updates shell profile PATH block
+
+Managed path:
+
+```bash
+$HOME/.symlx/bin
+```
+
+Opt out:
+
+```bash
+SYMLX_SKIP_PATH_SETUP=1 npm i -g symlx
+```
+
+To set a custome bin PATH:
+
+```bash
+symlx serve --bin-dir ~/.symlx/bin
+```
+
+## Runtime Safety Checks
+
+Before linking, symlx validates each resolved bin target:
+
+- file exists
+- target is not a directory
+- target is executable on unix-like systems
+
+Invalid targets fail early with actionable messages.
+
+## Exit Behavior
+
+- `Ctrl+C` (SIGINT), SIGTERM, SIGHUP, uncaught exception, and unhandled rejection trigger cleanup.
+- Session metadata is stored under `~/.symlx/sessions`.
+- Stale sessions leftover due to hard crashes are cleaned on startup.
+
+## Troubleshooting
+
+## "no bin entries found"
+
+Add a bin mapping in at least one place:
+
+- `package.json -> bin`
+- `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:
+
+```bash
+symlx serve --collision overwrite
+# or
+symlx serve --collision fail
+```
+
+## "package.json not found"
+
+Run in your project root, or pass bins inline/config.
+
+## Development
+
+```bash
+pnpm install
+pnpm run check
+pnpm run build
+pnpm run test
+```
+
+## Extending Commands (Contributor Contract)
+
+To add a new command while preserving set conventions:
+
+1. Define command surface in `src/cli.ts`.
+2. Keep orchestration in `src/commands/*`.
+3. Reuse `resolveOptions()` for deterministic source handling.
+4. Validate user-facing options with zod schemas in `src/lib/schema.ts`.
+5. Add behavior coverage in `test/*.test.ts`.
+6. Update this README command reference and examples.
+
+The goal is consistent behavior across all current and future commands.

package/dist/cli.js

@@ -35,38 +35,28 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const serve_1 = require("./commands/serve");
 const log = __importStar(require("./ui/logger"));
-// Accepted values for --collision.
-const ALLOWED_COLLISIONS = new Set(["prompt", "skip", "fail", "overwrite"]);
-// Converts raw CLI input into a validated union type used by the serve command.
-function parseCollisionPolicy(value) {
-    if (!ALLOWED_COLLISIONS.has(value)) {
-        throw new Error(`invalid collision policy "${value}". expected: prompt|skip|fail|overwrite`);
-    }
-    return value;
+const serve_1 = require("./commands/serve");
+function collectBinEntry(value, previous = []) {
+    previous.push(value);
+    return previous;
 }
 async function main() {
     // Commander orchestrates top-level commands/options and help output.
     const program = new commander_1.Command();
     program
-        .name("symlx")
-        .description("Temporary CLI bin linker with lifecycle cleanup")
+        .name('symlx')
+        .description('Temporary CLI bin linker with lifecycle cleanup')
         .showHelpAfterError();
     program
-        .command("serve")
-        .description("Link this project's package.json bins until symlx exits")
-        .option("--bin-dir <dir>", "target bin directory (default: ~/.symlx/bin)")
-        .option("--collision <policy>", "collision mode: prompt|skip|fail|overwrite", "prompt")
-        .option("--non-interactive", "disable interactive prompts", false)
-        .action(async (options) => {
-        // Delegate all runtime behavior to the command module.
-        await (0, serve_1.runServe)({
-            binDir: options.binDir,
-            collision: parseCollisionPolicy(options.collision),
-            nonInteractive: options.nonInteractive
-        });
-    });
+        .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, [])
+        .action(serve_1.serveCommand);
     await program.parseAsync(process.argv);
 }
 // Centralized fatal error boundary for command execution.

package/dist/commands/serve.js

@@ -32,74 +32,129 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runServe = runServe;
-const paths_1 = require("../core/paths");
-const link_manager_1 = require("../services/link-manager");
-const lifecycle_1 = require("../services/lifecycle");
-const package_bins_1 = require("../services/package-bins");
-const session_store_1 = require("../services/session-store");
-const collision_prompt_1 = require("../ui/collision-prompt");
+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);
 }
-// Main symlx behavior:
-// 1) resolve bins from package.json
-// 2) create links
-// 3) persist session
-// 4) keep process alive and cleanup on exit
-async function runServe(options) {
-    const cwd = process.cwd();
-    const paths = (0, paths_1.getSymlxPaths)(options.binDir);
-    // Prepare runtime directories and recover stale sessions from previous abnormal exits.
-    (0, session_store_1.cleanupStaleSessions)(paths.sessionDir);
-    (0, session_store_1.ensureSymlxDirectories)(paths.binDir, paths.sessionDir);
-    const bins = (0, package_bins_1.readBins)(cwd);
-    // Prompt policy only works when we can interact with a TTY.
-    const usePrompts = options.collision === 'prompt' &&
-        !options.nonInteractive &&
-        isInteractiveSession();
-    if (options.collision === 'prompt' && !usePrompts) {
-        log.warn('prompt collision mode requested but session is non-interactive; falling back to skip');
+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' };
     }
-    // Link creation returns both successful links and explicit skips.
-    const linkResult = await (0, link_manager_1.createLinks)({
-        bins,
-        binDir: paths.binDir,
-        policy: options.collision,
-        collisionResolver: usePrompts ? collision_prompt_1.promptCollisionDecision : undefined,
+    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) {
-        throw new Error('no links were created');
+        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'));
     }
-    // Session file is the source of truth for cleaning this exact run's links.
-    const sessionPath = (0, session_store_1.createSessionFilePath)(paths.sessionDir);
+}
+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: linkResult.created,
+        links,
     };
     (0, session_store_1.persistSession)(sessionPath, sessionRecord);
-    // Always cleanup linked commands when this process leaves.
+    return { sessionPath, sessionRecord };
+}
+function registerSessionCleanup(sessionPath, links) {
     (0, lifecycle_1.registerLifecycleCleanup)(() => {
-        (0, session_store_1.cleanupSession)(sessionPath, sessionRecord.links);
+        (0, session_store_1.cleanupSession)(sessionPath, links);
     });
-    log.info(`linked ${linkResult.created.length} command(s) into ${paths.binDir}`);
-    for (const link of linkResult.created) {
+}
+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})`);
     }
-    if (!(0, paths_1.pathContainsDir)(process.env.PATH, paths.binDir)) {
-        log.info(`add this to your shell config if needed:\nexport PATH="${paths.binDir}:$PATH"`);
+}
+function printPathHintIfNeeded(binDir) {
+    if ((0, utils_1.pathContainsDir)(process.env.PATH, binDir)) {
+        return;
     }
-    log.info('running. press Ctrl+C to cleanup links.');
-    // Keep process alive indefinitely; lifecycle handlers handle termination and cleanup.
-    await new Promise(() => {
+    log.info(`add this to your shell config if needed:\nexport PATH="${binDir}:$PATH"`);
+}
+function waitIndefinitely() {
+    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) {
+    const cwd = process.cwd();
+    const options = (0, options_1.resolveOptions)(cwd, schema_1.serveInlineOptionsSchema, inlineOptions);
+    return run(options);
+}

package/dist/lib/bin-targets.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidBinTargets = assertValidBinTargets;
+const node_fs_1 = __importDefault(require("node:fs"));
+function isExecutable(filePath) {
+    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 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',
+        };
+    }
+    if (!isExecutable(target)) {
+        return {
+            name,
+            target,
+            reason: 'target is not executable',
+            hint: `run: chmod +x ${target}`,
+        };
+    }
+    return undefined;
+}
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const hint = issue.hint ? ` (${issue.hint})` : '';
+        return `- ${issue.name} -> ${issue.target}: ${issue.reason}${hint}`;
+    })
+        .join('\n');
+}
+function assertValidBinTargets(bin) {
+    const issues = [];
+    for (const [name, target] of Object.entries(bin)) {
+        const issue = inspectBinTarget(name, target);
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    if (issues.length === 0) {
+        return;
+    }
+    throw new Error([
+        'invalid bin targets:',
+        formatIssues(issues),
+        'fix bin paths/permissions in package.json, symlx.config.json, or inline --bin and run again.',
+    ].join('\n'));
+}

package/dist/{services → lib}/link-manager.js

@@ -13,7 +13,7 @@ function tryLstat(filePath) {
     }
     catch (error) {
         const code = error.code;
-        if (code === "ENOENT") {
+        if (code === 'ENOENT') {
             return undefined;
         }
         throw error;
@@ -54,17 +54,17 @@ function toConflict(name, linkPath, target, node) {
             target,
             reason: node.existingTarget
                 ? `already linked to ${node.existingTarget}`
-                : "already exists as symlink",
+                : 'already exists as symlink',
             existingTarget: node.existingTarget,
-            isSymlink: true
+            isSymlink: true,
         };
     }
     return {
         name,
         linkPath,
         target,
-        reason: "already exists as a file",
-        isSymlink: false
+        reason: 'already exists as a file',
+        isSymlink: false,
     };
 }
 // Creates symlinks for all project bins according to the selected collision strategy.
@@ -79,27 +79,34 @@ async function createLinks(params) {
         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)) {
-                skipped.push({ name, linkPath, reason: "already linked to requested target" });
+            if (conflict.existingTarget &&
+                node_path_1.default.resolve(conflict.existingTarget) === node_path_1.default.resolve(target)) {
+                skipped.push({
+                    name,
+                    linkPath,
+                    reason: 'already linked to requested target',
+                });
                 continue;
             }
             let decision;
-            if (policy === "skip") {
-                decision = "skip";
+            if (policy === 'skip') {
+                decision = 'skip';
             }
-            else if (policy === "overwrite") {
-                decision = "overwrite";
+            else if (policy === 'overwrite') {
+                decision = 'overwrite';
             }
-            else if (policy === "fail") {
+            else if (policy === 'fail') {
                 throw new Error(`command "${name}" conflicts at ${linkPath}: ${conflict.reason}`);
             }
             else {
-                decision = collisionResolver ? await collisionResolver(conflict) : "skip";
+                decision = collisionResolver
+                    ? await collisionResolver(conflict)
+                    : 'skip';
             }
-            if (decision === "abort") {
+            if (decision === 'abort') {
                 throw new Error(`aborted on collision for command "${name}"`);
             }
-            if (decision === "skip") {
+            if (decision === 'skip') {
                 skipped.push({ name, linkPath, reason: conflict.reason });
                 continue;
             }