@aladac/hu 0.1.0-a1

package/src/lib/fs.ts

@@ -0,0 +1,119 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const HOME = process.env.HOME || process.env.USERPROFILE || '';
+export const CLAUDE_DIR = path.join(HOME, '.claude');
+export const PLANS_DIR = path.join(CLAUDE_DIR, 'plans');
+export const GLOBAL_DOCS = path.join(CLAUDE_DIR, 'documents');
+
+export const SYSTEM_DOCS = [
+  'MODELS.md',
+  'PLAN.md',
+  'TODO.md',
+  'TEST.md',
+  'REFACTOR.md',
+  'README.md',
+  'CLAUDE.md',
+  'LICENSE.md',
+  'CHANGELOG.md',
+  'CONTRIBUTING.md',
+];
+
+/**
+ * Find the git repository root from current directory
+ */
+export function findRepoRoot(): string {
+  let dir = process.cwd();
+  while (dir !== '/') {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+/**
+ * Recursively find all markdown files in a directory
+ */
+export function findMarkdownFiles(dir: string, recursive = true): string[] {
+  const files: string[] = [];
+  if (!fs.existsSync(dir)) return files;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory() && recursive) {
+      files.push(...findMarkdownFiles(fullPath, recursive));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * Parse YAML frontmatter from markdown content
+ */
+export function parseFrontmatter(content: string): Record<string, string> {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const fm: Record<string, string> = {};
+  const lines = match[1].split('\n');
+  for (const line of lines) {
+    const [key, ...rest] = line.split(':');
+    if (key && rest.length) {
+      fm[key.trim()] = rest.join(':').trim();
+    }
+  }
+  return fm;
+}
+
+/**
+ * Count checkboxes in markdown content
+ */
+export function countCheckboxes(content: string): { pending: number; completed: number } {
+  const pending = (content.match(/- \[ \]/g) || []).length;
+  const completed = (content.match(/- \[x\]/gi) || []).length;
+  return { pending, completed };
+}
+
+/**
+ * Safe file read - returns null if file doesn't exist
+ */
+export function readFile(filePath: string): string | null {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Safe file write
+ */
+export function writeFile(filePath: string, content: string): boolean {
+  try {
+    fs.writeFileSync(filePath, content);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if path exists
+ */
+export function exists(filePath: string): boolean {
+  return fs.existsSync(filePath);
+}
+
+/**
+ * Get file stats or null
+ */
+export function getStats(filePath: string): fs.Stats | null {
+  try {
+    return fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+}

package/src/lib/html.ts

@@ -0,0 +1,205 @@
+import * as cheerio from 'cheerio';
+import TurndownService from 'turndown';
+
+// Content selectors to try (in order of preference)
+const CONTENT_SELECTORS = [
+  'article',
+  'main',
+  '[role="main"]',
+  '.main-content',
+  '.content',
+  '.post-content',
+  '.article-content',
+  '.documentation',
+  '.docs-content',
+  '.markdown-body',
+  '#content',
+  '#main',
+  '.prose',
+];
+
+// Elements to remove for cleaner output
+const REMOVE_SELECTORS = [
+  'script',
+  'style',
+  'noscript',
+  'iframe',
+  'svg',
+  'nav',
+  'header:not(article header)',
+  'footer:not(article footer)',
+  '.nav',
+  '.navigation',
+  '.sidebar',
+  '.menu',
+  '.toc',
+  '.table-of-contents',
+  '.breadcrumb',
+  '.breadcrumbs',
+  '.ads',
+  '.advertisement',
+  '.ad-container',
+  '.social-share',
+  '.share-buttons',
+  '.comments',
+  '.comment-section',
+  '[aria-hidden="true"]',
+  '.sr-only',
+  '.visually-hidden',
+  '.cookie-banner',
+  '.popup',
+  '.modal',
+];
+
+// Extra selectors to remove when clean mode is enabled
+const EXTRA_CLEAN_SELECTORS = [
+  'aside',
+  '.related',
+  '.related-posts',
+  '.author-bio',
+  '.newsletter',
+  '.subscribe',
+  '.cta',
+  '.banner',
+  '.promo',
+  '.feedback',
+  '.edit-page',
+  '.page-nav',
+  '.pagination',
+];
+
+export interface FetchOptions {
+  selector?: string;
+  includeTitle?: boolean;
+  clean?: boolean;
+  raw?: boolean;
+}
+
+/**
+ * Fetch a URL and convert HTML to markdown
+ */
+export async function fetchAndConvert(url: string, opts: FetchOptions = {}): Promise<string> {
+  const response = await fetch(url, {
+    headers: {
+      'User-Agent':
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+      'Accept-Language': 'en-US,en;q=0.5',
+    },
+    redirect: 'follow',
+  });
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+
+  const html = await response.text();
+  const $ = cheerio.load(html);
+
+  // Get page title
+  const pageTitle = $('title').text().trim() || $('h1').first().text().trim();
+
+  // Remove unwanted elements
+  const selectorsToRemove = opts.clean
+    ? [...REMOVE_SELECTORS, ...EXTRA_CLEAN_SELECTORS]
+    : REMOVE_SELECTORS;
+
+  for (const sel of selectorsToRemove) {
+    try {
+      $(sel).remove();
+    } catch {
+      // Ignore invalid selectors
+    }
+  }
+
+  // Find main content
+  // biome-ignore lint/suspicious/noExplicitAny: cheerio types are complex
+  let $content: cheerio.Cheerio<any>;
+  if (opts.selector) {
+    $content = $(opts.selector);
+    if ($content.length === 0) {
+      console.error(`Warning: Selector "${opts.selector}" not found, using body`);
+      $content = $('body');
+    }
+  } else {
+    // Try content selectors in order
+    $content = $('body'); // Default
+    for (const sel of CONTENT_SELECTORS) {
+      const $el = $(sel);
+      if ($el.length > 0 && $el.text().trim().length > 100) {
+        $content = $el;
+        break;
+      }
+    }
+  }
+
+  // Configure Turndown
+  const turndown = new TurndownService({
+    headingStyle: 'atx',
+    codeBlockStyle: 'fenced',
+    bulletListMarker: '-',
+    emDelimiter: '*',
+    strongDelimiter: '**',
+    linkStyle: 'inlined',
+  });
+
+  // Custom rules for better output
+  turndown.addRule('preserveCodeBlocks', {
+    filter: ['pre'],
+    replacement: (content: string, node) => {
+      const element = node as unknown as {
+        querySelector: (s: string) => { className?: string; textContent?: string } | null;
+        textContent?: string;
+      };
+      const code = element.querySelector('code');
+      const lang = code?.className?.match(/language-(\w+)/)?.[1] || '';
+      const text = code?.textContent || element.textContent || content;
+      return `\n\n\`\`\`${lang}\n${text.trim()}\n\`\`\`\n\n`;
+    },
+  });
+
+  turndown.addRule('removeEmptyLinks', {
+    filter: (node): boolean => {
+      return node.nodeName === 'A' && !node.textContent?.trim();
+    },
+    replacement: (): string => '',
+  });
+
+  // Convert to markdown
+  let markdown = turndown.turndown($content.html() || '');
+
+  // Post-processing (unless raw mode)
+  if (!opts.raw) {
+    markdown = postProcess(markdown);
+  }
+
+  // Add title if requested
+  if (opts.includeTitle && pageTitle) {
+    markdown = `# ${pageTitle}\n\n${markdown}`;
+  }
+
+  return markdown;
+}
+
+/**
+ * Post-process markdown for cleaner output
+ */
+function postProcess(md: string): string {
+  const cleaned = md
+    // Remove excessive blank lines
+    .replace(/\n{4,}/g, '\n\n\n')
+    // Remove trailing whitespace
+    .replace(/[ \t]+$/gm, '')
+    // Remove empty list items
+    .replace(/^[-*]\s*$/gm, '')
+    // Clean up code blocks
+    .replace(/```\n\n+/g, '```\n')
+    .replace(/\n\n+```/g, '\n```')
+    // Remove lone bullets
+    .replace(/^\s*[-*]\s*\n/gm, '')
+    // Normalize headers (ensure space after #)
+    .replace(/^(#{1,6})([^#\s])/gm, '$1 $2')
+    // Trim
+    .trim();
+  return `${cleaned}\n`;
+}

package/src/lib/spinner.ts

@@ -0,0 +1,42 @@
+import { c } from './colors.ts';
+
+const spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+let spinnerIndex = 0;
+let spinnerInterval: ReturnType<typeof setInterval> | null = null;
+let currentSpinnerText = '';
+
+/**
+ * Start an animated spinner with text
+ */
+export function startSpinner(text: string): void {
+  currentSpinnerText = text;
+  spinnerIndex = 0;
+  process.stdout.write('\x1b[?25l'); // Hide cursor
+  spinnerInterval = setInterval(() => {
+    const frame = spinnerFrames[spinnerIndex % spinnerFrames.length];
+    process.stdout.write(`\r${c.cyan}${frame}${c.reset} ${currentSpinnerText}`);
+    spinnerIndex++;
+  }, 80);
+}
+
+/**
+ * Stop the spinner and show final status
+ */
+export function stopSpinner(success = true, finalText: string | null = null): void {
+  if (spinnerInterval) {
+    clearInterval(spinnerInterval);
+    spinnerInterval = null;
+  }
+  const icon = success ? `${c.green}✓${c.reset}` : `${c.red}✗${c.reset}`;
+  const text = finalText || currentSpinnerText;
+  process.stdout.write(`\r${icon} ${text}\x1b[K\n`);
+  process.stdout.write('\x1b[?25h'); // Show cursor
+}
+
+/**
+ * Update spinner text without stopping
+ */
+export function updateSpinner(text: string): void {
+  currentSpinnerText = text;
+}

package/src/types/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Common type definitions for hu
+ */
+
+export interface DocInfo {
+  path: string;
+  name: string;
+  title: string;
+  size: number;
+  sizeHuman: string;
+  lines: number;
+  modified: string;
+  source: string | null;
+  fetched: string | null;
+}
+
+export interface PlanInfo {
+  filename: string;
+  path: string;
+  title: string;
+  bullets: string[];
+  phases: string[];
+  size: number;
+  modified: string;
+  resumeCmd: string;
+}
+
+export interface SystemDocInfo {
+  name: string;
+  found: boolean;
+  path: string | null;
+  size: number | null;
+  sizeHuman: string | null;
+  lines: number | null;
+  modified: string | null;
+  pending: number | null;
+  completed: number | null;
+}
+
+export interface CheckboxResult {
+  file: string;
+  exists: boolean;
+  changed: boolean;
+  delete?: boolean;
+  reason?: string;
+  before?: { pending: number; completed: number };
+  after?: { pending: number; completed: number };
+  removed?: number;
+  newContent?: string | null;
+}
+
+export interface SpaceHogCheck {
+  name: string;
+  cmd: string;
+}
+
+export interface CleanupSuggestion {
+  item: string;
+  size: string;
+  cmd: string;
+}

package/tests/lib/colors.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { formatSize, parseSize, progressBar } from '../../src/lib/colors.ts';
+
+describe('parseSize', () => {
+  it('parses bytes', () => {
+    expect(parseSize('100')).toBe(100);
+    // Note: 'B' is not recognized as a unit, only K/M/G/T/P
+  });
+
+  it('parses kilobytes', () => {
+    expect(parseSize('1K')).toBe(1024);
+    expect(parseSize('2.5K')).toBe(2560);
+  });
+
+  it('parses megabytes', () => {
+    expect(parseSize('1M')).toBe(1024 * 1024);
+    expect(parseSize('10M')).toBe(10 * 1024 * 1024);
+  });
+
+  it('parses gigabytes', () => {
+    expect(parseSize('1G')).toBe(1024 ** 3);
+    expect(parseSize('50G')).toBe(50 * 1024 ** 3);
+  });
+
+  it('handles invalid input', () => {
+    expect(parseSize('')).toBe(0);
+    expect(parseSize('abc')).toBe(0);
+  });
+});
+
+describe('formatSize', () => {
+  it('formats bytes', () => {
+    expect(formatSize(100)).toBe('100 B');
+    expect(formatSize(500)).toBe('500 B');
+  });
+
+  it('formats kilobytes', () => {
+    expect(formatSize(1024)).toBe('1.0 KB');
+    expect(formatSize(2048)).toBe('2.0 KB');
+  });
+
+  it('formats megabytes', () => {
+    expect(formatSize(1024 * 1024)).toBe('1.0 MB');
+    expect(formatSize(5 * 1024 * 1024)).toBe('5.0 MB');
+  });
+
+  it('formats gigabytes', () => {
+    expect(formatSize(1024 ** 3)).toBe('1.0 GB');
+    expect(formatSize(10 * 1024 ** 3)).toBe('10.0 GB');
+  });
+});
+
+describe('progressBar', () => {
+  it('creates green bar for low percentage', () => {
+    const bar = progressBar(30, 10);
+    expect(bar).toContain('███');
+    expect(bar).toContain('\x1b[32m'); // green
+  });
+
+  it('creates yellow bar for medium percentage', () => {
+    const bar = progressBar(70, 10);
+    expect(bar).toContain('\x1b[33m'); // yellow
+  });
+
+  it('creates red bar for high percentage', () => {
+    const bar = progressBar(90, 10);
+    expect(bar).toContain('\x1b[31m'); // red
+  });
+});

package/tests/lib/fs.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { countCheckboxes, parseFrontmatter } from '../../src/lib/fs.ts';
+
+describe('parseFrontmatter', () => {
+  it('parses valid frontmatter', () => {
+    const content = `---
+source: https://example.com
+fetched: 2024-01-01
+---
+
+# Title
+
+Content here`;
+
+    const result = parseFrontmatter(content);
+    expect(result.source).toBe('https://example.com');
+    expect(result.fetched).toBe('2024-01-01');
+  });
+
+  it('returns empty object for no frontmatter', () => {
+    const content = '# Just a title\n\nNo frontmatter here';
+    const result = parseFrontmatter(content);
+    expect(result).toEqual({});
+  });
+
+  it('handles frontmatter with colons in values', () => {
+    const content = `---
+source: https://example.com:8080/path
+---
+
+Content`;
+
+    const result = parseFrontmatter(content);
+    expect(result.source).toBe('https://example.com:8080/path');
+  });
+});
+
+describe('countCheckboxes', () => {
+  it('counts pending checkboxes', () => {
+    const content = `
+- [ ] Task 1
+- [ ] Task 2
+- [x] Done task
+`;
+    const result = countCheckboxes(content);
+    expect(result.pending).toBe(2);
+    expect(result.completed).toBe(1);
+  });
+
+  it('handles case-insensitive completed checkboxes', () => {
+    const content = `
+- [x] lowercase
+- [X] uppercase
+`;
+    const result = countCheckboxes(content);
+    expect(result.completed).toBe(2);
+  });
+
+  it('returns zeros for no checkboxes', () => {
+    const content = 'Just plain text';
+    const result = countCheckboxes(content);
+    expect(result.pending).toBe(0);
+    expect(result.completed).toBe(0);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "outDir": "./dist",
+    "types": ["node"],
+    "lib": ["ES2022"]
+  },
+  "include": ["src/**/*", "tests/**/*", "vitest.config.ts"],
+  "exclude": ["node_modules", "tools", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/index.ts'],
+    },
+  },
+});