guide

1// guide mod ("Mode d'emploi des mods"): MODE-EMPLOI.md as a pane with tabs. The first tab, Sommaire, is the whole tree
2// with a link to every tab, category and sub-section; each other tab folds its categories. The "Nos mods" cards are
3// rebuilt at each draw from the neighbouring mods' plugin.json and hooks module. Read-only: no hook on tools or agents.
4import { atom, read, update } from 'claude-code'
5import type { EngineInterface, Register } from 'claude-code'
6
7import type { Doc, ModsCatalog } from '../types'
8import { card, modsMarkdown, modulePath } from './cards'
9import { between, locate, parse, slug } from './toc'
10
11const PANE = { id: 'mods-guide', title: "Mode d'emploi des mods" }
12const SOMMAIRE = 'sommaire'
13const tabAtom = atom({ plugin: 'guide', key: 'tab' } as const, SOMMAIRE)
14const catAtom = atom({ plugin: 'guide', key: 'cat' } as const, '')
15const subAtom = atom({ plugin: 'guide', key: 'sub' } as const, '')
16
17const text = async ($: EngineInterface, path: string): Promise<string | undefined> => {
18  try {
19    return (await $.fs.read(path, { as: 'text' })) as string
20  } catch {
21    return undefined
22  }
23}
24
25/** The guide with live cards for "Nos mods". */
26const loadDoc = async ($: EngineInterface): Promise<{ doc: Doc; problem: string }> => {
27  const root = $.plugin.root.replace(/\\/g, '/')
28  const md = await text($, `${root}/MODE-EMPLOI.md`)
29  if (!md) return { doc: { title: PANE.title, intro: '', tabs: [] }, problem: `cannot read ${root}/MODE-EMPLOI.md` }
30  let live = md
31  const raw = await text($, `${root}/mods.json`)
32  if (raw) {
33    try {
34      const catalog = JSON.parse(raw) as ModsCatalog
35      const mods = root.replace(/\/[^/]+$/, '')
36      const cards = []
37      for (const entry of catalog.mods) {
38        const dir = `${mods}/${entry.dir}`
39        const manifest = await text($, `${dir}/.claude-plugin/plugin.json`)
40        const rel = modulePath(await text($, `${dir}/hooks/hooks.json`))
41        cards.push(card(entry, catalog, manifest, rel ? await text($, `${dir}/${rel}`) : undefined))
42      }
43      live = between(md, 'mods', modsMarkdown(cards, catalog))
44    } catch {}
45  }
46  return { doc: parse(live), problem: '' }
47}
48
49/** `/mods-guide [onglet ou section]`: an anchor, or the start of a title. */
50const find = (doc: Doc, args: string) => {
51  const want = slug(args)
52  if (!want) return undefined
53  const exact = locate(doc, want)
54  if (exact) return exact
55  for (const t of doc.tabs) {
56    if (t.id.startsWith(want)) return { tab: t.id, cat: '', sub: '' }
57    for (const c of t.cats) {
58      if (c.id.startsWith(want)) return { tab: t.id, cat: c.id, sub: '' }
59      for (const s of c.subs) if (s.id.startsWith(want)) return { tab: t.id, cat: c.id, sub: s.id }
60    }
61  }
62  return undefined
63}
64
65const go = async ($: EngineInterface, to: { tab: string; cat: string; sub: string }) => {
66  await update($, tabAtom, () => to.tab)
67  await update($, catAtom, () => to.cat)
68  await update($, subAtom, () => to.sub)
69}
70
71export const register: Register = on => {
72  on('session.start', async ($, e, next) => {
73    await $.command.register({
74      name: 'mods-guide',
75      description: "Mode d'emploi des mods : onglets Bases, Événements, Interface, Configuration, Installer, Tester, Écrire un mod, Référence, Nos mods, FAQ",
76      argumentHint: '[onglet ou section]',
77    })
78    return next(e)
79  })
80
81  on('command.run', { command: 'mods-guide' }, async ($, e) => {
82    const { doc, problem } = await loadDoc($)
83    if (problem) return { text: `mods-guide: ${problem}` }
84    const args = (e.args ?? '').trim()
85    const to = args ? find(doc, args) : { tab: SOMMAIRE, cat: '', sub: '' }
86    if (!to) return { text: `mods-guide: pas de section « ${args} ». Onglets : ${doc.tabs.map(t => t.title).join(', ')}` }
87    await go($, to)
88    await $.ui.open({ id: PANE.id, title: PANE.title })
89    const where = to.tab === SOMMAIRE ? 'Sommaire' : doc.tabs.find(t => t.id === to.tab)?.title
90    return { text: `mods-guide: ouvert sur ${where}${to.cat ? ` › ${to.cat}` : ''}${to.sub ? ` › ${to.sub}` : ''}` }
91  })
92
93  on('ui.render', { component: 'Pane', requestId: 'mods-guide' }, async ($, e) => {
94    const { Box, Text, Button, Markdown } = $.ui.resolve(e)
95    const { doc, problem } = await loadDoc($)
96    const tab = await read($, tabAtom)
97    const cat = await read($, catAtom)
98    const sub = await read($, subAtom)
99    const current = doc.tabs.find(t => t.id === tab)
100    const on_ = (yes: boolean) => (yes ? {} : { plain: true as const })
101
102    const tabs = (
103      <Box flexDirection="row" gap={1} flexWrap="wrap">
104        <Button key="tab-sommaire" {...on_(!current)} onPress={() => go($, { tab: SOMMAIRE, cat: '', sub: '' })}>
105          Sommaire
106        </Button>
107        {doc.tabs.map(t => (
108          <Button key={`tab-${t.id}`} {...on_(t.id === current?.id)} onPress={() => go($, { tab: t.id, cat: '', sub: '' })}>
109            {t.title}
110          </Button>
111        ))}
112      </Box>
113    )
114
115    if (problem) return <Text color="error">{problem}</Text>
116
117    if (!current) {
118      return (
119        <Box flexDirection="column" gap={1}>
120          {tabs}
121          <Text bold>{`Sommaire général · ${doc.title}`}</Text>
122          {doc.intro ? <Markdown text={doc.intro.replace(/^Doc officielle.*$/m, '').trim()} /> : null}
123          <Box flexDirection="column">
124            {doc.tabs.map(t => (
125              <Box flexDirection="column">
126                <Button key={`go-${t.id}`} plain bold onPress={() => go($, { tab: t.id, cat: '', sub: '' })}>
127                  {t.title}
128                </Button>
129                {t.cats.map(c => (
130                  <Box flexDirection="column" paddingLeft={2}>
131                    <Button key={`go-${c.id}`} plain onPress={() => go($, { tab: t.id, cat: c.id, sub: '' })}>
132                      {c.title}
133                    </Button>
134                    {c.subs.map(s => (
135                      <Box paddingLeft={2}>
136                        <Button key={`go-${s.id}`} plain dimColor onPress={() => go($, { tab: t.id, cat: c.id, sub: s.id })}>
137                          {s.title}
138                        </Button>
139                      </Box>
140                    ))}
141                  </Box>
142                ))}
143              </Box>
144            ))}
145          </Box>
146        </Box>
147      )
148    }
149
150    return (
151      <Box flexDirection="column" gap={1}>
152        {tabs}
153        <Text bold>{current.title}</Text>
154        {current.intro ? <Markdown text={current.intro} /> : null}
155        {current.cats.map(c => {
156          const open = c.id === cat
157          return (
158            <Box flexDirection="column">
159              <Button key={`cat-${c.id}`} plain bold onPress={() => go($, { tab: current.id, cat: open ? '' : c.id, sub: '' })}>
160                {`${open ? '▾' : '▸'} ${c.title}${open ? '' : ` (${c.subs.length})`}`}
161              </Button>
162              {open && (
163                <Box flexDirection="column" paddingLeft={2} gap={1}>
164                  {c.body ? <Markdown text={c.body} /> : null}
165                  {c.subs.map(s => (
166                    <Box flexDirection="column">
167                      <Text bold {...(s.id === sub ? { color: 'success' as const } : {})}>{`${s.id === sub ? '→ ' : ''}${s.title}`}</Text>
168                      {s.body ? <Markdown text={s.body} /> : null}
169                    </Box>
170                  ))}
171                </Box>
172              )}
173            </Box>
174          )
175        })}
176        <Button key="back" plain dimColor onPress={() => go($, { tab: SOMMAIRE, cat: '', sub: '' })}>
177          ← Sommaire
178        </Button>
179      </Box>
180    )
181  })
182}
183

