fix: accept published installer migration checksums

This commit is contained in:
Colin
2026-06-04 12:23:29 -04:00
parent e8dc420b4d
commit b8e15c7a98
12 changed files with 198 additions and 3 deletions

View File

@@ -0,0 +1,5 @@
---
type: Fixed
pr: 674
---
Accept published installer migration checksums so Windows users upgrading from 1.2.0 to 1.3.0 do not hit checksum drift failures.

View File

@@ -125,6 +125,11 @@ The checksum is calculated from the migration definition. If an applied
migration's checksum changes, the installer must warn and refuse to silently migration's checksum changes, the installer must warn and refuse to silently
re-run it. Fix-forward migrations should use a new migration id. re-run it. Fix-forward migrations should use a new migration id.
Migration records may pin a stable `checksum` and list `legacyChecksums` for
checksums already written by published packages. This is only for compatibility
with released install state; new behavior should still ship as a new migration
id rather than mutating an already-applied migration in place.
## Migration Record ## Migration Record
Each migration exports a plain record plus pure planning logic. Each migration exports a plain record plus pure planning logic.

View File

@@ -64,6 +64,7 @@ const RULES = [
'tests/install-regressions.test.cjs', 'tests/install-regressions.test.cjs',
'tests/install-runtime-artifacts.test.cjs', 'tests/install-runtime-artifacts.test.cjs',
'tests/install-path-detection.test.cjs', 'tests/install-path-detection.test.cjs',
'tests/installer-migration-checksum-compat.test.cjs',
'tests/release-tarball-smoke.install.test.cjs', 'tests/release-tarball-smoke.install.test.cjs',
'tests/runtime-artifact-layout.test.cjs', 'tests/runtime-artifact-layout.test.cjs',
], ],
@@ -254,7 +255,7 @@ function classify(files) {
let fullMatrix = false; let fullMatrix = false;
for (const file of files) { for (const file of files) {
if (['bin/', 'gsd-core/', 'agents/', 'commands/', 'docs/', 'hooks/', 'tests/', 'scripts/'].some(p => file.startsWith(p)) || if (['bin/', 'gsd-core/', 'agents/', 'commands/', 'docs/', 'hooks/', 'tests/', 'scripts/', 'src/'].some(p => file.startsWith(p)) ||
file === 'package.json' || file === 'package-lock.json' || file === 'package.json' || file === 'package-lock.json' ||
(file.startsWith('tsconfig') && file.endsWith('.json')) || (file.startsWith('tsconfig') && file.endsWith('.json')) ||
file.startsWith('.github/workflows/') || file.startsWith('.github/workflows/') ||

View File

@@ -91,6 +91,7 @@ export function validateInstallerMigrationRecord(record: unknown, source?: strin
throw new Error(`migration record must declare destructive as a boolean: ${displaySource}`); throw new Error(`migration record must declare destructive as a boolean: ${displaySource}`);
} }
validateStringArray(rec, 'runtimes', displaySource); validateStringArray(rec, 'runtimes', displaySource);
validateStringArray(rec, 'legacyChecksums', displaySource);
requireStringArray(rec, 'scopes', displaySource); requireStringArray(rec, 'scopes', displaySource);
if (typeof rec['plan'] !== 'function') { if (typeof rec['plan'] !== 'function') {
throw new Error(`migration record must include a plan function: ${displaySource}`); throw new Error(`migration record must include a plan function: ${displaySource}`);

View File

@@ -208,12 +208,22 @@ function migrationChecksum(migration: MigrationRecord): string {
return `sha256:${sha256Text(JSON.stringify(serializable))}`; return `sha256:${sha256Text(JSON.stringify(serializable))}`;
} }
function migrationLegacyChecksums(migration: MigrationRecord): string[] {
return Array.isArray(migration.legacyChecksums)
? migration.legacyChecksums.filter((checksum): checksum is string => typeof checksum === 'string' && checksum.length > 0)
: [];
}
function migrationAcceptedChecksums(migration: MigrationRecord): Set<string> {
return new Set([migrationChecksum(migration), ...migrationLegacyChecksums(migration)]);
}
function assertAppliedMigrationChecksums(applied: Map<string, Record<string, unknown>>, migrations: MigrationRecord[]): void { function assertAppliedMigrationChecksums(applied: Map<string, Record<string, unknown>>, migrations: MigrationRecord[]): void {
for (const migration of migrations) { for (const migration of migrations) {
const entry = applied.get(migration.id as string); const entry = applied.get(migration.id as string);
if (!entry || !entry.checksum) continue; if (!entry || !entry.checksum) continue;
const checksum = migrationChecksum(migration); const accepted = migrationAcceptedChecksums(migration);
if (entry.checksum !== checksum) { if (!accepted.has(entry.checksum as string)) {
throw new Error( throw new Error(
`applied migration checksum changed for ${migration.id as string}; create a new fix-forward migration id` `applied migration checksum changed for ${migration.id as string}; create a new fix-forward migration id`
); );
@@ -923,6 +933,7 @@ export = {
acquireInstallMigrationLock, acquireInstallMigrationLock,
applyInstallerMigrationPlan, applyInstallerMigrationPlan,
classifyArtifact, classifyArtifact,
computeInstallerMigrationChecksum: migrationChecksum,
discoverInstallerMigrations, discoverInstallerMigrations,
planInstallerMigrations, planInstallerMigrations,
readInstallManifest, readInstallManifest,

View File

@@ -171,6 +171,8 @@ interface InstallerMigration {
title: string; title: string;
description: string; description: string;
introducedIn: string; introducedIn: string;
checksum: string;
legacyChecksums?: string[];
scopes: string[]; scopes: string[];
destructive: boolean; destructive: boolean;
plan: (ctx: PlanContext) => BaselineAction[]; plan: (ctx: PlanContext) => BaselineAction[];
@@ -181,6 +183,10 @@ const migration: InstallerMigration = {
title: 'Record first-time installer migration baseline', title: 'Record first-time installer migration baseline',
description: 'Classify existing install surfaces before destructive installer migrations run.', description: 'Classify existing install surfaces before destructive installer migrations run.',
introducedIn: '1.50.0', introducedIn: '1.50.0',
checksum: 'sha256:4ec58d35b30dbf39cc56e3972146086d8d31861ecd800cf0b37a7aa94fe74c2a',
legacyChecksums: [
'sha256:34608ea4e2f4e1c53b069604892860e603600d8573cc6a5584e4194044b48e67',
],
scopes: ['global', 'local'], scopes: ['global', 'local'],
destructive: false, destructive: false,
plan: ({ configDir, runtime, baselineScan, classifyArtifact }: PlanContext): BaselineAction[] => { plan: ({ configDir, runtime, baselineScan, classifyArtifact }: PlanContext): BaselineAction[] => {

View File

@@ -31,6 +31,8 @@ interface InstallerMigration {
title: string; title: string;
description: string; description: string;
introducedIn: string; introducedIn: string;
checksum: string;
legacyChecksums?: string[];
scopes: string[]; scopes: string[];
destructive: boolean; destructive: boolean;
plan: (ctx: MigrationPlanContext) => MigrationAction[]; plan: (ctx: MigrationPlanContext) => MigrationAction[];
@@ -46,6 +48,10 @@ const migration: InstallerMigration = {
title: 'Remove manifest-managed legacy orphan hook files', title: 'Remove manifest-managed legacy orphan hook files',
description: 'Remove legacy orphan hook files that are still manifest-managed.', description: 'Remove legacy orphan hook files that are still manifest-managed.',
introducedIn: '1.50.0', introducedIn: '1.50.0',
checksum: 'sha256:e492698748a2436a12a55f0940f539b9bf651d8ffcac6f60cd856a6dabd6788c',
legacyChecksums: [
'sha256:4488e38c127a5225b31016918bcbc85ba3fd3139291ad407b94e76c03c0b89d3',
],
scopes: ['global', 'local'], scopes: ['global', 'local'],
destructive: true, destructive: true,
// Retired generated hook files are removed only with manifest-managed // Retired generated hook files are removed only with manifest-managed

View File

@@ -48,6 +48,8 @@ interface InstallerMigration {
title: string; title: string;
description: string; description: string;
introducedIn: string; introducedIn: string;
checksum: string;
legacyChecksums?: string[];
runtimes: string[]; runtimes: string[];
scopes: string[]; scopes: string[];
destructive: boolean; destructive: boolean;
@@ -110,6 +112,10 @@ const migration: InstallerMigration = {
title: 'Remove legacy Codex hooks.json GSD hook registrations', title: 'Remove legacy Codex hooks.json GSD hook registrations',
description: 'Remove legacy Codex hooks.json GSD hook registrations after config.toml migration.', description: 'Remove legacy Codex hooks.json GSD hook registrations after config.toml migration.',
introducedIn: '1.50.0', introducedIn: '1.50.0',
checksum: 'sha256:5ce55294aa02f25758f604a569c899a6d2d060299189f5f447f68d8033157058',
legacyChecksums: [
'sha256:41f1545704dc72dfc3ab019207677a8652e389b200e8c450d52317df5bc198da',
],
runtimes: ['codex'], runtimes: ['codex'],
scopes: ['global', 'local'], scopes: ['global', 'local'],
destructive: true, destructive: true,

View File

@@ -48,6 +48,7 @@ interface InstallerMigration {
title: string; title: string;
description: string; description: string;
introducedIn: string; introducedIn: string;
checksum: string;
scopes: string[]; scopes: string[];
destructive: boolean; destructive: boolean;
plan(ctx: MigrationPlanContext): MigrationAction[]; plan(ctx: MigrationPlanContext): MigrationAction[];
@@ -80,6 +81,7 @@ const migration: InstallerMigration = {
'After the config dir rename from get-shit-done/ to gsd-core/ (#604), remove prior-manifest-managed files ' + // gsd-allow-legacy-name 'After the config dir rename from get-shit-done/ to gsd-core/ (#604), remove prior-manifest-managed files ' + // gsd-allow-legacy-name
'from the stale legacy directory during install (framework rollback restores them if install fails). User-added files are preserved.', 'from the stale legacy directory during install (framework rollback restores them if install fails). User-added files are preserved.',
introducedIn: '1.2.0', introducedIn: '1.2.0',
checksum: 'sha256:3a9f1d97f64097fb313203d19c6d93a187a38df61dd299afa5eef73e16124e95',
scopes: ['global', 'local'], scopes: ['global', 'local'],
destructive: true, destructive: true,
plan(ctx: MigrationPlanContext): MigrationAction[] { plan(ctx: MigrationPlanContext): MigrationAction[] {

View File

@@ -56,9 +56,18 @@ describe('ci-test-scope.cjs', () => {
assert.strictEqual(result.code_changed, true); assert.strictEqual(result.code_changed, true);
assert.strictEqual(result.full_matrix, true); assert.strictEqual(result.full_matrix, true);
assert.ok(result.targeted_tests.includes('tests/install.test.cjs')); assert.ok(result.targeted_tests.includes('tests/install.test.cjs'));
assert.ok(result.targeted_tests.includes('tests/installer-migration-checksum-compat.test.cjs'));
assert.ok(result.targeted_tests.includes('tests/release-tarball-smoke.install.test.cjs')); assert.ok(result.targeted_tests.includes('tests/release-tarball-smoke.install.test.cjs'));
}); });
test('ADR-457 installer source changes wake scoped CI and checksum compatibility guard', () => {
const result = scopeFor(['src/installer-migrations/000-first-time-baseline.cts']);
assert.strictEqual(result.code_changed, true);
assert.strictEqual(result.full_matrix, true);
assert.ok(result.targeted_tests.includes('tests/installer-migration-checksum-compat.test.cjs'));
assert.ok(result.windows_tests.includes('tests/installer-migration-checksum-compat.test.cjs'));
});
test('missing required CLI values fail with usage', () => { test('missing required CLI values fail with usage', () => {
const r = spawnSync(process.execPath, [SCRIPT, '--files'], { const r = spawnSync(process.execPath, [SCRIPT, '--files'], {
cwd: ROOT, cwd: ROOT,

View File

@@ -0,0 +1,49 @@
{
"_comment": "Published installer migration checksums that must remain accepted by future releases. If an existing migration implementation changes, preserve compatibility here via legacyChecksums or create a new fix-forward migration id.",
"migrations": {
"2026-05-11-first-time-baseline-scan": {
"published": [
{
"version": "1.2.0",
"checksum": "sha256:34608ea4e2f4e1c53b069604892860e603600d8573cc6a5584e4194044b48e67"
},
{
"version": "1.3.0",
"checksum": "sha256:4ec58d35b30dbf39cc56e3972146086d8d31861ecd800cf0b37a7aa94fe74c2a"
}
]
},
"2026-05-11-legacy-orphan-files": {
"published": [
{
"version": "1.2.0",
"checksum": "sha256:4488e38c127a5225b31016918bcbc85ba3fd3139291ad407b94e76c03c0b89d3"
},
{
"version": "1.3.0",
"checksum": "sha256:e492698748a2436a12a55f0940f539b9bf651d8ffcac6f60cd856a6dabd6788c"
}
]
},
"2026-05-11-codex-legacy-hooks-json": {
"published": [
{
"version": "1.2.0",
"checksum": "sha256:41f1545704dc72dfc3ab019207677a8652e389b200e8c450d52317df5bc198da"
},
{
"version": "1.3.0",
"checksum": "sha256:5ce55294aa02f25758f604a569c899a6d2d060299189f5f447f68d8033157058"
}
]
},
"2026-06-02-rename-get-shit-done-to-gsd-core": {
"published": [
{
"version": "1.3.0",
"checksum": "sha256:3a9f1d97f64097fb313203d19c6d93a187a38df61dd299afa5eef73e16124e95"
}
]
}
}
}

View File

@@ -0,0 +1,94 @@
'use strict';
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const {
computeInstallerMigrationChecksum,
discoverInstallerMigrations,
planInstallerMigrations,
} = require('../gsd-core/bin/lib/installer-migrations.cjs');
const { cleanup } = require('./helpers.cjs');
const FIXTURE = require('./fixtures/installer-migrations/published-checksums.json');
const MIGRATIONS_DIR = path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'installer-migrations');
function createConfigDir() {
const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-migration-checksum-compat-'));
fs.writeFileSync(
path.join(configDir, 'gsd-file-manifest.json'),
JSON.stringify({ version: 'compat-fixture', timestamp: '2026-06-04T00:00:00.000Z', mode: 'full', files: {} }, null, 2),
'utf8'
);
return configDir;
}
function writeAppliedState(configDir, migration, checksum, version) {
fs.writeFileSync(
path.join(configDir, 'gsd-install-state.json'),
JSON.stringify({
schemaVersion: 1,
appliedMigrations: [
{
id: migration.id,
checksum,
appliedAt: '2026-06-04T00:00:00.000Z',
packageVersion: version,
journal: 'gsd-migration-journal/published-compat-fixture.json',
},
],
}, null, 2),
'utf8'
);
}
function planContextFor(migration) {
return {
runtime: Array.isArray(migration.runtimes) && migration.runtimes.length > 0 ? migration.runtimes[0] : 'claude',
scope: Array.isArray(migration.scopes) && migration.scopes.length > 0 ? migration.scopes[0] : 'global',
};
}
test('shipped installer migration checksums remain accepted for upgrade compatibility', () => {
const migrations = discoverInstallerMigrations({ migrationsDir: MIGRATIONS_DIR });
const byId = new Map(migrations.map((migration) => [migration.id, migration]));
const fixtureIds = new Set(Object.keys(FIXTURE.migrations));
for (const migration of migrations) {
assert.ok(
fixtureIds.has(migration.id),
`current migration must be pinned in published-checksums.json: ${migration.id}`
);
}
for (const [migrationId, fixture] of Object.entries(FIXTURE.migrations)) {
const migration = byId.get(migrationId);
assert.ok(migration, `published migration fixture no longer exists: ${migrationId}`);
const currentChecksum = computeInstallerMigrationChecksum(migration);
assert.ok(
fixture.published.some((entry) => entry.checksum === currentChecksum),
`${migrationId} current checksum ${currentChecksum} is not pinned in published-checksums.json`
);
for (const { version, checksum } of fixture.published) {
const configDir = createConfigDir();
try {
writeAppliedState(configDir, migration, checksum, version);
assert.doesNotThrow(
() => planInstallerMigrations({
configDir,
migrations: [migration],
...planContextFor(migration),
}),
`${migrationId} must accept checksum ${checksum} from ${version}`
);
} finally {
cleanup(configDir);
}
}
}
});