@erclx/aitk 0.8.0

package/src/transcripts/metadata.ts

@@ -0,0 +1,54 @@
+export interface VideoMetadata {
+  readonly videoId: string
+  readonly title: string
+  readonly channel: string
+  readonly durationSeconds: number
+  readonly published: string
+  readonly url: string
+}
+
+const SLUG_PATTERN = /[^a-z0-9]+/g
+
+export function slugify(text: string, maxLength = 50): string {
+  const cleaned = text
+    .toLowerCase()
+    .replace(SLUG_PATTERN, '-')
+    .replace(/(^-|-$)/g, '')
+  if (!cleaned) return 'untitled'
+  return cleaned.slice(0, maxLength).replace(/-$/, '') || 'untitled'
+}
+
+export function formatUploadDate(yyyymmdd: string | undefined): string {
+  if (!yyyymmdd || yyyymmdd.length !== 8 || !/^\d{8}$/.test(yyyymmdd)) return ''
+  return `${yyyymmdd.slice(0, 4)}-${yyyymmdd.slice(4, 6)}-${yyyymmdd.slice(6)}`
+}
+
+function yamlEscape(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+}
+
+interface FrontmatterOptions {
+  readonly hasTranscript: boolean
+  readonly fetchedAt: string
+}
+
+export function renderFrontmatter(
+  video: VideoMetadata,
+  { hasTranscript, fetchedAt }: FrontmatterOptions,
+): string {
+  const lines = [
+    '---',
+    `title: ${yamlEscape(video.title)}`,
+    `channel: ${yamlEscape(video.channel)}`,
+    `video_id: ${video.videoId}`,
+    `url: ${video.url}`,
+    `duration: ${video.durationSeconds}`,
+    video.published ? `published: ${video.published}` : 'published:',
+    `fetched_at: ${fetchedAt}`,
+    `has_transcript: ${hasTranscript ? 'true' : 'false'}`,
+    '---',
+    '',
+    '',
+  ]
+  return lines.join('\n')
+}

package/src/transcripts/vtt.ts

@@ -0,0 +1,114 @@
+export interface Cue {
+  readonly timestamp: string
+  readonly text: string
+}
+
+const VTT_TIMESTAMP = /^(\d\d:)?\d\d:\d\d\.\d{3} --> .*$/
+const VTT_INLINE_TAG = /<[^>]+>/g
+const VTT_NUMERIC_LINE = /^\d+$/
+
+export function parseVtt(raw: string): Cue[] {
+  const cues: Cue[] = []
+  let currentTimestamp: string | null = null
+  let currentLines: string[] = []
+  let inHeader = true
+
+  const flush = (): void => {
+    if (currentTimestamp !== null && currentLines.length) {
+      const text = currentLines.join(' ').trim()
+      if (text) cues.push({ timestamp: currentTimestamp, text })
+    }
+    currentTimestamp = null
+    currentLines = []
+  }
+
+  for (const rawLine of raw.split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+$/, '')
+    if (inHeader) {
+      if (VTT_TIMESTAMP.test(line)) inHeader = false
+      else continue
+    }
+    if (VTT_TIMESTAMP.test(line)) {
+      flush()
+      currentTimestamp = line.split(' --> ', 1)[0].trim()
+      continue
+    }
+    if (line.trim() === '') {
+      flush()
+      continue
+    }
+    if (VTT_NUMERIC_LINE.test(line.trim())) continue
+    const cleaned = line.replace(VTT_INLINE_TAG, '').trim()
+    if (cleaned) currentLines.push(cleaned)
+  }
+  flush()
+  return cues
+}
+
+export function dedupeRollingCues(cues: Cue[]): Cue[] {
+  const deduped: Cue[] = []
+  let running = ''
+  for (const { timestamp, text } of cues) {
+    const maxOverlap = Math.min(running.length, text.length)
+    let overlap = 0
+    for (let size = maxOverlap; size > 0; size -= 1) {
+      if (running.endsWith(text.slice(0, size))) {
+        overlap = size
+        break
+      }
+    }
+    const addition = text.slice(overlap).trim()
+    if (!addition) continue
+    running = `${running} ${addition}`.trim()
+    deduped.push({ timestamp, text: addition })
+  }
+  return deduped
+}
+
+function vttTimestampToSeconds(stamp: string): number {
+  const parts = stamp.split(':')
+  let hours = '0'
+  let minutes: string
+  let rest: string
+  if (parts.length === 3) [hours, minutes, rest] = parts
+  else if (parts.length === 2) [minutes, rest] = parts
+  else return 0
+  const seconds = rest.split('.', 1)[0]
+  return Number(hours) * 3600 + Number(minutes) * 60 + Number(seconds)
+}
+
+function formatSeconds(seconds: number): string {
+  const minutes = Math.floor(seconds / 60)
+  const secs = seconds % 60
+  return `${String(minutes).padStart(2, '0')}:${String(secs).padStart(2, '0')}`
+}
+
+interface RenderOptions {
+  readonly keepTimestamps: boolean
+}
+
+export function renderBody(
+  cues: Cue[],
+  { keepTimestamps }: RenderOptions,
+): string {
+  if (!cues.length) return ''
+  if (keepTimestamps) {
+    const lines = cues.map(
+      ({ timestamp, text }) =>
+        `[${formatSeconds(vttTimestampToSeconds(timestamp))}] ${text}`,
+    )
+    return `${lines.join('\n')}\n`
+  }
+  const joined = cues.map(({ text }) => text).join(' ')
+  return `${paragraphWrap(joined)}\n`
+}
+
+function paragraphWrap(text: string, wordsPerParagraph = 60): string {
+  const words = text.split(/\s+/).filter(Boolean)
+  if (!words.length) return ''
+  const paragraphs: string[] = []
+  for (let start = 0; start < words.length; start += wordsPerParagraph) {
+    paragraphs.push(words.slice(start, start + wordsPerParagraph).join(' '))
+  }
+  return paragraphs.join('\n\n')
+}

