@dotdrelle/wiki-manager 0.15.41 → 0.15.43

package/src/core/toolLoop.test.js

@@ -86,3 +86,98 @@ test('propagates an abort thrown by executeCall', async () => {
     /aborted/,
   );
 });
+
+// Le tour paraissait figé pendant toute sa durée : la réponse n'apparaissait
+// qu'une fois complète, parce que la boucle n'appelait que completeWithTools.
+test('streams the answer when the caller asks for deltas', async () => {
+  const deltas = [];
+  const llm = {
+    async completeWithTools() { throw new Error('streamWithTools devait être préféré'); },
+    async streamWithTools({ onTextDelta }) {
+      onTextDelta('Le wiki ');
+      onTextDelta('contient 12 pages.');
+      return { content: 'Le wiki contient 12 pages.', tool_calls: [] };
+    },
+  };
+
+  const out = await runBoundedToolLoop({
+    llm,
+    tools: [],
+    executeCall: async () => 'unused',
+    onTextDelta: (delta) => deltas.push(delta),
+  });
+
+  assert.deepEqual(deltas, ['Le wiki ', 'contient 12 pages.']);
+  assert.equal(out.content, 'Le wiki contient 12 pages.');
+});
+
+test('keeps the non-streaming path when no delta callback is given', async () => {
+  let streamed = false;
+  const llm = {
+    async completeWithTools() { return { content: 'plain', tool_calls: [] }; },
+    async streamWithTools() { streamed = true; return { content: 'streamed', tool_calls: [] }; },
+  };
+
+  const out = await runBoundedToolLoop({ llm, tools: [], executeCall: async () => 'unused' });
+
+  assert.equal(streamed, false, 'sans onTextDelta, rien ne doit changer');
+  assert.equal(out.content, 'plain');
+});
+
+test('discards text emitted by an iteration that ends in tool calls', async () => {
+  // Un modèle peut écrire un raisonnement puis décider d'appeler un outil. Ce
+  // texte est remplacé par le tour suivant : le laisser afficherait des
+  // paragraphes qui disparaissent, pire que pas de streaming du tout.
+  let round = 0;
+  const deltas = [];
+  let resets = 0;
+  const llm = {
+    async streamWithTools({ onTextDelta }) {
+      round += 1;
+      if (round === 1) {
+        onTextDelta('Je vais regarder…');
+        const calls = [toolCall('c1', 'wiki__wiki_list_pages')];
+        return { message: { role: 'assistant', content: '', tool_calls: calls }, tool_calls: calls };
+      }
+      onTextDelta('12 pages.');
+      return { content: '12 pages.', tool_calls: [] };
+    },
+  };
+
+  const out = await runBoundedToolLoop({
+    llm,
+    tools: [],
+    executeCall: async () => 'ok',
+    onTextDelta: (delta) => deltas.push(delta),
+    onTextReset: () => { resets += 1; },
+  });
+
+  assert.deepEqual(deltas, ['Je vais regarder…', '12 pages.']);
+  assert.equal(resets, 1, 'le texte intermédiaire doit être annulé, une fois');
+  assert.equal(out.content, '12 pages.');
+});
+
+test('never asks to discard text that was never emitted', async () => {
+  let resets = 0;
+  let round = 0;
+  const llm = {
+    async streamWithTools() {
+      round += 1;
+      if (round === 1) {
+        const calls = [toolCall('c1', 'wiki__wiki_list_pages')];
+        return { message: { role: 'assistant', content: '', tool_calls: calls }, tool_calls: calls };
+      }
+      return { content: 'fini', tool_calls: [] };
+    },
+  };
+
+  await runBoundedToolLoop({
+    llm,
+    tools: [],
+    executeCall: async () => 'ok',
+    onTextDelta: () => {},
+    onTextReset: () => { resets += 1; },
+  });
+
+  assert.equal(resets, 0);
+});

package/src/core/wikiSetup.js

@@ -5,7 +5,8 @@ import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 import YAML from 'yaml';
 import { checkMissingDockerImages } from './dockerImages.js';
-import { patchWikircProfile } from './wikirc.js';
+import { loadWikircProfile, patchWikircProfile } from './wikirc.js';
+import { buildInheritedWikircPatch, copyCmeCredentials } from './workspaceInherit.js';
 import { resolveAgentsComposeContext } from './agentsCompose.js';
 import { managerEnvFile, managerMcpEndpointsFile, resolveAgentsDataDir } from './env.js';
 import { createWorkspace, findWorkspace, isValidWorkspaceName, listWorkspaces, managerRoot, workspacesDir } from './workspaces.js';
