notd-cli 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# notd
+
+Lightweight notes for your repo. Leave a thought, not a document.
+
+`notd` stores notes as Markdown files in a `.notd/` folder at the root of your repo. Notes are committed to git alongside your code — no external services, no databases, just files.
+
+## Installation
+
+```bash
+npm install -g notd-cli
+```
+
+## Usage
+
+```bash
+notd new        # create a new note
+notd list       # list all notes
+notd edit [id]  # edit a note's tags
+notd delete [id] # delete a note
+```
+
+If you omit the `[id]`, you'll be shown a list to pick from.
+
+## Note format
+
+Notes are stored in `.notd/` as Markdown files named after their first line:
+
+```
+.notd/
+└── fix-the-auth-bug.md
+```
+
+Each file includes frontmatter with timestamps and tags:
+
+```markdown
+---
+created: 2025-02-24T10:30:00.000Z
+updated: 2025-02-24T10:30:00.000Z
+tags:
+  - auth
+  - api
+---
+
+Fix the auth bug
+
+The token expiry check is using the wrong timezone. Need to normalise
+to UTC before comparing. See the discussion in PR #42.
+```
+
+## Requirements
+
+Node.js v18 or later.

package/bin/notd.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// This shebang line tells the OS to run this file with Node.js.
+// It's required for any npm CLI tool so the command works without typing "node" first.
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'new':
+    require('../src/commands/new');
+    break;
+  case 'list':
+    require('../src/commands/list');
+    break;
+  case 'edit':
+    require('../src/commands/edit');
+    break;
+  case 'delete':
+    require('../src/commands/delete');
+    break;
+  default:
+    console.log('Usage: notd <command>');
+    console.log('');
+    console.log('Commands:');
+    console.log('  new     Create a new note');
+    console.log('  list    List all notes');
+    console.log('  edit    Edit a note\'s tags');
+    console.log('  delete  Delete a note');
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "notd-cli",
+  "version": "0.1.0",
+  "description": "Lightweight notes for your repo. Leave a thought, not a document.",
+  "keywords": [
+    "notes",
+    "repo",
+    "cli",
+    "markdown",
+    "developer-notes",
+    "documentation"
+  ],
+  "homepage": "https://github.com/niccoates/notd#readme",
+  "bugs": {
+    "url": "https://github.com/niccoates/notd/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niccoates/notd.git"
+  },
+  "license": "MIT",
+  "author": "Nic Coates",
+  "type": "commonjs",
+  "main": "index.js",
+  "bin": {
+    "notd": "bin/notd.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  }
+}

package/src/commands/delete.js

