You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/10/11 15:29:21 UTC
(magpie) branch main updated: feat(setup): add zero-token setup drift check Claude Code mod (part of #1497) (#1552)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new 53ecbdeb feat(setup): add zero-token setup drift check Claude Code mod (part of #1497) (#1552)
53ecbdeb is described below
commit 53ecbdebd0b077d81ebf7c1bfae3b936ea8dfec7
Author: Vardhman Gupta <11...@users.noreply.github.com>
AuthorDate: Sun Oct 11 20:59:15 2026 +0530
feat(setup): add zero-token setup drift check Claude Code mod (part of #1497) (#1552)
* feat(setup): add zero-token setup drift check Claude Code mod (#1497)
* fix(setup): align drift-check mod with YAML lockfile parser, floor semantics, and local lock split (#1497)
* fix(setup): retain SessionStart hook in plugin.json for family plugin validation (#1497)
* fix(setup): reconcile hooks.json mod manifest and eliminate duplicate inline hook (#1497)
- Update tools/dev/check-family-plugins.py to recognize hooks/hooks.json for magpie-setup and enforce that inline 'hooks' is dropped from .claude-plugin/plugin.json when hooks.json is present, preventing Claude Code duplicate hooks load collisions.
- Remove duplicate inline 'hooks' from plugins/magpie-setup/.claude-plugin/plugin.json.
Co-authored-by: Vardhman Gupta <va...@gmail.com>
* fix(setup): align drift-check mod with Claude Code sandbox API and test runner (#1497)
- Remove node:fs and node:path imports to satisfy claude plugin validate --strict
- Accept harness-provided $.fs interface in checkSetupDrift and resolvePluginVersion
- Add zero-dependency joinPath helper for path resolution
- Import from claude-code/testing in test suite and use in-memory MockFs
* fix(setup): align hook registration AST and test exports for Claude Code mod validator (#1497)
- Remove typeof on check in register to satisfy strict static analysis
- Import test instead of it from claude-code/testing
* fix(setup): align hook registration AST and ui.render return for Claude Code mod validator (#1497)
* fix(setup): restore SessionStart shell hook in hooks.json, fix PEP 440 dev release ordering and direct member access on $ (#1497)
* fix(setup): align drift mod with Claude host API
* fix(setup): return AbovePrompt view directly and mount with real engine in tests
* style: format check-family-plugins.py with ruff
* fix(setup): drop test-only fallback in hook and seed atom directly in tests
- Read driftNotice atom alone without test-only fallback in ui.render
- Remove MockState class and synthetic mocks in test suite
- Mount AbovePrompt with real engine and props: {}
- Seed driftNotice atom directly and verify AbovePrompt mount
* test(setup): drive AbovePrompt drift tests end-to-end via engine session.start stubs
* test(setup): serve the installed version from plugin.json in the engine tests
The engine tests answered the version read from package.json and
returned '' for .claude-plugin/plugin.json, so they only exercised
resolvePluginVersion's fallback. Serve it from plugin.json, the path a
real session reads first.
Generated-by: Claude Opus 5
Claude-Session: https://claude.ai/code/session_01GTPsZ5aEE5bUVYqp47Dpvv
---------
Co-authored-by: Arnav <im...@gmail.com>
Co-authored-by: Jarek Potiuk <po...@apache.org>
---
plugins/magpie-setup/.claude-plugin/plugin.json | 17 +-
plugins/magpie-setup/hooks/drift-check.test.ts | 266 +++++++++++
plugins/magpie-setup/hooks/drift-check.ts | 561 ++++++++++++++++++++++++
plugins/magpie-setup/hooks/hooks.json | 21 +
plugins/magpie-setup/hooks/types.d.ts | 26 ++
tools/dev/check-family-plugins.py | 34 +-
6 files changed, 906 insertions(+), 19 deletions(-)
diff --git a/plugins/magpie-setup/.claude-plugin/plugin.json b/plugins/magpie-setup/.claude-plugin/plugin.json
index 1b436a85..7e72be18 100644
--- a/plugins/magpie-setup/.claude-plugin/plugin.json
+++ b/plugins/magpie-setup/.claude-plugin/plugin.json
@@ -9,19 +9,6 @@
"homepage": "https://magpie.apache.org/",
"repository": "https://github.com/apache/magpie",
"license": "Apache-2.0",
- "skills": "./skills",
- "hooks": {
- "SessionStart": [
- {
- "matcher": "startup",
- "hooks": [
- {
- "type": "command",
- "command": "${CLAUDE_PLUGIN_ROOT}/hooks/check-upgrade.sh",
- "timeout": 10
- }
- ]
- }
- ]
- }
+ "types": "./hooks/types.d.ts",
+ "skills": "./skills"
}
diff --git a/plugins/magpie-setup/hooks/drift-check.test.ts b/plugins/magpie-setup/hooks/drift-check.test.ts
new file mode 100644
index 00000000..370074a2
--- /dev/null
+++ b/plugins/magpie-setup/hooks/drift-check.test.ts
@@ -0,0 +1,266 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import { describe, test } from 'claude-code/testing';
+import {
+ checkSetupDrift,
+ resolvePluginVersion,
+ parseLockfile,
+ parseLocalLockfile,
+ parsePep440,
+ comparePep440,
+ joinPath,
+} from './drift-check.ts';
+
+class MockFsAsync {
+ private files = new Map<string, string>();
+
+ set(filePath: string, content: string): void {
+ this.files.set(filePath.replace(/\\/g, '/'), content);
+ }
+
+ async exists(filePath: string): Promise<boolean> {
+ return this.files.has(filePath.replace(/\\/g, '/'));
+ }
+
+ async read(filePath: string): Promise<string> {
+ const val = this.files.get(filePath.replace(/\\/g, '/'));
+ if (val === undefined) {
+ throw new Error(`ENOENT: no such file: ${filePath}`);
+ }
+ return val;
+ }
+}
+
+function assert(condition: any, message?: string): void {
+ if (!condition) {
+ throw new Error(message || 'Assertion failed');
+ }
+}
+
+function assertStrictEqual(actual: any, expected: any, message?: string): void {
+ if (actual !== expected) {
+ throw new Error(message || `Expected ${JSON.stringify(expected)} but got ${JSON.stringify(actual)}`);
+ }
+}
+
+function assertDeepStrictEqual(actual: any, expected: any): void {
+ if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+ throw new Error(`Expected deep equality: ${JSON.stringify(expected)} !== ${JSON.stringify(actual)}`);
+ }
+}
+
+describe('drift-check mod (Pilot 1)', () => {
+ const workspaceDir = '/test/workspace';
+ const pluginDir = '/test/plugin';
+
+ function createTestEnv(): MockFsAsync {
+ const fs = new MockFsAsync();
+ fs.set(
+ joinPath(pluginDir, '.claude-plugin', 'plugin.json'),
+ JSON.stringify({
+ name: 'magpie-setup',
+ version: '0.9.0',
+ })
+ );
+ return fs;
+ }
+
+ describe('pep440 and yaml parsers', () => {
+ test('parses epoch, release, pre, post, dev segments correctly', () => {
+ assertDeepStrictEqual(parsePep440('1!2.3.4rc5.post6.dev7'), {
+ epoch: 1,
+ release: [2, 3, 4],
+ pre: { type: 'rc', num: 5 },
+ post: 6,
+ dev: 7,
+ });
+ });
+
+ test('orders versions correctly', () => {
+ assert(comparePep440('1.0', '1.0.post1') < 0);
+ assert(comparePep440('1.0.dev1', '1.0a1') < 0);
+ assert(comparePep440('1.0a1', '1.0rc1') < 0);
+ assert(comparePep440('2.0', '1!1.0') < 0);
+ });
+ });
+
+ describe('checkSetupDrift logic', () => {
+ test('returns false drift when lockfile does not exist', async () => {
+ const fs = createTestEnv();
+ const exists = async (p: string) => await fs.exists(p);
+ const read = async (p: string) => await fs.read(p);
+ const result = await checkSetupDrift(exists, read, workspaceDir, pluginDir);
+ assertStrictEqual(result.isAdopted, false);
+ assertStrictEqual(result.hasDrift, false);
+ });
+
+ test('returns false drift when installed plugin satisfies marketplace adoption floor', async () => {
+ const fs = createTestEnv();
+ const exists = async (p: string) => await fs.exists(p);
+ const read = async (p: string) => await fs.read(p);
+
+ const lockContent = `method: marketplace
+url: apache/magpie
+min_version: 0.2.0
+
+plugins:
+ - magpie-setup
+`;
+ fs.set(joinPath(workspaceDir, '.apache-magpie.lock'), lockContent);
+
+ const result = await checkSetupDrift(exists, read, workspaceDir, pluginDir);
+ assertStrictEqual(result.isAdopted, true);
+ assertStrictEqual(result.hasDrift, false);
+ assertStrictEqual(result.lockVersion, '0.2.0');
+ assertStrictEqual(result.currentVersion, '0.9.0');
+ assertStrictEqual(result.message, undefined);
+ });
+
+ test('detects drift when installed plugin is below marketplace adoption floor', async () => {
+ const fs = createTestEnv();
+ const exists = async (p: string) => await fs.exists(p);
+ const read = async (p: string) => await fs.read(p);
+
+ const lockContent = `method: marketplace
+url: apache/magpie
+min_version: 1.0.0
+
+plugins:
+ - magpie-setup
+`;
+ fs.set(joinPath(workspaceDir, '.apache-magpie.lock'), lockContent);
+
+ const result = await checkSetupDrift(exists, read, workspaceDir, pluginDir);
+ assertStrictEqual(result.isAdopted, true);
+ assertStrictEqual(result.hasDrift, true);
+ assertStrictEqual(result.lockVersion, '1.0.0');
+ assertStrictEqual(result.currentVersion, '0.9.0');
+ assert(result.message?.includes('below adoption floor (1.0.0)'));
+ });
+
+ test('detects missing local snapshot lockfile for git-tag method', async () => {
+ const fs = createTestEnv();
+ const exists = async (p: string) => await fs.exists(p);
+ const read = async (p: string) => await fs.read(p);
+ const lockContent = `method: git-tag
+url: https://github.com/apache/magpie.git
+ref: v1.0.0
+`;
+ fs.set(joinPath(workspaceDir, '.apache-magpie.lock'), lockContent);
+
+ const result = await checkSetupDrift(exists, read, workspaceDir, pluginDir);
+ assertStrictEqual(result.isAdopted, true);
+ assertStrictEqual(result.hasDrift, true);
+ assert(result.message?.includes('Local snapshot lockfile missing'));
+ });
+
+ test('resolves plugin version correctly from candidate paths', async () => {
+ const fs = createTestEnv();
+ const exists = async (p: string) => await fs.exists(p);
+ const read = async (p: string) => await fs.read(p);
+ const version = await resolvePluginVersion(exists, read, pluginDir);
+ assertStrictEqual(version, '0.9.0');
+ });
+ });
+
+ describe('Claude Code hook registration and AbovePrompt UI', () => {
+ const LOCK_BELOW_FLOOR = [
+ 'method: marketplace',
+ 'url: apache/magpie',
+ 'min_version: 1.0.0',
+ '',
+ 'plugins:',
+ ' - magpie-setup',
+ '',
+ ].join('\n');
+
+ const LOCK_SATISFYING_FLOOR = [
+ 'method: marketplace',
+ 'url: apache/magpie',
+ 'min_version: 0.9.0',
+ '',
+ 'plugins:',
+ ' - magpie-setup',
+ '',
+ ].join('\n');
+
+ test('renders actual AbovePrompt view with drift notice when installed plugin is below adoption floor', async ($: any, on: any) => {
+ on('fs.exists', (_: any, e: any) => ({
+ value: true,
+ }));
+ on('fs.read', (_: any, e: any) => ({
+ value: e.path.endsWith('.apache-magpie.lock')
+ ? LOCK_BELOW_FLOOR
+ : e.path.endsWith('.claude-plugin/plugin.json')
+ ? JSON.stringify({ name: 'magpie-setup', version: '0.9.0' })
+ : '',
+ }));
+
+ on('ui.render', () => ({ type: 'Box', children: [] }));
+ on('session.start', () => ({ cwd: '/work' }));
+ on('session.root', () => ({ value: '/work' }));
+ on('command.register', () => ({ value: undefined }));
+
+ await $.session.start({ surface: 'terminal', isInteractive: true, cwd: '/work' });
+
+ for (const surface of ['terminal', 'desktop'] as const) {
+ const ui = await $.ui.mount({
+ plugin: 'magpie-setup',
+ surface,
+ component: 'AbovePrompt',
+ props: {},
+ });
+ const found = await ui.find({ type: 'Text', text: /below adoption floor/ });
+ assert(found, `Expected drift notice rendered on ${surface}`);
+ }
+ });
+
+ test('ui.render forwards unchanged when there is no notice (satisfying adoption floor)', async ($: any, on: any) => {
+ on('fs.exists', (_: any, e: any) => ({
+ value: true,
+ }));
+ on('fs.read', (_: any, e: any) => ({
+ value: e.path.endsWith('.apache-magpie.lock')
+ ? LOCK_SATISFYING_FLOOR
+ : e.path.endsWith('.claude-plugin/plugin.json')
+ ? JSON.stringify({ name: 'magpie-setup', version: '0.9.0' })
+ : '',
+ }));
+
+ on('ui.render', () => ({ type: 'Box', children: [] }));
+ on('session.start', () => ({ cwd: '/work' }));
+ on('session.root', () => ({ value: '/work' }));
+ on('command.register', () => ({ value: undefined }));
+
+ await $.session.start({ surface: 'terminal', isInteractive: true, cwd: '/work' });
+
+ for (const surface of ['terminal', 'desktop'] as const) {
+ const ui = await $.ui.mount({
+ plugin: 'magpie-setup',
+ surface,
+ component: 'AbovePrompt',
+ props: {},
+ });
+ const found = await ui.find({ type: 'Text', text: /below adoption floor/ });
+ assertStrictEqual(found, undefined, `AbovePrompt should not render drift text on ${surface} when no notice`);
+ }
+ });
+ });
+});
diff --git a/plugins/magpie-setup/hooks/drift-check.ts b/plugins/magpie-setup/hooks/drift-check.ts
new file mode 100644
index 00000000..83bc4649
--- /dev/null
+++ b/plugins/magpie-setup/hooks/drift-check.ts
@@ -0,0 +1,561 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import { atom, read, update } from 'claude-code';
+
+export const driftNotice = atom(
+ { plugin: 'magpie-setup', key: 'driftNotice' },
+ null as string | null
+);
+
+/**
+ * Parses a simple subset of YAML used for apache-magpie.lock files.
+ */
+function parseYamlLike(content: string): Record<string, any> {
+ const result: Record<string, any> = {};
+ const lines = content.split('\n');
+
+ let inList = false;
+ let currentListKey = '';
+
+ for (const rawLine of lines) {
+ const line = rawLine.trim();
+ if (!line || line.startsWith('#')) {
+ continue;
+ }
+
+ if (line.startsWith('- ')) {
+ if (inList && currentListKey) {
+ result[currentListKey].push(line.substring(2).trim());
+ }
+ continue;
+ }
+
+ const colonIndex = line.indexOf(':');
+ if (colonIndex > 0) {
+ const key = line.substring(0, colonIndex).trim();
+ const value = line.substring(colonIndex + 1).trim();
+
+ if (!value) {
+ inList = true;
+ currentListKey = key;
+ result[key] = [];
+ } else {
+ inList = false;
+ result[key] = value;
+ }
+ }
+ }
+
+ return result;
+}
+
+export interface LockfileData {
+ method: string;
+ url?: string;
+ min_version?: string;
+ ref?: string;
+ commit?: string;
+ plugins?: string[];
+}
+
+export function parseLockfile(content: string): LockfileData {
+ const parsed = parseYamlLike(content);
+ return {
+ method: parsed.method,
+ url: parsed.url,
+ min_version: parsed.min_version,
+ ref: parsed.ref,
+ commit: parsed.commit,
+ plugins: parsed.plugins,
+ };
+}
+
+export interface LocalLockfileData {
+ method: string;
+ url?: string;
+ source_ref?: string;
+ fetched_commit?: string;
+}
+
+export function parseLocalLockfile(content: string): LocalLockfileData {
+ const parsed = parseYamlLike(content);
+ return {
+ method: parsed.method,
+ url: parsed.url,
+ source_ref: parsed.source_ref,
+ fetched_commit: parsed.fetched_commit,
+ };
+}
+
+export interface DriftCheckResult {
+ isAdopted: boolean;
+ hasDrift: boolean;
+ lockVersion?: string;
+ currentVersion?: string;
+ message?: string;
+}
+
+/**
+ * Joins path segments normalizing slashes.
+ */
+export function joinPath(...segments: string[]): string {
+ if (segments.length === 0) return '.';
+ const parts: string[] = [];
+ for (const seg of segments) {
+ if (!seg) continue;
+ const split = seg.split(/[/\\]+/);
+ for (const p of split) {
+ if (p === '..') {
+ if (parts.length > 0 && parts[parts.length - 1] !== '..') {
+ parts.pop();
+ } else {
+ parts.push('..');
+ }
+ } else if (p !== '.' && p !== '') {
+ parts.push(p);
+ } else if (p === '' && parts.length === 0) {
+ parts.push(''); // leading slash
+ }
+ }
+ }
+ const result = parts.join('/');
+ if (result === '') return '/';
+ if (segments[0].startsWith('/') && !result.startsWith('/')) {
+ return '/' + result;
+ }
+ return result || '.';
+}
+
+export interface Pep440Version {
+ epoch: number;
+ release: number[];
+ pre?: { type: string; num: number };
+ post?: number;
+ dev?: number;
+}
+
+export function parsePep440(v: string): Pep440Version | null {
+ let s = v.trim().replace(/^v/i, '');
+ if (!s) return null;
+
+ let epoch = 0;
+ const epochMatch = s.match(/^(\d+)!/);
+ if (epochMatch) {
+ epoch = parseInt(epochMatch[1], 10);
+ s = s.slice(epochMatch[0].length);
+ }
+
+ // Look for .devN
+ let dev: number | undefined = undefined;
+ const devMatch = s.match(/[.-]?dev(\d+)?$/i);
+ if (devMatch) {
+ dev = devMatch[1] !== undefined ? parseInt(devMatch[1], 10) : 0;
+ s = s.slice(0, devMatch.index);
+ }
+
+ // Look for .postN
+ let post: number | undefined = undefined;
+ const postMatch = s.match(/[.-]?(post|r|rev)(\d+)?$/i);
+ if (postMatch) {
+ post = postMatch[2] !== undefined ? parseInt(postMatch[2], 10) : 0;
+ s = s.slice(0, postMatch.index);
+ }
+
+ // Look for pre-release (a|b|rc|alpha|beta|preview|c)
+ let pre: { type: string; num: number } | undefined = undefined;
+ const preMatch = s.match(/[.-]?(a|alpha|b|beta|rc|c|preview)(\d+)?$/i);
+ if (preMatch) {
+ let type = preMatch[1].toLowerCase();
+ if (type === 'alpha') type = 'a';
+ if (type === 'beta') type = 'b';
+ if (type === 'c' || type === 'preview') type = 'rc';
+ const num = preMatch[2] !== undefined ? parseInt(preMatch[2], 10) : 0;
+ pre = { type, num };
+ s = s.slice(0, preMatch.index);
+ }
+
+ const parts = s.split('.');
+ const release: number[] = [];
+ for (const part of parts) {
+ if (!part || !/^\d+$/.test(part)) return null;
+ release.push(parseInt(part, 10));
+ }
+ if (release.length === 0) return null;
+
+ return { epoch, release, pre, post, dev };
+}
+
+export function comparePep440(aStr: string, bStr: string): number {
+ const a = parsePep440(aStr);
+ const b = parsePep440(bStr);
+
+ if (!a || !b) {
+ return aStr.localeCompare(bStr);
+ }
+
+ if (a.epoch !== b.epoch) {
+ return a.epoch - b.epoch;
+ }
+
+ const maxLen = Math.max(a.release.length, b.release.length);
+ for (let i = 0; i < maxLen; i++) {
+ const aVal = a.release[i] ?? 0;
+ const bVal = b.release[i] ?? 0;
+ if (aVal !== bVal) {
+ return aVal - bVal;
+ }
+ }
+
+ const getPhaseRank = (v: Pep440Version) => {
+ if (v.dev !== undefined && !v.pre && !v.post) return -1; // e.g. 1.0.dev1
+ if (v.pre) {
+ if (v.pre.type === 'a') return 0;
+ if (v.pre.type === 'b') return 1;
+ if (v.pre.type === 'rc') return 2;
+ }
+ if (v.post !== undefined) return 4; // e.g. 1.0.post1
+ return 3; // final release: 1.0
+ };
+
+ const aPhase = getPhaseRank(a);
+ const bPhase = getPhaseRank(b);
+
+ if (aPhase !== bPhase) {
+ return aPhase - bPhase;
+ }
+
+ // Same phase comparisons:
+ if (aPhase === -1) {
+ return (a.dev ?? 0) - (b.dev ?? 0);
+ }
+
+ if (a.pre && b.pre) {
+ if (a.pre.num !== b.pre.num) {
+ return a.pre.num - b.pre.num;
+ }
+ const aDev = a.dev !== undefined ? a.dev : Infinity;
+ const bDev = b.dev !== undefined ? b.dev : Infinity;
+ if (aDev !== bDev) {
+ return aDev - bDev;
+ }
+ }
+
+ if (a.post !== undefined && b.post !== undefined) {
+ if (a.post !== b.post) {
+ return a.post - b.post;
+ }
+ const aDev = a.dev !== undefined ? a.dev : Infinity;
+ const bDev = b.dev !== undefined ? b.dev : Infinity;
+ if (aDev !== bDev) {
+ return aDev - bDev;
+ }
+ }
+
+ return 0;
+}
+
+/**
+ * Resolves the currently executing plugin's version using provided fs adapters.
+ */
+export async function resolvePluginVersion(
+ exists: (p: string) => Promise<boolean>,
+ read: (p: string) => Promise<string>,
+ pluginDir?: string
+): Promise<string | undefined> {
+ if (!pluginDir) return undefined;
+
+ const candidatePaths = [
+ joinPath(pluginDir, '.claude-plugin', 'plugin.json'),
+ joinPath(pluginDir, 'package.json'),
+ joinPath(pluginDir, '..', 'package.json'),
+ joinPath(pluginDir, '..', '..', 'package.json')
+ ];
+
+ for (const p of candidatePaths) {
+ try {
+ if (await exists(p)) {
+ const content = await read(p);
+ const parsed = JSON.parse(content);
+ if (parsed && typeof parsed.version === 'string' && parsed.version.trim()) {
+ return parsed.version.trim();
+ }
+ }
+ } catch {
+ // Continue searching next candidate
+ }
+ }
+
+ return undefined;
+}
+
+/**
+ * Core deterministic drift check between workspace lockfile and installed plugin/snapshot.
+ */
+export async function checkSetupDrift(
+ exists: (p: string) => Promise<boolean>,
+ read: (p: string) => Promise<string>,
+ workspaceDir: string,
+ pluginDir?: string
+): Promise<DriftCheckResult> {
+ try {
+ if (typeof exists !== 'function' || typeof read !== 'function') {
+ return {
+ isAdopted: false,
+ hasDrift: false,
+ };
+ }
+
+ const lockPath = joinPath(workspaceDir, '.apache-magpie.lock');
+
+ if (!(await exists(lockPath))) {
+ return {
+ isAdopted: false,
+ hasDrift: false,
+ };
+ }
+
+ const rawContent = await read(lockPath);
+ const content = rawContent.trim();
+ if (!content) {
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ message:
+ 'Apache Magpie: Empty `.apache-magpie.lock` detected. Run `/magpie-setup upgrade` to populate.',
+ };
+ }
+
+ let lockData: LockfileData;
+ try {
+ lockData = parseLockfile(content);
+ } catch {
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ message:
+ 'Apache Magpie: Malformed `.apache-magpie.lock` detected. Run `/magpie-setup upgrade` to repair.',
+ };
+ }
+
+ const method = lockData.method;
+
+ // 1. Method: marketplace (Adoption Floor semantics)
+ if (method === 'marketplace') {
+ const minVersion = lockData.min_version;
+ if (!minVersion) {
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ message:
+ 'Apache Magpie: Malformed `.apache-magpie.lock` (missing min_version). Run `/magpie-setup upgrade` to repair.',
+ };
+ }
+
+ const currentVersion = await resolvePluginVersion(exists, read, pluginDir);
+ if (currentVersion) {
+ // Floor semantics: drift only occurs when installed < min_version
+ if (comparePep440(currentVersion, minVersion) < 0) {
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ lockVersion: minVersion,
+ currentVersion,
+ message: `Apache Magpie: Installed plugin version (${currentVersion}) is below adoption floor (${minVersion}). Run \`/magpie-setup upgrade\` to reconcile.`,
+ };
+ }
+
+ return {
+ isAdopted: true,
+ hasDrift: false,
+ lockVersion: minVersion,
+ currentVersion,
+ };
+ }
+
+ return {
+ isAdopted: true,
+ hasDrift: false,
+ lockVersion: minVersion,
+ };
+ }
+
+ // 2. Snapshot methods (git-tag, git-branch, svn-zip)
+ if (method === 'git-tag' || method === 'git-branch' || method === 'svn-zip') {
+ const localLockPath = joinPath(workspaceDir, '.apache-magpie.local.lock');
+ const committedPin = lockData.ref || lockData.commit;
+
+ if (!(await exists(localLockPath))) {
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ lockVersion: committedPin,
+ message:
+ 'Apache Magpie: Local snapshot lockfile missing (`.apache-magpie.local.lock`). Run `/magpie-setup upgrade` to fetch snapshot.',
+ };
+ }
+
+ const rawLocalContent = await read(localLockPath);
+ const localContent = rawLocalContent.trim();
+ if (!localContent) {
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ lockVersion: committedPin,
+ message:
+ 'Apache Magpie: Empty `.apache-magpie.local.lock` detected. Run `/magpie-setup upgrade` to refresh.',
+ };
+ }
+
+ let localData: LocalLockfileData;
+ try {
+ localData = parseLocalLockfile(localContent);
+ } catch {
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ lockVersion: committedPin,
+ message:
+ 'Apache Magpie: Malformed `.apache-magpie.local.lock` detected. Run `/magpie-setup upgrade` to repair.',
+ };
+ }
+
+ if (method === 'git-tag' || method === 'git-branch') {
+ const refMismatch = Boolean(lockData.ref && localData.source_ref && lockData.ref !== localData.source_ref);
+ const commitMismatch = Boolean(
+ lockData.commit && localData.fetched_commit && lockData.commit !== localData.fetched_commit
+ );
+
+ if (refMismatch || commitMismatch) {
+ const localPin = localData.source_ref || localData.fetched_commit;
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ lockVersion: committedPin,
+ message: `Apache Magpie: Snapshot drift detected (${localPin} -> ${committedPin}). Run \`/magpie-setup upgrade\` to reconcile snapshot and overrides.`,
+ };
+ }
+
+ return {
+ isAdopted: true,
+ hasDrift: false,
+ lockVersion: committedPin,
+ };
+ }
+
+ if (method === 'svn-zip') {
+ if (lockData.ref && localData.source_ref && lockData.ref !== localData.source_ref) {
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ lockVersion: lockData.ref,
+ message: `Apache Magpie: Snapshot drift detected (${localData.source_ref} -> ${lockData.ref}). Run \`/magpie-setup upgrade\` to reconcile snapshot and overrides.`,
+ };
+ }
+
+ return {
+ isAdopted: true,
+ hasDrift: false,
+ lockVersion: lockData.ref,
+ };
+ }
+ }
+
+ return {
+ isAdopted: true,
+ hasDrift: true,
+ message:
+ 'Apache Magpie: Malformed `.apache-magpie.lock` (unknown or missing method). Run `/magpie-setup upgrade` to repair.',
+ };
+ } catch {
+ return {
+ isAdopted: false,
+ hasDrift: false,
+ };
+ }
+}
+
+/**
+ * Event hook registration entry point for Claude Code.
+ */
+export function register(on: any): void {
+ // 1. Hook session.start to check for lockfile drift
+ on('session.start', async ($: any, e: any, next: any) => {
+ try {
+ const workspaceDir = await $.session.root();
+ const pluginDir = $.plugin.root;
+
+ const result = await checkSetupDrift(
+ async (p) => await $.fs.exists(p),
+ async (p) => await $.fs.read(p),
+ workspaceDir,
+ pluginDir
+ );
+
+ if (result.hasDrift && result.message) {
+ await update($, driftNotice, () => result.message);
+ try {
+ $.ui.invalidate('ui.render');
+ } catch {
+ // fallback
+ }
+ } else {
+ await update($, driftNotice, () => null);
+ }
+ } catch {
+ // Safe no-op on exception
+ }
+ if (typeof next === 'function') {
+ return next(e);
+ }
+ });
+
+ // 2. Hook ui.render to display AbovePrompt drift banner if detected
+ on('ui.render', { component: 'AbovePrompt' }, async ($: any, e: any, next: any) => {
+ const notice = await read($, driftNotice);
+ if (!notice) {
+ if (typeof next === 'function') return next(e);
+ return;
+ }
+
+ try {
+ const { Box, Text } = $.ui.resolve(e);
+ if (Box && Text) {
+ return Box({
+ padding: 0,
+ children: [
+ Text({
+ children: [`\u26A0 ${notice}`],
+ color: 'warning',
+ bold: true,
+ }),
+ ],
+ });
+ }
+ } catch {
+ // Fallback cleanly
+ }
+
+ if (typeof next === 'function') {
+ return next(e);
+ }
+ });
+}
+
+export default register;
diff --git a/plugins/magpie-setup/hooks/hooks.json b/plugins/magpie-setup/hooks/hooks.json
new file mode 100644
index 00000000..dade963b
--- /dev/null
+++ b/plugins/magpie-setup/hooks/hooks.json
@@ -0,0 +1,21 @@
+{
+ "$schema": "https://code.claude.com/schemas/hooks.json",
+ "description": "Apache Magpie — Claude Code mods for zero-token setup drift detection and workspace verification.",
+ "hooks": {
+ "SessionStart": [
+ {
+ "matcher": "startup",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/check-upgrade.sh\"",
+ "timeout": 10
+ }
+ ]
+ }
+ ]
+ },
+ "modules": [
+ "./drift-check.ts"
+ ]
+}
diff --git a/plugins/magpie-setup/hooks/types.d.ts b/plugins/magpie-setup/hooks/types.d.ts
new file mode 100644
index 00000000..0e866303
--- /dev/null
+++ b/plugins/magpie-setup/hooks/types.d.ts
@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+declare module 'claude-code' {
+ interface PluginState {
+ 'magpie-setup': {
+ driftNotice: string | null;
+ };
+ }
+}
diff --git a/tools/dev/check-family-plugins.py b/tools/dev/check-family-plugins.py
index 456bf78b..88d7fb76 100644
--- a/tools/dev/check-family-plugins.py
+++ b/tools/dev/check-family-plugins.py
@@ -862,9 +862,33 @@ def check(fam: dict[str, set[str]]) -> list[str]:
if not UPGRADE_HOOK.is_file():
errors.append(f"{UPGRADE_HOOK}: missing (magpie-setup's SessionStart upgrade check)")
setup_manifest = PLUGINS / "magpie-setup" / ".claude-plugin" / "plugin.json"
+ setup_hooks_manifest = PLUGINS / "magpie-setup" / "hooks" / "hooks.json"
+ setup_types = PLUGINS / "magpie-setup" / "hooks" / "types.d.ts"
setup_data, _setup_err = load_json(setup_manifest)
- if setup_data is not None and "check-upgrade.sh" not in json.dumps(setup_data.get("hooks", {})):
- errors.append(f"{setup_manifest}: SessionStart hook does not reference check-upgrade.sh")
+ if setup_types.is_file() and setup_data is not None and setup_data.get("types") != "./hooks/types.d.ts":
+ errors.append(f"{setup_manifest}: 'types' must declare './hooks/types.d.ts'")
+ if setup_hooks_manifest.is_file():
+ hooks_data, hooks_err = load_json(setup_hooks_manifest)
+ if hooks_err:
+ errors.append(f"{setup_hooks_manifest}: {hooks_err}")
+ elif hooks_data is not None:
+ if not isinstance(hooks_data, dict):
+ errors.append(f"{setup_hooks_manifest}: expected a JSON object")
+ else:
+ if not isinstance(hooks_data.get("modules"), list) or not hooks_data.get("modules"):
+ errors.append(f"{setup_hooks_manifest}: 'modules' is missing or not a non-empty list")
+ if "check-upgrade.sh" not in json.dumps(hooks_data.get("hooks", {})):
+ errors.append(
+ f"{setup_hooks_manifest}: SessionStart hook does not reference check-upgrade.sh"
+ )
+ if setup_data is not None and "hooks" in setup_data:
+ errors.append(
+ f"{setup_manifest}: declares inline 'hooks' while {setup_hooks_manifest} is present; "
+ "drop inline 'hooks' to avoid duplicate hooks collision in Claude Code"
+ )
+ else:
+ if setup_data is not None and "check-upgrade.sh" not in json.dumps(setup_data.get("hooks", {})):
+ errors.append(f"{setup_manifest}: SessionStart hook does not reference check-upgrade.sh")
errors += check_setup_preflight_package()
errors += check_setup_templates()
@@ -1095,9 +1119,11 @@ def fix(fam: dict[str, set[str]]) -> int:
"name": name,
"description": f"Apache Magpie — {DESC.get(family, family + ' family skills')}",
**shared,
- "skills": "./skills",
}
- if name == "magpie-setup":
+ if (pdir / "hooks" / "types.d.ts").is_file():
+ manifest["types"] = "./hooks/types.d.ts"
+ manifest["skills"] = "./skills"
+ if name == "magpie-setup" and not (pdir / "hooks" / "hooks.json").is_file():
manifest["hooks"] = SETUP_HOOKS
(pdir / ".claude-plugin" / "plugin.json").write_text(
json.dumps(manifest, indent=2) + "\n", encoding="utf-8"