trackqa 0.0.0-stage → 0.1.0

package/dist/tools/trackqa-connect/src/clients/vscode-session.js

@@ -0,0 +1,145 @@
+import { lstat, mkdir, open, realpath, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { requireValue, setupFor, UUID } from "../core.js";
+import { fingerprint } from "./codex.js";
+export const vscodeEntry = (setup) => ({ type: 'http', url: setup.endpoint, headers: { Authorization: `Bearer \${env:${setup.envVar}}` } });
+export const matchesVSCodeEntry = (value, setup) => fingerprint(value) === fingerprint(vscodeEntry(setup));
+export function vscodePaths(home, setup) {
+    requireValue(path.isAbsolute(home) && UUID.test(setup.projectId) && fingerprint(setup) === fingerprint(setupFor(setup.projectId, 'vscode')), 'configuration_location_untrusted');
+    const root = path.join(home, setup.projectId), user = path.join(root, 'user-data');
+    return { root, user, extensions: path.join(root, 'extensions'), home: path.join(root, 'home'),
+        owner: path.join(root, 'owner.json'), process: path.join(root, 'process.json'),
+        mcp: path.join(user, 'User', 'mcp.json'), settings: path.join(user, 'User', 'settings.json') };
+}
+const bytes = (value) => Buffer.from(JSON.stringify(value, null, 2) + '\n');
+export function vscodePayloads(setup) {
+    return {
+        owner: bytes({ owner: 'TrackQA Connect VS Code Local v1', projectId: setup.projectId, server: setup.serverName }),
+        mcp: bytes({ servers: { [setup.serverName]: vscodeEntry(setup) } }),
+        settings: bytes({ 'update.mode': 'none', 'extensions.autoUpdate': 'off', 'extensions.autoCheckUpdates': false,
+            'telemetry.telemetryLevel': 'off', 'chat.editor.localAgent.enabled': true, 'chat.defaultToCopilotHarness': false,
+            'chat.editor.preferCopilotHarness': false, 'workbench.startupEditor': 'none', 'window.restoreWindows': 'none',
+            'window.title': 'TrackQA Local — ${activeEditorShort}' }),
+    };
+}
+export async function safeVSCodeDirectory(dir, create = false) {
+    const absolute = path.resolve(dir), root = path.parse(absolute).root;
+    let current = root;
+    for (const part of absolute.slice(root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        if (create) {
+            try {
+                await mkdir(current, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        const info = await lstat(current);
+        requireValue(info.isDirectory() && !info.isSymbolicLink() && (await realpath(current)).toLowerCase() === current.toLowerCase(), 'configuration_location_untrusted');
+    }
+}
+export async function readVSCodeFile(file) {
+    try {
+        const info = await lstat(file);
+        requireValue(info.isFile() && !info.isSymbolicLink() && info.nlink === 1 && info.size <= 16384
+            && (await realpath(file)).toLowerCase() === path.resolve(file).toLowerCase(), 'configuration_changed');
+        const handle = await open(file, 'r');
+        try {
+            const stat = await handle.stat();
+            requireValue(stat.ino === info.ino && stat.dev === info.dev, 'configuration_changed');
+            const content = await handle.readFile();
+            requireValue(content.length <= 16384, 'configuration_changed');
+            return content;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function writeVSCodeFile(file, content) {
+    const handle = await open(file, 'wx', 0o600);
+    try {
+        await handle.writeFile(content);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function owned(home, setup) {
+    const files = vscodePaths(home, setup);
+    try {
+        await safeVSCodeDirectory(home);
+        await safeVSCodeDirectory(files.root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    requireValue((await readVSCodeFile(files.owner))?.equals(vscodePayloads(setup).owner), 'configuration_conflict');
+    return files;
+}
+export async function readVSCodeSession(home, setup) {
+    const files = await owned(home, setup);
+    if (!files)
+        return null;
+    for (const dir of [files.user, path.dirname(files.mcp), files.extensions, files.home])
+        await safeVSCodeDirectory(dir);
+    const content = await readVSCodeFile(files.mcp);
+    if (!content)
+        return null;
+    requireValue(content.equals(vscodePayloads(setup).mcp), 'configuration_changed');
+    return vscodeEntry(setup);
+}
+export async function installVSCodeSession(home, setup) {
+    const files = vscodePaths(home, setup), payload = vscodePayloads(setup);
+    await safeVSCodeDirectory(home, true);
+    try {
+        await mkdir(files.root, { mode: 0o700 });
+        await writeVSCodeFile(files.owner, payload.owner);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        await owned(home, setup);
+    }
+    await safeVSCodeDirectory(files.root);
+    requireValue(!await readVSCodeFile(files.process), 'vscode_process_unconfirmed');
+    for (const file of [files.mcp, files.settings])
+        requireValue(!await readVSCodeFile(file), 'configuration_conflict');
+    for (const dir of [files.user, path.dirname(files.mcp), files.extensions, files.home,
+        path.join(files.home, 'AppData', 'Roaming'), path.join(files.home, 'AppData', 'Local'), path.join(files.home, 'Temp')])
+        await safeVSCodeDirectory(dir, true);
+    await writeVSCodeFile(files.settings, payload.settings);
+    await writeVSCodeFile(files.mcp, payload.mcp);
+    return fingerprint(vscodeEntry(setup));
+}
+export async function removeVSCodeSession(home, setup, hash) {
+    const files = await owned(home, setup);
+    if (!files)
+        return;
+    for (const dir of [files.user, path.dirname(files.mcp)])
+        await safeVSCodeDirectory(dir);
+    requireValue(!await readVSCodeFile(files.process), 'vscode_process_unconfirmed');
+    requireValue(hash === null || hash === fingerprint(vscodeEntry(setup)), 'configuration_changed');
+    // Validate both before deleting either. Never recursively remove IDE state or user files.
+    const payload = vscodePayloads(setup);
+    for (const key of ['mcp', 'settings']) {
+        const content = await readVSCodeFile(files[key]);
+        requireValue(!content || content.equals(payload[key]), 'configuration_changed');
+    }
+    for (const key of ['mcp', 'settings']) {
+        if (await readVSCodeFile(files[key]))
+            await unlink(files[key]);
+    }
+    // Keep the ownership marker and runtime-generated profile data. They may include
+    // user-created files; removing a connection does not authorize deleting them.
+}

package/dist/tools/trackqa-connect/src/clients/vscode.js

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { ConnectorError, requireValue, TOKEN, tools } from "../core.js";
+import { installVSCodeSession, matchesVSCodeEntry, readVSCodeFile, readVSCodeSession, removeVSCodeSession, vscodePaths, vscodePayloads } from "./vscode-session.js";
+import { launchVSCode, settleVSCodeRun, vscodeRuntime } from "./vscode-process.js";
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export function trustedVSCodeLocation(file, home = os.homedir(), platform = process.platform, cwd = process.cwd()) {
+    if (platform !== 'win32')
+        return false;
+    const paths = path.win32, resolved = paths.resolve(file).toLowerCase();
+    if (!paths.isAbsolute(file) || paths.basename(file).toLowerCase() !== 'code.exe' || resolved.startsWith(paths.resolve(cwd).toLowerCase() + paths.sep))
+        return false;
+    return [paths.join(home, 'AppData', 'Local', 'Programs', 'Microsoft VS Code', 'Code.exe'),
+        paths.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Microsoft VS Code', 'Code.exe')].some(candidate => paths.resolve(candidate).toLowerCase() === resolved);
+}
+async function regular(file) {
+    const stat = await lstat(file);
+    requireValue(stat.isFile() && !stat.isSymbolicLink() && (await realpath(file)).toLowerCase() === path.resolve(file).toLowerCase(), 'executable_untrusted');
+    return { path: file, sha256: sha(await readFile(file)) };
+}
+export async function checkVSCodeExecutable(file, trust = trustedVSCodeLocation) {
+    requireValue(trust(file), 'executable_untrusted');
+    const canonical = await realpath(file);
+    requireValue(trust(canonical), 'executable_untrusted');
+    const installation = path.dirname(canonical);
+    requireValue(!await lstat(path.join(installation, 'data')).catch(error => { if (error.code === 'ENOENT')
+        return null; throw error; }), 'client_unsupported');
+    const wrapper = path.join(installation, 'bin', 'code.cmd'), text = await readFile(wrapper, 'utf8');
+    const versionFolder = /%~dp0\.\.\\([0-9a-f]{10})\\resources\\app\\out\\cli\.js/.exec(text)?.[1];
+    requireValue(versionFolder || text.includes('%~dp0..\\resources\\app\\out\\cli.js'), 'client_unsupported');
+    const app = path.join(installation, ...(versionFolder ? [versionFolder] : []), 'resources', 'app');
+    const productFile = path.join(app, 'product.json'), packageFile = path.join(app, 'package.json'), cliFile = path.join(app, 'out', 'cli.js');
+    const product = JSON.parse(await readFile(productFile, 'utf8')), pkg = JSON.parse(await readFile(packageFile, 'utf8'));
+    requireValue(product.applicationName === 'code' && product.quality === 'stable' && product.version === pkg.version && /^1\.143\.\d+$/.test(pkg.version), 'client_unsupported');
+    const cli = await readFile(cliFile, 'utf8');
+    for (const flag of ['user-data-dir', 'extensions-dir', 'use-inmemory-secretstorage', 'disable-updates'])
+        requireValue(cli.includes(flag), 'client_unsupported');
+    const inputs = await Promise.all([canonical, wrapper, productFile, packageFile, cliFile].map(regular));
+    return { path: canonical, sha256: inputs[0].sha256, version: pkg.version, appServer: false, foregroundMode: 'direct', inputs, installation };
+}
+export async function detectVSCode(explicit, source = process.env, inspect = checkVSCodeExecutable) {
+    const candidates = explicit ? [explicit] : [path.join(os.homedir(), 'AppData', 'Local', 'Programs', 'Microsoft VS Code', 'Code.exe'),
+        path.join(source.ProgramFiles ?? 'C:\\Program Files', 'Microsoft VS Code', 'Code.exe')];
+    for (const candidate of candidates) {
+        try {
+            return await inspect(candidate);
+        }
+        catch (error) {
+            if (explicit || error instanceof ConnectorError && error.code === 'client_unsupported')
+                throw error instanceof ConnectorError ? error : new ConnectorError('executable_untrusted');
+        }
+    }
+    throw new ConnectorError('client_not_found');
+}
+export function vscodeEnvironment(home, setup, source = process.env) {
+    const files = vscodePaths(home, setup), clean = {};
+    for (const key of ['PATH', 'PATHEXT', 'SystemRoot', 'SystemDrive', 'WINDIR', 'COMSPEC', 'TERM', 'COLORTERM', 'LANG', 'LC_ALL',
+        'HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy', 'ALL_PROXY', 'all_proxy', 'NO_PROXY', 'no_proxy', 'NODE_USE_SYSTEM_CA', 'NODE_EXTRA_CA_CERTS']) {
+        if (source[key] !== undefined)
+            clean[key] = source[key];
+    }
+    return { ...clean, HOME: files.home, USERPROFILE: files.home, APPDATA: path.join(files.home, 'AppData', 'Roaming'),
+        LOCALAPPDATA: path.join(files.home, 'AppData', 'Local'), TEMP: path.join(files.home, 'Temp'), TMP: path.join(files.home, 'Temp'), VSCODE_DISABLE_TELEMETRY: '1' };
+}
+export function vscodeLaunchArgs(home, setup) {
+    const files = vscodePaths(home, setup);
+    return ['--new-window', '--user-data-dir', files.user, '--extensions-dir', files.extensions, '--skip-welcome', '--skip-release-notes',
+        '--disable-updates', '--disable-telemetry', '--sync', 'off', '--use-inmemory-secretstorage', '--log', 'warning'];
+}
+export const vscodeVerification = () => ({ authorized: null, verified: false, code: 'manual_verification_required' });
+export function vscodeInstructions(setup) {
+    return `Experimental VS Code Local harness only. In the window titled TrackQA Local, use Ctrl+Shift+P > MCP: List Servers > ${setup.serverName} > Start Server. Trust only this server if asked; inspect its Show Output action. Startup alone is not verification. Confirm Running and these five tools: ${tools.join(', ')}. In a separately authorized Local agent session, call only trackqa_connection_status and trackqa_list_projects and confirm project ${setup.projectId}. Do not submit a finding during acceptance. Account/model access is separate; do not switch to Copilot or provider harnesses. Use File > Exit to close the entire isolated instance, then return here for revocation. Manual observations remain unverified by this CLI.`;
+}
+export function vscodeAdapter(exe, sessionHome, source = process.env, runtime = vscodeRuntime) {
+    async function integrity() {
+        requireValue(!await lstat(path.join(exe.installation, 'data')).catch(error => { if (error.code === 'ENOENT')
+            return null; throw error; }), 'executable_changed');
+        for (const input of exe.inputs)
+            requireValue((await realpath(input.path)).toLowerCase() === input.path.toLowerCase() && sha(await readFile(input.path)) === input.sha256, 'executable_changed');
+    }
+    return {
+        client: 'vscode', label: 'VS Code Local', configurationHome: sessionHome, executable: exe,
+        entry: setup => readVSCodeSession(sessionHome, setup), matches: matchesVSCodeEntry,
+        installPreview: setup => `Connector-owned VS Code Local profile only: ${vscodePaths(sessionHome, setup).root}. Normal profiles/extensions/workspaces are not edited. Native MCP startup is manual; connectivity stays unverified. Runtime-generated IDE files are preserved on disconnect.`,
+        manualInstructions: vscodeInstructions,
+        async install(setup) { await integrity(); return installVSCodeSession(sessionHome, setup); },
+        async remove(setup, hash) {
+            const files = vscodePaths(sessionHome, setup);
+            await readVSCodeSession(sessionHome, setup);
+            await settleVSCodeRun(files.process, files.user, runtime);
+            await removeVSCodeSession(sessionHome, setup, hash);
+        },
+        async verify() { return vscodeVerification(); },
+        async launch(setup, token, signal) {
+            requireValue(TOKEN.test(token), 'token_invalid');
+            const files = vscodePaths(sessionHome, setup);
+            requireValue(await readVSCodeSession(sessionHome, setup), 'configuration_changed');
+            requireValue((await readVSCodeFile(files.settings))?.equals(vscodePayloads(setup).settings), 'configuration_changed');
+            // An isolated extensions directory is not permission to launch newly installed extensions.
+            requireValue((await readdir(files.extensions)).every(name => ['extensions.json', '.obsolete'].includes(name)), 'configuration_changed');
+            for (const [name, expected] of [['extensions.json', '[]'], ['.obsolete', '{}']]) {
+                const content = await readVSCodeFile(path.join(files.extensions, name));
+                try {
+                    requireValue(!content || JSON.stringify(JSON.parse(content.toString('utf8'))) === expected, 'configuration_changed');
+                }
+                catch {
+                    throw new ConnectorError('configuration_changed');
+                }
+            }
+            await integrity();
+            const env = { ...vscodeEnvironment(sessionHome, setup, source), [setup.envVar]: token };
+            token = '';
+            try {
+                await launchVSCode(exe.path, vscodeLaunchArgs(sessionHome, setup), env, files.user, files.process, signal, runtime);
+            }
+            finally {
+                delete env[setup.envVar];
+            }
+        },
+    };
+}

package/dist/tools/trackqa-connect/src/core.js

@@ -0,0 +1,87 @@
+import { stripVTControlCharacters } from 'node:util';
+import { mcpSetup, mcpTools } from "../../../src/lib/mcpOnboarding.js";
+export const SUPABASE_URL = 'https://mzeuimqfrswrwoaqjdmp.supabase.co';
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export const TOKEN = /^tqm_[0-9a-f]{64}$/;
+export const tools = mcpTools.map(tool => tool.name);
+export const setupFor = (id, client = 'codex') => {
+    const setup = mcpSetup(SUPABASE_URL, id);
+    return client === 'codex' ? setup : { ...setup, serverName: `${setup.serverName}_${client}`, envVar: `${setup.envVar}_${client.toUpperCase().replaceAll('-', '_')}` };
+};
+export class ConnectorError extends Error {
+    code;
+    constructor(code) { super('TrackQA connector operation did not complete.'); this.code = code; }
+}
+export function requireValue(condition, code) {
+    if (!condition)
+        throw new ConnectorError(code);
+}
+export function display(value) { return [...stripVTControlCharacters(value)].filter(char => char.charCodeAt(0) >= 32 && !(char.charCodeAt(0) >= 127 && char.charCodeAt(0) <= 159)).join('').slice(0, 160); }
+export function parseArgs(args) {
+    if (!args.length || (args.length === 1 && ['help', '--help', '-h'].includes(args[0])))
+        return { command: 'help' };
+    requireValue(['connect', 'status', 'disconnect'].includes(args[0]), 'usage');
+    const result = { command: args[0] };
+    const seen = new Set();
+    for (let i = 1; i < args.length; i++) {
+        const flag = args[i];
+        requireValue(!seen.has(flag), 'usage');
+        seen.add(flag);
+        if (flag === '--claude-only') {
+            result.claudeOnly = true;
+            continue;
+        }
+        const value = args[++i];
+        requireValue(['--client', '--codex-path', '--gemini-path', '--claude-path', '--vscode-path', '--project'].includes(flag) && value && !value.startsWith('--'), 'usage');
+        if (flag === '--client') {
+            requireValue(['codex', 'gemini', 'claude', 'vscode', 'vscode-copilot'].includes(value), 'client_unsupported');
+            result.client = value;
+        }
+        if (['--codex-path', '--gemini-path', '--claude-path', '--vscode-path'].includes(flag))
+            result.executable = value;
+        if (flag === '--project') {
+            requireValue(UUID.test(value), 'usage');
+            result.projectId = value.toLowerCase();
+        }
+    }
+    requireValue(['--codex-path', '--gemini-path', '--claude-path', '--vscode-path'].filter(flag => seen.has(flag)).length <= 1
+        && (!seen.has('--gemini-path') || result.client === 'gemini')
+        && (!seen.has('--codex-path') || !result.client || result.client === 'codex')
+        && (!seen.has('--claude-path') || result.client === 'claude')
+        && (!seen.has('--vscode-path') || result.client === 'vscode' || result.client === 'vscode-copilot')
+        && (!result.claudeOnly || (result.client === 'claude' && result.command === 'connect')), 'usage');
+    return result;
+}
+export async function boundedJson(response, maxBytes = 1_048_576) {
+    requireValue(!response.redirected && response.ok, 'request_failed');
+    if (response.status === 204)
+        return null;
+    const reader = response.body?.getReader();
+    requireValue(reader, 'response_invalid');
+    let size = 0;
+    const chunks = [];
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.length;
+            requireValue(size <= maxBytes, 'response_limit');
+            chunks.push(value);
+        }
+        // PostgREST void RPCs may return an empty successful body. Callers of reads
+        // and issuance still require their explicit array/object response shapes.
+        if (size === 0)
+            return null;
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            throw new ConnectorError('response_invalid');
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}

package/dist/tools/trackqa-connect/src/process.js

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process';
+import { ConnectorError } from "./core.js";
+export const spawnProcess = spawn;
+export function clientEnvironment(codexHome, env = process.env) {
+    const clean = { CODEX_HOME: codexHome, RUST_LOG: 'off' };
+    for (const key of ['PATH', 'PATHEXT', 'SystemRoot', 'WINDIR', 'COMSPEC', 'USERPROFILE', 'HOME', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'TMPDIR', 'TERM', 'COLORTERM', 'LANG', 'LC_ALL', 'OPENAI_API_KEY']) {
+        if (env[key])
+            clean[key] = env[key];
+    }
+    return clean;
+}
+// stdout/stderr are bounded and never forwarded. Native client diagnostics may
+// contain unrelated configuration secrets. Callers receive only sanitized errors.
+export async function capture(executable, args, env, spawnFn = spawnProcess, cwd) {
+    return new Promise((resolve, reject) => {
+        let output = '', size = 0, settled = false;
+        const child = spawnFn(executable, args, { env, cwd, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error) {
+                child.kill();
+                reject(error);
+            }
+            else
+                resolve(output);
+        };
+        const timer = setTimeout(() => finish(new ConnectorError('client_command_timeout')), 15_000);
+        child.on('error', () => finish(new ConnectorError('client_command_failed')));
+        for (const stream of [child.stdout, child.stderr]) {
+            stream?.on('error', () => finish(new ConnectorError('client_command_failed')));
+            stream?.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > 1_048_576)
+                    finish(new ConnectorError('client_response_limit'));
+                else if (stream === child.stdout)
+                    output += chunk.toString('utf8');
+            });
+        }
+        child.on('close', code => finish(code === 0 ? undefined : new ConnectorError('client_command_failed')));
+    });
+}
+export async function foreground(executable, env, signal, spawnFn = spawnProcess, args = []) {
+    if (signal?.aborted)
+        throw new ConnectorError('interrupted');
+    await new Promise((resolve, reject) => {
+        const options = { env, stdio: 'inherit', windowsHide: false };
+        const child = spawnFn(executable, [...args], options);
+        let settled = false, stopping = false, timer;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const abort = () => {
+            if (stopping || settled)
+                return;
+            stopping = true;
+            child.kill('SIGTERM');
+            timer = setTimeout(() => { child.kill('SIGKILL'); finish(new ConnectorError('interrupted')); }, 3000);
+        };
+        signal?.addEventListener('abort', abort, { once: true });
+        child.on('error', () => finish(new ConnectorError('client_launch_failed')));
+        child.on('exit', code => finish(signal?.aborted ? new ConnectorError('interrupted') : code === 0 ? undefined : new ConnectorError('client_exit_failed')));
+        if (signal?.aborted)
+            abort();
+    });
+}

package/dist/tools/trackqa-connect/src/state.js

@@ -0,0 +1,80 @@
+import { mkdir, open, readFile, rename, unlink, lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { requireValue, UUID, setupFor } from "./core.js";
+const fields = ['projectId', 'userId', 'client', 'executable', 'clientLabel', 'connectionId', 'phase', 'installed', 'lastVerifiedAt', 'configHash'];
+export const recordHome = (record) => record.client === 'vscode-copilot' ? record.vscodeCopilotHome : record.client === 'vscode' ? record.vscodeHome : record.client === 'claude' ? record.claudeHome : record.client === 'gemini' ? record.geminiHome : record.codexHome;
+export function validateRecord(record) {
+    const homeKey = record?.client === 'vscode-copilot' ? 'vscodeCopilotHome' : record?.client === 'vscode' ? 'vscodeHome' : record?.client === 'claude' ? 'claudeHome' : record?.client === 'gemini' ? 'geminiHome' : 'codexHome';
+    requireValue(record && Object.keys(record).length === fields.length + 1 && Object.keys(record).every(key => fields.includes(key) || key === homeKey)
+        && ['codex', 'gemini', 'claude', 'vscode', 'vscode-copilot'].includes(record.client) && UUID.test(record.projectId) && UUID.test(record.userId)
+        && (record.connectionId === null || UUID.test(record.connectionId))
+        && /^TrackQA Connect [0-9a-f-]{36}$/.test(record.clientLabel)
+        && ['planned', 'installed', 'issuing', 'active', 'revocation_pending', 'revoked'].includes(record.phase)
+        && typeof record.installed === 'boolean' && path.isAbsolute(record.executable) && typeof recordHome(record) === 'string' && path.isAbsolute(recordHome(record))
+        && (record.configHash === null || /^[0-9a-f]{64}$/.test(record.configHash))
+        && (record.lastVerifiedAt === null || Number.isFinite(Date.parse(record.lastVerifiedAt))), 'recovery_invalid');
+    setupFor(record.projectId, record.client);
+}
+export class Store {
+    root;
+    constructor(root) { requireValue(path.isAbsolute(root), 'recovery_unavailable'); this.root = root; }
+    async prepare() {
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        requireValue(!(await lstat(this.root)).isSymbolicLink(), 'recovery_unavailable');
+    }
+    async read() {
+        try {
+            const file = path.join(this.root, 'connections.json');
+            const stat = await lstat(file);
+            requireValue(stat.isFile() && !stat.isSymbolicLink() && stat.size <= 131072, 'recovery_invalid');
+            const records = JSON.parse(await readFile(file, 'utf8'));
+            requireValue(Array.isArray(records) && records.length <= 200, 'recovery_invalid');
+            records.forEach(validateRecord);
+            requireValue(new Set(records.map(record => `${record.client}:${record.projectId}`)).size === records.length, 'recovery_invalid');
+            return records;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+    async write(records) {
+        records.forEach(validateRecord);
+        await this.prepare();
+        const file = path.join(this.root, `state-${randomUUID()}.tmp`);
+        const handle = await open(file, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(records, null, 2) + '\n');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            await rename(file, path.join(this.root, 'connections.json'));
+        }
+        finally {
+            await unlink(file).catch(() => { });
+        }
+    }
+    async save(record) {
+        const records = await this.read();
+        await this.write([...records.filter(item => item.projectId !== record.projectId || item.client !== record.client), record]);
+    }
+    async remove(projectId, client = 'codex') { await this.write((await this.read()).filter(record => record.projectId !== projectId || record.client !== client)); }
+    async lock() {
+        await this.prepare();
+        const file = path.join(this.root, 'connector.lock');
+        let handle;
+        try {
+            handle = await open(file, 'wx', 0o600);
+        }
+        catch {
+            throw new Error('connector_busy_or_stale_lock');
+        }
+        await handle.writeFile(JSON.stringify({ pid: process.pid }));
+        return async () => { await handle.close(); await unlink(file); };
+    }
+}

package/dist/tools/trackqa-connect/src/testing/copilot-fixture-scope.js

@@ -0,0 +1,103 @@
+// Internal, fixed-fixture test capability. Normal connect never accepts this scope.
+import { requireValue, UUID } from "../core.js";
+import { adapterClient, adapterHome } from "../clients/adapter.js";
+export const COPILOT_FIXTURE = Object.freeze({ id: '5a759e3f-50b4-4fdd-b8ad-43469a7100c0', name: 'MCP Synthetic Pilot', key: 'MCPPILOT' });
+export const FIXTURE_POLICY = 'Allow native tool_search_tool capability discovery, incidental tool references and necessary embedding-service use. Allow only trackqa_connection_status, trackqa_list_projects, trackqa_list_issues and trackqa_get_issue as application tools, once each. Prohibit trackqa_submit_finding, unrelated application tools, background/delegated agents and automatic tool approval. Discovery references are metadata, not execution authorization.';
+export const unrevokedRoute = `/rest/v1/mcp_connections?project_id=eq.${COPILOT_FIXTURE.id}&revoked_at=is.null&select=id,project_id,user_id,client_label,revoked_at&limit=2`;
+export const inventoryRoute = (table, offset) => `/rest/v1/${table}?project_id=eq.${COPILOT_FIXTURE.id}&select=*&order=id.asc&limit=100&offset=${offset}`;
+const scopes = new WeakMap();
+const permits = new WeakMap();
+export function createFixtureScope() {
+    const scope = Object.freeze({});
+    scopes.set(scope, { active: false, recovery: false, enabled: false, issued: false });
+    return scope;
+}
+function getState(scope) {
+    const state = scopes.get(scope);
+    requireValue(state, 'fixture_capability_invalid');
+    return state;
+}
+export const fixtureScopeState = (scope) => Object.freeze({ ...getState(scope) });
+export function fixtureMembershipRoute(userId) {
+    return `/rest/v1/project_members?project_id=eq.${COPILOT_FIXTURE.id}&user_id=eq.${userId}&role=eq.OWNER&select=project_id,role,project:projects(id,name,key,mcp_enabled,archived)&limit=2`;
+}
+export function fixtureRequestAllowed(scope, userId, route, method = 'GET', body) {
+    const state = getState(scope), id = COPILOT_FIXTURE.id;
+    if (method === 'GET') {
+        if ([`/rest/v1/profiles?id=eq.${userId}&select=id&limit=2`, fixtureMembershipRoute(userId),
+            `/rest/v1/project_members?project_id=eq.${id}&user_id=eq.${userId}&select=user_id,role&limit=2`,
+            `/rest/v1/projects?id=eq.${id}&select=id,name,key,mcp_enabled,archived&limit=2`, unrevokedRoute].includes(route))
+            return true;
+        for (const table of ['issues', 'ai_findings'])
+            for (let offset = 0; offset <= 2000; offset += 100)
+                if (route === inventoryRoute(table, offset))
+                    return true;
+        const filters = [state.connectionId ? `id=eq.${state.connectionId}` : null,
+            state.label ? `client_label=eq.${encodeURIComponent(state.label)}&user_id=eq.${userId}` : null].filter(Boolean);
+        return filters.some(filter => route === `/rest/v1/mcp_connections?project_id=eq.${id}&${filter}&select=id,project_id,user_id,client_label,revoked_at&limit=2`);
+    }
+    if (!state.active)
+        return false;
+    if (method === 'PATCH' && route === `/rest/v1/projects?id=eq.${id}&select=id,mcp_enabled`) {
+        if (JSON.stringify(body) === '{"mcp_enabled":false}')
+            return state.enabled || state.recovery;
+        if (JSON.stringify(body) === '{"mcp_enabled":true}' && !state.recovery && !state.enabled && !state.issued) {
+            state.enabled = true;
+            return true;
+        }
+        return false;
+    }
+    if (method === 'POST' && route === '/rest/v1/rpc/issue_mcp_connection_token' && !state.recovery && !state.issued) {
+        const value = body;
+        if (value && Object.keys(value).length === 3 && value.p_project_id === id && value.p_user_id === userId
+            && typeof value.p_client_label === 'string' && /^TrackQA Connect [0-9a-f-]{36}$/.test(value.p_client_label)) {
+            state.issued = true;
+            state.label = value.p_client_label;
+            return true;
+        }
+    }
+    return method === 'POST' && route === '/rest/v1/rpc/revoke_mcp_connection' && !!state.connectionId
+        && JSON.stringify(body) === JSON.stringify({ p_connection_id: state.connectionId });
+}
+export function observeFixtureResponse(scope, userId, route, value) {
+    const state = getState(scope);
+    if (!state.issued || !Array.isArray(value) || value.length !== 1)
+        return;
+    if (route === '/rest/v1/rpc/issue_mcp_connection_token' && UUID.test(value[0]?.connection_id))
+        state.connectionId = value[0].connection_id;
+    else if (route.startsWith('/rest/v1/mcp_connections?') && value[0]?.project_id === COPILOT_FIXTURE.id
+        && value[0]?.user_id === userId && value[0]?.client_label === state.label && UUID.test(value[0]?.id))
+        state.connectionId = value[0].id;
+}
+// Only the acceptance orchestrator calls this after two fresh preflights and
+// explicit consent. Weak identity binds it to one Owner, adapter and Store.
+export function grantFixturePermit(scope, owner, adapter, store) {
+    const state = getState(scope);
+    requireValue(!state.active && !state.recovery && !state.granted && adapterClient(adapter) === 'vscode-copilot', 'fixture_capability_invalid');
+    state.granted = true;
+    const permit = Object.freeze({});
+    permits.set(permit, { scope, owner, adapter, store, used: false, expires: Date.now() + 60_000 });
+    return permit;
+}
+export function consumeFixturePermit(permit, owner, adapter, store) {
+    const entry = permits.get(permit);
+    requireValue(entry && !entry.used && entry.expires >= Date.now() && entry.owner === owner && entry.adapter === adapter && entry.store === store
+        && !getState(entry.scope).active && adapterClient(adapter) === 'vscode-copilot' && adapterHome(adapter), 'fixture_capability_invalid');
+    entry.used = true;
+    getState(entry.scope).active = true;
+}
+export function requireFixtureActive(scope, projectId) {
+    const state = getState(scope);
+    requireValue(state.active && !state.recovery && projectId === COPILOT_FIXTURE.id, 'fixture_capability_invalid');
+}
+export function enableFixtureRecovery(scope, record) {
+    const state = getState(scope);
+    state.active = true;
+    state.recovery = true;
+    state.enabled = true;
+    if (record) {
+        state.issued = true;
+        state.label = record.clientLabel;
+        state.connectionId = record.connectionId ?? undefined;
+    }
+}