javi-forge 1.28.1 → 1.29.0

package/dist/lib/claude-hook-settings.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure settings-entry ownership recognition for the SkillGuard Claude
+ * PreToolUse guard (Slice 2). Every function takes already-parsed JS values and
+ * returns values — ZERO filesystem access (all bytes-on-disk access lives in
+ * `claude-hook-manager.ts`). It covers protocol-shape validation, deterministic
+ * canonical identity (Decision ②: the live asset SHA token is normalized out
+ * before hashing), exact v0 legacy recognition by deep structural equality, and
+ * removal/merge PLANNING only. Identity is always recomputed from observed
+ * structure; a marker only claims ownership, it never proves it.
+ */
+import { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX } from "./__fixtures__/claude-hook-ownership.js";
+export { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, };
+/** The nine independent component states (identical for asset and settings). */
+export type ClaudeHookComponentState = "absent" | "managed-current" | "released-outdated" | "exact-legacy" | "edited-managed" | "foreign" | "symlink" | "non-regular" | "malformed";
+/** A released settings-entry identity: version plus placeholder-normalized hash. */
+export interface CanonicalSettingsEntry {
+    version: number;
+    canonicalSha256: string;
+}
+/** The manifest's settings-entry identity binding. */
+export interface SettingsIdentityManifest {
+    current: CanonicalSettingsEntry | null;
+    historical: CanonicalSettingsEntry[];
+}
+/** Result of classifying a settings container against the manifest identity. */
+export interface SettingsClassification {
+    state: ClaudeHookComponentState;
+    version?: number;
+    canonicalSha256?: string;
+    detail?: string;
+    /** Index of the marked group inside `hooks.PreToolUse`. */
+    groupIndex?: number;
+    /** Index of the marked handler inside the group's `hooks`. */
+    handlerIndex?: number;
+}
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * A valid settings container is an object; when `hooks` is present it MUST be
+ * an object; when `hooks.PreToolUse` is present it MUST be an array. Anything
+ * else is malformed.
+ */
+export declare function validateSettingsShape(parsed: unknown): boolean;
+/**
+ * Replace the trailing 64-hex asset SHA token in a managed `statusMessage` with
+ * the fixed placeholder so settings identity is invariant under asset rotation.
+ * A non-managed or malformed token is returned unchanged so it hashes to a
+ * distinct (non-current) value.
+ */
+export declare function normalizeStatusMessage(statusMessage: unknown): string;
+/** Parse the marker version (`…:v1:…` → 1) for diagnostics only. */
+export declare function parseVersionFromStatus(statusMessage: unknown): number | undefined;
+/**
+ * Canonicalize the marker-proven handler group into deterministic bytes and its
+ * SHA-256. Fixed key order (`type,command,args,timeout,statusMessage` inside a
+ * `matcher,hooks` group), the asset-SHA token normalized out, two-space indent
+ * plus a trailing newline. Only the single handler participates.
+ */
+export declare function canonicalizeSettingsEntry(group: unknown, handler: unknown): {
+    serialization: string;
+    canonicalSha256: string;
+};
+/**
+ * Order-sensitive for arrays, key-set-exact (order-insensitive) for objects,
+ * strict for scalars. No substring, normalization, or tolerance.
+ */
+export declare function deepStructuralEqual(a: unknown, b: unknown): boolean;
+/**
+ * In-object legacy recognition: exactly one deep-equal match for each of the
+ * four cohort objects (L1–L3 Pre, L4 Post) is `exact-legacy`; a partial,
+ * duplicate, or edited cohort is `foreign` (partial-legacy); unrecognized
+ * PreToolUse handler content is `foreign` per spec R2; only a container with no
+ * PreToolUse handler content is `absent` (installable). Whole-file SHA legacy is
+ * decided by the manager, which holds the raw bytes. (Spec R2 overrides
+ * design.md Algorithm C, which returns `absent` for the no-cohort fallthrough
+ * and so cannot flag a resembling unmarked handler.)
+ */
+export declare function classifyLegacy(parsed: unknown): SettingsClassification;
+/**
+ * Reduce a parsed settings container to one component state, from parsed
+ * structure only. Shape validation first, then marker-driven identity (always
+ * recomputed), then the legacy fallback when no marker is present.
+ */
+export declare function classifySettingsEntry(parsed: unknown, _currentAssetSha: string, identities: SettingsIdentityManifest): SettingsClassification;
+export interface ManagedRemovalPlan {
+    refused: boolean;
+    reason?: string;
+    state: ClaudeHookComponentState;
+    groupIndex?: number;
+    handlerIndex?: number;
+    /** True when removing the managed handler empties the group. */
+    removeGroup?: boolean;
+    /** Sibling handlers in the group that removal must preserve. */
+    preservedSiblings?: number;
+}
+/**
+ * Plan removal of the marker-proven managed handler. Only a recognized managed
+ * identity (`managed-current` or `released-outdated`) is eligible; foreign,
+ * partial-legacy, edited-managed, and every non-regular state refuse.
+ */
+export declare function planManagedClaudeHookRemoval(parsed: unknown, currentAssetSha: string, identities: SettingsIdentityManifest): ManagedRemovalPlan;
+export interface ManagedMergePlan {
+    refused: boolean;
+    reason?: string;
+    state: ClaudeHookComponentState;
+    action: "install" | "replace" | "noop" | "refuse";
+    groupIndex?: number;
+    handlerIndex?: number;
+    preservedSiblings?: number;
+}
+/**
+ * Plan the managed merge. `absent` installs a new group, `managed-current` is a
+ * no-op, `released-outdated` replaces the marked handler in place (siblings
+ * preserved), and every other state refuses (edited/force is a Slice-3 concern).
+ */
+export declare function planManagedClaudeHookMerge(parsed: unknown, currentAssetSha: string, identities: SettingsIdentityManifest): ManagedMergePlan;
+//# sourceMappingURL=claude-hook-settings.d.ts.map

