gitwrit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Terry Biddle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# gitwrit
+
+**Private, versioned writing for people who live in the terminal.**
+
+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.
+
+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.
+
+---
+
+## How it works
+
+gitwrit runs as a *background daemon*—but not the scary kind you have to exorcise. When you save a file, it waits a few seconds and then commits it locally. Every few minutes, it pushes everything to your remote. If your laptop sleeps, it catches up automatically when you wake it.
+
+The result feels like writing in Google Docs. Your work is always saved—except as *plain* Markdown without artifacts that sometimes pop up in text editors when you export to Markdown. The files also remain *yours*, *where you want them*, and fully *versioned*.
+
+---
+
+## Install
+
+**npm**
+```sh
+npm install -g gitwrit
+```
+
+**Yarn**
+```sh
+yarn global add gitwrit
+```
+
+---
+
+## Quick start
+
+```sh
+cd ~/notes
+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. 
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `gitwrit init` | Set up gitwrit in the current directory |
+| `gitwrit start` | Start watching your registered directories |
+| `gitwrit stop` | Stop the daemon gracefully |
+| `gitwrit restart` | Stop and restart (useful after config changes) |
+| `gitwrit status` | Show what gitwrit is watching and what it has done lately |
+| `gitwrit logs` | Tail the activity log |
+| `gitwrit config` | Edit global defaults or local directory overrides |
+| `gitwrit add [path]` | Add a directory to your watch list |
+| `gitwrit remove [path]` | Remove a directory from your watch list |
+| `gitwrit help` | List all available commands |
+
+---
+
+## Configuration
+
+gitwrit stores your global config at `~/.gitwritrc.json`. Run `gitwrit config` to edit it interactively.
+
+**Global defaults:**
+
+```json
+{
+  "fileTypes":    [".md", ".mdx"],
+  "debounce":     3000,
+  "pushInterval": 300000,
+  "branchMode":   "current",
+  "watch":        []
+}
+```
+
+**Per-directory overrides:**
+
+Run `gitwrit config` from inside a watched directory to set local overrides. Overrides are stored in `.gitwrit.json` in that directory. Anything not overridden falls through to your global defaults.
+
+---
+
+## Branch modes
+
+gitwrit supports two branch modes, configurable globally or per directory.
+
+**`current`** — Commits to whatever branch you currently have checked out. Switch branches freely; gitwrit follows you.
+
+**`autogenerated`** — Creates a fresh named branch at the start of each session. Branch names are generated by combining a random adjective, noun, and verb — like `crimson-walrus-stumbling` or `teal-fox-bouncing`. 64,000 possible combinations. Good for keeping autosave history separate from your main branch.
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+- Git
+- A configured Git remote (`git remote add origin <url>`) — gitwrit requires one before it will initialize a directory
+
+---
+
+## Why not Google Docs, Notion, or Obsidian Sync?
+
+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!
+
+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**.
+
+---
+
+## Open source
+
+gitwrit is open source and built to be extended. Contributions are welcome at every level—word lists, new file type support, commit message formatters, and more. See [CONTRIBUTING.md](CONTRIBUTING.md) and [EXTENSIONS.md](EXTENSIONS.md) to get started.
+
+---
+
+## License
+
+MIT

package/bin/gitwrit.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { init }    from '../src/commands/init.js';
+import { start }   from '../src/commands/start.js';
+import { stop }    from '../src/commands/stop.js';
+import { restart } from '../src/commands/restart.js';
+import { status }  from '../src/commands/status.js';
+import { config }  from '../src/commands/config.js';
+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';
+
+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
+  .helpOption(false);
+
+program.command('init')
+  .description('set up gitwrit in the current directory')
+  .action(init);
+
+program.command('start')
+  .description('start watching your registered directories')
+  .action(start);
+
+program.command('stop')
+  .description('stop the daemon gracefully')
+  .action(stop);
+
+program.command('restart')
+  .description('stop and restart the daemon')
+  .action(restart);
+
+program.command('status')
+  .description('show running state and recent activity')
+  .action(status);
+
+program.command('config')
+  .description('edit global defaults or local directory overrides')
+  .action(config);
+
+program.command('add [path]')
+  .description('add a directory to your watch list')
+  .action(add);
+
+program.command('remove [path]')
+  .description('remove a directory from your watch list')
+  .action(remove);
+
+program.command('logs')
+  .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')
+  .action(help);
+
+// ── hidden daemon command ─────────────────────────────────────────────────────
+// not shown in help — only called internally by `start`
+program.command('__daemon', { hidden: true })
+  .action(() => import('../src/daemon.js'));
+
+// ── fallback: no command given ────────────────────────────────────────────────
+if (process.argv.length <= 2) {
+  help();
+  process.exit(0);
+}
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "gitwrit",
+  "version": "0.1.0",
+  "description": "Private, versioned writing for people who live in the terminal.",
+  "type": "module",
+  "bin": {
+    "gitwrit": "bin/gitwrit.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node bin/gitwrit.js",
+    "test": "node --test test/integration.test.js"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^5.0.0",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.6.0",
+    "commander": "^12.1.0",
+    "simple-git": "^3.27.0"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,44 @@
+import { resolve } from 'path';
+import { cwd } from 'process';
+import { print } from '../ui.js';
+import { addWatchPath, globalConfigExists } from '../settings.js';
+import { isGitRepo, hasRemote } from '../git.js';
+
+export async function add(dirArg) {
+  const dir = resolve(dirArg || cwd());
+
+  if (!(await globalConfigExists())) {
+    print.gap();
+    print.bad('gitwrit is not set up yet.');
+    print.hint('Run gitwrit init first.');
+    print.gap();
+    return;
+  }
+
+  print.gap();
+
+  if (!(await isGitRepo(dir))) {
+    print.bad(`${dir} is not a Git repo.`);
+    print.hint('Run git init there first, then try again.');
+    print.gap();
+    return;
+  }
+
+  if (!(await hasRemote(dir))) {
+    print.bad('No Git remote configured.');
+    print.hint('Add a remote first:  git remote add origin <url>');
+    print.gap();
+    return;
+  }
+
+  const added = await addWatchPath({ type: 'directory', path: dir });
+
+  if (!added) {
+    print.warn(`${dir} is already in your watch list.`);
+  } else {
+    print.good(`${dir} added to your watch list.`);
+    print.hint('Run gitwrit restart to start watching it.');
+  }
+
+  print.gap();
+}

package/src/commands/config.js

@@ -0,0 +1,250 @@
+import { select, confirm, checkbox, input } from '@inquirer/prompts';
+import { resolve } from 'path';
+import { cwd } from 'process';
+
+import { print } from '../ui.js';
+import {
+  loadGlobalConfig,
+  saveGlobalConfig,
+  loadLocalConfig,
+  saveLocalConfig,
+  globalConfigExists,
+} from '../settings.js';
+
+// ─── field definitions ────────────────────────────────────────────────────────
+
+const FIELDS = [
+  { key: 'fileTypes',    label: 'File types'    },
+  { key: 'debounce',     label: 'Commit delay'  },
+  { key: 'pushInterval', label: 'Push interval' },
+  { key: 'branchMode',   label: 'Branch mode'   },
+];
+
+// ─── field editors ────────────────────────────────────────────────────────────
+
+async function editField(key, currentValue) {
+  if (key === 'fileTypes') {
+    return checkbox({
+      message: 'Which file types should gitwrit watch?',
+      choices: [
+        { name: '.md',  value: '.md',  checked: currentValue.includes('.md')  },
+        { name: '.mdx', value: '.mdx', checked: currentValue.includes('.mdx') },
+        { name: '.txt', value: '.txt', checked: currentValue.includes('.txt') },
+        { name: '.rst', value: '.rst', checked: currentValue.includes('.rst') },
+      ],
+    });
+  }
+
+  if (key === 'debounce') {
+    const choice = await select({
+      message: 'How long should gitwrit wait after a save before committing?',
+      choices: [
+        { name: '3 seconds  (recommended)', value: 3000  },
+        { name: '5 seconds',                value: 5000  },
+        { name: '10 seconds',               value: 10000 },
+        { name: 'Custom',                   value: 'custom' },
+      ],
+      default: currentValue,
+    });
+    if (choice === 'custom') {
+      const raw = await input({ message: 'Seconds to wait:' });
+      return parseFloat(raw) * 1000;
+    }
+    return choice;
+  }
+
+  if (key === 'pushInterval') {
+    const choice = await select({
+      message: 'How often should gitwrit push to remote?',
+      choices: [
+        { name: 'Every 5 minutes  (recommended)', value: 300000  },
+        { name: 'Every 10 minutes',               value: 600000  },
+        { name: 'Every 30 minutes',               value: 1800000 },
+        { name: 'Custom',                         value: 'custom' },
+      ],
+      default: currentValue,
+    });
+    if (choice === 'custom') {
+      const raw = await input({ message: 'Minutes between pushes:' });
+      return parseFloat(raw) * 60000;
+    }
+    return choice;
+  }
+
+  if (key === 'branchMode') {
+    return select({
+      message: 'Default branch mode?',
+      choices: [
+        { name: "Current branch   — commit to whatever branch you're on", value: 'current'       },
+        { name: 'Autogenerated    — create a fresh named branch each session',  value: 'autogenerated' },
+      ],
+      default: currentValue,
+    });
+  }
+}
+
+// ─── format a setting value for display ───────────────────────────────────────
+
+function formatValue(key, value) {
+  if (key === 'fileTypes')    return value.join(', ');
+  if (key === 'debounce')     return `${value / 1000}s after last save`;
+  if (key === 'pushInterval') return `Every ${value / 60000} min`;
+  if (key === 'branchMode')   return value;
+  return String(value);
+}
+
+// ─── global config flow ───────────────────────────────────────────────────────
+
+async function configureGlobal() {
+  print.divider('Global defaults');
+  print.gap();
+
+  const config = await loadGlobalConfig();
+
+  for (const { key, label } of FIELDS) {
+    print.row(label, formatValue(key, config[key]));
+  }
+
+  print.gap();
+
+  const field = await select({
+    message: 'Which setting would you like to change?',
+    choices: [
+      ...FIELDS.map(f => ({ name: f.label, value: f.key })),
+      { name: 'Done', value: null },
+    ],
+  });
+
+  if (!field) return;
+
+  const newValue = await editField(field, config[field]);
+  config[field] = newValue;
+  await saveGlobalConfig(config);
+
+  print.gap();
+  print.good('Global defaults updated.');
+  print.hint('Directories without local overrides will use these settings.');
+
+  print.gap();
+  const again = await confirm({ message: 'Change another setting?', default: false });
+  if (again) await configureGlobal();
+}
+
+// ─── local config flow ────────────────────────────────────────────────────────
+
+async function configureLocal(dir) {
+  print.divider(`${dir}  — local config`);
+  print.gap();
+
+  const global = await loadGlobalConfig();
+  const local  = await loadLocalConfig(dir) || {};
+  const hasOverrides = Object.keys(local).length > 0;
+
+  for (const { key, label } of FIELDS) {
+    const isOverridden = key in local;
+    const value = isOverridden ? local[key] : global[key];
+    const tag   = isOverridden ? 'local override ✎' : 'global';
+    print.row(label, formatValue(key, value), tag);
+  }
+
+  print.gap();
+
+  if (!hasOverrides) {
+    print.info('This directory is following all global defaults.');
+    print.gap();
+
+    const wantsOverride = await confirm({
+      message: 'Set a local override?',
+      default: false,
+    });
+    if (!wantsOverride) return;
+  }
+
+  const action = hasOverrides
+    ? await select({
+        message: 'What would you like to do?',
+        choices: [
+          { name: 'Edit an override',     value: 'edit'   },
+          { name: 'Remove an override',   value: 'remove' },
+          { name: 'Add another override', value: 'add'    },
+        ],
+      })
+    : 'add';
+
+  if (action === 'edit' || action === 'add') {
+    const overriddenKeys = Object.keys(local);
+    const choices = action === 'edit'
+      ? FIELDS.filter(f => overriddenKeys.includes(f.key))
+      : FIELDS.filter(f => !overriddenKeys.includes(f.key));
+
+    if (choices.length === 0) {
+      print.hint('Nothing to edit.');
+      return;
+    }
+
+    const field = await select({
+      message: 'Which setting?',
+      choices: choices.map(f => ({ name: f.label, value: f.key })),
+    });
+
+    const currentValue = local[field] ?? global[field];
+    const newValue = await editField(field, currentValue);
+    local[field] = newValue;
+    await saveLocalConfig(dir, local);
+    print.gap();
+    print.good('Local override saved.');
+  }
+
+  if (action === 'remove') {
+    const overriddenKeys = Object.keys(local);
+    const field = await select({
+      message: 'Which override would you like to remove?',
+      choices: FIELDS
+        .filter(f => overriddenKeys.includes(f.key))
+        .map(f => ({ name: f.label, value: f.key })),
+    });
+
+    delete local[field];
+    await saveLocalConfig(dir, local);
+    print.gap();
+    print.good(`Local override for "${field}" removed — reverting to global default.`);
+  }
+
+  print.gap();
+  const again = await confirm({ message: 'Make another change?', default: false });
+  if (again) await configureLocal(dir);
+}
+
+// ─── main ─────────────────────────────────────────────────────────────────────
+
+export async function config() {
+  if (!(await globalConfigExists())) {
+    print.gap();
+    print.bad('gitwrit is not set up yet.');
+    print.hint('Run gitwrit init first.');
+    print.gap();
+    return;
+  }
+
+  const dir = resolve(cwd());
+
+  print.gap();
+
+  const scope = await select({
+    message: 'What would you like to configure?',
+    choices: [
+      { name: 'Global defaults',          value: 'global' },
+      { name: `This directory  (${dir})`, value: 'local'  },
+    ],
+  });
+
+  print.gap();
+
+  if (scope === 'global') {
+    await configureGlobal();
+  } else {
+    await configureLocal(dir);
+  }
+
+  print.gap();
+}

package/src/commands/help.js

@@ -0,0 +1,53 @@
+import chalk from 'chalk';
+import { print } from '../ui.js';
+
+const commands = [
+  { name: 'init',    desc: 'Set up gitwrit in the current directory'                    },
+  { name: '',        desc: chalk.dim('(First run also configures your global defaults)') },
+  { name: 'start',   desc: 'Start watching your registered directories'                  },
+  { 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: 'logs',    desc: 'Tail the activity log'                                       },
+  { name: '',        desc: ''                                                             },
+  { name: 'config',  desc: 'Edit your global defaults or local directory overrides'      },
+  { name: 'add',     desc: 'Add a directory to your watch list'                          },
+  { name: 'remove',  desc: 'Remove a directory from your watch list'                     },
+  { name: '',        desc: ''                                                             },
+  { name: 'help',    desc: 'List all available commands'                                 },
+];
+
+const tips = [
+  'Run gitwrit init in any directory to register it.',
+  'Run gitwrit config from inside a watched directory to set local overrides.',
+  'gitwrit commits to whatever branch you\'re on — switch branches freely.',
+  'Branch mode "autogenerated" names your session branch automatically.',
+  'gitwrit requires a configured Git remote to push your work offsite.',
+];
+
+export function help() {
+  print.gap();
+  print.brand('gitwrit — Private, versioned writing for people who live in the terminal.');
+  print.gap();
+
+  console.log(chalk.dim('  commands'));
+  print.gap();
+
+  for (const { name, desc } of commands) {
+    const k = chalk.white(name.padEnd(12));
+    console.log(`    ${k}${desc}`);
+  }
+
+  print.gap();
+  console.log(chalk.dim('  tips'));
+  print.gap();
+
+  for (const tip of tips) {
+    print.hint(`· ${tip}`);
+  }
+
+  print.gap();
+  console.log(chalk.dim('  docs + source    github.com/TBiddy/gitwrit'));
+  print.gap();
+}