dsh-version-manager 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,185 @@
1
+ /**
2
+ * Taking a version from "planned" to "verified", one step at a time.
3
+ *
4
+ * The host's own update path is two profile operations (remove, then install),
5
+ * so a process that dies in the middle leaves the profile in a state nobody
6
+ * chose. This module does not try to make that atomic — it cannot, and claiming
7
+ * otherwise would be the single most dangerous lie a version manager can tell.
8
+ * What it does instead is write the intent down before the first byte changes,
9
+ * so the panel can say afterwards which step was reached:
10
+ *
11
+ * planned → snapshot_verified → applying → verifying → succeeded
12
+ * ↘ failed / cancelled / recovery_required
13
+ *
14
+ * Every transition is appended to an operation record on disk. A record that
15
+ * ends in `applying` is a record of a change whose outcome is unknown, and that
16
+ * is exactly what a `recovery_required` badge is for.
17
+ *
18
+ * @module dsh-version-manager/lib/host/operations
19
+ */
20
+
21
+ import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
22
+ import { join } from 'node:path'
23
+ import { randomUUID } from 'node:crypto'
24
+
25
+ /** The states a change can be in. Order matters: it is the order they occur. */
26
+ export const STATES = Object.freeze([
27
+ 'planned',
28
+ 'snapshot_verified',
29
+ 'applying',
30
+ 'verifying',
31
+ 'succeeded',
32
+ 'failed',
33
+ 'cancelled',
34
+ 'recovery_required',
35
+ ])
36
+
37
+ /** States after which nothing more will happen without a new explicit action. */
38
+ export const TERMINAL = Object.freeze(['succeeded', 'failed', 'cancelled', 'recovery_required'])
39
+
40
+ /**
41
+ * Where operation records live for one profile.
42
+ *
43
+ * @param {string} dshHome
44
+ * @param {string} profileId
45
+ * @returns {string}
46
+ */
47
+ export function operationRoot(dshHome, profileId) {
48
+ return join(dshHome, 'version-manager', 'operations', encodeSegment(profileId))
49
+ }
50
+
51
+ /**
52
+ * @param {string} value
53
+ * @returns {string}
54
+ */
55
+ function encodeSegment(value) {
56
+ return value.replace(/\//g, '%2F').replace(/[^A-Za-z0-9%._@-]/g, '_')
57
+ }
58
+
59
+ /**
60
+ * Start a record.
61
+ *
62
+ * Written before anything is touched, and written with `flag: 'wx'` so an id
63
+ * collision fails loudly instead of overwriting another operation's history.
64
+ *
65
+ * @param {object} input
66
+ * @param {string} input.dshHome
67
+ * @param {string} input.profileId
68
+ * @param {object} input.target
69
+ * @param {string} input.toVersion
70
+ * @returns {Promise<object>}
71
+ */
72
+ export async function beginOperation(input) {
73
+ const { dshHome, profileId, target, toVersion } = input
74
+ const directory = operationRoot(dshHome, profileId)
75
+ await mkdir(directory, { recursive: true })
76
+
77
+ const record = {
78
+ schema: 1,
79
+ id: randomUUID(),
80
+ startedAt: new Date().toISOString(),
81
+ state: 'planned',
82
+ profile: { id: profileId },
83
+ target: {
84
+ kind: target.kind,
85
+ targetId: target.targetId,
86
+ fromVersion: target.installedVersion,
87
+ toVersion,
88
+ declaredSpec: target.declaredSpec,
89
+ sourceKind: target.source?.kind ?? 'unknown',
90
+ },
91
+ transitions: [{ state: 'planned', at: new Date().toISOString() }],
92
+ error: null,
93
+ snapshotId: null,
94
+ }
95
+
96
+ await writeFile(join(directory, `${record.id}.json`), JSON.stringify(record, null, 2), {
97
+ encoding: 'utf8',
98
+ flag: 'wx',
99
+ })
100
+ return record
101
+ }
102
+
103
+ /**
104
+ * Append one transition and persist it.
105
+ *
106
+ * @param {string} dshHome
107
+ * @param {string} profileId
108
+ * @param {object} record
109
+ * @param {string} state
110
+ * @param {{ error?: string | null, snapshotId?: string | null, detail?: string | null }} [extra]
111
+ * @returns {Promise<object>}
112
+ */
113
+ export async function transition(dshHome, profileId, record, state, extra = {}) {
114
+ if (!STATES.includes(state)) throw new Error(`unknown operation state: ${state}`)
115
+ record.state = state
116
+ record.transitions.push({ state, at: new Date().toISOString() })
117
+ if (extra.error !== undefined) record.error = extra.error
118
+ if (extra.snapshotId !== undefined) record.snapshotId = extra.snapshotId
119
+ if (extra.detail !== undefined) record.detail = extra.detail
120
+ await persist(dshHome, profileId, record)
121
+ return record
122
+ }
123
+
124
+ /**
125
+ * @param {string} dshHome
126
+ * @param {string} profileId
127
+ * @param {object} record
128
+ */
129
+ async function persist(dshHome, profileId, record) {
130
+ const directory = operationRoot(dshHome, profileId)
131
+ const target = join(directory, `${record.id}.json`)
132
+ const temporary = join(directory, `.${record.id}.tmp`)
133
+ await writeFile(temporary, JSON.stringify(record, null, 2), { encoding: 'utf8', flag: 'w' })
134
+ await rename(temporary, target)
135
+ }
136
+
137
+ /**
138
+ * The newest records first.
139
+ *
140
+ * @param {string} dshHome
141
+ * @param {string} profileId
142
+ * @param {number} [limit]
143
+ * @returns {Promise<object[]>}
144
+ */
145
+ export async function listOperations(dshHome, profileId, limit = 20) {
146
+ const directory = operationRoot(dshHome, profileId)
147
+ let names
148
+ try {
149
+ names = await readdir(directory)
150
+ } catch (error) {
151
+ if (error?.code === 'ENOENT') return []
152
+ throw error
153
+ }
154
+ const rows = []
155
+ for (const name of names) {
156
+ if (!name.endsWith('.json')) continue
157
+ try {
158
+ rows.push(JSON.parse(await readFile(join(directory, name), 'utf8')))
159
+ } catch {
160
+ // An unreadable record is not a reason to hide the readable ones.
161
+ }
162
+ }
163
+ rows.sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)))
164
+ return rows.slice(0, limit)
165
+ }
166
+
167
+ /**
168
+ * Records that claim a change started but never reached a terminal state.
169
+ *
170
+ * This is the one place where "we do not know" has to be surfaced as its own
171
+ * answer: the process died mid-change, so the profile may be fine, may be
172
+ * half-updated, or may be broken, and no reading of the current state can tell
173
+ * which. The panel shows these as `recovery_required` and points at the
174
+ * snapshot, rather than reporting the current version as if it were chosen.
175
+ *
176
+ * @param {object[]} operations
177
+ * @returns {object[]}
178
+ */
179
+ export function unresolved(operations) {
180
+ return operations.filter(
181
+ (record) =>
182
+ !TERMINAL.includes(record.state) ||
183
+ record.state === 'recovery_required',
184
+ )
185
+ }