@jjanczur/tyran 0.1.31 → 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 +292 -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 +134 -7
- package/scripts/board.mjs +59 -7
- package/scripts/cost.mjs +392 -23
- package/scripts/doctor.mjs +155 -9
- package/scripts/ensure-gitleaks.mjs +254 -0
- package/scripts/journal.mjs +39 -2
- package/scripts/knowledge.mjs +89 -2
- package/scripts/overnight.mjs +2 -2
- package/scripts/pricing.mjs +255 -0
- 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
package/scripts/doctor.mjs
CHANGED
|
@@ -62,6 +62,8 @@ import {
|
|
|
62
62
|
STATE_FILE,
|
|
63
63
|
} from './project.mjs';
|
|
64
64
|
import { classifyPath, normalizePath, validateFile, knowledgeWarnings, MANDATORY_KERNEL_PATHS } from './schema.mjs';
|
|
65
|
+
import { auditEntries, loadEntries as loadKnowledgeEntries } from './knowledge.mjs';
|
|
66
|
+
import { readPlatformUsage } from './usage-source.mjs';
|
|
65
67
|
import { gitRunner } from './scan-repo.mjs';
|
|
66
68
|
import { parseMistakes, countSignatures, fenceState, KNOWLEDGE_THRESHOLD, MISTAKES_FILE, CLAUDE_MD_FILE } from './mistakes.mjs';
|
|
67
69
|
|
|
@@ -186,6 +188,8 @@ export const SEVERITY_BY_CODE = Object.freeze(
|
|
|
186
188
|
'lease-orphan': 'warning',
|
|
187
189
|
'lease-expired': 'warning',
|
|
188
190
|
'lease-release-by-non-holder': 'warning',
|
|
191
|
+
// worktrees
|
|
192
|
+
'worktree-accumulating': 'warning',
|
|
189
193
|
// projections
|
|
190
194
|
'projection-drift': 'warning',
|
|
191
195
|
'projection-absent': 'info',
|
|
@@ -202,6 +206,11 @@ export const SEVERITY_BY_CODE = Object.freeze(
|
|
|
202
206
|
'knowledge-unreadable': 'error',
|
|
203
207
|
'knowledge-not-a-directory': 'warning',
|
|
204
208
|
'knowledge-entry-oversized': 'warning',
|
|
209
|
+
// The AGGREGATE of the line above. `info`, not `warning`: nothing is
|
|
210
|
+
// broken and a store outgrows the budget in the ordinary course of being
|
|
211
|
+
// useful — but "1 of 31 entries reaches a brief" is the number that gets
|
|
212
|
+
// acted on, and five per-entry notes never added up to it for anyone.
|
|
213
|
+
'knowledge-store-unreachable': 'info',
|
|
205
214
|
// Not `info`, which is what it was: with `.tyran/` on disk and no policy
|
|
206
215
|
// under it the gate refuses every write in the repository. A severity that
|
|
207
216
|
// does not fail the check reports a locked-out repo as a note.
|
|
@@ -724,6 +733,45 @@ function closeSpawnHint(journalPath, init, agent) {
|
|
|
724
733
|
: `node scripts/journal.mjs close-spawn ${sq(journalPath)} ${sq(slug)} ${sq(agent)} --reason "<why>"`;
|
|
725
734
|
}
|
|
726
735
|
|
|
736
|
+
/**
|
|
737
|
+
* Is the knowledge store actually READABLE, as a whole?
|
|
738
|
+
*
|
|
739
|
+
* Every failure returns [] rather than throwing: this is advisory, it runs
|
|
740
|
+
* after the checks that decide whether the repo works at all, and a store
|
|
741
|
+
* that cannot be listed is already reported by `yamlFilesIn` above.
|
|
742
|
+
*/
|
|
743
|
+
function knowledgeReachability(knowledgeDir) {
|
|
744
|
+
let entries;
|
|
745
|
+
try {
|
|
746
|
+
if (!isDirectory(knowledgeDir)) return [];
|
|
747
|
+
({ entries } = loadKnowledgeEntries(knowledgeDir));
|
|
748
|
+
} catch {
|
|
749
|
+
return [];
|
|
750
|
+
}
|
|
751
|
+
if (!Array.isArray(entries) || entries.length === 0) return [];
|
|
752
|
+
const report = auditEntries(entries);
|
|
753
|
+
// Silent while the store still fits: pressure that is being obeyed is not a
|
|
754
|
+
// finding, and a check that is red on every healthy repo is one people skip.
|
|
755
|
+
if (report.unreachable === 0) return [];
|
|
756
|
+
const stuck = report.aloneTooBig;
|
|
757
|
+
const detail =
|
|
758
|
+
stuck.length === 0
|
|
759
|
+
? ''
|
|
760
|
+
: ` ${stuck.length} of them cannot appear in ANY brief even alone (widest: ` +
|
|
761
|
+
`${show(stuck[0].id)} at ${stuck[0].cost}), so no budget a caller passes will reach them.`;
|
|
762
|
+
return [
|
|
763
|
+
finding(
|
|
764
|
+
'knowledge-store-unreachable',
|
|
765
|
+
show(knowledgeDir),
|
|
766
|
+
`${report.reachable} of ${report.entries} knowledge entries can reach one brief at the ` +
|
|
767
|
+
`${report.budget}-codepoint budget; ${report.unreachable} cannot.${detail} The store is written ` +
|
|
768
|
+
'by every retrospective and read through that budget, so what does not fit is not merely ' +
|
|
769
|
+
'crowded — it reaches nobody',
|
|
770
|
+
`node scripts/knowledge.mjs audit --dir ${sq(knowledgeDir)} # the full list, widest first`,
|
|
771
|
+
),
|
|
772
|
+
];
|
|
773
|
+
}
|
|
774
|
+
|
|
727
775
|
/** How many unread keys are named before the rest are counted instead. */
|
|
728
776
|
const MAX_NAMED_KEYS = 12;
|
|
729
777
|
|
|
@@ -899,7 +947,17 @@ function askFindings(journalPath, at, read, reference) {
|
|
|
899
947
|
return findings;
|
|
900
948
|
}
|
|
901
949
|
|
|
902
|
-
|
|
950
|
+
/**
|
|
951
|
+
* Every spelling an agent has actually used for a lease's expiry.
|
|
952
|
+
*
|
|
953
|
+
* `expiry` leads because it is what agents overwhelmingly write: measured
|
|
954
|
+
* across every journal on a real machine, 33 `expiry` against 3 `expires`, so
|
|
955
|
+
* this finding read 3 of 36 recorded expiries and `lease-expired` was
|
|
956
|
+
* effectively dead. A denylist of spellings is a poor mechanism, but the
|
|
957
|
+
* alternative — refusing the ones agents naturally reach for — trades a quiet
|
|
958
|
+
* miss for a loud one over a field that is advisory anyway.
|
|
959
|
+
*/
|
|
960
|
+
const EXPIRY_KEYS = Object.freeze(['expiry', 'expires', 'expires_at', 'until']);
|
|
903
961
|
|
|
904
962
|
function leaseFindings(journalPath, at, events, reference) {
|
|
905
963
|
const findings = [];
|
|
@@ -1416,6 +1474,64 @@ function absentMistakes(repoRoot, path, run) {
|
|
|
1416
1474
|
checked: `${checked} — never existed`,
|
|
1417
1475
|
};
|
|
1418
1476
|
}
|
|
1477
|
+
/**
|
|
1478
|
+
* How many git worktrees this repository is carrying, and whether that has
|
|
1479
|
+
* become a problem nobody is looking at.
|
|
1480
|
+
*
|
|
1481
|
+
* Tyran's parallel model is a worktree per agent, and NOTHING removes one.
|
|
1482
|
+
* There is no removal path in any skill, agent or script; the journal has no
|
|
1483
|
+
* event that can even represent a worktree being destroyed; and doctor has
|
|
1484
|
+
* never enumerated them. Measured on one real machine: 26 in one repository,
|
|
1485
|
+
* 33 GB under another's `.worktrees/`, the oldest active for 68 days.
|
|
1486
|
+
*
|
|
1487
|
+
* REPORTS, never removes — and that restraint is the finding's whole design,
|
|
1488
|
+
* not doctor's general rule applied by rote. Most of those worktrees turned
|
|
1489
|
+
* out to hold work that never CONCLUDED rather than work that finished, so a
|
|
1490
|
+
* tool deleting "merged" ones would clear almost nothing while being able, on
|
|
1491
|
+
* a bad day, to delete something someone wanted. The operator gets the count,
|
|
1492
|
+
* the ages, and a command they can read before running.
|
|
1493
|
+
*
|
|
1494
|
+
* The threshold is deliberately generous: a handful of worktrees is the system
|
|
1495
|
+
* working as designed. This fires when they have stopped being cleaned up at
|
|
1496
|
+
* all, which is what the measured installs look like.
|
|
1497
|
+
*/
|
|
1498
|
+
export const WORKTREE_CEILING = 8;
|
|
1499
|
+
|
|
1500
|
+
export function worktreeFindings(repoRoot, run = null) {
|
|
1501
|
+
const checked = 'git worktrees';
|
|
1502
|
+
if (run === null) return { findings: [], checked: `${checked}: not checked (no git runner)` };
|
|
1503
|
+
if (run(['rev-parse', '--is-inside-work-tree']).trim() !== 'true') {
|
|
1504
|
+
return { findings: [], checked: `${checked}: no git here` };
|
|
1505
|
+
}
|
|
1506
|
+
const listing = run(['worktree', 'list', '--porcelain']);
|
|
1507
|
+
if (listing.trim() === '') return { findings: [], checked: `${checked}: none reported` };
|
|
1508
|
+
// One record per blank-line-separated block; the main checkout is one of
|
|
1509
|
+
// them and is never a leak, so it is counted and then subtracted.
|
|
1510
|
+
const blocks = listing.split(/\n\s*\n/).filter((b) => b.trim() !== '');
|
|
1511
|
+
const extra = Math.max(0, blocks.length - 1);
|
|
1512
|
+
const prunable = blocks.filter((b) => /^prunable /m.test(b)).length;
|
|
1513
|
+
if (extra <= WORKTREE_CEILING) {
|
|
1514
|
+
return { findings: [], checked: `${checked}: ${extra} beside the main checkout` };
|
|
1515
|
+
}
|
|
1516
|
+
return {
|
|
1517
|
+
findings: [
|
|
1518
|
+
finding(
|
|
1519
|
+
'worktree-accumulating',
|
|
1520
|
+
show(repoRoot),
|
|
1521
|
+
`${extra} git worktrees beside the main checkout` +
|
|
1522
|
+
(prunable > 0 ? `, ${prunable} of them already prunable` : '') +
|
|
1523
|
+
' — Tyran creates one per parallel agent and removes none, so they accumulate silently. ' +
|
|
1524
|
+
'They cost disk, and a stale one has already cost a validation baseline: a lint run swept ' +
|
|
1525
|
+
'leftover worktrees and reported 32,243 phantom errors. Nothing here is deleted for you; ' +
|
|
1526
|
+
'read the list before removing anything, because an unmerged worktree may hold work that ' +
|
|
1527
|
+
'was never finished rather than work that was',
|
|
1528
|
+
`git -C ${sq(repoRoot)} worktree list # then: git worktree remove <path>, after checking git -C <path> status`,
|
|
1529
|
+
),
|
|
1530
|
+
],
|
|
1531
|
+
checked: `${checked}: ${extra} beside the main checkout`,
|
|
1532
|
+
};
|
|
1533
|
+
}
|
|
1534
|
+
|
|
1419
1535
|
export function mistakesFindings(repoRoot, run = null) {
|
|
1420
1536
|
const path = join(repoRoot, MISTAKES_FILE);
|
|
1421
1537
|
if (!existsSync(path)) return absentMistakes(repoRoot, path, run);
|
|
@@ -1524,7 +1640,7 @@ export const ASK_QUEUE_FILES = Object.freeze(['ANSWERS.md', 'conductor.json']);
|
|
|
1524
1640
|
* one); without it a marker is reported as present, never as stale — doctor
|
|
1525
1641
|
* never reads the wall clock.
|
|
1526
1642
|
*/
|
|
1527
|
-
export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
|
|
1643
|
+
export function overnightFindings(dir, { now = null, configDoc = null, usageFallback = () => readPlatformUsage() } = {}) {
|
|
1528
1644
|
const findings = [];
|
|
1529
1645
|
const referenceMs = now !== null ? Date.parse(now) : null;
|
|
1530
1646
|
const markerPath = join(dir, 'state', 'paused-until.json');
|
|
@@ -1584,20 +1700,31 @@ export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
|
|
|
1584
1700
|
}
|
|
1585
1701
|
|
|
1586
1702
|
// A configured control that cannot see is the silent-absence class.
|
|
1703
|
+
//
|
|
1704
|
+
// The sidecar is no longer the only channel: the gate falls back to the
|
|
1705
|
+
// platform's own usage cache in `~/.claude.json`, which is why this finding
|
|
1706
|
+
// now asks whether ANY telemetry is reachable rather than whether the
|
|
1707
|
+
// statusline was installed. It used to fire on every install that had not
|
|
1708
|
+
// pasted a statusLine command — which, since the statusline was the only
|
|
1709
|
+
// writer and its payload is not always populated, was most of them, while
|
|
1710
|
+
// the real fault was usually that the platform was sending nothing.
|
|
1587
1711
|
const limits = knowsLimits(configDoc);
|
|
1588
1712
|
if (limits !== null && limits.mode !== 'off') {
|
|
1589
1713
|
const sidecar = readJsonIfSmall(sidecarPath);
|
|
1590
1714
|
const writtenMs = sidecar !== null ? Date.parse(typeof sidecar.written_at === 'string' ? sidecar.written_at : '') : NaN;
|
|
1591
1715
|
const ancient = referenceMs !== null && Number.isFinite(writtenMs) && referenceMs - writtenMs > 24 * 3600 * 1000;
|
|
1592
|
-
|
|
1716
|
+
const platform = usageFallback();
|
|
1717
|
+
if ((sidecar === null || ancient) && platform === null) {
|
|
1593
1718
|
findings.push(
|
|
1594
1719
|
finding(
|
|
1595
1720
|
'limit-telemetry-missing',
|
|
1596
1721
|
show(sidecarPath),
|
|
1597
|
-
`limits.mode is "${show(limits.mode)}"
|
|
1598
|
-
'
|
|
1599
|
-
'
|
|
1600
|
-
|
|
1722
|
+
`limits.mode is "${show(limits.mode)}" and NO usage telemetry is reachable — the sidecar is ` +
|
|
1723
|
+
`${sidecar === null ? 'absent' : 'over a day old'} and the platform's own cache in ~/.claude.json ` +
|
|
1724
|
+
'carries no window that is still running. The gate fails open without one, so the configured ' +
|
|
1725
|
+
'pause protects nothing. Usually this means the account is signed out, or the platform has not ' +
|
|
1726
|
+
'reported usage yet; see https://jjanczur.github.io/tyran/overnight/',
|
|
1727
|
+
`node scripts/statusline.mjs --sidecar-only # optional: a statusline is fresher, but no longer required`,
|
|
1601
1728
|
),
|
|
1602
1729
|
);
|
|
1603
1730
|
}
|
|
@@ -1632,7 +1759,13 @@ function knowsLimits(configDoc) {
|
|
|
1632
1759
|
return typeof limits.mode === 'string' ? limits : null;
|
|
1633
1760
|
}
|
|
1634
1761
|
|
|
1635
|
-
export function runStateChecks({
|
|
1762
|
+
export function runStateChecks({
|
|
1763
|
+
dir = '.tyran',
|
|
1764
|
+
now = null,
|
|
1765
|
+
staleHours = DEFAULT_STALE_HOURS,
|
|
1766
|
+
run = null,
|
|
1767
|
+
usageFallback = () => readPlatformUsage(),
|
|
1768
|
+
} = {}) {
|
|
1636
1769
|
const root = resolve(dir);
|
|
1637
1770
|
if (!existsSync(root)) {
|
|
1638
1771
|
return summarize(dir, [finding('no-state-dir', show(dir), 'no Tyran state directory here — nothing to check')], [
|
|
@@ -1699,6 +1832,15 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1699
1832
|
}
|
|
1700
1833
|
}
|
|
1701
1834
|
checked.push(`knowledge/: ${knowledge.files.length} file(s)`);
|
|
1835
|
+
// The AGGREGATE, which the per-entry warning above cannot show.
|
|
1836
|
+
//
|
|
1837
|
+
// `knowledge-entry-oversized` fires once per fat entry and each one reads as
|
|
1838
|
+
// a small, local untidiness. Measured on a real install it fired five times
|
|
1839
|
+
// while the true state was that `brief` returned ONE of thirty-one entries:
|
|
1840
|
+
// 104,178 codepoints of hard-won detail, reaching nobody. Five tidy-up notes
|
|
1841
|
+
// and "your knowledge store is 97% unread" are not the same message, and
|
|
1842
|
+
// only the second one gets acted on.
|
|
1843
|
+
findings.push(...knowledgeReachability(join(dir, 'knowledge')));
|
|
1702
1844
|
|
|
1703
1845
|
const policies = yamlFilesIn(join(dir, 'policies'), 'policies');
|
|
1704
1846
|
findings.push(...policies.findings);
|
|
@@ -1798,7 +1940,11 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1798
1940
|
findings.push(...mistakes.findings);
|
|
1799
1941
|
checked.push(mistakes.checked);
|
|
1800
1942
|
|
|
1801
|
-
|
|
1943
|
+
const worktrees = worktreeFindings(repoRoot, gitRun);
|
|
1944
|
+
findings.push(...worktrees.findings);
|
|
1945
|
+
checked.push(worktrees.checked);
|
|
1946
|
+
|
|
1947
|
+
findings.push(...overnightFindings(dir, { now, configDoc, usageFallback }));
|
|
1802
1948
|
checked.push('overnight: checked');
|
|
1803
1949
|
|
|
1804
1950
|
const trackedLeases = trackedLeaseFiles(gitRun, basename(root));
|
|
@@ -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
|
@@ -129,8 +129,16 @@ export const DATA_KNOWN = Object.freeze({
|
|
|
129
129
|
// normal operation back at itself.
|
|
130
130
|
decision: Object.freeze(['id', 'text', 'ask', 'ticket', 'signature', 'occurrences', 'path']),
|
|
131
131
|
finding: Object.freeze(['area', 'claim', 'proof', 'id', 'ticket', 'confidence']),
|
|
132
|
-
|
|
133
|
-
|
|
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']),
|
|
134
142
|
checkpoint: Object.freeze(['phase', 'next_steps']),
|
|
135
143
|
'retro.entry': Object.freeze(['kind', 'target', 'confidence']),
|
|
136
144
|
error: Object.freeze(['class', 'detail', 'ticket']),
|
|
@@ -685,6 +693,35 @@ function appendUnderLock(file, event, preread = null) {
|
|
|
685
693
|
if (issuePrefix !== undefined && isDataObject(stamped.data) && (stamped.data.id === undefined || stamped.data.id === '')) {
|
|
686
694
|
// a fresh object: the `data` the caller passed in stays the caller's
|
|
687
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
|
+
}
|
|
688
725
|
}
|
|
689
726
|
const errors = validateEvent(stamped);
|
|
690
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 }) => ({
|