peaks-loop 4.2.2 → 4.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +109 -0
- package/dist/cli/commands/code-context-now-command.js +8 -3
- package/dist/cli/commands/code-context-now-envelope.d.ts +27 -2
- package/dist/cli/commands/code-context-now-envelope.js +47 -2
- package/dist/cli/commands/compact-harness-window-command.js +19 -111
- package/dist/cli/commands/compact-harness-window-opt-out.d.ts +4 -0
- package/dist/cli/commands/compact-harness-window-opt-out.js +76 -0
- package/dist/cli/commands/compact-harness-window-percent.d.ts +39 -0
- package/dist/cli/commands/compact-harness-window-percent.js +78 -0
- package/dist/cli/commands/compact-harness-window-reports.d.ts +8 -0
- package/dist/cli/commands/compact-harness-window-reports.js +149 -0
- package/dist/cli/commands/workspace/init-actions.d.ts +2 -0
- package/dist/cli/commands/workspace/init-actions.js +15 -1
- package/dist/cli/commands/workspace/init-command.js +1 -1
- package/dist/cli/commands/workspace/init-envelope.d.ts +2 -1
- package/dist/cli/commands/workspace/init-envelope.js +18 -1
- package/dist/cli/commands/workspace/init-harness-threshold.d.ts +30 -0
- package/dist/cli/commands/workspace/init-harness-threshold.js +134 -0
- package/dist/services/context/auto-compact-reader.d.ts +6 -5
- package/dist/services/context/auto-compact-reader.js +24 -27
- package/dist/services/context/harness-compact-threshold-config.d.ts +178 -0
- package/dist/services/context/harness-compact-threshold-config.js +166 -0
- package/dist/services/context/harness-compact-threshold-ensure.d.ts +90 -0
- package/dist/services/context/harness-compact-threshold-ensure.js +158 -0
- package/dist/services/context/harness-compact-threshold-refusal.d.ts +39 -0
- package/dist/services/context/harness-compact-threshold-refusal.js +122 -0
- package/dist/services/context/harness-compact-threshold-reset-types.d.ts +59 -0
- package/dist/services/context/harness-compact-threshold-reset-types.js +9 -0
- package/dist/services/context/harness-compact-threshold-reset.d.ts +48 -0
- package/dist/services/context/harness-compact-threshold-reset.js +215 -0
- package/dist/services/context/harness-compact-threshold-verdict.d.ts +71 -0
- package/dist/services/context/harness-compact-threshold-verdict.js +124 -0
- package/dist/services/context/harness-percent-gates.d.ts +35 -0
- package/dist/services/context/harness-percent-gates.js +102 -0
- package/dist/services/context/harness-percent-ownership.d.ts +126 -0
- package/dist/services/context/harness-percent-ownership.js +200 -0
- package/dist/services/context/harness-settings-file.d.ts +70 -0
- package/dist/services/context/harness-settings-file.js +83 -0
- package/dist/services/context/harness-window-config.d.ts +53 -141
- package/dist/services/context/harness-window-config.js +58 -296
- package/dist/services/context/harness-window-opt-out.d.ts +67 -0
- package/dist/services/context/harness-window-opt-out.js +241 -0
- package/dist/services/context/harness-window-ownership.d.ts +49 -0
- package/dist/services/context/harness-window-ownership.js +130 -0
- package/dist/services/ide/adapters/claude-code-adapter.d.ts +9 -9
- package/dist/services/ide/adapters/claude-code-adapter.js +5 -5
- package/dist/services/ide/ide-compact-types.d.ts +23 -4
- package/dist/services/ide/shared/safe-path.d.ts +18 -0
- package/dist/services/ide/shared/safe-path.js +34 -1
- package/package.json +6 -6
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Harness auto-compact THRESHOLD percent — THE GATES, in order.
|
|
3
|
+
*
|
|
4
|
+
* Split out of `harness-compact-threshold-config.ts` so the writer stays under
|
|
5
|
+
* the file-size cap and so the order of the gates can be read (and tested) on
|
|
6
|
+
* its own. `syncHarnessPercent` is the only caller.
|
|
7
|
+
*
|
|
8
|
+
* Order is load-bearing and is the window writer's: opt-out and the home guard
|
|
9
|
+
* first (they are about WHERE), then "no value asked for", then the band (an
|
|
10
|
+
* out-of-band request is refused whatever the file holds), then the file's
|
|
11
|
+
* editability, then idempotence, then provenance last — so `unchanged` is
|
|
12
|
+
* reported for a human's own matching value rather than a refusal.
|
|
13
|
+
*/
|
|
14
|
+
import { type SettingsFileShape } from './harness-settings-file.js';
|
|
15
|
+
import type { HarnessCompactThresholdLocation } from './harness-compact-threshold-config.js';
|
|
16
|
+
/**
|
|
17
|
+
* The sentinel `percentSkipReason` returns for "the file already holds the
|
|
18
|
+
* wanted value" — a non-reason, so the action enum stays `written | unchanged |
|
|
19
|
+
* skipped` and the caller has one branch per outcome.
|
|
20
|
+
*/
|
|
21
|
+
export declare const SKIP_UNCHANGED = "__unchanged__";
|
|
22
|
+
/** Everything the gates are allowed to see. */
|
|
23
|
+
export interface PercentGateInput {
|
|
24
|
+
readonly location: HarnessCompactThresholdLocation;
|
|
25
|
+
readonly percent: number | null;
|
|
26
|
+
readonly settings: SettingsFileShape | null;
|
|
27
|
+
readonly fileRaw: unknown;
|
|
28
|
+
readonly filePercent: number | null;
|
|
29
|
+
readonly peakWritten: boolean;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* THE GATES: the reason this call must not write, `SKIP_UNCHANGED` when the
|
|
33
|
+
* file already holds the wanted value, or `null` when it may write.
|
|
34
|
+
*/
|
|
35
|
+
export declare function percentSkipReason(input: PercentGateInput): string | null;
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Harness auto-compact THRESHOLD percent — THE GATES, in order.
|
|
3
|
+
*
|
|
4
|
+
* Split out of `harness-compact-threshold-config.ts` so the writer stays under
|
|
5
|
+
* the file-size cap and so the order of the gates can be read (and tested) on
|
|
6
|
+
* its own. `syncHarnessPercent` is the only caller.
|
|
7
|
+
*
|
|
8
|
+
* Order is load-bearing and is the window writer's: opt-out and the home guard
|
|
9
|
+
* first (they are about WHERE), then "no value asked for", then the band (an
|
|
10
|
+
* out-of-band request is refused whatever the file holds), then the file's
|
|
11
|
+
* editability, then idempotence, then provenance last — so `unchanged` is
|
|
12
|
+
* reported for a human's own matching value rather than a refusal.
|
|
13
|
+
*/
|
|
14
|
+
import { isUserHomeProjectRoot } from '../config/config-safety.js';
|
|
15
|
+
import { isEditableSettingsFile, isLinkedSettingsFile, settingsEnvValue } from './harness-settings-file.js';
|
|
16
|
+
import { HARNESS_WINDOW_SYNC_OPTOUT_KEY, HARNESS_WINDOW_SYNC_OPTOUT_VALUE } from './harness-window-config.js';
|
|
17
|
+
import { parseHarnessCompactPercent } from './harness-percent-ownership.js';
|
|
18
|
+
/**
|
|
19
|
+
* The sentinel `percentSkipReason` returns for "the file already holds the
|
|
20
|
+
* wanted value" — a non-reason, so the action enum stays `written | unchanged |
|
|
21
|
+
* skipped` and the caller has one branch per outcome.
|
|
22
|
+
*/
|
|
23
|
+
export const SKIP_UNCHANGED = '__unchanged__';
|
|
24
|
+
/**
|
|
25
|
+
* THE GATES: the reason this call must not write, `SKIP_UNCHANGED` when the
|
|
26
|
+
* file already holds the wanted value, or `null` when it may write.
|
|
27
|
+
*/
|
|
28
|
+
export function percentSkipReason(input) {
|
|
29
|
+
const where = placementRefusal(input);
|
|
30
|
+
if (where !== null)
|
|
31
|
+
return where;
|
|
32
|
+
if (input.percent === null)
|
|
33
|
+
return noValueRefusal(input);
|
|
34
|
+
if (parseHarnessCompactPercent(input.percent) === null)
|
|
35
|
+
return 'out-of-range';
|
|
36
|
+
// THE LINK GUARD, before `unreadable-settings`. A symlinked `settings.local.json`
|
|
37
|
+
// — or a symlinked `.claude` directory holding an ordinary one — parses fine, so
|
|
38
|
+
// the editability test would say "editable" and the write would follow the link
|
|
39
|
+
// into whatever it points at. Its own reason — not
|
|
40
|
+
// `unreadable-settings` — because the file IS readable; the problem is where a
|
|
41
|
+
// write would land, and the user needs to be told that, not that their JSON is
|
|
42
|
+
// broken. See `isLinkedSettingsFile`.
|
|
43
|
+
if (isLinkedSettingsFile(input.location.settingsPath))
|
|
44
|
+
return 'symlinked-settings';
|
|
45
|
+
if (!isEditableSettingsFile(input.location.settingsPath))
|
|
46
|
+
return 'unreadable-settings';
|
|
47
|
+
if (input.filePercent === input.percent)
|
|
48
|
+
return SKIP_UNCHANGED;
|
|
49
|
+
// The same provenance rule as the window, decided from the FILE against its
|
|
50
|
+
// own marker: peaks-loop may update what it wrote and fill an empty slot, and
|
|
51
|
+
// never touches a value it did not write.
|
|
52
|
+
if (input.fileRaw !== undefined && !input.peakWritten)
|
|
53
|
+
return 'not-peaks-owned';
|
|
54
|
+
return null;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* The caller asked for no percent: why, from what the FILE holds.
|
|
58
|
+
*
|
|
59
|
+
* A value on disk that is not a percentage at all (`eighty`, `80.5`) is its own
|
|
60
|
+
* state: the caller has no number to offer because the FILE's value did not
|
|
61
|
+
* parse, which is not the same fact as "the caller asked for no percent" — that
|
|
62
|
+
* one reads `no-percent-resolved` and describes an empty slot.
|
|
63
|
+
*
|
|
64
|
+
* A whole NUMBER outside the band (`150`) is a third state: it parses, so it IS
|
|
65
|
+
* a percentage the harness will not accept. Reporting it as
|
|
66
|
+
* `unreadable-percent` told the user their value was not a percentage, which is
|
|
67
|
+
* false and points at the wrong remedy.
|
|
68
|
+
*/
|
|
69
|
+
function noValueRefusal(input) {
|
|
70
|
+
if (input.fileRaw === undefined || input.filePercent !== null)
|
|
71
|
+
return 'no-percent-resolved';
|
|
72
|
+
return isWholeNumber(input.fileRaw) ? 'out-of-range' : 'unreadable-percent';
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* THE SAME SPELLING RULE THE PARSER USES — digits with no leading zero beyond a
|
|
76
|
+
* lone `0`. `Number('80.0')`, `Number('+80')` and `Number('00080')` all succeed,
|
|
77
|
+
* so a bare "is it a finite whole number" test called a float or a signed
|
|
78
|
+
* spelling a whole number outside the band, and the notice told the user their
|
|
79
|
+
* `80.0` was "outside the 1..100 percent" when it was not a number at all.
|
|
80
|
+
*/
|
|
81
|
+
const PLAIN_WHOLE_SPELLING = /^(?:0|[1-9]\d*)$/;
|
|
82
|
+
/** One raw value is the plain whole-number spelling this module writes. */
|
|
83
|
+
function isWholeNumber(raw) {
|
|
84
|
+
if (typeof raw === 'number')
|
|
85
|
+
return Number.isInteger(raw);
|
|
86
|
+
if (typeof raw !== 'string')
|
|
87
|
+
return false;
|
|
88
|
+
return PLAIN_WHOLE_SPELLING.test(raw.trim());
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* The two WHERE gates, checked before anything about the value. Split out only
|
|
92
|
+
* to keep each function under the complexity ceiling — the order of the whole
|
|
93
|
+
* gate sequence is documented on `percentSkipReason`.
|
|
94
|
+
*/
|
|
95
|
+
function placementRefusal(input) {
|
|
96
|
+
if (settingsEnvValue(input.settings, HARNESS_WINDOW_SYNC_OPTOUT_KEY) ===
|
|
97
|
+
HARNESS_WINDOW_SYNC_OPTOUT_VALUE)
|
|
98
|
+
return 'opted-out';
|
|
99
|
+
if (input.location.projectRoot !== undefined && isUserHomeProjectRoot(input.location.projectRoot))
|
|
100
|
+
return 'unsafe-project-root';
|
|
101
|
+
return null;
|
|
102
|
+
}
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* WHO owns the harness auto-compact PERCENT key — one predicate, one classifier.
|
|
3
|
+
*
|
|
4
|
+
* This module exists so the three sides that have to agree about ownership (the
|
|
5
|
+
* writer, the rollback, the state report) cannot drift into three spellings of
|
|
6
|
+
* the same question. It is also what keeps the write half under the file-size
|
|
7
|
+
* cap, since every one of those sides needs this and nothing else from it.
|
|
8
|
+
*
|
|
9
|
+
* The percent key is `IdeCompactProfile.autoCompactPercentEnvVar` (declared per
|
|
10
|
+
* adapter — no IDE names here) and its provenance marker is
|
|
11
|
+
* `HARNESS_PERCENT_WRITTEN_KEY`, the twin of the window's.
|
|
12
|
+
*/
|
|
13
|
+
/** Whole-content plain decimal integer of at most `NAMED_INTEGER_MAX_DIGITS`. */
|
|
14
|
+
export declare function isPlainIntegerSpelling(raw: unknown): boolean;
|
|
15
|
+
/** How an unparseable settings value is described back (see above). */
|
|
16
|
+
export declare function boundedRawNote(raw: unknown): string;
|
|
17
|
+
/**
|
|
18
|
+
* Provenance marker for the percent key, the twin of
|
|
19
|
+
* `HARNESS_WINDOW_WRITTEN_KEY`: it records the value peaks-loop ITSELF last
|
|
20
|
+
* wrote, so a value that differs is a human's own setting and is never
|
|
21
|
+
* overwritten. Travels in the same write as the value it describes.
|
|
22
|
+
*/
|
|
23
|
+
export declare const HARNESS_PERCENT_WRITTEN_KEY = "PEAKS_HARNESS_PERCENT_WRITTEN";
|
|
24
|
+
/**
|
|
25
|
+
* The band the harness accepts for the percentage. It is a PERCENTAGE of the
|
|
26
|
+
* window, so 1..100 — and, like the window band, out-of-band values are
|
|
27
|
+
* REFUSED rather than clamped: a clamped write would put a different number in
|
|
28
|
+
* the file from the one reported, which is the same two-numbers drift the
|
|
29
|
+
* window band exists to prevent.
|
|
30
|
+
*/
|
|
31
|
+
export declare const HARNESS_COMPACT_PERCENT_MIN = 1;
|
|
32
|
+
/** See `HARNESS_COMPACT_PERCENT_MIN`. */
|
|
33
|
+
export declare const HARNESS_COMPACT_PERCENT_MAX = 100;
|
|
34
|
+
/**
|
|
35
|
+
* Parse a candidate percent. Whole integers 1..100 only (a number, or the
|
|
36
|
+
* numeric string a JSON `env` block always carries, in the plain decimal
|
|
37
|
+
* spelling `PLAIN_PERCENT_SPELLING` requires). Anything else — `0`, `101`,
|
|
38
|
+
* `80.5`, `80.0`, `8e1`, `'abc'`, `''`, `null` — is null, so callers can
|
|
39
|
+
* distinguish "absent" from "unusable" via the RAW value.
|
|
40
|
+
*/
|
|
41
|
+
export declare function parseHarnessCompactPercent(raw: unknown): number | null;
|
|
42
|
+
/**
|
|
43
|
+
* THE WRITER'S OWNERSHIP PREDICATE — strict, and deliberately NOT the one the
|
|
44
|
+
* rollback uses. See `percentOwnershipOf` for the pair.
|
|
45
|
+
*
|
|
46
|
+
* A value is the writer's to OVERWRITE only when `HARNESS_PERCENT_WRITTEN_KEY`
|
|
47
|
+
* is present and BOTH sides parse to the same number.
|
|
48
|
+
*
|
|
49
|
+
* The asymmetry with `isHarnessPercentRemovable` is the point. Removing a value
|
|
50
|
+
* deserves a wider rule than overwriting one: `--reset` is the documented
|
|
51
|
+
* recovery from a broken value and the user asked for it, while a probe or an
|
|
52
|
+
* init rewriting a value it cannot read would destroy the raw text the user
|
|
53
|
+
* needs in order to see what went wrong. Widening THIS predicate is how a
|
|
54
|
+
* background probe would silently replace a human's `eighty` — the exact
|
|
55
|
+
* "peaks-loop overruled my setting" failure the provenance marker exists to
|
|
56
|
+
* prevent.
|
|
57
|
+
*/
|
|
58
|
+
export declare function isHarnessPercentPeaksOwned(input: {
|
|
59
|
+
readonly fileRaw: unknown;
|
|
60
|
+
readonly markerRaw: unknown;
|
|
61
|
+
}): boolean;
|
|
62
|
+
/**
|
|
63
|
+
* THE ROLLBACK'S OWNERSHIP PREDICATE — what `--reset` may REMOVE.
|
|
64
|
+
*
|
|
65
|
+
* Wider than `isHarnessPercentPeaksOwned` by exactly ONE shape, which proves the
|
|
66
|
+
* value is a corruption of peaks-loop's own write rather than a human pin: the
|
|
67
|
+
* marker parses while the VALUE does not. peaks-loop only ever writes
|
|
68
|
+
* `String(n)` as its marker (a plain in-band integer), so a VALID numeric
|
|
69
|
+
* marker beside an unreadable value can only be its own write mangled
|
|
70
|
+
* afterwards — and that is the documented `--reset` recovery.
|
|
71
|
+
*
|
|
72
|
+
* No marker ⇒ human. A parseable value that differs from a parseable marker ⇒
|
|
73
|
+
* human takeover. A marker that does not parse is NOT evidence of ownership in
|
|
74
|
+
* any combination: an unreadable value beside it is the user's own (even when
|
|
75
|
+
* the two strings are equal — a human who typed the same typo into both rows
|
|
76
|
+
* proved nothing about peaks-loop), and it is KEPT. The earlier "both raws are
|
|
77
|
+
* equal and unreadable" arm classified that pair `peaks-corrupt` and `--reset`
|
|
78
|
+
* deleted a user value; it is gone.
|
|
79
|
+
*/
|
|
80
|
+
export declare function isHarnessPercentRemovable(input: {
|
|
81
|
+
readonly fileRaw: unknown;
|
|
82
|
+
readonly markerRaw: unknown;
|
|
83
|
+
}): boolean;
|
|
84
|
+
/**
|
|
85
|
+
* WHO the percent value on disk belongs to — the five states, named once so the
|
|
86
|
+
* rollback and the state report cannot describe the same file differently.
|
|
87
|
+
*
|
|
88
|
+
* - `peaks` — matches its marker: both sides parse to the same number
|
|
89
|
+
* - `peaks-corrupt` — marker present and parseable while the VALUE is not: a
|
|
90
|
+
* corruption of peaks-loop's own write
|
|
91
|
+
* - `human` — no marker, a parseable value that differs from its
|
|
92
|
+
* marker (a takeover), or any value whose MARKER does not
|
|
93
|
+
* parse (peaks-loop never wrote such a marker)
|
|
94
|
+
* - `stale-marker` — the value was deleted by hand, the marker survived
|
|
95
|
+
* - `none` — neither the value nor a marker
|
|
96
|
+
*/
|
|
97
|
+
export type HarnessPercentOwnership = 'peaks' | 'peaks-corrupt' | 'human' | 'stale-marker' | 'none';
|
|
98
|
+
/**
|
|
99
|
+
* Classify one (value, marker) pair — the single answer to "may `--reset`
|
|
100
|
+
* remove this, and what do we call it?".
|
|
101
|
+
*/
|
|
102
|
+
export declare function percentOwnershipOf(input: {
|
|
103
|
+
readonly fileRaw: unknown;
|
|
104
|
+
readonly markerRaw: unknown;
|
|
105
|
+
}): HarnessPercentOwnership;
|
|
106
|
+
/** What the file currently holds for the percent key, ownership included. */
|
|
107
|
+
export interface HarnessPercentState {
|
|
108
|
+
readonly key: string;
|
|
109
|
+
/**
|
|
110
|
+
* A BOUNDED description of what the file holds, present only when the key
|
|
111
|
+
* exists — never the raw string (MED-2). This state is printed as JSON and
|
|
112
|
+
* folded into logs, and the value is user-writable, so a secret mis-parked
|
|
113
|
+
* there must not travel. Its PRESENCE is what tells "holds something that
|
|
114
|
+
* does not parse" from "absent"; see `boundedRawNote`.
|
|
115
|
+
*/
|
|
116
|
+
readonly rawNote?: string;
|
|
117
|
+
/** The parsed percent, or null when absent / unparseable. */
|
|
118
|
+
readonly percent: number | null;
|
|
119
|
+
readonly ownership: HarnessPercentOwnership;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Read the percent half of the pair — the state-report counterpart of
|
|
123
|
+
* `readHarnessWindowState`, so `peaks compact harness-window` can show BOTH
|
|
124
|
+
* knobs it manages rather than only the window.
|
|
125
|
+
*/
|
|
126
|
+
export declare function readHarnessPercentState(settingsPath: string, percentKey: string): HarnessPercentState;
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* WHO owns the harness auto-compact PERCENT key — one predicate, one classifier.
|
|
3
|
+
*
|
|
4
|
+
* This module exists so the three sides that have to agree about ownership (the
|
|
5
|
+
* writer, the rollback, the state report) cannot drift into three spellings of
|
|
6
|
+
* the same question. It is also what keeps the write half under the file-size
|
|
7
|
+
* cap, since every one of those sides needs this and nothing else from it.
|
|
8
|
+
*
|
|
9
|
+
* The percent key is `IdeCompactProfile.autoCompactPercentEnvVar` (declared per
|
|
10
|
+
* adapter — no IDE names here) and its provenance marker is
|
|
11
|
+
* `HARNESS_PERCENT_WRITTEN_KEY`, the twin of the window's.
|
|
12
|
+
*/
|
|
13
|
+
/**
|
|
14
|
+
* WHO owns the harness auto-compact PERCENT key — one predicate, one classifier.
|
|
15
|
+
*
|
|
16
|
+
* This module exists so the three sides that have to agree about ownership (the
|
|
17
|
+
* writer, the rollback, the state report) cannot drift into three spellings of
|
|
18
|
+
* the same question. It also hosts the MED-2 bounded vocabulary below, which the
|
|
19
|
+
* window module and the envelope views share.
|
|
20
|
+
*
|
|
21
|
+
* The percent key is `IdeCompactProfile.autoCompactPercentEnvVar` (declared per
|
|
22
|
+
* adapter — no IDE names here) and its provenance marker is
|
|
23
|
+
* `HARNESS_PERCENT_WRITTEN_KEY`, the twin of the window's.
|
|
24
|
+
*/
|
|
25
|
+
import { readSettingsObject, settingsEnvValue } from './harness-settings-file.js';
|
|
26
|
+
/**
|
|
27
|
+
* MED-2 bounded vocabulary. A value here comes from a user-writable settings key
|
|
28
|
+
* whose rows reach JSON envelopes and logs, so a secret mis-parked at it must not
|
|
29
|
+
* travel: a plain integer (never a secret, and `150` out of band is the case the
|
|
30
|
+
* user must see) is NAMED; anything else is a fixed phrase plus a CHARACTER
|
|
31
|
+
* COUNT — no content, not even a prefix.
|
|
32
|
+
*/
|
|
33
|
+
const NAMED_INTEGER_MAX_DIGITS = 12;
|
|
34
|
+
/** Whole-content plain decimal integer of at most `NAMED_INTEGER_MAX_DIGITS`. */
|
|
35
|
+
export function isPlainIntegerSpelling(raw) {
|
|
36
|
+
if (typeof raw === 'number') {
|
|
37
|
+
return Number.isInteger(raw) && String(Math.abs(raw)).length <= NAMED_INTEGER_MAX_DIGITS;
|
|
38
|
+
}
|
|
39
|
+
if (typeof raw !== 'string')
|
|
40
|
+
return false;
|
|
41
|
+
return new RegExp(`^-?\\d{1,${String(NAMED_INTEGER_MAX_DIGITS)}}$`).test(raw.trim());
|
|
42
|
+
}
|
|
43
|
+
/** How an unparseable settings value is described back (see above). */
|
|
44
|
+
export function boundedRawNote(raw) {
|
|
45
|
+
if (raw === undefined)
|
|
46
|
+
return 'not set';
|
|
47
|
+
if (typeof raw === 'number' && isPlainIntegerSpelling(raw))
|
|
48
|
+
return `the number ${String(raw)}`;
|
|
49
|
+
if (typeof raw === 'string' && isPlainIntegerSpelling(raw))
|
|
50
|
+
return `the number ${raw.trim()}`;
|
|
51
|
+
if (Array.isArray(raw))
|
|
52
|
+
return 'an array (not echoed here)';
|
|
53
|
+
if (typeof raw === 'object' && raw !== null)
|
|
54
|
+
return 'an object (not echoed here)';
|
|
55
|
+
const length = typeof raw === 'string' ? raw.length : 1;
|
|
56
|
+
return `a value that is not a number (${String(length)} chars, not echoed here)`;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Provenance marker for the percent key, the twin of
|
|
60
|
+
* `HARNESS_WINDOW_WRITTEN_KEY`: it records the value peaks-loop ITSELF last
|
|
61
|
+
* wrote, so a value that differs is a human's own setting and is never
|
|
62
|
+
* overwritten. Travels in the same write as the value it describes.
|
|
63
|
+
*/
|
|
64
|
+
export const HARNESS_PERCENT_WRITTEN_KEY = 'PEAKS_HARNESS_PERCENT_WRITTEN';
|
|
65
|
+
/**
|
|
66
|
+
* The band the harness accepts for the percentage. It is a PERCENTAGE of the
|
|
67
|
+
* window, so 1..100 — and, like the window band, out-of-band values are
|
|
68
|
+
* REFUSED rather than clamped: a clamped write would put a different number in
|
|
69
|
+
* the file from the one reported, which is the same two-numbers drift the
|
|
70
|
+
* window band exists to prevent.
|
|
71
|
+
*/
|
|
72
|
+
export const HARNESS_COMPACT_PERCENT_MIN = 1;
|
|
73
|
+
/** See `HARNESS_COMPACT_PERCENT_MIN`. */
|
|
74
|
+
export const HARNESS_COMPACT_PERCENT_MAX = 100;
|
|
75
|
+
/**
|
|
76
|
+
* THE SPELLING peaks-loop writes (and therefore the only one it reads back):
|
|
77
|
+
* a plain decimal with NO leading zero beyond a lone `0`. `80.0`, `8e1`, `+80`,
|
|
78
|
+
* `080` and `00080` all evaluate to an in-band number under `Number()`, but
|
|
79
|
+
* none of them is a value this module can have written — `String(percent)`
|
|
80
|
+
* emits `80` and nothing else — so accepting them would let a hand edit or
|
|
81
|
+
* another tool masquerade as peaks-loop's own output. A value peaks-loop cannot
|
|
82
|
+
* have written is reported as unreadable, which is the honest state, and the
|
|
83
|
+
* `--reset` advice follows the OWNERSHIP of the value rather than this
|
|
84
|
+
* spelling (see `harness-compact-threshold-ensure.ts`).
|
|
85
|
+
*
|
|
86
|
+
* Two spellings matter for ownership, not for the band:
|
|
87
|
+
* - a lone `0`: `String(0)` is `0`, so `0` IS a spelling peaks-loop can
|
|
88
|
+
* emit. Paired with its own marker it is `peaks-corrupt` (out of band,
|
|
89
|
+
* removable), which is why it must parse here.
|
|
90
|
+
* - a leading zero (`080`): `String(80)` never emits one, so it is NOT a
|
|
91
|
+
* spelling peaks-loop writes — it must not parse to `80` (that let it equal
|
|
92
|
+
* its marker and be overwritten). It is also not evidence of a takeover:
|
|
93
|
+
* beside a VALID marker `80` it is peaks-loop's own `80` mangled afterwards,
|
|
94
|
+
* so `isHarnessPercentRemovable` classifies it `peaks-corrupt` through the
|
|
95
|
+
* marker-parses arm, never `human`.
|
|
96
|
+
*/
|
|
97
|
+
const PLAIN_PERCENT_SPELLING = /^(?:0|[1-9]\d*)$/;
|
|
98
|
+
/** In the harness's percent band AND a whole number. */
|
|
99
|
+
function isPercentInBand(value) {
|
|
100
|
+
return (Number.isInteger(value) &&
|
|
101
|
+
value >= HARNESS_COMPACT_PERCENT_MIN &&
|
|
102
|
+
value <= HARNESS_COMPACT_PERCENT_MAX);
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Parse a candidate percent. Whole integers 1..100 only (a number, or the
|
|
106
|
+
* numeric string a JSON `env` block always carries, in the plain decimal
|
|
107
|
+
* spelling `PLAIN_PERCENT_SPELLING` requires). Anything else — `0`, `101`,
|
|
108
|
+
* `80.5`, `80.0`, `8e1`, `'abc'`, `''`, `null` — is null, so callers can
|
|
109
|
+
* distinguish "absent" from "unusable" via the RAW value.
|
|
110
|
+
*/
|
|
111
|
+
export function parseHarnessCompactPercent(raw) {
|
|
112
|
+
if (typeof raw === 'number')
|
|
113
|
+
return isPercentInBand(raw) ? raw : null;
|
|
114
|
+
if (typeof raw !== 'string')
|
|
115
|
+
return null;
|
|
116
|
+
const text = raw.trim();
|
|
117
|
+
if (!PLAIN_PERCENT_SPELLING.test(text))
|
|
118
|
+
return null;
|
|
119
|
+
const parsed = Number(text);
|
|
120
|
+
return isPercentInBand(parsed) ? parsed : null;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* THE WRITER'S OWNERSHIP PREDICATE — strict, and deliberately NOT the one the
|
|
124
|
+
* rollback uses. See `percentOwnershipOf` for the pair.
|
|
125
|
+
*
|
|
126
|
+
* A value is the writer's to OVERWRITE only when `HARNESS_PERCENT_WRITTEN_KEY`
|
|
127
|
+
* is present and BOTH sides parse to the same number.
|
|
128
|
+
*
|
|
129
|
+
* The asymmetry with `isHarnessPercentRemovable` is the point. Removing a value
|
|
130
|
+
* deserves a wider rule than overwriting one: `--reset` is the documented
|
|
131
|
+
* recovery from a broken value and the user asked for it, while a probe or an
|
|
132
|
+
* init rewriting a value it cannot read would destroy the raw text the user
|
|
133
|
+
* needs in order to see what went wrong. Widening THIS predicate is how a
|
|
134
|
+
* background probe would silently replace a human's `eighty` — the exact
|
|
135
|
+
* "peaks-loop overruled my setting" failure the provenance marker exists to
|
|
136
|
+
* prevent.
|
|
137
|
+
*/
|
|
138
|
+
export function isHarnessPercentPeaksOwned(input) {
|
|
139
|
+
const file = parseHarnessCompactPercent(input.fileRaw);
|
|
140
|
+
const marker = parseHarnessCompactPercent(input.markerRaw);
|
|
141
|
+
return file !== null && marker === file;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* THE ROLLBACK'S OWNERSHIP PREDICATE — what `--reset` may REMOVE.
|
|
145
|
+
*
|
|
146
|
+
* Wider than `isHarnessPercentPeaksOwned` by exactly ONE shape, which proves the
|
|
147
|
+
* value is a corruption of peaks-loop's own write rather than a human pin: the
|
|
148
|
+
* marker parses while the VALUE does not. peaks-loop only ever writes
|
|
149
|
+
* `String(n)` as its marker (a plain in-band integer), so a VALID numeric
|
|
150
|
+
* marker beside an unreadable value can only be its own write mangled
|
|
151
|
+
* afterwards — and that is the documented `--reset` recovery.
|
|
152
|
+
*
|
|
153
|
+
* No marker ⇒ human. A parseable value that differs from a parseable marker ⇒
|
|
154
|
+
* human takeover. A marker that does not parse is NOT evidence of ownership in
|
|
155
|
+
* any combination: an unreadable value beside it is the user's own (even when
|
|
156
|
+
* the two strings are equal — a human who typed the same typo into both rows
|
|
157
|
+
* proved nothing about peaks-loop), and it is KEPT. The earlier "both raws are
|
|
158
|
+
* equal and unreadable" arm classified that pair `peaks-corrupt` and `--reset`
|
|
159
|
+
* deleted a user value; it is gone.
|
|
160
|
+
*/
|
|
161
|
+
export function isHarnessPercentRemovable(input) {
|
|
162
|
+
if (input.fileRaw === undefined || input.markerRaw === undefined)
|
|
163
|
+
return false;
|
|
164
|
+
const file = parseHarnessCompactPercent(input.fileRaw);
|
|
165
|
+
const marker = parseHarnessCompactPercent(input.markerRaw);
|
|
166
|
+
if (file !== null)
|
|
167
|
+
return marker === file;
|
|
168
|
+
return marker !== null;
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Classify one (value, marker) pair — the single answer to "may `--reset`
|
|
172
|
+
* remove this, and what do we call it?".
|
|
173
|
+
*/
|
|
174
|
+
export function percentOwnershipOf(input) {
|
|
175
|
+
if (input.fileRaw === undefined && input.markerRaw === undefined)
|
|
176
|
+
return 'none';
|
|
177
|
+
if (input.fileRaw === undefined)
|
|
178
|
+
return 'stale-marker';
|
|
179
|
+
if (!isHarnessPercentRemovable(input))
|
|
180
|
+
return 'human';
|
|
181
|
+
return parseHarnessCompactPercent(input.fileRaw) === null ? 'peaks-corrupt' : 'peaks';
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Read the percent half of the pair — the state-report counterpart of
|
|
185
|
+
* `readHarnessWindowState`, so `peaks compact harness-window` can show BOTH
|
|
186
|
+
* knobs it manages rather than only the window.
|
|
187
|
+
*/
|
|
188
|
+
export function readHarnessPercentState(settingsPath, percentKey) {
|
|
189
|
+
const settings = readSettingsObject(settingsPath);
|
|
190
|
+
const raw = settingsEnvValue(settings, percentKey);
|
|
191
|
+
const markerRaw = settingsEnvValue(settings, HARNESS_PERCENT_WRITTEN_KEY);
|
|
192
|
+
// The raw value is bounded HERE, at the point it would leave the module:
|
|
193
|
+
// deciding it once, at the source, means no caller can forget to map it.
|
|
194
|
+
return {
|
|
195
|
+
key: percentKey,
|
|
196
|
+
...(raw === undefined ? {} : { rawNote: boundedRawNote(raw) }),
|
|
197
|
+
percent: parseHarnessCompactPercent(raw),
|
|
198
|
+
ownership: percentOwnershipOf({ fileRaw: raw, markerRaw })
|
|
199
|
+
};
|
|
200
|
+
}
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The harness settings file, as a JSON object — the small shared read layer the
|
|
3
|
+
* threshold modules sit on.
|
|
4
|
+
*
|
|
5
|
+
* Why it is its own module: three of them (`-config`, `-verdict`, `-reset`) read
|
|
6
|
+
* the same file and must answer "cannot read it" identically. One copy here is
|
|
7
|
+
* what keeps a fourth reader from disagreeing about a corrupt file, and it is
|
|
8
|
+
* also what keeps each of those modules under the file-size cap.
|
|
9
|
+
*
|
|
10
|
+
* The READER is not a second copy. `readSettingsObject` and its shape already
|
|
11
|
+
* live in `harness-window-config.ts`, which had to answer the same question for
|
|
12
|
+
* the window sync; this module re-exports that one implementation so a corrupt
|
|
13
|
+
* file cannot be "readable" to one caller and "unreadable" to another. The
|
|
14
|
+
* helpers below are the threshold-specific view of it.
|
|
15
|
+
*
|
|
16
|
+
* Vendor neutrality: this knows about a JSON file with an `env` block and
|
|
17
|
+
* nothing else. The path and every key name are the caller's.
|
|
18
|
+
*/
|
|
19
|
+
import { readSettingsObject, type SettingsFileShape } from './harness-window-config.js';
|
|
20
|
+
export { readSettingsObject };
|
|
21
|
+
export type { SettingsFileShape };
|
|
22
|
+
/**
|
|
23
|
+
* True when the settings path, or the DIRECTORY holding it, is a LINK (a
|
|
24
|
+
* symlink, or on Windows a junction — `lstat` reports both as
|
|
25
|
+
* `isSymbolicLink()`), which none of this slice's writers may write through.
|
|
26
|
+
*
|
|
27
|
+
* RE-EXPORTED, not re-implemented, from `../ide/shared/safe-path.ts` — the
|
|
28
|
+
* module that already owns settings-path safety (`assertSafeSettingsFile`) — so
|
|
29
|
+
* there is one spelling of "what is a link" and every threshold module reaches
|
|
30
|
+
* it through here, with no import cycle. See that module for why the directory
|
|
31
|
+
* is checked as well as the file, and why an absent path still counts as
|
|
32
|
+
* writable.
|
|
33
|
+
*/
|
|
34
|
+
export { isLinkedSettingsFile } from '../ide/shared/safe-path.js';
|
|
35
|
+
/**
|
|
36
|
+
* True when the file is absent (editable) or a parseable JSON object.
|
|
37
|
+
*
|
|
38
|
+
* Exported because the reset path has to ask the same question before it
|
|
39
|
+
* decides a file is "unreadable and therefore untouchable" rather than
|
|
40
|
+
* "carrying nothing of peaks-loop's".
|
|
41
|
+
*/
|
|
42
|
+
export declare function isEditableSettingsFile(settingsPath: string): boolean;
|
|
43
|
+
/** The `env` object of a parsed settings file, or `{}` — never a shared reference. */
|
|
44
|
+
export declare function envBlock(settings: SettingsFileShape | null): Record<string, unknown>;
|
|
45
|
+
/** One key out of a parsed settings file's `env` block; `undefined` when absent. */
|
|
46
|
+
export declare function settingsEnvValue(settings: SettingsFileShape | null, key: string): unknown;
|
|
47
|
+
/** `was X` for a value that was there, nothing when it was not. */
|
|
48
|
+
export declare function wasValue(value: number | null): string;
|
|
49
|
+
/**
|
|
50
|
+
* The MED-2 bounded vocabulary (see `harness-percent-ownership.ts`), re-exported
|
|
51
|
+
* so every caller reaches it through one path.
|
|
52
|
+
*
|
|
53
|
+
* THE INVARIANT IS STRUCTURAL, NOT A MAPPER'S JOB. Every service-layer result in
|
|
54
|
+
* this slice that can carry text read from the settings file carries a bounded
|
|
55
|
+
* NOTE (`previousRawNote` / `rawNote` / `windowRawNote` …) computed where the
|
|
56
|
+
* value is read. A result that never holds the plaintext cannot leak it,
|
|
57
|
+
* whichever consumer logs or persists it.
|
|
58
|
+
*/
|
|
59
|
+
export { isPlainIntegerSpelling, boundedRawNote } from './harness-percent-ownership.js';
|
|
60
|
+
/**
|
|
61
|
+
* How a removed percent half is named — the number when it was one, and a
|
|
62
|
+
* fixed BOUNDED phrase (never the raw string, MED-2) when it was not.
|
|
63
|
+
*/
|
|
64
|
+
export declare function percentClause(percent: {
|
|
65
|
+
readonly key: string;
|
|
66
|
+
readonly ownership: string;
|
|
67
|
+
readonly previousPercent: number | null;
|
|
68
|
+
}): string;
|
|
69
|
+
/** The one sentence for a rollback that found nothing of peaks-loop's. */
|
|
70
|
+
export declare function nothingToRemoveSentence(settingsPath: string, windowKey: string, percentKey: string): string;
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The harness settings file, as a JSON object — the small shared read layer the
|
|
3
|
+
* threshold modules sit on.
|
|
4
|
+
*
|
|
5
|
+
* Why it is its own module: three of them (`-config`, `-verdict`, `-reset`) read
|
|
6
|
+
* the same file and must answer "cannot read it" identically. One copy here is
|
|
7
|
+
* what keeps a fourth reader from disagreeing about a corrupt file, and it is
|
|
8
|
+
* also what keeps each of those modules under the file-size cap.
|
|
9
|
+
*
|
|
10
|
+
* The READER is not a second copy. `readSettingsObject` and its shape already
|
|
11
|
+
* live in `harness-window-config.ts`, which had to answer the same question for
|
|
12
|
+
* the window sync; this module re-exports that one implementation so a corrupt
|
|
13
|
+
* file cannot be "readable" to one caller and "unreadable" to another. The
|
|
14
|
+
* helpers below are the threshold-specific view of it.
|
|
15
|
+
*
|
|
16
|
+
* Vendor neutrality: this knows about a JSON file with an `env` block and
|
|
17
|
+
* nothing else. The path and every key name are the caller's.
|
|
18
|
+
*/
|
|
19
|
+
import { existsSync } from 'node:fs';
|
|
20
|
+
import { readSettingsObject } from './harness-window-config.js';
|
|
21
|
+
export { readSettingsObject };
|
|
22
|
+
/**
|
|
23
|
+
* True when the settings path, or the DIRECTORY holding it, is a LINK (a
|
|
24
|
+
* symlink, or on Windows a junction — `lstat` reports both as
|
|
25
|
+
* `isSymbolicLink()`), which none of this slice's writers may write through.
|
|
26
|
+
*
|
|
27
|
+
* RE-EXPORTED, not re-implemented, from `../ide/shared/safe-path.ts` — the
|
|
28
|
+
* module that already owns settings-path safety (`assertSafeSettingsFile`) — so
|
|
29
|
+
* there is one spelling of "what is a link" and every threshold module reaches
|
|
30
|
+
* it through here, with no import cycle. See that module for why the directory
|
|
31
|
+
* is checked as well as the file, and why an absent path still counts as
|
|
32
|
+
* writable.
|
|
33
|
+
*/
|
|
34
|
+
export { isLinkedSettingsFile } from '../ide/shared/safe-path.js';
|
|
35
|
+
/**
|
|
36
|
+
* True when the file is absent (editable) or a parseable JSON object.
|
|
37
|
+
*
|
|
38
|
+
* Exported because the reset path has to ask the same question before it
|
|
39
|
+
* decides a file is "unreadable and therefore untouchable" rather than
|
|
40
|
+
* "carrying nothing of peaks-loop's".
|
|
41
|
+
*/
|
|
42
|
+
export function isEditableSettingsFile(settingsPath) {
|
|
43
|
+
if (!existsSync(settingsPath))
|
|
44
|
+
return true;
|
|
45
|
+
return readSettingsObject(settingsPath) !== null;
|
|
46
|
+
}
|
|
47
|
+
/** The `env` object of a parsed settings file, or `{}` — never a shared reference. */
|
|
48
|
+
export function envBlock(settings) {
|
|
49
|
+
const env = settings?.env;
|
|
50
|
+
return typeof env === 'object' && env !== null && !Array.isArray(env) ? env : {};
|
|
51
|
+
}
|
|
52
|
+
/** One key out of a parsed settings file's `env` block; `undefined` when absent. */
|
|
53
|
+
export function settingsEnvValue(settings, key) {
|
|
54
|
+
return envBlock(settings)[key];
|
|
55
|
+
}
|
|
56
|
+
/** `was X` for a value that was there, nothing when it was not. */
|
|
57
|
+
export function wasValue(value) {
|
|
58
|
+
return value === null ? '' : ` (was ${String(value)})`;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* The MED-2 bounded vocabulary (see `harness-percent-ownership.ts`), re-exported
|
|
62
|
+
* so every caller reaches it through one path.
|
|
63
|
+
*
|
|
64
|
+
* THE INVARIANT IS STRUCTURAL, NOT A MAPPER'S JOB. Every service-layer result in
|
|
65
|
+
* this slice that can carry text read from the settings file carries a bounded
|
|
66
|
+
* NOTE (`previousRawNote` / `rawNote` / `windowRawNote` …) computed where the
|
|
67
|
+
* value is read. A result that never holds the plaintext cannot leak it,
|
|
68
|
+
* whichever consumer logs or persists it.
|
|
69
|
+
*/
|
|
70
|
+
export { isPlainIntegerSpelling, boundedRawNote } from './harness-percent-ownership.js';
|
|
71
|
+
/**
|
|
72
|
+
* How a removed percent half is named — the number when it was one, and a
|
|
73
|
+
* fixed BOUNDED phrase (never the raw string, MED-2) when it was not.
|
|
74
|
+
*/
|
|
75
|
+
export function percentClause(percent) {
|
|
76
|
+
return percent.ownership === 'peaks-corrupt'
|
|
77
|
+
? `${percent.key} (held a value that is not a percentage, not echoed here)`
|
|
78
|
+
: `${percent.key}${wasValue(percent.previousPercent)}`;
|
|
79
|
+
}
|
|
80
|
+
/** The one sentence for a rollback that found nothing of peaks-loop's. */
|
|
81
|
+
export function nothingToRemoveSentence(settingsPath, windowKey, percentKey) {
|
|
82
|
+
return `Nothing to remove — ${settingsPath} carries no ${windowKey}, no ${percentKey}, and no provenance marker peaks-loop wrote, so nothing was written and no opt-out row was recorded.`;
|
|
83
|
+
}
|