@runeditrun/rer 0.2.98 → 0.2.100

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 (78) hide show
  1. package/README.md +1 -1
  2. package/cli/README.md +88 -2
  3. package/cli/business/api.mjs +4 -2
  4. package/cli/business/bounded-waves.d.mts +23 -0
  5. package/cli/business/bounded-waves.mjs +57 -0
  6. package/cli/business/catchup-task.mjs +9 -2
  7. package/cli/business/command.mjs +16 -4
  8. package/cli/business/connect.mjs +39 -33
  9. package/cli/business/export-inputs.mjs +12 -2
  10. package/cli/business/export-task.mjs +9 -2
  11. package/cli/business/legacy-package.mjs +117 -0
  12. package/cli/business/local-commands.mjs +10 -1
  13. package/cli/business/package-transfer.mjs +127 -0
  14. package/cli/business/questions.mjs +2 -2
  15. package/cli/business/state.mjs +47 -5
  16. package/cli/business/supervisor.mjs +46 -7
  17. package/cli/business/vendor-door.mjs +86 -13
  18. package/cli/business/vendors/README.md +41 -2
  19. package/cli/business/vendors/common.mjs +81 -0
  20. package/cli/business/vendors/index.mjs +12 -2
  21. package/cli/business/vendors/zendesk-attachments.mjs +57 -0
  22. package/cli/business/vendors/zendesk-encode.mjs +133 -0
  23. package/cli/business/vendors/zendesk-guide.mjs +34 -0
  24. package/cli/business/vendors/zendesk-package.mjs +28 -0
  25. package/cli/business/vendors/zendesk-pages.mjs +61 -0
  26. package/cli/business/vendors/zendesk-people.mjs +7 -0
  27. package/cli/business/vendors/zendesk-store.mjs +154 -0
  28. package/cli/business/vendors/zendesk-tickets.mjs +21 -0
  29. package/cli/business/vendors/zendesk-token.mjs +31 -0
  30. package/cli/business/vendors/zendesk-transport.mjs +48 -0
  31. package/cli/business/vendors/zendesk.mjs +61 -0
  32. package/cli/deploy-command.mjs +5 -4
  33. package/cli/deploy-inputs.mjs +1 -1
  34. package/cli/deploy.mjs +6 -4
  35. package/cli/production-auth.mjs +16 -3
  36. package/cli/production-mail.mjs +18 -1
  37. package/cli/site.mjs +1 -1
  38. package/global/CHANGELOG.md +42 -0
  39. package/global/README.md +1 -1
  40. package/modules/deploy-kit/README.md +10 -0
  41. package/modules/deploy-kit/provider.mjs +18 -2
  42. package/modules/import-kit/src/d1/jobs.ts +3 -1
  43. package/modules/import-kit/src/d1/retirement-scope.ts +2 -2
  44. package/modules/import-kit/src/d1/retirement-tally.ts +1 -0
  45. package/modules/import-kit/src/d1/retirement.ts +15 -5
  46. package/modules/import-kit/src/d1/types.ts +3 -0
  47. package/modules/import-kit/src/d1/wave-boundary.ts +33 -0
  48. package/modules/import-kit/src/d1/wave-retirement.ts +47 -0
  49. package/modules/import-kit/src/door/ADOPTING.md +37 -0
  50. package/modules/import-kit/src/door/README.md +66 -0
  51. package/modules/import-kit/src/door/admission.ts +13 -3
  52. package/modules/import-kit/src/door/authority.ts +1 -0
  53. package/modules/import-kit/src/door/failures.ts +1 -1
  54. package/modules/import-kit/src/door/grants.ts +19 -5
  55. package/modules/import-kit/src/door/handler.ts +12 -1
  56. package/modules/import-kit/src/door/index.ts +6 -0
  57. package/modules/import-kit/src/door/package.ts +121 -0
  58. package/modules/import-kit/src/door/planning.ts +44 -19
  59. package/modules/import-kit/src/door/protocol.ts +4 -2
  60. package/modules/import-kit/src/door/schema.ts +2 -0
  61. package/modules/import-kit/src/door/store.ts +2 -2
  62. package/modules/import-kit/src/door/types.ts +24 -1
  63. package/modules/import-kit/src/door/waves/README.md +158 -0
  64. package/modules/import-kit/src/door/waves/digests.ts +38 -0
  65. package/modules/import-kit/src/door/waves/inventory.ts +84 -0
  66. package/modules/import-kit/src/door/waves/journal.ts +19 -0
  67. package/modules/import-kit/src/door/waves/lifecycle.ts +242 -0
  68. package/modules/import-kit/src/door/waves/preparation.ts +190 -0
  69. package/modules/import-kit/src/door/waves/schema.ts +73 -0
  70. package/modules/import-kit/src/door/waves/store.ts +112 -0
  71. package/modules/import-kit/src/door/waves/types.ts +76 -0
  72. package/onboarding/adapter.mjs +7 -1
  73. package/onboarding/operator-installer.mjs +3 -1
  74. package/package.json +1 -1
  75. package/scripts/publish-check/README.md +20 -0
  76. package/scripts/publish-check/diagnostics.mjs +73 -0
  77. package/scripts/publish-check/slots.py +37 -7
  78. package/scripts/publish-check.mjs +64 -37
@@ -1,3 +1,4 @@
1
+ export { legacyPackage } from './legacy-package.mjs';
1
2
  import { writeFile, unlink } from 'node:fs/promises';
2
3
  import { join } from 'node:path';
3
4
  import { loadState, loadPending, saveState, stateDirectory, removeStateDirectory, removeWorkFiles, deviceCredentialHandle, liveSupervisor } from './state.mjs';
@@ -11,6 +12,7 @@ import { KEYED_VENDORS } from './vendors/index.mjs';
11
12
  import { vendorHandle } from './vendor-door.mjs';
12
13
  import { rerCommand, businessCommand } from './invocation.mjs';
13
14
  import { describe } from './errors.mjs';
15
+ import { clientCredential, removeZendeskStores } from './vendors/zendesk.mjs';
14
16
  import { supportsTaskKind } from './supervisor.mjs';
15
17
 
