diff options
| -rw-r--r-- | AGENTS.md | 72 | ||||
| -rw-r--r-- | CLAUDE.md | 6 |
2 files changed, 78 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cdd99cf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,72 @@ +# AGENTS.md + +Guidance for AI coding agents working in this repository. + +## What this is + +`bash-notes`: single-file bash note-taking script. Notes are plain files in +`$NOTESDIR`, indexed by a JSON database (`$DB`) managed with `jq`. Optional git +sync of the data dir to a remote. Built for use from rofi/i3 (spawns a terminal +running the editor). Only runtime dependency: `jq` (plus `git` if sync is on, +`/usr/share/dict/words` for random titles). + +## Layout and build + +`notes.sh` is a **generated file**. Never edit it directly. Edit `SOURCE/`, then +run `make`, and commit both the sources and the rebuilt `notes.sh` together. + +`make` concatenates, in this order: + +1. `SOURCE/head.sh`: shebang, license header, debug setup, `set_defaults()`, + rc file sourcing, PID file handling, `export_config`, `firstrun` +2. `SOURCE/CORE/helpers.sh`: `check_noteID`, `helptext`, `configtext`, + `random_title`, `exitwait` +3. `SOURCE/CORE/git.sh`: `gitsync`/`gitadd`/`gitedit`/`gitremove`, plus + top-level code that inits the data repo when `USEGIT` and `GITREMOTE` are set +4. `SOURCE/CORE/core-*.sh` (glob order): one command per file (add, backup, + edit, list, remove, show) +5. `SOURCE/main.sh`: `getopt` parsing and dispatch + +Since it is plain concatenation, top-level code runs in that order. A function +is callable from `main.sh` no matter which file defines it. + +Check the build is in sync: + + diff <(cat SOURCE/head.sh SOURCE/CORE/helpers.sh SOURCE/CORE/git.sh SOURCE/CORE/core-* SOURCE/main.sh) notes.sh + +## Conventions + +- `set_defaults()` in `head.sh` doubles as the template for `--userconf`: + `export_config` extracts it with sed between the `set_defaults() {` line and + the `} # end set_defaults, do not change this line.` marker, and rewrites + `VAR=${VAR:-default}` into `VAR=default`. Keep that marker line and that + assignment shape intact. +- New options: add to the `getopt` short/long lists in `main.sh`, the `case` + dispatch, `helptext`, and the usage block in `README.md`. +- DB writes go through `$TMPDB` then `mv` over `$DB`. +- Honour `$PLAIN` for output formatting. +- Indentation is mixed (tabs in most files, 4 spaces in `helpers.sh`/`git.sh`). + Match the file you are editing. +- Existing `# shellcheck disable=` comments are deliberate. Run + `shellcheck -S warning notes.sh` after changes and do not add new warnings. +- Bump `VERSION` in `head.sh` and the README ChangeLog for user-visible releases. + +## Testing + +No test suite. Verify by running in a sandbox so the real data dir, rc file, +and a GUI terminal are never touched: + + S=$(mktemp -d) + printf 'y\n' | BASEDIR=$S RCFILE=$S/rc TERMINAL=/bin/true ./notes.sh -l # firstrun + printf 'x' | BASEDIR=$S RCFILE=$S/rc TERMINAL=/bin/true ./notes.sh -a"title" + jq . $S/db.json + +Caveats: `exitwait` blocks on a keypress (feed stdin). The PID file +(`/var/tmp/notes.pid`) and `$TMPDB` (`/tmp/db.json`) are global, and starting +the script **kills any running instance**, including the user's. + +## Repo facts + +- License: CC BY-NC 4.0 (see README and `head.sh` header). No `LICENSE` file. +- `origin` pushes to both the personal git server and GitHub in one `git push`. +- `TODO` file is a scratch list, the real roadmap lives in the README "TO DO". diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0d86339 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +This file is intentionally thin. AGENTS.md is the single source of truth for +project guidance, shared across every agent tool. Edit AGENTS.md instead. + +@AGENTS.md |