chore: resolve remaining PR review nits and CLI hardening

Author: CI Bot

.gitignore

@@ -9,17 +9,17 @@ git-cms-test-*/
 .obsidian/
 
 # LaTeX artifacts
-*.aux
-*.log
-*.out
-*.toc
-*.synctex.gz
-*.fls
-*.fdb_latexmk
-*.bbl
-*.blg
-*.idx
-*.ind
-*.ilg
-*.lof
-*.lot
+docs/adr-tex-2/*.aux
+docs/adr-tex-2/*.log
+docs/adr-tex-2/*.out
+docs/adr-tex-2/*.toc
+docs/adr-tex-2/*.synctex.gz
+docs/adr-tex-2/*.fls
+docs/adr-tex-2/*.fdb_latexmk
+docs/adr-tex-2/*.bbl
+docs/adr-tex-2/*.blg
+docs/adr-tex-2/*.idx
+docs/adr-tex-2/*.ind
+docs/adr-tex-2/*.ilg
+docs/adr-tex-2/*.lof
+docs/adr-tex-2/*.lot

GETTING_STARTED.md

@@ -1,6 +1,6 @@
 # Getting Started with Git CMS
 
-This quick guide is the lightweight entry point. For the full walkthrough, use [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md).
+This quick guide is the lightweight entry point. For the full Docker-focused walkthrough in the docs folder, see [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md).
 
 ---
 

README.md

@@ -72,11 +72,13 @@ docker compose run --rm test
 ## Installation
 
 ```bash
-npm install -g git-cms
-# or linked locally
+# From source (recommended until npm publish):
 git clone https://github.com/flyingrobots/git-cms.git
 cd git-cms
 npm link
+
+# After publish, global install will work:
+# npm install -g git-cms
 ```
 
 ## Usage
@@ -114,13 +116,13 @@ Content is stored in `refs/_blog/articles/<slug>`.
 echo "# Hello World" | git cms draft hello-world "My First Post"
 ```
 
-### 3. List Articles
+### 4. List Articles
 ```bash
 git cms list
 # -> refs/_blog/articles/hello-world My First Post
 ```
 
-### 4. Publish
+### 5. Publish
 Publishing fast-forwards `refs/_blog/published/<slug>` to match the draft.
 
 ```bash

TESTING_GUIDE.md

@@ -203,12 +203,15 @@ docker compose run --rm test
 
 ## Advanced: Local Installation (Not Recommended Initially)
 
-If you understand what git-cms does and want to install it globally on your host:
+If you understand what git-cms does and want host CLI access:
 
 ```bash
-npm install -g git-cms
-# OR
-cd git-cms && npm link
+# From source (recommended until npm publish is complete):
+cd git-cms
+npm link
+
+# After publish, global install will work:
+# npm install -g git-cms
 ```
 
 **⚠️ WARNING:** Only use git-cms in dedicated repositories:

bin/git-cms.js

@@ -10,19 +10,22 @@ async function main() {
   const cwd = process.cwd();
   const refPrefix = process.env.CMS_REF_PREFIX || DEFAULT_REF_PREFIX;
 
-  const cms = new CmsService({ cwd, refPrefix });
-
   try {
+    const cms = new CmsService({ cwd, refPrefix });
     switch (cmd) {
       case 'draft': {
         const [rawSlug, title] = args;
         if (!rawSlug || !title) throw new Error('Usage: git cms draft <slug> "Title" < content.md');
         const slug = canonicalizeSlug(rawSlug);
-        
+
+        if (process.stdin.isTTY) {
+          throw new Error('Usage: git cms draft <slug> "Title" < content.md');
+        }
+
         const chunks = [];
         for await (const chunk of process.stdin) chunks.push(chunk);
         const body = Buffer.concat(chunks).toString('utf8');
-        
+
         const res = await cms.saveSnapshot({ slug, title, body });
         console.log(`Saved draft: ${res.sha} (${res.ref})`);
         break;
@@ -31,7 +34,7 @@ async function main() {
         const [rawSlug] = args;
         if (!rawSlug) throw new Error('Usage: git cms publish <slug>');
         const slug = canonicalizeSlug(rawSlug);
-        
+
         const res = await cms.publishArticle({ slug });
         console.log(`Published: ${res.sha} (${res.ref})`);
         break;
@@ -66,12 +69,12 @@ async function main() {
         process.exit(1);
     }
   } catch (err) {
-    console.error(`Error: ${err.message}`);
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
   }
 }
 
 main().catch((err) => {
-  console.error(`Error: ${err.message}`);
+  console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
   process.exit(1);
 });

docs/ADR.md

@@ -764,9 +764,11 @@ graph TB
 
 **Deployment Steps:**
 ```bash
+# One-time setup (from your cloned git-cms repo):
+# npm link
+
 cd ~/blog
 git init
-npm install -g git-cms
 echo "# My Post" | git cms draft my-post "Title"
 git cms publish my-post
 ```

docs/adr-tex-2/figures/context.tex

@@ -2,7 +2,7 @@
     \node [block] (Author) {Author\\(Human)};
     \node [block, below=1cm of Author] (GitCMS) {\textbf{git-cms}\\(Node.js App)};
     \node [block, right=2cm of GitCMS] (Stargate) {git-stargate\\(Git Gateway)};
-    \node [block, below=1cm of GitCMS] (LocalRepo) {.git/objects/\\(Local Repository)};
+    \node [block, below=1cm of GitCMS] (LocalRepo) {\texttt{.git/objects/}\\(Local Repository)};
     \node [block, right=2cm of Stargate] (PublicMirror) {Public Mirror\\(GitHub/GitLab)};
 
     \draw [line] (Author) -- node [align=center, scale=0.8] {CLI/HTTP API} (GitCMS);

docs/adr-tex-2/figures/responsibilities.tex

@@ -12,6 +12,6 @@
     \draw [line] (CMS.east |- CAS.west) -- (CAS.west);
     \draw [line] (CMS.east |- V.west) -- (V.west);
 
-    \draw [dashed-line] (EG.east) -- ++(0.5,0) |- (PL.east);
-    \draw [dashed-line] (CAS.east) -- ++(0.5,0) |- (PL.east);
+    \draw [dashed-line] (EG.east) -- ++(0.5,0) |- (PL.north east);
+    \draw [dashed-line] (CAS.east) -- ++(0.5,0) |- (PL.south east);
 \end{tikzpicture}

docs/adr-tex-2/sections/02-constraints.tex

@@ -20,7 +20,7 @@ \subsection{Technical Constraints}
 \textbf{TC-4: No Database Indexes} \\
 Traditional databases provide B-tree indexes for fast lookups. Git's ref enumeration is linear (\texttt{O(n)} for listing all refs in a namespace).
 
-\textbf{Mitigation:} Use ref namespaces strategically (e.g., \texttt{refs/\_blog/articles/<slug>}) to avoid polluting the global ref space.
+\textbf{Mitigation:} Use ref namespaces strategically (e.g., \texttt{refs/\_blog/articles/\textless slug\textgreater}) to avoid polluting the global ref space.
 
 \subsection{Regulatory Constraints}
 

docs/adr-tex-2/sections/03-context.tex

@@ -80,7 +80,7 @@ \subsubsection{In Scope}
     \item Encrypted asset storage (images, PDFs)
     \item Full version history via Git log
     \item CLI and HTTP API access
-    \item Multi-runtime support (Node, Bun, Deno)
+    \item Aspirational: Multi-runtime support (Node, Bun, Deno)
 \end{itemize}
 
 \subsubsection{Out of Scope}