package/src/ui.ts

@@ -0,0 +1,187 @@
+const GREEN = '\x1b[0;32m'
+const RED = '\x1b[0;31m'
+const YELLOW = '\x1b[0;33m'
+const WHITE = '\x1b[1;37m'
+const GREY = '\x1b[0;90m'
+const NC = '\x1b[0m'
+
+export function intro(title: string): void {
+  process.stderr.write(`${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}${title}${NC}\n`)
+}
+
+/**
+ * Timeline log levels matching `scripts/lib/ui.sh`, so a migrated command
+ * prints the same frame as the bash it replaced. All output is stderr,
+ * leaving stdout clean for JSON and lists.
+ */
+export function logInfo(message: string): void {
+  process.stderr.write(`${GREY}│${NC} ${GREEN}✓${NC} ${message}\n`)
+}
+
+export function logWarn(message: string): void {
+  process.stderr.write(`${GREY}│${NC} ${YELLOW}!${NC} ${message}\n`)
+}
+
+export function logAdd(message: string): void {
+  process.stderr.write(`${GREY}│${NC} ${GREEN}+${NC} ${message}\n`)
+}
+
+export function logRemove(message: string): void {
+  process.stderr.write(`${GREY}│${NC} ${RED}-${NC} ${message}\n`)
+}
+
+/**
+ * Renders the `✗` shape `docs/agents.md` specifies for a failure inside an
+ * open frame. It does not exit, so the caller closes the frame and returns an
+ * exit code rather than terminating mid-write.
+ */
+export function logError(message: string): void {
+  process.stderr.write(`${GREY}│${NC} ${RED}✗${NC} ${message}\n`)
+}
+
+export function logStep(message: string): void {
+  process.stderr.write(`${GREY}│${NC}\n${GREY}├${NC} ${WHITE}${message}${NC}\n`)
+}
+
+export function outro(): void {
+  process.stderr.write(`${GREY}└${NC}\n`)
+}
+
+/**
+ * Indents borrowed output inside an open frame, matching `pipe_output` in
+ * `scripts/lib/ui.sh`. Used for a document the command did not compose itself,
+ * such as a pull request body or the output of a git mutation.
+ */
+export function pipeOutput(text: string): void {
+  const lines = text.replace(/\n$/, '').split('\n')
+  process.stderr.write(
+    `${lines.map((line) => `${GREY}│${NC}  ${line}`).join('\n')}\n`,
+  )
+}
+
+export function frameError(message: string): void {
+  process.stderr.write(
+    `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${message}\n${GREY}└${NC}\n`,
+  )
+}
+
+export function frameSuccess(command: string, target: string): void {
+  process.stderr.write(
+    `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}${command}${NC}\n${GREY}│${NC}\n${GREY}│${NC} ${GREEN}✓${NC} ${target}\n${GREY}└${NC}\n`,
+  )
+}
+
+export function isNonInteractive(): boolean {
+  return process.env.AITK_NON_INTERACTIVE === '1'
+}
+
+/**
+ * `nonInteractiveDefault` opts a prompt into the `select_option` behavior from
+ * `scripts/lib/ui.sh`, where `AITK_NON_INTERACTIVE=1` resolves to the first
+ * option instead of failing. Callers that would rather fail loudly than pick
+ * for the user leave it off.
+ */
+export async function select<Value>(opts: {
+  message: string
+  options: { value: Value; label: string; hint?: string }[]
+  nonInteractiveDefault?: boolean
+}): Promise<Value> {
+  const { message, options } = opts
+  const count = options.length
+  let cursor = 0
+
+  if (opts.nonInteractiveDefault && isNonInteractive()) {
+    process.stderr.write(
+      `${GREY}│${NC}\n${GREY}◇${NC} ${message} ${WHITE}${options[0].label}${NC}\n`,
+    )
+    return options[0].value
+  }
+
+  const render = (): void => {
+    let out = `${GREY}│${NC}\n${GREEN}◆${NC} ${message}\n`
+    for (let i = 0; i < count; i++) {
+      const label = options[i].label
+      const hint = options[i].hint ? ` ${GREY}${options[i].hint}${NC}` : ''
+      if (i === cursor) {
+        out += `${GREY}│${NC}  ${GREEN}❯ ${label}${NC}${hint}\n`
+      } else {
+        out += `${GREY}│${NC}    ${GREY}${label}${NC}${hint}\n`
+      }
+    }
+    process.stderr.write(out)
+  }
+
+  const clear = (): void => {
+    process.stderr.write(`\x1b[${count + 2}A\x1b[J`)
+  }
+
+  return new Promise<Value>((resolve) => {
+    if (!process.stdin.isTTY) {
+      process.stderr.write(
+        `${GREY}│${NC} ${RED}✗${NC} ${message} requires a TTY. Pass an argument or set AITK_NON_INTERACTIVE=1.\n${GREY}└${NC}\n`,
+      )
+      process.exit(1)
+    }
+
+    const wasRaw = process.stdin.isRaw
+    process.stdin.setRawMode(true)
+    process.stdin.resume()
+
+    render()
+
+    const onData = (data: Buffer): void => {
+      const key = data.toString()
+
+      if (key === '\x1b[A' || key === 'k') {
+        cursor = (cursor - 1 + count) % count
+        clear()
+        render()
+      } else if (key === '\x1b[B' || key === 'j') {
+        cursor = (cursor + 1) % count
+        clear()
+        render()
+      } else if (key === '\r' || key === '\n') {
+        cleanup()
+        clear()
+        process.stderr.write(
+          `${GREY}│${NC}\n${GREY}◇${NC} ${message} ${WHITE}${options[cursor].label}${NC}\n`,
+        )
+        resolve(options[cursor].value)
+      } else if (key === '\x1b' || key === 'q' || key === '\x03') {
+        cleanup()
+        clear()
+        process.stderr.write(
+          `${GREY}│${NC}\n${GREY}◇${NC} ${message} ${RED}Cancelled${NC}\n${GREY}└${NC}\n`,
+        )
+        process.exit(1)
+      }
+    }
+
+    const cleanup = (): void => {
+      process.stdin.removeListener('data', onData)
+      process.stdin.setRawMode(wasRaw ?? false)
+      process.stdin.pause()
+    }
+
+    process.stdin.on('data', onData)
+  })
+}
+
+export async function confirm(opts: {
+  message: string
+  active?: string
+  inactive?: string
+}): Promise<boolean> {
+  const active = opts.active ?? 'Yes'
+  const inactive = opts.inactive ?? 'No'
+
+  const result = await select({
+    message: opts.message,
+    options: [
+      { value: true, label: active },
+      { value: false, label: inactive },
+    ],
+  })
+
+  return result
+}

