@runeditrun/rer 0.2.94 → 0.2.95

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 (54) hide show
  1. package/README.md +3 -0
  2. package/cli/README.md +3 -0
  3. package/cli/agent-journey-fixtures.mjs +1 -1
  4. package/cli/authoring.mjs +1 -1
  5. package/cli/business/carry-files.mjs +115 -0
  6. package/cli/business/carry.mjs +20 -81
  7. package/cli/business/choices.mjs +12 -7
  8. package/cli/contract.mjs +1 -1
  9. package/cli/door-clauses.mjs +28 -2
  10. package/cli/hosted-output.mjs +4 -2
  11. package/cli/hosted-queue-producers.mjs +43 -0
  12. package/cli/jsonc.mjs +1 -115
  13. package/cli/parse.mjs +1 -1
  14. package/cli/portability-migrations.mjs +2 -12
  15. package/edition-authoring/archive-source.mjs +86 -1
  16. package/edition-authoring/base-copies.mjs +15 -45
  17. package/edition-authoring/cli.mjs +1 -1
  18. package/edition-authoring/edition-migrations.mjs +2 -2
  19. package/edition-authoring/module-closure.mjs +119 -50
  20. package/edition-authoring/module-packages.mjs +12 -5
  21. package/edition-authoring/module-syntax.mjs +13 -50
  22. package/edition-authoring/runtime-dependencies.mjs +4 -4
  23. package/global/CHANGELOG.md +38 -0
  24. package/global/README.md +3 -0
  25. package/modules/agent-door/CLAUSES.md +12 -0
  26. package/modules/agent-door/conformance/audit.mjs +22 -4
  27. package/modules/agent-door/conformance/discovery.mjs +32 -1
  28. package/modules/agent-door/conformance/erasure.mjs +103 -0
  29. package/modules/agent-door/conformance/journey.mjs +19 -1
  30. package/modules/agent-door/conformance/policy-phases.mjs +6 -0
  31. package/modules/agent-door/conformance/protocol.mjs +13 -3
  32. package/modules/deploy-kit/jsonc.mjs +115 -0
  33. package/modules/deploy-kit/migration-directory.mjs +16 -0
  34. package/modules/deploy-kit/prepare.mjs +1 -1
  35. package/modules/deploy-kit/templates.mjs +9 -4
  36. package/modules/erasure/cascade.mjs +4 -4
  37. package/modules/erasure/index.d.mts +1 -1
  38. package/modules/erasure/index.mjs +1 -1
  39. package/modules/import-kit/src/d1/README.md +16 -1
  40. package/modules/import-kit/src/d1/preserved-reverse.ts +5 -2
  41. package/modules/import-kit/src/d1/read-fence.ts +14 -2
  42. package/modules/import-kit/src/d1/reverse.ts +4 -1
  43. package/modules/import-kit/src/d1/sets.ts +8 -0
  44. package/modules/import-kit/src/d1/snapshot-text.ts +68 -0
  45. package/modules/import-kit/src/d1/undo-report.ts +4 -1
  46. package/modules/import-kit/src/door/ADOPTING.md +9 -4
  47. package/modules/portability/README.md +28 -2
  48. package/modules/portability/bookkeeping.mjs +8 -4
  49. package/modules/portability/checkout-history.mjs +12 -6
  50. package/modules/portability/import.mjs +1 -1
  51. package/modules/portability/storage.mjs +7 -1
  52. package/modules/portability/worker-history.d.mts +1 -1
  53. package/modules/portability/worker-history.mjs +1 -1
  54. package/package.json +1 -1
@@ -4,7 +4,8 @@ import { readFile, readdir } from 'node:fs/promises';
4
4
  import { migrationStatements } from '../modules/portability/migration-sql.mjs';
5
5
  import { destinationLedger, ledgerNames, matchMigrationLedger } from '../modules/portability/ledgers.mjs';
6
6
  import { all, insist, PortabilityError } from '../modules/portability/storage.mjs';
7
- import { parseJsonc } from './jsonc.mjs';
7
+ import {migrationDirectory} from '../modules/deploy-kit/migration-directory.mjs';
8
+ export {migrationDirectory};
8
9
 
9
10
  // Seed-owned declarations, never archive metadata: the deploymentSpec prefix
10
11
  // for this binding's directory, and data-only seeds without schema files.
@@ -16,17 +17,6 @@ export function platformMigrationDeclaration(input={}) {
16
17
  return {prefix,dataOnly};
17
18
  }
18
19
 
19
- // Native archive/migration checks and deploy packaging use the same seed-owned
20
- // directory declaration. Only packaging supplies its historical fallback.
21
- export async function migrationDirectory(root,binding,{fallback}={}) {
22
- let config;
23
- try { config=parseJsonc(await readFile(join(root,'wrangler.jsonc'),'utf8')); }
24
- catch(error) { if(error.code!=='ENOENT' || fallback===undefined)throw error; return join(root,fallback); }
25
- const bindings=config.d1_databases?.filter(entry=>entry.binding===binding) ?? [];
26
- insist(bindings.length===1 || bindings.length===0 && fallback!==undefined,'migration_ledger:binding',409);
27
- return join(root,bindings[0]?.migrations_dir ?? fallback ?? 'migrations');
28
- }
29
-
30
20
  // Reproduce the runner's stored SQL text, then recover SQLite's statement
31
21
  // boundaries (migration-sql.mjs).
