cron-human 1.0.2 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Akin Ibitoye
+Copyright (c) 2026 Akin 
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -104,4 +104,57 @@ cron-human "*/15 * * * *" --json --quiet
 
 ## License
 
-MIT
+MIT © Akin Ibitoye
+
+## Interactive Mode (TUI)
+
+Launch the interactive Terminal UI with:
+
+```bash
+cron-human tui
+# or
+cron-human --interactive
+```
+
+![Cron Human TUI Screenshot](tui-screenshot.png)
+
+### Key Features
+- **Live Preview**: Real-time validation and English translation as you type.
+- **History**: Auto-saves successful cron expressions. Navigate history with `Up/Down` and reload with `Enter`.
+- **Clipboard Integration**: Paste (`Ctrl+V`) directly into the editor. Copy (`c`) saved expressions from history.
+- **Toggle Options**: Quickly enable/disable seconds support (`Space`).
+
+### Keybindings
+
+| Key | Action |
+|---|---|
+| `Tab` | Cycle focus (Input → Options → History) |
+| `Ctrl+V` | Paste from clipboard |
+| `Ctrl+R` | Reset/Clear input |
+| `Ctrl+C` / `Q` | Quit |
+
+**History Panel:**
+| Key | Action |
+|---|---|
+| `Up` / `Down` | Navigate history |
+| `Enter` | Load selected expression |
+| `c` | Copy selected expression |
+
+**Options Panel:**
+| Key | Action |
+|---|---|
+| `Space` | Toggle checkbox |
+
+## Manual Test Cases
+
+1. **Basic Minute**: `* * * * *` -> "Every minute"
+2. **Specific Time**: `30 14 * * *` -> "At 14:30"
+3. **Interval**: `*/5 * * * *` -> "Every 5 minutes"
+4. **Range**: `0 9-17 * * 1-5` -> "At 0 minutes past the hour, between 09:00 and 17:59, Monday through Friday"
+5. **Macro**: `@daily` -> "At 00:00"
+6. **With Seconds**: `*/30 * * * * *` (Enable "Allow Seconds") -> "Every 30 seconds"
+7. **Invalid**: `* * * 99 *` -> "Error: Invalid cron expression..."
+8. **Timezone**: Set TZ to `UTC` -> Verify next runs match UTC.
+9. **History**: Enter a valid cron -> Press Up -> should see it.
+10. **Help**: Press `Tab` until Focus is History, then `Tab` again -> Focus Input.
+11. **Clipboard**: Press `Ctrl+V` to paste a cron string. Select history item and press `c` to copy.

package/dist/cli.js

@@ -1,22 +1,31 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { createRequire } from 'module';
 import { DateTime } from 'luxon';
 import { explainCron, getNextRuns, validateCron } from './lib.js';
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
+import { handleErr } from "./utils/error.js";
+import pkg from "../package.json" with { type: "json" };
 const program = new Command();
 program
     .name('cron-human')
     .description('Converts cron expressions to human-readable English and prints next run times.')
     .version(pkg.version, '-v, --version')
-    .argument('<expression>', 'Cron expression to parse')
+    .argument('[expression]', 'Cron expression to parse')
     .option('-n, --next <number>', 'how many upcoming run times to print', '5')
     .option('--tz <timezone>', 'timezone for output (default: system timezone)')
     .option('--json', 'output machine-readable JSON', false)
     .option('-q, --quiet', 'only print the one-line human explanation (no next runs)', false)
     .option('--seconds', 'support 6-field cron expressions with seconds', false)