@@ -0,0 +1,70 @@
+const fs = require('fs');
+const readline = require('readline');
+const { readNotes, deleteNote } = require('../utils/files');
+const { formatDate } = require('../utils/format');
+
+function askViaTTY(question) {
+  return new Promise(resolve => {
+    const ttyInput = fs.createReadStream('/dev/tty');
+    const rl = readline.createInterface({
+      input: ttyInput,
+      output: process.stdout,
+    });
+    rl.question(question, answer => {
+      rl.close();
+      ttyInput.destroy();
+      resolve(answer);
+    });
+  });
+}
+
+function firstLine(content) {
+  const line = content.split('\n').find(l => l.trim() !== '') || '';
+  return line.replace(/^#+\s*/, '').trim();
+}
+
+async function run() {
+  const notes = readNotes();
+
+  if (notes.length === 0) {
+    console.log('No notes yet. Run `notd new` to create one.');
+    process.exit(0);
+  }
+
+  notes.sort((a, b) => new Date(b.created) - new Date(a.created));
+
+  let note;
+  const idArg = process.argv[3];
+
+  if (idArg) {
+    const index = parseInt(idArg, 10) - 1;
+    note = notes[index];
+    if (!note) {
+      console.log(`No note at index ${idArg}. Run \`notd list\` to see available notes.`);
+      process.exit(1);
+    }
+  } else {
+    notes.forEach((n, i) => {
+      console.log(`${String(i + 1).padStart(2)}  ${formatDate(n.created)}  ${firstLine(n.content)}`);
+    });
+    const choice = await askViaTTY('\nWhich note to delete? Enter a number: ');
+    const index = parseInt(choice, 10) - 1;
+    note = notes[index];
+    if (!note) {
+      console.log('Invalid selection.');
+      process.exit(1);
+    }
+  }
+
+  const confirm = await askViaTTY(`Delete "${firstLine(note.content)}"? (y/n): `);
+
+  if (confirm.trim().toLowerCase() !== 'y') {
+    console.log('Cancelled.');
+    process.exit(0);
+  }
+
+  deleteNote(note.filepath);
+  console.log('Note deleted.');
+}
+
+run();

package/src/commands/edit.js

@@ -0,0 +1,71 @@
+const fs = require('fs');
+const readline = require('readline');
+const { readNotes, updateNote } = require('../utils/files');
+const { formatDate } = require('../utils/format');
+
+function askViaTTY(question) {
+  return new Promise(resolve => {
+    const ttyInput = fs.createReadStream('/dev/tty');
+    const rl = readline.createInterface({
+      input: ttyInput,
+      output: process.stdout,
+    });
+    rl.question(question, answer => {
+      rl.close();
+      ttyInput.destroy(); // close the stream so the process can exit cleanly
+      resolve(answer);
+    });
+  });
+}
+
+function firstLine(content) {
+  const line = content.split('\n').find(l => l.trim() !== '') || '';
+  return line.replace(/^#+\s*/, '').trim();
+}
+
+async function run() {
+  const notes = readNotes();
+
+  if (notes.length === 0) {
+    console.log('No notes yet. Run `notd new` to create one.');
+    process.exit(0);
+  }
+
+  notes.sort((a, b) => new Date(b.created) - new Date(a.created));
+
+  let note;
+  const idArg = process.argv[3];
+
+  if (idArg) {
+    const index = parseInt(idArg, 10) - 1;
+    note = notes[index];
+    if (!note) {
+      console.log(`No note at index ${idArg}. Run \`notd list\` to see available notes.`);
+      process.exit(1);
+    }
+  } else {
+    notes.forEach((n, i) => {
+      console.log(`${String(i + 1).padStart(2)}  ${formatDate(n.created)}  ${firstLine(n.content)}`);
+    });
+    const choice = await askViaTTY('\nWhich note to edit? Enter a number: ');
+    const index = parseInt(choice, 10) - 1;
+    note = notes[index];
+    if (!note) {
+      console.log('Invalid selection.');
+      process.exit(1);
+    }
+  }
+
+  const currentTags = note.tags && note.tags.length > 0 ? note.tags.join(', ') : 'none';
+  const tagsInput = await askViaTTY(`Tags (current: ${currentTags}, Enter to keep): `);
+
+  // Empty input = keep existing tags; otherwise parse the new value
+  const tags = tagsInput.trim() === ''
+    ? (note.tags || [])
+    : tagsInput.split(',').map(t => t.trim()).filter(Boolean);
+
+  updateNote(note.filepath, note.content, tags);
+  console.log('Note updated.');
+}
+
+run();

package/src/commands/list.js

@@ -0,0 +1,30 @@
+const { readNotes } = require('../utils/files');
+const { formatDate } = require('../utils/format');
+
+const notes = readNotes();
+
+if (notes.length === 0) {
+  console.log('No notes yet. Run `notd new` to create one.');
+  process.exit(0);
+}
+
+// Sort newest first using the created timestamp in frontmatter
+notes.sort((a, b) => new Date(b.created) - new Date(a.created));
+
+// Find the longest first line so we can pad everything to align nicely
+const maxTitleLength = Math.max(...notes.map(n => firstLine(n.content).length));
+
+notes.forEach((note, i) => {
+  const index = String(i + 1).padStart(2);
+  const date = formatDate(note.created);
+  const title = firstLine(note.content).padEnd(maxTitleLength);
+  const tags = note.tags && note.tags.length > 0 ? `[${note.tags.join(', ')}]` : '';
+
+  console.log(`${index}  ${date}  ${title}  ${tags}`);
+});
+
+// Returns the first non-empty line of a note, stripping any markdown heading markers
+function firstLine(content) {
+  const line = content.split('\n').find(l => l.trim() !== '') || '';
+  return line.replace(/^#+\s*/, '').trim();
+}

package/src/commands/new.js

@@ -0,0 +1,54 @@
+const fs = require('fs');
+const readline = require('readline');
+const { writeNote } = require('../utils/files');
+
+// Read raw stdin until Ctrl+D (EOF) — no readline, no prompt characters bleeding in
+function collectMultilineInput(prompt) {
+  return new Promise(resolve => {
+    console.log(prompt);
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+// After stdin closes with Ctrl+D, we can't reuse it — so open /dev/tty directly.
+// /dev/tty is the controlling terminal device and works even after stdin has ended.
+function askViaTTY(question) {
+  return new Promise(resolve => {
+    const ttyInput = fs.createReadStream('/dev/tty');
+    const rl = readline.createInterface({
+      input: ttyInput,
+      output: process.stdout,
+    });
+    rl.question(question, answer => {
+      rl.close();
+      ttyInput.destroy(); // close the stream so the process can exit cleanly
+      resolve(answer);
+    });
+  });
+}
+
+async function run() {
+  const content = await collectMultilineInput(
+    'Enter your note (press Ctrl+D on a new line when done):\n'
+  );
+
+  if (!content.trim()) {
+    console.log('No content entered. Note not saved.');
+    process.exit(0);
+  }
+
+  const tagsInput = await askViaTTY('\nTags (comma-separated, or press Enter to skip): ');
+
+  const tags = tagsInput
+    .split(',')
+    .map(t => t.trim())
+    .filter(Boolean);
+
+  const filepath = writeNote(content, tags);
+  console.log(`\nNote saved: ${filepath}`);
+}
+
+run();

package/src/utils/files.js

@@ -0,0 +1,114 @@
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+
+// Walk up from the current directory to find the nearest .git folder.
+// This lets `notd` work from any subdirectory within a repo.
+function findRepoRoot() {
+  let dir = process.cwd();
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    // If we've reached the filesystem root without finding .git, give up and use cwd
+    if (parent === dir) return process.cwd();
+    dir = parent;
+  }
+}
+
+// Returns the path to the .notd/ directory, creating it if it doesn't exist
+function getNotdDir() {
+  const root = findRepoRoot();
+  const notdDir = path.join(root, '.notd');
+  if (!fs.existsSync(notdDir)) {
+    fs.mkdirSync(notdDir);
+  }
+  return notdDir;
+}
+
+// Turns the first line of a note into a filename-safe slug
+// e.g. "Fix the auth bug!" → "fix-the-auth-bug.md"
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '') // strip anything that's not a letter, number, space, or dash
+    .replace(/\s+/g, '-')         // spaces become dashes
+    .replace(/-+/g, '-')          // collapse multiple dashes
+    .slice(0, 60);                 // cap length so filenames stay readable
+}
+
+// Writes a new note file and returns the full path
+function writeNote(content, tags) {
+  const notdDir = getNotdDir();
+  const now = new Date().toISOString();
+
+  // Use the first line of the note as the filename
+  const firstLine = content.trim().split('\n')[0];
+  const filename = `${slugify(firstLine)}.md`;
+  const filepath = path.join(notdDir, filename);
+
+  // gray-matter's stringify builds the ---frontmatter--- block for us
+  const fileContent = matter.stringify(content.trim(), {
+    created: now,
+    updated: now,
+    tags: tags,
+  });
+
+  fs.writeFileSync(filepath, fileContent, 'utf8');
+  return filepath;
+}
+
+// Reads all notes from .notd/, returns them as an array of parsed objects
+function readNotes() {
+  const notdDir = getNotdDir();
+  const files = fs.readdirSync(notdDir).filter(f => f.endsWith('.md'));
+
+  return files.map(filename => {
+    const filepath = path.join(notdDir, filename);
+    const raw = fs.readFileSync(filepath, 'utf8');
+    const parsed = matter(raw);
+    return {
+      filename,
+      filepath,
+      // The frontmatter fields (created, updated, tags)
+      ...parsed.data,
+      // The note body (everything after the ---)
+      content: parsed.content.trim(),
+    };
+  });
+}
+
+// Updates an existing note, preserving its created timestamp.
+// If the first line changed, the file is renamed to match the new slug.
+function updateNote(filepath, content, tags) {
+  const notdDir = getNotdDir();
+
+  // Read the existing file so we can preserve the original created date
+  const raw = fs.readFileSync(filepath, 'utf8');
+  const parsed = matter(raw);
+
+  const fileContent = matter.stringify(content.trim(), {
+    created: parsed.data.created,
+    updated: new Date().toISOString(),
+    tags,
+  });
+
+  // Recalculate the slug in case the first line changed
+  const firstLine = content.trim().split('\n')[0];
+  const newFilepath = path.join(notdDir, `${slugify(firstLine)}.md`);
+
+  fs.writeFileSync(newFilepath, fileContent, 'utf8');
+
+  // Remove the old file if it was renamed
+  if (newFilepath !== filepath) {
+    fs.unlinkSync(filepath);
+  }
+
+  return newFilepath;
+}
+
+function deleteNote(filepath) {
+  fs.unlinkSync(filepath);
+}
+
+module.exports = { writeNote, updateNote, deleteNote, readNotes, getNotdDir };

package/src/utils/format.js

@@ -0,0 +1,12 @@
+// Formats an ISO date string (e.g. "2025-02-24T10:30:00.000Z") into a short readable date
+// We only need the date portion for list display — the time isn't useful there
+function formatDate(isoString) {
+  const date = new Date(isoString);
+  return date.toLocaleDateString('en-GB', {
+    day: '2-digit',
+    month: 'short',
+    year: 'numeric',
+  });
+}
+
+module.exports = { formatDate };