@g3nomaly/g3n-mods 0.0.0-stage → 0.1.1

package/mods/delete-guard/hooks/register.ts

@@ -0,0 +1,151 @@
+// packages/g3n-mods/mods/delete-guard/hooks/register.ts
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { Deletion } from '../types'
+
+const isOff = atom({ plugin: 'delete-guard', key: 'isOff' } as const, false)
+
+/** Shell syntax that starts a new command: `&&`, `||`, `;`, `|`, a newline, `$(` and a backtick. */
+const SEGMENT_BREAK = /&&|\|\||;|\||\n|\$\(|`/
+
+/** Words that run the command after them: `sudo rm`, `xargs -0 rm`, `env X=1 rm`. */
+const PREFIX = /^(?:\w+=\S*\s+|(?:sudo|command|exec|nice|nohup|time|env)\s+(?:-\S+\s+)*|xargs\s+(?:-\S+\s+)*)+/
+
+const DELETERS = new Set(['rm', 'shred', 'unlink', 'rimraf', 'srm'])
+
+/** Trash commands in order of preference, with how each one is spelled. */
+const TRASH_COMMANDS = [
+  { probe: 'trash', spell: 'trash' },
+  { probe: 'trash-put', spell: 'trash-put' },
+  { probe: 'gio', spell: 'gio trash' },
+] as const
+
+/**
+ * Splits a shell command line into its commands, each trimmed.
+ *
+ * @param command - Shell command line, e.g. `cd build && rm -rf dist`.
+ * @returns The non-empty commands in order.
+ */
+function segments(command: string): string[] {
+  return command.split(SEGMENT_BREAK).map(part => part.trim()).filter(part => part.length > 0)
+}
+
+/**
+ * Splits one command into words, dropping its prefixes and the program's directory.
+ *
+ * @param segment - One command, as `segments` returns it.
+ * @returns The program name first, then its arguments.
+ */
+function words(segment: string): string[] {
+  const [program = '', ...rest] = segment.replace(PREFIX, '').split(/\s+/)
+  return [program.split('/').pop() ?? program, ...rest]
+}
+
+/**
+ * Picks the operands of a command: every word that is not a flag, and every word after `--`.
+ *
+ * @param args - Words after the program name.
+ * @returns The operands in order.
+ */
+function operands(args: readonly string[]): string[] {
+  const end = args.indexOf('--')
+  const flagged = end === -1 ? args : args.slice(0, end)
+  const after = end === -1 ? [] : args.slice(end + 1)
+  return [...flagged.filter(arg => !arg.startsWith('-')), ...after]
+}
+
+/**
+ * @brief Finds the first permanent delete in a shell command line.
+ *
+ * Recognises `rm`, `shred`, `unlink`, `rimraf`, `find -delete`, `find -exec rm`
+ * and a forced `git clean`.
+ *
+ * @param command - Full shell command line, as the Bash tool received it.
+ * @returns The delete and what it removes, or `undefined` when nothing is deleted for good.
+ */
+export function findDeletion(command: string): Deletion | undefined {
+  for (const segment of segments(command)) {
+    const [program = '', ...args] = words(segment)
+    if (DELETERS.has(program)) {
+      return { segment, kind: 'files', paths: operands(args) }
+    }
+    if (program === 'find' && (args.includes('-delete') || /-exec(?:dir)?\s+(?:\S*\/)?rm\b/.test(segment))) {
+      return { segment, kind: 'find', paths: [] }
+    }
+    if (program === 'git' && args[0] === 'clean' && args.some(arg => /^-\w*f/.test(arg) || arg === '--force')) {
+      return { segment, kind: 'git-clean', paths: [] }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Builds the command Claude should run instead of a permanent delete.
+ *
+ * @param deletion - Delete to replace, see `Deletion`.
+ * @param trash - Trash command spelled as this machine has it, e.g. `gio trash`.
+ * @returns The suggested command, with `<paths>` where no path was named.
+ */
+function insteadOf(deletion: Deletion, trash: string): string {
+  switch (deletion.kind) {
+    case 'files':
+      return deletion.paths.length > 0 ? `${trash} ${deletion.paths.join(' ')}` : `${trash} <paths>`
+    case 'find':
+      return `${deletion.segment.replace(/\s-delete\b/, '').replace(/-exec(?:dir)?\s+.*$/, '')} -exec ${trash} {} +`.replace(/\s+/g, ' ')
+    case 'git-clean':
+      return `git clean -n to list the files, then ${trash} <paths>`
+  }
+}
+
+/**
+ * Finds the first trash command on this machine's PATH.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @returns The command as it should be spelled, or `undefined` when none is installed.
+ */
+async function detectTrash($: EngineInterface): Promise<string | undefined> {
+  for (const candidate of TRASH_COMMANDS) {
+    const found = await $.process.run(['sh', '-c', `command -v ${candidate.probe}`]).catch(() => undefined)
+    if (found?.exitCode === 0) return candidate.spell
+  }
+  return undefined
+}
+
+/**
+ * Registers this mod's `delete-guard` command, its session hook, and its Bash tool hook.
+ *
+ * @param on - Hook registration function the engine passes in.
+ */
+export const register: Register = on => {
+  let trash: string | undefined
+
+  on('session.start', async ($, e, next) => {
+    trash = await detectTrash($)
+    await $.command.register({
+      name: 'delete-guard',
+      description: 'Turn the permanent-delete guard on or off for this session',
+      argumentHint: 'on | off',
+    })
+    return next(e)
+  })
+
+  on('command.run', { command: 'delete-guard' }, async ($, e) => {
+    const wanted = e.args.trim()
+    if (wanted === 'on' || wanted === 'off') await update($, isOff, () => wanted === 'off')
+    const off = await read($, isOff)
+    return { text: `delete-guard is ${off ? 'off: permanent deletes run' : 'on: permanent deletes are denied'}.` }
+  })
+
+  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
+    if (await read($, isOff)) return next(e)
+    const deletion = findDeletion(e.command)
+    if (deletion === undefined) return next(e)
+
+    const spelled = trash ?? 'trash'
+    const install = trash === undefined ? ' (install trash-cli: sudo apt install trash-cli)' : ''
+    return {
+      deny: `delete-guard: \`${deletion.segment}\` deletes permanently. Move it to the trash instead: \`${insteadOf(deletion, spelled)}\`${install}.`,
+    }
+  }).catch(($, e, next) => (next.called ? next(e) : { deny: 'delete-guard: the guard failed, so the command was not run.' }))
+}