-    .action((expression, options) => {
+    .option('-i, --interactive', 'launch interactive TUI mode')
+    .action(async (expression, options) => {
+    if (options.interactive) {
+        const { startTui } = await import('./ui/launcher.js');
+        await startTui();
+        return;
+    }
+    if (!expression) {
+        program.help();
+        return;
+    }
     if (options.tz) {
         const test = DateTime.now().setZone(options.tz);
         if (!test.isValid) {
@@ -47,7 +56,8 @@ program
             description = explainCron(expression);
         }
         catch (e) {
-            console.error(`Error: Could not generate description. ${e?.message ?? e}`);
+            const err = handleErr(e);
+            console.error(`Error: Could not generate description. ${err.message}`);
             process.exit(1);
         }
         const output = {
@@ -68,9 +78,17 @@ program
             }
         }
     }
-    catch (err) {
-        console.error(`Error: ${err.message}`);
+    catch (e) {
+        const err = handleErr(e);
+        console.error(err);
         process.exit(1);
     }
 });
+// Add explicit command as well
+program.command('tui')
+    .description('Launch the interactive TUI')
+    .action(async () => {
+    const { startTui } = await import('./ui/launcher.js');
+    await startTui();
+});
 program.parse();

package/dist/lib.js

@@ -2,23 +2,22 @@ import cronstrue from 'cronstrue';
 import { DateTime } from 'luxon';
 import { CronExpressionParser } from 'cron-parser';
 const MACROS = {
-    "@yearly": "0 0 0 1 1 *",
-    "@annually": "0 0 0 1 1 *",
-    "@monthly": "0 0 0 1 * *",
-    "@weekly": "0 0 0 * * 0",
-    "@daily": "0 0 0 * * *",
-    "@hourly": "0 0 * * * *",
-    "@minutely": "0 * * * * *",
+    "@yearly": "0 0 1 1 *",
+    "@annually": "0 0 1 1 *",
+    "@monthly": "0 0 1 * *",
+    "@weekly": "0 0 * * 0",
+    "@daily": "0 0 * * *",
+    "@hourly": "0 * * * *",
+    "@minutely": "* * * * *",
     "@secondly": "* * * * * *",
-    "@weekdays": "0 0 0 * * 1-5",
-    "@weekends": "0 0 0 * * 0,6",
+    "@weekdays": "0 0 * * 1-5",
+    "@weekends": "0 0 * * 0,6",
 };
 function normalizeForParse(expr) {
     const t = expr.trim();
     if (!t.startsWith("@"))
         return t;
     const key = t.toLowerCase();
-    // for parsing, use expanded cron if known, otherwise keep original (will error)
     return MACROS[key] ?? t;
 }
 function fieldCount(expr) {
@@ -51,15 +50,9 @@ export function validateCron(expression, options = {}) {
     }
     const normalized = normalizeForParse(expression);
     if (expression.trim().startsWith("@")) {
-        try {
-            const parseOpts = {};
-            if (options.timezone)
-                parseOpts.tz = options.timezone;
-            CronExpressionParser.parse(normalized, parseOpts);
-            return null;
-        }
-        catch (err) {
-            return `Invalid cron expression: ${err.message}`;
+        const macro = expression.trim().toLowerCase();
+        if (macro === '@secondly' && !options.allowSeconds) {
+            return 'Error: @secondly requires --seconds flag.';
         }
     }
     const fields = fieldCount(normalized);

package/dist/ui/app.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare const App: React.FC;

package/dist/ui/app.js

@@ -0,0 +1,105 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from 'react';
+import { Box, Text, useInput, useApp } from 'ink';
+import { InputSection } from './components/InputSection.js';
+import { PreviewSection } from './components/PreviewSection.js';
+import { OptionsPanel } from './components/OptionsPanel.js';
+import { HistoryPanel } from './components/HistoryPanel.js';
+import clipboardy from 'clipboardy';
+var FocusArea;
+(function (FocusArea) {
+    FocusArea[FocusArea["Input"] = 0] = "Input";
+    FocusArea[FocusArea["Options"] = 1] = "Options";
+    FocusArea[FocusArea["History"] = 2] = "History";
+})(FocusArea || (FocusArea = {}));
+export const App = () => {
+    const { exit } = useApp();
+    const [expression, setExpression] = useState('');
+    const [timezone, setTimezone] = useState(undefined);
+    const [allowSeconds, setAllowSeconds] = useState(false);
+    const [focus, setFocus] = useState(FocusArea.Input);
+    const [history, setHistory] = useState([]);
+    const [historyIndex, setHistoryIndex] = useState(0);
+    const [showHelp, setShowHelp] = useState(false);
+    const [notification, setNotification] = useState(null);
+    useEffect(() => {
+        if (notification) {
+            const timer = setTimeout(() => setNotification(null), 2000);
+            return () => clearTimeout(timer);
+        }
+    }, [notification]);
+    useInput((input, key) => {
+        if (key.ctrl && input === 'c') {
+            exit();
+            return;
+        }
+        if (input === 'q' && !key.ctrl && focus !== FocusArea.Input) {
+            exit();
+            return;
+        }
+        if (key.tab) {
+            setFocus((prev) => {
+                if (prev === FocusArea.Input)
+                    return FocusArea.Options;
+                if (prev === FocusArea.Options)
+                    return FocusArea.History;
+                return FocusArea.Input;
+            });
+        }
+        if (key.ctrl && input === 'r') {
+            setExpression('');
+            setFocus(FocusArea.Input);
+        }
+        if (input === '?') {
+        }
+        if (key.ctrl && input === 'v') {
+            if (focus === FocusArea.Input) {
+                clipboardy.read().then(text => {
+                    if (text) {
+                        setExpression(text.trim());
+                        setNotification('Pasted from clipboard!');
+                    }
+                }).catch(err => {
+                    setNotification(`Paste failed: ${err.message}`);
+                });
+            }
+        }
+        if (focus === FocusArea.Options) {
+            if (input === ' ') {
+                setAllowSeconds(prev => !prev);
+            }
+        }
+        if (focus === FocusArea.History) {
+            if (key.upArrow) {
+                setHistoryIndex(prev => Math.max(0, prev - 1));
+            }
+            if (key.downArrow) {
+                setHistoryIndex(prev => Math.min(history.length - 1, prev + 1));
+            }
+            if (key.return) {
+                if (history[historyIndex]) {
+                    setExpression(history[historyIndex].expression);
+                    setFocus(FocusArea.Input);
+                }
+            }
+            if (input === 'c') {
+                if (history[historyIndex]) {
+                    clipboardy.write(history[historyIndex].expression).then(() => {
+                        setNotification('Copied to clipboard!');
+                    }).catch((err) => {
+                        setNotification(`Copy failed: ${err.message}`);
+                    });
+                }
+            }
+        }
+    });
+    const handleInputSubmit = (val) => {
+        if (val.trim()) {
+            const last = history[0];
+            if (!last || last.expression !== val) {
+                setHistory(prev => [{ expression: val, timestamp: new Date() }, ...prev].slice(0, 50));
+            }
+        }
+    };
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, width: "100%", height: "100%", children: [_jsxs(Box, { marginBottom: 1, justifyContent: "space-between", children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "magenta", children: "Cron Human TUI" }), _jsx(Text, { children: " | " }), _jsx(Text, { dimColor: true, children: "Ctrl+C to Quit" })] }), notification && _jsx(Text, { color: "yellow", bold: true, children: notification })] }), _jsx(InputSection, { value: expression, onChange: setExpression, onSubmit: handleInputSubmit, isFocused: focus === FocusArea.Input }), _jsx(Box, { marginY: 1, children: _jsx(OptionsPanel, { isFocused: focus === FocusArea.Options, timezone: timezone || "Local", allowSeconds: allowSeconds, onToggleSeconds: () => setAllowSeconds(!allowSeconds), onChangeTimezone: setTimezone }) }), _jsx(PreviewSection, { expression: expression, timezone: timezone, allowSeconds: allowSeconds }), _jsxs(Box, { marginTop: 1, children: [_jsx(HistoryPanel, { isFocused: focus === FocusArea.History, items: history.slice(0, 5), selectedIndex: historyIndex }), history.length > 5 && _jsxs(Text, { dimColor: true, children: ["... ", history.length - 5, " more"] })] })] }));
+};

