@runeditrun/rer 0.2.84 → 0.2.86

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 (236) hide show
  1. package/README.md +156 -50
  2. package/cli/README.md +78 -2
  3. package/cli/agent-door.mjs +149 -0
  4. package/cli/agent-fixtures.mjs +16 -0
  5. package/cli/agent-mail.mjs +54 -0
  6. package/cli/agent-network.mjs +64 -0
  7. package/cli/agent-reviewers.mjs +110 -0
  8. package/cli/agent-secrets.mjs +23 -0
  9. package/cli/agent-sponsors.mjs +43 -0
  10. package/cli/agent-surface.mjs +34 -0
  11. package/cli/agent-webhooks.mjs +19 -0
  12. package/cli/authoring.mjs +2 -1
  13. package/cli/bounded.mjs +1 -1
  14. package/cli/business/archive-task.mjs +32 -0
  15. package/cli/business/carry.mjs +151 -0
  16. package/cli/business/catchup-task.mjs +42 -0
  17. package/cli/business/choices.mjs +97 -0
  18. package/cli/business/command.mjs +29 -6
  19. package/cli/business/connect.mjs +20 -8
  20. package/cli/business/detector.mjs +4 -1
  21. package/cli/business/device.mjs +13 -0
  22. package/cli/business/export-inputs.mjs +69 -0
  23. package/cli/business/export-task.mjs +17 -0
  24. package/cli/business/invocation.mjs +8 -1
  25. package/cli/business/keychain.mjs +8 -1
  26. package/cli/business/lease.mjs +11 -1
  27. package/cli/business/local-commands.mjs +80 -30
  28. package/cli/business/outbound.mjs +9 -4
  29. package/cli/business/parsers-config.mjs +8 -7
  30. package/cli/business/parsers-syntax.mjs +7 -3
  31. package/cli/business/permissions.mjs +2 -0
  32. package/cli/business/questions.mjs +89 -6
  33. package/cli/business/setup-command.mjs +49 -0
  34. package/cli/business/setup-company.json +15 -0
  35. package/cli/business/setup-demo.mjs +95 -0
  36. package/cli/business/state.mjs +44 -10
  37. package/cli/business/supervisor.mjs +97 -32
  38. package/cli/business/vendor-door.mjs +230 -0
  39. package/cli/business/vendors/README.md +29 -3
  40. package/cli/business/vendors/common.mjs +8 -6
  41. package/cli/business/vendors/index.mjs +22 -11
  42. package/cli/business/vendors/sorry.mjs +106 -0
  43. package/cli/container-transfer.mjs +2 -2
  44. package/cli/contract.mjs +7 -7
  45. package/cli/demo-deploy-error.mjs +14 -0
  46. package/cli/demo-native.mjs +6 -2
  47. package/cli/deploy-command.mjs +6 -4
  48. package/cli/deploy-config.mjs +1 -1
  49. package/cli/deploy-owner-input.mjs +3 -1
  50. package/cli/deploy-variables.mjs +58 -0
  51. package/cli/deploy.mjs +9 -7
  52. package/cli/door-clauses.mjs +157 -0
  53. package/cli/errors.mjs +1 -1
  54. package/cli/export.mjs +16 -4
  55. package/cli/hosted-output.mjs +17 -7
  56. package/cli/human-error.mjs +20 -0
  57. package/cli/inspect.mjs +4 -0
  58. package/cli/jsonc.mjs +8 -4
  59. package/cli/lifecycle.mjs +26 -6
  60. package/cli/main.mjs +2 -1
  61. package/cli/managed-data-schema.mjs +127 -0
  62. package/cli/managed-data-zip.mjs +116 -0
  63. package/cli/managed-data.mjs +110 -0
  64. package/cli/managed-server.mjs +25 -14
  65. package/cli/native-owner-entry.mjs +86 -0
  66. package/cli/output.mjs +3 -2
  67. package/cli/parse.mjs +2 -2
  68. package/cli/portability-empty.mjs +65 -0
  69. package/cli/portability-migrations.mjs +33 -9
  70. package/cli/portability-policy.mjs +5 -2
  71. package/cli/portability-worker.mjs +15 -6
  72. package/cli/portability.mjs +30 -8
  73. package/cli/production-auth.mjs +1 -1
  74. package/cli/production-mail.mjs +8 -2
  75. package/cli/ready-summary.mjs +9 -0
  76. package/cli/run-transfers.mjs +37 -0
  77. package/cli/runtime-front-door.mjs +4 -4
  78. package/cli/server-proxy.mjs +4 -3
  79. package/cli/server-registry.mjs +13 -8
  80. package/cli/site.mjs +6 -1
  81. package/cli/transfers.mjs +17 -4
  82. package/edition-authoring/archive-source.mjs +59 -0
  83. package/edition-authoring/base-copies.mjs +147 -25
  84. package/edition-authoring/cli.mjs +1 -1
  85. package/edition-authoring/edition-migrations.mjs +7 -3
  86. package/edition-authoring/module-closure.mjs +2 -16
  87. package/edition-authoring/workflow-copies.mjs +1 -1
  88. package/edition-authoring/workflow-scripts.mjs +12 -3
  89. package/foundation/runtime/contract-docs.mjs +218 -34
  90. package/foundation/runtime/contract-prose-patterns.mjs +14 -0
  91. package/foundation/runtime/contract-prose.mjs +88 -0
  92. package/foundation/runtime/run-data.d.mts +1 -0
  93. package/foundation/runtime/run-data.mjs +2 -0
  94. package/global/CHANGELOG.md +126 -0
  95. package/global/README.md +156 -50
  96. package/global/cli/command.mjs +8 -2
  97. package/global/cli/install.mjs +4 -5
  98. package/global/cli/path-link.mjs +3 -2
  99. package/global/cli/repo-command.mjs +3 -7
  100. package/global/door/command.mjs +3 -1
  101. package/global/launch/dev.mjs +12 -2
  102. package/global/launch/facts.mjs +2 -2
  103. package/global/launch/render.mjs +16 -9
  104. package/global/launch/state.mjs +4 -4
  105. package/global/main.mjs +13 -8
  106. package/install.sh +17 -6
  107. package/modules/agent-door/CLAUSES.md +215 -0
  108. package/modules/agent-door/conformance/audit.mjs +66 -0
  109. package/modules/agent-door/conformance/authority.d.mts +2 -0
  110. package/modules/agent-door/conformance/authority.mjs +17 -0
  111. package/modules/agent-door/conformance/crypto.mjs +36 -0
  112. package/modules/agent-door/conformance/discovery.mjs +61 -0
  113. package/modules/agent-door/conformance/index.mjs +41 -0
  114. package/modules/agent-door/conformance/invocation.mjs +32 -0
  115. package/modules/agent-door/conformance/journey.mjs +112 -0
  116. package/modules/agent-door/conformance/narrowing.d.mts +1 -0
  117. package/modules/agent-door/conformance/narrowing.mjs +21 -0
  118. package/modules/agent-door/conformance/negative.mjs +47 -0
  119. package/modules/agent-door/conformance/network-modules.mjs +86 -0
  120. package/modules/agent-door/conformance/network-runtime.mjs +46 -0
  121. package/modules/agent-door/conformance/policy-phases.mjs +75 -0
  122. package/modules/agent-door/conformance/protocol.mjs +145 -0
  123. package/modules/agent-door/conformance/replay.mjs +38 -0
  124. package/modules/agent-door/conformance/schema.mjs +71 -0
  125. package/modules/agent-door/conformance/security.mjs +33 -0
  126. package/modules/agent-door/conformance/sponsors.mjs +68 -0
  127. package/modules/agent-door/conformance/surface.mjs +89 -0
  128. package/modules/agent-door/conformance/target.mjs +18 -0
  129. package/modules/agent-door/conformance/tool-name.d.mts +1 -0
  130. package/modules/agent-door/conformance/tool-name.mjs +7 -0
  131. package/modules/agent-door/conformance/webhooks.mjs +30 -0
  132. package/modules/container/README.md +6 -1
  133. package/modules/container/adapters/d1-limits.mjs +286 -0
  134. package/modules/container/adapters/d1-sqlite.mjs +95 -0
  135. package/modules/container/adapters/d1-workerd-preload.mjs +19 -0
  136. package/modules/container/adapters/d1-workerd-setup.mjs +26 -0
  137. package/modules/container/adapters/d1-workerd.mjs +5 -0
  138. package/modules/container/adapters/sqlite-worker.mjs +5 -3
  139. package/modules/container/build.mjs +1 -0
  140. package/modules/container/image-variables.mjs +14 -3
  141. package/modules/container/transfer.mjs +14 -4
  142. package/modules/container/worker-engine.mjs +3 -3
  143. package/modules/demo-host/README.md +6 -0
  144. package/modules/demo-host/build.mjs +1 -0
  145. package/modules/demo-host/native/prepare.mjs +2 -1
  146. package/modules/demo-host/native/sql.mjs +7 -2
  147. package/modules/demo-host/ownership.mjs +39 -0
  148. package/modules/demo-host/plan.mjs +2 -1
  149. package/modules/demo-host/remove.mjs +6 -1
  150. package/modules/deploy-kit/README.md +22 -2
  151. package/modules/deploy-kit/d1-import-diagnostics.mjs +56 -0
  152. package/modules/deploy-kit/d1-import.mjs +17 -5
  153. package/modules/deploy-kit/diagnostics.mjs +29 -3
  154. package/modules/deploy-kit/owner-cli.mjs +20 -7
  155. package/modules/deploy-kit/provider-transport.mjs +19 -4
  156. package/modules/deploy-kit/provider.mjs +57 -22
  157. package/modules/deploy-kit/readiness-window.mjs +1 -1
  158. package/modules/deploy-kit/site.mjs +8 -3
  159. package/modules/deploy-kit/worker.mjs +4 -4
  160. package/modules/import-kit/schema/importer-verification-receipt.schema.json +171 -0
  161. package/modules/import-kit/schema/importers.schema.json +107 -0
  162. package/modules/import-kit/src/d1/README.md +23 -4
  163. package/modules/import-kit/src/d1/atomic-prefix.ts +2 -2
  164. package/modules/import-kit/src/d1/budget.ts +15 -7
  165. package/modules/import-kit/src/d1/column-layout.ts +5 -0
  166. package/modules/import-kit/src/d1/creation.ts +15 -8
  167. package/modules/import-kit/src/d1/database.ts +3 -3
  168. package/modules/import-kit/src/d1/erasure-pages.ts +2 -1
  169. package/modules/import-kit/src/d1/erasure.ts +2 -2
  170. package/modules/import-kit/src/d1/jobs.ts +10 -6
  171. package/modules/import-kit/src/d1/plans.ts +14 -8
  172. package/modules/import-kit/src/d1/retirement.ts +2 -2
  173. package/modules/import-kit/src/d1/sets.ts +1 -3
  174. package/modules/import-kit/src/d1/staged-creation.ts +3 -3
  175. package/modules/import-kit/src/door/ADOPTING.md +20 -0
  176. package/modules/import-kit/src/door/README.md +2 -1
  177. package/modules/import-kit/src/door/admission.ts +5 -3
  178. package/modules/import-kit/src/door/archive.ts +5 -2
  179. package/modules/import-kit/src/door/authority.ts +1 -0
  180. package/modules/import-kit/src/door/grants.ts +1 -1
  181. package/modules/import-kit/src/door/handler.ts +14 -8
  182. package/modules/import-kit/src/door/index.ts +1 -1
  183. package/modules/import-kit/src/door/jobs.ts +40 -0
  184. package/modules/import-kit/src/door/limits.ts +1 -1
  185. package/modules/import-kit/src/door/operator.ts +3 -3
  186. package/modules/import-kit/src/door/planning.ts +10 -6
  187. package/modules/import-kit/src/door/protocol.ts +2 -2
  188. package/modules/import-kit/src/door/raw.ts +25 -0
  189. package/modules/import-kit/src/door/refusals.ts +2 -1
  190. package/modules/import-kit/src/door/types.ts +26 -6
  191. package/modules/import-kit/src/receipt/encoding.ts +37 -0
  192. package/modules/import-kit/src/receipt/index.ts +69 -0
  193. package/modules/import-kit/src/receipt/policy.ts +24 -0
  194. package/modules/import-kit/src/receipt/types.ts +64 -0
  195. package/modules/import-kit/src/receipt/uri.ts +45 -0
  196. package/modules/import-kit/src/receipt/validation.ts +87 -0
  197. package/modules/import-kit/src/status/encoding.ts +13 -0
  198. package/modules/import-kit/src/status/evidence.ts +218 -0
  199. package/modules/import-kit/src/status/index.ts +56 -0
  200. package/modules/import-kit/src/status/schema.ts +208 -0
  201. package/modules/import-kit/src/status/types.ts +86 -0
  202. package/modules/operator-auth/accounts/delegated.mjs +48 -0
  203. package/modules/operator-auth/index.d.mts +7 -0
  204. package/modules/operator-auth/service.mjs +2 -0
  205. package/modules/portability/README.md +138 -9
  206. package/modules/portability/backfills.mjs +9 -8
  207. package/modules/portability/bridge.mjs +32 -5
  208. package/modules/portability/catalogue.mjs +12 -5
  209. package/modules/portability/copies.mjs +8 -1
  210. package/modules/portability/derived.mjs +33 -0
  211. package/modules/portability/files.mjs +4 -3
  212. package/modules/portability/http-errors.mjs +1 -1
  213. package/modules/portability/http.mjs +3 -3
  214. package/modules/portability/import.mjs +29 -13
  215. package/modules/portability/index.d.mts +4 -3
  216. package/modules/portability/index.mjs +1 -1
  217. package/modules/portability/ledgers.mjs +3 -2
  218. package/modules/portability/legacy-safety.mjs +11 -2
  219. package/modules/portability/migration-history.mjs +2 -2
  220. package/modules/portability/progress.mjs +1 -0
  221. package/modules/portability/restore-empty.mjs +12 -0
  222. package/modules/release/github-verify.mjs +11 -2
  223. package/onboarding/adapter.mjs +35 -6
  224. package/onboarding/app-fetch.mjs +6 -4
  225. package/onboarding/development-runtime.mjs +19 -0
  226. package/onboarding/local/operation.mjs +45 -27
  227. package/onboarding/loopback-fetch.mjs +16 -0
  228. package/onboarding/operator-installer.mjs +2 -4
  229. package/onboarding/process-diagnostics.mjs +6 -2
  230. package/onboarding/production-runtime.mjs +4 -2
  231. package/onboarding/readiness.mjs +1 -0
  232. package/package.json +4 -2
  233. package/scripts/publish-check/copy_identities.py +3 -1
  234. package/scripts/publish-check/github_refs.py +32 -13
  235. package/scripts/publish-check/public_hygiene.py +1 -1
  236. package/cli/business/opt-ins.mjs +0 -33
