@oxygen-agent/cli 1.1021.7 → 1.1022.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +1 -1
  2. package/dist/command-families/program.js +2 -0
  3. package/dist/command-families/tables/bundle-export.d.ts +2 -1
  4. package/dist/command-families/tables/bundle-export.js +14 -3
  5. package/dist/command-manifest.js +2 -0
  6. package/dist/command-support.d.ts +6 -0
  7. package/dist/command-support.js +61 -9
  8. package/dist/commands/agent.js +2 -2
  9. package/dist/commands/approvals.js +3 -52
  10. package/dist/commands/billing.js +5 -5
  11. package/dist/commands/context.js +2 -2
  12. package/dist/commands/copilot.js +1 -1
  13. package/dist/commands/knowledge.js +2 -2
  14. package/dist/commands/members.d.ts +7 -0
  15. package/dist/commands/members.js +32 -0
  16. package/dist/commands/orgs.js +1 -1
  17. package/dist/commands/publishing.js +36 -2
  18. package/dist/commands/recipes.js +1 -1
  19. package/dist/commands/sequences.js +4 -4
  20. package/dist/commands/suppressions.js +2 -2
  21. package/dist/commands/verify.js +1 -1
  22. package/dist/commands/workspace-export.d.ts +61 -0
  23. package/dist/commands/workspace-export.js +565 -0
  24. package/dist/commands/workspace.js +24 -1
  25. package/dist/help.js +6 -1
  26. package/node_modules/@oxygen/shared/dist/access/permissions.d.ts +101 -0
  27. package/node_modules/@oxygen/shared/dist/access/permissions.js +129 -0
  28. package/node_modules/@oxygen/shared/dist/access/roles.d.ts +73 -0
  29. package/node_modules/@oxygen/shared/dist/access/roles.js +116 -0
  30. package/node_modules/@oxygen/shared/dist/agents/sessions.js +2 -1
  31. package/node_modules/@oxygen/shared/dist/agents/teammates.js +2 -1
  32. package/node_modules/@oxygen/shared/dist/capability-intents/collaboration.js +7 -6
  33. package/node_modules/@oxygen/shared/dist/capability-intents/discovery-and-skills.d.ts +12 -0
  34. package/node_modules/@oxygen/shared/dist/capability-intents/discovery-and-skills.js +54 -0
  35. package/node_modules/@oxygen/shared/dist/capability-intents/discovery-and-skills.rules.d.ts +2 -0
  36. package/node_modules/@oxygen/shared/dist/capability-intents/discovery-and-skills.rules.js +19 -0
  37. package/node_modules/@oxygen/shared/dist/capability-intents/index.generated.js +2 -0
  38. package/node_modules/@oxygen/shared/dist/capability-routes/discovery-and-skills.js +4 -4
  39. package/node_modules/@oxygen/shared/dist/collab.d.ts +0 -29
  40. package/node_modules/@oxygen/shared/dist/collab.js +0 -32
  41. package/node_modules/@oxygen/shared/dist/contracts/browser-operations.js +2 -2
  42. package/node_modules/@oxygen/shared/dist/contracts/customer-operations.js +4 -3
  43. package/node_modules/@oxygen/shared/dist/contracts/publishing-reads.js +1 -1
  44. package/node_modules/@oxygen/shared/dist/copilot/access.d.ts +1 -1
  45. package/node_modules/@oxygen/shared/dist/copilot/access.js +2 -1
  46. package/node_modules/@oxygen/shared/dist/decision-ledger.generated.js +11 -0
  47. package/node_modules/@oxygen/shared/dist/onboarding/guided-activation.js +3 -1
  48. package/node_modules/@oxygen/shared/dist/product-briefing-rules.js +2 -2
  49. package/node_modules/@oxygen/shared/dist/product-doctrine.js +1 -1
  50. package/node_modules/@oxygen/shared/dist/version.d.ts +1 -1
  51. package/node_modules/@oxygen/shared/dist/version.generated.d.ts +1 -1
  52. package/node_modules/@oxygen/shared/dist/version.generated.js +1 -1
  53. package/node_modules/@oxygen/shared/dist/version.js +1 -1
  54. package/package.json +1 -1
