@hasna/skills 0.10.56 → 0.10.57

package/bin/mcp.js

@@ -20019,7 +20019,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.56",
+    version: "0.10.57",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {

package/bin/migrate.js

@@ -25,7 +25,7 @@ import { join as join5 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.56",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

@@ -24140,7 +24140,7 @@ restoreLaunchCwd();
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.56",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

@@ -24143,7 +24143,7 @@ import { randomUUID as randomUUID6 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.56",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/index.d.ts

@@ -65,6 +65,8 @@ export type { ClaudeManagedHookProjection, ClaudeManagedHookProjectionOptions }
 export { captureDiscoveryDirectories, captureDiscoveryByteSources, captureDiscoveryPathSources, DISCOVERY_ROOT_UNRESOLVED, isDiscoveryRootUnresolved, type DiscoveryDirectory, type DiscoveryExecutable, type DiscoverySource } from "./lib/agent-discovery.js";
 export { captureClaudeMarketplaceRegistry, captureClaudeMarketplaceRegistryV2 } from "./lib/claude-marketplace-registry.js";
 export { captureClaudeMarketplaceEntry, hashClaudeMarketplaceEntry, CLAUDE_MARKETPLACE_ENTRY_HASH_MODE, type ClaudeMarketplaceEntrySelector, type ClaudeMarketplaceEntryWitness } from "./lib/claude-marketplace-entry-witness.js";
+export { captureClaudeProspectiveCandidateClosure } from "./lib/claude-prospective-review.js";
+export { hashClaudePluginManifest } from "./lib/claude-plugin-manifest-witness.js";
 export { captureClaudeSettings, captureClaudeSettingsV2, captureClaudeSettingsV3, captureClaudeSettingsV4, upgradeClaudeSettingsWitness, upgradeClaudeSettingsWitnessV4 } from "./lib/claude-settings-witness.js";
 export { buildPluginProjection, pluginTreeDigest, type PluginProjectionManifest, type PluginPayloadMapping, type PluginFileWitness } from "./lib/plugin-projection.js";
 export { planPluginAdmission, admitPlugin, resolveAdmittedPlugin, pluginResolverCommand, type PluginAdmissionTarget, type PluginAdmissionBinding, type PluginAdmissionPrincipal, type PluginAdmissionPlan, type PluginAdmissionIdentity, type PluginBundleIdentity, type PluginRoutingIdentity, type PluginAdmissionReceipt } from "./lib/plugin-admission.js";

package/dist/index.js

@@ -11833,7 +11833,7 @@ function replaceSkillSession(expected, replacement, plan, options = {}, beforeCo
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.56",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -48343,6 +48343,89 @@ async function reconcileSkillSession(input2, options = {}) {
   const result = replaceSkillSession(skillSessionSnapshotBinding(snapshot2), replacement, { ...plan, planDigest }, options, () => assertPlanWindow(issuedAt, expiresAt, (options.now ?? Date.now)()));
   return { applied: true, plan, planDigest, ...result };
 }
+// src/lib/claude-prospective-review.ts
+import { createHash as createHash35 } from "crypto";
+import { lstatSync as lstatSync28, readFileSync as readFileSync30, readdirSync as readdirSync17, realpathSync as realpathSync15 } from "fs";
+import { basename as basename14, dirname as dirname30, isAbsolute as isAbsolute26, join as join44, relative as relative12, resolve as resolve27, sep as sep15 } from "path";
+var MAX_CANDIDATE_FILES = 16384;
+var MAX_CANDIDATE_BYTES = 256 * 1024 * 1024;
+var sha6 = (data) => createHash35("sha256").update(data).digest("hex");
+function refuse4(reason2) {
+  throw new Error(`CLAUDE_CANDIDATE_REVIEW_REFUSED: ${reason2}`);
+}
+var GENERATED_MARKETPLACE_TIME = Object.freeze({ $generated: "claude-utc-timestamp", field: "known-marketplaces.lastUpdated" });
+var GENERATED_FRESH_PLUGIN_INSTALLED_AT = Object.freeze({ $generated: "claude-utc-timestamp", field: "installed_plugins.fresh-row.installedAt" });
+var GENERATED_PLUGIN_UPDATE_TIME = Object.freeze({ $generated: "claude-utc-timestamp", field: "installed_plugins.selected-row.lastUpdated" });
+function abs(path, name) {
+  if (typeof path !== "string" || !path || path.length > 4096 || /[\x00-\x1f\x7f]/.test(path) || !isAbsolute26(path) || resolve27(path) !== path)
+    refuse4(`${name} must be a normalized absolute path`);
+}
+function safeFile(path, name) {
+  abs(path, name);
+  for (let at = dirname30(path);; at = dirname30(at)) {
+    const stat3 = lstatSync28(at, { throwIfNoEntry: false });
+    if (!stat3?.isDirectory() || stat3.isSymbolicLink())
+      refuse4(`${name} traverses a symlink or non-directory`);
+    if (at === dirname30(at))
+      break;
+  }
+  const stat2 = lstatSync28(path, { throwIfNoEntry: false });
+  if (!stat2?.isFile() || stat2.isSymbolicLink() || stat2.size > MAX_CANDIDATE_BYTES)
+    refuse4(`${name} is not a bounded regular file`);
+  return readFileSync30(path);
+}
+function canonicalDir(path, name) {
+  abs(path, name);
+  if (realpathSync15(path) !== path || !lstatSync28(path).isDirectory())
+    refuse4(`${name} is not a canonical directory`);
+  for (let at = path;; at = dirname30(at)) {
+    const stat2 = lstatSync28(at);
+    if (!stat2.isDirectory() || stat2.isSymbolicLink())
+      refuse4(`${name} traverses a symlink`);
+    if (at === dirname30(at))
+      break;
+  }
+}
+function captureClaudeProspectiveCandidateClosure(root2) {
+  canonicalDir(root2, "candidate root");
+  const entries = [];
+  let bytes = 0;
+  const walk2 = (directory2) => {
+    const beforeDirectory = lstatSync28(directory2);
+    const names = readdirSync17(directory2).sort();
+    if (new Set(names).size !== names.length)
+      refuse4("candidate contains ambiguous directory entries");
+    for (const name of names) {
+      if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\") || /[\x00-\x1f\x7f]/.test(name))
+        refuse4("candidate contains an unsupported path member");
+      const path = join44(directory2, name), rel = relative12(root2, path).split(sep15).join("/");
+      if (entries.length >= MAX_CANDIDATE_FILES)
+        refuse4("candidate closure exceeds its member limit");
+      const stat2 = lstatSync28(path);
+      if (stat2.isSymbolicLink())
+        refuse4("candidate closure contains a symlink");
+      if (stat2.isDirectory()) {
+        entries.push([rel, "directory", null]);
+        walk2(path);
+      } else if (stat2.isFile()) {
+        bytes += stat2.size;
+        if (bytes > MAX_CANDIDATE_BYTES)
+          refuse4("candidate closure exceeds its byte limit");
+        const content = safeFile(path, "candidate member"), after = lstatSync28(path);
+        if (!after.isFile() || after.dev !== stat2.dev || after.ino !== stat2.ino || after.size !== stat2.size || after.mtimeMs !== stat2.mtimeMs || after.ctimeMs !== stat2.ctimeMs)
+          refuse4("candidate member changed while being read");
+        entries.push([rel, "file", sha6(content)]);
+      } else
+        refuse4("candidate closure contains a special file");
+    }
+    const afterDirectory = lstatSync28(directory2);
+    if (!afterDirectory.isDirectory() || afterDirectory.dev !== beforeDirectory.dev || afterDirectory.ino !== beforeDirectory.ino || afterDirectory.mtimeMs !== beforeDirectory.mtimeMs || afterDirectory.ctimeMs !== beforeDirectory.ctimeMs)
+      refuse4("candidate directory changed while being read");
+  };
+  walk2(root2);
+  entries.sort((a, b) => a[0].localeCompare(b[0]));
+  return sha6(JSON.stringify(entries));
+}
 export {
   writeStationSnapshot,
   writeStationHydration,
@@ -48483,6 +48566,7 @@ export {
   inspectPrivatePublication,
   importSkillsLocalSnapshot,
   homePathFor,
+  hashClaudePluginManifest,
   hashClaudeMarketplaceEntry,
   getToolPrimitive,
   getStorageStatus,
@@ -48566,6 +48650,7 @@ export {
   captureClaudeSettingsV3,
   captureClaudeSettingsV2,
   captureClaudeSettings,
+  captureClaudeProspectiveCandidateClosure,
   captureClaudeMarketplaceRegistryV2,
   captureClaudeMarketplaceRegistry,
   captureClaudeMarketplaceEntry,

package/dist/lib/agent-integration.d.ts

@@ -99,6 +99,8 @@ export interface AgentIntegrationPlan {
 }
 /** Normalize only the verified OS prefix, never hide user-controlled links. */
 export declare function canonicalSystemPath(path: string): string;
+export declare function canonicalAgentPath(path: string, aliases: AgentRootAlias[]): string;
+export declare function recheckRootAliases(aliases: AgentRootAlias[]): void;
 /** Parse the reviewed exact-target binding used by native migration. Paths are
  * deliberately project-relative so a manifest cannot silently select another
  * checkout when a project root changes. */

package/dist/lib/claude-prospective-review.d.ts

@@ -0,0 +1,140 @@
+import { type ReviewedDiscoveryInputs } from "./agent-discovery.js";
+export declare const CLAUDE_PROSPECTIVE_REVIEW_SCHEMA: "skills.claude-plugin-prospective-review/v1";
+export interface ClaudeProspectiveReviewRequest {
+    schema: typeof CLAUDE_PROSPECTIVE_REVIEW_SCHEMA;
+    scope: {
+        kind: "user" | "project";
+        projectPath: string;
+    };
+    native: {
+        home: string;
+        executable: {
+            path: string;
+            target: string;
+            version: string;
+            sha256: string;
+        };
+        configRoot: string;
+        pluginRoot: string;
+    };
+    skills: {
+        dataDir: string;
+        policySha256: string;
+        discoverySha256: string;
+        discoveryInputs: ReviewedDiscoveryInputs;
+    };
+    candidate: {
+        marketplace: string;
+        root: string;
+        catalogPath: string;
+        catalogSha256: string;
+        closureSha256: string;
+        plugins: Array<{
+            plugin: string;
+            manifestPath: string;
+            manifestSha256: string;
+            optionsPatch: Record<string, unknown>;
+        }>;
+        releaseManifest?: {
+            path: string;
+            sha256: string;
+        };
+        functionHooksEnv?: "1";
+    };
+    preimages: {
+        settings: {
+            path: string;
+            sha256: string | null;
+        };
+        userSettings: {
+            path: string;
+            sha256: string | null;
+        };
+        projectSettings: {
+            path: string;
+            sha256: string | null;
+        };
+        projectSettingsLocal: {
+            path: string;
+            sha256: string | null;
+        };
+        marketplaces: {
+            path: string;
+            sha256: string | null;
+        };
+        installedPlugins: {
+            path: string;
+            sha256: string | null;
+        };
+    };
+    /** Complete semantic documents expected after native adoption. The one
+     * timestamps generated by Claude for the owned marketplace and registration
+     * rows use exact typed field markers documented below; every other field is
+     * concrete. */
+    delta: {
+        settingsAfter: Record<string, unknown>;
+        knownMarketplacesAfter: Record<string, unknown>;
+        installedPluginsAfter: Record<string, unknown>;
+    };
+    review: {
+        pluginHooks: "reviewed-no-skill-injection";
+    };
+}
+export interface ClaudeProspectiveReviewReceipt {
+    schema: typeof CLAUDE_PROSPECTIVE_REVIEW_SCHEMA;
+    accepted: true;
+    applied: false;
+    scope: ClaudeProspectiveReviewRequest["scope"];
+    pluginIds: string[];
+    native: {
+        executablePath: string;
+        executableTarget: string;
+        executableVersion: string;
+        executableSha256: string;
+        configRoot: string;
+        pluginRoot: string;
+    };
+    candidate: {
+        marketplace: string;
+        plugins: Array<{
+            plugin: string;
+            pluginId: string;
+            manifestSha256: string;
+            optionsPatchSha256: string;
+        }>;
+        closureSha256: string;
+        catalogSha256: string;
+        releaseManifest?: {
+            path: string;
+            sha256: string;
+        };
+    };
+    targetSettingsPath: string;
+    skillsDiscoverySha256: string;
+    requestFileSha256: string;
+    semanticDocumentsSha256: string;
+    operationSha256: string;
+    expectedPostStateSha256: string;
+    preimages: Array<{
+        name: string;
+        path: string;
+        sha256: string | null;
+    }>;
+    ownedDelta: {
+        settingsEnabledPlugins: string[];
+        selectedPluginOptions: string[];
+        functionHooksEnv: string | null;
+        knownMarketplace: string;
+        installedPlugins: string[];
+        unrelatedGraph: "preserved-by-complete-semantic-documents";
+    };
+    identityPrecondition: "Harnesses must resolve the installed Claude home/config/plugin roots and executable path/version/hash plus the installed Skills data directory through their package-owned consumers, then compare every value before trusting this receipt; this validator checks supplied paths and current bytes only and does not establish actual consumer identity";
+    reviewPrecondition: "The caller's no-skill-injection assessment is bound to the raw request hash; structural checks are not semantic hook review, and Harnesses must retain its existing review record and verify the exact candidate binding";
+    limitation: "validation-only; native installer atomicity and crash recovery are not established";
+}
+/** Fingerprint every file byte and directory name under the frozen candidate.
+ * Symlinks and special files refuse; the digest binds the complete closure. */
+export declare function captureClaudeProspectiveCandidateClosure(root: string): string;
+/** Validate a frozen candidate review against the current filesystem. This is
+ * intentionally a planner only: its receipt is not native-install authority. */
+export declare function reviewClaudeProspectiveCandidate(request: ClaudeProspectiveReviewRequest, requestFileSha256: string): ClaudeProspectiveReviewReceipt;

package/dist/sdk/index.js

@@ -32373,7 +32373,7 @@ var init_event_sink = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.56",
+  version: "0.10.57",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/docs/plugin-admission.md

@@ -173,6 +173,65 @@ new loaders still require their dedicated review. API failure refuses an update;
 stale projection as synchronized. Claude may retain its previous installation
 after a refused update, whose existing local drift checks continue to apply.
 
+## Prospective Claude candidate review
+
+Before adding or changing a marketplace, an installer may call
+`skills hook review-claude-candidate --request <absolute-json-path> --json`.
+The `skills.claude-plugin-prospective-review/v1` request binds one frozen
+marketplace/catalog closure and a non-empty `plugins` array. Each selected
+plugin supplies its exact `plugin`, `manifestPath`, `manifestSha256` and bounded
+JSON `optionsPatch`; an optional `releaseManifest` carries the separate
+release.json path and raw-byte SHA-256. The request also binds current Skills
+and Claude preimages, explicit user/project scope, caller assessment and one
+complete expected semantic document set for the whole selected plugin batch.
+The validator checks every selected manifest and source against the same
+closure before returning one receipt. It derives the owned changes and refuses
+any unrelated graph change. Harnesses validates each options patch against its
+release manifest before invoking Claude; Skills does not copy its private
+option allowlists or infer that caller-supplied options are release-approved.
+The supported catalog shape uses relative selected-plugin sources inside that
+closure. Nontrivial `metadata.pluginRoot` values and native catalog or selected
+plugin dependency declarations refuse because this validator does not resolve
+or review unselected external plugins.
+The request may declare `functionHooksEnv: "1"`; without that declaration the
+environment document is preserved unchanged. The validator shallow-merges
+each declared options patch into the selected plugin's existing `options`;
+the patch must explicitly bind `enabled: true`, and the validator enforces that
+value after merging. This preserves all other selected options and unrelated
+plugin configuration. It refuses a selected `enabledPlugins` array shape that
+this schema does not model. Existing target registration rows keep their array
+positions, new rows append, and unrelated rows remain byte-semantically bound.
+Its receipt binds the raw request bytes and the complete projected documents;
+semantic digests use UTF-8 JSON with object keys recursively sorted in
+ECMAScript UTF-16 order, array order retained and JavaScript JSON primitive
+serialization.
+
+Native-generated fields use typed markers only in the exact selected rows:
+`{"$generated":"claude-utc-timestamp","field":"<path>"}` requires a valid generated
+UTC timestamp at that field. For a native update that may preserve or refresh
+`lastUpdated`, `{"$allowed":[<exact prior timestamp>,<generated marker>]}` permits
+only those two values. Existing `installedAt` remains exact; a fresh install's
+`installedAt` is generated. No other row fields accept markers.
+
+This is a read-only validator. It does not establish that caller-supplied
+`native.home`, config/plugin roots, executable identity or Skills `dataDir` are
+the installed consumers. Harnesses must resolve them through the installed
+package-owned consumers and compare them before trusting the receipt. It must
+also retain its existing review record and bind it to the exact candidate:
+the caller's no-skill-injection assessment is not a semantic hook review, and
+structural refusal checks do not prove hook behavior. Recheck all preimages and
+candidate closure immediately before the first native mutation. The validator
+does not claim native install atomicity or crash recovery.
+
+The optional release manifest witness binds the complete supplied release.json
+file bytes, path and SHA-256 in the request/receipt. Harnesses remains
+responsible for verifying that its release options correspond to every
+selected `optionsPatch`; the public Skills validator deliberately does not
+interpret private release schemas.
+Installed consumers can use the public `captureClaudeProspectiveCandidateClosure`
+and `hashClaudePluginManifest` exports to prepare the exact digests without
+copying the package's hashing algorithms.
+
 ## Reviewed plugin-hook attestation scope
 
 A reviewed discovery input carries `pluginHooks: "reviewed-no-skill-injection"`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.10.56",
+  "version": "0.10.57",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {