Class TrackedBlockTierHandler

java.lang.Object
network.ike.plugin.scaffold.TrackedBlockTierHandler
All Implemented Interfaces:
TierHandler
public final class TrackedBlockTierHandler extends Object implements TierHandler
Tier handler for ScaffoldTier.TRACKED_BLOCK.

Policy: same checksum-guarded refresh as ScaffoldTier.TRACKED, but only a bounded region inside the destination file is managed. The region is delimited by the block-begin and block-end line markers declared on the manifest entry. Content outside the markers belongs to the user and is never touched.

The source file in the scaffold zip contains only the block content (no markers). When publish installs a brand-new file, the markers are added around the template content.

The appliedSha / templateSha recorded in the lockfile for this tier are hashes of the block content, not the whole file. That way edits to unmanaged regions do not look like drift on the managed block.

Whitelist-style .gitignore awareness

Workspaces that ignore everything by default and whitelist a curated set of files (signalled by a bare * or ** line in the destination) need a different block payload — the blacklist patterns shipped in source would either silently have no effect or, worse, cause newly tracked scaffold files to be ignored. When the manifest entry sets whitelist-block-content (an inline string in extras) the handler substitutes that content for the source bytes when whitelist mode is detected on disk. When whitelist mode is detected but no whitelist-block-content is supplied, the entry is reported as user-managed (no write) so the publish run does not pollute the user's whitelist.

Create-case seeding

When the destination file does not exist yet and the caller supplies createContent (resolved from the manifest entry's create-source extra), the new file is seeded with that content followed by the managed block. This gives a brand-new repo bootstrapped via ike:scaffold-publish the full canonical template on day one (ike-issues#825) while keeping the #245 dedup semantics for existing files: the seed is written exactly once, is the user's from then on, and only the marker-delimited block is managed on subsequent runs. The lockfile hashes cover only the block content, so the seed never registers as drift.

  • Constructor Details

    • TrackedBlockTierHandler

      public TrackedBlockTierHandler()
      Construct a stateless tracked-block tier handler. Instances are safe to share across planning calls; all per-invocation state lives on method parameters.

  • Method Details

    • tier

      public ScaffoldTier tier()
      Description copied from interface: TierHandler
      Which tier this handler is responsible for.
      Specified by:
      tier in interface TierHandler
      Returns:
      the tier; never null

    • plan

      public TierAction plan(ManifestEntry entry, Path resolvedDest, byte[] currentContent, byte[] templateContent, byte[] createContent, LockfileEntry priorEntry)
      Description copied from interface: TierHandler
      Plan a single entry.
      Specified by:
      plan in interface TierHandler
      Parameters:
      entry - the manifest entry being planned
      resolvedDest - absolute destination path (placeholders already expanded)
      currentContent - bytes currently on disk at resolvedDest, or null if no file exists
      templateContent - bytes loaded from the scaffold zip at entry.source(); never null for file-based tiers
      createContent - bytes loaded from the scaffold zip at the entry's create-source extra, or null when the entry declares none. Only consulted when currentContent is null — tiers that support create-case seeding (currently ScaffoldTier.TRACKED_BLOCK) seed this content into the newly created file ahead of their managed region; other tiers ignore it
      priorEntry - lockfile entry from the last publish, or null if this entry has never been applied
      Returns:
      a TierAction describing what publish should do