gp-cron 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 git-puller contributors
+
+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,198 @@
+# git-puller
+
+Автоматическое обновление Git-проектов: команда `gp`, терминальная панель,
+фоновый процесс и команды после обновления. Без внешних npm-зависимостей.
+
+Node.js 20+ и Git. Основная платформа — macOS/Linux. Windows пока не поддерживается:
+остановка деревьев процессов и отключение Git hooks используют POSIX-механизмы.
+
+## Установка
+
+Из исходников, находясь в папке проекта:
+
+```sh
+npm install -g .
+gp --help
+```
+
+Для запуска без глобальной установки: `node bin/gp.js`.
+
+## Быстрый старт
+
+```sh
+cd ~/Projects/my-app
+gp add
+gp
+```
+
+`gp add` открывает мастер настройки. На первом шаге текущая папка предложена
+по умолчанию — нажмите Enter. Затем укажите название, интервал, команды после
+обновления, таймаут и подтвердите доверие. Путь можно передать явно:
+`gp add ~/Projects/my-app`.
+
+Папка должна быть корнем Git-репозитория; текущая ветка должна иметь upstream.
+При необходимости настройте его самостоятельно:
+
+```sh
+git branch --set-upstream-to=origin/main main
+```
+
+Добавленный проект сразу начинает обновляться. `--no-start` регистрирует его
+остановленным. Для серверов и скриптов есть явная настройка без вопросов:
+
+```sh
+gp add /srv/my-app --name my-app --interval 5m --trust \
+  --allow-commands --command 'npm ci' --command 'npm run build' \
+  --command 'pm2 reload my-app' --timeout 10m
+```
+
+Каждая команда выполняется отдельно, по порядку, в папке проекта через системный
+shell. Можно передавать `npm ci && npm run build` одной командой. Пустой список
+команд означает только обновление Git. При редактировании список вводится заново.
+Таймаут применяется к каждой команде; Git-операции имеют отдельный таймаут 120 секунд.
+Интервалы и таймауты: от `10s` до `168h`.
+
+## Терминальная панель
+
+`gp` открывает панель с автоматическим обновлением статусов, веткой, интервалом,
+временем последней проверки и обновления, следующей проверкой и причиной паузы.
+
+| Клавиша | Действие |
+| --- | --- |
+| ↑ / ↓ или k / j | Выбрать проект |
+| a | Добавить проект |
+| Space | Запустить / остановить расписание |
+| p | Проверить и обновить сейчас |
+| e | Изменить настройки |
+| l | Посмотреть последние логи |
+| r | Повторить команды после ошибки |
+| d | Удалить из реестра |
+| q / Ctrl+C | Закрыть панель; фоновые обновления продолжаются |
+
+Без интерактивного терминала `gp` выводит таблицу статусов. `NO_COLOR=1` отключает
+цвета в обычном CLI. Панель использует ANSI-терминал.
+
+## Команды
+
+```sh
+gp list                     # Также: status, ls
+gp scan ~/Projects          # Найти репозитории до четырёх уровней вложенности
+gp start my-app             # Включить расписание / возобновить после паузы
+gp stop my-app              # Остановить расписание, дать текущей задаче завершиться
+gp start all
+gp stop all
+gp pull my-app              # Разовая проверка, даже для остановленного проекта
+gp edit my-app
+gp info my-app              # JSON: настройки и состояние
+gp logs my-app --lines 50
+gp logs my-app --follow
+gp retry my-app             # Повторить весь список команд с начала
+gp accept my-app            # Подтвердить ручное решение; снять pending-команды
+gp remove my-app            # Файлы проекта и логи сохраняются
+gp daemon start
+gp daemon stop
+```
+
+Проект выбирается по имени, ID, уникальному префиксу ID или пути. `remove` и
+`accept` запрашивают подтверждение; в скриптах используйте `--yes`.
+`scan` только обнаруживает папки; доверие и регистрация выполняются через `add`.
+
+## Что происходит при обновлении
+
+1. Проверяется доверие, реальный путь, текущая ветка и upstream.
+2. Незавершённый merge/rebase и локальные изменения, включая untracked-файлы,
+   приостанавливают проект. Игнорируемые Git файлы не считаются изменениями.
+3. Выполняется `git fetch --prune`; состояние проверяется повторно.
+4. Выполняется `git merge --ff-only @{upstream}` — безопасный эквивалент
+   fast-forward pull. Никаких автоматических merge-коммитов, reset, stash или force.
+5. Если HEAD изменился, последовательно выполняются настроенные команды.
+6. Следующая проверка назначается через заданный интервал после завершения задачи.
+
+Расхождение истории, проблемы сети/авторизации и ошибки команд ставят проект
+на паузу с записью причины в статус и лог. Автоматических повторов ошибок нет.
+При локальных коммитах, когда upstream является предком HEAD, Git оставляет их
+без изменений. Репозитории с submodules не обновляют содержимое submodules
+автоматически: добавьте нужную команду самостоятельно.
+
+### Конфликты и локальные изменения
+
+При конфликте проект приостанавливается, локальные изменения сохраняются.
+Выполните commit/stash, закончите
+незавершённую операцию или вручную решите расхождение веток, затем:
+
+```sh
+gp start my-app
+```
+
+Если вы намеренно сменили ветку/upstream, подтвердите новую настройку через
+`gp edit my-app`. Сначала дождитесь завершения активного обновления.
+
+### Ошибка команды после обновления
+
+Git-обновление сохраняется; автоматического отката базы данных, файлов или внешних
+сервисов нет. Сохраняется pending-ревизия, новые обновления блокируются.
+
+```sh
+gp logs my-app
+gp edit my-app               # При необходимости исправить команды
+gp retry my-app              # Повторить все команды, включая уже успешные
+gp start my-app
+```
+
+Команды стоит делать идемпотентными. Если решаете проблему вручную, используйте
+`gp accept my-app`. Retry требует чистой рабочей папки и той же ревизии HEAD.
+Pending-состояние записывается до запуска команд. При аварии между обновлением
+HEAD и записью состояния проверьте выполнение команд вручную.
+
+## Доверие и доступ
+
+`--trust` или подтверждение мастера разрешает обращаться к Git remote и менять
+папку от имени вашего пользователя. `--allow-commands` дополнительно разрешает
+заданные shell-команды при неинтерактивной регистрации. Это реальное выполнение
+кода: команды сборки и `npm ci` могут запускать код, полученный из remote.
+Добавляйте только проекты и remote, которым доверяете.
+
+Доверие Git задаётся через `-c safe.directory=<точный путь>` для конкретного
+вызова, без изменения глобального Git-конфига и без wildcard. Встроенные Git hooks
+отключены. SSH и Git credentials должны быть настроены заранее; фоновый процесс
+не спрашивает пароли и не открывает интерактивную авторизацию.
+
+Не выполняйте параллельные ручные Git-операции в управляемой папке во время
+обновления: внутренние блокировки координируют процессы `gp`, но не другие программы.
+
+## Фоновый процесс и хранение
+
+Один daemon на каталог данных, одна задача на проект, проекты обновляются
+последовательно. Долгая сборка задерживает проверки остальных проектов. Блокировки
+с PID предотвращают пересечение `gp pull` и расписания; после завершения процесса
+устаревшая блокировка восстанавливается при следующем обращении.
+
+По умолчанию данные лежат в `~/.git-puller` (каталоги `0700`, новые файлы `0600`):
+
+- `config.json` — доверенные папки, расписание и команды;
+- `states/` — последние результаты и незавершённые команды;
+- `logs/` — логи проектов, ротация около 2 MiB с одной предыдущей копией;
+- `daemon.log` — ошибки фонового процесса; не ротируется автоматически;
+- `locks/` — блокировки процессов.
+
+`GP_HOME=/custom/path gp ...` изолирует отдельный реестр и daemon. Конфигурация
+записывается атомарно. Логи могут содержать вывод ваших команд: не выводите в них
+секреты. Удаление проекта сохраняет его историю на диске.
+
+Daemon стартует автоматически при `add`/`start`, живёт после закрытия панели.
+`stop all` выключает расписание, `daemon stop` завершает сам процесс и прерывает
+активную Git/shell-команду. После перезагрузки компьютера запустите `gp daemon start`
+или подключите эту команду к launchd/systemd; автозагрузка и самовосстановление
+упавшего daemon в этой версии не устанавливаются.
+
+## Разработка
+
+```sh
+npm test
+npm run check
+npm pack --dry-run
+```
+
+Интеграционные тесты создают локальные bare-remotes и проверяют настоящие
+fast-forward обновления, сохранность локальной работы, расхождение истории,
+ошибки/повтор команд, блокировки, таймауты и фоновое расписание. Сеть не нужна.

