@able-autonomy/able 0.0.21 → 0.2.0

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.
Files changed (42) hide show
  1. package/able.ts +9 -2
  2. package/config.ts +11 -0
  3. package/package.json +1 -1
  4. package/src/bloat/apply.test.ts +81 -0
  5. package/src/bloat/apply.ts +49 -0
  6. package/src/{agents → bloat}/blocks.ts +2 -2
  7. package/src/{agents → bloat}/checks.ts +2 -2
  8. package/src/bloat/compare.ts +63 -0
  9. package/src/{agents → bloat}/findings.ts +11 -7
  10. package/src/{agents → bloat}/grid.ts +4 -4
  11. package/src/bloat/index.ts +258 -0
  12. package/src/{agents → bloat}/load.ts +2 -2
  13. package/src/{agents → bloat}/picker.ts +3 -3
  14. package/src/bloat/report.ts +286 -0
  15. package/src/{agents → bloat}/scan.ts +2 -2
  16. package/src/bloat/show.ts +79 -0
  17. package/src/bloat/steps.ts +32 -0
  18. package/src/{agents → bloat}/types.ts +48 -3
  19. package/src/commit.ts +2 -1
  20. package/src/git.ts +43 -2
  21. package/src/push.ts +2 -1
  22. package/src/ui.ts +3 -0
  23. package/src/workspaces/fixture.ts +49 -0
  24. package/src/workspaces/index.ts +3 -1
  25. package/src/workspaces/ls.ts +56 -11
  26. package/src/workspaces/merge.ts +29 -13
  27. package/src/workspaces/new.ts +17 -15
  28. package/src/workspaces/overlap.test.ts +53 -0
  29. package/src/workspaces/overlap.ts +86 -0
  30. package/src/workspaces/preview.test.ts +81 -0
  31. package/src/workspaces/preview.ts +162 -0
  32. package/src/workspaces/refresh.ts +26 -24
  33. package/src/workspaces/rm.ts +6 -1
  34. package/src/workspaces/services.ts +2 -2
  35. package/src/workspaces/state.ts +56 -9
  36. package/src/workspaces/trunk.test.ts +88 -0
  37. package/sync.ts +5 -2
  38. package/src/agents/index.ts +0 -198
  39. package/src/agents/report.ts +0 -211
  40. package/src/agents/show.ts +0 -73
  41. package/src/agents/steps.ts +0 -32
  42. /package/src/{agents → bloat}/kinds.ts +0 -0
@@ -140,14 +140,14 @@ export function load(root: string, entries: Entry[]): LoadMap {
140
140
  return { files, folders, outside }
141
141
  }
142
142
 
143
- /** One line for `able agents run`. */
143
+ /** One line for `able bloat status`. */
144
144
  export function summary(map: LoadMap) {
145
145
  const words = map.folders.map((f) => f.host)
146
146
  const range = words.length > 1 ? `${n(Math.min(...words))}-${n(Math.max(...words))}` : n(words[0] ?? 0)
147
147
  return `${map.folders.length} folder${map.folders.length === 1 ? '' : 's'}, ${range} at start, +${n(map.folders[0]?.outside ?? 0)} outside`
148
148
  }
149
149
 
150
- /** The human view of `able agents load`. */
150
+ /** The human view of `able bloat load`. */
151
151
  export function render(map: LoadMap) {
152
152
  const out: string[] = []
153
153
  const width = Math.min(40, Math.max(4, ...map.files.map((f) => f.path.length)))
@@ -5,7 +5,7 @@
5
5
  import { relative } from 'node:path'
6
6
  import { bold, dim, paint256 } from '../ui.ts'
7
7
  import { kinds } from './kinds.ts'
8
- import type { Run } from './report.ts'
8
+ import type { Report } from './report.ts'
9
9
  import { clip, fit } from './scan.ts'
10
10
 
11
11
  const perPage = 10
@@ -18,8 +18,8 @@ const key = () =>
18
18
  })
19
19
 
20
20
  /** Lets the operator check findings on a terminal. Returns the answers to record, or undefined when they quit. */