32
22
  export async function migrationInventory(root,binding,{prefix},split) {
@@ -1,11 +1,96 @@
1
- // A source archive supplies one caller-identified revision, never Git history.
1
+ // Directory archives supply one snapshot. GitHub can also prove ancestry and
2
+ // supply older immutable trees without requiring a local Git object store.
2
3
  import fs from 'node:fs';
3
4
  import path from 'node:path';
4
5
  import crypto from 'node:crypto';
6
+ import {execFileSync} from 'node:child_process';
5
7
  import {hash, safe} from './files.mjs';
6
8
 
7
9
  const limit = 64 * 1024 * 1024;
8
10
  const objectId = bytes => crypto.createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
11
+ const commit = /^[a-f0-9]{40}$/;
12
+
13
+ export function apiReader(repository, revision) {
14
+ if (!commit.test(revision)) throw Error('Base API requires an immutable full 40-character commit');
15
+ const request = endpoint => {
16
+ try {
17
+ return JSON.parse(execFileSync('gh', ['api', `repos/${repository}/${endpoint}`], {
18
+ encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000, maxBuffer: limit,
19
+ }));
20
+ } catch (error) {
21
+ // Keep provider failures explicit without echoing arbitrary gh stderr,
22
+ // authentication diagnostics or credential-bearing transport URLs.
23
+ const status = /\bHTTP (\d{3})\b/.exec(error.stderr?.toString() ?? '')?.[1];
24
+ throw Error(`Cannot read Base ${revision} from the GitHub API${status ? ` (HTTP ${status})` : ''} (${endpoint}); no files were refreshed or copy record changed.`);
25
+ }
26
+ };
27
+ const trees = new Map(), objects = new Map(), ancestry = new Map();
28
+ return {
29
+ // Workflow-template discovery remains snapshot-only; no path history is
30
+ // invented from the API tree or the archive's version.
31
+ historyAvailable: false,
32
+ objectId,
33
+ tree(pin) {
34
+ if (!commit.test(pin)) throw Error('Base API requires an immutable full 40-character commit');
35
+ if (!trees.has(pin)) {
36
+ const pinned = request(`git/commits/${pin}`);
37
+ if (pinned.sha !== pin || !commit.test(pinned.tree?.sha)) throw Error('Base API did not resolve the immutable commit');
38
+ const entries = new Map();
39
+ const walk = (identity, prefix = '', recursive = true) => {
40
+ const tree = request(`git/trees/${identity}${recursive ? '?recursive=1' : ''}`);
41
+ if (recursive && tree.sha === identity && tree.truncated === true) return walk(identity, prefix, false);
42
+ if (tree.sha !== identity || tree.truncated !== false || !Array.isArray(tree.tree)) throw Error('Incomplete Base API tree');
43
+ for (const entry of tree.tree) {
44
+ safe(entry.path);
45
+ if ((!recursive && entry.path.includes('/')) || !commit.test(entry.sha)) throw Error('Invalid Base API tree entry');
46
+ const name = prefix + entry.path;
47
+ if (!recursive && entry.type === 'tree' && entry.mode === '040000') walk(entry.sha, name + '/');
48
+ else if (entry.type === 'blob' && ['100644', '100755'].includes(entry.mode)) entries.set(name, {object: entry.sha, mode: entry.mode});
49
+ }
50
+ };
51
+ walk(pinned.tree.sha);
52
+ trees.set(pin, new Map([...entries].sort(([a], [b]) => Buffer.compare(Buffer.from(a), Buffer.from(b)))));
53
+ }
54
+ return trees.get(pin);
55
+ },
56
+ blobs(ids) {
57
+ const result = new Map();
58
+ let size = 0;
59
+ for (const object of new Set(ids)) {
60
+ if (!commit.test(object)) throw Error('Invalid Base API blob identity');
61
+ if (!objects.has(object)) {
62
+ const blob = request(`git/blobs/${object}`);
63
+ if (blob.sha !== object || blob.encoding !== 'base64' || typeof blob.content !== 'string') throw Error('Invalid Base API blob');
64
+ const bytes = Buffer.from(blob.content, 'base64');
65
+ if (blob.size !== bytes.length || objectId(bytes) !== object) throw Error('Base API blob integrity mismatch');
66
+ objects.set(object, bytes);
67
+ }
68
+ const bytes = objects.get(object);
69
+ size += bytes.length;
70
+ if (size > limit) throw Error('Base API source output exceeds the 64 MiB acquisition limit');
71
+ result.set(object, bytes);
72
+ }
73
+ return result;
74
+ },
75
+ digests(ids) { return new Map([...this.blobs(ids)].map(([object, bytes]) => [object, hash(bytes)])); },
76
+ contains(pin, introduced) {
77
+ if (!commit.test(pin) || !commit.test(introduced)) throw Error('Base API ancestry requires immutable full commits');
78
+ const key = introduced + '...' + pin;
79
+ if (!ancestry.has(key)) {
80
+ const comparison = request(`compare/${key}?per_page=1`);
81
+ if (comparison.base_commit?.sha !== introduced || !commit.test(comparison.merge_base_commit?.sha) ||
82
+ !['ahead', 'identical', 'behind', 'diverged'].includes(comparison.status)) throw Error('Invalid Base API ancestry comparison');
83
+ if (['ahead', 'identical'].includes(comparison.status) && comparison.merge_base_commit.sha !== introduced) throw Error('Invalid Base API ancestry proof');
84
+ ancestry.set(key, ['ahead', 'identical'].includes(comparison.status));
85
+ }
86
+ return ancestry.get(key);
87
+ },
88
+ history(pin, name) {
89
+ const entry = this.tree(pin).get(safe(name));
90
+ return entry ? [{revision: pin, ...entry}] : [];
91
+ },
92
+ };
93
+ }
9
94
 
10
95
  export function archiveReader(directory, revision) {
11
96
  if (!/^[a-f0-9]{40}$/.test(revision)) throw Error('A Base archive requires its immutable full 40-character Base commit in --ref');
@@ -17,7 +17,7 @@ import {requireMaterializedCopies, preflightRefresh} from './copy-checkout.mjs';
17
17
  import {completeModuleCopies} from './module-closure.mjs';
18
18
  import {editionMigrations} from './edition-migrations.mjs';
19
19
  import {adoptWorkflowTemplates, completeWorkflowHelpers} from './workflow-copies.mjs';
20
- import {archiveReader} from './archive-source.mjs';
20
+ import {archiveReader, apiReader} from './archive-source.mjs';
21
21
 
22
22
  export const RECORD = 'base-copies.json';
23
23
  const commit = /^[a-f0-9]{40}$/, sha256 = /^[a-f0-9]{64}$/;
@@ -94,50 +94,19 @@ export function options(args, count) {
94
94
  result.positional.push(result.ref);
95
95
  }
96
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');
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>|--from-api]');
98
+ if (result.fromApi && ![1, 3].includes(count)) throw Error('--from-api is supported by record-base and refresh-base');
99
+ if (result.fromApi && (result.base || result.baseArchive || result.offline)) throw Error('--from-api cannot be combined with --base, --base-archive or --offline');
99
100
  safe(result.record);
100
101
  return result;
101
102
  }
