added documentaion and a hook build script to make onbaording easier

devs.md

@@ -63,6 +63,9 @@ npm test             # Run vitest tests (requires Docker services)
 
 ### Environment Setup
 
+- Clone with submodules: `git clone --recurse-submodules <repository-url>`
+- If you already cloned without them, run: `git submodule update --init --recursive`
+- The shared common library is provided by the `src/lib` submodule, and builds will fail if it is missing
 - Create `.env` file with `PATHS_TEST_INSTALL` pointing to test vault plug-in directories (`:` separated on Unix, `;` on Windows)
 - Development builds auto-copy to these paths on build
 

src/apps/cli/README.md

@@ -92,28 +92,39 @@ livesync-cli ./my-db pull folder/note.md ./note.md
 
 ## Installation
 
-### Build from source
+### Build from source
+
+```bash
+# Clone with submodules, because the shared core lives in src/lib
+git clone --recurse-submodules <repository-url>
+cd obsidian-livesync
+
+# If you already cloned without submodules, run this once instead
+git submodule update --init --recursive
+
+# Install dependencies from the repository root
+npm install
+
+# Build the CLI from its package directory
+cd src/apps/cli
+npm run build
+```
+
+If `src/lib` is missing, `npm run build` now stops early with a targeted message
+instead of a low-level Vite `ENOENT` error.
 
-```bash
+Run the CLI:
-# Install dependencies (ensure you are in repository root directory, not src/apps/cli)
+
-# due to shared dependencies with webapp and main library
+```bash
-npm install
+# Run with npm script (from repository root)
-# Build the project (ensure you are in `src/apps/cli` directory)
+npm run --silent cli -- [database-path] [command] [args...]
-npm run build
-```
-
-Run the CLI:
-
-```bash
-# Run with npm script (from repository root)
-npm run --silent cli -- [database-path] [command] [args...]
 # Run the built executable directly
 node src/apps/cli/dist/index.cjs [database-path] [command] [args...]
 ```
 
-### Docker
+### Docker
-
+
-A Docker image is provided for headless / server deployments. Build from the repository root:
+A Docker image is provided for headless / server deployments. Build from the repository root:
 
 ```bash
 docker build -f src/apps/cli/Dockerfile -t livesync-cli .

src/apps/cli/package.json

@@ -6,6 +6,7 @@
     "type": "module",
     "scripts": {
         "dev": "vite",
+        "prebuild": "node scripts/check-submodule.mjs",
         "build": "vite build",
         "preview": "vite preview",
         "cli": "node dist/index.cjs",

src/apps/cli/scripts/check-submodule.mjs

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const cliDir = process.cwd();
+const repoRoot = path.resolve(cliDir, "../../..");
+const requiredFiles = [
+    path.join(repoRoot, "src/lib/src/common/types.ts"),
+];
+
+const missingFiles = requiredFiles.filter((filePath) => !fs.existsSync(filePath));
+
+if (missingFiles.length === 0) {
+    process.exit(0);
+}
+
+console.error("[CLI Build Error] Required shared sources were not found.");
+console.error("This repository uses Git submodules, and the CLI depends on src/lib.");
+console.error("");
+console.error("Missing file(s):");
+for (const filePath of missingFiles) {
+    console.error(`  - ${path.relative(repoRoot, filePath)}`);
+}
+console.error("");
+console.error("Initialize submodules, then retry the CLI build:");
+console.error("  git submodule update --init --recursive");
+console.error("");
+console.error("For a fresh clone, prefer:");
+console.error("  git clone --recurse-submodules <repository-url>");
+console.error("");
+console.error("Then run:");
+console.error("  npm install");
+console.error("  cd src/apps/cli");
+console.error("  npm run build");
+
+process.exit(1);