foam-habits 1.0.0

package/dist/lib/__tests__/schemas.test.js

@@ -0,0 +1,49 @@
+import test from 'ava';
+import { parseGoal } from '../schemas.js';
+// parseGoal - basic cases
+test('parseGoal: parses integer with unit', t => {
+    const result = parseGoal('4L');
+    t.is(result.value, 4);
+    t.is(result.unit, 'L');
+});
+test('parseGoal: parses decimal with unit', t => {
+    const result = parseGoal('2.5km');
+    t.is(result.value, 2.5);
+    t.is(result.unit, 'km');
+});
+test('parseGoal: parses value with multi-char unit', t => {
+    const result = parseGoal('30min');
+    t.is(result.value, 30);
+    t.is(result.unit, 'min');
+});
+test('parseGoal: parses value with space before unit', t => {
+    const result = parseGoal('4 L');
+    t.is(result.value, 4);
+    t.is(result.unit, 'L');
+});
+test('parseGoal: parses value without unit', t => {
+    const result = parseGoal('10');
+    t.is(result.value, 10);
+    t.is(result.unit, undefined);
+});
+test('parseGoal: parses decimal without unit', t => {
+    const result = parseGoal('2.5');
+    t.is(result.value, 2.5);
+    t.is(result.unit, undefined);
+});
+// parseGoal - edge cases
+test('parseGoal: handles leading zeros', t => {
+    const result = parseGoal('08hours');
+    t.is(result.value, 8);
+    t.is(result.unit, 'hours');
+});
+test('parseGoal: throws on invalid format (no number)', t => {
+    t.throws(() => parseGoal('abc'), {
+        message: /Invalid goal format/,
+    });
+});
+test('parseGoal: throws on empty string', t => {
+    t.throws(() => parseGoal(''), {
+        message: /Invalid goal format/,
+    });
+});

package/dist/lib/__tests__/tracker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/__tests__/tracker.test.js

@@ -0,0 +1,54 @@
+import test from 'ava';
+import { getCompletionLevel } from '../tracker.js';
+// getCompletionLevel - boolean habits (no goal)
+test('getCompletionLevel: undefined value returns 0 (not done)', t => {
+    t.is(getCompletionLevel(undefined, undefined), 0);
+});
+test('getCompletionLevel: any value without goal returns 3 (complete)', t => {
+    t.is(getCompletionLevel(1, undefined), 3);
+    t.is(getCompletionLevel(0.5, undefined), 3);
+    t.is(getCompletionLevel(100, undefined), 3);
+});
+// getCompletionLevel - quantitative habits with default threshold (1.0)
+test('getCompletionLevel: meeting goal exactly returns 3', t => {
+    t.is(getCompletionLevel(4, 4), 3);
+});
+test('getCompletionLevel: exceeding goal returns 3', t => {
+    t.is(getCompletionLevel(5, 4), 3);
+});
+test('getCompletionLevel: 0 value with goal returns 0', t => {
+    t.is(getCompletionLevel(0, 4), 0);
+});
+test('getCompletionLevel: low progress returns 1 (red)', t => {
+    // With goal=4, threshold=1.0, partialThreshold = 0.625
+    // 1/4 = 0.25 < 0.625 -> level 1
+    t.is(getCompletionLevel(1, 4), 1);
+});
+test('getCompletionLevel: partial progress returns 2 (yellow)', t => {
+    // With goal=4, threshold=1.0, partialThreshold = 0.625
+    // 3/4 = 0.75 >= 0.625 but < 1.0 -> level 2
+    t.is(getCompletionLevel(3, 4), 2);
+});
+// getCompletionLevel - with custom threshold
+test('getCompletionLevel: custom threshold 0.8 - 80% is complete', t => {
+    // 3.2/4 = 0.8 >= threshold 0.8 -> complete
+    t.is(getCompletionLevel(3.2, 4, 0.8), 3);
+});
+test('getCompletionLevel: custom threshold 0.8 - 79% is partial', t => {
+    // 3.1/4 = 0.775 < threshold 0.8 but >= partialThreshold (0.8 * 0.625 = 0.5)
+    t.is(getCompletionLevel(3.1, 4, 0.8), 2);
+});
+test('getCompletionLevel: custom threshold 0.5 - 50% is complete', t => {
+    t.is(getCompletionLevel(2, 4, 0.5), 3);
+});
+test('getCompletionLevel: custom threshold 0.5 - 25% is low', t => {
+    // 1/4 = 0.25 < partialThreshold (0.5 * 0.625 = 0.3125) -> level 1
+    t.is(getCompletionLevel(1, 4, 0.5), 1);
+});
+// Edge cases
+test('getCompletionLevel: very small value is low (not zero)', t => {
+    t.is(getCompletionLevel(0.001, 4), 1);
+});
+test('getCompletionLevel: undefined value with goal returns 0', t => {
+    t.is(getCompletionLevel(undefined, 4), 0);
+});

package/dist/lib/config.d.ts

@@ -0,0 +1,16 @@
+import { type Config } from './schemas.js';
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Find the .foam/habits.yaml config file by searching up from cwd
+ */
+export declare function findConfigPath(startDir?: string): string | undefined;
+/**
+ * Load and validate the habits.yaml config file
+ */
+export declare function loadConfig(configPath?: string): Config;
+/**
+ * Get the root directory (where .foam/ is located)
+ */
+export declare function getRootDir(configPath?: string): string;

package/dist/lib/config.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { ConfigSchema } from './schemas.js';
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+/**
+ * Find the .foam/habits.yaml config file by searching up from cwd
+ */
+export function findConfigPath(startDir = process.cwd()) {
+    let currentDir = startDir;
+    while (currentDir !== path.dirname(currentDir)) {
+        const configPath = path.join(currentDir, '.foam', 'habits.yaml');
+        if (fs.existsSync(configPath)) {
+            return configPath;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return undefined;
+}
+/**
+ * Load and validate the habits.yaml config file
+ */
+export function loadConfig(configPath) {
+    const resolvedPath = configPath ?? findConfigPath();
+    if (!resolvedPath) {
+        throw new ConfigError('Could not find .foam/habits.yaml\n\n' +
+            'Create a config file at .foam/habits.yaml with your habits:\n\n' +
+            '  habits:\n' +
+            '    gym:\n' +
+            '      emoji: "🏋️"\n' +
+            '    water:\n' +
+            '      emoji: "💧"\n' +
+            '      goal: 3\n' +
+            '      unit: "L"\n');
+    }
+    if (!fs.existsSync(resolvedPath)) {
+        throw new ConfigError(`Config file not found: ${resolvedPath}`);
+    }
+    const raw = fs.readFileSync(resolvedPath, 'utf8');
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (error) {
+        throw new ConfigError(`Invalid YAML in ${resolvedPath}:\n${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = ConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const errors = result.error.issues
+            .map(issue => `  - ${issue.path.join('.')}: ${issue.message}`)
+            .join('\n');
+        throw new ConfigError(`Invalid habits.yaml:\n${errors}`);
+    }
+    return result.data;
+}
+/**
+ * Get the root directory (where .foam/ is located)
+ */
+export function getRootDir(configPath) {
+    const resolvedPath = configPath ?? findConfigPath();
+    if (!resolvedPath) {
+        return process.cwd();
+    }
+    // .foam/habits.yaml -> go up two levels
+    return path.dirname(path.dirname(resolvedPath));
+}

package/dist/lib/palette.d.ts

@@ -0,0 +1,7 @@
+export declare const PALETTE: {
+    readonly title: "#9EA5FF";
+    readonly red: "#FC8897";
+    readonly yellow: "#C0B435";
+    readonly green: "#6BC87B";
+    readonly dimmed: "#717380";
+};

package/dist/lib/palette.js

@@ -0,0 +1,8 @@
+export const PALETTE = {
+    title: '#9EA5FF',
+    red: '#FC8897',
+    yellow: '#C0B435',
+    green: '#6BC87B',
+    // Dimmed text with a slight tint matching the title hue
+    dimmed: '#717380',
+};

package/dist/lib/parser.d.ts

@@ -0,0 +1,34 @@
+import { type Config, type HabitEntry } from './schemas.js';
+export type ParseResult = {
+    entries: HabitEntry[];
+    warnings: string[];
+};
+/**
+ * Parse the journal folder from daily-note template content
+ * Exported for testing
+ */
+export declare function parseFolderFromTemplate(content: string): string | undefined;
+/**
+ * Extract the journal folder from Foam's daily-note template
+ * Reads .foam/templates/daily-note.md and parses the filepath from frontmatter
+ */
+export declare function inferJournalFolder(rootDir: string): string;
+/**
+ * Find all journal markdown files
+ */
+export declare function findJournalFiles(rootDir: string): string[];
+/**
+ * Extract the ## Habits section from a markdown file
+ */
+export declare function extractHabitsSection(content: string): string | undefined;
+/**
+ * Parse habit entries from the ## Habits section
+ */
+export declare function parseHabitEntries(habitsSection: string, date: string, config: Config, filePath: string): {
+    entries: HabitEntry[];
+    warnings: string[];
+};
+/**
+ * Parse all journal files and extract habit entries
+ */
+export declare function parseJournals(rootDir: string, config: Config): ParseResult;

package/dist/lib/parser.js

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+// Regex to extract date from filename (YYYY-MM-DD.md)
+const DATE_REGEX = /^(\d{4}-\d{2}-\d{2})\.md$/;
+// Regex to extract value from habit entry (e.g., "Water: 2.5L" -> 2.5)
+const VALUE_REGEX = /:\s*([\d.]+)/;
+// Default folder if template doesn't exist or can't be parsed
+const DEFAULT_JOURNAL_FOLDER = 'journal';
+/**
+ * Parse the journal folder from daily-note template content
+ * Exported for testing
+ */
+export function parseFolderFromTemplate(content) {
+    // Extract YAML frontmatter (between --- markers)
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch?.[1]) {
+        return undefined;
+    }
+    // Extract filepath from frontmatter (e.g., filepath: "/journal/${FOAM_DATE}...")
+    const filepathMatch = frontmatterMatch[1].match(/filepath:\s*["']?([^"'\n]+)["']?/);
+    if (!filepathMatch?.[1]) {
+        return undefined;
+    }
+    const filepath = filepathMatch[1].trim();
+    // Extract folder from filepath (everything before the filename pattern)
+    // Handle both "/journal/..." and "journal/..." formats
+    const normalizedPath = filepath.startsWith('/') ? filepath.slice(1) : filepath;
+    // Find the folder part (before the first ${...} or the last /)
+    const folderMatch = normalizedPath.match(/^([^$]+)\//);
+    if (folderMatch?.[1]) {
+        return folderMatch[1];
+    }
+    return undefined;
+}
+/**
+ * Extract the journal folder from Foam's daily-note template
+ * Reads .foam/templates/daily-note.md and parses the filepath from frontmatter
+ */
+export function inferJournalFolder(rootDir) {
+    const templatePath = path.join(rootDir, '.foam', 'templates', 'daily-note.md');
+    try {
+        if (!fs.existsSync(templatePath)) {
+            return DEFAULT_JOURNAL_FOLDER;
+        }
+        const content = fs.readFileSync(templatePath, 'utf8');
+        return parseFolderFromTemplate(content) ?? DEFAULT_JOURNAL_FOLDER;
+    }
+    catch {
+        return DEFAULT_JOURNAL_FOLDER;
+    }
+}
+/**
+ * Find all journal markdown files
+ */
+export function findJournalFiles(rootDir) {
+    const journalFolder = inferJournalFolder(rootDir);
+    const journalDir = path.join(rootDir, journalFolder);
+    if (!fs.existsSync(journalDir)) {
+        return [];
+    }
+    const files = fs.readdirSync(journalDir);
+    return files
+        .filter(file => DATE_REGEX.test(file))
+        .map(file => path.join(journalDir, file))
+        .sort();
+}
+/**
+ * Extract the ## Habits section from a markdown file
+ */
+export function extractHabitsSection(content) {
+    const lines = content.split('\n');
+    let inHabitsSection = false;
+    const habitsLines = [];
+    for (const line of lines) {
+        // Check for ## Habits header (case-insensitive)
+        if (/^##\s+habits?\s*$/i.test(line)) {
+            inHabitsSection = true;
+            continue;
+        }
+        // Stop at next section header
+        if (inHabitsSection && /^##\s+/.test(line)) {
+            break;
+        }
+        if (inHabitsSection) {
+            habitsLines.push(line);
+        }
+    }
+    return habitsLines.length > 0 ? habitsLines.join('\n') : undefined;
+}
+/**
+ * Parse habit entries from the ## Habits section
+ */
+export function parseHabitEntries(habitsSection, date, config, filePath) {
+    const entries = [];
+    const warnings = [];
+    const configHabitNames = new Set(Object.keys(config.habits).map(h => h.toLowerCase()));
+    const lines = habitsSection.split('\n');
+    for (const line of lines) {
+        // Match lines starting with "- " (list items)
+        const match = line.match(/^[-*]\s+(.+)$/);
+        if (!match?.[1])
+            continue;
+        const rawEntry = match[1].trim();
+        if (!rawEntry) {
+            warnings.push(`⚠ Malformed entry in ${path.basename(filePath)}: "${line}"`);
+            continue;
+        }
+        // Extract habit name (everything before ":" or the whole string)
+        const colonIndex = rawEntry.indexOf(':');
+        const habitName = colonIndex > 0 ? rawEntry.slice(0, colonIndex).trim() : rawEntry;
+        const habitNameLower = habitName.toLowerCase();
+        // Check if habit is in config
+        if (!configHabitNames.has(habitNameLower)) {
+            warnings.push(`⚠ Unknown habit "${habitName}" in ${path.basename(filePath)}`);
+            continue;
+        }
+        // Extract optional value
+        const valueMatch = rawEntry.match(VALUE_REGEX);
+        const value = valueMatch?.[1] ? parseFloat(valueMatch[1]) : undefined;
+        entries.push({
+            name: habitNameLower,
+            value: value ?? 1, // Default to 1 for boolean habits
+            date,
+        });
+    }
+    return { entries, warnings };
+}
+/**
+ * Parse a single journal file
+ */
+function parseJournalFile(filePath, config) {
+    const filename = path.basename(filePath);
+    const dateMatch = filename.match(DATE_REGEX);
+    if (!dateMatch?.[1]) {
+        return { entries: [], warnings: [`⚠ Invalid filename: ${filename}`] };
+    }
+    const date = dateMatch[1];
+    const content = fs.readFileSync(filePath, 'utf8');
+    const habitsSection = extractHabitsSection(content);
+    if (!habitsSection) {
+        return { entries: [], warnings: [] };
+    }
+    return parseHabitEntries(habitsSection, date, config, filePath);
+}
+/**
+ * Parse all journal files and extract habit entries
+ */
+export function parseJournals(rootDir, config) {
+    const journalFolder = inferJournalFolder(rootDir);
+    const files = findJournalFiles(rootDir);
+    const allEntries = [];
+    const allWarnings = [];
+    if (files.length === 0) {
+        allWarnings.push(`⚠ No journal files found in ${journalFolder}/`);
+    }
+    for (const file of files) {
+        const { entries, warnings } = parseJournalFile(file, config);
+        allEntries.push(...entries);
+        allWarnings.push(...warnings);
+    }
+    return {
+        entries: allEntries,
+        warnings: allWarnings,
+    };
+}

package/dist/lib/schemas.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+/**
+ * Parse a goal string like "4L", "30min", "2.5km" into value and unit
+ */
+export declare function parseGoal(goalStr: string): {
+    value: number;
+    unit: string | undefined;
+};
+export declare const HabitConfigSchema: z.ZodObject<{
+    emoji: z.ZodString;
+    goal: z.ZodOptional<z.ZodString>;
+    threshold: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const ConfigSchema: z.ZodObject<{
+    habits: z.ZodRecord<z.ZodString, z.ZodObject<{
+        emoji: z.ZodString;
+        goal: z.ZodOptional<z.ZodString>;
+        threshold: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const HabitEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodOptional<z.ZodNumber>;
+    date: z.ZodString;
+}, z.core.$strip>;
+export declare const HabitDataSchema: z.ZodObject<{
+    name: z.ZodString;
+    emoji: z.ZodString;
+    goal: z.ZodOptional<z.ZodNumber>;
+    unit: z.ZodOptional<z.ZodString>;
+    threshold: z.ZodDefault<z.ZodNumber>;
+    entries: z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodNumber>>;
+    streak: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ViewArgsSchema: z.ZodObject<{
+    weeks: z.ZodDefault<z.ZodNumber>;
+    currentMonth: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type HabitConfig = z.infer<typeof HabitConfigSchema>;
+export type Config = z.infer<typeof ConfigSchema>;
+export type HabitEntry = z.infer<typeof HabitEntrySchema>;
+export type HabitData = z.infer<typeof HabitDataSchema>;
+export type ViewArgs = z.infer<typeof ViewArgsSchema>;

package/dist/lib/schemas.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+/**
+ * Parse a goal string like "4L", "30min", "2.5km" into value and unit
+ */
+export function parseGoal(goalStr) {
+    const match = goalStr.match(/^([\d.]+)\s*(.*)$/);
+    if (!match?.[1]) {
+        throw new Error(`Invalid goal format: "${goalStr}". Expected format like "4L", "30min", "2.5km"`);
+    }
+    const value = parseFloat(match[1]);
+    const unit = match[2]?.trim() || undefined;
+    return { value, unit };
+}
+// Single habit definition in config (.foam/habits.yaml)
+export const HabitConfigSchema = z.object({
+    emoji: z.string().min(1),
+    // Goal with unit, e.g., "4L", "30min", "2.5km" (optional for boolean habits)
+    goal: z.string().optional(),
+    // Threshold percentage to consider habit "done" (0.0 - 1.0, default 1.0 = 100%)
+    threshold: z.number().min(0).max(1).default(1.0),
+});
+// Full habits.yaml config
+export const ConfigSchema = z.object({
+    habits: z.record(z.string(), HabitConfigSchema),
+});
+// Parsed habit entry from a daily note
+export const HabitEntrySchema = z.object({
+    name: z.string().min(1),
+    value: z.number().positive().optional(),
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+});
+// Aggregated habit data for display
+export const HabitDataSchema = z.object({
+    name: z.string(),
+    emoji: z.string(),
+    goal: z.number().optional(),
+    unit: z.string().optional(),
+    threshold: z.number().default(1.0),
+    // date (YYYY-MM-DD) -> value (undefined = not done, number = value or 1 for boolean)
+    entries: z.record(z.string(), z.number().optional()),
+    streak: z.number().int().nonnegative(),
+});
+// CLI args for view command
+export const ViewArgsSchema = z.object({
+    weeks: z.number().int().positive().default(4),
+    currentMonth: z.boolean().default(false),
+});

package/dist/lib/string-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Strip variation selectors (U+FE0E, U+FE0F) from emojis for consistent rendering
+ */
+export declare function stripVariationSelectors(str: string): string;
+/**
+ * Pad a string to a target visual width, accounting for emoji/unicode widths
+ */
+export declare function padEndVisual(str: string, targetWidth: number): string;
+/**
+ * Truncate a string to a max visual width, adding "…" if truncated
+ */
+export declare function truncateVisual(str: string, maxWidth: number): string;
+/**
+ * Get the visual width of a string
+ */
+export declare function getVisualWidth(str: string): number;

package/dist/lib/string-utils.js

@@ -0,0 +1,43 @@
+import stringWidth from 'string-width';
+/**
+ * Strip variation selectors (U+FE0E, U+FE0F) from emojis for consistent rendering
+ */
+export function stripVariationSelectors(str) {
+    // eslint-disable-next-line no-control-regex
+    return str.replace(/[\uFE0E\uFE0F]/g, '');
+}
+/**
+ * Pad a string to a target visual width, accounting for emoji/unicode widths
+ */
+export function padEndVisual(str, targetWidth) {
+    const currentWidth = stringWidth(str);
+    const padding = Math.max(0, targetWidth - currentWidth);
+    return str + ' '.repeat(padding);
+}
+/**
+ * Truncate a string to a max visual width, adding "…" if truncated
+ */
+export function truncateVisual(str, maxWidth) {
+    const currentWidth = stringWidth(str);
+    if (currentWidth <= maxWidth) {
+        return padEndVisual(str, maxWidth);
+    }
+    // Need to truncate - find where to cut
+    let truncated = '';
+    let width = 0;
+    for (const char of str) {
+        const charWidth = stringWidth(char);
+        if (width + charWidth > maxWidth - 1) {
+            break;
+        }
+        truncated += char;
+        width += charWidth;
+    }
+    return padEndVisual(truncated + '…', maxWidth);
+}
+/**
+ * Get the visual width of a string
+ */
+export function getVisualWidth(str) {
+    return stringWidth(str);
+}

package/dist/lib/tracker.d.ts

@@ -0,0 +1,14 @@
+import { type Config, type HabitEntry, type HabitData, type ViewArgs } from './schemas.js';
+/**
+ * Generate date range based on view args
+ */
+export declare function getDateRange(args: ViewArgs): string[];
+/**
+ * Aggregate habit entries into HabitData for rendering
+ */
+export declare function aggregateHabits(entries: HabitEntry[], config: Config, dateRange: string[]): HabitData[];
+/**
+ * Get completion level for a single cell (0-3)
+ * 0 = not done (░), 1 = low (▒), 2 = partial (▓), 3 = complete (█)
+ */
+export declare function getCompletionLevel(value: number | undefined, goal: number | undefined, threshold?: number): 0 | 1 | 2 | 3;