@runeditrun/rer 0.2.85 → 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 (144) hide show
  1. package/README.md +138 -29
  2. package/cli/README.md +61 -1
  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/business/archive-task.mjs +32 -0
  14. package/cli/business/carry.mjs +3 -1
  15. package/cli/business/catchup-task.mjs +42 -0
  16. package/cli/business/choices.mjs +97 -0
  17. package/cli/business/command.mjs +23 -5
  18. package/cli/business/connect.mjs +19 -7
  19. package/cli/business/detector.mjs +4 -1
  20. package/cli/business/device.mjs +13 -0
  21. package/cli/business/export-inputs.mjs +69 -0
  22. package/cli/business/export-task.mjs +17 -0
  23. package/cli/business/invocation.mjs +8 -1
  24. package/cli/business/keychain.mjs +8 -1
  25. package/cli/business/lease.mjs +11 -1
  26. package/cli/business/local-commands.mjs +79 -31
  27. package/cli/business/outbound.mjs +9 -4
  28. package/cli/business/parsers-config.mjs +8 -7
  29. package/cli/business/parsers-syntax.mjs +7 -3
  30. package/cli/business/permissions.mjs +2 -0
  31. package/cli/business/questions.mjs +89 -9
  32. package/cli/business/setup-command.mjs +49 -0
  33. package/cli/business/setup-company.json +15 -0
  34. package/cli/business/setup-demo.mjs +95 -0
  35. package/cli/business/state.mjs +44 -10
  36. package/cli/business/supervisor.mjs +94 -35
  37. package/cli/business/vendor-door.mjs +230 -0
  38. package/cli/business/vendors/README.md +29 -3
  39. package/cli/business/vendors/common.mjs +8 -6
  40. package/cli/business/vendors/index.mjs +22 -11
  41. package/cli/business/vendors/sorry.mjs +106 -0
  42. package/cli/contract.mjs +2 -2
  43. package/cli/demo-deploy-error.mjs +14 -0
  44. package/cli/demo-native.mjs +4 -1
  45. package/cli/deploy-config.mjs +1 -1
  46. package/cli/deploy-owner-input.mjs +3 -1
  47. package/cli/deploy-variables.mjs +58 -0
  48. package/cli/door-clauses.mjs +157 -0
  49. package/cli/export.mjs +16 -4
  50. package/cli/hosted-output.mjs +17 -7
  51. package/cli/inspect.mjs +4 -0
  52. package/cli/jsonc.mjs +8 -4
  53. package/cli/lifecycle.mjs +3 -1
  54. package/cli/main.mjs +1 -0
  55. package/cli/managed-data-schema.mjs +14 -1
  56. package/cli/portability-empty.mjs +6 -0
  57. package/cli/portability-migrations.mjs +26 -4
  58. package/cli/production-auth.mjs +1 -1
  59. package/cli/production-mail.mjs +8 -2
  60. package/edition-authoring/archive-source.mjs +59 -0
  61. package/edition-authoring/base-copies.mjs +92 -18
  62. package/edition-authoring/cli.mjs +1 -1
  63. package/edition-authoring/edition-migrations.mjs +7 -3
  64. package/edition-authoring/module-closure.mjs +2 -16
  65. package/edition-authoring/workflow-copies.mjs +1 -1
  66. package/edition-authoring/workflow-scripts.mjs +12 -3
  67. package/foundation/runtime/contract-docs.mjs +215 -32
  68. package/foundation/runtime/contract-prose-patterns.mjs +14 -0
  69. package/foundation/runtime/contract-prose.mjs +88 -0
  70. package/global/CHANGELOG.md +93 -0
  71. package/global/README.md +138 -29
  72. package/global/door/command.mjs +3 -1
  73. package/global/main.mjs +1 -1
  74. package/modules/agent-door/CLAUSES.md +215 -0
  75. package/modules/agent-door/conformance/audit.mjs +66 -0
  76. package/modules/agent-door/conformance/authority.d.mts +2 -0
  77. package/modules/agent-door/conformance/authority.mjs +17 -0
  78. package/modules/agent-door/conformance/crypto.mjs +36 -0
  79. package/modules/agent-door/conformance/discovery.mjs +61 -0
  80. package/modules/agent-door/conformance/index.mjs +41 -0
  81. package/modules/agent-door/conformance/invocation.mjs +32 -0
  82. package/modules/agent-door/conformance/journey.mjs +112 -0
  83. package/modules/agent-door/conformance/narrowing.d.mts +1 -0
  84. package/modules/agent-door/conformance/narrowing.mjs +21 -0
  85. package/modules/agent-door/conformance/negative.mjs +47 -0
  86. package/modules/agent-door/conformance/network-modules.mjs +86 -0
  87. package/modules/agent-door/conformance/network-runtime.mjs +46 -0
  88. package/modules/agent-door/conformance/policy-phases.mjs +75 -0
  89. package/modules/agent-door/conformance/protocol.mjs +145 -0
  90. package/modules/agent-door/conformance/replay.mjs +38 -0
  91. package/modules/agent-door/conformance/schema.mjs +71 -0
  92. package/modules/agent-door/conformance/security.mjs +33 -0
  93. package/modules/agent-door/conformance/sponsors.mjs +68 -0
  94. package/modules/agent-door/conformance/surface.mjs +89 -0
  95. package/modules/agent-door/conformance/target.mjs +18 -0
  96. package/modules/agent-door/conformance/tool-name.d.mts +1 -0
  97. package/modules/agent-door/conformance/tool-name.mjs +7 -0
  98. package/modules/agent-door/conformance/webhooks.mjs +30 -0
  99. package/modules/container/image-variables.mjs +8 -2
  100. package/modules/demo-host/README.md +6 -0
  101. package/modules/demo-host/ownership.mjs +39 -0
  102. package/modules/demo-host/plan.mjs +2 -1
  103. package/modules/demo-host/remove.mjs +6 -1
  104. package/modules/import-kit/schema/importer-verification-receipt.schema.json +171 -0
  105. package/modules/import-kit/schema/importers.schema.json +107 -0
  106. package/modules/import-kit/src/door/ADOPTING.md +20 -0
  107. package/modules/import-kit/src/door/README.md +2 -1
  108. package/modules/import-kit/src/door/admission.ts +5 -3
  109. package/modules/import-kit/src/door/archive.ts +5 -2
  110. package/modules/import-kit/src/door/authority.ts +1 -0
  111. package/modules/import-kit/src/door/grants.ts +1 -1
  112. package/modules/import-kit/src/door/handler.ts +14 -8
  113. package/modules/import-kit/src/door/index.ts +1 -1
  114. package/modules/import-kit/src/door/jobs.ts +40 -0
  115. package/modules/import-kit/src/door/operator.ts +3 -3
  116. package/modules/import-kit/src/door/planning.ts +10 -6
  117. package/modules/import-kit/src/door/protocol.ts +2 -2
  118. package/modules/import-kit/src/door/raw.ts +25 -0
  119. package/modules/import-kit/src/door/refusals.ts +1 -0
  120. package/modules/import-kit/src/door/types.ts +26 -6
  121. package/modules/import-kit/src/receipt/encoding.ts +37 -0
  122. package/modules/import-kit/src/receipt/index.ts +69 -0
  123. package/modules/import-kit/src/receipt/policy.ts +24 -0
  124. package/modules/import-kit/src/receipt/types.ts +64 -0
  125. package/modules/import-kit/src/receipt/uri.ts +45 -0
  126. package/modules/import-kit/src/receipt/validation.ts +87 -0
  127. package/modules/import-kit/src/status/encoding.ts +13 -0
  128. package/modules/import-kit/src/status/evidence.ts +218 -0
  129. package/modules/import-kit/src/status/index.ts +56 -0
  130. package/modules/import-kit/src/status/schema.ts +208 -0
  131. package/modules/import-kit/src/status/types.ts +86 -0
  132. package/modules/operator-auth/accounts/delegated.mjs +48 -0
  133. package/modules/operator-auth/index.d.mts +7 -0
  134. package/modules/operator-auth/service.mjs +2 -0
  135. package/modules/portability/README.md +32 -11
  136. package/modules/portability/bridge.mjs +22 -2
  137. package/modules/portability/copies.mjs +8 -1
  138. package/modules/portability/derived.mjs +33 -0
  139. package/modules/portability/http-errors.mjs +1 -1
  140. package/modules/portability/import.mjs +14 -7
  141. package/package.json +4 -2
  142. package/scripts/publish-check/copy_identities.py +3 -1
  143. package/scripts/publish-check/github_refs.py +32 -13
  144. package/cli/business/opt-ins.mjs +0 -37
