packages-scripts/git-hooks/README.md

Git Hooks for @packages Workspace

Git hooks that automate development workflows across all packages.

Available Hooks

post-push-dev-publish

Automatically publishes dev versions after successful git push.

Features:

• ✅ Non-blocking (runs in background)
• ✅ Respects package metadata (_.publish, [tool.lilith].publish)
• ✅ Works with both TypeScript and Python packages
• ✅ Logs to ~/.local/log/dev-publish/
• ✅ Graceful error handling

Behavior:

1. Detects package type (TypeScript or Python)
2. Checks if package is marked for publishing
3. Runs dev-publish in background after push
4. Logs output to timestamped file
5. Exits immediately (doesn't block git push)

Installation

Install for All Packages

cd ~/Code/@packages
./scripts/git-hooks/install-hooks.sh --all

This scans the workspace and installs hooks in all git repositories.

Install for Single Package

cd @config/yaml-config
../../scripts/git-hooks/install-hooks.sh --package .

Interactive Installation

./scripts/git-hooks/install-hooks.sh

Prompts for installation target:

1. All packages (scan workspace)
2. Current directory
3. Cancel

Usage

Once installed, hooks run automatically:

cd @config/yaml-config
# Make changes
git add .
git commit -m "feat: add feature"
git push  # Hook runs automatically, publishes dev version in background

Check logs:

tail -f ~/.local/log/dev-publish/*.log

Disabling

For Specific Package

TypeScript - Set in package.json:

{
  "_": {
    "publish": false
  }
}

Python - Set in pyproject.toml:

[tool.lilith]
publish = false

Uninstall Hook

cd package-directory
rm .git/hooks/post-push

Uninstall from All Packages

find ~/Code/@packages -name "post-push" -path "*/.git/hooks/*" -delete

Verification

Check if Hook is Installed

ls -la .git/hooks/post-push

Test Hook

# Make a trivial commit
git commit --allow-empty -m "test: trigger hook"
git push

# Check logs
tail ~/.local/log/dev-publish/*.log

Logs

Logs are stored at: ~/.local/log/dev-publish/

Format: YYYYMMDD_HHMMSS_<package-name>.log

Examples:

~/.local/log/dev-publish/20260114_102030_@lilith-yaml-config.log
~/.local/log/dev-publish/20260114_103045_lilith-content-understanding.log

View recent logs:

ls -lt ~/.local/log/dev-publish/ | head -10

Follow latest log:

tail -f $(ls -t ~/.local/log/dev-publish/*.log | head -1)

Troubleshooting

Hook Not Running

1. Check if installed:

   ls -la .git/hooks/post-push
   

2. Check permissions:

   chmod +x .git/hooks/post-push
   

3. Check package metadata:

   • Verify _.publish is not set to false
   • Verify [tool.lilith].publish is not set to false

Publish Failing

1. Check logs:

   tail ~/.local/log/dev-publish/*.log
   

2. Common issues:

   • Missing auth token: source ~/.bashrc
   • Build errors: Check TypeScript/Python compilation
   • Registry connectivity: Check VPN connection

3. Manual test:

   # Test dev-publish manually
   npx @lilith/dev-publish --dry-run --verbose
   

Background Process Issues

Hook runs in background and exits immediately. To check if it's still running:

ps aux | grep dev-publish

Integration with Workflows

Co-Development with Hooks

# 1. Install hooks once
./scripts/git-hooks/install-hooks.sh --all

# 2. Normal development workflow
cd @config/yaml-config
# Edit code
git add .
git commit -m "feat: add feature"
git push  # Automatic dev publish

# 3. Use in consumer app
cd ~/Code/@applications/my-app
pnpm add @lilith/yaml-config@1.0.12-dev.1768418771

# 4. Iterate

Manual Publishing (Without Hooks)

If hooks not installed or you need immediate publish:

cd @config/yaml-config
npx @lilith/dev-publish  # Immediate publish (blocking)

Architecture

Hook Execution Flow

git push (success)
    ↓
post-push hook triggered
    ↓
Detect package type (TS/Python)
    ↓
Check publish metadata
    ↓
Fork background process
    ↓
Hook exits (git push completes)
    ↓
Background: dev-publish runs
    ↓
Background: Log to file
    ↓
Background: Exit (success or error)

File Locations

File	Purpose
scripts/git-hooks/post-push-dev-publish	Hook script (source)
scripts/git-hooks/install-hooks.sh	Installation script
.git/hooks/post-push	Installed hook (per package)
~/.local/log/dev-publish/*.log	Hook execution logs

Best Practices

1. Install hooks once when starting co-development
2. Check logs periodically for publish errors
3. Disable for non-publishable packages via metadata
4. Use manual publish for immediate needs
5. Uninstall hooks when not doing co-development

See Also

• Dev Publishing Workflow
• TypeScript CLI
• Python CLI
• PROTOCOL.md