package/mods/delete-guard/types/index.d.ts

@@ -0,0 +1,14 @@
+// packages/g3n-mods/mods/delete-guard/types/index.d.ts
+
+/** A permanent delete found in a shell command: the command itself, its kind, and the paths it names. */
+export type Deletion = {
+  segment: string
+  kind: 'files' | 'find' | 'git-clean'
+  paths: string[]
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'delete-guard': { isOff: boolean }
+  }
+}

package/mods/focus-mode/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "focus-mode",
+  "version": "0.1.0",
+  "description": "A timed focus block with a countdown, a progress bar and an end button.",
+  "author": {
+    "name": "g3ntrovert"
+  },
+  "types": "./types/index.d.ts",
+  "userConfig": {
+    "minutes": {
+      "type": "number",
+      "title": "Minutes",
+      "default": 25,
+      "description": "Length of a focus block in minutes"
+    }
+  }
+}

package/mods/focus-mode/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/mods/focus-mode/hooks/register.tsx

@@ -0,0 +1,184 @@
+// packages/g3n-mods/mods/focus-mode/hooks/register.tsx
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { FocusBlock } from '../types'
+
+const PANE = 'focus-mode'
+const TITLE = 'Focus'
+const block = atom({ plugin: 'focus-mode', key: 'block' } as const, null)
+const finished = atom({ plugin: 'focus-mode', key: 'finished' } as const, 0)
+
+const DEFAULT_MINUTES = 25
+const MAX_SQUARES = 30
+const FILLED = '#e6b450'
+const EMPTY = '#3a3f4b'
+
+/**
+ * Formats remaining time as `mm:ss`, or `h:mm:ss` from an hour up.
+ *
+ * @param ms - Milliseconds left. Rounded up to whole seconds; negative values count as `0`.
+ * @returns Clock text, e.g. `24:59`.
+ */
+export function clock(ms: number): string {
+  const total = Math.max(0, Math.ceil(ms / 1000))
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  const s = total % 60
+  const mm = String(m).padStart(2, '0')
+  const ss = String(s).padStart(2, '0')
+  return h > 0 ? `${h}:${mm}:${ss}` : `${mm}:${ss}`
+}
+
+/**
+ * Formats a wall-clock time as `3:10 pm`.
+ *
+ * @param epochMs - Time in milliseconds since the epoch, shown in local time.
+ * @returns 12-hour clock text.
+ */
+function wallTime(epochMs: number): string {
+  const date = new Date(epochMs)
+  const hours = date.getHours()
+  const minutes = String(date.getMinutes()).padStart(2, '0')
+  return `${hours % 12 === 0 ? 12 : hours % 12}:${minutes} ${hours < 12 ? 'am' : 'pm'}`
+}
+
+/**
+ * Draws a row of squares as one SVG, lighting the first `filled` of them.
+ *
+ * @param count - Number of squares.
+ * @param filled - Number of lit squares, counted from the left.
+ * @returns The SVG markup as a string.
+ */
+function squaresSvg(count: number, filled: number): string {
+  const size = 10
+  const gap = 3
+  const width = count * (size + gap) - gap
+  const rects = Array.from({ length: count }, (_, i) =>
+    `<rect x="${i * (size + gap)}" y="0" width="${size}" height="${size}" rx="2" fill="${i < filled ? FILLED : EMPTY}"/>`)
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${size}" viewBox="0 0 ${width} ${size}">${rects.join('')}</svg>`
+}
+
+/**
+ * Starts a block of `minutes`, replacing one already running, and shows the pane.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param minutes - Length of the block in minutes.
+ */
+async function startFocus($: EngineInterface, minutes: number): Promise<void> {
+  const startedAt = await $.clock.now()
+  await update($, block, () => ({ startedAt, endsAt: startedAt + minutes * 60_000, minutes }))
+  await $.ui.open({ id: PANE, title: TITLE })
+}
+
+/**
+ * Ends the running block, and counts it as done when it ran its full time.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param isDone - `true` when the block ran out, `false` when the user ended it early.
+ */
+async function endFocus($: EngineInterface, isDone: boolean): Promise<void> {
+  const current = await read($, block)
+  if (current === null) return
+  await update($, block, () => null)
+  $.ui.status(undefined)
+  if (isDone) {
+    await update($, finished, n => n + 1)
+    $.ui.toast(`Focus block done: ${current.minutes} min`)
+    await $.ui.notify(`${current.minutes} minutes of focus done. Take a break.`, { title: 'Focus block done' }).catch(() => undefined)
+  }
+}
+
+/**
+ * Moves the running block on by one second: ends it when its time is up, else updates the countdown.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
+async function tick($: EngineInterface): Promise<void> {
+  const current = await read($, block)
+  if (current === null) return
+  const now = await $.clock.now()
+  if (now >= current.endsAt) {
+    await endFocus($, true)
+    return
+  }
+  $.ui.status(`focus ${clock(current.endsAt - now)}`)
+  $.ui.invalidate('ui.render')
+}
+
+/**
+ * Registers this mod's `focus-mode` command, its session hook, its tick, and its pane.
+ *
+ * @param on - Hook registration function the engine passes in.
+ * @param options - Plugin options; `minutes` sets the default block length.
+ */
+export const register: Register = (on, options) => {
+  const configured = Number(options.minutes ?? DEFAULT_MINUTES)
+  const defaultMinutes = Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_MINUTES
+
+  on('session.start', async ($, e, next) => {
+    await $.command.register({
+      name: 'focus-mode',
+      description: `Start a focus block (${defaultMinutes} min by default), or end the running one`,
+      argumentHint: '[minutes] | end',
+    })
+    $.clock.every(1000, () => void tick($))
+    return next(e)
+  })
+
+  on('command.run', { command: 'focus-mode' }, async ($, e) => {
+    const arg = e.args.trim()
+    if (arg === 'end' || arg === 'stop') {
+      await endFocus($, false)
+      return { text: 'Focus block ended.' }
+    }
+    const minutes = arg === '' ? defaultMinutes : Number(arg)
+    if (!Number.isFinite(minutes) || minutes <= 0 || minutes > 600) {
+      return { text: `"${arg}" is not a number of minutes. Use /focus-mode 25, or /focus-mode end.` }
+    }
+    await startFocus($, minutes)
+    return { text: `Focus block started: ${minutes} min.` }
+  })
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text, Button } = $.ui.resolve(e)
+    const current = await read($, block)
+
+    if (current === null) {
+      const done = await read($, finished)
+      return (
+        <Box flexDirection="row" justifyContent="space-between" alignItems="center">
+          <Text dimColor>{done > 0 ? `${done} focus block${done === 1 ? '' : 's'} done this session.` : 'No focus block running.'}</Text>
+          <Button key="start" label={`start ${defaultMinutes} min`} variant="primary" onPress={() => startFocus($, defaultMinutes)} />
+        </Box>
+      )
+    }
+
+    const now = await $.clock.now()
+    const remaining = current.endsAt - now
+    const count = Math.min(MAX_SQUARES, Math.max(1, Math.round(current.minutes)))
+    const filled = Math.ceil((remaining / (current.endsAt - current.startedAt)) * count)
+    const squares = e.surface === 'terminal'
+      ? (
+          <Text>
+            <Text color={FILLED}>{'■'.repeat(filled)}</Text>
+            <Text color={EMPTY}>{'■'.repeat(count - filled)}</Text>
+          </Text>
+        )
+      : (() => {
+          const { Svg } = $.ui.resolve(e)
+          return <Svg source={squaresSvg(count, filled)} alt={`${clock(remaining)} left`} width={count * 13 - 3} height={10} />
+        })()
+
+    return (
+      <Box flexDirection="row" alignItems="center" columnGap={3}>
+        <Text bold>{clock(remaining)}</Text>
+        <Box flexDirection="column" flexGrow={1} gap={0}>
+          {squares}
+          <Text dimColor>focus block · {current.minutes} min · ends {wallTime(current.endsAt)}</Text>
+        </Box>
+        <Button key="end" label="end focus" onPress={() => endFocus($, false)} />
+      </Box>
+    )
+  })
+}

