feat: add postinstall welcome banner and changelog display after upgrade (#48)

Show a welcome banner with quick-start commands after npm install.
Display relevant CHANGELOG.md entries after a successful upgrade so
users can see what changed between their old and new versions.

The changelog is bundled at build time via esbuild define and also
copied into the published npm package as a fallback.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: anandgupta42

packages/altimate-code/script/build.ts

@@ -25,6 +25,11 @@ if (!engineVersionMatch) {
 const engineVersion = engineVersionMatch[1]
 console.log(`Engine version: ${engineVersion}`)
 
+// Read CHANGELOG.md for bundling
+const changelogPath = path.resolve(dir, "../../CHANGELOG.md")
+const changelog = fs.existsSync(changelogPath) ? await Bun.file(changelogPath).text() : ""
+console.log(`Loaded CHANGELOG.md (${changelog.length} chars)`)
+
 const modelsUrl = process.env.OPENCODE_MODELS_URL || "https://models.dev"
 // Fetch and generate models.dev snapshot
 const modelsData = process.env.MODELS_DEV_API_JSON
@@ -213,6 +218,7 @@ for (const item of targets) {
       ALTIMATE_CLI_CHANNEL: `'${Script.channel}'`,
       ALTIMATE_ENGINE_VERSION: `'${engineVersion}'`,
       ALTIMATE_CLI_MIGRATIONS: JSON.stringify(migrations),
+      ALTIMATE_CLI_CHANGELOG: JSON.stringify(changelog),
       OTUI_TREE_SITTER_WORKER_PATH: bunfsRoot + workerRelativePath,
     },
   })

packages/altimate-code/script/postinstall.mjs

@@ -85,12 +85,48 @@ function prepareBinDirectory(binaryName) {
   return { binDir, targetPath }
 }
 
