Add DX tooling — biome, lefthook, CI, and task runner

.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /Users/nahiyan/Development/ghost log --oneline)",
+      "Bash(git:*)",
+      "Bash(pnpm install:*)",
+      "Bash(pnpm build:*)",
+      "Bash(pnpm test:*)",
+      "Bash(node:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx vitest:*)",
+      "Bash(npx biome:*)",
+      "Bash(just check:*)",
+      "Bash(just build:*)",
+      "Bash(npx lefthook:*)",
+      "Bash(mv commit-msg.pre-entire commit-msg)",
+      "Bash(mv post-commit.pre-entire post-commit)",
+      "Bash(mv pre-push.pre-entire pre-push)",
+      "Bash(mv prepare-commit-msg.pre-entire prepare-commit-msg)",
+      "Bash(pnpm:*)"
+    ]
+  }
+}

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+
+  test:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test

.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.tsbuildinfo
+.DS_Store

.npmrc

@@ -0,0 +1,2 @@
+shamefully-hoist=false
+strict-peer-dependencies=true

biome.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": ["**", "!**/test/fixtures"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noExplicitAny": "warn",
+        "noAssignInExpressions": "warn"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  }
+}

justfile

@@ -0,0 +1,47 @@
+# Default recipe
+default:
+    @just --list
+
+# ── Dev Environment ──────────────────────────────────────────
+
+# Install dependencies
+setup:
+    pnpm install
+
+# ── Build & Check ────────────────────────────────────────────
+
+# Run all checks (lint, format, typecheck, file sizes)
+check:
+    pnpm check
+
+# Format code
+fmt:
+    pnpm fmt
+
+# Check formatting without modifying
+fmt-check:
+    pnpm exec biome format .
+
+# Build all packages
+build:
+    pnpm build
+
+# Full CI gate
+ci: check test build
+
+# ── Test ─────────────────────────────────────────────────────
+
+# Run unit tests
+test:
+    pnpm test
+
+# Run tests in watch mode
+test-watch:
+    pnpm test:watch
+
+# ── Utilities ────────────────────────────────────────────────
+
+# Clean build artifacts
+clean:
+    pnpm clean
+    rm -rf node_modules packages/*/node_modules

lefthook.yml

@@ -0,0 +1,16 @@
+pre-commit:
+  commands:
+    format:
+      run: npx biome format --write . && npx biome check --fix . && git add -u
+    check:
+      run: just check
+
+pre-push:
+  parallel: true
+  commands:
+    check:
+      run: just check
+    test:
+      run: just test
+    build:
+      run: just build

package.json

@@ -0,0 +1,28 @@
+{
+  "name": "ghost",
+  "private": true,
+  "description": "Design drift detection system",
+  "license": "Apache-2.0",
+  "packageManager": "pnpm@10.12.4",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "tsc --build --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --build",
+    "check": "biome check . && pnpm typecheck && pnpm check:file-sizes",
+    "check:file-sizes": "node scripts/check-file-sizes.mjs",
+    "fmt": "biome format --write .",
+    "lint": "biome lint ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.0",
+    "@types/node": "^22.0.0",
+    "lefthook": "^2.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

packages/ghost-cli/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "ghost-cli",
+  "version": "0.1.0",
+  "description": "CLI for ghost design drift detection",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "ghost": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --build"
+  },
+  "dependencies": {
+    "@ghost/core": "workspace:*",
+    "citty": "^0.1.6"
+  }
+}

packages/ghost-cli/src/bin.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import {
+  formatCLIReport,
+  formatJSONReport,
+  loadConfig,
+  scan,
+} from "@ghost/core";
+import { defineCommand, runMain } from "citty";
+
+const scanCommand = defineCommand({
+  meta: {
+    name: "scan",
+    description: "Scan for design drift",
+  },
+  args: {
+    config: {
+      type: "string",
+      description: "Path to ghost config file",
+      alias: "c",
+    },
+    format: {
+      type: "string",
+      description: "Output format: cli or json",
+      default: "cli",
+    },
+    "no-color": {
+      type: "boolean",
+      description: "Disable colored output",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    try {
+      const config = await loadConfig(args.config);
+      const report = await scan(config);
+
+      const output =
+        args.format === "json"
+          ? formatJSONReport(report)
+          : formatCLIReport(report);
+
+      process.stdout.write(output);
+      process.exit(report.summary.errors > 0 ? 1 : 0);
+    } catch (err) {
+      console.error(
+        `Error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      process.exit(2);
+    }
+  },
+});
+
+const main = defineCommand({
+  meta: {
+    name: "ghost",
+    version: "0.1.0",
+    description: "Design drift detection",
+  },
+  subCommands: {
+    scan: scanCommand,
+  },
+});
+
+runMain(main);

packages/ghost-cli/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../ghost-core" }]
+}

packages/ghost-core/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ghost/core",
+  "version": "0.1.0",
+  "description": "Design drift detection engine",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --build"
+  },
+  "dependencies": {
+    "diff": "^7.0.0",
+    "jiti": "^2.4.0",
+    "pixelmatch": "^6.0.0",
+    "pngjs": "^7.0.0",
+    "postcss": "^8.5.0"
+  },
+  "optionalDependencies": {
+    "playwright": "^1.50.0"
+  },
+  "devDependencies": {
+    "@types/diff": "^6.0.0",
+    "@types/pngjs": "^6.0.0"
+  }
+}