@savvy-web/silk-effects 7.4.0 → 7.5.0

package/changesets/remark/plugins/maintenance-note.js

@@ -1,6 +1,19 @@
 import { getHeadingText, getVersionBlocks } from "../../utils/version-blocks.js";
+import { toString } from "mdast-util-to-string";
 
 //#region src/changesets/remark/plugins/maintenance-note.ts
+/**
+* Placeholder sentence `@changesets/apply-release-plan` (>= 8.1.0) emits as the
+* body of a version block that would otherwise render as a bare heading. Older
+* engine versions left such a block structurally empty.
+*/
+const ENGINE_PLACEHOLDER = "No changes in this release.";
+/** True when the block's only content is the engine's empty-release placeholder. */
+function isPlaceholderOnly(tree, block) {
+	if (block.endIndex - block.startIndex !== 1) return false;
+	const node = tree.children[block.startIndex];
+	return node.type === "paragraph" && toString(node).trim() === ENGINE_PLACEHOLDER;
+}
 function buildNoteChildren(reason) {
 	if (reason.kind === "unspecified" || reason.triggers.length === 0) return [{
 		type: "text",
@@ -31,7 +44,8 @@ const MaintenanceNotePlugin = (options) => {
 	return (tree) => {
 		const block = getVersionBlocks(tree).find((b) => getHeadingText(tree.children[b.headingIndex]) === options.version);
 		if (!block) return;
-		if (block.endIndex > block.startIndex) return;
+		const placeholderOnly = isPlaceholderOnly(tree, block);
+		if (block.endIndex > block.startIndex && !placeholderOnly) return;
 		const heading = {
 			type: "heading",
 			depth: 3,
@@ -53,7 +67,7 @@ const MaintenanceNotePlugin = (options) => {
 				}]
 			}]
 		};
-		tree.children.splice(block.startIndex, 0, heading, list);
+		tree.children.splice(block.startIndex, placeholderOnly ? 1 : 0, heading, list);
 	};
 };
 

package/index.d.ts

@@ -2805,7 +2805,7 @@ declare const ChangesetConfigError_base: new <A extends Record<string, any> = {}
  * @since 0.1.0
  * @public
  */
