@able-autonomy/able 0.0.19 → 0.0.20

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@able-autonomy/able",
3
- "version": "0.0.19",
3
+ "version": "0.0.20",
4
4
  "description": "Able's command line and the config types a host's able.config.ts uses",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -8,25 +8,9 @@ import { readFileSync } from 'node:fs'
8
8
  import { join } from 'node:path'
9
9
  import { splitFrontmatter } from './load.ts'
10
10
  import { clip, countWords, n, type Entry } from './scan.ts'
11
+ import type { Block, Blocks } from './types.ts'
11
12
 
12
- export interface Block {
13
- id: string
14
- path: string
15
- /** The headings above it, outermost first, and any lead-in line. */
16
- heading: string[]
17
- /** First and last line, 1-based, inclusive. */
18
- lines: [number, number]
19
- /** Character offsets into the file, [from, to), so a view can highlight exactly these words. */
20
- span: [number, number]
21
- words: number
22
- text: string
23
- }
24
-
25
- export interface Blocks {
26
- blocks: Block[]
27
- /** Agent files listed but not cut, with why. */
28
- skipped: { path: string; reason: string }[]
29
- }
13
+ export type { Block, Blocks }
30
14
 
31
15
  const cuttable = (e: Entry) => ['instructions', 'rule', 'skill', 'command'].includes(e.kind) && e.origin !== 'downloaded'
32
16
 
@@ -7,36 +7,9 @@ import { existsSync, readFileSync } from 'node:fs'
7
7
  import { dirname, join, normalize } from 'node:path'
8
8
  import { loadConfig, type AbleConfig } from '../../config.ts'
9
9
  import { clip, n, type Entry } from './scan.ts'
10
+ import type { Level, LintRule, Linter, Checks } from './types.ts'
10
11
 
11
- export type Level = 'off' | 'warn' | 'error' | 'on'
12
-
13
- export interface LintRule {
14
- name: string
15
- level: Level
16
- /** The file the rule was found in: the config itself or one it imports or extends. */
17
- from: string
18
- }
19
-
20
- export interface Linter {
21
- tool: string
22
- path: string
23
- /** parsed: JSON or YAML, read exactly. text: JavaScript, read as text without running it. */
24
- read: 'parsed' | 'text'
25
- rules: LintRule[]
26
- /** Files it imports or extends that were read too. */
27
- via: string[]
28
- /** Rule sets a JavaScript config switches on by name (`js.configs.recommended`): known on, their rules unlisted. */
29
- presets?: string[]
30
- }
31
-
32
- export interface Checks {
33
- commit: Record<string, string[]>
34
- merge: string[]
35
- linters: Linter[]
36
- settings: { path: string; allow: string[]; deny: string[]; ask: string[]; hooks: Record<string, string[]> }[]
37
- recipes: { path: string; names: string[] }[]
38
- scripts: { path: string; names: string[] }[]
39
- }
12
+ export type { Level, LintRule, Linter, Checks }
40
13
 
