symlx 0.1.0 → 0.1.2

package/README.md

@@ -1,63 +1,3 @@
-# zlx
+# symlx
 
-Temporary CLI bin linker for local development.
-
-## What it does
-
-`zlx serve` reads the current project's `package.json` `bin` entries and symlinks them into:
-
-`~/.zlx/bin`
-
-While `zlx serve` is running, those commands can be used from anywhere (if `~/.zlx/bin` is on your `PATH`).
-
-When the process exits, it removes only the links it created.
-
-## Command framework and structure
-
-`zlx` uses:
-
-- `commander` for command orchestration and typed options.
-- `prompts` for interactive/TUI collision handling.
-
-Project layout:
-
-- `src/commands` command handlers
-- `src/services` bin/session/lifecycle services
-- `src/core` shared types/path helpers
-- `src/ui` terminal UI prompts/logging
-
-## Usage
-
-```bash
-npx zlx serve
-```
-
-or if installed globally:
-
-```bash
-zlx serve
-```
-
-### Serve options
-
-```bash
-zlx serve --collision prompt
-zlx serve --collision skip
-zlx serve --collision fail
-zlx serve --collision overwrite
-zlx serve --non-interactive
-zlx serve --bin-dir /custom/bin
-```
-
-If your shell does not already include `~/.zlx/bin`, add:
-
-```bash
-export PATH="$HOME/.zlx/bin:$PATH"
-```
-
-## Notes
-
-- Prompt mode lets you choose overwrite/skip/abort when a command name already exists.
-- In non-interactive sessions, prompt mode falls back to skip.
-- Stale links from dead sessions are cleaned on the next startup.
-- `kill -9` cannot cleanup instantly, but stale cleanup runs next time.
+tomorrow...

package/dist/cli.js

@@ -50,13 +50,13 @@ async function main() {
     // Commander orchestrates top-level commands/options and help output.
     const program = new commander_1.Command();
     program
-        .name("zlx")
+        .name("symlx")
         .description("Temporary CLI bin linker with lifecycle cleanup")
         .showHelpAfterError();
     program
         .command("serve")
-        .description("Link this project's package.json bins until zlx exits")
-        .option("--bin-dir <dir>", "target bin directory (default: ~/.zlx/bin)")
+        .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) => {

package/dist/commands/serve.js

@@ -45,32 +45,34 @@ const log = __importStar(require("../ui/logger"));
 function isInteractiveSession() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
-// Main zlx behavior:
+// 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.getZlxPaths)(options.binDir);
+    const paths = (0, paths_1.getSymlxPaths)(options.binDir);
     // Prepare runtime directories and recover stale sessions from previous abnormal exits.
-    (0, session_store_1.ensureZlxDirectories)(paths.binDir, paths.sessionDir);
     (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");
+    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');
     }
     // 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
+        collisionResolver: usePrompts ? collision_prompt_1.promptCollisionDecision : undefined,
     });
     if (linkResult.created.length === 0) {
-        throw new Error("no links were created");
+        throw new Error('no links were created');
     }
     // Session file is the source of truth for cleaning this exact run's links.
     const sessionPath = (0, session_store_1.createSessionFilePath)(paths.sessionDir);
@@ -78,7 +80,7 @@ async function runServe(options) {
         pid: process.pid,
         cwd,
         createdAt: new Date().toISOString(),
-        links: linkResult.created
+        links: linkResult.created,
     };
     (0, session_store_1.persistSession)(sessionPath, sessionRecord);
     // Always cleanup linked commands when this process leaves.
@@ -95,7 +97,7 @@ async function runServe(options) {
     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"`);
     }