-declare class ChangesetConfigError extends ChangesetConfigError_base<{
+export declare class ChangesetConfigError extends ChangesetConfigError_base<{
   readonly path: string;
   readonly reason: string;
 }> {
@@ -2932,7 +2932,7 @@ declare const ChangesetConfigReader_base: Context.ServiceClass<ChangesetConfigRe
  * @since 0.1.0
  * @public
  */
-declare class ChangesetConfigReader extends ChangesetConfigReader_base {
+export declare class ChangesetConfigReader extends ChangesetConfigReader_base {
   /**
    * Production implementation of {@link ChangesetConfigReader}.
    *
@@ -3680,7 +3680,7 @@ declare const ChangesetConfig_base: Context.ServiceClass<ChangesetConfig, "@savv
  * @since 0.4.0
  * @public
  */
-declare class ChangesetConfig extends ChangesetConfig_base {
+export declare class ChangesetConfig extends ChangesetConfig_base {
   /**
    * The one ignore matcher: exact name match, or `@scope/*` wildcard.
    *
@@ -6811,7 +6811,7 @@ declare const BiomeSyncError_base: new <A extends Record<string, any> = {}>(args
  * @since 0.1.0
  * @public
  */
-declare class BiomeSyncError extends BiomeSyncError_base<{
+export declare class BiomeSyncError extends BiomeSyncError_base<{
   readonly path: string;
   readonly reason: string;
 }> {
@@ -6833,7 +6833,7 @@ declare const ConfigNotFoundError_base: new <A extends Record<string, any> = {}>
  * @since 0.1.0
  * @public
  */
-declare class ConfigNotFoundError extends ConfigNotFoundError_base<{
+export declare class ConfigNotFoundError extends ConfigNotFoundError_base<{
   readonly name: string;
   readonly searchedPaths: ReadonlyArray<string>;
 }> {
@@ -6863,7 +6863,7 @@ declare const PublishTargetBindingError_base: new <A extends Record<string, any>
  * @since 3.1.0
  * @public
  */
-declare class PublishTargetBindingError extends PublishTargetBindingError_base<{
+export declare class PublishTargetBindingError extends PublishTargetBindingError_base<{
   /** The package whose targets were being resolved. */
   readonly pkg: string;
   /** The directory detection selected, relative to the package root. */
@@ -6889,7 +6889,7 @@ declare const WorkspaceAnalysisError_base: new <A extends Record<string, any> =
  * @since 0.2.0
  * @public
  */
-declare class WorkspaceAnalysisError extends WorkspaceAnalysisError_base<{
+export declare class WorkspaceAnalysisError extends WorkspaceAnalysisError_base<{
   readonly root: string;
   readonly reason: string;
 }> {
@@ -9842,6 +9842,148 @@ declare const ConfigDiscoveryOptions: Schema.Struct<{
  */
 type ConfigDiscoveryOptions = typeof ConfigDiscoveryOptions.Type;
 //#endregion
+//#region src/schemas/SavvyInstallSection.d.ts
+/**
+ * The hooks {@link savvyInstallDeps} can be generated for.
+ *
+ * @remarks
+ * Both are needed, and `post-merge` is the one that matters most in practice:
+ * a fast-forward `git pull` — the batch-alignment case this exists for — fires
+ * `post-merge` and never `post-checkout`. They are separate spellings rather
+ * than one argument-sniffing block because the two hooks disagree on both
+ * halves of the decision: `post-checkout` is handed `<prev> <new> <flag>` and
+ * must ignore a file checkout, while `post-merge` is handed only a squash flag
+ * and has to recover its own range from `ORIG_HEAD`.
+ *
+ * @since 7.5.0
+ * @public
+ */
+type SavvyInstallHook = "post-checkout" | "post-merge";
+/**
+ * Section identity for the dependency auto-install block.
+ *
+ * `toolName` is `"savvy-install"`; pair with {@link savvyInstallDeps}.
+ *
+ * @since 7.5.0
+ * @public
+ */
+export declare const SavvyInstallSection: SectionId;
+/**
+ * Dependency auto-install shared across Silk Suite hook files.
+ *
+ * @remarks
+ * Brings `node_modules` back in line after a branch switch or a pull, so a batch
+ * of repos pulled to align their dependencies does not each need a manual
+ * install. Installs with lifecycle scripts skipped — `--ignore-scripts`, or
+ * `--mode=skip-build` for Yarn Berry, which dropped the former — because the goal
+ * is to get the dependency tree on disk, not to run a full postinstall.
+ *
+ * **That flag has a cost, and one shape of repo cannot pay it.** Where a package
+ * publishes through a built link directory — `publishConfig.directory` with
+ * `linkDirectory: true`, which is how this monorepo wires `dist/dev/pkg` — the
+ * workspace resolves its own dependencies through a directory that a `prepare`
+ * script has to build, and skipping scripts yields a populated `node_modules`
+ * pointing at nothing.
+ *
+ * Those repos ask for a full install through the LOCAL git config key
+ * `savvy.installLifecycleScripts`, which `savvy init` sets when it finds the
+ * shape. The decision deliberately does NOT read the checked-out tree. Doing so
+ * failed in both directions at once: a branch that merely declared the shape
+ * could turn lifecycle scripts back on just by being checked out, making
+ * `git checkout` of an untrusted revision a code-execution path; and the `jq`
+ * the scan needed is absent on stock macOS and Ubuntu, where the missing answer
+ * silently skipped scripts in precisely the repos that cannot survive it.
+ * `.git/config` is neither checked out nor parsed with `jq`, so it has neither
+ * failure mode.
+ *
+ * The package managers gate dependency scripts themselves on top of this —
+ * pnpm's `strictDepBuilds` with an `allowBuilds` allowlist being the case in
+ * point — but workspace and root lifecycle scripts still run, which is why the
+ * opt-in is local rather than inferred. With the flag on, the hook says on the
+ * way out that scripts were skipped rather than leaving it to be discovered.
+ *
+ * Deliberately self-contained, like `savvyToolchainCheck`: its homes carry
+ * `SavvyHooksSection` but no `SavvyBaseSection`, so it defines its own root, CI
+ * and package-manager lookups rather than depending on `ROOT`, `in_ci` or `PM`.
+ *
+ * Four guards keep it from firing on the many checkouts that are not dependency
+ * events, each a silent no-op:
+ *
+ * - CI, where the runtime action owns installation by construction.
+ * - `SAVVY_SKIP_INSTALL`, the escape hatch for a bisect or a scripted sweep that
+ *   does not want an install between steps.
+ * - `post-checkout` only: a branch-flag of `0`, which is `git checkout -- <file>`
+ *   and not a move between commits.
+ * - **The gate that makes this affordable:** nothing dependency-related actually
+ *   changed across the move. Without it every branch switch would pay for a full
+ *   install. A missing `node_modules` overrides it, since there is nothing to be
+ *   stale.
+ *
+ * A fresh clone is not among the cases it handles, and cannot be: husky sets
+ * `core.hooksPath` from its own `prepare` script, so until the first manual
+ * install has run there is no hook installed to fire.
+ *
+ * The install's exit status is swallowed and its output goes to stderr. Git
+ * ignores what `post-checkout` and `post-merge` return, so a failure here must
+ * not look like a failed checkout; the hint names the escape hatch instead.
+ *
+ * Every probe that can legitimately fail — no `ORIG_HEAD` to compare against, an
+ * unresolvable range — is neutralised with `|| true` rather than left to its own
+ * status. These blocks are co-owned and consumer content can sit below them, so
+ * under a hook running `set -e` a bare failing substitution would abort the whole
+ * file and take those later sections with it.
+ *
+ * @param hook - Which hook the block is being generated for; decides the
+ *   argument guard and how the comparison range is recovered.
+ * @returns The install shell, with no surrounding markers or trailing newline.
+ *
+ * @since 7.5.0
+ * @public
+ */
+export declare function savvyInstallDeps(hook: SavvyInstallHook): string;
+/**
+ * The local git config key that authorizes lifecycle scripts during a hook install.
+ *
+ * @remarks
+ * Local scope only. It lives in `.git/config`, which is never checked out, so no
+ * incoming revision can set it — that is the whole point of reading the decision
+ * from here rather than from a manifest in the tree.
+ *
+ * @since 7.5.0
+ * @public
+ */
+export declare const LIFECYCLE_SCRIPTS_CONFIG_KEY = "savvy.installLifecycleScripts";
+/**
+ * Whether `manifest` publishes through a built link directory.
+ *
+ * @remarks
+ * `publishConfig.directory` with `linkDirectory: true` means consumers of this
+ * package resolve it through a directory that a `prepare` script has to produce,
+ * so an install that skips lifecycle scripts leaves the link pointing at nothing.
+ * A workspace containing any such package is one whose owner probably wants
+ * {@link LIFECYCLE_SCRIPTS_CONFIG_KEY} set.
+ *
+ * Reporting the shape is deliberately separate from acting on it: this answers
+ * "does this repo need scripts", and a human still decides whether hook-time
+ * installs may run them.
+ *
+ * @param manifest - A parsed `package.json`; any non-object reads as `false`.
+ *
+ * @since 7.5.0
+ * @public
+ */
+export declare function publishesBuiltLinkDirectory(manifest: unknown): boolean;
+/**
+ * Build the dependency auto-install block for `hook`.
+ *
+ * @param hook - Which hook the section is destined for.
+ * @returns A shell `Section` (`commentStyle: hash`) keyed `SAVVY-INSTALL`.
+ *
+ * @since 7.5.0
+ * @public
+ */
+export declare function savvyInstallBlock(hook: SavvyInstallHook): Section;
+//#endregion
 //#region src/schemas/SavvySections.d.ts
 /**
  * Section identity for the shared package-manager preamble.
@@ -9856,7 +9998,7 @@ type ConfigDiscoveryOptions = typeof ConfigDiscoveryOptions.Type;
  * @since 0.5.0
  * @public
  */
-declare const SavvyBaseSection: SectionId;
+export declare const SavvyBaseSection: SectionId;
 /**
  * Section identity for the shared repo-hygiene block.
  *
@@ -9865,7 +10007,7 @@ declare const SavvyBaseSection: SectionId;
  * @since 0.5.0
  * @public
  */
-declare const SavvyHooksSection: SectionId;
+export declare const SavvyHooksSection: SectionId;
 /**
  * Package-manager detection preamble shared across Silk Suite hook files.
  *
@@ -9880,7 +10022,7 @@ declare const SavvyHooksSection: SectionId;
  * @since 0.5.0
  * @public
  */
-declare function savvyBasePreamble(): string;
+export declare function savvyBasePreamble(): string;
 /**
  * Repo-hygiene block shared across Silk Suite hook files.
  *
@@ -9893,7 +10035,7 @@ declare function savvyBasePreamble(): string;
  * @since 0.5.0
  * @public
  */
-declare function savvyHooksHygiene(): string;
+export declare function savvyHooksHygiene(): string;
 /**
  * Build a consumer's one-line tool section so every consumer calls the shared base
  * helpers identically.
@@ -9922,7 +10064,7 @@ declare function savvyHooksHygiene(): string;
  * @since 0.5.0
  * @public
  */
-declare function savvyToolSection(toolName: string, command: string): Section;
+export declare function savvyToolSection(toolName: string, command: string): Section;
 /**
  * Section identity for the package-manager toolchain drift check.
  *
@@ -9931,7 +10073,7 @@ declare function savvyToolSection(toolName: string, command: string): Section;
  * @since 7.3.0
  * @public
  */
-declare const SavvyToolchainSection: SectionId;
+export declare const SavvyToolchainSection: SectionId;
 /**
  * Package-manager drift check shared across Silk Suite hook files.
  *
@@ -9959,7 +10101,7 @@ declare const SavvyToolchainSection: SectionId;
  * @since 7.3.0
  * @public
  */
-declare function savvyToolchainCheck(): string;
+export declare function savvyToolchainCheck(): string;
 //#endregion
 //#region src/schemas/WorkspaceAnalysisSchemas.d.ts
 declare const SilkPublishConfig_base: Schema.Class<SilkPublishConfig, Schema.Struct<{
@@ -9989,7 +10131,7 @@ declare const SilkPublishConfig_base: Schema.Class<SilkPublishConfig, Schema.Str
  * @since 0.2.0
  * @public
  */
-declare class SilkPublishConfig extends SilkPublishConfig_base {}
+export declare class SilkPublishConfig extends SilkPublishConfig_base {}
 declare const AnalyzedWorkspace_base: Schema.Class<AnalyzedWorkspace, Schema.TaggedStruct<"AnalyzedWorkspace", {
   readonly name: Schema.String;
   readonly version: Schema.Struct<{
@@ -10013,7 +10155,7 @@ declare const AnalyzedWorkspace_base: Schema.Class<AnalyzedWorkspace, Schema.Tag
  * @since 0.2.0
  * @public
  */
-declare class AnalyzedWorkspace extends AnalyzedWorkspace_base {
+export declare class AnalyzedWorkspace extends AnalyzedWorkspace_base {
   get isRoot(): boolean;
   get isPublishable(): boolean;
   get isReleasable(): boolean;
@@ -10095,7 +10237,7 @@ declare const WorkspaceAnalysis_base: Schema.Class<WorkspaceAnalysis, Schema.Tag
  * @since 0.2.0
  * @public
  */
-declare class WorkspaceAnalysis extends WorkspaceAnalysis_base {
+export declare class WorkspaceAnalysis extends WorkspaceAnalysis_base {
   findWorkspace(name: string): Option.Option<AnalyzedWorkspace>;
   get rootWorkspace(): Option.Option<AnalyzedWorkspace>;
   get publishableWorkspaces(): ReadonlyArray<AnalyzedWorkspace>;
@@ -10121,7 +10263,7 @@ declare class WorkspaceAnalysis extends WorkspaceAnalysis_base {
  * @since 0.1.0
  * @public
  */
-declare function extractSemver(version: string): string;
+export declare function extractSemver(version: string): string;
 /**
  * Build the expected Biome JSON schema URL for a given version.
  *
@@ -10131,7 +10273,7 @@ declare function extractSemver(version: string): string;
  * @since 0.1.0
  * @public
  */
-declare function buildSchemaUrl(version: string): string;
+export declare function buildSchemaUrl(version: string): string;
 /**
  * The {@link BiomeSchemaSync} service shape.
  *
@@ -10192,7 +10334,7 @@ declare const BiomeSchemaSync_base: Context.ServiceClass<BiomeSchemaSync, "@savv
  * @since 0.1.0
  * @public
  */
-declare class BiomeSchemaSync extends BiomeSchemaSync_base {
+export declare class BiomeSchemaSync extends BiomeSchemaSync_base {
   /**
    * Production implementation of {@link BiomeSchemaSync}.
    *
@@ -10268,7 +10410,7 @@ declare const ConfigDiscovery_base: Context.ServiceClass<ConfigDiscovery, "@savv
  * @since 0.1.0
  * @public
  */
-declare class ConfigDiscovery extends ConfigDiscovery_base {
+export declare class ConfigDiscovery extends ConfigDiscovery_base {
   /**
    * Production implementation of {@link ConfigDiscovery}.
    *
@@ -10396,7 +10538,7 @@ interface PublishablePackage {
  * @since 0.4.0
  * @public
  */
-declare class SilkPublishability {
+export declare class SilkPublishability {
   /**
    * Apply silk publishability rules to a raw `package.json` and the bundler's resolved
    * target binding. Targets-first precedence:
@@ -10479,7 +10621,7 @@ declare class SilkPublishability {
  * @since 1.0.0
  * @public
  */
-declare const readTargetsBinding: (fs: FileSystem.FileSystem, pkgPath: string) => Effect.Effect<TargetsBinding | null>;
+export declare const readTargetsBinding: (fs: FileSystem.FileSystem, pkgPath: string) => Effect.Effect<TargetsBinding | null>;
 //#endregion
 //#region src/services/SilkWorkspaceAnalyzer.d.ts
 /**
@@ -10530,7 +10672,7 @@ declare const SilkWorkspaceAnalyzer_base: Context.ServiceClass<SilkWorkspaceAnal
  * @since 0.2.0
  * @public
  */
-declare class SilkWorkspaceAnalyzer extends SilkWorkspaceAnalyzer_base {
+export declare class SilkWorkspaceAnalyzer extends SilkWorkspaceAnalyzer_base {
   /**
    * Production implementation of {@link SilkWorkspaceAnalyzer}.
    *
@@ -10900,5 +11042,5 @@ declare namespace index_d_exports$5 {
   export { AffectedResult, AffectedResultType, CacheDiagnosis, CacheDiagnosisType, DryRunParseError, GlobalHashSummary, GraphNode, MissExplanation, NotATurboRepoError, PackageCacheStatus, TaskGraphResult, TaskGraphResultType, TurboCache, TurboDigest, TurboDryRun, TurboDryRunType, TurboDryTask, TurboDryTaskType, TurboEnvVars, TurboError, TurboExecError, TurboGlobalCacheInputs, TurboInspector, TurboInspectorShape, TurboNotInstalledError };
 }
 //#endregion
-export { AnalyzedWorkspace, BiomeSchemaSync, type BiomeSchemaSyncShape, BiomeSyncError, type BiomeSyncOptions, type BiomeSyncResult, ChangesetConfig, ChangesetConfigError, type ChangesetConfigFile, ChangesetConfigReader, type ChangesetConfigReaderShape, type ChangesetConfigShape, type ChangesetMode, index_d_exports as Changesets, index_d_exports$1 as Commitlint, type CommitlintPlugin, type CommitlintUserConfig, ConfigDiscovery, type ConfigDiscoveryOptions, type ConfigDiscoveryShape, type ConfigLocation, ConfigNotFoundError, type ConfigSource, index_d_exports$2 as Lint, index_d_exports$3 as PrBody, type PromptConfig, type PromptSettings, PublishTargetBindingError, type PublishablePackage, type RawPackageJson, type RawPublishConfig, type RawPublishTargets, type RawTargetObject, type RawTargetValue, index_d_exports$4 as Repos, type RuleApplicability, type RuleConfigTuple, type RuleSeverity, type RulesConfig, SavvyBaseSection, SavvyHooksSection, SavvyToolchainSection, type SilkChangesetConfigFile, SilkPublishConfig, SilkPublishability, SilkWorkspaceAnalyzer, type SilkWorkspaceAnalyzerShape, type TargetBinding, type TargetGroupBinding, type TargetsBinding, index_d_exports$5 as Turbo, WorkspaceAnalysis, WorkspaceAnalysisError, buildSchemaUrl, extractSemver, readTargetsBinding, savvyBasePreamble, savvyHooksHygiene, savvyToolSection, savvyToolchainCheck };
+export { type BiomeSchemaSyncShape, type BiomeSyncOptions, type BiomeSyncResult, type ChangesetConfigFile, type ChangesetConfigReaderShape, type ChangesetConfigShape, type ChangesetMode, index_d_exports as Changesets, index_d_exports$1 as Commitlint, type CommitlintPlugin, type CommitlintUserConfig, type ConfigDiscoveryOptions, type ConfigDiscoveryShape, type ConfigLocation, type ConfigSource, index_d_exports$2 as Lint, index_d_exports$3 as PrBody, type PromptConfig, type PromptSettings, type PublishablePackage, type RawPackageJson, type RawPublishConfig, type RawPublishTargets, type RawTargetObject, type RawTargetValue, index_d_exports$4 as Repos, type RuleApplicability, type RuleConfigTuple, type RuleSeverity, type RulesConfig, type SavvyInstallHook, type SilkChangesetConfigFile, type SilkWorkspaceAnalyzerShape, type TargetBinding, type TargetGroupBinding, type TargetsBinding, index_d_exports$5 as Turbo };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -12,10 +12,11 @@ import { WorkspaceAnalysisError } from "./errors/WorkspaceAnalysisError.js";
 import { lint_exports } from "./lint/index.js";
 import { pr_body_exports } from "./pr-body/index.js";
 import { repos_exports } from "./repos/index.js";
+import { LIFECYCLE_SCRIPTS_CONFIG_KEY, SavvyInstallSection, publishesBuiltLinkDirectory, savvyInstallBlock, savvyInstallDeps } from "./schemas/SavvyInstallSection.js";
 import { AnalyzedWorkspace, SilkPublishConfig, WorkspaceAnalysis } from "./schemas/WorkspaceAnalysisSchemas.js";
 import { BiomeSchemaSync, buildSchemaUrl, extractSemver } from "./services/BiomeSchemaSync.js";
 import { ConfigDiscovery } from "./services/ConfigDiscovery.js";
 import { SilkWorkspaceAnalyzer } from "./services/SilkWorkspaceAnalyzer.js";
 import { turbo_exports } from "./turbo/index.js";
 
-export { AnalyzedWorkspace, BiomeSchemaSync, BiomeSyncError, ChangesetConfig, ChangesetConfigError, ChangesetConfigReader, changesets_exports as Changesets, commitlint_exports as Commitlint, ConfigDiscovery, ConfigNotFoundError, lint_exports as Lint, pr_body_exports as PrBody, PublishTargetBindingError, repos_exports as Repos, SavvyBaseSection, SavvyHooksSection, SavvyToolchainSection, SilkPublishConfig, SilkPublishability, SilkWorkspaceAnalyzer, turbo_exports as Turbo, WorkspaceAnalysis, WorkspaceAnalysisError, buildSchemaUrl, extractSemver, readTargetsBinding, savvyBasePreamble, savvyHooksHygiene, savvyToolSection, savvyToolchainCheck };
+export { AnalyzedWorkspace, BiomeSchemaSync, BiomeSyncError, ChangesetConfig, ChangesetConfigError, ChangesetConfigReader, changesets_exports as Changesets, commitlint_exports as Commitlint, ConfigDiscovery, ConfigNotFoundError, LIFECYCLE_SCRIPTS_CONFIG_KEY, lint_exports as Lint, pr_body_exports as PrBody, PublishTargetBindingError, repos_exports as Repos, SavvyBaseSection, SavvyHooksSection, SavvyInstallSection, SavvyToolchainSection, SilkPublishConfig, SilkPublishability, SilkWorkspaceAnalyzer, turbo_exports as Turbo, WorkspaceAnalysis, WorkspaceAnalysisError, buildSchemaUrl, extractSemver, publishesBuiltLinkDirectory, readTargetsBinding, savvyBasePreamble, savvyHooksHygiene, savvyInstallBlock, savvyInstallDeps, savvyToolSection, savvyToolchainCheck };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/silk-effects",
-	"version": "7.4.0",
+	"version": "7.5.0",
 	"private": false,
 	"description": "Shared Effect library for Silk Suite conventions",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",
@@ -29,19 +29,19 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@changesets/apply-release-plan": "^8.0.0",
+		"@changesets/apply-release-plan": "^8.1.0",
 		"@changesets/changelog-git": "^1.0.0",
 		"@changesets/config": "^4.0.0",
-		"@changesets/get-github-info": "^1.0.0",
-		"@changesets/get-release-plan": "^5.0.0",
-		"@effected/github-references": "^0.1.0",
-		"@effected/glob": "^0.4.0",
-		"@effected/jsonc": "^0.8.1",
-		"@effected/markdown": "^0.8.1",
-		"@effected/package-json": "^0.13.0",
-		"@effected/templates": "^0.4.0",
-		"@effected/walker": "^0.5.0",
-		"@effected/yaml": "^0.12.0",
+		"@changesets/get-github-info": "^1.0.1",
+		"@changesets/get-release-plan": "^5.0.1",
+		"@effected/github-references": "^0.2.0",
+		"@effected/glob": "^0.5.0",
+		"@effected/jsonc": "^0.9.0",
+		"@effected/markdown": "^0.9.0",
+		"@effected/package-json": "^0.14.0",
+		"@effected/templates": "^0.5.0",
+		"@effected/walker": "^0.6.0",
+		"@effected/yaml": "^0.13.0",
 		"@manypkg/get-packages": "^3.1.0",
 		"mdast-util-heading-range": "^4.0.0",
 		"mdast-util-to-string": "^4.0.0",
@@ -54,9 +54,9 @@
 		"unist-util-visit": "^5.1.0"
 	},
 	"peerDependencies": {
-		"@effected/commands": "^0.5.0",
-		"@effected/git": "^0.10.0",
-		"@effected/workspaces": "^0.19.0",
-		"effect": "4.0.0-rc.109"
+		"@effected/commands": "^0.6.0",
+		"@effected/git": "^0.11.0",
+		"@effected/workspaces": "^0.20.0",
+		"effect": "4.0.0-rc.112"
 	}
 }

package/schemas/SavvyInstallSection.js

@@ -0,0 +1,232 @@
+import { CommentStyle, SectionId } from "@effected/templates";
+
+//#region src/schemas/SavvyInstallSection.ts
+/**
+* Section identity for the dependency auto-install block.
+*
+* `toolName` is `"savvy-install"`; pair with {@link savvyInstallDeps}.
+*
+* @since 7.5.0
+* @public
+*/
+const SavvyInstallSection = SectionId.make({
+	key: "SAVVY-INSTALL",
+	commentStyle: CommentStyle.hash
+});
+/**
+* Pathspecs whose change across a checkout or merge means `node_modules` is stale.
+*
+* @remarks
+* Git's default pathspec globbing does not stop a wildcard at a slash, so the
+* one nested-manifest entry below covers every workspace manifest at any depth
+* without needing a recursive spelling. Manifests are listed alongside lockfiles
+* because a dependency edit that has not been installed yet moves the manifest
+* first and the lockfile not at all.
+*/
+const DEPENDENCY_PATHS = [
+	"package.json",
+	"*/package.json",
+	"pnpm-lock.yaml",
+	"pnpm-workspace.yaml",
+	"package-lock.json",
+	"npm-shrinkwrap.json",
+	"yarn.lock",
+	"bun.lock",
+	"bun.lockb"
+].map((path) => `'${path}'`).join(" ");
+/**
+* Dependency auto-install shared across Silk Suite hook files.
+*
+* @remarks
+* Brings `node_modules` back in line after a branch switch or a pull, so a batch
+* of repos pulled to align their dependencies does not each need a manual
+* install. Installs with lifecycle scripts skipped — `--ignore-scripts`, or
+* `--mode=skip-build` for Yarn Berry, which dropped the former — because the goal
+* is to get the dependency tree on disk, not to run a full postinstall.
+*
+* **That flag has a cost, and one shape of repo cannot pay it.** Where a package
+* publishes through a built link directory — `publishConfig.directory` with
+* `linkDirectory: true`, which is how this monorepo wires `dist/dev/pkg` — the
+* workspace resolves its own dependencies through a directory that a `prepare`
+* script has to build, and skipping scripts yields a populated `node_modules`
+* pointing at nothing.
+*
+* Those repos ask for a full install through the LOCAL git config key
+* `savvy.installLifecycleScripts`, which `savvy init` sets when it finds the
+* shape. The decision deliberately does NOT read the checked-out tree. Doing so
+* failed in both directions at once: a branch that merely declared the shape
+* could turn lifecycle scripts back on just by being checked out, making
+* `git checkout` of an untrusted revision a code-execution path; and the `jq`
+* the scan needed is absent on stock macOS and Ubuntu, where the missing answer
+* silently skipped scripts in precisely the repos that cannot survive it.
+* `.git/config` is neither checked out nor parsed with `jq`, so it has neither
+* failure mode.
+*
+* The package managers gate dependency scripts themselves on top of this —
+* pnpm's `strictDepBuilds` with an `allowBuilds` allowlist being the case in
+* point — but workspace and root lifecycle scripts still run, which is why the
+* opt-in is local rather than inferred. With the flag on, the hook says on the
+* way out that scripts were skipped rather than leaving it to be discovered.
+*
+* Deliberately self-contained, like `savvyToolchainCheck`: its homes carry
+* `SavvyHooksSection` but no `SavvyBaseSection`, so it defines its own root, CI
+* and package-manager lookups rather than depending on `ROOT`, `in_ci` or `PM`.
+*
+* Four guards keep it from firing on the many checkouts that are not dependency
+* events, each a silent no-op:
+*
+* - CI, where the runtime action owns installation by construction.
+* - `SAVVY_SKIP_INSTALL`, the escape hatch for a bisect or a scripted sweep that
+*   does not want an install between steps.
+* - `post-checkout` only: a branch-flag of `0`, which is `git checkout -- <file>`
+*   and not a move between commits.
+* - **The gate that makes this affordable:** nothing dependency-related actually
+*   changed across the move. Without it every branch switch would pay for a full
+*   install. A missing `node_modules` overrides it, since there is nothing to be
+*   stale.
+*
+* A fresh clone is not among the cases it handles, and cannot be: husky sets
+* `core.hooksPath` from its own `prepare` script, so until the first manual
+* install has run there is no hook installed to fire.
+*
+* The install's exit status is swallowed and its output goes to stderr. Git
+* ignores what `post-checkout` and `post-merge` return, so a failure here must
+* not look like a failed checkout; the hint names the escape hatch instead.
+*
+* Every probe that can legitimately fail — no `ORIG_HEAD` to compare against, an
+* unresolvable range — is neutralised with `|| true` rather than left to its own
+* status. These blocks are co-owned and consumer content can sit below them, so
+* under a hook running `set -e` a bare failing substitution would abort the whole
+* file and take those later sections with it.
+*
+* @param hook - Which hook the block is being generated for; decides the
+*   argument guard and how the comparison range is recovered.
+* @returns The install shell, with no surrounding markers or trailing newline.
+*
+* @since 7.5.0
+* @public
+*/
+function savvyInstallDeps(hook) {
+	const skip = `! { [ -n "$CI" ] || [ -n "$GITHUB_ACTIONS" ] || [ -n "$SAVVY_SKIP_INSTALL" ]; }`;
+	return `if ${hook === "post-checkout" ? `${skip} && [ "$3" = "1" ]` : skip}; then
+  install_root=$(git rev-parse --show-toplevel 2>/dev/null) || true
+${hook === "post-checkout" ? `  install_from="$1"
+  install_to="$2"` : `  install_from=$(git rev-parse --verify --quiet ORIG_HEAD 2>/dev/null) || true
+  install_to="HEAD"`}
+  install_pm=""
+  if [ -n "$install_root" ] && [ -f "$install_root/package.json" ]; then
+    if command -v jq >/dev/null 2>&1; then
+      install_pm=$(jq -r '.packageManager // empty' "$install_root/package.json" 2>/dev/null | cut -d'@' -f1)
+    fi
+    if [ -z "$install_pm" ]; then
+      if   [ -f "$install_root/pnpm-lock.yaml" ]; then install_pm="pnpm"
+      elif [ -f "$install_root/yarn.lock" ];      then install_pm="yarn"
+      elif [ -f "$install_root/bun.lock" ] || [ -f "$install_root/bun.lockb" ]; then install_pm="bun"
+      else install_pm="npm"; fi
+    fi
+  fi
+  # packageManager comes from the checked-out revision, so it names an executable
+  # the tree controls. 'command -v' proves a binary exists, not that it is a
+  # package manager, so the name is checked against the supported four first.
+  case "$install_pm" in
+    npm|pnpm|yarn|bun) ;;
+    *) install_pm="" ;;
+  esac
+  # Nothing to bring up to date unless a manifest or lockfile actually moved.
+  # A missing node_modules skips the diff outright: there is no tree to be stale.
+  install_stale=""
+  if [ -n "$install_pm" ]; then
+    if [ ! -d "$install_root/node_modules" ]; then
+      install_stale=1
+    elif [ -n "$install_from" ] && [ -n "$install_to" ]; then
+      install_stale=$(git diff --name-only "$install_from" "$install_to" -- ${DEPENDENCY_PATHS} 2>/dev/null | head -n 1) || true
+    fi
+  fi
+  if [ -n "$install_stale" ] && command -v "$install_pm" >/dev/null 2>&1; then
+    # Whether lifecycle scripts run is a LOCAL decision, read from .git/config,
+    # which no checkout can rewrite. Default off. 'savvy init' turns it on for a
+    # workspace that publishes through built link directories, where the links
+    # point at directories a prepare script has to produce.
+    install_scripts=$(git -C "$install_root" config --bool --get savvy.installLifecycleScripts 2>/dev/null) || true
+    if [ "$install_scripts" = "true" ]; then
+      install_flag=""
+    else
+      # Berry dropped --ignore-scripts for the install mode; Classic never knew the
+      # mode. An unreadable major reads as Berry, the likelier of the two today.
+      install_flag="--ignore-scripts"
+      if [ "$install_pm" = "yarn" ]; then
+        case "$(yarn --version 2>/dev/null | cut -d. -f1)" in
+          1) ;;
+          *) install_flag="--mode=skip-build" ;;
+        esac
+      fi
+    fi
+    # ':+' so a full install announces itself as "pnpm install", not "pnpm install ".
+    printf '↻ dependencies changed, running %s install%s\\n' "$install_pm" "\${install_flag:+ $install_flag}" >&2
+    # Unquoted on purpose: empty must expand to NO argument rather than an empty
+    # one. Safe because every value is a static flag literal from this generator.
+    if ( cd "$install_root" && "$install_pm" install $install_flag ) >&2; then
+      if [ -n "$install_flag" ]; then
+        printf '  Lifecycle scripts were skipped. Run a full install if you need build outputs.\\n' >&2
+      fi
+    else
+      printf '⚠ %s install failed; run it yourself to see why.\\n' "$install_pm" >&2
+      printf '  Set SAVVY_SKIP_INSTALL=1 to stop this hook from trying.\\n' >&2
+    fi
+  fi
+  unset install_root install_from install_to install_pm install_stale install_scripts install_flag
+fi`;
+}
+/**
+* The local git config key that authorizes lifecycle scripts during a hook install.
+*
+* @remarks
+* Local scope only. It lives in `.git/config`, which is never checked out, so no
+* incoming revision can set it — that is the whole point of reading the decision
+* from here rather than from a manifest in the tree.
+*
+* @since 7.5.0
+* @public
+*/
+const LIFECYCLE_SCRIPTS_CONFIG_KEY = "savvy.installLifecycleScripts";
+/**
+* Whether `manifest` publishes through a built link directory.
+*
+* @remarks
+* `publishConfig.directory` with `linkDirectory: true` means consumers of this
+* package resolve it through a directory that a `prepare` script has to produce,
+* so an install that skips lifecycle scripts leaves the link pointing at nothing.
+* A workspace containing any such package is one whose owner probably wants
+* {@link LIFECYCLE_SCRIPTS_CONFIG_KEY} set.
+*
+* Reporting the shape is deliberately separate from acting on it: this answers
+* "does this repo need scripts", and a human still decides whether hook-time
+* installs may run them.
+*
+* @param manifest - A parsed `package.json`; any non-object reads as `false`.
+*
+* @since 7.5.0
+* @public
+*/
+function publishesBuiltLinkDirectory(manifest) {
+	if (typeof manifest !== "object" || manifest === null) return false;
+	const { publishConfig } = manifest;
+	if (typeof publishConfig !== "object" || publishConfig === null) return false;
+	const { directory, linkDirectory } = publishConfig;
+	return typeof directory === "string" && directory.length > 0 && linkDirectory === true;
+}
+/**
+* Build the dependency auto-install block for `hook`.
+*
+* @param hook - Which hook the section is destined for.
+* @returns A shell `Section` (`commentStyle: hash`) keyed `SAVVY-INSTALL`.
+*
+* @since 7.5.0
+* @public
+*/
+function savvyInstallBlock(hook) {
+	return SavvyInstallSection.section(savvyInstallDeps(hook));
+}
+
+//#endregion
+export { LIFECYCLE_SCRIPTS_CONFIG_KEY, SavvyInstallSection, publishesBuiltLinkDirectory, savvyInstallBlock, savvyInstallDeps };