@moxuli/moremote 0.1.0 → 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/README.md +1 -1
- package/dist/cli.js +24 -7
- package/dist/control-transport.d.ts +4 -0
- package/dist/control-transport.js +68 -0
- package/dist/control.js +109 -38
- package/docs/README.md +1 -1
- package/docs/STATE.md +27 -4
- package/docs/decisions/0001-managed-updates.md +1 -1
- package/docs/plans/2026-11-10-managed-updates.md +1 -1
- package/docs/releasing.md +20 -24
- package/docs/specs/06-managed-updates.md +8 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -70,5 +70,5 @@ Default CLI state uses `LOCALAPPDATA/MoRemoteCLI` on Windows, `~/Library/Applica
|
|
|
70
70
|
|
|
71
71
|
[Docs](docs/README.md) · [Contributing](CONTRIBUTING.md) · [License](LICENSE) · [Notices](NOTICE)
|
|
72
72
|
|
|
73
|
-
Public release prerequisites,
|
|
73
|
+
Public release prerequisites, existing-secret setup and exact verification commands:
|
|
74
74
|
[releasing](docs/releasing.md). Checked-in workflows are not proof of a published package.
|
package/dist/cli.js
CHANGED
|
@@ -54,13 +54,30 @@ async function stopRuntime(dir) { if (!await requestControl(dir, 'stop'))
|
|
|
54
54
|
if (!await requestControl(dir, 'status'))
|
|
55
55
|
return;
|
|
56
56
|
} throw Error('STOP_TIMEOUT'); }
|
|
57
|
-
async function stopManaged(dir) {
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
await
|
|
62
|
-
}
|
|
63
|
-
|
|
57
|
+
async function stopManaged(dir) {
|
|
58
|
+
requestSupervisorStop(dir);
|
|
59
|
+
let legacyUnavailable = false;
|
|
60
|
+
try {
|
|
61
|
+
await stopRuntime(dir);
|
|
62
|
+
}
|
|
63
|
+
catch (error) {
|
|
64
|
+
if (error instanceof Error && error.message === 'LEGACY_WINDOWS_CONTROL_UNAVAILABLE' && readUpdateState(dir))
|
|
65
|
+
legacyUnavailable = true;
|
|
66
|
+
else
|
|
67
|
+
throw error;
|
|
68
|
+
}
|
|
69
|
+
if (readUpdateState(dir))
|
|
70
|
+
for (let i = 0; i < 900; i++) {
|
|
71
|
+
if (!supervisorRunning(dir)) {
|
|
72
|
+
if (legacyUnavailable && await requestControl(dir, 'status'))
|
|
73
|
+
throw Error('STOP_TIMEOUT');
|
|
74
|
+
return;
|
|
75
|
+
}
|
|
76
|
+
await sleep(200);
|
|
77
|
+
}
|
|
78
|
+
if (readUpdateState(dir) && supervisorRunning(dir))
|
|
79
|
+
throw Error('SUPERVISOR_STOP_TIMEOUT');
|
|
80
|
+
}
|
|
64
81
|
async function stopOwned(dir, definition) { await stopService(definition); await stopManaged(dir); }
|
|
65
82
|
async function main() {
|
|
66
83
|
if (args.help || !action) {
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { type ResourceIdentity, type RuntimeOwner } from './resources.js';
|
|
2
|
+
export declare function controlFraming(dir: string, owner: RuntimeOwner): 'legacy-eof' | 'json-lines-v1';
|
|
3
|
+
export declare function publishControlTransport(dir: string, owner: RuntimeOwner): Promise<ResourceIdentity>;
|
|
4
|
+
export declare function removeControlTransport(dir: string, identity: ResourceIdentity, owner: RuntimeOwner): boolean;
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import { join } from 'node:path';
|
|
2
|
+
import { openSync, closeSync, fsyncSync, renameSync } from 'node:fs';
|
|
3
|
+
import { createHash, randomUUID } from 'node:crypto';
|
|
4
|
+
import { privateManagedDirectory } from './config.js';
|
|
5
|
+
import { managedRoot } from './update-state.js';
|
|
6
|
+
import { inspectResource, readPrivateText, createPrivateFile, removeOwnedResource, sameResource } from './resources.js';
|
|
7
|
+
const OWNER = 'MoRemote CLI control transport';
|
|
8
|
+
function readDescriptor(dir) {
|
|
9
|
+
if (!inspectResource(join(dir, 'managed'), 'directory', true))
|
|
10
|
+
return null;
|
|
11
|
+
const root = managedRoot(dir), path = join(root, 'runtime-transport.json');
|
|
12
|
+
if (!inspectResource(path, 'file', true))
|
|
13
|
+
return null;
|
|
14
|
+
const file = readPrivateText(path, 2048);
|
|
15
|
+
let value;
|
|
16
|
+
try {
|
|
17
|
+
value = JSON.parse(file.text);
|
|
18
|
+
}
|
|
19
|
+
catch {
|
|
20
|
+
throw Error('INVALID_CONTROL_TRANSPORT');
|
|
21
|
+
}
|
|
22
|
+
if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== 7 || value.owner !== OWNER || value.version !== 1 || value.framing !== 'json-lines-v1' || typeof value.instanceId !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value.instanceId) || !Number.isSafeInteger(value.pid) || value.pid < 1 || value.pid > 2147483647 || !Number.isSafeInteger(value.startedAt) || value.startedAt < 1 || typeof value.tokenHash !== 'string' || !/^[0-9a-f]{64}$/.test(value.tokenHash))
|
|
23
|
+
throw Error('INVALID_CONTROL_TRANSPORT');
|
|
24
|
+
return { ...file, value };
|
|
25
|
+
}
|
|
26
|
+
function matches(value, owner) { return value.instanceId === owner.instanceId && value.pid === owner.pid && value.startedAt === owner.startedAt && value.tokenHash === createHash('sha256').update(owner.token).digest('hex'); }
|
|
27
|
+
export function controlFraming(dir, owner) {
|
|
28
|
+
const descriptor = readDescriptor(dir);
|
|
29
|
+
return descriptor && matches(descriptor.value, owner) ? 'json-lines-v1' : 'legacy-eof';
|
|
30
|
+
}
|
|
31
|
+
export async function publishControlTransport(dir, owner) {
|
|
32
|
+
// Nested managed resources are understood/ignored by the published 0.1.0
|
|
33
|
+
// root reader; its exact six/seven-key runtime lock/record stays unchanged.
|
|
34
|
+
await privateManagedDirectory(join(dir, 'managed'));
|
|
35
|
+
const root = managedRoot(dir), path = join(root, 'runtime-transport.json'), before = readDescriptor(dir);
|
|
36
|
+
const value = { owner: OWNER, version: 1, framing: 'json-lines-v1', instanceId: owner.instanceId, pid: owner.pid, startedAt: owner.startedAt, tokenHash: createHash('sha256').update(owner.token).digest('hex') };
|
|
37
|
+
const temp = path + '.' + randomUUID() + '.tmp', identity = createPrivateFile(temp, JSON.stringify(value) + '\n');
|
|
38
|
+
try {
|
|
39
|
+
const current = readDescriptor(dir);
|
|
40
|
+
if (before ? (!current || !sameResource(before.identity, current.identity) || before.text !== current.text) : current !== null)
|
|
41
|
+
throw Error('CONTROL_TRANSPORT_CHANGED');
|
|
42
|
+
renameSync(temp, path);
|
|
43
|
+
if (process.platform !== 'win32') {
|
|
44
|
+
const fd = openSync(root, 'r');
|
|
45
|
+
try {
|
|
46
|
+
fsyncSync(fd);
|
|
47
|
+
}
|
|
48
|
+
finally {
|
|
49
|
+
closeSync(fd);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
return identity;
|
|
53
|
+
}
|
|
54
|
+
finally {
|
|
55
|
+
removeOwnedResource(temp, identity);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
export function removeControlTransport(dir, identity, owner) {
|
|
59
|
+
try {
|
|
60
|
+
const current = readDescriptor(dir);
|
|
61
|
+
if (!current || !sameResource(current.identity, identity) || !matches(current.value, owner))
|
|
62
|
+
return false;
|
|
63
|
+
return removeOwnedResource(join(managedRoot(dir), 'runtime-transport.json'), identity);
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
return false;
|
|
67
|
+
}
|
|
68
|
+
}
|
package/dist/control.js
CHANGED
|
@@ -3,6 +3,7 @@ import { randomBytes, randomUUID, timingSafeEqual, createHash } from 'node:crypt
|
|
|
3
3
|
import { join } from 'node:path';
|
|
4
4
|
import { chmodSync, renameSync, readdirSync } from 'node:fs';
|
|
5
5
|
import { assertStateRoot, createPrivateFile, hasCode, inspectResource, inspectRuntime, readRuntimeOwner, readRuntimeRecord, removeOwnedResource, runtimeMatches, RUNTIME_OWNER, sameResource, writePrivateAtomic } from './resources.js';
|
|
6
|
+
import { controlFraming, publishControlTransport, removeControlTransport } from './control-transport.js';
|
|
6
7
|
export function controlEndpoint(dir) { return process.platform === 'win32' ? '\\\\.\\pipe\\moremote-cli-' + createHash('sha256').update(dir).digest('hex').slice(0, 24) : join(dir, 'runtime.sock'); }
|
|
7
8
|
function object(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
|
|
8
9
|
function removeRuntimeFile(path, identity, owner, record = false) {
|
|
@@ -40,53 +41,95 @@ export async function requestControl(dir, action) {
|
|
|
40
41
|
return null;
|
|
41
42
|
const expectedRecord = resources.record.identity;
|
|
42
43
|
const record = resources.record.value;
|
|
44
|
+
const framing = controlFraming(dir, record);
|
|
45
|
+
if (framing === 'legacy-eof' && process.platform === 'win32') {
|
|
46
|
+
if (!running(record.pid))
|
|
47
|
+
return null;
|
|
48
|
+
throw Error('LEGACY_WINDOWS_CONTROL_UNAVAILABLE');
|
|
49
|
+
}
|
|
43
50
|
const ownerEnded = () => { const path = join(dir, 'runtime.json'); if (!inspectResource(path, 'file', true))
|
|
44
51
|
return true; const current = readRuntimeRecord(path); return !sameResource(current.identity, expectedRecord) || !runtimeMatches(current.value, record); };
|
|
45
|
-
const
|
|
52
|
+
const { promise, resolve, reject } = Promise.withResolvers();
|
|
53
|
+
const socket = createConnection(controlEndpoint(dir));
|
|
54
|
+
let raw = '', settled = false;
|
|
55
|
+
socket.setEncoding('utf8');
|
|
56
|
+
const succeed = (value) => { if (settled)
|
|
57
|
+
return; settled = true; clearTimeout(timer); socket.destroy(); resolve(value); };
|
|
58
|
+
const fail = (error) => { if (settled)
|
|
59
|
+
return; settled = true; clearTimeout(timer); socket.destroy(); reject(error); };
|
|
60
|
+
const disconnected = () => { if (settled)
|
|
61
|
+
return; if (raw) {
|
|
62
|
+
fail(Error('CONTROL_INVALID_RESPONSE'));
|
|
63
|
+
return;
|
|
64
|
+
} try {
|
|
46
65
|
if (ownerEnded())
|
|
47
|
-
|
|
66
|
+
succeed(null);
|
|
48
67
|
else
|
|
49
|
-
|
|
68
|
+
fail(Error('CONTROL_CONNECTION_CLOSED'));
|
|
50
69
|
}
|
|
51
70
|
catch (error) {
|
|
52
|
-
|
|
71
|
+
fail(error);
|
|
53
72
|
} };
|
|
54
|
-
const
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
73
|
+
const parseResponse = (frame) => { try {
|
|
74
|
+
const value = JSON.parse(frame);
|
|
75
|
+
if (!object(value))
|
|
76
|
+
throw Error('CONTROL_INVALID_RESPONSE');
|
|
77
|
+
succeed(value);
|
|
78
|
+
}
|
|
79
|
+
catch {
|
|
80
|
+
fail(Error('CONTROL_INVALID_RESPONSE'));
|
|
81
|
+
} };
|
|
82
|
+
const timer = setTimeout(() => fail(Error('CONTROL_TIMEOUT')), 2000);
|
|
58
83
|
socket.on('connect', () => {
|
|
59
84
|
try {
|
|
60
85
|
const current = inspectRuntime(dir);
|
|
61
86
|
if (!current.record || !sameResource(current.record.identity, expectedRecord) || !runtimeMatches(current.record.value, record))
|
|
62
87
|
throw Error('RUNTIME_RESOURCE_COLLISION');
|
|
63
|
-
|
|
88
|
+
if (controlFraming(dir, current.record.value) !== framing)
|
|
89
|
+
throw Error('CONTROL_TRANSPORT_CHANGED');
|
|
90
|
+
const payload = JSON.stringify({ token: record.token, action }) + '\n';
|
|
91
|
+
// The owned generation fact selects exactly one exchange, never a timeout
|
|
92
|
+
// probe/replay. Published 0.1.0 uses EOF; new named pipes remain duplex.
|
|
93
|
+
if (framing === 'legacy-eof')
|
|
94
|
+
socket.end(payload);
|
|
95
|
+
else
|
|
96
|
+
socket.write(payload);
|
|
64
97
|
}
|
|
65
98
|
catch (error) {
|
|
66
|
-
|
|
99
|
+
fail(error);
|
|
67
100
|
}
|
|
68
101
|
});
|
|
69
|
-
socket.on('data', chunk => {
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
102
|
+
socket.on('data', chunk => {
|
|
103
|
+
if (settled)
|
|
104
|
+
return;
|
|
105
|
+
raw += chunk;
|
|
106
|
+
if (Buffer.byteLength(raw) > 4096) {
|
|
107
|
+
fail(Error('CONTROL_LIMIT'));
|
|
108
|
+
return;
|
|
109
|
+
}
|
|
110
|
+
if (framing === 'legacy-eof')
|
|
111
|
+
return;
|
|
112
|
+
const end = raw.indexOf('\n');
|
|
113
|
+
if (end < 0)
|
|
114
|
+
return;
|
|
115
|
+
if (end !== raw.length - 1) {
|
|
116
|
+
fail(Error('CONTROL_INVALID_RESPONSE'));
|
|
117
|
+
return;
|
|
118
|
+
}
|
|
119
|
+
parseResponse(raw.slice(0, end));
|
|
120
|
+
});
|
|
121
|
+
socket.on('end', () => { if (framing === 'legacy-eof' && raw)
|
|
122
|
+
parseResponse(raw);
|
|
123
|
+
else
|
|
124
|
+
disconnected(); });
|
|
125
|
+
socket.on('close', disconnected);
|
|
126
|
+
socket.on('error', error => { if (settled)
|
|
127
|
+
return; if (hasCode(error, 'ECONNREFUSED') || hasCode(error, 'ENOENT'))
|
|
128
|
+
succeed(null);
|
|
86
129
|
else if (hasCode(error, 'ECONNRESET') || hasCode(error, 'EPIPE'))
|
|
87
130
|
disconnected();
|
|
88
131
|
else
|
|
89
|
-
|
|
132
|
+
fail(error); });
|
|
90
133
|
return promise;
|
|
91
134
|
}
|
|
92
135
|
function closeServer(server) {
|
|
@@ -138,36 +181,57 @@ export async function ownRuntime(dir, status, stop) {
|
|
|
138
181
|
const lockPath = join(dir, 'runtime.lock'), recordPath = join(dir, 'runtime.json');
|
|
139
182
|
let lock = createPrivateFile(lockPath, JSON.stringify(owner) + '\n');
|
|
140
183
|
const staging = process.platform === 'win32' ? endpoint : join(dir, 's.' + owner.instanceId.slice(0, 8));
|
|
141
|
-
let socketIdentity = null, recordIdentity = null;
|
|
184
|
+
let socketIdentity = null, recordIdentity = null, transportIdentity;
|
|
142
185
|
const server = createServer({ allowHalfOpen: true }, socket => {
|
|
143
|
-
let raw = '';
|
|
144
|
-
socket.
|
|
186
|
+
let raw = '', handled = false;
|
|
187
|
+
socket.setEncoding('utf8');
|
|
188
|
+
const timer = setTimeout(() => socket.destroy(), 2000);
|
|
189
|
+
socket.once('close', () => clearTimeout(timer));
|
|
145
190
|
socket.on('error', () => { });
|
|
146
|
-
socket.on('
|
|
147
|
-
|
|
148
|
-
|
|
191
|
+
socket.on('end', () => socket.destroy());
|
|
192
|
+
const reply = (value) => { const frame = JSON.stringify(value) + '\n'; if (Buffer.byteLength(frame) > 4096)
|
|
193
|
+
socket.destroy();
|
|
194
|
+
else
|
|
195
|
+
socket.write(frame); };
|
|
196
|
+
socket.on('data', chunk => {
|
|
197
|
+
if (handled) {
|
|
198
|
+
socket.destroy();
|
|
199
|
+
return;
|
|
200
|
+
}
|
|
201
|
+
raw += chunk;
|
|
202
|
+
if (Buffer.byteLength(raw) > 4096) {
|
|
203
|
+
handled = true;
|
|
204
|
+
socket.destroy();
|
|
205
|
+
return;
|
|
206
|
+
}
|
|
207
|
+
const end = raw.indexOf('\n');
|
|
208
|
+
if (end < 0)
|
|
209
|
+
return;
|
|
210
|
+
handled = true;
|
|
149
211
|
try {
|
|
150
|
-
|
|
212
|
+
if (end !== raw.length - 1)
|
|
213
|
+
throw Error('CONTROL_FRAME');
|
|
214
|
+
const request = JSON.parse(raw.slice(0, end));
|
|
151
215
|
if (!object(request) || typeof request.token !== 'string' || request.token.length !== 43)
|
|
152
216
|
throw Error('CONTROL_AUTH');
|
|
153
217
|
const left = Buffer.from(request.token), right = Buffer.from(owner.token);
|
|
154
218
|
if (left.length !== right.length || !timingSafeEqual(left, right))
|
|
155
219
|
throw Error('CONTROL_AUTH');
|
|
156
220
|
if (request.action === 'stop') {
|
|
157
|
-
socket.end(JSON.stringify({ ok: true, stopping: true }));
|
|
158
221
|
stop();
|
|
222
|
+
reply({ ok: true, stopping: true });
|
|
159
223
|
}
|
|
160
224
|
else if (request.action === 'status') {
|
|
161
225
|
const value = status();
|
|
162
226
|
if (!object(value))
|
|
163
227
|
throw Error('CONTROL_STATUS');
|
|
164
|
-
|
|
228
|
+
reply({ ok: true, ...value });
|
|
165
229
|
}
|
|
166
230
|
else
|
|
167
231
|
throw Error('CONTROL_ACTION');
|
|
168
232
|
}
|
|
169
233
|
catch {
|
|
170
|
-
|
|
234
|
+
reply({ ok: false });
|
|
171
235
|
}
|
|
172
236
|
});
|
|
173
237
|
});
|
|
@@ -196,6 +260,9 @@ export async function ownRuntime(dir, status, stop) {
|
|
|
196
260
|
renameSync(staging, endpoint);
|
|
197
261
|
socketIdentity = { dev: secured.dev, ino: secured.ino };
|
|
198
262
|
}
|
|
263
|
+
// Publish the generation fact durably before making its unchanged legacy-
|
|
264
|
+
// compatible record visible; readers can never select EOF for this record.
|
|
265
|
+
transportIdentity = await publishControlTransport(dir, owner);
|
|
199
266
|
recordIdentity = writePrivateAtomic(recordPath, { ...owner, socket: socketIdentity });
|
|
200
267
|
}
|
|
201
268
|
catch (error) {
|
|
@@ -204,6 +271,8 @@ export async function ownRuntime(dir, status, stop) {
|
|
|
204
271
|
removeOwnedResource(endpoint, socketIdentity, 'socket');
|
|
205
272
|
if (recordIdentity)
|
|
206
273
|
removeRuntimeFile(recordPath, recordIdentity, owner, true);
|
|
274
|
+
if (transportIdentity)
|
|
275
|
+
removeControlTransport(dir, transportIdentity, owner);
|
|
207
276
|
removeRuntimeFile(lockPath, lock, owner);
|
|
208
277
|
throw error;
|
|
209
278
|
}
|
|
@@ -220,6 +289,8 @@ export async function ownRuntime(dir, status, stop) {
|
|
|
220
289
|
if (recordIdentity)
|
|
221
290
|
removeRuntimeFile(recordPath, recordIdentity, owner, true);
|
|
222
291
|
removeRuntimeFile(lockPath, lock, owner);
|
|
292
|
+
if (transportIdentity)
|
|
293
|
+
removeControlTransport(dir, transportIdentity, owner);
|
|
223
294
|
})();
|
|
224
295
|
return closing;
|
|
225
296
|
};
|
package/docs/README.md
CHANGED
|
@@ -12,7 +12,7 @@ separately gated cloud/Apple activation.
|
|
|
12
12
|
- [Endpoint controls, occurrences and receipt lifecycle](specs/04-control-and-receipt-lifecycle.md)
|
|
13
13
|
- [Endpoint and lifecycle behavior](specs/05-endpoint-and-lifecycle.md)
|
|
14
14
|
- [Managed updates and compatibility](specs/06-managed-updates.md)
|
|
15
|
-
- [Public release and
|
|
15
|
+
- [Public release and existing publishing-secret prerequisites](releasing.md)
|
|
16
16
|
- [Managed-update decision](decisions/0001-managed-updates.md)
|
|
17
17
|
- [Managed-update implementation plan](plans/2026-11-10-managed-updates.md)
|
|
18
18
|
- [Configuration registry](configuration.md)
|
package/docs/STATE.md
CHANGED
|
@@ -31,8 +31,8 @@ remain separate gates.
|
|
|
31
31
|
## Managed updates and release — local acceptance complete
|
|
32
32
|
|
|
33
33
|
The owner authorized public scoped npm identity `@moxuli/moremote`, retained
|
|
34
|
-
private bootstrap/supervisor
|
|
35
|
-
|
|
34
|
+
private bootstrap/supervisor and cycle-safe automatic runtime activation.
|
|
35
|
+
Native service/state/executable identities remain unchanged.
|
|
36
36
|
See [decision](decisions/0001-managed-updates.md), [specification](specs/06-managed-updates.md),
|
|
37
37
|
[plan](plans/2026-11-10-managed-updates.md) and [publication prerequisites](releasing.md).
|
|
38
38
|
|
|
@@ -52,8 +52,31 @@ completed independent-context review is not represented as cross-vendor approval
|
|
|
52
52
|
Public GitHub repository `moxuli/moremote-cli` exists. The owner authorized the
|
|
53
53
|
first public0.1.0 release and reuse of an existing locally protected publishing
|
|
54
54
|
token; its npm identity is verified without disclosing the credential. No new
|
|
55
|
-
token or npm login is required.
|
|
56
|
-
|
|
55
|
+
token or npm login is required. Existing organization secret `NPM_TOKEN` is
|
|
56
|
+
restricted to this selected CLI repository; the release publish step reuses it.
|
|
57
|
+
Workstation0.1.0 publication is independently visible through the anonymous npm
|
|
58
|
+
registry. Published tarball SHA256 is
|
|
59
|
+
`6bf3cab16245745f5f9d43026687cff880ca081f106f195d6abe40a169c5efd6`;
|
|
60
|
+
registry SHA1 matches and a fresh exact public install runs version/help/
|
|
61
|
+
configure/status with cloud off, no runtime/pairs and no installed service.
|
|
62
|
+
Initial asynchronous404 processing was observed; publication was not repeated.
|
|
63
|
+
|
|
64
|
+
Hosted CI42821005843 accepts Ubuntu24.04 and macOS15 check/build/package-upgrade;
|
|
65
|
+
Windows2025 reports8control-transport failures (112pass/10explicit POSIX skips).
|
|
66
|
+
The correction is patch0.1.1: generation-bound transport selection preserves the
|
|
67
|
+
published strict runtime shape; framed peers avoid Windows half-close, while
|
|
68
|
+
known legacy POSIX transport is selected before exactly one write, never replayed.
|
|
69
|
+
Historical0.1.0 Windows EOF control remains explicitly unavailable/unknown;
|
|
70
|
+
managed stop requires real supervisor/runtime retirement evidence.
|
|
71
|
+
|
|
72
|
+
Final types,35focused control/lifecycle/CLI consumers, build and actual published
|
|
73
|
+
0.1.0 retained-bootstrap→0.1.1 archive upgrade pass. The latter verifies active/
|
|
74
|
+
previous selection, both transport generations, selected frontend and clean
|
|
75
|
+
shutdown without a service/cloud/official-data mutation. Independent review
|
|
76
|
+
closes the mixed-transport finding with no remaining actionable P1/P2 issue.
|
|
77
|
+
Hosted final Windows acceptance and tag publishing still need receiver results.
|
|
78
|
+
Environment `npm-release` has a `v*` tag-only deployment policy; no new secret
|
|
79
|
+
was created.
|
|
57
80
|
|
|
58
81
|
## Locally accepted implementation
|
|
59
82
|
|
|
@@ -14,6 +14,6 @@ Reject alternatives: global npm self-update (permission/package-manager ownershi
|
|
|
14
14
|
|
|
15
15
|
## Consequences
|
|
16
16
|
|
|
17
|
-
More disk is retained; the bootstrap's implementation remains fixed until explicit service maintenance. An update cannot force progress through a hung operation. This is preferable to corrupting authority or reporting false success. Package
|
|
17
|
+
More disk is retained; the bootstrap's implementation remains fixed until explicit service maintenance. An update cannot force progress through a hung operation. This is preferable to corrupting authority or reporting false success. Package publication, hosted release, OS service acceptance and physical APNs delivery remain distinct gates. Reuse the owner's existing selected-repository publishing secret; do not require new credentials or a web-only trust migration to release.
|
|
18
18
|
|
|
19
19
|
Contracts: [managed updates](../specs/06-managed-updates.md), [release prerequisites](../releasing.md), [plan](../plans/2026-11-10-managed-updates.md).
|
|
@@ -19,7 +19,7 @@ Activation queues a verified candidate. The supervisor requests a drain, never f
|
|
|
19
19
|
- `src/runtime.ts`: parent-only IPC drain at cycle boundary and readiness, preserve mutation/journal semantics.
|
|
20
20
|
- `src/cli.ts`: managed run/service/update/status/opt-out integration and installed-version reporting.
|
|
21
21
|
- `tests/updater.test.ts`: real state/install/handoff processes with synthetic packages, failure/concurrency/opt-out boundaries.
|
|
22
|
-
- `.github/workflows/{ci,release}.yml`, `scripts/release.mjs`: frozen Node24.13.0, exact identity/tag validation, deterministic tarball
|
|
22
|
+
- `.github/workflows/{ci,release}.yml`, `scripts/release.mjs`: frozen Node24.13.0, exact identity/tag validation, deterministic tarball and a least-privilege publishing step using the already-provisioned organization secret.
|
|
23
23
|
|
|
24
24
|
## Verification entrypoints (integration owner only)
|
|
25
25
|
|
package/docs/releasing.md
CHANGED
|
@@ -1,38 +1,34 @@
|
|
|
1
1
|
# Releasing @moxuli/moremote
|
|
2
2
|
|
|
3
|
-
Repository: public `moxuli/moremote-cli`; package: public `@moxuli/moremote`; executable: `moremote-cli`. No unscoped
|
|
3
|
+
Repository: public `moxuli/moremote-cli`; package: public `@moxuli/moremote`; executable: `moremote-cli`. No unscoped alias is published. Credentials never belong in this repository, release assets or package contents.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Existing publishing authority
|
|
6
6
|
|
|
7
|
-
The
|
|
7
|
+
The owner already provisioned organization secret `NPM_TOKEN`, restricted to this selected public CLI repository. Reuse that configuration. Do not create another token, require a new login, or block release on a web-only trusted-publisher migration. The workstation's protected publishing credential is separately loaded at point of use; do not echo it or commit an authenticated npm configuration.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The release job uses environment `npm-release`. Only its publish step receives the existing secret as `NODE_AUTH_TOKEN`; checks, dependency installation, builds and package scripts do not receive it. The temporary npm configuration contains the literal environment placeholder, pins both default and `@moxuli` registries to npmjs, has private permissions and is removed after publishing. No authentication file is packaged. Token authority/expiry and required interactive provider checks still apply; never bypass them or claim acceptance from a valid identity read alone.
|
|
10
10
|
|
|
11
|
-
-
|
|
12
|
-
- workflow filename **`release.yml`** (not its full path);
|
|
13
|
-
- environment **`npm-release`**;
|
|
14
|
-
- permit **direct `npm publish`** (current npm defaults may allow staged publish only).
|
|
15
|
-
|
|
16
|
-
Create the matching GitHub environment, restrict it to protected release tags and add required reviewers if desired. Configure tag protection/Rulesets so only authorized maintainers can create release tags. A newly created npm trusted-publisher configuration must complete its first successful publish within the current documented two-day validation window; recreate an expired configuration rather than adding a long-lived secret fallback. For the first OIDC release, bump to a genuinely new version (for example0.1.1); npm versions cannot be overwritten. After successful OIDC publication, require2FA and disallow traditional tokens in npm publishing access, and separately revoke unused automation tokens under owner authorization. Existing organization secrets are not consumed by these workflows.
|
|
11
|
+
Configure the release environment to accept authorized `v*` tags. Branch/tag protection and required reviewers remain owner-governed settings. Token replacement/revocation is a separate account action. npm trusted publishing remains an optional future migration, not an additional prerequisite for the current owner's existing setup.
|
|
17
12
|
|
|
18
13
|
## Normal release
|
|
19
14
|
|
|
20
|
-
1. Keep dependencies pinned
|
|
21
|
-
2. Review public
|
|
22
|
-
3. The
|
|
23
|
-
4. Only after npm publication
|
|
24
|
-
5. If npm
|
|
15
|
+
1. Keep dependencies pinned. Preserve the compatibility tuple only when storage/wire rollback is genuinely safe. On Node24.13.0 run `npm ci --ignore-scripts`, `npm run check`, `npm run smoke:upgrade`, `node scripts/release.mjs validate vX.Y.Z` and `node scripts/release.mjs pack vX.Y.Z`.
|
|
16
|
+
2. Review public contents and changelog. Update package.json and only lockfile root versions, commit through review, then push the exact owner-authorized stable `vX.Y.Z` tag. Prerelease/range/mismatched tags fail closed. Generated tarballs/SHA256SUMS are release outputs, not tracked source.
|
|
17
|
+
3. The GitHub-hosted Ubuntu24.04 job validates repository/tag/package/lock identity, checks/builds and produces two byte-identical packs. It publishes the exact tested tarball with the existing scoped secret, public access and GitHub provenance. Node24.13.0 is pinned; no global toolchain upgrade occurs.
|
|
18
|
+
4. Only after npm accepts publication does the job create a GitHub Release with the identical tarball and SHA256SUMS. Release concurrency is serialized and never cancels an in-flight publish. Only this job receives contents:write/id-token:write for release/provenance; ordinary CI is contents:read. Checkout credentials are not persisted and release builds use no cache.
|
|
19
|
+
5. If npm fails, no successful GitHub Release is created. If npm accepted but GitHub creation failed, **do not republish or retag**: recover the exact published bytes, validate integrity against the accepted build artifact/checksum, and recover the GitHub Release under the owner's release authorization. npm versions are immutable.
|
|
20
|
+
6. npm can acknowledge submission while processing a new package. Require an independent anonymous registry read and installation of the public exact version before claiming availability. Do not repeatedly republish while processing. Record the receiver result in STATE.
|
|
25
21
|
|
|
26
|
-
|
|
22
|
+
The first workstation bootstrap publication is0.1.0. Subsequent automated releases must use a genuinely new version; neither workflow reruns nor corrected documentation can replace published0.1.0 bytes.
|
|
27
23
|
|
|
28
|
-
|
|
24
|
+
CI also runs portable behavior and isolated real packaged-upgrade smoke on macOS/Linux/Windows. It never installs a real login service. Native platform managers and physical APNs are separate acceptance gates.
|
|
29
25
|
|
|
30
|
-
|
|
26
|
+
## Verified action pins and primary sources
|
|
31
27
|
|
|
32
|
-
- [`actions/checkout` v6.0.2](https://github.com/actions/checkout/tree/de0fac2e4500dabe0009e67214ff5f5447ce83dd):
|
|
33
|
-
- [`actions/setup-node` v6.1.0](https://github.com/actions/setup-node/tree/395ad3262231945c25e8478fd5baf05154b1d79f):
|
|
34
|
-
- [
|
|
35
|
-
- [
|
|
36
|
-
- [
|
|
28
|
+
- [`actions/checkout` v6.0.2](https://github.com/actions/checkout/tree/de0fac2e4500dabe0009e67214ff5f5447ce83dd): resolved official tag.
|
|
29
|
+
- [`actions/setup-node` v6.1.0](https://github.com/actions/setup-node/tree/395ad3262231945c25e8478fd5baf05154b1d79f): resolved official tag.
|
|
30
|
+
- [GitHub publishing Node packages](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages): scoped public publishing, token use and provenance.
|
|
31
|
+
- [npm provenance](https://docs.npmjs.com/generating-provenance-statements): hosted build identity is separate from npm publishing authority.
|
|
32
|
+
- [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/): optional future short-lived authentication migration.
|
|
37
33
|
|
|
38
|
-
|
|
34
|
+
Never infer a registry package, hosted workflow result, release or protection setting from checked-in YAML alone. Record only exercised facts, without private accounts or credential values.
|
|
@@ -16,6 +16,12 @@ Readiness observers use the runtime's positive parent IPC acknowledgement after
|
|
|
16
16
|
|
|
17
17
|
An empty control EOF or reset is `CONTROL_CONNECTION_CLOSED` while the previously validated owner still exists, not a raw JSON parser exception or a successful stop. A malformed/nonobject reply is `CONTROL_INVALID_RESPONSE`. Only observed retirement/replacement of that exact validated record can classify an empty disconnect as not-running. No control or official mutation is retried because of a lost reply.
|
|
18
18
|
|
|
19
|
+
Ephemeral control transport compatibility: `managed/runtime-transport.json` is a marked version1, private/no-follow descriptor binding `json-lines-v1` to instanceId, pid, startedAt and SHA256(token). It is durably published before the runtime record. The original strict runtime.lock/runtime.json shapes remain unchanged, so retained0.1.0 readers and crash recovery can still read them; the existing marked managed directory contains the additional descriptor. Cleanup removes only the matching descriptor inode/generation.
|
|
20
|
+
|
|
21
|
+
The controller chooses one transport from that fact before sending: a matching descriptor means bounded4KiB newline frames and a duplex connection; no descriptor or a valid descriptor from another generation means the known0.1.0 EOF/unframed transport on POSIX. Invalid/linked/foreign descriptors are terminal, not an excuse to guess or probe. Ownership and selected framing are revalidated immediately before the single write. There is no timeout-based fallback, second connection or action replay.
|
|
22
|
+
|
|
23
|
+
Historical Windows boundary: unchanged published0.1.0 EOF-only control cannot provide a reliable duplex named-pipe reply. A live such generation reports `LEGACY_WINDOWS_CONTROL_UNAVAILABLE`, never fake status/stopped. It remains an explicit selectable candidate. The retained supervisor's separate child IPC can still drain, roll back or stop it. A managed stop waits for supervisor retirement and positive runtime retirement evidence before reporting success; an unsupervised live historical runtime remains unavailable/unknown. New framed runtimes retain full Windows support. An absent PID or retired record is evidence, not permission to signal an arbitrary PID.
|
|
24
|
+
|
|
19
25
|
The first installed-package `run` or explicit service installation obtains its exact current version into `managed/versions/<version>/node_modules/@moxuli/moremote`. Lifecycle scripts are disabled. npm network retries are disabled, fetches have a60second limit and installation has a120second process limit. Package name/version, ordinary nonsymlinked build/entry files and directory ownership are verified before an atomic staging rename. Existing version directories are immutable and reverified. Failed installations never change selection. There is no global npm self-overwrite or sudo.
|
|
20
26
|
|
|
21
27
|
## Durable selection and bounded discovery
|
|
@@ -45,5 +51,5 @@ The packaged smoke explicitly invokes the old frontend through a parent-director
|
|
|
45
51
|
## Official design references
|
|
46
52
|
|
|
47
53
|
- [Claude Code update behavior and package-manager boundaries](https://code.claude.com/docs/en/setup#update-claude-code): background checks, next-start activation, diagnostic visibility, opt-out; native versus Homebrew/WinGet/OS-package manager boundaries. This project borrows the owned-version/launcher boundary, not Claude's installer or global package-manager upgrade behavior. Our continuously running consumer needs an explicit cycle-safe handoff rather than a silent session restart.
|
|
48
|
-
- [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/):
|
|
49
|
-
- [GitHub Node package publication](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages): exact
|
|
54
|
+
- [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/): an optional future authentication migration, not a prerequisite for the owner's existing organization publishing secret.
|
|
55
|
+
- [GitHub Node package publication](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages): exact identity, scoped public access and build-before-publish/provenance. Existing `NPM_TOKEN` is available only to this selected public repository and exposed as `NODE_AUTH_TOKEN` only during its release publish step.
|