# Auto-Sync: Keeping Service Docs Up to Date

## Overview

The `sync.sh` script extracts metadata from actual service repositories (package.json, Pipfile, Cargo.toml, Makefile, etc.) and appends it to the corresponding `services/*.md` file in insights-ai. This ensures AI agents always have current dependency versions, available commands, and project structure.

## How It Works

1. For each service, the script detects the project type (Node.js, Python, Rust, dbt)
2. Reads relevant config files from the service repo
3. Generates a metadata block wrapped in `<!-- SYNC:START -->` and `<!-- SYNC:END -->` markers
4. Appends/replaces this block at the bottom of `services/<service>.md`

**Hand-written content is never modified.** Only the auto-generated block between the SYNC markers is touched.

### What Gets Extracted

| Service Type | Files Read | Metadata Extracted |
|-------------|-----------|-------------------|
| **Node.js** | package.json, .nvmrc, tsconfig.json | Name, version, engines, scripts, key dependencies, TS config |
| **Python** | Pipfile / requirements.txt, .python-version, Makefile | Python version, dependencies, Makefile targets |
| **Rust** | Cargo.toml, rust-toolchain.toml, Makefile | Package info, dependencies, Rust version, Makefile targets |
| **dbt** | dbt_project.yml, Pipfile, Makefile, packages.yml | dbt project config, dependencies, targets, dbt packages |
| **All** | Directory listing | Top-level directory structure |

## Manual Usage

```bash
cd insights-ai

# Sync all 12 services
./sync.sh

# Sync a single service
./sync.sh graphql-product

# Preview changes without writing (dry run)
./sync.sh --dry-run

# Sync and show git diff
./sync.sh --diff

# Dry run for one service
./sync.sh --dry-run graphql-product
```

## Claude Code Hook Integration

Add this to your `~/.claude/settings.json` to auto-sync when you edit service code:

```json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "\"$(git rev-parse --show-toplevel 2>/dev/null || echo .)/../insights-ai/sync.sh\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}
```

This runs sync.sh at the end of every Claude Code session, ensuring docs are always refreshed after coding work.

For a lighter touch, sync only when specific files change:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE '(package\\.json|Pipfile|Cargo\\.toml|dbt_project\\.yml|Makefile)'; then \"$(git rev-parse --show-toplevel 2>/dev/null || echo .)/../insights-ai/sync.sh\" 2>/dev/null || true; fi"
          }
        ]
      }
    ]
  }
}
```

## Git Pre-Commit Hook

To sync before every commit in insights-ai:

```bash
# Create the hook
cat > insights-ai/.git/hooks/pre-commit << 'EOF'
#!/usr/bin/env bash
# Auto-sync service docs before committing
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
"${SCRIPT_DIR}/sync.sh" 2>/dev/null || true
git add services/*.md 2>/dev/null || true
EOF

chmod +x insights-ai/.git/hooks/pre-commit
```

## Per-Service Repo Hook

To sync when committing changes in a service repo:

```bash
# Example: in graphql-product/.git/hooks/pre-commit
cat > graphql-product/.git/hooks/pre-commit << 'EOF'
#!/usr/bin/env bash
INSIGHTS_AI="$(dirname "$(pwd)")/insights-ai"
if [[ -x "${INSIGHTS_AI}/sync.sh" ]]; then
    "${INSIGHTS_AI}/sync.sh" "$(basename "$(pwd)")" 2>/dev/null || true
fi
EOF

chmod +x graphql-product/.git/hooks/pre-commit
```

## Output Format

The sync block looks like this in a service doc:

```markdown
<!-- SYNC:START -->
<!-- Auto-generated by sync.sh on 2026-04-01 12:00 UTC. Do not edit manually. -->

### Extracted Metadata

**Service type:** node
**Last synced:** 2026-04-01 12:00 UTC

#### Package Info

    Name: graphql-product
    Version: 1.0.0
    Node: >=24.0.0

#### Available Scripts

    build, lint, start, test, test:unit, test:integration, ...

#### Key Dependencies

    @apollo/server: ^4.0.0
    @theorchard/datasource-ows: ^2.0.0
    ...

#### Directory Structure (top-level)

    src, tests, scripts, ...

<!-- SYNC:END -->
```

## Troubleshooting

### "parse error" in extracted metadata

The script uses `python3` to parse JSON files (package.json, tsconfig.json). Ensure Python 3 is installed:

```bash
python3 --version
```

### Service directory not found

The script looks for service repos as siblings of the insights-ai directory:

```
Sony/
├── insights-ai/    # This repo
├── graphql-product/ # Must be here
└── ows-analytics/   # Must be here
```

If your repos are elsewhere, create symlinks or adjust `PARENT_DIR` in sync.sh.

### No changes after sync

If `./sync.sh --diff` shows no changes, the docs are already current. The sync block includes a timestamp, so re-running will always update the "Last synced" date even if nothing else changed.