+function printWelcome(version) {
+  const v = `altimate-code v${version} installed`
+  const lines = [
+    "",
+    "  Get started:",
+    "    altimate              Open the TUI",
+    '    altimate run "hello"  Run a quick task',
+    "    altimate --help       See all commands",
+    "",
+    "  Docs: https://altimate-code.dev",
+    "",
+  ]
+  // Box width: pad all lines to the same length
+  const contentWidth = Math.max(v.length, ...lines.map((l) => l.length)) + 2
+  const pad = (s) => s + " ".repeat(contentWidth - s.length)
+  const top = `  ╭${"─".repeat(contentWidth + 2)}╮`
+  const bot = `  ╰${"─".repeat(contentWidth + 2)}╯`
+  const empty = `  │ ${" ".repeat(contentWidth)} │`
+  const row = (s) => `  │ ${pad(s)} │`
+
+  console.log(top)
+  console.log(empty)
+  console.log(row(` ${v}`))
+  for (const line of lines) console.log(row(line))
+  console.log(bot)
+}
+
 async function main() {
+  let version
+  try {
+    const pkgPath = path.join(__dirname, "package.json")
+    if (fs.existsSync(pkgPath)) {
+      version = JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version
+    }
+  } catch {}
+
   try {
     if (os.platform() === "win32") {
       // On Windows, the .exe is already included in the package and bin field points to it
       // No postinstall setup needed
       console.log("Windows detected: binary setup not needed (using packaged .exe)")
+      if (version) printWelcome(version)
       return
     }
 
@@ -105,6 +141,7 @@ async function main() {
       fs.copyFileSync(binaryPath, target)
     }
     fs.chmodSync(target, 0o755)
+    if (version) printWelcome(version)
   } catch (error) {
     console.error("Failed to setup altimate-code binary:", error.message)
     process.exit(1)

packages/altimate-code/script/publish.ts

@@ -19,6 +19,7 @@ await $`mkdir -p ./dist/${pkg.name}`
 await $`cp -r ./bin ./dist/${pkg.name}/bin`
 await $`cp ./script/postinstall.mjs ./dist/${pkg.name}/postinstall.mjs`
 await Bun.file(`./dist/${pkg.name}/LICENSE`).write(await Bun.file("../../LICENSE").text())
+await Bun.file(`./dist/${pkg.name}/CHANGELOG.md`).write(await Bun.file("../../CHANGELOG.md").text())
 
 await Bun.file(`./dist/${pkg.name}/package.json`).write(
   JSON.stringify(

packages/altimate-code/src/cli/changelog.ts

@@ -0,0 +1,67 @@
+declare const ALTIMATE_CLI_CHANGELOG: string | undefined
+
+/** Parse a semver string into comparable numeric tuple. Returns null on failure. */
+function parseSemver(v: string): [number, number, number] | null {
+  const clean = v.replace(/^v/, "").split("-")[0]
+  const parts = clean.split(".")
+  if (parts.length !== 3) return null
+  const nums = parts.map(Number) as [number, number, number]
+  if (nums.some(isNaN)) return null
+  return nums
+}
+
+/** Compare two semver tuples: -1 if a < b, 0 if equal, 1 if a > b */
+function compareSemver(a: [number, number, number], b: [number, number, number]): number {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] < b[i]) return -1
+    if (a[i] > b[i]) return 1
+  }
+  return 0
+}
+
+/**
+ * Parse changelog content and extract entries for versions between
+ * `fromVersion` (exclusive) and `toVersion` (inclusive).
+ */
+export function extractChangelogFromContent(content: string, fromVersion: string, toVersion: string): string {
+  try {
+    if (!content) return ""
+
+    const from = parseSemver(fromVersion)
+    const to = parseSemver(toVersion)
+    if (!from || !to) return ""
+
+    // Split on ## [x.y.z] headings
+    const sectionRegex = /^## \[([^\]]+)\]/gm
+    const sections: { version: string; start: number }[] = []
+    let match: RegExpExecArray | null
+    while ((match = sectionRegex.exec(content)) !== null) {
+      sections.push({ version: match[1], start: match.index })
+    }
+
+    if (sections.length === 0) return ""
+
+    const lines: string[] = []
+    for (let i = 0; i < sections.length; i++) {
+      const ver = parseSemver(sections[i].version)
+      if (!ver) continue
+      // Include versions where: from < ver <= to
+      if (compareSemver(ver, from) > 0 && compareSemver(ver, to) <= 0) {
+        const end = i + 1 < sections.length ? sections[i + 1].start : content.length
+        lines.push(content.slice(sections[i].start, end).trimEnd())
+      }
+    }
+
+    return lines.join("\n\n")
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * Extract changelog entries using the build-time bundled CHANGELOG.md.
+ */
+export function extractChangelog(fromVersion: string, toVersion: string): string {
+  const content = typeof ALTIMATE_CLI_CHANGELOG === "string" ? ALTIMATE_CLI_CHANGELOG : ""
+  return extractChangelogFromContent(content, fromVersion, toVersion)
+}

packages/altimate-code/src/cli/cmd/upgrade.ts

@@ -2,6 +2,7 @@ import type { Argv } from "yargs"
 import { UI } from "../ui"
 import * as prompts from "@clack/prompts"
 import { Installation } from "../../installation"
+import { extractChangelog } from "../changelog"
 
 export const UpgradeCommand = {
   command: "upgrade [target]",
@@ -68,6 +69,12 @@ export const UpgradeCommand = {
       return
     }
     spinner.stop("Upgrade complete")
+
+    const changelog = extractChangelog(Installation.VERSION, target)
+    if (changelog) {
+      prompts.log.info("What's new:\n\n" + changelog)
+    }
+
     prompts.outro("Done")
   },
 }

packages/altimate-code/test/cli/changelog.test.ts

@@ -0,0 +1,86 @@
+import { test, expect } from "bun:test"
+import { extractChangelogFromContent } from "../../src/cli/changelog"
+
+const sampleChangelog = `# Changelog
+
+## [0.3.0] - 2026-04-01
+
+### Added
+
+- New feature A
+
+## [0.2.2] - 2026-03-05
+
+### Fixed
+
+- Bug fix B
+
+## [0.2.1] - 2026-03-05
+
+### Added
+
+- Feature C
+
+## [0.2.0] - 2026-03-04
+
+### Added
+
+- Feature D
+
+## [0.1.0] - 2025-06-01
+
+### Added
+
+- Initial release
+`
+
+test("extracts changelog between two versions", () => {
+  const result = extractChangelogFromContent(sampleChangelog, "0.2.0", "0.2.2")
+  expect(result).toContain("## [0.2.2]")
+  expect(result).toContain("Bug fix B")
+  expect(result).toContain("## [0.2.1]")
+  expect(result).toContain("Feature C")
+  expect(result).not.toContain("## [0.2.0]")
+  expect(result).not.toContain("## [0.3.0]")
+  expect(result).not.toContain("## [0.1.0]")
+})
+
+test("extracts single version", () => {
+  const result = extractChangelogFromContent(sampleChangelog, "0.2.1", "0.2.2")
+  expect(result).toContain("## [0.2.2]")
+  expect(result).toContain("Bug fix B")
+  expect(result).not.toContain("## [0.2.1]")
+})
+
+test("returns empty string when no versions in range", () => {
+  const result = extractChangelogFromContent(sampleChangelog, "0.3.0", "0.4.0")
+  expect(result).toBe("")
+})
+
+test("returns empty string for empty content", () => {
+  expect(extractChangelogFromContent("", "0.1.0", "0.2.0")).toBe("")
+})
+
+test("handles v-prefixed versions", () => {
+  const result = extractChangelogFromContent(sampleChangelog, "v0.2.0", "v0.2.2")
+  expect(result).toContain("## [0.2.2]")
+  expect(result).toContain("## [0.2.1]")
+})
+
+test("returns empty string for invalid version strings", () => {
+  expect(extractChangelogFromContent(sampleChangelog, "not-a-version", "0.2.0")).toBe("")
+  expect(extractChangelogFromContent(sampleChangelog, "0.1.0", "bad")).toBe("")
+})
+
+test("works with the real CHANGELOG.md", async () => {
+  const fs = await import("fs")
+  const path = await import("path")
+  const changelogPath = path.resolve(import.meta.dir, "../../../../CHANGELOG.md")
+  if (!fs.existsSync(changelogPath)) return // skip if not available
+
+  const content = fs.readFileSync(changelogPath, "utf-8")
+  const result = extractChangelogFromContent(content, "0.1.0", "0.2.0")
+  expect(result).toContain("## [0.2.0]")
+  expect(result).toContain("Context management")
+  expect(result).not.toContain("## [0.1.0]")
+})