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.
- package/LICENSE +21 -0
- package/README.md +234 -2
- package/cordis.patch.yml +12 -0
- package/docs/baseline.md +224 -0
- package/lib/client.js +2367 -0
- package/lib/host/compat.js +303 -0
- package/lib/host/git-routes.js +376 -0
- package/lib/host/git-skill.js +1133 -0
- package/lib/host/inventory.js +231 -0
- package/lib/host/locate.js +169 -0
- package/lib/host/lockfile.js +124 -0
- package/lib/host/operations.js +185 -0
- package/lib/host/routes.js +1336 -0
- package/lib/host/skill-restore.js +346 -0
- package/lib/host/skills.js +327 -0
- package/lib/host/snapshot-store.js +335 -0
- package/lib/host/spec.js +274 -0
- package/lib/index.js +49 -0
- package/package.json +60 -4
|
@@ -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
|
+
}
|