@erclx/aitk 0.8.0

package/src/slides/layouts.ts

@@ -0,0 +1,391 @@
+import type PptxGenJS from 'pptxgenjs'
+import type { Slide } from '@/slides/parse'
+import { FONTS, type Theme, TYPE } from '@/slides/styles'
+
+type Deck = InstanceType<typeof PptxGenJS>
+type PptxSlide = ReturnType<Deck['addSlide']>
+
+export interface LayoutInfo {
+  name: string
+  description: string
+}
+
+export interface NavEntry {
+  title: string
+  slideNumber: number
+}
+
+export interface DeckNav {
+  deckTitle: string
+  tocSlide?: number
+  sections: NavEntry[]
+}
+
+export const LAYOUTS: LayoutInfo[] = [
+  { name: 'title', description: 'Cover slide with deck title and subtitle' },
+  { name: 'toc', description: 'Contents slide linking to each section' },
+  { name: 'section', description: 'Section divider with one large heading' },
+  { name: 'bullets', description: 'Title above a bullet list' },
+  { name: 'two-column', description: 'Two labeled columns of bullets' },
+  { name: 'stat-callout', description: 'Row of large stats with captions' },
+  { name: 'grid', description: 'Two-by-two cards, each a term and detail' },
+  { name: 'quote', description: 'Large pull quote with attribution' },
+]
+
+const W = 13.333
+const H = 7.5
+const MX = 0.7
+const CW = W - MX * 2
+const BODY_Y = 1.7
+
+const RENDERERS: Record<
+  string,
+  (s: PptxSlide, slide: Slide, theme: Theme) => void
+> = {
+  title: renderTitle,
+  section: renderSection,
+  bullets: renderBullets,
+  'two-column': renderTwoColumn,
+  'stat-callout': renderStatCallout,
+  grid: renderGrid,
+  quote: renderQuote,
+}
+
+export function renderDeckSlide(
+  s: PptxSlide,
+  slide: Slide,
+  theme: Theme,
+): void {
+  const renderer = RENDERERS[slide.layout] ?? renderBullets
+  renderer(s, slide, theme)
+}
+
+export function renderToc(
+  s: PptxSlide,
+  slide: Slide,
+  theme: Theme,
+  nav: DeckNav,
+): void {
+  addTitle(s, slide.title || 'Contents', theme)
+  if (nav.sections.length === 0) return
+  s.addText(
+    nav.sections.map((entry) => ({
+      text: entry.title,
+      options: { breakLine: true, hyperlink: { slide: entry.slideNumber } },
+    })),
+    {
+      x: MX,
+      y: BODY_Y,
+      w: CW,
+      h: 5,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body + 2,
+      color: theme.accent,
+      valign: 'top',
+      lineSpacingMultiple: 1.6,
+    },
+  )
+}
+
+export function addFooter(
+  s: PptxSlide,
+  slide: Slide,
+  theme: Theme,
+  nav: DeckNav,
+): void {
+  if (slide.layout === 'title' || slide.layout === 'toc') return
+  if (nav.deckTitle) {
+    s.addText(nav.deckTitle, {
+      x: MX,
+      y: H - 0.5,
+      w: CW / 2,
+      h: 0.3,
+      fontFace: FONTS.body,
+      fontSize: TYPE.caption,
+      color: theme.muted,
+      valign: 'middle',
+    })
+  }
+  if (nav.tocSlide) {
+    s.addText('Contents', {
+      x: MX + CW / 2,
+      y: H - 0.5,
+      w: CW / 2,
+      h: 0.3,
+      fontFace: FONTS.body,
+      fontSize: TYPE.caption,
+      color: theme.muted,
+      align: 'right',
+      valign: 'middle',
+      hyperlink: { slide: nav.tocSlide },
+    })
+  }
+}
+
+function renderTitle(s: PptxSlide, slide: Slide, theme: Theme): void {
+  s.addText(clean(slide.title), {
+    x: MX,
+    y: 2.6,
+    w: CW,
+    h: 1.4,
+    fontFace: FONTS.heading,
+    fontSize: TYPE.cover,
+    bold: true,
+    color: theme.ink,
+    valign: 'top',
+  })
+  const subtitle = slide.content.join(' ').trim()
+  if (subtitle) {
+    s.addText(clean(subtitle), {
+      x: MX,
+      y: 4.1,
+      w: CW,
+      h: 1,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body + 4,
+      color: theme.muted,
+      valign: 'top',
+    })
+  }
+}
+
+function renderSection(s: PptxSlide, slide: Slide, theme: Theme): void {
+  s.addText(clean(slide.title), {
+    x: MX,
+    y: 2.9,
+    w: CW,
+    h: 1.6,
+    fontFace: FONTS.heading,
+    fontSize: TYPE.section,
+    bold: true,
+    color: theme.accent,
+    valign: 'middle',
+  })
+}
+
+function renderBullets(s: PptxSlide, slide: Slide, theme: Theme): void {
+  addTitle(s, slide.title, theme)
+  const items = bullets(slide.content)
+  if (items.length === 0) return
+  s.addText(
+    items.map((text) => ({
+      text,
+      options: { bullet: { code: '2022' }, breakLine: true },
+    })),
+    {
+      x: MX,
+      y: BODY_Y,
+      w: CW,
+      h: 5,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body,
+      color: theme.ink,
+      valign: 'top',
+      lineSpacingMultiple: 1.3,
+      paraSpaceAfter: 10,
+    },
+  )
+}
+
+function renderTwoColumn(s: PptxSlide, slide: Slide, theme: Theme): void {
+  addTitle(s, slide.title, theme)
+  const cols = columns(slide.content)
+  const gap = 0.6
+  const colWidth = (CW - gap) / 2
+  cols.slice(0, 2).forEach((col, index) => {
+    const x = MX + index * (colWidth + gap)
+    s.addText(col.heading, {
+      x,
+      y: BODY_Y,
+      w: colWidth,
+      h: 0.6,
+      fontFace: FONTS.heading,
+      fontSize: TYPE.body + 4,
+      bold: true,
+      color: theme.accent,
+      valign: 'top',
+    })
+    if (col.items.length === 0) return
+    s.addText(
+      col.items.map((text) => ({
+        text,
+        options: { bullet: { code: '2022' }, breakLine: true },
+      })),
+      {
+        x,
+        y: BODY_Y + 0.7,
+        w: colWidth,
+        h: 4.3,
+        fontFace: FONTS.body,
+        fontSize: TYPE.body,
+        color: theme.ink,
+        valign: 'top',
+        lineSpacingMultiple: 1.3,
+        paraSpaceAfter: 8,
+      },
+    )
+  })
+}
+
+function renderStatCallout(s: PptxSlide, slide: Slide, theme: Theme): void {
+  addTitle(s, slide.title, theme)
+  const stats = pairs(slide.content).slice(0, 4)
+  if (stats.length === 0) return
+  const gap = 0.5
+  const cellWidth = (CW - gap * (stats.length - 1)) / stats.length
+  stats.forEach((stat, index) => {
+    const x = MX + index * (cellWidth + gap)
+    s.addText(stat.left, {
+      x,
+      y: 2.6,
+      w: cellWidth,
+      h: 1.3,
+      fontFace: FONTS.heading,
+      fontSize: TYPE.stat,
+      bold: true,
+      color: theme.accent,
+      align: 'left',
+      valign: 'top',
+    })
+    s.addText(stat.right, {
+      x,
+      y: 3.9,
+      w: cellWidth,
+      h: 1.4,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body,
+      color: theme.muted,
+      align: 'left',
+      valign: 'top',
+    })
+  })
+}
+
+function renderGrid(s: PptxSlide, slide: Slide, theme: Theme): void {
+  addTitle(s, slide.title, theme)
+  const cards = pairs(slide.content).slice(0, 4)
+  const gap = 0.5
+  const cardWidth = (CW - gap) / 2
+  const cardHeight = 2.1
+  cards.forEach((card, index) => {
+    const col = index % 2
+    const row = Math.floor(index / 2)
+    const x = MX + col * (cardWidth + gap)
+    const y = BODY_Y + row * (cardHeight + gap)
+    s.addShape('roundRect', {
+      x,
+      y,
+      w: cardWidth,
+      h: cardHeight,
+      fill: { color: theme.surface },
+      line: { type: 'none' },
+      rectRadius: 0.08,
+    })
+    s.addText(card.left, {
+      x: x + 0.3,
+      y: y + 0.25,
+      w: cardWidth - 0.6,
+      h: 0.6,
+      fontFace: FONTS.heading,
+      fontSize: TYPE.body + 4,
+      bold: true,
+      color: theme.ink,
+      valign: 'top',
+    })
+    s.addText(card.right, {
+      x: x + 0.3,
+      y: y + 0.95,
+      w: cardWidth - 0.6,
+      h: cardHeight - 1.2,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body - 2,
+      color: theme.ink,
+      valign: 'top',
+      lineSpacingMultiple: 1.2,
+    })
+  })
+}
+
+function renderQuote(s: PptxSlide, slide: Slide, theme: Theme): void {
+  const lines = slide.content
+  const attribution = lines.find((line) => /^(—|-)\s/.test(line.trim()))
+  const quote = lines
+    .filter((line) => line !== attribution)
+    .join(' ')
+    .trim()
+  s.addText(clean(quote), {
+    x: MX,
+    y: 2.2,
+    w: CW,
+    h: 2.6,
+    fontFace: FONTS.heading,
+    fontSize: TYPE.quote,
+    italic: true,
+    color: theme.ink,
+    valign: 'top',
+    lineSpacingMultiple: 1.25,
+  })
+  if (attribution) {
+    s.addText(clean(attribution.replace(/^(—|-)\s+/, '')), {
+      x: MX,
+      y: 5,
+      w: CW,
+      h: 0.6,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body,
+      bold: true,
+      color: theme.accent,
+      valign: 'top',
+    })
+  }
+}
+
+function addTitle(s: PptxSlide, title: string, theme: Theme): void {
+  if (!title) return
+  s.addText(clean(title), {
+    x: MX,
+    y: 0.5,
+    w: CW,
+    h: 0.9,
+    fontFace: FONTS.heading,
+    fontSize: TYPE.title,
+    bold: true,
+    color: theme.ink,
+    valign: 'top',
+  })
+}
+
+function clean(text: string): string {
+  return text.replace(/\*\*/g, '').replace(/`/g, '').trim()
+}
+
+function bullets(content: string[]): string[] {
+  return content
+    .filter((line) => line.trim().startsWith('-'))
+    .map((line) => clean(line.replace(/^\s*-\s+/, '')))
+}
+
+function pairs(content: string[]): { left: string; right: string }[] {
+  return content
+    .filter((line) => line.trim().startsWith('-'))
+    .map((line) => line.replace(/^\s*-\s+/, ''))
+    .map((line) => {
+      const [left, ...rest] = line.split(/\s*:\s*/)
+      return { left: clean(left), right: clean(rest.join(': ')) }
+    })
+}
+
+function columns(content: string[]): { heading: string; items: string[] }[] {
+  const cols: { heading: string; items: string[] }[] = []
+  for (const line of content) {
+    const heading = line.match(/^##\s+(.+)/)
+    if (heading) {
+      cols.push({ heading: clean(heading[1]), items: [] })
+      continue
+    }
+    if (line.trim().startsWith('-') && cols.length > 0) {
+      cols[cols.length - 1].items.push(clean(line.replace(/^\s*-\s+/, '')))
+    }
+  }
+  return cols
+}

package/src/slides/open.ts

@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs'
+import { execa } from 'execa'
+
+export async function openDeck(path: string): Promise<boolean> {
+  const windowsPath = await execa('wslpath', ['-w', path], { reject: false })
+  if (windowsPath.exitCode === 0) {
+    const cwd = existsSync('/mnt/c') ? '/mnt/c' : undefined
+    const result = await execa(
+      'cmd.exe',
+      ['/c', 'start', '', windowsPath.stdout.trim()],
+      { cwd, reject: false },
+    )
+    return result.exitCode === 0
+  }
+  const opener = process.platform === 'darwin' ? 'open' : 'xdg-open'
+  const result = await execa(opener, [path], { reject: false })
+  return result.exitCode === 0
+}

package/src/slides/parse.ts

@@ -0,0 +1,84 @@
+import { readFileSync } from 'node:fs'
+import type { Variant } from '@/slides/styles'
+
+export interface DeckMeta {
+  title: string
+  variant: Variant
+}
+
+export interface Slide {
+  layout: string
+  title: string
+  content: string[]
+}
+
+export interface Deck {
+  meta: DeckMeta
+  slides: Slide[]
+}
+
+const DEFAULT_META: DeckMeta = {
+  title: '',
+  variant: 'light',
+}
+
+export function parseSlidesDoc(path: string): Deck {
+  return parseSlides(readFileSync(path, 'utf8'))
+}
+
+export function parseSlides(raw: string): Deck {
+  const { meta, body } = splitFrontmatter(raw)
+  const slides = body
+    .split(/^---\s*$/m)
+    .map(parseSlide)
+    .filter((slide): slide is Slide => slide !== null)
+  return { meta, slides }
+}
+
+function splitFrontmatter(raw: string): { meta: DeckMeta; body: string } {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?/)
+  if (!match) return { meta: { ...DEFAULT_META }, body: raw }
+  return { meta: parseMeta(match[1]), body: raw.slice(match[0].length) }
+}
+
+function parseMeta(block: string): DeckMeta {
+  const meta: DeckMeta = { ...DEFAULT_META }
+  for (const line of block.split('\n')) {
+    const match = line.match(/^(\w+):\s*(.+?)\s*$/)
+    if (!match) continue
+    const [, key, value] = match
+    if (key === 'title') meta.title = value
+    if (key === 'variant' && (value === 'light' || value === 'dark')) {
+      meta.variant = value
+    }
+  }
+  return meta
+}
+
+function parseSlide(chunk: string): Slide | null {
+  let title = ''
+  let layout = ''
+  const content: string[] = []
+  for (const line of chunk.split('\n')) {
+    const heading = line.match(/^#\s+(.+?)\s*$/)
+    const declared = line.match(/^layout:\s*(.+?)\s*$/)
+    if (heading && !title) {
+      title = heading[1]
+      continue
+    }
+    if (declared && !layout) {
+      layout = declared[1].trim()
+      continue
+    }
+    content.push(line)
+  }
+  const trimmed = content.filter((line) => line.trim())
+  if (!title && !layout && trimmed.length === 0) return null
+  return { layout: layout || inferLayout(trimmed), title, content: trimmed }
+}
+
+function inferLayout(content: string[]): string {
+  return content.some((line) => line.trim().startsWith('-'))
+    ? 'bullets'
+    : 'title'
+}

package/src/slides/render.ts

@@ -0,0 +1,88 @@
+import { copyFileSync, mkdirSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import PptxGenJS from 'pptxgenjs'
+import {
+  addFooter,
+  type DeckNav,
+  renderDeckSlide,
+  renderToc,
+} from '@/slides/layouts'
+import { type Deck, parseSlidesDoc } from '@/slides/parse'
+import { buildTheme, type Variant } from '@/slides/styles'
+
+export interface RenderResult {
+  pptxPath: string
+  mirrorPath?: string
+  slideCount: number
+}
+
+export interface RenderOptions {
+  variant?: Variant
+  mirror?: string
+}
+
+export async function renderSlidesDoc(
+  sourcePath: string,
+  outDir: string,
+  options: RenderOptions = {},
+): Promise<RenderResult> {
+  const deck = parseSlidesDoc(sourcePath)
+  const variant = options.variant ?? deck.meta.variant
+  const theme = buildTheme(variant)
+
+  const pptx = new PptxGenJS()
+  pptx.layout = 'LAYOUT_WIDE'
+  if (deck.meta.title) pptx.title = deck.meta.title
+
+  const nav = buildNav(deck)
+  for (const slide of deck.slides) {
+    const target = pptx.addSlide()
+    target.background = { color: theme.background }
+    if (slide.layout === 'toc') {
+      renderToc(target, slide, theme, nav)
+    } else {
+      renderDeckSlide(target, slide, theme)
+    }
+    addFooter(target, slide, theme, nav)
+  }
+
+  mkdirSync(outDir, { recursive: true })
+  const fileName = outputName(sourcePath)
+  const pptxPath = join(outDir, fileName)
+  await pptx.writeFile({ fileName: pptxPath })
+
+  const mirrorPath = options.mirror
+    ? mirrorDeck(pptxPath, options.mirror, fileName)
+    : undefined
+  return { pptxPath, mirrorPath, slideCount: deck.slides.length }
+}
+
+function mirrorDeck(
+  pptxPath: string,
+  mirrorDir: string,
+  fileName: string,
+): string {
+  mkdirSync(mirrorDir, { recursive: true })
+  const mirrorPath = join(mirrorDir, fileName)
+  copyFileSync(pptxPath, mirrorPath)
+  return mirrorPath
+}
+
+export function buildNav(deck: Deck): DeckNav {
+  let tocSlide: number | undefined
+  const sections: DeckNav['sections'] = []
+  deck.slides.forEach((slide, index) => {
+    const slideNumber = index + 1
+    if (slide.layout === 'toc' && tocSlide === undefined) {
+      tocSlide = slideNumber
+    }
+    if (slide.layout === 'section') {
+      sections.push({ title: slide.title, slideNumber })
+    }
+  })
+  return { deckTitle: deck.meta.title, tocSlide, sections }
+}
+
+function outputName(sourcePath: string): string {
+  return basename(sourcePath).replace(/\.md$/, '') + '.pptx'
+}

package/src/slides/styles.ts

@@ -0,0 +1,44 @@
+export type Variant = 'light' | 'dark'
+
+export interface Theme {
+  background: string
+  surface: string
+  ink: string
+  muted: string
+  accent: string
+}
+
+const LIGHT: Theme = {
+  background: 'FAF7F2',
+  surface: 'F4EFE6',
+  ink: '1A1815',
+  muted: '7A736A',
+  accent: 'A4471C',
+}
+
+const DARK: Theme = {
+  background: '1A1815',
+  surface: '23201C',
+  ink: 'F4EFE6',
+  muted: 'A39C92',
+  accent: 'C8602E',
+}
+
+export const FONTS = {
+  heading: 'Arial',
+  body: 'Calibri',
+} as const
+
+export const TYPE = {
+  cover: 44,
+  section: 40,
+  title: 30,
+  body: 16,
+  stat: 54,
+  quote: 30,
+  caption: 11,
+} as const
+
+export function buildTheme(variant: Variant): Theme {
+  return variant === 'dark' ? DARK : LIGHT
+}

package/src/snippets/adapter.ts

@@ -0,0 +1,34 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { snippetsSourceDir } from '@/snippets/categories'
+import type { InstalledFile, SyncAdapter } from '@/sync/engine'
+
+/**
+ * Matches installed snippets to sources by relative path, where gov matches by
+ * rule name. `derive_dest_rel_path` in `scripts/snippets/install.sh` keeps the
+ * immediate parent for a nested snippet and flattens a root-level one to its
+ * filename, which is the shape a source-relative path already has, so
+ * destination and source rel paths agree for everything the toolkit ships.
+ */
+export function createSnippetsAdapter(root: string): SyncAdapter {
+  const sourceDir = snippetsSourceDir(root)
+
+  return {
+    banner: 'aitk snippets sync',
+    label: 'snippets',
+    missingMessage:
+      "No .claude/snippets/ found in target. Run 'aitk snippets install' first.",
+    unit: 'snippets',
+    installedRoot: (target: string) => join(target, '.claude', 'snippets'),
+    locateSource: (file: InstalledFile) => locateSource(sourceDir, file),
+    stamp: { domain: 'snippets', toolkitRoot: root },
+  }
+}
+
+function locateSource(
+  sourceDir: string,
+  file: InstalledFile,
+): string | undefined {
+  const source = join(sourceDir, file.relToRoot)
+  return existsSync(source) ? source : undefined
+}