owenloop 0.5.0 → 0.5.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/CHANGELOG.md +45 -0
- package/README.md +137 -35
- package/bin/owenloop.mjs +49 -1
- package/dist/packages/work/src/agent/brief.d.ts +8 -4
- package/dist/packages/work/src/agent/brief.js +7 -3
- package/dist/packages/work/src/agent/loop.d.ts +13 -7
- package/dist/packages/work/src/agent/loop.js +136 -9
- package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
- package/dist/packages/work/src/agent/model-policy.js +138 -0
- package/dist/packages/work/src/bundle/cache.d.ts +7 -5
- package/dist/packages/work/src/bundle/cache.js +20 -6
- package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
- package/dist/packages/work/src/bundle/fetch.js +27 -7
- package/dist/packages/work/src/bundle/types.d.ts +8 -4
- package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
- package/dist/packages/work/src/consumed-verifier.js +205 -0
- package/dist/packages/work/src/exec/instructions.d.ts +99 -0
- package/dist/packages/work/src/exec/instructions.js +323 -0
- package/dist/packages/work/src/exec/loop.d.ts +12 -1
- package/dist/packages/work/src/exec/loop.js +137 -20
- package/dist/packages/work/src/exec/payload.d.ts +29 -0
- package/dist/packages/work/src/exec/payload.js +54 -0
- package/dist/packages/work/src/exec/receipt.d.ts +9 -6
- package/dist/packages/work/src/exec/receipt.js +12 -1
- package/dist/packages/work/src/exec/runner.d.ts +7 -1
- package/dist/packages/work/src/exec/runner.js +74 -3
- package/dist/packages/work/src/harness/child-env.js +7 -0
- package/dist/packages/work/src/harness/claude.d.ts +20 -8
- package/dist/packages/work/src/harness/claude.js +260 -58
- package/dist/packages/work/src/harness/codex.d.ts +5 -4
- package/dist/packages/work/src/harness/codex.js +169 -41
- package/dist/packages/work/src/harness/contract.d.ts +36 -11
- package/dist/packages/work/src/harness/fake.js +1 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
- package/dist/packages/work/src/harness/permissions.d.ts +16 -3
- package/dist/packages/work/src/harness/permissions.js +102 -13
- package/dist/packages/work/src/harness/session-store.d.ts +27 -9
- package/dist/packages/work/src/harness/session-store.js +271 -67
- package/dist/packages/work/src/hold/mcp.d.ts +25 -5
- package/dist/packages/work/src/hold/mcp.js +126 -11
- package/dist/packages/work/src/hub/client.d.ts +2 -1
- package/dist/packages/work/src/hub/client.js +14 -1
- package/dist/packages/work/src/hub/types.d.ts +69 -33
- package/dist/packages/work/src/hub/types.js +8 -10
- package/dist/packages/work/src/mcp/server.js +1 -1
- package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
- package/dist/packages/work/src/owenloop-bin.js +18 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
- package/dist/packages/work/src/roles/agent-run.js +116 -34
- package/dist/packages/work/src/roles/exec.d.ts +8 -0
- package/dist/packages/work/src/roles/exec.js +27 -2
- package/dist/packages/work/src/roles/hold.d.ts +4 -0
- package/dist/packages/work/src/roles/hold.js +44 -5
- package/dist/packages/work/src/roles/lint.d.ts +3 -4
- package/dist/packages/work/src/roles/lint.js +41 -7
- package/dist/packages/work/src/roles/settings.js +5 -0
- package/dist/packages/work/src/roles/shift.d.ts +1 -0
- package/dist/packages/work/src/roles/shift.js +23 -1
- package/dist/packages/work/src/settings/settings.d.ts +17 -1
- package/dist/packages/work/src/settings/settings.js +39 -0
- package/dist/packages/work/src/shift/loop.d.ts +14 -3
- package/dist/packages/work/src/shift/loop.js +447 -164
- package/dist/packages/work/src/shift/protocol.d.ts +4 -0
- package/dist/packages/work/src/shift/runtime.d.ts +2 -0
- package/dist/packages/work/src/shift/runtime.js +66 -3
- package/dist/packages/work/src/shift/spawn.d.ts +41 -18
- package/dist/packages/work/src/shift/spawn.js +89 -31
- package/dist/packages/work/src/shift/state.d.ts +53 -51
- package/dist/packages/work/src/shift/state.js +325 -102
- package/dist/packages/work/src/submit-proof.d.ts +36 -0
- package/dist/packages/work/src/submit-proof.js +93 -0
- package/dist/src/add.d.ts +64 -259
- package/dist/src/add.js +81 -615
- package/dist/src/archive.d.ts +97 -0
- package/dist/src/archive.js +591 -0
- package/dist/src/bundle/index.d.ts +64 -0
- package/dist/src/bundle/index.js +508 -0
- package/dist/src/bundle/manifest.d.ts +50 -0
- package/dist/src/bundle/manifest.js +435 -0
- package/dist/src/bundle/runtime.d.ts +26 -0
- package/dist/src/bundle/runtime.js +64 -0
- package/dist/src/bundle/tar.d.ts +62 -0
- package/dist/src/bundle/tar.js +238 -0
- package/dist/src/bundle/types.d.ts +105 -0
- package/dist/src/bundle/types.js +21 -0
- package/dist/src/cli.d.ts +90 -20
- package/dist/src/cli.js +2407 -365
- package/dist/src/credentials.d.ts +4 -3
- package/dist/src/credentials.js +21 -19
- package/dist/src/crypto/allowed-signers.d.ts +68 -0
- package/dist/src/crypto/allowed-signers.js +307 -0
- package/dist/src/crypto/canonical.d.ts +8 -0
- package/dist/src/crypto/canonical.js +92 -0
- package/dist/src/crypto/chain.d.ts +65 -0
- package/dist/src/crypto/chain.js +377 -0
- package/dist/src/crypto/dsse.d.ts +209 -0
- package/dist/src/crypto/dsse.js +282 -0
- package/dist/src/crypto/enrollment.d.ts +78 -0
- package/dist/src/crypto/enrollment.js +186 -0
- package/dist/src/crypto/index.d.ts +48 -0
- package/dist/src/crypto/index.js +44 -0
- package/dist/src/crypto/keys.d.ts +258 -0
- package/dist/src/crypto/keys.js +908 -0
- package/dist/src/crypto/org-root.d.ts +33 -0
- package/dist/src/crypto/org-root.js +78 -0
- package/dist/src/crypto/origin-rules.d.ts +56 -0
- package/dist/src/crypto/origin-rules.js +143 -0
- package/dist/src/crypto/policy-floor.d.ts +98 -0
- package/dist/src/crypto/policy-floor.js +353 -0
- package/dist/src/crypto/records.d.ts +316 -0
- package/dist/src/crypto/records.js +157 -0
- package/dist/src/crypto/scope.d.ts +49 -0
- package/dist/src/crypto/scope.js +83 -0
- package/dist/src/crypto/ssh.d.ts +171 -0
- package/dist/src/crypto/ssh.js +396 -0
- package/dist/src/crypto/submission.d.ts +33 -0
- package/dist/src/crypto/submission.js +47 -0
- package/dist/src/crypto/trust-roots.d.ts +29 -0
- package/dist/src/crypto/trust-roots.js +39 -0
- package/dist/src/crypto/verify-consumed.d.ts +67 -0
- package/dist/src/crypto/verify-consumed.js +259 -0
- package/dist/src/crypto/verify-origin.d.ts +50 -0
- package/dist/src/crypto/verify-origin.js +151 -0
- package/dist/src/crypto/verify-publication.d.ts +60 -0
- package/dist/src/crypto/verify-publication.js +150 -0
- package/dist/src/defs.d.ts +24 -1
- package/dist/src/defs.js +145 -25
- package/dist/src/engine.d.ts +99 -3
- package/dist/src/engine.js +238 -34
- package/dist/src/factory.d.ts +16 -0
- package/dist/src/factory.js +16 -4
- package/dist/src/global-config.d.ts +59 -0
- package/dist/src/global-config.js +84 -0
- package/dist/src/hub.d.ts +75 -21
- package/dist/src/hub.js +123 -40
- package/dist/src/index.d.ts +17 -2
- package/dist/src/index.js +20 -2
- package/dist/src/install.d.ts +538 -0
- package/dist/src/install.js +1981 -0
- package/dist/src/lock.d.ts +15 -57
- package/dist/src/lock.js +251 -143
- package/dist/src/mcp/serve.d.ts +46 -22
- package/dist/src/mcp/serve.js +167 -44
- package/dist/src/mcp/server.js +12 -1
- package/dist/src/model.d.ts +15 -0
- package/dist/src/model.js +111 -1
- package/dist/src/order-resolver.d.ts +184 -0
- package/dist/src/order-resolver.js +252 -0
- package/dist/src/package-version.d.ts +10 -0
- package/dist/src/package-version.js +42 -0
- package/dist/src/paths.d.ts +14 -1
- package/dist/src/paths.js +18 -0
- package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
- package/dist/src/schemas/index.d.ts +1416 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +106 -0
- package/dist/src/schemas/origin.v1.schema.json +68 -0
- package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
- package/dist/src/schemas/publication.v1.schema.json +31 -0
- package/dist/src/schemas/revocation.v1.schema.json +39 -0
- package/dist/src/schemas/submission.v1.schema.json +61 -0
- package/dist/src/store/def-source.d.ts +52 -0
- package/dist/src/store/def-source.js +335 -0
- package/dist/src/store/index-file.d.ts +69 -0
- package/dist/src/store/index-file.js +151 -0
- package/dist/src/store/index.d.ts +27 -0
- package/dist/src/store/index.js +22 -0
- package/dist/src/store/ingestor.d.ts +43 -0
- package/dist/src/store/ingestor.js +211 -0
- package/dist/src/store/install.d.ts +228 -0
- package/dist/src/store/install.js +555 -0
- package/dist/src/store/instruction-source.d.ts +49 -0
- package/dist/src/store/instruction-source.js +298 -0
- package/dist/src/store/origin-evidence.d.ts +21 -0
- package/dist/src/store/origin-evidence.js +66 -0
- package/dist/src/store/pre-commit-verifier.d.ts +68 -0
- package/dist/src/store/pre-commit-verifier.js +418 -0
- package/dist/src/store/resolve.d.ts +138 -0
- package/dist/src/store/resolve.js +363 -0
- package/dist/src/store/types.d.ts +288 -0
- package/dist/src/store/types.js +356 -0
- package/dist/src/types.d.ts +45 -11
- package/dist/src/untar.d.ts +8 -23
- package/dist/src/untar.js +10 -136
- package/docs/agent-runner.md +86 -0
- package/docs/authoring.md +57 -6
- package/docs/bundles.md +250 -0
- package/docs/cli.md +1171 -97
- package/docs/crypto.md +816 -0
- package/docs/design.md +342 -20
- package/docs/embedding.md +132 -25
- package/docs/wire-contracts.md +380 -0
- package/package.json +6 -1
- package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
- package/plugins/claude-code/plugin/.mcp.json +14 -0
- package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
- package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
- package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
- package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
- package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
- package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
- package/plugins/codex/.agents/plugins/marketplace.json +21 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
- package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
- package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
- package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
- package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
- package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
- package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
package/dist/src/add.js
CHANGED
|
@@ -1,71 +1,29 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
2
|
+
* The GitHub route for `owenloop add <owner>/<repo>[@ref]`: spec parsing, URL
|
|
3
|
+
* building, the `installed.json` ledger, old-name migration parking, and the
|
|
4
|
+
* v1 crash-recovery adapter. The host-neutral filesystem transaction this
|
|
5
|
+
* route rides on — safe staging, the atomic swap with a retained backup,
|
|
6
|
+
* finalize/rollback, the atomic metadata write, the install lock, and the
|
|
7
|
+
* two-phase journal + recovery — lives in `src/install.ts` (engine core);
|
|
8
|
+
* this module keeps only what is GitHub-specific and re-exports the shared
|
|
9
|
+
* names callers and tests have always imported from here.
|
|
5
10
|
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
* arg glue live in `src/cli.ts` (`dispatchAdd`) so this module stays trivially
|
|
9
|
-
* unit-testable and `cli.ts` doesn't widen its export surface just to reuse
|
|
10
|
-
* `Args`/`CliError`/etc.
|
|
11
|
+
* The network fetch and arg glue live in `src/cli.ts` (`dispatchAdd`) so this
|
|
12
|
+
* module stays trivially unit-testable.
|
|
11
13
|
*/
|
|
12
|
-
import { existsSync, lstatSync,
|
|
13
|
-
import {
|
|
14
|
+
import { existsSync, lstatSync, readFileSync, renameSync, rmSync } from 'node:fs';
|
|
15
|
+
import { join, resolve, sep } from 'node:path';
|
|
14
16
|
import { createHash } from 'node:crypto';
|
|
15
|
-
import {
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
*/
|
|
26
|
-
export function archivePathViolation(relPath) {
|
|
27
|
-
if (relPath === '')
|
|
28
|
-
return 'empty path';
|
|
29
|
-
if (relPath.includes('\0'))
|
|
30
|
-
return 'contains a NUL byte';
|
|
31
|
-
if (isAbsolute(relPath) || /^[\\/]/.test(relPath) || /^[A-Za-z]:/.test(relPath)) {
|
|
32
|
-
return 'is an absolute path';
|
|
33
|
-
}
|
|
34
|
-
// Split on both separators so '..\\' tricks and doubled separators can't
|
|
35
|
-
// smuggle a traversal segment past the check.
|
|
36
|
-
const segments = relPath.split(/[\\/]+/);
|
|
37
|
-
if (segments.some((s) => s === '.' || s === '..')) {
|
|
38
|
-
return "contains a '.' or '..' segment";
|
|
39
|
-
}
|
|
40
|
-
if (relPath.length > MAX_ARCHIVE_PATH_LENGTH) {
|
|
41
|
-
return `exceeds ${MAX_ARCHIVE_PATH_LENGTH}-char path length limit`;
|
|
42
|
-
}
|
|
43
|
-
return undefined;
|
|
44
|
-
}
|
|
45
|
-
/**
|
|
46
|
-
* Returns `undefined` if `relPath` is a safe SINGLE-SEGMENT lockfile install
|
|
47
|
-
* path, else a human-readable reason it must be rejected. Stricter than
|
|
48
|
-
* {@link archivePathViolation}: a lockfile entry's `path` is one on-disk path
|
|
49
|
-
* segment by construction — both the current `<owner>-<repo>-<hash>` scheme and
|
|
50
|
-
* the only legacy scheme this tool ever wrote (`<owner>-<repo>`, see
|
|
51
|
-
* {@link installFolder}) — so ANY separator is refused outright. That single
|
|
52
|
-
* rule makes `..` traversal, `.owenloop/../../x`, and nested escape shapes
|
|
53
|
-
* unrepresentable before any `join`/`rename` ever touches the path. Like
|
|
54
|
-
* `archivePathViolation` this is reject-don't-normalize: a bad path is refused,
|
|
55
|
-
* never canonicalized into a "safe" one.
|
|
56
|
-
*/
|
|
57
|
-
export function lockfilePathViolation(relPath) {
|
|
58
|
-
// Reuse the shared checks (empty, NUL, absolute, '.'/'..' segments, length).
|
|
59
|
-
const base = archivePathViolation(relPath);
|
|
60
|
-
if (base)
|
|
61
|
-
return base;
|
|
62
|
-
// A lockfile install path additionally must be a single segment: no
|
|
63
|
-
// separators at all, so a multi-segment on-disk path like 'legacy/olddir'
|
|
64
|
-
// (which passes archivePathViolation) is still refused here.
|
|
65
|
-
if (/[\\/]/.test(relPath))
|
|
66
|
-
return 'contains a path separator';
|
|
67
|
-
return undefined;
|
|
68
|
-
}
|
|
17
|
+
import { commitInstall as commitInstallGeneric, finalizeInstallCommit as finalizeInstallCommitGeneric, acquireInstallLock as acquireInstallLockGeneric, lockfilePathViolation, archivePathViolation, recoverInterruptedInstall as recoverInterruptedInstallGeneric, rollbackInstallCommit as rollbackInstallCommitGeneric, writeJsonAtomic, } from "./install.js";
|
|
18
|
+
// Re-export the shared transaction surface under the names callers/tests have
|
|
19
|
+
// always imported from this module (the move to src/install.ts was
|
|
20
|
+
// logic-preserving). `finalizeInstallCommit` and `rollbackInstallCommit` are
|
|
21
|
+
// NOT re-exported: this module defines the GitHub-aware versions — they also
|
|
22
|
+
// handle the parked old-name dir, which the generic ones do not know about —
|
|
23
|
+
// and they shadow the generic versions.
|
|
24
|
+
export { archivePathViolation, lockfilePathViolation, stageFiles, rmRecursiveForce, RollbackFailedError, STAGING_DIRNAME, ADD_JOURNAL_FILENAME, releaseInstallLock, validateAddJournal, readAddJournal, writeAddJournal, removeAddJournal, } from "./install.js";
|
|
25
|
+
/** GitHub-legal (superset) charset for an owner/repo name — see `parseRepoSpec`. */
|
|
26
|
+
const REPO_NAME_RE = /^[A-Za-z0-9._-]+$/;
|
|
69
27
|
/** Parse `owner/repo` or `owner/repo@ref` into its parts; `ref` defaults to `'HEAD'`. */
|
|
70
28
|
export function parseRepoSpec(spec) {
|
|
71
29
|
const atIdx = spec.lastIndexOf('@');
|
|
@@ -95,8 +53,6 @@ export function parseRepoSpec(spec) {
|
|
|
95
53
|
}
|
|
96
54
|
return { owner, repo, ref };
|
|
97
55
|
}
|
|
98
|
-
/** GitHub-legal (superset) charset for an owner/repo name — see `parseRepoSpec`. */
|
|
99
|
-
const REPO_NAME_RE = /^[A-Za-z0-9._-]+$/;
|
|
100
56
|
/**
|
|
101
57
|
* The single-path-segment install folder for a package, derived from its
|
|
102
58
|
* `owner/repo` identity: `<owner>-<repo>-<sha256(owner/repo)[:8]>`. The 8-hex
|
|
@@ -125,16 +81,16 @@ function isPlainObject(value) {
|
|
|
125
81
|
* Structurally validate a parsed `installed.json`, fail-closed. A
|
|
126
82
|
* parseable-but-schema-invalid lockfile is a hard error naming the offending
|
|
127
83
|
* entry+field — never silently reset to `{}` (which would erase ownership
|
|
128
|
-
* records and re-enable the clobbering
|
|
129
|
-
*
|
|
84
|
+
* records and re-enable the clobbering `installFolder` was hardened against)
|
|
85
|
+
* and never normalized. This is the trust boundary for the lockfile:
|
|
130
86
|
* downstream code (`dispatchAdd`, `parkOldNameDir`) may only act on entries
|
|
131
87
|
* that have passed through here. Critically, EVERY entry is validated, not just
|
|
132
88
|
* the one being installed — `dispatchAdd` re-serializes the whole lockfile on
|
|
133
89
|
* success, so acting while carrying a poisoned sibling entry would re-persist
|
|
134
90
|
* it. Unknown extra keys (on the lockfile or an entry) are tolerated for
|
|
135
91
|
* forward compatibility; required shape is enforced, additions are not
|
|
136
|
-
* forbidden. Returns the value narrowed to
|
|
137
|
-
*
|
|
92
|
+
* forbidden. Returns the value narrowed to `Lockfile`. `path` appears only in
|
|
93
|
+
* error messages.
|
|
138
94
|
*/
|
|
139
95
|
export function validateLockfile(parsed, path) {
|
|
140
96
|
const fail = (detail) => {
|
|
@@ -190,7 +146,7 @@ export function validateLockfile(parsed, path) {
|
|
|
190
146
|
* re-enable the clobbering `installFolder` was hardened against. A file that
|
|
191
147
|
* parses but is structurally invalid (bad version, malformed entry, a `path`
|
|
192
148
|
* that is not a safe single segment, a bad `sha`/`files`) is likewise a
|
|
193
|
-
* fail-closed hard error — see
|
|
149
|
+
* fail-closed hard error — see `validateLockfile`. The lockfile is never
|
|
194
150
|
* trusted for filesystem paths.
|
|
195
151
|
*/
|
|
196
152
|
export function readLockfile(path) {
|
|
@@ -207,139 +163,26 @@ export function readLockfile(path) {
|
|
|
207
163
|
return validateLockfile(parsed, path);
|
|
208
164
|
}
|
|
209
165
|
/**
|
|
210
|
-
*
|
|
211
|
-
* over
|
|
212
|
-
*
|
|
213
|
-
*
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
* directory).
|
|
217
|
-
*
|
|
218
|
-
* If the final `renameSync` throws (EACCES, EISDIR on `path`, a full disk), the
|
|
219
|
-
* temp sibling is removed on a best-effort basis before the error propagates so
|
|
220
|
-
* a failed write cannot leak a `<path>.tmp.<pid>` file. The original rename
|
|
221
|
-
* error is surfaced unchanged — never swallowed, and never masked by a failure
|
|
222
|
-
* of that cleanup removal (if the removal itself throws, that error is swallowed
|
|
223
|
-
* and the tmp sibling may remain in that double fault).
|
|
166
|
+
* Write the lockfile atomically: serialize into a sibling temp file, then
|
|
167
|
+
* rename over the destination — the shared atomic tmp+rename discipline from
|
|
168
|
+
* `src/install.ts`. A crash or a concurrent reader never sees a half-written
|
|
169
|
+
* `installed.json`, and two racing writers can only ever leave a fully-formed
|
|
170
|
+
* file. On a failed rename the temp sibling is removed best-effort and the
|
|
171
|
+
* ORIGINAL rename error is surfaced unchanged.
|
|
224
172
|
*/
|
|
225
|
-
function writeJsonAtomic(path, value, opts = {}) {
|
|
226
|
-
const rm = opts.rm ?? ((p, o) => rmSync(p, o));
|
|
227
|
-
mkdirSync(dirname(path), { recursive: true });
|
|
228
|
-
const tmp = `${path}.tmp.${process.pid}`;
|
|
229
|
-
writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
|
|
230
|
-
try {
|
|
231
|
-
renameSync(tmp, path);
|
|
232
|
-
}
|
|
233
|
-
catch (e) {
|
|
234
|
-
// Best-effort cleanup: the temp sibling should not leak on a failed write,
|
|
235
|
-
// but if the removal ITSELF throws (e.g. unlink EACCES) we must not let that
|
|
236
|
-
// replace the original rename error — swallow the cleanup error and rethrow
|
|
237
|
-
// `e`. A tmp sibling may survive in that double fault.
|
|
238
|
-
try {
|
|
239
|
-
rm(tmp, { force: true });
|
|
240
|
-
}
|
|
241
|
-
catch {
|
|
242
|
-
// ignore — surfacing the original rename error matters more than cleanup.
|
|
243
|
-
}
|
|
244
|
-
throw e;
|
|
245
|
-
}
|
|
246
|
-
}
|
|
247
173
|
export function writeLockfile(path, lf, opts = {}) {
|
|
248
174
|
writeJsonAtomic(path, lf, opts);
|
|
249
175
|
}
|
|
250
|
-
// ---- staging + atomic commit -----------------------------------------------
|
|
251
|
-
/** The staging root under a defs dir where installs are assembled + validated. */
|
|
252
|
-
export const STAGING_DIRNAME = '.owenloop-staging';
|
|
253
|
-
/**
|
|
254
|
-
* Write `files` (relative path → bytes) into `targetDir` (a staging dir), NOT
|
|
255
|
-
* the final install destination. Unlike a direct install, this never clears a
|
|
256
|
-
* live folder: the caller stages here, validates, then `commitInstall`s with an
|
|
257
|
-
* atomic rename, so a failure mid-write can only ever corrupt throwaway staging
|
|
258
|
-
* content. Returns the sorted list of relative paths written.
|
|
259
|
-
*/
|
|
260
|
-
export function stageFiles(targetDir, files) {
|
|
261
|
-
const written = [];
|
|
262
|
-
for (const [relPath, bytes] of files) {
|
|
263
|
-
// Defense-in-depth: this function is exported and writes whole directory
|
|
264
|
-
// trees, so it must not trust its caller to have validated keys.
|
|
265
|
-
const violation = archivePathViolation(relPath);
|
|
266
|
-
if (violation) {
|
|
267
|
-
throw new Error(`refusing to write unsafe archive path '${relPath}': ${violation}`);
|
|
268
|
-
}
|
|
269
|
-
const full = join(targetDir, relPath);
|
|
270
|
-
mkdirSync(dirname(full), { recursive: true });
|
|
271
|
-
writeFileSync(full, bytes);
|
|
272
|
-
written.push(relPath);
|
|
273
|
-
}
|
|
274
|
-
return written.sort();
|
|
275
|
-
}
|
|
276
|
-
/**
|
|
277
|
-
* Thrown by `commitInstall` when the atomic swap fails AND the rollback of it
|
|
278
|
-
* fails too — a near-impossible same-filesystem double-fault. Carries the path
|
|
279
|
-
* where the previous version was left so the caller can preserve it (its
|
|
280
|
-
* `preservedAt` sits under the staging root, which the caller would otherwise
|
|
281
|
-
* clean up as debris). A distinguishable type so the caller can tell this
|
|
282
|
-
* "must-preserve" double-fault apart from an ordinary swap failure.
|
|
283
|
-
*/
|
|
284
|
-
export class RollbackFailedError extends Error {
|
|
285
|
-
preservedAt;
|
|
286
|
-
constructor(message, preservedAt) {
|
|
287
|
-
super(message);
|
|
288
|
-
this.name = 'RollbackFailedError';
|
|
289
|
-
this.preservedAt = preservedAt;
|
|
290
|
-
}
|
|
291
|
-
}
|
|
292
176
|
/**
|
|
293
177
|
* Atomically swap a validated `stagingDir` into place at `defsDir/folder`,
|
|
294
|
-
*
|
|
295
|
-
*
|
|
296
|
-
*
|
|
297
|
-
*
|
|
298
|
-
*
|
|
299
|
-
* previous install on success — it returns an {@link InstallCommitHandle} whose
|
|
300
|
-
* `backupDir` still holds it. The caller must then either
|
|
301
|
-
* {@link finalizeInstallCommit} (discard the backup, making the swap permanent)
|
|
302
|
-
* once its follow-on work — the lockfile write — has durably succeeded, or
|
|
303
|
-
* {@link rollbackInstallCommit} to restore the previous directory state if that
|
|
304
|
-
* work fails. This is what lets "commit the directory + write the lockfile" be
|
|
305
|
-
* one recoverable operation.
|
|
306
|
-
*
|
|
307
|
-
* Sequence: back up any existing install (rename dest → `<stagingDir>-old`) — if
|
|
308
|
-
* that fails nothing has changed; rename staging → dest; on failure rename the
|
|
309
|
-
* backup back (throwing {@link RollbackFailedError} if even that fails, so the
|
|
310
|
-
* caller can preserve the named copy).
|
|
178
|
+
* retaining the displaced previous install on the returned handle (see
|
|
179
|
+
* `src/install.ts:commitInstall` for the full two-phase semantics). This is a
|
|
180
|
+
* typed pass-through: `folder` is a SINGLE on-disk segment, and the returned
|
|
181
|
+
* handle carries the GitHub-only `oldName` migration field once
|
|
182
|
+
* `parkOldNameDir` runs.
|
|
311
183
|
*/
|
|
312
|
-
export function commitInstall(defsDir, folder, stagingDir) {
|
|
313
|
-
|
|
314
|
-
const dest = join(defsDir, folder);
|
|
315
|
-
const backupDir = `${stagingDir}-old`;
|
|
316
|
-
const undoDir = `${stagingDir}-undo`;
|
|
317
|
-
let backedUp = false;
|
|
318
|
-
if (existsSync(dest)) {
|
|
319
|
-
// Ownership is verified by the caller before we get here. If this rename
|
|
320
|
-
// throws, nothing has changed — dest is still the previous install.
|
|
321
|
-
renameSync(dest, backupDir);
|
|
322
|
-
backedUp = true;
|
|
323
|
-
}
|
|
324
|
-
try {
|
|
325
|
-
renameSync(stagingDir, dest);
|
|
326
|
-
}
|
|
327
|
-
catch (e) {
|
|
328
|
-
if (backedUp) {
|
|
329
|
-
try {
|
|
330
|
-
renameSync(backupDir, dest);
|
|
331
|
-
}
|
|
332
|
-
catch (rollbackErr) {
|
|
333
|
-
// Near-impossible (same dir, same fs), but if even the rollback fails,
|
|
334
|
-
// name the backup so the previous version is recoverable by hand — and
|
|
335
|
-
// signal (via the type) that the caller must preserve it.
|
|
336
|
-
throw new RollbackFailedError(`install of '${folder}' failed and rollback failed too; ` +
|
|
337
|
-
`previous version preserved at ${backupDir}: ${rollbackErr.message}`, backupDir);
|
|
338
|
-
}
|
|
339
|
-
}
|
|
340
|
-
throw e;
|
|
341
|
-
}
|
|
342
|
-
return { dest, backupDir: backedUp ? backupDir : undefined, undoDir };
|
|
184
|
+
export function commitInstall(defsDir, folder, stagingDir, options = {}) {
|
|
185
|
+
return commitInstallGeneric(defsDir, folder, stagingDir, options);
|
|
343
186
|
}
|
|
344
187
|
/**
|
|
345
188
|
* Migrate a source off its old `<owner>-<repo>` install directory by PARKING it
|
|
@@ -347,7 +190,7 @@ export function commitInstall(defsDir, folder, stagingDir) {
|
|
|
347
190
|
* rollback can put it back where the (still-unchanged) lockfile expects it.
|
|
348
191
|
* Records the move on `handle.oldName`. If the old dir does not exist on disk
|
|
349
192
|
* (the lockfile names a path that is already gone), records nothing — matching
|
|
350
|
-
* the previous
|
|
193
|
+
* the previous tolerance of absence.
|
|
351
194
|
*
|
|
352
195
|
* Defense-in-depth (Layer 3): even though `readLockfile`/`validateLockfile` and
|
|
353
196
|
* the use-site in `dispatchAdd` already constrain `oldRelPath` to a safe single
|
|
@@ -359,9 +202,8 @@ export function commitInstall(defsDir, folder, stagingDir) {
|
|
|
359
202
|
* `oldRelPath` must be a single segment AND resolve under `defsDir`, and the
|
|
360
203
|
* target must be a real directory — a symlink at the legacy path is refused (a
|
|
361
204
|
* symlinked segment must never be parked/finalized, since finalize deletes it).
|
|
362
|
-
* Deliberate behavior change vs.
|
|
363
|
-
* at the old path
|
|
364
|
-
* it is now refused, which is fail-closed and correct.
|
|
205
|
+
* Deliberate behavior change vs. a bare `existsSync` probe: a DANGLING symlink
|
|
206
|
+
* at the old path is refused, which is fail-closed and correct.
|
|
365
207
|
*/
|
|
366
208
|
export function parkOldNameDir(handle, defsDir, oldRelPath) {
|
|
367
209
|
const violation = lockfilePathViolation(oldRelPath);
|
|
@@ -394,38 +236,29 @@ export function parkOldNameDir(handle, defsDir, oldRelPath) {
|
|
|
394
236
|
handle.oldName = { originalPath, parkedAt };
|
|
395
237
|
}
|
|
396
238
|
/**
|
|
397
|
-
* Make the commit permanent: discard the retained previous install
|
|
398
|
-
* parked old-name dir
|
|
239
|
+
* Make the commit permanent: discard the retained previous install AND any
|
|
240
|
+
* parked old-name dir (the GitHub-only half the generic finalizer does not
|
|
241
|
+
* know about). Call ONLY after the follow-on lockfile write has durably
|
|
399
242
|
* succeeded — this is the point of no return.
|
|
400
243
|
*/
|
|
401
244
|
export function finalizeInstallCommit(handle) {
|
|
402
|
-
|
|
403
|
-
rmSync(handle.backupDir, { recursive: true, force: true });
|
|
245
|
+
finalizeInstallCommitGeneric(handle);
|
|
404
246
|
if (handle.oldName)
|
|
405
247
|
rmSync(handle.oldName.parkedAt, { recursive: true, force: true });
|
|
406
248
|
}
|
|
407
249
|
/**
|
|
408
|
-
*
|
|
409
|
-
*
|
|
410
|
-
*
|
|
411
|
-
*
|
|
412
|
-
*
|
|
413
|
-
* 3. if an old-name dir was parked, rename it back to where the lockfile says.
|
|
414
|
-
* The parked new content under `undoDir` is left for the caller's staging-root
|
|
415
|
-
* cleanup to dispose of. Any throw propagates to the caller.
|
|
416
|
-
*
|
|
417
|
-
* Safe to call from a FAILED `parkOldNameDir`: that helper records
|
|
418
|
-
* `handle.oldName` only after its single rename succeeds, so a park failure
|
|
419
|
-
* leaves `oldName` unset and step 3 self-skips — there is no "park partially
|
|
420
|
-
* happened" state to reconcile (the park is one atomic rename).
|
|
250
|
+
* Restore the previous directory state after a failed commit: the GitHub-only
|
|
251
|
+
* counterpart of `finalizeInstallCommit`. Restores the swapped-out destination
|
|
252
|
+
* exactly as the generic rollback does, THEN renames the parked old-name dir
|
|
253
|
+
* back to its original name — the same order as before the transaction was
|
|
254
|
+
* generalized. Call ONLY before the follow-on lockfile write has succeeded.
|
|
421
255
|
*/
|
|
422
256
|
export function rollbackInstallCommit(handle) {
|
|
423
|
-
|
|
424
|
-
if (handle.backupDir)
|
|
425
|
-
renameSync(handle.backupDir, handle.dest);
|
|
257
|
+
rollbackInstallCommitGeneric(handle);
|
|
426
258
|
if (handle.oldName)
|
|
427
259
|
renameSync(handle.oldName.parkedAt, handle.oldName.originalPath);
|
|
428
260
|
}
|
|
261
|
+
// ---- per-project install lock --------------------------------------------------
|
|
429
262
|
/**
|
|
430
263
|
* Acquire the per-project install lock at `lockPath`. A 1-line adapter over the
|
|
431
264
|
* generic `acquireFileLock`, pinning `label` so the timeout message reads
|
|
@@ -433,402 +266,35 @@ export function rollbackInstallCommit(handle) {
|
|
|
433
266
|
* with `releaseInstallLock` in a `finally`.
|
|
434
267
|
*/
|
|
435
268
|
export function acquireInstallLock(lockPath, opts = {}) {
|
|
436
|
-
return
|
|
437
|
-
}
|
|
438
|
-
/** Release a lock acquired by `acquireInstallLock` — the generic `releaseFileLock`. */
|
|
439
|
-
export const releaseInstallLock = releaseFileLock;
|
|
440
|
-
// ---- crash-recovery journal ------------------------------------------------
|
|
441
|
-
//
|
|
442
|
-
// A process that dies (crash, SIGKILL — see docs/cli.md on power-loss limits)
|
|
443
|
-
// partway through the destructive part of an install — the `commitInstall` swap,
|
|
444
|
-
// the old-name park, or the ledger write — must leave `.owenloop` recoverable to a consistent
|
|
445
|
-
// (defs-on-disk ⇔ ledger) state by the NEXT `add`, never a half-applied tree.
|
|
446
|
-
// Today's failure arms in `dispatchAdd` only cover IN-PROCESS failures (a throw
|
|
447
|
-
// we catch and roll back); a hard kill skips them entirely. This journal closes
|
|
448
|
-
// that gap: `dispatchAdd` writes a one-record intent file before the first
|
|
449
|
-
// destructive step and advances/removes it as the install progresses, and the
|
|
450
|
-
// next `add` runs `recoverInterruptedInstall` under the same A3 install lock,
|
|
451
|
-
// BEFORE the stale-staging cleanup, to roll a leftover install forward or back.
|
|
452
|
-
//
|
|
453
|
-
// The journal is attacker-influenceable input, exactly like the lockfile (a
|
|
454
|
-
// hostile checkout can ship a crafted `.owenloop/add.journal`). It is validated
|
|
455
|
-
// fail-closed with the A1 discipline (`lockfilePathViolation` on every path
|
|
456
|
-
// field, single-segment ⇒ traversal unrepresentable), every mutation path is
|
|
457
|
-
// re-derived from the CURRENT run's resolved `defsDir` plus those validated
|
|
458
|
-
// segments — never from a recorded absolute path — and A2's symlink rule is
|
|
459
|
-
// re-asserted at each mutation site. Any bad shape, unknown phase, defsDir
|
|
460
|
-
// mismatch, or contradictory disk state REFUSES with no filesystem mutation and
|
|
461
|
-
// leaves the journal in place as evidence.
|
|
462
|
-
/** Journal filename under `.owenloop/` (sibling of `installed.json`/`add.lock`). */
|
|
463
|
-
export const ADD_JOURNAL_FILENAME = 'add.journal';
|
|
464
|
-
/**
|
|
465
|
-
* Structurally validate a parsed `add.journal`, fail-closed — the trust
|
|
466
|
-
* boundary for the journal, mirroring {@link validateLockfile}. A
|
|
467
|
-
* parseable-but-invalid journal is a hard error naming the file and the manual
|
|
468
|
-
* remedy; recovery NEVER acts on a field that has not passed through here. Every
|
|
469
|
-
* path field must be a safe single segment so a crafted journal cannot represent
|
|
470
|
-
* traversal before any `join`/`rename`. Unknown extra keys are tolerated
|
|
471
|
-
* (forward compatibility, same as the lockfile). `ref`/`startedAt` are
|
|
472
|
-
* diagnostics: validated for type when present, but not required. `path`
|
|
473
|
-
* appears only in error messages.
|
|
474
|
-
*/
|
|
475
|
-
export function validateAddJournal(parsed, path) {
|
|
476
|
-
const fail = (detail) => {
|
|
477
|
-
throw new Error(`invalid crash-recovery journal at ${path}: ${detail} — ` +
|
|
478
|
-
`inspect and remove it manually, then re-run add`);
|
|
479
|
-
};
|
|
480
|
-
if (!isPlainObject(parsed))
|
|
481
|
-
return fail('top-level value is not an object');
|
|
482
|
-
if (parsed.version !== 1) {
|
|
483
|
-
return fail(`unsupported journal version ${JSON.stringify(parsed.version)} (expected 1)`);
|
|
484
|
-
}
|
|
485
|
-
if (parsed.phase !== 'applying' && parsed.phase !== 'finalizing') {
|
|
486
|
-
return fail(`unknown phase ${JSON.stringify(parsed.phase)} (expected 'applying' or 'finalizing')`);
|
|
487
|
-
}
|
|
488
|
-
if (typeof parsed.source !== 'string' || parsed.source === '') {
|
|
489
|
-
return fail("'source' is not a non-empty string");
|
|
490
|
-
}
|
|
491
|
-
if (typeof parsed.sha !== 'string' || !SHA_HEX_RE.test(parsed.sha)) {
|
|
492
|
-
return fail("'sha' is not a 40-char hex commit sha");
|
|
493
|
-
}
|
|
494
|
-
const segment = (field, value) => {
|
|
495
|
-
if (typeof value !== 'string')
|
|
496
|
-
fail(`'${field}' is not a string`);
|
|
497
|
-
const violation = lockfilePathViolation(value);
|
|
498
|
-
if (violation)
|
|
499
|
-
fail(`'${field}' ${violation}`);
|
|
500
|
-
};
|
|
501
|
-
segment('folder', parsed.folder);
|
|
502
|
-
segment('stagingId', parsed.stagingId);
|
|
503
|
-
if (parsed.oldNamePath !== undefined)
|
|
504
|
-
segment('oldNamePath', parsed.oldNamePath);
|
|
505
|
-
if (typeof parsed.hadDest !== 'boolean')
|
|
506
|
-
return fail("'hadDest' is not a boolean");
|
|
507
|
-
if (typeof parsed.defsDir !== 'string' || parsed.defsDir === '') {
|
|
508
|
-
return fail("'defsDir' is not a non-empty string");
|
|
509
|
-
}
|
|
510
|
-
if (parsed.ref !== undefined && typeof parsed.ref !== 'string')
|
|
511
|
-
return fail("'ref' is not a string");
|
|
512
|
-
if (parsed.startedAt !== undefined && typeof parsed.startedAt !== 'number') {
|
|
513
|
-
return fail("'startedAt' is not a number");
|
|
514
|
-
}
|
|
515
|
-
return parsed;
|
|
516
|
-
}
|
|
517
|
-
/**
|
|
518
|
-
* Read `.owenloop/add.journal`. Absent ⇒ `null` (the happy path — no
|
|
519
|
-
* interrupted install to recover). Present-but-unparseable ⇒ a hard error;
|
|
520
|
-
* present-but-schema-invalid ⇒ a hard error via {@link validateAddJournal}.
|
|
521
|
-
* Never silently ignores a malformed journal (that would let a crafted file
|
|
522
|
-
* quietly disable recovery) and never trusts it for filesystem paths.
|
|
523
|
-
*/
|
|
524
|
-
export function readAddJournal(path) {
|
|
525
|
-
if (!existsSync(path))
|
|
526
|
-
return null;
|
|
527
|
-
const raw = readFileSync(path, 'utf8');
|
|
528
|
-
let parsed;
|
|
529
|
-
try {
|
|
530
|
-
parsed = JSON.parse(raw);
|
|
531
|
-
}
|
|
532
|
-
catch (e) {
|
|
533
|
-
throw new Error(`corrupt crash-recovery journal at ${path}: ${e.message} — ` +
|
|
534
|
-
`inspect and remove it manually, then re-run add`);
|
|
535
|
-
}
|
|
536
|
-
return validateAddJournal(parsed, path);
|
|
537
|
-
}
|
|
538
|
-
/** Write the journal atomically (tmp+rename), same discipline as the lockfile. */
|
|
539
|
-
export function writeAddJournal(path, journal, opts = {}) {
|
|
540
|
-
writeJsonAtomic(path, journal, opts);
|
|
541
|
-
}
|
|
542
|
-
/** Remove the journal (force: absence is not an error — clean-completion / idempotent). */
|
|
543
|
-
export function removeAddJournal(path) {
|
|
544
|
-
rmSync(path, { force: true });
|
|
545
|
-
}
|
|
546
|
-
/** Build a fail-closed recovery-refusal error naming the journal + manual remedy. */
|
|
547
|
-
function recoveryRefusal(journalPath, detail) {
|
|
548
|
-
return new Error(`refusing crash-recovery: ${detail} — inspect ${journalPath} and the defs dir, ` +
|
|
549
|
-
`resolve the state by hand, then re-run add`);
|
|
550
|
-
}
|
|
551
|
-
/**
|
|
552
|
-
* `lstat`-probe a recovery path: `'dir'` if it is a real directory, `'absent'`
|
|
553
|
-
* if it does not exist. Fail-closed on anything else — a symlink (A2 rule: a
|
|
554
|
-
* symlinked segment must never be renamed/rm'd, since finalize/rollback would
|
|
555
|
-
* act through it) or a non-directory file is refused. `lstat`, never `stat`, so
|
|
556
|
-
* a symlink is seen as a symlink, not followed to its target.
|
|
557
|
-
*
|
|
558
|
-
* The PARENT is checked too, not just the leaf: `lstat` on the leaf sees a
|
|
559
|
-
* symlinked leaf, but a symlinked *parent* directory would be silently followed
|
|
560
|
-
* by the `rename`/`rm` that acts on the leaf, redirecting the whole mutation
|
|
561
|
-
* outside `defsDir` (a hostile checkout planting `.owenloop-staging` as a
|
|
562
|
-
* symlink is exactly this). Refuse a symlinked immediate parent before trusting
|
|
563
|
-
* the leaf probe. (Absent parent ⇒ the leaf is absent too; nothing to refuse.)
|
|
564
|
-
*/
|
|
565
|
-
function probeRecoveryDir(p, journalPath, label) {
|
|
566
|
-
const parent = dirname(p);
|
|
567
|
-
const parentSt = lstatSync(parent, { throwIfNoEntry: false });
|
|
568
|
-
if (parentSt?.isSymbolicLink()) {
|
|
569
|
-
throw recoveryRefusal(journalPath, `${label} parent '${parent}' is a symlink`);
|
|
570
|
-
}
|
|
571
|
-
let st;
|
|
572
|
-
try {
|
|
573
|
-
st = lstatSync(p);
|
|
574
|
-
}
|
|
575
|
-
catch (e) {
|
|
576
|
-
if (e.code === 'ENOENT')
|
|
577
|
-
return 'absent';
|
|
578
|
-
throw e;
|
|
579
|
-
}
|
|
580
|
-
if (st.isSymbolicLink())
|
|
581
|
-
throw recoveryRefusal(journalPath, `${label} at '${p}' is a symlink`);
|
|
582
|
-
if (!st.isDirectory())
|
|
583
|
-
throw recoveryRefusal(journalPath, `${label} at '${p}' is not a directory`);
|
|
584
|
-
return 'dir';
|
|
585
|
-
}
|
|
586
|
-
/** Re-assert resolved-path containment at a mutation target (belt-and-braces). */
|
|
587
|
-
function assertUnderDefs(p, defsDir, journalPath) {
|
|
588
|
-
if (!resolve(p).startsWith(resolve(defsDir) + sep)) {
|
|
589
|
-
throw recoveryRefusal(journalPath, `path '${p}' escapes the defs directory`);
|
|
590
|
-
}
|
|
269
|
+
return acquireInstallLockGeneric(lockPath, opts);
|
|
591
270
|
}
|
|
592
271
|
/**
|
|
593
|
-
* Bring an interrupted install back to a consistent (defs ⇔
|
|
594
|
-
* remove the journal. Called by `dispatchAdd` under the
|
|
595
|
-
* BEFORE the stale-staging cleanup
|
|
596
|
-
*
|
|
597
|
-
*
|
|
598
|
-
*
|
|
599
|
-
*
|
|
600
|
-
*
|
|
601
|
-
*
|
|
602
|
-
* 1. `finalizing` ⇒ roll forward: the ledger is durably new; only finalize's
|
|
603
|
-
* discards may be missing. Clear the retained backup + parked old-name and
|
|
604
|
-
* the staging root. Trivially idempotent.
|
|
605
|
-
* 2. `applying` + the ledger already records this source at `journal.sha`/
|
|
606
|
-
* `journal.folder` ⇒ the commit MAY have landed, but the ledger match alone
|
|
607
|
-
* does not prove it — branch on disk: dest present ⇒ the swap completed ⇒
|
|
608
|
-
* roll forward; dest ABSENT ⇒ a same-sha re-add crashed inside commitInstall's
|
|
609
|
-
* dest→backup / staging→dest window and backupDir holds the only copy ⇒ roll
|
|
610
|
-
* back (restore it) rather than discarding it (which would be silent data
|
|
611
|
-
* loss against a ledger that still records the install).
|
|
612
|
-
* 3. `applying`, no ledger match (or ledger match with dest absent) ⇒ roll back
|
|
613
|
-
* through the guarded, idempotent decision table below (mirroring
|
|
614
|
-
* `rollbackInstallCommit`'s order) — EXCEPT the case-(c) fresh-install
|
|
615
|
-
* discard, which acts on the journal alone (staging + backup both absent) and
|
|
616
|
-
* so requires LEDGER corroboration of an interrupted old-name migration
|
|
617
|
-
* (`installed.path === journal.oldNamePath`) before it will delete an
|
|
618
|
-
* existing dest; uncorroborated ⇒ refuse fail-closed, mutate nothing, leave
|
|
619
|
-
* the journal and dest in place (the journal is repo-committable, so a forged
|
|
620
|
-
* one must never drive a deletion).
|
|
621
|
-
*
|
|
622
|
-
* Crash-safety of recovery itself: the journal is removed LAST, after all
|
|
623
|
-
* restore/discard renames, and every step is a single atomic rename guarded by
|
|
624
|
-
* existence probes — so a crash mid-recovery leaves the journal intact and a
|
|
625
|
-
* strict subset of the work done; the next attempt re-derives state from disk
|
|
626
|
-
* and continues (the dest-absent arm of case (b), the touch-nothing arm of
|
|
627
|
-
* case (c), and the case-(c) uncorroborated refusal ARE the mid-rollback resume
|
|
628
|
-
* / fail-closed states). Running it twice is a no-op the second time.
|
|
629
|
-
*
|
|
630
|
-
* Any refusal (invalid journal, defsDir mismatch, symlink where a directory is
|
|
631
|
-
* expected, contradictory disk state) throws WITHOUT mutating anything and
|
|
632
|
-
* leaves the journal in place; `dispatchAdd` sets `preserveStagingRoot` so its
|
|
633
|
-
* `finally` cannot then destroy the backups a later attempt needs.
|
|
272
|
+
* Bring an interrupted GitHub-route install back to a consistent (defs ⇔
|
|
273
|
+
* lockfile) state, then remove the journal. Called by `dispatchAdd` under the
|
|
274
|
+
* per-project install lock, BEFORE the stale-staging cleanup. Also recovers a
|
|
275
|
+
* v2 (workflow-store) journal found at the same location — the generic
|
|
276
|
+
* recovery dispatches on journal version. See `src/install.ts`
|
|
277
|
+
* `recoverInterruptedInstall` for the full roll-forward/roll-back decision
|
|
278
|
+
* table and crash-safety argument. Refusals throw without mutating anything
|
|
279
|
+
* and leave the journal in place.
|
|
634
280
|
*/
|
|
635
281
|
export function recoverInterruptedInstall(args) {
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
const undoDir = `${stagingDir}-undo`;
|
|
655
|
-
const parkedOldName = `${undoDir}-oldname`;
|
|
656
|
-
const dest = join(defsDir, journal.folder);
|
|
657
|
-
const oldNameOriginal = journal.oldNamePath !== undefined ? join(defsDir, journal.oldNamePath) : undefined;
|
|
658
|
-
// Symlink-guard the staging ROOT itself before deriving any mutation from it.
|
|
659
|
-
// `dispatchAdd`'s `mkdirRefusingSymlink` guards `.owenloop` and the default
|
|
660
|
-
// defsDir, but NOT `<defsDir>/.owenloop-staging` — and stagingDir/backupDir/
|
|
661
|
-
// undoDir/parkedOldName all hang off it, so a hostile checkout that ships
|
|
662
|
-
// `.owenloop-staging` as a symlink would make every rename/rm below act
|
|
663
|
-
// through it, moving/deleting dirs OUTSIDE defsDir. `lstat` (never `stat`) so
|
|
664
|
-
// the link is seen as a link; a non-dir squatting there is refused too; absent
|
|
665
|
-
// is fine (a fresh recovery mkdirs it). This runs BEFORE any fs mutation, and
|
|
666
|
-
// recovery now precedes dispatchAdd's `rmSync(stagingRoot)`, so nothing else
|
|
667
|
-
// clears it first.
|
|
668
|
-
const stagingRootSt = lstatSync(stagingRoot, { throwIfNoEntry: false });
|
|
669
|
-
if (stagingRootSt?.isSymbolicLink()) {
|
|
670
|
-
throw recoveryRefusal(journalPath, `staging root '${stagingRoot}' is a symlink`);
|
|
671
|
-
}
|
|
672
|
-
if (stagingRootSt && !stagingRootSt.isDirectory()) {
|
|
673
|
-
throw recoveryRefusal(journalPath, `staging root '${stagingRoot}' is not a directory`);
|
|
674
|
-
}
|
|
675
|
-
// Belt-and-braces containment: re-assert that EVERY rename/rm source and target
|
|
676
|
-
// resolves under defsDir — not just dest/oldNameOriginal, but every staging-
|
|
677
|
-
// root-derived path too (a crafted journal + a symlinked staging root must not
|
|
678
|
-
// drive a mutation outside the tree). Single-segment folder/oldNamePath/
|
|
679
|
-
// stagingId already make lexical traversal unrepresentable; this is the extra
|
|
680
|
-
// guard the review asked for on the staging-derived paths.
|
|
681
|
-
for (const p of [stagingRoot, stagingDir, backupDir, undoDir, parkedOldName, dest]) {
|
|
682
|
-
assertUnderDefs(p, defsDir, journalPath);
|
|
683
|
-
}
|
|
684
|
-
if (oldNameOriginal !== undefined)
|
|
685
|
-
assertUnderDefs(oldNameOriginal, defsDir, journalPath);
|
|
686
|
-
// Roll forward: the ledger is durably new; discard the retained backup + parked
|
|
687
|
-
// old-name dir and clear the staging root, then drop the journal. Symlink-
|
|
688
|
-
// guarded before each rm; both dirs live under the staging root, so the final
|
|
689
|
-
// clear is the real cleanup — the explicit rms honor "refuse a symlink" first.
|
|
690
|
-
const rollForward = () => {
|
|
691
|
-
if (probeRecoveryDir(backupDir, journalPath, 'backup dir') === 'dir') {
|
|
692
|
-
rmSync(backupDir, { recursive: true, force: true });
|
|
693
|
-
}
|
|
694
|
-
if (probeRecoveryDir(parkedOldName, journalPath, 'parked old-name dir') === 'dir') {
|
|
695
|
-
rmSync(parkedOldName, { recursive: true, force: true });
|
|
696
|
-
}
|
|
697
|
-
rmSync(stagingRoot, { recursive: true, force: true });
|
|
698
|
-
removeAddJournal(journalPath);
|
|
699
|
-
};
|
|
700
|
-
if (journal.phase === 'finalizing') {
|
|
701
|
-
rollForward();
|
|
702
|
-
return 'rolled-forward';
|
|
703
|
-
}
|
|
704
|
-
// phase === 'applying': the ledger write may or may not have landed. Read it
|
|
705
|
-
// (fail-closed validation applies — a corrupt ledger aborts the add exactly as
|
|
706
|
-
// it does today) and check whether it already records this exact install.
|
|
707
|
-
const lf = readLockfile(lockfilePath);
|
|
708
|
-
const installed = lf.installed[journal.source];
|
|
709
|
-
if (installed && installed.sha === journal.sha && installed.path === journal.folder) {
|
|
710
|
-
// The ledger records this exact source@sha — but a ledger match ALONE does
|
|
711
|
-
// NOT prove the commit swap landed. Branch on ACTUAL disk state:
|
|
712
|
-
// - dest PRESENT ⇒ the swap completed (a crash in the writeLockfile→phase-
|
|
713
|
-
// rewrite window, or a same-sha re-add already past the swap): dest holds
|
|
714
|
-
// that sha's content, so (defs ⇔ ledger) is consistent ⇒ roll forward
|
|
715
|
-
// (discard the now-stale backup).
|
|
716
|
-
// - dest ABSENT ⇒ we are inside commitInstall's 4a→4b window of a SAME-sha
|
|
717
|
-
// re-add (dest was renamed to backupDir, and the staging→dest swap never
|
|
718
|
-
// ran). backupDir now holds the ONLY copy of the content. Rolling forward
|
|
719
|
-
// would `rmSync` it — silent data loss, leaving the ledger claiming an
|
|
720
|
-
// install that is gone from disk. Fall THROUGH to the roll-back table,
|
|
721
|
-
// which restores backupDir → dest; the ledger already records this sha, so
|
|
722
|
-
// the restored state is consistent. The two cases are distinguishable by
|
|
723
|
-
// disk, so branch on it rather than trusting the ledger match alone.
|
|
724
|
-
if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
|
|
725
|
-
rollForward();
|
|
726
|
-
return 'rolled-forward';
|
|
727
|
-
}
|
|
728
|
-
}
|
|
729
|
-
// ROLL BACK — restore the pre-commit directory state. Guarded idempotent
|
|
730
|
-
// renames mirroring rollbackInstallCommit's order; a symlinked source is
|
|
731
|
-
// refused fail-closed at each probe.
|
|
732
|
-
mkdirSync(stagingRoot, { recursive: true }); // ensure undo/backup renames have a home
|
|
733
|
-
const stagingState = probeRecoveryDir(stagingDir, journalPath, 'staging dir');
|
|
734
|
-
const backupState = probeRecoveryDir(backupDir, journalPath, 'backup dir');
|
|
735
|
-
if (stagingState === 'dir') {
|
|
736
|
-
// (a) Swap 4b (staging → dest) never happened.
|
|
737
|
-
if (backupState === 'dir') {
|
|
738
|
-
// Crash between 4a (dest → backup) and 4b: dest is necessarily absent.
|
|
739
|
-
// Restore the backup. Fail closed if dest unexpectedly exists too.
|
|
740
|
-
if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
|
|
741
|
-
throw recoveryRefusal(journalPath, `both the backup dir and destination '${dest}' exist`);
|
|
742
|
-
}
|
|
743
|
-
renameSync(backupDir, dest);
|
|
744
|
-
}
|
|
745
|
-
// else backup absent: dest still holds the original (upgrade, pre-backup) or
|
|
746
|
-
// is absent (fresh install, pre-swap) — already consistent, nothing to move.
|
|
747
|
-
}
|
|
748
|
-
else if (backupState === 'dir') {
|
|
749
|
-
// (b) Staging gone, backup present — an upgrade crashed AFTER the swap.
|
|
750
|
-
if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
|
|
751
|
-
// Park the new content aside, then restore the backup over dest.
|
|
752
|
-
if (probeRecoveryDir(undoDir, journalPath, 'undo dir') === 'dir') {
|
|
753
|
-
throw recoveryRefusal(journalPath, `undo dir '${undoDir}' already exists`);
|
|
754
|
-
}
|
|
755
|
-
renameSync(dest, undoDir);
|
|
756
|
-
renameSync(backupDir, dest);
|
|
757
|
-
}
|
|
758
|
-
else {
|
|
759
|
-
// dest absent: a prior rollback/recovery died between its two renames (the
|
|
760
|
-
// new content is already parked under undoDir) — just restore the backup.
|
|
761
|
-
renameSync(backupDir, dest);
|
|
762
|
-
}
|
|
763
|
-
}
|
|
764
|
-
else {
|
|
765
|
-
// (c) Staging gone, backup gone.
|
|
766
|
-
if (!journal.hadDest) {
|
|
767
|
-
// Fresh install: the swap may have put new content at dest. Discarding it
|
|
768
|
-
// (rename → undoDir, then rm with the staging root at step (e)) is the ONLY
|
|
769
|
-
// destructive arm that acts on the word of the journal alone — staging and
|
|
770
|
-
// backup are both absent by definition of case (c), so the journal is the
|
|
771
|
-
// only thing asserting this dir is a crash orphan. But the journal lives in
|
|
772
|
-
// repository-controlled content (`.owenloop/add.journal` is committable), so
|
|
773
|
-
// a hostile checkout can forge a schema-VALID `applying`/`hadDest:false`
|
|
774
|
-
// journal naming an existing UNRELATED workflow dir and drive its deletion.
|
|
775
|
-
// Fail closed: only delete when the LEDGER corroborates that this dest is a
|
|
776
|
-
// fresh hashed dir left by an interrupted OLD-NAME MIGRATION — i.e. the
|
|
777
|
-
// ledger still records `journal.source` at the migration's old-name path
|
|
778
|
-
// (`installed.path === journal.oldNamePath`). That is exactly the state of
|
|
779
|
-
// the corroborated old-name-migration crash; the parked old-name dir is NOT
|
|
780
|
-
// required as evidence (a crash in the swap→park window legitimately has no
|
|
781
|
-
// parked dir yet). Anything else — no ledger entry, or an entry at some
|
|
782
|
-
// other path (including `journal.folder` itself, which contradicts
|
|
783
|
-
// `hadDest:false`) — is uncorroborated: refuse, mutate nothing, leave the
|
|
784
|
-
// journal AND dest in place as evidence.
|
|
785
|
-
//
|
|
786
|
-
// Deliberate, documented regression: the genuine fresh-install crash between
|
|
787
|
-
// the swap and the ledger write (dest present, no ledger, no staging, no
|
|
788
|
-
// backup) is on-disk INDISTINGUISHABLE from the forgery — every
|
|
789
|
-
// distinguishing artifact is itself repo-committable and therefore forgeable
|
|
790
|
-
// — so it now fails closed here instead of auto-discarding. The error names
|
|
791
|
-
// the manual remedy. Raising the bar from "journal alone" to "journal +
|
|
792
|
-
// corroborating ledger" is the scope; moving/authenticating recovery state
|
|
793
|
-
// OUTSIDE repository-controlled content is the tracked follow-up (an attacker
|
|
794
|
-
// who forges BOTH the journal and a matching ledger old-name entry — or a
|
|
795
|
-
// backup dir, reaching case (b) — can still drive destructive recovery).
|
|
796
|
-
if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
|
|
797
|
-
const migrationCorroborated = journal.oldNamePath !== undefined &&
|
|
798
|
-
installed !== undefined &&
|
|
799
|
-
installed.path === journal.oldNamePath;
|
|
800
|
-
if (!migrationCorroborated) {
|
|
801
|
-
throw recoveryRefusal(journalPath, `journal claims an interrupted fresh install of '${journal.folder}', but nothing ` +
|
|
802
|
-
`corroborates it (no ledger entry for this source at the journal's old-name path, ` +
|
|
803
|
-
`no staging dir, no backup) while '${dest}' exists — refusing to discard that ` +
|
|
804
|
-
`directory. If you did not run an interrupted add in this checkout, remove the ` +
|
|
805
|
-
`journal; if a fresh install really was interrupted, remove '${dest}' as well`);
|
|
806
|
-
}
|
|
807
|
-
if (probeRecoveryDir(undoDir, journalPath, 'undo dir') === 'dir') {
|
|
808
|
-
throw recoveryRefusal(journalPath, `undo dir '${undoDir}' already exists`);
|
|
809
|
-
}
|
|
810
|
-
renameSync(dest, undoDir);
|
|
811
|
-
}
|
|
812
|
-
}
|
|
813
|
-
// hadDest === true: the backup was already restored (a completed in-process
|
|
814
|
-
// rollback whose journal-remove failed, or a prior recovery attempt) — dirs
|
|
815
|
-
// are consistent; touch nothing.
|
|
816
|
-
}
|
|
817
|
-
// (d) Restore a parked old-name dir to where the (unchanged) ledger expects it.
|
|
818
|
-
if (oldNameOriginal !== undefined) {
|
|
819
|
-
if (probeRecoveryDir(parkedOldName, journalPath, 'parked old-name dir') === 'dir') {
|
|
820
|
-
if (probeRecoveryDir(oldNameOriginal, journalPath, 'old-name original') === 'dir') {
|
|
821
|
-
// Both present is contradictory — unreachable under the single-writer
|
|
822
|
-
// lock, so don't guess which to keep.
|
|
823
|
-
throw recoveryRefusal(journalPath, `both the parked old-name dir and its original '${oldNameOriginal}' exist`);
|
|
824
|
-
}
|
|
825
|
-
renameSync(parkedOldName, oldNameOriginal);
|
|
826
|
-
}
|
|
827
|
-
// parked absent ⇒ already restored (idempotent re-run) — skip.
|
|
828
|
-
}
|
|
829
|
-
// (e) The undo/backup leftovers are debris now; clear the staging root and
|
|
830
|
-
// remove the journal LAST so a crash before this leaves everything replayable.
|
|
831
|
-
rmSync(stagingRoot, { recursive: true, force: true });
|
|
832
|
-
removeAddJournal(journalPath);
|
|
833
|
-
return 'rolled-back';
|
|
282
|
+
return recoverInterruptedInstallGeneric({
|
|
283
|
+
defsDir: args.defsDir,
|
|
284
|
+
journalPath: args.journalPath,
|
|
285
|
+
lockfilePath: args.lockfilePath,
|
|
286
|
+
recoveryMarkerDir: args.recoveryMarkerDir,
|
|
287
|
+
v2Replacement: args.v2Replacement,
|
|
288
|
+
readLedger: () => {
|
|
289
|
+
// readLockfile validates fail-closed; a corrupt lockfile aborts the add
|
|
290
|
+
// exactly as it does on the normal path.
|
|
291
|
+
const lf = readLockfile(args.lockfilePath);
|
|
292
|
+
return (source) => {
|
|
293
|
+
const entry = lf.installed[source];
|
|
294
|
+
if (entry === undefined)
|
|
295
|
+
return undefined;
|
|
296
|
+
return { sha: entry.sha, path: entry.path };
|
|
297
|
+
};
|
|
298
|
+
},
|
|
299
|
+
});
|
|
834
300
|
}
|