package/bin/gp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+main().catch(error => {
+  console.error(`gp: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "gp-cron",
+  "version": "0.1.0",
+  "description": "A safe, local Git project updater with a terminal dashboard",
+  "type": "module",
+  "bin": { "gp": "bin/gp.js" },
+  "engines": { "node": ">=20" },
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test", "check": "node --check bin/gp.js && node --check src/cli.js && node --check src/worker.js", "start": "node bin/gp.js" },
+  "keywords": ["git", "updater", "cli", "tui", "automation"],
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,296 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+import { createInterface } from 'node:readline/promises';
+import { config, home, alive, interval, lock, logFile, select, setState, state, updateConfig } from './store.js';
+import { daemon, inspect, pull } from './worker.js';
+
+const entry = fileURLToPath(new URL('../bin/gp.js', import.meta.url));
+const color = (code, text) => process.stdout.isTTY && !process.env.NO_COLOR ? `\x1b[${code}m${text}\x1b[0m` : text;
+const safe = value => String(value ?? '').replace(/[\x00-\x1f\x7f-\x9f]/g, ' ');
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+function options(args) {
+  const result = { _: [], command: [] };
+  const flags = new Set(['trust', 'allow-commands', 'no-start', 'yes', 'follow']);
+  const values = new Set(['name', 'interval', 'command', 'timeout', 'lines']);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) { result._.push(arg); continue; }
+    const key = arg.slice(2);
+    if (flags.has(key)) result[key] = true;
+    else if (values.has(key) && args[i + 1] !== undefined) {
+      const value = args[++i];
+      if (key === 'command') result.command.push(value); else result[key] = value;
+    } else throw new Error(`Unknown or incomplete option: ${arg}`);
+  }
+  return result;
+}
+function daemonPid() {
+  try { const pid = Number(fs.readFileSync(path.join(home, 'locks', 'daemon.lock'), 'utf8')); return alive(pid) ? pid : null; } catch { return null; }
+}
+async function ensureDaemon() {
+  if (daemonPid()) return;
+  const fd = fs.openSync(path.join(home, 'daemon.log'), 'a', 0o600);
+  const child = spawn(process.execPath, [entry, '__daemon'], { detached: true, stdio: ['ignore', fd, fd], env: { ...process.env, GP_HOME: home } });
+  let spawnError;
+  child.on('error', error => { spawnError = error; });
+  child.unref(); fs.closeSync(fd);
+  for (let i = 0; i < 50; i++) { if (spawnError) throw spawnError; if (daemonPid()) return; await sleep(100); }
+  throw new Error(`Daemon failed to start. Inspect ${path.join(home, 'daemon.log')}`);
+}
+async function promptSession(fn) {
+  if (!process.stdin.isTTY) throw new Error('Interactive setup needs a terminal. Use --trust and explicit options; see gp help.');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try { return await fn(async (label, fallback = '') => (await rl.question(`${label}${fallback ? ` [${fallback}]` : ''}: `)).trim() || fallback); }
+  finally { rl.close(); }
+}
+async function wizard(folder, existing) {
+  return promptSession(async ask => {
+    const repo = await inspect(folder || await ask('Repository folder', process.cwd()));
+    console.log(`\n${safe(repo.path)}\nBranch: ${safe(repo.branch)} → ${safe(repo.upstream)}\n`);
+    const name = await ask('Project name', existing?.name || path.basename(repo.path));
+    const frequency = interval(await ask('Update interval (10s, 5m, 1h)', existing ? `${existing.interval / 1000}s` : '5m'));
+    console.log('Commands run in this folder using your shell, with your user permissions.');
+    if (existing?.commands.length) console.log(`Current commands: ${safe(existing.commands.join(' → '))}`);
+    const commands = [];
+    console.log('Enter each post-update command in execution order. Empty input finishes.');
+    while (true) { const command = await ask(`Command ${commands.length + 1}`); if (!command) break; commands.push(command); }
+    const timeout = interval(await ask('Timeout for each command', existing ? `${existing.commandTimeout / 1000}s` : '10m'));
+    console.log('Trust allows Git network access and updates in this folder. Built-in Git hooks are disabled.');
+    if ((await ask('Trust this folder and enable these commands? Type yes', 'no')).toLowerCase() !== 'yes') throw new Error('Setup cancelled.');
+    return { ...repo, name, interval: frequency, commands, commandTimeout: timeout, trusted: true };
+  });
+}
+async function add(folder, opts) {
+  let values;
+  if (opts.trust) {
+    const repo = await inspect(path.resolve(folder || '.'));
+    if (opts.command.length && !opts['allow-commands']) throw new Error('Use --allow-commands to explicitly authorize post-update commands.');
+    values = { ...repo, name: opts.name || path.basename(repo.path), interval: interval(opts.interval || '5m'), commands: opts.command, commandTimeout: interval(opts.timeout || '10m'), trusted: true };
+  } else values = await wizard(folder);
+  const project = { ...values, id: crypto.randomBytes(4).toString('hex'), enabled: !opts['no-start'] };
+  updateConfig(c => {
+    if (c.projects.some(p => p.path === project.path || p.name === project.name || p.id === project.name) || project.name === 'all') throw new Error('Project folder or name is already registered, or name is reserved.');
+    c.projects.push(project);
+  });
+  if (project.enabled) await ensureDaemon();
+  console.log(`Added ${safe(project.name)} (${project.id})${project.enabled ? ' · running' : ' · stopped'}`);
+}
+function status(p) {
+  const s = state(p.id);
+  if (!p.enabled) return 'stopped';
+  if (s.blocked) return 'paused';
+  if (!daemonPid()) return 'offline';
+  return ['checking', 'commands'].includes(s.phase) ? s.phase : 'watching';
+}
+function list() {
+  const projects = config().projects;
+  console.log(color('1;36', '  gp · git-puller') + `  daemon ${daemonPid() ? `online · ${daemonPid()}` : 'offline'}`);
+  if (!projects.length) { console.log('\nNo projects yet. Run gp add /path/to/project'); return; }
+  console.table(projects.map(p => ({ id: p.id, project: safe(p.name), status: status(p), interval: `${p.interval / 1000}s`, branch: safe(p.branch), updated: state(p.id).updatedAt || '—', folder: safe(p.path) })));
+}
+function mutateProject(p, fn) {
+  const release = lock(`project-${p.id}`);
+  if (!release) throw new Error('Project is currently updating. Try again when it finishes.');
+  try { return fn(); } finally { release(); }
+}
+async function edit(p) {
+  const values = await wizard(p.path, p);
+  mutateProject(p, () => updateConfig(c => {
+    if (values.name === 'all' || c.projects.some(item => item.id !== p.id && (item.name === values.name || item.id === values.name))) throw new Error('Project name is already used or reserved.');
+    const current = c.projects.find(item => item.id === p.id);
+    if (!current) throw new Error('Project was removed.');
+    Object.assign(current, values);
+  }));
+  console.log('Saved. Run gp start to resume a paused project.');
+}
+async function logs(p, opts = {}) {
+  const count = Number(opts.lines || 30);
+  if (!Number.isInteger(count) || count < 1 || count > 10000) throw new Error('--lines must be between 1 and 10000.');
+  const file = logFile(p.id);
+  const content = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  console.log(content.trimEnd().split('\n').slice(-count).map(safe).join('\n') || 'No logs yet.');
+  if (!opts.follow) return;
+  let offset = Buffer.byteLength(content), stopped = false;
+  const stop = () => { stopped = true; };
+  process.on('SIGINT', stop); process.on('SIGTERM', stop);
+  try {
+    while (!stopped) {
+      await sleep(500);
+      if (!fs.existsSync(file)) continue;
+      const data = fs.readFileSync(file);
+      if (data.length < offset) offset = 0;
+      if (data.length > offset) console.log(safe(data.subarray(offset).toString()).trim());
+      offset = data.length;
+    }
+  } finally { process.off('SIGINT', stop); process.off('SIGTERM', stop); }
+}
+async function scan(root) {
+  const found = [];
+  function walk(dir, depth) {
+    if (fs.existsSync(path.join(dir, '.git'))) { found.push(dir); return; }
+    if (depth >= 4) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) if (e.isDirectory() && !e.name.startsWith('.') && !['node_modules', 'vendor', 'dist'].includes(e.name)) walk(path.join(dir, e.name), depth + 1);
+  }
+  walk(fs.realpathSync(root || '.'), 0);
+  const known = new Set(config().projects.map(p => p.path));
+  for (const folder of found) console.log(`${known.has(folder) ? 'registered' : 'available '}  ${safe(folder)}`);
+  console.log(`${found.length} repositories found. Register with gp add "<folder>".`);
+}
+async function action(command, query, opts = {}) {
+  if (command === 'start' || command === 'stop') {
+    const targets = query === 'all' ? config().projects : [select(query)];
+    const releases = [];
+    try {
+      if (command === 'start') for (const p of targets) {
+        const release = lock(`project-${p.id}`);
+        if (!release) throw new Error(`${p.name} is currently updating. Try again when it finishes.`);
+        releases.push(release);
+      }
+      if (command === 'start') for (const p of targets) setState(p.id, { blocked: false, phase: 'idle', nextRun: 0, error: null });
+      updateConfig(c => { for (const p of c.projects) if (targets.some(t => t.id === p.id)) p.enabled = command === 'start'; });
+    } finally { for (const release of releases.reverse()) release(); }
+    if (command === 'start') await ensureDaemon();
+    console.log(`${command === 'start' ? 'Started' : 'Stopped scheduling'} ${targets.length} project(s).${command === 'stop' ? ' An active job is allowed to finish.' : ''}`);
+    return;
+  }
+  const p = select(query);
+  if (command === 'edit') return edit(p);
+  if (command === 'logs') return logs(p, opts);
+  if (command === 'info') { console.log(JSON.stringify({ ...p, status: status(p), runtime: state(p.id) }, null, 2)); return; }
+  if (command === 'pull' || command === 'retry') {
+    const result = await pull(p, { retry: command === 'retry' });
+    if (result.error) throw new Error(result.error);
+    console.log(result.busy ? 'Project is already updating.' : 'Done.'); return;
+  }
+  if (command === 'remove' || command === 'accept') {
+    if (!opts.yes) {
+      const confirmed = await promptSession(async ask => (await ask(command === 'remove' ? `Unregister ${p.name}? Files will stay. Type yes` : 'Clear pending commands without running them? Type yes', 'no')) === 'yes');
+      if (!confirmed) return;
+    }
+    mutateProject(p, () => {
+      if (command === 'remove') updateConfig(c => { c.projects = c.projects.filter(item => item.id !== p.id); });
+      else setState(p.id, { pendingRevision: null, blocked: false, error: null, phase: 'idle', nextRun: Date.now() + p.interval });
+    });
+    console.log(command === 'remove' ? 'Project unregistered; files and logs retained.' : 'Pending commands cleared.'); return;
+  }
+  throw new Error(`Unknown command: ${command}`);
+}
+
+async function dashboard() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return list();
+  let selected = 0, busy = false, done = false, notice = '';
+  readline.emitKeypressEvents(process.stdin);
+  const draw = () => {
+    if (busy || done) return;
+    const projects = config().projects;
+    selected = Math.max(0, Math.min(selected, projects.length - 1));
+    const width = Math.max(30, (process.stdout.columns || 90) - 2);
+    const line = text => console.log(safe(text).slice(0, width));
+    process.stdout.write('\x1b[2J\x1b[H');
+    console.log(color('1;36', '  ◈  git-puller') + color('2', `   daemon ${daemonPid() ? '● online' : '○ offline'}`));
+    line('  Git projects, quietly kept current.'); console.log();
+    const visible = Math.max(1, (process.stdout.rows || 24) - 13);
+    const first = Math.max(0, selected - visible + 1);
+    for (let index = first; index < Math.min(projects.length, first + visible); index++) {
+      const p = projects[index];
+      const text = ` ${index === selected ? '›' : ' '} ${p.name.padEnd(22)} ${status(p).padEnd(10)} ${String(p.interval / 1000).padStart(5)}s  ${p.branch}`;
+      console.log(color(index === selected ? '1;36' : '0', safe(text).slice(0, width)));
+    }
+    if (!projects.length) line('  No projects. Press a to add your first repository.');
+    const p = projects[selected];
+    console.log();
+    if (p) {
+      const s = state(p.id);
+      line(`  ${p.path}`);
+      line(`  Checked: ${s.checkedAt || '—'}   Updated: ${s.updatedAt || '—'}`);
+      line(`  Next: ${p.enabled && !s.blocked && s.nextRun ? new Date(s.nextRun).toLocaleTimeString() : '—'}`);
+      if (s.error) line(`  ⚠ ${s.error}`);
+    }
+    console.log();
+    line('  ↑↓ select  a add  space start/stop  p pull  e edit  l logs');
+    line('  r retry commands  d remove  q quit');
+    if (notice) line(`  ${notice}`);
+  };
+  const cleanup = () => { clearInterval(timer); process.stdin.off('keypress', keypress); process.stdin.setRawMode(false); process.stdin.pause(); process.stdout.write('\x1b[?25h\n'); };
+  let finish;
+  const completed = new Promise(resolve => { finish = resolve; });
+  const keypress = async (text, key = {}) => {
+    if (busy || done) return;
+    if (text === 'q' || (key.ctrl && key.name === 'c')) { done = true; cleanup(); finish(); return; }
+    const projects = config().projects;
+    if (key.name === 'up' || text === 'k') { selected--; draw(); return; }
+    if (key.name === 'down' || text === 'j') { selected++; draw(); return; }
+    const p = projects[selected];
+    if (!['a', ' ', 'p', 'e', 'l', 'r', 'd'].includes(text) || (text !== 'a' && !p)) return;
+    busy = true; process.stdin.setRawMode(false); process.stdout.write('\x1b[?25h\x1b[2J\x1b[H');
+    try {
+      if (text === 'a') await add(undefined, { command: [] });
+      else await action(({ ' ': p.enabled ? 'stop' : 'start', p: 'pull', e: 'edit', l: 'logs', r: 'retry', d: 'remove' })[text], p.id);
+      notice = 'Done';
+    } catch (error) { notice = error.message; console.log(safe(error.message)); }
+    finally {
+      await promptSession(async ask => { await ask('Press Enter to return'); });
+      process.stdin.setRawMode(true); process.stdin.resume(); process.stdout.write('\x1b[?25l'); busy = false; draw();
+    }
+  };
+  process.stdin.setRawMode(true); process.stdin.resume(); process.stdout.write('\x1b[?25l');
+  process.stdin.on('keypress', keypress);
+  const timer = setInterval(draw, 1000);
+  draw(); await completed;
+}
+
+const help = `git-puller · gp
+
+  gp                         Interactive dashboard (↑↓, keyboard shortcuts)
+  gp add [folder]            Guided registration, trust, schedule and commands
+  gp list                    Project status (alias: status, ls)
+  gp scan [folder]            Discover repositories, up to four levels deep
+  gp start <name|id|all>      Start/resume scheduled updates
+  gp stop <name|id|all>       Stop scheduling; active job finishes
+  gp pull <name|id>          Check and update immediately, even when stopped
+  gp edit <name|id>          Reconfigure interactively
+  gp info <name|id>          Configuration and runtime state as JSON
+  gp logs <name|id>          Logs (--follow, --lines 50)
+  gp retry <name|id>         Rerun pending post-update commands from the beginning
+  gp accept <name|id>        Clear pending commands after manual resolution
+  gp remove <name|id>        Unregister, preserving repository and logs
+  gp daemon start|stop       Manage the background process
+  gp help                    Show this help
+
+Non-interactive setup:
+  gp add ./app --trust --interval 5m --name app \\
+    --allow-commands --command 'npm ci' --command 'npm run build'
+
+Options: --no-start, --timeout 10m; remove/accept: --yes.
+Data: ${home} (override with GP_HOME).
+Only fast-forward updates; local changes/diverged history pause the project.
+Fix Git manually, then gp start <name>. Commands run only after HEAD changes.
+`;
+export async function main(args = process.argv.slice(2)) {
+  config();
+  const [command, ...rest] = args;
+  if (command === '__daemon') return daemon();
+  if (!command || command === 'ui') return dashboard();
+  if (['help', '--help', '-h'].includes(command)) { console.log(help); return; }
+  if (['--version', '-v'].includes(command)) { console.log('0.1.0'); return; }
+  if (['list', 'ls', 'status'].includes(command)) return list();
+  const opts = options(rest);
+  if (command === 'add') return add(opts._[0], opts);
+  if (command === 'scan') return scan(opts._[0]);
+  if (command === 'daemon') {
+    if (opts._[0] === 'start') { await ensureDaemon(); console.log('Daemon online.'); return; }
+    if (opts._[0] !== 'stop') throw new Error('Use gp daemon start|stop.');
+    const pid = daemonPid();
+    if (!pid) { console.log('Daemon is offline.'); return; }
+    process.kill(pid, 'SIGTERM');
+    for (let i = 0; i < 50; i++) { if (!daemonPid()) { console.log('Daemon stopped.'); return; } await sleep(100); }
+    console.log('Shutdown requested; waiting for the active job to finish.'); return;
+  }
+  return action(command, opts._[0], opts);
+}

package/src/process.js

@@ -0,0 +1,27 @@
+import { spawn } from 'node:child_process';
+
+export function run(command, args, { cwd, timeout = 120000, shell = false, onOutput } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, shell, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never', GIT_SSH_COMMAND: `${process.env.GIT_SSH_COMMAND || 'ssh'} -oBatchMode=yes -oConnectTimeout=15` } });
+    let output = '', timedOut = false;
+    const collect = data => { const text = data.toString(); output = (output + text).slice(-64000); onOutput?.(text); };
+    child.stdout.on('data', collect); child.stderr.on('data', collect);
+    function kill() {
+      try { process.kill(process.platform === 'win32' ? child.pid : -child.pid, 'SIGKILL'); } catch {}
+    }
+    const timer = setTimeout(() => { timedOut = true; kill(); }, timeout);
+    const abort = () => kill();
+    process.on('SIGTERM', abort); process.on('SIGINT', abort);
+    const cleanup = () => { clearTimeout(timer); process.off('SIGTERM', abort); process.off('SIGINT', abort); };
+    child.on('error', error => { cleanup(); reject(error); });
+    child.on('close', (code, signal) => {
+      cleanup();
+      if (code === 0 && !timedOut) resolve(output.trim());
+      else reject(new Error(timedOut ? `Command timed out after ${timeout / 1000}s: ${command}` : `${command} failed (${code ?? signal}): ${output.trim()}`));
+    });
+  });
+}
+export function git(folder, args, options = {}) {
+  // Trust only this invocation; never change the user's global safe.directory.
+  return run('git', ['-c', `safe.directory=${folder}`, '-c', 'core.hooksPath=/dev/null', '-C', folder, ...args], options);
+}

package/src/store.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+export const home = path.resolve(process.env.GP_HOME || path.join(os.homedir(), '.git-puller'));
+export function init() {
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  for (const dir of ['states', 'logs', 'locks']) fs.mkdirSync(path.join(home, dir), { recursive: true, mode: 0o700 });
+}
+export function atomic(file, value) {
+  const temp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(temp, file);
+}
+export function read(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return fallback; throw new Error(`Cannot read ${file}: ${e.message}`); }
+}
+export function config() { init(); return read(path.join(home, 'config.json'), { version: 1, projects: [] }); }
+export function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+// Exclusive files carry their owner PID. An empty/unfinished lock gets a grace period.
+export function lock(name) {
+  init();
+  const file = path.join(home, 'locks', `${name}.lock`);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(file, 'wx', 0o600);
+      fs.writeFileSync(fd, String(process.pid)); fs.closeSync(fd);
+      return () => { try { if (fs.readFileSync(file, 'utf8') === String(process.pid)) fs.unlinkSync(file); } catch {} };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      let owner, age;
+      try { owner = Number(fs.readFileSync(file, 'utf8')); age = Date.now() - fs.statSync(file).mtimeMs; }
+      catch (e) { if (e.code === 'ENOENT') continue; throw e; }
+      if (alive(owner) || (!owner && age < 10000)) return null;
+      try { fs.unlinkSync(file); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    }
+  }
+  return null;
+}
+export function updateConfig(fn) {
+  const release = lock('config');
+  if (!release) throw new Error('Configuration is busy; try again.');
+  try { const value = config(); fn(value); atomic(path.join(home, 'config.json'), value); return value; }
+  finally { release(); }
+}
+export function state(id) { return read(path.join(home, 'states', `${id}.json`), {}); }
+export function setState(id, patch) { atomic(path.join(home, 'states', `${id}.json`), { ...state(id), ...patch }); }
+export function logFile(id) { return path.join(home, 'logs', `${id}.log`); }
+export function log(id, message) {
+  const file = logFile(id);
+  try { if (fs.statSync(file).size > 2 * 1024 * 1024) fs.renameSync(file, `${file}.1`); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  fs.appendFileSync(file, `[${new Date().toISOString()}] ${message}\n`, { mode: 0o600 });
+}
+export function select(query, projects = config().projects) {
+  const exact = projects.filter(p => p.id === query || p.name === query || p.path === path.resolve(query || '.'));
+  if (exact.length === 1) return exact[0];
+  const partial = projects.filter(p => query && p.id.startsWith(query));
+  if (!exact.length && partial.length === 1) return partial[0];
+  throw new Error(`Project "${query}" is missing or ambiguous. Run gp list.`);
+}
+export function interval(value) {
+  const match = /^(\d+(?:\.\d+)?)(s|m|h)?$/.exec(String(value));
+  const ms = match && Number(match[1]) * ({ s: 1000, m: 60000, h: 3600000 }[match[2] || 's']);
+  if (!ms || ms < 10000 || ms > 7 * 86400000) throw new Error('Interval must be between 10s and 168h (for example 5m).');
+  return ms;
+}

package/src/worker.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, run } from './process.js';
+import { config, home, lock, log, setState, state } from './store.js';
+
+export async function inspect(folder) {
+  const real = fs.realpathSync(folder);
+  const root = await git(real, ['rev-parse', '--show-toplevel']);
+  if (fs.realpathSync(root) !== real) throw new Error('Choose the repository root, not a subfolder.');
+  let branch, upstream;
+  try { branch = await git(real, ['symbolic-ref', '--quiet', '--short', 'HEAD']); }
+  catch { throw new Error('Detached HEAD: check out a branch before registering or resuming.'); }
+  try { upstream = await git(real, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']); }
+  catch { throw new Error(`No upstream for branch ${branch}. Configure tracking with git branch --set-upstream-to, then gp edit.`); }
+  return { path: real, branch, upstream };
+}
+async function clean(p) {
+  if (fs.realpathSync(p.path) !== p.path) throw new Error('Repository path changed; add and trust it again.');
+  const info = await inspect(p.path);
+  if (info.branch !== p.branch || info.upstream !== p.upstream) throw new Error('Branch or upstream changed; review with gp edit.');
+  const dir = await git(p.path, ['rev-parse', '--absolute-git-dir']);
+  for (const marker of ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply', 'BISECT_LOG']) {
+    if (fs.existsSync(path.join(dir, marker))) throw new Error('An unfinished Git operation needs attention. Finish or abort it in the repository.');
+  }
+  if (await git(p.path, ['status', '--porcelain', '--untracked-files=normal'])) throw new Error('Local changes found. Commit or stash them, then run gp start.');
+}
+async function hooks(p, revision) {
+  setState(p.id, { phase: 'commands', pendingRevision: revision });
+  for (const command of p.commands) {
+    log(p.id, `$ ${command}`);
+    await run(command, [], { cwd: p.path, shell: true, timeout: p.commandTimeout, onOutput: text => log(p.id, text.trimEnd()) });
+  }
+  setState(p.id, { pendingRevision: null });
+}
+export async function pull(p, { retry = false } = {}) {
+  const release = lock(`project-${p.id}`);
+  if (!release) return { busy: true };
+  try {
+    if (!p.trusted) throw new Error('Repository is not trusted.');
+    const previous = state(p.id);
+    if (previous.pendingRevision && !retry) throw new Error('Post-update commands failed or were interrupted. Review logs and use gp retry, or gp accept to clear the pending run.');
+    setState(p.id, { phase: 'checking', checkedAt: new Date().toISOString(), error: null });
+    await clean(p);
+    const before = await git(p.path, ['rev-parse', 'HEAD']);
+    if (retry) {
+      if (!previous.pendingRevision) throw new Error('No pending commands to retry.');
+      if (before !== previous.pendingRevision) throw new Error('HEAD changed since the failed commands; review and use gp accept.');
+      await hooks(p, before);
+    } else {
+      log(p.id, `Checking ${p.branch} → ${p.upstream}`);
+      await git(p.path, ['fetch', '--prune']);
+      // Recheck after network I/O in case another process modified the working tree.
+      await clean(p);
+      if (before !== await git(p.path, ['rev-parse', 'HEAD'])) throw new Error('HEAD changed during fetch. Try again after other Git operations finish.');
+      await git(p.path, ['merge', '--ff-only', '--no-edit', '@{upstream}']);
+      const after = await git(p.path, ['rev-parse', 'HEAD']);
+      if (before !== after) {
+        setState(p.id, { revision: after, updatedAt: new Date().toISOString(), pendingRevision: p.commands.length ? after : null });
+        log(p.id, `Updated ${before.slice(0, 8)} → ${after.slice(0, 8)}`);
+        await hooks(p, after);
+      } else log(p.id, 'Already up to date');
+    }
+    setState(p.id, { phase: 'idle', blocked: false, error: null, nextRun: Date.now() + p.interval });
+    return { ok: true };
+  } catch (error) {
+    log(p.id, `PAUSED: ${error.message}`);
+    setState(p.id, { phase: 'paused', blocked: true, error: error.message, nextRun: null });
+    return { error: error.message };
+  } finally { release(); }
+}
+export async function daemon() {
+  const release = lock('daemon');
+  if (!release) return;
+  let stopping = false;
+  const stop = () => { stopping = true; };
+  process.on('SIGTERM', stop); process.on('SIGINT', stop);
+  try {
+    while (!stopping) {
+      const projects = config().projects;
+      // Sequential jobs bound load and keep shutdown predictable.
+      for (const p of projects) {
+        if (stopping) break;
+        const current = config().projects.find(item => item.id === p.id);
+        const s = state(p.id);
+        if (current?.enabled && !s.blocked && (!s.nextRun || s.nextRun <= Date.now())) await pull(current);
+      }
+      if (!stopping) await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+  } finally { release(); process.off('SIGTERM', stop); process.off('SIGINT', stop); }
+}