dsh-rewind-plugin 0.4.1 → 0.5.0

package/lib/types/client/candidates.d.ts

@@ -18,11 +18,12 @@ export declare const PREVIEW_CHARS = 80;
 /**
  * Default cap on how many user messages the rewind picker lists (newest kept).
  *
- * A fixed 10 made long sessions look "incomplete" (only the newest 10 shown).
- * 50 keeps the picker scrollable/searchable via the popupSelect shell while
- * covering far longer sessions; callers can still pass an explicit `limit`.
+ * Matches the snapshot store's MAX_ANCHOR_GROUPS (100), so the picker shows
+ * every anchor group that can still restore file backups; 100 stays
+ * scrollable/searchable via the popupSelect shell, and callers can still
+ * pass an explicit `limit`.
  */
-export declare const DEFAULT_CANDIDATE_LIMIT = 50;
+export declare const DEFAULT_CANDIDATE_LIMIT = 100;
 /** One selectable rewind target. */
 export interface RewindCandidate {
     /** Absolute log seq of the `user/message` event. */

package/lib/types/client/index.d.ts

@@ -37,6 +37,6 @@ export declare const inject: string[];
 export declare function apply(ctx: ClientContext): void;
 /**
  * Public contract — rewind visibility. Stable, semver-protected; the rest of
- * this module is internal. See `docs/client-contract.md`.
+ * this module is internal. See `docs/contract/client-contract.md`.
  */
 export { hiddenSeqsOf, targetSeqOfArgs, type HiddenChat } from './hidden.ts';

package/lib/types/index.d.ts

@@ -26,13 +26,15 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 export { SnapshotStore } from './snapshot.ts';
-export type { CheckpointEntry, FileImpact, RestoreOutcome } from './snapshot.ts';
+export type { CheckpointEntry, FileImpact, PruneStaleReport, RestoreOutcome, RestoreJournal, RestoreJournalState, RestoreReconcileReport } from './snapshot.ts';
 export declare const name = "dsh-rewind";
 export declare const inject: string[];
 /** Plugin config: optional override of the checkpoint store root. */
 export interface RewindConfig {
     /** Checkpoint store root (defaults to `~/.dsh/rewind-snapshots`). */
     readonly snapshotDir?: string;
+    /** In-place content dedup (identical before-content → link). Default `true`. */
+    readonly dedup?: boolean;
 }
 /**
  * Register the `/rewind` command and the checkpoint pipeline (before-capture

package/lib/types/locales.d.ts

@@ -49,6 +49,23 @@ export declare const en: {
     noUserMessages: string;
     chooseMode: string;
     'command.description': string;
+    'cleanup.description': string;
+    'cleanup.inputHint': string;
+    'cleanup.status': string;
+    'cleanup.enabled': string;
+    'cleanup.disabled': string;
+    'cleanup.present': string;
+    'cleanup.absent': string;
+    'cleanup.onOk': string;
+    'cleanup.offOk': string;
+    'cleanup.maxAgeOk': string;
+    'cleanup.cfgInvalid': string;
+    'cleanup.saveFailed': string;
+    'cleanup.runDry': string;
+    'cleanup.runApply': string;
+    'cleanup.runFailed': string;
+    'cleanup.skipped': string;
+    'cleanup.usage': string;
 };
 /** The host rewind dictionary key union. */
 export type HostKey = keyof typeof en;

package/lib/types/rewind.d.ts

@@ -80,10 +80,11 @@ export interface RewindPlan {
 export declare const CANDIDATE_PREVIEW_CHARS = 80;
 /**
  * Default cap on how many user messages a candidate listing returns (newest
- * kept). Raised from 10 so long sessions don't look incomplete; callers can
+ * kept). Matches the snapshot store's MAX_ANCHOR_GROUPS (100), so every
+ * anchor group that still has restorable file backups is listed; callers can
  * still pass an explicit `limit`.
  */
-export declare const DEFAULT_CANDIDATE_LIMIT = 50;
+export declare const DEFAULT_CANDIDATE_LIMIT = 100;
 /**
  * Turn number for the rewind marker.
  *

package/lib/types/snapshot-cleanup.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Snapshot cleanup policy: the persisted config file, its validation, the
+ * `/snapshot-auto-cleanup` command's argument grammar, and the auto-sweep
+ * throttle. Kept free of host wiring so the policy and the parser are
+ * unit-testable in isolation; `src/index.ts` is the only consumer.
+ *
+ * Semantics (the "cleanup" vocabulary deliberately avoids "retention"):
+ * - `enabled` toggles the AUTOMATIC (24h) sweep. `false` (the default) keeps
+ *   every snapshot — the pre-feature behavior — and never writes a file.
+ * - `maxAgeDays` is the only "keep" knob: a finished session dir whose newest
+ *   member stamp is older than this many days of idle is removed by a sweep.
+ *   `0`/negative/non-integer are rejected, so a broken file can never steer
+ *   the sweep into deleting everything.
+ * - The config file is created ONLY by an explicit `/snapshot-auto-cleanup`
+ *   write. An absent file reads as the safe default (off); an unreadable or
+ *   invalid file reports `ok:false` so a sweep fail-closes (deletes nothing)
+ *   instead of guessing.
+ *
+ * @module dsh-rewind/snapshot-cleanup
+ */
+/** The cleanup policy, as persisted under `~/.dsh/snapshot-cleanup.json`. */
+export interface CleanupConfig {
+    readonly enabled: boolean;
+    readonly maxAgeDays: number;
+}
+export declare const CLEANUP_CONFIG_FILENAME = "snapshot-cleanup.json";
+/** Environment variable overriding the config file path. */
+export declare const CLEANUP_CONFIG_ENV = "DSH_SNAPSHOT_CLEANUP_CONFIG";
+/** The default keep threshold: finished sessions idle > 30 days are pruned. */
+export declare const DEFAULT_MAX_AGE_DAYS = 30;
+/** The safe default policy (off) — a missing/corrupt file behaves like this. */
+export declare const DEFAULT_CLEANUP_CONFIG: CleanupConfig;
+/** Auto-sweep cadence (the user's hardcoded 24h rhythm — not user-set). */
+export declare const AUTO_SWEEP_INTERVAL_MS: number;
+/** Resolve the config file path: env override, else `~/.dsh/snapshot-cleanup.json`. */
+export declare function resolveCleanupConfigPath(): string;
+/** The state file that records the last automatic-sweep wall-clock time. */
+export declare const STATE_FILENAME = "snapshot-cleanup-last-sweep.json";
+/**
+ * Resolve the last-sweep state path. It sits beside the config file so the
+ * 24h cadence SURVIVES a host restart (a real deployment is rarely up 24/7,
+ * so an in-memory timestamp would reset on every boot and re-sweep too often).
+ */
+export declare function resolveCleanupStatePath(): string;
+/**
+ * Read the persisted last-sweep time (epoch ms). A missing or corrupt file
+ * reads as `0` ("never swept"), so the next activity runs the sweep — which is
+ * safe because the sweep is idempotent and never deletes the active session.
+ */
+export declare function loadLastSweepAt(path: string): Promise<number>;
+/** Persist the last-sweep time, atomically (temp + rename). */
+export declare function saveLastSweepAt(path: string, ms: number): Promise<void>;
+/** The slice of a store `runAutoCleanupCheck` needs (pruneStale). */
+export interface AutoCleanupPruner {
+    pruneStale(opts: {
+        keepActiveId?: string;
+        maxAgeDays: number;
+        dryRun?: boolean;
+    }): Promise<unknown>;
+}
+/**
+ * The one-shot auto-cleanup check. Loads the policy + persisted last-sweep time
+ * and, only when enabled AND >=24h since the last sweep, runs the sweep and
+ * re-anchors the window on disk. Dependencies (store, paths, logger) are
+ * injected so the composition is unit-testable without a host. Never rejects:
+ * a corrupt config fail-closes (no deletion) and logs, a prune failure logs.
+ *
+ * `sessionId` is the active session directory that must never be pruned.
+ */
+export declare function runAutoCleanupCheck(deps: {
+    pruner: AutoCleanupPruner;
+    configPath: string;
+    statePath: string;
+    log: (msg: string) => void;
+}, sessionId: string | undefined): Promise<void>;
+/**
+ * Validate one parsed JSON value into a {@link CleanupConfig}. Tolerates
+ * unknown extra keys; rejects a present-but-wrong-typed known key. Missing
+ * known keys fall back to the safe default.
+ */
+export declare function parseCleanupConfig(raw: unknown): {
+    ok: true;
+    config: CleanupConfig;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Load and validate the config file. A missing file is NOT an error: it reads
+ * as the safe default (off, `fromFile:false`). An unreadable, non-JSON, or
+ * structurally-invalid file is `ok:false` so a sweep fail-closes.
+ */
+export declare function loadCleanupConfig(path: string): Promise<{
+    ok: true;
+    config: CleanupConfig;
+    fromFile: boolean;
+} | {
+    ok: false;
+    error: string;
+}>;
+/**
+ * Persist a validated {@link CleanupConfig}, atomically (temp + rename). Any
+ * invalid value throws before the file is touched, so the command can never
+ * write a broken policy.
+ */
+export declare function saveCleanupConfig(path: string, config: CleanupConfig): Promise<void>;
+/** The `/snapshot-auto-cleanup` sub-command the parser can resolve to. */
+export type CleanupCommandAction = 'status' | 'on' | 'off' | 'max-age' | 'run' | 'run-apply';
+/**
+ * Parse the free-form text after `/snapshot-auto-cleanup`. Pure so it is
+ * unit-testable; `src/index.ts` maps the resolved action onto the store / the
+ * config file. `max-age` returns the validated positive day count.
+ */
+export declare function parseCleanupCommand(rawInput: string): {
+    action: CleanupCommandAction;
+    value?: number;
+} | {
+    error: string;
+};
+/**
+ * The 24h auto-sweep throttle. `lastAtMs` of `0` means "never ran" (a fresh
+ * process), so the first call always sweeps; after that a call within 24h is
+ * a no-op, matching the "every machine at most once per day" model.
+ */
+export declare function shouldRunAutoSweep(lastAtMs: number, nowMs: number): boolean;