package/src/wiki/init.ts

@@ -0,0 +1,85 @@
+import { existsSync, statSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const WIKI_DIR = join('.claude', 'wiki')
+const LEGACY_WIKI_DIR = 'wiki'
+const INDEX_FILE = 'index.md'
+
+export const WIKI_DIR_REL = `${WIKI_DIR}/`
+export const WIKI_INDEX_REL = join(WIKI_DIR, INDEX_FILE)
+export const LEGACY_WIKI_DIR_REL = `${LEGACY_WIKI_DIR}/`
+
+const INDEX_SEED = `---
+title: Wiki
+subtitle: Reference pages for tools, workflows, and concepts
+---
+
+# Wiki
+
+Reference pages for tools, workflows, and concepts.
+`
+
+export type WikiChange = 'dir' | 'index'
+
+export interface WikiPlan {
+  readonly changes: readonly WikiChange[]
+  readonly hasIndex: boolean
+  readonly hasLegacyWiki: boolean
+}
+
+export function wikiDir(target: string): string {
+  return join(target, WIKI_DIR)
+}
+
+/**
+ * A target scaffolded before the wiki moved under `.claude/` keeps its pages at
+ * the root. The verb reports that folder rather than moving it, because a move
+ * is a migration and the `migration-*` skills own those.
+ */
+export function legacyWikiDir(target: string): string {
+  return join(target, LEGACY_WIKI_DIR)
+}
+
+/**
+ * Stands in for the `cd "$target"` in the bash `guard_root`, which validated
+ * the target existed as a side effect. Without it a typo'd path scaffolds a
+ * whole new tree, since the apply step creates parents.
+ */
+export function isWikiTarget(target: string): boolean {
+  try {
+    return statSync(target).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Reports what a scaffold would create without writing. The directory and the
+ * index are tracked separately because a target can carry one without the
+ * other, and only the index has content worth preserving.
+ */
+export function planWikiInit(target: string): WikiPlan {
+  const dir = wikiDir(target)
+  const index = join(dir, INDEX_FILE)
+  const changes: WikiChange[] = []
+
+  if (!existsSync(dir)) changes.push('dir')
+
+  const hasIndex = existsSync(index)
+  if (!hasIndex) changes.push('index')
+
+  return { changes, hasIndex, hasLegacyWiki: existsSync(legacyWikiDir(target)) }
+}
+
+export async function applyWikiInit(
+  target: string,
+  plan: WikiPlan,
+): Promise<void> {
+  const dir = wikiDir(target)
+  await mkdir(dir, { recursive: true })
+
+  if (plan.changes.includes('index')) {
+    await writeFile(join(dir, INDEX_FILE), INDEX_SEED)
+  }
+}

package/standards/architecture.md

@@ -0,0 +1,41 @@
+---
+title: Architecture reference
+description: Shape and content rules for .claude/ARCHITECTURE.md
+---
+
+# Architecture reference
+
+Applies to `.claude/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: principles live there, patterns and decisions live here. Update when a decision is made or a risk is resolved.
+
+## What goes in
+
+- A high-level overview of how the system is structured and why
+- Key technical decisions as named H3 entries: what was chosen and why over the alternatives, including stack and library choices
+- Risks and open questions still unresolved
+
+## What does not go in
+
+- Per-domain structure and narrative. That belongs in `.claude/context/<domain>.md`, one file per domain.
+- Setup commands and install instructions. Those live in the README.
+- How individual functions work line by line. Those go in code comments.
+- Full type definitions. They live in code. Reference the shape conceptually if needed.
+
+## Sections
+
+Use `## Overview`, `## Key technical decisions` with one named H3 per decision, and `## Risks / open questions`. Name each decision and give the reasoning, especially for non-obvious choices. Skip entries where the rationale is self-evident.
+
+## Template
+
+```markdown
+# Architecture
+
+## Overview
+
+## Key technical decisions
+
+### Decision name
+
+Reasoning and tradeoffs.
+
+## Risks / open questions
+```

package/standards/bundled/branch.md

@@ -0,0 +1,49 @@
+---
+title: Branch reference
+description: Branch naming format and type conventions
+consumers: git-branch, git-split, git-pr, claude-standards-audit
+---
+
+# Branch reference
+
+## Format
+
+- Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
+- Length: 50 characters maximum
+- Casing: kebab-case only, no underscores or camelCase
+- Description: 2 words maximum, 3 only when genuinely needed for specificity
+- Capture the core change, not the commit message verbatim
+- For branches with multiple commits, use the unifying concern as the description.
+- Do not duplicate type in description (e.g., `feat/feature-login`)
+
+## Types
+
+- `feat`: new feature or capability
+- `fix`: bug fix
+- `refactor`: structural changes (not a fix or feature)
+- `docs`: documentation only (README)
+- `chore`: maintenance tasks (deps, tooling, configs)
+- `perf`: performance improvements
+- `test`: add or modify tests
+- `style`: code formatting (whitespace, semicolons)
+- `build`: build system changes (webpack, npm scripts)
+- `ci`: CI/CD pipeline changes (GitHub Actions)
+- `revert`: revert a previous commit
+
+## Examples
+
+### Correct
+
+```plaintext
+feat/jwt-expiration                    # clear feature scope
+fix/AUTH-123-connection-pool           # includes ticket ID
+refactor/remove-deprecated-endpoints   # clear refactor intent
+```
+
+### Incorrect
+
+```plaintext
+feature/auth_stuff                                        # wrong type + underscore
+feat/feature-add-login                                    # duplicates type in description
+fix/DB-456-fix-the-database-connection-pool-memory-leak   # exceeds 50 chars + verbatim message
+```

package/standards/bundled/commit.md

@@ -0,0 +1,63 @@
+---
+title: Commit reference
+description: Commit message format and type conventions
+consumers: git-commit, git-stage
+---
+
+# Commit message reference
+
+## Format
+
+- Structure: `<type>(<scope>): <subject>`
+- Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
+- Subject: 72 characters maximum, no trailing period
+
+## Types
+
+- `feat`: new feature or capability
+- `fix`: bug fix
+- `refactor`: structural changes (not a fix or feature)
+- `docs`: documentation only (README)
+- `chore`: maintenance tasks (deps, tooling, configs)
+- `perf`: performance improvements
+- `test`: add or modify tests
+- `style`: code formatting (whitespace, semicolons)
+- `build`: build system changes (webpack, npm scripts)
+- `ci`: CI/CD pipeline changes (GitHub Actions)
+- `revert`: revert a previous commit
+
+## Scope
+
+- Single lowercase word representing a system component
+- Prefer single word
+- Use kebab-case only when two words are genuinely needed for specificity
+- Do not use specific filenames as scopes
+- Do not use a scope that duplicates the type
+- Write scopes for release readability. They surface in `changelogithub` release notes.
+
+## Subject
+
+- Use imperative mood (`add` not `added`)
+- Describe the actual technical change, not that something changed
+- Do not use vague verbs (`improve`, `refine`, `enhance`)
+- Do not repeat the scope in the subject line
+- Use single quotes if quoting
+- No backslash escaping or internal double quotes
+- No conversational filler or introductory phrases
+
+## Examples
+
+### Correct
+
+```plaintext
+feat(api): add retry logic for failed webhooks       # specific verb + clear change
+fix(auth): update 'UserSession' validation logic     # scoped + imperative + single quotes
+```
+
+### Incorrect
+
+```plaintext
+fix(user-auth): Fixed the redirect loop.    # wrong casing + period + multi-word scope
+docs(docs): update the readme.              # duplicate scope + period
+docs(api): improve documentation            # vague verb + lacks specificity
+```

package/standards/bundled/issue.md

@@ -0,0 +1,84 @@
+---
+title: Issue reference
+description: GitHub issue title, labels, and body conventions
+consumers: git-issue
+---
+
+# Issue reference
+
+## Title
+
+- Format: `<type>: <subject>`
+- Type is `bug` or `task`. Lowercase the type and the first word of the subject.
+- Length: 72 characters maximum, no trailing period.
+
+## Labels
+
+- Apply `bug` for a defect and `enhancement` for a task or improvement.
+- Both are GitHub default labels. A label that does not exist makes `gh` reject the issue. Create it once with `gh label create`.
+- One label per issue unless a second genuinely applies.
+
+## Content
+
+- Use imperative mood and describe the actual defect or work, not that something is wrong.
+- Do not open with "This issue," "I want," or "We should."
+- Do not use buzzwords or speculative future scope.
+- State observable behavior for a bug, not a guessed cause.
+
+## Sections
+
+- `## Summary`: one line naming what and why.
+- `## Details`: for a bug, what happens versus what is expected. For a task, what to build.
+- `## Context`: for a bug, repro steps or commands. For a task, the driving reason, or `none`.
+- `## Proposed` (optional): one line naming a fix or approach. Omit when open.
+
+## Formatting
+
+- End every bullet with a period.
+- Keep each section to one or two lines.
+
+## Examples
+
+### Correct (bug)
+
+```markdown
+## Summary
+
+Fix the feedback CLI so it applies the `feedback` label.
+
+## Details
+
+`aitk feedback --github` opens an issue with no label, so `toolkit-triage` never lists it.
+
+## Context
+
+Run a piped `aitk feedback --github`, then check the issue carries no `feedback` label.
+
+## Proposed
+
+Pass `--label feedback` through the shared issue helper.
+```
+
+### Correct (task)
+
+```markdown
+## Summary
+
+Add a git-issue skill so a session can file an issue on the current repo.
+
+## Details
+
+Format an issue from session context and file it with `gh issue create`, next to git-pr in the git family.
+
+## Context
+
+The toolkit-issue skill only files on the toolkit repo. A general path is needed for target projects.
+```
+
+### Incorrect
+
+```markdown
+## Summary
+
+This issue is about the feedback system being kind of broken, and we should probably make it more robust.
+```