package/mods/focus-mode/types/index.d.ts

@@ -0,0 +1,14 @@
+// packages/g3n-mods/mods/focus-mode/types/index.d.ts
+
+/** A running focus block; times are milliseconds since the epoch. */
+export type FocusBlock = {
+  startedAt: number
+  endsAt: number
+  minutes: number
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'focus-mode': { block: FocusBlock | null; finished: number }
+  }
+}

package/mods/handoff/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "handoff",
+  "version": "0.1.0",
+  "description": "Writes a handoff with the handoff skill, clears the session, and starts the fresh one with your next prompt.",
+  "author": {
+    "name": "g3ntrovert"
+  },
+  "types": "./types/index.d.ts"
+}

package/mods/handoff/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/mods/handoff/hooks/register.tsx

@@ -0,0 +1,156 @@
+// packages/g3n-mods/mods/handoff/hooks/register.tsx
+import { atom, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { PendingHandoff } from '../types'
+
+const pending = atom({ plugin: 'handoff', key: 'pending' } as const, null)
+
+const STORE_KEY = 'pending'
+const SKILL_PATH = '.claude/skills/handoff/SKILL.md'
+/** A handoff older than this is dropped instead of attached. */
+const MAX_AGE_MS = 24 * 60 * 60 * 1000
+
+/** The handoff skill's instructions, used when no `handoff` skill is installed. */
+const FALLBACK_SKILL = [
+  'Write a handoff document summarising the current conversation so a fresh agent can continue the work.',
+  'Include a "suggested skills" section, which suggests skills that the agent should invoke.',
+  'Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.',
+  'Redact any sensitive information, such as API keys, passwords, or personally identifiable information.',
+  'If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.',
+].join('\n\n')
+
+/**
+ * Removes the frontmatter block from a Markdown skill file.
+ *
+ * @param text - Full text of a `SKILL.md` file.
+ * @returns The body, trimmed.
+ */
+function withoutFrontmatter(text: string): string {
+  return text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim()
+}
+
+/**
+ * Tells whether a stored value has the shape of a `PendingHandoff`.
+ *
+ * @param value - Value read from the store, of unknown shape.
+ * @returns `true` when `text` and `path` are strings and `createdAt` is a number.
+ */
+function isPendingHandoff(value: unknown): value is PendingHandoff {
+  return typeof value === 'object' && value !== null
+    && 'text' in value && typeof value.text === 'string'
+    && 'path' in value && typeof value.path === 'string'
+    && 'createdAt' in value && typeof value.createdAt === 'number'
+}
+
+/**
+ * Loads the `handoff` skill's instructions: the project's copy, else the user's, else the built-in copy.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @returns The instructions without their frontmatter.
+ */
+async function loadSkill($: EngineInterface): Promise<string> {
+  const root = await $.session.root()
+  const home = await $.env.get('HOME')
+  for (const path of [`${root}/${SKILL_PATH}`, home === undefined ? '' : `${home}/${SKILL_PATH}`]) {
+    if (path !== '' && (await $.fs.exists(path))) return withoutFrontmatter(await $.fs.read(path))
+  }
+  return FALLBACK_SKILL
+}
+
+/**
+ * Builds the path of a handoff document in the OS temporary folder, named by the time it was written.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param now - Time the handoff was written, in milliseconds since the epoch.
+ * @returns Absolute path, e.g. `/tmp/claude-handoff-2026-10-11T09-30-00.md`.
+ */
+async function documentPath($: EngineInterface, now: number): Promise<string> {
+  const tmp = ((await $.env.get('TMPDIR')) ?? '/tmp').replace(/\/$/, '')
+  const stamp = new Date(now).toISOString().replace(/[:.]/g, '-').slice(0, 19)
+  return `${tmp}/claude-handoff-${stamp}.md`
+}
+
+/**
+ * Runs /clear, after the command that asked for it has answered. Shows a toast when /clear cannot run.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
+async function clearSession($: EngineInterface): Promise<void> {
+  await $.command.run({ command: 'clear' }).catch(() => $.ui.toast('Run /clear to start the fresh session; the handoff waits for your next prompt.'))
+}
+
+/**
+ * Takes the handoff waiting for the next prompt, and removes it from the store either way.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @returns The handoff, or `undefined` when none waits or it is older than 24 hours.
+ */
+async function takePending($: EngineInterface): Promise<PendingHandoff | undefined> {
+  const stored = await $.store.get(STORE_KEY)
+  if (!isPendingHandoff(stored)) return undefined
+  await $.store.delete(STORE_KEY)
+  await update($, pending, () => null)
+  $.ui.status(undefined)
+  const now = await $.clock.now()
+  return now - stored.createdAt > MAX_AGE_MS ? undefined : stored
+}
+
+/**
+ * Registers this mod's `handoff-new` command, its session hook, and its prompt hook.
+ *
+ * @param on - Hook registration function the engine passes in.
+ */
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({
+      name: 'handoff-new',
+      description: 'Write a handoff, clear the session, and start the fresh one with your next prompt',
+      argumentHint: 'what the next session is for',
+    })
+    const stored = await $.store.get(STORE_KEY)
+    if (isPendingHandoff(stored)) {
+      await update($, pending, () => stored)
+      $.ui.status('handoff ready: your next prompt starts with it')
+    }
+    return next(e)
+  })
+
+  on('command.run', { command: 'handoff-new' }, async ($, e) => {
+    const skill = await loadSkill($)
+    const focus = e.args.trim()
+    const prompt = [
+      'Write the handoff document these instructions describe, for the conversation so far.',
+      'You cannot use tools. Answer with the document as Markdown and nothing else; it is saved for you.',
+      focus.length > 0 ? `The next session will be used for: ${focus}` : '',
+      '<instructions>',
+      skill,
+      '</instructions>',
+    ].filter(line => line.length > 0).join('\n\n')
+
+    $.ui.toast('Writing the handoff…')
+    const written = await $.model.fork({ prompt })
+    if (!written.isAnswered) {
+      return { text: `The handoff was not written (${written.reason}). The conversation is unchanged.`, exitCode: 1 }
+    }
+
+    const now = await $.clock.now()
+    const path = await documentPath($, now)
+    await $.fs.write(path, written.text)
+    const handoff: PendingHandoff = { text: written.text, path, createdAt: now }
+    await $.store.set(STORE_KEY, handoff)
+    await update($, pending, () => handoff)
+    $.ui.status('handoff ready: your next prompt starts with it')
+    $.clock.after(0, () => void clearSession($))
+    return { text: `Handoff saved to ${path}. The conversation clears now; your next prompt starts the fresh session with it.` }
+  })
+
+  on('prompt.submit', async ($, e, next) => {
+    if (e.text.trimStart().startsWith('/')) return next(e)
+    const handoff = await takePending($)
+    if (handoff === undefined) return next(e)
+    $.ui.toast('Handoff attached to this prompt')
+    const context = `Handoff from the previous session, saved at ${handoff.path}:\n\n${handoff.text}`
+    return next({ ...e, context: [...(e.context ?? []), context] })
+  }).catch(($, e, next) => next(e))
+}

package/mods/handoff/types/index.d.ts

@@ -0,0 +1,15 @@
+// packages/g3n-mods/mods/handoff/types/index.d.ts
+
+/** A handoff written and waiting for the next prompt; `createdAt` is milliseconds since the epoch. */
+export type PendingHandoff = {
+  text: string
+  /** Absolute path the document was saved to */
+  path: string
+  createdAt: number
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    handoff: { pending: PendingHandoff | null }
+  }
+}

package/mods/hide-personal-data/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "hide-personal-data",
+  "version": "0.1.0",
+  "description": "Masks names, emails and other personal data in replies; hover to show them.",
+  "author": {
+    "name": "g3ntrovert"
+  },
+  "types": "./types/index.d.ts",
+  "userConfig": {
+    "names": {
+      "type": "string",
+      "title": "Names",
+      "default": "",
+      "description": "Extra names to mask, separated by commas"
+    }
+  }
+}

package/mods/hide-personal-data/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }