@jjanczur/tyran 0.1.30 → 0.1.32
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 +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +427 -0
- package/README.md +16 -4
- package/agents/reviewer.md +56 -9
- package/agents/scout.md +8 -2
- package/bin/tyran.mjs +8 -0
- package/hooks/scripts/policy-gate.mjs +22 -1
- package/hooks/scripts/secrets-gate.mjs +147 -11
- package/hooks/scripts/usage-gate.mjs +46 -12
- package/package.json +1 -1
- package/scripts/board-html.mjs +166 -9
- package/scripts/board.mjs +70 -8
- package/scripts/cost.mjs +392 -23
- package/scripts/doctor.mjs +302 -24
- package/scripts/ensure-gitleaks.mjs +254 -0
- package/scripts/journal.mjs +216 -0
- package/scripts/knowledge.mjs +89 -2
- package/scripts/migrate.mjs +191 -0
- package/scripts/overnight.mjs +2 -2
- package/scripts/pricing.mjs +255 -0
- package/scripts/project.mjs +159 -7
- package/scripts/scan-repo.mjs +120 -1
- package/scripts/schema.mjs +30 -6
- package/scripts/statusline.mjs +4 -1
- package/scripts/tiers.mjs +24 -0
- package/scripts/usage-source.mjs +135 -0
- package/skills/code-review/SKILL.md +1 -1
- package/skills/setup/SKILL.md +96 -10
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* ensure-gitleaks — remove the one prerequisite that blocks day one.
|
|
4
|
+
*
|
|
5
|
+
* The secrets gate refuses every commit and push until `gitleaks` exists, and
|
|
6
|
+
* it refuses rather than warning for a reason that has not changed: a check
|
|
7
|
+
* that passes when its scanner is missing is a check you disable by
|
|
8
|
+
* uninstalling a package.
|
|
9
|
+
*
|
|
10
|
+
* The unstated assumption in that design is that the operator can install a
|
|
11
|
+
* binary. Measured against the people actually adopting this: some have no
|
|
12
|
+
* Homebrew, no admin rights, or are on Windows. For them the realistic
|
|
13
|
+
* outcome of "install gitleaks and re-run" is not a safer repository — it is
|
|
14
|
+
* switching the hook off, or abandoning the tool. A gate nobody can satisfy
|
|
15
|
+
* protects nothing, which is the same argument `.tyran/config.yaml` being
|
|
16
|
+
* AUTO already rests on.
|
|
17
|
+
*
|
|
18
|
+
* So this fetches the scanner instead of asking someone else to. It is the
|
|
19
|
+
* same thing `.github/workflows/ci.yml` has always done — pinned version,
|
|
20
|
+
* pinned checksum — moved to where a user can reach it.
|
|
21
|
+
*
|
|
22
|
+
* ## Why a checksum table and not "download the latest"
|
|
23
|
+
*
|
|
24
|
+
* This writes an executable and something else later runs it. Version alone
|
|
25
|
+
* is not integrity: a tag can be moved, a mirror can lie, and a scanner that
|
|
26
|
+
* has been replaced reports clean on everything. The digests below are the
|
|
27
|
+
* ones GitHub publishes for 8.30.1, and a mismatch DELETES the download and
|
|
28
|
+
* refuses. The linux_x64 line is the same digest ci.yml already pins, which
|
|
29
|
+
* is the cross-check that this table was transcribed and not invented.
|
|
30
|
+
*
|
|
31
|
+
* Usage:
|
|
32
|
+
* node scripts/ensure-gitleaks.mjs [--check]
|
|
33
|
+
*
|
|
34
|
+
* Exit: 0 present or installed · 1 unavailable (reason printed) · 2 usage.
|
|
35
|
+
*/
|
|
36
|
+
import { createHash } from 'node:crypto';
|
|
37
|
+
import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
|
|
38
|
+
import { execFileSync } from 'node:child_process';
|
|
39
|
+
import { join } from 'node:path';
|
|
40
|
+
import { homedir, tmpdir } from 'node:os';
|
|
41
|
+
|
|
42
|
+
/** The version this table describes. Bumping it means re-fetching every digest. */
|
|
43
|
+
export const GITLEAKS_VERSION = '8.30.1';
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* SHA-256 per platform, from the release's own `checksums.txt`.
|
|
47
|
+
*
|
|
48
|
+
* Keyed `<process.platform>-<process.arch>` so the lookup cannot drift from
|
|
49
|
+
* what Node reports. A platform absent from this table is a REFUSAL with
|
|
50
|
+
* instructions, never a silent skip — an unknown platform is exactly where a
|
|
51
|
+
* "best effort" download would install something unverified.
|
|
52
|
+
*/
|
|
53
|
+
export const GITLEAKS_SHA256 = Object.freeze({
|
|
54
|
+
'darwin-arm64': 'b40ab0ae55c505963e365f271a8d3846efbc170aa17f2607f13df610a9aeb6a5',
|
|
55
|
+
'darwin-x64': 'dfe101a4db2255fc85120ac7f3d25e4342c3c20cf749f2c20a18081af1952709',
|
|
56
|
+
'linux-arm64': 'e4a487ee7ccd7d3a7f7ec08657610aa3606637dab924210b3aee62570fb4b080',
|
|
57
|
+
// The digest ci.yml pins. If these two ever disagree, one of them is wrong.
|
|
58
|
+
'linux-x64': '551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb',
|
|
59
|
+
'win32-arm64': 'b95f5e4f5c425cedca7ee203d9afd29597e692c4924a12ed42f970537c72cc0f',
|
|
60
|
+
'win32-x64': 'd29144deff3a68aa93ced33dddf84b7fdc26070add4aa0f4513094c8332afc4e',
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Where a managed scanner lives: under the operator's HOME, never the repo.
|
|
65
|
+
*
|
|
66
|
+
* The first shape of this put it in `<repo>/.tyran/bin/`, which is worse in a
|
|
67
|
+
* way worth recording: a path inside the repository travels with a clone, so
|
|
68
|
+
* a planted binary that reports clean on everything would arrive with the
|
|
69
|
+
* checkout — the attack the tracked-only rule for `.gitleaksignore` already
|
|
70
|
+
* exists to prevent, reopened through a file that is not even in a diff.
|
|
71
|
+
* Under the home directory the scanner is the operator's machine, exactly
|
|
72
|
+
* like anything on PATH, and one install serves every repository on it.
|
|
73
|
+
*/
|
|
74
|
+
export const MANAGED_DIR = join(homedir(), '.tyran', 'bin');
|
|
75
|
+
|
|
76
|
+
const ASSET_ARCH = Object.freeze({ arm64: 'arm64', x64: 'x64' });
|
|
77
|
+
|
|
78
|
+
/** The release asset name for a platform key, or null if unsupported. */
|
|
79
|
+
export function assetFor(platform = process.platform, arch = process.arch) {
|
|
80
|
+
const a = ASSET_ARCH[arch];
|
|
81
|
+
if (a === undefined) return null;
|
|
82
|
+
if (platform === 'darwin') return `gitleaks_${GITLEAKS_VERSION}_darwin_${a}.tar.gz`;
|
|
83
|
+
if (platform === 'linux') return `gitleaks_${GITLEAKS_VERSION}_linux_${a}.tar.gz`;
|
|
84
|
+
if (platform === 'win32') return `gitleaks_${GITLEAKS_VERSION}_windows_${a}.zip`;
|
|
85
|
+
return null;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export const managedBinPath = (platform = process.platform) =>
|
|
89
|
+
join(MANAGED_DIR, platform === 'win32' ? 'gitleaks.exe' : 'gitleaks');
|
|
90
|
+
|
|
91
|
+
/** SHA-256 of a file on disk, hex. */
|
|
92
|
+
export function digestOf(path) {
|
|
93
|
+
return createHash('sha256').update(readFileSync(path)).digest('hex');
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Is a usable `gitleaks` already reachable? Checks the operator's override
|
|
98
|
+
* first, then PATH — the two the gate itself consults, in the gate's order.
|
|
99
|
+
*/
|
|
100
|
+
export function alreadyAvailable({ run = defaultRun } = {}) {
|
|
101
|
+
const explicit = process.env.TYRAN_GITLEAKS_BIN;
|
|
102
|
+
if (typeof explicit === 'string' && explicit !== '') {
|
|
103
|
+
return run(explicit, ['version']) === null ? null : { path: explicit, why: 'TYRAN_GITLEAKS_BIN' };
|
|
104
|
+
}
|
|
105
|
+
const version = run('gitleaks', ['version']);
|
|
106
|
+
return version === null ? null : { path: 'gitleaks', why: 'on PATH', version: version.trim() };
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
function defaultRun(bin, args) {
|
|
110
|
+
try {
|
|
111
|
+
return execFileSync(bin, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 });
|
|
112
|
+
} catch {
|
|
113
|
+
return null;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Download one URL to a path, following redirects. GitHub answers a release
|
|
119
|
+
* asset with a 302 to a CDN, so a client that does not follow them downloads
|
|
120
|
+
* an HTML document and hashes it — which fails the digest check rather than
|
|
121
|
+
* installing anything, but reports the wrong reason.
|
|
122
|
+
*/
|
|
123
|
+
async function download(url, dest, { redirects = 5 } = {}) {
|
|
124
|
+
const { get } = await import('node:https');
|
|
125
|
+
const { createWriteStream } = await import('node:fs');
|
|
126
|
+
return new Promise((resolvePromise, reject) => {
|
|
127
|
+
get(url, { headers: { 'user-agent': 'tyran-ensure-gitleaks' } }, (res) => {
|
|
128
|
+
const { statusCode, headers } = res;
|
|
129
|
+
if (statusCode !== undefined && statusCode >= 300 && statusCode < 400 && headers.location) {
|
|
130
|
+
res.resume();
|
|
131
|
+
if (redirects === 0) return reject(new Error('too many redirects'));
|
|
132
|
+
return resolvePromise(download(headers.location, dest, { redirects: redirects - 1 }));
|
|
133
|
+
}
|
|
134
|
+
if (statusCode !== 200) {
|
|
135
|
+
res.resume();
|
|
136
|
+
return reject(new Error(`HTTP ${statusCode} from ${url}`));
|
|
137
|
+
}
|
|
138
|
+
const file = createWriteStream(dest);
|
|
139
|
+
res.pipe(file);
|
|
140
|
+
file.on('finish', () => file.close(() => resolvePromise(undefined)));
|
|
141
|
+
file.on('error', reject);
|
|
142
|
+
}).on('error', reject);
|
|
143
|
+
});
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Fetch, verify and unpack the pinned scanner into `<dir>/bin/`.
|
|
148
|
+
*
|
|
149
|
+
* The digest is checked BEFORE anything is unpacked and before the file is
|
|
150
|
+
* made executable: an archive that fails is deleted and nothing it contained
|
|
151
|
+
* ever reaches the disk as a program.
|
|
152
|
+
*
|
|
153
|
+
* `tar` does the unpacking on every platform — bsdtar reads zip, and Windows
|
|
154
|
+
* has shipped it since 10 — so this needs no archive library and no
|
|
155
|
+
* dependency, which is the property that lets it ship inside a plugin.
|
|
156
|
+
*/
|
|
157
|
+
export async function installGitleaks({ platform = process.platform, arch = process.arch, run = defaultRun } = {}) {
|
|
158
|
+
const key = `${platform}-${arch}`;
|
|
159
|
+
const asset = assetFor(platform, arch);
|
|
160
|
+
const expected = GITLEAKS_SHA256[key];
|
|
161
|
+
if (asset === null || expected === undefined) {
|
|
162
|
+
return { ok: false, reason: `no pinned build for ${key}`, unsupported: true };
|
|
163
|
+
}
|
|
164
|
+
const target = managedBinPath(platform);
|
|
165
|
+
if (existsSync(target) && digestOf(target) !== '' && run(target, ['version']) !== null) {
|
|
166
|
+
return { ok: true, path: target, already: true };
|
|
167
|
+
}
|
|
168
|
+
const url = `https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/${asset}`;
|
|
169
|
+
const staging = join(tmpdir(), `tyran-gitleaks-${process.pid}`);
|
|
170
|
+
mkdirSync(staging, { recursive: true });
|
|
171
|
+
const archive = join(staging, asset);
|
|
172
|
+
try {
|
|
173
|
+
await download(url, archive);
|
|
174
|
+
const actual = digestOf(archive);
|
|
175
|
+
if (actual !== expected) {
|
|
176
|
+
rmSync(staging, { recursive: true, force: true });
|
|
177
|
+
return {
|
|
178
|
+
ok: false,
|
|
179
|
+
reason: `checksum mismatch for ${asset}: expected ${expected}, got ${actual}. Nothing was installed.`,
|
|
180
|
+
};
|
|
181
|
+
}
|
|
182
|
+
execFileSync('tar', ['-xf', archive, '-C', staging], { stdio: 'ignore', timeout: 60_000 });
|
|
183
|
+
const unpacked = join(staging, platform === 'win32' ? 'gitleaks.exe' : 'gitleaks');
|
|
184
|
+
if (!existsSync(unpacked)) {
|
|
185
|
+
rmSync(staging, { recursive: true, force: true });
|
|
186
|
+
return { ok: false, reason: `the archive did not contain a gitleaks binary` };
|
|
187
|
+
}
|
|
188
|
+
mkdirSync(MANAGED_DIR, { recursive: true });
|
|
189
|
+
writeFileSync(target, readFileSync(unpacked));
|
|
190
|
+
if (platform !== 'win32') chmodSync(target, 0o755);
|
|
191
|
+
rmSync(staging, { recursive: true, force: true });
|
|
192
|
+
if (run(target, ['version']) === null) {
|
|
193
|
+
return { ok: false, reason: 'the installed binary did not run — the platform build may not match this machine' };
|
|
194
|
+
}
|
|
195
|
+
return { ok: true, path: target, installed: true, digest: expected };
|
|
196
|
+
} catch (error) {
|
|
197
|
+
rmSync(staging, { recursive: true, force: true });
|
|
198
|
+
return { ok: false, reason: String(error.message ?? error) };
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
const MANUAL =
|
|
203
|
+
'Install it by hand and re-run:\n' +
|
|
204
|
+
' macOS brew install gitleaks\n' +
|
|
205
|
+
' Linux see https://github.com/gitleaks/gitleaks/releases (or your package manager)\n' +
|
|
206
|
+
'or point TYRAN_GITLEAKS_BIN at an existing binary.';
|
|
207
|
+
|
|
208
|
+
function usage(message) {
|
|
209
|
+
if (message) console.error(`ensure-gitleaks: ${message}`);
|
|
210
|
+
console.error('usage: node scripts/ensure-gitleaks.mjs [--check]');
|
|
211
|
+
process.exit(2);
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
async function main(argv) {
|
|
215
|
+
const args = argv.slice(2);
|
|
216
|
+
for (const arg of args) {
|
|
217
|
+
if (arg.startsWith('--') && arg !== '--check') usage(`unknown flag ${arg}`);
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
const found = alreadyAvailable();
|
|
221
|
+
if (found !== null) {
|
|
222
|
+
console.log(`ensure-gitleaks: already available (${found.why})${found.version ? ` — ${found.version}` : ''}`);
|
|
223
|
+
process.exit(0);
|
|
224
|
+
}
|
|
225
|
+
const local = managedBinPath();
|
|
226
|
+
if (existsSync(local) && defaultRun(local, ['version']) !== null) {
|
|
227
|
+
console.log(`ensure-gitleaks: present at ${local}`);
|
|
228
|
+
process.exit(0);
|
|
229
|
+
}
|
|
230
|
+
if (args.includes('--check')) {
|
|
231
|
+
console.error('ensure-gitleaks: NOT available — the secrets gate refuses every commit and push until it is.');
|
|
232
|
+
console.error(MANUAL);
|
|
233
|
+
process.exit(1);
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
console.log(`ensure-gitleaks: fetching gitleaks ${GITLEAKS_VERSION} for ${process.platform}-${process.arch}…`);
|
|
237
|
+
const result = await installGitleaks();
|
|
238
|
+
if (!result.ok) {
|
|
239
|
+
console.error(`ensure-gitleaks: could not install it (${result.reason})`);
|
|
240
|
+
console.error(MANUAL);
|
|
241
|
+
process.exit(1);
|
|
242
|
+
}
|
|
243
|
+
console.log(`ensure-gitleaks: installed ${result.path}`);
|
|
244
|
+
console.log(`ensure-gitleaks: verified sha256 ${result.digest}`);
|
|
245
|
+
console.log('ensure-gitleaks: the secrets gate finds this automatically — nothing to add to your shell.');
|
|
246
|
+
process.exit(0);
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
if (import.meta.url === `file://${process.argv[1]}`) {
|
|
250
|
+
main(process.argv).catch((error) => {
|
|
251
|
+
console.error(`ensure-gitleaks: ${error.message}`);
|
|
252
|
+
process.exit(1);
|
|
253
|
+
});
|
|
254
|
+
}
|
package/scripts/journal.mjs
CHANGED
|
@@ -83,6 +83,125 @@ export const DATA_REQUIRED = Object.freeze({
|
|
|
83
83
|
error: ['class'],
|
|
84
84
|
});
|
|
85
85
|
|
|
86
|
+
/**
|
|
87
|
+
* Per-type keys that some consumer actually READS. Descriptive, not enforced.
|
|
88
|
+
*
|
|
89
|
+
* `append` does not and must not check this: `data may always carry extra
|
|
90
|
+
* keys` is a promise this file makes, the evidence gate relies on it for four
|
|
91
|
+
* of its own keys, and every journal ever written would fail retroactively if
|
|
92
|
+
* it became a rule. Measured on one real install: 130 distinct (event, key)
|
|
93
|
+
* pairs across 39 initiatives, and the long tail is deliberate annotation —
|
|
94
|
+
* `init.created.hardware`, `retro.entry.proposed_as_diffs`, `spawn.stories`.
|
|
95
|
+
*
|
|
96
|
+
* What this map is FOR is the narrow case hiding in that tail: a key that was
|
|
97
|
+
* MEANT to be read and is not, because it was misspelled. `next_step` for
|
|
98
|
+
* `next_steps` is accepted, ignored, and leaves the resume surface empty while
|
|
99
|
+
* the agent that wrote it believes it recorded something. Doctor compares
|
|
100
|
+
* unread keys against this map and reports only the near-misses; the rest are
|
|
101
|
+
* counted, because they are the contract working rather than a defect.
|
|
102
|
+
*
|
|
103
|
+
* `null` means "free-form on purpose": the fold keeps the whole `data` object
|
|
104
|
+
* for these, so there is no such thing as a key it does not read.
|
|
105
|
+
*/
|
|
106
|
+
export const DATA_KNOWN = Object.freeze({
|
|
107
|
+
'init.created': null,
|
|
108
|
+
'plan.accepted': null,
|
|
109
|
+
'ticket.created': Object.freeze(['id', 'title', 'text', 'deps']),
|
|
110
|
+
'ticket.status': Object.freeze(['ticket', 'column', 'reason', 'until']),
|
|
111
|
+
spawn: Object.freeze(['agent', 'role', 'model', 'ticket', 'worktree']),
|
|
112
|
+
report: Object.freeze(['agent', 'verdict', 'ticket', 'text', 'note', 'evidence', 'closed_by']),
|
|
113
|
+
progress: Object.freeze(['agent', 'state', 'ticket', 'detail', 'next']),
|
|
114
|
+
// Row two is the evidence gate's own, written on every SubagentStop; row
|
|
115
|
+
// three is `answer.mjs` closing an operator question. Both are Tyran writing
|
|
116
|
+
// to its own journal, so leaving either out would have every install report
|
|
117
|
+
// its own normal operation back at itself.
|
|
118
|
+
gate: Object.freeze([
|
|
119
|
+
'kind', 'result', 'evidence', 'evidence_ref', 'ticket', 'question', 'recommendation', 'default',
|
|
120
|
+
'reason', 'signals', 'code', 'would_be', 'initiative_inferred_from',
|
|
121
|
+
'answer', 'answer_mode', 'decision', 'via',
|
|
122
|
+
]),
|
|
123
|
+
review: Object.freeze(['ticket', 'verdict', 'by']),
|
|
124
|
+
merge: Object.freeze(['ticket', 'sha', 'mode']),
|
|
125
|
+
// `ask`/`ticket` come from `answer.mjs` closing an operator question;
|
|
126
|
+
// `signature`/`occurrences`/`path` from `mistakes.mjs` recording a promoted
|
|
127
|
+
// rule. Tyran's OWN writers, so leaving them out would have every install
|
|
128
|
+
// that has ever answered a question or run a retrospective report its own
|
|
129
|
+
// normal operation back at itself.
|
|
130
|
+
decision: Object.freeze(['id', 'text', 'ask', 'ticket', 'signature', 'occurrences', 'path']),
|
|
131
|
+
finding: Object.freeze(['area', 'claim', 'proof', 'id', 'ticket', 'confidence']),
|
|
132
|
+
// The expiry spellings doctor reads, plus the human description agents
|
|
133
|
+
// attach. Measured across every journal on a real machine, agents wrote
|
|
134
|
+
// `expiry` 33 times, `purpose` 28, `story` 21, `text` 21 — none of them
|
|
135
|
+
// known, so every lease an agent took the trouble to describe reported
|
|
136
|
+
// `journal-key-unread` back at its author. A schema that flags the fields
|
|
137
|
+
// its own agents naturally write is training them to write less.
|
|
138
|
+
'lease.acquired': Object.freeze([
|
|
139
|
+
'resource', 'holder', 'mode', 'expiry', 'expires', 'expires_at', 'until', 'purpose', 'story', 'text', 'note',
|
|
140
|
+
]),
|
|
141
|
+
'lease.released': Object.freeze(['resource', 'holder', 'text', 'note']),
|
|
142
|
+
checkpoint: Object.freeze(['phase', 'next_steps']),
|
|
143
|
+
'retro.entry': Object.freeze(['kind', 'target', 'confidence']),
|
|
144
|
+
error: Object.freeze(['class', 'detail', 'ticket']),
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Is `typo` one edit away from `known`? Insert, delete or substitute.
|
|
149
|
+
*
|
|
150
|
+
* Deliberately distance ONE and nothing looser. At two, `note` matches `next`
|
|
151
|
+
* and the check starts inventing typos in correct journals — and this feeds a
|
|
152
|
+
* finding that fails the check, so a false positive costs an operator a red
|
|
153
|
+
* doctor on a healthy repo, which is how a check gets switched off.
|
|
154
|
+
*/
|
|
155
|
+
export function isOneEditApart(typo, known) {
|
|
156
|
+
if (typo === known) return false;
|
|
157
|
+
const [a, b] = typo.length <= known.length ? [typo, known] : [known, typo];
|
|
158
|
+
if (b.length - a.length > 1) return false;
|
|
159
|
+
let i = 0;
|
|
160
|
+
let j = 0;
|
|
161
|
+
let edits = 0;
|
|
162
|
+
while (i < a.length && j < b.length) {
|
|
163
|
+
if (a[i] === b[j]) { i += 1; j += 1; continue; }
|
|
164
|
+
if (++edits > 1) return false;
|
|
165
|
+
if (a.length === b.length) i += 1;
|
|
166
|
+
j += 1;
|
|
167
|
+
}
|
|
168
|
+
return edits + (b.length - j) + (a.length - i) <= 1;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* Keys no consumer reads, split into the two that need different sentences.
|
|
173
|
+
*
|
|
174
|
+
* `nearMisses` are almost certainly misspellings of a key that IS read —
|
|
175
|
+
* the accept-then-ignore failure, worth a finding each. `unread` is everything
|
|
176
|
+
* else: counted, never dropped (ADR-19 correction 1), and not called a defect,
|
|
177
|
+
* because carrying extra keys is what the envelope promises.
|
|
178
|
+
*
|
|
179
|
+
* Short keys are exempt from the near-miss test: at three characters or fewer
|
|
180
|
+
* almost anything is one edit from something.
|
|
181
|
+
*/
|
|
182
|
+
export function unreadDataKeys(events) {
|
|
183
|
+
const unread = new Map(); // "ev.key" -> count
|
|
184
|
+
const nearMisses = new Map(); // "ev.key" -> {ev, key, meant, count}
|
|
185
|
+
for (const event of events) {
|
|
186
|
+
const known = DATA_KNOWN[event?.ev];
|
|
187
|
+
if (known === undefined || known === null) continue;
|
|
188
|
+
const data = event.data;
|
|
189
|
+
if (typeof data !== 'object' || data === null || Array.isArray(data)) continue;
|
|
190
|
+
for (const key of Object.keys(data)) {
|
|
191
|
+
if (known.includes(key)) continue;
|
|
192
|
+
const id = `${event.ev}.${key}`;
|
|
193
|
+
unread.set(id, (unread.get(id) ?? 0) + 1);
|
|
194
|
+
if (key.length < 4) continue;
|
|
195
|
+
const meant = known.find((k) => k.length >= 4 && isOneEditApart(key, k));
|
|
196
|
+
if (meant === undefined) continue;
|
|
197
|
+
const hit = nearMisses.get(id) ?? { ev: event.ev, key, meant, count: 0 };
|
|
198
|
+
hit.count += 1;
|
|
199
|
+
nearMisses.set(id, hit);
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
return { unread, nearMisses: [...nearMisses.values()].sort((a, b) => (a.ev + a.key).localeCompare(b.ev + b.key)) };
|
|
203
|
+
}
|
|
204
|
+
|
|
86
205
|
/**
|
|
87
206
|
* Closed VALUE sets inside `data`, for the same reason the event set is
|
|
88
207
|
* closed: an unknown value must be a loud rejection at append time, not a
|
|
@@ -331,6 +450,74 @@ export function pairSpawns(events) {
|
|
|
331
450
|
return { open, orphanReports, badNames, pairs, unusable, ambiguous };
|
|
332
451
|
}
|
|
333
452
|
|
|
453
|
+
/**
|
|
454
|
+
* The one `checkpoint.phase` value that MEANS something to a reader.
|
|
455
|
+
*
|
|
456
|
+
* `phase` is otherwise free text — the field carries epic labels (`E2`),
|
|
457
|
+
* lifecycle notes (`resumed`, `usage-limit-pause`) and whatever else a
|
|
458
|
+
* conductor finds useful, and it stays that way. This single value is
|
|
459
|
+
* reserved: it says the initiative is over, which is the one thing a
|
|
460
|
+
* projection cannot infer from any other event. Nothing in `EVENT_TYPES`
|
|
461
|
+
* closes an initiative, so before this an initiative could be wound up with
|
|
462
|
+
* its spawns still open, and every consumer went on calling those agents
|
|
463
|
+
* live for as long as the journal survived.
|
|
464
|
+
*
|
|
465
|
+
* Compared case-insensitively and trimmed, because it is written by hand.
|
|
466
|
+
*/
|
|
467
|
+
export const CLOSED_PHASE = 'closed';
|
|
468
|
+
|
|
469
|
+
/** Does this checkpoint's phase declare the initiative over? */
|
|
470
|
+
export function isClosingPhase(phase) {
|
|
471
|
+
return typeof phase === 'string' && phase.trim().toLowerCase() === CLOSED_PHASE;
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
/**
|
|
475
|
+
* How long an open spawn may stand, in JOURNAL time, before it is stale.
|
|
476
|
+
*
|
|
477
|
+
* Lives here rather than in either consumer because both `doctor.mjs` and
|
|
478
|
+
* `project.mjs` have to answer the same question and neither may own it:
|
|
479
|
+
* doctor imports the projection, so the projection cannot import doctor back.
|
|
480
|
+
* It is the same reasoning `pairSpawns` above records — the projection used to
|
|
481
|
+
* compute "who is still working" with a rule of its own, and the operator got
|
|
482
|
+
* two contradictory pictures. Staleness was the half of that answer still
|
|
483
|
+
* written twice: doctor said an agent had been abandoned while the board went
|
|
484
|
+
* on calling it `running` forever.
|
|
485
|
+
*/
|
|
486
|
+
export const DEFAULT_STALE_HOURS = 4;
|
|
487
|
+
|
|
488
|
+
/** Hours between two ISO timestamps, or null if either is unparseable. */
|
|
489
|
+
export function hoursBetween(fromTs, toTs) {
|
|
490
|
+
const from = Date.parse(fromTs);
|
|
491
|
+
const to = Date.parse(toTs);
|
|
492
|
+
if (Number.isNaN(from) || Number.isNaN(to)) return null;
|
|
493
|
+
return (to - from) / 3_600_000;
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* Is this open spawn stale, measured against the initiative's own movement?
|
|
498
|
+
*
|
|
499
|
+
* `reference` is the journal's latest timestamp, NOT the wall clock, and that
|
|
500
|
+
* is the whole point: staleness here means "the initiative moved on without
|
|
501
|
+
* it", which is a property of the recorded history and reads the same in six
|
|
502
|
+
* months as it does now. A wall-clock rule would instead call every agent in
|
|
503
|
+
* a finished initiative stale the moment you walked away from it.
|
|
504
|
+
*
|
|
505
|
+
* That also keeps `board.json` byte-exact under `--check`: the answer is
|
|
506
|
+
* derived from event timestamps, so two clones of one journal agree. The
|
|
507
|
+
* `age-fresh/warm/cold/dead` colours on the HTML page are a DIFFERENT
|
|
508
|
+
* question — "how long since it last spoke, right now, in the reader's own
|
|
509
|
+
* timezone" — computed client-side precisely because the artefact may not
|
|
510
|
+
* read a clock. An agent can be `age-dead` (quiet for hours) without being
|
|
511
|
+
* stale, and stale without being `age-dead`.
|
|
512
|
+
*
|
|
513
|
+
* Returns the age alongside the verdict so a caller that reports the number
|
|
514
|
+
* does not recompute it — the same additive shape `pairSpawns` returns.
|
|
515
|
+
*/
|
|
516
|
+
export function spawnStaleness(spawnTs, reference, staleHours = DEFAULT_STALE_HOURS) {
|
|
517
|
+
const ageHours = reference === null || reference === undefined ? null : hoursBetween(spawnTs, reference);
|
|
518
|
+
return { ageHours, stale: ageHours !== null && ageHours >= staleHours, staleHours };
|
|
519
|
+
}
|
|
520
|
+
|
|
334
521
|
/** Agents whose `spawn` has no matching `report` or `review` yet — the "still working" set. */
|
|
335
522
|
export function openSpawns(file) {
|
|
336
523
|
const { open } = pairSpawns(readJournal(file).events);
|
|
@@ -506,6 +693,35 @@ function appendUnderLock(file, event, preread = null) {
|
|
|
506
693
|
if (issuePrefix !== undefined && isDataObject(stamped.data) && (stamped.data.id === undefined || stamped.data.id === '')) {
|
|
507
694
|
// a fresh object: the `data` the caller passed in stays the caller's
|
|
508
695
|
stamped.data = { ...stamped.data, id: nextIdFrom(read().events, issuePrefix) };
|
|
696
|
+
} else if (issuePrefix !== undefined && isDataObject(stamped.data) && typeof stamped.data.id === 'string') {
|
|
697
|
+
// A caller-supplied id that is ALREADY TAKEN is refused.
|
|
698
|
+
//
|
|
699
|
+
// Measured in the field: two implementers running in parallel each passed
|
|
700
|
+
// an id they had worked out for themselves, and both were honoured — the
|
|
701
|
+
// ledger then held two `F-7`s, and "see F-7" is ambiguous forever, because
|
|
702
|
+
// history is append-only and nothing detects it later.
|
|
703
|
+
//
|
|
704
|
+
// The narrow fix, not the broad one. Refusing EVERY caller-supplied id was
|
|
705
|
+
// the first proposal and it removes a documented capability — the comment
|
|
706
|
+
// above says an explicit id still wins, and a test pins it — to prevent a
|
|
707
|
+
// failure that only ever occurs on COLLISION. So collision is what this
|
|
708
|
+
// refuses, and a fresh explicit id still passes untouched.
|
|
709
|
+
//
|
|
710
|
+
// Inside the lock, on the same read as the mint above: a check outside it
|
|
711
|
+
// would let two concurrent writers both pass and both append, which is the
|
|
712
|
+
// exact race being closed.
|
|
713
|
+
const taken = read().events.some(
|
|
714
|
+
(e) => e?.ev === stamped.ev && typeof e?.data?.id === 'string' && e.data.id === stamped.data.id,
|
|
715
|
+
);
|
|
716
|
+
if (taken) {
|
|
717
|
+
throw new Error(
|
|
718
|
+
`invalid event: ${q(stamped.ev)} id ${q(stamped.data.id)} is already used in ${q(file)}.\n` +
|
|
719
|
+
' Two events under one id make every later reference to it ambiguous, and the journal is\n' +
|
|
720
|
+
' append-only, so nothing can disambiguate them afterwards.\n' +
|
|
721
|
+
` Omit "id" and ${q('append')} issues the next free one, which is what it is for — or run\n` +
|
|
722
|
+
` node scripts/journal.mjs next-id ${q(file)} ${q(issuePrefix)}`,
|
|
723
|
+
);
|
|
724
|
+
}
|
|
509
725
|
}
|
|
510
726
|
const errors = validateEvent(stamped);
|
|
511
727
|
if (errors.length > 0) {
|
package/scripts/knowledge.mjs
CHANGED
|
@@ -143,6 +143,60 @@ export function renderBrief(selected, matched, { budget = DEFAULT_BUDGET, dir =
|
|
|
143
143
|
return [header, ...lines, ...tail].join('\n') + '\n';
|
|
144
144
|
}
|
|
145
145
|
|
|
146
|
+
/**
|
|
147
|
+
* Which entries can never reach a handoff, and why.
|
|
148
|
+
*
|
|
149
|
+
* The budget is deliberately the pressure that keeps entries scoped, and the
|
|
150
|
+
* omission line names the cost of every individual brief. What nothing did
|
|
151
|
+
* was AGGREGATE that: measured on a real install, `brief '**'` returned **1
|
|
152
|
+
* of 31 entries** and the other thirty were dropped by the 4000-codepoint
|
|
153
|
+
* budget. Ninety kilobytes of measured detail — migration-number races,
|
|
154
|
+
* TEST/PROD schema drift — accumulated for months and reached nobody.
|
|
155
|
+
*
|
|
156
|
+
* That is the opposite of the failure people expect. The store is not
|
|
157
|
+
* expensive to read; it is unread, while growing without bound, and the
|
|
158
|
+
* pressure the budget applies lands on nothing because no one is looking at
|
|
159
|
+
* the total.
|
|
160
|
+
*
|
|
161
|
+
* So this reports the whole store against the budget at once. It is a
|
|
162
|
+
* MEASUREMENT, never an edit: pruning needs judgement about which of two
|
|
163
|
+
* overlapping entries is the true one, and a script that guessed would delete
|
|
164
|
+
* exactly the hard-won detail this exists to protect.
|
|
165
|
+
*
|
|
166
|
+
* `alone` is the diagnostic that matters most: an entry that does not fit the
|
|
167
|
+
* budget even as the ONLY entry can never appear in any brief, under any
|
|
168
|
+
* paths, ever. It is not competing for space — it is unreachable.
|
|
169
|
+
*/
|
|
170
|
+
export function auditEntries(entries, { budget = DEFAULT_BUDGET } = {}) {
|
|
171
|
+
const sized = entries.map((entry) => {
|
|
172
|
+
const cost = Array.from(entryLine(entry)).length + 1;
|
|
173
|
+
return { id: entry.id, kind: entry.kind, confidence: entry.confidence, cost, alone: cost > budget };
|
|
174
|
+
});
|
|
175
|
+
// Ranked the way `brief` ranks, so "would reach a brief" means what a brief
|
|
176
|
+
// would actually do rather than what this function finds convenient.
|
|
177
|
+
const ranked = [...sized].sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
|
|
178
|
+
let used = 0;
|
|
179
|
+
let reachable = 0;
|
|
180
|
+
for (const entry of ranked) {
|
|
181
|
+
if (used + entry.cost > budget && reachable > 0) break;
|
|
182
|
+
used += entry.cost;
|
|
183
|
+
reachable += 1;
|
|
184
|
+
}
|
|
185
|
+
const total = sized.reduce((sum, e) => sum + e.cost, 0);
|
|
186
|
+
return {
|
|
187
|
+
budget,
|
|
188
|
+
entries: sized.length,
|
|
189
|
+
// How many a single widest-possible brief could carry.
|
|
190
|
+
reachable,
|
|
191
|
+
unreachable: sized.length - reachable,
|
|
192
|
+
// Entries too large to appear even alone — the ones pruning must address
|
|
193
|
+
// first, because no budget any caller passes will rescue them.
|
|
194
|
+
aloneTooBig: sized.filter((e) => e.alone).map((e) => ({ id: e.id, cost: e.cost })),
|
|
195
|
+
totalCost: total,
|
|
196
|
+
widest: sized.slice().sort((a, b) => b.cost - a.cost).slice(0, 5).map((e) => ({ id: e.id, cost: e.cost })),
|
|
197
|
+
};
|
|
198
|
+
}
|
|
199
|
+
|
|
146
200
|
// ---------------------------------------------------------------- CLI
|
|
147
201
|
|
|
148
202
|
const VALUE_FLAGS = ['dir', 'kinds', 'limit', 'budget'];
|
|
@@ -190,8 +244,10 @@ function parseArgs(argv) {
|
|
|
190
244
|
|
|
191
245
|
function main() {
|
|
192
246
|
const [command, ...rest] = process.argv.slice(2);
|
|
193
|
-
const usage =
|
|
194
|
-
|
|
247
|
+
const usage =
|
|
248
|
+
'usage: knowledge.mjs brief [<path>...] [--dir <knowledge-dir>] [--kinds k,k] [--limit N] [--budget CHARS] [--json]\n' +
|
|
249
|
+
' knowledge.mjs audit [--dir <knowledge-dir>] [--budget CHARS] [--json]';
|
|
250
|
+
if (command !== 'brief' && command !== 'audit') {
|
|
195
251
|
console.error(usage);
|
|
196
252
|
process.exit(2);
|
|
197
253
|
}
|
|
@@ -232,6 +288,37 @@ function main() {
|
|
|
232
288
|
return;
|
|
233
289
|
}
|
|
234
290
|
|
|
291
|
+
if (command === 'audit') {
|
|
292
|
+
const report = auditEntries(entries, { budget: flags.budget });
|
|
293
|
+
if (flags.json) {
|
|
294
|
+
console.log(jsonEscapeInvisible(JSON.stringify(report, null, 2)));
|
|
295
|
+
process.exitCode = 0;
|
|
296
|
+
return;
|
|
297
|
+
}
|
|
298
|
+
const out = [
|
|
299
|
+
`knowledge audit (${escapeInvisible(flags.dir)})`,
|
|
300
|
+
` ${report.entries} entries, ${report.totalCost} codepoints total`,
|
|
301
|
+
` ${report.reachable} could reach one brief at the ${report.budget}-codepoint budget; ` +
|
|
302
|
+
`${report.unreachable} could not`,
|
|
303
|
+
];
|
|
304
|
+
if (report.aloneTooBig.length > 0) {
|
|
305
|
+
const n = report.aloneTooBig.length;
|
|
306
|
+
out.push(` ${n} entr${n === 1 ? 'y' : 'ies'} cannot appear in ANY brief, even alone:`);
|
|
307
|
+
for (const e of report.aloneTooBig) out.push(` ${escapeInvisible(e.id)} — ${e.cost} codepoints`);
|
|
308
|
+
}
|
|
309
|
+
if (report.widest.length > 0) {
|
|
310
|
+
out.push(' widest:');
|
|
311
|
+
for (const e of report.widest) out.push(` ${escapeInvisible(e.id)} — ${e.cost}`);
|
|
312
|
+
}
|
|
313
|
+
// A measurement, never an edit: which of two overlapping entries is the
|
|
314
|
+
// true one is a judgement, and a script that guessed would delete the
|
|
315
|
+
// hard-won detail this exists to protect.
|
|
316
|
+
out.push(' This reports; it never edits. /tyran:retro consolidates, writing a NEW file for review.');
|
|
317
|
+
process.stdout.write(out.join('\n') + '\n');
|
|
318
|
+
process.exitCode = 0;
|
|
319
|
+
return;
|
|
320
|
+
}
|
|
321
|
+
|
|
235
322
|
const { selected, matched, limited } = selectEntries(entries, { paths: normalized, kinds: flags.kinds, limit: flags.limit });
|
|
236
323
|
if (flags.json) {
|
|
237
324
|
const payload = selected.map(({ id, kind, confidence, text, applies_to, file }) => ({
|