feat(sessions): keep every session, record review details, name and stamp the PDF

Sessions are now the unit of the product instead of an implicit capture run.

- Nothing is deleted by default: the fixed 10-session cap is gone. An age limit
  (Never / 7 / 14 / 30 / 90 / 180 / 365 days) is chosen in Settings > Sessions and
  applied on launch, after archiving, and by "Clean up now". Sent PDFs are never
  touched.
- Each session carries review details: lane, deployed version, commit, reviewer
  (pre-filled with the Mac user) and a free note. They persist in session.json and
  are inherited by the next session, so a review run is typed once.
- PDF file names are Redline-<yyyyMMdd-HHmm>-<LANE>-<SHORTID>.pdf, and every page
  carries a two-line reference footer (tool, build time, session / lane, deployed
  build, commit, reviewer, note). The PDF document info carries the same values in
  Author and Keywords.
- Verification: 159 tests, a headless panel self-test, and a LaunchServices-driven
  end-to-end run that types and clicks the real panel.
This commit is contained in:
Claude Fable 5
2026-10-31 11:32:54 +04:00
parent 542aad296b
commit 02fa791b78
26 changed files with 2780 additions and 279 deletions
@@ -4,9 +4,9 @@ import ImageIO
import Testing
import ShotdeckCore
// Session lifecycle + retention (MMDB-2925): "Start new session" keeps the current
// screenshots as a past session, and the newest 10 sessions are retained in the one
// archive folder.
// Session lifecycle + retention: "Start new session" keeps the current screenshots as
// a past session; every session is kept by default, and an age limit chosen in
// Settings is the only thing that ever removes one.
// MARK: - 1. closeCurrentSession keeps the captures as a past session
@@ -95,14 +95,16 @@ func pastSessionsDistinguishSentFromUnsentByPDFFileName() async throws {
#expect(past.map(\.pdfFileName) == [nil, "Redline-20261011-120000.pdf"])
}
// MARK: - 4. retention keeps the newest 10 sessions, in the one archive folder
// MARK: - 4. nothing is deleted by default
@Test
func retentionKeepsTheNewestTenSessionsAndRemovesTheRest() async throws {
func defaultPolicyKeepsEverySession() async throws {
let (root, paths) = try makeIsolatedPaths()
defer { try? FileManager.default.removeItem(at: root) }
let store = try SpoolStore(paths: paths)
#expect(await store.configuredRetention() == .never)
var closedIDs: [UUID] = []
for index in 0..<12 {
_ = try await store.append(
@@ -113,78 +115,141 @@ func retentionKeepsTheNewestTenSessionsAndRemovesTheRest() async throws {
closedIDs.append(closed.id)
}
// All 12 sessions live in the single archive/ folder as UUID session folders.
// All 12 sessions live on in the single archive/ folder; none was pruned.
let fm = FileManager.default
let entries = try fm.contentsOfDirectory(at: paths.archive, includingPropertiesForKeys: nil)
let sessionDirs = entries.filter { UUID(uuidString: $0.lastPathComponent) != nil }
#expect(sessionDirs.count == SpoolStore.defaultRetainedSessionCount)
#expect(sessionDirs.count == closedIDs.count)
let kept = try await store.archivedSessions().map(\.id)
#expect(kept == Array(closedIDs.suffix(SpoolStore.defaultRetainedSessionCount).reversed()))
#expect(kept == closedIDs.reversed())
// The two oldest sessions are gone; the newest ten are fully on disk.
for id in closedIDs.prefix(2) {
#expect(!fm.fileExists(atPath: paths.archiveDirectory(id).path))
}
for id in closedIDs.suffix(SpoolStore.defaultRetainedSessionCount) {
for id in closedIDs {
#expect(fm.fileExists(atPath: paths.archiveDirectory(id).appendingPathComponent("session.json").path))
}
// The open session is never touched by retention.
let open = try await store.currentSession()
#expect(open.state == .open)
#expect(open.isEmpty)
#expect(fm.fileExists(atPath: paths.sessionDirectory(open.id).path))
// A prune under the default policy removes nothing at all.
#expect(try await store.pruneExpiredSessions().isEmpty)
#expect(try await store.expiredSessionIDs().isEmpty)
}
// MARK: - 5. explicit prune keeps exactly the requested count
// MARK: - 5. an age limit removes exactly the expired sessions
@Test
func pruneArchivedSessionsKeepingNRemovesExactlyTheOldest() async throws {
func ageLimitRemovesOnlySessionsOlderThanTheCutoff() async throws {
let (root, paths) = try makeIsolatedPaths()
defer { try? FileManager.default.removeItem(at: root) }
let store = try SpoolStore(paths: paths)
var closedIDs: [UUID] = []
for _ in 0..<4 {
_ = try await store.append(
pngData: try makePNGData(width: 4, height: 4, red: 0.2, green: 0.2, blue: 0.2),
pixelWidth: 4, pixelHeight: 4, scale: 1.0, capturedAt: Date())
closedIDs.append(try #require(try await store.closeCurrentSession()).id)
let now = Date(timeIntervalSince1970: 1_700_000_000) // fixed "now" for the test
let day: TimeInterval = 86_400
let oldIDs = try [
try writeArchivedSession(createdAt: now.addingTimeInterval(-40 * day), in: paths),
try writeArchivedSession(createdAt: now.addingTimeInterval(-31 * day), in: paths),
]
let recentIDs = try [
try writeArchivedSession(createdAt: now.addingTimeInterval(-29 * day), in: paths),
try writeArchivedSession(createdAt: now.addingTimeInterval(-1 * day), in: paths),
]
let store = try SpoolStore(paths: paths, retention: .days(30))
// Asking what would happen deletes nothing.
#expect(Set(try await store.expiredSessionIDs(now: now)) == Set(oldIDs))
#expect(try await store.archivedSessions().count == 4)
let removed = try await store.pruneExpiredSessions(now: now)
#expect(Set(removed) == Set(oldIDs))
let fm = FileManager.default
for id in oldIDs {
#expect(!fm.fileExists(atPath: paths.archiveDirectory(id).path))
}
for id in recentIDs {
#expect(fm.fileExists(atPath: paths.archiveDirectory(id).appendingPathComponent("session.json").path))
}
let removed = try await store.pruneArchivedSessions(keeping: 2)
#expect(removed == Array(closedIDs.prefix(2).reversed())) // newest-first walk order
let kept = try await store.archivedSessions().map(\.id)
#expect(kept == Array(closedIDs.suffix(2).reversed()))
// Idempotent: nothing left to prune at that limit.
let removedAgain = try await store.pruneArchivedSessions(keeping: 2)
#expect(removedAgain.isEmpty)
// The open session is never a candidate, and a second pass is a no-op.
#expect(try await store.currentSession().state == .open)
#expect(try await store.pruneExpiredSessions(now: now).isEmpty)
}
// MARK: - 6. retention runs on the send path too
// MARK: - 6. the archive path applies the configured age limit
@Test
func theSendArchivePathAppliesRetention() async throws {
func theArchivePathAppliesTheAgeLimit() async throws {
let (root, paths) = try makeIsolatedPaths()
defer { try? FileManager.default.removeItem(at: root) }
let store = try SpoolStore(paths: paths)
var sentIDs: [UUID] = []
for index in 0..<(SpoolStore.defaultRetainedSessionCount + 3) {
_ = try await store.append(
pngData: try makePNGData(width: 4, height: 4, red: 0.3, green: 0.3, blue: 0.3),
pixelWidth: 4, pixelHeight: 4, scale: 1.0,
capturedAt: Date(timeIntervalSince1970: 1_700_100_000 + Double(index)))
let archived = try await store.archiveCurrent(pdfFileName: "Redline-\(index).pdf")
sentIDs.append(archived.id)
}
let day: TimeInterval = 86_400
let expiredID = try writeArchivedSession(
createdAt: Date().addingTimeInterval(-10 * day), in: paths)
let store = try SpoolStore(paths: paths, retention: .days(7))
_ = try await store.append(
pngData: try makePNGData(width: 4, height: 4, red: 0.3, green: 0.3, blue: 0.3),
pixelWidth: 4, pixelHeight: 4, scale: 1.0, capturedAt: Date())
let archived = try await store.archiveCurrent(pdfFileName: "Redline-20261031-1200-A1B2C3D4.pdf")
let kept = try await store.archivedSessions()
#expect(kept.count == SpoolStore.defaultRetainedSessionCount)
#expect(kept.map(\.id) == Array(sentIDs.suffix(SpoolStore.defaultRetainedSessionCount).reversed()))
#expect(kept.allSatisfy { $0.pdfFileName != nil })
#expect(kept.map(\.id) == [archived.id])
#expect(!FileManager.default.fileExists(atPath: paths.archiveDirectory(expiredID).path))
}
// MARK: - 7. review context is persisted, survives a relaunch and is inherited
@Test
func reviewContextPersistsAndIsInheritedByTheNextSession() async throws {
let (root, paths) = try makeIsolatedPaths()
defer { try? FileManager.default.removeItem(at: root) }
let store = try SpoolStore(paths: paths)
let context = ReviewContext(
lane: "dev03", deployedVersion: "v1.4.2 (41)", commit: "a1b2c3d4",
reviewer: "Ben Hippler", note: "checkout flow")
let updated = try await store.setContext(context)
#expect(updated.context == context)
// A second store on the same directory is what a relaunch sees.
let reopened = try SpoolStore(paths: paths)
#expect(try await reopened.currentSession().context == context)
_ = try await store.append(
pngData: try makePNGData(width: 4, height: 4, red: 0.4, green: 0.4, blue: 0.4),
pixelWidth: 4, pixelHeight: 4, scale: 1.0, capturedAt: Date())
let archived = try #require(try await store.closeCurrentSession())
#expect(archived.context == context)
// The fresh session keeps the same review details.
#expect(try await store.currentSession().context == context)
}
// MARK: - 8. a manifest written before contexts existed still loads
@Test
func legacyManifestWithoutContextDecodesAsEmptyContext() async throws {
let (root, paths) = try makeIsolatedPaths()
defer { try? FileManager.default.removeItem(at: root) }
let id = UUID()
let dir = paths.archiveDirectory(id)
try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
let legacyJSON = """
{
"id": "\(id.uuidString)",
"createdAt": "2026-10-11T12:00:00Z",
"state": "archived",
"captures": [],
"pdfFileName": "Redline-20261011-120000.pdf"
}
"""
try Data(legacyJSON.utf8).write(to: dir.appendingPathComponent("session.json"))
let store = try SpoolStore(paths: paths)
let sessions = try await store.archivedSessions()
#expect(sessions.map(\.id) == [id])
#expect(sessions.first?.context == .empty)
#expect(sessions.first?.pdfFileName == "Redline-20261011-120000.pdf")
}
// MARK: - 7. a stale open session is never returned as current (truth guard)
@@ -218,6 +283,28 @@ func aStaleOpenSessionIsNeverReturnedAsCurrent() async throws {
// MARK: - Fixtures
/// Writes an archived session folder with the given creation date, exactly the shape
/// production writes (a manifest plus one PNG), so retention can be exercised without
/// waiting days.
private func writeArchivedSession(createdAt: Date, in paths: AppSupportPaths) throws -> UUID {
let id = UUID()
let dir = paths.archiveDirectory(id)
try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
let pngName = "001-A1B2C3D4.png"
try makePNGData(width: 4, height: 4, red: 0.5, green: 0.5, blue: 0.5)
.write(to: dir.appendingPathComponent(pngName))
let capture = Capture(
id: UUID(), sequence: 1, fileName: pngName,
pixelWidth: 4, pixelHeight: 4, scale: 1.0, capturedAt: createdAt)
let session = CaptureSession(
id: id, createdAt: createdAt, state: .archived, captures: [capture],
pdfFileName: "Redline-\(DubaiTime.fileMinuteStamp(createdAt)).pdf")
let encoder = JSONEncoder()
encoder.dateEncodingStrategy = .iso8601
try encoder.encode(session).write(to: dir.appendingPathComponent("session.json"))
return id
}
private enum FixtureError: Error {
case pngGenerationFailed
}