-    log.info("running. press Ctrl+C to cleanup links.");
+    log.info('running. press Ctrl+C to cleanup links.');
     // Keep process alive indefinitely; lifecycle handlers handle termination and cleanup.
     await new Promise(() => {
         setInterval(() => undefined, 60_000);

package/dist/core/paths.js

@@ -3,19 +3,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getZlxPaths = getZlxPaths;
+exports.getSymlxPaths = getSymlxPaths;
 exports.pathContainsDir = pathContainsDir;
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 // Central place for runtime paths so every command/service resolves locations consistently.
-function getZlxPaths(customBinDir) {
-    // zlx keeps mutable runtime state under the user's home directory.
-    const rootDir = node_path_1.default.join(node_os_1.default.homedir(), ".zlx");
+function getSymlxPaths(customBinDir) {
+    // symlx keeps mutable runtime state under the user's home directory.
+    const rootSymlxDir = node_path_1.default.join(node_os_1.default.homedir(), '.symlx');
     // Commands are linked here unless the caller overrides with --bin-dir.
-    const binDir = customBinDir ? node_path_1.default.resolve(customBinDir) : node_path_1.default.join(rootDir, "bin");
+    const binDir = customBinDir
+        ? node_path_1.default.resolve(customBinDir)
+        : node_path_1.default.join(rootSymlxDir, 'bin');
     // Session files live separately from bins and are used for stale cleanup.
-    const sessionDir = node_path_1.default.join(rootDir, "sessions");
-    return { rootDir, binDir, sessionDir };
+    const sessionDir = node_path_1.default.join(rootSymlxDir, 'sessions');
+    return { binDir, sessionDir };
 }
 // Checks if PATH already contains a directory so we can avoid noisy setup hints.
 function pathContainsDir(currentPath, targetDir) {
@@ -23,6 +25,8 @@ function pathContainsDir(currentPath, targetDir) {
         return false;
     }
     const resolvedTarget = node_path_1.default.resolve(targetDir);
-    const parts = currentPath.split(node_path_1.default.delimiter).map((item) => node_path_1.default.resolve(item));
+    const parts = currentPath
+        .split(node_path_1.default.delimiter)
+        .map((item) => node_path_1.default.resolve(item));
     return parts.includes(resolvedTarget);
 }

package/dist/services/lifecycle.js

@@ -24,12 +24,12 @@ function registerLifecycleCleanup(cleanup) {
     process.on("SIGHUP", onSignal);
     // Fatal process events still attempt cleanup before exiting with failure.
     process.on("uncaughtException", (error) => {
-        process.stderr.write(`[zlx] uncaught exception: ${String(error)}\n`);
+        process.stderr.write(`[symlx] uncaught exception: ${String(error)}\n`);
         runCleanup();
         process.exit(1);
     });
     process.on("unhandledRejection", (reason) => {
-        process.stderr.write(`[zlx] unhandled rejection: ${String(reason)}\n`);
+        process.stderr.write(`[symlx] unhandled rejection: ${String(reason)}\n`);
         runCleanup();
         process.exit(1);
     });

package/dist/services/session-store.js

@@ -3,34 +3,33 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureZlxDirectories = ensureZlxDirectories;
+exports.ensureSymlxDirectories = ensureSymlxDirectories;
 exports.cleanupStaleSessions = cleanupStaleSessions;
 exports.persistSession = persistSession;
 exports.createSessionFilePath = createSessionFilePath;
 exports.cleanupSession = cleanupSession;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-// Lightweight JSON reader used for session metadata files.
-function readJsonFile(filePath) {
-    const raw = node_fs_1.default.readFileSync(filePath, "utf8");
-    return JSON.parse(raw);
-}
 // Checks whether a PID from a previous session is still alive.
 function isProcessAlive(pid) {
+    // PIDs are always positive integer typically less the 2^15
     if (!Number.isInteger(pid) || pid <= 0) {
         return false;
     }
     try {
+        // Check on the process without killing it (signal 0)
         process.kill(pid, 0);
         return true;
     }
     catch (error) {
         const code = error.code;
-        return code !== "ESRCH";
+        // If the error code is not ESRCH, then it means the process does not exist
+        // If it's EPERM, then it's running, you simply don't have permission to signal it (fair enough)
+        return code !== 'ESRCH';
     }
 }
 // Session files are best-effort state; deletion failure should not fail the command.
-function deleteSessionFile(filePath) {
+function deleteFile(filePath) {
     try {
         node_fs_1.default.unlinkSync(filePath);
     }
@@ -39,9 +38,10 @@ function deleteSessionFile(filePath) {
     }
 }
 // Invalid/corrupted session files are ignored and later removed.
-function loadSession(filePath) {
+function loadSessionFileJSON(filePath) {
     try {
-        return readJsonFile(filePath);
+        const raw = node_fs_1.default.readFileSync(filePath, 'utf8');
+        return JSON.parse(raw);
     }
     catch {
         return undefined;
@@ -67,35 +67,41 @@ function cleanupLinks(links) {
         }
     }
 }
+// -----------------------------------------------------------
 // Ensures runtime directories exist before linking/saving sessions.
-function ensureZlxDirectories(binDir, sessionDir) {
+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.
 function cleanupStaleSessions(sessionDir) {
+    // If the directory does not exist, return early
     if (!node_fs_1.default.existsSync(sessionDir)) {
         return;
     }
+    // Loop through the files within the session
     for (const entry of node_fs_1.default.readdirSync(sessionDir)) {
-        if (!entry.endsWith(".json")) {
+        const filePath = node_path_1.default.join(sessionDir, entry);
+        // Delete any files that are not .json, session files can only be JSON
+        if (!entry.endsWith('.json')) {
+            deleteFile(filePath);
             continue;
         }
-        const filePath = node_path_1.default.join(sessionDir, entry);
-        const record = loadSession(filePath);
+        // If the expected file structure has been corrupted, delete the file
+        const record = loadSessionFileJSON(filePath);
         if (!record) {
-            deleteSessionFile(filePath);
+            deleteFile(filePath);
             continue;
         }
         if (!isProcessAlive(record.pid)) {
             cleanupLinks(record.links);
-            deleteSessionFile(filePath);
+            deleteFile(filePath);
         }
     }
 }
 // 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");
+    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) {
@@ -105,5 +111,5 @@ function createSessionFilePath(sessionDir) {
 // Cleanup for the active process/session.
 function cleanupSession(sessionPath, links) {
     cleanupLinks(links);
-    deleteSessionFile(sessionPath);
+    deleteFile(sessionPath);
 }

package/dist/ui/logger.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.info = info;
 exports.warn = warn;
 exports.error = error;
-const PREFIX = "[zlx]";
+const PREFIX = "[symlx]";
 // Thin logging wrappers keep formatting centralized and easy to swap later.
 function info(message) {
     process.stdout.write(`${PREFIX} ${message}\n`);

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "symlx",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Temporary local CLI bin linker",
   "license": "MIT",
   "bin": {
-    "symlx": "dist/cli.js"
+    "symlx": "dist/cli.js",
+    "cx": "dist/cli.js"
   },
   "files": [
     "dist",