@@ -0,0 +1,565 @@
1
+ import { OxygenError } from "@oxygen/shared/cli-result";
2
+ import { renderKnowledgePageMarkdown } from "@oxygen/shared/knowledge/markdown";
3
+ import { OXYGEN_VERSION } from "@oxygen/shared/version";
4
+ import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
5
+ import { join, resolve } from "node:path";
6
+ import { setTimeout as delay } from "node:timers/promises";
7
+ import { exportTableBundle } from "../command-families/tables/bundle-export.js";
8
+ import { requestOxygen } from "../http-client.js";
9
+ import { pageFilePath } from "../knowledge-mirror.js";
10
+ // `oxygen workspace export` is a Control-surface composition, like the
11
+ // workspace map: every part is a read its primitive already owns, written to a
12
+ // local folder. It creates nothing in the workspace and spends nothing.
13
+ export const WORKSPACE_EXPORT_PARTS = [
14
+ "tables",
15
+ "crm",
16
+ "knowledge",
17
+ "workflows",
18
+ "sequences",
19
+ "dashboards",
20
+ "tags",
21
+ "folders",
22
+ "do_not_contact",
23
+ "settings",
24
+ ];
25
+ export const WORKSPACE_EXPORT_FORMAT = "oxygen-workspace-export";
26
+ export const WORKSPACE_EXPORT_FORMAT_VERSION = 1;
27
+ // A backup must never be mistaken for more than it is, so the manifest names
28
+ // what even a complete export leaves behind.
29
+ export const WORKSPACE_EXPORT_NOT_INCLUDED = [
30
+ { what: "Connections, API keys, OAuth tokens and mailbox credentials OXYGEN stores", why: "Never exported; reconnect each account wherever you restore. A secret typed into a column or workflow definition is part of that definition and is exported as written." },
31
+ { what: "Unibox conversations and message history", why: "Not part of this export yet." },
32
+ { what: "Sequence enrollments and send history", why: "Not part of this export yet; sequences/ holds each sequence's definition and settings." },
33
+ { what: "CRM notes, tasks, files and activity timelines", why: "Not part of this export yet. CRM companies, people and deals are in tables/, their object definitions in crm-objects.json." },
34
+ { what: "Links between tables and records", why: "Table bundles carry no relation edges; re-create them with `oxygen tables relate` and `oxygen tables link` after importing." },
35
+ { what: "Saved table views, feeds, webhooks, schedules and auto-run or auto-dedupe settings", why: "Not part of this export yet; each table's columns and rows are." },
36
+ { what: "Prompt templates, email assets, spintax, Functions, custom HTTP integrations and sender profiles", why: "Not part of this export yet." },
37
+ { what: "Members, roles, billing and personal preferences", why: "Not part of this export; settings.json holds the workspace-wide settings the CLI can read." },
38
+ { what: "Archived tables and wiki pages, and pending knowledge proposals", why: "Only live tables and pages are exported; workflows and sequences are exported whatever their status." },
39
+ { what: "The wiki's activity log, earlier page revisions and pages shared from other workspaces", why: "Not part of this export yet; knowledge/ holds the current version of each page this workspace owns." },
40
+ { what: "Agents, posts, signals, ads and knowledge files", why: "Not part of this export yet." },
41
+ ];
42
+ const RESTORE_HINTS = {
43
+ tables: "oxygen tables import-bundle --file tables/<table>.jsonl. A CRM object's table imports as a plain table; crm-objects.json holds the object definitions to re-create it.",
44
+ knowledge: "Each file is the page markdown `oxygen knowledge sync` writes: frontmatter, then the body. Re-create a page with `oxygen knowledge page upsert --slug --title --type --tags --body`, taking each value from its file.",
45
+ workflows: "oxygen workflows import --file workflows/<workflow>.oxygen-workflow.json (create-only, disabled). A .stored.json file is a legacy recipe or step workflow's stored definition and a .draft.json file the newest unpublished revision, kept for reference.",
46
+ };
47
+ // The refusals that mean "not with this login" rather than "broken".
48
+ const LOGIN_REFUSALS = new Set(["api_key_read_only", "insufficient_role"]);
49
+ function isLoginRefusal(error) {
50
+ return error instanceof OxygenError && LOGIN_REFUSALS.has(error.code);
51
+ }
52
+ /** `--only` → parts, accepting `do-not-contact` for `do_not_contact`. */
53
+ export function readWorkspaceExportParts(value) {
54
+ if (value === undefined)
55
+ return [...WORKSPACE_EXPORT_PARTS];
56
+ const requested = value.split(",").map((entry) => entry.trim().toLowerCase().replace(/-/g, "_")).filter(Boolean);
57
+ const unknown = requested.filter((entry) => !WORKSPACE_EXPORT_PARTS.includes(entry));
58
+ if (requested.length === 0 || unknown.length > 0) {
59
+ throw new OxygenError("invalid_option", `--only takes a comma-separated list of: ${WORKSPACE_EXPORT_PARTS.join(", ")}.`, {
60
+ details: { only: value, unknown, allowed: [...WORKSPACE_EXPORT_PARTS] },
61
+ exitCode: 2,
62
+ });
63
+ }
64
+ return WORKSPACE_EXPORT_PARTS.filter((part) => requested.includes(part));
65
+ }
66
+ export async function exportWorkspace(options, dependencies = {}) {
67
+ const dir = resolve(options.output);
68
+ // Refuse before any request: an export never mixes into, or overwrites, files already there.
69
+ assertExportTarget(dir);
70
+ const progress = options.progress ?? (() => undefined);
71
+ const request = retryingRead(dependencies.request ?? requestOxygen, dependencies.wait ?? ((ms) => delay(ms)), progress);
72
+ const now = dependencies.now ?? (() => new Date());
73
+ const startedAt = now().toISOString();
74
+ const whoami = await request("/api/cli/whoami");
75
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
76
+ const context = { dir, request, progress, failures: [], unavailable: [] };
77
+ const parts = {};
78
+ for (const part of WORKSPACE_EXPORT_PARTS) {
79
+ if (!options.parts.includes(part)) {
80
+ parts[part] = { status: "skipped", reason: "not selected with --only" };
81
+ continue;
82
+ }
83
+ progress(`${part}: exporting`);
84
+ const failuresBefore = context.failures.length;
85
+ const unavailableBefore = context.unavailable.length;
86
+ try {
87
+ const summary = await PART_EXPORTERS[part](context);
88
+ const failed = context.failures.length - failuresBefore;
89
+ const unavailable = context.unavailable.length - unavailableBefore;
90
+ parts[part] = {
91
+ status: failed > 0 ? "partial" : "exported",
92
+ ...summary,
93
+ ...(failed > 0 ? { failed } : {}),
94
+ ...(unavailable > 0 ? { unavailable } : {}),
95
+ };
96
+ progress(`${part}: ${summary.count} exported${failed > 0 ? `, ${failed} failed` : ""}${unavailable > 0 ? `, ${unavailable} not readable with this login` : ""}`);
97
+ }
98
+ catch (error) {
99
+ recordFailure(context, part, undefined, error);
100
+ const refused = isLoginRefusal(error);
101
+ parts[part] = { status: refused ? "unavailable" : "failed", count: 0 };
102
+ progress(`${part}: ${refused ? "not readable with this login" : "failed"} (${describeFailure(error).message})`);
103
+ }
104
+ }
105
+ const selectedEveryPart = WORKSPACE_EXPORT_PARTS.every((part) => options.parts.includes(part));
106
+ // Complete means the whole workspace: a subset, or a part this login may not
107
+ // read, is not a full backup even though nothing failed.
108
+ const complete = context.failures.length === 0 && context.unavailable.length === 0 && selectedEveryPart;
109
+ const manifestPath = join(dir, "manifest.json");
110
+ // Written last, and only here: a folder without manifest.json is an interrupted export.
111
+ writeJson(manifestPath, {
112
+ format: WORKSPACE_EXPORT_FORMAT,
113
+ format_version: WORKSPACE_EXPORT_FORMAT_VERSION,
114
+ complete,
115
+ ...(selectedEveryPart ? {} : { only: [...options.parts] }),
116
+ workspace: {
117
+ id: whoami.organization?.id ?? null,
118
+ name: whoami.organization?.name ?? null,
119
+ slug: whoami.organization?.slug ?? null,
120
+ },
121
+ exported_by_cli: OXYGEN_VERSION,
122
+ started_at: startedAt,
123
+ finished_at: now().toISOString(),
124
+ parts,
125
+ failures: context.failures,
126
+ unavailable: context.unavailable,
127
+ not_included: WORKSPACE_EXPORT_NOT_INCLUDED,
128
+ restore: RESTORE_HINTS,
129
+ });
130
+ const summary = {
131
+ output: dir,
132
+ manifest: manifestPath,
133
+ complete,
134
+ parts: Object.fromEntries(Object.entries(parts).map(([part, value]) => [part, {
135
+ status: value.status,
136
+ ...(typeof value.count === "number" ? { count: value.count } : {}),
137
+ ...(typeof value.rows === "number" ? { rows: value.rows } : {}),
138
+ }])),
139
+ ...(context.unavailable.length > 0 ? { unavailable: context.unavailable } : {}),
140
+ not_included: WORKSPACE_EXPORT_NOT_INCLUDED.map((entry) => entry.what),
141
+ credits_used: 0,
142
+ };
143
+ if (context.failures.length > 0) {
144
+ throw new OxygenError("workspace_export_incomplete", `The export finished with ${context.failures.length} failed item(s); everything else is written. manifest.json lists each failure. Re-run into a new folder to try again, or with --only for the failed parts.`, { details: { ...summary, failures: context.failures.slice(0, 20), failure_count: context.failures.length }, exitCode: 1 });
145
+ }
146
+ return summary;
147
+ }
148
+ const PART_EXPORTERS = {
149
+ tables: exportTables,
150
+ // The CRM model the record tables sit on: fields, identities, relationships, layouts.
151
+ crm: (context) => exportSingleRead(context, "crm-objects.json", "/api/cli/crm/objects", "objects"),
152
+ knowledge: exportKnowledge,
153
+ workflows: exportWorkflows,
154
+ sequences: exportSequences,
155
+ dashboards: exportDashboards,
156
+ tags: (context) => exportSingleRead(context, "tags.json", "/api/cli/tags", "tags"),
157
+ folders: (context) => exportSingleRead(context, "folders.json", "/api/cli/projects", "projects"),
158
+ do_not_contact: exportDoNotContact,
159
+ settings: exportSettings,
160
+ };
161
+ // Every table, CRM objects included (they are object-backed tables), one
162
+ // bundle each — the same file `tables export-bundle --output` writes.
163
+ async function exportTables(context) {
164
+ const tables = await listEveryTable(context.request);
165
+ const directory = join(context.dir, "tables");
166
+ mkdirSync(directory);
167
+ const claimStem = stemNamer();
168
+ const files = [];
169
+ let rows = 0;
170
+ for (const [index, table] of tables.entries()) {
171
+ const label = table.slug ?? table.id;
172
+ context.progress(`tables ${index + 1}/${tables.length}: ${table.displayName ?? label}`);
173
+ const file = `${claimStem(label, table.id)}.jsonl`;
174
+ try {
175
+ const result = await exportTableBundle(table.id, { output: join(directory, file) }, context.request);
176
+ const rowCount = typeof result.row_count === "number" ? result.row_count : 0;
177
+ rows += rowCount;
178
+ // Bundles carry columns and rows only; the table's tags and folder stay here.
179
+ files.push({
180
+ file: `tables/${file}`, id: table.id, slug: table.slug ?? null, name: table.displayName ?? null, kind: table.kind ?? null,
181
+ rows: rowCount, tags: table.tags ?? [], folder: folderOf(table),
182
+ });
183
+ }
184
+ catch (error) {
185
+ recordFailure(context, "tables", label, error);
186
+ }
187
+ }
188
+ return { count: files.length, listed: tables.length, rows, files };
189
+ }
190
+ // The folder's public identity only: the listing also carries its internal schema name.
191
+ function folderOf(table) {
192
+ const project = table.project;
193
+ if (project && typeof project === "object" && !Array.isArray(project)) {
194
+ const { id, slug, displayName, name } = project;
195
+ return { id: id ?? null, slug: slug ?? null, name: displayName ?? name ?? null };
196
+ }
197
+ return table.projectId ? { id: table.projectId, slug: null, name: null } : null;
198
+ }
199
+ async function listEveryTable(request) {
200
+ const tables = [];
201
+ let cursor = null;
202
+ for (;;) {
203
+ const params = new URLSearchParams({ all: "true" });
204
+ if (cursor)
205
+ params.set("cursor", cursor);
206
+ const page = await request(`/api/cli/tables?${params.toString()}`);
207
+ tables.push(...(page.tables ?? []));
208
+ if (!page.capped)
209
+ return tables;
210
+ if (!page.nextCursor || page.nextCursor === cursor) {
211
+ throw new OxygenError("workspace_export_list_stalled", "The table list said it holds more tables but returned no cursor to read them.", {
212
+ details: { listed: tables.length },
213
+ exitCode: 1,
214
+ });
215
+ }
216
+ cursor = page.nextCursor;
217
+ }
218
+ }
219
+ const KNOWLEDGE_EXPORT_MAX_BATCHES = 10_000;
220
+ // Every live wiki page as the markdown file `oxygen knowledge sync` writes,
221
+ // rendered here from the page read. Not through the sync delta: its first
222
+ // batch seeds the starter wiki, and an export creates nothing. The manifest
223
+ // and page reads are also the ones a read-only key and a client login may make.
224
+ async function exportKnowledge(context) {
225
+ const directory = join(context.dir, "knowledge");
226
+ mkdirSync(directory);
227
+ const slugs = await listLiveKnowledgeSlugs(context.request);
228
+ let count = 0;
229
+ for (const slug of slugs) {
230
+ try {
231
+ const read = await context.request(`/api/cli/knowledge/pages/get?${new URLSearchParams({ slug, include_links: "false" }).toString()}`);
232
+ const page = read.page;
233
+ // Archived or deleted since the manifest was read.
234
+ if (!page || page.status === "archived")
235
+ continue;
236
+ const markdown = renderKnowledgePageMarkdown({
237
+ id: page.id, slug: page.slug, type: page.type, title: page.title, status: page.status, tags: page.tags ?? [],
238
+ canonical: page.isCanonical === true, summary: page.summary ?? null, revision: page.revision,
239
+ updatedAt: new Date(page.updatedAt).toISOString(), webUrl: read.web_url ?? "", data: page.data ?? {}, body: page.body ?? null,
240
+ });
241
+ const path = pageFilePath(directory, page.slug);
242
+ writeFileSync(isReservedFileStem(page.slug) ? join(directory, `_${page.slug}.md`) : path, markdown, { encoding: "utf8", flag: "wx" });
243
+ count += 1;
244
+ }
245
+ catch (error) {
246
+ recordFailure(context, "knowledge", slug, error);
247
+ }
248
+ }
249
+ return { count, listed: slugs.length };
250
+ }
251
+ async function listLiveKnowledgeSlugs(request) {
252
+ const slugs = [];
253
+ let cursor = null;
254
+ for (let batch = 0; batch < KNOWLEDGE_EXPORT_MAX_BATCHES; batch += 1) {
255
+ const manifest = await request("/api/cli/knowledge/sync/manifest", {
256
+ method: "POST",
257
+ body: cursor ? { cursor } : {},
258
+ });
259
+ for (const page of manifest.pages ?? []) {
260
+ // Archived and slug-less pages are tombstones.
261
+ if (page.slug && page.status !== "archived")
262
+ slugs.push(page.slug);
263
+ }
264
+ if (!manifest.has_more)
265
+ return [...new Set(slugs)];
266
+ if (!manifest.next_cursor || manifest.next_cursor === cursor) {
267
+ throw new OxygenError("knowledge_sync_stalled", "The wiki cursor did not advance between batches; stopped to avoid a loop.", {
268
+ details: { cursor, listed: slugs.length },
269
+ exitCode: 1,
270
+ });
271
+ }
272
+ cursor = manifest.next_cursor;
273
+ }
274
+ throw new OxygenError("knowledge_sync_incomplete", "The wiki held more batches than one export reads.", {
275
+ details: { batch_cap: KNOWLEDGE_EXPORT_MAX_BATCHES, listed: slugs.length },
276
+ exitCode: 1,
277
+ });
278
+ }
279
+ // Graph workflows as the portable definition `workflows import` installs
280
+ // (source account ids and trigger authority removed). Legacy recipe and step
281
+ // workflows cannot be made portable, so their stored definition is kept as is.
282
+ // A workflow never published, or edited since, has its newest saved revision
283
+ // only in the revision history, so that is written beside it as a draft.
284
+ async function exportWorkflows(context) {
285
+ const list = await context.request("/api/cli/workflows?all=true");
286
+ const workflows = list.workflows ?? [];
287
+ const directory = join(context.dir, "workflows");
288
+ mkdirSync(directory);
289
+ const claimStem = stemNamer();
290
+ let count = 0;
291
+ let portable = 0;
292
+ let stored = 0;
293
+ let drafts = 0;
294
+ for (const workflow of workflows) {
295
+ const label = workflow.slug ?? workflow.id;
296
+ const stem = claimStem(label, workflow.id);
297
+ try {
298
+ const read = await context.request("/api/cli/workflows/get", { method: "POST", body: { workflow: workflow.id } });
299
+ const definition = read.workflow ?? {};
300
+ let written = false;
301
+ if (definition.manifest) {
302
+ const exported = workflow.format === "graph" ? await readPortableWorkflow(context.request, workflow.id) : null;
303
+ if (exported) {
304
+ writeJson(join(directory, `${stem}.oxygen-workflow.json`), exported);
305
+ portable += 1;
306
+ }
307
+ else {
308
+ writeJson(join(directory, `${stem}.stored.json`), definition);
309
+ stored += 1;
310
+ }
311
+ written = true;
312
+ }
313
+ if (!definition.manifest || definition.draftRevision) {
314
+ const history = await context.request(`/api/cli/workflows/revisions?${new URLSearchParams({ workflow: workflow.id, limit: "1", include_manifest: "true" }).toString()}`);
315
+ const newest = history.revisions?.[0];
316
+ if (newest?.manifest) {
317
+ writeJson(join(directory, `${stem}.draft.json`), { workflow: { id: workflow.id, slug: workflow.slug ?? null, name: workflow.name ?? null }, revision: newest });
318
+ drafts += 1;
319
+ written = true;
320
+ }
321
+ }
322
+ if (!written)
323
+ throw new OxygenError("workflow_definition_missing", "The workflow has no published definition and no saved revision to export.");
324
+ count += 1;
325
+ }
326
+ catch (error) {
327
+ recordFailure(context, "workflows", label, error);
328
+ }
329
+ }
330
+ return { count, listed: workflows.length, portable, stored, drafts };
331
+ }
332
+ async function readPortableWorkflow(request, workflow) {
333
+ try {
334
+ const data = await request("/api/cli/workflows/export", { method: "POST", body: { workflow } });
335
+ return data.definition ?? null;
336
+ }
337
+ catch (error) {
338
+ // A graph-listed workflow whose current revision is still legacy, or a login
339
+ // that may read the stored definition but not request the portable one.
340
+ if (isLoginRefusal(error) || (error instanceof OxygenError && error.code === "workflow_export_requires_editable_graph"))
341
+ return null;
342
+ throw error;
343
+ }
344
+ }
345
+ async function exportSequences(context) {
346
+ const list = await context.request("/api/cli/sequences?view=summary");
347
+ const sequences = list.sequences ?? [];
348
+ const total = typeof list.fleet?.total === "number" ? list.fleet.total : sequences.length;
349
+ if (total > sequences.length) {
350
+ recordFailure(context, "sequences", undefined, new OxygenError("sequence_list_capped", `The sequence list returned ${sequences.length} of ${total} sequences; the rest were not exported.`));
351
+ }
352
+ return exportEach(context, "sequences", sequences, async (sequence) => context.request(`/api/cli/sequences/${encodeURIComponent(sequence.id)}`));
353
+ }
354
+ async function exportDashboards(context) {
355
+ const list = await context.request("/api/cli/dashboards");
356
+ return exportEach(context, "dashboards", list.dashboards ?? [], async (dashboard) => {
357
+ const data = await context.request(`/api/cli/dashboards/${encodeURIComponent(dashboard.id)}`);
358
+ return data.dashboard ?? data;
359
+ });
360
+ }
361
+ async function exportEach(context, part, items, read) {
362
+ const directory = join(context.dir, part);
363
+ mkdirSync(directory);
364
+ const claimStem = stemNamer();
365
+ let count = 0;
366
+ for (const item of items) {
367
+ const label = item.slug ?? item.id;
368
+ try {
369
+ writeJson(join(directory, `${claimStem(label, item.id)}.json`), await read(item));
370
+ count += 1;
371
+ }
372
+ catch (error) {
373
+ recordFailure(context, part, label, error);
374
+ }
375
+ }
376
+ return { count, listed: items.length };
377
+ }
378
+ async function exportSingleRead(context, file, path, listKey) {
379
+ const data = await context.request(path);
380
+ writeJson(join(context.dir, file), stripLinks(data));
381
+ const list = data[listKey];
382
+ return { count: Array.isArray(list) ? list.length : 0, file };
383
+ }
384
+ const DO_NOT_CONTACT_LISTS = [
385
+ { name: "leads", path: "/api/cli/suppressions", key: "suppressions" },
386
+ { name: "addresses", path: "/api/cli/suppressions/addresses", key: "address_suppressions" },
387
+ { name: "domains", path: "/api/cli/suppressions/domains", key: "domain_suppressions" },
388
+ { name: "companies", path: "/api/cli/suppressions/companies", key: "company_suppressions" },
389
+ { name: "phones", path: "/api/cli/suppressions/phones", key: "phone_suppressions" },
390
+ ];
391
+ const DO_NOT_CONTACT_PAGE_SIZE = 500;
392
+ const DO_NOT_CONTACT_MAX_PAGES = 20_000;
393
+ // The five do-not-contact lists, each read page by page until a page comes back
394
+ // empty: stopping on a short page would trust a page size the route may cap lower.
395
+ async function exportDoNotContact(context) {
396
+ const directory = join(context.dir, "do-not-contact");
397
+ mkdirSync(directory);
398
+ const counts = {};
399
+ for (const list of DO_NOT_CONTACT_LISTS) {
400
+ try {
401
+ const { entries, repeated } = await readEveryPage(context.request, list.path, list.key);
402
+ writeJson(join(directory, `${list.name}.json`), { list: list.name, count: entries.length, entries });
403
+ counts[list.name] = entries.length;
404
+ if (repeated > 0) {
405
+ throw new OxygenError("workspace_export_list_unstable", `${repeated} ${list.name} entries came back twice while paging, so others may have been skipped. Re-run the export.`, {
406
+ details: { list: list.name, read: entries.length, repeated },
407
+ exitCode: 1,
408
+ });
409
+ }
410
+ }
411
+ catch (error) {
412
+ recordFailure(context, "do_not_contact", list.name, error);
413
+ }
414
+ }
415
+ return { count: Object.values(counts).reduce((sum, value) => sum + value, 0), lists: counts };
416
+ }
417
+ async function readEveryPage(request, path, key) {
418
+ const entries = [];
419
+ const seen = new Set();
420
+ let offset = 0;
421
+ let repeated = 0;
422
+ let previousFirst = null;
423
+ for (let page = 0; page < DO_NOT_CONTACT_MAX_PAGES; page += 1) {
424
+ const params = new URLSearchParams({ limit: String(DO_NOT_CONTACT_PAGE_SIZE), offset: String(offset) });
425
+ const data = await request(`${path}?${params.toString()}`);
426
+ const rows = Array.isArray(data[key]) ? data[key] : [];
427
+ if (rows.length === 0)
428
+ return { entries, repeated };
429
+ const first = JSON.stringify(rows[0]);
430
+ // A route that ignored the offset would hand back the same page forever.
431
+ if (first === previousFirst) {
432
+ throw new OxygenError("workspace_export_list_stalled", `${path} returned the same page twice; stopped to avoid a loop.`, {
433
+ details: { path, read: entries.length, offset },
434
+ exitCode: 1,
435
+ });
436
+ }
437
+ previousFirst = first;
438
+ offset += rows.length;
439
+ for (const row of rows) {
440
+ const id = row && typeof row === "object" && typeof row.id === "string" ? row.id : JSON.stringify(row);
441
+ if (seen.has(id)) {
442
+ repeated += 1;
443
+ continue;
444
+ }
445
+ seen.add(id);
446
+ entries.push(row);
447
+ }
448
+ }
449
+ throw new OxygenError("workspace_export_list_stalled", `${path} held more pages than one export reads.`, {
450
+ details: { path, read: entries.length },
451
+ exitCode: 1,
452
+ });
453
+ }
454
+ const SETTINGS_SOURCES = [
455
+ { name: "beta_features", path: "/api/cli/settings/beta-features" },
456
+ { name: "do_not_contact_policy", path: "/api/cli/suppressions/policy" },
457
+ { name: "approval_gates", path: "/api/cli/collab/gates" },
458
+ { name: "spend_budgets", path: "/api/cli/budget" },
459
+ ];
460
+ // Readable workspace-wide settings; personal ones (sidebar pages) stay out.
461
+ async function exportSettings(context) {
462
+ const settings = {};
463
+ for (const source of SETTINGS_SOURCES) {
464
+ try {
465
+ settings[source.name] = stripLinks(await context.request(source.path));
466
+ }
467
+ catch (error) {
468
+ recordFailure(context, "settings", source.name, error);
469
+ }
470
+ }
471
+ writeJson(join(context.dir, "settings.json"), settings);
472
+ return { count: Object.keys(settings).length, sections: Object.keys(settings) };
473
+ }
474
+ // ---------------------------------------------------------------------------
475
+ const READ_RETRY_ATTEMPTS = 6;
476
+ // An hourly read budget can ask for a long wait; a daily one is past saving here.
477
+ const RATE_LIMIT_MAX_WAIT_SECONDS = 15 * 60;
478
+ const TRANSIENT_READ_FAILURES = new Set(["network_error", "network_timeout", "invalid_response"]);
479
+ /**
480
+ * Every export call is a read, so a rate limit or a dropped connection is
481
+ * waited out and retried instead of failing a long export. Anything else
482
+ * surfaces at once.
483
+ */
484
+ export function retryingRead(request, wait, progress) {
485
+ return async function read(path, options) {
486
+ for (let attempt = 1;; attempt += 1) {
487
+ try {
488
+ return await request(path, options);
489
+ }
490
+ catch (error) {
491
+ const seconds = retryDelaySeconds(error, attempt);
492
+ if (seconds === null)
493
+ throw error;
494
+ progress(`waiting ${seconds}s, then retrying ${path.split("?")[0]} (${error.code})`);
495
+ await wait(seconds * 1000);
496
+ }
497
+ }
498
+ };
499
+ }
500
+ function retryDelaySeconds(error, attempt) {
501
+ if (!(error instanceof OxygenError) || attempt >= READ_RETRY_ATTEMPTS)
502
+ return null;
503
+ if (error.code === "rate_limit_exceeded") {
504
+ const after = readRetryAfterSeconds(error.details);
505
+ if (after === null)
506
+ return Math.min(5 * 2 ** (attempt - 1), 60);
507
+ return after <= RATE_LIMIT_MAX_WAIT_SECONDS ? Math.max(1, after) : null;
508
+ }
509
+ const retryable = TRANSIENT_READ_FAILURES.has(error.code)
510
+ || (Boolean(error.details) && typeof error.details === "object" && error.details.retryable === true);
511
+ return retryable ? Math.min(2 * 2 ** (attempt - 1), 30) : null;
512
+ }
513
+ function readRetryAfterSeconds(details) {
514
+ if (!details || typeof details !== "object" || Array.isArray(details))
515
+ return null;
516
+ const value = details.retry_after_seconds;
517
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.ceil(value) : null;
518
+ }
519
+ function assertExportTarget(dir) {
520
+ if (!existsSync(dir))
521
+ return;
522
+ if (!statSync(dir).isDirectory() || readdirSync(dir).length > 0) {
523
+ throw new OxygenError("workspace_export_output_not_empty", `Refusing to export into '${dir}': it is not an empty folder. Pass a new or empty folder.`, {
524
+ details: { output: dir },
525
+ exitCode: 2,
526
+ });
527
+ }
528
+ }
529
+ function recordFailure(context, part, item, error) {
530
+ (isLoginRefusal(error) ? context.unavailable : context.failures).push({ part, ...(item ? { item } : {}), ...describeFailure(error) });
531
+ }
532
+ function describeFailure(error) {
533
+ if (error instanceof OxygenError)
534
+ return { code: error.code, message: error.message };
535
+ return { code: "unknown", message: error instanceof Error ? error.message : String(error) };
536
+ }
537
+ /** Unique, filesystem-safe file stems within one folder: the slug, else slug + id. */
538
+ function stemNamer() {
539
+ const used = new Set();
540
+ return (preferred, id) => {
541
+ const base = safeFileStem(preferred);
542
+ let stem = base;
543
+ if (used.has(stem))
544
+ stem = `${base}-${safeFileStem(id).slice(0, 12)}`;
545
+ for (let index = 2; used.has(stem); index += 1)
546
+ stem = `${base}-${index}`;
547
+ used.add(stem);
548
+ return stem;
549
+ };
550
+ }
551
+ function safeFileStem(value) {
552
+ const stem = value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, 120) || "item";
553
+ return isReservedFileStem(stem) ? `_${stem}` : stem;
554
+ }
555
+ // Windows refuses these names whatever the extension.
556
+ function isReservedFileStem(stem) {
557
+ return /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/.test(stem.split(".")[0] ?? "");
558
+ }
559
+ const LINK_KEYS = new Set(["deepLink", "deep_link", "web_url"]);
560
+ function stripLinks(data) {
561
+ return Object.fromEntries(Object.entries(data).filter(([key]) => !LINK_KEYS.has(key)));
562
+ }
563
+ function writeJson(path, value) {
564
+ writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
565
+ }
@@ -1,5 +1,6 @@
1
1
  import { requestOxygen } from "../http-client.js";