1// "Nos mods": one card per mod, built from what the mod itself ships (plugin.json, hooks/hooks.json, its hooks
2// module's source) plus the few facts only mods.json knows (state, data read, tests). Pure: no `$`.
3import type { Card, CatalogEntry, ModsCatalog } from '../types'
4
5type Manifest = {
6  name?: string
7  version?: string
8  description?: string
9  userConfig?: Record<string, { title?: string; default?: unknown; options?: unknown[] }>
10}
11
12const uniq = (xs: string[]) => [...new Set(xs)]
13
14/** Events the module hooks: `on('event'` / `on("event"`. */
15export const eventsIn = (src: string) => uniq([...src.matchAll(/\bon\(\s*['"]([\w.*-]+)['"]/g)].map(m => m[1]!))
16
17/** Slash commands the module registers: `$.command.register({ name: 'x'`. */
18export const commandsIn = (src: string) =>
19  uniq([...src.matchAll(/\$\.command\.register\(\s*\{[^}]*?\bname:\s*['"]([\w-]+)['"]/gs)].map(m => `/${m[1]}`))
20
21/** Whether the source can refuse anything: a `deny` answer or a `drop` of a prompt. */
22export const canBlock = (src: string) => /\{\s*deny\s*:|\bdeny:\s*['"`]|\{\s*drop\s*:/.test(src)
23
24/** Whether it draws: a Pane, a band above the prompt, a status line, toasts. */
25export function drawsIn(src: string): string[] {
26  const out: string[] = []
27  if (/component:\s*['"]Pane['"]/.test(src)) out.push('panneau')
28  if (/component:\s*['"]AbovePrompt['"]/.test(src)) out.push('bandeau')
29  if (/\$\.ui\.status\(/.test(src)) out.push('ligne de statut')
30  if (/\$\.ui\.toast\(/.test(src)) out.push('toasts')
31  if (/['"]prompt\.compose['"]/.test(src)) out.push('note dans le prompt système')
32  return out
33}
34
35/** The hooks module path a hooks.json names, relative to the mod folder. */
36export function modulePath(hooksJson: string | undefined): string | undefined {
37  try {
38    const first = (JSON.parse(hooksJson ?? '') as { modules?: string[] }).modules?.[0]
39    return first ? `hooks/${first.replace(/^\.\//, '')}` : undefined
40  } catch {
41    return undefined
42  }
43}
44
45/** One card. `manifest` and `source` are undefined for a mod that is not in this folder (planned, or not installed here). */
46export function card(entry: CatalogEntry, catalog: ModsCatalog, manifest?: string, source?: string): Card {
47  let m: Manifest = {}
48  try {
49    m = manifest ? (JSON.parse(manifest) as Manifest) : {}
50  } catch {}
51  const src = source ?? ''
52  const options = Object.entries(m.userConfig ?? {}).map(([key, f]) => {
53    const choices = Array.isArray(f.options) ? ` (${f.options.join(' | ')})` : ''
54    return `${key}${f.title ? ` « ${f.title} »` : ''}${choices}, défaut ${JSON.stringify(f.default ?? '')}`
55  })
56  const found = Boolean(manifest)
57  return {
58    dir: entry.dir,
59    name: m.name ?? entry.name ?? entry.dir,
60    version: m.version ?? '',
61    description: m.description ?? entry.description ?? '',
62    state: catalog.states[entry.state] ?? entry.state,
63    found,
64    events: eventsIn(src),
65    commands: commandsIn(src),
66    draws: drawsIn(src),
67    blocks: canBlock(src),
68    options,
69    data: entry.data ?? '',
70    note: entry.note ?? '',
71    tests: entry.tests ?? [],
72    enable: found ? `ajoute <dépôt>/mods/${entry.dir} à CLAUDE_CODE_PLUGIN_DIRS, ou lance claude --plugin-dir mods/${entry.dir}` : 'pas encore dans le dépôt',
73  }
74}
75
76/** The same card as Markdown, for MODE-EMPLOI.md. */
77export function cardMarkdown(c: Card): string {
78  const rows = [
79    `#### ${c.name}`,
80    '',
81    `${c.description || '(pas de description)'}`,
82    '',
83    `- **État** : ${c.state}${c.version ? ` · version ${c.version}` : ''}${c.note ? ` · ${c.note}` : ''}`,
84    `- **Fonctionnement** : ${c.found ? `événements ${c.events.map(e => `\`${e}\``).join(', ') || 'aucun'}` : 'pas encore écrit'} · lit : ${c.data || '—'} · ${c.found ? (c.blocks ? '⚠ peut refuser un appel' : 'aucun blocage') : 'sans blocage prévu'}`,
85    `- **Fonctionnalités** : commandes ${c.commands.map(x => `\`${x}\``).join(', ') || 'aucune'} · affiche : ${c.draws.join(', ') || 'rien'} · options userConfig : ${c.options.length ? c.options.join(' ; ') : 'aucune'}`,
86    `- **Activer** : ${c.found ? `\`<dépôt>/mods/${c.dir}\` dans \`CLAUDE_CODE_PLUGIN_DIRS\`, ou \`claude --plugin-dir mods/${c.dir}\`` : c.enable}`,
87    `- **Tests** : ${c.tests.length ? c.tests.map(t => `\`${t}\``).join(' · ') : 'aucun pour l’instant'}`,
88  ]
89  return rows.join('\n')
90}
91
92/** The whole "Nos mods" block: one card per mod, then the archived / rejected table. */
93export function modsMarkdown(cards: Card[], catalog: ModsCatalog): string {
94  const parts = ['### Fiches', ...cards.map(cardMarkdown)]
95  parts.push(
96    [
97      '### Archivés / rejetés',
98      '',
99      '| Mod | Verdict | Pourquoi |',
100      '|---|---|---|',
101      ...catalog.archived.map(a => `| ${a.name} | ${a.verdict} | ${a.why} |`),
102    ].join('\n'),
103  )
104  return parts.join('\n\n')
105}
106

1// MODE-EMPLOI.md as a tree: `##` = a tab, `###` = a category, `####` = a sub-section.
2// Pure: the pane, the build script (scripts/build.mjs) and node --test all use it.
3import type { Doc, Section, Tab } from '../types'
4
5/** GitHub's heading anchor: lower case, punctuation dropped (letters of any script kept), spaces to dashes. */
6export function slug(title: string): string {
7  return title
8    .trim()
9    .toLowerCase()
10    .replace(/[^\p{L}\p{N}\s_-]/gu, '')
11    .replace(/\s/g, '-')
12}
13
14const TOC = /<!-- toc:start -->[\s\S]*?<!-- toc:end -->/
15
16/** Splits the guide into tabs, categories and sub-sections. The table of contents block is left out of every body. */
17export function parse(md: string): Doc {
18  const text = md.replace(/\r\n/g, '\n').replace(TOC, '')
19  const doc: Doc = { title: '', intro: '', tabs: [] }
20  let tab: Tab | undefined
21  let cat: Section | undefined
22  let sub: Section | undefined
23  const body: string[] = []
24  let fence = false
25  const flush = () => {
26    const t = body.join('\n').trim()
27    body.length = 0
28    if (sub) sub.body = t
29    else if (cat) cat.body = t
30    else if (tab) tab.intro = t
31    else doc.intro = t
32  }
33  for (const line of text.split('\n')) {
34    if (/^\s*```/.test(line)) fence = !fence
35    const m = fence ? null : /^(#{1,4})\s+(.*?)\s*$/.exec(line)
36    if (!m) {
37      body.push(line)
38      continue
39    }
40    const level = m[1]!.length
41    const title = m[2]!
42    flush()
43    if (level === 1) doc.title = title
44    else if (level === 2) {
45      tab = { id: slug(title), title, intro: '', cats: [] }
46      doc.tabs.push(tab)
47      cat = undefined
48      sub = undefined
49    } else if (level === 3 && tab) {
50      cat = { id: slug(title), title, body: '', subs: [] }
51      tab.cats.push(cat)
52      sub = undefined
53    } else if (level === 4 && cat) {
54      sub = { id: slug(title), title, body: '', subs: [] }
55      cat.subs.push(sub)
56    } else body.push(line)
57  }
58  flush()
59  return doc
60}
61
62/** Every anchor of the tree, in order; the build script refuses a duplicate. */
63export function anchors(doc: Doc): string[] {
64  const out: string[] = []
65  for (const t of doc.tabs) {
66    out.push(t.id)
67    for (const c of t.cats) {
68      out.push(c.id)
69      for (const s of c.subs) out.push(s.id)
70    }
71  }
72  return out
73}
74
75/** The table of contents as nested Markdown links to the same anchors. */
76export function tocMarkdown(doc: Doc): string {
77  const lines: string[] = []
78  for (const t of doc.tabs) {
79    lines.push(`- [${t.title}](#${t.id})`)
80    for (const c of t.cats) {
81      lines.push(`  - [${c.title}](#${c.id})`)
82      for (const s of c.subs) lines.push(`    - [${s.title}](#${s.id})`)
83    }
84  }
85  return lines.join('\n')
86}
87
88/** Puts a fresh table of contents between the markers (the markers must be there). */
89export function withToc(md: string): string {
90  const toc = tocMarkdown(parse(md))
91  return md.replace(TOC, `<!-- toc:start -->\n${toc}\n<!-- toc:end -->`)
92}
93
94/** Replaces what lies between `<!-- name:start -->` and `<!-- name:end -->`. */
95export function between(md: string, name: string, content: string): string {
96  const re = new RegExp(`<!-- ${name}:start -->[\\s\\S]*?<!-- ${name}:end -->`)
97  return md.replace(re, `<!-- ${name}:start -->\n${content}\n<!-- ${name}:end -->`)
98}
99
100/** Where a press on a Sommaire link leads: the tab, the category to unfold and the sub-section to mark. */
101export function locate(doc: Doc, anchor: string): { tab: string; cat: string; sub: string } | undefined {
102  for (const t of doc.tabs) {
103    if (t.id === anchor) return { tab: t.id, cat: '', sub: '' }
104    for (const c of t.cats) {
105      if (c.id === anchor) return { tab: t.id, cat: c.id, sub: '' }
106      for (const s of c.subs) if (s.id === anchor) return { tab: t.id, cat: c.id, sub: s.id }
107    }
108  }
109  return undefined
110}
111

1// Shapes of the guide mod: the parsed MODE-EMPLOI.md, mods.json, a mod card, and its `$.state` values.
2
3export type Section = { id: string; title: string; body: string; subs: Section[] }
4export type Tab = { id: string; title: string; intro: string; cats: Section[] }
5export type Doc = { title: string; intro: string; tabs: Tab[] }
6
7export type CatalogEntry = {
8  dir: string
9  name?: string
10  state: string
11  description?: string
12  data?: string
13  note?: string
14  tests?: string[]
15}
16export type ModsCatalog = {
17  states: Record<string, string>
18  mods: CatalogEntry[]
19  archived: { name: string; verdict: string; why: string }[]
20}
21export type Card = {
22  dir: string
23  name: string
24  version: string
25  description: string
26  state: string
27  /** the mod's plugin.json was found beside this one */
28  found: boolean
29  events: string[]
30  commands: string[]
31  draws: string[]
32  blocks: boolean
33  options: string[]
34  data: string
35  note: string
36  tests: string[]
37  enable: string
38}
39
40declare module 'claude-code' {
41  interface PluginState {
42    guide: {
43      /** tab shown: 'sommaire' or a `##` heading's anchor */
44      tab: string
45      /** category unfolded in that tab ('' = none) */
46      cat: string
47      /** sub-section marked after a Sommaire link ('' = none) */
48      sub: string
49    }
50  }
51}
52