@runeditrun/rer 0.2.94 → 0.2.96

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 (71) hide show
  1. package/README.md +16 -2
  2. package/cli/README.md +5 -1
  3. package/cli/agent-door.mjs +4 -0
  4. package/cli/agent-journey-fixtures.mjs +1 -1
  5. package/cli/authoring.mjs +1 -1
  6. package/cli/business/carry-files.mjs +142 -0
  7. package/cli/business/carry.mjs +37 -83
  8. package/cli/business/choices.mjs +17 -8
  9. package/cli/business/connect.mjs +6 -5
  10. package/cli/business/invocation.mjs +3 -2
  11. package/cli/business/local-commands.mjs +6 -6
  12. package/cli/business/questions.mjs +4 -1
  13. package/cli/business/state.mjs +4 -1
  14. package/cli/checkout-folders.mjs +14 -0
  15. package/cli/checkout-preparation.mjs +83 -0
  16. package/cli/contract.mjs +1 -1
  17. package/cli/door-clauses.mjs +29 -2
  18. package/cli/hosted-output.mjs +14 -3
  19. package/cli/hosted-queue-producers.mjs +43 -0
  20. package/cli/jsonc.mjs +1 -115
  21. package/cli/parse.mjs +1 -1
  22. package/cli/portability-migrations.mjs +2 -12
  23. package/edition-authoring/archive-source.mjs +86 -1
  24. package/edition-authoring/base-copies.mjs +15 -45
  25. package/edition-authoring/cli.mjs +1 -1
  26. package/edition-authoring/edition-migrations.mjs +2 -2
  27. package/edition-authoring/module-closure.mjs +119 -50
  28. package/edition-authoring/module-packages.mjs +12 -5
  29. package/edition-authoring/module-syntax.mjs +13 -50
  30. package/edition-authoring/runtime-dependencies.mjs +4 -4
  31. package/foundation/runtime/contract-docs.mjs +1 -1
  32. package/global/CHANGELOG.md +70 -0
  33. package/global/README.md +16 -2
  34. package/global/cli/layout.mjs +3 -0
  35. package/global/launch/facts.mjs +1 -29
  36. package/global/launch/state.mjs +3 -6
  37. package/global/list.mjs +9 -15
  38. package/modules/agent-door/CLAUSES.md +12 -0
  39. package/modules/agent-door/conformance/audit.mjs +22 -4
  40. package/modules/agent-door/conformance/discovery.mjs +32 -1
  41. package/modules/agent-door/conformance/erasure.mjs +103 -0
  42. package/modules/agent-door/conformance/index.mjs +13 -4
  43. package/modules/agent-door/conformance/journey.mjs +19 -1
  44. package/modules/agent-door/conformance/policy-phases.mjs +34 -1
  45. package/modules/agent-door/conformance/protocol.mjs +13 -3
  46. package/modules/agent-door/conformance/relay.mjs +63 -0
  47. package/modules/agent-door/conformance/unpair.mjs +47 -0
  48. package/modules/deploy-kit/jsonc.mjs +115 -0
  49. package/modules/deploy-kit/migration-directory.mjs +16 -0
  50. package/modules/deploy-kit/prepare.mjs +1 -1
  51. package/modules/deploy-kit/templates.mjs +9 -4
  52. package/modules/erasure/cascade.mjs +4 -4
  53. package/modules/erasure/index.d.mts +1 -1
  54. package/modules/erasure/index.mjs +1 -1
  55. package/modules/import-kit/src/d1/README.md +16 -1
  56. package/modules/import-kit/src/d1/preserved-reverse.ts +5 -2
  57. package/modules/import-kit/src/d1/read-fence.ts +14 -2
  58. package/modules/import-kit/src/d1/reverse.ts +4 -1
  59. package/modules/import-kit/src/d1/sets.ts +8 -0
  60. package/modules/import-kit/src/d1/snapshot-text.ts +68 -0
  61. package/modules/import-kit/src/d1/undo-report.ts +4 -1
  62. package/modules/import-kit/src/door/ADOPTING.md +9 -4
  63. package/modules/portability/README.md +28 -2
  64. package/modules/portability/bookkeeping.mjs +8 -4
  65. package/modules/portability/checkout-history.mjs +12 -6
  66. package/modules/portability/import.mjs +1 -1
  67. package/modules/portability/storage.mjs +7 -1
  68. package/modules/portability/worker-history.d.mts +1 -1
  69. package/modules/portability/worker-history.mjs +1 -1
  70. package/onboarding/operator-migrations.mjs +5 -1
  71. package/package.json +1 -1
