log-llm-config-staging 1.3.44

package/dist/log_config_files/collection/plugin_collector.js

@@ -0,0 +1,89 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readJSONFile, readMarkdownFile } from '../readers/file_readers.js';
+import { getInstalledPluginsPath, getPluginHooksPath, getPluginMcpPaths, getPluginSkillFilename, getPluginSkillsDir } from '../paths/path_constants_helpers.js';
+import { versionFromPluginCachePath, parseInstalledPluginKey } from './plugin_version_helpers.js';
+function collectSkillFiles(skillsDir, results, constants) {
+    const skillFilename = getPluginSkillFilename(constants);
+    try {
+        for (const d of readdirSync(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory())) {
+            const skillPath = join(skillsDir, d.name, skillFilename);
+            if (!existsSync(skillPath))
+                continue;
+            const content = readMarkdownFile(skillPath);
+            if (content !== null) {
+                const ver = versionFromPluginCachePath(skillPath, constants);
+                results.push({ file_type: 'claude_skill', file_path: skillPath, raw_content: { content, source: 'file', ...(ver ? { version: ver } : {}) } });
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`Error reading skills dir ${skillsDir}:`, err instanceof Error ? err.message : String(err));
+    }
+}
+function collectMcpFile(installPath, results, constants) {
+    const mcpPaths = getPluginMcpPaths(constants);
+    for (const rel of mcpPaths) {
+        const mcpPath = join(installPath, rel);
+        if (!existsSync(mcpPath))
+            continue;
+        const content = readJSONFile(mcpPath);
+        if (content !== null) {
+            const ver = versionFromPluginCachePath(mcpPath, constants);
+            results.push({ file_type: 'claude_plugin_mcp', file_path: mcpPath, raw_content: typeof content === 'object' ? { ...content, ...(ver ? { version: ver } : {}) } : content });
+            break;
+        }
+    }
+}
+function collectPluginInstallEntries(pluginKey, entries, results, constants) {
+    const { name: pluginName, publisher } = parseInstalledPluginKey(pluginKey);
+    const skillsDirName = getPluginSkillsDir(constants);
+    const hooksRel = getPluginHooksPath(constants);
+    for (const entry of entries) {
+        const installPath = entry?.installPath;
+        if (!installPath || typeof installPath !== 'string' || !existsSync(installPath))
+            continue;
+        const version = (entry?.version != null && entry?.version !== '') ? String(entry.version).trim() : '';
+        results.push({ file_type: 'claude_plugin_manifest', file_path: installPath, raw_content: { name: pluginName || pluginKey, version, publisher: publisher || '' } });
+        const skillsPath = join(installPath, skillsDirName);
+        if (existsSync(skillsPath))
+            collectSkillFiles(skillsPath, results, constants);
+        const hooksPath = join(installPath, hooksRel);
+        if (existsSync(hooksPath)) {
+            const content = readJSONFile(hooksPath);
+            if (content !== null) {
+                const ver = versionFromPluginCachePath(hooksPath, constants);
+                results.push({ file_type: 'claude_hooks', file_path: hooksPath, raw_content: typeof content === 'object' ? { ...content, ...(ver ? { version: ver } : {}) } : content });
+            }
+        }
+        collectMcpFile(installPath, results, constants);
+    }
+}
+function collectConfigFilesFromInstalledPlugins(constants) {
+    const home = homedir();
+    const installedPluginsPath = getInstalledPluginsPath(home, constants);
+    const results = [];
+    if (!existsSync(installedPluginsPath))
+        return results;
+    let manifest;
+    try {
+        const raw = readJSONFile(installedPluginsPath);
+        if (!raw)
+            return results;
+        manifest = raw;
+    }
+    catch {
+        return results;
+    }
+    const plugins = manifest?.plugins;
+    if (!plugins || typeof plugins !== 'object')
+        return results;
+    results.push({ file_type: 'claude_plugin_manifest', file_path: installedPluginsPath, raw_content: manifest });
+    for (const [pluginKey, entries] of Object.entries(plugins)) {
+        if (Array.isArray(entries))
+            collectPluginInstallEntries(pluginKey, entries, results, constants);
+    }
+    return results;
+}
+export { collectConfigFilesFromInstalledPlugins };

package/dist/log_config_files/collection/plugin_version_helpers.js

@@ -0,0 +1,37 @@
+/** Needles used to identify the plugin segment within a cache path. Requires backend client_path_constants. */
+function getPluginPathNeedles(constants) {
+    const needles = [];
+    if (constants.plugin_skills_dir)
+        needles.push(`/${constants.plugin_skills_dir}/`);
+    if (constants.plugin_hooks_path)
+        needles.push(`/${constants.plugin_hooks_path}`);
+    for (const p of constants.plugin_mcp_paths ?? [])
+        needles.push(`/${p}`);
+    if (!needles.length)
+        throw new Error('client_path_constants missing plugin path keys (plugin_skills_dir, plugin_hooks_path, plugin_mcp_paths)');
+    return needles;
+}
+function versionFromPluginCachePath(filePath, constants) {
+    const norm = filePath.replace(/\\/g, '/');
+    if (!norm.includes('plugins/cache/'))
+        return '';
+    const needles = getPluginPathNeedles(constants);
+    let segmentEnd = -1;
+    for (const needle of needles) {
+        const idx = norm.indexOf(needle);
+        if (idx !== -1 && (segmentEnd === -1 || idx < segmentEnd))
+            segmentEnd = idx;
+    }
+    if (segmentEnd === -1)
+        return '';
+    const before = norm.slice(0, segmentEnd);
+    const lastSlash = before.lastIndexOf('/');
+    return lastSlash === -1 ? '' : before.slice(lastSlash + 1).trim();
+}
+function parseInstalledPluginKey(pluginKey) {
+    const at = pluginKey.indexOf('@');
+    if (at === -1)
+        return { name: pluginKey.trim(), publisher: '' };
+    return { name: pluginKey.slice(0, at).trim(), publisher: pluginKey.slice(at + 1).trim() };
+}
+export { versionFromPluginCachePath, parseInstalledPluginKey };

package/dist/log_config_files/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Barrel — all public exports. Sub-modules live in this folder.
+export { BATCH_CHUNK_SIZE } from './sender/batch_sender.js';
+export { sendConfigFile, sendConfigFilesBatch, sendIngestSessionStart, sendIngestSessionFinish } from './sender/batch_sender.js';
+export { createSignature, canonicalizePayload } from './sender/signing.js';
+export { readVSCDBState } from './readers/vscdb_reader.js';
+export { readJSONFile, readMarkdownFile } from './readers/file_readers.js';
+export { resolvePatternToTargets } from './paths/pattern_resolver.js';
+export { ensureAuthentication } from './auth/auth_flow.js';
+export { collectConfigFilesFromPatterns, collectConfigFilesFromInstalledPlugins, collectMcpToolFiles, determineFileTypeFromPath, } from './collection/config_collector.js';
+export { main, logSingleFile } from './runtime/main_runner.js';
+// Entry point guard (when invoked directly via npx or node)
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.includes('log_config_files')) {
+    const { main } = await import('./runtime/main_runner.js');
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/dist/log_config_files/paths/path_constants_helpers.js

@@ -0,0 +1,71 @@
+/**
+ * Build paths from backend client_path_constants + home.
+ * All functions require constants from the API response — no hardcoded fallbacks.
+ * Throws if constants or a required key is missing.
+ */
+import { join } from 'node:path';
+function requireKey(constants, key, label) {
+    const val = constants[key];
+    if (val === undefined || val === null)
+        throw new Error(`client_path_constants missing required key "${String(key)}" (${label})`);
+    return val;
+}
+export function getVscdbPath(home, constants) {
+    const segments = requireKey(constants, 'vscdb_path_under_home', 'vscdb path segments');
+    return join(home, ...segments);
+}
+export function getExtensionsCachePath(home, constants) {
+    const segments = requireKey(constants, 'extensions_cache_path_under_home', 'extensions cache path segments');
+    return join(home, ...segments);
+}
+export function getCursorProjectsPath(home, constants) {
+    const rel = requireKey(constants, 'cursor_projects_path_under_home', 'cursor projects path');
+    return join(home, rel.replace(/^~\//, ''));
+}
+export function getInstalledPluginsPath(home, constants) {
+    const rel = requireKey(constants, 'installed_plugins_path_under_home', 'installed plugins path');
+    return join(home, rel.replace(/^~\//, ''));
+}
+export function getOptAiSecManagementPath(home, constants) {
+    const rel = requireKey(constants, 'opt_ai_sec_management_under_home', 'opt-ai-sec management path');
+    return join(home, rel.replace(/^~\//, ''));
+}
+export function getAuthKeyPathFromConstants(home, constants) {
+    const base = getOptAiSecManagementPath(home, constants);
+    const filename = requireKey(constants, 'auth_key_filename', 'auth key filename');
+    return join(base, filename);
+}
+export function getHookLogPathFromConstants(home, constants) {
+    const base = getOptAiSecManagementPath(home, constants);
+    const filename = requireKey(constants, 'hook_log_filename', 'hook log filename');
+    return join(base, filename);
+}
+export function getSensitivePathsAuditPathFromConstants(home, constants) {
+    const base = getOptAiSecManagementPath(home, constants);
+    const filename = requireKey(constants, 'sensitive_paths_audit_filename', 'sensitive paths audit filename');
+    return join(base, filename);
+}
+export function getExtensionsCacheInstalledSuffix(constants) {
+    return requireKey(constants, 'extensions_cache_installed_suffix', 'extensions cache installed suffix');
+}
+export function getPluginSkillFilename(constants) {
+    return requireKey(constants, 'plugin_skill_filename', 'plugin skill filename');
+}
+export function getPluginSkillsDir(constants) {
+    return requireKey(constants, 'plugin_skills_dir', 'plugin skills directory');
+}
+export function getPluginHooksPath(constants) {
+    return requireKey(constants, 'plugin_hooks_path', 'plugin hooks path');
+}
+export function getPluginMcpPaths(constants) {
+    return requireKey(constants, 'plugin_mcp_paths', 'plugin mcp paths');
+}
+/** Build path from a path_constant_key (from PATH_RESOLUTION_SPECS). Keeps pattern_resolver data-driven. */
+export function getPathByConstantKey(home, constants, pathConstantKey) {
+    const val = constants[pathConstantKey];
+    if (Array.isArray(val))
+        return join(home, ...val);
+    if (typeof val === 'string')
+        return join(home, val.replace(/^~\//, ''));
+    throw new Error(`client_path_constants missing required key "${pathConstantKey}"`);
+}

package/dist/log_config_files/paths/pattern_resolver.js

@@ -0,0 +1,227 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPathByConstantKey, getExtensionsCacheInstalledSuffix } from './path_constants_helpers.js';
+const RECURSIVE_GLOB_MAX_DEPTH = 20;
+/** Only non-empty strings (empty would match all dirs via startsWith('')). */
+function normalizePathSkipPrefixes(prefixes) {
+    if (!Array.isArray(prefixes))
+        return [];
+    return prefixes.filter((p) => typeof p === 'string' && p.length > 0);
+}
+function expandRecursiveGlobPathPattern(pathPattern, fileType, home, contentFormat, dirGlob, homeRecurseSkipDirs = []) {
+    const norm = pathPattern.replace(/\\/g, '/');
+    const doubleStarIndex = norm.indexOf('**');
+    if (doubleStarIndex === -1)
+        return [];
+    const before = norm.slice(0, doubleStarIndex).replace(/\/+$/, '');
+    const after = norm.slice(doubleStarIndex + 2).replace(/^\/+/, '');
+    if (!after)
+        return [];
+    let basePath;
+    if (before === '~' || before.startsWith('~/')) {
+        basePath = join(home, before === '~' ? '' : before.slice(2));
+    }
+    else {
+        return [];
+    }
+    const targets = [];
+    const parts = after.split('/');
+    const dirName = parts[0];
+    const fileName = parts.length > 1 ? parts[parts.length - 1] : null;
+    const skipSet = homeRecurseSkipDirs.length ? new Set(homeRecurseSkipDirs) : new Set();
+    function walk(dir, depth, isHomeRoot) {
+        if (depth > RECURSIVE_GLOB_MAX_DEPTH || !existsSync(dir))
+            return;
+        try {
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                const full = join(dir, entry.name);
+                if (!entry.isDirectory())
+                    continue;
+                if (isHomeRoot && skipSet.has(entry.name))
+                    continue;
+                if (entry.name === dirName) {
+                    const filePath = parts.length === 1 ? full : join(full, ...parts.slice(1));
+                    if (fileName && existsSync(filePath))
+                        targets.push({ path: filePath, file_type: fileType, content_format: contentFormat });
+                }
+                walk(full, depth + 1, false);
+            }
+        }
+        catch { /* ignore read errors */ }
+    }
+    walk(basePath, 0, true);
+    return targets;
+}
+function expandGlobPathPattern(pathPattern, fileType, home, projectRoot, contentFormat, dirGlob, absolutePathPrefixes = []) {
+    const norm = pathPattern.replace(/\\/g, '/');
+    const targets = [];
+    const asteriskIndex = norm.indexOf('*');
+    if (asteriskIndex === -1)
+        return targets;
+    const isDir = norm.endsWith('/');
+    const [before, after] = norm.split('*');
+    const afterNorm = after.replace(/^\/+/, '');
+    // If `before` doesn't end with '/', the * is mid-segment (e.g. "extensions/saoudrizwan.claude-dev*/" →
+    // parent="extensions/", namePrefix="saoudrizwan.claude-dev"). Split on last '/' to get the real base dir.
+    let parentPart = before.replace(/\/+$/, '');
+    let namePrefix = '';
+    if (!before.endsWith('/')) {
+        const lastSlash = parentPart.lastIndexOf('/');
+        if (lastSlash !== -1) {
+            namePrefix = parentPart.slice(lastSlash + 1);
+            parentPart = parentPart.slice(0, lastSlash);
+        }
+    }
+    let basePath;
+    if (parentPart.startsWith('~/')) {
+        basePath = join(home, parentPart.slice(2));
+    }
+    else if (parentPart.startsWith('/') && absolutePathPrefixes.some((prefix) => parentPart.startsWith(prefix))) {
+        basePath = parentPart;
+    }
+    else {
+        basePath = join(projectRoot, parentPart.startsWith('/') ? parentPart.slice(1) : parentPart);
+    }
+    if (!existsSync(basePath))
+        return targets;
+    try {
+        for (const entry of readdirSync(basePath, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            if (namePrefix && !entry.name.startsWith(namePrefix))
+                continue;
+            const resolvedPath = join(basePath, entry.name, afterNorm);
+            if (!existsSync(resolvedPath))
+                continue;
+            targets.push({ path: resolvedPath, file_type: fileType, isDirectory: isDir, dir_glob: dirGlob, content_format: contentFormat });
+        }
+    }
+    catch { /* ignore read errors */ }
+    return targets;
+}
+/**
+ * Expand MCP tool glob from backend spec. No hardcoded .cursor/mcps/tools; structure comes from API.
+ */
+function expandGlobFromSpec(spec, home, pathSkipPrefixes = []) {
+    const targets = [];
+    const basePath = join(home, spec.base_path_under_home.replace(/^~\//, ''));
+    if (!existsSync(basePath))
+        return targets;
+    const skipPrefixes = normalizePathSkipPrefixes(pathSkipPrefixes);
+    function matchesGlob(name, pattern) {
+        if (pattern === '*')
+            return true;
+        if (pattern.startsWith('*.')) {
+            const ext = pattern.slice(1);
+            return name.endsWith(ext);
+        }
+        return name === pattern;
+    }
+    function recurse(currentPath, segmentIndex, wildcardValues) {
+        if (segmentIndex === spec.segments.length) {
+            try {
+                for (const entry of readdirSync(currentPath, { withFileTypes: true })) {
+                    if (entry.isDirectory())
+                        continue;
+                    const name = entry.name;
+                    const full = join(currentPath, name);
+                    if (!matchesGlob(name, spec.file_glob))
+                        continue;
+                    const values = [...wildcardValues, name];
+                    let logical = spec.logical_path_template;
+                    for (let i = 0; i < values.length; i++) {
+                        logical = logical.replace(new RegExp(`\\{\\{${i}\\}\\}`, 'g'), values[i]);
+                    }
+                    targets.push({
+                        path: full,
+                        file_type: spec.file_type,
+                        content_format: spec.content_format,
+                        logicalFilePath: logical,
+                    });
+                }
+            }
+            catch { /* ignore */ }
+            return;
+        }
+        const seg = spec.segments[segmentIndex];
+        if (seg.type === 'literal') {
+            const next = join(currentPath, seg.name);
+            if (existsSync(next))
+                recurse(next, segmentIndex + 1, wildcardValues);
+            return;
+        }
+        if (seg.type === 'dir_wildcard') {
+            const skips = seg.skip_prefixes?.length ? normalizePathSkipPrefixes(seg.skip_prefixes) : skipPrefixes;
+            try {
+                for (const entry of readdirSync(currentPath, { withFileTypes: true })) {
+                    if (!entry.isDirectory())
+                        continue;
+                    if (skips.some((p) => entry.name.startsWith(p)))
+                        continue;
+                    recurse(join(currentPath, entry.name), segmentIndex + 1, [...wildcardValues, entry.name]);
+                }
+            }
+            catch { /* ignore */ }
+        }
+    }
+    recurse(basePath, 0, []);
+    return targets;
+}
+function pushTargetPaths(targets, p, fileType, isDir, collectStyle, contentFormat, dirGlob) {
+    if (isDir) {
+        targets.push({ path: p, file_type: fileType, isDirectory: true, dir_glob: dirGlob, collect_style: collectStyle, content_format: contentFormat });
+    }
+    else {
+        targets.push({ path: p, file_type: fileType, collect_style: collectStyle, content_format: contentFormat });
+    }
+}
+/**
+ * Resolve a single (path, type, file_type) from the API to concrete collection targets.
+ */
+function resolvePatternToTargets(pathPattern, pathType, fileType, projectRoot, home, pathSkipPrefixes = [], collectStyle, contentFormat, dirGlob, homeRecurseSkipDirs = [], pathResolution, resolveUnderHome = true, absolutePathPrefixes = [], mcpToolGlobSpec, clientPathConstants, pathResolutionSpecs) {
+    const norm = pathPattern.replace(/\\/g, '/');
+    const targets = [];
+    const spec = pathResolution && pathResolutionSpecs?.[pathResolution] ? pathResolutionSpecs[pathResolution] : null;
+    if (spec?.type === 'mcp_tool_glob' && mcpToolGlobSpec) {
+        return expandGlobFromSpec(mcpToolGlobSpec, home, pathSkipPrefixes);
+    }
+    if (spec?.type === 'vscdb') {
+        if (!clientPathConstants)
+            throw new Error(`client_path_constants required to resolve path_resolution="${pathResolution}"`);
+        const basePath = getPathByConstantKey(home, clientPathConstants, spec.path_constant_key);
+        const sep = spec.fragment_separator;
+        const fragment = norm.includes(sep) ? sep + norm.split(sep).slice(1).join(sep) : spec.default_fragment;
+        targets.push({ path: basePath + fragment, file_type: fileType, content_format: contentFormat });
+        return targets;
+    }
+    if (spec?.type === 'extensions_cache') {
+        if (!clientPathConstants)
+            throw new Error(`client_path_constants required to resolve path_resolution="${pathResolution}"`);
+        const basePath = getPathByConstantKey(home, clientPathConstants, spec.path_constant_key);
+        const suffix = getExtensionsCacheInstalledSuffix(clientPathConstants);
+        targets.push({ path: basePath + suffix, file_type: fileType, content_format: contentFormat ?? 'extensions_cache' });
+        return targets;
+    }
+    if (norm.includes('**'))
+        return expandRecursiveGlobPathPattern(pathPattern, fileType, home, contentFormat, dirGlob, homeRecurseSkipDirs);
+    if (norm.includes('*'))
+        return expandGlobPathPattern(pathPattern, fileType, home, projectRoot, contentFormat, dirGlob, absolutePathPrefixes);
+    const isDir = pathType === 'dir' || norm.endsWith('/');
+    const rel = norm.replace(/\/+$/, '');
+    if (norm.startsWith('/') && absolutePathPrefixes.some((prefix) => norm.startsWith(prefix))) {
+        pushTargetPaths(targets, norm, fileType, isDir, collectStyle, contentFormat, dirGlob);
+        return targets;
+    }
+    if (norm.startsWith('~/')) {
+        pushTargetPaths(targets, join(home, rel.slice(2)), fileType, isDir, collectStyle, contentFormat, dirGlob);
+        return targets;
+    }
+    const stripLeadingSlash = rel.startsWith('/') ? rel.slice(1) : rel;
+    pushTargetPaths(targets, join(projectRoot, stripLeadingSlash), fileType, isDir, collectStyle, contentFormat, dirGlob);
+    if (stripLeadingSlash.startsWith('.') && resolveUnderHome) {
+        pushTargetPaths(targets, join(home, stripLeadingSlash), fileType, isDir, collectStyle, contentFormat, dirGlob);
+    }
+    return targets;
+}
+export { normalizePathSkipPrefixes, resolvePatternToTargets, expandGlobFromSpec };
+export { expandRecursiveGlobPathPattern, expandGlobPathPattern };

package/dist/log_config_files/readers/file_readers.js

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs';
+/** Read and parse an MCP config file. Returns null on any error. */
+function readMCPConfig(filePath) {
+    try {
+        if (!existsSync(filePath))
+            return null;
+        return JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    catch (error) {
+        console.error(`Error reading ${filePath}:`, error instanceof Error ? error.message : String(error));
+        return null;
+    }
+}
+/** Read and parse a JSON file. Warns on permission errors, returns null on any failure. */
+function readJSONFile(filePath) {
+    try {
+        if (!existsSync(filePath))
+            return null;
+        return JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    catch (error) {
+        if (error.code === 'EACCES' || error.code === 'EPERM') {
+            console.warn(`Permission denied reading ${filePath} (may require elevated permissions)`);
+        }
+        return null;
+    }
+}
+/** Read a text/markdown file. Warns on permission errors, returns null on any failure. */
+function readMarkdownFile(filePath) {
+    try {
+        if (!existsSync(filePath))
+            return null;
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'EACCES' || error.code === 'EPERM') {
+            console.warn(`Permission denied reading ${filePath} (may require elevated permissions)`);
+        }
+        return null;
+    }
+}
+/** Read installed extensions from Cursor extensions cache file. */
+function readInstalledExtensions(extensionsCachePath) {
+    const pathToRead = extensionsCachePath;
+    const extensions = [];
+    try {
+        if (!existsSync(pathToRead))
+            return extensions;
+        const data = JSON.parse(readFileSync(pathToRead, 'utf-8'));
+        if (data.result && Array.isArray(data.result)) {
+            for (const ext of data.result) {
+                const id = ext.identifier?.id;
+                if (id) {
+                    extensions.push({
+                        id,
+                        displayName: ext.manifest?.displayName || ext.manifest?.publisher || '',
+                        version: ext.manifest?.version || '',
+                        publisher: ext.manifest?.publisher,
+                    });
+                }
+            }
+        }
+    }
+    catch (error) {
+        console.warn(`Error reading installed extensions from cache (${pathToRead}):`, error instanceof Error ? error.message : String(error));
+    }
+    return extensions;
+}
+export { readMCPConfig, readJSONFile, readMarkdownFile, readInstalledExtensions };

package/dist/log_config_files/readers/vscdb_config_builder.js

@@ -0,0 +1,146 @@
+import { homedir } from 'node:os';
+import { readVSCDBState } from './vscdb_reader.js';
+import { getVscdbPath } from '../paths/path_constants_helpers.js';
+import { getByPath } from '../collection/enrichment_helpers.js';
+import { hookRunLog } from '../runtime/hook_logger.js';
+/** True if path is a vscdb virtual path (db file or db#fragment). Uses backend vscdb_basename and vscdb_entry_specs only. */
+export function isVscdbVirtualPath(filePath, response) {
+    if (!response?.vscdb_entry_specs?.length)
+        return false;
+    const norm = filePath.replace(/\\/g, '/');
+    if (norm.includes('#')) {
+        const fragment = '#' + norm.split('#').slice(1).join('#');
+        if (response.vscdb_entry_specs.some((s) => s.path_suffix === fragment))
+            return true;
+    }
+    if (response.vscdb_basename && (norm.endsWith(response.vscdb_basename) || norm.endsWith(response.vscdb_basename + '#')))
+        return true;
+    return false;
+}
+/**
+ * If path is a vscdb virtual path per API response, read DB and build raw_content + file_type; else return null.
+ * Caller uses this so main_runner has no state.vscdb branches.
+ */
+export function tryReadVscdbVirtualFile(filePath, response) {
+    if (!response?.vscdb_entry_specs?.length)
+        return null;
+    const norm = filePath.replace(/\\/g, '/');
+    const actualPath = norm.split('#')[0];
+    const pathSuffix = norm.includes('#') ? '#' + norm.split('#').slice(1).join('#') : '#composerState';
+    const spec = response.vscdb_entry_specs.find((s) => s.path_suffix === pathSuffix) ?? response.vscdb_entry_specs.find((s) => s.path_suffix === '#composerState');
+    if (!spec)
+        return null;
+    const isAbsolute = actualPath.startsWith('/') || (actualPath.length >= 2 && actualPath[1] === ':');
+    if (!response.client_path_constants)
+        throw new Error('client_path_constants required from API response to resolve vscdb path');
+    const defaultVscdbPath = getVscdbPath(homedir(), response.client_path_constants);
+    const dbPath = isAbsolute ? actualPath : defaultVscdbPath;
+    const vscdbState = readVSCDBState(dbPath, response.vscdb_read_queries ?? undefined, response.vscdb_merge_from_composer_state ?? undefined);
+    if (!vscdbState)
+        return null;
+    const rawContent = buildVscdbRawContentFromSpec(vscdbState, spec);
+    if (!rawContent)
+        return null;
+    return { rawContent, fileType: spec.file_type };
+}
+function setNested(obj, dotPath, value) {
+    const parts = dotPath.split('.');
+    const safe = (k) => k !== '__proto__' && k !== 'constructor' && k !== 'prototype';
+    if (!parts.every(safe))
+        return;
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const p = parts[i];
+        if (!(p in cur) || typeof cur[p] !== 'object')
+            cur[p] = Object.create(null);
+        cur = cur[p];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+function buildRawContent(state, stateKey, value, includeKeys, ts) {
+    const raw = { source: 'state.vscdb', extracted_at: ts };
+    if (stateKey.includes('.')) {
+        setNested(raw, stateKey, value);
+    }
+    else {
+        raw[stateKey] = value;
+    }
+    if (includeKeys?.length) {
+        for (const k of includeKeys) {
+            if (k in state && state[k] !== undefined)
+                raw[k] = state[k];
+        }
+    }
+    return raw;
+}
+/** Build raw_content for a single state.vscdb fragment from a backend spec. Validation uses spec.value_constraint only. */
+function buildVscdbRawContentFromSpec(state, spec) {
+    const value = getByPath(state, spec.state_key);
+    if (value === undefined || value === null)
+        return null;
+    if (spec.value_constraint === 'non_empty_array') {
+        if (!Array.isArray(value) || value.length === 0)
+            return null;
+    }
+    if (spec.value_constraint === 'boolean') {
+        const okBool = typeof value === 'boolean';
+        const okSqliteInt = typeof value === 'number' && (value === 0 || value === 1);
+        if (!okBool && !okSqliteInt)
+            return null;
+    }
+    return buildRawContent(state, spec.state_key, value, spec.include_keys, new Date().toISOString());
+}
+/**
+ * Build config file entries from state.vscdb using backend-driven specs and read queries.
+ * No hardcoded file_type, path fragments, or ItemTable keys; all from API.
+ */
+function summarizeComposerStateValue(composerState) {
+    if (composerState === null || composerState === undefined || typeof composerState !== 'object' || Array.isArray(composerState)) {
+        return `composerState_type=${composerState === null ? 'null' : typeof composerState}`;
+    }
+    const o = composerState;
+    const m4 = o.modes4;
+    if (!Array.isArray(m4))
+        return `modes4=${m4 === undefined ? 'absent' : typeof m4}`;
+    const agent = m4.find((x) => x !== null && typeof x === 'object' && !Array.isArray(x) && x.id === 'agent');
+    if (!agent)
+        return `modes4_len=${m4.length} agent_row=missing`;
+    return `modes4_len=${m4.length} agent_autoRun=${JSON.stringify(agent.autoRun)} agent_fullAutoRun=${JSON.stringify(agent.fullAutoRun)}`;
+}
+/** Exported for main_runner: one-line summary of uploaded #composerState payload (policy full-auto-run input). */
+export function summarizeComposerPayloadForDiagnostics(raw) {
+    const inner = summarizeComposerStateValue(raw.composerState);
+    const rawKeys = Object.keys(raw)
+        .filter((k) => k !== 'source' && k !== 'extracted_at')
+        .slice(0, 16);
+    return `${inner} payload_keys=[${rawKeys.join(',')}]`;
+}
+function collectVscdbEntries(vscdbPath, specs, readQueries, mergeFromComposerState) {
+    if (!specs?.length)
+        return [];
+    const state = readVSCDBState(vscdbPath, readQueries, mergeFromComposerState);
+    if (!state || typeof state !== 'object') {
+        hookRunLog(`diag vscdb collect: readVSCDBState returned null/invalid vscdb=${vscdbPath}`);
+        return [];
+    }
+    const sk = Object.keys(state);
+    hookRunLog(`diag vscdb collect: readVSCDBState ok vscdb=${vscdbPath} top_keys=[${sk.slice(0, 24).join(',')}] ${summarizeComposerStateValue(state.composerState)}`);
+    const entries = [];
+    for (const spec of specs) {
+        const atPath = getByPath(state, spec.state_key);
+        const rawContent = buildVscdbRawContentFromSpec(state, spec);
+        if (!rawContent) {
+            if (spec.state_key === 'composerState' || spec.path_suffix === '#composerState') {
+                hookRunLog(`diag vscdb collect: skipped composer emit value_constraint=${spec.value_constraint ?? 'none'} at_path=${atPath === undefined ? 'undefined' : atPath === null ? 'null' : typeof atPath} path_suffix=${spec.path_suffix}`);
+            }
+            continue;
+        }
+        entries.push({
+            file_type: spec.file_type,
+            file_path: `${vscdbPath}${spec.path_suffix}`,
+            raw_content: rawContent,
+        });
+    }
+    return entries;
+}
+export { collectVscdbEntries, buildVscdbRawContentFromSpec };