@@ -10,12 +10,14 @@ import os from 'node:os';
10
10
  import path from 'node:path';
11
11
  import crypto from 'node:crypto';
12
12
  import {execFileSync} from 'node:child_process';
13
+ import {fileURLToPath} from 'node:url';
13
14
  import {hash, json, git, raw, gitReader, safe, noLinks, requirePhysical, testSource} from './files.mjs';
14
15
  import {snapshot, acknowledgementDrift} from './base-acknowledgements.mjs';
15
16
  import {requireMaterializedCopies, preflightRefresh} from './copy-checkout.mjs';
16
17
  import {completeModuleCopies} from './module-closure.mjs';
17
18
  import {editionMigrations} from './edition-migrations.mjs';
18
19
  import {adoptWorkflowTemplates, completeWorkflowHelpers} from './workflow-copies.mjs';
20
+ import {archiveReader} from './archive-source.mjs';
19
21
 
20
22
  export const RECORD = 'base-copies.json';
21
23
  const commit = /^[a-f0-9]{40}$/, sha256 = /^[a-f0-9]{64}$/;
@@ -37,16 +39,28 @@ function baseRepository(root) {
37
39
  return (source?.kind === 'git' ? source.repository : source?.origin?.repository) || 'runeditrun/base';
38
40
  }
