@keepgoingdev/cli 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @keepgoing/cli
+
+Terminal CLI for [KeepGoing](https://keepgoing.dev) — resume side projects without the mental friction.
+
+## Install
+
+```bash
+# Run without installing
+npx @keepgoing/cli status
+
+# Install globally
+npm install -g @keepgoing/cli
+
+# Or add to a project
+npm install --save-dev @keepgoing/cli
+```
+
+## Commands
+
+### `keepgoing status`
+
+Show the last checkpoint for the current project.
+
+```
+KeepGoing · 12 days ago
+
+  Summary:   Refactored auth middleware to support JWT rotation
+  Next step: Implement verifyRefreshToken helper in auth.ts
+  Branch:    feature/auth-refactor
+  Files:     auth.ts, middleware.ts, routes/token.ts (+2 more)
+```
+
+Flags:
+
+- `--cwd <path>` — override the working directory
+- `--json` — output raw JSON of the last checkpoint (for scripting)
+- `--quiet` — output a single summary line (used by the shell hook)
+
+### `keepgoing save`
+
+Save a new checkpoint interactively. Prompts for:
+
+1. What did you work on? (required)
+2. What's your next step? (required)
+3. Any blockers? (optional)
+
+Git branch and touched files are auto-detected from the workspace.
+
+### `keepgoing hook install`
+
+Install a shell hook that runs `keepgoing status --quiet` automatically whenever you `cd` into a directory that contains `.keepgoing/`.
+
+Supports **zsh** and **bash**. Detected from `$SHELL`.
+
+```bash
+keepgoing hook install
+# → Reload your shell:
+source ~/.zshrc   # or ~/.bashrc
+```
+
+### `keepgoing hook uninstall`
+
+Remove the shell hook from your `~/.zshrc` or `~/.bashrc`.
+
+```bash
+keepgoing hook uninstall
+```
+
+## Shell Hook Setup
+
+The shell hook gives you zero-friction project context when you enter a project directory.
+
+After running `keepgoing hook install` and reloading your shell, entering any directory with a `.keepgoing/` folder will automatically print:
+
+```
+KeepGoing · 3 days ago · Refactored auth middleware to support JWT rotation
+```
+
+## Data Format
+
+Reads and writes the same `.keepgoing/` schema used by the VS Code extension:
+
+- `.keepgoing/sessions.json` — all checkpoints
+- `.keepgoing/state.json` — last session state
+- `.keepgoing/meta.json` — project metadata
+
+## Development
+
+From the monorepo root:
+
+```bash
+npm run build --workspace=apps/cli
+```

package/dist/index.js

@@ -0,0 +1,529 @@
+#!/usr/bin/env node
+
+// src/storage.ts
+import fs from "fs";
+import path from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+
+// ../../packages/shared/src/session.ts
+import { randomUUID } from "crypto";
+function generateCheckpointId() {
+  return randomUUID();
+}
+function createCheckpoint(fields) {
+  return {
+    id: generateCheckpointId(),
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...fields
+  };
+}
+
+// ../../packages/shared/src/timeUtils.ts
+function formatRelativeTime(timestamp) {
+  const now = Date.now();
+  const then = new Date(timestamp).getTime();
+  const diffMs = now - then;
+  if (isNaN(diffMs)) {
+    return "unknown time";
+  }
+  if (diffMs < 0) {
+    return "in the future";
+  }
+  const seconds = Math.floor(diffMs / 1e3);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  const weeks = Math.floor(days / 7);
+  const months = Math.floor(days / 30);
+  const years = Math.floor(days / 365);
+  if (seconds < 10) {
+    return "just now";
+  } else if (seconds < 60) {
+    return `${seconds} seconds ago`;
+  } else if (minutes < 60) {
+    return minutes === 1 ? "1 minute ago" : `${minutes} minutes ago`;
+  } else if (hours < 24) {
+    return hours === 1 ? "1 hour ago" : `${hours} hours ago`;
+  } else if (days < 7) {
+    return days === 1 ? "1 day ago" : `${days} days ago`;
+  } else if (weeks < 4) {
+    return weeks === 1 ? "1 week ago" : `${weeks} weeks ago`;
+  } else if (months < 12) {
+    return months === 1 ? "1 month ago" : `${months} months ago`;
+  } else {
+    return years === 1 ? "1 year ago" : `${years} years ago`;
+  }
+}
+
+// ../../packages/shared/src/gitUtils.ts
+import { execFileSync, execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function getCurrentBranch(workspacePath) {
+  try {
+    const result = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd: workspacePath,
+      encoding: "utf-8",
+      timeout: 5e3
+    });
+    return result.trim() || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function getTouchedFiles(workspacePath) {
+  try {
+    const result = execFileSync("git", ["status", "--porcelain"], {
+      cwd: workspacePath,
+      encoding: "utf-8",
+      timeout: 5e3
+    });
+    if (!result.trim()) {
+      return [];
+    }
+    return result.trim().split("\n").map((line) => line.substring(3).trim()).filter((file) => file.length > 0 && !file.endsWith("/"));
+  } catch {
+    return [];
+  }
+}
+
+// ../../packages/shared/src/reentry.ts
+var RECENT_SESSION_COUNT = 5;
+function getRecentSessions(allSessions, count = RECENT_SESSION_COUNT) {
+  return allSessions.slice(-count).reverse();
+}
+
+// src/storage.ts
+var STORAGE_DIR = ".keepgoing";
+var META_FILE = "meta.json";
+var SESSIONS_FILE = "sessions.json";
+var STATE_FILE = "state.json";
+var KeepGoingReader = class {
+  storagePath;
+  metaFilePath;
+  sessionsFilePath;
+  stateFilePath;
+  constructor(workspacePath) {
+    this.storagePath = path.join(workspacePath, STORAGE_DIR);
+    this.metaFilePath = path.join(this.storagePath, META_FILE);
+    this.sessionsFilePath = path.join(this.storagePath, SESSIONS_FILE);
+    this.stateFilePath = path.join(this.storagePath, STATE_FILE);
+  }
+  exists() {
+    return fs.existsSync(this.storagePath);
+  }
+  getState() {
+    return this.readJsonFile(this.stateFilePath);
+  }
+  getMeta() {
+    return this.readJsonFile(this.metaFilePath);
+  }
+  getSessions() {
+    return this.parseSessions().sessions;
+  }
+  getLastSession() {
+    const { sessions, wrapperLastSessionId } = this.parseSessions();
+    if (sessions.length === 0) {
+      return void 0;
+    }
+    const state = this.getState();
+    if (state?.lastSessionId) {
+      const found = sessions.find((s) => s.id === state.lastSessionId);
+      if (found) return found;
+    }
+    if (wrapperLastSessionId) {
+      const found = sessions.find((s) => s.id === wrapperLastSessionId);
+      if (found) return found;
+    }
+    return sessions[sessions.length - 1];
+  }
+  getRecentSessions(count) {
+    return getRecentSessions(this.getSessions(), count);
+  }
+  parseSessions() {
+    const raw = this.readJsonFile(this.sessionsFilePath);
+    if (!raw) return { sessions: [] };
+    if (Array.isArray(raw)) return { sessions: raw };
+    return { sessions: raw.sessions ?? [], wrapperLastSessionId: raw.lastSessionId };
+  }
+  readJsonFile(filePath) {
+    try {
+      if (!fs.existsSync(filePath)) return void 0;
+      const raw = fs.readFileSync(filePath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+  }
+};
+var KeepGoingWriter = class {
+  storagePath;
+  sessionsFilePath;
+  stateFilePath;
+  metaFilePath;
+  constructor(workspacePath) {
+    this.storagePath = path.join(workspacePath, STORAGE_DIR);
+    this.sessionsFilePath = path.join(this.storagePath, SESSIONS_FILE);
+    this.stateFilePath = path.join(this.storagePath, STATE_FILE);
+    this.metaFilePath = path.join(this.storagePath, META_FILE);
+  }
+  ensureDir() {
+    if (!fs.existsSync(this.storagePath)) {
+      fs.mkdirSync(this.storagePath, { recursive: true });
+    }
+  }
+  saveCheckpoint(checkpoint, projectName) {
+    this.ensureDir();
+    let sessionsData;
+    try {
+      if (fs.existsSync(this.sessionsFilePath)) {
+        const raw = JSON.parse(fs.readFileSync(this.sessionsFilePath, "utf-8"));
+        if (Array.isArray(raw)) {
+          sessionsData = { version: 1, project: projectName, sessions: raw };
+        } else {
+          sessionsData = raw;
+        }
+      } else {
+        sessionsData = { version: 1, project: projectName, sessions: [] };
+      }
+    } catch {
+      sessionsData = { version: 1, project: projectName, sessions: [] };
+    }
+    sessionsData.sessions.push(checkpoint);
+    sessionsData.lastSessionId = checkpoint.id;
+    fs.writeFileSync(this.sessionsFilePath, JSON.stringify(sessionsData, null, 2), "utf-8");
+    const state = {
+      lastSessionId: checkpoint.id,
+      lastKnownBranch: checkpoint.gitBranch,
+      lastActivityAt: checkpoint.timestamp
+    };
+    fs.writeFileSync(this.stateFilePath, JSON.stringify(state, null, 2), "utf-8");
+    let meta;
+    try {
+      if (fs.existsSync(this.metaFilePath)) {
+        meta = JSON.parse(fs.readFileSync(this.metaFilePath, "utf-8"));
+        meta.lastUpdated = checkpoint.timestamp;
+      } else {
+        meta = {
+          projectId: randomUUID2(),
+          createdAt: checkpoint.timestamp,
+          lastUpdated: checkpoint.timestamp
+        };
+      }
+    } catch {
+      meta = {
+        projectId: randomUUID2(),
+        createdAt: checkpoint.timestamp,
+        lastUpdated: checkpoint.timestamp
+      };
+    }
+    fs.writeFileSync(this.metaFilePath, JSON.stringify(meta, null, 2), "utf-8");
+  }
+};
+
+// src/render.ts
+var RESET = "\x1B[0m";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var YELLOW = "\x1B[33m";
+var CYAN = "\x1B[36m";
+function renderCheckpoint(checkpoint, daysSince) {
+  const relTime = formatRelativeTime(checkpoint.timestamp);
+  if (daysSince !== void 0 && daysSince >= 7) {
+    console.log(`${YELLOW}\u26A0 This project has been idle for ${daysSince} days.${RESET}`);
+  }
+  console.log(`
+${BOLD}KeepGoing${RESET} \xB7 ${DIM}${relTime}${RESET}
+`);
+  const label = (s) => `${CYAN}${s}${RESET}`;
+  if (checkpoint.summary) {
+    console.log(`  ${label("Summary:")}   ${checkpoint.summary}`);
+  }
+  if (checkpoint.nextStep) {
+    console.log(`  ${label("Next step:")} ${checkpoint.nextStep}`);
+  }
+  if (checkpoint.blocker) {
+    console.log(`  ${label("Blocker:")}   ${checkpoint.blocker}`);
+  }
+  if (checkpoint.gitBranch) {
+    console.log(`  ${label("Branch:")}    ${checkpoint.gitBranch}`);
+  }
+  if (checkpoint.touchedFiles && checkpoint.touchedFiles.length > 0) {
+    const MAX_FILES = 3;
+    const shown = checkpoint.touchedFiles.slice(0, MAX_FILES).join(", ");
+    const extra = checkpoint.touchedFiles.length - MAX_FILES;
+    const filesStr = extra > 0 ? `${shown} (+${extra} more)` : shown;
+    console.log(`  ${label("Files:")}     ${filesStr}`);
+  }
+  console.log("");
+}
+function renderQuiet(checkpoint) {
+  const relTime = formatRelativeTime(checkpoint.timestamp);
+  const summary = checkpoint.summary || checkpoint.nextStep || "checkpoint saved";
+  console.log(`KeepGoing \xB7 ${relTime} \xB7 ${summary}`);
+}
+function renderNoData() {
+  console.log(
+    `No KeepGoing data found. Run ${BOLD}keepgoing save${RESET} to save your first checkpoint.`
+  );
+}
+
+// src/commands/status.ts
+async function statusCommand(opts) {
+  const reader = new KeepGoingReader(opts.cwd);
+  if (!reader.exists()) {
+    if (!opts.quiet) {
+      renderNoData();
+    }
+    process.exit(0);
+  }
+  const lastSession = reader.getLastSession();
+  if (!lastSession) {
+    if (!opts.quiet) {
+      renderNoData();
+    }
+    process.exit(0);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(lastSession, null, 2));
+    return;
+  }
+  if (opts.quiet) {
+    renderQuiet(lastSession);
+    return;
+  }
+  const daysSince = Math.floor(
+    (Date.now() - new Date(lastSession.timestamp).getTime()) / (1e3 * 60 * 60 * 24)
+  );
+  renderCheckpoint(lastSession, daysSince);
+}
+
+// src/commands/save.ts
+import readline from "readline";
+import path2 from "path";
+function prompt(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+async function saveCommand(opts) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  let summary = "";
+  let nextStep = "";
+  let blocker = "";
+  try {
+    while (!summary) {
+      summary = await prompt(rl, "What did you work on? ");
+      if (!summary) {
+        console.log("  (This field is required)");
+      }
+    }
+    while (!nextStep) {
+      nextStep = await prompt(rl, "What's your next step? ");
+      if (!nextStep) {
+        console.log("  (This field is required)");
+      }
+    }
+    blocker = await prompt(rl, "Any blockers? (leave empty to skip) ");
+  } finally {
+    rl.close();
+  }
+  const gitBranch = getCurrentBranch(opts.cwd);
+  const touchedFiles = getTouchedFiles(opts.cwd);
+  const checkpoint = createCheckpoint({
+    summary,
+    nextStep,
+    blocker: blocker || void 0,
+    gitBranch,
+    touchedFiles,
+    workspaceRoot: opts.cwd,
+    source: "manual"
+  });
+  const projectName = path2.basename(opts.cwd);
+  const writer = new KeepGoingWriter(opts.cwd);
+  writer.saveCheckpoint(checkpoint, projectName);
+  console.log("Checkpoint saved.");
+}
+
+// src/commands/hook.ts
+import fs2 from "fs";
+import path3 from "path";
+import os from "os";
+var HOOK_MARKER_START = "# keepgoing-hook-start";
+var HOOK_MARKER_END = "# keepgoing-hook-end";
+var ZSH_HOOK = `${HOOK_MARKER_START}
+# KeepGoing shell hook \u2014 auto-injected by 'keepgoing hook install'
+if command -v keepgoing >/dev/null 2>&1; then
+  function chpwd() {
+    if [ -d ".keepgoing" ]; then
+      keepgoing status --quiet
+    fi
+  }
+fi
+${HOOK_MARKER_END}`;
+var BASH_HOOK = `${HOOK_MARKER_START}
+# KeepGoing shell hook \u2014 auto-injected by 'keepgoing hook install'
+if command -v keepgoing >/dev/null 2>&1; then
+  function cd() {
+    builtin cd "$@" || return
+    if [ -d ".keepgoing" ]; then
+      keepgoing status --quiet
+    fi
+  }
+fi
+${HOOK_MARKER_END}`;
+function detectShellRcFile() {
+  const shellEnv = process.env["SHELL"] ?? "";
+  const home = os.homedir();
+  if (shellEnv.endsWith("zsh")) {
+    return { shell: "zsh", rcFile: path3.join(home, ".zshrc") };
+  }
+  if (shellEnv.endsWith("bash")) {
+    return { shell: "bash", rcFile: path3.join(home, ".bashrc") };
+  }
+  return void 0;
+}
+function hookInstallCommand() {
+  const detected = detectShellRcFile();
+  if (!detected) {
+    console.error(
+      'Could not detect your shell. Set $SHELL to "zsh" or "bash" and try again.'
+    );
+    process.exit(1);
+  }
+  const { shell, rcFile } = detected;
+  const hookBlock = shell === "zsh" ? ZSH_HOOK : BASH_HOOK;
+  let existing = "";
+  try {
+    existing = fs2.readFileSync(rcFile, "utf-8");
+  } catch {
+  }
+  if (existing.includes(HOOK_MARKER_START)) {
+    console.log(`KeepGoing hook is already installed in ${rcFile}.`);
+    return;
+  }
+  fs2.appendFileSync(rcFile, `
+${hookBlock}
+`, "utf-8");
+  console.log(`KeepGoing hook installed in ${rcFile}.`);
+  console.log(`Reload your shell config to activate it:
+`);
+  console.log(`  source ${rcFile}`);
+}
+function hookUninstallCommand() {
+  const detected = detectShellRcFile();
+  if (!detected) {
+    console.error(
+      'Could not detect your shell. Set $SHELL to "zsh" or "bash" and try again.'
+    );
+    process.exit(1);
+  }
+  const { rcFile } = detected;
+  let existing = "";
+  try {
+    existing = fs2.readFileSync(rcFile, "utf-8");
+  } catch {
+    console.log(`${rcFile} not found \u2014 nothing to remove.`);
+    return;
+  }
+  if (!existing.includes(HOOK_MARKER_START)) {
+    console.log("KeepGoing hook is not installed \u2014 nothing to remove.");
+    return;
+  }
+  const pattern = new RegExp(
+    `
+?${HOOK_MARKER_START}[\\s\\S]*?${HOOK_MARKER_END}
+?`,
+    "g"
+  );
+  const updated = existing.replace(pattern, "").replace(/\n{3,}/g, "\n\n");
+  fs2.writeFileSync(rcFile, updated, "utf-8");
+  console.log(`KeepGoing hook removed from ${rcFile}.`);
+  console.log(`Reload your shell config to deactivate it:
+`);
+  console.log(`  source ${rcFile}`);
+}
+
+// src/index.ts
+var HELP_TEXT = `
+keepgoing: resume side projects without the mental friction
+
+Usage:
+  keepgoing status     Show the last checkpoint for this project
+  keepgoing save       Save a new checkpoint interactively
+  keepgoing hook       Manage the shell hook
+
+Options:
+  --cwd <path>    Override the working directory (default: current directory)
+  --json          Output raw JSON (status only)
+  --quiet         Output a single summary line (status only)
+  -h, --help      Show this help text
+
+Hook subcommands:
+  keepgoing hook install    Install the shell hook into ~/.zshrc or ~/.bashrc
+  keepgoing hook uninstall  Remove the shell hook
+`;
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let command = "";
+  let subcommand = "";
+  let cwd = process.cwd();
+  let json = false;
+  let quiet = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--cwd" && i + 1 < args.length) {
+      cwd = args[++i];
+    } else if (arg === "--json") {
+      json = true;
+    } else if (arg === "--quiet") {
+      quiet = true;
+    } else if (arg === "-h" || arg === "--help") {
+      command = "help";
+    } else if (!command) {
+      command = arg;
+    } else if (!subcommand) {
+      subcommand = arg;
+    }
+  }
+  return { command, subcommand, cwd, json, quiet };
+}
+async function main() {
+  const { command, subcommand, cwd, json, quiet } = parseArgs(process.argv);
+  switch (command) {
+    case "status":
+      await statusCommand({ cwd, json, quiet });
+      break;
+    case "save":
+      await saveCommand({ cwd });
+      break;
+    case "hook":
+      if (subcommand === "install") {
+        hookInstallCommand();
+      } else if (subcommand === "uninstall") {
+        hookUninstallCommand();
+      } else {
+        console.error(
+          `Unknown hook subcommand: "${subcommand}". Use "install" or "uninstall".`
+        );
+        process.exit(1);
+      }
+      break;
+    case "help":
+    case "":
+      console.log(HELP_TEXT);
+      break;
+    default:
+      console.error(`Unknown command: "${command}". Run "keepgoing --help" for usage.`);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@keepgoingdev/cli",
+  "version": "0.1.0",
+  "description": "Terminal CLI for KeepGoing. Resume side projects without the mental friction.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "keepgoing": "./dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "prepublishOnly": "tsup"
+  },
+  "devDependencies": {
+    "@keepgoingdev/shared": "*",
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  }
+}