SPB Git
spboucher.ai

spb/forge-studio

Public

The Instruments of LLM training — a native macOS cockpit for Forge. Train language models from scratch on Apple Silicon without a terminal.

macosswiftaimlxtraining

Forge Studio M1: SwiftPM app skeleton, full config codec, run supervisor, live dashboard

- RESEARCH.md: ground-truth Forge contract (config schema incl. waves 1-3,
  CLI, log.csv grammar with elapsed_s, checkpoint/resume, signals)
- ForgeConfig: byte-compatible Codable mirror of every model/train field,
  param-count formula cross-checked against forge info, LR-schedule math
- Services: ProcessRunner (actor, line streaming), LogParser (header-driven
  CSV + stdout events), MetricsStore (actor, incremental CSV tail, LTTB
  snapshots), RunStore (atomic registry), RunSupervisor (state machine,
  launch/stop, 1 Hz ingest), ForgeBinaryLocator, SystemInfo
- Charts: LTTB downsampler, bias-corrected EMA
- UI: NavigationSplitView shell, run rows/badges, RunDetail dashboard
  (loss raw+EMA+val, log-Y, best-val marker, LR/tok-s/grad-norm secondary
  charts, console), New Run sheet (presets, derived panel, LR preview,
  inline validation), Settings with forge-info validation
- scripts: package-app.sh (SPM -> .app, ad-hoc) and notarize.sh with the
  real zyquo-term identity (Team 3YM54G49SN, profile MacLustr-Notarize)
- 8 tests green: config round-trip vs real configs, param count, LTTB,
  EMA, CSV/stdout parsers, state machine, LR preview

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
simon-pierre boucher committed (Aug 5, 2026) Browse files

25 changed files +2,227 −0