@@ -208,20 +209,62 @@ export async function refreshRunningContainers(options = {}) {
   return { skipped: false, refreshed, errors };
 }
 
-export async function createNewWorkspace(name, targetPath) {
+export async function createNewWorkspace(name, targetPath, options = {}) {
   try {
     const output = await createWorkspace(name, targetPath, { timeout: 600_000 });
-    const workspace = finalizeCreatedWorkspace(name);
-    return { output, workspace };
+    const { workspace, inherited } = await finalizeCreatedWorkspace(name, options);
+    return { output, workspace, inherited };
   } catch (err) {
     throw wrapDockerError(err);
   }
 }
 
-export function finalizeCreatedWorkspace(name) {
+/**
+ * @param options.inheritFrom name of the workspace to copy LLM config and CME
+ *   credentials from — normally the session's current workspace. Omitted, or
+ *   unknown, means "scaffold defaults only", the previous behaviour.
+ */
+export async function finalizeCreatedWorkspace(name, options = {}) {
   const workspace = findWorkspace(name);
-  if (workspace) initializeWorkspaceWikirc(workspace);
-  return workspace;
+  if (!workspace) return { workspace: null, inherited: [] };
+  // Order matters: the access key is this workspace's own credential and must
+  // land before anything else touches the file.
+  initializeWorkspaceWikirc(workspace);
+  const inherited = await inheritWorkspaceSetup(workspace, options.inheritFrom ?? null);
+  return { workspace, inherited };
+}
+
+/**
+ * Carry an existing workspace's proven setup over to a new one. Best effort by
+ * design: a workspace that exists and works must never fail to be created
+ * because the workspace next door has an unreadable config.
+ */
+export async function inheritWorkspaceSetup(workspace, sourceName) {
+  if (!workspace?.workspacePath || !sourceName || sourceName === workspace.name) return [];
+  const source = findWorkspace(sourceName);
+  if (!source?.workspacePath) return [];
+
+  const inherited = [];
+  try {
+    const { config: sourceConfig } = loadWikircProfile(source.workspacePath, 'default');
+    const { config: targetConfig } = loadWikircProfile(workspace.workspacePath, 'default');
+    const { patch, inherited: keys } = buildInheritedWikircPatch(sourceConfig, targetConfig);
+    if (keys.length > 0) {
+      patchWikircProfile(workspace.workspacePath, 'default', patch);
+      inherited.push(...keys);
+    }
+  } catch {
+    // Unreadable or absent profile on either side — nothing to inherit.
+  }
+
+  try {
+    const copied = await copyCmeCredentials(resolveAgentsDataDir(), source.name, workspace.name);
+    if (copied) inherited.push('cme.app_data.json');
+  } catch {
+    // Credentials are a convenience, not a prerequisite.
+  }
+
+  return inherited;
 }
 
 export function initializeWorkspaceWikirc(workspace) {

package/src/core/wikiWorkspace.test.js

@@ -105,3 +105,67 @@ test('container refresh pulls and renews only services that are already running'
   assert.match(script, /refresh_running_services 'No running external agent containers to refresh' 'Refreshed running agents: %s' _agents_dc/);
   assert.match(script, /refresh_running_services "No running workspace containers to refresh: \$workspace" "Refreshed running workspace containers: \$workspace \(%s\)" compose_for_workspace "\$workspace"/);
 });
+
+// `${arr[@]}` on an empty array is an unbound-variable error under `set -u` in
+// bash <= 4.3, and macOS still ships /bin/bash 3.2. `parse_global_options`
+// tripped on it, so `wiki-workspace` with no global option died before reaching
+// any subcommand.
+//
+// The execution check below cannot catch a regression on a CI running bash 5,
+// where an empty array is legal — hence the source assertion that every
+// optional array keeps the `${arr[@]+"${arr[@]}"}` guard. Both are needed.
+test('optional arrays keep the empty-array guard required by bash 3.2', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  for (const name of ['parsed', 'PARSED_ARGS', 'log_args']) {
+    const unguarded = new RegExp(String.raw`(?<!\+)"\$\{${name}\[@\]\}"`);
+    assert.doesNotMatch(script, unguarded, `${name}[@] must use the \${name[@]+"..."} guard`);
+  }
+  assert.match(script, /set -- \$\{parsed\[@\]\+"\$\{parsed\[@\]\}"\}/);
+  assert.match(script, /set -- \$\{PARSED_ARGS\[@\]\+"\$\{PARSED_ARGS\[@\]\}"\}/);
+});
+
+test('wiki-workspace reaches its usage text with no arguments', async () => {
+  const { spawnSync } = await import('node:child_process');
+  const scriptPath = new URL('../../wiki-workspace', import.meta.url).pathname;
+
+  const result = spawnSync('bash', [scriptPath], { encoding: 'utf8' });
+
+  assert.doesNotMatch(`${result.stdout}${result.stderr}`, /unbound variable/);
+  assert.match(result.stdout, /^Usage:/);
+  assert.equal(result.status, 2);
+});
+
+// `reset` deletes everything workspace_reset_keep rejects, and its very next
+// statement is `run_wiki … init`, which opens with need_workspace_env. If
+// `.env` ever falls out of the keep list, reset erases the workspace and then
+// dies before re-scaffolding it — and recovering with `config` mints new ports
+// and MCP tokens, invalidating every reference to the old ones. Exercise the
+// real function rather than asserting on the source text.
+test('workspace_reset_keep protects the workspace registration and method', async () => {
+  const { spawnSync } = await import('node:child_process');
+  const scriptPath = new URL('../../wiki-workspace', import.meta.url).pathname;
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+  const start = script.indexOf('workspace_reset_keep() {');
+  assert.notEqual(start, -1, 'workspace_reset_keep must exist');
+  const body = script.slice(start, script.indexOf('\n}', start) + 2);
+
+  const ask = (name) =>
+    spawnSync('bash', ['-c', `${body}\nworkspace_reset_keep "$1"`, '_', name]).status === 0;
+
+  for (const kept of ['.env', '.env.local', '.wikirc.yaml', '.wikirc.yaml.prod', 'templates', 'build-context', '.git']) {
+    assert.equal(ask(kept), true, `${kept} must survive a reset`);
+  }
+  for (const removed of ['wiki', 'deliverables', 'raw', '.wiki', 'CLAUDE.md', '.gitignore', '.environment']) {
+    assert.equal(ask(removed), false, `${removed} must be reset`);
+  }
+});
+
+test('reset re-scaffolds through run_wiki, which requires the workspace env', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  // The coupling the keep list depends on: if either half moves, revisit it.
+  assert.match(script, /run_wiki\(\) \{\n  local workspace="\$1"\n  shift\n  need_workspace_env "\$workspace"/);
+  assert.match(script, /run_wiki "\$workspace" init/);
+  assert.match(script, /workspace_env_file\(\) \{\n  local workspace="\$1"\n  printf '%s\/%s\/\.env\\n'/);
+});

package/src/core/wikirc.test.js

@@ -163,7 +163,7 @@ test('writeVectorConfig removes commented vector placeholders it replaces', () =
   assert.equal(parsed.retrieval.vector.apiKey, 'vector-key');
 });
 
-test('finalizeCreatedWorkspace copies generated wiki token into default wikirc', () => {
+test('finalizeCreatedWorkspace copies generated wiki token into default wikirc', async () => {
   const root = mkdtempSync(join(tmpdir(), 'wikirc-workspace-token-'));
   const registryRoot = join(root, 'registry');
   const registryPath = join(registryRoot, 'demo');
@@ -190,7 +190,7 @@ test('finalizeCreatedWorkspace copies generated wiki token into default wikirc',
   const previousDir = process.env.WIKI_WORKSPACES_DIR;
   process.env.WIKI_WORKSPACES_DIR = registryRoot;
   try {
-    const workspace = finalizeCreatedWorkspace('demo');
+    const { workspace } = await finalizeCreatedWorkspace('demo');
     const parsed = YAML.parse(readFileSync(join(workspacePath, '.wikirc.yaml'), 'utf8'));
 
     assert.equal(workspace.name, 'demo');
@@ -249,3 +249,122 @@ test('containerReachableUrl only touches loopback hosts', () => {
   assert.equal(containerReachableUrl('http://gateway:4000/v1').rewritten, false);
   assert.equal(containerReachableUrl(undefined).rewritten, false);
 });
+
+// /new used to leave the operator re-entering the same endpoint, key and model
+// they had just proven working in the workspace next door.
+test('finalizeCreatedWorkspace seeds a new workspace from the one in use', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'wikirc-inherit-'));
+  const registryRoot = join(root, 'registry');
+  const agentsData = join(root, '.agents-data');
+  const token = 'b'.repeat(64);
+
+  const makeWorkspace = (name, wikirc) => {
+    const registryPath = join(registryRoot, name);
+    const workspacePath = join(root, name);
+    mkdirSync(registryPath, { recursive: true });
+    mkdirSync(workspacePath, { recursive: true });
+    writeFileSync(join(registryPath, '.env'), [
+      `WORKSPACE_NAME=${name}`,
+      `WIKI_WORKSPACE_PATH=${workspacePath}`,
+      `WIKI_MCP_AUTH_TOKEN=${token}`,
+      '',
+    ].join('\n'), 'utf8');
+    writeFileSync(join(workspacePath, '.wikirc.yaml'), wikirc, 'utf8');
+    return workspacePath;
+  };
+
+  makeWorkspace('acpi', [
+    'language: en',
+    'llm:',
+    '  provider: ai-gateway',
+    '  engine: generic',
+    '  baseUrl: https://itsdonna.events/v1',
+    '  model: deepseek-v4-pro',
+    '  apiKey: sk-real-gateway-key',
+    'mcp:',
+    '  accessKey: ' + 'c'.repeat(64),
+    '',
+  ].join('\n'));
+
+  // Exactly what the scaffold writes: placeholders everywhere.
+  const targetPath = makeWorkspace('nouveau', [
+    'language: en',
+    'llm:',
+    '  provider: openai-compatible',
+    '  engine: generic',
+    '  baseUrl: https://mon-provider.example.com/v1',
+    '  model: YOUR_MODEL_NAME',
+    '  apiKey: YOUR_LLM_API_KEY',
+    'mcp:',
+    '  # accessKey: your-secret-key',
+    '',
+  ].join('\n'));
+
+  mkdirSync(join(agentsData, 'cme', 'acpi', 'cme'), { recursive: true });
+  writeFileSync(join(agentsData, 'cme', 'acpi', 'cme', 'app_data.json'), '{"pat":"x"}', 'utf8');
+
+  const previousDir = process.env.WIKI_WORKSPACES_DIR;
+  const previousData = process.env.AGENTS_DATA_DIR;
+  process.env.WIKI_WORKSPACES_DIR = registryRoot;
+  process.env.AGENTS_DATA_DIR = agentsData;
+  try {
+    const { inherited } = await finalizeCreatedWorkspace('nouveau', { inheritFrom: 'acpi' });
+    const parsed = YAML.parse(readFileSync(join(targetPath, '.wikirc.yaml'), 'utf8'));
+
+    assert.equal(parsed.llm.baseUrl, 'https://itsdonna.events/v1');
+    assert.equal(parsed.llm.model, 'deepseek-v4-pro');
+    assert.equal(parsed.llm.apiKey, 'sk-real-gateway-key');
+    assert.equal(parsed.llm.provider, 'ai-gateway');
+    // The workspace keeps ITS own MCP credential, written just before.
+    assert.equal(parsed.mcp.accessKey, token);
+    assert.ok(inherited.includes('llm.baseUrl'));
+    assert.ok(inherited.includes('cme.app_data.json'));
+    assert.equal(
+      readFileSync(join(agentsData, 'cme', 'nouveau', 'cme', 'app_data.json'), 'utf8'),
+      '{"pat":"x"}',
+    );
+  } finally {
+    if (previousDir === undefined) delete process.env.WIKI_WORKSPACES_DIR;
+    else process.env.WIKI_WORKSPACES_DIR = previousDir;
+    if (previousData === undefined) delete process.env.AGENTS_DATA_DIR;
+    else process.env.AGENTS_DATA_DIR = previousData;
+  }
+});
+
+test('finalizeCreatedWorkspace without a source keeps scaffold defaults', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'wikirc-noinherit-'));
+  const registryRoot = join(root, 'registry');
+  const registryPath = join(registryRoot, 'solo');
+  const workspacePath = join(root, 'solo');
+  const token = 'd'.repeat(64);
+  mkdirSync(registryPath, { recursive: true });
+  mkdirSync(workspacePath, { recursive: true });
+  writeFileSync(join(registryPath, '.env'), [
+    'WORKSPACE_NAME=solo',
+    `WIKI_WORKSPACE_PATH=${workspacePath}`,
+    `WIKI_MCP_AUTH_TOKEN=${token}`,
+    '',
+  ].join('\n'), 'utf8');
+  writeFileSync(join(workspacePath, '.wikirc.yaml'), [
+    'language: en',
+    'llm:',
+    '  baseUrl: https://mon-provider.example.com/v1',
+    'mcp:',
+    '  # accessKey: your-secret-key',
+    '',
+  ].join('\n'), 'utf8');
+
+  const previousDir = process.env.WIKI_WORKSPACES_DIR;
+  process.env.WIKI_WORKSPACES_DIR = registryRoot;
+  try {
+    const { inherited } = await finalizeCreatedWorkspace('solo');
+    const parsed = YAML.parse(readFileSync(join(workspacePath, '.wikirc.yaml'), 'utf8'));
+
+    assert.deepEqual(inherited, []);
+    assert.equal(parsed.llm.baseUrl, 'https://mon-provider.example.com/v1');
+    assert.equal(parsed.mcp.accessKey, token);
+  } finally {
+    if (previousDir === undefined) delete process.env.WIKI_WORKSPACES_DIR;
+    else process.env.WIKI_WORKSPACES_DIR = previousDir;
+  }
+});

package/src/core/workspaceInherit.js

@@ -0,0 +1,149 @@
+import { copyFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Config a freshly created workspace inherits from an existing one.
+ *
+ * A new workspace was scaffolded with placeholder values only
+ * (`YOUR_MODEL_NAME`, `https://mon-provider.example.com/v1`…), so the operator
+ * had to redo the whole LLM setup by hand — reachable endpoint, gateway key,
+ * model name, vector settings — every single time, for values they had already
+ * proven working next door. `/new` now carries them over.
+ *
+ * Two rules make this safe rather than merely convenient:
+ *
+ *   - Only ABSENT or PLACEHOLDER target values are filled. Anything the
+ *     scaffold or the operator already set for real is left alone, so this can
+ *     never overwrite a deliberate choice.
+ *   - `mcp.accessKey` is never inherited. It is the workspace's own credential
+ *     and `initializeWorkspaceWikirc` has already written the right one.
+ */
+
+// Kept identical to SetupWizard.tsx on purpose — the wizard applies the same
+// "a scaffolded value is not an answer" rule. `workspaceInherit.test.js`
+// asserts the two literals stay in sync.
+export const PLACEHOLDER_VALUE_RE = /YOUR_|<your|example\.com|infinity\.local/i;
+
+const INHERITED_LLM_KEYS = ['baseUrl', 'model', 'apiKey', 'temperature', 'timeoutMs'];
+
+// `provider` and `engine` describe HOW the endpoint in `baseUrl` behaves, so
+// they are bound to it rather than inherited on their own merit.
+//
+// The scaffold ships `provider: openai-compatible` / `engine: generic` as
+// defaults, and those are real values — not placeholders the fill rule would
+// replace. Inheriting a gateway's `baseUrl` while leaving them behind produced
+// a config claiming a direct openai-compatible server against an AI gateway:
+// exactly the conflation the provider/engine split was introduced to end.
+const ENDPOINT_BOUND_KEYS = ['provider', 'engine'];
+
+// `retrieval.vector` stays independent from `llm` but inherits provider/engine/
+// baseUrl/apiKey when absent, so only keys the source states EXPLICITLY are
+// worth carrying: copying an inherited value would freeze it and break the
+// link the source deliberately left open.
+const INHERITED_VECTOR_KEYS = [
+  'enabled',
+  'provider',
+  'engine',
+  'baseUrl',
+  'apiKey',
+  'embeddingModel',
+  'rerankerModel',
+];
+
+/** A value the operator actually chose, as opposed to scaffold filler. */
+export function isRealValue(value) {
+  if (value === null || value === undefined) return false;
+  if (typeof value === 'boolean' || typeof value === 'number') return true;
+  if (typeof value !== 'string') return false;
+  const text = value.trim();
+  return text.length > 0 && !PLACEHOLDER_VALUE_RE.test(text);
+}
+
+function inheritSection(sourceSection, targetSection, keys, prefix, patch, inherited) {
+  for (const key of keys) {
+    const from = sourceSection?.[key];
+    if (!isRealValue(from)) continue;
+    // Present AND real on the target: a deliberate value, never overwritten.
+    if (isRealValue(targetSection?.[key])) continue;
+    patch[key] = from;
+    inherited.push(`${prefix}.${key}`);
+  }
+}
+
+/**
+ * @param sourceConfig parsed `.wikirc.yaml` of the workspace to copy from
+ * @param targetConfig parsed `.wikirc.yaml` of the freshly created workspace
+ * @returns `{ patch, inherited }` — `patch` is shaped for `patchWikircProfile`
+ *   and is `{}` when there is nothing to carry over.
+ */
+export function buildInheritedWikircPatch(sourceConfig, targetConfig) {
+  const inherited = [];
+  const llm = {};
+  const vector = {};
+
+  inheritSection(sourceConfig?.llm, targetConfig?.llm, INHERITED_LLM_KEYS, 'llm', llm, inherited);
+  // Only once the endpoint itself has been taken over.
+  if (llm.baseUrl) {
+    for (const key of ENDPOINT_BOUND_KEYS) {
+      const from = sourceConfig?.llm?.[key];
+      if (!isRealValue(from) || from === targetConfig?.llm?.[key]) continue;
+      llm[key] = from;
+      inherited.push(`llm.${key}`);
+    }
+  }
+
+  inheritSection(
+    sourceConfig?.retrieval?.vector,
+    targetConfig?.retrieval?.vector,
+    INHERITED_VECTOR_KEYS,
+    'retrieval.vector',
+    vector,
+    inherited,
+  );
+
+  // The gateway key unlocks every provider behind it. If the vector endpoint
+  // ends up on a different host than the LLM one, an inherited apiKey would be
+  // sent there — the exact leak the wizard already refuses to create. Drop the
+  // inherited baseUrl rather than the key: staying on the LLM endpoint is the
+  // conservative default, and the operator can still point it elsewhere.
+  const effectiveLlmBaseUrl = llm.baseUrl ?? targetConfig?.llm?.baseUrl ?? sourceConfig?.llm?.baseUrl;
+  const effectiveVectorBaseUrl = vector.baseUrl ?? targetConfig?.retrieval?.vector?.baseUrl;
+  const hasOwnVectorKey = isRealValue(vector.apiKey ?? targetConfig?.retrieval?.vector?.apiKey);
+  if (effectiveVectorBaseUrl && effectiveVectorBaseUrl !== effectiveLlmBaseUrl && !hasOwnVectorKey) {
+    delete vector.baseUrl;
+    const index = inherited.indexOf('retrieval.vector.baseUrl');
+    if (index >= 0) inherited.splice(index, 1);
+  }
+
+  const patch = {};
+  if (Object.keys(llm).length > 0) patch.llm = llm;
+  if (Object.keys(vector).length > 0) patch.retrieval = { vector };
+  return { patch, inherited };
+}
+
+export function cmeCredentialsPath(agentsDataDir, workspaceName) {
+  return join(agentsDataDir, 'cme', workspaceName, 'cme', 'app_data.json');
+}
+
+/**
+ * Carry the Confluence credentials of an existing workspace over to a new one.
+ *
+ * `app_data.json` only — NOT `sources-manifest.yaml`. The credentials are a
+ * property of the operator's Confluence account and are identical everywhere;
+ * which spaces and pages a workspace exports is precisely what makes it a
+ * different workspace, and copying that would silently re-export someone
+ * else's scope on the first run.
+ */
+export async function copyCmeCredentials(agentsDataDir, sourceWorkspace, targetWorkspace) {
+  if (!agentsDataDir || !sourceWorkspace || !targetWorkspace) return null;
+  if (sourceWorkspace === targetWorkspace) return null;
+  const from = cmeCredentialsPath(agentsDataDir, sourceWorkspace);
+  const to = cmeCredentialsPath(agentsDataDir, targetWorkspace);
+  if (!existsSync(from)) return null;
+  // An existing target file is a real configuration; never clobber it.
+  if (existsSync(to)) return null;
+  await mkdir(join(agentsDataDir, 'cme', targetWorkspace, 'cme'), { recursive: true });
+  await copyFile(from, to);
+  return to;
+}