package/dist/lib/claude-hook-settings.js

@@ -0,0 +1,283 @@
+/**
+ * Pure settings-entry ownership recognition for the SkillGuard Claude
+ * PreToolUse guard (Slice 2). Every function takes already-parsed JS values and
+ * returns values — ZERO filesystem access (all bytes-on-disk access lives in
+ * `claude-hook-manager.ts`). It covers protocol-shape validation, deterministic
+ * canonical identity (Decision ②: the live asset SHA token is normalized out
+ * before hashing), exact v0 legacy recognition by deep structural equality, and
+ * removal/merge PLANNING only. Identity is always recomputed from observed
+ * structure; a marker only claims ownership, it never proves it.
+ */
+import { createHash } from "node:crypto";
+import { ASSET_SHA_PLACEHOLDER, LEGACY_COHORT, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, } from "./__fixtures__/claude-hook-ownership.js";
+export { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, };
+// Shape helpers
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * A valid settings container is an object; when `hooks` is present it MUST be
+ * an object; when `hooks.PreToolUse` is present it MUST be an array. Anything
+ * else is malformed.
+ */
+export function validateSettingsShape(parsed) {
+    if (!isPlainObject(parsed))
+        return false;
+    const { hooks } = parsed;
+    if (hooks !== undefined && !isPlainObject(hooks))
+        return false;
+    const pre = isPlainObject(hooks) ? hooks.PreToolUse : undefined;
+    if (pre !== undefined && !Array.isArray(pre))
+        return false;
+    return true;
+}
+// Canonical identity (Decision ②)
+const ASSET_SHA_TOKEN = /^[0-9a-f]{64}$/;
+const VERSION_PATTERN = /^javi-forge-global-pretooluse:v(\d+):sha256:/;
+/**
+ * Replace the trailing 64-hex asset SHA token in a managed `statusMessage` with
+ * the fixed placeholder so settings identity is invariant under asset rotation.
+ * A non-managed or malformed token is returned unchanged so it hashes to a
+ * distinct (non-current) value.
+ */
+export function normalizeStatusMessage(statusMessage) {
+    if (typeof statusMessage !== "string")
+        return "";
+    if (!statusMessage.startsWith(MANAGED_STATUS_PREFIX))
+        return statusMessage;
+    const token = statusMessage.slice(MANAGED_STATUS_PREFIX.length);
+    return ASSET_SHA_TOKEN.test(token)
+        ? `${MANAGED_STATUS_PREFIX}${ASSET_SHA_PLACEHOLDER}`
+        : statusMessage;
+}
+/** Parse the marker version (`…:v1:…` → 1) for diagnostics only. */
+export function parseVersionFromStatus(statusMessage) {
+    if (typeof statusMessage !== "string")
+        return undefined;
+    const match = VERSION_PATTERN.exec(statusMessage);
+    return match ? Number(match[1]) : undefined;
+}
+/**
+ * Canonicalize the marker-proven handler group into deterministic bytes and its
+ * SHA-256. Fixed key order (`type,command,args,timeout,statusMessage` inside a
+ * `matcher,hooks` group), the asset-SHA token normalized out, two-space indent
+ * plus a trailing newline. Only the single handler participates.
+ */
+export function canonicalizeSettingsEntry(group, handler) {
+    const h = isPlainObject(handler) ? handler : {};
+    const g = isPlainObject(group) ? group : {};
+    const canonicalHandler = {
+        type: h.type,
+        command: h.command,
+        args: h.args,
+        timeout: h.timeout,
+        statusMessage: normalizeStatusMessage(h.statusMessage),
+    };
+    const canonicalGroup = { matcher: g.matcher, hooks: [canonicalHandler] };
+    const serialization = `${JSON.stringify(canonicalGroup, null, 2)}\n`;
+    const canonicalSha256 = createHash("sha256")
+        .update(serialization, "utf8")
+        .digest("hex");
+    return { serialization, canonicalSha256 };
+}
+// Legacy recognition (deep structural equality only)
+/**
+ * Order-sensitive for arrays, key-set-exact (order-insensitive) for objects,
+ * strict for scalars. No substring, normalization, or tolerance.
+ */
+export function deepStructuralEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+            return false;
+        }
+        return a.every((item, index) => deepStructuralEqual(item, b[index]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length)
+            return false;
+        return keysA.every((key) => Object.hasOwn(b, key) && deepStructuralEqual(a[key], b[key]));
+    }
+    return false;
+}
+function countDeepMatches(target, list) {
+    let count = 0;
+    for (const item of list)
+        if (deepStructuralEqual(target, item))
+            count++;
+    return count;
+}
+/**
+ * In-object legacy recognition: exactly one deep-equal match for each of the
+ * four cohort objects (L1–L3 Pre, L4 Post) is `exact-legacy`; a partial,
+ * duplicate, or edited cohort is `foreign` (partial-legacy); unrecognized
+ * PreToolUse handler content is `foreign` per spec R2; only a container with no
+ * PreToolUse handler content is `absent` (installable). Whole-file SHA legacy is
+ * decided by the manager, which holds the raw bytes. (Spec R2 overrides
+ * design.md Algorithm C, which returns `absent` for the no-cohort fallthrough
+ * and so cannot flag a resembling unmarked handler.)
+ */
+export function classifyLegacy(parsed) {
+    const hooks = isPlainObject(parsed) ? parsed.hooks : undefined;
+    const pre = isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+    const post = isPlainObject(hooks) && Array.isArray(hooks.PostToolUse)
+        ? hooks.PostToolUse
+        : [];
+    const counts = [
+        countDeepMatches(LEGACY_COHORT.L1, pre),
+        countDeepMatches(LEGACY_COHORT.L2, pre),
+        countDeepMatches(LEGACY_COHORT.L3, pre),
+        countDeepMatches(LEGACY_COHORT.L4, post),
+    ];
+    if (counts.every((count) => count === 1)) {
+        return { state: "exact-legacy", detail: "cohort" };
+    }
+    if (counts.some((count) => count >= 1)) {
+        return { state: "foreign", detail: "partial-legacy" };
+    }
+    const preHandlers = pre.reduce((total, group) => total +
+        (isPlainObject(group) && Array.isArray(group.hooks)
+            ? group.hooks.length
+            : 0), 0);
+    if (preHandlers > 0)
+        return { state: "foreign", detail: "no-marker" };
+    return { state: "absent" };
+}
+function findManagedMarkers(groups) {
+    const markers = [];
+    for (let groupIndex = 0; groupIndex < groups.length; groupIndex++) {
+        const group = groups[groupIndex];
+        const handlers = isPlainObject(group) && Array.isArray(group.hooks) ? group.hooks : [];
+        for (let handlerIndex = 0; handlerIndex < handlers.length; handlerIndex++) {
+            const handler = handlers[handlerIndex];
+            if (isPlainObject(handler) &&
+                typeof handler.statusMessage === "string" &&
+                handler.statusMessage.startsWith(MANAGED_STATUS_PREFIX)) {
+                markers.push({ groupIndex, handlerIndex, group, handler });
+            }
+        }
+    }
+    return markers;
+}
+function isValidMatcherGroup(group) {
+    return (isPlainObject(group) &&
+        typeof group.matcher === "string" &&
+        Array.isArray(group.hooks));
+}
+/**
+ * Reduce a parsed settings container to one component state, from parsed
+ * structure only. Shape validation first, then marker-driven identity (always
+ * recomputed), then the legacy fallback when no marker is present.
+ */
+export function classifySettingsEntry(parsed, _currentAssetSha, identities) {
+    if (!validateSettingsShape(parsed))
+        return { state: "malformed" };
+    const hooks = isPlainObject(parsed) ? parsed.hooks : undefined;
+    const groups = isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+    const markers = findManagedMarkers(groups);
+    if (markers.length > 1) {
+        return { state: "edited-managed", detail: "multiple markers" };
+    }
+    if (markers.length === 0)
+        return classifyLegacy(parsed);
+    const marker = markers[0];
+    if (!isValidMatcherGroup(marker.group)) {
+        return { state: "edited-managed", detail: "marker in invalid container" };
+    }
+    const { canonicalSha256 } = canonicalizeSettingsEntry(marker.group, marker.handler);
+    const version = parseVersionFromStatus(marker.handler.statusMessage);
+    const base = {
+        version,
+        canonicalSha256,
+        groupIndex: marker.groupIndex,
+        handlerIndex: marker.handlerIndex,
+    };
+    if (identities.current &&
+        canonicalSha256 === identities.current.canonicalSha256) {
+        return { state: "managed-current", ...base };
+    }
+    if (identities.historical.some((entry) => entry.canonicalSha256 === canonicalSha256)) {
+        return { state: "released-outdated", ...base };
+    }
+    return { state: "edited-managed", ...base };
+}
+function groupHandlerCount(parsed, groupIndex) {
+    const hooks = isPlainObject(parsed) ? parsed.hooks : undefined;
+    const groups = isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+    const group = groups[groupIndex];
+    return isPlainObject(group) && Array.isArray(group.hooks)
+        ? group.hooks.length
+        : 0;
+}
+/**
+ * Plan removal of the marker-proven managed handler. Only a recognized managed
+ * identity (`managed-current` or `released-outdated`) is eligible; foreign,
+ * partial-legacy, edited-managed, and every non-regular state refuse.
+ */
+export function planManagedClaudeHookRemoval(parsed, currentAssetSha, identities) {
+    const cls = classifySettingsEntry(parsed, currentAssetSha, identities);
+    if (cls.state === "managed-current" || cls.state === "released-outdated") {
+        const handlerCount = groupHandlerCount(parsed, cls.groupIndex ?? -1);
+        const preservedSiblings = Math.max(handlerCount - 1, 0);
+        return {
+            refused: false,
+            state: cls.state,
+            groupIndex: cls.groupIndex,
+            handlerIndex: cls.handlerIndex,
+            removeGroup: preservedSiblings === 0,
+            preservedSiblings,
+        };
+    }
+    return {
+        refused: true,
+        reason: `refuse removal for state ${cls.state}`,
+        state: cls.state,
+    };
+}
+/**
+ * Plan the managed merge. `absent` installs a new group, `managed-current` is a
+ * no-op, `released-outdated` replaces the marked handler in place (siblings
+ * preserved), and every other state refuses (edited/force is a Slice-3 concern).
+ */
+export function planManagedClaudeHookMerge(parsed, currentAssetSha, identities) {
+    const cls = classifySettingsEntry(parsed, currentAssetSha, identities);
+    if (cls.state === "absent") {
+        return { refused: false, state: cls.state, action: "install" };
+    }
+    if (cls.state === "managed-current") {
+        return {
+            refused: false,
+            state: cls.state,
+            action: "noop",
+            groupIndex: cls.groupIndex,
+            handlerIndex: cls.handlerIndex,
+        };
+    }
+    if (cls.state === "released-outdated") {
+        const preservedSiblings = Math.max(groupHandlerCount(parsed, cls.groupIndex ?? -1) - 1, 0);
+        return {
+            refused: false,
+            state: cls.state,
+            action: "replace",
+            groupIndex: cls.groupIndex,
+            handlerIndex: cls.handlerIndex,
+            preservedSiblings,
+        };
+    }
+    return {
+        refused: true,
+        reason: `refuse merge for state ${cls.state}`,
+        state: cls.state,
+        action: "refuse",
+    };
+}
+//# sourceMappingURL=claude-hook-settings.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.28.1",
+	"version": "1.29.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {