@unbrained/pm-cli 2026.9.6 → 2026.9.8

package/dist/sdk/files.js

@@ -1,536 +1,2 @@
-/**
- * @module sdk/files
- *
- * Implements the pm files command surface and its agent-facing runtime behavior.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ed504f2b-8b78-5fca-a4a7-7b0709a65533")}catch(e){}}();
-import { assertInitializedTracker } from "./environment/tracker-preflight.js";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { getActiveExtensionRegistrations, hasActiveOnReadHooks, } from "../core/extensions/index.js";
-import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { locateItem, listAllItemMetadata, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
-import { readItemMetadataDerivedIndexState } from "../core/store/item-metadata-cache.js";
-import { queryLinkedFileMetadataIndex } from "../core/store/item-metadata-query-index.js";
-import { resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
-import { readSettings } from "../core/store/settings.js";
-import { resolveAuthor } from "../core/shared/author.js";
-import { isPathWithinDirectory } from "../core/fs/path-utils.js";
-import { dedupeLinkedArtifacts, normalizeLinkedPath, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, } from "./linked-artifacts.js";
-import { explainSourceTraceability, } from "./traceability/source-traceability.js";
-/** Bounds fuzzy relative-path scanning while preserving full absolute-path discovery. */
-const RELATIVE_REFERENCE_SCAN_MAX_CHARS = 32_768;
-function normalizeCandidatePathForOutput(value) {
-    return normalizeLinkedPath(path.normalize(value));
-}
-async function realpathForContainment(inputPath) {
-    try {
-        return await fs.realpath(inputPath);
-    }
-    catch {
-        return path.resolve(inputPath);
-    }
-}
-function linkedFileResolvedKey(linkedFile, projectRoot) {
-    const resolvedPath = path.isAbsolute(linkedFile.path)
-        ? path.resolve(linkedFile.path)
-        : path.resolve(projectRoot, linkedFile.path);
-    return `${normalizeCandidatePathForOutput(resolvedPath)}::${linkedFile.scope}`;
-}
-function collectTextReferences(value, fieldPath, references) {
-    if (typeof value === "string") {
-        const trimmed = value.trim();
-        if (trimmed.length > 0) {
-            references.push({ field: fieldPath, value: trimmed });
-        }
-        return;
-    }
-    if (Array.isArray(value)) {
-        value.forEach((entry, index) => collectTextReferences(entry, `${fieldPath}[${index}]`, references));
-        return;
-    }
-    if (typeof value === "object" && value !== null) {
-        for (const [key, nested] of Object.entries(value)) {
-            /* c8 ignore next -- root-level object traversal always carries a non-empty field path in current callers. */
-            collectTextReferences(nested, fieldPath ? `${fieldPath}.${key}` : key, references);
-        }
-    }
-}
-function collectItemTextReferences(document) {
-    const references = [];
-    collectTextReferences(document.metadata, "metadata", references);
-    collectTextReferences(document.body, "body", references);
-    return references;
-}
-function cleanupPathToken(value) {
-    let next = value.trim();
-    next = next.replace(/^[`"'<([{]+/u, "");
-    next = next.replace(/[`"'>)\]},;!?]+$/u, "");
-    next = next.replace(/[.]+$/u, "");
-    next = next.replace(/:(?:\d+)(?::\d+)?$/u, "");
-    next = next.replace(/[.]+$/u, "");
-    return next;
-}
-function extractRawPathReferences(references) {
-    const rawReferences = [];
-    const absolutePattern = /(?:[A-Za-z]:[\\/]|\/)[^\s"'`<>()[\]{},;]+/gu;
-    const relativePattern = /(?:\.{1,2}[\\/])?(?:(?:[A-Za-z0-9_.@-]+[\\/])+[A-Za-z0-9_.@-]+|[A-Za-z0-9_.@-]+\.[A-Za-z0-9][A-Za-z0-9._-]*)/gu;
-    for (const reference of references) {
-        const seenInField = new Set();
-        const boundedRelativeValue = reference.value.slice(0, RELATIVE_REFERENCE_SCAN_MAX_CHARS);
-        for (const [pattern, input] of [
-            [absolutePattern, reference.value],
-            [relativePattern, boundedRelativeValue],
-        ]) {
-            pattern.lastIndex = 0;
-            for (const match of input.matchAll(pattern)) {
-                const token = cleanupPathToken(match[0]);
-                if (!token || seenInField.has(token)) {
-                    continue;
-                }
-                seenInField.add(token);
-                rawReferences.push({ field: reference.field, value: token });
-            }
-        }
-    }
-    return rawReferences;
-}
-async function resolveDiscoveredFile(rawPath, workspaceRoot, invocationRoot = workspaceRoot) {
-    const absolutePath = path.isAbsolute(rawPath)
-        ? path.resolve(rawPath)
-        : path.resolve(invocationRoot, rawPath);
-    let stats;
-    try {
-        stats = await fs.stat(absolutePath);
-    }
-    catch {
-        return undefined;
-    }
-    if (!stats.isFile()) {
-        return undefined;
-    }
-    const [canonicalProjectRoot, canonicalAbsolutePath] = await Promise.all([
-        realpathForContainment(workspaceRoot),
-        realpathForContainment(absolutePath),
-    ]);
-    if (isPathWithinDirectory(canonicalProjectRoot, canonicalAbsolutePath)) {
-        const relativePath = path.relative(canonicalProjectRoot, canonicalAbsolutePath);
-        if (!relativePath ||
-            relativePath.startsWith("..") ||
-            path.isAbsolute(relativePath)) {
-            return undefined;
-        }
-        return {
-            path: normalizeCandidatePathForOutput(relativePath),
-            scope: "project",
-        };
-    }
-    return {
-        path: normalizeCandidatePathForOutput(absolutePath),
-        scope: "global",
-    };
-}
-async function discoverReferencedFiles(document, workspaceRoot, invocationRoot = workspaceRoot) {
-    const existingResolvedKeys = new Set((document.metadata.files ?? []).map((entry) => linkedFileResolvedKey(entry, workspaceRoot)));
-    const grouped = new Map();
-    const rawReferences = extractRawPathReferences(collectItemTextReferences(document));
-    const resolvedByValue = new Map();
-    await Promise.all([...new Set(rawReferences.map((reference) => reference.value))].map(async (value) => {
-        resolvedByValue.set(value, await resolveDiscoveredFile(value, workspaceRoot, invocationRoot));
-    }));
-    const resolvedReferences = rawReferences.map((reference) => ({
-        reference,
-        resolved: resolvedByValue.get(reference.value),
-    }));
-    for (const { reference, resolved } of resolvedReferences) {
-        if (!resolved) {
-            continue;
-        }
-        const key = linkedFileResolvedKey(resolved, workspaceRoot);
-        const existing = grouped.get(key) ?? {
-            path: resolved.path,
-            scope: resolved.scope,
-            sourceFields: new Set(),
-            originalPaths: new Set(),
-            sourceCount: 0,
-        };
-        existing.sourceFields.add(reference.field);
-        existing.originalPaths.add(reference.value);
-        existing.sourceCount += 1;
-        grouped.set(key, existing);
-    }
-    return [...grouped.entries()]
-        .map(([key, entry]) => ({
-        path: entry.path,
-        scope: entry.scope,
-        status: existingResolvedKeys.has(key)
-            ? "already_linked"
-            : "addable",
-        source_count: entry.sourceCount,
-        source_fields: [...entry.sourceFields].sort((left, right) => left.localeCompare(right)),
-        original_paths: [...entry.originalPaths].sort((left, right) => left.localeCompare(right)),
-    }))
-        .sort((left, right) => {
-        const byStatus = left.status.localeCompare(right.status);
-        if (byStatus !== 0)
-            return byStatus;
-        const byPath = left.path.localeCompare(right.path);
-        if (byPath !== 0)
-            return byPath;
-        /* c8 ignore next -- path+status collisions are uncommon in deterministic fixtures. */
-        return left.scope.localeCompare(right.scope);
-    });
-}
-/** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export const _testOnly = {
-    relativeReferenceScanMaxChars: RELATIVE_REFERENCE_SCAN_MAX_CHARS,
-    normalizeCandidatePathForOutput,
-    realpathForContainment,
-    linkedFileResolvedKey,
-    collectTextReferences,
-    collectItemTextReferences,
-    cleanupPathToken,
-    extractRawPathReferences,
-    resolveDiscoveredFile,
-    discoverReferencedFiles,
-};
-/** Implements run files for the public runtime surface of this module. */
-export async function runFiles(id, options, global) {
-    const result = await runLinkedArtifacts(id, options, global, {
-        metadataKey: "files",
-        op: "files_add",
-        bareNoun: "file",
-        supportsAppendStable: true,
-    });
-    return renameArtifactsResultKey(result, "files");
-}
-async function normalizeFilesLookupPaths(values, workspaceRoot) {
-    const canonicalWorkspaceRoot = await realpathForContainment(workspaceRoot);
-    const paths = await Promise.all(values.map(async (value) => {
-        const trimmed = value.trim();
-        if (!trimmed) {
-            throw new PmCliError("Files lookup paths must not be empty.", EXIT_CODE.USAGE);
-        }
-        if (!path.isAbsolute(trimmed))
-            return normalizeLinkedPath(trimmed);
-        const canonicalAbsolutePath = await realpathForContainment(trimmed);
-        return isPathWithinDirectory(canonicalWorkspaceRoot, canonicalAbsolutePath)
-            ? normalizeLinkedPath(path.relative(canonicalWorkspaceRoot, canonicalAbsolutePath))
-            : normalizeLinkedPath(canonicalAbsolutePath);
-    }));
-    const uniquePaths = [...new Set(paths)].sort((left, right) => left.localeCompare(right));
-    if (uniquePaths.length === 0) {
-        throw new PmCliError("Files lookup requires at least one path.", EXIT_CODE.USAGE);
-    }
-    return uniquePaths;
-}
-function resolveFilesLookupWindow(options) {
-    for (const [label, value] of [
-        ["limit", options.limit],
-        ["offset", options.offset],
-    ]) {
-        if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
-            throw new PmCliError(`Files lookup ${label} must be a non-negative integer.`, EXIT_CODE.USAGE);
-        }
-    }
-    const { offset = 0, limit = 50 } = options;
-    return {
-        offset: Math.max(0, Math.floor(offset)),
-        limit: options.noTruncate ? undefined : Math.max(0, Math.floor(limit)),
-    };
-}
-function projectFilesLookupItem(item) {
-    return {
-        id: item.id,
-        title: item.title,
-        type: item.type,
-        status: item.status,
-        priority: item.priority,
-        updated_at: item.updated_at,
-    };
-}
-function compareFilesLookupCandidates(left, right) {
-    const byPriority = left.item.priority - right.item.priority;
-    if (byPriority !== 0)
-        return byPriority;
-    const byUpdated = right.item.updated_at.localeCompare(left.item.updated_at);
-    return byUpdated === 0
-        ? left.item.id.localeCompare(right.item.id)
-        : byUpdated;
-}
-function matchingFilesLookupCandidates(params) {
-    return params.metadata
-        .map((item) => ({
-        item,
-        files: (item.files ?? [])
-            .filter((file) => params.paths.includes(normalizeLinkedPath(file.path)) &&
-            (params.scope === undefined || file.scope === params.scope))
-            .sort((left, right) => {
-            const byPath = left.path.localeCompare(right.path);
-            return byPath === 0 ? left.scope.localeCompare(right.scope) : byPath;
-        }),
-    }))
-        .filter((match) => match.files.length > 0)
-        .sort(compareFilesLookupCandidates);
-}
-async function resolveFilesLookupTraceability(params) {
-    if (!params.explain)
-        return undefined;
-    return explainSourceTraceability({
-        workspaceRoot: params.workspaceRoot,
-        paths: params.paths,
-        candidates: params.matching,
-        corpus: params.metadata,
-        ...(params.lineRange ? { lineRange: params.lineRange } : {}),
-        ...(params.decisionDepth === undefined
-            ? {}
-            : { decisionDepth: params.decisionDepth }),
-    });
-}
-async function queryFilesLookupIndex(params) {
-    if ([
-        params.strictRead,
-        params.noTruncate,
-        params.explain,
-        hasActiveOnReadHooks(),
-    ].includes(true)) {
-        return null;
-    }
-    const indexState = await readItemMetadataDerivedIndexState(params.pmRoot, [
-        ...new Set(Object.values(params.typeToFolder)),
-    ]);
-    if (!indexState)
-        return null;
-    return queryLinkedFileMetadataIndex({
-        pmRoot: params.pmRoot,
-        expectedSourceCursor: indexState.source_cursor,
-        paths: params.paths,
-        scope: params.scope,
-        limit: params.limit,
-        offset: params.offset,
-    });
-}
-async function queryFilesLookupSource(params) {
-    const warnings = [];
-    const metadata = await listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeToFolder, warnings, params.settings.schema);
-    const matching = matchingFilesLookupCandidates({
-        metadata,
-        paths: params.paths,
-        scope: params.scope,
-    });
-    const readWarnings = warnings.filter((warning) => /^item_list_(?:item|directory)_read_failed:/u.test(warning));
-    if (params.strictRead && readWarnings.length > 0) {
-        throw new PmCliError(`Files lookup could not read every item: ${readWarnings.join("; ")}`, EXIT_CODE.GENERIC_FAILURE);
-    }
-    const traceability = await resolveFilesLookupTraceability({
-        explain: params.explain,
-        workspaceRoot: params.workspaceRoot,
-        paths: params.paths,
-        matching,
-        metadata,
-        lineRange: params.lineRange,
-        decisionDepth: params.decisionDepth,
-    });
-    const ranked = traceability
-        ? [...matching].sort((left, right) => {
-            const byScore = traceability.explanations.get(right.item.id).score -
-                traceability.explanations.get(left.item.id).score;
-            if (byScore !== 0)
-                return byScore;
-            return compareFilesLookupCandidates(left, right);
-        })
-        : matching;
-    const page = ranked.slice(params.offset, params.limit === undefined ? undefined : params.offset + params.limit);
-    return {
-        paths: params.paths,
-        total: matching.length,
-        count: page.length,
-        offset: params.offset,
-        limit: params.limit ?? null,
-        has_more: params.offset + page.length < matching.length,
-        truncated: params.offset + page.length < matching.length,
-        completeness: {
-            status: readWarnings.length === 0 ? "complete" : "partial",
-            source: "source_scan",
-        },
-        warnings,
-        matches: page.map((match) => ({
-            item: projectFilesLookupItem(match.item),
-            files: match.files,
-            ...(traceability
-                ? { traceability: traceability.explanations.get(match.item.id) }
-                : {}),
-        })),
-        ...(traceability ? { traceability_receipt: traceability.receipt } : {}),
-    };
-}
-/** Resolve the pm items that reference one or more source paths. */
-export async function runFilesLookup(options, global) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    const workspaceRoot = resolveWorkspaceRoot(pmRoot);
-    await assertInitializedTracker(pmRoot);
-    const paths = await normalizeFilesLookupPaths(options.paths, workspaceRoot);
-    if (options.lineRange && paths.length !== 1) {
-        throw new PmCliError("Files lookup line attribution requires exactly one source path.", EXIT_CODE.USAGE);
-    }
-    const settings = await readSettings(pmRoot);
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const { offset, limit } = resolveFilesLookupWindow(options);
-    const indexed = await queryFilesLookupIndex({
-        pmRoot,
-        typeToFolder: typeRegistry.type_to_folder,
-        paths,
-        scope: options.scope,
-        limit,
-        offset,
-        strictRead: options.strictRead === true,
-        noTruncate: options.noTruncate === true,
-        explain: options.explain === true || options.lineRange !== undefined,
-    });
-    if (indexed) {
-        return {
-            paths,
-            total: indexed.total,
-            count: indexed.matches.length,
-            offset,
-            limit: limit,
-            has_more: offset + indexed.matches.length < indexed.total,
-            truncated: offset + indexed.matches.length < indexed.total,
-            completeness: { status: "unchecked", source: "index" },
-            warnings: [],
-            matches: indexed.matches.map((match) => ({
-                item: projectFilesLookupItem(match.item),
-                files: match.files,
-            })),
-        };
-    }
-    return queryFilesLookupSource({
-        pmRoot,
-        settings,
-        typeToFolder: typeRegistry.type_to_folder,
-        paths,
-        scope: options.scope,
-        limit,
-        offset,
-        strictRead: options.strictRead === true,
-        workspaceRoot,
-        explain: options.explain === true || options.lineRange !== undefined,
-        lineRange: options.lineRange,
-        decisionDepth: options.decisionDepth,
-    });
-}
-/** Implements run files discover for the public runtime surface of this module. */
-export async function runFilesDiscover(id, options, global) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    const workspaceRoot = resolveWorkspaceRoot(pmRoot);
-    await assertInitializedTracker(pmRoot);
-    const settings = await readSettings(pmRoot);
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
-    /* c8 ignore next -- not-found behavior is validated by CLI integration coverage. */
-    if (!located) {
-        throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
-    }
-    const loaded = await readLocatedItem(located, { schema: settings.schema });
-    const candidates = await discoverReferencedFiles(loaded.document, workspaceRoot, process.cwd());
-    const addableCandidates = candidates.filter((candidate) => candidate.status === "addable");
-    const skippedExisting = candidates.filter((candidate) => candidate.status === "already_linked");
-    const requestedApply = options.apply === true;
-    const note = options.note?.trim() || "discovered from item text";
-    if (!requestedApply || addableCandidates.length === 0) {
-        const files = loaded.document.metadata.files ?? [];
-        return {
-            id: located.id,
-            files,
-            changed: false,
-            apply: requestedApply,
-            count: files.length,
-            candidate_count: candidates.length,
-            addable_count: addableCandidates.length,
-            added_count: 0,
-            skipped_existing_count: skippedExisting.length,
-            candidates,
-            added: [],
-            skipped_existing: skippedExisting,
-        };
-    }
-    const author = resolveAuthor(options.author, settings.author_default);
-    const discoveredAdds = addableCandidates.map((candidate) => ({
-        path: candidate.path,
-        scope: candidate.scope,
-        note,
-    }));
-    let appliedAdds = [];
-    const appliedCandidateIndices = new Set();
-    const result = await mutateItem({
-        pmRoot,
-        settings,
-        id,
-        op: "files_discover",
-        author,
-        message: options.message ?? "Discover referenced file links",
-        force: options.force,
-        mutate(document) {
-            const next = [...(document.metadata.files ?? [])];
-            const existingResolvedKeys = new Set(next.map((entry) => linkedFileResolvedKey(entry, workspaceRoot)));
-            appliedAdds = [];
-            appliedCandidateIndices.clear();
-            for (const [index, add] of discoveredAdds.entries()) {
-                const resolvedKey = linkedFileResolvedKey(add, workspaceRoot);
-                /* c8 ignore next -- duplicate-key race paths are exercised in broader CLI race tests. */
-                if (existingResolvedKeys.has(resolvedKey)) {
-                    continue;
-                }
-                next.push(add);
-                existingResolvedKeys.add(resolvedKey);
-                appliedAdds.push(add);
-                appliedCandidateIndices.add(index);
-            }
-            const deduped = dedupeLinkedArtifacts(next);
-            /* c8 ignore next -- appendStable branch is covered through runFiles command contract tests. */
-            const normalized = options.appendStable
-                ? deduped
-                : sortLinkedArtifacts(deduped);
-            if (normalized.length > 0) {
-                document.metadata.files = normalized;
-            }
-            else {
-                delete document.metadata.files;
-            }
-            return {
-                /* c8 ignore next -- no-op mutation responses may emit empty changedFields for skipped discover batches. */
-                changedFields: appliedAdds.length > 0 ? ["files"] : [],
-                /* c8 ignore next -- warning emission is exercised by race-aware integration tests. */
-                warnings: appliedAdds.length !== discoveredAdds.length
-                    ? [
-                        `files_discover_skipped_existing:${discoveredAdds.length - appliedAdds.length}`,
-                    ]
-                    : [],
-            };
-        },
-    });
-    const files = result.item.files ?? [];
-    const addedResolvedKeys = new Set(appliedAdds.map((entry) => linkedFileResolvedKey(entry, workspaceRoot)));
-    const added = files.filter((entry) => addedResolvedKeys.has(linkedFileResolvedKey(entry, workspaceRoot)));
-    const skippedDuringApply = addableCandidates.filter((_candidate, index) => !appliedCandidateIndices.has(index));
-    const allSkippedExisting = [...skippedExisting, ...skippedDuringApply];
-    return {
-        id: result.item.id,
-        files,
-        changed: added.length > 0,
-        apply: true,
-        count: files.length,
-        candidate_count: candidates.length,
-        addable_count: addableCandidates.length,
-        added_count: added.length,
-        skipped_existing_count: allSkippedExisting.length,
-        candidates,
-        added,
-        skipped_existing: allSkippedExisting,
-    };
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="573da024-c791-5ff2-b3ee-3529804bab43")}catch(e2){}})();import{assertInitializedTracker}from"./environment/tracker-preflight.js";import fs from"node:fs/promises";import path from"node:path";import{getActiveExtensionRegistrations,hasActiveOnReadHooks}from"../core/extensions/index.js";import{resolveItemTypeRegistry}from"../core/item/type-registry.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{locateItem,listAllItemMetadata,mutateItem,readLocatedItem}from"../core/store/item-store.js";import{readItemMetadataDerivedIndexState}from"../core/store/item-metadata-cache.js";import{queryLinkedFileMetadataIndex}from"../core/store/item-metadata-query-index.js";import{resolvePmRoot,resolveWorkspaceRoot}from"../core/store/paths.js";import{readSettings}from"../core/store/settings.js";import{resolveAuthor}from"../core/shared/author.js";import{isPathWithinDirectory}from"../core/fs/path-utils.js";import{dedupeLinkedArtifacts,normalizeLinkedPath,renameArtifactsResultKey,runLinkedArtifacts,sortLinkedArtifacts}from"./linked-artifacts.js";import{explainSourceTraceability}from"./traceability/source-traceability.js";const RELATIVE_REFERENCE_SCAN_MAX_CHARS=32768;function normalizeCandidatePathForOutput(value){return normalizeLinkedPath(path.normalize(value))}async function realpathForContainment(inputPath){try{return await fs.realpath(inputPath)}catch{return path.resolve(inputPath)}}function linkedFileResolvedKey(linkedFile,projectRoot){const resolvedPath=path.isAbsolute(linkedFile.path)?path.resolve(linkedFile.path):path.resolve(projectRoot,linkedFile.path);return`${normalizeCandidatePathForOutput(resolvedPath)}::${linkedFile.scope}`}function collectTextReferences(value,fieldPath,references){if(typeof value==="string"){const trimmed=value.trim();if(trimmed.length>0){references.push({field:fieldPath,value:trimmed})}return}if(Array.isArray(value)){value.forEach((entry,index)=>collectTextReferences(entry,`${fieldPath}[${index}]`,references));return}if(typeof value==="object"&&value!==null){for(const[key,nested]of Object.entries(value)){collectTextReferences(nested,fieldPath?`${fieldPath}.${key}`:key,references)}}}function collectItemTextReferences(document){const references=[];collectTextReferences(document.metadata,"metadata",references);collectTextReferences(document.body,"body",references);return references}function cleanupPathToken(value){let next=value.trim();next=next.replace(/^[`"'<([{]+/u,"");next=next.replace(/[`"'>)\]},;!?]+$/u,"");next=next.replace(/[.]+$/u,"");next=next.replace(/:(?:\d+)(?::\d+)?$/u,"");next=next.replace(/[.]+$/u,"");return next}function extractRawPathReferences(references){const rawReferences=[];const absolutePattern=/(?:[A-Za-z]:[\\/]|\/)[^\s"'`<>()[\]{},;]+/gu;const relativePattern=/(?:\.{1,2}[\\/])?(?:(?:[A-Za-z0-9_.@-]+[\\/])+[A-Za-z0-9_.@-]+|[A-Za-z0-9_.@-]+\.[A-Za-z0-9][A-Za-z0-9._-]*)/gu;for(const reference of references){const seenInField=new Set;const boundedRelativeValue=reference.value.slice(0,RELATIVE_REFERENCE_SCAN_MAX_CHARS);for(const[pattern,input]of[[absolutePattern,reference.value],[relativePattern,boundedRelativeValue]]){pattern.lastIndex=0;for(const match of input.matchAll(pattern)){const token=cleanupPathToken(match[0]);if(!token||seenInField.has(token)){continue}seenInField.add(token);rawReferences.push({field:reference.field,value:token})}}}return rawReferences}async function resolveDiscoveredFile(rawPath,workspaceRoot,invocationRoot=workspaceRoot){const absolutePath=path.isAbsolute(rawPath)?path.resolve(rawPath):path.resolve(invocationRoot,rawPath);let stats;try{stats=await fs.stat(absolutePath)}catch{return void 0}if(!stats.isFile()){return void 0}const[canonicalProjectRoot,canonicalAbsolutePath]=await Promise.all([realpathForContainment(workspaceRoot),realpathForContainment(absolutePath)]);if(isPathWithinDirectory(canonicalProjectRoot,canonicalAbsolutePath)){const relativePath=path.relative(canonicalProjectRoot,canonicalAbsolutePath);if(!relativePath||relativePath.startsWith("..")||path.isAbsolute(relativePath)){return void 0}return{path:normalizeCandidatePathForOutput(relativePath),scope:"project"}}return{path:normalizeCandidatePathForOutput(absolutePath),scope:"global"}}async function discoverReferencedFiles(document,workspaceRoot,invocationRoot=workspaceRoot){const existingResolvedKeys=new Set((document.metadata.files??[]).map(entry=>linkedFileResolvedKey(entry,workspaceRoot)));const grouped=new Map;const rawReferences=extractRawPathReferences(collectItemTextReferences(document));const resolvedByValue=new Map;await Promise.all([...new Set(rawReferences.map(reference=>reference.value))].map(async value=>{resolvedByValue.set(value,await resolveDiscoveredFile(value,workspaceRoot,invocationRoot))}));const resolvedReferences=rawReferences.map(reference=>({reference,resolved:resolvedByValue.get(reference.value)}));for(const{reference,resolved}of resolvedReferences){if(!resolved){continue}const key=linkedFileResolvedKey(resolved,workspaceRoot);const existing=grouped.get(key)??{path:resolved.path,scope:resolved.scope,sourceFields:new Set,originalPaths:new Set,sourceCount:0};existing.sourceFields.add(reference.field);existing.originalPaths.add(reference.value);existing.sourceCount+=1;grouped.set(key,existing)}return[...grouped.entries()].map(([key,entry])=>({path:entry.path,scope:entry.scope,status:existingResolvedKeys.has(key)?"already_linked":"addable",source_count:entry.sourceCount,source_fields:[...entry.sourceFields].sort((left,right)=>left.localeCompare(right)),original_paths:[...entry.originalPaths].sort((left,right)=>left.localeCompare(right))})).sort((left,right)=>{const byStatus=left.status.localeCompare(right.status);if(byStatus!==0)return byStatus;const byPath=left.path.localeCompare(right.path);if(byPath!==0)return byPath;return left.scope.localeCompare(right.scope)})}const _testOnly={relativeReferenceScanMaxChars:RELATIVE_REFERENCE_SCAN_MAX_CHARS,normalizeCandidatePathForOutput,realpathForContainment,linkedFileResolvedKey,collectTextReferences,collectItemTextReferences,cleanupPathToken,extractRawPathReferences,resolveDiscoveredFile,discoverReferencedFiles};async function runFiles(id,options,global2){const result=await runLinkedArtifacts(id,options,global2,{metadataKey:"files",op:"files_add",bareNoun:"file",supportsAppendStable:true});return renameArtifactsResultKey(result,"files")}async function normalizeFilesLookupPaths(values,workspaceRoot){const canonicalWorkspaceRoot=await realpathForContainment(workspaceRoot);const paths=await Promise.all(values.map(async value=>{const trimmed=value.trim();if(!trimmed){throw new PmCliError("Files lookup paths must not be empty.",EXIT_CODE.USAGE)}if(!path.isAbsolute(trimmed))return normalizeLinkedPath(trimmed);const canonicalAbsolutePath=await realpathForContainment(trimmed);return isPathWithinDirectory(canonicalWorkspaceRoot,canonicalAbsolutePath)?normalizeLinkedPath(path.relative(canonicalWorkspaceRoot,canonicalAbsolutePath)):normalizeLinkedPath(canonicalAbsolutePath)}));const uniquePaths=[...new Set(paths)].sort((left,right)=>left.localeCompare(right));if(uniquePaths.length===0){throw new PmCliError("Files lookup requires at least one path.",EXIT_CODE.USAGE)}return uniquePaths}function resolveFilesLookupWindow(options){for(const[label,value]of[["limit",options.limit],["offset",options.offset]]){if(value!==void 0&&(!Number.isInteger(value)||value<0)){throw new PmCliError(`Files lookup ${label} must be a non-negative integer.`,EXIT_CODE.USAGE)}}const{offset=0,limit=50}=options;return{offset:Math.max(0,Math.floor(offset)),limit:options.noTruncate?void 0:Math.max(0,Math.floor(limit))}}function projectFilesLookupItem(item){return{id:item.id,title:item.title,type:item.type,status:item.status,priority:item.priority,updated_at:item.updated_at}}function compareFilesLookupCandidates(left,right){const byPriority=left.item.priority-right.item.priority;if(byPriority!==0)return byPriority;const byUpdated=right.item.updated_at.localeCompare(left.item.updated_at);return byUpdated===0?left.item.id.localeCompare(right.item.id):byUpdated}function matchingFilesLookupCandidates(params){return params.metadata.map(item=>({item,files:(item.files??[]).filter(file=>params.paths.includes(normalizeLinkedPath(file.path))&&(params.scope===void 0||file.scope===params.scope)).sort((left,right)=>{const byPath=left.path.localeCompare(right.path);return byPath===0?left.scope.localeCompare(right.scope):byPath})})).filter(match=>match.files.length>0).sort(compareFilesLookupCandidates)}async function resolveFilesLookupTraceability(params){if(!params.explain)return void 0;return explainSourceTraceability({workspaceRoot:params.workspaceRoot,paths:params.paths,candidates:params.matching,corpus:params.metadata,...params.lineRange?{lineRange:params.lineRange}:{},...params.decisionDepth===void 0?{}:{decisionDepth:params.decisionDepth}})}async function queryFilesLookupIndex(params){if([params.strictRead,params.noTruncate,params.explain,hasActiveOnReadHooks()].includes(true)){return null}const indexState=await readItemMetadataDerivedIndexState(params.pmRoot,[...new Set(Object.values(params.typeToFolder))]);if(!indexState)return null;return queryLinkedFileMetadataIndex({pmRoot:params.pmRoot,expectedSourceCursor:indexState.source_cursor,paths:params.paths,scope:params.scope,limit:params.limit,offset:params.offset})}async function queryFilesLookupSource(params){const warnings=[];const metadata=await listAllItemMetadata(params.pmRoot,params.settings.item_format,params.typeToFolder,warnings,params.settings.schema);const matching=matchingFilesLookupCandidates({metadata,paths:params.paths,scope:params.scope});const readWarnings=warnings.filter(warning=>/^item_list_(?:item|directory)_read_failed:/u.test(warning));if(params.strictRead&&readWarnings.length>0){throw new PmCliError(`Files lookup could not read every item: ${readWarnings.join("; ")}`,EXIT_CODE.GENERIC_FAILURE)}const traceability=await resolveFilesLookupTraceability({explain:params.explain,workspaceRoot:params.workspaceRoot,paths:params.paths,matching,metadata,lineRange:params.lineRange,decisionDepth:params.decisionDepth});const ranked=traceability?[...matching].sort((left,right)=>{const byScore=traceability.explanations.get(right.item.id).score-traceability.explanations.get(left.item.id).score;if(byScore!==0)return byScore;return compareFilesLookupCandidates(left,right)}):matching;const page=ranked.slice(params.offset,params.limit===void 0?void 0:params.offset+params.limit);return{paths:params.paths,total:matching.length,count:page.length,offset:params.offset,limit:params.limit??null,has_more:params.offset+page.length<matching.length,truncated:params.offset+page.length<matching.length,completeness:{status:readWarnings.length===0?"complete":"partial",source:"source_scan"},warnings,matches:page.map(match=>({item:projectFilesLookupItem(match.item),files:match.files,...traceability?{traceability:traceability.explanations.get(match.item.id)}:{}})),...traceability?{traceability_receipt:traceability.receipt}:{}}}async function runFilesLookup(options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);const workspaceRoot=resolveWorkspaceRoot(pmRoot);await assertInitializedTracker(pmRoot);const paths=await normalizeFilesLookupPaths(options.paths,workspaceRoot);if(options.lineRange&&paths.length!==1){throw new PmCliError("Files lookup line attribution requires exactly one source path.",EXIT_CODE.USAGE)}const settings=await readSettings(pmRoot);const typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations());const{offset,limit}=resolveFilesLookupWindow(options);const indexed=await queryFilesLookupIndex({pmRoot,typeToFolder:typeRegistry.type_to_folder,paths,scope:options.scope,limit,offset,strictRead:options.strictRead===true,noTruncate:options.noTruncate===true,explain:options.explain===true||options.lineRange!==void 0});if(indexed){return{paths,total:indexed.total,count:indexed.matches.length,offset,limit,has_more:offset+indexed.matches.length<indexed.total,truncated:offset+indexed.matches.length<indexed.total,completeness:{status:"unchecked",source:"index"},warnings:[],matches:indexed.matches.map(match=>({item:projectFilesLookupItem(match.item),files:match.files}))}}return queryFilesLookupSource({pmRoot,settings,typeToFolder:typeRegistry.type_to_folder,paths,scope:options.scope,limit,offset,strictRead:options.strictRead===true,workspaceRoot,explain:options.explain===true||options.lineRange!==void 0,lineRange:options.lineRange,decisionDepth:options.decisionDepth})}async function runFilesDiscover(id,options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);const workspaceRoot=resolveWorkspaceRoot(pmRoot);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot);const typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations());const located=await locateItem(pmRoot,id,settings.id_prefix,settings.item_format,typeRegistry.type_to_folder);if(!located){throw new PmCliError(`Item ${id} not found`,EXIT_CODE.NOT_FOUND)}const loaded=await readLocatedItem(located,{schema:settings.schema});const candidates=await discoverReferencedFiles(loaded.document,workspaceRoot,process.cwd());const addableCandidates=candidates.filter(candidate=>candidate.status==="addable");const skippedExisting=candidates.filter(candidate=>candidate.status==="already_linked");const requestedApply=options.apply===true;const note=options.note?.trim()||"discovered from item text";if(!requestedApply||addableCandidates.length===0){const files2=loaded.document.metadata.files??[];return{id:located.id,files:files2,changed:false,apply:requestedApply,count:files2.length,candidate_count:candidates.length,addable_count:addableCandidates.length,added_count:0,skipped_existing_count:skippedExisting.length,candidates,added:[],skipped_existing:skippedExisting}}const author=resolveAuthor(options.author,settings.author_default);const discoveredAdds=addableCandidates.map(candidate=>({path:candidate.path,scope:candidate.scope,note}));let appliedAdds=[];const appliedCandidateIndices=new Set;const result=await mutateItem({pmRoot,settings,id,op:"files_discover",author,message:options.message??"Discover referenced file links",force:options.force,mutate(document){const next=[...document.metadata.files??[]];const existingResolvedKeys=new Set(next.map(entry=>linkedFileResolvedKey(entry,workspaceRoot)));appliedAdds=[];appliedCandidateIndices.clear();for(const[index,add]of discoveredAdds.entries()){const resolvedKey=linkedFileResolvedKey(add,workspaceRoot);if(existingResolvedKeys.has(resolvedKey)){continue}next.push(add);existingResolvedKeys.add(resolvedKey);appliedAdds.push(add);appliedCandidateIndices.add(index)}const deduped=dedupeLinkedArtifacts(next);const normalized=options.appendStable?deduped:sortLinkedArtifacts(deduped);if(normalized.length>0){document.metadata.files=normalized}else{delete document.metadata.files}return{changedFields:appliedAdds.length>0?["files"]:[],warnings:appliedAdds.length!==discoveredAdds.length?[`files_discover_skipped_existing:${discoveredAdds.length-appliedAdds.length}`]:[]}}});const files=result.item.files??[];const addedResolvedKeys=new Set(appliedAdds.map(entry=>linkedFileResolvedKey(entry,workspaceRoot)));const added=files.filter(entry=>addedResolvedKeys.has(linkedFileResolvedKey(entry,workspaceRoot)));const skippedDuringApply=addableCandidates.filter((_candidate,index)=>!appliedCandidateIndices.has(index));const allSkippedExisting=[...skippedExisting,...skippedDuringApply];return{id:result.item.id,files,changed:added.length>0,apply:true,count:files.length,candidate_count:candidates.length,addable_count:addableCandidates.length,added_count:added.length,skipped_existing_count:allSkippedExisting.length,candidates,added,skipped_existing:allSkippedExisting}}export{_testOnly,runFiles,runFilesDiscover,runFilesLookup};
 //# sourceMappingURL=files.js.map
-//# debugId=ed504f2b-8b78-5fca-a4a7-7b0709a65533

package/dist/sdk/flag-invocation-contracts.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module sdk/flag-invocation-contracts
- *
- * Compiles flag vocabulary into a complete machine-readable invocation model.
- */
 import type { CliFlagContract } from "./cli-contracts.js";
 /** Supported channels through which a flag obtains its value. */
 export type CliFlagInputSource = "argv" | "file" | "stdin";