package/dist/ui/components/HelpScreen.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare const HelpScreen: React.FC;

package/dist/ui/components/HelpScreen.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+export const HelpScreen = () => {
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "white", padding: 1, children: [_jsx(Text, { bold: true, underline: true, children: "Help & Keybindings" }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { bold: true, children: "Tab" }), _jsxs(Text, { children: [": Cycle focus (Input -", '>', " Options -", '>', " History)"] })] }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Enter" }), _jsx(Text, { children: ": Run conversion / Save to history" })] }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Up/Down" }), _jsx(Text, { children: ": Navigate history" })] }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "c" }), _jsx(Text, { children: ": Copy selected history item" })] }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Ctrl+V" }), _jsx(Text, { children: ": Paste from clipboard" })] }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Ctrl+R" }), _jsx(Text, { children: ": Reset input" })] }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Ctrl+C / Q" }), _jsx(Text, { children: ": Quit" })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { bold: true, underline: true, children: "Examples:" }) }), _jsx(Box, { children: _jsx(Text, { children: "* * * * *       (Every minute)" }) }), _jsx(Box, { children: _jsx(Text, { children: "0 12 * * 1-5    (At 12:00 on weekdays)" }) }), _jsx(Box, { children: _jsx(Text, { children: "@daily          (Run once a day at midnight)" }) })] }));
+};

