build(rail): the 10.4.12 candidate takes main — the walls leave this repo, the rail writes its entry into soulcraftlabs/releases

2026-09-03 08:36:01 -07:00 · 2026-09-03 08:36:01 -07:00 · 4c81d7d4c3
commit 4c81d7d4c3
parent dadfa61b5f bc82d36294
6 changed files with 454 additions and 335 deletions
--- a/tests/unit/release/wall-entry.test.ts
+++ b/tests/unit/release/wall-entry.test.ts
@ -4,12 +4,15 @@
 * The script's only real interface is its CLI (it has no importable
 * exports by design — one door, no parallel API to drift from it), so
 * these tests spawn it exactly as scripts/release.sh does: as a child
- * process, against a temp copy of a wall file and a fixture CHANGELOG,
- * never against the repo's real releases/*.json.
+ * process, against a fixture CHANGELOG and a throwaway local bare repo
+ * standing in for git@source.soulcraft.com:soulcraftlabs/releases.git
+ * (--remote) plus a throwaway cache directory (--cache-dir) standing in
+ * for ~/.cache/soulcraft-releases — never the real remote, never the
+ * real developer cache.
 */
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { execFileSync } from 'node:child_process'
-import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'node:fs'
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, chmodSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'

@ -25,6 +28,10 @@ function run(args: string[], cwd: string): { status: number; stdout: string; std
  }
 }

+function git(args: string[], cwd: string): string {
+  return execFileSync('git', ['-C', cwd, ...args], { encoding: 'utf8' }).trim()
+}
+
 const CHANGELOG_HEADER = '# Changelog\n\nAll notable changes, in this fixture.\n'

 /** Build a CHANGELOG.md with one entry per [version, bullets[]] pair, newest first. */
