@yeison.restrepo.r/code-conductor 1.30.0 → 1.31.1
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/README.md +1 -0
- package/global/commands/cc-checkpoint.md +2 -0
- package/global/commands/cc-compact.md +17 -2
- package/package.json +1 -1
- package/project-template/.claude/commands/cc-implement.md +28 -0
- package/project-template/.claude/commands/cc-plan.md +37 -2
- package/scripts/conductor-db.mjs +1 -1
- package/scripts/resume-read.mjs +22 -12
- package/scripts/snap-build.mjs +4 -7
- package/scripts/snap-contract.mjs +39 -0
- package/scripts/snap-validate.mjs +8 -8
package/README.md
CHANGED
|
@@ -314,6 +314,7 @@ code-conductor/
|
|
|
314
314
|
├── scripts/
|
|
315
315
|
│ ├── conductor-db.mjs Zero-dep node:sqlite engine (.conductor/cache.db)
|
|
316
316
|
│ ├── resume-read.mjs Phase-entry resume reader (DB snapshot → handoff fallback)
|
|
317
|
+
│ ├── snap-contract.mjs SNAP limits, caps, field sets, version ceiling
|
|
317
318
|
│ ├── snap-build.mjs SNAP v1/v2 handoff serializer
|
|
318
319
|
│ ├── snap-validate.mjs SNAP schema validator
|
|
319
320
|
│ ├── session-id.mjs Stable session-id resolver
|
|
@@ -14,6 +14,8 @@ Identify and extract:
|
|
|
14
14
|
- Add a timestamped section: `## Checkpoint [YYYY-MM-DD HH:MM]`
|
|
15
15
|
- List decisions, conventions, and debt from this session
|
|
16
16
|
|
|
17
|
+
**Staging that update, where the workflow commits it:** stage by tracked-ness, with an explicit path. A `project.md` that is already tracked takes `git add -u ".claude/memory/project.md"`; one that is not yet tracked takes plain `git add ".claude/memory/project.md"`, or `git add -f` where the project ignores `.claude/`. **Never an unconditional `-u` here.** This command is global and also runs in freshly scaffolded projects, which do not ignore `.claude/` and whose `project.md` is not yet tracked: there `-u` exits 128 and would halt the checkpoint before its DB tail, trading a defect those projects never had for one they would.
|
|
18
|
+
|
|
17
19
|
**Update `.claude/memory/personal.md`** (local only):
|
|
18
20
|
- Add any developer preferences observed this session
|
|
19
21
|
|
|
@@ -35,12 +35,27 @@ Once the snapshot is written successfully, output exactly:
|
|
|
35
35
|
|
|
36
36
|
After the handoff file is written and the compact prompt is ready — and **only** if the authoritative write succeeded — run this synchronous, fail-open tail. Any failure here is non-fatal: never revert the handoff file, never suppress the compact prompt.
|
|
37
37
|
|
|
38
|
+
<!-- SESSION-ROW-TAIL:BEGIN -->
|
|
39
|
+
**Preconditions.** `c` is the full-40 `git rev-parse HEAD`, lowercased, matching `/^[0-9a-f]{7,40}$/`, `"0000000"` on any failure; `s` is the active spec stem or `"none"`. Both are derived exactly as this command's body already specifies.
|
|
40
|
+
|
|
38
41
|
1. Ensure `.conductor/` exists (`mkdir -p .conductor`, best-effort). If that fails, skip the tail entirely.
|
|
39
42
|
2. Resolve the session id: `id="$(node .claude/scripts/session-id.mjs 2>>.conductor/last-write.log)"`.
|
|
40
|
-
3.
|
|
43
|
+
3. Probe how to launch `node:sqlite`, the same probe the `cc-implement` Step 6 hook runs: no flag first, else `--experimental-sqlite --no-warnings`, else skip the write.
|
|
44
|
+
4. Upsert the session row. Every argv scalar is double-quoted, because a repository path can contain spaces:
|
|
41
45
|
|
|
42
46
|
`node <probe-flags> .claude/scripts/conductor-db.mjs session "$id" "$ph" "$s" "$c" >> .conductor/last-write.log 2>&1`
|
|
43
|
-
|
|
47
|
+
5. **Loud degrade.** If the probe skipped the write, or the write exited non-zero, append one line naming the reason:
|
|
48
|
+
|
|
49
|
+
`printf '%s\n' "CC_DB_TAIL: session row not written (<reason>)" >> .conductor/last-write.log`
|
|
50
|
+
|
|
51
|
+
A row that is simply absent is the shape that let the recorded phase go stale across two boundaries unnoticed. The absence is always reported.
|
|
52
|
+
|
|
53
|
+
Every redirect uses append mode (`>>`), never `>`, so a rapid or parallel second run never truncates a preceding trace. Any failure in this block is **non-fatal**: the command reports its normal outcome regardless.
|
|
54
|
+
|
|
55
|
+
**Cross-platform note.** The forms above are Unix-canonical; the `.md` file is an agent instruction, not a literal script. On Windows/PowerShell realize the same semantics: set `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)` first, capture `$id = node .claude/scripts/session-id.mjs`, and append the log with `… 2>&1 | Out-File -Append -Encoding utf8 .conductor/last-write.log`, never the bare `*>>`, whose default encoding is UTF-16LE on PS 5.1 and would corrupt the trace. Ensure the directory with `New-Item -ItemType Directory -Force .conductor`.
|
|
56
|
+
<!-- SESSION-ROW-TAIL:END -->
|
|
57
|
+
|
|
58
|
+
6. Insert the snapshot row, piping the v1 blob on **stdin** (never argv):
|
|
44
59
|
|
|
45
60
|
`printf '%s' "$snap_json" | node <probe-flags> .claude/scripts/conductor-db.mjs snapshot "$c" >> .conductor/last-write.log 2>&1`
|
|
46
61
|
|
package/package.json
CHANGED
|
@@ -162,3 +162,31 @@ After the hook: if the task state is `[!]`, halt with the failure report from St
|
|
|
162
162
|
---
|
|
163
163
|
|
|
164
164
|
Confirm between tasks unless the developer explicitly says to proceed without confirmation.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Phase exit - session row
|
|
169
|
+
|
|
170
|
+
Step 1 returned no `[ ]` match at `offset = 0`, so every task is complete and the
|
|
171
|
+
implementation phase has finished. Write that fact here, at its own boundary, after
|
|
172
|
+
the completion summary has been output.
|
|
173
|
+
|
|
174
|
+
<!-- SESSION-ROW-TAIL:BEGIN -->
|
|
175
|
+
**Preconditions.** `c` is the full-40 `git rev-parse HEAD`, lowercased, matching `/^[0-9a-f]{7,40}$/`, `"0000000"` on any failure; `s` is the active spec stem or `"none"`. Both are derived exactly as this command's body already specifies.
|
|
176
|
+
|
|
177
|
+
1. Ensure `.conductor/` exists (`mkdir -p .conductor`, best-effort). If that fails, skip the tail entirely.
|
|
178
|
+
2. Resolve the session id: `id="$(node .claude/scripts/session-id.mjs 2>>.conductor/last-write.log)"`.
|
|
179
|
+
3. Probe how to launch `node:sqlite`, the same probe the `cc-implement` Step 6 hook runs: no flag first, else `--experimental-sqlite --no-warnings`, else skip the write.
|
|
180
|
+
4. Upsert the session row. Every argv scalar is double-quoted, because a repository path can contain spaces:
|
|
181
|
+
|
|
182
|
+
`node <probe-flags> .claude/scripts/conductor-db.mjs session "$id" "impl" "$s" "$c" >> .conductor/last-write.log 2>&1`
|
|
183
|
+
5. **Loud degrade.** If the probe skipped the write, or the write exited non-zero, append one line naming the reason:
|
|
184
|
+
|
|
185
|
+
`printf '%s\n' "CC_DB_TAIL: session row not written (<reason>)" >> .conductor/last-write.log`
|
|
186
|
+
|
|
187
|
+
A row that is simply absent is the shape that let the recorded phase go stale across two boundaries unnoticed. The absence is always reported.
|
|
188
|
+
|
|
189
|
+
Every redirect uses append mode (`>>`), never `>`, so a rapid or parallel second run never truncates a preceding trace. Any failure in this block is **non-fatal**: the command reports its normal outcome regardless.
|
|
190
|
+
|
|
191
|
+
**Cross-platform note.** The forms above are Unix-canonical; the `.md` file is an agent instruction, not a literal script. On Windows/PowerShell realize the same semantics: set `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)` first, capture `$id = node .claude/scripts/session-id.mjs`, and append the log with `… 2>&1 | Out-File -Append -Encoding utf8 .conductor/last-write.log`, never the bare `*>>`, whose default encoding is UTF-16LE on PS 5.1 and would corrupt the trace. Ensure the directory with `New-Item -ItemType Directory -Force .conductor`.
|
|
192
|
+
<!-- SESSION-ROW-TAIL:END -->
|
|
@@ -98,6 +98,13 @@ Each step must include:
|
|
|
98
98
|
order, so a staging step placed above its edit commits the file's previous content while
|
|
99
99
|
every checkbox still reports `[X]`, and the divergence surfaces only at whatever later task
|
|
100
100
|
asserts on that file's expected state, pointing at the wrong task.
|
|
101
|
+
- **Staging form within a step.** Where a staged path sits under a directory the repository
|
|
102
|
+
ignores, plain `git add <path>` exits 1 even when a tracked file staged correctly, because
|
|
103
|
+
the pathspec matched the ignored ancestor. Generate `git add -u <path>` when the file is
|
|
104
|
+
already tracked, `git add -f <path>` when it is new and under an ignored directory, and
|
|
105
|
+
plain `git add <path>` otherwise. Always generate an explicit path: bare `git add -u`
|
|
106
|
+
stages every modified tracked file in the repository. The branch is on tracked-ness, never
|
|
107
|
+
on habit, because `-u` exits 128 on an untracked path whether or not an ignore rule exists.
|
|
101
108
|
|
|
102
109
|
## Test List
|
|
103
110
|
- [ ] Unit tests for [unit]
|
|
@@ -125,8 +132,8 @@ instruction in step 7.
|
|
|
125
132
|
|
|
126
133
|
**Precondition on Task 0.** This gate runs to completion — the warning, the offer, and
|
|
127
134
|
either the confirmed `git switch` or an explicit decline —
|
|
128
|
-
**before any step of the approved plan's Task 0 executes**, including its `git add
|
|
129
|
-
`git add -f` and its `git commit`. Its position in this file is not the guarantee; the
|
|
135
|
+
**before any step of the approved plan's Task 0 executes**, including its `git add`,
|
|
136
|
+
`git add -u` or `git add -f` and its `git commit`. Its position in this file is not the guarantee; the
|
|
130
137
|
execution order is.
|
|
131
138
|
Under the plan-commit ritual, Task 0 runs at approval, which is exactly when a plan commit
|
|
132
139
|
lands on the wrong branch.
|
|
@@ -225,3 +232,31 @@ subject.
|
|
|
225
232
|
> "Plan complete. Run `/cc-compact` now before starting implementation."
|
|
226
233
|
|
|
227
234
|
Do not proceed to implementation without user confirmation that `/cc-compact` has been run.
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## Phase exit - session row
|
|
239
|
+
|
|
240
|
+
The plan phase has completed, which is the only moment at which "phase `plan` just
|
|
241
|
+
finished" is a fact rather than a deduction. Write it here, at its own boundary.
|
|
242
|
+
Run this after step 7's exit instruction has been printed.
|
|
243
|
+
|
|
244
|
+
<!-- SESSION-ROW-TAIL:BEGIN -->
|
|
245
|
+
**Preconditions.** `c` is the full-40 `git rev-parse HEAD`, lowercased, matching `/^[0-9a-f]{7,40}$/`, `"0000000"` on any failure; `s` is the active spec stem or `"none"`. Both are derived exactly as this command's body already specifies.
|
|
246
|
+
|
|
247
|
+
1. Ensure `.conductor/` exists (`mkdir -p .conductor`, best-effort). If that fails, skip the tail entirely.
|
|
248
|
+
2. Resolve the session id: `id="$(node .claude/scripts/session-id.mjs 2>>.conductor/last-write.log)"`.
|
|
249
|
+
3. Probe how to launch `node:sqlite`, the same probe the `cc-implement` Step 6 hook runs: no flag first, else `--experimental-sqlite --no-warnings`, else skip the write.
|
|
250
|
+
4. Upsert the session row. Every argv scalar is double-quoted, because a repository path can contain spaces:
|
|
251
|
+
|
|
252
|
+
`node <probe-flags> .claude/scripts/conductor-db.mjs session "$id" "plan" "$s" "$c" >> .conductor/last-write.log 2>&1`
|
|
253
|
+
5. **Loud degrade.** If the probe skipped the write, or the write exited non-zero, append one line naming the reason:
|
|
254
|
+
|
|
255
|
+
`printf '%s\n' "CC_DB_TAIL: session row not written (<reason>)" >> .conductor/last-write.log`
|
|
256
|
+
|
|
257
|
+
A row that is simply absent is the shape that let the recorded phase go stale across two boundaries unnoticed. The absence is always reported.
|
|
258
|
+
|
|
259
|
+
Every redirect uses append mode (`>>`), never `>`, so a rapid or parallel second run never truncates a preceding trace. Any failure in this block is **non-fatal**: the command reports its normal outcome regardless.
|
|
260
|
+
|
|
261
|
+
**Cross-platform note.** The forms above are Unix-canonical; the `.md` file is an agent instruction, not a literal script. On Windows/PowerShell realize the same semantics: set `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)` first, capture `$id = node .claude/scripts/session-id.mjs`, and append the log with `… 2>&1 | Out-File -Append -Encoding utf8 .conductor/last-write.log`, never the bare `*>>`, whose default encoding is UTF-16LE on PS 5.1 and would corrupt the trace. Ensure the directory with `New-Item -ItemType Directory -Force .conductor`.
|
|
262
|
+
<!-- SESSION-ROW-TAIL:END -->
|
package/scripts/conductor-db.mjs
CHANGED
|
@@ -15,6 +15,7 @@ import { execFileSync } from 'node:child_process';
|
|
|
15
15
|
import { mkdirSync, existsSync, renameSync, unlinkSync, statSync, readSync } from 'node:fs';
|
|
16
16
|
import { dirname, basename, join, resolve, relative, sep } from 'node:path';
|
|
17
17
|
import { fileURLToPath } from 'node:url';
|
|
18
|
+
import { PRE_PARSE_MAX_BYTES as MAX_SNAP_BYTES } from './snap-contract.mjs';
|
|
18
19
|
|
|
19
20
|
const PREFIX = 'CONDUCTOR_DB:';
|
|
20
21
|
const warn = (m) => process.stderr.write(`${PREFIX} ${m}\n`);
|
|
@@ -24,7 +25,6 @@ const MAX_KEY_LEN = 512;
|
|
|
24
25
|
const WALK_CAP = 40;
|
|
25
26
|
const USAGE = "usage: conductor-db.mjs record <plan_file> <task_id> <state> | init";
|
|
26
27
|
const SCHEMA_VERSION = 2;
|
|
27
|
-
const MAX_SNAP_BYTES = 10 * 1024 * 1024; // 10 MiB
|
|
28
28
|
const MAX_CONTENT_BYTES = 1024 * 1024; // 1 MiB
|
|
29
29
|
const STDIN_CHUNK = 65536;
|
|
30
30
|
|
package/scripts/resume-read.mjs
CHANGED
|
@@ -57,10 +57,17 @@ function resolveHash() {
|
|
|
57
57
|
return SENTINEL;
|
|
58
58
|
}
|
|
59
59
|
|
|
60
|
-
//
|
|
60
|
+
// snap-validate writes one `SNAP_ERROR: ...` line per rejection; the first is the cause.
|
|
61
|
+
function reasonOf(r) {
|
|
62
|
+
const first = String(r.stderr || '').trim().split('\n')[0];
|
|
63
|
+
return first || ('validator exit ' + r.status);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// Validate an existing file path via snap-validate. Returns the verdict AND the
|
|
67
|
+
// validator's own reason, so a degrade can name what was wrong (BUG-038).
|
|
61
68
|
function validateFile(p) {
|
|
62
69
|
const r = spawnSync(process.execPath, [VALIDATE, p], { encoding: 'utf8', env: process.env });
|
|
63
|
-
return r.status === 0;
|
|
70
|
+
return { ok: r.status === 0, reason: reasonOf(r) };
|
|
64
71
|
}
|
|
65
72
|
|
|
66
73
|
// Probe how to launch node:sqlite. Returns [] (no flag), ['--experimental-sqlite','--no-warnings'], or null (unavailable).
|
|
@@ -77,10 +84,10 @@ function probeSqliteFlags() {
|
|
|
77
84
|
function validateBlob(blob) {
|
|
78
85
|
const tmp = join(COND, 'resume-validate.' + process.pid + '.tmp.json');
|
|
79
86
|
try { mkdirSync(COND, { recursive: true }); writeFileSync(tmp, blob, 'utf8'); }
|
|
80
|
-
catch { return false; } // FS write error
|
|
87
|
+
catch { return { ok: false, reason: 'temp write failed' }; } // FS write error, blob unusable
|
|
81
88
|
try {
|
|
82
89
|
const r = spawnSync(process.execPath, [VALIDATE, tmp], { encoding: 'utf8', env: process.env });
|
|
83
|
-
return r.status === 0;
|
|
90
|
+
return { ok: r.status === 0, reason: reasonOf(r) };
|
|
84
91
|
} finally { tryUnlink(tmp); }
|
|
85
92
|
}
|
|
86
93
|
|
|
@@ -91,15 +98,17 @@ function queryDb(hash) {
|
|
|
91
98
|
return null;
|
|
92
99
|
}
|
|
93
100
|
const flags = probeSqliteFlags();
|
|
94
|
-
if (flags === null)
|
|
101
|
+
if (flags === null) { trace('db-unavailable degrade: node:sqlite absent'); return null; }
|
|
95
102
|
const args = flags.concat([CONDUCTOR_DB, 'get-snapshot', hash]);
|
|
96
103
|
const r = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: 5000, env: process.env });
|
|
97
|
-
if (r.status !== 0
|
|
104
|
+
if (r.status !== 0) { trace('db-query degrade: get-snapshot exit ' + r.status); return null; }
|
|
105
|
+
if (!r.stdout) return null; // no row for this hash is an ordinary miss, not a rejection
|
|
98
106
|
const blob = r.stdout.trim();
|
|
99
107
|
if (blob === '') return null;
|
|
100
|
-
|
|
108
|
+
const verdict = validateBlob(blob);
|
|
109
|
+
if (!verdict.ok) { trace('db-invalid degrade: ' + verdict.reason); return null; }
|
|
101
110
|
const snap = parseJson(blob);
|
|
102
|
-
if (snap === undefined) { trace('db-invalid degrade'); return null; }
|
|
111
|
+
if (snap === undefined) { trace('db-invalid degrade: unparseable after validation'); return null; }
|
|
103
112
|
return snap;
|
|
104
113
|
}
|
|
105
114
|
|
|
@@ -141,12 +150,13 @@ function main() {
|
|
|
141
150
|
if (!existsSync(HANDOFF)) { trace('miss'); return { code: 3, out: '' }; }
|
|
142
151
|
let content;
|
|
143
152
|
try { content = readFileSync(HANDOFF, 'utf8'); }
|
|
144
|
-
catch { trace('file-unreadable degrade'); return { code: 3, out: '' }; } // leave file on disk
|
|
153
|
+
catch (e) { trace('file-unreadable degrade: ' + ((e && e.code) || 'unknown')); return { code: 3, out: '' }; } // leave file on disk
|
|
145
154
|
if (content.trim() === '') { trace('file-empty degrade'); tryUnlink(HANDOFF); return { code: 3, out: '' }; }
|
|
146
|
-
|
|
155
|
+
const fileVerdict = validateFile(HANDOFF);
|
|
156
|
+
if (!fileVerdict.ok) { trace('file-invalid halt: ' + fileVerdict.reason); return { code: 4, out: '' }; } // leave on disk
|
|
147
157
|
const snap = parseJson(content);
|
|
148
|
-
if (snap === undefined) { trace('file-invalid halt'); return { code: 4, out: '' }; }
|
|
149
|
-
if (snap.sys.c !== hash) { trace('file-stale-hash degrade'); tryUnlink(HANDOFF); return { code: 3, out: '' }; }
|
|
158
|
+
if (snap === undefined) { trace('file-invalid halt: unparseable after validation'); return { code: 4, out: '' }; }
|
|
159
|
+
if (snap.sys.c !== hash) { trace('file-stale-hash degrade: ' + snap.sys.c + ' != ' + hash); tryUnlink(HANDOFF); return { code: 3, out: '' }; }
|
|
150
160
|
// valid + hash matches → bind (content already captured), then unlink.
|
|
151
161
|
const out = buildHit('file', snap, hash);
|
|
152
162
|
trace('file-bind+unlink');
|
package/scripts/snap-build.mjs
CHANGED
|
@@ -1,8 +1,5 @@
|
|
|
1
1
|
import { readFileSync } from 'node:fs';
|
|
2
|
-
|
|
3
|
-
const MAX_SNAP_BYTES = 10485760; // 10 MiB (v2)
|
|
4
|
-
const V1_MAX_CHARS = 4096; // handoff-file contract (v1)
|
|
5
|
-
const CAPS = { n: [3, 200], f: [20, 300], d: [10, 300], x: [5, 200] };
|
|
2
|
+
import { CAPS, PRE_PARSE_MAX_BYTES as MAX_SNAP_BYTES, V1_MAX_CHARS } from './snap-contract.mjs';
|
|
6
3
|
|
|
7
4
|
const die = (msg) => { process.stderr.write(`SNAP_BUILD_ERROR: ${msg}\n`); process.exit(1); };
|
|
8
5
|
const byteLen = (s) => Buffer.byteLength(s, 'utf8');
|
|
@@ -48,12 +45,12 @@ for (const k of ['ph', 'c', 's']) {
|
|
|
48
45
|
}
|
|
49
46
|
|
|
50
47
|
const sys = { ph: obj.ph, c: obj.c, s: obj.s };
|
|
51
|
-
const ops = { n: normArray(obj.n, CAPS.n), f: normArray(obj.f, CAPS.f) };
|
|
52
|
-
const mem = { d: normArray(obj.d, CAPS.d), x: normArray(obj.x, CAPS.x) };
|
|
48
|
+
const ops = { n: normArray(obj.n, CAPS['ops.n']), f: normArray(obj.f, CAPS['ops.f']) };
|
|
49
|
+
const mem = { d: normArray(obj.d, CAPS['mem.d']), x: normArray(obj.x, CAPS['mem.x']) };
|
|
53
50
|
const pr = typeof obj.pr === 'string' ? obj.pr : '';
|
|
54
51
|
|
|
55
52
|
if (pr === '') {
|
|
56
|
-
// ---- v1:
|
|
53
|
+
// ---- v1: V1_MAX_CHARS cap, drop oldest of mem.d / ops.f ----
|
|
57
54
|
const snap = { v: 1, sys, ops, mem };
|
|
58
55
|
let line = JSON.stringify(snap);
|
|
59
56
|
while (line.length > V1_MAX_CHARS && (mem.d.length || ops.f.length)) {
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
// scripts/snap-contract.mjs
|
|
2
|
+
// The handoff contract: every limit, array cap, field set and version the SNAP
|
|
3
|
+
// envelope is defined by. snap-build.mjs (writer), snap-validate.mjs (validator)
|
|
4
|
+
// and conductor-db.mjs (store) all import from here, so a literal on one side
|
|
5
|
+
// cannot drift from the other. Zero dependencies, node: builtins only.
|
|
6
|
+
|
|
7
|
+
// Hard pre-parse ceiling: the largest any version may legitimately be. Applied
|
|
8
|
+
// before JSON.parse, whatever version the payload claims, so a hostile or
|
|
9
|
+
// corrupt file cannot exhaust memory through the parser.
|
|
10
|
+
export const PRE_PARSE_MAX_BYTES = 10485760; // 10 MiB
|
|
11
|
+
|
|
12
|
+
// The v1 context budget for .claude/memory/session-snapshot.json, a file whose
|
|
13
|
+
// whole purpose is to be read into a session. Not a drifted literal: a real
|
|
14
|
+
// constraint, kept under its own name.
|
|
15
|
+
export const V1_MAX_CHARS = 4096;
|
|
16
|
+
|
|
17
|
+
// Post-parse, version-specific caps, applied once snap.v is known. For v2 the
|
|
18
|
+
// two tiers coincide; they separate the moment a v3 arrives with its own budget.
|
|
19
|
+
export const POST_PARSE_MAX = { 1: V1_MAX_CHARS, 2: PRE_PARSE_MAX_BYTES };
|
|
20
|
+
|
|
21
|
+
// Highest v this contract understands. Raising it here moves the
|
|
22
|
+
// SNAP_UNKNOWN_VERSION boundary with no edit anywhere else.
|
|
23
|
+
export const MAX_VERSION = 2;
|
|
24
|
+
|
|
25
|
+
// One array-cap table in ONE key scheme: dotted path to [count cap, element cap].
|
|
26
|
+
// Two schemes for one table is how a drift hides from every diff and grep.
|
|
27
|
+
export const CAPS = {
|
|
28
|
+
'ops.n': [3, 200],
|
|
29
|
+
'ops.f': [20, 300],
|
|
30
|
+
'mem.d': [10, 300],
|
|
31
|
+
'mem.x': [5, 200],
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
// Field sets. Top-level is per version; block members are version-invariant.
|
|
35
|
+
export const TOP_FIELDS = {
|
|
36
|
+
1: ['v', 'sys', 'ops', 'mem'],
|
|
37
|
+
2: ['v', 'sys', 'ops', 'mem', 'pr'],
|
|
38
|
+
};
|
|
39
|
+
export const BLOCK_FIELDS = { sys: ['ph', 'c', 's'], ops: ['n', 'f'], mem: ['d', 'x'] };
|
|
@@ -1,25 +1,25 @@
|
|
|
1
|
-
import { readFileSync } from 'node:fs';
|
|
1
|
+
import { readFileSync } from 'node:fs'; import { BLOCK_FIELDS, CAPS, MAX_VERSION, POST_PARSE_MAX, PRE_PARSE_MAX_BYTES, TOP_FIELDS } from './snap-contract.mjs';
|
|
2
2
|
const err = (m) => { process.stderr.write(`SNAP_ERROR: ${m}\n`); process.exit(1); };
|
|
3
3
|
const path = process.argv[2]; if (path === undefined) err('no path provided');
|
|
4
4
|
let raw; try { raw = readFileSync(path, 'utf8'); } catch (e) { err(e.code === 'ENOENT' ? 'file not found' : e.code); }
|
|
5
5
|
if (raw.includes('�')) err('encoding error');
|
|
6
6
|
const trimmed = raw.trim(); if (trimmed.includes('\n')) err('internal newline in payload');
|
|
7
|
-
if (trimmed === '') err('empty file');
|
|
7
|
+
if (trimmed === '') err('empty file');
|
|
8
|
+
if (raw.length > PRE_PARSE_MAX_BYTES) err(`payload too large: ${raw.length} > ${PRE_PARSE_MAX_BYTES} (pre-parse ceiling)`);
|
|
8
9
|
let snap; try { snap = JSON.parse(trimmed); } catch { err('malformed JSON'); }
|
|
9
10
|
if (typeof snap !== 'object' || snap === null || Array.isArray(snap)) err('root must be a plain object');
|
|
10
11
|
for (const b of ['sys', 'ops', 'mem']) if (typeof snap[b] !== 'object' || snap[b] === null || Array.isArray(snap[b])) err(`missing block: ${b}`);
|
|
11
12
|
const req = { v: snap.v, 'sys.ph': snap.sys.ph, 'sys.c': snap.sys.c, 'sys.s': snap.sys.s, 'ops.n': snap.ops.n, 'ops.f': snap.ops.f, 'mem.d': snap.mem.d, 'mem.x': snap.mem.x };
|
|
12
13
|
const missing = Object.entries(req).filter(([, v]) => v === undefined).map(([k]) => k);
|
|
13
14
|
if (missing.length) { for (const k of missing) process.stderr.write(`SNAP_ERROR: missing: ${k}\n`); process.exit(1); }
|
|
14
|
-
const topAllowed = snap.v
|
|
15
|
+
const topAllowed = TOP_FIELDS[snap.v] || TOP_FIELDS[1];
|
|
15
16
|
const topExtra = Object.keys(snap).find(k => !topAllowed.includes(k)); if (topExtra) err(`unexpected key: ${topExtra}`);
|
|
16
17
|
if (snap.pr !== undefined && typeof snap.pr !== 'string') err('pr must be a string');
|
|
17
|
-
const
|
|
18
|
-
|
|
19
|
-
if (
|
|
18
|
+
for (const b of ['sys', 'ops', 'mem']) { const extra = Object.keys(snap[b]).find(k => !BLOCK_FIELDS[b].includes(k)); if (extra) err(`unexpected key: ${b}.${extra}`); }
|
|
19
|
+
if (typeof snap.v !== 'number' || !Number.isInteger(snap.v) || snap.v < 1) err('v must be a positive integer'); if (snap.v > MAX_VERSION) err('SNAP_UNKNOWN_VERSION');
|
|
20
|
+
if (raw.length > POST_PARSE_MAX[snap.v]) err(`payload too large: ${raw.length} > ${POST_PARSE_MAX[snap.v]} (v${snap.v} cap)`);
|
|
20
21
|
if (!['spec', 'plan', 'impl', 'rev'].includes(snap.sys.ph)) err('ph must be spec|plan|impl|rev');
|
|
21
|
-
const
|
|
22
|
-
for (const [key, [cap, elemCap]] of Object.entries(caps)) {
|
|
22
|
+
for (const [key, [cap, elemCap]] of Object.entries(CAPS)) {
|
|
23
23
|
const [blk, sub] = key.split('.'); const arr = snap[blk][sub]; if (!Array.isArray(arr)) err(`${key} must be an array`); if (arr.length > cap) err(`${key} exceeds cap`);
|
|
24
24
|
arr.forEach((el, i) => { if (typeof el !== 'string' || el.trim() === '') err(`empty element in ${key}[${i}]`); if (JSON.stringify(el).slice(1, -1).length > elemCap) err(`element too long in ${key}[${i}]`); });
|
|
25
25
|
}
|