@optimuslabs/harness-map-staging 1.5.16

package/dist/log_config_files/collection/skills_cli_collector.js

@@ -0,0 +1,162 @@
+import { spawnSync } from 'node:child_process';
+import { closeSync, mkdtempSync, openSync, readFileSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const SKILLS_CLI_FILE_TYPE = 'skills_cli_installed';
+export const SKILLS_CLI_INSTALLED_PATH = join(homedir(), '.agents', '.skills-cli-installed.json');
+/** Override the skills package spec, e.g. `skills@1.5.10`. Default uses whatever is on the machine. */
+export const SKILLS_CLI_NPX_PACKAGE_ENV = 'SKILLS_CLI_NPX_PACKAGE';
+const LIST_TIMEOUT_MS = 120_000;
+/** stderr from npx/npm only; stdout is streamed to a temp file (avoids pipe/maxBuffer truncation). */
+const LIST_STDERR_MAX_BUFFER = 16 * 1024 * 1024;
+function listExecEnv() {
+    return {
+        ...process.env,
+        DISABLE_TELEMETRY: process.env.DISABLE_TELEMETRY ?? '1',
+    };
+}
+function npxPackageSpec() {
+    const fromEnv = (process.env[SKILLS_CLI_NPX_PACKAGE_ENV] || '').trim();
+    return fromEnv || 'skills';
+}
+/** Strip leading npx/npm noise and parse the skills `list --json` array payload. */
+export function parseSkillsListJsonStdout(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return [];
+    const start = trimmed.indexOf('[');
+    if (start < 0) {
+        throw new SyntaxError('skills list --json: no JSON array in stdout');
+    }
+    let end = trimmed.lastIndexOf(']');
+    let lastErr;
+    while (end > start) {
+        const slice = trimmed.slice(start, end + 1);
+        try {
+            const parsed = JSON.parse(slice);
+            if (!Array.isArray(parsed))
+                return [];
+            return parsed;
+        }
+        catch (err) {
+            lastErr = err instanceof SyntaxError ? err : new SyntaxError(String(err));
+            end = trimmed.lastIndexOf(']', end - 1);
+        }
+    }
+    throw lastErr ?? new SyntaxError('skills list --json: could not parse stdout');
+}
+export function runSkillsListJson(args, cwd) {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'optimus-skills-list-'));
+    const outPath = join(tmpDir, 'stdout.json');
+    const outFd = openSync(outPath, 'w');
+    try {
+        const child = spawnSync('npx', [npxPackageSpec(), 'list', ...args, '--json'], {
+            cwd,
+            timeout: LIST_TIMEOUT_MS,
+            env: listExecEnv(),
+            stdio: ['ignore', outFd, 'pipe'],
+            maxBuffer: LIST_STDERR_MAX_BUFFER,
+        });
+        if (child.error)
+            throw child.error;
+        if (child.status !== 0) {
+            const stderr = (child.stderr ?? '').toString().trim();
+            throw new Error(stderr || `npx skills list exited ${child.status ?? 'unknown'}`);
+        }
+    }
+    finally {
+        closeSync(outFd);
+    }
+    try {
+        const out = readFileSync(outPath, 'utf8');
+        return parseSkillsListJsonStdout(out);
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+function assignListLockFields(row, out) {
+    for (const key of ['source', 'sourceUrl', 'sourceType']) {
+        if (!Object.prototype.hasOwnProperty.call(row, key))
+            continue;
+        const raw = row[key];
+        if (raw == null) {
+            out[key] = null;
+        }
+        else {
+            const trimmed = String(raw).trim();
+            out[key] = trimmed || null;
+        }
+    }
+}
+function normalizeListRows(rows, scope) {
+    const out = [];
+    for (const row of rows) {
+        const name = (row.name || '').trim();
+        const path = (row.path || '').trim();
+        if (!name || !path)
+            continue;
+        const agents = Array.isArray(row.agents)
+            ? row.agents.map((a) => String(a).trim()).filter(Boolean)
+            : [];
+        const entry = {
+            name,
+            path,
+            scope: (row.scope || scope).trim() || scope,
+            agents,
+        };
+        assignListLockFields(row, entry);
+        out.push(entry);
+    }
+    return out;
+}
+/** One-line-per-scope summary for hook_request.log (matches `skills list --json`). */
+export function formatSkillsListScopeForHookLog(scopeLabel, entries) {
+    if (entries.length === 0) {
+        return `skills_cli list ${scopeLabel}: 0 skill(s)`;
+    }
+    const detail = entries
+        .map((e) => `${e.name}@${e.path} agents=${e.agents.length ? e.agents.join(',') : 'none'}`)
+        .join(' | ');
+    return `skills_cli list ${scopeLabel}: ${entries.length} skill(s) — ${detail}`;
+}
+function runSkillsListForScope(scopeLabel, args, projectRoot, logLine) {
+    try {
+        return runSkillsListJson(args, projectRoot);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logLine(`skills_cli: list ${scopeLabel} --json failed: ${msg}`);
+        return [];
+    }
+}
+export function collectSkillsCliInstalled(projectRoot, log) {
+    const logLine = (message) => {
+        log?.(message);
+    };
+    const packageSpec = npxPackageSpec();
+    logLine(`skills_cli: npx ${packageSpec} — list -g --json && list --json (projectRoot=${projectRoot})`);
+    const globalRows = runSkillsListForScope('-g', ['-g'], projectRoot, logLine);
+    const projectRows = runSkillsListForScope('project', [], projectRoot, logLine);
+    const global = normalizeListRows(globalRows, 'global');
+    const project = normalizeListRows(projectRows, 'project');
+    logLine(formatSkillsListScopeForHookLog('-g', global));
+    logLine(formatSkillsListScopeForHookLog('project', project));
+    const payload = {
+        version: 1,
+        skills_cli_version: packageSpec,
+        generated_at: new Date().toISOString(),
+        global,
+        project,
+    };
+    if (payload.global.length === 0 && payload.project.length === 0) {
+        logLine('skills_cli_installed: not uploaded (no global or project skills)');
+        return null;
+    }
+    logLine(`skills_cli_installed: upload ${SKILLS_CLI_INSTALLED_PATH} global=${global.length} project=${project.length}`);
+    return {
+        file_type: SKILLS_CLI_FILE_TYPE,
+        file_path: SKILLS_CLI_INSTALLED_PATH,
+        raw_content: payload,
+    };
+}

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, 'optimuslabs_management_under_home', '.optimuslabs 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,326 @@
+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);
+}
+/**
+ * Expands glob patterns with double-asterisk (recursive directory traversal).
+ *
+ * Example: ~/.cursor/plugins/cache/ ** /skills/ recursively finds all skills
+ * directories under the cache folder, up to RECURSIVE_GLOB_MAX_DEPTH.
+ *
+ * @param pathPattern - Glob pattern with double-asterisk for recursive descent
+ * @param fileType - File type classification for collected targets
+ * @param home - User home directory path
+ * @param contentFormat - Optional content format hint
+ * @param dirGlob - Optional directory glob pattern
+ * @param homeRecurseSkipDirs - Directory names to skip when recursing from home
+ * @returns Array of collection targets matching the pattern
+ */
+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('/').filter((s) => s.length > 0);
+    if (parts.length === 0)
+        return [];
+    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 (parts.length === 1) {
+                        // e.g. ~/.cursor/plugins/cache/**/skills/ — collect each matched skills/ tree as a directory target
+                        if (existsSync(filePath)) {
+                            targets.push({
+                                path: filePath,
+                                file_type: fileType,
+                                isDirectory: true,
+                                content_format: contentFormat,
+                                dir_glob: dirGlob,
+                            });
+                        }
+                    }
+                    else 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;
+}
+/**
+ * Expands glob patterns with asterisk wildcards (non-recursive) into concrete file or directory paths.
+ *
+ * Supports multi-segment wildcards (e.g., star-slash-star-slash patterns).
+ *
+ * **Key behavior:** On the final segment of a file pattern (not ending in slash), wildcards match
+ * files; earlier segments—and directory patterns—match directories only. This allows filename
+ * patterns like local_STAR.json to correctly resolve files rather than directories.
+ *
+ * Examples:
+ * - Pattern ending with a literal filename matches that file in wildcard directories
+ * - Pattern ending with prefix_STAR.ext matches files with that prefix and extension
+ * - Pattern ending with slash matches only directories
+ *
+ * @param pathPattern - Glob pattern (may not contain double-asterisk; use expandRecursiveGlobPathPattern for that)
+ * @param fileType - File type classification for collected targets
+ * @param home - User home directory path
+ * @param projectRoot - Project root directory path
+ * @param contentFormat - Optional content format hint
+ * @param dirGlob - Optional directory glob pattern
+ * @param absolutePathPrefixes - Allowed absolute path prefixes
+ * @returns Array of collection targets matching the pattern
+ */
+function expandGlobPathPattern(pathPattern, fileType, home, projectRoot, contentFormat, dirGlob, absolutePathPrefixes = []) {
+    const norm = pathPattern.replace(/\\/g, '/');
+    if (!norm.includes('*'))
+        return [];
+    // `**` is the recursive-glob sigil handled by expandRecursiveGlobPathPattern.
+    if (norm.includes('**'))
+        return [];
+    const isDir = norm.endsWith('/');
+    // Resolve the literal prefix that ends before the first wildcard segment.
+    const firstStarIndex = norm.indexOf('*');
+    const lastSlashBeforeStar = norm.lastIndexOf('/', firstStarIndex);
+    if (lastSlashBeforeStar === -1)
+        return [];
+    const parentPart = norm.slice(0, lastSlashBeforeStar);
+    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 [];
+    // Walk remaining segments. Each segment may be a bare wildcard '*' (matches
+    // any single directory), a prefix/suffix wildcard like 'foo*' or 'foo*bar',
+    // or a literal name. Recursion correctly handles multi-wildcard patterns
+    // such as ``*/*/cowork_plugins/marketplaces/*/.claude-plugin/marketplace.json``
+    // — the prior single-split implementation only expanded the first wildcard
+    // and silently pushed a partial directory path as the target, which then
+    // surfaced as EISDIR when downstream collectors tried to read it as a file.
+    const remaining = norm.slice(lastSlashBeforeStar + 1);
+    const segments = remaining.split('/').filter((s) => s !== '');
+    const targets = [];
+    function recurse(currentPath, segIdx) {
+        if (segIdx === segments.length) {
+            if (!existsSync(currentPath))
+                return;
+            targets.push({ path: currentPath, file_type: fileType, isDirectory: isDir, dir_glob: dirGlob, content_format: contentFormat });
+            return;
+        }
+        const seg = segments[segIdx];
+        // On the final segment of a file pattern (not ending in `/`) wildcards
+        // match files; earlier segments — and dir patterns — match directories.
+        const wantFile = segIdx === segments.length - 1 && !isDir;
+        const entryMatches = (entry) => wantFile ? entry.isFile() : entry.isDirectory();
+        if (seg === '*') {
+            if (!existsSync(currentPath))
+                return;
+            try {
+                for (const entry of readdirSync(currentPath, { withFileTypes: true })) {
+                    if (!entryMatches(entry))
+                        continue;
+                    recurse(join(currentPath, entry.name), segIdx + 1);
+                }
+            }
+            catch { /* ignore read errors */ }
+        }
+        else if (seg.includes('*')) {
+            const wildcardIdx = seg.indexOf('*');
+            const prefix = seg.slice(0, wildcardIdx);
+            const suffix = seg.slice(wildcardIdx + 1);
+            if (!existsSync(currentPath))
+                return;
+            try {
+                for (const entry of readdirSync(currentPath, { withFileTypes: true })) {
+                    if (!entryMatches(entry))
+                        continue;
+                    if (prefix && !entry.name.startsWith(prefix))
+                        continue;
+                    if (suffix && !entry.name.endsWith(suffix))
+                        continue;
+                    recurse(join(currentPath, entry.name), segIdx + 1);
+                }
+            }
+            catch { /* ignore read errors */ }
+        }
+        else {
+            recurse(join(currentPath, seg), segIdx + 1);
+        }
+    }
+    recurse(basePath, 0);
+    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 (spec?.type === 'env_dir_file') {
+        const configuredDir = process.env[spec.env_var]?.trim();
+        const baseDir = configuredDir
+            ? configuredDir.replace(/^~\//, `${home}/`)
+            : join(home, spec.fallback_under_home.replace(/^~\//, ''));
+        pushTargetPaths(targets, join(baseDir, spec.filename), fileType, false, collectStyle, contentFormat, dirGlob);
+        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/composer_shadow_merge.js

@@ -0,0 +1,67 @@
+import { CURSOR_SHADOW_KEYS_NESTED_WINS, coalesceCursorEnabledShadowValue, stripShadowKeysFromReactiveBlobUpload, } from './cursor_shadow_merge_ruleset.js';
+const CURSOR_SHADOW_KEYS_MERGE_ENABLED_OR = new Set([
+    'isWebSearchToolEnabled',
+    'isWebSearchToolEnabled2',
+]);
+/**
+ * Collect include_keys from composer_with_include read steps (backend-driven list).
+ */
+export function shadowKeysFromReadQueries(readQueries) {
+    const keys = new Set();
+    for (const step of readQueries ?? []) {
+        if (step.value_kind === 'composer_with_include' && step.include_keys?.length) {
+            for (const k of step.include_keys) {
+                keys.add(k);
+            }
+        }
+    }
+    return [...keys];
+}
+/**
+ * Resolve one shadow key from reactive blob root + nested composerState (matches scan_targets).
+ */
+export function mergeCursorShadowKeyValue(key, root, nested) {
+    const rootVal = Object.prototype.hasOwnProperty.call(root, key) ? root[key] : undefined;
+    const nestedVal = nested && Object.prototype.hasOwnProperty.call(nested, key) ? nested[key] : undefined;
+    if (CURSOR_SHADOW_KEYS_NESTED_WINS.has(key)) {
+        if (nestedVal !== undefined)
+            return nestedVal;
+        if (rootVal !== undefined)
+            return rootVal;
+        return undefined;
+    }
+    if (CURSOR_SHADOW_KEYS_MERGE_ENABLED_OR.has(key)) {
+        return coalesceCursorEnabledShadowValue(rootVal, nestedVal);
+    }
+    if (rootVal !== undefined)
+        return rootVal;
+    return nestedVal;
+}
+/**
+ * Merge shadow keys from the reactive blob into nested composerState (canonical for policy).
+ * Matches policy_engine.scan_targets; strips duplicate top-level keys from the upload shape.
+ */
+export function mergeShadowKeysIntoComposerState(stateData, shadowKeys) {
+    if (!shadowKeys.length)
+        return;
+    const hasNested = stateData.composerState &&
+        typeof stateData.composerState === 'object' &&
+        !Array.isArray(stateData.composerState);
+    const hasRootKey = shadowKeys.some((k) => Object.prototype.hasOwnProperty.call(stateData, k));
+    if (!hasNested && !hasRootKey)
+        return;
+    let cs = stateData.composerState;
+    if (!hasNested) {
+        cs = {};
+        stateData.composerState = cs;
+    }
+    const composerState = cs;
+    const root = stateData;
+    for (const key of shadowKeys) {
+        const merged = mergeCursorShadowKeyValue(key, root, composerState);
+        if (merged !== undefined) {
+            composerState[key] = merged;
+        }
+    }
+    stripShadowKeysFromReactiveBlobUpload(stateData);
+}