package/cli/export.mjs CHANGED
@@ -2,11 +2,15 @@ import { cp, mkdir, readFile, readdir, rm, writeFile, lstat } from 'node:fs/prom
2
2
  import { createHash } from 'node:crypto';
3
3
  import { resolve, dirname, relative } from 'node:path';
4
4
  import { testSource } from '../composition/git-source.mjs';
5
- import { cliVersion } from './version.mjs';
5
+ import { cliVersion, stampedVersion } from './version.mjs';
6
+ import { execFileSync } from 'node:child_process';
6
7
 
7
8
  // Copy whole maintained source/tooling directories. Python publication scans
8
9
  // load sibling modules and data dynamically; they belong in the inventory too.
9
- export const sourceRoots = ['default-seed/public/rer-theme.css', 'default-seed/public/brand/mark.svg', 'default-seed/public/fonts/outfit', 'bin/rer.mjs', 'cli', 'modules/delivery-producer/declarations.mjs', 'modules/delivery-producer/bindings.mjs', 'modules/delivery-producer/migrations.mjs', 'modules/delivery-producer/mail.mjs', 'modules/job-queue', 'modules/release', 'modules/deploy-kit', 'modules/site', 'modules/container', 'modules/demo-host', 'modules/demo', 'modules/integrations/core', 'modules/mail', 'modules/ai', 'modules/portability', 'modules/d1-transport', 'modules/import-kit/src/d1', 'modules/import-kit/src/door', 'modules/import-kit/src/readers', 'modules/import-kit/src/provenance/numeric-credentials.ts', 'modules/import-kit/src/types.ts', 'modules/import-kit/src/plan', 'modules/import-kit/src/provenance/canonical-hash.ts', 'modules/import-kit/src/provenance/canonical-stream.ts', 'modules/import-kit/src/provenance/credential-names.ts', 'modules/import-kit/src/provenance/credentials.ts', 'modules/import-kit/src/provenance/identity.ts', 'modules/import-kit/src/provenance/json-snapshot.ts', 'modules/import-kit/src/provenance/resumable-sha256.ts', 'modules/import-kit/src/provenance/validate-json.ts', 'modules/import-kit/src/journal/authority.ts', 'modules/import-kit/src/storage/originals.ts', 'modules/import-kit/src/storage/provenance.ts', 'modules/import-kit/src/storage/schema.ts', 'modules/erasure', 'modules/dependencies', 'modules/operator-auth', 'modules/owner-claim', 'operations', 'scripts/publish-check', 'scripts/publish-check.mjs', 'composition/git-source.mjs', 'edition-authoring/adopt.mjs', 'edition-authoring/base-acknowledgements.mjs', 'edition-authoring/base-copies.mjs', 'edition-authoring/module-closure.mjs', 'edition-authoring/edition-migrations.mjs', 'edition-authoring/cli.mjs', 'edition-authoring/copy-checkout.mjs', 'edition-authoring/files.mjs', 'edition-authoring/lock.mjs', 'edition-authoring/manifest.mjs', 'edition-authoring/offline-git.mjs', 'edition-authoring/parent-comparison.mjs', 'edition-authoring/projection-lock.mjs', 'edition-authoring/release.mjs', 'edition-authoring/runtime-dependencies.mjs', 'edition-authoring/module-resolution.mjs', 'edition-authoring/package-target.mjs', 'edition-authoring/module-syntax.mjs', 'edition-authoring/module-edges.mjs', 'edition-authoring/vendor/babel-parser', 'edition-authoring/workflow-copies.mjs', 'edition-authoring/workflow-scripts.mjs', 'edition-authoring/vendor/yaml', 'edition-authoring/sources.mjs', 'edition-authoring/updates.mjs', 'foundation/runtime/seed-contract.mjs', 'foundation/runtime/run-data.mjs', 'foundation/runtime/run-data.d.mts', 'foundation/runtime/contract-docs.mjs'];
10
+ export const sourceRoots = ['default-seed/public/rer-theme.css', 'default-seed/public/brand/mark.svg', 'default-seed/public/fonts/outfit', 'bin/rer.mjs', 'cli', 'modules/delivery-producer/declarations.mjs', 'modules/delivery-producer/bindings.mjs', 'modules/delivery-producer/migrations.mjs', 'modules/delivery-producer/mail.mjs', 'modules/job-queue', 'modules/release', 'modules/deploy-kit', 'modules/site', 'modules/container', 'modules/demo-host', 'modules/demo', 'modules/integrations/core', 'modules/mail', 'modules/ai', 'modules/portability', 'modules/d1-transport', 'modules/import-kit/src/receipt', 'modules/import-kit/src/status', 'modules/import-kit/schema', 'modules/import-kit/src/d1', 'modules/import-kit/src/door', 'modules/import-kit/src/readers', 'modules/import-kit/src/provenance/numeric-credentials.ts', 'modules/import-kit/src/types.ts', 'modules/import-kit/src/plan', 'modules/import-kit/src/provenance/canonical-hash.ts', 'modules/import-kit/src/provenance/canonical-stream.ts', 'modules/import-kit/src/provenance/credential-names.ts', 'modules/import-kit/src/provenance/credentials.ts', 'modules/import-kit/src/provenance/identity.ts', 'modules/import-kit/src/provenance/json-snapshot.ts', 'modules/import-kit/src/provenance/resumable-sha256.ts', 'modules/import-kit/src/provenance/validate-json.ts', 'modules/import-kit/src/journal/authority.ts', 'modules/import-kit/src/storage/originals.ts', 'modules/import-kit/src/storage/provenance.ts', 'modules/import-kit/src/storage/schema.ts', 'modules/erasure', 'modules/dependencies', 'modules/operator-auth', 'modules/owner-claim', 'operations', 'scripts/publish-check', 'scripts/publish-check.mjs', 'composition/git-source.mjs', 'edition-authoring/adopt.mjs', 'edition-authoring/base-acknowledgements.mjs', 'edition-authoring/base-copies.mjs', 'edition-authoring/module-closure.mjs', 'edition-authoring/edition-migrations.mjs', 'edition-authoring/cli.mjs', 'edition-authoring/copy-checkout.mjs', 'edition-authoring/files.mjs', 'edition-authoring/lock.mjs', 'edition-authoring/manifest.mjs', 'edition-authoring/offline-git.mjs', 'edition-authoring/parent-comparison.mjs', 'edition-authoring/projection-lock.mjs', 'edition-authoring/release.mjs', 'edition-authoring/runtime-dependencies.mjs', 'edition-authoring/module-resolution.mjs', 'edition-authoring/package-target.mjs', 'edition-authoring/module-syntax.mjs', 'edition-authoring/module-edges.mjs', 'edition-authoring/vendor/babel-parser', 'edition-authoring/workflow-copies.mjs', 'edition-authoring/workflow-scripts.mjs', 'edition-authoring/vendor/yaml', 'edition-authoring/sources.mjs', 'edition-authoring/updates.mjs', 'foundation/runtime/seed-contract.mjs', 'foundation/runtime/run-data.mjs', 'foundation/runtime/run-data.d.mts', 'foundation/runtime/contract-docs.mjs'];
11
+ sourceRoots.push('modules/agent-door/conformance', 'modules/agent-door/CLAUSES.md');
12
+ sourceRoots.push('edition-authoring/archive-source.mjs');
13
+ sourceRoots.push('foundation/runtime/contract-prose.mjs', 'foundation/runtime/contract-prose-patterns.mjs');
10
14
  export async function inventory(base, roots = sourceRoots) {
11
15
  const files = [];
12
16
  async function walk(path) {
@@ -40,8 +44,16 @@ export async function exportCLI(base, destination) {
40
44
  record[path] = { source: path, sha256: createHash('sha256').update(bytes).digest('hex') };
41
45
  }
42
46
  const onboardingFiles=Object.fromEntries(await Promise.all((await inventory(base,['onboarding'])).map(async path=>[path.slice('onboarding/'.length),{source:path,sha256:createHash('sha256').update(await readFile(resolve(base,path))).digest('hex')}])));
43
- // cliVersion: the rer version of this Base source, which `rer describe` reports.
44
- const version = cliVersion(base);
47
+ // The maintained reference is committed beside its exporter. Stamp its last
48
+ // exported source change, so committing generated copies does not invalidate
49
+ // their version again. Exports to other checkouts still name the exact HEAD.
50
+ let version;
51
+ if (resolve(destination) === resolve(base, 'default-seed')) {
52
+ const revision = execFileSync('git', ['-C', base, 'log', '-1', '--format=%H', 'HEAD', '--',
53
+ 'global/package.json', ...files, ...Object.values(onboardingFiles).map(file => file.source)], { encoding: 'utf8' }).trim();
54
+ const source = JSON.parse(await readFile(resolve(base, 'global/package.json'), 'utf8'));
55
+ version = stampedVersion(base, source.version, revision);
56
+ } else version = cliVersion(base);
45
57
  await writeFile(resolve(target, 'inventory.json'), JSON.stringify({ version: 1, ...(version ? { cliVersion: version } : {}), onboarding: '../base-onboarding', onboardingFiles, files: record }, null, 2) + '\n');
46
58
  await writeFile(resolve(destination, 'scripts/rer.mjs'), "#!/usr/bin/env node\nimport { main } from './base-cli/cli/main.mjs';\nprocess.exitCode = await main();\n");
47
59
  }
@@ -9,11 +9,12 @@ import { migrate } from '../modules/container/migrations.mjs';
9
9
  import { readMigrationRewrites, withRewrites } from '../modules/deploy-kit/migrations.mjs';
10
10
  import { RerError } from './errors.mjs';
11
11
  import { hostedMailCredentials } from './hosted-mail.mjs';
12
+ import { shared } from './shared.mjs';
12
13
 
13
14
  // Serve the production build the way rer deploy hosts it (assets behind the
14
15
  // Worker, deploy identity bound, a public https origin) on loopback, with no
15
16
  // network or account. The ingress hands the app the hosted URL and Host.
16
- const ORIGIN = 'https://rer-hosted-check.invalid';
17
+ export const HOSTED_ORIGIN = 'https://rer-hosted-check.invalid';
17
18
  const ingress = `export default {fetch(request,env){const url=new URL(request.headers.get('x-rer-original-url')),headers=new Headers(request.headers);headers.delete('x-rer-original-url');headers.set('host',url.host);return env.APP.fetch(new Request(url,{method:request.method,headers,redirect:'manual',...(!['GET','HEAD'].includes(request.method)?{body:request.body}:{})}))}}`;
18
19
  const read = async path => JSON.parse(await readFile(path, 'utf8'));
19
20
  const optional = path => read(path).catch(error => { if (error.code === 'ENOENT') return {}; throw error; });
@@ -43,7 +44,8 @@ const links = html => [...html.matchAll(/(?:src|href)=["'](\/[^"'#?\s]+)/g)].map
43
44
 
44
45
  /** The build served as rer deploy hosts it, with declared vars, origin and
45
46
  * stand-in deploy/Managed mail secrets. `fetch(path, init)` uses the deployed origin. */
46
- export async function serveHosted(root, { declaration: declarationPath = 'deploy.json' } = {}) {
47
+ export async function serveHosted(root, { declaration: declarationPath = 'deploy.json', bindings = {}, outboundService } = {}) {
48
+ const { loopbackFetch } = await shared('loopback-fetch.mjs');
47
49
  const build = join(root, 'dist/server'), client = join(root, 'dist/client');
48
50
  let config;
49
51
  try { config = await read(join(build, 'wrangler.json')); }
@@ -61,9 +63,9 @@ export async function serveHosted(root, { declaration: declarationPath = 'deploy
61
63
  if (!Object.hasOwn(secrets, binding)) secrets[binding] = standIn({}, manifest.fields?.find(field => field.name === binding));
62
64
  }
63
65
  const mf = new Miniflare(convertV4MiniflareOptions({ host: '127.0.0.1', port: 0, cf: false, workers: [{ name: 'ingress', modules: true, script: ingress, serviceBindings: { APP: 'app' } }, {
64
- name: 'app', modules, modulesRoot: build, compatibilityDate: config.compatibility_date, compatibilityFlags: config.compatibility_flags,
65
- bindings: { ...config.vars, ...declaration.vars, ...secrets, ...(declaration.originVar ? { [declaration.originVar]: ORIGIN } : {}),
66
- RER_DEPLOY_SOURCE: identity.sourceSha, RER_DEPLOY_FINGERPRINT: identity.fingerprint, RER_VERSION: { id: identity.versionId, tag: '', timestamp: new Date().toISOString() } },
66
+ name: 'app', ...(outboundService ? { outboundService } : {}), modules, modulesRoot: build, compatibilityDate: config.compatibility_date, compatibilityFlags: config.compatibility_flags,
67
+ bindings: { ...config.vars, ...declaration.vars, ...secrets, ...(declaration.originVar ? { [declaration.originVar]: HOSTED_ORIGIN } : {}),
68
+ RER_DEPLOY_SOURCE: identity.sourceSha, RER_DEPLOY_FINGERPRINT: identity.fingerprint, RER_VERSION: { id: identity.versionId, tag: '', timestamp: new Date().toISOString() }, ...bindings },
67
69
  d1Databases: Object.fromEntries((config.d1_databases ?? []).map(item => [item.binding, item.database_id ?? item.database_name])),
68
70
  r2Buckets: Object.fromEntries((config.r2_buckets ?? []).map(item => [item.binding, item.bucket_name])),
69
71
  kvNamespaces: Object.fromEntries((config.kv_namespaces ?? []).map(item => [item.binding, item.id ?? item.binding])),
@@ -84,8 +86,16 @@ export async function serveHosted(root, { declaration: declarationPath = 'deploy
84
86
  await migrate(await mf.getD1Database(item.binding, 'app'), withRewrites(plan, await readMigrationRewrites(root), { partial: true }));
85
87
  }
86
88
  } catch (error) { await mf.dispose(); throw error; }
87
- return { client, identity, origin: ORIGIN, close: () => mf.dispose(),
88
- fetch: (path, { headers, ...init } = {}) => fetch(loopback, { ...init, redirect: 'manual', headers: { ...headers, 'x-rer-original-url': `${ORIGIN}/${path}` } }) };
89
+ return { client, identity, origin: HOSTED_ORIGIN,
90
+ database: async binding => {
91
+ if (!(config.d1_databases ?? []).some(item => item.binding === binding)) throw new RerError('hosted_database_invalid', 'Verification can read only a declared disposable database binding.', 1);
92
+ const db = await mf.getD1Database(binding, 'app');
93
+ return { prepare(sql) {
94
+ if (typeof sql !== 'string' || !/^\s*SELECT\b/i.test(sql) || sql.includes(';')) throw new RerError('hosted_database_invalid', 'Verification state access is read-only SELECT.', 1);
95
+ return db.prepare(sql);
96
+ } };
97
+ }, close: () => mf.dispose(),
98
+ fetch: (path, { headers, ...init } = {}) => loopbackFetch(loopback, { ...init, redirect: 'manual', headers: { ...headers, 'x-rer-original-url': `${HOSTED_ORIGIN}/${path}` } }) };
89
99
  }
90
100
 
91
101
  export async function checkHostedOutput(root, options) {
package/cli/inspect.mjs CHANGED
@@ -1,3 +1,4 @@
1
+ import { deployVariableClause } from './deploy-variables.mjs';
1
2
  import { browserDoctor } from './browser-runtime.mjs';
2
3
  import { dependencyDoctor } from './dependency-doctor.mjs';
3
4
  import { inventory } from './export.mjs';
@@ -25,6 +26,7 @@ import { checkoutPlaceholderMarks } from './placeholder-mark.mjs';
25
26
  import { contractStatusClauses } from './contract-status.mjs';
26
27
  import { hostedExportCommand } from './hosted-export-command.mjs';
27
28
  import { cloudflareCredentials } from './deploy-needs.mjs';
29
+ import { agentSurfaceClauses } from './agent-surface.mjs';
28
30
 
29
31
  // cliVersion: the rer version of the code answering (absent for a vendored copy
30
32
  // too old to record one). defaults: what a server start applies when the person
@@ -81,6 +83,8 @@ export async function check(project, explicitProfile) {
81
83
  // A warning, never a failing clause: live run sites redeploy while seeds keep Base's mark.
82
84
  let placeholderMarks = [];
83
85
  clauses.push(...await deliveryDeclarationClauses(project.root));
86
+ clauses.push(await deployVariableClause(project.root, project.adapter));
87
+ clauses.push(...await agentSurfaceClauses(project.root));
84
88
  for (const command of project.commands) add('SC-10.inputs.' + command.name, command.available, `Restore the declared inputs for ${command.name}.`);
85
89
  for (const loop of project.descriptor.loops ?? []) add('SC-10.loop.' + loop.id, !loop.required || loop.enabled, `Enable the required ${loop.id} loop or correct its declaration.`);
86
90
  if (project.profile === 'first-party' || explicitProfile === 'first-party') {
package/cli/jsonc.mjs CHANGED
@@ -7,8 +7,8 @@ function location(text, position) {
7
7
  // version's error wording. An explicit stack also handles deeply nested input.
8
8
  // Only comments and commas accepted by the grammar are masked; offsets stay in
9
9
  // the original source and comment removal can never join separate tokens.
10
- export function parseJsonc(text) {
11
- const result = text.split(''), stack = [{ kind: 'root', state: 'value' }];
10
+ export function parseJsonc(text, onProperty) {
11
+ const result = text.split(''), stack = [{ kind: 'root', state: 'value', path: [] }];
12
12
  let index = 0;
13
13
  const fail = (message, position = index) => {
14
14
  throw new SyntaxError(`${position === text.length ? 'Unexpected end of JSON input' : message} at ${location(text, position)}`);
@@ -80,7 +80,10 @@ export function parseJsonc(text) {
80
80
  index++; stack.pop();
81
81
  } else if (frame.state === 'keyOrEnd') {
82
82
  if (char !== '"') fail('Expected a property name');
83
- string(); frame.state = 'colon';
83
+ const start = index; string();
84
+ frame.key = onProperty ? JSON.parse(text.slice(start, index)) : undefined;
85
+ onProperty?.([...frame.path, frame.key], start);
86
+ frame.state = 'colon';
84
87
  } else if (frame.state === 'colon') {
85
88
  if (char !== ':') fail("Expected ':' after property name");
86
89
  index++; frame.state = 'value';
@@ -91,10 +94,11 @@ export function parseJsonc(text) {
91
94
  if (text[index] === closing) result[comma] = ' ';
92
95
  frame.state = frame.kind === 'object' ? 'keyOrEnd' : 'valueOrEnd';
93
96
  } else {
97
+ const path = !onProperty ? undefined : frame.kind === 'root' ? [] : [...frame.path, frame.kind === 'array' ? frame.next++ : frame.key];
94
98
  frame.state = frame.kind === 'root' ? 'end' : 'comma';
95
99
  if (char === '{' || char === '[') {
96
100
  index++;
97
- stack.push({ kind: char === '{' ? 'object' : 'array', state: char === '{' ? 'keyOrEnd' : 'valueOrEnd' });
101
+ stack.push({ kind: char === '{' ? 'object' : 'array', state: char === '{' ? 'keyOrEnd' : 'valueOrEnd', path, next: 0 });
98
102
  } else if (char === '"') string();
99
103
  else if (char === '-' || digit()) number();
100
104
  else {
package/cli/lifecycle.mjs CHANGED
@@ -112,7 +112,9 @@ async function runLifecycle(project, options, out, deployRedaction) {
112
112
  const declaration = adapter.deployDeclaration ?? adapter.deploy?.declaration;
113
113
  const hosted = await (await import('./hosted-output.mjs')).checkHostedOutput(project.root, { declaration });
114
114
  await store.step('Checking that page sections hydrate as separate units');
115
- return { hosted, hydration: await (await import('./hydration/check.mjs')).checkHydration(project.root, { pages: adapter.publicPages, declaration, report: lines => lines.forEach(line => store.report(line)) }) };
115
+ const hydration = await (await import('./hydration/check.mjs')).checkHydration(project.root, { pages: adapter.publicPages, declaration, report: lines => lines.forEach(line => store.report(line)) });
116
+ const agentDoor = await (await import('./agent-door.mjs')).checkAgentDoor(project.root, { declaration, setupManifest: project.setupManifest, owner: adapter.hooks?.owner, report: line => store.report(line) });
117
+ return { hosted, hydration, agentDoor };
116
118
  }
117
119
  if (['export', 'import'].includes(options.verb)) return await transfer(project, options, signal, { store, operationToken: operation.token });
118
120
  if (options.verb === 'deploy') {
package/cli/main.mjs CHANGED
@@ -8,6 +8,7 @@ import { check, describe, doctorSummary } from './inspect.mjs';
8
8
  import { selectNodeRuntime } from './node-runtime.mjs';
9
9
 
10
10
  export async function main(argv = process.argv.slice(2)) {
11
+ if (argv[0] === 'door' && argv[1] === 'clauses') return (await import('./door-clauses.mjs')).doorClausesCommand(argv.slice(2));
11
12
  if (argv[0] === 'business') return (await import('./business/command.mjs')).businessCommand(argv.slice(1));
12
13
  if (argv[0] === 'companion') return (await import('./companion/command.mjs')).companionCommand(argv.slice(1));
13
14
  // Every runtime a seed's hooks start inherits this: Wrangler and the Cloudflare
@@ -24,7 +24,10 @@ export async function managedSchema(db, plan, policy, ledger) {
24
24
  if (!normalized.has(object.sql)) normalized.set(object.sql, schemaSQL(object.sql));
25
25
  return normalized.get(object.sql);
26
26
  };
27
- const objects = source.filter(object => ['table', 'trigger', 'index', 'view'].includes(object.type));
27
+ // Older native restores left engine-owned staging tables behind. They are
28
+ // transient copies, excluded from portability identity, not unknown product DDL.
29
+ const objects = source.filter(object => ['table', 'trigger', 'index', 'view'].includes(object.type)
30
+ && !(object.type === 'table' && object.name.toLowerCase().startsWith('rer_portability_stage_')));
28
31
  const retired = new Map();
29
32
  let previous = new Map();
30
33
  try {
@@ -37,6 +40,16 @@ export async function managedSchema(db, plan, policy, ledger) {
37
40
  }
38
41
  previous = current;
39
42
  }
43
+ // A Managed dump omits derived virtual tables and their shadow storage.
44
+ // Install only exact policy names that the destination's own migrations
45
+ // establish as virtual tables. Source SQL never gains a virtual-table door.
46
+ const virtual = scratch.prepare('PRAGMA table_list').all().filter(table => table.type === 'virtual');
47
+ for (const table of virtual) if ((policy.derivedTables ?? []).includes(table.name) && !(policy.includeTables ?? []).includes(table.name)) {
48
+ insist(!objects.some(object => object.type === 'table' && object.name === table.name), 'managed_data_schema_incompatible', 409);
49
+ const target = previous.get(key({ type: 'table', name: table.name }));
50
+ try { await db.prepare(target.sql).run(); }
51
+ catch { throw new PortabilityError('managed_data_derived_refused', 409); }
52
+ }
40
53
  // Native restore also installs runtime-owned bookkeeping. Derive it with
41
54
  // the same destination helpers, never a source name or a policy wildcard.
42
55
  const native = nativeDatabase(scratch);
@@ -47,6 +47,12 @@ export async function emptyNativePreflight({ root, binding, policy, policyModule
47
47
  const after = await Promise.all(paths.map(status));
48
48
  insist(before.every((info, i) => info ? after[i] && ['ino', 'size', 'mtimeMs', 'ctimeMs'].every(key => info[key] === after[i][key]) : !after[i]), 'restore_state_changed', 409);
49
49
  snapshot = new DatabaseSync(join(directory, 'database.sqlite'), { readOnly: true });
50
+ // Wrangler can create a D1 file before any product migrations run. Only
51
+ // literal SQLite/Cloudflare engine internals may exist in that empty file;
52
+ // policy exclusions and migration ledgers do not make other schema empty.
53
+ // Every existing product/foreign object still goes through the full policy
54
+ // and occupied-table checks before migrations can change the destination.
55
+ if (!snapshot.prepare("SELECT 1 FROM sqlite_master WHERE substr(lower(name),1,7) <> 'sqlite_' AND substr(lower(name),1,4) <> '_cf_' LIMIT 1").get()) return;
50
56
  const db = { prepare(sql) { const query = snapshot.prepare(sql); let values = []; return {
51
57
  bind(...args) { values = args; return this; },
52
58
  async all() { return { results: query.all(...values) }; },
@@ -62,27 +62,49 @@ export async function mapMigrationLedger({root,binding='DB',platformMigrations,e
62
62
  } catch(error) { throw constantRefusal(error); }
63
63
  }
64
64
 
65
+ // Older runners leave Wrangler's bookkeeping beside their authoritative hashed
66
+ // history. A tracked D1 ledger is another history and must agree with it.
67
+ async function legacyPairPreflight(db) {
68
+ const columns=await all(db,'PRAGMA table_info(_rer_deploy_migrations)');
69
+ insist(['name','sha256','state'].every(name=>columns.some(column=>column.name===name)),'migration_ledger:incompatible',409);
70
+ const history=await all(db,'SELECT name,sha256,state FROM _rer_deploy_migrations ORDER BY name');
71
+ insist(history.every(row=>row.state==='applied'),'migration_ledger:uncertain',409);
72
+ insist(history.every(row=>typeof row.name==='string' && typeof row.sha256==='string' && /^[a-f0-9]{64}$/.test(row.sha256)) && new Set(history.map(row=>row.name)).size===history.length,'migration_ledger:incompatible',409);
73
+ const nativeColumns=(await all(db,'PRAGMA table_info(d1_migrations)')).map(column=>column.name);
74
+ const tracked=nativeColumns.includes('state') || nativeColumns.includes('sha256');
75
+ insist(['id','name','applied_at'].every(name=>nativeColumns.includes(name)) && (!tracked || nativeColumns.includes('state') && nativeColumns.includes('sha256')),'migration_ledger:incompatible',409);
76
+ const native=await all(db,`SELECT name${tracked?',sha256,state':''} FROM d1_migrations ORDER BY id`);
77
+ insist(native.every(row=>typeof row.name==='string') && new Set(native.map(row=>row.name)).size===native.length,'migration_ledger:incompatible',409);
78
+ if(tracked) {
79
+ insist(native.every(row=>row.state==='applied'),'migration_ledger:uncertain',409);
80
+ insist(native.every(row=>typeof row.sha256==='string' && /^[a-f0-9]{64}$/.test(row.sha256)),'migration_ledger:incompatible',409);
81
+ insist(native.length===history.length && native.every((row,index)=>row.name===history[index].name && row.sha256===history[index].sha256),'migration_ledger:multiple',409);
82
+ } else insist(native.every(row=>history.some(prior=>prior.name===row.name)),'migration_ledger:multiple',409);
83
+ }
84
+
65
85
  // Adapter entry point, before *any* native Wrangler apply. The caller supplies
66
86
  // the real target binding and keeps its writers stopped through apply/transfer.
67
87
  // This only reads: it never repairs history or creates a second ledger.
68
88
  export async function nativeMigrationPreflight({root,db,binding='DB',platformMigrations}) {
69
89
  const declaration=platformMigrationDeclaration(platformMigrations);
70
90
  const tables=await all(db,`SELECT type,name FROM sqlite_master WHERE lower(name) IN (${ledgerNames.map(name=>`'${name}'`).join(',')})`);
71
- insist(tables.length<=1,'migration_ledger:multiple',409);
91
+ const legacyPair=tables.length===2 && ['_rer_deploy_migrations','d1_migrations'].every(name=>tables.some(row=>row.name===name));
92
+ insist(tables.length<=1 || legacyPair,'migration_ledger:multiple',409);
72
93
  insist(tables.every(row=>row.type==='table' && ledgerNames.includes(row.name)),'migration_ledger:incompatible',409);
73
- const table=tables[0]?.name;
94
+ const table=legacyPair?'_rer_deploy_migrations':tables[0]?.name;
74
95
  if(!table)return {nativeApply:true};
75
96
  // This runner's history cannot authorize Wrangler to apply the same files.
76
- insist(table!=='_rer_deploy_migrations','migration_ledger:runner',409);
97
+ insist(table!=='_rer_deploy_migrations' || legacyPair,'migration_ledger:runner',409);
77
98
  const files=await migrationInventory(root,binding,declaration);
78
99
  let nativeApply=false;
79
100
  try {
101
+ if(legacyPair)await legacyPairPreflight(db);
80
102
  const ledger=await destinationLedger(db),applied=matchMigrationLedger(ledger,files,declaration);
81
103
  // Wrangler skips only literal filenames, not transfer aliases or hashes.
82
104
  if(table==='d1_migrations')insist(ledger.every(row=>files.some(file=>file.name===row.name)),'migration_ledger:incompatible',409);
83
105
  nativeApply=table==='d1_migrations' && files.some(file=>!applied.includes(file.name));
84
106
  // The checkout file is named: it is the seed's own, never a ledger value.
85
- if(table==='rer_migrations')for(const file of files)if(!applied.includes(file.name))throw Object.assign(new PortabilityError('migration_ledger:unapplied',409),{migration:file.name});
107
+ if(table!=='d1_migrations')for(const file of files)if(!applied.includes(file.name))throw Object.assign(new PortabilityError('migration_ledger:unapplied',409),{migration:file.name});
86
108
  } catch(error) { throw constantRefusal(error); }
87
109
  return {nativeApply};
88
110
  }
@@ -12,7 +12,7 @@ export async function requireProductionAuth({ root, declaration, env, setupManif
12
12
  for (const secret of declaration.secrets ?? []) if (env[secret.environment]?.trim()) bindings[secret.binding] = env[secret.environment];
13
13
  const mail = await productionMail(root, declaration, env, declarationPath);
14
14
  if (!setupManifest?.steps?.some(step => step.type === 'owner-claim') && !dependencies.length && !mail.declared) return;
15
- if (mail.senderIssue && options.verb === 'deploy') throw refuse(`${mail.senderIssue} Nothing was built or uploaded.`);
15
+ if (mail.senderIssue && options.verb === 'deploy' && !(options.dryRun && mail.fixtureSender)) throw refuse(`${mail.senderIssue} Nothing was built or uploaded.`);
16
16
  if (mail.configured()) return;
17
17
  if (mail.canInspect && !options.dryRun && declarationPath) {
18
18
  try {
@@ -11,11 +11,16 @@ const present = value => typeof value === 'string' && Boolean(value.trim());
11
11
  // The sender forms the mail runtime sends from: a bare address or "Display Name <address>".
12
12
  const sender = value => { try { parseAddress(value); return true; } catch { return false; } };
13
13
  const SENDER = "MAIL_FROM (a real sender on your provider's verified domain; bare address or Display Name <address>)";
14
+ const fixtureSender = value => {
15
+ if (!sender(value)) return false;
16
+ const domain = parseAddress(value).email.toLowerCase().split('@')[1];
17
+ return /(?:^|\.)(?:invalid|example|test|localhost)$/.test(domain)
18
+ || /(?:^|\.)example\.(?:com|net|org)$/.test(domain);
19
+ };
14
20
  const placeholderSender = value => {
15
21
  if (!sender(value)) return false;
16
22
  const { email } = parseAddress(value), [local, domain] = email.toLowerCase().split('@');
17
- return /(?:^|\.)(?:invalid|example|test|localhost)$/.test(domain)
18
- || /(?:^|\.)example\.(?:com|net|org)$/.test(domain)
23
+ return fixtureSender(value)
19
24
  || /^(?:your-?domain|your-?business|fake|placeholder|changeme)\./.test(domain)
20
25
  || /^(?:fake|placeholder|change-?me|replace-?me|your-?email|your-?name|you)(?:[+._-]|$)/.test(local);
21
26
  };
@@ -99,6 +104,7 @@ export async function productionMail(root, declaration, env, declarationPath = '
99
104
  return {
100
105
  declared: 'MAIL_PROVIDER' in bindings || publicInputs.has('MAIL_PROVIDER') || secrets.has('MAIL_API_KEY') || selected.length > 0,
101
106
  senderIssue,
107
+ fixtureSender: fixtureSender(bindings.MAIL_FROM),
102
108
  configured: (live = []) => routes.some(missing => missing(live).length === 0),
103
109
  canInspect: sender(bindings.MAIL_FROM) && !senderIssue && routes.length > 0,
104
110
  missing: routes.length ? routes.map(missing => missing([]).join(', ')).join(' or ') : [
@@ -0,0 +1,59 @@
1
+ // A source archive supplies one caller-identified revision, never Git history.
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import crypto from 'node:crypto';
5
+ import {hash, safe} from './files.mjs';
6
+
7
+ const limit = 64 * 1024 * 1024;
8
+ const objectId = bytes => crypto.createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
9
+
10
+ export function archiveReader(directory, revision) {
11
+ if (!/^[a-f0-9]{40}$/.test(revision)) throw Error('A Base archive requires its immutable full 40-character Base commit in --ref');
12
+ if (!fs.lstatSync(directory).isDirectory()) throw Error('Base archive must be a plain directory without .git');
13
+ const root = fs.realpathSync(directory), tree = new Map(), objects = new Map();
14
+ function bytes(name) {
15
+ const filename = path.join(root, name), stat = fs.lstatSync(filename);
16
+ if (!stat.isFile()) throw Error(`Base archive source is not a regular file: ${name}`);
17
+ if (stat.size > limit) throw Error('Base archive source output exceeds the 64 MiB acquisition limit');
18
+ return fs.readFileSync(filename);
19
+ }
20
+ function walk(prefix = '') {
21
+ for (const name of fs.readdirSync(path.join(root, prefix)).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)))) {
22
+ if (name.toLowerCase() === '.git') throw Error('Base archive must be a plain directory without .git');
23
+ const relative = safe(prefix ? `${prefix}/${name}` : name), stat = fs.lstatSync(path.join(root, relative));
24
+ if (stat.isDirectory()) walk(relative);
25
+ else if (stat.isFile()) {
26
+ const object = objectId(bytes(relative)), mode = stat.mode & 0o100 ? '100755' : '100644';
27
+ tree.set(relative, {object, mode});
28
+ if (!objects.has(object)) objects.set(object, relative);
29
+ } else throw Error(`Unsupported Base archive entry: ${relative}; supply regular files and directories only`);
30
+ }
31
+ }
32
+ walk();
33
+ const orderedTree = new Map([...tree].sort(([a], [b]) => Buffer.compare(Buffer.from(a), Buffer.from(b))));
34
+ const history = () => { throw Error('Base archive has no Git history. Repeat with --base <checkout> containing the recorded and target commits; no files were refreshed.'); };
35
+ return {
36
+ historyAvailable: false,
37
+ objectId,
38
+ tree(pin) { return pin === revision ? orderedTree : history(); },
39
+ blobs(ids) {
40
+ const result = new Map(), unique = [...new Set(ids)];
41
+ for (let offset = 0; offset < unique.length; offset += 100) {
42
+ let size = 0;
43
+ for (const object of unique.slice(offset, offset + 100)) {
44
+ const name = objects.get(object);
45
+ if (!name) throw Error(`Base archive object ${object} is not available`);
46
+ const data = bytes(name);
47
+ size += data.length;
48
+ if (size > limit) throw Error('Base archive source output exceeds the 64 MiB acquisition limit');
49
+ if (objectId(data) !== object) throw Error(`Base archive changed while reading ${name}; retry with an unchanged archive`);
50
+ result.set(object, data);
51
+ }
52
+ }
53
+ return result;
54
+ },
55
+ digests(ids) { return new Map([...this.blobs(ids)].map(([object, data]) => [object, hash(data)])); },
56
+ contains: history,
57
+ history,
58
+ };
59
+ }
@@ -17,6 +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
21
 
21
22
  export const RECORD = 'base-copies.json';
22
23
  const commit = /^[a-f0-9]{40}$/, sha256 = /^[a-f0-9]{64}$/;
@@ -44,7 +45,11 @@ function declaredRemote(record, root) {
44
45
  }
45
46
 
46
47
  // An explicit checkout, else the record's legacy repository, else the seed's declaration.
47
- 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
+ }
48
53
  if (base) {
49
54
  const repository = fs.realpathSync(base);
50
55
  const source = gitReader(repository, offline);
@@ -67,25 +72,74 @@ function open(record, base, root, offline = false) {
67
72
  }
68
73
 
69
74
  export function options(args, count) {
70
- const result = {positional: [], record: RECORD, base: null, offline: false, editionMigration: []};
75
+ const result = {positional: [], record: RECORD, base: null, baseArchive: null, offline: false, editionMigration: []};
71
76
  for (let i = 0; i < args.length; i++) {
72
77
  const arg = args[i];
73
78
  if (arg === '--offline') result.offline = true;
79
+ else if (arg === '--from-api') result.fromApi = true;
74
80
  else if (arg === '--edition-migration') {
75
81
  if (!args[i + 1] || args[i + 1].startsWith('--')) throw Error(`${arg} requires a value`);
76
82
  result.editionMigration.push(args[++i]);
77
83
  }
78
- else if (arg === '--record' || arg === '--base') {
79
- if (!args[i + 1]) throw Error(`${arg} requires a value`);
80
- 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];
81
89
  } else if (arg.startsWith('--')) throw Error(`Unknown option: ${arg}`);
82
90
  else result.positional.push(arg);
83
91
  }
84
- 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');
85
99
  safe(result.record);
86
100
  return result;
87
101
  }
88
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
+
89
143
  export function validate(record) {
90
144
  const legacy = record?.repository;
91
145
  if (record?.schemaVersion !== 1 || (legacy !== undefined && (typeof legacy !== 'string' || !legacy || legacy.startsWith('-'))) || !Array.isArray(record.copies)) {
@@ -101,6 +155,14 @@ export function validate(record) {
101
155
  safe(name);
102
156
  if (!within(name, copy.path) || !sha256.test(digest)) throw Error(`Invalid recorded copy file: ${name}`);
103
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
+ }
104
166
  if (copy.adapted !== undefined) {
105
167
  if (!copy.adapted || typeof copy.adapted !== 'object' || Array.isArray(copy.adapted)) throw Error(`Invalid adaptations: ${copy.path}`);
106
168
  for (const [name, revision] of Object.entries(copy.adapted)) {
@@ -186,6 +248,7 @@ function containsHistory(origin, source, revision, introduced) {
186
248
  }
187
249
 
188
250
  function reader(origin) {
251
+ if (origin.read) return origin.read;
189
252
  const source = origin.source ?? gitReader(origin.repository);
190
253
  const format = source.git('rev-parse', '--show-object-format');
191
254
  const trees = new Map(), ancestry = new Map();
@@ -253,7 +316,8 @@ function recordFile(root, recordPath) {
253
316
  return filename;
254
317
  }
255
318
 
256
- 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');
257
321
  const filename = recordFile(root, recordPath);
258
322
  if (!filename) throw Error(`No ${recordPath} found; run record-base <path> <origin-path> <commit> first`);
259
323
  const record = validate(JSON.parse(fs.readFileSync(filename, 'utf8')));
@@ -326,16 +390,18 @@ export function verifyCopies(root, {record: recordPath, base, offline}) {
326
390
  };
327
391
  }
328
392
 
329
- 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}) {
330
394
  safe(localPath); safe(originPath);
331
395
  if (!commit.test(revision)) throw Error('Record an immutable full Base commit');
332
396
  const filename = recordFile(root, recordPath) || path.join(root, recordPath);
333
397
  const record = validate(fs.existsSync(filename) ? JSON.parse(fs.readFileSync(filename, 'utf8')) : {schemaVersion: 1, copies: []});
334
398
  const files = seedFiles(root);
335
- const origin = open(record, base, root);
336
- 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);
337
402
  try {
338
- const read = reader(origin);
403
+ const read = fromApi ? apiReader(record, root, revision) : reader(origin);
404
+ delete record.repository;
339
405
  const sources = [...read.tree(revision)].filter(([name]) => within(name, originPath));
340
406
  if (!sources.length) throw Error(`No Base source at ${originPath} in ${revision}`);
341
407
  const present = sources.filter(([name]) => files.get(mapped(name, originPath, localPath))?.regular);
@@ -345,7 +411,8 @@ export function recordCopy(root, {positional: [localPath, originPath, revision],
345
411
  const ordered = present.map(([name, {object, mode}]) => [mapped(name, originPath, localPath), digests.get(object), mode]).sort(([a], [b]) => a.localeCompare(b));
346
412
  const recorded = Object.fromEntries(ordered.map(([name, digest]) => [name, digest]));
347
413
  const modes = Object.fromEntries(ordered.map(([name, , mode]) => [name, mode]));
348
- 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));
349
416
  validate(record);
350
417
  fs.writeFileSync(filename, json(record));
351
418
  return {
@@ -360,7 +427,8 @@ export function recordCopy(root, {positional: [localPath, originPath, revision],
360
427
 
361
428
  // Explicitly transfer one recorded file to seed ownership without changing its bytes
362
429
  // or its Base digest/mode. The per-file revision survives later whole-copy refreshes.
363
- 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');
364
432
  safe(name);
365
433
  const filename = recordFile(root, recordPath);
366
434
  if (!filename) throw Error(`No ${recordPath} found; run record-base first`);
@@ -387,15 +455,15 @@ export function adaptCopy(root, {positional: [name], record: recordPath}) {
387
455
  // entirely, just as absent files are dropped from directory copies. Local edits
388
456
  // are refused, never overwritten, as is any change to an existing file under a
389
457
  // migrations folder.
390
- export function refreshCopies(root, {positional: [revision], record: recordPath, base, offline, editionMigration = []}) {
458
+ export function refreshCopies(root, {positional: [revision], record: recordPath, base, baseArchive, offline, editionMigration = []}) {
391
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>.');
392
- 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>.');
393
461
  const filename = recordFile(root, recordPath);
394
462
  if (!filename) throw Error(`No ${recordPath} found; run record-base <path> <origin-path> <commit> first`);
395
463
  const record = validate(JSON.parse(fs.readFileSync(filename, 'utf8')));
396
464
  const files = seedFiles(root);
397
465
  requireMaterializedCopies(root, record, files);
398
- const origin = open(record, base, root, offline);
466
+ const origin = open(record, base, root, offline, baseArchive, revision);
399
467
  origin.refresh = {revision, recordPath, editionMigration};
400
468
  let writing = false, notices = [];
401
469
  try {
@@ -437,8 +505,14 @@ export function refreshCopies(root, {positional: [revision], record: recordPath,
437
505
  // removals, and a still-present singleton must retain a Base source.
438
506
  const retired = Object.keys(copy.files).length === 1 && Object.hasOwn(copy.files, copy.path) &&
439
507
  !files.has(copy.path) && !fs.existsSync(path.join(root, copy.path)) && !Object.hasOwn(copy.adapted || {}, copy.path);
440
- const pinned = read.tree(copy.revision);
441
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);
442
516
  const tests = Object.keys(copy.files).some(name => testSource(mapped(name, copy.path, copy.originPath)));
443
517
  const sources = [...next].filter(([name]) => {
444
518
  if (!within(name, copy.originPath)) return false;
@@ -495,7 +569,7 @@ export function refreshCopies(root, {positional: [revision], record: recordPath,
495
569
  recorded[name] = upstream.get(object); modes[name] = mode;
496
570
  }
497
571
  changes.push({path: copy.path, from: copy.revision, files: sources.length, added, removed});
498
- 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()});
499
573
  }
500
574
  record.copies = plans.filter(plan => !plan.retired).map(plan => plan.copy);
501
575
  delete record.repository;