Add rsync exit code awareness + plan operation abstraction

- spawn.js: rsync() wrapper handles exit codes 0/24 as OK, 23 as fatal
- spawn.js: capture() accepts allowedExitCodes option
- run.js: all rsync calls go through rsync() wrapper
- PLAN.md: document planned operation abstraction refactor
This commit is contained in:
2026-03-07 01:41:25 +00:00
parent ab7479e62d
commit 45924cbcd7
3 changed files with 83 additions and 17 deletions

34
PLAN.md
View File

@@ -127,6 +127,40 @@ CWD or implicit defaults for directories — explicit is safer.
All external tools (rsync, zstd, xdelta3) are spawned with explicit argument arrays.
No shell string interpolation ever. Use Node's `child_process.spawn` or similar.
### Planned: Operation Abstractions
Currently dry-run logic is scattered inline throughout the run command. The intent is to refactor
toward self-describing operation objects — each operation knows both how to describe itself (for
dry-run) and how to execute itself. This makes the run command a clean sequence of operations,
makes per-tool behavior easy to adjust (e.g. rsync exit code handling), and makes dry-run output
a natural consequence of the abstraction rather than duplicated conditional logic.
Sketch:
```js
// Each tool gets its own operation type
const op = rsyncOp({ args: [...], allowedExitCodes: [0, 24] });
op.describe(); // prints what it would do
await op.run(); // executes
// Run command becomes:
const ops = buildOps(config);
if (dry) ops.forEach(op => op.describe());
else for (const op of ops) await op.run();
```
Per-tool exit code handling (e.g. rsync's partial transfer codes) lives inside the operation,
not scattered across callers.
### Current: rsync Exit Code Handling
rsync meaningful exit codes:
- `0` — success
- `23` — partial transfer due to error (fatal)
- `24` — partial transfer due to vanished source files (acceptable in some cases)
Currently basic: any non-zero exit code throws. Finer-grained handling planned as part of the
operation abstraction refactor.
## Occasional Snapshots
Delta chains are efficient but fragile over long chains. Periodic full snapshots (every N deltas,