2
2
  import { readOption } from "../util.js";
3
+ import { WORKSPACE_EXPORT_PARTS, exportWorkspace, readWorkspaceExportParts } from "./workspace-export.js";
3
4
  import { Command } from "commander";
4
5
  // The map is bounded twice over — a scan window per kind, then a character
5
6
  // budget across all of them — and both bounds are invisible in the rendered
@@ -47,7 +48,7 @@ export function registerWorkspaceFamily(program, handleAsyncAction) {
47
48
  // compositions over reads the primitives already own — neither is a primitive.
48
49
  const workspaceCommand = program
49
50
  .command("workspace")
50
- .description("Inspect this workspace or end its managed external infrastructure.")
51
+ .description("Inspect this workspace, export a full copy of it, or end its managed external infrastructure.")
51
52
  .addHelpText("before", "\nActive workspace and identity: oxygen whoami --summary-json (read-only, 0 credits).\n")
52
53
  .addCommand(new Command("map")
53
54
  .description("What this workspace actually contains: the newest tables, CRM objects, sequences, workflows, agents, wiki pages, posts and projects, each with its id, last activity, tags and link, plus your Oxygents, group chats and Copilot chats where the Copilot is yours. With --query it also searches CRM records and inbox conversations. Read-only, 0 credits. Capability search tells you what OXYGEN can do; this tells you what is here.")
@@ -75,6 +76,28 @@ export function registerWorkspaceFamily(program, handleAsyncAction) {
75
76
  return data;
76
77
  });
77
78
  }));
