gitwrit 0.1.0 → 0.2.1

package/README.md

@@ -4,7 +4,7 @@
 
 Made for `git`-ters and `writ`-ters.
 
-**gitwrit**  watches your Markdown files and quietly commits and pushes them to your Git repository — no manual `git add`, no `git commit`, no `git push`. You write. gitwrit handles the rest.
+**gitwrit** watches your Markdown files and quietly commits and pushes them to your Git repository — no manual `git add`, no `git commit`, no `git push`. You write. gitwrit handles the rest.
 
 It is built for engineers writing internal specs, researchers building private knowledge bases, AI practitioners documenting models and experiments, and anyone who wants the safety of version control without the overhead of Git discipline. Your files stay in your own repository, on your own terms—not in someone else's cloud.
 
@@ -40,7 +40,7 @@ gitwrit init    # first run sets up global defaults + registers this directory
 gitwrit start   # start watching
 ```
 
-That's it. Write something, save it, and gitwrit commits it. 
+That's it. Write something, save it, and gitwrit commits it.
 
 ---
 
@@ -93,6 +93,18 @@ gitwrit supports two branch modes, configurable globally or per directory.
 
 ---
 
+## Updates
+
+gitwrit checks for updates automatically after every command. If a newer version is available, you will see a single note at the bottom of your output:
+
+```
+  · Update available: 0.2.1 → 0.3.0   Run npm install -g gitwrit to update.
+```
+
+The check runs in the background, caches for 24 hours, and fails silently if you are offline. It will never interrupt or slow down your workflow.
+
+---
+
 ## Requirements
 
 - Node.js ≥ 18
@@ -105,7 +117,7 @@ gitwrit supports two branch modes, configurable globally or per directory.
 
 Those tools store your files on their infrastructure. gitwrit does not. Your writing lives in a plain Git repository that you control, pushed wherever you want—GitHub, GitLab, a private server, anywhere that accepts a Git remote.
 
-Just to be clear, there's defnitely nothing wrong with using any of these tools. I use them!
+Just to be clear, there is absolutely nothing wrong with using any of these tools. I use them!
 
 But I thought making this might be especially useful for proprietary documentation like internal specs, research notes, model cards, experiment logs, etc. For when putting files into a third-party cloud is not an option, or when you want to keep everything essential to your codebase **all in one place**.
 
@@ -119,4 +131,4 @@ gitwrit is open source and built to be extended. Contributions are welcome at ev
 
 ## License
 
-MIT
+MIT

package/bin/gitwrit.js

@@ -11,59 +11,61 @@ import { add }     from '../src/commands/add.js';
 import { remove }  from '../src/commands/remove.js';
 import { logs }    from '../src/commands/logs.js';
 import { help }    from '../src/commands/help.js';
+import { checkForUpdate, currentVersion } from '../src/updater.js';
+import chalk from 'chalk';
+import { TEAL, PINK } from '../src/ui.js';
 
 const program = new Command();
 
 program
   .name('gitwrit')
-  .description('private, versioned writing for people who live in the terminal.')
-  .version('0.1.0')
-  .addHelpCommand(false)    // we handle help ourselves
+  .description('Private, versioned writing for people who live in the terminal.')
+  .version('0.2.1')
+  .addHelpCommand(false)
   .helpOption(false);
 
 program.command('init')
-  .description('set up gitwrit in the current directory')
+  .description('Set up gitwrit in the current directory')
   .action(init);
 
 program.command('start')
-  .description('start watching your registered directories')
+  .description('Start watching your registered directories')
   .action(start);
 
 program.command('stop')
-  .description('stop the daemon gracefully')
+  .description('Stop the daemon gracefully')
   .action(stop);
 
 program.command('restart')
-  .description('stop and restart the daemon')
+  .description('Stop and restart the daemon')
   .action(restart);
 
 program.command('status')
-  .description('show running state and recent activity')
+  .description('Show running state and recent activity')
   .action(status);
 
 program.command('config')
-  .description('edit global defaults or local directory overrides')
+  .description('Edit global defaults or local directory overrides')
   .action(config);
 
 program.command('add [path]')
-  .description('add a directory to your watch list')
+  .description('Add a directory to your watch list')
   .action(add);
 
 program.command('remove [path]')
-  .description('remove a directory from your watch list')
+  .description('Remove a directory from your watch list')
   .action(remove);
 
 program.command('logs')
-  .description('tail the activity log')
+  .description('Tail the activity log')
   .option('-n, --lines <number>', 'number of lines to show', '20')
   .action((opts) => logs(parseInt(opts.lines, 10)));
 
 program.command('help')
-  .description('show all commands')
+  .description('List all available commands')
   .action(help);
 
 // ── hidden daemon command ─────────────────────────────────────────────────────
-// not shown in help — only called internally by `start`
 program.command('__daemon', { hidden: true })
   .action(() => import('../src/daemon.js'));
 
@@ -73,4 +75,21 @@ if (process.argv.length <= 2) {
   process.exit(0);
 }
 
-program.parse(process.argv);
+// ── run command then check for updates ───────────────────────────────────────
+// update check runs after the command completes so it never delays the user.
+// shows a single hint line at the bottom if a newer version is available.
+program.parseAsync(process.argv).then(async () => {
+  const latest = await checkForUpdate();
+  if (latest) {
+    console.log(
+      '\n' +
+      chalk.dim('  · Update available: ') +
+      chalk.hex(TEAL)(currentVersion()) +
+      chalk.dim(' → ') +
+      chalk.hex(PINK).bold(latest) +
+      chalk.dim('   Run ') +
+      chalk.white('npm install -g gitwrit') +
+      chalk.dim(' to update.')
+    );
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitwrit",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Private, versioned writing for people who live in the terminal.",
   "type": "module",
   "bin": {
@@ -19,9 +19,13 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^5.0.0",
+    "boxen": "^7.1.1",
     "chalk": "^5.3.0",
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
+    "figlet": "^1.11.0",
+    "gradient-string": "^2.0.2",
+    "ora": "^8.2.0",
     "simple-git": "^3.27.0"
   }
 }

package/src/banner.js

@@ -0,0 +1,51 @@
+import figlet from 'figlet';
+import gradient from 'gradient-string';
+import chalk from 'chalk';
+
+// ─── palette ──────────────────────────────────────────────────────────────────
+
+const TEAL = '#2EC4B6';
+const PINK = '#F72585';
+
+const brandGradient = gradient(TEAL, PINK);
+
+// ─── banner ───────────────────────────────────────────────────────────────────
+
+// renders the full gitwrit banner:
+//   - BlurVision ASCII art in teal→pink gradient
+//   - tagline with git (teal) and writ (pink) colored separately
+//   - subtitle dimmed
+//
+// shown on:
+//   - gitwrit init  (first run only)
+//   - gitwrit help
+
+export function renderBanner() {
+  const ascii = figlet.textSync('gitwrit', {
+    font: 'BlurVision ASCII',
+    horizontalLayout: 'default',
+  });
+
+  // apply gradient line by line so the block characters catch
+  // the color transition at different densities (░ ▒ ▓)
+  const colored = brandGradient.multiline(ascii);
+
+  // tagline — git in teal, writ in pink, rest dimmed
+  const tagline =
+    chalk.dim('  Made for ') +
+    chalk.hex(TEAL).bold('`git`') +
+    chalk.dim('-ters and ') +
+    chalk.hex(PINK).bold('`writ`') +
+    chalk.dim('-ters.');
+
+  // subtitle
+  const subtitle = chalk.dim(
+    '  Private, versioned writing for people who live in the terminal.'
+  );
+
+  console.log();
+  console.log(colored);
+  console.log(subtitle);
+  console.log(tagline);
+  console.log();
+}

package/src/commands/help.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { print } from '../ui.js';
+import { print, TEAL, PINK } from '../ui.js';
+import { renderBanner } from '../banner.js';
 
 const commands = [
   { name: 'init',    desc: 'Set up gitwrit in the current directory'                    },
@@ -8,7 +9,7 @@ const commands = [
   { name: 'stop',    desc: 'Stop the daemon gracefully'                                  },
   { name: 'restart', desc: 'Stop and restart  (useful after config changes)'             },
   { name: '',        desc: ''                                                             },
-  { name: 'status',  desc: 'Show what gitwrit is watching and what it\'s done lately'   },
+  { name: 'status',  desc: 'Show what gitwrit is watching and what it\'s done lately'    },
   { name: 'logs',    desc: 'Tail the activity log'                                       },
   { name: '',        desc: ''                                                             },
   { name: 'config',  desc: 'Edit your global defaults or local directory overrides'      },
@@ -27,15 +28,13 @@ const tips = [
 ];
 
 export function help() {
-  print.gap();
-  print.brand('gitwrit — Private, versioned writing for people who live in the terminal.');
-  print.gap();
+  renderBanner();
 
   console.log(chalk.dim('  commands'));
   print.gap();
 
   for (const { name, desc } of commands) {
-    const k = chalk.white(name.padEnd(12));
+    const k = chalk.hex(TEAL)(name.padEnd(12));
     console.log(`    ${k}${desc}`);
   }
 
@@ -48,6 +47,9 @@ export function help() {
   }
 
   print.gap();
-  console.log(chalk.dim('  docs + source    github.com/TBiddy/gitwrit'));
+  console.log(
+    chalk.dim('  docs + source    ') +
+    chalk.hex(TEAL)('github.com/TBiddy/gitwrit')
+  );
   print.gap();
-}
+}

package/src/commands/init.js

@@ -2,8 +2,10 @@ import { checkbox, select, confirm, input } from '@inquirer/prompts';
 import { mkdir } from 'fs/promises';
 import { resolve } from 'path';
 import { cwd } from 'process';
+import ora from 'ora';
 
-import { print } from '../ui.js';
+import { print, TEAL, PINK } from '../ui.js';
+import { renderBanner } from '../banner.js';
 import {
   DEFAULTS,
   globalConfigExists,
@@ -23,7 +25,8 @@ export async function init() {
   // ── first-run: global setup ────────────────────────────────────────────────
 
   if (isFirstRun) {
-    print.brand("Welcome to gitwrit. Let's get you set up.");
+    renderBanner();
+    print.brand('Welcome to gitwrit. Let\'s get you set up.');
     print.gap();
     print.divider('Global defaults');
     print.hint('These apply to every directory you watch.');
@@ -77,7 +80,7 @@ export async function init() {
       message: 'Default branch mode?',
       choices: [
         {
-          name: "Current branch   — commit to whatever branch you're on",
+          name: 'Current branch   — commit to whatever branch you\'re on',
           value: 'current',
         },
         {
@@ -107,19 +110,23 @@ export async function init() {
   print.divider(`Registering ${dir}`);
   print.gap();
 
-  // hard gate: must be a git repo
+  // validate repo with spinner
+  const spinner = ora({
+    text: 'Checking repository...',
+    color: 'cyan',
+  }).start();
+
   const repoValid = await isGitRepo(dir);
   if (!repoValid) {
-    print.bad(`${dir} is not a Git repo.`);
+    spinner.fail('Not a Git repository.');
     print.hint('Run git init here first, then run gitwrit init again.');
     print.gap();
     process.exit(1);
   }
 
-  // hard gate: must have a remote
   const remoteValid = await hasRemote(dir);
   if (!remoteValid) {
-    print.bad('No Git remote configured.');
+    spinner.fail('No Git remote configured.');
     print.hint('gitwrit pushes your work to a remote repository to keep it safe.');
     print.hint('Add one first:  git remote add origin <url>');
     print.hint('Then run gitwrit init again.');
@@ -127,11 +134,10 @@ export async function init() {
     process.exit(1);
   }
 
-  print.good('Valid Git repo found.');
-  print.good('Remote origin configured.');
+  spinner.succeed('Valid Git repo with remote confirmed.');
   print.gap();
 
-  // local overrides — only ask if not first run (first run just inherits global)
+  // local overrides — only ask if not first run
   let useGlobalDefaults = true;
   if (!isFirstRun) {
     useGlobalDefaults = await confirm({
@@ -144,7 +150,6 @@ export async function init() {
     print.hint('Local overrides can be set anytime with gitwrit config.');
   }
 
-  // register the directory in global watch list
   const added = await addWatchPath({ type: 'directory', path: dir });
 
   print.gap();
@@ -167,6 +172,6 @@ export async function init() {
   print.row('Committing', `${config.debounce / 1000}s after last save`);
   print.row('Pushing',    `Every ${config.pushInterval / 60000} min`);
   print.gap();
-  print.hint("Run gitwrit start whenever you're ready.");
+  print.hint('Run gitwrit start whenever you\'re ready.');
   print.gap();
-}
+}

package/src/commands/start.js

@@ -2,6 +2,7 @@ import { spawn } from 'child_process';
 import { writeFile, mkdir, readFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import ora from 'ora';
 
 import { print } from '../ui.js';
 import { PID_FILE, GITWRIT_DIR } from '../paths.js';
@@ -77,6 +78,12 @@ export async function start() {
 
   await mkdir(GITWRIT_DIR, { recursive: true });
 
+  // spinner while daemon spins up
+  const spinner = ora({
+    text: 'Starting gitwrit...',
+    color: 'cyan',
+  }).start();
+
   const daemon = spawn(process.execPath, [DAEMON_SCRIPT], {
     detached: true,
     stdio: 'ignore',
@@ -87,18 +94,10 @@ export async function start() {
   });
 
   daemon.unref();
-
   await writeFile(PID_FILE, String(daemon.pid), 'utf8');
-
   await new Promise(r => setTimeout(r, 300));
 
-  print.gap();
-
-  if (wasUnclean) {
-    print.brand('gitwrit is running — picked up where you left off.');
-  } else {
-    print.brand('gitwrit is running.');
-  }
+  spinner.succeed(wasUnclean ? 'Picked up where you left off.' : 'gitwrit is running.');
 
   print.gap();
   print.row('Watching',    config.watch.map(w => w.path).join(', '));
@@ -115,4 +114,4 @@ export async function start() {
   print.gap();
   print.hint(randomStartMessage());
   print.gap();
-}
+}

package/src/notify.js

@@ -0,0 +1,34 @@
+import { exec } from 'child_process';
+import { platform } from 'os';
+
+// ─── native notification ───────────────────────────────────────────────────────
+//
+// fires a native OS notification with no npm dependencies.
+// macOS  → osascript
+// Linux  → notify-send (degrades silently if not installed)
+// other  → silent, no crash
+//
+// only called in two places:
+//   1. scheduler.js  — on push failure (always notify)
+//   2. nowhere else  — stop summary lives in the terminal output only
+
+export function notify(title, message) {
+  const os = platform();
+
+  // sanitize inputs — prevent shell injection via single-quote stripping
+  const safeTitle   = title.replace(/'/g, '');
+  const safeMessage = message.replace(/'/g, '');
+
+  if (os === 'darwin') {
+    exec(
+      `osascript -e 'display notification "${safeMessage}" with title "${safeTitle}"'`,
+      () => {} // ignore errors — notification is best-effort
+    );
+  } else if (os === 'linux') {
+    exec(
+      `notify-send "${safeTitle}" "${safeMessage}" 2>/dev/null`,
+      () => {}
+    );
+  }
+  // windows + anything else — silent
+}

package/src/scheduler.js

@@ -1,11 +1,10 @@
 import { push, getUnpushedCount } from './git.js';
 import { logger } from './logger.js';
 import { writeState, readState } from './state.js';
+import { notify } from './notify.js';
 
 // ─── scheduler ────────────────────────────────────────────────────────────────
 
-// maintains a set of repos that have unpushed commits and pushes them
-// on a fixed interval. safe to call multiple times — push is idempotent.
 export function createScheduler({ interval, onPushComplete }) {
   const pendingRepos = new Set();
 
@@ -21,13 +20,17 @@ export function createScheduler({ interval, onPushComplete }) {
         await push(dir);
         pendingRepos.delete(dir);
         await logger.push(`${dir}`);
-
-        const state = await readState();
         await writeState({ lastPushedAt: new Date().toISOString() });
 
         if (onPushComplete) onPushComplete(dir);
       } catch (err) {
         await logger.error(`push failed for ${dir}: ${err.message}`);
+
+        // native OS notification — only fires on failure
+        notify(
+          'gitwrit — Push failed',
+          'Your commits are safe locally. Check your network or remote config.'
+        );
       }
     }
   }
@@ -35,12 +38,8 @@ export function createScheduler({ interval, onPushComplete }) {
   const timer = setInterval(flush, interval);
 
   return {
-    // call this after every successful local commit
-    queue: (dir) => pendingRepos.add(dir),
-
-    // flush immediately (e.g. on wake from sleep)
-    flushNow: () => flush(),
-
-    stop: () => clearInterval(timer),
+    queue:    (dir) => pendingRepos.add(dir),
+    flushNow: ()    => flush(),
+    stop:     ()    => clearInterval(timer),
   };
 }

package/src/ui.js

@@ -1,26 +1,31 @@
 import chalk from 'chalk';
 
+// ─── palette ──────────────────────────────────────────────────────────────────
+
+export const TEAL = '#2EC4B6';
+export const PINK = '#F72585';
+
 // ─── sigil + brand ────────────────────────────────────────────────────────────
 
 export const SIGIL = '✦';
 
-export const brand  = (msg) => chalk.white(`\n  ${SIGIL} ${msg}`);
-export const info   = (msg) => chalk.white(`    ${msg}`);
-export const good   = (msg) => chalk.green(`  ✔  ${msg}`);
-export const bad    = (msg) => chalk.red(`  ✗  ${msg}`);
-export const warn   = (msg) => chalk.yellow(`  ⚠  ${msg}`);
-export const hint   = (msg) => chalk.dim(`    ${msg}`);
+export const brand   = (msg) => chalk.hex(TEAL)(`\n  ${SIGIL} ${msg}`);
+export const info    = (msg) => chalk.white(`    ${msg}`);
+export const good    = (msg) => chalk.hex(TEAL)(`  ✔  ${msg}`);
+export const bad     = (msg) => chalk.red(`  ✗  ${msg}`);
+export const warn    = (msg) => chalk.hex(PINK)(`  ⚠  ${msg}`);
+export const hint    = (msg) => chalk.dim(`    ${msg}`);
 export const divider = (label) =>
-  chalk.dim(`\n  ${'─'.repeat(41)}\n  ${label}\n  ${'─'.repeat(41)}`);
+  chalk.hex(TEAL).dim(`\n  ${'─'.repeat(41)}\n  `) +
+  chalk.hex(TEAL)(label) +
+  chalk.hex(TEAL).dim(`\n  ${'─'.repeat(41)}`);
 
 // ─── key/value rows ───────────────────────────────────────────────────────────
 
-// prints a two-column row like:
-//   watching    ~/notes
 export function row(key, value, tag) {
   const k = chalk.dim(key.padEnd(14));
   const v = chalk.white(value);
-  const t = tag ? chalk.dim(` (${tag})`) : '';
+  const t = tag ? chalk.hex(PINK).dim(` (${tag})`) : '';
   return `    ${k}${v}${t}`;
 }
 
@@ -47,8 +52,8 @@ export const print = {
 export function timeAgo(date) {
   if (!date) return 'never';
   const seconds = Math.floor((Date.now() - new Date(date)) / 1000);
-  if (seconds < 10)  return 'just now';
-  if (seconds < 60)  return `${seconds}s ago`;
+  if (seconds < 10)   return 'just now';
+  if (seconds < 60)   return `${seconds}s ago`;
   if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
   if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
   return `${Math.floor(seconds / 86400)}d ago`;
@@ -57,7 +62,7 @@ export function timeAgo(date) {
 // ─── ms formatting ────────────────────────────────────────────────────────────
 
 export function formatMs(ms) {
-  if (ms < 1000) return `${ms}ms`;
+  if (ms < 1000)  return `${ms}ms`;
   if (ms < 60000) return `${ms / 1000}s`;
   return `${ms / 60000} min`;
 }

package/src/updater.js

@@ -0,0 +1,88 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { GITWRIT_DIR } from './paths.js';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+// ─── current version ──────────────────────────────────────────────────────────
+
+const require = createRequire(import.meta.url);
+const PKG = require(join(dirname(fileURLToPath(import.meta.url)), '../package.json'));
+const CURRENT_VERSION = PKG.version;
+
+// ─── cache ────────────────────────────────────────────────────────────────────
+
+const CACHE_FILE = join(GITWRIT_DIR, 'update-check.json');
+const CACHE_TTL  = 1000 * 60 * 60 * 24; // 24 hours
+
+async function readCache() {
+  try {
+    const raw = await readFile(CACHE_FILE, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(data) {
+  try {
+    await mkdir(GITWRIT_DIR, { recursive: true });
+    await writeFile(CACHE_FILE, JSON.stringify(data), 'utf8');
+  } catch {
+    // cache write failure is non-fatal
+  }
+}
+
+// ─── registry fetch ───────────────────────────────────────────────────────────
+
+async function fetchLatestVersion() {
+  const res = await fetch('https://registry.npmjs.org/gitwrit/latest', {
+    signal: AbortSignal.timeout(3000), // 3s timeout — never block the user
+  });
+  if (!res.ok) throw new Error(`registry responded ${res.status}`);
+  const data = await res.json();
+  return data.version;
+}
+
+// ─── public api ───────────────────────────────────────────────────────────────
+
+// returns the latest version string if an update is available,
+// or null if up to date, offline, or the check fails for any reason.
+// always resolves — never rejects.
+export async function checkForUpdate() {
+  try {
+    const cache = await readCache();
+    const now   = Date.now();
+
+    // use cached result if fresh
+    if (cache && (now - cache.checkedAt) < CACHE_TTL) {
+      return isNewer(cache.latestVersion, CURRENT_VERSION)
+        ? cache.latestVersion
+        : null;
+    }
+
+    // fetch fresh
+    const latestVersion = await fetchLatestVersion();
+    await writeCache({ latestVersion, checkedAt: now });
+
+    return isNewer(latestVersion, CURRENT_VERSION) ? latestVersion : null;
+  } catch {
+    return null; // offline, registry down, anything — silent
+  }
+}
+
+export function currentVersion() {
+  return CURRENT_VERSION;
+}
+
+// ─── semver comparison ────────────────────────────────────────────────────────
+
+function isNewer(latest, current) {
+  const parse = v => v.replace(/^v/, '').split('.').map(Number);
+  const [lMaj, lMin, lPat] = parse(latest);
+  const [cMaj, cMin, cPat] = parse(current);
+  if (lMaj !== cMaj) return lMaj > cMaj;
+  if (lMin !== cMin) return lMin > cMin;
+  return lPat > cPat;
+}