102
103
 
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) {
104
+ // Share the authenticated immutable API reader for recording and refreshing.
105
+ function apiSource(record, root, revision) {
106
106
  const declared = record.repository ?? baseRepository(root);
107
107
  const repository = /^(?:https:\/\/github\.com\/)?([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(declared)?.[1];
108
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
- };
109
+ return {read: apiReader(repository, revision), head: revision, close() {}};
141
110
  }
142
111
 
143
112
  export function validate(record) {
@@ -398,9 +367,9 @@ export function recordCopy(root, {positional: [localPath, originPath, revision],
398
367
  const files = seedFiles(root);
399
368
  if (fromApi && (base || baseArchive || offline)) throw Error('--from-api cannot be combined with --base, --base-archive or --offline');
400
369
  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);
370
+ const origin = fromApi ? apiSource(record, root, revision) : open(record, base, root, offline, baseArchive, revision);
402
371
  try {
403
- const read = fromApi ? apiReader(record, root, revision) : reader(origin);
372
+ const read = reader(origin);
404
373
  delete record.repository;
405
374
  const sources = [...read.tree(revision)].filter(([name]) => within(name, originPath));
406
375
  if (!sources.length) throw Error(`No Base source at ${originPath} in ${revision}`);
@@ -427,8 +396,8 @@ export function recordCopy(root, {positional: [localPath, originPath, revision],
427
396
 
428
397
  // Explicitly transfer one recorded file to seed ownership without changing its bytes
429
398
  // or its Base digest/mode. The per-file revision survives later whole-copy refreshes.
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');
399
+ export function adaptCopy(root, {positional: [name], record: recordPath, baseArchive, ref, fromApi}) {
400
+ if (baseArchive || ref || fromApi) throw Error('--base-archive, --ref and --from-api are supported by record-base and refresh-base');
432
401
  safe(name);
433
402
  const filename = recordFile(root, recordPath);
434
403
  if (!filename) throw Error(`No ${recordPath} found; run record-base first`);
@@ -455,21 +424,22 @@ export function adaptCopy(root, {positional: [name], record: recordPath, baseArc
455
424
  // entirely, just as absent files are dropped from directory copies. Local edits
456
425
  // are refused, never overwritten, as is any change to an existing file under a
457
426
  // migrations folder.
458
- export function refreshCopies(root, {positional: [revision], record: recordPath, base, baseArchive, offline, editionMigration = []}) {
427
+ export function refreshCopies(root, {positional: [revision], record: recordPath, base, baseArchive, offline, fromApi, editionMigration = []}) {
459
428
  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>.');
429
+ if (fromApi && (base || baseArchive || offline)) throw Error('--from-api cannot be combined with --base, --base-archive or --offline');
460
430
  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>.');
461
431
  const filename = recordFile(root, recordPath);
462
432
  if (!filename) throw Error(`No ${recordPath} found; run record-base <path> <origin-path> <commit> first`);
463
433
  const record = validate(JSON.parse(fs.readFileSync(filename, 'utf8')));
464
434
  const files = seedFiles(root);
465
435
  requireMaterializedCopies(root, record, files);
466
- const origin = open(record, base, root, offline, baseArchive, revision);
436
+ const origin = fromApi ? apiSource(record, root, revision) : open(record, base, root, offline, baseArchive, revision);
467
437
  origin.refresh = {revision, recordPath, editionMigration};
468
438
  let writing = false, notices = [];
469
439
  try {
470
440
  const read = reader(origin);
471
441
  const next = read.tree(revision);
472
- const migrations = editionMigrations(record, {tree: next, read, revision, base: base ? origin.repository : null, recordPath, offline, consent: editionMigration});
442
+ const migrations = editionMigrations(record, {tree: next, read, revision, base: base ? origin.repository : null, recordPath, offline, fromApi, consent: editionMigration});
473
443
  const index = new Set(raw(root, 'ls-files', '-z').toString('utf8').split('\0').filter(Boolean));
474
444
  for (const name of record.copies.flatMap(copy => Object.keys(copy.files))) requirePhysical(root, name);
475
445
  const upstream = read.digests([...next.values()].map(({object}) => object));
@@ -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>|--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>]');
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>|--from-api]');
81
81
  console.log(json(result));
82
82
  } catch (error) {
83
83
  console.error(error.message);
@@ -3,7 +3,7 @@ import {safe} from './files.mjs';
3
3
  import {fileURLToPath} from 'node:url';
4
4
  const dataPath = 'foundation/edition-migrations.json';
5
5
  const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
6
- export function editionMigrations(record, {tree, read, revision, base, recordPath, offline, consent = []}) {
6
+ export function editionMigrations(record, {tree, read, revision, base, recordPath, offline, fromApi, consent = []}) {
7
7
  let migrations = [];
8
8
  const fail = reason => { throw Error(`Base edition migration data error: ${reason}. Repair ${dataPath} in Base and commit it, then refresh to that commit; no files were refreshed.`); };
9
9
  if (tree.has(dataPath)) {
@@ -38,7 +38,7 @@ export function editionMigrations(record, {tree, read, revision, base, recordPat
38
38
  if (missing.length) {
39
39
  const cli = fileURLToPath(new URL('./cli.mjs', import.meta.url));
40
40
  // Keep automatic acquisition automatic: its temporary checkout closes on refusal.
41
- const command = `${quote(process.execPath)} ${quote(cli)} refresh-base ${revision}${base ? ' --base ' + quote(base) : ''} --record ${quote(recordPath)}${offline ? ' --offline' : ''}${applicable.map(step => ' --edition-migration ' + step.id).join('')}`;
41
+ const command = `${quote(process.execPath)} ${quote(cli)} refresh-base ${revision}${base ? ' --base ' + quote(base) : ''} --record ${quote(recordPath)}${offline ? ' --offline' : ''}${fromApi ? ' --from-api' : ''}${applicable.map(step => ' --edition-migration ' + step.id).join('')}`;
42
42
  throw Error(`Edition migrations require consent before planning:\n${missing.map(step => `${step.id}: ${step.copies.join(', ')}; ${step.guide}: ${step.edit}`).join('\n')}\nReview the guides and repeat exactly: ${command}\nRefresh will leave these edition-owned edits owed; no files were refreshed.`);
43
43
  }
44
44
  return applicable;
@@ -5,6 +5,7 @@ import {raw, safe, requirePhysical, testSource, freedEntries, toolFile} from './
5
5
  import {dependencies, resolve, external, bindings, lexicalExports} from './runtime-dependencies.mjs';
6
6
  import {relocateDependencies} from './module-edges.mjs';
7
7
  import {sharedNamespaces} from './copy-namespaces.mjs';
8
+ import {fileURLToPath} from 'node:url';
8
9
  import {acknowledgementCommand} from './base-acknowledgements.mjs';
9
10
  import {checkModulePackages} from './module-packages.mjs';
10
11
  const code = name => /\.(?:[cm]?[jt]s|[jt]sx)$/.test(name) && !testSource(name);
@@ -18,6 +19,7 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
18
19
  const mappings = plans.filter(plan => !plan.retired).map(({copy}) => ({copy, ...namespace(copy)})).filter(mapping => mapping.from);
19
20
  const shared = sharedNamespaces(mappings);
20
21
  const cache = new Map(), planned = new Map(), recorded = new Map(), queue = [], withheld = [];
22
+ const retainedTargets = new Set();
21
23
  const disk = {has: name => {
22
24
  try { return fs.lstatSync(path.join(root, name)).isFile(); }
23
25
  catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return false; throw error; }
@@ -32,10 +34,11 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
32
34
  if (stat) removedObjects.add(target, stat);
33
35
  }
34
36
  const inspect = target => requirePhysical(root, safe(target), {cache, freed: removedObjects.has});
35
- function enqueue(plan, source, entry, adapted = false) {
37
+ function enqueue(plan, source, entry, retained = false) {
36
38
  const target = mapped(source, plan.copy);
37
- if (!adapted) planned.set(target, {plan, source, entry});
38
- if (code(source)) queue.push({plan, source, target, entry, adapted});
39
+ if (retained) retainedTargets.add(target);
40
+ else planned.set(target, {plan, source, entry});
41
+ if (code(source)) queue.push({plan, source, target, entry, retained});
39
42
  }
40
43
  for (const plan of plans) {
41
44
  for (const target of Object.keys(plan.copy.files)) recorded.set(target, plan);
@@ -44,7 +47,7 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
44
47
  }
45
48
  const directoryAdditions = new Set([...planned].filter(([target, {plan}]) => !Object.hasOwn(plan.copy.files, target) && !tree.has(plan.copy.originPath)).map(([target]) => target));
46
49
  const packageRoots = new Set([...planned.keys()].filter(target => !directoryAdditions.has(target)));
47
- for (const {target, adapted} of queue) if (adapted) packageRoots.add(target);
50
+ for (const {target, retained} of queue) if (retained) packageRoots.add(target);
48
51
  function namespace(copy) {
49
52
  const file = Object.hasOwn(copy.files, copy.path) || tree.has(copy.originPath);
50
53
  if (file && path.posix.basename(copy.path) !== path.posix.basename(copy.originPath)) return {};
@@ -82,7 +85,15 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
82
85
  if (index.has(target)) {
83
86
  if (!physical.stat) refuse(target, 'tracked edition source is missing', `git restore -- ${quote(target)}`);
84
87
  ownerSources.set(target, source);
85
- return; // Tracked, unrecorded source remains edition-owned, even at equal bytes.
88
+ // Retain ownership and bytes, but close Base edges introduced by seed
89
+ // reconciliation just as for an acknowledged adaptation. Seed-only
90
+ // helpers have no Base source and do not acquire a guessed origin.
91
+ if (tree.has(source) && code(source) && !retainedTargets.has(target)) {
92
+ retainedTargets.add(target);
93
+ packageRoots.add(target);
94
+ queue.push({source, target, retained: true});
95
+ }
96
+ return;
86
97
  }
87
98
  if (physical.stat && !index.has(target)) refuse(target, 'existing file has no Base copy record or Git index entry', `git add -f -- ${quote(target)}`);
88
99
  let plan = plans.find(plan => inside(target, plan.copy.path));
@@ -110,7 +121,7 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
110
121
  // records and plans satisfy that local edge before looking for a new source.
111
122
  const view = {
112
123
  has: name => planned.has(name) || recorded.has(name) || index.has(name) && disk.has(name),
113
- read: name => planned.has(name) ? blob(planned.get(name).entry) : local(name),
124
+ read: name => planned.has(name) ? relocations.get(name)?.toString('utf8') ?? blob(planned.get(name).entry) : local(name),
114
125
  };
115
126
  function requests(bytes, source, target) {
116
127
  return dependencies(bytes, source).filter(request => {
@@ -125,6 +136,9 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
125
136
  const originScope = {}, targetScope = {}, manifests = new Set();
126
137
  const dependency = resolve(tree, source, specifier, {...request, manifests, package: originScope});
127
138
  const destination = resolve(view, target, specifier, {...request, package: targetScope});
139
+ // A retained file's own relative imports without a Base counterpart stay
140
+ // seed-owned. Only Base dependencies participate in copy delivery.
141
+ if (retainedTargets.has(target) && specifier.startsWith('.') && !dependency) return {...request, external: true};
128
142
  if (!specifier.startsWith('.')) {
129
143
  if (originScope.external && targetScope.external && originScope.value === targetScope.value) return {...request, external: true};
130
144
  if (!targetScope.managed || originScope.external || targetScope.external) return {...request, reason: 'runtime package scope differs from its Base source'};
@@ -140,9 +154,9 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
140
154
  return {...request, dependency: source, destination, satisfied: true};
141
155
  }
142
156
  const expected = dependency && path.posix.join(path.posix.dirname(target), path.posix.relative(path.posix.dirname(source), dependency));
143
- // Relocate only new deliveries. Existing files and acknowledged adaptations
144
- // retain their current imports and ownership, including old missing edges.
145
- if (specifier.startsWith('.') && dependency && !recorded.has(target) && !witness(expected, dependency)) {
157
+ // Relocate only new deliveries. Retained files keep their seed-owned
158
+ // imports; a missing Base edge must have a witness at that exact path.
159
+ if (specifier.startsWith('.') && dependency && !recorded.has(target) && !retainedTargets.has(target) && !witness(expected, dependency)) {
146
160
  const destinations = recordedDestination(dependency);
147
161
  if (destinations.length > 1) return {...request, manifests, dependency, destination: expected,
148
162
  reason: `ambiguous Base copy mappings for ${dependency}: ${destinations.join(', ')}`};
@@ -164,16 +178,16 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
164
178
  // Preserve these edges during traversal; required planned files may still
165
179
  // complete a sparse historical copy by satisfying them.
166
180
  const baseline = new Set();
167
- for (const {plan, source, target} of queue) {
168
- if (!Object.hasOwn(plan.copy.files, target) || !disk.has(target) || bootstrap(source)) continue;
181
+ for (const {plan, source, target, retained} of queue) {
182
+ if (retained || !Object.hasOwn(plan.copy.files, target) || !disk.has(target) || bootstrap(source)) continue;
169
183
  for (const request of requests(local(target), source, target)) {
170
184
  const candidate = edge(source, target, request);
171
185
  if (!resolve(disk, target, request.specifier, request) && !recorded.has(candidate.destination)) baseline.add(key(target, request));
172
186
  }
173
187
  }
174
188
  // Do not let an optional directory addition incidentally fill an old edge.
175
- for (const {plan, source, target} of queue) {
176
- if (!Object.hasOwn(plan.copy.files, target) || !disk.has(target)) continue;
189
+ for (const {plan, source, target, retained} of queue) {
190
+ if (retained || !Object.hasOwn(plan.copy.files, target) || !disk.has(target)) continue;
177
191
  for (const request of requests(local(target), source, target)) if (baseline.has(key(target, request))) {
178
192
  const destination = resolve(view, target, request.specifier, request);
179
193
  if (!directoryAdditions.has(destination)) continue;
@@ -183,40 +197,51 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
183
197
  withheld.push({path: destination, originPath: addition.source, dependency: request.specifier});
184
198
  }
185
199
  }
186
- const incoming = new Set();
187
- for (const item of queue) for (const request of requests(item.adapted ? local(item.target) : blob(item.entry), item.source, item.target)) {
200
+ const incoming = new Set(), newlyRequired = new Set();
201
+ for (const item of queue) for (const request of requests(item.retained ? local(item.target) : blob(item.entry), item.source, item.target)) {
188
202
  if (baseline.has(key(item.target, request))) continue;
189
203
  const {destination} = edge(item.source, item.target, request);
190
- if (destination) incoming.add(destination);
204
+ if (destination) {
205
+ incoming.add(destination);
206
+ if (!item.retained) {
207
+ const before = disk.has(item.target) ? local(item.target) : '';
208
+ const previous = dependencies(before, item.source);
209
+ const oldNames = bindings(before, request.types, item.source).get(request.specifier);
210
+ const names = bindings(blob(item.entry), request.types, item.source).get(request.specifier);
211
+ if (!previous.some(old => key(item.target, old) === key(item.target, request)) ||
212
+ [...names ?? []].some(name => !oldNames?.has(name))) newlyRequired.add(destination);
213
+ }
214
+ }
191
215
  }
192
216
  function exportsAt(target, types = false, seen = new Set()) {
193
217
  if (seen.has(target)) return new Set();
194
218
  seen.add(target); inspect(target);
195
- if (!disk.has(target)) return null;
219
+ if (!view.has(target)) return null;
196
220
  if (!types && /\.d\.[cm]?ts$/.test(target)) return new Set();
197
221
  if (target.endsWith('.json')) return new Set(['default']);
198
- const result = lexicalExports(local(target), specifier => {
199
- const next = resolve(disk, target, specifier, {types});
222
+ const result = lexicalExports(view.read(target), specifier => {
223
+ const next = resolve(view, target, specifier, {types});
200
224
  return next ? exportsAt(next, types, seen) : null;
201
- }, types);
225
+ }, types, target);
202
226
  if (result === null) return null;
203
227
  const declaration = target.replace(/\.mjs$/, '.d.mts').replace(/\.js$/, '.d.ts');
204
- if (types && declaration !== target && disk.has(declaration)) {
228
+ if (types && declaration !== target && view.has(declaration)) {
205
229
  const declared = exportsAt(declaration, true, seen);
206
230
  if (declared === null) return null;
207
231
  for (const name of declared) result.add(name);
208
232
  }
209
233
  return result;
210
234
  }
235
+ const missingExports = new Map(), exportChecks = [];
211
236
  const seen = new Set();
212
237
  for (let i = 0; i < queue.length; i++) {
213
- const item = queue[i], {plan, source, target, entry, adapted} = item;
214
- if (seen.has(target) || !adapted && !plan.sources.some(([name]) => name === source)) continue;
238
+ const item = queue[i], {plan, source, target, entry, retained} = item;
239
+ if (seen.has(target) || !retained && !plan.sources.some(([name]) => name === source)) continue;
215
240
  seen.add(target);
216
- const bytes = adapted ? local(target) : blob(entry);
217
- const before = Object.hasOwn(plan.copy.files, target) && disk.has(target) ? local(target) : '';
218
- const imports = bindings(bytes), oldBindings = bindings(before);
219
- const typeImports = bindings(bytes, true), oldTypes = bindings(before, true);
241
+ const bytes = retained ? local(target) : blob(entry);
242
+ const before = !retained && Object.hasOwn(plan.copy.files, target) && disk.has(target) ? local(target) : '';
243
+ const imports = bindings(bytes, false, source), oldBindings = bindings(before, false, source);
244
+ const typeImports = bindings(bytes, true, source), oldTypes = bindings(before, true, source);
220
245
  const edges = requests(bytes, source, target).map(request => edge(source, target, request));
221
246
  // lock.mjs reads the whole tool dynamically to identify it. Deliver that
222
247
  // same file set, including parser notices and modules outside its imports.
@@ -232,7 +257,13 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
232
257
  const declaration = source.replace(/\.mjs$/, '.d.mts').replace(/\.cjs$/, '.d.cts');
233
258
  if (declaration !== source && tree.has(declaration)) edges.push({dependency: declaration, destination: target.replace(/\.mjs$/, '.d.mts').replace(/\.cjs$/, '.d.cts')});
234
259
  const novel = directoryAdditions.has(target) && !required.has(target) && !incoming.has(target);
235
- const preserved = request => baseline.has(key(target, request));
260
+ // An incoming importer can newly require a file which the seed has just
261
+ // restored and recorded at this target pin. Close that pristine Base file
262
+ // now; its unresolved siblings are the recovery refresh's deliveries.
263
+ // Ordinary older copies retain their historical edges. Seed-owned roots
264
+ // instead close the Base dependencies of their current local bytes.
265
+ const restored = !retained && plan.copy.revision === revision && newlyRequired.has(target);
266
+ const preserved = request => !restored && baseline.has(key(target, request));
236
267
  let hold;
237
268
  for (const edge of edges) {
238
269
  const {specifier, dependency, destination, satisfied} = edge;
@@ -253,38 +284,76 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
253
284
  if (edge.external || preserved(edge)) continue;
254
285
  include(dependency, destination);
255
286
  const owner = recorded.get(destination);
256
- if (!adapted && !planned.has(destination) && (index.has(destination) || owner?.copy.adapted?.[destination])) {
257
- for (const [types, current, previous] of [[false, imports, oldBindings], [true, typeImports, oldTypes]]) {
258
- const exported = exportsAt(destination, types);
259
- for (const name of current.get(specifier) ?? []) if (exported && !exported.has(name) && !previous.get(specifier)?.has(name)) {
260
- const comparison = destination + '.base';
261
- const extract = baseArchive ? `cp ${quote(path.join(baseArchive, dependency))} ${quote(comparison)}` :
262
- `git -C ${quote(base)} show ${quote(revision + ':' + dependency)} > ${quote(comparison)}`;
263
- throw Error([
264
- `Cannot refresh module ${target}: ${destination} does not export ${name} required by Base ${dependency} at ${revision}. No files were refreshed.`,
265
- 'Save the incoming dependency for comparison:', extract,
266
- `Merge the required exports from ${quote(comparison)} into ${quote(destination)}, preserving seed edits.`,
267
- ...(owner?.copy.adapted?.[destination] ? ['Review the reconciled bytes and mode, then acknowledge this adaptation:', acknowledgementCommand(root, destination, recordPath)] : []),
268
- `Remove ${quote(comparison)} after reconciliation, then repeat refresh-base.`,
269
- ].join('\n'));
270
- }
271
- }
287
+ if (dependency && (retained || !planned.has(destination) && (index.has(destination) || owner?.copy.adapted?.[destination]))) {
288
+ exportChecks.push({target, destination, dependency, specifier, imports, oldBindings, typeImports, oldTypes,
289
+ ancestor: owner?.copy.adapted?.[destination] ?? owner?.copy.revision ?? plan?.copy.revision ?? revision});
290
+ }
291
+ }
292
+ if (!retained && edges.some(edge => edge.relocation)) relocations.set(target, Buffer.from(relocateDependencies(bytes, edges)));
293
+ }
294
+ // Validate against the complete effective graph, including dependencies just
295
+ // planned through a retained file's re-exports. Unknown exports must not mask
296
+ // a genuinely absent name merely because those dependencies were missing.
297
+ for (const {target, destination, dependency, specifier, imports, oldBindings, typeImports, oldTypes, ancestor} of exportChecks) {
298
+ for (const [types, current, previous] of [[false, imports, oldBindings], [true, typeImports, oldTypes]]) {
299
+ const exported = exportsAt(destination, types);
300
+ for (const name of current.get(specifier) ?? []) if (exported && !exported.has(name) && !previous.get(specifier)?.has(name)) {
301
+ const key = JSON.stringify([target, destination, name, types]);
302
+ missingExports.set(key, {target, destination, dependency, name, ancestor});
272
303
  }
273
304
  }
274
- if (!adapted && edges.some(edge => edge.relocation)) relocations.set(target, Buffer.from(relocateDependencies(bytes, edges)));
275
305
  }
276
306
  const modules = new Map();
277
307
  for (const [target, {source, entry}] of planned) if (/\.(?:[cm]?[jt]s|[jt]sx)$/.test(source)) {
278
308
  const bytes = blob(entry);
279
309
  modules.set(target, {source, bytes, dependencies: requests(bytes, source, target).map(request => edge(source, target, request).destination).filter(Boolean)});
280
310
  }
281
- for (const {source, target, adapted} of queue) if (adapted) {
311
+ for (const {source, target, retained} of queue) if (retained) {
282
312
  const bytes = local(target);
283
- // Adaptations are roots of the retained graph; their own package choices
284
- // stay seed-owned, while new delivered dependencies must be declared.
285
- modules.set(target, {source, bytes: '', dependencies: requests(bytes, source, target).map(request => edge(source, target, request).destination).filter(Boolean)});
313
+ // Only Base imports still used by the retained file participate in package
314
+ // adoption. Seed-only package choices remain outside refresh's ownership.
315
+ const baseRequests = tree.has(source) ? dependencies(tree.read(source), source) : [];
316
+ const packageRequests = dependencies(bytes, source).filter(request => baseRequests.some(incoming => key(target, incoming) === key(target, request)));
317
+ modules.set(target, {source, bytes, packageRequests,
318
+ dependencies: requests(bytes, source, target).map(request => edge(source, target, request).destination).filter(Boolean)});
319
+ }
320
+ const refusals = [...missingExports.values()].map(({target, destination, dependency, name}) =>
321
+ `Cannot refresh module ${target}: ${destination} does not export ${name} required by Base ${dependency} at ${revision}.`);
322
+ let packages;
323
+ try { packages = checkModulePackages(root, modules, packageRoots, tree); }
324
+ catch (error) { refusals.push(error.message); }
325
+ if (missingExports.size) {
326
+ refusals.push('No files were refreshed. Reconcile each retained dependency in this order:');
327
+ const retained = new Map([...missingExports.values()].map(item => [item.destination, item]));
328
+ for (const {destination, dependency, ancestor} of retained.values()) {
329
+ const comparison = destination + '.base', saved = destination + '.seed', original = destination + '.ancestor';
330
+ const extract = baseArchive ? `cp ${quote(path.join(baseArchive, dependency))} ${quote(comparison)}` :
331
+ `git -C ${quote(base)} show ${quote(revision + ':' + dependency)} > ${quote(comparison)}`;
332
+ const acquisition = baseArchive ? `--base-archive ${quote(baseArchive)}` : `--base ${quote(base)}`;
333
+ const record = recordPath === 'base-copies.json' ? '' : ` --record ${quote(recordPath)}`;
334
+ refusals.push(
335
+ `Save seed edits and the original Base version used as the merge ancestor for ${quote(destination)} (use unused backup paths):`,
336
+ `cp ${quote(destination)} ${quote(saved)}`,
337
+ ...(baseArchive ? ['Obtain the original Base version from the recorded pin for the merge ancestor.'] :
338
+ [`git -C ${quote(base)} show ${quote(ancestor + ':' + dependency)} > ${quote(original)}`]),
339
+ 'Save the incoming dependency for comparison:', extract,
340
+ 'Install and record the incoming Base file before refreshing:',
341
+ `cp ${quote(comparison)} ${quote(destination)}`,
342
+ `node ${quote(fileURLToPath(new URL('./cli.mjs', import.meta.url)))} record-base ${quote(destination)} ${quote(dependency)} ${quote(revision)} ${acquisition}${record}`,
343
+ "Add all named packages at Base's listed versions with the seed's package manager.",
344
+ `rer refresh-base --ref ${quote(revision)} ${acquisition}${record}`,
345
+ 'After refresh delivers the new Base dependencies, merge the saved seed edits onto the new Base file; resolve any conflicts:',
346
+ `git merge-file ${quote(destination)} ${quote(original)} ${quote(saved)}`,
347
+ 'If the seed source has no Base ancestor, reconcile its edits explicitly instead of guessing an ancestor.',
348
+ 'Review the reconciled bytes and mode, then acknowledge this adaptation:',
349
+ acknowledgementCommand(root, destination, recordPath),
350
+ `rer refresh-base --ref ${quote(revision)} ${acquisition}${record}`,
351
+ `Remove ${quote(comparison)}, ${quote(original)} and ${quote(saved)} after reconciliation.`,
352
+ );
353
+ }
286
354
  }
287
- const packages = checkModulePackages(root, modules, packageRoots, tree);
355
+ if (refusals.length) throw Error(refusals.join('\n'));
356
+
288
357
  for (const [target, item] of packages.withheld) {
289
358
  const {plan, source} = planned.get(target);
290
359
  plan.sources = plan.sources.filter(([name]) => name !== source);
@@ -36,7 +36,7 @@ export function checkModulePackages(root, modules, roots, tree) {
36
36
  if (!manifests.has(reference)) manifests.set(reference, JSON.parse(tree.read(reference)));
37
37
  return version(manifests.get(reference), name);
38
38
  }
39
- for (const [target, module] of modules) for (const request of dependencies(module.bytes, module.source)) {
39
+ for (const [target, module] of modules) for (const request of module.packageRequests ?? dependencies(module.bytes, module.source)) {
40
40
  const name = packageName(request.specifier);
41
41
  if (!name) continue;
42
42
  const scope = {};
@@ -47,7 +47,10 @@ export function checkModulePackages(root, modules, roots, tree) {
47
47
  if (!packages.has(key)) packages.set(key, {package: name, version: declared ?? null, baseVersion: pinned ?? null,
48
48
  conflict: Boolean(declared && pinned && declared !== pinned), files: []});
49
49
  packages.get(key).files.push(target);
50
- if (!declared) missing.set(target, {package: name, baseVersion: pinned ?? null});
50
+ if (!declared) {
51
+ if (!missing.has(target)) missing.set(target, new Map());
52
+ missing.get(target).set(name, {package: name, baseVersion: pinned ?? null});
53
+ }
51
54
  }
52
55
  const required = new Set();
53
56
  function retain(target) {
@@ -56,9 +59,13 @@ export function checkModulePackages(root, modules, roots, tree) {
56
59
  for (const dependency of modules.get(target).dependencies) retain(dependency);
57
60
  }
58
61
  roots.forEach(retain);
59
- for (const [target, item] of missing) if (required.has(target)) {
60
- throw Error(`Cannot refresh module ${target}: package ${item.package} is not declared in the seed's package.json${item.baseVersion ? ` (Base uses ${item.baseVersion})` : ''}. This module is required by retained source. Review its adoption, declare and install the dependency with the seed's package manager, then repeat refresh-base; no files were refreshed.`);
62
+ const refusals = [];
63
+ for (const [target, items] of missing) if (required.has(target)) for (const item of items.values()) {
64
+ refusals.push(`Cannot refresh module ${target}: package ${item.package} is not declared in the seed's package.json${item.baseVersion ? ` (Base uses ${item.baseVersion})` : ''}. This module is required by retained source.`);
61
65
  }
66
+ if (refusals.length) throw Error([...refusals,
67
+ "Review their adoption, declare and install all named dependencies at Base's listed versions with the seed's package manager, then repeat refresh-base; no files were refreshed.",
68
+ ].join('\n'));
62
69
  // Withhold the whole connected optional addition, including its importers
63
70
  // and exclusive siblings, rather than leaving half of a feature behind.
64
71
  const neighbours = new Map([...modules.keys()].map(target => [target, new Set()]));
@@ -71,6 +78,6 @@ export function checkModulePackages(root, modules, roots, tree) {
71
78
  withheld.set(target, {...reason, path: target, originPath: modules.get(target).source, reason: 'undeclared-package'});
72
79
  for (const neighbour of neighbours.get(target)) hold(neighbour, reason);
73
80
  }
74
- for (const [target, reason] of missing) hold(target, reason);
81
+ for (const [target, items] of missing) hold(target, items.values().next().value);
75
82
  return {withheld, packageDependencies: [...packages.values()].map(item => ({...item, files: [...new Set(item.files)].sort()}))};
76
83
  }