25 changed files
Unified Split
added .gitignore +3 −0
@@ -0,0 +1,3 @@
1+.build/
2+dist/
3+.DS_Store
added CLAUDE.md +27 −0
@@ -0,0 +1,27 @@
1+# CLAUDE.md — Forge Studio
2+
3+<!--
4+Author: Simon-Pierre Boucher
5+Contact: contact@spboucher.ai
6+-->
7+
8+> **Instruction to Claude:** Every source file created in this project (Swift, scripts,
9+> plists, Metal, Makefiles) must begin with a header comment containing:
10+> `Author: Simon-Pierre Boucher — contact@spboucher.ai`
11+
12+> **Quality bar:** This app must feel like a first-party Apple pro tool — the
13+> "Instruments of LLM training." Every screen, every chart, every error message is
14+> judged against that standard. If a feature would ship half-working, it doesn't ship;
15+> it gets fixed. No placeholder UI, no TODO left in released code, no chart that
16+> jitters, no run state that can be lost.
17+
18+(Spec complète fournie par l'utilisateur — voir la conversation d'origine ; ce fichier
19+reprend les points de contrat. L'app est le compagnon GUI de Forge :
20+https://github.com/spboucher-ai/forge — datasets, config, runs, dashboard de métriques
21+légendaire, checkpoints/génération/éval, DMG signé/notarisé.)
22+
23+- macOS 14+, Apple Silicon, Swift 5.10+/SwiftUI/Swift Concurrency, Swift Charts.
24+- Build canonique : SwiftPM (pattern zyquo-term) ; l'app pilote le binaire `forge`
25+ en sous-processus ; métriques via `log.csv` (flush par step, voir RESEARCH.md).
26+- Signing/notarization : identité et profil extraits de zyquo-term (voir
27+ scripts/notarize.sh) — Team 3YM54G49SN, profil keychain "MacLustr-Notarize".
added ForgeStudio/Charts/Downsampler.swift +59 −0
@@ -0,0 +1,59 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// LTTB (largest-triangle-three-buckets) downsampling: preserves the visual
4+// shape of a series — endpoints kept exactly, one representative point per
5+// bucket chosen to maximize the triangle area with its neighbors. Used to
6+// keep chart data at ~2× pixel width regardless of run length.
7+import Foundation
8+
9+enum Downsampler {
10+ struct XY: Equatable, Sendable {
11+ var x: Double
12+ var y: Double
13+ }
14+
15+ static func lttb(_ points: [XY], threshold: Int) -> [XY] {
16+ let n = points.count
17+ guard threshold >= 3, n > threshold else { return points }
18+
19+ var sampled: [XY] = []
20+ sampled.reserveCapacity(threshold)
21+ sampled.append(points[0])
22+
23+ let bucketSize = Double(n - 2) / Double(threshold - 2)
24+ var a = 0 // index of the previously selected point
25+
26+ for i in 0..<(threshold - 2) {
27+ // Average of the NEXT bucket is the third triangle vertex.
28+ let nextStart = Int(Double(i + 1) * bucketSize) + 1
29+ let nextEnd = min(Int(Double(i + 2) * bucketSize) + 1, n)
30+ var avgX = 0.0, avgY = 0.0
31+ let span = max(nextEnd - nextStart, 1)
32+ for j in nextStart..<max(nextEnd, nextStart + 1) where j < n {
33+ avgX += points[j].x
34+ avgY += points[j].y
35+ }
36+ avgX /= Double(span)
37+ avgY /= Double(span)
38+
39+ let start = Int(Double(i) * bucketSize) + 1
40+ let end = min(Int(Double(i + 1) * bucketSize) + 1, n - 1)
41+
42+ var maxArea = -1.0
43+ var chosen = start
44+ let pa = points[a]
45+ for j in start..<max(end, start + 1) {
46+ let area = abs((pa.x - avgX) * (points[j].y - pa.y)
47+ - (pa.x - points[j].x) * (avgY - pa.y))
48+ if area > maxArea {
49+ maxArea = area
50+ chosen = j
51+ }
52+ }
53+ sampled.append(points[chosen])
54+ a = chosen
55+ }
56+ sampled.append(points[n - 1])
57+ return sampled
58+ }
59+}
added ForgeStudio/Charts/Smoothing.swift +22 −0
@@ -0,0 +1,22 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Bias-corrected exponential moving average (TensorBoard semantics): with
4+// smoothing s ∈ [0,1), ema_t = s·ema_{t-1} + (1−s)·x_t, displayed as
5+// ema_t / (1 − s^(t+1)) so early points aren't dragged toward zero.
6+import Foundation
7+
8+enum Smoothing {
9+ static func ema(_ values: [Double], smoothing: Double) -> [Double] {
10+ guard smoothing > 0, smoothing < 1, !values.isEmpty else { return values }
11+ var out: [Double] = []
12+ out.reserveCapacity(values.count)
13+ var acc = 0.0
14+ var correction = 1.0
15+ for v in values {
16+ acc = smoothing * acc + (1 - smoothing) * v
17+ correction *= smoothing
18+ out.append(acc / (1 - correction))
19+ }
20+ return out
21+ }
22+}
added ForgeStudio/ForgeStudioApp.swift +75 −0
@@ -0,0 +1,75 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Forge Studio — GUI companion for the Forge LLM training framework.
4+import SwiftUI
5+
6+@main
7+struct ForgeStudioApp: App {
8+ @State private var model = AppModel()
9+
10+ var body: some Scene {
11+ WindowGroup("Forge Studio") {
12+ ContentView()
13+ .environment(model)
14+ .frame(minWidth: 980, minHeight: 640)
15+ }
16+ Settings {
17+ SettingsView()
18+ .environment(model)
19+ }
20+ }
21+}
22+
23+@Observable
24+@MainActor
25+final class AppModel {
26+ var store: RunStore
27+ var supervisor: RunSupervisor
28+ var forgeDevice: String?
29+ var forgeError: String?
30+
31+ init() {
32+ let workspace = ForgeBinaryLocator.savedWorkspaceURL
33+ ?? FileManager.default.homeDirectoryForCurrentUser
34+ .appendingPathComponent("ForgeStudioWorkspace")
35+ let store = RunStore(workspace: workspace)
36+ self.store = store
37+ self.supervisor = RunSupervisor(store: store)
38+ Task { await self.validateForge() }
39+ }
40+
41+ func validateForge() async {
42+ guard let binary = ForgeBinaryLocator.savedBinaryURL
43+ ?? ForgeBinaryLocator.candidates().first else {
44+ forgeError = "Binaire forge introuvable — choisissez-le dans les Réglages."
45+ return
46+ }
47+ switch await ForgeBinaryLocator.validate(binary: binary) {
48+ case .success(let v):
49+ forgeDevice = v.version
50+ forgeError = nil
51+ ForgeBinaryLocator.save(binary: binary)
52+ case .failure(let e):
53+ forgeError = e.localizedDescription
54+ }
55+ }
56+
57+ func datasets() -> [Dataset] {
58+ let dataDir = store.workspaceURL.appendingPathComponent("data")
59+ let forgeData = ForgeBinaryLocator.savedBinaryURL?
60+ .deletingLastPathComponent().deletingLastPathComponent()
61+ .appendingPathComponent("data")
62+ var found: [Dataset] = []
63+ for root in [dataDir, forgeData].compactMap({ $0 }) {
64+ guard let subdirs = try? FileManager.default.contentsOfDirectory(
65+ at: root, includingPropertiesForKeys: nil) else { continue }
66+ for dir in subdirs {
67+ if let ds = Dataset.scan(directory: dir),
68+ !found.contains(where: { $0.path == ds.path }) {
69+ found.append(ds)
70+ }
71+ }
72+ }
73+ return found.sorted { $0.name < $1.name }
74+ }
75+}
added ForgeStudio/Models/Dataset.swift +74 −0
@@ -0,0 +1,74 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// A prepared dataset folder: train.bin/val.bin (llm.c-style header
4+// {magic 20240520, version, num_tokens} then uint16 tokens) + a forgebpe
5+// tokenizer model whose vocab size must match model.vocab_size.
6+import Foundation
7+
8+struct Dataset: Identifiable, Equatable {
9+ var id: String { path }
10+ var path: String
11+ var name: String
12+ var trainTokens: Int?
13+ var valTokens: Int?
14+ var vocabSize: Int?
15+ var sizeOnDisk: Int64
16+
17+ static let binMagic: Int32 = 20_240_520
18+
19+ // num_tokens lives at int32 offset 2 of the 256-int32 header.
20+ static func tokenCount(binURL: URL) -> Int? {
21+ guard let fh = try? FileHandle(forReadingFrom: binURL),
22+ let data = try? fh.read(upToCount: 12), data.count == 12 else {
23+ return nil
24+ }
25+ try? fh.close()
26+ let ints = data.withUnsafeBytes { $0.load(fromByteOffset: 0, as: (Int32, Int32, Int32).self) }
27+ guard ints.0 == binMagic else { return nil }
28+ return Int(ints.2)
29+ }
30+
31+ // forgebpe v1 header: line 1 "forgebpe v1", line 2 vocab size.
32+ static func vocabSize(tokenizerURL: URL) -> Int? {
33+ guard let fh = try? FileHandle(forReadingFrom: tokenizerURL),
34+ let data = try? fh.read(upToCount: 64),
35+ let head = String(data: data, encoding: .utf8) else { return nil }
36+ try? fh.close()
37+ let lines = head.split(separator: "\n", maxSplits: 2)
38+ guard lines.count >= 2, lines[0].hasPrefix("forgebpe") else { return nil }
39+ return Int(lines[1].trimmingCharacters(in: .whitespaces))
40+ }
41+
42+ static func scan(directory: URL) -> Dataset? {
43+ let fm = FileManager.default
44+ let train = directory.appendingPathComponent("train.bin")
45+ guard fm.fileExists(atPath: train.path) else { return nil }
46+ let val = directory.appendingPathComponent("val.bin")
47+ let tok = (try? fm.contentsOfDirectory(at: directory,
48+ includingPropertiesForKeys: nil))?
49+ .first { $0.pathExtension == "model" }
50+ var size: Int64 = 0
51+ if let items = try? fm.contentsOfDirectory(at: directory,
52+ includingPropertiesForKeys: [.fileSizeKey]) {
53+ for f in items {
54+ size += Int64((try? f.resourceValues(forKeys: [.fileSizeKey]).fileSize) ?? 0)
55+ }
56+ }
57+ return Dataset(
58+ path: directory.path,
59+ name: directory.lastPathComponent,
60+ trainTokens: tokenCount(binURL: train),
61+ valTokens: fm.fileExists(atPath: val.path) ? tokenCount(binURL: val) : nil,
62+ vocabSize: tok.flatMap { vocabSize(tokenizerURL: $0) },
63+ sizeOnDisk: size)
64+ }
65+}
66+
67+struct Checkpoint: Identifiable, Equatable {
68+ var id: String { path }
69+ var path: String
70+ var step: Int
71+ var sizeBytes: Int64
72+ var modifiedAt: Date
73+ var valLossAtStep: Double?
74+}
added ForgeStudio/Models/ForgeConfig.swift +295 −0
@@ -0,0 +1,295 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Codable mirror of Forge's JSON config (src/nn/config.h, RESEARCH.md §2).
4+// Field names are byte-compatible with the C++ parser; defaults match the
5+// C++ defaults so a partially-specified JSON round-trips identically.
6+import Foundation
7+
8+struct ModelConfig: Codable, Equatable {
9+ var name = "model"
10+ var nLayers = 6
11+ var dModel = 384
12+ var nHeads = 6
13+ var nKvHeads = 6
14+ var dFf = 1024
15+ var vocabSize = 4096
16+ var contextLength = 512
17+ var tiedEmbeddings = true
18+ var useRope = true
19+ var ropeTheta = 10000.0
20+ var norm = "rmsnorm" // rmsnorm | layernorm
21+ var normEps = 1e-6
22+ var activation = "swiglu" // swiglu | gelu | relu2
23+ var dropout = 0.0
24+ var quant = "none" // none | int8 | ternary
25+ var qkNorm = false
26+ var finalSoftcap = 0.0
27+ var scaleEmbeddings = false
28+ var attentionBias = false
29+ var headDimOverride = 0 // JSON key "head_dim"; 0 = d_model/n_heads
30+ var nopeEvery = 0
31+ var normPlacement = "pre" // pre | post | sandwich
32+ var ropeScaleFactor = 0.0
33+ var ropeScaleLow = 1.0
34+ var ropeScaleHigh = 4.0
35+ var ropeScaleOrigCtx = 8192
36+ var slidingWindow = 0
37+ var slidingGlobalEvery = 0
38+ var ropeThetaGlobal = 0.0
39+ var attnSoftcap = 0.0
40+ var nExperts = 0
41+ var moeTopK = 2
42+ var moeAuxWeight = 0.01
43+ var nSharedExperts = 0
44+ var moeScoring = "softmax" // softmax | sigmoid
45+ var moeNormTopk = true
46+ var routedScalingFactor = 1.0
47+ var moeDFf = 0
48+ var firstKDense = 0
49+ var moeBiasGamma = 0.0
50+
51+ enum CodingKeys: String, CodingKey {
52+ case name
53+ case nLayers = "n_layers", dModel = "d_model", nHeads = "n_heads"
54+ case nKvHeads = "n_kv_heads", dFf = "d_ff", vocabSize = "vocab_size"
55+ case contextLength = "context_length", tiedEmbeddings = "tied_embeddings"
56+ case useRope = "use_rope", ropeTheta = "rope_theta", norm
57+ case normEps = "norm_eps", activation, dropout, quant
58+ case qkNorm = "qk_norm", finalSoftcap = "final_softcap"
59+ case scaleEmbeddings = "scale_embeddings", attentionBias = "attention_bias"
60+ case headDimOverride = "head_dim", nopeEvery = "nope_every"
61+ case normPlacement = "norm_placement"
62+ case ropeScaleFactor = "rope_scale_factor", ropeScaleLow = "rope_scale_low"
63+ case ropeScaleHigh = "rope_scale_high", ropeScaleOrigCtx = "rope_scale_orig_ctx"
64+ case slidingWindow = "sliding_window"
65+ case slidingGlobalEvery = "sliding_global_every"
66+ case ropeThetaGlobal = "rope_theta_global", attnSoftcap = "attn_softcap"
67+ case nExperts = "n_experts", moeTopK = "moe_top_k"
68+ case moeAuxWeight = "moe_aux_weight", nSharedExperts = "n_shared_experts"
69+ case moeScoring = "moe_scoring", moeNormTopk = "moe_norm_topk"
70+ case routedScalingFactor = "routed_scaling_factor", moeDFf = "moe_d_ff"
71+ case firstKDense = "first_k_dense", moeBiasGamma = "moe_bias_gamma"
72+ }
73+
74+ // Forge tolerates missing keys everywhere — mirror that.
75+ init() {}
76+ init(from decoder: Decoder) throws {
77+ let c = try decoder.container(keyedBy: CodingKeys.self)
78+ func g<T: Decodable>(_ k: CodingKeys, _ d: T) -> T {
79+ (try? c.decodeIfPresent(T.self, forKey: k)) as? T ?? d
80+ }
81+ name = g(.name, name); nLayers = g(.nLayers, nLayers)
82+ dModel = g(.dModel, dModel); nHeads = g(.nHeads, nHeads)
83+ nKvHeads = g(.nKvHeads, nHeads); dFf = g(.dFf, dFf)
84+ vocabSize = g(.vocabSize, vocabSize)
85+ contextLength = g(.contextLength, contextLength)
86+ tiedEmbeddings = g(.tiedEmbeddings, tiedEmbeddings)
87+ useRope = g(.useRope, useRope); ropeTheta = g(.ropeTheta, ropeTheta)
88+ norm = g(.norm, norm); normEps = g(.normEps, normEps)
89+ activation = g(.activation, activation); dropout = g(.dropout, dropout)
90+ quant = g(.quant, quant); qkNorm = g(.qkNorm, qkNorm)
91+ finalSoftcap = g(.finalSoftcap, finalSoftcap)
92+ scaleEmbeddings = g(.scaleEmbeddings, scaleEmbeddings)
93+ attentionBias = g(.attentionBias, attentionBias)
94+ headDimOverride = g(.headDimOverride, headDimOverride)
95+ nopeEvery = g(.nopeEvery, nopeEvery)
96+ normPlacement = g(.normPlacement, normPlacement)
97+ ropeScaleFactor = g(.ropeScaleFactor, ropeScaleFactor)
98+ ropeScaleLow = g(.ropeScaleLow, ropeScaleLow)
99+ ropeScaleHigh = g(.ropeScaleHigh, ropeScaleHigh)
100+ ropeScaleOrigCtx = g(.ropeScaleOrigCtx, ropeScaleOrigCtx)
101+ slidingWindow = g(.slidingWindow, slidingWindow)
102+ slidingGlobalEvery = g(.slidingGlobalEvery, slidingGlobalEvery)
103+ ropeThetaGlobal = g(.ropeThetaGlobal, ropeThetaGlobal)
104+ attnSoftcap = g(.attnSoftcap, attnSoftcap)
105+ nExperts = g(.nExperts, nExperts); moeTopK = g(.moeTopK, moeTopK)
106+ moeAuxWeight = g(.moeAuxWeight, moeAuxWeight)
107+ nSharedExperts = g(.nSharedExperts, nSharedExperts)
108+ moeScoring = g(.moeScoring, moeScoring)
109+ moeNormTopk = g(.moeNormTopk, moeNormTopk)
110+ routedScalingFactor = g(.routedScalingFactor, routedScalingFactor)
111+ moeDFf = g(.moeDFf, moeDFf); firstKDense = g(.firstKDense, firstKDense)
112+ moeBiasGamma = g(.moeBiasGamma, moeBiasGamma)
113+ }
114+
115+ var headDim: Int { headDimOverride > 0 ? headDimOverride : dModel / max(nHeads, 1) }
116+
117+ // Same formula as ModelConfig::num_params() — cross-checked by
118+ // ParamCountTests against `forge info`.
119+ var paramCount: Int {
120+ let hd = headDim
121+ var attn = dModel * nHeads * hd + 2 * dModel * nKvHeads * hd
122+ + nHeads * hd * dModel
123+ if attentionBias { attn += (nHeads + 2 * nKvHeads) * hd }
124+ let actMats = activation == "swiglu" ? 3 : 2
125+ let mlpDense = actMats * dModel * dFf
126+ let expertDff = (nExperts > 0 && moeDFf > 0) ? moeDFf : dFf
127+ let mlpMoe = (nExperts + nSharedExperts) * actMats * dModel * expertDff
128+ + nExperts * dModel
129+ let nMoeLayers = nExperts > 0 ? nLayers - min(firstKDense, nLayers) : 0
130+ let mlpTotal = nMoeLayers * mlpMoe + (nLayers - nMoeLayers) * mlpDense
131+ let normsPerLayer = normPlacement == "sandwich" ? 4 : 2
132+ var norms = (norm == "layernorm" ? 2 : 1) * dModel
133+ * (normsPerLayer * nLayers + 1)
134+ if qkNorm { norms += 2 * hd * nLayers }
135+ var total = nLayers * attn + mlpTotal + norms + vocabSize * dModel
136+ if !tiedEmbeddings { total += vocabSize * dModel }
137+ if !useRope { total += contextLength * dModel }
138+ return total
139+ }
140+
141+ // Mirrors the C++ parse-time validation; returns human-actionable errors.
142+ var validationErrors: [String] {
143+ var e: [String] = []
144+ if headDimOverride == 0 && nHeads > 0 && dModel % nHeads != 0 {
145+ e.append("d_model doit être divisible par n_heads (ou fixer head_dim)")
146+ }
147+ if nKvHeads > 0 && nHeads % nKvHeads != 0 {
148+ e.append("n_heads doit être divisible par n_kv_heads")
149+ }
150+ if headDim % 2 != 0 { e.append("head_dim doit être pair (paires RoPE)") }
151+ if !["rmsnorm", "layernorm"].contains(norm) { e.append("norm invalide") }
152+ if !["swiglu", "gelu", "relu2"].contains(activation) {
153+ e.append("activation invalide")
154+ }
155+ if !["pre", "post", "sandwich"].contains(normPlacement) {
156+ e.append("norm_placement invalide")
157+ }
158+ if !["none", "int8", "ternary"].contains(quant) { e.append("quant invalide") }
159+ if nExperts > 0 && !(1...nExperts).contains(moeTopK) {
160+ e.append("moe_top_k doit être dans [1, n_experts]")
161+ }
162+ if nSharedExperts > 0 && nExperts == 0 {
163+ e.append("n_shared_experts requiert n_experts > 0")
164+ }
165+ if firstKDense < 0 || firstKDense > nLayers {
166+ e.append("first_k_dense doit être dans [0, n_layers]")
167+ }
168+ for (v, n) in [(nLayers, "n_layers"), (dModel, "d_model"), (nHeads, "n_heads"),
169+ (dFf, "d_ff"), (vocabSize, "vocab_size"),
170+ (contextLength, "context_length")] where v <= 0 {
171+ e.append("\(n) doit être > 0")
172+ }
173+ return e
174+ }
175+}
176+
177+struct TrainConfig: Codable, Equatable {
178+ var lr = 6e-4
179+ var minLrRatio = 0.1
180+ var warmupSteps = 2000
181+ var maxSteps = 100_000
182+ var schedule = "cosine" // cosine | wsd
183+ var wsdDecayFrac = 0.15
184+ var optimizer = "adamw" // adamw | muon
185+ var muonLr = 0.02
186+ var muonMomentum = 0.95
187+ var beta1 = 0.9
188+ var beta2 = 0.95
189+ var eps = 1e-8
190+ var weightDecay = 0.1
191+ var gradClip = 1.0
192+ var batchSize = 32
193+ var gradAccumSteps = 1
194+ var precision = "f32"
195+ var checkpointEvery = 1000
196+ var forgeSave = true
197+ var forgeDtype = "f32"
198+ var evalEvery = 500
199+ var evalBatches = 20
200+ var seed = 1337
201+ var deterministic = false
202+
203+ enum CodingKeys: String, CodingKey {
204+ case lr, minLrRatio = "min_lr_ratio", warmupSteps = "warmup_steps"
205+ case maxSteps = "max_steps", schedule, wsdDecayFrac = "wsd_decay_frac"
206+ case optimizer, muonLr = "muon_lr", muonMomentum = "muon_momentum"
207+ case beta1, beta2, eps, weightDecay = "weight_decay"
208+ case gradClip = "grad_clip", batchSize = "batch_size"
209+ case gradAccumSteps = "grad_accum_steps", precision
210+ case checkpointEvery = "checkpoint_every", forgeSave = "forge_save"
211+ case forgeDtype = "forge_dtype", evalEvery = "eval_every"
212+ case evalBatches = "eval_batches", seed, deterministic
213+ }
214+
215+ init() {}
216+ init(from decoder: Decoder) throws {
217+ let c = try decoder.container(keyedBy: CodingKeys.self)
218+ func g<T: Decodable>(_ k: CodingKeys, _ d: T) -> T {
219+ (try? c.decodeIfPresent(T.self, forKey: k)) as? T ?? d
220+ }
221+ lr = g(.lr, lr); minLrRatio = g(.minLrRatio, minLrRatio)
222+ warmupSteps = g(.warmupSteps, warmupSteps); maxSteps = g(.maxSteps, maxSteps)
223+ schedule = g(.schedule, schedule)
224+ wsdDecayFrac = g(.wsdDecayFrac, wsdDecayFrac)
225+ optimizer = g(.optimizer, optimizer); muonLr = g(.muonLr, muonLr)
226+ muonMomentum = g(.muonMomentum, muonMomentum)
227+ beta1 = g(.beta1, beta1); beta2 = g(.beta2, beta2); eps = g(.eps, eps)
228+ weightDecay = g(.weightDecay, weightDecay); gradClip = g(.gradClip, gradClip)
229+ batchSize = g(.batchSize, batchSize)
230+ gradAccumSteps = g(.gradAccumSteps, gradAccumSteps)
231+ precision = g(.precision, precision)
232+ checkpointEvery = g(.checkpointEvery, checkpointEvery)
233+ forgeSave = g(.forgeSave, forgeSave); forgeDtype = g(.forgeDtype, forgeDtype)
234+ evalEvery = g(.evalEvery, evalEvery); evalBatches = g(.evalBatches, evalBatches)
235+ seed = g(.seed, seed); deterministic = g(.deterministic, deterministic)
236+ }
237+
238+ var validationErrors: [String] {
239+ var e: [String] = []
240+ if lr <= 0 { e.append("lr doit être > 0") }
241+ if warmupSteps > maxSteps { e.append("warmup_steps ≤ max_steps requis") }
242+ if !["cosine", "wsd"].contains(schedule) { e.append("schedule invalide") }
243+ if !["adamw", "muon"].contains(optimizer) { e.append("optimizer invalide") }
244+ if !(0.0..<1.0).contains(wsdDecayFrac) || wsdDecayFrac <= 0 {
245+ e.append("wsd_decay_frac doit être dans (0, 1)")
246+ }
247+ if !["f32", "f16", "bf16"].contains(forgeDtype) {
248+ e.append("forge_dtype invalide")
249+ }
250+ if batchSize <= 0 || gradAccumSteps <= 0 || maxSteps <= 0 {
251+ e.append("batch/accum/max_steps doivent être > 0")
252+ }
253+ return e
254+ }
255+
256+ // LR schedule preview (same math as src/train/scheduler.h).
257+ func lrAt(step: Int) -> Double {
258+ let minLr = lr * minLrRatio
259+ if step < warmupSteps {
260+ return lr * Double(step + 1) / Double(warmupSteps + 1)
261+ }
262+ if schedule == "wsd" {
263+ let decaySteps = max(1, Int(Double(maxSteps) * wsdDecayFrac))
264+ let decayStart = maxSteps - decaySteps
265+ if step < decayStart { return lr }
266+ if step >= maxSteps { return minLr }
267+ let ratio = Double(step - decayStart) / Double(decaySteps)
268+ return minLr + (lr - minLr) * (1.0 - ratio.squareRoot())
269+ }
270+ if step >= maxSteps { return minLr }
271+ let ratio = Double(step - warmupSteps) / Double(maxSteps - warmupSteps)
272+ return minLr + 0.5 * (1.0 + cos(.pi * ratio)) * (lr - minLr)
273+ }
274+}
275+
276+struct ForgeConfig: Codable, Equatable {
277+ var model = ModelConfig()
278+ var train = TrainConfig()
279+
280+ var tokensPerStep: Int { train.batchSize * model.contextLength * train.gradAccumSteps }
281+ var totalTokens: Int { tokensPerStep * train.maxSteps }
282+ var validationErrors: [String] {
283+ model.validationErrors + train.validationErrors
284+ }
285+
286+ static func load(from url: URL) throws -> ForgeConfig {
287+ try JSONDecoder().decode(ForgeConfig.self, from: Data(contentsOf: url))
288+ }
289+
290+ func exportJSON() throws -> Data {
291+ let enc = JSONEncoder()
292+ enc.outputFormatting = [.prettyPrinted, .sortedKeys]
293+ return try enc.encode(self)
294+ }
295+}
added ForgeStudio/Models/MetricPoint.swift +18 −0
@@ -0,0 +1,18 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// One row of log.csv (RESEARCH.md §3). valLoss is nil when the CSV holds
4+// the -1 sentinel; elapsedS is nil for pre-elapsed_s runs (6-column header).
5+import Foundation
6+
7+struct MetricPoint: Equatable, Sendable {
8+ var step: Int
9+ var trainLoss: Double
10+ var lr: Double
11+ var gradNorm: Double
12+ var tokensPerSec: Double
13+ var valLoss: Double?
14+ var elapsedS: Double?
15+
16+ var tokensSeen: (Int) -> Int { { tokensPerStep in (step + 1) * tokensPerStep } }
17+ var perplexity: Double { exp(trainLoss) }
18+}
added ForgeStudio/Models/Run.swift +53 −0
@@ -0,0 +1,53 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// A training run: identity, config, directories, and the state machine
4+// (RunSupervisor is the only mutator; every transition is persisted
5+// atomically by RunStore).
6+import Foundation
7+
8+enum RunState: String, Codable, CaseIterable {
9+ case queued, launching, running, finishing, finished, failed, stopped
10+
11+ var isActive: Bool {
12+ switch self {
13+ case .launching, .running, .finishing: return true
14+ default: return false
15+ }
16+ }
17+
18+ // Legal transitions — RunSupervisor refuses anything else.
19+ static let transitions: [RunState: Set<RunState>] = [
20+ .queued: [.launching, .stopped],
21+ .launching: [.running, .failed, .stopped],
22+ .running: [.finishing, .finished, .failed, .stopped],
23+ .finishing: [.finished, .failed, .stopped],
24+ .finished: [], .failed: [], .stopped: [],
25+ ]
26+}
27+
28+struct Run: Codable, Identifiable, Equatable {
29+ var id: UUID = UUID()
30+ var name: String
31+ var createdAt: Date
32+ var state: RunState = .queued
33+ var config: ForgeConfig
34+ var datasetPath: String
35+ var outDirectory: String // <workspace>/runs/<name>-<timestamp>
36+ var resumeCheckpoint: String? // forge train --resume
37+ var pid: Int32? // live forge process (crash recovery)
38+ var lastStep: Int?
39+ var lastTrainLoss: Double?
40+ var bestValLoss: Double?
41+ var bestValStep: Int?
42+ var exitCode: Int32?
43+ var failureReason: String?
44+
45+ var logCSVPath: String { outDirectory + "/log.csv" }
46+ var runLogPath: String { outDirectory + "/run.log" }
47+ var configPath: String { outDirectory + "/config.json" }
48+
49+ var progress: Double {
50+ guard let step = lastStep, config.train.maxSteps > 0 else { return 0 }
51+ return min(1.0, Double(step + 1) / Double(config.train.maxSteps))
52+ }
53+}
added ForgeStudio/Services/ForgeBinaryLocator.swift +66 −0
@@ -0,0 +1,66 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Finds and validates the forge binary: a candidate is accepted only if
4+// `forge info` runs and reports a device — the same probe surfaces the GPU
5+// name for the header. Paths persist in UserDefaults.
6+import Foundation
7+
8+struct ForgeValidation: Equatable, Sendable {
9+ var version: String // device line, e.g. "Apple M5 Max"
10+ var binaryPath: String
11+}
12+
13+enum ForgeBinaryLocator {
14+ static let defaultsKey = "forge.binary.path"
15+ static let workspaceKey = "forge.workspace.path"
16+
17+ static var savedBinaryURL: URL? {
18+ UserDefaults.standard.string(forKey: defaultsKey).map { URL(fileURLWithPath: $0) }
19+ }
20+
21+ static var savedWorkspaceURL: URL? {
22+ UserDefaults.standard.string(forKey: workspaceKey).map { URL(fileURLWithPath: $0) }
23+ }
24+
25+ static func save(binary: URL) {
26+ UserDefaults.standard.set(binary.path, forKey: defaultsKey)
27+ }
28+
29+ static func save(workspace: URL) {
30+ UserDefaults.standard.set(workspace.path, forKey: workspaceKey)
31+ }
32+
33+ /// Candidate locations, most specific first.
34+ static func candidates() -> [URL] {
35+ var urls: [URL] = []
36+ if let saved = savedBinaryURL { urls.append(saved) }
37+ let home = FileManager.default.homeDirectoryForCurrentUser
38+ urls.append(home.appendingPathComponent("Desktop/forge/build/forge"))
39+ urls.append(URL(fileURLWithPath: "/usr/local/bin/forge"))
40+ return urls.filter { FileManager.default.isExecutableFile(atPath: $0.path) }
41+ }
42+
43+ /// Runs `forge info` and parses the device line.
44+ static func validate(binary: URL) async -> Result<ForgeValidation, Error> {
45+ let runner = ProcessRunner()
46+ do {
47+ let (lines, exit) = try await runner.launch(
48+ executable: binary, arguments: ["info"],
49+ currentDirectory: binary.deletingLastPathComponent())
50+ var device = ""
51+ for await (line, _) in lines where line.hasPrefix("device: ") {
52+ device = String(line.dropFirst("device: ".count))
53+ }
54+ let status = await exit.value
55+ guard status.code == 0, !device.isEmpty else {
56+ throw NSError(domain: "ForgeStudio", code: 1, userInfo: [
57+ NSLocalizedDescriptionKey:
58+ "forge info a échoué (code \(status.code)). Vérifiez que forge.metallib est à côté du binaire.",
59+ ])
60+ }
61+ return .success(ForgeValidation(version: device, binaryPath: binary.path))
62+ } catch {
63+ return .failure(error)
64+ }
65+ }
66+}
added ForgeStudio/Services/LogParser.swift +85 −0
@@ -0,0 +1,85 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Parsers for Forge's two output channels (RESEARCH.md §3):
4+// - log.csv: header-driven, the structured metrics source of truth.
5+// Handles both the 7-column (elapsed_s) and legacy 6-column layouts.
6+// - stdout: events the CSV doesn't carry (checkpoint saved, fmodel commit,
7+// run banner), parsed defensively — garbage lines are ignored, never fatal.
8+import Foundation
9+
10+struct LogParser {
11+ // ---- log.csv --------------------------------------------------------
12+
13+ struct CSVSchema: Equatable {
14+ var columns: [String]
15+ static let current = CSVSchema(columns: [
16+ "step", "loss", "lr", "grad_norm", "tokens_per_sec", "val_loss",
17+ "elapsed_s",
18+ ])
19+ }
20+
21+ private(set) var schema: CSVSchema?
22+
23+ /// Feed one CSV line (header or data). Returns a point for data lines.
24+ mutating func parseCSVLine(_ line: String) -> MetricPoint? {
25+ let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
26+ guard !trimmed.isEmpty else { return nil }
27+ if trimmed.hasPrefix("step,") {
28+ schema = CSVSchema(columns: trimmed.split(separator: ",").map(String.init))
29+ return nil
30+ }
31+ let cols = schema?.columns ?? CSVSchema.current.columns
32+ let parts = trimmed.split(separator: ",", omittingEmptySubsequences: false)
33+ guard parts.count >= 5 else { return nil }
34+ func f(_ name: String) -> Double? {
35+ guard let i = cols.firstIndex(of: name), i < parts.count else { return nil }
36+ return Double(parts[i])
37+ }
38+ guard let step = f("step").map({ Int($0) }),
39+ let loss = f("loss") else { return nil }
40+ let val = f("val_loss")
41+ return MetricPoint(
42+ step: step,
43+ trainLoss: loss,
44+ lr: f("lr") ?? 0,
45+ gradNorm: f("grad_norm") ?? 0,
46+ tokensPerSec: f("tokens_per_sec") ?? 0,
47+ valLoss: (val ?? -1) >= 0 ? val : nil,
48+ elapsedS: f("elapsed_s"))
49+ }
50+
51+ // ---- stdout events ---------------------------------------------------
52+
53+ enum StdoutEvent: Equatable {
54+ case banner(params: Int, steps: Int, tokensPerStep: Int, backend: String)
55+ case checkpointSaved(path: String)
56+ case forgeCommit(manifest: String)
57+ }
58+
59+ static func parseStdout(_ line: String) -> StdoutEvent? {
60+ if line.hasPrefix("checkpoint saved: ") {
61+ return .checkpointSaved(path: String(line.dropFirst("checkpoint saved: ".count)))
62+ }
63+ if line.hasPrefix("fmodel: ") {
64+ let rest = line.dropFirst("fmodel: ".count)
65+ let manifest = rest.split(separator: " ").first.map(String.init) ?? ""
66+ return .forgeCommit(manifest: manifest)
67+ }
68+ if line.hasPrefix("training ") {
69+ // "training <name>: <p> params, <s> steps, <t> tokens/step, backend=<b>…"
70+ // The model name may contain digits — only parse after the colon.
71+ guard let colon = line.range(of: ": ") else { return nil }
72+ let tail = line[colon.upperBound...]
73+ let numbers = tail.split(whereSeparator: { !"0123456789".contains($0) })
74+ .compactMap { Int($0) }
75+ let backend = line.range(of: "backend=").map {
76+ String(line[$0.upperBound...].prefix(while: { $0 != "," }))
77+ }
78+ if numbers.count >= 3 {
79+ return .banner(params: numbers[0], steps: numbers[1],
80+ tokensPerStep: numbers[2], backend: backend ?? "?")
81+ }
82+ }
83+ return nil
84+ }
85+}
added ForgeStudio/Services/MetricsStore.swift +80 −0
@@ -0,0 +1,80 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Per-run time series. Append-only (raw data is never thrown away); the UI
4+// asks for downsampled snapshots sized to the chart's pixel width. An actor
5+// so live ingest and UI reads never race.
6+import Foundation
7+
8+actor MetricsStore {
9+ private(set) var points: [MetricPoint] = []
10+ private var parser = LogParser()
11+ private var csvOffset: UInt64 = 0
12+
13+ struct Snapshot: Sendable {
14+ var train: [Downsampler.XY]
15+ var trainEMA: [Downsampler.XY]
16+ var val: [Downsampler.XY]
17+ var lr: [Downsampler.XY]
18+ var tokensPerSec: [Downsampler.XY]
19+ var gradNorm: [Downsampler.XY]
20+ var lastPoint: MetricPoint?
21+ var bestVal: (step: Int, loss: Double)?
22+ var count: Int
23+ }
24+
25+ func append(_ p: MetricPoint) { points.append(p) }
26+
27+ func reset() {
28+ points.removeAll()
29+ parser = LogParser()
30+ csvOffset = 0
31+ }
32+
33+ /// Incremental tail of log.csv: reads only bytes past the last offset,
34+ /// so polling during a live run costs O(new lines).
35+ func ingestCSV(at url: URL) {
36+ guard let fh = try? FileHandle(forReadingFrom: url) else { return }
37+ defer { try? fh.close() }
38+ try? fh.seek(toOffset: csvOffset)
39+ guard let data = try? fh.readToEnd(), !data.isEmpty else { return }
40+ // Only consume complete lines; leave a partial tail for next poll.
41+ var consumable = data
42+ if let lastNL = data.lastIndex(of: 0x0A) {
43+ consumable = data[data.startIndex...lastNL]
44+ } else {
45+ return
46+ }
47+ csvOffset += UInt64(consumable.count)
48+ guard let text = String(data: consumable, encoding: .utf8) else { return }
49+ for line in text.split(separator: "\n") {
50+ if let p = parser.parseCSVLine(String(line)) { points.append(p) }
51+ }
52+ }
53+
54+ func snapshot(maxPoints: Int, smoothing: Double) -> Snapshot {
55+ func series(_ f: (MetricPoint) -> Double?) -> [Downsampler.XY] {
56+ points.compactMap { p in f(p).map { .init(x: Double(p.step), y: $0) } }
57+ }
58+ let train = series { $0.trainLoss }
59+ let emaValues = Smoothing.ema(train.map(\.y), smoothing: smoothing)
60+ let ema = zip(train, emaValues).map { Downsampler.XY(x: $0.x, y: $1) }
61+ let val = series { $0.valLoss }
62+ var best: (Int, Double)?
63+ for p in points {
64+ if let v = p.valLoss, v.isFinite, best == nil || v < best!.1 {
65+ best = (p.step, v)
66+ }
67+ }
68+ func ds(_ s: [Downsampler.XY]) -> [Downsampler.XY] {
69+ Downsampler.lttb(s, threshold: maxPoints)
70+ }
71+ return Snapshot(
72+ train: ds(train), trainEMA: ds(ema), val: val, // val is sparse: keep raw
73+ lr: ds(series { $0.lr }),
74+ tokensPerSec: ds(series { $0.tokensPerSec }),
75+ gradNorm: ds(series { $0.gradNorm }),
76+ lastPoint: points.last,
77+ bestVal: best,
78+ count: points.count)
79+ }
80+}
added ForgeStudio/Services/ProcessRunner.swift +111 −0
@@ -0,0 +1,111 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Actor wrapping Foundation.Process: launch, stream stdout/stderr line by
4+// line (partial lines buffered, never lost), signal, await exit. All
5+// consumers get lines through AsyncStream — nothing ever touches the main
6+// thread.
7+import Foundation
8+
9+actor ProcessRunner {
10+ struct Exit: Sendable {
11+ let code: Int32
12+ let wasSignaled: Bool
13+ }
14+
15+ enum RunnerError: LocalizedError {
16+ case notRunning
17+ case launchFailed(String)
18+ var errorDescription: String? {
19+ switch self {
20+ case .notRunning: return "Le processus n'est pas en cours d'exécution."
21+ case .launchFailed(let why): return "Échec du lancement : \(why)"
22+ }
23+ }
24+ }
25+
26+ private var process: Process?
27+
28+ var pid: Int32? { process?.processIdentifier }
29+ var isRunning: Bool { process?.isRunning ?? false }
30+
31+ /// Launches `executable args`, returning a line stream (stdout+stderr
32+ /// merged, tagged) and a task that resolves with the exit status.
33+ func launch(executable: URL, arguments: [String],
34+ currentDirectory: URL? = nil,
35+ environment: [String: String]? = nil)
36+ throws -> (lines: AsyncStream<(line: String, isStderr: Bool)>,
37+ exit: Task<Exit, Never>)
38+ {
39+ let p = Process()
40+ p.executableURL = executable
41+ p.arguments = arguments
42+ if let cwd = currentDirectory { p.currentDirectoryURL = cwd }
43+ if let env = environment {
44+ p.environment = ProcessInfo.processInfo.environment.merging(env) { $1 }
45+ }
46+ let outPipe = Pipe(), errPipe = Pipe()
47+ p.standardOutput = outPipe
48+ p.standardError = errPipe
49+
50+ var continuation: AsyncStream<(line: String, isStderr: Bool)>.Continuation!
51+ let stream = AsyncStream<(line: String, isStderr: Bool)> { continuation = $0 }
52+ let cont = continuation!
53+
54+ // Two readers feeding one stream; a small actor-free state via
55+ // DispatchQueue keeps partial-line buffers private per pipe.
56+ let group = DispatchGroup()
57+ for (pipe, isErr) in [(outPipe, false), (errPipe, true)] {
58+ group.enter()
59+ let handle = pipe.fileHandleForReading
60+ DispatchQueue.global(qos: .userInitiated).async {
61+ var buffer = Data()
62+ while true {
63+ let chunk = handle.availableData
64+ if chunk.isEmpty { break } // EOF
65+ buffer.append(chunk)
66+ while let nl = buffer.firstIndex(of: 0x0A) {
67+ let lineData = buffer[buffer.startIndex..<nl]
68+ buffer.removeSubrange(buffer.startIndex...nl)
69+ if let line = String(data: lineData, encoding: .utf8) {
70+ cont.yield((line, isErr))
71+ }
72+ }
73+ }
74+ if !buffer.isEmpty, let tail = String(data: buffer, encoding: .utf8) {
75+ cont.yield((tail, isErr)) // final unterminated line
76+ }
77+ group.leave()
78+ }
79+ }
80+
81+ do { try p.run() } catch {
82+ cont.finish()
83+ throw RunnerError.launchFailed(error.localizedDescription)
84+ }
85+ process = p
86+
87+ let exitTask = Task<Exit, Never> {
88+ await withCheckedContinuation { (k: CheckedContinuation<Void, Never>) in
89+ group.notify(queue: .global()) { k.resume() }
90+ }
91+ p.waitUntilExit()
92+ cont.finish()
93+ return Exit(code: p.terminationStatus,
94+ wasSignaled: p.terminationReason == .uncaughtSignal)
95+ }
96+ return (stream, exitTask)
97+ }
98+
99+ /// SIGTERM (forge has no SIGINT handler — see RESEARCH.md §5: the
100+ /// process dies without a final checkpoint; recovery = ckpt_latest.bin).
101+ func terminate() throws {
102+ guard let p = process, p.isRunning else { throw RunnerError.notRunning }
103+ p.terminate()
104+ }
105+
106+ /// Escalation of last resort; the caller confirms with the user first.
107+ func kill() throws {
108+ guard let p = process, p.isRunning else { throw RunnerError.notRunning }
109+ Darwin.kill(p.processIdentifier, SIGKILL)
110+ }
111+}
added ForgeStudio/Services/RunStore.swift +60 −0
@@ -0,0 +1,60 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Run registry with atomic persistence: every mutation writes
4+// runs.json.tmp then renames — the app survives kill -9 at any moment with
5+// either the old or the new registry, never a torn one.
6+import Foundation
7+
8+@Observable
9+final class RunStore {
10+ private(set) var runs: [Run] = []
11+ let workspaceURL: URL
12+ private var registryURL: URL { workspaceURL.appendingPathComponent("runs.json") }
13+
14+ init(workspace: URL) {
15+ workspaceURL = workspace
16+ load()
17+ }
18+
19+ func load() {
20+ guard let data = try? Data(contentsOf: registryURL),
21+ let decoded = try? JSONDecoder().decode([Run].self, from: data) else {
22+ return
23+ }
24+ runs = decoded
25+ }
26+
27+ func upsert(_ run: Run) {
28+ if let i = runs.firstIndex(where: { $0.id == run.id }) {
29+ runs[i] = run
30+ } else {
31+ runs.append(run)
32+ }
33+ persist()
34+ }
35+
36+ func remove(_ run: Run) {
37+ runs.removeAll { $0.id == run.id }
38+ persist()
39+ }
40+
41+ private func persist() {
42+ do {
43+ let enc = JSONEncoder()
44+ enc.outputFormatting = [.prettyPrinted, .sortedKeys]
45+ enc.dateEncodingStrategy = .iso8601
46+ let data = try enc.encode(runs)
47+ let tmp = registryURL.appendingPathExtension("tmp")
48+ try FileManager.default
49+ .createDirectory(at: workspaceURL, withIntermediateDirectories: true)
50+ try data.write(to: tmp, options: .atomic)
51+ _ = try FileManager.default.replaceItemAt(registryURL, withItemAt: tmp)
52+ } catch {
53+ // Persistence failure must be visible, never silent: kept on the
54+ // store for the UI to surface.
55+ lastPersistError = error.localizedDescription
56+ }
57+ }
58+
59+ private(set) var lastPersistError: String?
60+}
added ForgeStudio/Services/RunSupervisor.swift +158 −0
@@ -0,0 +1,158 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Owns a live run end to end: builds the out directory, launches
4+// `forge train`, streams stdout/stderr to run.log + the console buffer,
5+// polls log.csv into the MetricsStore, and drives the Run state machine.
6+// Single-writer: all Run mutations flow through here and persist via
7+// RunStore immediately.
8+import Foundation
9+
10+@Observable
11+@MainActor
12+final class RunSupervisor {
13+ let store: RunStore
14+ let metrics = MetricsStore()
15+
16+ private(set) var activeRunID: UUID?
17+ private(set) var consoleLines: [String] = []
18+ private var runner: ProcessRunner?
19+ private var csvPoller: Task<Void, Never>?
20+
21+ init(store: RunStore) {
22+ self.store = store
23+ }
24+
25+ enum SupervisorError: LocalizedError {
26+ case busy, invalidConfig([String]), forgeNotConfigured
27+ var errorDescription: String? {
28+ switch self {
29+ case .busy:
30+ return "Un entraînement est déjà en cours — Forge Studio les exécute séquentiellement."
31+ case .invalidConfig(let errs):
32+ return "Config invalide : " + errs.joined(separator: " · ")
33+ case .forgeNotConfigured:
34+ return "Binaire forge non configuré (Réglages)."
35+ }
36+ }
37+ }
38+
39+ private func transition(_ run: inout Run, to next: RunState) {
40+ guard RunState.transitions[run.state]?.contains(next) == true else { return }
41+ run.state = next
42+ store.upsert(run)
43+ }
44+
45+ func start(config: ForgeConfig, datasetPath: String, name: String,
46+ resumeFrom: String? = nil) async throws {
47+ guard activeRunID == nil else { throw SupervisorError.busy }
48+ let errors = config.validationErrors
49+ guard errors.isEmpty else { throw SupervisorError.invalidConfig(errors) }
50+ guard let forge = ForgeBinaryLocator.savedBinaryURL else {
51+ throw SupervisorError.forgeNotConfigured
52+ }
53+
54+ let stamp = ISO8601DateFormatter().string(from: .now)
55+ .replacingOccurrences(of: ":", with: "-")
56+ let outDir = store.workspaceURL
57+ .appendingPathComponent("runs/\(name)-\(stamp)")
58+ try FileManager.default.createDirectory(at: outDir,
59+ withIntermediateDirectories: true)
60+ var run = Run(name: name, createdAt: .now, config: config,
61+ datasetPath: datasetPath, outDirectory: outDir.path,
62+ resumeCheckpoint: resumeFrom)
63+ try config.exportJSON().write(to: URL(fileURLWithPath: run.configPath))
64+ store.upsert(run)
65+
66+ var args = ["train", "--config", run.configPath, "--data", datasetPath,
67+ "--out", run.outDirectory]
68+ if let resume = resumeFrom { args += ["--resume", resume] }
69+
70+ transition(&run, to: .launching)
71+ activeRunID = run.id
72+ consoleLines.removeAll()
73+ await metrics.reset()
74+
75+ let processRunner = ProcessRunner()
76+ runner = processRunner
77+ let (lines, exit) = try await processRunner.launch(
78+ executable: forge, arguments: args,
79+ currentDirectory: forge.deletingLastPathComponent())
80+ run.pid = await processRunner.pid
81+ transition(&run, to: .running)
82+
83+ // Console + run.log + stdout events.
84+ let logURL = URL(fileURLWithPath: run.runLogPath)
85+ FileManager.default.createFile(atPath: logURL.path, contents: nil)
86+ let logHandle = try? FileHandle(forWritingTo: logURL)
87+ let runID = run.id
88+ Task { [weak self] in
89+ for await (line, isErr) in lines {
90+ logHandle?.write(Data((line + "\n").utf8))
91+ await MainActor.run {
92+ guard let self else { return }
93+ self.consoleLines.append(isErr ? "⚠︎ " + line : line)
94+ if self.consoleLines.count > 5000 {
95+ self.consoleLines.removeFirst(1000)
96+ }
97+ }
98+ }
99+ try? logHandle?.close()
100+ }
101+
102+ // CSV poller: 1 Hz incremental tail, updates run summary fields.
103+ let csvURL = URL(fileURLWithPath: run.logCSVPath)
104+ csvPoller = Task { [weak self] in
105+ while !Task.isCancelled {
106+ guard let self else { return }
107+ await self.metrics.ingestCSV(at: csvURL)
108+ let snap = await self.metrics.snapshot(maxPoints: 4, smoothing: 0)
109+ await MainActor.run {
110+ guard var r = self.store.runs.first(where: { $0.id == runID })
111+ else { return }
112+ if let last = snap.lastPoint {
113+ r.lastStep = last.step
114+ r.lastTrainLoss = last.trainLoss
115+ }
116+ if let best = snap.bestVal {
117+ r.bestValLoss = best.loss
118+ r.bestValStep = best.step
119+ }
120+ self.store.upsert(r)
121+ }
122+ try? await Task.sleep(for: .seconds(1))
123+ }
124+ }
125+
126+ // Exit watcher.
127+ Task { [weak self] in
128+ let status = await exit.value
129+ await MainActor.run {
130+ guard let self,
131+ var r = self.store.runs.first(where: { $0.id == runID })
132+ else { return }
133+ self.csvPoller?.cancel()
134+ r.pid = nil
135+ r.exitCode = status.code
136+ if status.code == 0 {
137+ self.transition(&r, to: .finished)
138+ } else if r.state == .finishing || status.wasSignaled {
139+ self.transition(&r, to: .stopped)
140+ } else {
141+ r.failureReason = "forge s'est terminé avec le code \(status.code) — voir run.log"
142+ self.transition(&r, to: .failed)
143+ }
144+ self.activeRunID = nil
145+ self.runner = nil
146+ }
147+ }
148+ }
149+
150+ /// SIGTERM. Forge has no signal handler: the process dies immediately and
151+ /// the last ckpt_latest.bin is the recovery point (UI says so).
152+ func stop() async {
153+ guard let id = activeRunID,
154+ var run = store.runs.first(where: { $0.id == id }) else { return }
155+ transition(&run, to: .finishing)
156+ try? await runner?.terminate()
157+ }
158+}
added ForgeStudio/Services/SystemInfo.swift +37 −0
@@ -0,0 +1,37 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Chip name, core count and unified memory via sysctl — feeds the memory
4+// estimate badge in the New Run form.
5+import Foundation
6+
7+enum SystemInfo {
8+ static func sysctlString(_ name: String) -> String? {
9+ var size = 0
10+ guard sysctlbyname(name, nil, &size, nil, 0) == 0, size > 0 else { return nil }
11+ var buf = [CChar](repeating: 0, count: size)
12+ guard sysctlbyname(name, &buf, &size, nil, 0) == 0 else { return nil }
13+ return String(cString: buf)
14+ }
15+
16+ static func sysctlInt(_ name: String) -> Int64? {
17+ var value: Int64 = 0
18+ var size = MemoryLayout<Int64>.size
19+ guard sysctlbyname(name, &value, &size, nil, 0) == 0 else { return nil }
20+ return value
21+ }
22+
23+ static var chipName: String { sysctlString("machdep.cpu.brand_string") ?? "Apple Silicon" }
24+ static var memoryBytes: Int64 { sysctlInt("hw.memsize") ?? 0 }
25+ static var cpuCores: Int { Int(sysctlInt("hw.ncpu") ?? 0) }
26+
27+ /// Rough training footprint: weights+grads+AdamW moments in f32 (4 copies
28+ /// of params × 4 bytes) + activation estimate per micro-batch.
29+ static func estimatedTrainingBytes(config: ForgeConfig) -> Int64 {
30+ let params = Int64(config.model.paramCount)
31+ let states = params * 4 * 4
32+ let actPerToken = Int64(config.model.nLayers * config.model.dModel * 24)
33+ let activations = actPerToken
34+ * Int64(config.train.batchSize * config.model.contextLength)
35+ return states + activations
36+ }
37+}
added ForgeStudio/Views/ContentView.swift +118 −0
@@ -0,0 +1,118 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Navigation shell: runs in the sidebar, live dashboard in the detail pane.
4+import SwiftUI
5+
6+struct ContentView: View {
7+ @Environment(AppModel.self) private var app
8+ @State private var selection: UUID?
9+ @State private var showNewRun = false
10+
11+ var body: some View {
12+ NavigationSplitView {
13+ List(selection: $selection) {
14+ Section("Runs") {
15+ ForEach(app.store.runs.sorted { $0.createdAt > $1.createdAt }) { run in
16+ RunRow(run: run).tag(run.id)
17+ }
18+ }
19+ }
20+ .navigationSplitViewColumnWidth(min: 220, ideal: 260)
21+ .toolbar {
22+ ToolbarItem(placement: .primaryAction) {
23+ Button {
24+ showNewRun = true
25+ } label: {
26+ Label("Nouveau run", systemImage: "plus")
27+ }
28+ .disabled(app.forgeError != nil)
29+ }
30+ }
31+ } detail: {
32+ if let id = selection,
33+ let run = app.store.runs.first(where: { $0.id == id }) {
34+ RunDetailView(run: run)
35+ } else {
36+ EmptyStateView()
37+ }
38+ }
39+ .sheet(isPresented: $showNewRun) {
40+ NewRunSheet()
41+ }
42+ }
43+}
44+
45+struct RunRow: View {
46+ let run: Run
47+
48+ var body: some View {
49+ VStack(alignment: .leading, spacing: 2) {
50+ HStack {
51+ Text(run.name).font(.headline)
52+ Spacer()
53+ StateBadge(state: run.state)
54+ }
55+ HStack(spacing: 8) {
56+ Text("\(run.config.model.paramCount.formatted(.number.notation(.compactName))) params")
57+ if let loss = run.lastTrainLoss {
58+ Text(String(format: "loss %.3f", loss))
59+ }
60+ if run.state.isActive {
61+ ProgressView(value: run.progress).frame(width: 60)
62+ }
63+ }
64+ .font(.caption)
65+ .foregroundStyle(.secondary)
66+ }
67+ .padding(.vertical, 2)
68+ }
69+}
70+
71+struct StateBadge: View {
72+ let state: RunState
73+
74+ var color: Color {
75+ switch state {
76+ case .running, .launching: return .green
77+ case .finished: return .blue
78+ case .failed: return .red
79+ case .stopped: return .orange
80+ case .queued, .finishing: return .gray
81+ }
82+ }
83+
84+ var body: some View {
85+ Text(state.rawValue)
86+ .font(.caption2.weight(.semibold))
87+ .padding(.horizontal, 6)
88+ .padding(.vertical, 2)
89+ .background(color.opacity(0.18), in: Capsule())
90+ .foregroundStyle(color)
91+ }
92+}
93+
94+struct EmptyStateView: View {
95+ @Environment(AppModel.self) private var app
96+
97+ var body: some View {
98+ VStack(spacing: 12) {
99+ Image(systemName: "flame")
100+ .font(.system(size: 48))
101+ .foregroundStyle(.orange)
102+ Text("Forge Studio").font(.largeTitle.weight(.semibold))
103+ if let device = app.forgeDevice {
104+ Label(device, systemImage: "cpu")
105+ .foregroundStyle(.secondary)
106+ }
107+ if let error = app.forgeError {
108+ Label(error, systemImage: "exclamationmark.triangle")
109+ .foregroundStyle(.red)
110+ SettingsLink { Text("Ouvrir les Réglages…") }
111+ } else {
112+ Text("Sélectionnez un run, ou créez-en un nouveau (+).")
113+ .foregroundStyle(.secondary)
114+ }
115+ }
116+ .frame(maxWidth: .infinity, maxHeight: .infinity)
117+ }
118+}
added ForgeStudio/Views/NewRunSheet.swift +242 −0
@@ -0,0 +1,242 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// New Run editor: preset picker, the high-traffic model/train fields, the
4+// live derived panel (params, tokens/step, epochs, memory badge) and the LR
5+// schedule preview. Inline validation gates the Start button. (The long
6+// tail of variant knobs lives in the "Avancé" JSON editor — full form in M2.)
7+import Charts
8+import SwiftUI
9+
10+struct NewRunSheet: View {
11+ @Environment(AppModel.self) private var app
12+ @Environment(\.dismiss) private var dismiss
13+ @State private var config = ForgeConfig()
14+ @State private var runName = "run"
15+ @State private var datasetPath = ""
16+ @State private var startError: String?
17+
18+ private var datasets: [Dataset] { app.datasets() }
19+ private var dataset: Dataset? { datasets.first { $0.path == datasetPath } }
20+ private var errors: [String] {
21+ var e = config.validationErrors
22+ if datasetPath.isEmpty { e.append("choisir un dataset") }
23+ if let v = dataset?.vocabSize, v != config.model.vocabSize {
24+ e.append("vocab_size (\(config.model.vocabSize)) ≠ tokenizer du dataset (\(v))")
25+ }
26+ return e
27+ }
28+
29+ var body: some View {
30+ VStack(spacing: 0) {
31+ HStack {
32+ Text("Nouveau run").font(.title2.weight(.semibold))
33+ Spacer()
34+ presetMenu
35+ }
36+ .padding()
37+ Divider()
38+ HSplitView {
39+ Form {
40+ Section("Run") {
41+ TextField("Nom", text: $runName)
42+ Picker("Dataset", selection: $datasetPath) {
43+ Text("—").tag("")
44+ ForEach(datasets) { ds in
45+ Text("\(ds.name) · vocab \(ds.vocabSize ?? 0) · \((ds.trainTokens ?? 0).formatted(.number.notation(.compactName))) tokens")
46+ .tag(ds.path)
47+ }
48+ }
49+ .onChange(of: datasetPath) {
50+ if let v = dataset?.vocabSize { config.model.vocabSize = v }
51+ }
52+ }
53+ Section("Modèle") {
54+ intField("n_layers", $config.model.nLayers)
55+ intField("d_model", $config.model.dModel)
56+ intField("n_heads", $config.model.nHeads)
57+ intField("n_kv_heads (GQA)", $config.model.nKvHeads)
58+ intField("d_ff", $config.model.dFf)
59+ intField("context_length", $config.model.contextLength)
60+ Picker("activation", selection: $config.model.activation) {
61+ ForEach(["swiglu", "gelu", "relu2"], id: \.self) { Text($0) }
62+ }
63+ Picker("norm", selection: $config.model.norm) {
64+ ForEach(["rmsnorm", "layernorm"], id: \.self) { Text($0) }
65+ }
66+ Toggle("tied_embeddings", isOn: $config.model.tiedEmbeddings)
67+ Toggle("qk_norm", isOn: $config.model.qkNorm)
68+ intField("sliding_window (0 = full)", $config.model.slidingWindow)
69+ }
70+ Section("Entraînement") {
71+ doubleField("lr", $config.train.lr)
72+ intField("max_steps", $config.train.maxSteps)
73+ intField("warmup_steps", $config.train.warmupSteps)
74+ Picker("schedule", selection: $config.train.schedule) {
75+ ForEach(["cosine", "wsd"], id: \.self) { Text($0) }
76+ }
77+ Picker("optimizer", selection: $config.train.optimizer) {
78+ ForEach(["adamw", "muon"], id: \.self) { Text($0) }
79+ }
80+ intField("batch_size (micro)", $config.train.batchSize)
81+ intField("grad_accum_steps", $config.train.gradAccumSteps)
82+ intField("checkpoint_every", $config.train.checkpointEvery)
83+ intField("eval_every", $config.train.evalEvery)
84+ }
85+ }
86+ .formStyle(.grouped)
87+ .frame(minWidth: 380)
88+
89+ DerivedPanel(config: config, dataset: dataset)
90+ .frame(minWidth: 300)
91+ .padding()
92+ }
93+ Divider()
94+ HStack {
95+ if let first = errors.first {
96+ Label(first, systemImage: "exclamationmark.triangle")
97+ .foregroundStyle(.red)
98+ .font(.callout)
99+ }
100+ if let startError {
101+ Text(startError).foregroundStyle(.red).font(.callout)
102+ }
103+ Spacer()
104+ Button("Annuler") { dismiss() }
105+ Button("Démarrer l'entraînement") {
106+ Task {
107+ do {
108+ config.model.name = runName
109+ try await app.supervisor.start(
110+ config: config, datasetPath: datasetPath,
111+ name: runName)
112+ dismiss()
113+ } catch {
114+ startError = error.localizedDescription
115+ }
116+ }
117+ }
118+ .keyboardShortcut(.defaultAction)
119+ .disabled(!errors.isEmpty)
120+ }
121+ .padding()
122+ }
123+ .frame(minWidth: 860, minHeight: 620)
124+ .onAppear {
125+ if let first = datasets.first { datasetPath = first.path }
126+ }
127+ }
128+
129+ private var presetMenu: some View {
130+ Menu("Presets") {
131+ ForEach(Presets.all, id: \.name) { preset in
132+ Button(preset.name) {
133+ config = preset.config
134+ runName = preset.config.model.name
135+ if let v = dataset?.vocabSize { config.model.vocabSize = v }
136+ }
137+ }
138+ }
139+ .frame(width: 120)
140+ }
141+
142+ private func intField(_ label: String, _ value: Binding<Int>) -> some View {
143+ TextField(label, value: value, format: .number)
144+ }
145+
146+ private func doubleField(_ label: String, _ value: Binding<Double>) -> some View {
147+ TextField(label, value: value, format: .number.precision(.significantDigits(1...6)))
148+ }
149+}
150+
151+struct DerivedPanel: View {
152+ let config: ForgeConfig
153+ let dataset: Dataset?
154+
155+ var body: some View {
156+ VStack(alignment: .leading, spacing: 14) {
157+ Text("Dérivés").font(.headline)
158+ derived("Paramètres",
159+ config.model.paramCount.formatted(.number.notation(.compactName)))
160+ derived("Tokens/step", config.tokensPerStep.formatted())
161+ derived("Tokens totaux",
162+ config.totalTokens.formatted(.number.notation(.compactName)))
163+ if let t = dataset?.trainTokens, t > 0 {
164+ derived("Epochs sur le dataset",
165+ String(format: "%.2f", Double(config.totalTokens) / Double(t)))
166+ }
167+ memoryBadge
168+ Divider()
169+ Text("Schedule LR").font(.headline)
170+ Chart {
171+ let steps = stride(from: 0, to: config.train.maxSteps,
172+ by: max(1, config.train.maxSteps / 200))
173+ ForEach(Array(steps), id: \.self) { s in
174+ LineMark(x: .value("step", s),
175+ y: .value("lr", config.train.lrAt(step: s)))
176+ .foregroundStyle(.purple)
177+ }
178+ }
179+ .frame(height: 140)
180+ Spacer()
181+ }
182+ }
183+
184+ private var memoryBadge: some View {
185+ let bytes = SystemInfo.estimatedTrainingBytes(config: config)
186+ let machine = SystemInfo.memoryBytes
187+ let gb = Double(bytes) / 1e9
188+ let ok = bytes < machine * 8 / 10
189+ return HStack {
190+ Image(systemName: ok ? "memorychip" : "exclamationmark.triangle.fill")
191+ Text(String(format: "~%.1f GB estimés / %.0f GB unifiés", gb,
192+ Double(machine) / 1e9))
193+ }
194+ .font(.callout)
195+ .foregroundStyle(ok ? Color.secondary : Color.orange)
196+ }
197+
198+ private func derived(_ label: String, _ value: String) -> some View {
199+ HStack {
200+ Text(label).foregroundStyle(.secondary)
201+ Spacer()
202+ Text(value).monospacedDigit()
203+ }
204+ .font(.callout)
205+ }
206+}
207+
208+enum Presets {
209+ struct Preset {
210+ let name: String
211+ let config: ForgeConfig
212+ }
213+
214+ // Mirrors configs/ in the forge repo (gpt-10m-1epoch, gpt-50m…).
215+ static let all: [Preset] = {
216+ var p10 = ForgeConfig()
217+ p10.model.name = "gpt-10m"
218+ p10.model.nLayers = 6; p10.model.dModel = 384; p10.model.nHeads = 6
219+ p10.model.nKvHeads = 6; p10.model.dFf = 1024; p10.model.vocabSize = 4096
220+ p10.model.contextLength = 512
221+ p10.train.lr = 6e-4; p10.train.warmupSteps = 58; p10.train.maxSteps = 584
222+ p10.train.batchSize = 64; p10.train.gradAccumSteps = 1
223+ p10.train.checkpointEvery = 200; p10.train.evalEvery = 100
224+
225+ var p50 = ForgeConfig()
226+ p50.model.name = "gpt-50m"
227+ p50.model.nLayers = 10; p50.model.dModel = 640; p50.model.nHeads = 10
228+ p50.model.nKvHeads = 10; p50.model.dFf = 1728; p50.model.vocabSize = 4096
229+ p50.model.contextLength = 1024
230+ p50.train.lr = 5e-4; p50.train.warmupSteps = 117; p50.train.maxSteps = 1170
231+ p50.train.batchSize = 8; p50.train.gradAccumSteps = 8
232+ p50.train.checkpointEvery = 200; p50.train.evalEvery = 100
233+
234+ var muon = p50
235+ muon.model.name = "gpt-50m-muon"
236+ muon.train.optimizer = "muon"; muon.train.schedule = "wsd"
237+
238+ return [Preset(name: "gpt-10m (1 epoch)", config: p10),
239+ Preset(name: "gpt-50m", config: p50),
240+ Preset(name: "gpt-50m Muon+WSD", config: muon)]
241+ }()
242+}
added ForgeStudio/Views/RunDetailView.swift +227 −0
@@ -0,0 +1,227 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Run dashboard: status strip, the loss chart (raw + bias-corrected EMA +
4+// val points, log/linear Y, best-val marker), and the console. Live data
5+// arrives via the supervisor's MetricsStore at ~1 Hz.
6+import Charts
7+import SwiftUI
8+
9+struct RunDetailView: View {
10+ let run: Run
11+ @Environment(AppModel.self) private var app
12+ @State private var snapshot: MetricsStore.Snapshot?
13+ @State private var smoothing = 0.6
14+ @State private var logScale = true
15+ @State private var showConsole = false
16+ @State private var historicStore: MetricsStore?
17+
18+ private var isLive: Bool { app.supervisor.activeRunID == run.id }
19+
20+ var body: some View {
21+ VStack(spacing: 0) {
22+ StatusStrip(run: run, snapshot: snapshot)
23+ Divider()
24+ ScrollView {
25+ VStack(alignment: .leading, spacing: 16) {
26+ lossChart
27+ HStack(spacing: 24) {
28+ secondaryChart(title: "Learning rate",
29+ series: snapshot?.lr ?? [], format: "%.2e")
30+ secondaryChart(title: "Tokens/s",
31+ series: snapshot?.tokensPerSec ?? [], format: "%.0f")
32+ secondaryChart(title: "Grad norm",
33+ series: snapshot?.gradNorm ?? [], format: "%.2f",
34+ threshold: run.config.train.gradClip)
35+ }
36+ DisclosureGroup("Console (\(app.supervisor.consoleLines.count) lignes)",
37+ isExpanded: $showConsole) {
38+ ConsoleView(lines: isLive ? app.supervisor.consoleLines
39+ : ["(run terminé — voir run.log)"])
40+ }
41+ }
42+ .padding()
43+ }
44+ }
45+ .toolbar {
46+ if isLive {
47+ ToolbarItem {
48+ Button(role: .destructive) {
49+ Task { await app.supervisor.stop() }
50+ } label: {
51+ Label("Stop", systemImage: "stop.fill")
52+ }
53+ .help("SIGTERM — forge ne checkpointe pas à l'arrêt ; reprise depuis ckpt_latest.bin")
54+ }
55+ }
56+ }
57+ .task(id: run.id) { await refreshLoop() }
58+ .navigationTitle(run.name)
59+ }
60+
61+ private var lossChart: some View {
62+ VStack(alignment: .leading, spacing: 8) {
63+ HStack {
64+ Text("Loss").font(.title3.weight(.semibold))
65+ Spacer()
66+ Toggle("log Y", isOn: $logScale).toggleStyle(.checkbox)
67+ HStack(spacing: 4) {
68+ Text("EMA")
69+ Slider(value: $smoothing, in: 0...0.99).frame(width: 120)
70+ Text(String(format: "%.2f", smoothing)).monospacedDigit()
71+ }
72+ .font(.caption)
73+ }
74+ Chart {
75+ ForEach(snapshot?.train ?? [], id: \.x) { p in
76+ LineMark(x: .value("step", p.x), y: .value("loss", p.y),
77+ series: .value("s", "train"))
78+ .foregroundStyle(.blue.opacity(0.25))
79+ }
80+ ForEach(snapshot?.trainEMA ?? [], id: \.x) { p in
81+ LineMark(x: .value("step", p.x), y: .value("ema", p.y),
82+ series: .value("s", "train EMA"))
83+ .foregroundStyle(.blue)
84+ }
85+ ForEach(snapshot?.val ?? [], id: \.x) { p in
86+ LineMark(x: .value("step", p.x), y: .value("val", p.y),
87+ series: .value("s", "val"))
88+ .foregroundStyle(.orange)
89+ PointMark(x: .value("step", p.x), y: .value("val", p.y))
90+ .foregroundStyle(.orange)
91+ .symbolSize(24)
92+ }
93+ if let best = snapshot?.bestVal {
94+ RuleMark(y: .value("best", best.loss))
95+ .foregroundStyle(.orange.opacity(0.4))
96+ .lineStyle(.init(lineWidth: 1, dash: [4, 4]))
97+ .annotation(position: .topTrailing) {
98+ Text(String(format: "best val %.3f @ %d", best.loss, best.step))
99+ .font(.caption2)
100+ .foregroundStyle(.orange)
101+ }
102+ }
103+ }
104+ .if(logScale) { $0.chartYScale(type: .log) }
105+ .chartLegend(.visible)
106+ .frame(minHeight: 320)
107+ }
108+ }
109+
110+ private func secondaryChart(title: String, series: [Downsampler.XY],
111+ format: String, threshold: Double? = nil) -> some View {
112+ VStack(alignment: .leading, spacing: 4) {
113+ HStack {
114+ Text(title).font(.caption.weight(.semibold))
115+ Spacer()
116+ if let last = series.last {
117+ Text(String(format: format, last.y))
118+ .font(.caption.monospacedDigit())
119+ .foregroundStyle(.secondary)
120+ }
121+ }
122+ Chart {
123+ ForEach(series, id: \.x) { p in
124+ LineMark(x: .value("step", p.x), y: .value("v", p.y))
125+ .foregroundStyle(.teal)
126+ }
127+ if let t = threshold, t > 0 {
128+ RuleMark(y: .value("clip", t))
129+ .lineStyle(.init(lineWidth: 1, dash: [3, 3]))
130+ .foregroundStyle(.red.opacity(0.5))
131+ }
132+ }
133+ .chartXAxis(.hidden)
134+ .frame(height: 110)
135+ }
136+ }
137+
138+ private func refreshLoop() async {
139+ if isLive {
140+ while !Task.isCancelled && app.supervisor.activeRunID == run.id {
141+ snapshot = await app.supervisor.metrics
142+ .snapshot(maxPoints: 1200, smoothing: smoothing)
143+ try? await Task.sleep(for: .milliseconds(500))
144+ }
145+ }
146+ // Historical (or freshly finished): load the whole CSV once.
147+ let store = MetricsStore()
148+ historicStore = store
149+ await store.ingestCSV(at: URL(fileURLWithPath: run.logCSVPath))
150+ snapshot = await store.snapshot(maxPoints: 1200, smoothing: smoothing)
151+ }
152+}
153+
154+struct StatusStrip: View {
155+ let run: Run
156+ let snapshot: MetricsStore.Snapshot?
157+
158+ var body: some View {
159+ HStack(spacing: 20) {
160+ StateBadge(state: run.state)
161+ if let step = run.lastStep {
162+ VStack(alignment: .leading, spacing: 1) {
163+ Text("step \(step + 1) / \(run.config.train.maxSteps)")
164+ .font(.callout.monospacedDigit())
165+ ProgressView(value: run.progress).frame(width: 140)
166+ }
167+ }
168+ if let last = snapshot?.lastPoint {
169+ metric("loss", String(format: "%.4f", last.trainLoss))
170+ metric("ppl", String(format: "%.1f", exp(last.trainLoss)))
171+ metric("tok/s", String(format: "%.0f", last.tokensPerSec))
172+ if let e = last.elapsedS {
173+ metric("écoulé", Duration.seconds(e)
174+ .formatted(.time(pattern: .hourMinuteSecond)))
175+ }
176+ }
177+ if let best = run.bestValLoss {
178+ metric("best val", String(format: "%.4f", best))
179+ }
180+ Spacer()
181+ Text("\(run.config.model.paramCount.formatted(.number.notation(.compactName))) params")
182+ .foregroundStyle(.secondary)
183+ }
184+ .padding(.horizontal)
185+ .padding(.vertical, 10)
186+ }
187+
188+ private func metric(_ label: String, _ value: String) -> some View {
189+ VStack(alignment: .leading, spacing: 1) {
190+ Text(label).font(.caption2).foregroundStyle(.secondary)
191+ Text(value).font(.callout.monospacedDigit())
192+ }
193+ }
194+}
195+
196+struct ConsoleView: View {
197+ let lines: [String]
198+
199+ var body: some View {
200+ ScrollViewReader { proxy in
201+ ScrollView {
202+ LazyVStack(alignment: .leading, spacing: 0) {
203+ ForEach(Array(lines.enumerated()), id: \.offset) { i, line in
204+ Text(line)
205+ .font(.system(.caption, design: .monospaced))
206+ .textSelection(.enabled)
207+ .id(i)
208+ }
209+ }
210+ .frame(maxWidth: .infinity, alignment: .leading)
211+ }
212+ .frame(height: 200)
213+ .background(.black.opacity(0.85))
214+ .clipShape(RoundedRectangle(cornerRadius: 6))
215+ .onChange(of: lines.count) {
216+ proxy.scrollTo(lines.count - 1, anchor: .bottom)
217+ }
218+ }
219+ }
220+}
221+
222+extension View {
223+ @ViewBuilder
224+ func `if`<T: View>(_ condition: Bool, transform: (Self) -> T) -> some View {
225+ if condition { transform(self) } else { self }
226+ }
227+}
added ForgeStudio/Views/SettingsView.swift +68 −0
@@ -0,0 +1,68 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Paths (forge binary, workspace) with live validation via `forge info`.
4+import SwiftUI
5+import UniformTypeIdentifiers
6+
7+struct SettingsView: View {
8+ @Environment(AppModel.self) private var app
9+ @State private var binaryPath = ForgeBinaryLocator.savedBinaryURL?.path ?? ""
10+ @State private var workspacePath = ForgeBinaryLocator.savedWorkspaceURL?.path ?? ""
11+
12+ var body: some View {
13+ Form {
14+ Section("Binaire forge") {
15+ HStack {
16+ TextField("Chemin", text: $binaryPath)
17+ .font(.callout.monospaced())
18+ Button("Choisir…") { pickBinary() }
19+ }
20+ if let device = app.forgeDevice {
21+ Label("Validé — \(device)", systemImage: "checkmark.circle.fill")
22+ .foregroundStyle(.green)
23+ } else if let error = app.forgeError {
24+ Label(error, systemImage: "xmark.circle.fill")
25+ .foregroundStyle(.red)
26+ }
27+ Button("Revalider") {
28+ ForgeBinaryLocator.save(binary: URL(fileURLWithPath: binaryPath))
29+ Task { await app.validateForge() }
30+ }
31+ }
32+ Section("Espace de travail") {
33+ HStack {
34+ TextField("Dossier (runs/, data/)", text: $workspacePath)
35+ .font(.callout.monospaced())
36+ Button("Choisir…") { pickWorkspace() }
37+ }
38+ Text("Runs : \(app.store.workspaceURL.path)/runs")
39+ .font(.caption)
40+ .foregroundStyle(.secondary)
41+ }
42+ }
43+ .formStyle(.grouped)
44+ .frame(width: 560, height: 320)
45+ }
46+
47+ private func pickBinary() {
48+ let panel = NSOpenPanel()
49+ panel.allowedContentTypes = [.unixExecutable, .executable]
50+ panel.canChooseDirectories = false
51+ if panel.runModal() == .OK, let url = panel.url {
52+ binaryPath = url.path
53+ ForgeBinaryLocator.save(binary: url)
54+ Task { await app.validateForge() }
55+ }
56+ }
57+
58+ private func pickWorkspace() {
59+ let panel = NSOpenPanel()
60+ panel.canChooseDirectories = true
61+ panel.canChooseFiles = false
62+ panel.canCreateDirectories = true
63+ if panel.runModal() == .OK, let url = panel.url {
64+ workspacePath = url.path
65+ ForgeBinaryLocator.save(workspace: url)
66+ }
67+ }
68+}
added Package.swift +25 −0
@@ -0,0 +1,25 @@
1+// swift-tools-version: 5.10
2+// Author: Simon-Pierre Boucher — contact@spboucher.ai
3+// Forge Studio — native macOS GUI companion for the Forge LLM training
4+// framework. SwiftPM is the canonical build system (zyquo-term pattern);
5+// scripts/package-app.sh turns the executable into a .app bundle.
6+import PackageDescription
7+
8+let package = Package(
9+ name: "ForgeStudio",
10+ platforms: [.macOS(.v14)],
11+ products: [
12+ .executable(name: "ForgeStudio", targets: ["ForgeStudio"])
13+ ],
14+ targets: [
15+ .executableTarget(
16+ name: "ForgeStudio",
17+ path: "ForgeStudio"
18+ ),
19+ .testTarget(
20+ name: "ForgeStudioTests",
21+ dependencies: ["ForgeStudio"],
22+ path: "Tests"
23+ ),
24+ ]
25+)
added RESEARCH.md +126 −0
@@ -0,0 +1,126 @@
1+<!-- Author: Simon-Pierre Boucher — contact@spboucher.ai -->
2+
3+# RESEARCH.md — Ground truth Forge pour Forge Studio
4+### Source : lecture directe du code Forge (même auteur, même machine), août 2026
5+
6+## 1. CLI `forge` (src/main.cpp)
7+
8+```
9+forge train --config <json> --data <dir> --out <dir> [--resume <ckpt>] [--backend metal|cpu]
10+forge generate --checkpoint <ckpt|.forge> --tokenizer <model> --prompt <text>
11+ [--temp t] [--top-k k] [--max-tokens n] [--seed s]
12+forge eval --checkpoint <ckpt|.forge> --data <val.bin> [--batches n]
13+forge export --checkpoint <ckpt.bin> --out <model.forge> [--dtype f32|f16|bf16]
14+ [--shard-mb n] [--tag label]
15+forge info [--config <json>]
16+```
17+- Les flags sont `--key value` ; un flag sans valeur vaut `"true"`.
18+- `generate`/`eval` acceptent un repo `.forge` (répertoire) ou un manifest.json.
19+- Exit code 0 = succès ; erreurs fatales → stderr + abort (code ≠ 0).
20+
21+## 2. Schéma de config (src/nn/config.h) — vérité au 2026-08-05
22+
23+### `model` (défauts entre parenthèses)
24+name("model") · n_layers(6) · d_model(384) · n_heads(6) · n_kv_heads(=n_heads, GQA si <)
25+· d_ff(1024) · vocab_size(4096) · context_length(512) · tied_embeddings(true)
26+· use_rope(true) · rope_theta(10000) · norm("rmsnorm"|"layernorm") · norm_eps(1e-6)
27+· activation("swiglu"|"gelu"|"relu2") · dropout(0)
28+· quant("none"|"int8"|"ternary") · qk_norm(false) · final_softcap(0) ·
29+scale_embeddings(false) · attention_bias(false) · head_dim(0=auto) · nope_every(0)
30+· norm_placement("pre"|"post"|"sandwich") · rope_scale_factor(0=off) ·
31+rope_scale_low(1) · rope_scale_high(4) · rope_scale_orig_ctx(8192)
32+· sliding_window(0) · sliding_global_every(0) · rope_theta_global(0) · attn_softcap(0)
33+· n_experts(0) · moe_top_k(2) · moe_aux_weight(0.01) · n_shared_experts(0)
34+· moe_scoring("softmax"|"sigmoid") · moe_norm_topk(true) · routed_scaling_factor(1)
35+· moe_d_ff(0) · first_k_dense(0) · moe_bias_gamma(0)
36+
37+Validations (levées comme exceptions au parse) : d_model % n_heads == 0 (sauf head_dim
38+explicite) ; n_heads % n_kv_heads == 0 ; head_dim pair ; moe_top_k ∈ [1, n_experts] ;
39+n_shared_experts ⇒ n_experts>0 ; first_k_dense ∈ [0, n_layers] ; enums valides.
40+
41+### `train`
42+lr(6e-4) · min_lr_ratio(0.1) · warmup_steps(2000) · max_steps(100000)
43+· schedule("cosine"|"wsd") · wsd_decay_frac(0.15) · optimizer("adamw"|"muon")
44+· muon_lr(0.02) · muon_momentum(0.95) · beta1(0.9) · beta2(0.95) · eps(1e-8)
45+· weight_decay(0.1) · grad_clip(1.0, 0=off) · batch_size(32, MICRO-batch)
46+· grad_accum_steps(1) · precision("f32", parsé mais pas encore honoré)
47+· checkpoint_every(1000, 0=off) · forge_save(true) · forge_dtype("f32"|"f16"|"bf16")
48+· eval_every(500, 0=off) · eval_batches(20) · seed(1337) · deterministic(false)
49+
50+Dérivés : tokens/step = batch_size × context_length × grad_accum_steps ;
51+param count = formule de ModelConfig::num_params() (répliquée dans ForgeConfig.swift,
52+à cross-checker via `forge info`).
53+
54+## 3. Métriques structurées — log.csv (PAS besoin de patch JSONL)
55+
56+`<out>/log.csv`, en-tête écrit au step 0, **une ligne par step, flushée** :
57+```
58+step,loss,lr,grad_norm,tokens_per_sec,val_loss,elapsed_s
59+584,2.296893,3.680000e-04,0.558962,13692.0,-1.000000,3861.402
60+```
61+- `val_loss = -1.0` quand pas d'éval à ce step (eval tous les `eval_every` steps,
62+ à step ≡ eval_every-1 mod eval_every).
63+- `elapsed_s` (ajouté commit 147560e) = wall-clock depuis le début du run.
64+- Resume : le fichier est rouvert en append (pas de second en-tête) ; les anciens runs
65+ peuvent avoir 6 colonnes (sans elapsed_s) → parser dirigé par l'en-tête.
66+- stdout humain en parallèle : `step %6lld | loss %.4f | lr %.2e | gnorm %.3f | %f tok/s[ | val %.4f]`
67+ + lignes `checkpoint saved: <path>` et `fmodel: <manifest> — N tensors reused…`.
68+ Première ligne : `training <name>: <params> params, <steps> steps, <tps> tokens/step, backend=…, opt=…, sched=…`.
69+
70+## 4. Checkpoints & resume
71+
72+- `<out>/ckpt_%06d.bin` tous les `checkpoint_every` steps + `ckpt_latest.bin` à chaque
73+ fois + checkpoint final à max_steps. Format binaire FRGE v1 (poids + état optimiseur
74+ + step + config JSON embarquée).
75+- **`--resume <ckpt>` EXISTE** et reprend au step sauvé (dataloader re-seedé du step).
76+- `.forge` : si forge_save, chaque checkpoint committe aussi les poids dans
77+ `<out>/model.forge/` (manifests + shards contenu-adressés ; `tools/fmodel.py log`
78+ pour l'historique).
79+
80+## 5. Signaux
81+
82+`forge train` n'installe AUCUN handler SIGINT/SIGTERM : le process meurt
83+immédiatement, sans checkpoint de sortie. Conséquence UI : « Stop » = SIGTERM après
84+confirmation ; la reprise se fait du dernier `ckpt_latest.bin` (perte ≤
85+checkpoint_every steps). L'UI doit l'annoncer honnêtement.
86+
87+## 6. Datasets (tools/)
88+
89+- `prepare_data.py --out data/tinystories [--vocab-size N] [--max-train-mb MB]
90+ [--tokenizer path]` → `train.bin`, `val.bin` (en-tête {magic 20240520, version 1,
91+ num_tokens} puis tokens uint16), `tokN.model` (forgebpe v1, texte).
92+- `prepare_hf_data.py --source|--mix|--preset … --out <dir>` : 13 sources HF
93+ streamées, mélanges pondérés (voir --list).
94+- Contrainte dure : `model.vocab_size` == vocab du tokenizer du dataset.
95+- Token count d'un .bin : lire l'en-tête int32[3] (offset 8 = num_tokens) — pas de
96+ division de taille de fichier.
97+
98+## 7. Signing / notarization (extrait de zyquo-term, RÉEL)
99+
100+- Identité : `Developer ID Application: Simon-Pierre Boucher (3YM54G49SN)` (Team
101+ 3YM54G49SN), certificat dans le login keychain.
102+- Profil notarytool : `MacLustr-Notarize` (keychain profile).
103+- Pattern : SwiftPM canonique (pas de .xcodeproj) → `scripts/package-app.sh`
104+ (bundle + codesign ad-hoc pour dev) → `scripts/notarize.sh` (Developer ID +
105+ hardened runtime + DMG + notarytool submit --wait + stapler).
106+- Zyquo-term signe : binaire (avec entitlements) puis .app puis .dmg, options
107+ `--force --options runtime --timestamp`.
108+
109+## 8. Décisions
110+
111+- **Métriques : log.csv suffit** (structuré, flushé, versionné par en-tête) — pas de
112+ patch --metrics-file nécessaire ; parser regex du stdout gardé en fallback pour
113+ détecter `checkpoint saved:` en live.
114+- **Build : SwiftPM** (pattern zyquo-term), pas de .xcodeproj — Xcode 26 présent si
115+ besoin d'archive.
116+- **Sandbox : non** (l'app pilote des binaires externes arbitraires) ; Developer ID +
117+ Hardened Runtime, comme zyquo-term.
118+
119+## 9. État d'avancement Studio
120+
121+- [x] M1 fondations : Package.swift, modèles Codable complets (schéma §2), services
122+ (ProcessRunner, LogParser, MetricsStore, RunStore, BinaryLocator, SystemInfo),
123+ LTTB + EMA, app squelette naviguable, scripts build/package/notarize.
124+- [ ] M2 éditeur New Run complet (panneau dérivé, preview LR, validation inline)
125+- [ ] M3 dashboard chart interactif complet (hover/zoom/follow-live)
126+- [ ] M4-M8 : voir CLAUDE.md.
added Tests/ForgeStudioTests.swift +116 −0
@@ -0,0 +1,116 @@
1+// Author: Simon-Pierre Boucher — contact@spboucher.ai
2+//
3+// Contract tests: config codec against the REAL forge configs, the
4+// param-count formula against `forge info`, LTTB invariants, EMA bias
5+// correction, CSV parser against real and mutated lines, state machine.
6+import XCTest
7+@testable import ForgeStudio
8+
9+final class ForgeStudioTests: XCTestCase {
10+ let forgeRepo = URL(fileURLWithPath: NSHomeDirectory() + "/Desktop/forge")
11+
12+ func testConfigRoundTripAgainstRealConfigs() throws {
13+ let configsDir = forgeRepo.appendingPathComponent("configs")
14+ let files = (try? FileManager.default.contentsOfDirectory(
15+ at: configsDir, includingPropertiesForKeys: nil))?
16+ .filter { $0.pathExtension == "json" } ?? []
17+ try XCTSkipIf(files.isEmpty, "forge repo introuvable")
18+ for url in files {
19+ let cfg = try ForgeConfig.load(from: url)
20+ // Re-export and re-parse: field names must be byte-compatible.
21+ let data = try cfg.exportJSON()
22+ let reparsed = try JSONDecoder().decode(ForgeConfig.self, from: data)
23+ XCTAssertEqual(cfg, reparsed, url.lastPathComponent)
24+ XCTAssertTrue(cfg.validationErrors.isEmpty,
25+ "\(url.lastPathComponent): \(cfg.validationErrors)")
26+ }
27+ }
28+
29+ func testParamCountMatchesForgeInfo() throws {
30+ // Known-good values printed by `forge info` for the shipped configs.
31+ let expected: [(String, Double)] = [
32+ ("gpt-50m.json", 52.20), ("gpt-50m-moe.json", 151.75),
33+ ("gpt-50m-deep.json", 50.60), ("gpt-50m-mistral.json", 48.10),
34+ ]
35+ for (file, millions) in expected {
36+ let url = forgeRepo.appendingPathComponent("configs/\(file)")
37+ guard let cfg = try? ForgeConfig.load(from: url) else { continue }
38+ XCTAssertEqual(Double(cfg.model.paramCount) / 1e6, millions,
39+ accuracy: 0.01, file)
40+ }
41+ }
42+
43+ func testLTTBInvariants() {
44+ let pts = (0..<10_000).map {
45+ Downsampler.XY(x: Double($0), y: sin(Double($0) / 50) + Double($0) * 0.001)
46+ }
47+ let ds = Downsampler.lttb(pts, threshold: 500)
48+ XCTAssertEqual(ds.count, 500)
49+ XCTAssertEqual(ds.first, pts.first) // endpoints preserved exactly
50+ XCTAssertEqual(ds.last, pts.last)
51+ XCTAssertTrue(zip(ds, ds.dropFirst()).allSatisfy { $0.x < $1.x }) // monotonic
52+ XCTAssertEqual(Downsampler.lttb(pts, threshold: 20_000).count, pts.count)
53+ }
54+
55+ func testEMABiasCorrection() {
56+ // A constant series must stay exactly constant under bias-corrected EMA.
57+ let ema = Smoothing.ema([Double](repeating: 3.5, count: 100), smoothing: 0.9)
58+ XCTAssertTrue(ema.allSatisfy { abs($0 - 3.5) < 1e-9 })
59+ XCTAssertEqual(Smoothing.ema([1, 2, 3], smoothing: 0), [1, 2, 3])
60+ }
61+
62+ func testCSVParser() {
63+ var p = LogParser()
64+ XCTAssertNil(p.parseCSVLine("step,loss,lr,grad_norm,tokens_per_sec,val_loss,elapsed_s"))
65+ let pt = p.parseCSVLine("584,2.296893,3.680000e-04,0.558962,13692.0,-1.000000,3861.402")
66+ XCTAssertEqual(pt?.step, 584)
67+ XCTAssertEqual(pt!.trainLoss, 2.296893, accuracy: 1e-9)
68+ XCTAssertNil(pt?.valLoss) // -1 sentinel
69+ XCTAssertEqual(pt!.elapsedS!, 3861.402, accuracy: 1e-6)
70+ let withVal = p.parseCSVLine("599,2.19,3.05e-04,0.55,13748.0,2.3299,3960.1")
71+ XCTAssertEqual(withVal!.valLoss!, 2.3299, accuracy: 1e-9)
72+ // Legacy 6-column header, garbage, truncation: never crash.
73+ var legacy = LogParser()
74+ _ = legacy.parseCSVLine("step,loss,lr,grad_norm,tokens_per_sec,val_loss")
75+ let old = legacy.parseCSVLine("10,5.2,1e-4,0.9,42000.0,-1.0")
76+ XCTAssertNil(old?.elapsedS)
77+ XCTAssertNil(legacy.parseCSVLine("garbage,🤖,,"))
78+ XCTAssertNil(legacy.parseCSVLine("1,2"))
79+ XCTAssertNil(legacy.parseCSVLine(""))
80+ }
81+
82+ func testStdoutEvents() {
83+ XCTAssertEqual(
84+ LogParser.parseStdout("checkpoint saved: runs/x/ckpt_000200.bin"),
85+ .checkpointSaved(path: "runs/x/ckpt_000200.bin"))
86+ if case .banner(let params, let steps, let tps, let backend)? =
87+ LogParser.parseStdout(
88+ "training gpt-50m: 52196480 params, 1170 steps, 65536 tokens/step, backend=metal, opt=adamw, sched=cosine")
89+ {
90+ XCTAssertEqual(params, 52_196_480)
91+ XCTAssertEqual(steps, 1170)
92+ XCTAssertEqual(tps, 65536)
93+ XCTAssertEqual(backend, "metal")
94+ } else {
95+ XCTFail("banner non parsé")
96+ }
97+ }
98+
99+ func testRunStateMachine() {
100+ // Terminal states allow nothing; queued can't jump to finished.
101+ XCTAssertTrue(RunState.transitions[.finished]!.isEmpty)
102+ XCTAssertTrue(RunState.transitions[.failed]!.isEmpty)
103+ XCTAssertFalse(RunState.transitions[.queued]!.contains(.finished))
104+ XCTAssertTrue(RunState.transitions[.running]!.contains(.finishing))
105+ }
106+
107+ func testLRSchedulePreviewMatchesForgeMath() {
108+ var t = TrainConfig()
109+ t.lr = 5e-4; t.warmupSteps = 100; t.maxSteps = 1000
110+ XCTAssertEqual(t.lrAt(step: 0), 5e-4 * 1.0 / 101.0, accuracy: 1e-12)
111+ XCTAssertEqual(t.lrAt(step: 999) > t.lr * t.minLrRatio, true)
112+ XCTAssertEqual(t.lrAt(step: 1000), t.lr * t.minLrRatio, accuracy: 1e-12)
113+ t.schedule = "wsd"
114+ XCTAssertEqual(t.lrAt(step: 500), t.lr, accuracy: 1e-15) // plateau
115+ }
116+}
added scripts/notarize.sh +42 −0
@@ -0,0 +1,42 @@
1+#!/bin/bash
2+# Author: Simon-Pierre Boucher — contact@spboucher.ai
3+# Developer ID signing, DMG, and notarization for Forge Studio.
4+# Identity and notarization flow reused from the zyquo-term pipeline
5+# (Team 3YM54G49SN, notarytool keychain profile "MacLustr-Notarize").
6+set -euo pipefail
7+cd "$(dirname "$0")/.."
8+
9+IDENTITY="Developer ID Application: Simon-Pierre Boucher (3YM54G49SN)"
10+KEYCHAIN_PROFILE="MacLustr-Notarize"
11+APP_DIR="dist/ForgeStudio.app"
12+DMG_NAME="dist/ForgeStudio-0.1.0.dmg"
13+
14+./scripts/package-app.sh release
15+
16+echo "=== Signing (Developer ID, hardened runtime) ==="
17+codesign --force --options runtime --timestamp \
18+ --sign "$IDENTITY" "$APP_DIR/Contents/MacOS/ForgeStudio"
19+codesign --force --options runtime --timestamp \
20+ --sign "$IDENTITY" "$APP_DIR"
21+codesign --verify --deep --strict --verbose=2 "$APP_DIR"
22+
23+echo "=== DMG ==="
24+rm -f "$DMG_NAME"
25+if command -v create-dmg >/dev/null; then
26+ create-dmg --volname "Forge Studio" --app-drop-link 480 200 \
27+ --window-size 660 420 "$DMG_NAME" "$APP_DIR"
28+else
29+ hdiutil create -volname "Forge Studio" -srcfolder "$APP_DIR" \
30+ -ov -format UDZO "$DMG_NAME"
31+fi
32+codesign --force --sign "$IDENTITY" --timestamp "$DMG_NAME"
33+
34+echo "=== Notarizing (profile: $KEYCHAIN_PROFILE) ==="
35+xcrun notarytool submit "$DMG_NAME" --keychain-profile "$KEYCHAIN_PROFILE" --wait
36+
37+echo "=== Stapling ==="
38+xcrun stapler staple "$APP_DIR"
39+xcrun stapler staple "$DMG_NAME"
40+xcrun stapler validate "$DMG_NAME"
41+spctl -a -vv "$APP_DIR"
42+echo "OK: $DMG_NAME"
added scripts/package-app.sh +40 −0
@@ -0,0 +1,40 @@
1+#!/bin/bash
2+# Author: Simon-Pierre Boucher — contact@spboucher.ai
3+# Build the SwiftPM executable and wrap it into ForgeStudio.app (ad-hoc
4+# signed — fast local iteration; scripts/notarize.sh does the real signing).
5+set -euo pipefail
6+cd "$(dirname "$0")/.."
7+
8+CONFIG="${1:-release}"
9+swift build -c "$CONFIG"
10+
11+BIN=".build/$CONFIG/ForgeStudio"
12+APP_DIR="dist/ForgeStudio.app"
13+rm -rf "$APP_DIR"
14+mkdir -p "$APP_DIR/Contents/MacOS" "$APP_DIR/Contents/Resources"
15+
16+cp "$BIN" "$APP_DIR/Contents/MacOS/ForgeStudio"
17+
18+cat > "$APP_DIR/Contents/Info.plist" <<'PLIST'
19+<?xml version="1.0" encoding="UTF-8"?>
20+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
21+<plist version="1.0">
22+<dict>
23+ <key>CFBundleName</key><string>Forge Studio</string>
24+ <key>CFBundleDisplayName</key><string>Forge Studio</string>
25+ <key>CFBundleIdentifier</key><string>ai.spboucher.forge-studio</string>
26+ <key>CFBundleExecutable</key><string>ForgeStudio</string>
27+ <key>CFBundleVersion</key><string>1</string>
28+ <key>CFBundleShortVersionString</key><string>0.1.0</string>
29+ <key>CFBundlePackageType</key><string>APPL</string>
30+ <key>LSMinimumSystemVersion</key><string>14.0</string>
31+ <key>LSApplicationCategoryType</key><string>public.app-category.developer-tools</string>
32+ <key>NSHighResolutionCapable</key><true/>
33+ <key>NSHumanReadableCopyright</key><string>© Simon-Pierre Boucher</string>
34+</dict>
35+</plist>
36+PLIST
37+
38+codesign --force --deep --sign - "$APP_DIR"
39+codesign --verify --deep --strict --verbose=2 "$APP_DIR"
40+echo "OK: $APP_DIR"
41
Menu

Theme
↑↓ navigate ↵ open esc close / or ⌘K anywhere