16
18
  export async function paired() {
@@ -44,6 +46,7 @@ export async function forgetLocally(state, { stopRun = true } = {}) {
44
46
  for (const handle of store ? state.vendorHandles ?? [] : []) if (await attempt('vendorKeys', () => store.delete(handle))) vendorKeys.push(handle);
45
47
  const refused = store ? await attempt('credential', () => store.delete(deviceCredentialHandle(state))) : undefined;
46
48
  await removeCarries();
49
+ await removeZendeskStores(directory);
47
50
  if (!leftovers.length) { await removeStateDirectory(); return []; }
48
51
  const unique = [...new Set(leftovers)];
49
52
  const cause = refused && (refused.sandboxRefused ? `macOS Keychain refused to remove it inside this agent sandbox (security exited with status ${refused.osStatus ?? 'unknown'}).` : describe(refused));
@@ -65,6 +68,7 @@ export async function revokedByServer(state) {
65
68
  if (await permissionsAdded()) leftovers.push('permissions');
66
69
  const saved = { ...state, revoked: { at: new Date().toISOString(), leftovers, ...(cause ? { cause } : {}) } };
67
70
  await saveState(saved);
71
+ await removeZendeskStores(stateDirectory());
68
72
  await removeWorkFiles(['state.json', 'permissions.json', 'service.json', 'run.lock', 'carried.json']);
69
73
  return saved;
70
74
  }
@@ -74,10 +78,15 @@ export async function vendorKey(action, vendor) {
74
78
  const { state } = await paired(), store = createCredentialStore(), handle = vendorHandle(vendor);
75
79
  if (action === 'add') {
76
80
  let secret = await readSecret();
77
- try { await store.set(handle, secret); } finally { secret = undefined; }
81
+ try { if (vendor === 'zendesk') clientCredential(secret); await store.set(handle, secret); } finally { secret = undefined; }
78
82
  state.vendorHandles = [...new Set([...(state.vendorHandles ?? []), handle])];
79
83
  } else {
84
+ if (vendor === 'zendesk') await stopSupervisor(stateDirectory());
80
85
  await store.delete(handle);
86
+ if (vendor === 'zendesk') {
87
+ await removeZendeskStores(stateDirectory());
88
+ state.vendorRevocations = { ...state.vendorRevocations, zendesk: true };
89
+ }
81
90
  state.vendorHandles = (state.vendorHandles ?? []).filter(item => item !== handle);
82
91
  }
83
92
  await saveState(state);
@@ -0,0 +1,127 @@
1
+ import { constants } from 'node:fs';
2
+ import { open, mkdir, chmod, readFile, rename, unlink, writeFile } from 'node:fs/promises';
3
+ import { join } from 'node:path';
4
+ import { createHash, randomUUID } from 'node:crypto';
5
+
6
+ const CHUNK = 65_536, MAX_BYTES = 32 * 1024 ** 3;
7
+ const hash = bytes => createHash('sha256').update(bytes).digest('hex');
8
+ const id = value => typeof value === 'string' && /^[0-9A-Za-z][0-9A-Za-z_-]{0,127}$/.test(value);
9
+ const pathValid = value => typeof value === 'string' && /^[A-Za-z0-9_][A-Za-z0-9_./-]*$/.test(value) && !value.split('/').some(p => !p || p === '.' || p === '..');
10
+ async function durableJson(path, value) {
11
+ const temporary = path + '.' + randomUUID() + '.tmp';
12
+ const file = await open(temporary, 'wx', 0o600);
13
+ try { await file.writeFile(JSON.stringify(value)); await file.sync(); } finally { await file.close(); }
14
+ try { await rename(temporary, path); } finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
15
+ }
16
+
17
+ /** Concatenated index and exact source files; no JSON reserialization of the package files. */
18
+ export async function buildPackage({ files, source, mode = 'snapshot', records, totals, quota, directory, signal }) {
19
+ if (!Number.isSafeInteger(quota) || quota < CHUNK || quota > 2 * 1024 ** 2) throw Error('Unsupported package grant byte quota.');
20
+ if (!Array.isArray(files) || !files.length || files.length > 100_000) throw Error('Invalid package files.');
21
+ let offset = 0; const names = new Set();
22
+ const entries = files.map(file => {
23
+ if (!pathValid(file.path) || file.path === 'index.ndjson' || names.has(file.path) || !Number.isSafeInteger(file.bytes) || file.bytes < 0 || !/^[a-f0-9]{64}$/.test(file.sha256)) throw Error('Invalid package file.');
24
+ names.add(file.path);
25
+ const entry = { path: file.path, bytes: file.bytes, sha256: file.sha256, offset };
26
+ offset += file.bytes;
27
+ if (!Number.isSafeInteger(offset) || offset > MAX_BYTES) throw Error('Package byte limit.');
28
+ return entry;
29
+ });
30
+ const index = Buffer.from(entries.map(row => JSON.stringify(row) + '\n').join(''));
31
+ if (index.length > quota || index.length + offset > MAX_BYTES) throw Error('Package index or stream byte limit.');
32
+ await mkdir(directory, { recursive: true, mode: 0o700 }); await chmod(directory, 0o700);
33
+ const segments = [], streamHash = createHash('sha256'); let pending = Buffer.alloc(0), bytes = 0;
34
+ const save = async value => {
35
+ const ordinal = segments.length, path = join(directory, `segment-${ordinal}`), temporary = path + '.tmp';
36
+ const file = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o600);
37
+ try { await file.writeFile(value); await file.sync(); } finally { await file.close(); }
38
+ await rename(temporary, path); segments.push({ bytes: value.length, sha256: hash(value), file: path });
39
+ };
40
+ const feed = async value => {
41
+ signal?.throwIfAborted(); streamHash.update(value); bytes += value.length;
42
+ let position = 0;
43
+ while (position < value.length) {
44
+ const length = Math.min(quota - pending.length, value.length - position);
45
+ pending = Buffer.concat([pending, value.subarray(position, position + length)]); position += length;
46
+ if (pending.length === quota) { await save(pending); pending = Buffer.alloc(0); }
47
+ }
48
+ };
49
+ await feed(index);
50
+ for (const file of files) {
51
+ const handle = await open(file.file, constants.O_RDONLY | constants.O_NOFOLLOW), digest = createHash('sha256'); let size = 0;
52
+ try {
53
+ const info = await handle.stat(); if (!info.isFile() || info.size !== file.bytes) throw Error('Package source changed before upload.');
54
+ for await (const chunk of handle.createReadStream({ autoClose: false, highWaterMark: CHUNK })) {
55
+ size += chunk.length; if (size > file.bytes) throw Error('Package source changed before upload.');
56
+ digest.update(chunk); await feed(chunk);
57
+ }
58
+ if (size !== file.bytes || digest.digest('hex') !== file.sha256) throw Error('Package source changed before upload.');
59
+ } finally { await handle.close(); }
60
+ }
61
+ if (pending.length) await save(pending);
62
+ const manifest = { format: 'rer-door-package/1', source, mode, stream: { bytes, sha256: streamHash.digest('hex') },
63
+ segments: segments.map(({ bytes, sha256 }) => ({ bytes, sha256 })), index: { path: 'index.ndjson', bytes: index.length, sha256: hash(index) }, records, totals };
64
+ const manifestBytes = Buffer.from(JSON.stringify(manifest));
65
+ if (manifestBytes.length > quota) throw Error('Package manifest exceeds the grant byte quota.');
66
+ const manifestPath = join(directory, 'rer-package.json'); await writeFile(manifestPath, manifestBytes, { mode: 0o600 });
67
+ return { manifest, directory, segments, manifestFile: { bytes: manifestBytes.length, sha256: hash(manifestBytes), file: manifestPath } };
68
+ }
69
+
70
+ /** Persist upload ids before their first request. Inventory is the authority after an interrupted ACK. */
71
+ export async function transferPackage({ prepared, fresh, request, signal, checkpoint, catchup = false, planAction = 'plan', planInput = {} }) {
72
+ const { manifestFile, segments, directory } = prepared, journalPath = join(directory, 'journal.json');
73
+ let journal;
74
+ try { journal = JSON.parse(await readFile(journalPath, 'utf8')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
75
+ if (!journal || journal.manifestSha256 !== manifestFile.sha256) journal = { manifestSha256: manifestFile.sha256, uploads: {}, supported: false };
76
+ if (!journal.uploads || typeof journal.uploads !== 'object') throw Error('Invalid package journal.');
77
+ const save = () => durableJson(journalPath, journal);
78
+ let done = 0;
79
+ async function upload(file, name, key) {
80
+ let uploadId = journal.uploads[key], inventory = null;
81
+ if (uploadId !== undefined && !id(uploadId)) throw Error('Invalid package journal upload id.');
82
+ if (uploadId) {
83
+ try { inventory = await request(await fresh('uploads'), { uploadId }, signal); }
84
+ catch (error) { if (error.doorStatus !== 404) throw error; uploadId = null; }
85
+ }
86
+ if (!uploadId) { uploadId = randomUUID(); journal.uploads[key] = uploadId; await save(); }
87
+ const handle = await open(file.file, constants.O_RDONLY | constants.O_NOFOLLOW);
88
+ try {
89
+ const totalChunks = Math.ceil(file.bytes / CHUNK), received = new Map();
90
+ if (inventory) {
91
+ if (inventory.uploadId !== uploadId || inventory.bundleSha256 !== file.sha256 || !Array.isArray(inventory.received)) throw Error('Invalid package inventory.');
92
+ for (const row of inventory.received) {
93
+ if (!Number.isSafeInteger(row.ordinal) || row.ordinal < 0 || row.ordinal >= totalChunks || received.has(row.ordinal)) throw Error('Invalid package chunk inventory.');
94
+ received.set(row.ordinal, row);
95
+ }
96
+ }
97
+ for (let index = 0; index < totalChunks; index++) {
98
+ signal.throwIfAborted();
99
+ const bytes = Buffer.alloc(Math.min(CHUNK, file.bytes - index * CHUNK)), { bytesRead } = await handle.read(bytes, 0, bytes.length, index * CHUNK);
100
+ if (bytesRead !== bytes.length) throw Error('Package spool changed.');
101
+ const row = received.get(index);
102
+ if (row && (row.sha256 !== hash(bytes) || row.size !== bytes.length)) throw Error('Package inventory differs from local bytes.');
103
+ if (!row) {
104
+ const result = await request(await fresh('uploads'), { uploadId, name, bundleSha256: file.sha256, totalBytes: file.bytes, totalChunks, index, chunkSha256: hash(bytes), base64: bytes.toString('base64') }, signal);
105
+ if (result.uploadId !== uploadId || result.bundleSha256 !== file.sha256 || index === totalChunks - 1 && result.complete !== true) throw Error('Invalid package upload answer.');
106
+ }
107
+ done += bytes.length;
108
+ await checkpoint({ bytes_done: done });
109
+ }
110
+ } finally { await handle.close(); }
111
+ return uploadId;
112
+ }
113
+ const uploadId = await upload(manifestFile, 'rer-package.json', 'manifest');
114
+ let preview;
115
+ try { preview = await request(await fresh(planAction), { ...planInput, uploadId, ...(catchup ? { catchup: true } : {}) }, signal); }
116
+ catch (error) {
117
+ if (error.doorStatus !== 409 || error.doorCode !== 'package_segment_missing' || !Array.isArray(error.doorDetails?.missing) || !error.doorDetails.missing.length
118
+ || error.doorDetails.missing.some(row => !segments.some(s => s.sha256 === row.sha256 && s.bytes === row.bytes))) {
119
+ throw Object.assign(Error('SEED_PACKAGE_UNSUPPORTED: the seed did not accept a manifest-first package probe. No segments were sent.'), { cause: error });
120
+ }
121
+ journal.supported = true; await save();
122
+ }
123
+ if (preview && !journal.supported && planAction==='prepare' && preview.protocol==='rer-bounded-waves/1' && typeof preview.parentId==='string') {journal.supported=true;await save();}
124
+ if (preview && !journal.supported) throw Error('SEED_PACKAGE_UNSUPPORTED: the seed did not request package segments. No segments were sent.');
125
+ if (!preview) for (let index = 0; index < segments.length; index++) await upload(segments[index], 'rer-segment', String(index));
126
+ return { uploadId, bundle: { size: manifestFile.bytes, sha256: manifestFile.sha256 }, ...(preview ? { preview } : {}) };
127
+ }
@@ -122,7 +122,7 @@ export async function next() {
122
122
  if (!item) {
123
123
  // Nothing to answer here; say whether run has work, or what it waits for.
124
124
  const work = tasks.find(task => Object.hasOwn(runWork, task.kind) && task.state === 'ready');
125
- if (work) { process.stdout.write(`Ready for run: ${runWork[work.kind]}. Start it with: ${businessCommand('run')}\n`); return; }
125
+ if (work) { process.stdout.write(`Ready for run: ${runWork[work.kind]}. Start it with: ${businessCommand('run --once')}\n`); return; }
126
126
  process.stdout.write(`${waitingFor(state)}\nNothing yet.\n`); return;
127
127
  }
128
128
  const id = identifier(item.task_id);
@@ -142,7 +142,7 @@ export async function next() {
142
142
  + (vendor && !keyed(vendor) ? `Vendor key: none; ${name} is read from its public page, with no key.\n`
143
143
  : stored ? `Vendor key: the owner's read-only ${name} key is stored in this computer's OS credential storage. To replace it, ${keyStep(vendor)}\n`
144
144
  : `Vendor key: ${keyStep(vendor)}${vendor ? '' : `\n where <vendor> is the tool this step reads: ${Object.keys(vendorNames).filter(keyed).join(' | ')}`}\n`)
145
- + `Then run: ${businessCommand('run')}\n`);
145
+ + `Then run: ${businessCommand('run --once')}\n`);
146
146
  return;
147
147
  }
148
148
  const { toolId, vendorId, vendors } = classification(item);
@@ -3,6 +3,7 @@ import { readFileSync, unlinkSync } from 'node:fs';
3
3
  import { dirname, join, resolve } from 'node:path';
4
4
  import { homedir } from 'node:os';
5
5
  import { createHash, randomUUID } from 'node:crypto';
6
+ import { setTimeout as delay } from 'node:timers/promises';
6
7
  import { localCause } from './errors.mjs';
7
8
 
8
9
  // RER_BUSINESS_STATE_DIR names the folder itself, for agent sandboxes that may write only
@@ -61,7 +62,7 @@ async function saveJson(name, value) {
61
62
  * Folders made only for the check are removed again, so a refused connect
62
63
  * leaves nothing behind.
63
64
  */
64
- export async function checkStateWritable() {
65
+ export async function checkStateWritable({ codeExists = true } = {}) {
65
66
  const directory = stateDirectory(), probe = join(directory, `${randomUUID()}.tmp`), created = [];
66
67
  for (let path = directory; path !== dirname(path); path = dirname(path)) {
67
68
  try { await lstat(path); break; } catch (error) { if (error.code !== 'ENOENT') break; created.push(path); }
@@ -77,7 +78,7 @@ export async function checkStateWritable() {
77
78
  const fix = chosenStateDirectory()
78
79
  ? 'Allow writes to that folder in this session, or set RER_BUSINESS_STATE_DIR to a folder this session can write'
79
80
  : 'Allow writes to that folder, or set RER_BUSINESS_STATE_DIR to a folder this session can write (in Codex, one inside the working folder, such as RER_BUSINESS_STATE_DIR="$PWD/.rer-business")';
80
- throw Error(`Business cannot save its state in ${directory}: ${localCause(error) ?? error.message}. Nothing was sent, so the pairing code still works. ${fix}, then run connect again.`);
81
+ throw Error(`Business cannot save its state in ${directory}: ${localCause(error) ?? error.message}. ${codeExists ? 'Nothing was sent, so the pairing code still works.' : 'Nothing was sent.'} ${fix}, then run connect again.`);
81
82
  } finally {
82
83
  for (const path of created) await rmdir(path).catch(() => {});
83
84
  }
@@ -85,13 +86,13 @@ export async function checkStateWritable() {
85
86
 
86
87
  // Files this CLI writes in its state folder. A folder named by RER_BUSINESS_STATE_DIR
87
88
  // may hold other things, so only these are removed from it.
88
- const owned = /^(?:(?:state|pairing|progress|permissions|service|carried)\.json|run\.lock|disconnect|service(?:-error)?\.log|discovery-[A-Za-z0-9_.:-]+\.(?:json|tmp)|export-[0-9a-f]{32}\.bundle|.*[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp(?:\.check)?)$/;
89
+ const owned = /^(?:(?:state|pairing|progress|permissions|service|carried|legacy-package)\.json|(?:run|pairing)\.lock|disconnect|service(?:-error)?\.log|discovery-[A-Za-z0-9_.:-]+\.(?:json|tmp)|export-[0-9a-f]{32}\.bundle|package-[0-9a-f]{32}|.*[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp(?:\.check)?)$/;
89
90
  /** After a revocation whose local cleanup was refused, keep only what a later
90
91
  * disconnect needs to finish: the state and the receipts of what remains. */
91
92
  export async function removeWorkFiles(keep = ['state.json', 'permissions.json', 'service.json']) {
92
93
  let entries;
93
94
  try { entries = await readdir(stateDirectory()); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
94
- for (const name of entries) if (owned.test(name) && !keep.includes(name)) await rm(join(stateDirectory(), name), { force: true });
95
+ for (const name of entries) if (owned.test(name) && !keep.includes(name)) await rm(join(stateDirectory(), name), { recursive: true, force: true });
95
96
  }
96
97
 
97
98
  export async function removeStateDirectory() {
@@ -104,7 +105,7 @@ export async function removeStateDirectory() {
104
105
  }
105
106
  let entries;
106
107
  try { entries = await readdir(directory); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
107
- for (const name of entries) if (owned.test(name)) await rm(join(directory, name), { force: true });
108
+ for (const name of entries) if (owned.test(name)) await rm(join(directory, name), { recursive: true, force: true });
108
109
  await rmdir(directory).catch(error => { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; });
109
110
  }
110
111
 
@@ -153,3 +154,44 @@ export async function lockSupervisor() {
153
154
  }
154
155
  throw Error('Could not acquire Business supervisor lock.');
155
156
  }
157
+
158
+ /** Serialize the pending read, start and save. Contenders wait, then resume
159
+ * the saved pairing; the lock never covers the foreground approval wait. */
160
+ export async function lockPairing(signal) {
161
+ const directory = stateDirectory(), path = join(directory, 'pairing.lock'), created = [];
162
+ for (let parent = directory; parent !== dirname(parent); parent = dirname(parent)) {
163
+ try { await lstat(parent); break; } catch (error) { if (error.code !== 'ENOENT') break; created.push(parent); }
164
+ }
165
+ const cleanDirectories = async () => { for (const parent of created) await rmdir(parent).catch(() => {}); };
166
+ let file;
167
+ try {
168
+ while (true) {
169
+ signal?.throwIfAborted();
170
+ await mkdir(directory, { recursive: true, mode: 0o700 });
171
+ try { file = await open(path, 'wx', 0o600); }
172
+ catch (error) {
173
+ if (error.code === 'ENOENT') continue; // A failed starter removed its empty folder.
174
+ if (error.code !== 'EEXIST') throw error;
175
+ if (await liveSupervisor(path)) await delay(50, undefined, { signal });
176
+ else await unlink(path).catch(error => { if (error.code !== 'ENOENT') throw error; });
177
+ continue;
178
+ }
179
+ try { await file.writeFile(String(process.pid)); } finally { await file.close(); }
180
+ const refresh = setInterval(() => { const now = new Date(); utimes(path, now, now).catch(() => {}); }, 30_000);
181
+ refresh.unref();
182
+ const exit = () => { try { if (readFileSync(path, 'utf8') === String(process.pid)) unlinkSync(path); } catch { /* Already gone. */ } };
183
+ process.once('exit', exit);
184
+ let released = false;
185
+ return async () => {
186
+ if (released) return;
187
+ released = true;
188
+ clearInterval(refresh); process.off('exit', exit); exit();
189
+ await cleanDirectories();
190
+ };
191
+ }
192
+ } catch (error) {
193
+ if (file) await unlink(path).catch(() => {});
194
+ await cleanDirectories();
195
+ throw error;
196
+ }
197
+ }
@@ -11,7 +11,7 @@ import { Lease } from './lease.mjs';
11
11
  import { runDiscovery } from './discovery-task.mjs';
12
12
  import { applyChoices } from './choices.mjs';
13
13
  import { businessCommand } from './invocation.mjs';
14
- import { ExportWaiting, vendorHandle } from './vendor-door.mjs';
14
+ import { ExportWaiting, vendorHandle, titledVendor } from './vendor-door.mjs';
15
15
  import { runExport } from './export-task.mjs';
16
16
  import { runCatchup } from './catchup-task.mjs';
17
17
  import { runArchive } from './archive-task.mjs';
@@ -22,6 +22,27 @@ const kinds = new Set(['discover.local', ...Object.keys(vendorWork)]);
22
22
  export function supportsTaskKind(kind) { return kinds.has(kind); }
23
23
  const checkIn = 25_000;
24
24
 
25
+ // Only these platform refusals hand work to the owner. Catch-up completion
26
+ // has already surrendered its lease; an export-input wait never claims one.
27
+ function ownerWait(error, state, task) {
28
+ if (error.status !== 409) return null;
29
+ const catchup = error.code === 'business_catchup_approval_required';
30
+ if (!catchup && !(error.code === 'business_export_inputs_required' && error.state === 'waiting_for_owner')) return null;
31
+ let link = ownerLink(state);
32
+ if (catchup && typeof error.link === 'string') {
33
+ try {
34
+ const url = new URL(error.link, state.origin);
35
+ if (url.origin === state.origin && !url.username && !url.password && !url.search && !url.hash
36
+ && url.pathname.startsWith(new URL(link).pathname + '/moves/')) link = url.href;
37
+ } catch { /* The Business page is where the owner can find this step. */ }
38
+ }
39
+ const vendor = task && titledVendor(task.kind, task.title);
40
+ const step = catchup ? 'approve this catch-up' : vendor === 'sorry' ? 'confirm the address'
41
+ : ['sentry', 'pagerduty'].includes(vendor) ? 'confirm the export details' : null;
42
+ if (!step) return `${error.reason ?? "Waiting for the owner's export inputs."}\nIn Business: ${link}`;
43
+ return `${error.reason ? error.reason + '\n' : ''}Waiting for the owner to ${step} in Business: ${link}`;
44
+ }
45
+
25
46
  /** Work this computer's tasks. It says what it is doing and what it waits
26
47
  * for, applies the owner's choices at every check-in, and removes run.lock on
27
48
  * every exit, including Ctrl-C, SIGTERM and a closed terminal (SIGHUP). */
@@ -29,7 +50,7 @@ export async function run({ once = false } = {}) {
29
50
  const { state, credential } = await paired(), api = new Api(state.origin, credential), directory = stateDirectory();
30
51
  // Tasks this run handed back as paused, with what each waits for. An export
31
52
  // waiting only for the owner's vendor key is picked up again once it is stored.
32
- const parked = new Map(), unlock = await lockSupervisor(), stop = new AbortController();
53
+ const parked = new Map(), ownerWaits = new Map(), unlock = await lockSupervisor(), stop = new AbortController();
33
54
  // A terminal's Ctrl-C reaches npx and this process together, and npx then
34
55
  // forwards another SIGINT, which can arrive at any moment until this process
35
56
  // has exited. So the handlers stay for the rest of the process: a repeated
@@ -42,7 +63,7 @@ export async function run({ once = false } = {}) {
42
63
  let progress, stopCarry, said = '', held = null, summaries = [];
43
64
  const say = text => { if (text !== said) { said = text; process.stdout.write(text + '\n'); } };
44
65
  // An agent step that waits is said in its own words, never as "Nothing yet".
45
- const waits = () => [...new Set([...summaries.filter(task => parked.has(task.task_id)).map(task => parked.get(task.task_id).message), ...agentWaiting(summaries)])];
66
+ const waits = () => [...new Set([...ownerWaits.values()].concat(summaries.filter(task => parked.has(task.task_id)).map(task => parked.get(task.task_id).message), agentWaiting(summaries)))];
46
67
  // With no agent step waiting, a move's owner step (freeze, rollback, cancellation) is named with its link.
47
68
  const idle = () => { const owner = ownerWaiting(summaries, state); return owner.length ? owner.join('\n') : waitingFor(state); };
48
69
  try {
@@ -60,6 +81,9 @@ export async function run({ once = false } = {}) {
60
81
  }
61
82
  if (!progress.pendingClaim) {
62
83
  summaries = await nextQuestions(api, stop.signal);
84
+ // A wait belongs only to a task Business still lists as needing input.
85
+ // Cancellation, completion or another computer taking it clears the line.
86
+ for (const id of ownerWaits.keys()) if (!summaries.some(task => task.task_id === id && ['needs_input', 'waiting_for_owner'].includes(task.state))) ownerWaits.delete(id);
63
87
  const handles = (await loadState())?.vendorHandles ?? [];
64
88
  for (const [id, wait] of parked) if (wait.keyMissing && handles.includes(vendorHandle(wait.keyMissing))) parked.delete(id);
65
89
  const selected = summaries.find(task => kinds.has(task.kind) && ['ready','leased'].includes(task.state) && !parked.has(task.task_id));
@@ -76,9 +100,18 @@ export async function run({ once = false } = {}) {
76
100
  let claimed;
77
101
  try { claimed = await api.post('/api/business/executors/claim', { ...progress.pendingClaim, wait_seconds: 25 }, { signal: stop.signal }); }
78
102
  catch (error) {
79
- if (error.status !== 409) throw error;
103
+ const waiting = ownerWait(error, state, summaries.find(task => task.task_id === progress.pendingClaim.task_id));
104
+ if (!waiting) {
105
+ if (error.status !== 409) throw error;
106
+ progress = {}; await saveProgress(progress);
107
+ held = null;
108
+ if (once) throw error;
109
+ await pause(checkIn, stop.signal); continue;
110
+ }
111
+ ownerWaits.set(progress.pendingClaim.task_id, waiting); say(waiting);
80
112
  progress = {}; await saveProgress(progress);
81
- if (once) throw error;
113
+ held = null;
114
+ if (once) return;
82
115
  await pause(checkIn, stop.signal); continue;
83
116
  }
84
117
  if (!claimed.task || claimed.task.state !== 'leased' || claimed.task.fence !== claimed.fence || Date.parse(claimed.lease_expires_at) <= Date.now()) {
@@ -130,14 +163,20 @@ export async function run({ once = false } = {}) {
130
163
  }
131
164
  } catch (error) { failure = lease.signal.aborted ? lease.signal.reason : error; }
132
165
  finally {
133
- if (!finished && failure?.status !== 401) {
166
+ if (!finished && failure?.status !== 401 && !ownerWait(failure ?? {}, state)) {
134
167
  try { await lease.release(stop.signal.aborted ? 'handover' : parked.has(claimed.task.id) ? 'paused' : 'failed'); released = true; }
135
168
  catch (error) { if (error.status === 401) failure = error; }
136
169
  }
137
170
  await lease.close();
138
- if (finished || released) { progress = {}; await saveProgress(progress); }
171
+ if (finished || released || ownerWait(failure ?? {}, state)) { progress = {}; await saveProgress(progress); }
139
172
  }
140
173
  if (failure) {
174
+ const waiting = ownerWait(failure, state);
175
+ if (waiting && !stop.signal.aborted) {
176
+ ownerWaits.set(claimed.task.id, waiting); say(waiting); held = null;
177
+ if (once) return;
178
+ await pause(checkIn, stop.signal); continue;
179
+ }
141
180
  if (failure.status === 401 || once || !parked.has(claimed.task.id)) throw failure;
142
181
  process.stderr.write(failure.message + '\n');
143
182
  }
@@ -1,7 +1,12 @@
1
+ import { buildPackage, transferPackage } from './package-transfer.mjs';
2
+ import { registeredLegacyPackage } from './legacy-package.mjs';
3
+ import { prepareZendeskPackage } from './vendors/zendesk-package.mjs';
1
4
  import { createHash } from 'node:crypto';
2
5
  import { constants } from 'node:fs';
3
6
  import { open, unlink } from 'node:fs/promises';
4
7
  import { join } from 'node:path';
8
+ import { loadState, saveState } from './state.mjs';
9
+ import { snapshot as zendeskSnapshot, storePath as zendeskStorePath, removeZendeskStores } from './vendors/zendesk.mjs';
5
10
  import { taskPath } from './api.mjs';
6
11
  import { assertChunk } from './outbound.mjs';
7
12
  import { createCredentialStore } from './keychain.mjs';
@@ -18,7 +23,7 @@ import { businessCommand } from './invocation.mjs';
18
23
  const CHUNK_BYTES = 65_536;
19
24
  const DOOR_RESPONSE_BYTES = 4 * 1024 * 1024;
20
25
  // The catalogue names the platform builds vendor task titles from.
21
- export const vendorNames = Object.freeze({ sentry: 'Sentry', uptimerobot: 'UptimeRobot', pagerduty: 'PagerDuty', calendly: 'Calendly', sorry: 'Sorry' });
26
+ export const vendorNames = Object.freeze({ sentry: 'Sentry', uptimerobot: 'UptimeRobot', pagerduty: 'PagerDuty', calendly: 'Calendly', sorry: 'Sorry', zendesk: 'Zendesk', 'happytohelp-legacy': 'HappyToHelp legacy' });
22
27
  /** Whether a vendor's export needs the owner's read-only key (Sorry's public page does not). */
23
28
  export const keyed = vendor => KEYED_VENDORS.includes(vendor);
24
29
  export const vendorHandle = vendor => `vendor:${vendor}:read`;
@@ -89,19 +94,20 @@ function destination(task, grant) {
89
94
  function adapterInputs(vendor, task) {
90
95
  const inputs = exportInputs(vendor, task);
91
96
  if (inputs) return inputs;
92
- const needs = vendor === 'calendly' ? 'an import door that takes its folder of files' : `${inputNeeds[vendor]}, which this task does not carry yet`;
93
- throw new ExportWaiting(`Business vendor export for ${vendorNames[vendor]} needs ${needs}. Task released as paused.`, 'configuration_required');
97
+ const message = vendor === 'calendly' ? 'Waiting for the owner: this tool needs its folder of files shared with Business.'
98
+ : `Waiting for the owner to confirm ${inputNeeds[vendor]} in Business.`;
99
+ throw new ExportWaiting(message, 'configuration_required');
94
100
  }
95
101
 
96
102
  /** One RER-signed import grant for one door request. `review` asks for a
97
103
  * catch-up plan grant without the owner's standing approval; a plan grant
98
104
  * Business minted under that approval says so with `catchup: 'bounded'`. */
99
- async function doorGrant(lease, action, origin, vendor, { review = false } = {}) {
100
- const grant = await lease.importGrant(action, review ? { review: true } : {});
105
+ async function doorGrant(lease, action, origin, vendor, { review = false, bounded } = {}) {
106
+ const grant = await lease.importGrant(action, { ...(review ? { review: true } : {}), ...(bounded ? { bounded } : {}) });
101
107
  if (!grant || grant.action !== action || grant.destination !== new URL(`/api/rer/import/${action}`, origin).href
102
108
  || typeof grant.authorization !== 'string' || grant.authorization.length > 8192 || !/^Bearer [A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(grant.authorization)
103
109
  || !VENDORS.includes(grant.namespace) || vendor && grant.namespace !== vendor || !(Date.parse(grant.expires_at) > Date.now())
104
- || Object.hasOwn(grant, 'catchup') && (grant.catchup !== 'bounded' || action !== 'plan' || review)) throw Error('Business returned an invalid import grant.');
110
+ || Object.hasOwn(grant, 'catchup') && (grant.catchup !== 'bounded' || !['plan','prepare'].includes(action) || review)) throw Error('Business returned an invalid import grant.');
105
111
  return grant;
106
112
  }
107
113
 
@@ -129,7 +135,7 @@ export async function door(grant, body, signal) {
129
135
  if (!response.ok) {
130
136
  // A door code is snake_case, sometimes with one named reason (`catchup_requires_proposal:source_records_gone`).
131
137
  const doorCode = typeof result?.error === 'string' && /^[a-z][a-z0-9_]{0,79}(?::[a-z][a-z0-9_]{0,79})?$/.test(result.error) ? result.error : null;
132
- throw Object.assign(Error(`The app's import door refused the ${action} request (HTTP ${response.status}${doorCode ? `: ${doorCode}` : ''}).`), { doorStatus: response.status, doorCode });
138
+ throw Object.assign(Error(`The app's import door refused the ${action} request (HTTP ${response.status}${doorCode ? `: ${doorCode}` : ''}).`), { doorStatus: response.status, doorCode, ...(doorCode === 'package_segment_missing' ? { doorDetails: result.details } : {}) });
133
139
  }
134
140
  if (!result || typeof result !== 'object' || Array.isArray(result)) throw Error(`The app's import door returned an invalid ${action} answer.`);
135
141
  return result;
@@ -137,12 +143,21 @@ export async function door(grant, body, signal) {
137
143
 
138
144
  /** Run the shipped adapter into a private 0600 bundle file, checking every
139
145
  * item with the outbound detector before it is written. */
140
- async function exportBundle({ vendor, key = null, inputs, path, quota, signal }) {
146
+ async function exportBundle({ vendor, key = null, inputs, path, quota, signal, directory, runId, business }) {
141
147
  await unlink(path).catch(error => { if (error.code !== 'ENOENT') throw error; });
142
148
  const file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
143
- const digest = createHash('sha256'); let size = 0;
149
+ const digest = createHash('sha256'); let size = 0, zendeskStore;
144
150
  try {
145
- for await (const item of exportVendor(vendor, { key, inputs, signal })) {
151
+ let items;
152
+ if (vendor === 'zendesk') {
153
+ const root = zendeskStorePath(directory, business, `https://${inputs.account.subdomain}.zendesk.com`);
154
+ const result = await zendeskSnapshot({ key, inputs, directory: inputs.mode === 'census' ? join(root, 'probe') : root, runId, signal });
155
+ if (result.kind === 'census') throw new ExportWaiting(`Zendesk census: ${result.census.tickets.unique} tickets; ${result.census.unswept} unswept. CENSUS_OUTPUTS_UNSUPPORTED: waiting for Business census task outputs.`, 'connected_runner_required');
156
+ if (result.kind === 'package') return { package: result, store: result.store, mode: inputs.mode };
157
+ zendeskStore = result.store;
158
+ items = [{ bytes: result.bytes }];
159
+ } else items = exportVendor(vendor, { key, inputs, signal });
160
+ for await (const item of items) {
146
161
  assertChunk(item.bytes, key ? [key] : []);
147
162
  size += item.bytes.length;
148
163
  if (size > quota) throw Error(`Business vendor export is larger than the app's import door accepts (${quota} bytes). Nothing was uploaded.`);
@@ -158,7 +173,7 @@ async function exportBundle({ vendor, key = null, inputs, path, quota, signal })
158
173
  throw Error(`${vendorNames[vendor]} export stopped (${error.code}${error.status ? `, HTTP ${error.status}` : ''}). Nothing was uploaded.`);
159
174
  } finally { await file.close(); }
160
175
  if (!size) throw Error(`${vendorNames[vendor]} export produced nothing to upload.`);
161
- return { size, sha256: digest.digest('hex') };
176
+ return { size, sha256: digest.digest('hex'), ...(zendeskStore ? { store: zendeskStore, mode: inputs.mode } : {}) };
162
177
  }
163
178
 
164
179
  async function readChunk(path, index, size) {
@@ -198,19 +213,72 @@ export async function withUploadedBundle({ lease, task, grant: claimedGrant, dir
198
213
  const fresh = async (action, options) => {
199
214
  if (action === 'uploads' && spare && Date.parse(spare.expires_at) - Date.now() > 60_000) { const grant = spare; spare = null; return grant; }
200
215
  spare = null;
201
- return doorGrant(lease, action, origin, vendor, options);
216
+ return doorGrant(lease, action, origin, vendor, options ?? (task.bounded_waves && action==='prepare' ? {bounded:{protocol:task.bounded_waves.protocol,migration:task.bounded_waves.migration,revision:task.bounded_waves.revision,policy:task.bounded_waves.policy}} : undefined));
202
217
  };
203
218
  const inputs = adapterInputs(vendor, task);
219
+ const state = vendor === 'zendesk' ? await loadState() : null;
220
+ if (vendor === 'zendesk' && inputs.mode === 'retire') {
221
+ // The retire signal is local revocation, never an OAuth/provider write.
222
+ await createCredentialStore().delete(vendorHandle(vendor));
223
+ await removeZendeskStores(directory);
224
+ await saveState({ ...state, vendorHandles: (state.vendorHandles ?? []).filter(handle => handle !== vendorHandle(vendor)), vendorRevocations: { ...state.vendorRevocations, zendesk: true } });
225
+ throw new ExportWaiting('Zendesk retired locally (VENDOR_REVOKED). RETIRE_OUTPUTS_UNSUPPORTED: waiting for Business retire task acknowledgement.', 'connected_runner_required');
226
+ }
227
+ if (vendor === 'zendesk' && state?.vendorRevocations?.zendesk) throw new VendorExportError('VENDOR_REVOKED');
204
228
  let key = keyed(vendor) ? await createCredentialStore().get(vendorHandle(vendor)) : null;
205
229
  if (keyed(vendor) && !key) throw new ExportWaiting(`Business vendor export needs the owner's read-only ${name} key on this computer: ${keyStep(vendor)}\nThen run ${businessCommand('run')} again.`, 'owner_required', { keyMissing: vendor });
230
+ if (vendor === 'happytohelp-legacy') {
231
+ if (!['export.vendor', 'catchup.vendor'].includes(task.kind)) throw new ExportWaiting('Legacy package tasks require a package-aware export or catch-up reader.', 'configuration_required');
232
+ let legacy;
233
+ try { legacy = await registeredLegacyPackage(); }
234
+ catch (error) { throw new ExportWaiting(error.message, 'configuration_required'); }
235
+ say(doing(name, origin, false));
236
+ const packageDirectory = join(directory, `package-${hash(task.id).slice(0, 32)}`);
237
+ let prepared;
238
+ try {
239
+ prepared = await buildPackage({ files: legacy.files, quota, directory: packageDirectory, signal,
240
+ source: { format: legacy.manifest.format, version: 1, origin: 'legacy-database', exportedAt: legacy.manifest.exportedAt ?? legacy.manifest.source.exportedAt ?? null,
241
+ synthetic: legacy.manifest.source.synthetic === true, adapter: 'rer:happytohelp-legacy' },
242
+ records: { total: null, byKind: {} }, totals: { rowCounts: legacy.rowCounts, objects: legacy.objects } });
243
+ } catch { throw new ExportWaiting(`Legacy package changed or could not be prepared: ${legacy.path}. Recheck and register that package again.`, 'configuration_required'); }
244
+ let uploaded;
245
+ try { uploaded = await transferPackage({ prepared, fresh, request: door, signal, checkpoint: cp => lease.checkpointSaved(cp), catchup: task.kind === 'catchup.vendor', ...(task.bounded_waves ? { planAction:'prepare', planInput:{ordinal:0} } : {}) }); }
246
+ catch (error) { if (!error.message.startsWith('SEED_PACKAGE_UNSUPPORTED')) throw error; throw new ExportWaiting(error.message, 'configuration_required'); }
247
+ const { outputs, said } = await finish({ vendor, name, origin, ...uploaded, fresh });
248
+ await lease.complete(outputs);
249
+ return said;
250
+ }
206
251
  const path = join(directory, `export-${hash(task.id).slice(0, 32)}.bundle`);
207
252
  try {
208
253
  say(doing(name, origin, keyed(vendor)));
209
254
  let bundle;
210
- try { bundle = await exportBundle({ vendor, key, inputs, path, quota, signal }); } finally { key = undefined; }
255
+ try { bundle = await exportBundle({ vendor, key, inputs, path, quota, signal, directory, runId: task.id, business: state?.businessId }); } finally { key = undefined; }
256
+ if (bundle.package) {
257
+ const prepared = await prepareZendeskPackage({ result: bundle.package, quota, directory: join(bundle.store.path, `package-${hash(task.id).slice(0,32)}`), signal, mode: inputs.mode });
258
+ const uploaded = await transferPackage({ prepared, fresh, request: door, signal, checkpoint: cp => lease.checkpointSaved(cp), catchup: task.kind === 'catchup.vendor' || inputs.mode === 'sweep' });
259
+ const finished = await finish({ vendor, name, origin, ...uploaded, fresh });
260
+ await lease.complete(finished.outputs);
261
+ return finished.said;
262
+ }
211
263
  const total = Math.ceil(bundle.size / CHUNK_BYTES);
212
264
  let uploadId;
265
+ const received = new Set();
266
+ const journal = bundle.store?.events.findLast(event => event.kind === 'transfer');
267
+ if (journal && journal.origin === origin && journal.bundleSha256 === bundle.sha256 && journal.totalBytes === bundle.size) {
268
+ try {
269
+ const inventory = await door(await fresh('uploads'), { uploadId: journal.uploadId }, signal);
270
+ if (inventory.uploadId !== journal.uploadId || inventory.bundleSha256 !== bundle.sha256 || !Array.isArray(inventory.received)) throw new VendorExportError('INVALID_CHECKPOINT');
271
+ for (const item of inventory.received) {
272
+ if (!Number.isSafeInteger(item.ordinal) || item.ordinal < 0 || item.ordinal >= total || received.has(item.ordinal)) throw new VendorExportError('INVALID_CHECKPOINT');
273
+ const bytes = await readChunk(path, item.ordinal, bundle.size);
274
+ if (item.sha256 !== hash(bytes) || item.size !== bytes.length) throw new VendorExportError('INVALID_CHECKPOINT');
275
+ received.add(item.ordinal);
276
+ }
277
+ uploadId = journal.uploadId;
278
+ } catch (error) { if (error.doorStatus !== 404) throw error; }
279
+ }
213
280
  for (let index = 0; index < total; index++) {
281
+ if (received.has(index)) continue;
214
282
  signal.throwIfAborted();
215
283
  const bytes = await readChunk(path, index, bundle.size);
216
284
  const result = await door(await fresh('uploads'), { ...(uploadId ? { uploadId } : {}), name: capability.output, bundleSha256: bundle.sha256,
@@ -218,6 +286,11 @@ export async function withUploadedBundle({ lease, task, grant: claimedGrant, dir
218
286
  if (typeof result.uploadId !== 'string' || !DOOR_ID.test(result.uploadId) || uploadId && result.uploadId !== uploadId
219
287
  || result.bundleSha256 !== bundle.sha256 || index === total - 1 && result.complete !== true) throw Error("The app's import door returned an invalid upload answer.");
220
288
  uploadId = result.uploadId;
289
+ if (bundle.store) {
290
+ const transfer = { kind: 'transfer', origin, bundleSha256: bundle.sha256, totalBytes: bundle.size, uploadId };
291
+ await bundle.store.commit(bundle.store.state, transfer);
292
+ await bundle.store.write('transfer.json', transfer);
293
+ }
221
294
  await lease.checkpointSaved({ page: index + 1, total, bytes_done: Math.min((index + 1) * CHUNK_BYTES, bundle.size), progress: Math.floor((index + 1) / total * 90) });
222
295
  }
223
296
  const { outputs, said } = await finish({ vendor, name, origin, uploadId, bundle, fresh });
@@ -23,9 +23,9 @@ No export runs merely by importing these modules. No account export was run
23
23
  during implementation.
24
24
 
25
25
  `VENDORS` is the closed vendor enum (`sentry`, `uptimerobot`, `pagerduty`,
26
- `calendly`, `sorry`). `VENDOR_CAPABILITIES` describes the adapter,
26
+ `calendly`, `sorry`, `zendesk`, `happytohelp-legacy`). `VENDOR_CAPABILITIES` describes the adapter,
27
27
  required vendor-key capability, native importer format, layout and read scopes.
28
- These adapters cannot verify that a supplied key itself has read-only scope;
28
+ Except for Zendesk's checked OAuth scopes, adapters cannot verify that a supplied key itself has read-only scope;
29
29
  the owner must create the documented read-only key where the vendor offers one.
30
30
 
31
31
  ## Transport and resume
@@ -174,3 +174,42 @@ Seed documentation and official APIs were inspected on 16 October 2026.
174
174
  These sources document shapes; no real-account parity or migration success is
175
175
  claimed. Parent integration must provide seed assembly and transport under the
176
176
  actual import grant protocol, plus network-edge acceptance coverage.
177
+
178
+ ## Zendesk's retained snapshot
179
+
180
+ `zendesk` is a keyed vendor with `layout: 'snapshot'`. Its credential is the
181
+ hidden-input JSON client credential documented in [the CLI guide](../../README.md#zendesk-offline-snapshots),
182
+ rather than a bare API token. `snapshot({key,inputs,directory,runId,signal})` in
183
+ `zendesk.mjs` drives phases A–F into the durable store. `exportVendor` accepts
184
+ `directory` and `runId` for this vendor; the Business door provides a directory
185
+ keyed by Business and account. It does not apply the older vendors' 2,000-item
186
+ or one-MiB item limits. The complete deliverable is checked against HH v1 limits
187
+ before any upload. Package-required results use the shared package sender with path bindings and
188
+ sidecars. It probes the manifest before sending segments, resumes the transfer
189
+ journal and plans one complete snapshot; no per-part plan or fallback is used.
190
+
191
+ Responsibilities are separated into token/scope checking, transport, pages,
192
+ tickets/comments, people, attachments, Guide, store and HH encoding. Requests
193
+ stop at 250,000, responses at 32 MiB, records/blobs at 64 MiB, snapshots at
194
+ 32 GiB. The opt-in `pacedClient` in `common.mjs` supports bounded 429 retries
195
+ (1–60 seconds, at most three per request and ten minutes per run), rate headers,
196
+ and manual attachment redirects. Without rate headers it waits at least six
197
+ seconds between incremental requests and 300 ms otherwise. Other vendors keep
198
+ `client()` and its previous no-retry behavior.
199
+
200
+ Only the account origin receives Authorization. The first attachment URL must
201
+ be on that origin's attachment path. One redirect may go to a public HTTPS DNS
202
+ host, with no userinfo, IP, explicit port or local/private address, and receives
203
+ no credential even when it returns to the account origin. Further redirects
204
+ are errors. Pagination is independently checked for account origin, exact
205
+ collection and allowed query parameters.
206
+
207
+ Checkpoints point at immutable SHA-256 journal nodes and raw objects. Each page
208
+ is fsynced before its journal and atomic checkpoint; a kill before acknowledgement
209
+ leaves only unreachable objects. Resume validates the reachable graph and
210
+ rebuilds last-version records and census from it. Repeated attachment bytes
211
+ have one blob. The census declares tombstones, inaccessible/deleted/malware/large
212
+ attachments and omissions explicitly. Guide 404 records unavailable coverage.
213
+ The JSON census and Guide sidecars stay local and in the package; Business
214
+ receives only the door's ids and SHA for a successful bundle. See the CLI guide
215
+ for the separate Business census/retire output dependencies.