@ -41,11 +48,7 @@ function buildChangelog(entries: Array<{ version: string; date: string; bullets:
 }

 function wallFile(product: string, entries: unknown[]): string {
-  return JSON.stringify(
-    { product, entries, history: 'Earlier releases are recorded in CHANGELOG.md in this repository.' },
-    null,
-    2,
-  ) + '\n'
+  return JSON.stringify({ product, entries }, null, 2) + '\n'
 }

 const BASE_ENTRY = {
@ -57,31 +60,76 @@ const BASE_ENTRY = {
  thumb: null,
 }

+/** A throwaway bare repo standing in for the real soulcraftlabs/releases remote. */
+function initBareRemote(): string {
+  const remoteDir = mkdtempSync(join(tmpdir(), 'wall-remote-'))
+  execFileSync('git', ['init', '--bare', '-b', 'main', remoteDir])
+  return remoteDir
+}
+
+/** Seed the bare remote with an initial <product>.json, via a throwaway clone. */
+function seedRemote(remoteDir: string, product: string, entries: unknown[]): void {
+  const seedDir = mkdtempSync(join(tmpdir(), 'wall-seed-'))
+  execFileSync('git', ['clone', remoteDir, seedDir], { stdio: 'ignore' })
+  git(['config', 'user.email', 'seed@example.com'], seedDir)
+  git(['config', 'user.name', 'Seed'], seedDir)
+  writeFileSync(join(seedDir, `${product}.json`), wallFile(product, entries))
+  git(['add', `${product}.json`], seedDir)
+  git(['commit', '-m', 'seed'], seedDir)
+  git(['push', 'origin', 'main'], seedDir)
+  rmSync(seedDir, { recursive: true, force: true })
+}
+
+/** Read <product>.json back out of the bare remote's main tip, via a throwaway clone. */
+function readRemote(remoteDir: string, product: string): any {
+  const readDir = mkdtempSync(join(tmpdir(), 'wall-read-'))
+  execFileSync('git', ['clone', remoteDir, readDir], { stdio: 'ignore' })
+  const data = JSON.parse(readFileSync(join(readDir, `${product}.json`), 'utf8'))
+  rmSync(readDir, { recursive: true, force: true })
+  return data
+}
+
+/** Reject every push — stands in for any push failure (including a genuine
+ * non-fast-forward raced by a concurrent release rail), which this script
+ * treats identically: refuse loudly, name the cure, touch nothing further. */
+function makeRemoteRejectPushes(remoteDir: string): void {
+  const hookPath = join(remoteDir, 'hooks', 'pre-receive')
+  writeFileSync(hookPath, '#!/bin/sh\necho "remote: simulated push rejection" >&2\nexit 1\n')
+  chmodSync(hookPath, 0o755)
+}
+
 let dir: string
+let remoteDir: string
+let cacheDir: string

 beforeEach(() => {
  dir = mkdtempSync(join(tmpdir(), 'wall-entry-test-'))
+  remoteDir = initBareRemote()
+  cacheDir = join(mkdtempSync(join(tmpdir(), 'wall-cache-')), 'soulcraft-releases')
 })

 afterEach(() => {
  rmSync(dir, { recursive: true, force: true })
+  rmSync(remoteDir, { recursive: true, force: true })
+  rmSync(cacheDir, { recursive: true, force: true })
 })

-describe('wall-entry.mjs — generate + prepend', () => {
-  it('derives headline from the first bullet and items from every bullet, hashes stripped', () => {
+describe('wall-entry.mjs — generate + publish', () => {
+  it('derives headline from the first bullet and items from every bullet, hashes stripped, and pushes it to the remote', () => {
+    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
    writeFileSync(
      join(dir, 'CHANGELOG.md'),
      buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix(wall): mechanize the entry', 'test(wall): pin the shape'] }]),
    )
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [BASE_ENTRY]))

    const result = run(
-      ['--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--file', 'wall.json'],
+      ['--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
      dir,
    )
    expect(result.status).toBe(0)
+    expect(result.stdout).toMatch(/wrote v10\.4\.12.*pushed/i)

-    const wall = JSON.parse(readFileSync(join(dir, 'wall.json'), 'utf8'))
+    const wall = readRemote(remoteDir, 'open-brainy')
    expect(wall.entries).toHaveLength(2)
    expect(wall.entries[0]).toEqual({
      version: '10.4.12',
@ -96,68 +144,192 @@ describe('wall-entry.mjs — generate + prepend', () => {
  })

  it('prepends newest-first — the new entry lands at index 0 ahead of every existing one', () => {
-    writeFileSync(
-      join(dir, 'CHANGELOG.md'),
-      buildChangelog([{ version: '10.5.0', date: '2026-09-03', bullets: ['feat: ten five'] }]),
-    )
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [BASE_ENTRY, { ...BASE_ENTRY, version: '10.4.10' }]))
+    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY, { ...BASE_ENTRY, version: '10.4.10' }])
+    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.5.0', date: '2026-09-03', bullets: ['feat: ten five'] }]))

-    run(['--product', 'open-brainy', '--version', '10.5.0', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--file', 'wall.json'], dir)
+    run(['--product', 'open-brainy', '--version', '10.5.0', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir], dir)

-    const wall = JSON.parse(readFileSync(join(dir, 'wall.json'), 'utf8'))
+    const wall = readRemote(remoteDir, 'open-brainy')
    expect(wall.entries.map((e: any) => e.version)).toEqual(['10.5.0', '10.4.11', '10.4.10'])
  })

-  it('derives no URL (null) for a product with no known public release-page pattern', () => {
+  it('replaces an entry with the same version instead of duplicating it — idempotent re-runs', () => {
+    seedRemote(remoteDir, 'open-brainy', [
+      { ...BASE_ENTRY, headline: 'stale headline, pre-fix' },
+      { ...BASE_ENTRY, version: '10.4.10' },
+    ])
+    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.11', date: '2026-09-02', bullets: ['fix: the corrected headline'] }]))
+
+    const result = run(
+      ['--product', 'open-brainy', '--version', '10.4.11', '--date', '2026-09-02', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
+      dir,
+    )
+    expect(result.status).toBe(0)
+    expect(result.stdout).toMatch(/replaced v10\.4\.11/i)
+
+    const wall = readRemote(remoteDir, 'open-brainy')
+    expect(wall.entries).toHaveLength(2) // not 3 — replaced, not duplicated
+    expect(wall.entries[0].version).toBe('10.4.11')
+    expect(wall.entries[0].headline).toBe('fix: the corrected headline')
+    expect(wall.entries[1].version).toBe('10.4.10')
+  })
+
+  it('a re-run with byte-identical content commits nothing and still succeeds', () => {
+    // headline always equals items[0] for a derived entry, so this fixture
+    // (unlike BASE_ENTRY, whose headline/items intentionally diverge for the
+    // shape-only tests below) has to keep the two in lockstep to ever roundtrip.
+    const stableEntry = { ...BASE_ENTRY, headline: 'A faster open.', items: ['A faster open.'] }
+    seedRemote(remoteDir, 'open-brainy', [stableEntry])
+    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.11', date: '2026-09-02', bullets: ['A faster open.'] }]))
+    const before = readRemote(remoteDir, 'open-brainy')
+
+    const result = run(
+      ['--product', 'open-brainy', '--version', '10.4.11', '--date', '2026-09-02', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
+      dir,
+    )
+    expect(result.status).toBe(0)
+    expect(result.stdout).toMatch(/nothing to commit/i)
+    expect(readRemote(remoteDir, 'open-brainy')).toEqual(before)
+  })
+
+  it('derives the public package-page permalink for the product engine (private repo, never null)', () => {
+    seedRemote(remoteDir, 'brainy', [{ ...BASE_ENTRY, version: '11.0.5', url: 'https://source.soulcraft.com/soulcraft/-/packages/npm/@soulcraft%2Fbrainy/11.0.5' }])
    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '11.0.6', date: '2026-09-03', bullets: ['fix: a native-only fix'] }]))
-    writeFileSync(join(dir, 'wall.json'), wallFile('brainy', [{ ...BASE_ENTRY, version: '11.0.5', url: null }]))

-    run(['--product', 'brainy', '--version', '11.0.6', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--file', 'wall.json'], dir)
+    const result = run(
+      ['--product', 'brainy', '--version', '11.0.6', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
+      dir,
+    )
+    expect(result.status).toBe(0)

-    const wall = JSON.parse(readFileSync(join(dir, 'wall.json'), 'utf8'))
-    expect(wall.entries[0].url).toBeNull()
+    const wall = readRemote(remoteDir, 'brainy')
+    expect(wall.entries[0].url).toBe('https://source.soulcraft.com/soulcraft/-/packages/npm/@soulcraft%2Fbrainy/11.0.6')
    expect(wall.entries[0].thumb).toBeNull()
  })

-  it('refuses by name when the version is already present, and leaves the file untouched', () => {
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.11', date: '2026-09-02', bullets: ['fix: whatever'] }]))
-    const before = wallFile('open-brainy', [BASE_ENTRY])
-    writeFileSync(join(dir, 'wall.json'), before)
+  it('refuses a product with no permalink pattern, naming the cure', () => {
+    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
+    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '1.0.0', date: '2026-09-03', bullets: ['feat: first'] }]))

-    const result = run(
-      ['--product', 'open-brainy', '--version', '10.4.11', '--date', '2026-09-02', '--from-changelog', 'CHANGELOG.md', '--file', 'wall.json'],
-      dir,
-    )
-
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/refusing.*10\.4\.11.*already present/i)
-    expect(readFileSync(join(dir, 'wall.json'), 'utf8')).toBe(before) // untouched
+    const result = run(['--product', 'mystery', '--version', '1.0.0', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir], dir)
+    expect(result.status).not.toBe(0)
+    expect(result.stderr).toMatch(/no permalink pattern for product "mystery"/)
+    expect(result.stderr).toMatch(/never carry url: null/)
  })

-  it('refuses when the CHANGELOG has no entry yet for the target version', () => {
+  it('refuses when the CHANGELOG has no entry yet for the target version, and touches no remote', () => {
+    seedRemote(remoteDir, 'open-brainy', [])
    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.11', date: '2026-09-02', bullets: ['fix: whatever'] }]))
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', []))
+    const beforeSha = git(['rev-parse', 'main'], remoteDir)

    const result = run(
-      ['--product', 'open-brainy', '--version', '99.0.0', '--date', '2026-09-02', '--from-changelog', 'CHANGELOG.md', '--file', 'wall.json'],
+      ['--product', 'open-brainy', '--version', '99.0.0', '--date', '2026-09-02', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
      dir,
    )

    expect(result.status).toBe(1)
    expect(result.stderr).toMatch(/no CHANGELOG entry yet/i)
+    expect(git(['rev-parse', 'main'], remoteDir)).toBe(beforeSha)
  })

-  it('refuses a cross-product write when --product does not match the target file', () => {
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '1.0.0', date: '2026-09-03', bullets: ['fix: wrong repo'] }]))
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [BASE_ENTRY]))
+  it('refuses by naming the cure when the remote cannot be cloned', () => {
+    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix: whatever'] }]))
+    const noSuchRemote = join(tmpdir(), 'wall-remote-does-not-exist-' + Date.now())

    const result = run(
-      ['--product', 'brainy', '--version', '1.0.0', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--file', 'wall.json'],
+      ['--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', noSuchRemote, '--cache-dir', cacheDir],
      dir,
    )

    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/product "open-brainy".*--product "brainy"/i)
+    expect(result.stderr).toMatch(/cannot clone/i)
+    expect(result.stderr).toMatch(/cure:/i)
+  })
+
+  it('refuses by naming the cure, and touches no remote, when the fetched wall fails shape validation', () => {
+    const seedDir = mkdtempSync(join(tmpdir(), 'wall-seed-broken-'))
+    execFileSync('git', ['clone', remoteDir, seedDir], { stdio: 'ignore' })
+    git(['config', 'user.email', 'seed@example.com'], seedDir)
+    git(['config', 'user.name', 'Seed'], seedDir)
+    writeFileSync(
+      join(seedDir, 'open-brainy.json'),
+      JSON.stringify({ product: 'open-brainy', entries: [{ version: '10.4.11', date: '2026-09-02', items: ['x'], url: null }] }, null, 2),
+    )
+    git(['add', 'open-brainy.json'], seedDir)
+    git(['commit', '-m', 'seed broken'], seedDir)
+    git(['push', 'origin', 'main'], seedDir)
+    rmSync(seedDir, { recursive: true, force: true })
+    const beforeSha = git(['rev-parse', 'main'], remoteDir)
+
+    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix: whatever'] }]))
+
+    const result = run(
+      ['--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
+      dir,
+    )
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toMatch(/fails shape validation/i)
+    expect(result.stderr).toMatch(/missing key\(s\) headline/i)
+    expect(git(['rev-parse', 'main'], remoteDir)).toBe(beforeSha)
+  })
+
+  it('refuses by naming the cure when the remote rejects the push (stands in for a raced non-fast-forward)', () => {
+    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
+    makeRemoteRejectPushes(remoteDir)
+    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix: whatever'] }]))
+
+    const result = run(
+      ['--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
+      dir,
+    )
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toMatch(/push to .* failed/i)
+    expect(result.stderr).toMatch(/cure:/i)
+  })
+
+  it('refuses a cross-product write when the file\'s "product" field does not match --product', () => {
+    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
+    const seedDir = mkdtempSync(join(tmpdir(), 'wall-seed-mismatch-'))
+    execFileSync('git', ['clone', remoteDir, seedDir], { stdio: 'ignore' })
+    git(['config', 'user.email', 'seed@example.com'], seedDir)
+    git(['config', 'user.name', 'Seed'], seedDir)
+    const corrupted = JSON.parse(readFileSync(join(seedDir, 'open-brainy.json'), 'utf8'))
+    corrupted.product = 'brainy'
+    writeFileSync(join(seedDir, 'open-brainy.json'), JSON.stringify(corrupted, null, 2) + '\n')
+    git(['add', 'open-brainy.json'], seedDir)
+    git(['commit', '-m', 'corrupt product field'], seedDir)
+    git(['push', 'origin', 'main'], seedDir)
+    rmSync(seedDir, { recursive: true, force: true })
+
+    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '1.0.0', date: '2026-09-03', bullets: ['fix: wrong repo'] }]))
+
+    const result = run(
+      ['--product', 'open-brainy', '--version', '1.0.0', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
+      dir,
+    )
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toMatch(/product "brainy".*--product "open-brainy"/i)
+  })
+})
+
+describe('wall-entry.mjs — --dry-run', () => {
+  it('prints the entry and the target path, and touches neither the cache dir nor the remote', () => {
+    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
+    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix: a dry run'] }]))
+    const beforeSha = git(['rev-parse', 'main'], remoteDir)
+
+    const result = run(
+      ['--dry-run', '--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
+      dir,
+    )
+
+    expect(result.status).toBe(0)
+    expect(result.stdout).toMatch(/would write to/i)
+    expect(result.stdout).toMatch(/"version": "10\.4\.12"/)
+    expect(git(['rev-parse', 'main'], remoteDir)).toBe(beforeSha)
  })
 })

@ -169,21 +341,28 @@ describe('wall-entry.mjs — --check', () => {
    expect(result.stdout).toMatch(/OK/)
  })

+  it('passes a file where "thumb" is entirely absent (optional per the HQ contract)', () => {
+    const { thumb, ...noThumb } = BASE_ENTRY as any
+    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [noThumb]))
+    const result = run(['--check', '--file', 'wall.json'], dir)
+    expect(result.status).toBe(0)
+  })
+
  it('catches a missing entry key', () => {
-    const broken = { version: '1.0.0', date: '2026-09-03', headline: 'h', items: ['i'], url: null } // no "thumb"
+    const broken = { version: '1.0.0', date: '2026-09-03', headline: 'h', items: ['i'] } // no "url"
    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [broken]))
    const result = run(['--check', '--file', 'wall.json'], dir)
    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/missing key\(s\) thumb/)
+    expect(result.stderr).toMatch(/missing key\(s\) url/)
  })

-  it('catches an unexpected top-level key', () => {
+  it('catches an unexpected top-level key (e.g. the retired "history" field)', () => {
    const raw = JSON.parse(wallFile('open-brainy', [BASE_ENTRY]))
-    raw.extra = 'not allowed'
+    raw.history = 'retired field'
    writeFileSync(join(dir, 'wall.json'), JSON.stringify(raw))
    const result = run(['--check', '--file', 'wall.json'], dir)
    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/unexpected key\(s\) extra/)
+    expect(result.stderr).toMatch(/unexpected key\(s\) history/)
  })

  it('catches entries that are not newest-first', () => {