📂 sync-cli (shadow-docs)

AI-Powered Git Workspace Documentation Synchronizer CLI Daemon

An intelligent developer workspace utility that monitors repository states, captures structural diffs, and integrates with the Google Gemini API to automatically generate and append codebase change summaries to STRUCTURE.md.

⚙️ Core Architecture & Flow

  [npx shadow-docs sync]  OR  [shadow-docs sync]
          │
          ▼
   (Git Verification) ➔ ensureCleanTree()
          │
     ┌────┴────────────────────────┐
     ▼                             ▼
[No Lock File]               [Has Lock File]
  └─► Baseline created.        ├─► git diff <lastHash> HEAD
  └─► Save current hash.       ├─► Read existing STRUCTURE.md (History)
  └─► Gather git ls-files (Structure)
                               │
                               ▼
                        (Ultimate Context)
                               │
                               ▼
                       [AIManager (Gemini)]
                               │
                               ▼
                  (Update Docs & Save lock state)

🛠️ Installation & Setup

1. Install Dependencies

Ensure you are in the project root directory and run:

npm install

This installs the required dependencies including @google/generative-ai for AI calls, commander for CLI structure, and chalk for console coloring.

2. Environment Configuration

Create a .env file in the root folder and add your Google Gemini API key:

GOOGLE_GEMINI_API_KEY=your_gemini_api_key_here

3. Compile the Codebase

Compile the TypeScript files using the local TS compiler config:

npm run build

This runs the TS compiler (tsc), transpiling TypeScript source files into executable ES modules inside the dist/ directory.

🚀 CLI Commands & Usage

The CLI currently exposes one primary command: sync.

Running the CLI Locally (via npx)

To test or execute the synchronization command directly from the build distribution:

npx shadow-docs sync

Running the CLI Globally (Recommended)

You can link the executable binary globally to your local system path:

npm link

After linking, you can run the CLI from any target repository workspace on your machine directly:

shadow-docs sync

What the sync Command Does:

1. Validates Git Tree Cleanliness: Checks that your working tree has no uncommitted changes (ensureCleanTree). If there are dirty files, it aborts execution to maintain a stable commit-based baseline.
2. Baseline Initialization (First Run): If .shadow-lock does not exist, it saves the current HEAD commit hash in .shadow-lock as a starting baseline. No documentation is written, and it prints Baseline created!.
3. Diff Comparison (Subsequent Runs): On later runs, it compares the current HEAD commit hash against the lastHash stored in .shadow-lock.
4. Generates Context Prompt: If changes exist, it extracts the code diff, maps the project file listing (git ls-files), and reads the existing documentation history (STRUCTURE.md).
5. Generates and Appends Summary: Sends the full context to the Google Gemini model and appends the returned bulleted change summary to STRUCTURE.md without wiping existing records.

📂 Repository Directory Layout

shadow-docs/
├── src/
│   ├── commands/
│   │   └── sync.ts      # Main sync command orchestrator
│   ├── lib/
│   │   ├── ai.ts        # Gemini API prompt builder & content generator
│   │   └── git.ts       # Git status, diff, & file listings
│   ├── utils/
│   │   └── store.ts     # State management (.shadow-lock & STRUCTURE.md)
│   └── index.ts         # Commander CLI entrypoint registration
├── tsconfig.json        # TypeScript compiler parameters
└── package.json         # Package configuration and script definitions

🔒 State Persistence Specifications

• .shadow-lock: A lightweight state configuration tracking the last synchronized commit hash and date:

  {
    "lastHash": "7083be62ee1e594ff1d81cbce7bed79ace4ee5a4",
    "updatedAt": "2026-07-12T14:44:56Z"
  }

• STRUCTURE.md: The persistent documentation diary. The tool automatically appends updates to this file chronologically:

  ## 🗓️ Update: YYYY-MM-DD
  * Summary of code modifications generated by the model.

🚫 Constraints & Safety Rules

• ❌ No Dirty Trees: The tool will abort execution if uncommitted active changes exist.
• ❌ No Environment Bypass: Requires a valid GOOGLE_GEMINI_API_KEY to be loaded before generating summaries.
• ❌ No Manual Lock Modifications: Modifying .shadow-lock manually might cause desynchronized states.