79
+ // One step instead of an export per table, workflow and list (Plain T-366).
80
+ workspaceCommand.addCommand(new Command("export")
81
+ .description("Copy this whole workspace into one local folder, for a backup or before leaving OXYGEN: every table (CRM companies, people and deals included) as a bundle `tables import-bundle` restores, the CRM object definitions, every wiki page as markdown, workflows, sequences, dashboards, tags, folders, the do-not-contact lists and readable settings, plus manifest.json saying what was and was not exported. Read-only, 0 credits; connections and the credentials OXYGEN stores (API keys, OAuth tokens, mailbox passwords) are never exported.")
82
+ .requiredOption("--output <dir>", "A new or empty folder to write the export into. Never merges into or overwrites existing files.")
83
+ .option("--only <parts>", `Export only these comma-separated parts: ${WORKSPACE_EXPORT_PARTS.join(", ")}. Defaults to every part.`)
84
+ .option("--json", "Print a JSON envelope.")
85
+ .addHelpText("after", `
86
+ Layout: manifest.json, tables/<table>.jsonl, crm-objects.json, knowledge/<page>.md, workflows/<workflow>.oxygen-workflow.json (a legacy recipe or step workflow is <workflow>.stored.json, its stored definition, and unpublished work is <workflow>.draft.json), sequences/<sequence>.json, dashboards/<dashboard>.json, tags.json, folders.json, do-not-contact/<list>.json and settings.json.
87
+
88
+ Restore a table with \`oxygen tables import-bundle --file <file>\` and a graph workflow with \`oxygen workflows import --file <file>\` (create-only, disabled).
89
+
90
+ A large workspace takes a while: tables stream row by row, and a rate-limited or dropped read waits and retries. A failed item does not stop the export: manifest.json lists it and the command exits non-zero. A part this login may not read (a read-only key, a client login) is listed as unavailable instead. manifest.json says complete: true only when every part was selected and read; the exit code is non-zero only when something failed, so check complete before relying on a copy as a full backup. A folder without manifest.json is an interrupted export.
91
+
92
+ Not exported: connections and their stored credentials, Unibox conversations, sequence enrollments and send history, CRM notes, tasks and files, links between tables, saved views, feeds and webhooks, prompt templates, Functions, custom HTTP integrations, sender profiles, members and roles, archived tables and wiki pages, the wiki's activity log and earlier page revisions, agents, posts, signals and ads. A secret typed into a column or workflow definition is part of that definition and is exported as written. manifest.json names each gap.
93
+ `)
94
+ .action(async (options) => {
95
+ await handleAsyncAction("workspace export", options, () => exportWorkspace({
96
+ output: options.output,
97
+ parts: readWorkspaceExportParts(options.only),
98
+ ...(options.json ? {} : { progress: (line) => process.stderr.write(`${line}\n`) }),
99
+ }));
100
+ }));
78
101
  workspaceCommand.addCommand(new Command("infrastructure-exit")
79
102
  .description("Leave, close or offboard a workspace's managed external infrastructure in one action. Preview every renewing resource and its release-timing note, then with --approved stop renewals and begin provider teardown. Known paid terms are honored; some dates are estimated or unavailable. Sending connections are disconnected; records and history remain. Requires an exact workspace confirmation and the fresh preview hash. Free, 0 credits.")
80
103
  .option("--approved", "Begin the approved teardown.")
package/dist/help.js CHANGED
@@ -187,7 +187,12 @@ export function applyOxygenHelp(program, binaryName, docsUrl = "https://oxygen-a
187
187
  "Conventions:",
188
188
  " --json prints a stable envelope {ok, data|error, meta}; errors always print it.",
189
189
  " Free Sequence launch previews omit --approved and --max-credits.",
190
- " Credit-spending commands require --approved --max-credits <n>.",
190
+ // Not every paid command takes --approved: one-off finds and email checks
191
+ // spend under --mode live and a ceiling, and a table auto-run under its own
192
+ // or the plan's default ceiling (find-run-mode.ts, tables/auto-run route).
193
+ " Paid runs (tools run, columns run, enrich-column run, crm sync run) require",
194
+ " --approved and a --max-credits <n> ceiling. The find and verify email commands",
195
+ " spend with --mode live --max-credits <n> instead; for others, read their --help.",
191
196
  " Zero-credit external writes require --approved; supply a preview-bound plan",
192
197
  " token when the command requires one (see its preview and --help).",
193
198
  " State-changing responses include a web_url deep-link to inspect the result.",