How to Set Up Pre-Commit and Pre-Push Validation Hooks in aios-core

aios-core uses Husky to automatically enforce manifest consistency on every commit and synchronize the IDS entity registry before each push.

Setting up pre-commit and pre-push validation hooks in aios-core ensures that your install manifest stays synchronized and the IDS (Intelligent Data System) registry remains up-to-date. The SynkraAI/aios-core repository leverages Husky to manage Git hooks, automatically installing validation scripts when you run npm install.

How Pre-Commit and Pre-Push Hooks Work in aios-core

The repository defines two primary validation hooks that execute at different stages of your Git workflow.

Pre-Commit Hook (.husky/pre-commit)

The pre-commit hook runs scripts/ensure-manifest.js to validate and regenerate .aios-core/install-manifest.yaml whenever files under .aios-core/ are staged.

#!/usr/bin/env sh

# Keep install-manifest.yaml synchronized whenever .aios-core files are committed.

node scripts/ensure-manifest.js

The script performs the following operations:

• Detect staged files using getStagedFiles() (lines 8-15) to run git diff --cached --name-only
• Decision logic via shouldCheckManifest() (lines 18-25) checks if any staged file lives under .aios-core/ (excluding the manifest itself)
• Regeneration flow in main() (lines 27-45) validates the manifest with scripts/validate-manifest, regenerates it via scripts/generate-install-manifest.js, stages the updated file, and prints a success message

Pre-Push Hook (.husky/pre-push)

The pre-push hook executes .aios-core/hooks/ids-pre-push.js to synchronize the IDS entity registry before pushing changes to the remote.

#!/usr/bin/env sh

# IDS Registry Sync (Story IDS-3)

# Ensures entity registry is up-to-date before push (sync, non-blocking).

node .aios-core/hooks/ids-pre-push.js || true

Key implementation details:

• Change detection via getChangedFilesSinceRemote() (lines 38-86) computes files changed between local HEAD and the remote tracking branch using git diff
• Docs-only skip logic in isDocsOnlyPush() (lines 33-36) identifies if the push contains only documentation changes (docs/, README.md, CHANGELOG.md, etc.) and skips registry sync when true
• Registry update through main() (lines 94-123) loads .aios-core/core/ids/registry-updater.js and processes changes, logging errors but exiting with code 0 to ensure the push is never blocked

Setting Up the Validation Hooks

Follow these steps to configure the pre-commit and pre-push validation hooks in your local aios-core environment.

1. Clone the repository

   git clone https://github.com/SynkraAI/aios-core.git
   cd aios-core

2. Install dependencies

   npm ci

   The prepare script automatically triggers husky, which creates the Git hooks under .husky/.

3. Verify hook installation

   ls -l .husky

   You should see pre-commit and pre-push files, both marked as executable.

4. Test the pre-commit hook

   echo "# test" > .aios-core/example.txt
   
   git add .aios-core/example.txt
   git commit -m "Test pre-commit hook"

   The hook invokes ensure-manifest.js. If the manifest requires updating, it regenerates automatically and gets staged.

5. Test the pre-push hook

   git push

   The pre-push hook runs ids-pre-push.js. For non-documentation changes, the IDS registry synchronizes before the push completes.

Customizing the Hooks

You can extend or modify the validation behavior by editing the underlying scripts.

• Add additional validation to the pre-commit process by modifying scripts/ensure-manifest.js or creating new scripts and referencing them from .husky/pre-commit

• Change registry behavior by editing .aios-core/hooks/ids-pre-push.js to adjust docs-only detection logic or make the sync blocking instead of non-blocking

• Force registry sync even on documentation-only pushes by setting the environment variable before pushing:

  export AIOS_IDS_FORCE=1
  git push

Summary

• aios-core uses Husky to manage Git hooks, automatically installing them during npm install
• The pre-commit hook runs scripts/ensure-manifest.js to synchronize .aios-core/install-manifest.yaml when files under .aios-core/ change
• The pre-push hook executes .aios-core/hooks/ids-pre-push.js to update the IDS entity registry, skipping documentation-only pushes
• Both hooks are located in .husky/ and call Node.js scripts that implement validation logic using functions like getStagedFiles(), shouldCheckManifest(), and isDocsOnlyPush()

Frequently Asked Questions

How do I manually run the manifest validation check?

You can execute the pre-commit validation logic manually by running node scripts/ensure-manifest.js from the repository root. This script inspects staged files using getStagedFiles() and regenerates the manifest via scripts/generate-install-manifest.js if .aios-core/ files have changed.

Can I skip the pre-push hook when pushing documentation changes?

The pre-push hook automatically skips the IDS registry sync when isDocsOnlyPush() detects that only documentation files (such as docs/, README.md, or CHANGELOG.md) have changed. If you need to force the registry update anyway, set AIOS_IDS_FORCE=1 before running git push.

What happens if the IDS registry update fails during pre-push?

The pre-push hook is designed to be non-blocking. Even if ids-pre-push.js encounters errors while loading .aios-core/core/ids/registry-updater.js or processing changes, it logs the error and exits with code 0. The || true in the shell script ensures that git push proceeds regardless of the script's exit status.

Where are the hook scripts located in the repository?

The Git hook entry points reside in .husky/pre-commit and .husky/pre-push. These shell scripts call the actual validation logic located at scripts/ensure-manifest.js (for pre-commit) and .aios-core/hooks/ids-pre-push.js (for pre-push), which in turn utilize .aios-core/core/ids/registry-updater.js for registry synchronization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}