symlx 0.1.3 → 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

@@ -50,11 +50,12 @@ async function main() {
         .showHelpAfterError();
     program
         .command('serve')
-        .description("Link this project's package.json bins until symlx exits")
+        .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=./cli.js', collectBinEntry, [])
+        .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);
 }

package/dist/commands/serve.js

@@ -32,81 +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.serveCommand = serveCommand;
-const paths_1 = require("../lib/paths");
-const link_manager_1 = require("../services/link-manager");
-const lifecycle_1 = require("../services/lifecycle");
-// @ts-ignore
-const package_bins_1 = require("../services/package-bins");
-const session_store_1 = require("../services/session-store");
-const collision_prompt_1 = require("../ui/collision-prompt");
+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 run(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 };
     }
-    // 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,
+    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) {
-        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 options = (0, options_1.resolveOptions)(schema_1.serveInlineOptionsSchema, 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/lib/options.js

@@ -7,40 +7,86 @@ exports.resolveOptions = resolveOptions;
 const path_1 = __importDefault(require("path"));
 const node_os_1 = __importDefault(require("node:os"));
 const utils_1 = require("./utils");
-const validate_1 = require("./validate");
-const package_bins_1 = require("../services/package-bins");
-const defaultOptions = {
+const validator_1 = require("./validator");
+const DEFAULT_OPTIONS = {
     collision: 'prompt',
     nonInteractive: false,
     binDir: path_1.default.join(node_os_1.default.homedir(), '.symlx', 'bin'),
     bin: {},
+    binResolutionStrategy: 'replace',
 };
+function hasBinEntries(bin) {
+    return Boolean(bin && Object.keys(bin).length > 0);
+}
+function computeResolvedBin(inlineBin, configFileBin, packageJSONBin, binResolutionStrategy) {
+    // Aggregates bin from all sources:
+    // inline + config + package.json + default
+    if (binResolutionStrategy === 'merge') {
+        return {
+            ...(packageJSONBin ?? {}),
+            ...(configFileBin ?? {}),
+            ...(inlineBin ?? {}),
+        };
+    }
+    // Bin source precedence is value-aware:
+    // inline (if non-empty) -> config (if non-empty) -> package.json (if non-empty) -> default.
+    return hasBinEntries(inlineBin)
+        ? inlineBin
+        : hasBinEntries(configFileBin)
+            ? configFileBin
+            : hasBinEntries(packageJSONBin)
+                ? packageJSONBin
+                : DEFAULT_OPTIONS.bin;
+}
+function withCwdPrefixedBin(cwd, bin) {
+    return Object.fromEntries(Object.entries(bin).map(([name, target]) => [
+        name,
+        path_1.default.resolve(cwd, target),
+    ]));
+}
 // Function to aggregate all options from different sources in order or priority
-function resolveOptions(inlineOptionsSchema, inlineOptions) {
-    // Load the bin from package.json
-    const packageJSONOptions = (0, package_bins_1.loadPackageJSONOptions)(process.cwd());
-    // Load and validate the options from the config file,
-    // silently overriding invalid non-critical values with defaults or inline based on order of priority
-    const configFileOptions = (0, utils_1.loadConfigFileOptions)();
-    const validatedConfigFileOptions = (0, validate_1.validateConfigFileOptions)(configFileOptions);
-    // Validate the CLI inline options if available
-    const validatedInlineOptions = (0, validate_1.validateInlineOptions)(inlineOptionsSchema, inlineOptions);
-    // Default options first
-    // -> Config file options override defaults
-    // -> CLI inline options overrides config file options
-    const finalOptiions = {
-        ...defaultOptions,
+function resolveOptions(cwd, inlineOptionsSchema, inlineOptions) {
+    const packageJSONLoadResult = (0, utils_1.loadPackageJSONOptions)(cwd);
+    const validatedPackageJSONOptions = (0, validator_1.validatePackageJSONOptions)(packageJSONLoadResult);
+    const packageJSONIssues = [
+        ...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
+        .bin;
+    const mergedOptions = {
+        ...DEFAULT_OPTIONS,
+        ...(validatedPackageJSONOptions ?? {}),
         ...(validatedConfigFileOptions ?? {}),
         ...(validatedInlineOptions ?? {}),
     };
-    if (!Object.entries(finalOptiions.bin).length) {
-        throw new Error([
-            'no bin entries found. add at least one bin in any of these places:',
-            '1) package.json -> "bin": { "my-cli": "./cli.js" }',
-            '2) symlx.config.json -> "bin": { "my-cli": "./cli.js" }',
-            '3) inline CLI -> symlx serve --bin my-cli=./cli.js',
-            '4) if package.json "bin" is a string, set a valid package.json "name" (used to infer the bin name).',
-        ].join('\n'));
+    const resolvedBin = computeResolvedBin(inlineBin, validatedConfigFileOptions.bin, validatedPackageJSONOptions.bin, mergedOptions.binResolutionStrategy);
+    const finalOptions = {
+        ...mergedOptions,
+        bin: withCwdPrefixedBin(cwd, resolvedBin),
+    };
+    if (Object.keys(finalOptions.bin).length > 0) {
+        return finalOptions;
+    }
+    const primaryIssue = packageJSONIssues[0];
+    if (primaryIssue) {
+        throw new Error(primaryIssue);
     }
-    return finalOptiions;
+    throw new Error([
+        'no bin entries found.',
+        'add at least one command in one of these places:',
+        '1) package.json -> "bin": { "my-cli": "./cli.js" }',
+        '2) symlx.config.json -> "bin": { "my-cli": "./cli.js" }',
+        '3) inline CLI -> symlx serve --bin my-cli=./cli.js',
+    ].join('\n'));
 }

package/dist/lib/schema.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.serveInlineOptionsSchema = exports.configFileOptionsSchema = exports.binEntriesToRecordSchema = void 0;
+exports.serveInlineOptionsSchema = exports.configFileOptionsSchema = exports.packageJSONOptionsSchema = void 0;
 const zod_1 = require("zod");
 const log = __importStar(require("../ui/logger"));
 const binNameSchema = zod_1.z
@@ -43,8 +43,29 @@ const binTargetSchema = zod_1.z
     .string()
     .trim()
     .min(1)
-    .regex(/^\.{1,2}\//, 'bin target must be a relative path like ./cli.js');
-const customBinSchema = zod_1.z.record(binNameSchema, binTargetSchema);
+    .regex(/^(?!\/)(?![A-Za-z]:[\\/])(?!(?:\\\\|\/\/)).+/, 'bin target must be a relative path like ./cli.js');
+const binRecordSchema = zod_1.z.record(binNameSchema, binTargetSchema);
+const binEntrySchema = zod_1.z
+    .string()
+    .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?=(?!\/)(?![A-Za-z]:[\\/])(?!(?:\\\\|\/\/)).+$/, 'expected <name=relative/path>');
+const binEntriesToRecordSchema = zod_1.z
+    .array(binEntrySchema)
+    .optional()
+    .default([])
+    .transform((entries) => Object.fromEntries(entries.map((entry) => {
+    const [name, target] = entry.split('=', 2);
+    return [name, target];
+})));
+// -------------------------------------------
+// package.json Schema: Just bin for now
+// -------------------------------------------
+const packageJSONOptionsSchema = zod_1.z.object({
+    bin: binRecordSchema.optional(),
+});
+exports.packageJSONOptionsSchema = packageJSONOptionsSchema;
+// -------------------------------------------
+// symlx.config.json options: should allow configuring all options
+// -------------------------------------------
 const configFileOptionsSchema = zod_1.z.object({
     binDir: zod_1.z
         .string()
@@ -64,21 +85,21 @@ const configFileOptionsSchema = zod_1.z.object({
         log.warn('invalid "nonInteractive" value in config file; using default.');
         return undefined;
     }),
-    bin: customBinSchema.optional(),
+    bin: binRecordSchema.optional(),
+    binResolutionStrategy: zod_1.z.enum(['replace', 'merge']).optional(),
 });
 exports.configFileOptionsSchema = configFileOptionsSchema;
-const binEntrySchema = zod_1.z
-    .string()
-    .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?=\.{1,2}\/.+$/, 'expected <name=./relative/path>');
-exports.binEntriesToRecordSchema = zod_1.z
-    .array(binEntrySchema)
-    .optional()
-    .default([])
-    .transform((entries) => Object.fromEntries(entries.map((entry) => {
-    const [name, target] = entry.split('=', 2);
-    return [name, target];
-})));
-const serveInlineOptionsSchema = configFileOptionsSchema.extend({
-    bin: exports.binEntriesToRecordSchema,
+// -------------------------------------------
+// varying command inline options: highest priority in field:value resolution
+// -------------------------------------------
+const serveInlineOptionsSchema = configFileOptionsSchema
+    .pick({
+    binDir: true,
+    collision: true,
+    nonInteractive: true,
+    binResolutionStrategy: true,
+})
+    .extend({
+    bin: binEntriesToRecordSchema,
 });
 exports.serveInlineOptionsSchema = serveInlineOptionsSchema;

package/dist/{services → lib}/session-store.js

@@ -44,7 +44,7 @@ exports.cleanupSession = cleanupSession;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const log = __importStar(require("../ui/logger"));
-const utils_1 = require("../lib/utils");
+const utils_1 = require("./utils");
 // Checks whether a PID from a previous session is still alive.
 function isProcessAlive(pid) {
     // PIDs are always positive integer typically less the 2^15
@@ -63,15 +63,6 @@ function isProcessAlive(pid) {
         return code !== 'ESRCH';
     }
 }
-// Session files are best-effort state; deletion failure should not fail the command.
-function deleteFile(filePath) {
-    try {
-        node_fs_1.default.unlinkSync(filePath);
-    }
-    catch {
-        // Best-effort cleanup.
-    }
-}
 // Removes only symlinks that still point to the exact targets we created.
 // This avoids deleting user-managed commands with the same name.
 function cleanupLinks(links) {
@@ -92,7 +83,6 @@ function cleanupLinks(links) {
         }
     }
 }
-// -----------------------------------------------------------
 // Ensures runtime directories exist before linking/saving sessions.
 function ensureSymlxDirectories(binDir, sessionDir) {
     node_fs_1.default.mkdirSync(binDir, { recursive: true });
@@ -110,19 +100,19 @@ function cleanupStaleSessions(sessionDir) {
         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);
+            (0, utils_1.deleteFile)(filePath);
             continue;
         }
         // If the expected file structure has been corrupted, delete the file
         const record = (0, utils_1.loadJSONFile)(filePath);
         if (!record) {
-            deleteFile(filePath);
+            (0, utils_1.deleteFile)(filePath);
             continue;
         }
         // If process is dead, unlink the command from the bin and delete the session file
         if (!isProcessAlive(record.pid)) {
             cleanupLinks(record.links);
-            deleteFile(filePath);
+            (0, utils_1.deleteFile)(filePath);
             cleanUpCount++;
         }
     }
@@ -142,5 +132,5 @@ function createSessionFilePath(sessionDir) {
 // Cleanup for the active process/session.
 function cleanupSession(sessionPath, links) {
     cleanupLinks(links);
-    deleteFile(sessionPath);
+    (0, utils_1.deleteFile)(sessionPath);
 }

package/dist/lib/utils.js

@@ -5,6 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadJSONFile = loadJSONFile;
 exports.loadConfigFileOptions = loadConfigFileOptions;
+exports.loadPackageJSONOptions = loadPackageJSONOptions;
+exports.deleteFile = deleteFile;
+exports.pathContainsDir = pathContainsDir;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // Invalid/corrupted JSON files are ignored.
@@ -17,9 +20,108 @@ function loadJSONFile(filePath) {
         return undefined;
     }
 }
-function loadConfigFileOptions() {
-    const cwd = process.cwd();
+function formatReadError(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+function readJSONFileWithIssue(filePath, label) {
+    try {
+        const raw = node_fs_1.default.readFileSync(filePath, 'utf8');
+        return { data: JSON.parse(raw) };
+    }
+    catch (error) {
+        return {
+            issue: `invalid ${label} at ${filePath}: ${formatReadError(error)}`,
+        };
+    }
+}
+function loadConfigFileOptions(cwd) {
     const configPath = node_path_1.default.join(cwd, 'symlx.config.json');
-    const configFileOptions = loadJSONFile(configPath);
-    return configFileOptions;
+    if (!node_fs_1.default.existsSync(configPath)) {
+        return {};
+    }
+    const result = readJSONFileWithIssue(configPath, 'symlx.config.json');
+    if (result.issue) {
+        return { issue: result.issue };
+    }
+    return { options: result.data };
+}
+// npm allows `bin` as a string; in that form the command name defaults to package name
+// (without scope for scoped packages).
+function inferBinName(packageName) {
+    if (!packageName) {
+        return undefined;
+    }
+    if (packageName.startsWith('@')) {
+        const parts = packageName.split('/');
+        if (parts.length !== 2 || !parts[1]) {
+            return undefined;
+        }
+        return parts[1];
+    }
+    return packageName;
+}
+// Loads and validates all bin entries for the current project.
+// Returned map is command name => absolute target file path.
+function loadPackageJSONOptions(cwd) {
+    const packageJsonPath = node_path_1.default.join(cwd, 'package.json');
+    if (!node_fs_1.default.existsSync(packageJsonPath)) {
+        return {
+            bin: {},
+            issues: [`package.json not found at ${packageJsonPath}`],
+        };
+    }
+    const parsedPackageJSON = readJSONFileWithIssue(packageJsonPath, 'package.json');
+    if (parsedPackageJSON.issue) {
+        return {
+            bin: {},
+            issues: [parsedPackageJSON.issue],
+        };
+    }
+    const packageJson = parsedPackageJSON.data;
+    if (!packageJson || !packageJson.bin) {
+        return {
+            bin: {},
+            issues: [],
+        };
+    }
+    const bin = {};
+    const issues = [];
+    if (typeof packageJson.bin === 'string') {
+        const inferredBinName = inferBinName(packageJson.name);
+        if (inferredBinName) {
+            bin[inferredBinName] = packageJson.bin;
+        }
+        else {
+            issues.push('bin field is a string, but could not infer name, set a valid package.json "name"');
+        }
+    }
+    else {
+        for (const [name, relTarget] of Object.entries(packageJson.bin)) {
+            bin[name] = relTarget;
+        }
+    }
+    return { bin, issues };
+}
+// Session files are best-effort state; deletion failure should not fail the command.
+function deleteFile(filePath) {
+    try {
+        node_fs_1.default.unlinkSync(filePath);
+    }
+    catch {
+        // Best-effort cleanup.
+    }
+}
+// Checks if PATH already contains a directory so we can avoid noisy setup hints.
+function pathContainsDir(currentPath, targetDir) {
+    if (!currentPath) {
+        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));
+    return parts.includes(resolvedTarget);
 }

package/dist/lib/{validate.js → validator.js}

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateInlineOptions = validateInlineOptions;
+exports.validatePackageJSONOptions = validatePackageJSONOptions;
 exports.validateConfigFileOptions = validateConfigFileOptions;
+exports.validateInlineOptions = validateInlineOptions;
 const schema_1 = require("./schema");
 function formatIssues(error) {
     const details = error.issues
@@ -12,12 +13,12 @@ function formatIssues(error) {
         .join('; ');
     return details || 'invalid input';
 }
-function validateInlineOptions(schema, input, label = 'input') {
-    const result = schema.safeParse(input || {});
+function validatePackageJSONOptions(input) {
+    const result = schema_1.packageJSONOptionsSchema.safeParse(input || {});
     if (!result.success) {
-        throw new Error(`invalid ${label}: ${formatIssues(result.error)}`);
+        return { bin: {}, issues: result.error.issues.map((i) => i.message) };
     }
-    return result.data;
+    return { ...result.data, issues: [] };
 }
 function validateConfigFileOptions(input, label = 'input') {
     const result = schema_1.configFileOptionsSchema.safeParse(input || {});
@@ -26,3 +27,10 @@ function validateConfigFileOptions(input, label = 'input') {
     }
     return result.data;
 }
+function validateInlineOptions(schema, input, label = 'input') {
+    const result = schema.safeParse(input || {});
+    if (!result.success) {
+        throw new Error(`invalid ${label}: ${formatIssues(result.error)}`);
+    }
+    return result.data;
+}

package/dist/postinstall.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const PREFIX = '[symlx]';
+const START = '# >>> symlx path >>>';
+const END = '# <<< symlx path <<<';
+const BIN_PATH = '$HOME/.symlx/bin';
+const PROFILE_BASENAMES = ['.zprofile', '.zshrc', '.bashrc'];
+function info(message) {
+    process.stdout.write(`${PREFIX} ${message}\n`);
+}
+function warn(message) {
+    process.stderr.write(`${PREFIX} ${message}\n`);
+}
+function printManualPathSetupGuidance() {
+    if (process.platform === 'win32') {
+        info('manual setup (PowerShell):');
+        info('[Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\\\\.symlx\\\\bin;$env:Path", "User")');
+        info('then open a new terminal');
+        return;
+    }
+    info('manual setup: add this to ~/.zshrc, ~/.zprofile, or ~/.bashrc');
+    info(START);
+    info('if [[ ":$PATH:" != *":$HOME/.symlx/bin:"* ]]; then');
+    info('  export PATH="$HOME/.symlx/bin:$PATH"');
+    info('fi');
+    info(END);
+    info('then run: source ~/.zshrc (or your active shell profile)');
+}
+function resolveProfilePaths(homeDir) {
+    return PROFILE_BASENAMES.map((basename) => node_path_1.default.join(homeDir, basename));
+}
+function toHomeRelativePath(filePath, homeDir) {
+    if (filePath.startsWith(`${homeDir}${node_path_1.default.sep}`)) {
+        return `~/${node_path_1.default.relative(homeDir, filePath)}`;
+    }
+    return filePath;
+}
+function getPreferredSourcePath(updatedPaths) {
+    const shell = process.env.SHELL ?? '';
+    const preferredBasename = shell.includes('zsh')
+        ? '.zshrc'
+        : shell.includes('bash')
+            ? '.bashrc'
+            : undefined;
+    if (!preferredBasename) {
+        return updatedPaths[0];
+    }
+    return (updatedPaths.find((filePath) => node_path_1.default.basename(filePath) === preferredBasename) ??
+        updatedPaths[0]);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildPathBlock() {
+    return [
+        START,
+        `if [[ ":$PATH:" != *":${BIN_PATH}:"* ]]; then`,
+        `  export PATH="${BIN_PATH}:$PATH"`,
+        'fi',
+        END,
+    ].join('\n');
+}
+function ensureTrailingNewline(value) {
+    return value.endsWith('\n') ? value : `${value}\n`;
+}
+function upsertProfileBlock(filePath, block) {
+    const exists = node_fs_1.default.existsSync(filePath);
+    const current = exists ? node_fs_1.default.readFileSync(filePath, 'utf8') : '';
+    const normalizedCurrent = current.replace(/\r\n/g, '\n');
+    const markerPattern = new RegExp(`${escapeRegExp(START)}[\\s\\S]*?${escapeRegExp(END)}\\n?`, 'm');
+    let next;
+    if (markerPattern.test(normalizedCurrent)) {
+        next = normalizedCurrent.replace(markerPattern, `${block}\n`);
+    }
+    else if (normalizedCurrent.trim().length === 0) {
+        next = `${block}\n`;
+    }
+    else {
+        next = `${ensureTrailingNewline(normalizedCurrent)}\n${block}\n`;
+    }
+    if (next === normalizedCurrent) {
+        return false;
+    }
+    node_fs_1.default.writeFileSync(filePath, next, 'utf8');
+    return true;
+}
+function run() {
+    if (process.env.SYMLX_SKIP_PATH_SETUP === '1') {
+        info('skipping PATH setup because SYMLX_SKIP_PATH_SETUP=1');
+        printManualPathSetupGuidance();
+        return;
+    }
+    if (process.platform === 'win32') {
+        info('skipping shell profile PATH setup on Windows');
+        printManualPathSetupGuidance();
+        return;
+    }
+    const homeDir = node_os_1.default.homedir();
+    if (!homeDir) {
+        warn('could not resolve home directory; skipping PATH setup');
+        printManualPathSetupGuidance();
+        return;
+    }
+    const block = buildPathBlock();
+    const profilePaths = resolveProfilePaths(homeDir);
+    const existingPaths = profilePaths.filter((filePath) => node_fs_1.default.existsSync(filePath));
+    const targets = existingPaths.length > 0 ? existingPaths : [profilePaths[0]];
+    const updated = [];
+    for (const target of targets) {
+        try {
+            const changed = upsertProfileBlock(target, block);
+            if (changed) {
+                updated.push(target);
+            }
+        }
+        catch (error) {
+            warn(`could not update ${target}: ${String(error)}`);
+        }
+    }
+    if (updated.length > 0) {
+        info(`added ${BIN_PATH} to PATH in:`);
+        for (const target of updated) {
+            info(`- ${target}`);
+        }
+        const preferredSourcePath = getPreferredSourcePath(updated);
+        if (preferredSourcePath) {
+            const sourceTarget = toHomeRelativePath(preferredSourcePath, homeDir);
+            info(`run now: source ${sourceTarget}`);
+        }
+        info('or open a new shell to apply immediately');
+    }
+    else {
+        info(`PATH setup already present (${BIN_PATH})`);
+    }
+}
+run();

package/dist/preinstall.js

@@ -0,0 +1,10 @@
+"use strict";
+const PREFIX = '[symlx]';
+function info(message) {
+    process.stdout.write(`${PREFIX} ${message}\n`);
+}
+function run() {
+    info('notice: install will update your shell profile PATH with $HOME/.symlx/bin');
+    info('set SYMLX_SKIP_PATH_SETUP=1 to skip automatic PATH setup');
+}
+run();

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "symlx",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Temporary local CLI bin linker",
   "license": "MIT",
   "bin": {
-    "symlx": "dist/clii.js",
-    "cx": "dist/clii.js"
+    "symlx": "dist/cli.js",
+    "cx": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -31,6 +31,10 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
-    "check": "tsc -p tsconfig.json --noEmit"
+    "watch": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && tsc -p tsconfig.test.json && node --test .tmp-tests/test/**/*.test.js",
+    "preinstall": "node dist/preinstall.js",
+    "postinstall": "node dist/postinstall.js"
   }
 }

package/dist/core/paths.js

@@ -1,32 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-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 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(rootSymlxDir, 'bin');
-    // Session files live separately from bins and are used for stale cleanup.
-    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) {
-    if (!currentPath) {
-        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));
-    return parts.includes(resolvedTarget);
-}

package/dist/core/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/paths.js

@@ -1,26 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSymlxPaths = getSymlxPaths;
-exports.pathContainsDir = pathContainsDir;
-const node_os_1 = __importDefault(require("node:os"));
-const node_path_1 = __importDefault(require("node:path"));
-function getSymlxPaths(binDir) {
-    // Keep mutable runtime state under the user's home directory.
-    // Session files live separately from bins and are used for stale cleanup.
-    const sessionDir = node_path_1.default.join(node_os_1.default.homedir(), '.symlx', 'sessions');
-    return { binDir, sessionDir };
-}
-// Checks if PATH already contains a directory so we can avoid noisy setup hints.
-function pathContainsDir(currentPath, targetDir) {
-    if (!currentPath) {
-        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));
-    return parts.includes(resolvedTarget);
-}

package/dist/lib/validators.js

@@ -1,29 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.serveOptionsSchema = exports.collisionPolicySchema = void 0;
-exports.validate = validate;
-const zod_1 = require("zod");
-const collisionPolicySchema = zod_1.z.enum(['prompt', 'skip', 'fail', 'overwrite']);
-exports.collisionPolicySchema = collisionPolicySchema;
-const serveOptionsSchema = zod_1.z.object({
-    binDir: zod_1.z.string().trim().min(1).optional(),
-    collision: collisionPolicySchema,
-    nonInteractive: zod_1.z.boolean(),
-});
-exports.serveOptionsSchema = serveOptionsSchema;
-function formatIssues(error) {
-    const details = error.issues
-        .map((issue) => {
-        const pathLabel = issue.path.length > 0 ? issue.path.join('.') : 'value';
-        return `${pathLabel}: ${issue.message}`;
-    })
-        .join('; ');
-    return details || 'invalid input';
-}
-function validate(schema, input, label = 'input') {
-    const result = schema.safeParse(input);
-    if (!result.success) {
-        throw new Error(`invalid ${label}: ${formatIssues(result.error)}`);
-    }
-    return result.data;
-}

package/dist/services/package-bins.js

@@ -1,62 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadPackageJSONOptions = loadPackageJSONOptions;
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const utils_1 = require("../lib/utils");
-// npm allows `bin` as a string; in that form the command name defaults to package name
-// (without scope for scoped packages).
-function inferBinName(packageName) {
-    if (!packageName) {
-        return undefined;
-    }
-    if (packageName.startsWith('@')) {
-        const parts = packageName.split('/');
-        if (parts.length !== 2 || !parts[1]) {
-            return undefined;
-        }
-        return parts[1];
-    }
-    return packageName;
-}
-// Loads and validates all bin entries for the current project.
-// Returned map is command name => absolute target file path.
-function loadPackageJSONOptions(cwd) {
-    const packageJsonPath = node_path_1.default.join(cwd, 'package.json');
-    if (!node_fs_1.default.existsSync(packageJsonPath)) {
-        return {
-            bin: {},
-        };
-    }
-    const packageJson = (0, utils_1.loadJSONFile)(packageJsonPath);
-    if (!packageJson || !packageJson.bin) {
-        return {
-            bin: {},
-        };
-    }
-    const bins = {};
-    if (typeof packageJson.bin === 'string') {
-        const inferredBinName = inferBinName(packageJson.name);
-        if (inferredBinName) {
-            bins[inferredBinName] = node_path_1.default.resolve(cwd, packageJson.bin);
-        }
-    }
-    else {
-        for (const [name, relTarget] of Object.entries(packageJson.bin)) {
-            bins[name] = node_path_1.default.resolve(cwd, relTarget);
-        }
-    }
-    // if (bins.size === 0) {
-    //   throw new Error('no bin entries found');
-    // }
-    // // Fail fast if package.json points to non-existing executables.
-    // for (const [name, target] of bins.entries()) {
-    //   if (!fs.existsSync(target)) {
-    //     throw new Error(`bin target for "${name}" does not exist: ${target}`);
-    //   }
-    // }
-    return { bin: {} };
-}