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
@@ -2,7 +2,7 @@ import Foundation
public enum SessionState: String, Codable, Sendable {
case open // accepting captures
case archived // closed and kept as a past session (sent or not); pruned by retention
case archived // closed and kept as a past session (sent or not); pruned only by an age policy the user set
}
/// The manifest persisted as session.json alongside the PNGs.
@@ -12,28 +12,39 @@ public struct CaptureSession: Codable, Sendable, Identifiable, Equatable {
public private(set) var state: SessionState
public private(set) var captures: [Capture]
/// Set when the PDF is built, so a re-send reuses the same file. nil on a
/// session that was closed without ever sending — the Past submissions list
/// session that was closed without ever sending — the Past sessions list
/// shows that as "Not sent".
public private(set) var pdfFileName: String?
/// Lane / deployed build / commit / reviewer / note for this session. Absent from
/// manifests written before v0.5.0 — those decode as `.empty`, never a guess.
public private(set) var context: ReviewContext
public init(
id: UUID,
createdAt: Date,
state: SessionState,
captures: [Capture],
pdfFileName: String?
pdfFileName: String?,
context: ReviewContext = .empty
) {
self.id = id
self.createdAt = createdAt
self.state = state
self.captures = captures
self.pdfFileName = pdfFileName
self.context = context
}
public var isEmpty: Bool {
captures.isEmpty
}
/// First 8 characters of the UUID, uppercase — the stable short handle used in
/// file names, the session list and the PDF header.
public var shortID: String {
String(id.uuidString.replacingOccurrences(of: "-", with: "").prefix(8)).uppercased()
}
/// max(sequence)+1, or 1 when empty.
public var nextSequence: Int {
(captures.map(\.sequence).max() ?? 0) + 1
@@ -46,7 +57,8 @@ public struct CaptureSession: Codable, Sendable, Identifiable, Equatable {
createdAt: createdAt,
state: state,
captures: captures + [capture],
pdfFileName: pdfFileName
pdfFileName: pdfFileName,
context: context
)
}
@@ -58,7 +70,8 @@ public struct CaptureSession: Codable, Sendable, Identifiable, Equatable {
createdAt: createdAt,
state: state,
captures: captures.filter { $0.id != captureID },
pdfFileName: pdfFileName
pdfFileName: pdfFileName,
context: context
)
}
@@ -70,7 +83,50 @@ public struct CaptureSession: Codable, Sendable, Identifiable, Equatable {
createdAt: createdAt,
state: .archived,
captures: captures,
pdfFileName: pdfFileName
pdfFileName: pdfFileName,
context: context
)
}
/// Value-semantic: returns a new session; does not mutate `self`.
public func withContext(_ newContext: ReviewContext) -> CaptureSession {
CaptureSession(
id: id,
createdAt: createdAt,
state: state,
captures: captures,
pdfFileName: pdfFileName,
context: newContext
)
}
/// Value-semantic: returns a new session; does not mutate `self`.
public func withPDFFileName(_ name: String?) -> CaptureSession {
CaptureSession(
id: id,
createdAt: createdAt,
state: state,
captures: captures,
pdfFileName: name,
context: context
)
}
private enum CodingKeys: String, CodingKey {
case id, createdAt, state, captures, pdfFileName, context
}
/// `context` is decoded leniently so every manifest written before v0.5.0 keeps
/// loading; all other keys are required, exactly as before.
public init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
self.init(
id: try container.decode(UUID.self, forKey: .id),
createdAt: try container.decode(Date.self, forKey: .createdAt),
state: try container.decode(SessionState.self, forKey: .state),
captures: try container.decode([Capture].self, forKey: .captures),
pdfFileName: try container.decodeIfPresent(String.self, forKey: .pdfFileName),
context: try container.decodeIfPresent(ReviewContext.self, forKey: .context) ?? .empty
)
}
}
@@ -0,0 +1,90 @@
import Foundation
/// What a review session is ABOUT, recorded once per session and printed on every
/// PDF page plus the PDF's document info, so an annotated page that comes back
/// weeks later still says which lane, build and commit it referred to, who took it
/// and when.
///
/// Every field is optional in practice (empty string = not recorded); nothing here
/// is invented when the user leaves it blank. `note` is free text.
public struct ReviewContext: Codable, Sendable, Equatable {
/// Hard cap per field: this text ends up on every PDF page, so an unbounded
/// paste must not be able to break the layout.
public static let maxFieldLength = 120
public var lane: String
public var deployedVersion: String
public var commit: String
public var reviewer: String
public var note: String
public init(
lane: String = "",
deployedVersion: String = "",
commit: String = "",
reviewer: String = "",
note: String = ""
) {
self.lane = Self.cleaned(lane)
self.deployedVersion = Self.cleaned(deployedVersion)
self.commit = Self.cleaned(commit)
self.reviewer = Self.cleaned(reviewer)
self.note = Self.cleaned(note)
}
public static let empty = ReviewContext()
/// The macOS account's own name, used to pre-fill `reviewer` on a fresh session.
/// `NSFullUserName()` is empty on a host with no full name set, in which case the
/// short login name identifies the same person.
public static func currentUser() -> String {
let full = NSFullUserName().trimmingCharacters(in: .whitespacesAndNewlines)
if !full.isEmpty { return cleaned(full) }
return cleaned(NSUserName())
}
public var isEmpty: Bool {
lane.isEmpty && deployedVersion.isEmpty && commit.isEmpty && reviewer.isEmpty && note.isEmpty
}
/// "DEV03 · v1.4.2 · a1b2c3d · Ben Hippler" — empty parts are dropped, never
/// replaced with a placeholder.
public var summaryLine: String {
summaryParts.joined(separator: " · ")
}
/// The individual summary parts in display order, empty ones dropped.
public var summaryParts: [String] {
var parts: [String] = []
if !lane.isEmpty { parts.append(lane) }
if !deployedVersion.isEmpty { parts.append(deployedVersion) }
if !commit.isEmpty { parts.append(commit) }
if !reviewer.isEmpty { parts.append(reviewer) }
return parts
}
/// JSON kept tolerant on purpose: an older manifest has no context at all, and a
/// newer one may add fields. Any unknown key is ignored; every known field is
/// optional.
public init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
self.init(
lane: try container.decodeIfPresent(String.self, forKey: .lane) ?? "",
deployedVersion: try container.decodeIfPresent(String.self, forKey: .deployedVersion) ?? "",
commit: try container.decodeIfPresent(String.self, forKey: .commit) ?? "",
reviewer: try container.decodeIfPresent(String.self, forKey: .reviewer) ?? "",
note: try container.decodeIfPresent(String.self, forKey: .note) ?? ""
)
}
/// Trims, collapses line breaks (the value is drawn on one line) and caps length.
static func cleaned(_ raw: String) -> String {
let collapsed = raw
.replacingOccurrences(of: "\r\n", with: " ")
.replacingOccurrences(of: "\n", with: " ")
.replacingOccurrences(of: "\r", with: " ")
.trimmingCharacters(in: .whitespaces)
guard collapsed.count > maxFieldLength else { return collapsed }
return String(collapsed.prefix(maxFieldLength))
}
}