39
41
 
42
+ function declaredRemote(record, root) {
43
+ const declared = record.repository ?? baseRepository(root);
44
+ return declared === 'runeditrun/base' ? 'https://github.com/runeditrun/base.git' : declared;
45
+ }
46
+
40
47
  // An explicit checkout, else the record's legacy repository, else the seed's declaration.
41
- function open(record, base, root, offline = false) {
48
+ function open(record, base, root, offline = false, baseArchive = null, revision = null) {
49
+ if (baseArchive) {
50
+ if (base) throw Error('Choose either --base or --base-archive');
51
+ return {repository: path.resolve(baseArchive), read: archiveReader(baseArchive, revision), head: revision, offline: true, close() {}};
52
+ }
42
53
  if (base) {
43
54
  const repository = fs.realpathSync(base);
44
55
  const source = gitReader(repository, offline);
45
- try { return {repository, source, head: source.git('rev-parse', 'HEAD'), offline, close: source.close}; }
56
+ try { return {repository, source, head: source.git('rev-parse', 'HEAD'), offline, close: source.close,
57
+ remote: () => {
58
+ try { return git(repository, 'remote', 'get-url', 'origin'); }
59
+ catch { return declaredRemote(record, root); }
60
+ }}; }
46
61
  catch (error) { source.close(); throw error; }
47
62
  }
48
- const declared = record.repository ?? baseRepository(root);
49
- const source = declared === 'runeditrun/base' ? 'https://github.com/runeditrun/base.git' : declared;
63
+ const source = declaredRemote(record, root);
50
64
  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'base-copies-'));