41
14
  const tools: [RegExp, string][] = [
42
15
  [/(^|\/)(eslint\.config\.[cm]?[jt]s|\.eslintrc(\.(json|ya?ml|c?js))?)$/, 'eslint'],
@@ -176,7 +149,7 @@ function justRecipes(text: string) {
176
149
  for (const line of text.split('\n')) {
177
150
  const mod = line.match(/^mod\s+([\w-]+)/)
178
151
  if (mod) names.push(`${mod[1]}::`)
179
- const recipe = line.match(/^@?([A-Za-z_][\w-]*)\b[^:=]*:(?!=)/)
152
+ const recipe = line.match(/^@?([A-Za-z_][\w-]*)\b[^:]*:(?!=)/)
180
153
  if (recipe && !/^(set|export|alias|import|mod)\b/.test(line)) names.push(recipe[1])
181
154
  }
182
155
  return names
@@ -5,48 +5,20 @@
5
5
  import { existsSync, readFileSync } from 'node:fs'
6
6
  import { hash, type Block } from './blocks.ts'
7
7
  import { isKind, kinds, related, type Kind } from './kinds.ts'
8
+ import type { RuleFinding, Proposal, Rule } from './types.ts'
9
+
10
+ export type { RuleFinding, Proposal, Rule }
8
11
 
9
12
  export const format = 'able.agents.findings@1'
10
13
 
11
14
  /** Where the skill keeps its findings between steps: Able's per-checkout state, gitignored. */
12
15
  export const findingsPath = '.able/agents/findings.json'
13
16
 
14
- export interface RuleFinding {
15
- /** The rule's words, quoted exactly from the block (whitespace may differ). */
16
- text: string
17
- kind: Kind
18
- confidence: 'high' | 'low'
19
- /** One line: why this kind. */
20
- reason: string
21
- /** For a duplicate or a conflict: the ids of the blocks holding the other rule. */
22
- with?: string[]
23
- /** Step 6, for every rule not kept: the file the change goes in and the change itself, concrete enough to apply. */
24
- proposal?: Proposal
25
- /** Step 6: the agent's recommendation for the operator's pick. The picker starts from it. */
26
- recommend?: 'yes' | 'no'
27
- }
28
-
29
- export interface Proposal {
30
- /** The file the change goes in: a linter config, a settings file, a new rules file, the rule's own file. */
31
- target: string
32
- /** The change: the lint rule entry, the deny entry, the pointer line, the paths rule, "delete", or the question. */
33
- change: string
34
- }
35
-
36
17
  export interface Findings {
37
18
  format: typeof format
38
19
  findings: { block: string; rules: RuleFinding[] }[]
39
20
  }
40
21
 
41
- export interface Rule extends RuleFinding {
42
- /** The block's id plus a short hash of the rule's words: survives edits elsewhere in the block. */
43
- id: string
44
- block: string
45
- path: string
46
- /** Character offsets into the file, [from, to). */
47
- span: [number, number]
48
- }
49
-
50
22
  export interface Checked {
51
23
  rules: Rule[]
52
24
  /** Blocks the findings don't mention: not yet classified. */
@@ -84,6 +56,7 @@ export function check(findings: Findings, blocks: Block[]): Checked {
84
56
  if (!at) errors.push(`${id}: quote not found in the block: "${(r.text ?? '').slice(0, 50)}"`)
85
57
  else if (!isKind(r.kind)) errors.push(`${id}: unknown kind ${JSON.stringify(r.kind)} (one of ${Object.keys(kinds).join(', ')})`)
86
58
  else if (r.confidence !== 'high' && r.confidence !== 'low') errors.push(`${id}: confidence must be high or low`)
59
+ else if (r.with !== undefined && !(Array.isArray(r.with) && r.with.every((w) => typeof w === 'string'))) errors.push(`${id}: "with" is an array of block ids, as ["CLAUDE.md#d6dd73"]`)
87
60
  else if (related.includes(r.kind) && !r.with?.length) errors.push(`${id}: a ${r.kind} names the other rule's block in "with"`)
88
61
  else if (r.with?.some((w) => !byId.has(w))) errors.push(`${id}: "with" names an unknown block`)
89
62
  else if (r.proposal && (typeof r.proposal.target !== 'string' || typeof r.proposal.change !== 'string')) errors.push(`${id}: a proposal has a target and a change`)
@@ -8,8 +8,9 @@
8
8
  // able agents classify [--json] step 5's result: the agent's findings checked against the blocks, drawn by kind
9
9
  // able agents propose [--json] step 6's result: each rule not kept with its proposal, or what is still owed
10
10
  // able agents report step 7: checks the findings and writes the run to <journal>/agents/<date>-<hhmm>.json
11
- // able agents show [<run>] [--step <n>] step 8: a run read back from its file (the latest by default)
12
- // able agents pick [<yes|no> <n>…] step 9: the operator's picks in the latest run (no arguments on a terminal: checkboxes)
11
+ // able agents show [<run>] [--step <n>|--json] step 8: a run read back from its file (the latest by default)
12
+ // able agents pick [<yes|no> <n>…]… [--run <run>] step 9: the operator's picks in the latest run, or the one named
13
+ // (no arguments on a terminal: checkboxes)
13
14
  //
14
15
  // Read-only on the host's agent files: the only files written are the findings (by the skill) and the run file.
15
16
 
@@ -28,8 +29,10 @@ import * as show from './show.ts'
28
29
  import { steps, who } from './steps.ts'
29
30
 
30
31
  const [sub = '', ...args] = process.argv.slice(3)
31
- const names = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--step')
32
- const stepArg = args.includes('--step') ? args[args.indexOf('--step') + 1] : undefined
32
+ const valued = ['--step', '--run']
33
+ const names = args.filter((a, i) => !a.startsWith('--') && !valued.includes(args[i - 1] ?? ''))
34
+ const option = (name: string) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined)
35
+ const stepArg = option('--step')
33
36
  const json = args.includes('--json')
34
37
  const asGrid = args.includes('--grid')
35
38
  const root = hostRoot()
@@ -60,13 +63,13 @@ const classified = once(() => {
60
63
  })
61
64
 
62
65
  const journal = once(async () => (await loadConfig(root)).journal)
63
- /** The latest run, or the one named on the command line for `show`. */
66
+ /** The latest run, or the one named on the command line: `show <run>`, `pick --run <run>`. */
64
67
  const latest = once(async () => {
65
- const path = report.findRun(root, await journal(), sub === 'show' ? names[0] : undefined)
68
+ const path = report.findRun(root, await journal(), sub === 'show' ? names[0] : option('--run'))
66
69
  return path ? { path, run: report.readRun(path) } : undefined
67
70
  })
68
71
  type Latest = Awaited<ReturnType<typeof latest>>
69
- const requireLatest = async () => (await latest()) ?? fail('no run yet: able agents report writes one')
72
+ const requireLatest = async () => (await latest()) ?? fail(option('--run') || (sub === 'show' && names[0]) ? 'no such run' : 'no run yet: able agents report writes one')
70
73
  /** Steps 7 to 9 all show the latest run; only their line in `run` differs. */
71
74
  const latestView = (summary: (l: NonNullable<Latest>) => string, none: string) =>
72
75
  built<Latest>({ result: latest, summary: (l) => (l ? summary(l) : none), render: (l) => (l ? show.render(l.run, l.path, root) : ' No run yet.') })
@@ -113,6 +116,7 @@ async function writeReport() {
113
116
  for (const id of ['scan', 'load', 'blocks', 'checks', 'classify', 'propose']) summaries[id] = views[id].summary(await views[id].result())
114
117
  const at = new Date()
115
118
  const path = report.runPath(root, await journal(), at)
119
+ const before = report.findRun(root, await journal())
116
120
  const run = report.build({
117
121
  scan: entries(),
118
122
  load: (await views.load.result()) as load.LoadMap,
@@ -123,24 +127,32 @@ async function writeReport() {
123
127
  root,
124
128
  path,
125
129
  at,
130
+ previous: before ? report.readRun(before) : undefined,
126
131
  })
127
132
  await report.saveRun(path, run)
128
133
  console.log(`\n ${green('wrote')} ${relative(root, path)}\n\n${show.render(run, path, root)}\n`)
129
134
  }
130
135
 
131
- /** Step 9: on a terminal with no arguments, the checkbox picker; otherwise `pick yes 1 3 5`, `pick no 2`. */
136
+ /** Step 9: on a terminal with no arguments, the checkbox picker; otherwise `pick yes 1 3 5`, `pick no 2`, or both at
137
+ * once, `pick yes 1 3 no 2` (the dashboard's page records its checkboxes this way). */
132
138
  async function writePicks() {
133
139
  const l = await requireLatest()
134
- const [answer, ...numbers] = names
135
140
  let answers: Map<number, 'yes' | 'no'> | undefined
136
- if (!answer && tty && process.stdin.isTTY) {
141
+ if (!names.length && tty && process.stdin.isTTY) {
137
142
  answers = await pickInteractive(l.run, l.path, root)
138
143
  if (!answers) return console.log('\n Nothing recorded.\n')
139
- } else if (answer === 'yes' || answer === 'no') answers = new Map(numbers.map((x) => [Number(x), answer]))
140
- else fail('usage: able agents pick [<yes|no> <n>…] (no arguments on a terminal opens the checkboxes)')
144
+ } else if (names[0] === 'yes' || names[0] === 'no') {
145
+ answers = new Map()
146
+ let answer: 'yes' | 'no' = names[0]
147
+ for (const x of names.slice(1))
148
+ if (x === 'yes' || x === 'no') answer = x
149
+ else if (/^\d+$/.test(x)) answers.set(Number(x), answer)
150
+ else fail(`not a finding number: ${x}`)
151
+ } else fail('usage: able agents pick [<yes|no> <n>…]… [--run <run>] (no arguments on a terminal opens the checkboxes)')
141
152
  const unknown = await report.pick(l.path, l.run, answers)
142
153
  if (unknown.length) fail(`no finding numbered ${unknown.join(', ')} in ${relative(root, l.path)}`)
143
154
  const { yes, no, open } = report.tally(l.run)
155
+ if (json) return console.log(JSON.stringify({ run: relative(root, l.path), yes, no, open }))
144
156
  console.log(`\n ${green('recorded')} ${yes} yes, ${no} no, ${open} not picked, in ${relative(root, l.path)}\n`)
145
157
  }
146
158
 
@@ -173,7 +185,8 @@ else if (sub === 'show' && stepArg) {
173
185
  const id = l.run.steps.find((s) => String(s.n) === stepArg || s.id === stepArg)?.id
174
186
  if (!id) fail(`no step ${stepArg}: 1 to ${l.run.steps.length}, or a name`)
175
187
  console.log(`\n${show.step(l.run, id)}\n`)
176
- } else if (views[sub]) {
188
+ } else if (sub === 'show' && json) console.log(JSON.stringify((await requireLatest()).run))
189
+ else if (views[sub]) {
177
190
  const view = views[sub]
178
191
  const r = await view.result()
179
192
  console.log(json ? JSON.stringify(r) : `\n${asGrid && view.grid ? view.grid(r) : view.render(r)}\n`)
@@ -1,6 +1,10 @@
1
1
  // The ten kinds a rule can be: where it really belongs. Step 5 (classify) gives each rule exactly one; the grid, the
2
2
  // skill and `show` all read them from here.
3
3
 
4
+ import type { Kind } from './types.ts'
5
+
6
+ export type { Kind }
7
+
4
8
  export const kinds = {
5
9
  keep: { letter: '#', means: "knowledge the agent can't find itself: architecture, boundaries, why", becomes: 'stays' },
6
10
  scoped: { letter: 's', means: 'real knowledge, needed only for some files or tasks', becomes: 'a `paths:` rule, a skill or a linked doc' },
@@ -12,9 +16,7 @@ export const kinds = {
12
16
  expiring: { letter: 'x', means: 'true for now: a pivot, a migration in progress, history', becomes: 'dated, or deleted' },
13
17
  duplicate: { letter: '=', means: 'says what another rule already says', becomes: 'merged into the other' },
14
18
  conflict: { letter: '!', means: 'contradicts another rule', becomes: 'the operator picks which holds' },
15
- } as const
16
-
17
- export type Kind = keyof typeof kinds
19
+ } as const satisfies Record<Kind, { letter: string; means: string; becomes: string }>
18
20
 
19
21
  export const isKind = (k: unknown): k is Kind => typeof k === 'string' && k in kinds
20
22
 
@@ -6,43 +6,9 @@ import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node
6
6
  import { homedir } from 'node:os'
7
7
  import { dirname, join, relative, resolve } from 'node:path'
8
8
  import { countWords, fit, instructionNames, n, type Entry } from './scan.ts'
9
+ import type { LoadKind, LoadedFile, FolderLoad, OutsideFile, LoadMap } from './types.ts'
9
10
 
10
- /** always: at launch. folder: when the agent works in that folder. paths: a rule whose `paths:` match a file it touches.
11
- * skill: its name and description at launch, the body on use. config: settings, hooks and MCP, not text the agent reads.
12
- * never: not loaded by Claude here. */
13
- export type LoadKind = 'always' | 'folder' | 'paths' | 'skill' | 'config' | 'never'
14
-
15
- export interface LoadedFile {
16
- path: string
17
- load: LoadKind
18
- /** The folder it belongs to, from the root ('.' for the root): where an instruction file sits, or the folder that holds its `.claude/`. */
19
- folder: string
20
- /** Words loaded at launch by an agent in `folder` (with any `@` imports), and words loaded only on use. */
21
- atStart: number
22
- onUse: number
23
- imports?: string[]
24
- note?: string
25
- }
26
-
27
- export interface FolderLoad {
28
- folder: string
29
- host: number
30
- outside: number
31
- }
32
-
33
- export interface OutsideFile {
34
- path: string
35
- /** `broken`: a symlink whose target is gone, so Claude loads nothing from it. */
36
- load: LoadKind | 'broken'
37
- atStart: number
38
- onUse: number
39
- }
40
-
41
- export interface LoadMap {
42
- files: LoadedFile[]
43
- folders: FolderLoad[]
44
- outside: OutsideFile[]
45
- }
11
+ export type { LoadKind, LoadedFile, FolderLoad, OutsideFile, LoadMap }
46
12
 
47
13
  const home = homedir()
48
14
  const tilde = (p: string) => (p.startsWith(home) ? `~${p.slice(home.length)}` : p)
@@ -82,8 +48,10 @@ function importsOf(file: string, seen = new Set<string>()): string[] {
82
48
  return found
83
49
  }
84
50
 
85
- /** The folder an agent file belongs to: an instruction file's own folder, else the folder holding its `.claude/` or `.agents/`. */
51
+ /** The folder an agent file belongs to: an instruction file's own folder, else the folder holding its `.claude/` or
52
+ * `.agents/`. A root `skills/` skill that is not `source` is linked into the root's `.claude/skills/`, so it is the root's. */
86
53
  function folderOf(path: string) {
54
+ if (/^skills\/[^/]+\/SKILL\.md$/.test(path)) return '.'
87
55
  const m = path.match(/^(.*?)(?:^|\/)\.(?:claude|agents)\//)
88
56
  const dir = m ? m[1] : dirname(path)
89
57
  return dir === '' ? '.' : dir
@@ -1,7 +1,10 @@
1
1
  // Step 7, report: checks the agent's findings (every block classified, every rule not kept proposed), merges them with
2
2
  // steps 1 to 4, works out the impact, and writes the run to `<journal>/agents/<yyyy-mm-dd>-<hhmm>.json`. Every run is
3
- // kept. Step 9's picks are written into the same file by `able agents pick`. The run is the one source `show` and,
4
- // later, the dashboard read; it holds each rule's span, so a view can highlight its words.
3
+ // kept. Step 9's picks are written into the same file by `able agents pick`. The run 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.agents@2`) a rule keeps no copy of its words or its path: both come from its block (the block's text
7
+ // at the rule's span), filled in again by `readRun`. `@1` runs, which stored both, still read.
5
8
 
6
9
  import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
7
10
  import { dirname, join, relative } from 'node:path'
@@ -13,37 +16,14 @@ import { pickOrder, type Kind } from './kinds.ts'
13
16
  import { chain, type LoadMap } from './load.ts'
14
17
  import { countWords, type Entry } from './scan.ts'
15
18
  import { runsDir, steps } from './steps.ts'
19
+ import type { Finding, Run } from './types.ts'
16
20
 
17
- export const format = 'able.agents@1'
21
+ export type { Finding, Run }
18
22
 
19
- export interface Finding extends Rule {
20
- /** The number the operator picks it by, in the order `show` lists them; kept rules have none. */
21
- n?: number
22
- /** 1-based line of the rule's first word in its file. */
23
- line: number
24
- words: number
25
- pick?: 'yes' | 'no'
26
- }
23
+ export const format = 'able.agents@2'
27
24
 
28
- export interface Run {
29
- format: typeof format
30
- at: string
31
- steps: { n: number; id: string; kind: string; summary: string }[]
32
- scan: Entry[]
33
- load: LoadMap
34
- blocks: Blocks
35
- checks: Checks
36
- /** Every rule found, kept ones included; the ones not kept carry a number to pick by. */
37
- rules: Finding[]
38
- impact: {
39
- /** Host words an agent starting in each folder loads, now and with every proposal applied. */
40
- folders: { folder: string; before: number; after: number }[]
41
- /** Rules and words per kind. */
42
- byKind: Partial<Record<Kind, { rules: number; words: number }>>
43
- }
44
- /** Each CLAUDE.md as a vendor-neutral AGENTS.md: what would convert, and what stands in the way (version 2 converts). */
45
- agentsMd: { path: string; blockers: string[] }[]
46
- }
25
+ /** The formats `readRun` reads: every one written so far. */
26
+ export const formats = ['able.agents@1', format] as const satisfies Run['format'][]
47
27
 
48
28
  /** Kinds whose words leave the start-up set once applied: everything but keep, and a conflict until it is picked. */
49
29
  const leaves = (k: Kind) => k !== 'keep' && k !== 'conflict'
@@ -63,7 +43,21 @@ export function runs(root: string, journal: string) {
63
43
  : []
64
44
  }
65
45
 
66
- export const readRun = (path: string) => JSON.parse(readFileSync(path, 'utf8')) as Run
46
+ /** A run from its text, whichever format it was written in, with each rule's words and path filled in from its block. */
47
+ export function parseRun(text: string): Run {
48
+ const run = JSON.parse(text) as Run
49
+ if (!formats.includes(run.format)) throw new Error(`a run in format ${JSON.stringify(run.format)}: this able reads ${formats.join(' and ')}`)
50
+ const blockOf = new Map(run.blocks.blocks.map((b) => [b.id, b]))
51
+ for (const r of run.rules) {
52
+ const b = blockOf.get(r.block)
53
+ if (!b) continue
54
+ r.path ??= b.path
55
+ r.text ??= b.text.slice(r.span[0] - b.span[0], r.span[1] - b.span[0])
56
+ }
57
+ return run
58
+ }
59
+
60
+ export const readRun = (path: string) => parseRun(readFileSync(path, 'utf8'))
67
61
 
68
62
  /** A run file by name or date prefix (`2026-11-16`, `2026-11-16-2240`), or the latest. */
69
63
  export function findRun(root: string, journal: string, name?: string) {
@@ -94,8 +88,21 @@ export function tally(run: Run) {
94
88
  }
95
89
 
96
90
  /** Builds the run. `path` is where it will be written; `summaries` are steps 1 to 6's lines, the rest are worked out here. */
97
- export function build(input: { scan: Entry[]; load: LoadMap; blocks: Blocks; checks: Checks; checked: Checked; summaries: Record<string, string>; root: string; path: string; at: Date }): Run {
91
+ export function build(input: {
92
+ scan: Entry[]
93
+ load: LoadMap
94
+ blocks: Blocks
95
+ checks: Checks
96
+ checked: Checked
97
+ summaries: Record<string, string>
98
+ root: string
99
+ path: string
100
+ at: Date
101
+ /** The run before this one: its picks carry forward by rule id, so what was answered isn't asked again. */
102
+ previous?: Run
103
+ }): Run {
98
104
  const { scan, load, blocks, checks, checked } = input
105
+ const earlier = new Map(input.previous?.rules.flatMap((r) => (r.pick ? [[r.id, r.pick] as const] : [])))
99
106
  const blockOf = new Map(blocks.blocks.map((b) => [b.id, b]))
100
107
  let n = 0
101
108
  const rules = checked.rules
@@ -105,7 +112,7 @@ export function build(input: { scan: Entry[]; load: LoadMap; blocks: Blocks; che
105
112
  return { ...r, line, words: countWords(r.text) }
106
113
  })
107
114
  .sort((a, b) => pickOrder.indexOf(a.kind) - pickOrder.indexOf(b.kind) || a.path.localeCompare(b.path) || a.span[0] - b.span[0])
108
- .map((r) => (r.kind === 'keep' ? r : { ...r, n: ++n }))
115
+ .map((r) => (r.kind === 'keep' ? r : { ...r, n: ++n, ...(earlier.has(r.id) && { pick: earlier.get(r.id) }) }))
109
116
 
110
117
  // A rule counts at start for a folder when its file loads at start there: an instruction file or always-on rule in the
111
118
  // folder's chain, or a skill's description.
@@ -147,9 +154,8 @@ export function build(input: { scan: Entry[]; load: LoadMap; blocks: Blocks; che
147
154
  ...input.summaries,
148
155
  report: relative(input.root, input.path),
149
156
  show: `${root ? root.before - root.after : 0} words leave the root's start`,
150
- pick: `0 of ${rules.filter((r) => r.n).length} picked`,
151
157
  }
152
- return {
158
+ const run: Run = {
153
159
  format,
154
160
  at: input.at.toISOString(),
155
161
  steps: steps.filter((s) => s.v1).map((s) => ({ n: s.n, id: s.id, kind: s.kind, summary: summaries[s.id] ?? '' })),
@@ -161,6 +167,8 @@ export function build(input: { scan: Entry[]; load: LoadMap; blocks: Blocks; che
161
167
  impact: { folders, byKind },
162
168
  agentsMd,
163
169
  }
170
+ run.steps.find((s) => s.id === 'pick')!.summary = tally(run).line
171
+ return run
164
172
  }
165
173
 
166
174
  /** The run's file name: local date and time, so two runs a minute apart are both kept. */
@@ -172,10 +180,22 @@ export function runName(at = new Date()) {
172
180
  /** Where a run taken at `at` is written. */
173
181
  export const runPath = (root: string, journal: string, at: Date) => join(runsFolder(root, journal), runName(at))
174
182
 
175
- /** Writes a run file; the one place its format on disk is set. */
183
+ /** JSON broken into lines down to the lists (rules, blocks, files), each of their items on one line: small, and still a
184
+ * readable diff. */
185
+ export function lines(value: unknown, depth = 0): string {
186
+ const flat = JSON.stringify(value)
187
+ if (value === null || typeof value !== 'object' || flat.length <= 100 || depth > 2 || (depth === 2 && !Array.isArray(value))) return flat
188
+ const pad = ' '.repeat(depth + 1)
189
+ 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)}`)
190
+ const [open, close] = Array.isArray(value) ? ['[', ']'] : ['{', '}']
191
+ return `${open}\n${items.map((i) => pad + i).join(',\n')}\n${' '.repeat(depth)}${close}`
192
+ }
193
+
194
+ /** Writes a run file, always in the current format; the one place its form on disk is set. */
176
195
  export async function saveRun(path: string, run: Run) {
177
196
  mkdirSync(dirname(path), { recursive: true })
178
- await Bun.write(path, `${JSON.stringify(run, null, 1)}\n`)
197
+ const rules = run.rules.map(({ text: _text, path: _path, ...r }) => r)
198
+ await Bun.write(path, `${lines({ ...run, format, rules })}\n`)
179
199
  }
180
200
 
181
201
  /** Step 9: records the operator's yes or no on numbered findings in the run, and saves it. */
@@ -1,23 +1,12 @@
1
1
  // Step 1, scan: every agent file in the host, what kind it is, and its size. Reads only.
2
2
  // Files come from git (tracked plus untracked, gitignored ones skipped), so `node_modules` and build output never show.
3
3
 
4
- import { existsSync, readFileSync } from 'node:fs'
5
- import { join } from 'node:path'
4
+ import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs'
5
+ import { join, relative } from 'node:path'
6
6
  import { lines as gitLines } from '../git.ts'
7
+ import type { FileKind, SkillOrigin, Entry } from './types.ts'
7
8
 
8
- export type FileKind = 'instructions' | 'rule' | 'settings' | 'skill' | 'command' | 'hook' | 'memory' | 'mcp' | 'cursor'
9
-
10
- /** house: the host's own skill. downloaded: listed in skills-lock.json, changed upstream. source: a root `skills/` the
11
- * host publishes (Able's own), which Claude does not load in this repo. */
12
- export type SkillOrigin = 'house' | 'downloaded' | 'source'
13
-
14
- export interface Entry {
15
- path: string
16
- kind: FileKind
17
- words: number
18
- lines: number
19
- origin?: SkillOrigin
20
- }
9
+ export type { FileKind, SkillOrigin, Entry }
21
10
 
22
11
  export const countWords = (text: string) => text.split(/\s+/).filter(Boolean).length
23
12
 
@@ -59,8 +48,23 @@ function downloadedSkills(root: string) {
59
48
  return new Set(Object.keys(JSON.parse(readFileSync(lock, 'utf8')).skills ?? {}))
60
49
  }
61
50
 
51
+ /** The root skills/ the host links into .claude/skills/ (each link a folder git lists as one file): source it
52
+ * publishes that Claude loads here too, so they count as the host's own skills. */
53
+ function linkedSkills(root: string, files: string[]) {
54
+ return new Set(
55
+ files.flatMap((path) => {
56
+ if (!/^\.claude\/skills\/[^/]+$/.test(path)) return []
57
+ const full = join(root, path)
58
+ if (!lstatSync(full, { throwIfNoEntry: false })?.isSymbolicLink() || !existsSync(full)) return []
59
+ const target = relative(realpathSync(root), realpathSync(full))
60
+ return /^skills\/[^/]+$/.test(target) ? [target.split('/')[1]!] : []
61
+ }),
62
+ )
63
+ }
64
+
62
65
  export function scan(root: string, files: string[]): Entry[] {
63
66
  const downloaded = downloadedSkills(root)
67
+ const linked = linkedSkills(root, files)
64
68
  return files
65
69
  .flatMap((path) => {
66
70
  const kind = kindOf(path)
@@ -70,7 +74,7 @@ export function scan(root: string, files: string[]): Entry[] {
70
74
  const entry: Entry = { path, kind, words: countWords(text), lines: text.split('\n').length }
71
75
  if (kind === 'skill') {
72
76
  const name = path.split('/').at(-2) ?? ''
73
- entry.origin = path.startsWith('skills/') ? 'source' : downloaded.has(name) ? 'downloaded' : 'house'
77
+ entry.origin = path.startsWith('skills/') && !linked.has(name) ? 'source' : downloaded.has(name) ? 'downloaded' : 'house'
74
78
  }
75
79
  return [entry]
76
80
  })
@@ -0,0 +1,171 @@
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
2
+ // that wrote it without type-checking the CLI's code. Each step's module re-exports its own.
3
+
4
+ /** The ten kinds a rule can be (kinds.ts holds their letters and meanings). */
5
+ export type Kind = 'keep' | 'scoped' | 'lint' | 'check' | 'enforced' | 'guard' | 'discoverable' | 'expiring' | 'duplicate' | 'conflict'
6
+
7
+ // scan.ts
8
+ export type FileKind = 'instructions' | 'rule' | 'settings' | 'skill' | 'command' | 'hook' | 'memory' | 'mcp' | 'cursor'
9
+
10
+ /** house: the host's own skill. downloaded: listed in skills-lock.json, changed upstream. source: a root `skills/` the
11
+ * host publishes (Able's own), which Claude does not load in this repo. */
12
+ export type SkillOrigin = 'house' | 'downloaded' | 'source'
13
+
14
+ export interface Entry {
15
+ path: string
16
+ kind: FileKind
17
+ words: number
18
+ lines: number
19
+ origin?: SkillOrigin
20
+ }
21
+
22
+ // load.ts
23
+ /** always: at launch. folder: when the agent works in that folder. paths: a rule whose `paths:` match a file it touches.
24
+ * skill: its name and description at launch, the body on use. config: settings, hooks and MCP, not text the agent reads.
25
+ * never: not loaded by Claude here. */
26
+ export type LoadKind = 'always' | 'folder' | 'paths' | 'skill' | 'config' | 'never'
27
+
28
+ export interface LoadedFile {
29
+ path: string
30
+ load: LoadKind
31
+ /** The folder it belongs to, from the root ('.' for the root): where an instruction file sits, or the folder that holds its `.claude/`. */
32
+ folder: string
33
+ /** Words loaded at launch by an agent in `folder` (with any `@` imports), and words loaded only on use. */
34
+ atStart: number
35
+ onUse: number
36
+ imports?: string[]
37
+ note?: string
38
+ }
39
+
40
+ export interface FolderLoad {
41
+ folder: string
42
+ host: number
43
+ outside: number
44
+ }
45
+
46
+ export interface OutsideFile {
47
+ path: string
48
+ /** `broken`: a symlink whose target is gone, so Claude loads nothing from it. */
49
+ load: LoadKind | 'broken'
50
+ atStart: number
51
+ onUse: number
52
+ }
53
+
54
+ export interface LoadMap {
55
+ files: LoadedFile[]
56
+ folders: FolderLoad[]
57
+ outside: OutsideFile[]
58
+ }
59
+
60
+ // blocks.ts
61
+ export interface Block {
62
+ id: string
63
+ path: string
64
+ /** The headings above it, outermost first, and any lead-in line. */
65
+ heading: string[]
66
+ /** First and last line, 1-based, inclusive. */
67
+ lines: [number, number]
68
+ /** Character offsets into the file, [from, to), so a view can highlight exactly these words. */
69
+ span: [number, number]
70
+ words: number
71
+ text: string
72
+ }
73
+
74
+ export interface Blocks {
75
+ blocks: Block[]
76
+ /** Agent files listed but not cut, with why. */
77
+ skipped: { path: string; reason: string }[]
78
+ }
79
+
80
+ // checks.ts
81
+ export type Level = 'off' | 'warn' | 'error' | 'on'
82
+
83
+ export interface LintRule {
84
+ name: string
85
+ level: Level
86
+ /** The file the rule was found in: the config itself or one it imports or extends. */
87
+ from: string
88
+ }
89
+
90
+ export interface Linter {
91
+ tool: string
92
+ path: string
93
+ /** parsed: JSON or YAML, read exactly. text: JavaScript, read as text without running it. */
94
+ read: 'parsed' | 'text'
95
+ rules: LintRule[]
96
+ /** Files it imports or extends that were read too. */
97
+ via: string[]
98
+ /** Rule sets a JavaScript config switches on by name (`js.configs.recommended`): known on, their rules unlisted. */
99
+ presets?: string[]
100
+ }
101
+
102
+ export interface Checks {
103
+ commit: Record<string, string[]>
104
+ merge: string[]
105
+ linters: Linter[]
106
+ settings: { path: string; allow: string[]; deny: string[]; ask: string[]; hooks: Record<string, string[]> }[]
107
+ recipes: { path: string; names: string[] }[]
108
+ scripts: { path: string; names: string[] }[]
109
+ }
110
+
111
+ // findings.ts
112
+ export interface RuleFinding {
113
+ /** The rule's words, quoted exactly from the block (whitespace may differ). */
114
+ text: string
115
+ kind: Kind
116
+ confidence: 'high' | 'low'
117
+ /** One line: why this kind. */
118
+ reason: string
119
+ /** For a duplicate or a conflict: the ids of the blocks holding the other rule. */
120
+ with?: string[]
121
+ /** Step 6, for every rule not kept: the file the change goes in and the change itself, concrete enough to apply. */
122
+ proposal?: Proposal
123
+ /** Step 6: the agent's recommendation for the operator's pick. The picker starts from it. */
124
+ recommend?: 'yes' | 'no'
125
+ }
126
+
127
+ export interface Proposal {
128
+ /** The file the change goes in: a linter config, a settings file, a new rules file, the rule's own file. */
129
+ target: string
130
+ /** The change: the lint rule entry, the deny entry, the pointer line, the paths rule, "delete", or the question. */
131
+ change: string
132
+ }
133
+
134
+ export interface Rule extends RuleFinding {
135
+ /** The block's id plus a short hash of the rule's words: survives edits elsewhere in the block. */
136
+ id: string
137
+ block: string
138
+ path: string
139
+ /** Character offsets into the file, [from, to). */
140
+ span: [number, number]
141
+ }
142
+
143
+ // report.ts
144
+ export interface Finding extends Rule {
145
+ /** The number the operator picks it by, in the order `show` lists them; kept rules have none. */
146
+ n?: number
147
+ /** 1-based line of the rule's first word in its file. */
148
+ line: number
149
+ words: number
150
+ pick?: 'yes' | 'no'
151
+ }
152
+
153
+ export interface Run {
154
+ format: 'able.agents@1' | 'able.agents@2'
155
+ at: string
156
+ steps: { n: number; id: string; kind: string; summary: string }[]
157
+ scan: Entry[]
158
+ load: LoadMap
159
+ blocks: Blocks
160
+ checks: Checks
161
+ /** Every rule found, kept ones included; the ones not kept carry a number to pick by. */
162
+ rules: Finding[]
163
+ impact: {
164
+ /** Host words an agent starting in each folder loads, now and with every proposal applied. */
165
+ folders: { folder: string; before: number; after: number }[]
166
+ /** Rules and words per kind. */
167
+ byKind: Partial<Record<Kind, { rules: number; words: number }>>
168
+ }
169
+ /** Each CLAUDE.md as a vendor-neutral AGENTS.md: what would convert, and what stands in the way (version 2 converts). */
170
+ agentsMd: { path: string; blockers: string[] }[]
171
+ }
@@ -4,7 +4,7 @@
4
4
  // able ws ls [--json] every checkout: offset, services, tree, resources held
5
5
  // able ws current [--json] the checkout this runs in: slug, branch, path, port offset, main checkout
6
6
  // able ws refresh merges the trunk into this workspace
7
- // able ws merge ["message"] [--yes] merges this workspace into the trunk as `Merge feat/<slug>`
7
+ // able ws merge ["message"] [--yes] [--keep-open] merges this workspace into the trunk as `Merge feat/<slug>`
8
8
  // able ws rm <slug> [--force] stops and removes a workspace, deleting its branch once merged
9
9
  // able ws start | stop [<service>…] the workspace's services, in dependency order
10
10
  // able ws status the services running in this checkout
@@ -1,6 +1,9 @@
1
- // able ws merge ["message"] [--yes]: merges this workspace into the trunk, from inside it.
1
+ // able ws merge ["message"] [--yes] [--keep-open]: merges this workspace into the trunk, from inside it.
2
2
  //
3
- // Refuses while the workspace's brief has no `## Ledger` (its close). Merges origin's trunk into `feat/<slug>`, runs the commit checks of every folder the branch changed and then the
3
+ // Refuses while the workspace's brief has no `## Ledger` (its close), unless `--keep-open`: a finished part lands and
4
+ // the workspace stays open for the rest, with no close and no ledger needed. `able sync` files a workspace's follow-ups
5
+ // only from a brief with its ledger, by their titles, so the final close and merge file them once, however many
6
+ // partial merges came before. Merges origin's trunk into `feat/<slug>`, runs the commit checks of every folder the branch changed and then the
4
7
  // merge checks (decisions 73, 100), pushes `feat/<slug>` and merges it into origin's trunk as one merge commit,
5
8
  // `Merge feat/<slug>`, which is how `able sync` finds it. A message commits what is still dirty first. The main checkout takes no part; afterwards it is
6
9
  // fast-forwarded when it is on the trunk and nothing of its own is in the way.
@@ -25,8 +28,10 @@ const dirty = dirtyCount(ws.path)
25
28
  if (dirty && !msg) fail(`${dirty} uncommitted file(s); commit them (able commit), or pass a message to commit them all at once`)
26
29
 
27
30
  // The close goes in with the branch: a brief without its ledger is never merged (`able sync` reads that ledger).
31
+ const keepOpen = args.includes('--keep-open')
28
32
  const brief = join(ws.path, config.journal, 'workspaces', `${ws.slug}.md`)
29
- if (existsSync(brief) && !readFileSync(brief, 'utf8').includes('\n## Ledger\n')) fail(`${relative(ws.path, brief)} has no ## Ledger; close the workspace first (the able-close-ws skill), then merge`)
33
+ if (!keepOpen && existsSync(brief) && !readFileSync(brief, 'utf8').includes('\n## Ledger\n'))
34
+ fail(`${relative(ws.path, brief)} has no ## Ledger; close the workspace first (the able-close-ws skill), then merge, or land what is done with --keep-open`)
30
35
 
31
36
  const step = working(`merge ${ws.slug}`)
32
37
  step(`fetching ${trunk}`)
@@ -77,5 +82,7 @@ console.log(
77
82
  ? ` ${green('✓')} main checkout fast-forwarded`
78
83
  : yellow(` main checkout not updated${onTrunk ? ': its own changes are in the way' : `: it is not on ${trunk}`}; pull it there: git pull --ff-only`),
79
84
  )
80
- console.log(`\n ${dim('next, from the main checkout:')} able ws rm ${ws.slug}\n`)
85
+ console.log(
86
+ keepOpen ? `\n ${dim('the workspace stays open: keep working here, and close it (able-close-ws) before its last merge')}\n` : `\n ${dim('next, from the main checkout:')} able ws rm ${ws.slug}\n`,
87
+ )
81
88
  status({ state: 'done', msg: `merge: ${ws.branch} is on ${trunk}` })