21
- export async function pickInteractive(run: Run, path: string, root: string): Promise<Map<number, 'yes' | 'no'> | undefined> {
22
- const items = run.rules.filter((r) => r.n)
21
+ export async function pickInteractive(report: Report, path: string, root: string): Promise<Map<number, 'yes' | 'no'> | undefined> {
22
+ const items = report.rules.filter((r) => r.n)
23
23
  if (!items.length) return new Map()
24
24
  const checked = new Set(items.filter((r) => (r.pick ?? r.recommend) === 'yes').map((r) => r.n!))
25
25
  const pages = Math.ceil(items.length / perPage)
@@ -0,0 +1,286 @@
1
+ // Step 7, report: checks the agent's findings (every block classified, every rule not kept proposed), merges them with
2
+ // steps 1 to 4, works out the impact, and writes the report to `<journal>/bloat/<yyyy-mm-dd>-<hhmm>.json`. Every report is
3
+ // kept. Step 9's picks are written into the same file by `able bloat pick`. The report is the one source `show` and the
4
+ // dashboard read; it holds each rule's span, so a view can highlight its words.
5
+ //
6
+ // On disk (`able.bloat.report@1`) a rule keeps no copy of its words or its path: both come from its block (the block's
7
+ // text at the rule's span), filled in again by `readReport`. Reports from before the rename (`able.agents@1`, which
8
+ // stored both, and `able.agents@2`, the same as now) still read, from the old folder too (steps.ts, legacyReportsDir).
9
+ // A report is written again only by `pick`, in the current format.
10
+
11
+ import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
12
+ import { basename, dirname, join, relative } from 'node:path'
13
+ import type { Blocks } from './blocks.ts'
14
+ import type { Checks } from './checks.ts'
15
+ import type { Checked, Rule } from './findings.ts'
16
+ import { unproposed } from './findings.ts'
17
+ import { pickOrder, type Kind } from './kinds.ts'
18
+ import { chain, type LoadMap } from './load.ts'
19
+ import { countWords, type Entry } from './scan.ts'
20
+ import { legacyReportsDir, reportsDir, steps } from './steps.ts'
21
+ import type { Finding, HistoryLine, Report } from './types.ts'
22
+
23
+ export type { Finding, HistoryLine, Report }
24
+
25
+ export const format = 'able.bloat.report@1'
26
+
27
+ /** The formats `readReport` reads: every one written so far. */
28
+ export const formats = ['able.agents@1', 'able.agents@2', format] as const satisfies Report['format'][]
29
+
30
+ /** Kinds whose words leave the start-up set once applied: everything but keep, and a conflict until it is picked. */
31
+ const leaves = (k: Kind) => k !== 'keep' && k !== 'conflict'
32
+
33
+ /** Whether a rule's words load at start for an agent in `folder`: its file is an instruction file or always-on rule in
34
+ * the folder's chain, or it is a skill's description. */
35
+ export function atStart(load: LoadMap, blocks: Blocks) {
36
+ const fileLoad = new Map(load.files.map((f) => [f.path, f]))
37
+ const blockOf = new Map(blocks.blocks.map((b) => [b.id, b]))
38
+ return (r: { path: string; block: string }, folder: string) => {
39
+ const f = fileLoad.get(r.path)
40
+ if (!f) return false
41
+ if (f.load === 'skill') return blockOf.get(r.block)?.heading[0] === 'description'
42
+ return (f.load === 'always' || f.load === 'folder') && chain(folder).includes(f.folder)
43
+ }
44
+ }
45
+
46
+ const words = (s: string) => new Set(s.toLowerCase().match(/[a-z0-9]+/g) ?? [])
47
+ /** How alike two sets of words are, 0 to 1: the share of their words they have in common. */
48
+ function alike(x: Set<string>, y: Set<string>) {
49
+ const both = [...x].filter((w) => y.has(w)).length
50
+ return both / (x.size + y.size - both || 1)
51
+ }
52
+
53
+ /** Lineage: for each rule, the applied finding of the report before whose words it carries, in the file the finding
54
+ * was applied to. Half alike or more counts; the most alike wins. */
55
+ export function lineage(previous: Report | undefined) {
56
+ const applied = (previous?.rules ?? []).flatMap((r) => (r.applied ? [{ id: r.id, target: r.applied.target, words: words(r.text) }] : []))
57
+ return (r: { path: string; text: string }) => {
58
+ const mine = words(r.text)
59
+ let best: { id: string; score: number } | undefined
60
+ for (const a of applied) {
61
+ if (a.target !== r.path) continue
62
+ const score = alike(a.words, mine)
63
+ if (score >= 0.5 && score > (best?.score ?? 0)) best = { id: a.id, score }
64
+ }
65
+ return best?.id
66
+ }
67
+ }
68
+
69
+ export function reportsFolder(root: string, journal: string) {
70
+ return join(root, journal, reportsDir)
71
+ }
72
+
73
+ /** The report files, oldest first, from the folder and the one before the rename; a name in both is the folder's. */
74
+ export function reports(root: string, journal: string) {
75
+ const byName = new Map<string, string>()
76
+ for (const name of [reportsDir, legacyReportsDir]) {
77
+ const dir = join(root, journal, name)
78
+ if (existsSync(dir)) for (const f of readdirSync(dir)) if (/^\d{4}-\d{2}-\d{2}-\d{4}\.json$/.test(f) && !byName.has(f)) byName.set(f, join(dir, f))
79
+ }
80
+ return [...byName.values()].sort((a, b) => basename(a).localeCompare(basename(b)))
81
+ }
82
+
83
+ /** A report from its text, whichever format it was written in, with each rule's words and path filled in from its block. */
84
+ export function parseReport(text: string): Report {
85
+ const report = JSON.parse(text) as Report
86
+ if (!formats.includes(report.format)) throw new Error(`a report in format ${JSON.stringify(report.format)}: this able reads ${formats.join(' and ')}`)
87
+ const blockOf = new Map(report.blocks.blocks.map((b) => [b.id, b]))
88
+ for (const r of report.rules) {
89
+ const b = blockOf.get(r.block)
90
+ if (!b) continue
91
+ r.path ??= b.path
92
+ r.text ??= b.text.slice(r.span[0] - b.span[0], r.span[1] - b.span[0])
93
+ }
94
+ return report
95
+ }
96
+
97
+ export const readReport = (path: string) => parseReport(readFileSync(path, 'utf8'))
98
+
99
+ /** A report file by its name or the start of it (`2026-11-16`, `2026-11-16-2240`), or its code (`K3M9QA`); else the
100
+ * latest. */
101
+ export function findReport(root: string, journal: string, name?: string) {
102
+ const all = reports(root, journal)
103
+ if (!name) return all.at(-1)
104
+ const asked = name.replace(/\.json$/, '')
105
+ return all.filter((p) => basename(p).startsWith(asked) || reportCode(basename(p, '.json')) === asked.toUpperCase()).at(-1)
106
+ }
107
+
108
+ /** What blocks the report: findings errors, blocks not classified, rules not proposed. */
109
+ export function problems(c: Checked) {
110
+ return [...c.errors, ...c.missing.map((id) => `${id}: not classified`), ...unproposed(c).map((r) => `${r.id}: ${r.kind}, no proposal yet`)]
111
+ }
112
+
113
+ /** Step 10's tally: yes picks applied, and still to apply. */
114
+ export function applyTally(report: Report) {
115
+ const yes = report.rules.filter((r) => r.n && r.pick === 'yes')
116
+ const applied = yes.filter((r) => r.applied).length
117
+ return { applied, left: yes.length - applied, line: yes.length ? `${applied} applied, ${yes.length - applied} to apply` : 'waits for yes picks' }
118
+ }
119
+
120
+ /** The step lines that change after a report is written (picks, applies), worked out again from the report; a report
121
+ * from before a step existed gains it. */
122
+ function refreshSteps(report: Report) {
123
+ for (const s of steps) if (!report.steps.some((x) => x.id === s.id)) report.steps.push({ n: s.n, id: s.id, kind: s.kind, summary: '' })
124
+ const lines: Record<string, string> = { pick: tally(report).line, apply: applyTally(report).line }
125
+ for (const s of report.steps) if (s.id in lines) s.summary = lines[s.id]!
126
+ }
127
+
128
+ /** Step 9's tally: findings to pick, and the answers so far. */
129
+ export function tally(report: Report) {
130
+ const numbered = report.rules.filter((r) => r.n)
131
+ const yes = numbered.filter((r) => r.pick === 'yes').length
132
+ const no = numbered.filter((r) => r.pick === 'no').length
133
+ return { numbered: numbered.length, yes, no, open: numbered.length - yes - no, line: `${yes + no} of ${numbered.length} picked` }
134
+ }
135
+
136
+ // Letters and digits that can't be mistaken for each other read aloud or copied by hand: no 0/O, no 1/I/L.
137
+ const codeAlphabet = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'
138
+ /** A report's short handle (as conformance reports have, `X7E5LI`), from its name, so it needs no storing and never
139
+ * changes: the name's FNV-1a hash in six of `codeAlphabet`'s characters. */
140
+ export function reportCode(name: string) {
141
+ let h = 0x811c9dc5
142
+ for (const ch of name) h = Math.imul(h ^ ch.charCodeAt(0), 0x01000193) >>> 0
143
+ let code = ''
144
+ for (let i = 0; i < 6; i++, h = Math.floor(h / codeAlphabet.length)) code += codeAlphabet[h % codeAlphabet.length]
145
+ return code
146
+ }
147
+
148
+ /** A report's line in the history: the picker's label and the trend's point. */
149
+ export function historyLine(path: string, report: Report, from = ''): HistoryLine {
150
+ const root = report.impact.folders.find((f) => f.folder === '.')
151
+ const { line: _line, ...picks } = tally(report)
152
+ const name = basename(path, '.json')
153
+ return {
154
+ name,
155
+ code: reportCode(name),
156
+ file: from ? relative(from, path) : path,
157
+ format: report.format,
158
+ at: report.at,
159
+ files: report.scan.length,
160
+ rules: report.rules.length,
161
+ start: { before: root?.before ?? 0, after: root?.after ?? 0 },
162
+ byKind: Object.fromEntries(Object.entries(report.impact.byKind).map(([k, v]) => [k, v.rules])),
163
+ picks,
164
+ }
165
+ }
166
+
167
+ /** Every report's line, oldest first. */
168
+ export const history = (root: string, journal: string) => reports(root, journal).map((p) => historyLine(p, readReport(p), root))
169
+
170
+ /** Builds the report. `path` is where it will be written; `summaries` are steps 1 to 6's lines, the rest are worked out here. */
171
+ export function build(input: {
172
+ scan: Entry[]
173
+ load: LoadMap
174
+ blocks: Blocks
175
+ checks: Checks
176
+ checked: Checked
177
+ summaries: Record<string, string>
178
+ root: string
179
+ path: string
180
+ at: Date
181
+ /** The report before this one: its picks carry forward by rule id, so what was answered isn't asked again. */
182
+ previous?: Report
183
+ }): Report {
184
+ const { scan, load, blocks, checks, checked } = input
185
+ const earlier = new Map(input.previous?.rules.flatMap((r) => (r.pick ? [[r.id, r.pick] as const] : [])))
186
+ const cameFrom = lineage(input.previous)
187
+ const blockOf = new Map(blocks.blocks.map((b) => [b.id, b]))
188
+ let n = 0
189
+ const rules = checked.rules
190
+ .map((r) => {
191
+ const b = blockOf.get(r.block)!
192
+ const line = b.lines[0] + b.text.slice(0, r.span[0] - b.span[0]).split('\n').length - 1
193
+ const from = cameFrom(r)
194
+ return { ...r, line, words: countWords(r.text), ...(from && { from }) }
195
+ })
196
+ .sort((a, b) => pickOrder.indexOf(a.kind) - pickOrder.indexOf(b.kind) || a.path.localeCompare(b.path) || a.span[0] - b.span[0])
197
+ .map((r) => (r.kind === 'keep' ? r : { ...r, n: ++n, ...(earlier.has(r.id) && { pick: earlier.get(r.id) }) }))
198
+
199
+ const starts = atStart(load, blocks)
200
+ const folders = load.folders.map((f) => ({
201
+ folder: f.folder,
202
+ before: f.host,
203
+ after: f.host - rules.filter((r) => leaves(r.kind) && starts(r, f.folder)).reduce((s, r) => s + r.words, 0),
204
+ }))
205
+ const byKind: Report['impact']['byKind'] = {}
206
+ for (const r of rules) {
207
+ const k = (byKind[r.kind] ??= { rules: 0, words: 0 })
208
+ k.rules++
209
+ k.words += r.words
210
+ }
211
+
212
+ const pathRules = scan.some((e) => e.kind === 'rule')
213
+ const agentsMd = scan
214
+ .filter((e) => e.kind === 'instructions' && e.path.endsWith('CLAUDE.md') && !e.path.endsWith('CLAUDE.local.md'))
215
+ .map((e) => {
216
+ const dir = dirname(e.path)
217
+ const at = (name: string) => (dir === '.' ? name : `${dir}/${name}`)
218
+ const blockers = [
219
+ ...(existsSync(join(input.root, at('CLAUDE.local.md'))) ? ['a CLAUDE.local.md beside it stops Claude reading AGENTS.md'] : []),
220
+ ...(scan.some((x) => x.path === at('AGENTS.md')) ? ['an AGENTS.md already exists beside it: merge, do not overwrite'] : []),
221
+ ...(pathRules && dir === '.' ? ['.claude/rules with paths: are Claude-only and stay where they are'] : []),
222
+ ]
223
+ return { path: e.path, blockers }
224
+ })
225
+
226
+ const root = folders.find((f) => f.folder === '.')
227
+ const summaries: Record<string, string> = {
228
+ ...input.summaries,
229
+ report: relative(input.root, input.path),
230
+ show: `${root ? root.before - root.after : 0} words leave the root's start`,
231
+ compare: input.previous ? 'able bloat compare: this report against the one before' : 'waits for a second report',
232
+ }
233
+ const report: Report = {
234
+ format,
235
+ at: input.at.toISOString(),
236
+ steps: steps.map((s) => ({ n: s.n, id: s.id, kind: s.kind, summary: summaries[s.id] ?? '' })),
237
+ scan,
238
+ load,
239
+ blocks,
240
+ checks,
241
+ rules,
242
+ impact: { folders, byKind },
243
+ agentsMd,
244
+ }
245
+ refreshSteps(report)
246
+ return report
247
+ }
248
+
249
+ /** The report's file name: local date and time, so two reports a minute apart are both kept. */
250
+ export function reportName(at = new Date()) {
251
+ const p = (v: number) => String(v).padStart(2, '0')
252
+ return `${at.getFullYear()}-${p(at.getMonth() + 1)}-${p(at.getDate())}-${p(at.getHours())}${p(at.getMinutes())}.json`
253
+ }
254
+
255
+ /** Where a report taken at `at` is written. */
256
+ export const reportPath = (root: string, journal: string, at: Date) => join(reportsFolder(root, journal), reportName(at))
257
+
258
+ /** JSON broken into lines down to the lists (rules, blocks, files), each of their items on one line: small, and still a
259
+ * readable diff. */
260
+ export function lines(value: unknown, depth = 0): string {
261
+ const flat = JSON.stringify(value)
262
+ if (value === null || typeof value !== 'object' || flat.length <= 100 || depth > 2 || (depth === 2 && !Array.isArray(value))) return flat
263
+ const pad = ' '.repeat(depth + 1)
264
+ const items = Array.isArray(value) ? value.map((v) => lines(v, depth + 1)) : Object.entries(value).map(([k, v]) => `${JSON.stringify(k)}: ${lines(v, depth + 1)}`)
265
+ const [open, close] = Array.isArray(value) ? ['[', ']'] : ['{', '}']
266
+ return `${open}\n${items.map((i) => pad + i).join(',\n')}\n${' '.repeat(depth)}${close}`
267
+ }
268
+
269
+ /** Writes a report file, always in the current format, its step lines up to date; the one place its form on disk is set. */
270
+ export async function saveReport(path: string, report: Report) {
271
+ mkdirSync(dirname(path), { recursive: true })
272
+ refreshSteps(report)
273
+ const rules = report.rules.map(({ text: _text, path: _path, ...r }) => r)
274
+ await Bun.write(path, `${lines({ ...report, format, rules })}\n`)
275
+ }
276
+
277
+ /** Step 9: records the operator's yes or no on numbered findings in the report, and saves it. An applied finding keeps
278
+ * its yes. */
279
+ export async function pick(path: string, report: Report, answers: Map<number, 'yes' | 'no'>) {
280
+ const known = new Set(report.rules.flatMap((r) => (r.n ? [r.n] : [])))
281
+ const unknown = [...answers.keys()].filter((x) => !known.has(x))
282
+ if (unknown.length) return unknown
283
+ for (const r of report.rules) if (r.n && answers.has(r.n) && !r.applied) r.pick = answers.get(r.n)
284
+ await saveReport(path, report)
285
+ return unknown
286
+ }
@@ -81,13 +81,13 @@ export function scan(root: string, files: string[]): Entry[] {
81
81
  .sort((a, b) => a.path.localeCompare(b.path))
82
82
  }
83
83
 
84
- /** One line for `able agents run`. */
84
+ /** One line for `able bloat status`. */
85
85
  export const summary = (entries: Entry[]) => `${entries.length} files, ${n(entries.reduce((sum, e) => sum + e.words, 0))} words`
86
86
 
87
87
  /** A path cut in the middle to fit, so the view stays narrow enough for a terminal and a chat. */
88
88
  export const fit = (path: string, max: number) => (path.length <= max ? path : `${path.slice(0, 12)}...${path.slice(-(max - 15))}`)
89
89
 
90
- /** The human view of `able agents scan`. */
90
+ /** The human view of `able bloat scan`. */
91
91
  export function render(entries: Entry[]) {
92
92
  const width = Math.min(48, Math.max(4, ...entries.map((e) => e.path.length)))
93
93
  const lines = [` ${'PATH'.padEnd(width)} ${'KIND'.padEnd(16)} ${'WORDS'.padStart(6)} ${'LINES'.padStart(5)}`]
@@ -0,0 +1,79 @@
1
+ // Step 8, show: a report read back from its file and printed as plain text, narrow enough for a terminal and a chat.
2
+ // `--step <n>` prints one step's full view from the same file, so any step can be looked at again later.
3
+
4
+ import { relative } from 'node:path'
5
+ import { dim } from '../ui.ts'
6
+ import * as blocks from './blocks.ts'
7
+ import * as checks from './checks.ts'
8
+ import * as grid from './grid.ts'
9
+ import { kinds, pickOrder } from './kinds.ts'
10
+ import * as load from './load.ts'
11
+ import { reportName, tally, type Finding, type Report } from './report.ts'
12
+ import { who } from './steps.ts'
13
+ import { clip, fit, n, render as renderScan } from './scan.ts'
14
+
15
+ /** One step's full view, from the report file. */
16
+ export function step(report: Report, id: string) {
17
+ // In reading order, as the file has them; the report stores them in pick order.
18
+ const checked = { rules: [...report.rules].sort((a, b) => a.span[0] - b.span[0]), missing: [], errors: [] }
19
+ const views: Record<string, () => string> = {
20
+ scan: () => renderScan(report.scan),
21
+ load: () => load.render(report.load),
22
+ blocks: () => blocks.render(report.blocks),
23
+ checks: () => checks.render(report.checks),
24
+ classify: () => grid.byKind(report.blocks, checked),
25
+ }
26
+ return views[id]?.() ?? ` Step ${id} has no view of its own: its result is in the findings below.\n\n${findings(report)}`
27
+ }
28
+
29
+ /** A finding as two lines: where it is and its words, then its proposal. `mark` comes first, as `show`'s pick box. */
30
+ export function findingLine(r: Finding, mark = '') {
31
+ return [
32
+ ` ${mark}${String(r.n).padStart(3)} ${r.confidence.padEnd(4)} ${fit(`${r.path}:${r.line}`, 34).padEnd(34)} "${clip(r.text.replace(/\s+/g, ' '), 46)}"`,
33
+ `${' '.repeat(mark.length + 13)}→ ${r.proposal ? `${clip(r.proposal.target, 40)}: ${clip(r.proposal.change, 64)}` : dim('no proposal yet')}`,
34
+ ]
35
+ }
36
+
37
+ function findings(report: Report) {
38
+ const out: string[] = []
39
+ const numbered = report.rules.filter((r) => r.n)
40
+ for (const kind of pickOrder) {
41
+ const list = numbered.filter((r) => r.kind === kind)
42
+ if (!list.length) continue
43
+ out.push(` ${kinds[kind].letter} ${kind.toUpperCase()} ${list.length} ${dim(`→ ${kinds[kind].becomes}`)}`)
44
+ for (const r of list) {
45
+ const pick = r.pick === 'yes' ? '[y]' : r.pick === 'no' ? '[n]' : '[ ]'
46
+ const [where, proposal] = findingLine(r, pick)
47
+ out.push(`${where}${r.recommend ? dim(` rec ${r.recommend}`) : ''}`, `${' '.repeat(16)}${dim(clip(r.reason, 92))}`, proposal!)
48
+ }
49
+ out.push('')
50
+ }
51
+ return out.join('\n')
52
+ }
53
+
54
+ export function render(report: Report, path: string, root: string) {
55
+ const out: string[] = []
56
+ const { numbered } = tally(report)
57
+ out.push(
58
+ ` REPORT ${reportName(new Date(report.at))
59
+ .replace(/\.json$/, '')
60
+ .replace(/-(\d\d)(\d\d)$/, ' $1:$2')} ${relative(root, path)} ${report.format}`,
61
+ '',
62
+ )
63
+ out.push(' STEPS')
64
+ for (const s of report.steps) out.push(` ${String(s.n).padStart(2)} ${who[s.kind as keyof typeof who]} ${s.id.padEnd(10)} ${s.summary}`)
65
+
66
+ out.push('', ` WORDS AT START, BY FOLDER (host files; tokens are about 1.3 x words)`)
67
+ out.push(` ${'folder'.padEnd(24)} ${'now'.padStart(6)} ${'after'.padStart(6)} ${'saved'.padStart(6)}`)
68
+ for (const f of report.impact.folders)
69
+ out.push(` ${clip(f.folder === '.' ? '(root)' : f.folder, 24).padEnd(24)} ${n(f.before).padStart(6)} ${n(f.after).padStart(6)} ${`-${n(f.before - f.after)}`.padStart(6)}`)
70
+
71
+ const kept = report.impact.byKind.keep
72
+ out.push('', ` FINDINGS ${numbered} to pick${kept ? `, ${kept.rules} rules kept` : ''} [y] yes [n] no [ ] not picked yet`, '')
73
+ out.push(findings(report))
74
+
75
+ out.push(' AGENTS.md (vendor-neutral; converting is version 2)')
76
+ for (const a of report.agentsMd) out.push(` ${a.path.padEnd(24)} ${a.blockers.length ? a.blockers.join('; ') : 'would convert: AGENTS.md, plus a CLAUDE.md of one line, @AGENTS.md'}`)
77
+ if (!report.agentsMd.length) out.push(' no CLAUDE.md files')
78
+ return out.join('\n')
79
+ }
@@ -0,0 +1,32 @@
1
+ // The steps of a report, as data: `able bloat status` walks them, the skill follows them, a dashboard page will show them.
2
+
3
+ export type StepKind = 'mechanical' | 'agent' | 'operator'
4
+
5
+ export interface Step {
6
+ n: number
7
+ /** The step's one name, also its command: `able bloat <id>`. */
8
+ id: string
9
+ kind: StepKind
10
+ }
11
+
12
+ /** The letter each kind of step shows as in `status` and `show`. */
13
+ export const who: Record<StepKind, string> = { mechanical: 'M', agent: 'A', operator: 'O' }
14
+
15
+ export const steps: Step[] = [
16
+ { n: 1, id: 'scan', kind: 'mechanical' },
17
+ { n: 2, id: 'load', kind: 'mechanical' },
18
+ { n: 3, id: 'blocks', kind: 'mechanical' },
19
+ { n: 4, id: 'checks', kind: 'mechanical' },
20
+ { n: 5, id: 'classify', kind: 'agent' },
21
+ { n: 6, id: 'propose', kind: 'agent' },
22
+ { n: 7, id: 'report', kind: 'mechanical' },
23
+ { n: 8, id: 'show', kind: 'mechanical' },
24
+ { n: 9, id: 'pick', kind: 'operator' },
25
+ { n: 10, id: 'apply', kind: 'agent' },
26
+ { n: 11, id: 'compare', kind: 'mechanical' },
27
+ ]
28
+
29
+ /** The folder reports are written to, under the host's journal. One name, so renaming the diagnostic is one line. */
30
+ export const reportsDir = 'bloat'
31
+ /** Where reports were written before the diagnostic was named bloat (as `able agents`): still read, never written. */
32
+ export const legacyReportsDir = 'agents'
@@ -1,4 +1,4 @@
1
- // The shapes a run is made of, types only and importing nothing, so api/ and web/ can read a run file typed by the CLI
1
+ // The shapes a report is made of, types only and importing nothing, so api/ and web/ can read a report file typed by the CLI
2
2
  // that wrote it without type-checking the CLI's code. Each step's module re-exports its own.
3
3
 
4
4
  /** The ten kinds a rule can be (kinds.ts holds their letters and meanings). */
@@ -148,10 +148,15 @@ export interface Finding extends Rule {
148
148
  line: number
149
149
  words: number
150
150
  pick?: 'yes' | 'no'
151
+ /** Step 10: where a yes pick went, recorded by `able bloat apply --record` once the agent has made the change. */
152
+ applied?: { at: string; target: string }
153
+ /** Lineage: the id of the finding in the report before that this rule came from, when it was applied and moved here
154
+ * (its words found again in the file it was applied to). */
155
+ from?: string
151
156
  }
152
157
 
153
- export interface Run {
154
- format: 'able.agents@1' | 'able.agents@2'
158
+ export interface Report {
159
+ format: 'able.agents@1' | 'able.agents@2' | 'able.bloat.report@1'
155
160
  at: string
156
161
  steps: { n: number; id: string; kind: string; summary: string }[]
157
162
  scan: Entry[]
@@ -169,3 +174,43 @@ export interface Run {
169
174
  /** Each CLAUDE.md as a vendor-neutral AGENTS.md: what would convert, and what stands in the way (version 2 converts). */
170
175
  agentsMd: { path: string; blockers: string[] }[]
171
176
  }
177
+
178
+ // compare.ts
179
+ /** Step 11: a report against the one after it, once picks were applied in between. */
180
+ export interface Comparison {
181
+ /** Words at start an agent in each folder loads: before, predicted after the applied picks, and actual. */
182
+ folders: { folder: string; before: number; predicted: number; actual: number | null }[]
183
+ /** Each applied finding: gone from where it was, or still there; and the rule it became, when the new report found
184
+ * its words again in the file it went to (its `from`). */
185
+ applied: { n: number; id: string; kind: Kind; path: string; target: string; gone: boolean; became?: { id: string; kind: Kind; path: string }; state: string }[]
186
+ /** Findings of the old report that are gone though nobody picked them yes: a rule lost, or its words changed. */
187
+ unpicked: { n: number; id: string; kind: Kind; path: string; text: string }[]
188
+ /** Yes picks that are gone though nothing recorded where they went (`able bloat apply --record` was missed). */
189
+ unrecorded: { n: number; id: string; kind: Kind; path: string; text: string }[]
190
+ }
191
+
192
+ /** `able bloat compare --json`: the comparison and the two reports' names. */
193
+ export interface Compared {
194
+ c: Comparison
195
+ names: { old: string; next: string }
196
+ }
197
+
198
+ /** One report in the diagnostic's history (`able bloat history`): what the report picker shows of it, and a point on
199
+ * the trend charts. Worked out from the report file, so it never disagrees with it. */
200
+ export interface HistoryLine {
201
+ /** The report's name, its file's: `2026-11-18-1449`. */
202
+ name: string
203
+ /** Its short handle, easy to say and type: six letters and digits from its name (report.ts, reportCode). */
204
+ code: string
205
+ /** Its file, from the root, and the format it was written in. */
206
+ file: string
207
+ format: Report['format']
208
+ at: string
209
+ files: number
210
+ rules: number
211
+ /** Host words an agent starting at the root loads, now and with every proposal applied. */
212
+ start: { before: number; after: number }
213
+ /** Rules per kind. */
214
+ byKind: Partial<Record<Kind, number>>
215
+ picks: { numbered: number; yes: number; no: number; open: number }
216
+ }
package/src/commit.ts CHANGED
@@ -14,13 +14,14 @@ import { runChecks } from './checks.ts'
14
14
  import { failOnMerge, git, gitLoud } from './git.ts'
15
15
  import { status, working } from './status.ts'
16
16
  import { bold, cancel, confirm, dim, fail, green } from './ui.ts'
17
- import { current } from './workspaces/state.ts'
17
+ import { current, refuseInPreview } from './workspaces/state.ts'
18
18
 
19
19
  const argv = process.argv.slice(3)
20
20
  const [msg, ...named] = argv.filter((a) => !a.startsWith('--'))
21
21
  if (!msg) fail('usage: able commit "<message>" [<path>…] [--dry] [--yes]')
22
22
 
23
23
  const at = await current()
24
+ refuseInPreview(at, 'able commit')
24
25
  const root = at.path
25
26
  failOnMerge(root)
26
27
 
package/src/git.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  // The git calls every command shares: capture output, stream it, or stay quiet; and the questions commands keep
2
2
  // asking (dirty, unpushed, behind, merge in progress) answered once.
3
3
 
4
+ import { existsSync, statSync } from 'node:fs'
4
5
  import { dirname, resolve } from 'node:path'
5
- import { dim, fail, red } from './ui.ts'
6
+ import { dim, fail, red, when, yellow } from './ui.ts'
6
7
 
7
8
  const spawn = (cwd: string, args: string[], stdio: 'inherit' | 'ignore') => Bun.spawnSync(['git', '-C', cwd, ...args], { stdout: stdio, stderr: stdio })
8
9
 
@@ -32,7 +33,47 @@ export const dirtyCount = (cwd: string) => lines(cwd, 'status', '--porcelain').l
32
33
  /** Commits reachable from HEAD and from no remote ref: what exists only here. */
33
34
  export const unpushedCount = (cwd: string) => count(cwd, 'HEAD', '--not', '--remotes')
34
35
 
35
- export const fetchTrunk = (cwd: string, trunk: string) => gitQuiet(cwd, 'fetch', '--quiet', 'origin', trunk)
36
+ /** When `origin/<trunk>` was last fetched here: FETCH_HEAD's time, else the remote ref's last move. */
37
+ export function lastFetched(cwd: string, trunk: string) {
38
+ const head = resolve(cwd, git(cwd, 'rev-parse', '--git-path', 'FETCH_HEAD'))
39
+ const at = existsSync(head) ? statSync(head).mtime : new Date(git(cwd, 'log', '-g', '-1', '--format=%cI', `refs/remotes/origin/${trunk}`) || NaN)
40
+ return Number.isNaN(at.getTime()) ? 'never' : when(at)
41
+ }
42
+
43
+ /**
44
+ * Fetches `origin/<trunk>`, the trunk every command means. When origin can't be reached it says so and carries on
45
+ * with the copy it has; a command that must push then calls `needOrigin`. Returns whether the fetch worked.
46
+ */
47
+ export function fetchTrunk(cwd: string, trunk: string) {
48
+ if (gitQuiet(cwd, 'fetch', '--quiet', 'origin', trunk)) return true
49
+ console.log(yellow(` couldn't reach origin; using origin/${trunk} as of ${lastFetched(cwd, trunk)}`))
50
+ return false
51
+ }
52
+
53
+ /** Fails when the fetch couldn't reach origin and the command is about to push. */
54
+ export const needOrigin = (fetched: boolean, trunk: string) => fetched || fail(`couldn't reach origin/${trunk}, and this has to push; nothing pushed`)
55
+
56
+ /** Commits on `local <trunk>` that `origin/<trunk>` doesn't have, oldest first, as `<hash> <subject>`. */
57
+ // A missing `local <trunk>` makes git fail, and `lines` then answers no commits.
58
+ export const unpushedOnTrunk = (cwd: string, trunk: string, notIn?: string) =>
59
+ lines(cwd, 'log', '--reverse', '--format=%h %s', `origin/${trunk}..refs/heads/${trunk}`, ...(notIn ? ['--not', notIn] : []))
60
+
61
+ /** Commits on `local <trunk>`, not on `origin/<trunk>`, that HEAD took in through a merge: off its first-parent line, so
62
+ * a branch's own commits never count, even when local <trunk> was fast-forwarded onto them. `%h %s` each, oldest first. */
63
+ export function carriedFromLocal(cwd: string, trunk: string) {
64
+ const fromLocal = new Set(lines(cwd, 'rev-list', `origin/${trunk}..refs/heads/${trunk}`))
65
+ const own = new Set(lines(cwd, 'rev-list', '--first-parent', `origin/${trunk}..HEAD`))
66
+ return lines(cwd, 'log', '--reverse', '--format=%H %h %s', `origin/${trunk}..HEAD`)
67
+ .map((l) => [l.slice(0, l.indexOf(' ')), l.slice(l.indexOf(' ') + 1)] as const)
68
+ .filter(([c]) => fromLocal.has(c) && !own.has(c))
69
+ .map(([, shown]) => shown)
70
+ }
71
+
72
+ /** Names the commits on `local <trunk>` a command left out, and how to bring them in. */
73
+ export function warnLeftOut(left: string[], what: string, hint: string) {
74
+ if (!left.length) return
75
+ console.log(`${yellow(`\n ${left.length} commit(s) ${what}`)}\n${left.map((l) => dim(` ${l}`)).join('\n')}\n ${dim(hint)}`)
76
+ }
36
77
 
37
78
  export const failOnMerge = (cwd: string) => git(cwd, 'rev-parse', '-q', '--verify', 'MERGE_HEAD') && fail('a merge is in progress; finish it (commit) or abort it first')
38
79
 
package/src/push.ts CHANGED
@@ -2,9 +2,10 @@
2
2
 
3
3
  import { gitLoud } from './git.ts'
4
4
  import { fail, green } from './ui.ts'
5
- import { current } from './workspaces/state.ts'
5
+ import { current, refuseInPreview } from './workspaces/state.ts'
6
6
 
7
7
  const at = await current()
8
+ refuseInPreview(at, 'able push')
8
9
  if (at.isWorkspace) fail('a workspace is merged with: able ws merge')
9
10
  if (!at.branch || at.branch === 'HEAD') fail('not on a branch')
10
11
  if (!gitLoud(at.path, 'push', '--follow-tags', 'origin', at.branch)) fail(`push of ${at.branch} failed`)
package/src/ui.ts CHANGED
@@ -15,6 +15,9 @@ export const red = paint(31)
15
15
  export const green = paint(32)
16
16
  export const yellow = paint(33)
17
17
 
18
+ /** A moment as the CLI prints it: `19 Nov 2026, 13:37`. */
19
+ export const when = (at: Date | string) => new Date(at).toLocaleString('en-GB', { dateStyle: 'medium', timeStyle: 'short' })
20
+
18
21
  /** Prints the message, reports the error and exits 1. */
19
22
  export function fail(message: string): never {
20
23
  status({ state: 'error', msg: message })