Add pluggable movement strategies (v1.3.0)

Turn the hardcoded straight-line sweep into a strategy system behind three
seams so new patterns are easy to add and, for the first time, testable
without nut.js or a real screen:

- src/device.ts:     injectable Device seam over nut.js (autoDelayMs lives
                     here now); the only module that touches the native lib.
- src/strategies.ts: pure per-pattern path generators + registry + lenient
                     name resolution. Ships line, diagonal, jitter, walk,
                     arc, figureEight.
- src/executor.ts:   single executePath driver owning bounds policy
                     (abort/clamp/reflect), pacing, interrupt detection, and
                     restore-on-clean.

keeper.ts's simulateActivity now selects a strategy and delegates to the
executor; the default `line` pattern is byte-for-byte the previous behavior.

New config surface, layered CLI > file > default with strict validation:
- -p/--pattern <name>   movement strategy (names matched case/-/_-insensitive)
- -s/--step-size <px>   pixels per step; stepCount is now a step *count*

Robustness for the new edge-seeking patterns: interrupt detection compares
against the last commanded (rounded) point with a 2px tolerance, and
clamp/reflect stay a couple pixels off the screen edge, so sub-pixel cursor
placement on scaled/multi-monitor displays isn't misread as user activity.
jitter's radius scales with sweep length so it moves at the default stepSize.

Tests: new suites for strategies, the executor (all bounds policies,
rounding, interrupt, tolerance, pacing), and the keeper loop; config and
configFile suites extended for pattern/stepSize. editor.test.ts moved to
tests/ for consistency. 64 pass.
This commit is contained in:
2026-08-13 15:36:22 -05:00
parent 7777b16540
commit db3310c247
18 changed files with 1319 additions and 153 deletions
+31 -3
View File
@@ -16,7 +16,9 @@
* -m, --move-interval Idle time (seconds) before a sweep fires.
* -c, --check-interval Cursor poll cadence (seconds).
* -d, --step-delay Pause between synthetic steps (ms).
* -n, --step-count Steps per sweep (pixels).
* -n, --step-count Steps per sweep (count).
* -s, --step-size Pixels moved per step.
* -p, --pattern Movement strategy name (see strategies.ts).
* -V, --verbose Enable per-sweep / interrupt / bounds logging.
* (`-V` capital because `-v` is `--version`.)
*
@@ -31,6 +33,7 @@ import { parseArgs } from "node:util";
import { DEFAULT_CONFIG, defaultConfigPath } from "./config.ts";
import { CliError } from "./errors.ts";
import { PATTERN_NAMES, resolvePatternName } from "./strategies.ts";
/**
* Result of `parseCliArgs`. Numeric fields are `undefined` when the user
@@ -45,7 +48,10 @@ export interface ParsedCliArgs {
moveInterval: number | undefined; // seconds
checkInterval: number | undefined; // seconds
stepDelay: number | undefined; // milliseconds
stepCount: number | undefined; // pixels
stepCount: number | undefined; // count
stepSize: number | undefined; // pixels
/** Movement strategy name, validated against the registry. */
pattern: string | undefined;
/**
* `true` when `-V`/`--verbose` was passed; `undefined` when it was not.
* `undefined` (not `false`) lets the layered resolver distinguish "user
@@ -69,6 +75,20 @@ function parsePositiveNumber(name: string, raw: string | undefined): number | un
return n;
}
/**
* Validate a CLI-supplied movement-pattern name. Returns `undefined` when
* the flag was not supplied; throws `CliError` naming the valid patterns
* when the value isn't a registered strategy.
*/
function parsePatternName(raw: string | undefined): string | undefined {
if (raw === undefined) return undefined;
const canonical: string | null = resolvePatternName(raw);
if (canonical === null) {
throw new CliError(`invalid value for --pattern: '${raw}' (valid: ${PATTERN_NAMES.join(", ")})`);
}
return canonical;
}
/**
* Parse `process.argv` into a typed `ParsedCliArgs`. Uses Node's built-in
* `parseArgs` in strict mode so unknown flags and missing values surface
@@ -88,6 +108,8 @@ export function parseCliArgs(): ParsedCliArgs {
"check-interval": { type: "string", short: "c" },
"step-delay": { type: "string", short: "d" },
"step-count": { type: "string", short: "n" },
"step-size": { type: "string", short: "s" },
pattern: { type: "string", short: "p" },
verbose: { type: "boolean", short: "V" },
},
strict: true,
@@ -110,6 +132,8 @@ export function parseCliArgs(): ParsedCliArgs {
checkInterval: parsePositiveNumber("check-interval", values["check-interval"] as string | undefined),
stepDelay: parsePositiveNumber("step-delay", values["step-delay"] as string | undefined),
stepCount: parsePositiveNumber("step-count", values["step-count"] as string | undefined),
stepSize: parsePositiveNumber("step-size", values["step-size"] as string | undefined),
pattern: parsePatternName(values.pattern as string | undefined),
verbose: values.verbose === true ? true : undefined,
};
}
@@ -152,7 +176,10 @@ Options:
-m, --move-interval <seconds> Idle time before a sweep fires. Default: ${moveDefaultSec}.
-c, --check-interval <seconds> Cursor poll cadence. Default: ${checkDefaultSec}.
-d, --step-delay <ms> Pause between synthetic steps. Default: ${DEFAULT_CONFIG.stepDelay}.
-n, --step-count <pixels> Steps per sweep. Default: ${DEFAULT_CONFIG.stepCount}.
-n, --step-count <count> Steps per sweep. Default: ${DEFAULT_CONFIG.stepCount}.
-s, --step-size <pixels> Pixels moved per step. Default: ${DEFAULT_CONFIG.stepSize}.
-p, --pattern <name> Movement strategy. Default: ${DEFAULT_CONFIG.pattern}.
One of: ${PATTERN_NAMES.join(", ")}.
-V, --verbose Log every sweep, interrupt, and bounds event
(default prints only the startup banner).
@@ -162,6 +189,7 @@ Examples:
move
move --move-interval 180 --check-interval 5
move -m 300 -V
move --pattern arc --step-size 3
move --config ~/myprofile.json
`);
}