@@ -0,0 +1,83 @@
1
+ // Read-only setup facts shared by the launcher, list and portable Business carry.
2
+ // Vendored commands cannot import global/launch, so these rules live with the CLI.
3
+ import { createHash } from 'node:crypto';
4
+ import { execFile } from 'node:child_process';
5
+ import { readFile, stat } from 'node:fs/promises';
6
+ import { basename, join } from 'node:path';
7
+ import { fileURLToPath } from 'node:url';
8
+ import { promisify } from 'node:util';
9
+ import { serversDirectory } from './server-registry.mjs';
10
+ import { exactVersion } from './package-mode.mjs';
11
+ import { shared } from './shared.mjs';
12
+
13
+ async function readJson(path) {
14
+ try { return JSON.parse(await readFile(path, 'utf8')); }
15
+ catch (error) { if (error.code === 'ENOENT' || error instanceof SyntaxError) return undefined; throw error; }
16
+ }
17
+ async function mtime(path) { try { return (await stat(path)).mtimeMs; } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; } }
18
+
19
+ export function launchPath(checkout, env = process.env) {
20
+ const name = basename(checkout).toLowerCase().replace(/[^a-z0-9-]+/g, '-').slice(0, 40) || 'checkout';
21
+ return join(serversDirectory(env), 'launches', `${name}-${createHash('sha256').update(checkout).digest('hex').slice(0, 12)}`);
22
+ }
23
+
24
+ // A checkout is set up when its pin's describe says so (`local.prepared`, from
25
+ // rer-cli-2); for older pins, when its primary private settings file holds
26
+ // anything. The pin's describe names it (`local.settings`, where the pin has it).
27
+ export async function hasSettings(root, described) {
28
+ if (typeof described?.local?.prepared === 'boolean') return described.local.prepared;
29
+ const primary = described?.local?.settings?.[0] ?? '.dev.vars';
30
+ try { return (await stat(join(root, primary))).size > 0; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
31
+ }
32
+
33
+ // Every pin's setup saves its answers file only once it has finished, so a
34
+ // file newer than this launcher's record of its own attempt (its start for
35
+ // 'running', its end for 'failed') is a setup that finished after it.
36
+ async function finishedSince(root, described, at) {
37
+ const saved = await mtime(join(root, described?.local?.installerState ?? '.seed/installer', 'setup-answers.json'));
38
+ return saved !== undefined && typeof at === 'number' && saved > at;
39
+ }
40
+
41
+ // Setup runs on a checkout with no saved settings ('fresh'). When a setup this
42
+ // launcher started did not finish ('running' after a kill, or 'failed') and no
43
+ // setup has finished since, it runs again ('resume') and keeps what the earlier
44
+ // attempt saved. A checkout set up any other way is never set up again.
45
+ // A checkout that is not prepared but already holds an owner (a setting a newer
46
+ // manifest added is missing) resumes too, so the saved owner and origin are
47
+ // kept; one without a saved owner gets the local owner ('fresh').
48
+ export async function setupNeeded(root, described, last) {
49
+ if (!await hasSettings(root, described)) return described?.local?.ownerSaved === true ? 'resume' : 'fresh';
50
+ if (!last || last.state === 'done') return undefined;
51
+ return await finishedSince(root, described, last.at) ? undefined : 'resume';
52
+ }
53
+
54
+ const bundledEntry = fileURLToPath(new URL('../bin/rer.mjs', import.meta.url));
55
+ async function pinnedEntry(checkout) {
56
+ const manifest = await readJson(join(checkout, 'package.json')).catch(() => null);
57
+ const declared = manifest?.devDependencies?.['@runeditrun/rer'] ?? manifest?.dependencies?.['@runeditrun/rer'];
58
+ const installed = declared && (await readJson(join(checkout, 'node_modules/@runeditrun/rer/package.json')).catch(() => null))?.version;
59
+ if (declared && !(installed && (installed === declared || !exactVersion.test(declared)))) return null;
60
+ if (declared) return join(checkout, 'node_modules/@runeditrun/rer/bin/rer.mjs');
61
+ const vendored = join(checkout, 'scripts/rer.mjs');
62
+ return await stat(vendored).then(info => info.isFile()).catch(() => false) ? vendored : bundledEntry;
63
+ }
64
+
65
+ export async function checkoutPreparation(checkout, env = process.env) {
66
+ let describing = true;
67
+ try {
68
+ const entry = await pinnedEntry(checkout);
69
+ if (!entry) return { prepared: false, reason: 'the pinned rer package is not installed: run rer install' };
70
+ const { stdout } = await promisify(execFile)(process.execPath, [entry, 'describe', '--json'], { cwd: checkout, env, maxBuffer: 16 * 1024 * 1024, timeout: 30000 });
71
+ const described = JSON.parse(stdout);
72
+ describing = false;
73
+ const last = await readJson(join(launchPath(checkout, env), 'setup.json'));
74
+ const needed = await setupNeeded(checkout, described, last);
75
+ return { prepared: !needed, ...(needed ? { reason: 'the checkout is not set up yet: run rer setup' } : {}) };
76
+ } catch (error) {
77
+ const { createRedaction, credentialValues } = await shared('redaction.mjs');
78
+ const redaction = createRedaction();
79
+ redaction.addSecrets(credentialValues(env));
80
+ const cause = error.stderr?.trim() || (describing ? `rer describe failed in ${checkout}.` : error.message);
81
+ return { prepared: null, reason: `rer describe fails here: ${redaction.redact(cause.split('\n')[0])}` };
82
+ }
83
+ }
package/cli/contract.mjs CHANGED
@@ -29,7 +29,7 @@ export const signinVerb = Object.freeze({ bootstrap: 'before', flags: [...common
29
29
  // Their project-package bootstrap uses the same contract as every checkout verb.
30
30
  export const authoringVerbs = Object.freeze({
31
31
  'adopt-edition': {bootstrap: 'before', flags: [...commonFlags], effects: 'Add edition.json and sources.lock.json for the existing tracked local source, preserving declared project identity and existing copy/composition records. Create an empty base-copies.json only when none exists. Review and stage the new authoring inputs; no source regeneration, install setup or commit.'},
32
- 'refresh-base': {bootstrap: 'before', flags: [...commonFlags, '--ref', '--base', '--base-archive', '--record', '--offline', '--edition-migration'], effects: 'Consent to each declared edition edit with repeatable --edition-migration ID; refresh leaves the edit owed. Refresh recorded Base copies to --ref FULL_COMMIT, preserving acknowledged adaptations and applied migrations; announce removed singleton retirement. Deliver invoked workflow helpers atomically; adopt tracked known historical Verify templates and preserve divergent workflows with adoption notices. Acquire committed source from the declared Base repository (default https://github.com/runeditrun/base.git), or use --base CHECKOUT or --base-archive DIRECTORY with --ref FULL_COMMIT for an exported source tree. --offline requires --base and never acquires remote source. Refuse incomplete Git checkouts without changing their records. Review the diff and run edition tests before committing.'},
32
+ 'refresh-base': {bootstrap: 'before', flags: [...commonFlags, '--ref', '--base', '--base-archive', '--from-api', '--record', '--offline', '--edition-migration'], effects: 'Consent to each declared edition edit with repeatable --edition-migration ID; refresh leaves the edit owed. Refresh recorded Base copies to --ref FULL_COMMIT, preserving acknowledged adaptations and applied migrations; announce removed singleton retirement. Deliver invoked workflow helpers atomically; adopt tracked known historical Verify templates and preserve divergent workflows with adoption notices. Acquire committed source from the declared Base repository (default https://github.com/runeditrun/base.git), or read immutable trees, blobs and ancestry through authenticated gh with --from-api, or use --base CHECKOUT or --base-archive DIRECTORY with --ref FULL_COMMIT for an exported source tree. --offline requires --base or --base-archive and never acquires remote source. Refuse incomplete Git checkouts without changing their records. Review the diff and run edition tests before committing.'},
33
33
  });
34
34
  export const aliases = Object.fromEntries([...Object.keys(verbs).filter(v => v !== 'install'), 'release', 'deps', 'rer'].map(name => [name, name === 'deps' ? 'install' : name === 'rer' ? null : name]));
35
35
  export const releaseFlags = ['--repo', '--project', '--repository', '--output', '--ref', '--public-base', '--dry-run', '--local-verify', '--verify-workflow', '--scan-timeout-seconds', '--tag', '--clean-history', '--onto', '--env-file', '--allow-placeholder-mark', '--no-queue'];
@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
2
2
  import { spawnSync } from 'node:child_process';
3
3
  import { existsSync, readFileSync, writeFileSync } from 'node:fs';
4
4
  import { resolve, relative, isAbsolute } from 'node:path';
5
- import { parseContract } from '../foundation/runtime/seed-contract.mjs';
5
+ import { parseContract, plainText } from '../foundation/runtime/seed-contract.mjs';
6
6
  import { RerError } from './errors.mjs';
7
7
 
8
8
  export const clausesHelp = `Usage: rer door clauses (--write | --check) [--cwd DIR]
@@ -10,6 +10,7 @@ export const clausesHelp = `Usage: rer door clauses (--write | --check) [--cwd D
10
10
  Synchronize BASE-AGENT-001 through BASE-AGENT-013 in CONTRACT.md.
11
11
  --write adds or updates Base's requirements, preserving existing status,
12
12
  evidence and gaps, then runs the seed's contract-docs write and check.
13
+ It requires a Shared duties (Base) table and skips duties listed there.
13
14
  --check is read-only and names missing or stale clauses (exit 1).
14
15
  Seed-owned clauses and the judged revision stay unchanged. Newly added clauses
15
16
  start missing. Regenerate the seed's source lock last, before committing.
@@ -64,6 +65,30 @@ function headings(lines) {
64
65
  });
65
66
  }
66
67
 
68
+ function sharedDuties(original, required) {
69
+ const lines = original.split(/\r?\n/), outline = headings(lines);
70
+ const cells = line => line?.trim().replace(/^\|/, '').replace(/(?<!\\)\|$/, '').split(/(?<!\\)\|/).map(cell => cell.trim());
71
+ const section = outline.find(item => item.level === 2 && item.title.trim() === 'Shared duties (Base)');
72
+ const end = section && (outline.find(item => item.index > section.index && item.level <= 2)?.index ?? lines.length);
73
+ let fence;
74
+ for (let i = (section?.index ?? lines.length) + 1; i < end; i++) {
75
+ const mark = /^\s*(`{3,}|~{3,})/.exec(lines[i])?.[1];
76
+ if (mark) { if (!fence) fence = mark[0]; else if (fence === mark[0]) fence = undefined; continue; }
77
+ if (fence) continue;
78
+ if (!lines[i].trimStart().startsWith('|')) continue;
79
+ const header = cells(lines[i]), divider = cells(lines[i + 1]);
80
+ if (plainText(header[0]) !== 'Base duty' || divider?.length !== header.length || !divider.every(cell => /^:?-{3,}:?$/.test(cell))) continue;
81
+ const duties = new Set();
82
+ for (let row = i + 2; row < end && lines[row].trimStart().startsWith('|'); row++) {
83
+ const id = plainText(cells(lines[row])[0]);
84
+ if (/^BASE-AGENT-\d{3}$/.test(id)) duties.add(id);
85
+ }
86
+ return duties;
87
+ }
88
+ if (!required) return new Set();
89
+ fail('CONTRACT.md needs a Shared duties (Base) table with a Base duty column before --write. Add the table, then retry; no files were written.');
90
+ }
91
+
67
92
  // contract-docs owns summary generation. Suppress only its three derived rows
68
93
  // for structural validation while a contract is awaiting regeneration.
69
94
  function withoutSummary(text) {
@@ -139,7 +164,9 @@ export async function doorClausesCommand(args, env = process.env) {
139
164
  root = resolve(root);
140
165
  const file = resolve(root, 'CONTRACT.md');
141
166
  if (!existsSync(file)) fail('No CONTRACT.md found. Run rer door clauses from the seed root or pass --cwd DIR.');
142
- const original = read(file), { text, changed } = synchronize(original, definitions(canonical(root)));
167
+ const original = read(file);
168
+ const inherited = sharedDuties(original, mode === '--write');
169
+ const { text, changed } = synchronize(original, definitions(canonical(root)).filter(clause => !inherited.has(clause.id)));
143
170
  if (changed.length) console.log(`Agent clauses: ${changed.join(', ')}.`);
144
171
  if (mode === '--check' && changed.length) return 1;
145
172
  const commands = generator(root);
@@ -15,6 +15,7 @@ import { shared } from './shared.mjs';
15
15
  import { registerHistoryInstallation, preparationDatabase } from './agent-history-database.mjs';
16
16
  import { verificationRpc } from './agent-rpc.mjs';
17
17
  import { hostedOrigins } from './hosted-hosts.mjs';
18
+ import { preparationProducers } from './hosted-queue-producers.mjs';
18
19
  import { FixtureDatabaseError } from '../modules/agent-door/conformance/fixtures.mjs';
19
20
 
20
21
  // Serve the production build the way rer deploy hosts it (assets behind the
@@ -126,7 +127,7 @@ export async function serveHosted(root, { declaration: declarationPath = 'deploy
126
127
  durableObjects: Object.fromEntries((config.durable_objects?.bindings ?? []).filter(item => !item.script_name).map(item => [item.name, { className: item.class_name, useSQLite: true }])),
127
128
  ...(config.assets ? { assets: { directory: client, binding: config.assets.binding ?? 'ASSETS', routerConfig: { has_user_worker: true, invoke_user_worker_ahead_of_assets: RUN_WORKER_FIRST } } } : {}),
128
129
  }] };
129
- let preparation, held = false;
130
+ let preparation, producers, held = false;
130
131
  const waiting = new Set();
131
132
  const release = () => { held = false; for (const resume of waiting) resume(); waiting.clear(); };
132
133
  // Install the gate before owner hooks retain any D1 handles; replacing
@@ -141,6 +142,7 @@ export async function serveHosted(root, { declaration: declarationPath = 'deploy
141
142
  if (held) await new Promise(resume => waiting.add(resume));
142
143
  return new Response(null, { status: 204 });
143
144
  } };
145
+ producers = preparationProducers(options, config);
144
146
  }
145
147
  const mf = new Miniflare(convertV4MiniflareOptions(options));
146
148
  let loopback;
@@ -179,7 +181,7 @@ export async function serveHosted(root, { declaration: declarationPath = 'deploy
179
181
  }
180
182
  catch { throw new Error('Native scheduled preparation failed; fixture values are not logged.'); }
181
183
  },
182
- queues: Object.freeze({ hold: () => { held = true; }, release }),
184
+ queues: Object.freeze({ hold: () => { held = true; }, release, ...producers(mf) }),
183
185
  });
184
186
  })(),
185
187
  database: async binding => {
@@ -189,7 +191,16 @@ export async function serveHosted(root, { declaration: declarationPath = 'deploy
189
191
  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);
190
192
  return db.prepare(sql);
191
193
  } };
192
- }, close: () => { release(); return mf.dispose(); },
194
+ },
195
+ // The same installation again without the named bindings: its Worker restarts, its storage and other bindings stay.
196
+ // Handles taken before it (preparation, history) end; take any later ones from the hosted object again.
197
+ rebind: async names => {
198
+ const app = options.workers.find(worker => worker.name === 'app');
199
+ for (const name of names) delete app.bindings[name];
200
+ await mf.setOptions(convertV4MiniflareOptions(options));
201
+ loopback = await mf.ready;
202
+ },
203
+ close: () => { release(); return mf.dispose(); },
193
204
  fetch: (path, { headers, origin = HOSTED_ORIGIN, ...init } = {}) => {
194
205
  if (!origins.includes(origin)) throw new RerError('agent_door_origin', 'Agent conformance request must use a declared hosted installation origin.', 1);
195
206
  return loopbackFetch(loopback, { ...init, redirect: 'manual', headers: { ...headers, 'x-rer-original-url': `${origin}/${path}` } });
@@ -0,0 +1,43 @@
1
+ import { RerError } from './errors.mjs';
2
+
3
+ // Only disposable conformance hosts install these RPC producers. The native
4
+ // queue lives behind the fault check, so a rejected send cannot enqueue work.
5
+ const producer = `import { WorkerEntrypoint } from 'cloudflare:workers';
6
+ let failed = false;
7
+ // The default control entrypoint is available only to the host. Application
8
+ // bindings use Producer, which exposes only the queue operations below.
9
+ export default { fetch(request) { failed = new URL(request.url).pathname === '/fail'; return new Response(null, { status: 204 }); } };
10
+ export class Producer extends WorkerEntrypoint {
11
+ async send(body, options) { if (failed) throw new Error('Conformance queue producer failure.'); return this.env.QUEUE.send(body, options); }
12
+ async sendBatch(messages, options) { if (failed) throw new Error('Conformance queue producer failure.'); return this.env.QUEUE.sendBatch(messages, options); }
13
+ }`;
14
+
15
+ export function preparationProducers(options, config) {
16
+ const app = options.workers.find(worker => worker.name === 'app');
17
+ const declared = new Map();
18
+ const validate = binding => {
19
+ if (!declared.has(binding)) throw new RerError('hosted_queue_invalid', 'Queue preparation requires a declared producer binding.', 1);
20
+ };
21
+ for (const [index, item] of (config.queues?.producers ?? []).entries()) {
22
+ const name = `rer-conformance-queue-${index}`;
23
+ declared.set(item.binding, name);
24
+ options.workers.push({ name, modules: true, script: producer, compatibilityDate: config.compatibility_date,
25
+ queueProducers: { QUEUE: item.queue },
26
+ });
27
+ app.serviceBindings[item.binding] = { name, entrypoint: 'Producer' };
28
+ }
29
+ app.queueProducers = {};
30
+ return mf => {
31
+ const control = async (binding, action) => {
32
+ const response = await (await mf.getWorker(declared.get(binding))).fetch('https://queue.invalid/' + action, { method: 'POST' });
33
+ if (!response.ok) throw new RerError('hosted_queue_invalid', 'Disposable queue producer control failed.', 1);
34
+ };
35
+ return Object.freeze({
36
+ fail: binding => { validate(binding); return control(binding, 'fail'); },
37
+ restore: binding => {
38
+ if (binding === undefined) return Promise.all([...declared.keys()].map(name => control(name, 'restore')));
39
+ validate(binding); return control(binding, 'restore');
40
+ },
41
+ });
42
+ };
43
+ }
package/cli/jsonc.mjs CHANGED
@@ -1,115 +1 @@
1
- function location(text, position) {
2
- const lines = text.slice(0, position).split('\n');
3
- return `position ${position} (line ${lines.length} column ${lines.at(-1).length + 1})`;
4
- }
5
-
6
- // Validate JSONC before JSON.parse so diagnostics do not depend on the Node
7
- // version's error wording. An explicit stack also handles deeply nested input.
8
- // Only comments and commas accepted by the grammar are masked; offsets stay in
9
- // the original source and comment removal can never join separate tokens.
10
- export function parseJsonc(text, onProperty) {
11
- const result = text.split(''), stack = [{ kind: 'root', state: 'value', path: [] }];
12
- let index = 0;
13
- const fail = (message, position = index) => {
14
- throw new SyntaxError(`${position === text.length ? 'Unexpected end of JSON input' : message} at ${location(text, position)}`);
15
- };
16
- const unterminated = (kind, start) => {
17
- throw new SyntaxError(`Unterminated ${kind} at ${location(text, start)}; close the ${kind}.`);
18
- };
19
- const blank = start => {
20
- for (let i = start; i < index; i++) if (text[i] !== '\n' && text[i] !== '\r') result[i] = ' ';
21
- };
22
- const space = () => {
23
- while (index < text.length) {
24
- if (' \t\r\n'.includes(text[index])) { index++; continue; }
25
- const start = index;
26
- if (text[index] === '/' && text[index + 1] === '/') {
27
- index += 2;
28
- while (index < text.length && text[index] !== '\n' && text[index] !== '\r') index++;
29
- } else if (text[index] === '/' && text[index + 1] === '*') {
30
- const end = text.indexOf('*/', index + 2);
31
- if (end === -1) unterminated('block comment', start);
32
- index = end + 2;
33
- } else break;
34
- blank(start);
35
- }
36
- };
37
- const string = () => {
38
- const start = index++;
39
- let end = index;
40
- while (end < text.length && text[end] !== '"') end = Math.min(text.length, end + (text[end] === '\\' ? 2 : 1));
41
- if (end === text.length) unterminated('string', start);
42
- while (index < end) {
43
- if (text.charCodeAt(index) < 32) fail('Unescaped control character in string');
44
- if (text[index++] !== '\\') continue;
45
- if (text[index] === 'u') {
46
- index++;
47
- for (let digit = 0; digit < 4; digit++, index++) {
48
- if (index >= end || !/[0-9a-fA-F]/.test(text[index])) fail('Invalid Unicode escape');
49
- }
50
- } else {
51
- if (!'"\\/bfnrt'.includes(text[index])) fail('Invalid string escape');
52
- index++;
53
- }
54
- }
55
- index++;
56
- };
57
- const digit = () => index < text.length && text[index] >= '0' && text[index] <= '9';
58
- const digits = () => {
59
- if (!digit()) fail('Expected a digit');
60
- do { index++; } while (digit());
61
- };
62
- const number = () => {
63
- if (text[index] === '-') index++;
64
- if (text[index] === '0') index++;
65
- else digits();
66
- if (text[index] === '.') { index++; digits(); }
67
- if (text[index] === 'e' || text[index] === 'E') {
68
- index++;
69
- if (text[index] === '+' || text[index] === '-') index++;
70
- digits();
71
- }
72
- };
73
- while (stack.length) {
74
- space();
75
- const frame = stack.at(-1), char = text[index], closing = frame.kind === 'object' ? '}' : ']';
76
- if (frame.state === 'end') {
77
- if (index < text.length) fail('Unexpected token after JSON value');
78
- stack.pop();
79
- } else if ((frame.state === 'keyOrEnd' || frame.state === 'valueOrEnd' || frame.state === 'comma') && char === closing) {
80
- index++; stack.pop();
81
- } else if (frame.state === 'keyOrEnd') {
82
- if (char !== '"') fail('Expected a property name');
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';
87
- } else if (frame.state === 'colon') {
88
- if (char !== ':') fail("Expected ':' after property name");
89
- index++; frame.state = 'value';
90
- } else if (frame.state === 'comma') {
91
- if (char !== ',') fail(`Expected ',' or '${closing}'`);
92
- const comma = index++;
93
- space();
94
- if (text[index] === closing) result[comma] = ' ';
95
- frame.state = frame.kind === 'object' ? 'keyOrEnd' : 'valueOrEnd';
96
- } else {
97
- const path = !onProperty ? undefined : frame.kind === 'root' ? [] : [...frame.path, frame.kind === 'array' ? frame.next++ : frame.key];
98
- frame.state = frame.kind === 'root' ? 'end' : 'comma';
99
- if (char === '{' || char === '[') {
100
- index++;
101
- stack.push({ kind: char === '{' ? 'object' : 'array', state: char === '{' ? 'keyOrEnd' : 'valueOrEnd', path, next: 0 });
102
- } else if (char === '"') string();
103
- else if (char === '-' || digit()) number();
104
- else {
105
- const literal = { t: 'true', f: 'false', n: 'null' }[char];
106
- if (!literal) fail('Unexpected token in JSON value');
107
- for (const expected of literal) {
108
- if (text[index] !== expected) fail(`Expected '${literal}'`);
109
- index++;
110
- }
111
- }
112
- }
113
- }
114
- return JSON.parse(result.join(''));
115
- }
1
+ export {parseJsonc} from '../modules/deploy-kit/jsonc.mjs';
package/cli/parse.mjs CHANGED
@@ -3,7 +3,7 @@ import { authoringVerbs, commonFlags, serverDefaults, signinVerb, verbs } from '
3
3
  import { invalid, refuse } from './errors.mjs';
4
4
  import { isLoopbackHost } from '../modules/operator-auth/loopback.mjs';
5
5
  import { normalizeEmail } from '../modules/operator-auth/policy.mjs';
6
- const booleans = new Set(['--help', '--json', '--non-interactive', '--yes', '--dry-run', '--stop', '--detach', '--foreground', '--no-queue', '--login', '--legacy-v1', '--acknowledge-unverified-metadata', '--acknowledge-unverified-schema-objects', '--door', '--direct', '--site', '--remove', '--demo', '--offline']);
6
+ const booleans = new Set(['--help', '--json', '--non-interactive', '--yes', '--dry-run', '--stop', '--detach', '--foreground', '--no-queue', '--login', '--legacy-v1', '--acknowledge-unverified-metadata', '--acknowledge-unverified-schema-objects', '--door', '--direct', '--site', '--remove', '--demo', '--offline', '--from-api']);
7
7
  export const mailbox = value => typeof value === 'string' && value.length <= 254 && /^[a-zA-Z0-9.!+_%\-]+@[a-zA-Z0-9\-]+(?:\.[a-zA-Z0-9\-]+)+$/.test(value);
8
8
  export const validOwnerName = value => typeof value === 'string' && Boolean(value.trim()) && value.length <= 200 && !/[\p{Cc}\p{Cf}]/u.test(value);
9
9
  // A loopback host: the shared predicate (including `*.localhost` door names),
@@ -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);