package/dist/ui/components/HistoryPanel.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+interface HistoryItem {
+    expression: string;
+    timestamp: Date;
+}
+interface HistoryPanelProps {
+    isFocused: boolean;
+    items: HistoryItem[];
+    selectedIndex: number;
+}
+export declare const HistoryPanel: React.FC<HistoryPanelProps>;
+export {};

package/dist/ui/components/HistoryPanel.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+export const HistoryPanel = ({ isFocused, items, selectedIndex }) => {
+    if (items.length === 0) {
+        return (_jsxs(Box, { borderStyle: "round", borderColor: isFocused ? "green" : "gray", paddingX: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "History:" }), _jsx(Text, { dimColor: true, children: "No history yet. Press Enter to save successful runs." })] }));
+    }
+    return (_jsxs(Box, { borderStyle: "round", borderColor: isFocused ? "green" : "gray", paddingX: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "History (Up/Down to navigate, Enter to load, 'c' to copy):" }), items.map((item, index) => (_jsx(Box, { children: _jsxs(Text, { color: index === selectedIndex ? "cyan" : "white", children: [index === selectedIndex ? "> " : "  ", item.expression] }) }, index)))] }));
+};

package/dist/ui/components/InputSection.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+interface InputSectionProps {
+    value: string;
+    onChange: (value: string) => void;
+    onSubmit: (value: string) => void;
+    isFocused: boolean;
+}
+export declare const InputSection: React.FC<InputSectionProps>;
+export {};

package/dist/ui/components/InputSection.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import TextInput from 'ink-text-input';
+export const InputSection = ({ value, onChange, onSubmit, isFocused }) => {
+    return (_jsxs(Box, { borderStyle: "round", borderColor: isFocused ? "green" : "gray", paddingX: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, color: isFocused ? "green" : "white", children: "Cron Expression:" }), _jsx(Box, { children: _jsx(TextInput, { value: value, onChange: onChange, onSubmit: onSubmit, focus: isFocused, placeholder: "* * * * *" }) })] }));
+};

package/dist/ui/components/OptionsPanel.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+interface OptionsPanelProps {
+    isFocused: boolean;
+    timezone: string;
+    allowSeconds: boolean;
+    onToggleSeconds: () => void;
+    onChangeTimezone: (tz: string) => void;
+}
+export declare const OptionsPanel: React.FC<OptionsPanelProps>;
+export {};

