owenloop 0.5.0 → 0.5.2
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 +67 -0
- package/README.md +144 -35
- package/bin/owenloop.mjs +49 -1
- package/dist/packages/work/src/agent/brief.d.ts +29 -4
- package/dist/packages/work/src/agent/brief.js +49 -4
- package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
- package/dist/packages/work/src/agent/capability-model.js +148 -0
- package/dist/packages/work/src/agent/loop.d.ts +56 -7
- package/dist/packages/work/src/agent/loop.js +166 -9
- 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 +29 -1
- package/dist/packages/work/src/exec/loop.js +313 -35
- 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 +84 -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 +30 -10
- package/dist/packages/work/src/harness/session-store.js +317 -89
- package/dist/packages/work/src/hold/mcp.d.ts +25 -5
- package/dist/packages/work/src/hold/mcp.js +134 -12
- package/dist/packages/work/src/hub/client.d.ts +8 -1
- package/dist/packages/work/src/hub/client.js +15 -1
- package/dist/packages/work/src/hub/types.d.ts +137 -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 +115 -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 +6 -0
- package/dist/packages/work/src/roles/hold.js +83 -13
- 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 +19 -2
- package/dist/packages/work/src/roles/shift.d.ts +1 -0
- package/dist/packages/work/src/roles/shift.js +36 -2
- package/dist/packages/work/src/settings/settings.d.ts +70 -1
- package/dist/packages/work/src/settings/settings.js +90 -4
- package/dist/packages/work/src/shift/logretention.d.ts +253 -0
- package/dist/packages/work/src/shift/logretention.js +407 -0
- package/dist/packages/work/src/shift/logsink.d.ts +14 -0
- package/dist/packages/work/src/shift/logsink.js +98 -0
- package/dist/packages/work/src/shift/loop.d.ts +32 -4
- package/dist/packages/work/src/shift/loop.js +687 -166
- package/dist/packages/work/src/shift/protocol.d.ts +128 -1
- package/dist/packages/work/src/shift/protocol.js +14 -0
- package/dist/packages/work/src/shift/runtime.d.ts +16 -0
- package/dist/packages/work/src/shift/runtime.js +291 -5
- package/dist/packages/work/src/shift/server.d.ts +13 -0
- package/dist/packages/work/src/shift/server.js +61 -36
- package/dist/packages/work/src/shift/spawn.d.ts +115 -19
- package/dist/packages/work/src/shift/spawn.js +234 -30
- package/dist/packages/work/src/shift/state.d.ts +76 -49
- package/dist/packages/work/src/shift/state.js +350 -103
- package/dist/packages/work/src/shift/truncate.d.ts +35 -0
- package/dist/packages/work/src/shift/truncate.js +73 -0
- package/dist/packages/work/src/submit-proof.d.ts +61 -0
- package/dist/packages/work/src/submit-proof.js +119 -0
- package/dist/packages/work/src/submit-value.d.ts +48 -0
- package/dist/packages/work/src/submit-value.js +118 -0
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +11 -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/capabilities.d.ts +93 -0
- package/dist/src/capabilities.js +101 -0
- package/dist/src/cli.d.ts +90 -20
- package/dist/src/cli.js +2421 -374
- 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 +319 -0
- package/dist/src/crypto/records.js +168 -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 +335 -27
- package/dist/src/engine.d.ts +211 -6
- package/dist/src/engine.js +459 -59
- 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 +102 -32
- package/dist/src/hub.js +147 -58
- package/dist/src/index.d.ts +19 -2
- package/dist/src/index.js +23 -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 +174 -44
- package/dist/src/mcp/server.js +12 -1
- package/dist/src/model.d.ts +51 -0
- package/dist/src/model.js +157 -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 +1433 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +120 -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/store.d.ts +33 -1
- package/dist/src/store.js +57 -4
- package/dist/src/types.d.ts +146 -12
- 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 +64 -6
- package/docs/bundles.md +350 -0
- package/docs/cli.md +1298 -106
- package/docs/crypto.md +832 -0
- package/docs/design.md +342 -20
- package/docs/embedding.md +132 -25
- package/docs/shift-logs.md +642 -0
- package/docs/wire-contracts.md +395 -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.d.ts
CHANGED
|
@@ -1,38 +1,19 @@
|
|
|
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 {
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
* Returns `undefined` if `relPath` is safe to `join()` under a destination
|
|
16
|
-
* directory, else a human-readable reason it must be rejected. This is
|
|
17
|
-
* reject-don't-normalize: a synthetic archive entry like
|
|
18
|
-
* `workflows/../../victim` is refused outright, never canonicalized into a
|
|
19
|
-
* "safe" path. Part of SEC-1 — an unnormalized entry name must never escape
|
|
20
|
-
* the staging or install directory.
|
|
21
|
-
*/
|
|
22
|
-
export declare function archivePathViolation(relPath: string): string | undefined;
|
|
23
|
-
/**
|
|
24
|
-
* Returns `undefined` if `relPath` is a safe SINGLE-SEGMENT lockfile install
|
|
25
|
-
* path, else a human-readable reason it must be rejected. Stricter than
|
|
26
|
-
* {@link archivePathViolation}: a lockfile entry's `path` is one on-disk path
|
|
27
|
-
* segment by construction — both the current `<owner>-<repo>-<hash>` scheme and
|
|
28
|
-
* the only legacy scheme this tool ever wrote (`<owner>-<repo>`, see
|
|
29
|
-
* {@link installFolder}) — so ANY separator is refused outright. That single
|
|
30
|
-
* rule makes `..` traversal, `.owenloop/../../x`, and nested escape shapes
|
|
31
|
-
* unrepresentable before any `join`/`rename` ever touches the path. Like
|
|
32
|
-
* `archivePathViolation` this is reject-don't-normalize: a bad path is refused,
|
|
33
|
-
* never canonicalized into a "safe" one.
|
|
34
|
-
*/
|
|
35
|
-
export declare function lockfilePathViolation(relPath: string): string | undefined;
|
|
14
|
+
import type { InstallCommitHandle as GenericInstallCommitHandle, InstallLockHandle, AcquireLockOpts, CommitInstallOptions, RecoveryOutcome, V2ReplacementRecoveryActions } from './install.ts';
|
|
15
|
+
export { archivePathViolation, lockfilePathViolation, stageFiles, rmRecursiveForce, RollbackFailedError, STAGING_DIRNAME, ADD_JOURNAL_FILENAME, releaseInstallLock, validateAddJournal, readAddJournal, writeAddJournal, removeAddJournal, } from './install.ts';
|
|
16
|
+
export type { AddJournal, AddJournalPhase, RecoveryOutcome, InstallLockHandle, AcquireLockOpts } from './install.ts';
|
|
36
17
|
export interface RepoSpec {
|
|
37
18
|
owner: string;
|
|
38
19
|
repo: string;
|
|
@@ -54,10 +35,10 @@ export declare function githubShaUrl(owner: string, repo: string, ref: string):
|
|
|
54
35
|
export declare function githubTarballUrl(owner: string, repo: string, sha: string): string;
|
|
55
36
|
/**
|
|
56
37
|
* One installed-package record. `path` is a single on-disk folder segment (see
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
38
|
+
* `lockfilePathViolation`); `sha` is a 40-char hex commit sha; `source` equals
|
|
39
|
+
* the record's key in `Lockfile.installed`. These invariants are NOT trusted
|
|
40
|
+
* from disk — `validateLockfile` enforces every one on read, fail-closed,
|
|
41
|
+
* before any consumer acts on an entry.
|
|
61
42
|
*/
|
|
62
43
|
export interface InstalledEntry {
|
|
63
44
|
source: string;
|
|
@@ -75,16 +56,16 @@ export interface Lockfile {
|
|
|
75
56
|
* Structurally validate a parsed `installed.json`, fail-closed. A
|
|
76
57
|
* parseable-but-schema-invalid lockfile is a hard error naming the offending
|
|
77
58
|
* entry+field — never silently reset to `{}` (which would erase ownership
|
|
78
|
-
* records and re-enable the clobbering
|
|
79
|
-
*
|
|
59
|
+
* records and re-enable the clobbering `installFolder` was hardened against)
|
|
60
|
+
* and never normalized. This is the trust boundary for the lockfile:
|
|
80
61
|
* downstream code (`dispatchAdd`, `parkOldNameDir`) may only act on entries
|
|
81
62
|
* that have passed through here. Critically, EVERY entry is validated, not just
|
|
82
63
|
* the one being installed — `dispatchAdd` re-serializes the whole lockfile on
|
|
83
64
|
* success, so acting while carrying a poisoned sibling entry would re-persist
|
|
84
65
|
* it. Unknown extra keys (on the lockfile or an entry) are tolerated for
|
|
85
66
|
* forward compatibility; required shape is enforced, additions are not
|
|
86
|
-
* forbidden. Returns the value narrowed to
|
|
87
|
-
*
|
|
67
|
+
* forbidden. Returns the value narrowed to `Lockfile`. `path` appears only in
|
|
68
|
+
* error messages.
|
|
88
69
|
*/
|
|
89
70
|
export declare function validateLockfile(parsed: unknown, path: string): Lockfile;
|
|
90
71
|
/**
|
|
@@ -94,76 +75,36 @@ export declare function validateLockfile(parsed: unknown, path: string): Lockfil
|
|
|
94
75
|
* re-enable the clobbering `installFolder` was hardened against. A file that
|
|
95
76
|
* parses but is structurally invalid (bad version, malformed entry, a `path`
|
|
96
77
|
* that is not a safe single segment, a bad `sha`/`files`) is likewise a
|
|
97
|
-
* fail-closed hard error — see
|
|
78
|
+
* fail-closed hard error — see `validateLockfile`. The lockfile is never
|
|
98
79
|
* trusted for filesystem paths.
|
|
99
80
|
*/
|
|
100
81
|
export declare function readLockfile(path: string): Lockfile;
|
|
101
|
-
/**
|
|
102
|
-
* Write the lockfile atomically: serialize into a sibling temp file, then
|
|
103
|
-
* `renameSync` over the destination. A crash or a concurrent reader never sees
|
|
104
|
-
* a half-written `installed.json` (rename is atomic within a directory), and
|
|
105
|
-
* two racing writers can only ever leave a fully-formed file.
|
|
106
|
-
*
|
|
107
|
-
* If the final `renameSync` throws (EACCES, EISDIR on `path`, a full disk),
|
|
108
|
-
* the temp sibling is removed on a best-effort basis before the error
|
|
109
|
-
* propagates so a failed write cannot leak an `installed.json.tmp.<pid>` file.
|
|
110
|
-
* The original rename error is surfaced unchanged — never swallowed, and never
|
|
111
|
-
* masked by a failure of that cleanup removal (if the removal itself throws,
|
|
112
|
-
* that error is swallowed and the tmp sibling may remain in that double fault).
|
|
113
|
-
*/
|
|
114
82
|
export interface WriteLockfileOpts {
|
|
115
83
|
/**
|
|
116
84
|
* Removal op used to clean up the temp sibling when the atomic rename fails.
|
|
117
85
|
* Defaults to `rmSync`; injectable so a test can force the cleanup itself to
|
|
118
|
-
* throw and prove the ORIGINAL rename error still surfaces
|
|
119
|
-
* test-determinism seam as `AcquireLockOpts` in this file.
|
|
86
|
+
* throw and prove the ORIGINAL rename error still surfaces.
|
|
120
87
|
*/
|
|
121
88
|
rm?: (path: string, opts: {
|
|
122
89
|
force: true;
|
|
123
90
|
}) => void;
|
|
124
91
|
}
|
|
125
|
-
export declare function writeLockfile(path: string, lf: Lockfile, opts?: WriteLockfileOpts): void;
|
|
126
|
-
/** The staging root under a defs dir where installs are assembled + validated. */
|
|
127
|
-
export declare const STAGING_DIRNAME = ".owenloop-staging";
|
|
128
92
|
/**
|
|
129
|
-
* Write
|
|
130
|
-
*
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
*
|
|
134
|
-
|
|
135
|
-
export declare function stageFiles(targetDir: string, files: Map<string, Uint8Array>): string[];
|
|
136
|
-
/**
|
|
137
|
-
* Thrown by `commitInstall` when the atomic swap fails AND the rollback of it
|
|
138
|
-
* fails too — a near-impossible same-filesystem double-fault. Carries the path
|
|
139
|
-
* where the previous version was left so the caller can preserve it (its
|
|
140
|
-
* `preservedAt` sits under the staging root, which the caller would otherwise
|
|
141
|
-
* clean up as debris). A distinguishable type so the caller can tell this
|
|
142
|
-
* "must-preserve" double-fault apart from an ordinary swap failure.
|
|
93
|
+
* Write the lockfile atomically: serialize into a sibling temp file, then
|
|
94
|
+
* rename over the destination — the shared atomic tmp+rename discipline from
|
|
95
|
+
* `src/install.ts`. A crash or a concurrent reader never sees a half-written
|
|
96
|
+
* `installed.json`, and two racing writers can only ever leave a fully-formed
|
|
97
|
+
* file. On a failed rename the temp sibling is removed best-effort and the
|
|
98
|
+
* ORIGINAL rename error is surfaced unchanged.
|
|
143
99
|
*/
|
|
144
|
-
export declare
|
|
145
|
-
readonly preservedAt: string;
|
|
146
|
-
constructor(message: string, preservedAt: string);
|
|
147
|
-
}
|
|
100
|
+
export declare function writeLockfile(path: string, lf: Lockfile, opts?: WriteLockfileOpts): void;
|
|
148
101
|
/**
|
|
149
|
-
* A handle to a committed-but-not-yet-finalized install
|
|
150
|
-
*
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
* directory state back if a later step (the lockfile write) fails. The caller
|
|
154
|
-
* MUST eventually either `finalizeInstallCommit` (discard the retained dirs) or
|
|
155
|
-
* `rollbackInstallCommit` (restore the previous state). All retained/undo paths
|
|
156
|
-
* derive from `stagingDir`, so they live under `<defsDir>/.owenloop-staging/` —
|
|
157
|
-
* same filesystem (renames stay atomic), and the staging-root cleanup covers
|
|
158
|
-
* them.
|
|
102
|
+
* A handle to a committed-but-not-yet-finalized GitHub install — the generic
|
|
103
|
+
* transaction handle plus the old-name migration record `parkOldNameDir` sets.
|
|
104
|
+
* The caller MUST eventually either `finalizeInstallCommit` (discard the
|
|
105
|
+
* retained dirs) or `rollbackInstallCommit` (restore the previous state).
|
|
159
106
|
*/
|
|
160
|
-
export interface InstallCommitHandle {
|
|
161
|
-
/** `defsDir/folder` — now holding the NEW content. */
|
|
162
|
-
dest: string;
|
|
163
|
-
/** `${stagingDir}-old` — the displaced previous dest, if one existed. */
|
|
164
|
-
backupDir?: string;
|
|
165
|
-
/** `${stagingDir}-undo` — where a rollback parks the new content before restoring. */
|
|
166
|
-
undoDir: string;
|
|
107
|
+
export interface InstallCommitHandle extends GenericInstallCommitHandle {
|
|
167
108
|
/** Set by `parkOldNameDir` when an old-naming dir was migrated off. */
|
|
168
109
|
oldName?: {
|
|
169
110
|
originalPath: string;
|
|
@@ -172,32 +113,20 @@ export interface InstallCommitHandle {
|
|
|
172
113
|
}
|
|
173
114
|
/**
|
|
174
115
|
* Atomically swap a validated `stagingDir` into place at `defsDir/folder`,
|
|
175
|
-
*
|
|
176
|
-
*
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
* previous install on success — it returns an {@link InstallCommitHandle} whose
|
|
181
|
-
* `backupDir` still holds it. The caller must then either
|
|
182
|
-
* {@link finalizeInstallCommit} (discard the backup, making the swap permanent)
|
|
183
|
-
* once its follow-on work — the lockfile write — has durably succeeded, or
|
|
184
|
-
* {@link rollbackInstallCommit} to restore the previous directory state if that
|
|
185
|
-
* work fails. This is what lets "commit the directory + write the lockfile" be
|
|
186
|
-
* one recoverable operation.
|
|
187
|
-
*
|
|
188
|
-
* Sequence: back up any existing install (rename dest → `<stagingDir>-old`) — if
|
|
189
|
-
* that fails nothing has changed; rename staging → dest; on failure rename the
|
|
190
|
-
* backup back (throwing {@link RollbackFailedError} if even that fails, so the
|
|
191
|
-
* caller can preserve the named copy).
|
|
116
|
+
* retaining the displaced previous install on the returned handle (see
|
|
117
|
+
* `src/install.ts:commitInstall` for the full two-phase semantics). This is a
|
|
118
|
+
* typed pass-through: `folder` is a SINGLE on-disk segment, and the returned
|
|
119
|
+
* handle carries the GitHub-only `oldName` migration field once
|
|
120
|
+
* `parkOldNameDir` runs.
|
|
192
121
|
*/
|
|
193
|
-
export declare function commitInstall(defsDir: string, folder: string, stagingDir: string): InstallCommitHandle;
|
|
122
|
+
export declare function commitInstall(defsDir: string, folder: string, stagingDir: string, options?: CommitInstallOptions): InstallCommitHandle;
|
|
194
123
|
/**
|
|
195
124
|
* Migrate a source off its old `<owner>-<repo>` install directory by PARKING it
|
|
196
125
|
* (rename → `<stagingDir>-undo-oldname`) instead of deleting it, so a later
|
|
197
126
|
* rollback can put it back where the (still-unchanged) lockfile expects it.
|
|
198
127
|
* Records the move on `handle.oldName`. If the old dir does not exist on disk
|
|
199
128
|
* (the lockfile names a path that is already gone), records nothing — matching
|
|
200
|
-
* the previous
|
|
129
|
+
* the previous tolerance of absence.
|
|
201
130
|
*
|
|
202
131
|
* Defense-in-depth (Layer 3): even though `readLockfile`/`validateLockfile` and
|
|
203
132
|
* the use-site in `dispatchAdd` already constrain `oldRelPath` to a safe single
|
|
@@ -209,37 +138,25 @@ export declare function commitInstall(defsDir: string, folder: string, stagingDi
|
|
|
209
138
|
* `oldRelPath` must be a single segment AND resolve under `defsDir`, and the
|
|
210
139
|
* target must be a real directory — a symlink at the legacy path is refused (a
|
|
211
140
|
* symlinked segment must never be parked/finalized, since finalize deletes it).
|
|
212
|
-
* Deliberate behavior change vs.
|
|
213
|
-
* at the old path
|
|
214
|
-
* it is now refused, which is fail-closed and correct.
|
|
141
|
+
* Deliberate behavior change vs. a bare `existsSync` probe: a DANGLING symlink
|
|
142
|
+
* at the old path is refused, which is fail-closed and correct.
|
|
215
143
|
*/
|
|
216
144
|
export declare function parkOldNameDir(handle: InstallCommitHandle, defsDir: string, oldRelPath: string): void;
|
|
217
145
|
/**
|
|
218
|
-
* Make the commit permanent: discard the retained previous install
|
|
219
|
-
* parked old-name dir
|
|
146
|
+
* Make the commit permanent: discard the retained previous install AND any
|
|
147
|
+
* parked old-name dir (the GitHub-only half the generic finalizer does not
|
|
148
|
+
* know about). Call ONLY after the follow-on lockfile write has durably
|
|
220
149
|
* succeeded — this is the point of no return.
|
|
221
150
|
*/
|
|
222
151
|
export declare function finalizeInstallCommit(handle: InstallCommitHandle): void;
|
|
223
152
|
/**
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
* 3. if an old-name dir was parked, rename it back to where the lockfile says.
|
|
230
|
-
* The parked new content under `undoDir` is left for the caller's staging-root
|
|
231
|
-
* cleanup to dispose of. Any throw propagates to the caller.
|
|
232
|
-
*
|
|
233
|
-
* Safe to call from a FAILED `parkOldNameDir`: that helper records
|
|
234
|
-
* `handle.oldName` only after its single rename succeeds, so a park failure
|
|
235
|
-
* leaves `oldName` unset and step 3 self-skips — there is no "park partially
|
|
236
|
-
* happened" state to reconcile (the park is one atomic rename).
|
|
153
|
+
* Restore the previous directory state after a failed commit: the GitHub-only
|
|
154
|
+
* counterpart of `finalizeInstallCommit`. Restores the swapped-out destination
|
|
155
|
+
* exactly as the generic rollback does, THEN renames the parked old-name dir
|
|
156
|
+
* back to its original name — the same order as before the transaction was
|
|
157
|
+
* generalized. Call ONLY before the follow-on lockfile write has succeeded.
|
|
237
158
|
*/
|
|
238
159
|
export declare function rollbackInstallCommit(handle: InstallCommitHandle): void;
|
|
239
|
-
/** The install lock handle — now the generic `FileLockHandle` from `lock.ts`. */
|
|
240
|
-
export type InstallLockHandle = FileLockHandle;
|
|
241
|
-
/** The install lock acquire options — now the generic `AcquireFileLockOpts` from `lock.ts`. */
|
|
242
|
-
export type AcquireLockOpts = AcquireFileLockOpts;
|
|
243
160
|
/**
|
|
244
161
|
* Acquire the per-project install lock at `lockPath`. A 1-line adapter over the
|
|
245
162
|
* generic `acquireFileLock`, pinning `label` so the timeout message reads
|
|
@@ -247,80 +164,6 @@ export type AcquireLockOpts = AcquireFileLockOpts;
|
|
|
247
164
|
* with `releaseInstallLock` in a `finally`.
|
|
248
165
|
*/
|
|
249
166
|
export declare function acquireInstallLock(lockPath: string, opts?: AcquireLockOpts): Promise<InstallLockHandle>;
|
|
250
|
-
/** Release a lock acquired by `acquireInstallLock` — the generic `releaseFileLock`. */
|
|
251
|
-
export declare const releaseInstallLock: typeof releaseFileLock;
|
|
252
|
-
/** Journal filename under `.owenloop/` (sibling of `installed.json`/`add.lock`). */
|
|
253
|
-
export declare const ADD_JOURNAL_FILENAME = "add.journal";
|
|
254
|
-
/**
|
|
255
|
-
* The two durable phases an in-flight install can be caught in. Absent (no
|
|
256
|
-
* file) is the third, happy state. Deliberately coarse — every extra journal
|
|
257
|
-
* rewrite is itself a crash window, and each install step is a single atomic
|
|
258
|
-
* rename, so directory existence/absence recovers the fine-grained progress the
|
|
259
|
-
* two phases don't record.
|
|
260
|
-
*
|
|
261
|
-
* - `applying`: written after staging+validation succeed, immediately before
|
|
262
|
-
* `commitInstall`. The ledger write (the documented commit point) has NOT yet
|
|
263
|
-
* happened, so recovery rolls BACK — unless the ledger turns out to already
|
|
264
|
-
* match (a crash in the tiny writeLockfile→rewrite window), in which case it
|
|
265
|
-
* rolls forward.
|
|
266
|
-
* - `finalizing`: written immediately after the ledger write succeeds, before
|
|
267
|
-
* `finalizeInstallCommit`. The commit point has passed, so recovery rolls
|
|
268
|
-
* FORWARD (finishes discarding the retained backup + parked old-name dir).
|
|
269
|
-
*/
|
|
270
|
-
export type AddJournalPhase = 'applying' | 'finalizing';
|
|
271
|
-
/**
|
|
272
|
-
* One crash-recovery journal record. `folder`, `stagingId`, and `oldNamePath`
|
|
273
|
-
* are single on-disk path segments (each {@link lockfilePathViolation}-checked
|
|
274
|
-
* on read); `defsDir` is compared for equality ONLY and is never joined into a
|
|
275
|
-
* mutation path; `ref`/`startedAt` are diagnostics. These invariants are NOT
|
|
276
|
-
* trusted from disk — {@link validateAddJournal} enforces every one, fail-closed.
|
|
277
|
-
*/
|
|
278
|
-
export interface AddJournal {
|
|
279
|
-
version: 1;
|
|
280
|
-
phase: AddJournalPhase;
|
|
281
|
-
/** Ledger key of the source being installed — for the ledger-match check. */
|
|
282
|
-
source: string;
|
|
283
|
-
/** 40-char hex commit sha being installed — for the ledger-match check. */
|
|
284
|
-
sha: string;
|
|
285
|
-
/** Install folder segment (`dest = join(defsDir, folder)`). Single segment. */
|
|
286
|
-
folder: string;
|
|
287
|
-
/** Basename of this run's staging dir (`stg_<hex>`). Single segment. */
|
|
288
|
-
stagingId: string;
|
|
289
|
-
/** Did `dest` exist when the journal was written (⇒ a backup dir will exist)? */
|
|
290
|
-
hadDest: boolean;
|
|
291
|
-
/** Set only for an old-name (`<owner>-<repo>`) migration. Single segment. */
|
|
292
|
-
oldNamePath?: string;
|
|
293
|
-
/** Resolved defs dir at journal-write time — equality-checked, never joined. */
|
|
294
|
-
defsDir: string;
|
|
295
|
-
/** The `@ref` this install pinned — diagnostics only. */
|
|
296
|
-
ref: string;
|
|
297
|
-
/** Journal-write epoch ms — diagnostics only. */
|
|
298
|
-
startedAt: number;
|
|
299
|
-
}
|
|
300
|
-
/**
|
|
301
|
-
* Structurally validate a parsed `add.journal`, fail-closed — the trust
|
|
302
|
-
* boundary for the journal, mirroring {@link validateLockfile}. A
|
|
303
|
-
* parseable-but-invalid journal is a hard error naming the file and the manual
|
|
304
|
-
* remedy; recovery NEVER acts on a field that has not passed through here. Every
|
|
305
|
-
* path field must be a safe single segment so a crafted journal cannot represent
|
|
306
|
-
* traversal before any `join`/`rename`. Unknown extra keys are tolerated
|
|
307
|
-
* (forward compatibility, same as the lockfile). `ref`/`startedAt` are
|
|
308
|
-
* diagnostics: validated for type when present, but not required. `path`
|
|
309
|
-
* appears only in error messages.
|
|
310
|
-
*/
|
|
311
|
-
export declare function validateAddJournal(parsed: unknown, path: string): AddJournal;
|
|
312
|
-
/**
|
|
313
|
-
* Read `.owenloop/add.journal`. Absent ⇒ `null` (the happy path — no
|
|
314
|
-
* interrupted install to recover). Present-but-unparseable ⇒ a hard error;
|
|
315
|
-
* present-but-schema-invalid ⇒ a hard error via {@link validateAddJournal}.
|
|
316
|
-
* Never silently ignores a malformed journal (that would let a crafted file
|
|
317
|
-
* quietly disable recovery) and never trusts it for filesystem paths.
|
|
318
|
-
*/
|
|
319
|
-
export declare function readAddJournal(path: string): AddJournal | null;
|
|
320
|
-
/** Write the journal atomically (tmp+rename), same discipline as the lockfile. */
|
|
321
|
-
export declare function writeAddJournal(path: string, journal: AddJournal, opts?: WriteLockfileOpts): void;
|
|
322
|
-
/** Remove the journal (force: absence is not an error — clean-completion / idempotent). */
|
|
323
|
-
export declare function removeAddJournal(path: string): void;
|
|
324
167
|
export interface RecoverInterruptedInstallArgs {
|
|
325
168
|
/** The CURRENT run's resolved defs dir — every mutation path derives from it. */
|
|
326
169
|
defsDir: string;
|
|
@@ -328,57 +171,19 @@ export interface RecoverInterruptedInstallArgs {
|
|
|
328
171
|
journalPath: string;
|
|
329
172
|
/** Path to `.owenloop/installed.json` — read to decide the commit-point boundary. */
|
|
330
173
|
lockfilePath: string;
|
|
174
|
+
/** External marker directory for fresh v2 recovery corroboration. */
|
|
175
|
+
recoveryMarkerDir?: string;
|
|
176
|
+
/** CAS-only hardening and verification actions when a shared v2 journal is found. */
|
|
177
|
+
v2Replacement?: V2ReplacementRecoveryActions;
|
|
331
178
|
}
|
|
332
179
|
/**
|
|
333
|
-
*
|
|
334
|
-
*
|
|
335
|
-
*
|
|
336
|
-
*
|
|
337
|
-
*
|
|
338
|
-
*
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
/**
|
|
342
|
-
* Bring an interrupted install back to a consistent (defs ⇔ ledger) state, then
|
|
343
|
-
* remove the journal. Called by `dispatchAdd` under the A3 install lock,
|
|
344
|
-
* BEFORE the stale-staging cleanup (the backups a rollback needs live under the
|
|
345
|
-
* staging root). No journal ⇒ returns immediately (happy path unchanged).
|
|
346
|
-
*
|
|
347
|
-
* Roll-forward vs roll-back rule: the durable ledger write is the commit point.
|
|
348
|
-
* At or past it, roll FORWARD (finish the discard); before it, roll BACK
|
|
349
|
-
* (restore the previous state). Concretely:
|
|
350
|
-
*
|
|
351
|
-
* 1. `finalizing` ⇒ roll forward: the ledger is durably new; only finalize's
|
|
352
|
-
* discards may be missing. Clear the retained backup + parked old-name and
|
|
353
|
-
* the staging root. Trivially idempotent.
|
|
354
|
-
* 2. `applying` + the ledger already records this source at `journal.sha`/
|
|
355
|
-
* `journal.folder` ⇒ the commit MAY have landed, but the ledger match alone
|
|
356
|
-
* does not prove it — branch on disk: dest present ⇒ the swap completed ⇒
|
|
357
|
-
* roll forward; dest ABSENT ⇒ a same-sha re-add crashed inside commitInstall's
|
|
358
|
-
* dest→backup / staging→dest window and backupDir holds the only copy ⇒ roll
|
|
359
|
-
* back (restore it) rather than discarding it (which would be silent data
|
|
360
|
-
* loss against a ledger that still records the install).
|
|
361
|
-
* 3. `applying`, no ledger match (or ledger match with dest absent) ⇒ roll back
|
|
362
|
-
* through the guarded, idempotent decision table below (mirroring
|
|
363
|
-
* `rollbackInstallCommit`'s order) — EXCEPT the case-(c) fresh-install
|
|
364
|
-
* discard, which acts on the journal alone (staging + backup both absent) and
|
|
365
|
-
* so requires LEDGER corroboration of an interrupted old-name migration
|
|
366
|
-
* (`installed.path === journal.oldNamePath`) before it will delete an
|
|
367
|
-
* existing dest; uncorroborated ⇒ refuse fail-closed, mutate nothing, leave
|
|
368
|
-
* the journal and dest in place (the journal is repo-committable, so a forged
|
|
369
|
-
* one must never drive a deletion).
|
|
370
|
-
*
|
|
371
|
-
* Crash-safety of recovery itself: the journal is removed LAST, after all
|
|
372
|
-
* restore/discard renames, and every step is a single atomic rename guarded by
|
|
373
|
-
* existence probes — so a crash mid-recovery leaves the journal intact and a
|
|
374
|
-
* strict subset of the work done; the next attempt re-derives state from disk
|
|
375
|
-
* and continues (the dest-absent arm of case (b), the touch-nothing arm of
|
|
376
|
-
* case (c), and the case-(c) uncorroborated refusal ARE the mid-rollback resume
|
|
377
|
-
* / fail-closed states). Running it twice is a no-op the second time.
|
|
378
|
-
*
|
|
379
|
-
* Any refusal (invalid journal, defsDir mismatch, symlink where a directory is
|
|
380
|
-
* expected, contradictory disk state) throws WITHOUT mutating anything and
|
|
381
|
-
* leaves the journal in place; `dispatchAdd` sets `preserveStagingRoot` so its
|
|
382
|
-
* `finally` cannot then destroy the backups a later attempt needs.
|
|
180
|
+
* Bring an interrupted GitHub-route install back to a consistent (defs ⇔
|
|
181
|
+
* lockfile) state, then remove the journal. Called by `dispatchAdd` under the
|
|
182
|
+
* per-project install lock, BEFORE the stale-staging cleanup. Also recovers a
|
|
183
|
+
* v2 (workflow-store) journal found at the same location — the generic
|
|
184
|
+
* recovery dispatches on journal version. See `src/install.ts`
|
|
185
|
+
* `recoverInterruptedInstall` for the full roll-forward/roll-back decision
|
|
186
|
+
* table and crash-safety argument. Refusals throw without mutating anything
|
|
187
|
+
* and leave the journal in place.
|
|
383
188
|
*/
|
|
384
189
|
export declare function recoverInterruptedInstall(args: RecoverInterruptedInstallArgs): RecoveryOutcome;
|