owenloop 0.4.1 → 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.
Files changed (282) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +182 -53
  3. package/bin/owenloop.mjs +50 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +176 -0
  5. package/dist/packages/work/src/agent/brief.js +197 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +141 -0
  7. package/dist/packages/work/src/agent/loop.js +669 -0
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  11. package/dist/packages/work/src/agent/workdir.js +319 -0
  12. package/dist/packages/work/src/bundle/cache.d.ts +92 -0
  13. package/dist/packages/work/src/bundle/cache.js +338 -0
  14. package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
  15. package/dist/packages/work/src/bundle/fetch.js +345 -0
  16. package/dist/packages/work/src/bundle/types.d.ts +164 -0
  17. package/dist/packages/work/src/bundle/types.js +1 -0
  18. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  19. package/dist/packages/work/src/consumed-verifier.js +205 -0
  20. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  21. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  22. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  23. package/dist/packages/work/src/credentials/reader.js +32 -0
  24. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  25. package/dist/packages/work/src/credentials/resolve.js +56 -0
  26. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  27. package/dist/packages/work/src/exec/instructions.js +323 -0
  28. package/dist/packages/work/src/exec/loop.d.ts +40 -0
  29. package/dist/packages/work/src/exec/loop.js +332 -0
  30. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  31. package/dist/packages/work/src/exec/payload.js +54 -0
  32. package/dist/packages/work/src/exec/receipt.d.ts +41 -0
  33. package/dist/packages/work/src/exec/receipt.js +32 -0
  34. package/dist/packages/work/src/exec/runner.d.ts +71 -0
  35. package/dist/packages/work/src/exec/runner.js +256 -0
  36. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  37. package/dist/packages/work/src/harness/child-env.js +134 -0
  38. package/dist/packages/work/src/harness/claude.d.ts +140 -0
  39. package/dist/packages/work/src/harness/claude.js +837 -0
  40. package/dist/packages/work/src/harness/codex.d.ts +111 -0
  41. package/dist/packages/work/src/harness/codex.js +1024 -0
  42. package/dist/packages/work/src/harness/contract.d.ts +308 -0
  43. package/dist/packages/work/src/harness/contract.js +32 -0
  44. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  45. package/dist/packages/work/src/harness/fake.js +91 -0
  46. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  47. package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
  48. package/dist/packages/work/src/harness/permissions.d.ts +75 -0
  49. package/dist/packages/work/src/harness/permissions.js +182 -0
  50. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  51. package/dist/packages/work/src/harness/registry.js +45 -0
  52. package/dist/packages/work/src/harness/session-store.d.ts +181 -0
  53. package/dist/packages/work/src/harness/session-store.js +523 -0
  54. package/dist/packages/work/src/harness/types.d.ts +29 -0
  55. package/dist/packages/work/src/harness/types.js +14 -0
  56. package/dist/packages/work/src/harnesses.d.ts +38 -0
  57. package/dist/packages/work/src/harnesses.js +38 -0
  58. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  59. package/dist/packages/work/src/hold/loop.js +23 -0
  60. package/dist/packages/work/src/hold/mcp.d.ts +75 -0
  61. package/dist/packages/work/src/hold/mcp.js +264 -0
  62. package/dist/packages/work/src/hub/client.d.ts +23 -0
  63. package/dist/packages/work/src/hub/client.js +91 -0
  64. package/dist/packages/work/src/hub/types.d.ts +326 -0
  65. package/dist/packages/work/src/hub/types.js +26 -0
  66. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  67. package/dist/packages/work/src/lease/loop.js +277 -0
  68. package/dist/packages/work/src/main.d.ts +1 -0
  69. package/dist/packages/work/src/main.js +48 -0
  70. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  71. package/dist/packages/work/src/mcp/server.js +320 -0
  72. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  73. package/dist/packages/work/src/owenloop-bin.js +18 -0
  74. package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
  75. package/dist/packages/work/src/roles/agent-run.js +529 -0
  76. package/dist/packages/work/src/roles/exec.d.ts +48 -0
  77. package/dist/packages/work/src/roles/exec.js +228 -0
  78. package/dist/packages/work/src/roles/hold.d.ts +72 -0
  79. package/dist/packages/work/src/roles/hold.js +363 -0
  80. package/dist/packages/work/src/roles/join.d.ts +18 -0
  81. package/dist/packages/work/src/roles/join.js +204 -0
  82. package/dist/packages/work/src/roles/lint.d.ts +58 -0
  83. package/dist/packages/work/src/roles/lint.js +234 -0
  84. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  85. package/dist/packages/work/src/roles/prepare.js +249 -0
  86. package/dist/packages/work/src/roles/release.d.ts +48 -0
  87. package/dist/packages/work/src/roles/release.js +137 -0
  88. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  89. package/dist/packages/work/src/roles/sessions.js +180 -0
  90. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  91. package/dist/packages/work/src/roles/settings.js +71 -0
  92. package/dist/packages/work/src/roles/shift.d.ts +13 -0
  93. package/dist/packages/work/src/roles/shift.js +250 -0
  94. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  95. package/dist/packages/work/src/roles/signals.js +62 -0
  96. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  97. package/dist/packages/work/src/settings/provision.js +47 -0
  98. package/dist/packages/work/src/settings/settings.d.ts +136 -0
  99. package/dist/packages/work/src/settings/settings.js +155 -0
  100. package/dist/packages/work/src/shift/client.d.ts +24 -0
  101. package/dist/packages/work/src/shift/client.js +124 -0
  102. package/dist/packages/work/src/shift/loop.d.ts +131 -0
  103. package/dist/packages/work/src/shift/loop.js +751 -0
  104. package/dist/packages/work/src/shift/protocol.d.ts +95 -0
  105. package/dist/packages/work/src/shift/protocol.js +24 -0
  106. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  107. package/dist/packages/work/src/shift/routing.js +50 -0
  108. package/dist/packages/work/src/shift/runtime.d.ts +45 -0
  109. package/dist/packages/work/src/shift/runtime.js +337 -0
  110. package/dist/packages/work/src/shift/server.d.ts +23 -0
  111. package/dist/packages/work/src/shift/server.js +716 -0
  112. package/dist/packages/work/src/shift/spawn.d.ts +109 -0
  113. package/dist/packages/work/src/shift/spawn.js +158 -0
  114. package/dist/packages/work/src/shift/state.d.ts +79 -0
  115. package/dist/packages/work/src/shift/state.js +385 -0
  116. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  117. package/dist/packages/work/src/submit-proof.js +93 -0
  118. package/dist/packages/work/src/usage.d.ts +6 -0
  119. package/dist/packages/work/src/usage.js +175 -0
  120. package/dist/src/add.d.ts +189 -0
  121. package/dist/src/add.js +300 -0
  122. package/dist/src/archive.d.ts +97 -0
  123. package/dist/src/archive.js +591 -0
  124. package/dist/src/bundle/index.d.ts +64 -0
  125. package/dist/src/bundle/index.js +508 -0
  126. package/dist/src/bundle/manifest.d.ts +50 -0
  127. package/dist/src/bundle/manifest.js +435 -0
  128. package/dist/src/bundle/runtime.d.ts +26 -0
  129. package/dist/src/bundle/runtime.js +64 -0
  130. package/dist/src/bundle/tar.d.ts +62 -0
  131. package/dist/src/bundle/tar.js +238 -0
  132. package/dist/src/bundle/types.d.ts +105 -0
  133. package/dist/src/bundle/types.js +21 -0
  134. package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
  135. package/dist/src/cli.js +5968 -0
  136. package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
  137. package/dist/{credentials.js → src/credentials.js} +35 -31
  138. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  139. package/dist/src/crypto/allowed-signers.js +307 -0
  140. package/dist/src/crypto/canonical.d.ts +8 -0
  141. package/dist/src/crypto/canonical.js +92 -0
  142. package/dist/src/crypto/chain.d.ts +65 -0
  143. package/dist/src/crypto/chain.js +377 -0
  144. package/dist/src/crypto/dsse.d.ts +209 -0
  145. package/dist/src/crypto/dsse.js +282 -0
  146. package/dist/src/crypto/enrollment.d.ts +78 -0
  147. package/dist/src/crypto/enrollment.js +186 -0
  148. package/dist/src/crypto/index.d.ts +48 -0
  149. package/dist/src/crypto/index.js +44 -0
  150. package/dist/src/crypto/keys.d.ts +258 -0
  151. package/dist/src/crypto/keys.js +908 -0
  152. package/dist/src/crypto/org-root.d.ts +33 -0
  153. package/dist/src/crypto/org-root.js +78 -0
  154. package/dist/src/crypto/origin-rules.d.ts +56 -0
  155. package/dist/src/crypto/origin-rules.js +143 -0
  156. package/dist/src/crypto/policy-floor.d.ts +98 -0
  157. package/dist/src/crypto/policy-floor.js +353 -0
  158. package/dist/src/crypto/records.d.ts +316 -0
  159. package/dist/src/crypto/records.js +157 -0
  160. package/dist/src/crypto/scope.d.ts +49 -0
  161. package/dist/src/crypto/scope.js +83 -0
  162. package/dist/src/crypto/ssh.d.ts +171 -0
  163. package/dist/src/crypto/ssh.js +396 -0
  164. package/dist/src/crypto/submission.d.ts +33 -0
  165. package/dist/src/crypto/submission.js +47 -0
  166. package/dist/src/crypto/trust-roots.d.ts +29 -0
  167. package/dist/src/crypto/trust-roots.js +39 -0
  168. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  169. package/dist/src/crypto/verify-consumed.js +259 -0
  170. package/dist/src/crypto/verify-origin.d.ts +50 -0
  171. package/dist/src/crypto/verify-origin.js +151 -0
  172. package/dist/src/crypto/verify-publication.d.ts +60 -0
  173. package/dist/src/crypto/verify-publication.js +150 -0
  174. package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
  175. package/dist/{defs.js → src/defs.js} +181 -61
  176. package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
  177. package/dist/{engine.js → src/engine.js} +251 -47
  178. package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
  179. package/dist/{factory.js → src/factory.js} +16 -4
  180. package/dist/src/global-config.d.ts +59 -0
  181. package/dist/src/global-config.js +84 -0
  182. package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
  183. package/dist/{hub.js → src/hub.js} +493 -52
  184. package/dist/src/index.d.ts +47 -0
  185. package/dist/src/index.js +41 -0
  186. package/dist/src/install.d.ts +538 -0
  187. package/dist/src/install.js +1981 -0
  188. package/dist/src/lock.d.ts +38 -0
  189. package/dist/src/lock.js +325 -0
  190. package/dist/src/mcp/serve.d.ts +109 -0
  191. package/dist/{mcp → src/mcp}/serve.js +335 -75
  192. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  193. package/dist/{mcp → src/mcp}/server.js +18 -10
  194. package/dist/{model.d.ts → src/model.d.ts} +15 -0
  195. package/dist/{model.js → src/model.js} +112 -2
  196. package/dist/src/order-resolver.d.ts +184 -0
  197. package/dist/src/order-resolver.js +252 -0
  198. package/dist/src/package-version.d.ts +10 -0
  199. package/dist/src/package-version.js +42 -0
  200. package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
  201. package/dist/{paths.js → src/paths.js} +18 -0
  202. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  203. package/dist/src/schemas/index.d.ts +1416 -0
  204. package/dist/src/schemas/index.js +31 -0
  205. package/dist/src/schemas/order.v1.schema.json +106 -0
  206. package/dist/src/schemas/origin.v1.schema.json +68 -0
  207. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  208. package/dist/src/schemas/publication.v1.schema.json +31 -0
  209. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  210. package/dist/src/schemas/submission.v1.schema.json +61 -0
  211. package/dist/src/store/def-source.d.ts +52 -0
  212. package/dist/src/store/def-source.js +335 -0
  213. package/dist/src/store/index-file.d.ts +69 -0
  214. package/dist/src/store/index-file.js +151 -0
  215. package/dist/src/store/index.d.ts +27 -0
  216. package/dist/src/store/index.js +22 -0
  217. package/dist/src/store/ingestor.d.ts +43 -0
  218. package/dist/src/store/ingestor.js +211 -0
  219. package/dist/src/store/install.d.ts +228 -0
  220. package/dist/src/store/install.js +555 -0
  221. package/dist/src/store/instruction-source.d.ts +49 -0
  222. package/dist/src/store/instruction-source.js +298 -0
  223. package/dist/src/store/origin-evidence.d.ts +21 -0
  224. package/dist/src/store/origin-evidence.js +66 -0
  225. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  226. package/dist/src/store/pre-commit-verifier.js +418 -0
  227. package/dist/src/store/resolve.d.ts +138 -0
  228. package/dist/src/store/resolve.js +363 -0
  229. package/dist/src/store/types.d.ts +288 -0
  230. package/dist/src/store/types.js +356 -0
  231. package/dist/{types.d.ts → src/types.d.ts} +58 -24
  232. package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
  233. package/dist/src/untar.js +38 -0
  234. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  235. package/dist/{util.js → src/util.js} +3 -2
  236. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  237. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  238. package/docs/agent-runner.md +86 -0
  239. package/docs/authoring.md +150 -59
  240. package/docs/bundles.md +250 -0
  241. package/docs/cli.md +1758 -163
  242. package/docs/crypto.md +816 -0
  243. package/docs/design.md +374 -52
  244. package/docs/embedding.md +135 -27
  245. package/docs/wire-contracts.md +380 -0
  246. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  247. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  248. package/examples/workflows/judges/gate-sharpness.md +39 -0
  249. package/examples/workflows/judges/security.md +34 -0
  250. package/package.json +22 -8
  251. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  252. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  253. package/plugins/claude-code/plugin/.mcp.json +14 -0
  254. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  255. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  256. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  257. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  258. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  259. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  260. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  261. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  262. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  263. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  264. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  265. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  266. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  267. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  268. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
  269. package/dist/add.d.ts +0 -384
  270. package/dist/add.js +0 -834
  271. package/dist/cli.js +0 -3270
  272. package/dist/index.d.ts +0 -32
  273. package/dist/index.js +0 -23
  274. package/dist/lock.d.ts +0 -80
  275. package/dist/lock.js +0 -217
  276. package/dist/mcp/serve.d.ts +0 -84
  277. package/dist/untar.js +0 -164
  278. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  279. /package/dist/{schema.js → src/schema.js} +0 -0
  280. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  281. /package/dist/{store.js → src/store.js} +0 -0
  282. /package/dist/{types.js → src/types.js} +0 -0
