Notes for coding agents (and people) working on diffdeck. The README covers what it does and how to run it; this file covers the things that are easy to break.
- Simple first. KISS, DRY, no speculative abstractions. Plain JavaScript (no TypeScript), React 19, Vite, the
gitCLI. No runtime dependencies: everything indevDependencies, React and the icons are bundled intodist/. - Read-only toward repos. diffdeck never commits, fetches, checks out or writes anything inside a repo. All git calls go through
server/git.jsand must stay read-only. Its only state is~/.diffdeck.json. - Never run a repo's code. A repo's own
.git/configcan name programs for git to run, and a watched folder may hold a repo someone else made. Every git call must keep them off (see Server). - Windows, macOS and Linux. Paths may use
\. Usepathon the server,execFile(never a shell), and test anything path-related with a Windows path in mind. - Plain words in the UI. Short, human copy ("Never pushed", "Stop watching this folder?"), no jargon.
server/git.jsis the only place that runs git, throughgit(), which putsSAFEin front of every call:--no-optional-locks(status doesn't touch the index),core.quotepath=false(non-ASCII paths stay readable),core.fsmonitor=falseandlog.showSignature=false(a repo's config can't makestatusrun a hook orlogrungpg.program).status()never throws: a broken repo comes back as{ error }and shows as an Error row.- Filter commands are the third way a repo's config runs code:
git statusrunsfilter.<name>.cleanon files it re-reads.filterOff(dir)blanks every filter the repo's own config defines (-c filter.x.clean=), except git-lfs's own commands. It reads the config text first and only asks git (git config --local --includes --get-regexp ^filter\.) when that text mentionsfilterorinclude, so most repos cost no extra process. Status runs with--ignore-submodules=dirtyso git never steps into a submodule under the parent's settings; submodules are nested repos with their own row.server/git.test.jsproves all of this against a repo whose config points both at a script: keep that test passing. Any new git command needs the same thought: does a repo setting make it run something? - Status comes from
git status --porcelain=v2 --branch --show-stash,git log -5andgit remote -v.filesis capped at 200, butchangedis the real count.webUrl()strips credentials, so only a clean https URL ever reaches the page. pkgcomes fromreadPkg()inserver/api.js: the repo'spackage.jsonscripts, dependencies and devDependencies (string values only), ornullwhen there is none. The page (src/Pkg.jsx) shows ten of each and the rest in a side sheet, a native<dialog>like the others.- Discovery (
server/api.js): a watched path is either a repo or a folder of repos (one level down). Every repo found is checked one more level down for nested repos, which carryparent. A repo found twice is listed once. - Added paths are cleaned: surrounding quotes stripped (Explorer's "Copy as path"),
~expanded, the Windows drive letter uppercased (sov:\andV:\are the same root). load()refuses to go on if~/.diffdeck.jsonexists but can't be parsed, so a hand-edited typo is never overwritten. Missing file means empty config.- Every route answers with the full fresh list (
list()), so the page has one code path:run(url, opts)insrc/App.jsxsets the data. Keep new routes that way. The only exception isGET /ping. - Security: the CLI listens on 127.0.0.1 only and answers only to localhost Host headers (DNS rebinding). In
api(), before any route: aSec-Fetch-Siteother thansame-originornonegets 403, reads included, so another site (or another localhost port, which counts as same-site) can't make diffdeck run git in a loop; non-GET requests with a foreignOriginget 403; POSTs must beapplication/json, which another site can't send without a CORS preflight that nothing answers. A request with noSec-Fetch-Siteis a script (a secondnpx diffdeckpinging) and passes. Keep all three in front of any new route;server/api.test.jschecks the first. - The CLI's static server answers a URL that doesn't decode with 400 instead of throwing, which would take the process down. Paths that leave
dist/get the page. - Port 4747 is fixed on purpose: the theme lives in localStorage per origin. A second
npx diffdeckfinds the first throughGET /api/pingand just opens it; if the port belongs to something else it tries the next one (unless--portwas given). pnpm devmounts the sameapihandler inside Vite (vite.config.js), so dev and the CLI behave the same.server/pickFolder.jsopens the OS folder dialog behind Browse (PowerShell, osascript, zenity). It resolves to an empty string when cancelled. It deliberately has nowindowsHide, which would hide the dialog itself.
- Config shape:
roots: [path],fields: [{ key, desc, type, default?, repo? }],meta: { "<repo path>": { [key]: value } }andabout: { "<repo path>": text }, the repo description (setAbout,POST /about, up to 1,000 characters, mirrored asLIMITinsrc/About.jsx,r.abouton the page). - A description renders through
inline()insrc/inline.js:*bold*,_italic_,[text](url)and bare URLs, as tokens turned into React elements, never HTML. Only http(s) links passsafeUrl; anything else stays text. Keep it that way: nodangerouslySetInnerHTML. - Types:
boolean,string,text,date(YYYY-MM-DD, what<input type="date">gives). - Fields are defined globally, values are per repo. A field without
repois Global (every repo has it); withrepoit is Local to that one path.fieldsFor(fields, path)gives a repo's fields, globals first, and every UI place (list rows, details, search, the dialog) goes through it. A field is identified bykeyplusrepo, so edits and deletes send both (DELETE /fields?key=&repo=). - Names are unique among the fields one repo can see: globals never share a name, and a local can't take a global's name (or a global a local's), so
meta[path][key]is never ambiguous. Two repos may each have a local with the same name. Scope is fixed at creation; there is no promote or demote. server/meta.jsholds all the rules as pure functions (saveField,removeField,setValue,setAbout,withMeta). The API and the demo both use them, so they must stay free of Node APIs. Validation lives there: name up to 40 characters, description up to 200, short text up to 200 with no line breaks, long text up to 10,000.src/Meta.jsxmirrors the text limits asmaxLength(LIMIT); change both together.- Empty values (
'',false,null) are never stored; they delete the key, and a repo with no values left is dropped frommeta. A Yes / No field is therefore eithertrueor absent. The one exception is thenullmarker for fields with a default, below. - A field may have a
default(the dialog's NULL box, checked, means none).withMetafills it in for repos without their own value. Clearing a value on a field with a default storesnullinstead of deleting the key, so the repo stays empty;withMetadrops nulls, so the page never sees one. Dropping the default drops those nulls too. - Renaming a field (
was→key) moves its values; a type change keeps only values that fit the new type. Field names that exist onObject.prototype(constructor,__proto__, …) are refused, so plainobj[key]lookups stay safe. - Values and local fields are keyed by the repo's absolute path. Moving a repo loses its metadata; removing a watched folder keeps it (it comes back if you re-add the folder).
- The fields dialog is opened from one repo's details (
FieldsDialog repo={r}): it lists the globals and that repo's locals, and the scope choice ("Every repo" / "Only “name”") shows only when adding. The form also sets the default value, with a NULL box for none. - Inputs in the details pane are uncontrolled and keyed by their saved value, so a fresh value from the server remounts them while the input you moved to keeps focus. Text and dates save on blur or Enter (Ctrl+Enter in long text), switches on change, and nothing is sent when the value didn't change. Esc in an input undoes the edit and stops propagation, so it doesn't close the pane.
- Inbox layout: the list (
aside.side) on the left, the open repo (main) on the right, each scrolling on its own inside a100dvhpage. Under 860px only one shows: the list, or the open repo with its X going back. - The list is a tree of groups: a top-level repo plus its nested repos (
kids), which sit indented under it on guide lines and fold with the count button that leads the parent's third line, before its tags, or a double-click on the parent row (folded, a Set of parent paths). There is no fold-arrow column, so rows keep their width. Filters, search and sort work on groups; a group shows if the parent or any kid matches. Search covers contents only (contents(): name, branch, path, description, commit subjects, file paths) andHihighlights matches; metadata has its own filters (src/Filters.jsx,metaHit), one select per field, with a filter on a local field matching only the repo that has it.rowsRefholds the rows on screen in order, which is what the arrow keys walk. - Details pane (
Detailsinsrc/Repo.jsx): title, then a full-width row with the description (src/About.jsx, edited in place) and the path, the actions (copy path and VS Code on the left, the remote on the right), status, files and commits, scripts and dependencies (src/Pkg.jsx), metadata. - Status:
badges()insrc/Repo.jsxdecides the pills and their tone (bad,warn,ok, plain). A badge'shintis a caveat for its tooltip: behind is only as fresh as the last fetch. Uncommitted files get plain words fromfileKind(), never git's two-letter code. Each row has a status dot with the reasons in a tooltip; a folded parent's dot also covers its hidden kids. - In demo mode an Empty state button in the top bar swaps
datafor an emptyview, so the hosted demo can show the first-run page. - A click anywhere on a row opens the repo: the handler is on the
.rowdiv, and the row's button has none of its own (its click bubbles up, so the keyboard takes the same path). The fold button and the status dot stay out of it. Opening a repo scrollsmainto the top; under 860px, where the page itself scrolls,listYremembers where the list was and closing goes back there. - Keys outside inputs and dialogs:
/focuses search, up and down move the selection (also while typing in search), Esc closes the open repo. Esc in search clears it, then blurs, and stops there. Watched folders and the add bar live in a native<details>under the list; with no folders yet, the add bar sits in the empty state instead. - The page refreshes on window focus (coming back from the editor) and every
AUTOminutes (5) while the tab is visible; the Refresh button's tooltip says so.refresh()dedupes overlapping calls throughinflight. - Tooltips: write a plain
title="".<TitleTips />(src/Tip.jsx, rendered once inApp) shows any title as a styled bubble after 1.5s, in a manual popover so it sits above dialogs. While hovered the title moves todata-title, so the browser's own tooltip never doubles it.<Tip>stays for the status dot, which shows at once and holds rich content. - Dialogs are native
<dialog>withshowModal():useConfirm()insrc/Confirm.jsxandFieldsDialoginsrc/Meta.jsx. Render a confirm outside another dialog's React tree, or its Esc reaches the outer dialog'sonCancel. The details pane ignores Esc while any dialog is open. - Errors from the API show in the page notice;
FieldsDialogshows the sameerror, because the page notice is hidden behind the modal.
src/app.css, one file, tokens from the cdn.farm design system ("Glacier" accent). Light and dark are[data-theme]on<html>, set inindex.htmlbefore first paint to avoid a flash.- Breakpoints: 860px (one pane at a time, the page scrolls as a whole), 640px (phone: icon-only Refresh, the empty-state add bar wraps, tooltips fixed along the bottom of the screen) and 420px (small phone: rows rearrange, pills under the name and branch and commit on their own lines, filters 2 by 2, detail actions in a grid). Inputs are 16px on phones so iOS doesn't zoom. In the list the tooltip opens to the right of the dot, so the pane's edge never clips it.
- Long labels shorten with an ellipsis (
min-width: 0plusoverflow: hiddenon a<span>), never by overflowing the page.
pnpm screenshot(scripts/screenshot.js) builds the demo, serves it with Vite'spreview()and savesdocs/screenshot.pngfor the README with the Chrome, Edge or Chromium already installed. It captures at 2x, thensharp(dev only, never shipped) scales it to 1600px wide and writes a 256-colour palette PNG, about a third of the capture's size. Chrome runs async with its own temp profile, because a sync call blocks the preview server in the same process, and the script waits for the file because on Windows chrome.exe can return before it is written. The page opens a repo from?open=<repo path>and unfolds the metadata filters with?filters, which the script uses. Rerun it after visible UI changes.vite --mode demoswapsapi()fordemoApi()fromsrc/demo.js(dynamically imported, so normal builds never include it). It builds todist-demo/with relative paths for GitHub Pages (.github/workflows/demo.yml).- The sample data must be shaped exactly like
GET /api/repos. When the API shape changes, updatesrc/demo.jstoo. Times and dates are relative to now so the demo never ages. Metadata edits work in memory; adding or removing watched folders explains that it is a demo.
pnpm testrunsnode --test, which picks up every*.test.js:server/(git parsing and the repo-config guard, the API's origin check, metadata rules) andsrc/inline.test.js(description markdown). Plainnode:testandassert, no framework. Test files are left out of the npm package.- Check
pnpm buildandpnpm build:demoafter UI changes. - Releases:
pnpm release(or:minor,:major,:beta) from a cleanmain. Agents never run a release: notpnpm release*,npm versionornpm publish. They make a version commit and a git tag before the publish, which needs the owner's npm login and security key and so fails, leaving a stray bump and tag behind. The owner runs it by hand in their own terminal (npm login,npm whoami,pnpm release; see the README). Note user-facing changes inCHANGELOG.mdunder Unreleased. - Commits: plain human titles, no
feat:style prefixes, no co-author trailers, no URLs in messages.