51
65
  try {
52
66
  execFileSync('git', ['clone', '--bare', '--quiet', '--', source, temporary], {env: {...process.env, GIT_NO_REPLACE_OBJECTS: '1'}, stdio: 'pipe'});
@@ -54,29 +68,78 @@ function open(record, base, root, offline = false) {
54
68
  fs.rmSync(temporary, {recursive: true, force: true});
55
69
  throw Error('Cannot acquire Base source. Clone https://github.com/runeditrun/base.git when online, then repeat with --base <checkout>.');
56
70
  }
57
- return {repository: temporary, head: null, close: () => fs.rmSync(temporary, {recursive: true, force: true})};
71
+ return {repository: temporary, head: null, remote: () => source, close: () => fs.rmSync(temporary, {recursive: true, force: true})};
58
72
  }
59
73
 
60
74
  export function options(args, count) {
61
- const result = {positional: [], record: RECORD, base: null, offline: false, editionMigration: []};
75
+ const result = {positional: [], record: RECORD, base: null, baseArchive: null, offline: false, editionMigration: []};
62
76
  for (let i = 0; i < args.length; i++) {
63
77
  const arg = args[i];
64
78
  if (arg === '--offline') result.offline = true;
79
+ else if (arg === '--from-api') result.fromApi = true;
65
80
  else if (arg === '--edition-migration') {
66
81
  if (!args[i + 1] || args[i + 1].startsWith('--')) throw Error(`${arg} requires a value`);
67
82
  result.editionMigration.push(args[++i]);
68
83
  }
69
- else if (arg === '--record' || arg === '--base') {
70
- if (!args[i + 1]) throw Error(`${arg} requires a value`);
71
- result[arg.slice(2)] = args[++i];
84
+ else if (['--record', '--base', '--base-archive', '--ref'].includes(arg)) {
85
+ if (!args[i + 1] || args[i + 1].startsWith('--')) throw Error(`${arg} requires a value`);
86
+ const key = arg === '--base-archive' ? 'baseArchive' : arg.slice(2);
87
+ if (key === 'ref' && result.ref) throw Error('Provide --ref only once');
88
+ result[key] = args[++i];
72
89
  } else if (arg.startsWith('--')) throw Error(`Unknown option: ${arg}`);
73
90
  else result.positional.push(arg);
74
91
  }
75
- if (result.positional.length !== count) throw Error('Usage: verify-base [--record <file>] [--base <checkout>] [--offline] | record-base <path> <origin-path> <revision> [--record <file>] [--base <checkout>] | adapt-base <file> [--record <file>] | refresh-base <revision> [--record <file>] [--base <checkout>]');
92
+ if (result.ref) {
93
+ if (![1, 3].includes(count) || result.positional.length !== count - 1) throw Error('Use --ref instead of the positional Base revision');
94
+ result.positional.push(result.ref);
95
+ }
96
+ if (result.base && result.baseArchive) throw Error('Choose either --base or --base-archive');
97
+ if (result.positional.length !== count) throw Error('Usage: verify-base [--record <file>] [--base <checkout>] [--offline] | record-base <path> <origin-path> <revision>|--ref <revision> [--record <file>] [--base <checkout>|--base-archive <directory>|--from-api|--offline --base <checkout>] | adapt-base <file> [--record <file>] | refresh-base <revision>|--ref <revision> [--record <file>] [--base <checkout>|--base-archive <directory>]');
98
+ if (result.fromApi && count !== 3) throw Error('--from-api is only supported by record-base');
76
99
  safe(result.record);
77
100
  return result;
78
101
  }
79
102
 
103
+ // Read immutable Git objects through GitHub, without cloning Base or trusting
104
+ // an archive's filesystem modes. Refuse incomplete trees and verify blob IDs.
105
+ function apiReader(record, root, revision) {
106
+ const declared = record.repository ?? baseRepository(root);
107
+ const repository = /^(?:https:\/\/github\.com\/)?([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(declared)?.[1];
108
+ if (!repository) throw Error('--from-api requires a GitHub Base repository');
109
+ const request = endpoint => {
110
+ try {
111
+ return JSON.parse(execFileSync('gh', ['api', `repos/${repository}/git/${endpoint}`], {
112
+ encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000, maxBuffer: 64 * 1024 * 1024,
113
+ }));
114
+ } catch { throw Error(`Cannot read immutable Base ${revision} from the GitHub API; no copy record was changed.`); }
115
+ };
116
+ const pinned = request(`commits/${revision}`);
117
+ if (pinned.sha !== revision || !commit.test(pinned.tree?.sha)) throw Error('Base API did not resolve the immutable commit; no copy record was changed.');
118
+ const tree = request(`trees/${pinned.tree.sha}?recursive=1`);
119
+ if (tree.sha !== pinned.tree.sha || tree.truncated !== false || !Array.isArray(tree.tree)) throw Error('Incomplete Base API tree; no copy record was changed.');
120
+ const entries = new Map();
121
+ for (const entry of tree.tree) {
122
+ safe(entry.path);
123
+ if (entry.type === 'blob' && FILE_MODES.includes(entry.mode)) {
124
+ if (!commit.test(entry.sha)) throw Error('Invalid Base API blob identity');
125
+ entries.set(entry.path, {object: entry.sha, mode: entry.mode});
126
+ }
127
+ }
128
+ return {
129
+ tree: () => entries,
130
+ digests(objects) {
131
+ return new Map([...new Set(objects)].map(object => {
132
+ const blob = request(`blobs/${object}`);
133
+ if (blob.sha !== object || blob.encoding !== 'base64' || typeof blob.content !== 'string') throw Error('Invalid Base API blob');
134
+ const bytes = Buffer.from(blob.content, 'base64');
135
+ const actual = crypto.createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
136
+ if (blob.size !== bytes.length || actual !== object) throw Error('Base API blob integrity mismatch; no copy record was changed.');
137
+ return [object, hash(bytes)];
138
+ }));
139
+ },
140
+ };
141
+ }
142
+
80
143
  export function validate(record) {
81
144
  const legacy = record?.repository;
82
145
  if (record?.schemaVersion !== 1 || (legacy !== undefined && (typeof legacy !== 'string' || !legacy || legacy.startsWith('-'))) || !Array.isArray(record.copies)) {
@@ -92,6 +155,14 @@ export function validate(record) {
92
155
  safe(name);
93
156
  if (!within(name, copy.path) || !sha256.test(digest)) throw Error(`Invalid recorded copy file: ${name}`);
94
157
  }
158
+ if (copy.originFiles !== undefined) {
159
+ if (!Array.isArray(copy.originFiles) || new Set(copy.originFiles).size !== copy.originFiles.length) throw Error(`Invalid Base source membership: ${copy.path}`);
160
+ for (const name of copy.originFiles) {
161
+ safe(name);
162
+ if (!within(name, copy.originPath)) throw Error(`Invalid Base source membership: ${name}`);
163
+ }
164
+ for (const name of Object.keys(copy.files)) if (!copy.adapted?.[name] && !copy.originFiles.includes(mapped(name, copy.path, copy.originPath))) throw Error(`Missing Base source membership: ${name}`);
165
+ }
95
166
  if (copy.adapted !== undefined) {
96
167
  if (!copy.adapted || typeof copy.adapted !== 'object' || Array.isArray(copy.adapted)) throw Error(`Invalid adaptations: ${copy.path}`);
97
168
  for (const [name, revision] of Object.entries(copy.adapted)) {
@@ -139,10 +210,48 @@ function seedFiles(root) {
139
210
  return files;
140
211
  }
141
212
 
213
+ const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
214
+
215
+ // A fresh object store avoids inheriting shallow boundaries from the supplied
216
+ // checkout. Fetch only the two immutable tips, with no tags or other branches.
217
+ function containsHistory(origin, source, revision, introduced) {
218
+ try {
219
+ const ancestor = source.git('merge-base', revision, introduced);
220
+ if (ancestor === introduced) return true;
221
+ if (git(origin.repository, 'rev-parse', '--is-shallow-repository') === 'false') return false;
222
+ } catch { /* Missing ancestry must be acquired before deciding applicability. */ }
223
+ const remote = origin.remote();
224
+ const format = source.git('rev-parse', '--show-object-format');
225
+ const fetch = ['fetch', '--no-tags', '--no-recurse-submodules', '--', remote, revision, introduced];
226
+ const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'base-history-'));
227
+ try {
228
+ if (origin.offline) throw Error('offline');
229
+ execFileSync('git', ['init', '--bare', '--quiet', '--template=', '--object-format=' + format, temporary], {stdio: 'pipe'});
230
+ execFileSync('git', ['-C', temporary, ...fetch], {
231
+ env: {...process.env, GIT_NO_REPLACE_OBJECTS: '1', GIT_TERMINAL_PROMPT: '0'}, stdio: 'pipe', timeout: 60_000,
232
+ });
233
+ return git(temporary, 'merge-base', revision, introduced) === introduced;
234
+ } catch {
235
+ const {revision: target, recordPath, editionMigration} = origin.refresh;
236
+ const refs = [...new Set([revision, introduced, target])];
237
+ const cli = fileURLToPath(new URL('../bin/rer.mjs', import.meta.url));
238
+ const repair = 'history=$(mktemp -d) && git init --bare --quiet --template= --object-format=' + format +
239
+ ' "$history" && git -C "$history" fetch --no-tags --no-recurse-submodules -- ' +
240
+ [remote, ...refs].map(quote).join(' ') + ' && ' +
241
+ [process.execPath, cli, 'refresh-base', '--ref', target, '--base'].map(quote).join(' ') +
242
+ ' "$history" --record ' + quote(recordPath) +
243
+ editionMigration.map(id => ' --edition-migration ' + quote(id)).join('');
244
+ throw Error(`Cannot compare Base history for ${revision} and ${introduced} from remote ${remote}${origin.offline ? ' while offline' : '; fetching the required revisions failed or their ancestry is unavailable'}. No files were refreshed. When online, run exactly:\n${repair}`);
245
+ } finally {
246
+ fs.rmSync(temporary, {recursive: true, force: true});
247
+ }
248
+ }
249
+
142
250
  function reader(origin) {
251
+ if (origin.read) return origin.read;
143
252
  const source = origin.source ?? gitReader(origin.repository);
144
253
  const format = source.git('rev-parse', '--show-object-format');
145
- const trees = new Map();
254
+ const trees = new Map(), ancestry = new Map();
146
255
  return {
147
256
  // Git object identity of local bytes, to find copies by content without reading Base blobs.
148
257
  objectId: bytes => crypto.createHash(format).update(`blob ${bytes.length}\0`).update(bytes).digest('hex'),
@@ -185,8 +294,9 @@ function reader(origin) {
185
294
  },
186
295
  contains(revision, introduced) {
187
296
  this.tree(revision); this.tree(introduced);
188
- try { return source.git('merge-base', revision, introduced) === introduced; }
189
- catch { throw Error(`Cannot compare Base history for ${revision} and ${introduced}; fetch full Base history, then repeat refresh-base; no files were refreshed.`); }
297
+ const key = revision + ':' + introduced;
298
+ if (!ancestry.has(key)) ancestry.set(key, containsHistory(origin, source, revision, introduced));
299
+ return ancestry.get(key);
190
300
  },
191
301
  history(revision, name) {
192
302
  return source.git('log', '--format=%H', revision, '--', name).split('\n').filter(Boolean)
@@ -206,7 +316,8 @@ function recordFile(root, recordPath) {
206
316
  return filename;
207
317
  }
208
318
 
209
- export function verifyCopies(root, {record: recordPath, base, offline}) {
319
+ export function verifyCopies(root, {record: recordPath, base, baseArchive, offline}) {
320
+ if (baseArchive) throw Error('--base-archive is supported by record-base and refresh-base; use verify-base --offline to check recorded local bytes');
210
321
  const filename = recordFile(root, recordPath);
211
322
  if (!filename) throw Error(`No ${recordPath} found; run record-base <path> <origin-path> <commit> first`);
212
323
  const record = validate(JSON.parse(fs.readFileSync(filename, 'utf8')));
@@ -279,16 +390,18 @@ export function verifyCopies(root, {record: recordPath, base, offline}) {
279
390
  };
280
391
  }
281
392
 
282
- export function recordCopy(root, {positional: [localPath, originPath, revision], record: recordPath, base}) {
393
+ export function recordCopy(root, {positional: [localPath, originPath, revision], record: recordPath, base, baseArchive, offline, fromApi}) {
283
394
  safe(localPath); safe(originPath);
284
395
  if (!commit.test(revision)) throw Error('Record an immutable full Base commit');
285
396
  const filename = recordFile(root, recordPath) || path.join(root, recordPath);
286
397
  const record = validate(fs.existsSync(filename) ? JSON.parse(fs.readFileSync(filename, 'utf8')) : {schemaVersion: 1, copies: []});
287
398
  const files = seedFiles(root);
288
- const origin = open(record, base, root);
289
- delete record.repository;
399
+ if (fromApi && (base || baseArchive || offline)) throw Error('--from-api cannot be combined with --base, --base-archive or --offline');
400
+ if (offline && !base && !baseArchive) throw Error('record-base --offline requires --base <checkout> or --base-archive <directory>; use --from-api while online');
401
+ const origin = fromApi ? {close() {}} : open(record, base, root, offline, baseArchive, revision);
290
402
  try {
291
- const read = reader(origin);
403
+ const read = fromApi ? apiReader(record, root, revision) : reader(origin);
404
+ delete record.repository;
292
405
  const sources = [...read.tree(revision)].filter(([name]) => within(name, originPath));
293
406
  if (!sources.length) throw Error(`No Base source at ${originPath} in ${revision}`);
294
407
  const present = sources.filter(([name]) => files.get(mapped(name, originPath, localPath))?.regular);
@@ -298,7 +411,8 @@ export function recordCopy(root, {positional: [localPath, originPath, revision],
298
411
  const ordered = present.map(([name, {object, mode}]) => [mapped(name, originPath, localPath), digests.get(object), mode]).sort(([a], [b]) => a.localeCompare(b));
299
412
  const recorded = Object.fromEntries(ordered.map(([name, digest]) => [name, digest]));
300
413
  const modes = Object.fromEntries(ordered.map(([name, , mode]) => [name, mode]));
301
- record.copies = [...record.copies.filter(copy => copy.path !== localPath), {path: localPath, originPath, revision, files: recorded, modes}].sort((a, b) => a.path.localeCompare(b.path));
414
+ const originFiles = sources.map(([name]) => name).sort();
415
+ record.copies = [...record.copies.filter(copy => copy.path !== localPath), {path: localPath, originPath, revision, files: recorded, modes, originFiles}].sort((a, b) => a.path.localeCompare(b.path));
302
416
  validate(record);
303
417
  fs.writeFileSync(filename, json(record));
304
418
  return {
@@ -313,7 +427,8 @@ export function recordCopy(root, {positional: [localPath, originPath, revision],
313
427
 
314
428
  // Explicitly transfer one recorded file to seed ownership without changing its bytes
315
429
  // or its Base digest/mode. The per-file revision survives later whole-copy refreshes.
316
- export function adaptCopy(root, {positional: [name], record: recordPath}) {
430
+ export function adaptCopy(root, {positional: [name], record: recordPath, baseArchive, ref}) {
431
+ if (baseArchive || ref) throw Error('--base-archive and --ref are supported by record-base and refresh-base');
317
432
  safe(name);
318
433
  const filename = recordFile(root, recordPath);
319
434
  if (!filename) throw Error(`No ${recordPath} found; run record-base first`);
@@ -340,15 +455,16 @@ export function adaptCopy(root, {positional: [name], record: recordPath}) {
340
455
  // entirely, just as absent files are dropped from directory copies. Local edits
341
456
  // are refused, never overwritten, as is any change to an existing file under a
342
457
  // migrations folder.
343
- export function refreshCopies(root, {positional: [revision], record: recordPath, base, offline, editionMigration = []}) {
458
+ export function refreshCopies(root, {positional: [revision], record: recordPath, base, baseArchive, offline, editionMigration = []}) {
344
459
  if (!commit.test(revision)) throw Error('Refresh requires an immutable full 40-character Base commit. Resolve the release tag with git -C <base-checkout> rev-parse <tag>^{commit}, then repeat with --ref <commit> --base <base-checkout>.');
345
- if (offline && !base) throw Error('Offline refresh needs a Base checkout. Repeat rer refresh-base --ref <commit> --offline --base <checkout> containing that commit.');
460
+ if (offline && !base && !baseArchive) throw Error('Offline refresh needs a Base checkout or archive. Repeat rer refresh-base --ref <commit> --offline --base <checkout> containing that commit, or use --base-archive <directory>.');
346
461
  const filename = recordFile(root, recordPath);
347
462
  if (!filename) throw Error(`No ${recordPath} found; run record-base <path> <origin-path> <commit> first`);
348
463
  const record = validate(JSON.parse(fs.readFileSync(filename, 'utf8')));
349
464
  const files = seedFiles(root);
350
465
  requireMaterializedCopies(root, record, files);
351
- const origin = open(record, base, root, offline);
466
+ const origin = open(record, base, root, offline, baseArchive, revision);
467
+ origin.refresh = {revision, recordPath, editionMigration};
352
468
  let writing = false, notices = [];
353
469
  try {
354
470
  const read = reader(origin);
@@ -389,8 +505,14 @@ export function refreshCopies(root, {positional: [revision], record: recordPath,
389
505
  // removals, and a still-present singleton must retain a Base source.
390
506
  const retired = Object.keys(copy.files).length === 1 && Object.hasOwn(copy.files, copy.path) &&
391
507
  !files.has(copy.path) && !fs.existsSync(path.join(root, copy.path)) && !Object.hasOwn(copy.adapted || {}, copy.path);
392
- const pinned = read.tree(copy.revision);
393
508
  if (retired) return {copy, sources: [], retired, removed: [copy.path]};
509
+ // An archive has only the target tree. Complete prior source membership
510
+ // retains the distinction between omitted old files and new additions.
511
+ let pinned;
512
+ if (baseArchive && copy.revision !== revision) {
513
+ if (!copy.originFiles) throw Error(`Base copy ${copy.path} lacks prior source membership (originFiles). Repeat this refresh with --base <checkout> containing the recorded and target commits; future archive refreshes can then preserve omitted files. No files were refreshed.`);
514
+ pinned = new Set(copy.originFiles);
515
+ } else pinned = read.tree(copy.revision);
394
516
  const tests = Object.keys(copy.files).some(name => testSource(mapped(name, copy.path, copy.originPath)));
395
517
  const sources = [...next].filter(([name]) => {
396
518
  if (!within(name, copy.originPath)) return false;
@@ -447,7 +569,7 @@ export function refreshCopies(root, {positional: [revision], record: recordPath,
447
569
  recorded[name] = upstream.get(object); modes[name] = mode;
448
570
  }
449
571
  changes.push({path: copy.path, from: copy.revision, files: sources.length, added, removed});
450
- Object.assign(copy, {revision, files: recorded, modes});
572
+ Object.assign(copy, {revision, files: recorded, modes, originFiles: [...next.keys()].filter(name => within(name, copy.originPath)).sort()});
451
573
  }
452
574
  record.copies = plans.filter(plan => !plan.retired).map(plan => plan.copy);
453
575
  delete record.repository;
@@ -77,7 +77,7 @@ try {
77
77
  } else if (command === 'record-base') result = recordCopy(root, options(args.slice(1), 3));
78
78
  else if (command === 'adapt-base') result = adaptCopy(root, options(args.slice(1), 1));
79
79
  else if (command === 'refresh-base') result = refreshCopies(root, options(args.slice(1), 1));
80
- else throw Error('Usage: cli.mjs adopt|inspect|lock|check|receipt <sidecar-json>|changes|extract <id|parent> <new-output>|compare <id|parent> <candidate-checkout> [current-parent-checkout]|materialize <new-output>|promote <id>|release <new-local-git-repository>|verify-base [--record <file>] [--base <checkout>] [--offline]|record-base <path> <origin-path> <revision> [--record <file>] [--base <checkout>]|adapt-base <file> [--record <file>]|refresh-base <revision> [--record <file>] [--base <checkout>]');
80
+ else throw Error('Usage: cli.mjs adopt|inspect|lock|check|receipt <sidecar-json>|changes|extract <id|parent> <new-output>|compare <id|parent> <candidate-checkout> [current-parent-checkout]|materialize <new-output>|promote <id>|release <new-local-git-repository>|verify-base [--record <file>] [--base <checkout>] [--offline]|record-base <path> <origin-path> <revision>|--ref <revision> [--record <file>] [--base <checkout>|--base-archive <directory>|--from-api|--offline --base <checkout>]|adapt-base <file> [--record <file>]|refresh-base <revision>|--ref <revision> [--record <file>] [--base <checkout>|--base-archive <directory>]');
81
81
  console.log(json(result));
82
82
  } catch (error) {
83
83
  console.error(error.message);
@@ -16,7 +16,7 @@ export function editionMigrations(record, {tree, read, revision, base, recordPat
16
16
  typeof step.guide !== 'string' || !step.guide || typeof step.edit !== 'string' || !step.edit ||
17
17
  !Array.isArray(step.deliver) || step.deliver.some(name => typeof name !== 'string')) fail('invalid entry');
18
18
  safe(step.origin); safe(step.guide); step.deliver.forEach(safe);
19
- read.tree(step.introduced);
19
+ if (read.historyAvailable !== false) read.tree(step.introduced);
20
20
  for (const name of step.deliver) if (!tree.has(name)) fail(`missing delivery ${name}`);
21
21
  ids.add(step.id);
22
22
  }
@@ -25,9 +25,13 @@ export function editionMigrations(record, {tree, read, revision, base, recordPat
25
25
  }
26
26
  for (const id of consent) if (!migrations.some(step => step.id === id)) throw Error(`Unknown edition migration ${id} at Base ${revision}. Use only ids declared in ${dataPath} at that commit; no files were refreshed.`);
27
27
  const applicable = migrations.flatMap(step => {
28
+ // No introduction can be crossed by an unrelated copy or a same-pin
29
+ // refresh. Archives can decide those cases without claiming Git ancestry.
30
+ const candidates = record.copies.flatMap(copy => copy.revision === revision ? [] : Object.keys(copy.files).filter(name =>
31
+ !copy.adapted?.[name] && copy.originPath + name.slice(copy.path.length) === step.origin).map(name => ({name, revision: copy.revision})));
32
+ if (!candidates.length) return [];
28
33
  if (!read.contains(revision, step.introduced)) return [];
29
- const copies = record.copies.flatMap(copy => Object.keys(copy.files).filter(name =>
30
- !copy.adapted?.[name] && copy.originPath + name.slice(copy.path.length) === step.origin && !read.contains(copy.revision, step.introduced)));
34
+ const copies = candidates.filter(copy => !read.contains(copy.revision, step.introduced)).map(copy => copy.name);
31
35
  return copies.length ? [{...step, copies}] : [];
32
36
  });
33
37
  const missing = applicable.filter(step => !consent.includes(step.id));
@@ -120,7 +120,8 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, d
120
120
  const key = (target, request) => JSON.stringify([target, request.kind, request.types, request.specifier]);
121
121
  const bootstrap = source => /^(?:edition-authoring|(?:default-seed|export)\/scripts\/base-cli\/edition-authoring)\//.test(source);
122
122
  // Snapshot the original unresolved set once, before closure can add a file.
123
- // Only toolkit bootstraps and recorded removals may change that baseline.
123
+ // Preserve these edges during traversal; required planned files may still
124
+ // complete a sparse historical copy by satisfying them.
124
125
  const baseline = new Set();
125
126
  for (const {plan, source, target} of queue) {
126
127
  if (!Object.hasOwn(plan.copy.files, target) || !disk.has(target) || bootstrap(source)) continue;
@@ -213,20 +214,5 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, d
213
214
  }
214
215
  }
215
216
  }
216
- const expected = new Set(), unresolved = new Set();
217
- const removed = new Set(plans.flatMap(plan => plan.removed));
218
- const final = {has: name => planned.has(name) || !removed.has(name) && disk.has(name), read: view.read};
219
- for (const {plan, source, target, entry, adapted} of queue) {
220
- if (!adapted && !plan.sources.some(([name]) => name === source)) continue;
221
- for (const request of requests(adapted ? local(target) : blob(entry), source, target)) {
222
- const id = key(target, request);
223
- if (!baseline.has(id)) continue;
224
- expected.add(id);
225
- if (!resolve(final, target, request.specifier, request)) unresolved.add(id);
226
- }
227
- }
228
- if (expected.size !== unresolved.size || [...expected].some(id => !unresolved.has(id))) {
229
- refuse('baseline imports', 'a planned file would resolve an edition-owned unresolved edge', '${EDITOR:-vi} base-copies.json');
230
- }
231
217
  return withheld;
232
218
  }
@@ -54,7 +54,7 @@ export function adoptWorkflowTemplates(root, plans, {tree, read, revision, files
54
54
  if (match) {
55
55
  include(plans, target, source, tree.get(source), revision);
56
56
  templateAdoptions.push({path: target, originPath: source, from: match.revision});
57
- } else if (target.endsWith('.yml')) {
57
+ } else if (target.endsWith('.yml') && !file.read().equals(read.blobs([tree.get(source).object]).get(tree.get(source).object))) {
58
58
  notices.push(`${target}: preserved seed-owned workflow. The current template pins Ubuntu 24.04 and moves browser and apt caches to the runner temporary directory. To adopt, merge export/${path.posix.basename(source)} from Base ${revision} into ${target}, then run node node_modules/@runeditrun/rer/edition-authoring/cli.mjs record-base ${target} ${source} ${revision} --base <base-checkout> and repeat rer refresh-base --ref ${revision} --base <base-checkout>.`);
59
59
  }
60
60
  }
@@ -95,16 +95,25 @@ export function shellWords(script) {
95
95
 
96
96
  export function literalPaths(script) {
97
97
  const names = new Set();
98
- function scan(text, ancestors = new Set()) {
98
+ function scan(text, ancestors = new Set(), words = shellWords(text)) {
99
99
  if (ancestors.has(text)) return;
100
100
  const nested = new Set([...ancestors, text]);
101
- for (const {value, dynamic} of shellWords(text)) {
101
+ for (const {value, dynamic} of words) {
102
102
  if (dynamic) continue;
103
103
  const relative = value.replace(/^\.\//, '');
104
104
  if ((value.startsWith('./') || relative.startsWith('scripts/') || !/\s/.test(value) && (relative.includes('/') || /\.[a-z0-9]+$/i.test(relative))) && !relative.startsWith('/')) names.add(relative);
105
105
  // A complete quoted path is one word; only script-like quoted content is
106
106
  // recursively tokenized, never a path whose filename contains whitespace.
107
- else if (/\s/.test(value)) scan(value, nested);
107
+ else if (/\s/.test(value)) {
108
+ // Decoded arguments may be prose, not another shell program. A quote
109
+ // that was literal in its enclosing word must not invalidate that
110
+ // workflow. Recurse only when the whole argument is valid shell text;
111
+ // the actual run script and its substitutions are still strict.
112
+ let words;
113
+ try { words = shellWords(value); }
114
+ catch { continue; }
115
+ scan(value, nested, words);
116
+ }
108
117
  }
109
118
  }
110
119
  scan(script);