package/dist/ui/components/OptionsPanel.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+export const OptionsPanel = ({ isFocused, timezone, allowSeconds, onToggleSeconds, onChangeTimezone }) => {
+    return (_jsxs(Box, { borderStyle: "round", borderColor: isFocused ? "green" : "gray", paddingX: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Options (Press Tab to focus, then Space to toggle):" }), _jsxs(Box, { children: [_jsxs(Text, { color: isFocused ? "cyan" : "white", children: ["[ ", allowSeconds ? 'X' : ' ', " ] Allow Seconds"] }), _jsx(Box, { marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["Timezone: ", timezone || 'Local', " (Ctrl+T to set)"] }) })] })] }));
+};

package/dist/ui/components/PreviewSection.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+interface PreviewSectionProps {
+    expression: string;
+    timezone?: string;
+    allowSeconds?: boolean;
+}
+export declare const PreviewSection: React.FC<PreviewSectionProps>;
+export {};

package/dist/ui/components/PreviewSection.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { validateCron, explainCron, getNextRuns } from '../../lib.js';
+export const PreviewSection = ({ expression, timezone, allowSeconds }) => {
+    const validationError = validateCron(expression, { timezone, allowSeconds });
+    let content;
+    let nextRuns = [];
+    let isError = false;
+    if (validationError) {
+        content = validationError;
+        isError = true;
+    }
+    else {
+        try {
+            content = explainCron(expression);
+            nextRuns = getNextRuns(expression, 3, timezone);
+        }
+        catch (e) {
+            content = e.message;
+            isError = true;
+        }
+    }
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: isError ? "red" : "blue", paddingX: 1, flexGrow: 1, children: [_jsx(Text, { bold: true, color: "white", children: "Human Readable:" }), _jsx(Text, { color: isError ? "red" : "green", children: content }), !isError && nextRuns.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "Next runs:" }), nextRuns.map((run, i) => (_jsxs(Text, { dimColor: true, children: ["  - ", run] }, i)))] }))] }));
+};

package/dist/ui/launcher.d.ts

@@ -0,0 +1 @@
+export declare function startTui(): Promise<void>;

package/dist/ui/launcher.js

@@ -0,0 +1,7 @@
+import React from 'react';
+import { render } from 'ink';
+import { App } from './app.js';
+export function startTui() {
+    const { waitUntilExit } = render(React.createElement(App));
+    return waitUntilExit();
+}

package/dist/utils/error.d.ts

@@ -0,0 +1,5 @@
+declare class CliError extends Error {
+    constructor(msg: string);
+}
+declare function handleErr(err: unknown): CliError;
+export { CliError, handleErr };

package/dist/utils/error.js

@@ -0,0 +1,17 @@
+class CliError extends Error {
+    constructor(msg) {
+        super(msg);
+    }
+}
+function handleErr(err) {
+    if (err instanceof Error) {
+        return new CliError(err.message);
+    }
+    else if (typeof err === "string") {
+        return new CliError(err);
+    }
+    else {
+        return new CliError("unknown error");
+    }
+}
+export { CliError, handleErr };

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "cron-human",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "A CLI that converts cron expressions to human-readable English and prints next run times",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
+  "type": "module",
   "bin": {
     "cron-human": "dist/cli.js"
   },
-  "type": "module",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "start": "node dist/cli.js",
+    "start": "node dist/cli.js '*/5 * * * *'",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -38,21 +38,35 @@
     "LICENSE"
   ],
   "dependencies": {
+    "clipboardy": "^5.1.0",
     "commander": "^14.0.2",
     "cron-parser": "^5.5.0",
     "cronstrue": "^3.9.0",
-    "luxon": "^3.7.2"
+    "ink": "^6.6.0",
+    "ink-select-input": "^6.2.0",
+    "ink-text-input": "^6.0.0",
+    "luxon": "^3.7.2",
+    "react": "^19.2.4"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/ink-select-input": "^3.0.5",
+    "@types/ink-text-input": "^2.0.5",
     "@types/luxon": "^3.7.1",
     "@types/node": "^25.0.10",
+    "@types/react": "^19.2.10",
     "@typescript-eslint/eslint-plugin": "^8.53.1",
     "@typescript-eslint/parser": "^8.53.1",
+    "chalk": "^5.6.2",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
+    "ink-testing-library": "^4.0.0",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
+  },
+  "overrides": {
+    "es-toolkit": "1.42.0"
   }
 }