package/dist/add.d.ts DELETED
@@ -1,384 +0,0 @@
1
- /**
2
- * Pure helpers for the `owenloop add <owner>/<repo>[@ref]` CLI verb (workflow
3
- * distribution Stage 1 — see the design doc this implements,
4
- * `docs/workflow-distribution.md` §3 in the companion hub repo).
5
- *
6
- * These are the network-free, filesystem-adjacent pieces: spec parsing, URL
7
- * building, lockfile read/write, and file installation. The network fetch and
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
- */
12
- import { releaseFileLock } from './lock.ts';
13
- import type { AcquireFileLockOpts, FileLockHandle } from './lock.ts';
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;
36
- export interface RepoSpec {
37
- owner: string;
38
- repo: string;
39
- ref: string;
40
- }
41
- /** Parse `owner/repo` or `owner/repo@ref` into its parts; `ref` defaults to `'HEAD'`. */
42
- export declare function parseRepoSpec(spec: string): RepoSpec;
43
- /**
44
- * The single-path-segment install folder for a package, derived from its
45
- * `owner/repo` identity: `<owner>-<repo>-<sha256(owner/repo)[:8]>`. The 8-hex
46
- * suffix makes the (owner,repo)→folder mapping injective in practice — the old
47
- * `<owner>-<repo>` scheme collided (`a-b/c` and `a/b-c` both mapped to
48
- * `a-b-c`, and the second install clobbered the first). Keying on the source
49
- * (matching the lockfile key) keeps the folder STABLE across versions, so a
50
- * user's documented `--defs workflows/<folder>` pointer survives upgrades.
51
- */
52
- export declare function installFolder(owner: string, repo: string): string;
53
- export declare function githubShaUrl(owner: string, repo: string, ref: string): string;
54
- export declare function githubTarballUrl(owner: string, repo: string, sha: string): string;
55
- /**
56
- * One installed-package record. `path` is a single on-disk folder segment (see
57
- * {@link lockfilePathViolation}); `sha` is a 40-char hex commit sha; `source`
58
- * equals the record's key in {@link Lockfile.installed}. These invariants are
59
- * NOT trusted from disk — {@link validateLockfile} enforces every one on read,
60
- * fail-closed, before any consumer acts on an entry.
61
- */
62
- export interface InstalledEntry {
63
- source: string;
64
- ref: string;
65
- sha: string;
66
- installedAt: number;
67
- path: string;
68
- files: string[];
69
- }
70
- export interface Lockfile {
71
- version: 1;
72
- installed: Record<string, InstalledEntry>;
73
- }
74
- /**
75
- * Structurally validate a parsed `installed.json`, fail-closed. A
76
- * parseable-but-schema-invalid lockfile is a hard error naming the offending
77
- * entry+field — never silently reset to `{}` (which would erase ownership
78
- * records and re-enable the clobbering {@link installFolder} was hardened
79
- * against) and never normalized. This is the trust boundary for the lockfile:
80
- * downstream code (`dispatchAdd`, `parkOldNameDir`) may only act on entries
81
- * that have passed through here. Critically, EVERY entry is validated, not just
82
- * the one being installed — `dispatchAdd` re-serializes the whole lockfile on
83
- * success, so acting while carrying a poisoned sibling entry would re-persist
84
- * it. Unknown extra keys (on the lockfile or an entry) are tolerated for
85
- * forward compatibility; required shape is enforced, additions are not
86
- * forbidden. Returns the value narrowed to {@link Lockfile}. `path` appears
87
- * only in error messages.
88
- */
89
- export declare function validateLockfile(parsed: unknown, path: string): Lockfile;
90
- /**
91
- * Read `.owenloop/installed.json`; a missing file is an empty lockfile, not an
92
- * error. A file that exists but does not parse is a hard error naming the path
93
- * — never silently reset to `{}`, which would erase ownership records and
94
- * re-enable the clobbering `installFolder` was hardened against. A file that
95
- * parses but is structurally invalid (bad version, malformed entry, a `path`
96
- * that is not a safe single segment, a bad `sha`/`files`) is likewise a
97
- * fail-closed hard error — see {@link validateLockfile}. The lockfile is never
98
- * trusted for filesystem paths.
99
- */
100
- 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
- export interface WriteLockfileOpts {
115
- /**
116
- * Removal op used to clean up the temp sibling when the atomic rename fails.
117
- * Defaults to `rmSync`; injectable so a test can force the cleanup itself to
118
- * throw and prove the ORIGINAL rename error still surfaces — the same
119
- * test-determinism seam as `AcquireLockOpts` in this file.
120
- */
121
- rm?: (path: string, opts: {
122
- force: true;
123
- }) => void;
124
- }
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
- /**
129
- * Write `files` (relative path → bytes) into `targetDir` (a staging dir), NOT
130
- * the final install destination. Unlike a direct install, this never clears a
131
- * live folder: the caller stages here, validates, then `commitInstall`s with an
132
- * atomic rename, so a failure mid-write can only ever corrupt throwaway staging
133
- * content. Returns the sorted list of relative paths written.
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.
143
- */
144
- export declare class RollbackFailedError extends Error {
145
- readonly preservedAt: string;
146
- constructor(message: string, preservedAt: string);
147
- }
148
- /**
149
- * A handle to a committed-but-not-yet-finalized install, returned by
150
- * `commitInstall`. The install directory already holds the NEW content, but the
151
- * displaced previous install (and any migrated old-name dir) are RETAINED under
152
- * the staging root — not yet discarded — so the caller can still roll the
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.
159
- */
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;
167
- /** Set by `parkOldNameDir` when an old-naming dir was migrated off. */
168
- oldName?: {
169
- originalPath: string;
170
- parkedAt: string;
171
- };
172
- }
173
- /**
174
- * Atomically swap a validated `stagingDir` into place at `defsDir/folder`,
175
- * rolling back to the previous install if the swap itself fails. Both dirs live
176
- * on the same filesystem by construction (staging is under `defsDir`), so the
177
- * renames are atomic and `EXDEV` is impossible.
178
- *
179
- * Two-phase commit: unlike a one-shot swap, this does NOT delete the displaced
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).
192
- */
193
- export declare function commitInstall(defsDir: string, folder: string, stagingDir: string): InstallCommitHandle;
194
- /**
195
- * Migrate a source off its old `<owner>-<repo>` install directory by PARKING it
196
- * (rename → `<stagingDir>-undo-oldname`) instead of deleting it, so a later
197
- * rollback can put it back where the (still-unchanged) lockfile expects it.
198
- * Records the move on `handle.oldName`. If the old dir does not exist on disk
199
- * (the lockfile names a path that is already gone), records nothing — matching
200
- * the previous `rmSync(..., { force: true })` tolerance of absence.
201
- *
202
- * Defense-in-depth (Layer 3): even though `readLockfile`/`validateLockfile` and
203
- * the use-site in `dispatchAdd` already constrain `oldRelPath` to a safe single
204
- * segment, the authoritative containment check is re-asserted HERE, at the
205
- * mutation site, before any rename — a poisoned `existing.path` must never move
206
- * a directory outside `defsDir` (which `finalizeInstallCommit` would then
207
- * recursively delete). Following this project's TOCTOU discipline, the check
208
- * that matters is the one at the filesystem operation, not only up front:
209
- * `oldRelPath` must be a single segment AND resolve under `defsDir`, and the
210
- * target must be a real directory — a symlink at the legacy path is refused (a
211
- * symlinked segment must never be parked/finalized, since finalize deletes it).
212
- * Deliberate behavior change vs. the old `existsSync` probe: a DANGLING symlink
213
- * at the old path was previously silently ignored (existsSync follows links);
214
- * it is now refused, which is fail-closed and correct.
215
- */
216
- export declare function parkOldNameDir(handle: InstallCommitHandle, defsDir: string, oldRelPath: string): void;
217
- /**
218
- * Make the commit permanent: discard the retained previous install and any
219
- * parked old-name dir. Call ONLY after the follow-on lockfile write has durably
220
- * succeeded — this is the point of no return.
221
- */
222
- export declare function finalizeInstallCommit(handle: InstallCommitHandle): void;
223
- /**
224
- * Undo a `commitInstall` (plus any `parkOldNameDir`), restoring the pre-commit
225
- * directory state. Order matters:
226
- * 1. park the new content out of `dest` (rename dest → undoDir) — for a fresh
227
- * install, this alone restores "nothing installed";
228
- * 2. if a previous install was displaced, rename its backup back over `dest`;
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).
237
- */
238
- 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
- /**
244
- * Acquire the per-project install lock at `lockPath`. A 1-line adapter over the
245
- * generic `acquireFileLock`, pinning `label` so the timeout message reads
246
- * "another owenloop add is in progress …" byte-for-byte as before. Always pair
247
- * with `releaseInstallLock` in a `finally`.
248
- */
249
- 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
- export interface RecoverInterruptedInstallArgs {
325
- /** The CURRENT run's resolved defs dir — every mutation path derives from it. */
326
- defsDir: string;
327
- /** Path to `.owenloop/add.journal`. */
328
- journalPath: string;
329
- /** Path to `.owenloop/installed.json` — read to decide the commit-point boundary. */
330
- lockfilePath: string;
331
- }
332
- /**
333
- * What `recoverInterruptedInstall` DID, for callers (the offline `add --recover`
334
- * entry point) that report the result to the user. A refusal is NOT an outcome —
335
- * it throws. `'rolled-back'` collapses the roll-back table's terminal arms,
336
- * including the touch-nothing / already-consistent ones (distinguishing
337
- * "restored" from "was already consistent" per arm would thread state through
338
- * the decision table for message cosmetics only).
339
- */
340
- export type RecoveryOutcome = 'no-journal' | 'rolled-forward' | 'rolled-back';
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.
383
- */
384
- export declare function recoverInterruptedInstall(args: RecoverInterruptedInstallArgs): RecoveryOutcome;