rootrework 1.0.2 → 1.0.3

package/src/client.mjs

@@ -0,0 +1,408 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import http from 'node:http';
+import { randomUUID, randomBytes, createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+export const defaults = { issuer: 'https://rootrework.com', resource: 'https://rootrework.com/mcp', scope: 'mcp' };
+export const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+export function statePath(env = process.env, platform = process.platform, home = os.homedir()) {
+  if (env.ROOTREWORK_STATE_DIR) return path.resolve(env.ROOTREWORK_STATE_DIR);
+  const base = platform === 'win32' ? env.LOCALAPPDATA || path.join(home, 'AppData', 'Local') : platform === 'darwin' ? path.join(home, 'Library', 'Application Support') : env.XDG_STATE_HOME || path.join(home, '.local', 'state');
+  return path.join(base, 'rootRework');
+}
+export async function readJson(file, fallback = null) {
+  try { return JSON.parse(await fs.readFile(file, 'utf8')); } catch (error) { if (error.code === 'ENOENT') return fallback; throw error; }
+}
+export async function writeJson(file, value) {
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  const handle = await fs.open(temporary, 'wx', 0o600);
+  try { await handle.writeFile(JSON.stringify(value, null, 2) + '\n'); await handle.sync(); } finally { await handle.close(); }
+  try { await fs.rename(temporary, file); } catch (error) { await fs.rm(temporary, { force: true }); throw error; }
+}
+export async function withLock(file, callback) {
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  let handle;
+  for (let attempt = 0; attempt < 150; attempt++) {
+    try { handle = await fs.open(file, 'wx', 0o600); await handle.writeFile(JSON.stringify({ pid: process.pid, at: Date.now() })); break; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const lock = await readJson(file).catch(() => null);
+      if (lock && !alive(lock.pid)) { await fs.rm(file, { force: true }); continue; }
+      await sleep(100);
+    }
+  }
+  if (!handle) throw new Error('Another installation or session update is still running.');
+  try { return await callback(); } finally { await handle.close(); await fs.rm(file, { force: true }); }
+}
+export function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+export async function requestJson(url, options = {}) {
+  const response = await fetch(url, { ...options, signal: options.signal || AbortSignal.timeout(40000) });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) throw Object.assign(new Error(data.error_description || data.message || data.error || `HTTP ${response.status}`), { code: data.error, status: response.status, data });
+  return data;
+}
+export async function discover(issuer = defaults.issuer) {
+  const selected = new URL(issuer);
+  if (selected.protocol !== 'https:' && selected.hostname !== '127.0.0.1') throw new Error('The issuer must use HTTPS.');
+  const response = await fetch(new URL('/.well-known/oauth-authorization-server', selected), { signal: AbortSignal.timeout(30000), redirect: 'follow' });
+  if (!response.ok) throw new Error(`Discovery failed: HTTP ${response.status}`);
+  const metadata = await response.json();
+  const effectiveOrigin = new URL(response.url).origin;
+  if (metadata.issuer !== effectiveOrigin) throw new Error('Authorization-server issuer mismatch.');
+  if (!metadata.registration_endpoint || !metadata.code_challenge_methods_supported?.includes('S256')) throw new Error('The server does not provide DCR with S256.');
+  for (const key of ['authorization_endpoint', 'token_endpoint', 'registration_endpoint']) if (new URL(metadata[key]).origin !== metadata.issuer) throw new Error(`Unexpected ${key} origin.`);
+  return metadata;
+}
+export async function openBrowser(url) {
+  let command, args;
+  if (process.platform === 'win32') { command = 'rundll32.exe'; args = ['url.dll,FileProtocolHandler', url]; }
+  else if (process.platform === 'darwin') { command = 'open'; args = [url]; }
+  else { command = 'xdg-open'; args = [url]; }
+  return await new Promise(resolve => {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.once('error', () => resolve(false)); child.once('spawn', () => { child.unref(); resolve(true); });
+  });
+}
+export async function login(stateDir, { issuer = defaults.issuer, replaceRegistration = false, onAuthorize = async url => { process.stdout.write(JSON.stringify({ state: 'authorization_required', url }) + '\n'); await openBrowser(url); } } = {}) {
+  await fs.mkdir(stateDir, { recursive: true, mode: 0o700 });
+  const metadata = await discover(issuer);
+  const canonicalRegistration = path.join(stateDir, 'registration.json');
+  const persistedRegistration = await readJson(canonicalRegistration);
+  if (persistedRegistration && persistedRegistration.issuer !== metadata.issuer) throw new Error('Stored registration belongs to a different issuer.');
+  const registrationFile = path.join(stateDir, replaceRegistration ? 'registration-replacement.json' : 'registration.json');
+  let registration = await readJson(registrationFile);
+  if (registration && registration.issuer !== metadata.issuer) throw new Error('Stored registration belongs to a different issuer.');
+  const interrupted = await readJson(path.join(stateDir, 'registration-pending.json'));
+  if (!registration && interrupted && interrupted.issuer !== metadata.issuer) throw new Error('Interrupted registration belongs to a different issuer.');
+  const existingCallback = registration?.redirect_uris?.[0] || (interrupted?.issuer === metadata.issuer ? interrupted.redirect : null);
+  const server = http.createServer();
+  const requestedPort = existingCallback ? Number(new URL(existingCallback).port) : 0;
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(requestedPort, '127.0.0.1', resolve); });
+  const redirect = `http://127.0.0.1:${server.address().port}/callback`;
+  let timer;
+  try {
+    if (!registration) {
+      let pending = await readJson(path.join(stateDir, 'registration-pending.json'));
+      if (pending && pending.issuer === metadata.issuer && pending.redirect !== redirect) {
+        throw new Error('An interrupted registration is bound to a different callback. Retry repair before creating a new registration.');
+      }
+      pending ||= { issuer: metadata.issuer, redirect, key: randomUUID() };
+      await writeJson(path.join(stateDir, 'registration-pending.json'), pending);
+      const created = await requestJson(metadata.registration_endpoint, { method: 'POST', headers: { 'content-type': 'application/json', 'idempotency-key': pending.key }, body: JSON.stringify({ client_name: 'rootRework', application_type: 'native', redirect_uris: [redirect], token_endpoint_auth_method: 'none', grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'] }) });
+      if (created.token_endpoint_auth_method !== 'none' || !created.redirect_uris?.includes(redirect) || created.client_secret) throw new Error('The effective public-client registration is incompatible.');
+      registration = { ...created, issuer: metadata.issuer };
+      await writeJson(registrationFile, registration);
+      await fs.rm(path.join(stateDir, 'registration-pending.json'), { force: true });
+    }
+    const verifier = randomBytes(32).toString('base64url');
+    const state = randomBytes(32).toString('base64url');
+    const authorization = new URL(metadata.authorization_endpoint);
+    for (const [key, value] of Object.entries({ response_type: 'code', client_id: registration.client_id, redirect_uri: redirect, scope: 'mcp', resource: `${metadata.issuer}/mcp`, state, code_challenge: createHash('sha256').update(verifier).digest('base64url'), code_challenge_method: 'S256' })) authorization.searchParams.set(key, value);
+    const completion = new Promise((resolve, reject) => {
+      timer = setTimeout(() => reject(new Error('Authorization did not complete. The registration is retained for retry.')), 10 * 60 * 1000);
+      server.on('request', (request, response) => {
+        const callback = new URL(request.url, redirect);
+        if (request.method !== 'GET' || callback.pathname !== '/callback') { response.writeHead(404).end(); return; }
+        if (callback.searchParams.get('state') !== state || callback.searchParams.get('iss') !== metadata.issuer) { response.writeHead(400).end('Invalid callback.'); return; }
+        clearTimeout(timer);
+        response.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' }).end(callback.searchParams.has('code') ? 'Connected. You may close this page.' : 'Authorization failed.');
+        if (callback.searchParams.has('error')) reject(new Error(callback.searchParams.get('error')));
+        else resolve(callback.searchParams.get('code'));
+      });
+    });
+    const [code] = await Promise.all([completion, Promise.resolve().then(() => onAuthorize(authorization.href))]);
+    const token = await requestJson(metadata.token_endpoint, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'authorization_code', client_id: registration.client_id, code, redirect_uri: redirect, code_verifier: verifier, resource: `${metadata.issuer}/mcp` }) });
+    const identity = await requestJson(`${metadata.issuer}/agent/identity`, { headers: { authorization: `Bearer ${token.access_token}` } });
+    const previous = await readJson(path.join(stateDir, 'session.json'));
+    const session = { schema: 1, issuer: metadata.issuer, resource: `${metadata.issuer}/mcp`, client: registration, token: { ...token, expires_at: token.expires_at || Date.now() + token.expires_in * 1000 }, accountId: identity.accountId, deviceId: previous?.accountId === identity.accountId ? previous.deviceId : randomUUID(), deviceName: previous?.accountId === identity.accountId ? previous.deviceName : os.hostname() };
+    if (replaceRegistration) await writeJson(canonicalRegistration, registration);
+    await writeJson(path.join(stateDir, 'session.json'), session);
+    if (replaceRegistration) await fs.rm(registrationFile, { force: true });
+    await fs.rm(path.join(stateDir, 'session-refresh.json'), { force: true });
+    return session;
+  } finally { clearTimeout(timer); server.close(); }
+}
+export async function accessSession(stateDir, { refresh = false } = {}) {
+  return await withLock(path.join(stateDir, 'session.lock'), () => readAccessSession(stateDir, { refresh }));
+}
+async function readAccessSession(stateDir, { refresh = false } = {}) {
+    const session = await readJson(path.join(stateDir, 'session.json'));
+    if (!session) throw Object.assign(new Error('Sign in to connect this computer.'), { code: 'login_required' });
+    if (session.ownerInput !== undefined && (session.ownerInput !== '0' || !session.accountId || !session.deviceId)) throw new Error('The private owner initialization record is invalid.');
+    let expiry = session.token.expires_at;
+    if (expiry && expiry < 1e12) expiry *= 1000;
+    if (!refresh && expiry > Date.now() + 60000) return session;
+    const metadata = await discover(session.issuer);
+    const pendingFile = path.join(stateDir, 'session-refresh.json');
+    let pending = await readJson(pendingFile);
+    if (pending && (pending.refreshToken !== session.token.refresh_token || pending.clientId !== session.client.client_id)) { await fs.rm(pendingFile, { force: true }); pending = null; }
+    pending ||= { key: randomUUID(), clientId: session.client.client_id, refreshToken: session.token.refresh_token };
+    await writeJson(pendingFile, pending);
+    const body = new URLSearchParams({ grant_type: 'refresh_token', refresh_token: session.token.refresh_token, client_id: session.client.client_id, resource: session.resource });
+    const token = await requestJson(metadata.token_endpoint, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded', 'idempotency-key': pending.key }, body });
+    session.token = { ...token, expires_at: token.expires_at || Date.now() + token.expires_in * 1000 };
+    await writeJson(path.join(stateDir, 'session.json'), session);
+    await fs.rm(pendingFile, { force: true });
+    return session;
+}
+export async function initializeOwner(stateDir, file) {
+  if (!file || file.startsWith('--')) throw new Error('A private provisioned installation file is required.');
+  const input = await readJson(path.resolve(file));
+  if (!input || input.ownerInput !== '0' || !input.accountId || !input.deviceId || input.issuer !== defaults.issuer || input.resource !== defaults.resource) throw new Error('Invalid private owner initialization.');
+  return await withLock(path.join(stateDir, 'session.lock'), async () => {
+    const previous = await readJson(path.join(stateDir, 'session.json'));
+    if (previous && ['accountId', 'deviceId', 'issuer', 'resource'].some(key => previous[key] !== input[key])) throw new Error('This state directory belongs to another account or device.');
+    let session = previous ? await readAccessSession(stateDir) : input;
+    const inspect = () => requestJson(`${session.issuer}/agent/identity`, { headers: { authorization: `Bearer ${session.token.access_token}` } });
+    let identity;
+    try { identity = await inspect(); } catch (error) {
+      if (!previous || error.status !== 401) throw error;
+      session = await readAccessSession(stateDir, { refresh: true });
+      identity = await inspect();
+    }
+    if (!identity.owner || identity.accountId !== input.accountId || identity.deviceId !== input.deviceId || identity.clientId !== session.client?.client_id) throw new Error('The owner association does not match the issued installation session.');
+    await writeJson(path.join(stateDir, 'session.json'), { ...session, schema: 1, deviceName: session.deviceName || 'root', ownerInput: input.ownerInput, ownerInputAcceptedAt: session.ownerInputAcceptedAt || Date.now() });
+    await writeJson(path.join(stateDir, 'registration.json'), { ...session.client, issuer: session.issuer });
+    return { state: 'configured', account_id: identity.accountId, device_id: identity.deviceId, owner_input_accepted: true, zero_only: /^0+$/.test(input.ownerInput) };
+  });
+}
+export async function api(stateDir, endpoint, body, options = {}) {
+  let session = await accessSession(stateDir);
+  const invoke = () => requestJson(new URL(endpoint, session.issuer), { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${session.token.access_token}` }, body: JSON.stringify(body), ...options });
+  try { return await invoke(); } catch (error) {
+    if (error.status !== 401) throw error;
+    session = await accessSession(stateDir, { refresh: true });
+    return await invoke();
+  }
+}
+
+async function locateDependency(name, from) {
+  for (let current = from; ; current = path.dirname(current)) {
+    const candidate = path.join(current, 'node_modules', ...name.split('/'));
+    if (await readJson(path.join(candidate, 'package.json'))) return candidate;
+    if (path.dirname(current) === current) return null;
+  }
+}
+async function collectFiles(source, destination, selected, excludeDependencies = false) {
+  const info = await fs.stat(source);
+  if (info.isDirectory()) {
+    for (const name of await fs.readdir(source)) if (!excludeDependencies || !['node_modules', '.git'].includes(name)) await collectFiles(path.join(source, name), path.join(destination, name), selected, excludeDependencies);
+  } else if (info.isFile()) selected.add(destination);
+}
+async function copyDependencies(source, destination, ancestors = new Map(), selected = null, copy = true) {
+  const manifest = await readJson(path.join(source, 'package.json'));
+  const dependencies = { ...manifest.dependencies, ...manifest.optionalDependencies };
+  for (const name of Object.keys(dependencies)) {
+    const resolved = await locateDependency(name, source);
+    if (!resolved) {
+      if (manifest.optionalDependencies?.[name]) continue;
+      throw new Error(`Missing installed dependency: ${name}`);
+    }
+    const real = await fs.realpath(resolved);
+    if (ancestors.get(name) === real) continue;
+    const target = path.join(destination, 'node_modules', ...name.split('/'));
+    if (selected) await collectFiles(real, target, selected, true);
+    if (copy) { await fs.mkdir(path.dirname(target), { recursive: true }); await fs.cp(real, target, { recursive: true, dereference: true, filter: item => path.basename(item) !== 'node_modules' && path.basename(item) !== '.git' }); }
+    await copyDependencies(real, target, new Map([...ancestors, [name, real]]), selected, copy);
+  }
+}
+async function sameFile(source, destination) {
+  const a = await fs.readFile(source);
+  try { return a.equals(await fs.readFile(destination)); } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+async function repairTree(source, destination) {
+  if (path.resolve(source) === path.resolve(destination)) return;
+  const info = await fs.stat(source);
+  if (info.isDirectory()) {
+    await fs.mkdir(destination, { recursive: true, mode: info.mode & 0o777 });
+    for (const name of await fs.readdir(source)) await repairTree(path.join(source, name), path.join(destination, name));
+  } else if (info.isFile() && !await sameFile(source, destination)) {
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    await fs.copyFile(source, temporary); await fs.chmod(temporary, info.mode & 0o777);
+    await fs.rename(temporary, destination);
+    if (!await sameFile(source, destination)) throw new Error('Installation readback differs from its selected release.');
+  }
+}
+async function copyPayload(source, destination, repair = false) {
+  const manifest = await readJson(path.join(source, 'package.json'));
+  const entries = [...new Set([...(manifest.files || ['bin', 'src', 'config']), 'package.json', 'LICENSE'])];
+  for (const entry of entries) {
+    if (path.isAbsolute(entry) || entry.split(/[\\/]/).includes('..')) throw new Error('Invalid package payload path.');
+    const from = path.join(source, entry), to = path.join(destination, entry);
+    if (repair) await repairTree(from, to);
+    else { await fs.mkdir(path.dirname(to), { recursive: true }); await fs.cp(from, to, { recursive: true, dereference: true }); }
+  }
+  for (const excluded of ['auth.mjs', 'worker.mjs', 'public.mjs']) if (!entries.includes(`src/${excluded}`) && !entries.includes('src')) await fs.rm(path.join(destination, 'src', excluded), { force: true });
+}
+async function ownedFiles(source, destination) {
+  const manifest = await readJson(path.join(source, 'package.json'));
+  const selected = new Set();
+  for (const entry of [...new Set([...(manifest.files || ['bin', 'src', 'config']), 'package.json', 'LICENSE'])]) {
+    if (path.isAbsolute(entry) || entry.split(/[\\/]/).includes('..')) throw new Error('Invalid package payload path.');
+    await collectFiles(path.join(source, entry), path.join(destination, entry), selected);
+  }
+  await copyDependencies(source, destination, new Map(), selected, false);
+  return [...selected].map(file => path.relative(destination, file)).sort();
+}
+async function removeFiles(base, files) {
+  const parents = new Set([base]);
+  for (const relative of files) {
+    if (typeof relative !== 'string' || path.isAbsolute(relative) || relative.split(/[\\/]/).includes('..')) throw new Error('Invalid owned-file record.');
+    const file = path.join(base, relative), info = await fs.lstat(file).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    if (info && !info.isDirectory()) await fs.unlink(file);
+    for (let current = path.dirname(file); current !== base && current.startsWith(base + path.sep); current = path.dirname(current)) parents.add(current);
+  }
+  for (const directory of [...parents].sort((a, b) => b.length - a.length)) try { await fs.rmdir(directory); } catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; }
+}
+async function payloadMatches(source, destination) {
+  const manifest = await readJson(path.join(source, 'package.json'));
+  async function sameTree(from, to, excludeDependencies = false) {
+    let a, b; try { a = await fs.stat(from); b = await fs.stat(to); } catch { return false; }
+    if (a.isDirectory()) {
+      if (!b.isDirectory()) return false;
+      for (const name of await fs.readdir(from)) {
+        if (excludeDependencies && ['node_modules', '.git'].includes(name)) continue;
+        if (!await sameTree(path.join(from, name), path.join(to, name), excludeDependencies)) return false;
+      }
+      return true;
+    }
+    return a.isFile() && b.isFile() && a.size === b.size && (a.mode & 0o111) === (b.mode & 0o111) && await sameFile(from, to);
+  }
+  for (const entry of [...new Set([...(manifest.files || ['bin', 'src', 'config']), 'package.json', 'LICENSE'])]) {
+    if (path.isAbsolute(entry) || entry.split(/[\\/]/).includes('..')) throw new Error('Invalid package payload path.');
+    if (!await sameTree(path.join(source, entry), path.join(destination, entry))) return false;
+  }
+  async function dependenciesMatch(fromRoot, toRoot, ancestors = new Map()) {
+    const descriptor = await readJson(path.join(fromRoot, 'package.json'));
+    for (const name of Object.keys({ ...descriptor.dependencies, ...descriptor.optionalDependencies })) {
+      const from = await locateDependency(name, fromRoot), to = path.join(toRoot, 'node_modules', ...name.split('/'));
+      if (!from) { if (descriptor.optionalDependencies?.[name]) continue; return false; }
+      const real = await fs.realpath(from);
+      if (ancestors.get(name) === real) continue;
+      if (!await sameTree(real, to, true) || !await dependenciesMatch(real, to, new Map([...ancestors, [name, real]]))) return false;
+    }
+    return true;
+  }
+  return dependenciesMatch(source, destination);
+}
+export async function activateInstallation(stateDir, prepared) {
+  const previous = await readJson(path.join(stateDir, 'installation.json'));
+  const value = { schema: 1, version: prepared.version, release: prepared.release, previousRelease: previous?.release !== prepared.release ? previous?.release : previous?.previousRelease, source: prepared.source || prepared.release };
+  await writeJson(path.join(stateDir, 'installation.json'), value);
+  return value;
+}
+export async function materialize(stateDir, sourceRoot = packageRoot, { activate = true, projectionRoot = sourceRoot } = {}) {
+  return await withLock(path.join(stateDir, 'install.lock'), async () => {
+    const manifest = await readJson(path.join(sourceRoot, 'package.json'));
+    if (!manifest || typeof manifest.version !== 'string' || !/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(manifest.version)) throw new Error('Invalid release manifest.');
+    let target = path.join(stateDir, 'releases', manifest.version);
+    const current = await readJson(path.join(target, 'package.json'));
+    const active = await readJson(path.join(stateDir, 'installation.json'));
+    if (active?.version === manifest.version && await payloadMatches(sourceRoot, active.release)) target = active.release;
+    else if (!current || !await payloadMatches(sourceRoot, target)) {
+      if (current) target += '-' + randomUUID();
+      const staging = `${target}.${randomUUID()}.tmp`;
+      try {
+        await fs.mkdir(staging, { recursive: true, mode: 0o700 });
+        await copyPayload(sourceRoot, staging); await copyDependencies(sourceRoot, staging);
+        if (!await payloadMatches(sourceRoot, staging)) throw new Error('Staged release readback differs from its selected source.');
+        await fs.rename(staging, target);
+      } catch (error) { await fs.rm(staging, { recursive: true, force: true }); throw error; }
+    }
+    const prepared = { release: target, version: manifest.version, source: sourceRoot };
+    const releases = await readJson(path.join(stateDir, 'releases.json'), {});
+    if (active?.release && !releases[active.release] && await readJson(path.join(active.release, 'package.json'))) releases[active.release] = await ownedFiles(active.release, active.release);
+    releases[target] = await ownedFiles(sourceRoot, target);
+    await writeJson(path.join(stateDir, 'releases.json'), releases);
+    if (activate) await activateInstallation(stateDir, prepared);
+    const projection = await materializeProjection(target, stateDir, manifest.version, projectionPath(projectionRoot), target);
+    return { ...prepared, projection };
+  });
+}
+export function projectionPath(sourceRoot) {
+  let cursor = sourceRoot;
+  while (path.dirname(cursor) !== cursor && path.basename(cursor) !== 'node_modules') cursor = path.dirname(cursor);
+  if (path.basename(cursor) !== 'node_modules') cursor = path.join(sourceRoot, 'node_modules');
+  return path.join(cursor, 'rootEnterprise', 'rootRework', 'node_modules', 'user');
+}
+export async function materializeProjection(sourceRoot, stateDir, version, explicitPath, release = sourceRoot) {
+  const destination = explicitPath || projectionPath(sourceRoot);
+  const marker = path.join(destination, 'data', 'installation.json');
+  const directories = ['data', 'sources'];
+  for (const directory of [destination, ...directories.map(name => path.join(destination, name))]) {
+    const info = await fs.lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    if (info && !info.isDirectory()) throw new Error('The user-product destination contains unowned files.');
+  }
+  const markerInfo = await fs.lstat(marker).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (markerInfo && !markerInfo.isFile()) throw new Error('The user-product destination contains unowned files.');
+  const prior = await readJson(marker);
+  if (prior && (prior.schema !== 1 || prior.product !== 'rootRework' || typeof prior.stateDir !== 'string' || path.resolve(prior.stateDir) !== path.resolve(stateDir))) throw new Error('The user-product projection belongs to another installation.');
+  if (!prior) {
+    const contents = await fs.readdir(destination).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+    for (const name of contents) if (!directories.includes(name) || (await fs.readdir(path.join(destination, name))).length) throw new Error('The user-product destination contains unowned files.');
+  }
+  await fs.mkdir(path.join(destination, 'data'), { recursive: true, mode: 0o700 });
+  await fs.mkdir(path.join(destination, 'sources'), { recursive: true });
+  const session = await readJson(path.join(stateDir, 'session.json'));
+  const files = (await ownedFiles(sourceRoot, path.join(destination, 'sources'))).map(name => path.join('sources', name));
+  files.push(path.join('data', 'client.json'), path.join('data', 'installation.json'));
+  if (session) files.push(path.join('data', 'session.json'));
+  const tracked = await readJson(path.join(stateDir, 'projections.json'), []);
+  if (!tracked.includes(destination)) { tracked.push(destination); await writeJson(path.join(stateDir, 'projections.json'), tracked); }
+  await writeJson(marker, { schema: 1, product: 'rootRework', version, stateDir, release, owned_files: [...new Set([...(prior?.owned_files || []), ...files])] });
+  await fs.copyFile(path.join(sourceRoot, 'config', 'client.json'), path.join(destination, 'data', 'client.json'));
+  if (session) await writeJson(path.join(destination, 'data', 'session.json'), session);
+  await copyPayload(sourceRoot, path.join(destination, 'sources'), true);
+  await copyDependencies(sourceRoot, path.join(destination, 'sources'));
+  await removeFiles(destination, (prior?.owned_files || []).filter(file => !files.includes(file)));
+  await writeJson(marker, { schema: 1, product: 'rootRework', version, stateDir, release, owned_files: files });
+  return destination;
+}
+export async function removeOwnedCode(stateDir, { purge = false } = {}) {
+  const removed = [], retained = [], cleaned = [];
+  async function removalState(directory) { cleaned.push(directory); if (await fs.lstat(directory).catch(() => null)) retained.push(directory); else removed.push(directory); }
+  const activeTasks = [];
+  for (const name of await fs.readdir(path.join(stateDir, 'tasks')).catch(() => [])) {
+    const record = await readJson(path.join(stateDir, 'tasks', name, 'state.json')).catch(() => null);
+    if (record && !['completed_success', 'completed_failure', 'cancelled', 'timed_out', 'unknown_outcome'].includes(record.state) && alive(record.supervisor_pid || record.worker_pid)) activeTasks.push(name);
+  }
+  if (purge && activeTasks.length) throw new Error('Active task supervisors still use this installation. Finish or cancel those tasks before purging its data.');
+  for (const destination of await readJson(path.join(stateDir, 'projections.json'), [])) {
+    const marker = await readJson(path.join(destination, 'data', 'installation.json'));
+    if (!marker) continue;
+    if (path.resolve(marker.stateDir || '') !== path.resolve(stateDir) || marker.product !== 'rootRework') { retained.push(destination); continue; }
+    if (path.resolve(destination) === path.resolve(stateDir) || path.resolve(stateDir).startsWith(path.resolve(destination) + path.sep)) throw new Error('An invalid projection cannot be removed.');
+    if (!marker.owned_files) { retained.push(destination); continue; }
+    await removeFiles(destination, marker.owned_files);
+    await removalState(destination);
+    const nodeModules = path.dirname(destination), product = path.dirname(nodeModules), scope = path.dirname(product);
+    if (path.basename(nodeModules) === 'node_modules' && path.basename(product) === 'rootRework' && path.basename(scope) === 'rootEnterprise') for (const directory of [nodeModules, product, scope]) try { await fs.rmdir(directory); } catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; }
+  }
+  if (!activeTasks.length) {
+    for (const [directory, files] of Object.entries(await readJson(path.join(stateDir, 'releases.json'), {}))) {
+      if (!path.resolve(directory).startsWith(path.resolve(stateDir, 'releases') + path.sep)) throw new Error('Invalid release ownership record.');
+      await removeFiles(directory, files); await removalState(directory);
+    }
+    await fs.rm(path.join(stateDir, 'releases.json'), { force: true });
+    await fs.rmdir(path.join(stateDir, 'releases')).catch(error => { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; });
+  }
+  for (const directory of await readJson(path.join(stateDir, 'candidates.json'), [])) {
+    if (!path.resolve(directory).startsWith(path.resolve(stateDir, 'candidates') + path.sep)) throw new Error('Invalid candidate ownership record.');
+    await fs.rm(directory, { recursive: true, force: true }); removed.push(directory);
+  }
+  await fs.rmdir(path.join(stateDir, 'candidates')).catch(error => { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; });
+  for (const name of ['installation.json', 'projections.json', 'candidates.json', 'transition.json', 'service.json', 'agent-stop.json']) await fs.rm(path.join(stateDir, name), { force: true });
+  if (purge) {
+    for (const name of ['session.json', 'session-refresh.json', 'registration.json', 'registration-pending.json', 'registration-replacement.json', 'status.json', 'agent.json', 'agent.log', 'scheduler-status.json', 'operations', 'tasks', 'requests', 'cursors', 'artifacts', 'schedules', 'extension-pages', 'extension-requests', 'retention']) await fs.rm(path.join(stateDir, name), { recursive: true, force: true });
+  }
+  return { removed, cleaned_code: cleaned, retained_unowned: retained, retained_running_tasks: activeTasks, retained_data: !purge, remote_data_deleted: false };
+}