How Archify Update Checker Functionality Validates Release Integrity

Archify's update checker functionality validates every release through a CI-integrated subsystem that verifies semantic versioning, SHA-256 hashes, and cross-artifact consistency across three core scripts.

The tt-a1i/archify repository implements a self-contained update checking subsystem that ensures every release artifact maintains cryptographic and semantic integrity. This Archify update checker functionality operates entirely within the CI pipeline, parsing git tags, validating JSON manifests, and enforcing strict version consistency across documentation, metadata, and compiled archives.

Core Components of the Update Checking Subsystem

The subsystem consists of three interconnected scripts that enforce release contracts through automated validation.

Stable Manifest Validator

The scripts/check-stable-update-manifest.mjs script performs immutable validation of the stable release manifest located at docs/skill-updates/archify/stable.json. It accepts CLI arguments including --root, --archive, --tag, and --source-ref to locate the built archive and git reference.

The script extracts the version from annotated git tags using the regex /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/ and verifies it matches both archify/package.json and the manifest's declared version. It calls validateStableUpdateManifest from archify/scripts/update-contract.mjs to verify the manifest's schema, repository reference, commit tree SHA, and artifact SHA-256.

Release Identity Enforcer

The scripts/check-release-identity.mjs script conducts exhaustive cross-artifact consistency checks for every release channel. It reads archify/package.json, CHANGELOG.md, README* files, docs/index.html, docs/start.html, and archify/skill-release.json to ensure version alignment.

The script calls validateLocalRelease to verify skill metadata and validateStableUpdateManifest to confirm manifest integrity. It validates that archify/package-lock.json mirrors the exact version, that archify/SKILL.md aligns with the core version, and that HTML generator meta tags contain the correct version string. The script also enforces the "9/9" proof receipt rule (lines 71-76) and confirms that Chinese and English README copies are byte-identical.

Contract Utilities

The archify/scripts/update-contract.mjs module provides shared validation logic used by both checker scripts. It exports parseSemver for version parsing, validateStableUpdateManifest for manifest schema enforcement, and validateCanonicalUtcTimestamp for temporal verification.

The module defines strict key set validation through hasExactKeys and sanitizes free-form fields against bidirectional or control characters. It also defines the canonical SemVer regex and helper functions including compareSemver, releaseChannelForVersion, and isStableCoreVersion.

How the Validation Pipeline Executes

The CI pipeline invokes the update checker functionality through two distinct entry points that run sequentially after the release build completes.

1. Identity Verification – The CI runs node scripts/check-release-identity.mjs to perform cross-artifact consistency checks. This script parses the package version using parseSemver to determine if the release is a development prerelease or stable build.

2. Manifest Validation – The CI runs node scripts/check-stable-update-manifest.mjs --archive path/to/archify.zip --tag vX.Y.Z to validate the specific release archive against the manifest.

During execution, the stable manifest validator reads the annotated tag's taggerdate field (lines 64-86 in check-stable-update-manifest.mjs) to confirm the publishedAt timestamp matches the tagger's UTC time. It then computes the SHA-256 hash of the supplied archive using crypto.createHash('sha256') and validates it against the manifest's artifact.sha256 field.

Critical Validation Checks Explained

The Archify update checker functionality enforces several cryptographic and semantic constraints that prevent invalid releases from propagating.

Semantic Version Parsing

Both scripts rely on the canonical SemVer regex defined in update-contract.mjs to extract version components. The parseSemver function validates that tags follow the vMAJOR.MINOR.PATCH format and distinguishes stable releases from development prereleases through isStableCoreVersion checks.

// scripts/check-stable-update-manifest.mjs
const version = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
  .exec(tag || '')
  ?.slice(1, 4).join('.') ?? null;
if (!version) fail(`--tag must be a stable vMAJOR.MINOR.PATCH tag; found ${JSON.stringify(tag)}.`);

Git Tag Metadata Verification

The stable manifest validator retrieves the annotated tag's UTC date using git commands. It confirms this timestamp matches exactly with the publishedAt field in docs/skill-updates/archify/stable.json, ensuring temporal consistency between git history and release metadata.

Archive Integrity Verification

Cryptographic verification occurs through SHA-256 hashing of the built archify.zip archive. The script compares the computed hash against the immutable artifact.sha256 value stored in the manifest, preventing tampering or corruption of release artifacts between build and distribution.

Cross-Artifact Consistency

The release identity checker verifies that all documentation artifacts advertise identical version information. The checkReadme function confirms that README files contain exact version badges and explicit "Current stable version" or "Current development version" markers in both English and Chinese.

// scripts/check-release-identity.mjs
function checkReadme(relativePath, source, version, language, isDevelopment) {
  const badge = `/badge/version-${shieldEscape(version)}-`;
  const markerLabel = language === 'zh'
    ? isDevelopment ? '当前开发版本：' : '当前稳定版本：'
    : isDevelopment ? 'Current development version:' : 'Current stable version:';
  const hasMarker = source.split('\n')
    .some(line => line.includes(markerLabel) && line.includes(`\`v${version}\``));
  if (!source.includes(badge) || !hasMarker) {
    fail(`${relativePath} must advertise ${isDevelopment ? 'development' : 'stable'} identity v${version} with an exact escaped badge and explicit ${isDevelopment ? 'development' : 'stable'} marker.`);
  }
}

Summary

• The Archify update checker functionality comprises three scripts: check-stable-update-manifest.mjs, check-release-identity.mjs, and update-contract.mjs.
• Validation runs entirely within the CI pipeline, parsing CLI arguments to locate archives and git references.
• The system enforces strict SemVer compliance using regex patterns defined in update-contract.mjs.
• Cryptographic integrity is ensured through SHA-256 hashing of release archives against manifest declarations.
• Cross-artifact consistency checks verify version alignment across package files, documentation, and metadata in multiple languages.

Frequently Asked Questions

How does Archify validate the stable update manifest?

Archify validates the stable update manifest through the validateStableUpdateManifest function in archify/scripts/update-contract.mjs. This function checks that the manifest contains exactly the required keys (schemaVersion, skillId, channel, version, publishedAt, source, artifact, summary, releaseNotes, severity), validates the repository URL matches EXPECTED_REPOSITORY, confirms the git ref follows v${value.version} format, and verifies the tree SHA matches a 40-character hexadecimal pattern while the artifact SHA-256 matches a 64-character pattern.

What files does the release identity checker examine?

The scripts/check-release-identity.mjs script examines archify/package.json, CHANGELOG.md, all README* files, docs/index.html, docs/start.html, archify/skill-release.json, archify/package-lock.json, and archify/SKILL.md. It verifies that HTML meta tags, version badges, and explicit version markers remain consistent across all these artifacts, including verification that Chinese and English copies are byte-identical.

Where is the SemVer parsing logic defined?

The SemVer parsing logic resides in archify/scripts/update-contract.mjs through the parseSemver function. This function uses a canonical regex pattern to validate version strings and supports comparison operations through compareSemver and channel determination via releaseChannelForVersion.

What happens if validation fails in the CI pipeline?

If any validation check fails, the scripts log a prefixed error message (such as stable update manifest: or release identity:) and exit with a non-zero status code. This failure signal causes the CI job to terminate immediately, preventing the release from proceeding until all integrity constraints are satisfied.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}