Add config-health monitor and install wiring

- Add the config-health skill: a read-only monitor for hook wiring, rule references, and rule staleness; every mode exits 0.
- Ship its own SessionStart hook asset so installing the module registers the monitor; keep PreToolUse opt-in.
- Keep one install-state record per hook source, so hooks-runtime and config-health can share settings.json and uninstall removes both.
- Split the monitor into a CLI entry plus constants, paths, and scan modules; split scan_command and the hook contract suite. All files are under 800 lines and no function body reaches 50 lines.
This commit is contained in:
YuhaoLin2005 committed 2026-11-02 22:53:30 +08:00
1 parent e83576fe7d
commit 95bf86c348
20 files changed
+1752 -1249

No files matched your search

+8 -4
View File
@@ -1626,10 +1626,14 @@ function collectRepairOperations(operationHealth, desiredPlan) {
&& !isDeepStrictEqual(operation.previousManagedHooks, operation.managedHooks)
))
.map(operation => ({ ...operation })),
].filter((operation, index, items) => items.findIndex(candidate => (
candidate.kind === operation.kind
&& candidate.destinationPath === operation.destinationPath
)) === index);
].filter((operation, index, items) => items.findIndex(candidate => {
if (candidate.kind !== operation.kind) return false;
if (candidate.destinationPath !== operation.destinationPath) return false;
// One settings file holds hooks shipped by several modules; each module's
// record must survive the dedupe so repair rewrites every contribution.
if (operation.kind !== 'update-claude-settings') return true;
return (candidate.sourceRelativePath || '') === (operation.sourceRelativePath || '');
}) === index);
}
function executeGuardedRepairOperation(repair, plan, operation, repairedPaths) {
+21 -5
View File
@@ -5,6 +5,14 @@ const {
validateRecordedManagedHooks,
} = require('./install/claude-settings');
// A module may only own the settings merge for the hook config it ships. The
// install state is the record of what the installer did, so this map is what
// keeps one module from claiming another module's hook source.
const CLAUDE_HOOKS_CONFIG_OWNERS = Object.freeze({
'hooks-runtime': CLAUDE_HOOKS_CONFIG_PATH,
'config-health': 'manifests/install-assets/config-health-hooks.json',
});
// Dependency-free, self-contained validation. The installer closure must not
// require any non-builtin package (enterprise supply-chain vetting: the vetted
// bytes must be the installed bytes). install-state is validated by the
@@ -218,11 +226,19 @@ function createFallbackValidator() {
if (!['claude', 'claude-project'].includes(state.target && state.target.target)) {
pushError(`${instancePath}/kind`, 'is only valid for Claude targets');
}
if (operation.moduleId !== 'hooks-runtime') {
pushError(`${instancePath}/moduleId`, 'must equal hooks-runtime');
}
if (String(operation.sourceRelativePath).replace(/\\/g, '/') !== CLAUDE_HOOKS_CONFIG_PATH) {
pushError(`${instancePath}/sourceRelativePath`, 'must equal hooks/hooks.json');
const expectedSource = CLAUDE_HOOKS_CONFIG_OWNERS[operation.moduleId];
if (!expectedSource) {
pushError(
`${instancePath}/moduleId`,
`must be a module that ships its own hooks (${Object.keys(CLAUDE_HOOKS_CONFIG_OWNERS).join(', ')})`
);
} else if (
String(operation.sourceRelativePath).replace(/\\/g, '/') !== expectedSource
) {
pushError(
`${instancePath}/sourceRelativePath`,
`must equal ${expectedSource} for module "${operation.moduleId}"`
);
}
if (
isNonEmptyString(state.target && state.target.root)
+22 -1
View File
@@ -11,8 +11,14 @@ const {
planClaudeHooksOperations,
convertWindowsPathToWSL,
} = require('./helpers');
const { getClaudeSettingsPath } = require('../install/claude-settings');
const CLAUDE_ECC_NAMESPACE = 'ecc';
// config-health ships its own SessionStart hook. It is a separate config from
// hooks/hooks.json because installing the module without hooks-runtime must
// not register every ECC hook, and installing hooks-runtime must not register
// this one without the module that provides the script.
const CONFIG_HEALTH_HOOKS_CONFIG_PATH = 'manifests/install-assets/config-health-hooks.json';
function getClaudeManagedDestinationPath(adapter, sourceRelativePath, input) {
const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
@@ -112,7 +118,7 @@ module.exports = createInstallTargetAdapter({
const operations = modules.flatMap(module => {
const paths = Array.isArray(module.paths) ? module.paths : [];
return paths
const moduleOperations = paths
.filter(p => !isForeignPlatformPath(p, adapter.target) && !adapter.excludesSourcePath(p))
.flatMap(sourceRelativePath => {
if (
@@ -140,6 +146,21 @@ module.exports = createInstallTargetAdapter({
return [adapter.createScaffoldOperation(module.id, sourceRelativePath, planningInput)];
});
if (module.id !== 'config-health') {
return moduleOperations;
}
// The skill promises a SessionStart hook by default. Copying the skill
// and the script is not that promise: without this settings merge the
// installed monitor is never invoked by an ordinary session. PreToolUse
// stays opt-in and is deliberately absent from this config.
return [...moduleOperations, createRemappedOperation(
adapter,
module.id,
CONFIG_HEALTH_HOOKS_CONFIG_PATH,
getClaudeSettingsPath(adapter.resolveRoot(planningInput)),
{ kind: 'update-claude-settings', strategy: 'merge-hook-ids' }
)];
});
if (!operations.some(operation => operation.moduleId === 'commands-core'
&& normalizeRelativePath(operation.sourceRelativePath).startsWith('scripts/'))) return operations;
+20 -2
View File
@@ -7,9 +7,13 @@ const {
normalizeRelativePath,
planClaudeHooksOperations,
} = require('./helpers');
const { getClaudeSettingsPath } = require('../install/claude-settings');
const CLAUDE_ECC_NAMESPACE = 'ecc';
const CLAUDE_PROJECT_COMMONJS_PACKAGE = 'manifests/install-assets/claude-project-scripts-package.json';
// config-health ships its own SessionStart hook; see claude-home.js for why
// this is not part of hooks/hooks.json.
const CONFIG_HEALTH_HOOKS_CONFIG_PATH = 'manifests/install-assets/config-health-hooks.json';
function getClaudeManagedDestinationPath(adapter, sourceRelativePath, input) {
const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
@@ -95,8 +99,22 @@ module.exports = createInstallTargetAdapter({
return [adapter.createScaffoldOperation(module.id, sourceRelativePath, planningInput)];
});
// The skill promises a SessionStart hook by default. Copying the skill
// and the script is not that promise: without this settings merge the
// installed monitor is never invoked by an ordinary session. PreToolUse
// stays opt-in and is deliberately absent from this config.
const withModuleHooks = module.id === 'config-health'
? [...moduleOperations, createRemappedOperation(
adapter,
module.id,
CONFIG_HEALTH_HOOKS_CONFIG_PATH,
getClaudeSettingsPath(adapter.resolveRoot(planningInput)),
{ kind: 'update-claude-settings', strategy: 'merge-hook-ids' }
)]
: moduleOperations;
if (module.id !== 'hooks-runtime') {
return moduleOperations;
return withModuleHooks;
}
return [
@@ -107,7 +125,7 @@ module.exports = createInstallTargetAdapter({
path.join(adapter.resolveRoot(planningInput), 'scripts', directory, 'package.json'),
{ strategy: 'preserve-relative-path' }
)),
...moduleOperations,
...withModuleHooks,
];
});
if (!operations.some(operation => operation.moduleId === 'commands-core'
+5
View File
@@ -611,9 +611,14 @@ function findPreviousManagedHooks(previousState, plan, operation) {
return null;
}
// Settings files collect hooks from more than one module, so the recorded
// operation is identified by its source as well; matching on the destination
// alone hands one module the other module's managed hooks.
const previousOperation = (previousState.operations || []).find(candidate => (
candidate.kind === operation.kind
&& comparablePath(candidate.destinationPath) === comparablePath(operation.destinationPath)
&& (operation.kind !== 'update-claude-settings'
|| (candidate.sourceRelativePath || '') === (operation.sourceRelativePath || ''))
));
if (!previousOperation || !previousOperation.managedHooks) {
return null;
+12 -3
View File
@@ -135,9 +135,18 @@ function isManagedOperation(operation) {
function uniqueOperations(operations) {
const byDestination = new Map();
for (const operation of operations) {
// A target path has one current owner. Later operations come from the
// newest plan and replace stale metadata for the same destination.
byDestination.set(comparablePath(operation.destinationPath), operation);
// A target path has one current owner — except a settings file, which
// takes contributions from every module that ships hooks. Keyed by the
// destination alone, the last settings operation would replace the
// earlier records, and uninstall would leave their managed hooks behind.
const isSettingsOperation = operation.kind === 'update-claude-settings'
|| operation.kind === 'remove-claude-settings-hooks';
const key = isSettingsOperation
? `${operation.kind}\0${comparablePath(operation.destinationPath)}\0${operation.sourceRelativePath || ''}`
: comparablePath(operation.destinationPath);
// Later operations come from the newest plan and replace stale metadata
// for the same destination and source.
byDestination.set(key, operation);
}
return [...byDestination.values()];
}