mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-11 21:57:14 +03:00
feat(hooks): package design hook in plugin, install to settings.local.json (#243)
* feat(hooks): package design hook in plugin, install to settings.local.json
Three related changes to how the Impeccable design hook is distributed,
plus an unrelated build fix discovered along the way.
Package the hook in the Claude Code plugin
- The marketplace / `/plugin install` path previously shipped the skill and
agents but no hook, so those users never got the design detector. The build
now emits `plugin/hooks/hooks.json` (auto-discovered at the plugin root),
resolving the script via `${CLAUDE_PLUGIN_ROOT}` so it works wherever Claude
Code unpacks the plugin instead of assuming a `.claude/skills/` layout.
CLI installs the hook into settings.local.json, not shared settings.json
- `npx impeccable skills install/update` now writes the Claude hook to the
gitignored `.claude/settings.local.json` (a machine-local install side
effect) rather than the team-shared `settings.json`, which could otherwise
be committed and break for teammates without the skill installed.
- Graceful handling (leave-it-never-duplicate): if our hook already lives in
the shared `settings.json` (a legacy install or a deliberate user move), it
is honored in place and never duplicated into the local override, which
would otherwise run the detector twice per edit.
- The skill's `/impeccable hooks on|off` toggle is unaffected: it only writes
`.impeccable/hook.json`, never the settings files.
Fix universal.zip build failure under archiver v8
- `archiver` was bumped to v8 (now ESM, factory function removed) but
`scripts/lib/zip.js` still used the old `archiver('zip', ...)` API, so every
build silently failed to produce `dist/universal.zip` (the skill-release
artifact). Switched to `new ZipArchive({...})`.
Also folds in a pre-existing local rename of the hook status message
("Scanning design" -> "Checking UI changes") and its regenerated provider
output.
Tests: new coverage for the plugin-packaged hook manifest and the
shared-settings honor-in-place path; existing CLI assertions moved to
settings.local.json. Full suite green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): detect hook by marker, not file existence (Bugbot)
hookInstalledForProvider treated any existing settings.local.json (or
hooks.json) as proof the hook was installed. Those files commonly hold
unrelated local settings, so the already-installed `skills install` path
would skip repairing a genuinely missing hook that `update` would add.
Detect the Impeccable marker in the file instead of mere existence. Adds a
test for the exact case: a settings.local.json with only permissions still
triggers hook repair and preserves the unrelated content.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* test(build): fail loud on a broken release zip + cover the zip writer
Close the gap that let the archiver v8 break ship a 0-byte universal.zip
with a green test suite:
- createProviderZip no longer swallows failures. It throws on a missing
source, an archive with zero entries, or a 0-byte output, and build() now
exits non-zero on any such rejection. A build that can't produce its release
artifact fails instead of deploying an empty bundle.
- New tests/zip.test.mjs exercises the real zip writer and round-trips through
extract-zip (the unpacker the CLI uses): a valid bundle unpacks to the skill
tree, and the empty/missing-source cases throw. Wired into the core suite so
it runs in `bun run test`.
Why this matters: the prior CLI e2e tests stub the bundle as a local
directory, so they never built, downloaded, or unzipped a real archive. The
zip writer had no coverage and failed soft, so Dependabot's archiver 7->8
major bump merged green and the deploy shipped an unusable bundle.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): scope hook marker scan to the hooks subtree + prune local dupes (Bugbot)
Two follow-ups from Bugbot:
- fileHasImpeccableHookMarker scanned the whole settings file as raw text, so
an unrelated string (e.g. a permissions allow entry that mentions the hook
path) could falsely read as an installed hook and block install/repair or
the shared-settings skip. Now it parses the JSON and scans only the `hooks`
subtree.
- When the hook is honored in the shared settings.json, copyProviderHooks
skipped the local write but left a stale hook in settings.local.json from an
earlier machine-local install, so Claude Code loaded both and ran the
detector twice per edit. It now prunes the local copy (preserving unrelated
local settings, dropping the file if only our scaffolding remained).
Adds tests for both: a permissions string mentioning the hook path still
triggers repair, and a shared hook prunes the stale local duplicate while
keeping unrelated permissions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
0ec64aad1b
commit
9c0012d4e1
+19
-3
@@ -21,7 +21,7 @@ import { fileURLToPath } from 'url';
|
||||
import { readSourceFiles, readPatterns, stashPerProjectArtifacts, restorePerProjectArtifacts } from './lib/utils.js';
|
||||
import { generateApiData } from './lib/api-data.js';
|
||||
import { createTransformer, PROVIDERS } from './lib/transformers/index.js';
|
||||
import { hooksJsonFor } from './lib/transformers/hooks.js';
|
||||
import { hooksJsonFor, buildClaudePluginHooksManifest } from './lib/transformers/hooks.js';
|
||||
import { createAllZips } from './lib/zip.js';
|
||||
import { ANTIPATTERNS } from '../cli/engine/registry/antipatterns.mjs';
|
||||
// Sub-page generation is now handled by Astro content collections.
|
||||
@@ -708,9 +708,11 @@ async function build() {
|
||||
const pluginManifestDir = path.join(pluginRoot, '.claude-plugin');
|
||||
const pluginSkillsDir = path.join(pluginRoot, 'skills');
|
||||
const pluginAgentsDir = path.join(pluginRoot, 'agents');
|
||||
const pluginHooksDir = path.join(pluginRoot, 'hooks');
|
||||
if (fs.existsSync(pluginManifestDir)) fs.rmSync(pluginManifestDir, { recursive: true });
|
||||
if (fs.existsSync(pluginSkillsDir)) fs.rmSync(pluginSkillsDir, { recursive: true });
|
||||
if (fs.existsSync(pluginAgentsDir)) fs.rmSync(pluginAgentsDir, { recursive: true });
|
||||
if (fs.existsSync(pluginHooksDir)) fs.rmSync(pluginHooksDir, { recursive: true });
|
||||
|
||||
const rootManifest = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, '.claude-plugin/plugin.json'), 'utf-8'));
|
||||
const claudeAgentsSrc = path.join(DIST_DIR, 'claude-code', '.claude', 'agents');
|
||||
@@ -746,6 +748,16 @@ async function build() {
|
||||
copyDirSync(claudeAgentsSrc, pluginAgentsDir);
|
||||
}
|
||||
|
||||
// Ship the design detector as a plugin-packaged hook. Claude Code
|
||||
// auto-discovers `hooks/hooks.json` at the plugin root, so marketplace /
|
||||
// `/plugin install` users get the PostToolUse hook without it being merged
|
||||
// into their project `.claude/settings.json` (that path is the CLI's job).
|
||||
fs.mkdirSync(pluginHooksDir, { recursive: true });
|
||||
fs.writeFileSync(
|
||||
path.join(pluginHooksDir, 'hooks.json'),
|
||||
JSON.stringify(buildClaudePluginHooksManifest(), null, 2) + '\n',
|
||||
);
|
||||
|
||||
console.log('📦 Built Claude Code plugin subtree at ./plugin/');
|
||||
} else {
|
||||
console.log('📋 Skipped root harness and plugin sync (--skip-root-sync)');
|
||||
@@ -774,5 +786,9 @@ async function build() {
|
||||
console.log('\n✨ Build complete!');
|
||||
}
|
||||
|
||||
// Run the build
|
||||
build();
|
||||
// Run the build. A rejection here (e.g. the release zip failing to build) must
|
||||
// exit non-zero so a broken artifact never deploys silently.
|
||||
build().catch((err) => {
|
||||
console.error(`\n❌ Build failed: ${err.message}`);
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
@@ -1,18 +1,27 @@
|
||||
/**
|
||||
* Build-pipeline emitters for the Impeccable design hook.
|
||||
*
|
||||
* The hook install path in this PR is project-local:
|
||||
* - Claude Code: `.claude/settings.json`
|
||||
* - Codex: `.codex/hooks.json`
|
||||
* - Cursor: `.cursor/hooks.json`
|
||||
* Two emission targets exist:
|
||||
*
|
||||
* No provider marketplace or Codex plugin packaging is emitted here.
|
||||
* 1. Project-local install (the `npx impeccable skills install` CLI path):
|
||||
* - Claude Code: `.claude/settings.json` (${CLAUDE_PROJECT_DIR}-relative)
|
||||
* - Codex: `.codex/hooks.json`
|
||||
* - Cursor: `.cursor/hooks.json`
|
||||
*
|
||||
* 2. Claude Code plugin package (the marketplace / `/plugin install` path):
|
||||
* - `plugin/hooks/hooks.json` (${CLAUDE_PLUGIN_ROOT}-relative)
|
||||
*
|
||||
* The plugin variant resolves the hook script relative to the installed plugin
|
||||
* root rather than assuming a `.claude/skills/impeccable/` layout, so it stays
|
||||
* correct wherever Claude Code unpacks the plugin.
|
||||
*/
|
||||
|
||||
export const IMPECCABLE_HOOK_COMMAND_MARKER = 'skills/impeccable/scripts/hook.mjs';
|
||||
|
||||
const TIMEOUT_SECONDS = 5;
|
||||
const STATUS_MESSAGE = 'Checking UI changes';
|
||||
const CLAUDE_PROJECT_HOOK = '${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs';
|
||||
const CLAUDE_PLUGIN_HOOK = '${CLAUDE_PLUGIN_ROOT}/skills/impeccable/scripts/hook.mjs';
|
||||
const CODEX_PROJECT_HOOK = '$(git rev-parse --show-toplevel)/.agents/skills/impeccable/scripts/hook.mjs';
|
||||
const CURSOR_BEFORE_EDIT_SCRIPT = '.cursor/skills/impeccable/scripts/hook-before-edit.mjs';
|
||||
|
||||
@@ -28,7 +37,32 @@ export function buildClaudeSettingsManifest() {
|
||||
type: 'command',
|
||||
command: `node "${CLAUDE_PROJECT_HOOK}"`,
|
||||
timeout: TIMEOUT_SECONDS,
|
||||
statusMessage: 'Scanning design',
|
||||
statusMessage: STATUS_MESSAGE,
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// Plugin-packaged variant of the Claude hook. Same schema as the settings.json
|
||||
// manifest (Claude Code reads an identical `hooks` object from a plugin's
|
||||
// `hooks/hooks.json`), but the command resolves relative to ${CLAUDE_PLUGIN_ROOT}
|
||||
// so it does not depend on the skill being copied into `.claude/skills/`.
|
||||
export function buildClaudePluginHooksManifest() {
|
||||
return {
|
||||
description: 'Impeccable design detector: runs after Edit/Write/MultiEdit on UI files and surfaces findings as system reminders.',
|
||||
hooks: {
|
||||
PostToolUse: [
|
||||
{
|
||||
matcher: 'Edit|Write|MultiEdit',
|
||||
hooks: [
|
||||
{
|
||||
type: 'command',
|
||||
command: `node "${CLAUDE_PLUGIN_HOOK}"`,
|
||||
timeout: TIMEOUT_SECONDS,
|
||||
statusMessage: STATUS_MESSAGE,
|
||||
},
|
||||
],
|
||||
},
|
||||
@@ -49,7 +83,7 @@ export function buildCodexHooksManifest() {
|
||||
type: 'command',
|
||||
command: `node "${CODEX_PROJECT_HOOK}"`,
|
||||
timeout: TIMEOUT_SECONDS,
|
||||
statusMessage: 'Scanning design',
|
||||
statusMessage: STATUS_MESSAGE,
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
+31
-23
@@ -8,9 +8,8 @@
|
||||
|
||||
import path from 'path';
|
||||
import { createWriteStream, existsSync, statSync } from 'fs';
|
||||
import * as archiverModule from 'archiver';
|
||||
|
||||
const createArchiver = archiverModule.default || archiverModule.create || archiverModule;
|
||||
// archiver v8 is ESM and exports format-specific classes (no factory function).
|
||||
import { ZipArchive } from 'archiver';
|
||||
|
||||
/**
|
||||
* Create ZIP file for a provider directory
|
||||
@@ -23,33 +22,42 @@ export async function createProviderZip(providerDir, distDir, providerName) {
|
||||
const zipPath = path.join(distDir, zipFileName);
|
||||
|
||||
if (!existsSync(providerDir)) {
|
||||
console.warn(`⚠️ Provider directory not found: ${providerDir}`);
|
||||
return;
|
||||
throw new Error(`Cannot create ${zipFileName}: provider directory not found: ${providerDir}`);
|
||||
}
|
||||
|
||||
try {
|
||||
await new Promise((resolve, reject) => {
|
||||
const output = createWriteStream(zipPath);
|
||||
const archive = createArchiver('zip', { zlib: { level: 9 } });
|
||||
// Fail loud, never soft. This artifact ships to `npx impeccable skills
|
||||
// install` via the bundle endpoint; a build that can't produce a real zip
|
||||
// must exit non-zero rather than deploy an empty one. (archiver v8's ESM
|
||||
// break previously failed here silently and shipped a 0-byte universal.zip.)
|
||||
let entryCount = 0;
|
||||
await new Promise((resolve, reject) => {
|
||||
const output = createWriteStream(zipPath);
|
||||
const archive = new ZipArchive({ zlib: { level: 9 } });
|
||||
|
||||
output.on('close', resolve);
|
||||
archive.on('error', reject);
|
||||
output.on('close', resolve);
|
||||
output.on('error', reject);
|
||||
archive.on('error', reject);
|
||||
archive.on('entry', () => { entryCount += 1; });
|
||||
|
||||
archive.pipe(output);
|
||||
archive.glob('**/*', {
|
||||
cwd: providerDir,
|
||||
dot: true,
|
||||
ignore: ['**/.DS_Store'],
|
||||
});
|
||||
archive.finalize();
|
||||
archive.pipe(output);
|
||||
archive.glob('**/*', {
|
||||
cwd: providerDir,
|
||||
dot: true,
|
||||
ignore: ['**/.DS_Store'],
|
||||
});
|
||||
archive.finalize();
|
||||
});
|
||||
|
||||
const stats = statSync(zipPath);
|
||||
const sizeMB = (stats.size / 1024 / 1024).toFixed(2);
|
||||
console.log(` 📦 ${zipFileName} (${sizeMB} MB)`);
|
||||
} catch (error) {
|
||||
console.error(` ❌ Failed to create ${zipFileName}:`, error.message);
|
||||
if (entryCount === 0) {
|
||||
throw new Error(`Created ${zipFileName} but it contains no entries (source: ${providerDir}).`);
|
||||
}
|
||||
const { size } = statSync(zipPath);
|
||||
if (size === 0) {
|
||||
throw new Error(`Created ${zipFileName} but it is 0 bytes.`);
|
||||
}
|
||||
|
||||
const sizeMB = (size / 1024 / 1024).toFixed(2);
|
||||
console.log(` 📦 ${zipFileName} (${sizeMB} MB)`);
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -29,7 +29,7 @@ export const SUITES = {
|
||||
/^site\/(pages|content|components|layouts)\//,
|
||||
/^README(\.npm)?\.md$/,
|
||||
/^cli\/bin\//,
|
||||
/^tests\/(build|cleanup-deprecated|context|context-signals|critique-storage|design-parser|docs-integrity|hook|hook-build|impeccable-paths|skills-cli|test-suites|windows-path-fix)\.test\.(js|mjs)$/,
|
||||
/^tests\/(build|cleanup-deprecated|context|context-signals|critique-storage|design-parser|docs-integrity|hook|hook-build|impeccable-paths|skills-cli|test-suites|windows-path-fix|zip)\.test\.(js|mjs)$/,
|
||||
/^tests\/lib\//,
|
||||
],
|
||||
commands: [
|
||||
@@ -59,6 +59,7 @@ export const SUITES = {
|
||||
'tests/hook.test.mjs',
|
||||
'tests/impeccable-paths.test.mjs',
|
||||
'tests/test-suites.test.mjs',
|
||||
'tests/zip.test.mjs',
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
Reference in New Issue
Block a user