@unbrained/pm-cli 2026.9.6 → 2026.9.8

package/dist/sdk/linked-artifacts.js

@@ -1,531 +1,2 @@
-/**
- * @module sdk/linked-artifacts
- *
- * Implements the pm linked artifacts 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]="accd0229-6974-5950-8cea-74f517706878")}catch(e){}}();
-import { assertInitializedTracker } from "./environment/tracker-preflight.js";
-import fs from "node:fs/promises";
-import path from "node:path";
-import fg from "fast-glob";
-import { isFileAbsentError } from "../core/fs/fs-utils.js";
-import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
-import { assertNoAmbiguousBareCommaEntry, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, parseCsvKv, } from "../core/item/parse.js";
-import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
-import { isRemoteLinkedArtifactReference } from "../core/validate/linked-artifact-reference.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { stableValueEquals } from "../core/shared/serialization.js";
-import { locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
-import { resolvePmRoot, resolveWorkspaceRoot } from "../core/store/paths.js";
-import { readSettings } from "../core/store/settings.js";
-import { SCOPE_VALUES } from "../types/index.js";
-import { resolveAuthor } from "../core/shared/author.js";
-/** Allowed CSV/markdown keys for each structured linked-artifact option (GH-258). */
-export const LINKED_ARTIFACT_ADD_KEYS = ["path", "scope", "note"];
-/** Public contract for linked artifact add glob keys, shared by SDK and presentation-layer consumers. */
-export const LINKED_ARTIFACT_ADD_GLOB_KEYS = [
-    "pattern",
-    "glob",
-    "path",
-    "scope",
-    "note",
-];
-/** Public contract for linked artifact remove keys, shared by SDK and presentation-layer consumers. */
-export const LINKED_ARTIFACT_REMOVE_KEYS = ["path"];
-/** Public contract for linked artifact migrate keys, shared by SDK and presentation-layer consumers. */
-export const LINKED_ARTIFACT_MIGRATE_KEYS = ["from", "to"];
-/** Keys that are valid on --add but meaningless on --remove (GH-277). Rejected with audit-trail guidance (--message) rather than the generic unknown-key error so agents are not left believing a removal note was recorded. */
-const LINKED_ARTIFACT_REMOVE_UNSUPPORTED_KEYS = new Set([
-    "note",
-    "scope",
-]);
-/** Implements ensure scope for the public runtime surface of this module. */
-export function ensureScope(raw) {
-    const value = (raw ?? "project");
-    if (!SCOPE_VALUES.includes(value)) {
-        throw new PmCliError(`Invalid scope "${raw}". Valid scopes: ${SCOPE_VALUES.join(", ")} (default: project).`, EXIT_CODE.USAGE);
-    }
-    return value;
-}
-/** Implements looks like structured path entry for the public runtime surface of this module. */
-export function looksLikeStructuredPathEntry(raw) {
-    if (raw.startsWith("```") || raw.includes("\n")) {
-        return true;
-    }
-    if (/^(?:[-*+]\s+)?(?:path|scope|note)\s*[:=]/i.test(raw)) {
-        return true;
-    }
-    // An equals sign is valid inside filesystem paths and URL query strings.
-    // Preserve unmistakable whitespace-free path/URL shapes while routing
-    // leading assignment syntax through the structured-key allowlist so typos
-    // and malformed URL-plus-note input remain atomic failures (GH-258,
-    // GH-1000).
-    const firstCommaIndex = raw.indexOf(",");
-    const leadingSegment = raw.slice(0, firstCommaIndex >= 0 ? firstCommaIndex : raw.length);
-    const equalsIndex = leadingSegment.indexOf("=");
-    if (equalsIndex >= 0 &&
-        !/\s/u.test(raw) &&
-        (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(raw) ||
-            /^(?:[A-Za-z]:[\\/]|[\\/]{1,2}|\.\.?(?:[\\/]))/u.test(raw) ||
-            [raw.indexOf("/"), raw.indexOf("\\")].some((separatorIndex) => separatorIndex >= 0 && separatorIndex < equalsIndex))) {
-        return false;
-    }
-    return leadingSegment.includes("=") || looksLikeGenericKeyValueEntry(raw);
-}
-/** Whether a Markdown destination contains only balanced parentheses. */
-function hasBalancedParentheses(value) {
-    let depth = 0;
-    for (const character of value) {
-        if (character === "(")
-            depth += 1;
-        if (character === ")")
-            depth -= 1;
-        if (depth < 0)
-            return false;
-    }
-    return depth === 0;
-}
-/** Parse one lossless bare, Markdown, or CSV-label remote documentation reference. */
-function parseDocumentationReference(trimmed) {
-    if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(trimmed) &&
-        !looksLikeStructuredPathEntry(trimmed)) {
-        return { path: trimmed, scope: "project", note: undefined };
-    }
-    const labelEnd = trimmed.indexOf("](");
-    if (trimmed.startsWith("[") && labelEnd > 0 && trimmed.endsWith(")")) {
-        const destination = trimmed.slice(labelEnd + 2, -1).trim();
-        if (destination.length > 0 && hasBalancedParentheses(destination)) {
-            return {
-                path: destination,
-                scope: "project",
-                note: trimmed.slice(1, labelEnd).trim() || undefined,
-            };
-        }
-    }
-    const delimiterIndex = trimmed.indexOf(",");
-    if (delimiterIndex < 0)
-        return undefined;
-    const label = trimmed.slice(0, delimiterIndex).trim();
-    const destination = trimmed.slice(delimiterIndex + 1).trim();
-    if (label.length === 0 ||
-        !/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(destination)) {
-        return undefined;
-    }
-    return { path: destination, scope: "project", note: label };
-}
-/** Implements parse add entries for the public runtime surface of this module. */
-export function parseAddEntries(raw, bareNoun) {
-    if (!raw)
-        return [];
-    return raw.flatMap((entry) => {
-        const trimmed = entry.trim();
-        if (bareNoun === "doc") {
-            const reference = parseDocumentationReference(trimmed);
-            if (reference !== undefined)
-                return [reference];
-        }
-        assertNoAmbiguousBareCommaEntry(trimmed, "--add", `${bareNoun} path`, looksLikeStructuredPathEntry(trimmed));
-        const kv = looksLikeStructuredPathEntry(trimmed)
-            ? parseCsvKv(entry, "--add")
-            : { path: trimmed };
-        assertNoUnknownCsvKeys(kv, "--add", LINKED_ARTIFACT_ADD_KEYS);
-        if (!kv.path) {
-            throw new PmCliError(`--add requires path=<value> or a bare ${bareNoun} path`, EXIT_CODE.USAGE);
-        }
-        return [
-            {
-                path: kv.path,
-                scope: ensureScope(kv.scope),
-                note: kv.note?.trim() || undefined,
-            },
-        ];
-    });
-}
-/** Implements parse add glob entries for the public runtime surface of this module. */
-export function parseAddGlobEntries(raw) {
-    if (!raw)
-        return [];
-    return raw.map((entry) => {
-        const trimmed = entry.trim();
-        if (!trimmed) {
-            throw new PmCliError("--add-glob requires a glob pattern value", EXIT_CODE.USAGE);
-        }
-        if (trimmed.includes("=") ||
-            /^(?:[-*+]\s+)?(?:pattern|glob|path)\s*[:=]/i.test(trimmed) ||
-            trimmed.startsWith("```")) {
-            const kv = parseCsvKv(trimmed, "--add-glob");
-            assertNoUnknownCsvKeys(kv, "--add-glob", LINKED_ARTIFACT_ADD_GLOB_KEYS);
-            const pattern = kv.pattern?.trim() || kv.glob?.trim() || kv.path?.trim();
-            if (!pattern) {
-                throw new PmCliError("--add-glob key/value form requires pattern=<glob>", EXIT_CODE.USAGE);
-            }
-            return {
-                pattern,
-                scope: ensureScope(kv.scope),
-                note: kv.note?.trim() || undefined,
-            };
-        }
-        return {
-            pattern: trimmed,
-            scope: "project",
-        };
-    });
-}
-/** Implements parse remove entries for the public runtime surface of this module. */
-export function parseRemoveEntries(raw) {
-    if (!raw)
-        return [];
-    return raw.map((entry) => {
-        const trimmed = entry.trim();
-        if (!trimmed) {
-            throw new PmCliError("--remove requires a path value", EXIT_CODE.USAGE);
-        }
-        if (trimmed.includes("=") ||
-            /^(?:[-*+]\s+)?path\s*[:=]/i.test(trimmed) ||
-            trimmed.startsWith("```")) {
-            const kv = parseCsvKv(trimmed, "--remove");
-            // GH-277: --remove identifies an existing link by path only; it does not
-            // attach per-link metadata. Reject the --add-only keys with guidance toward
-            // the audit-trail path (--message) rather than the generic "unrecognized
-            // key" error, which left agents believing they had recorded a removal note.
-            const unsupportedRemoveKeys = Object.keys(kv).filter((key) => LINKED_ARTIFACT_REMOVE_UNSUPPORTED_KEYS.has(key.toLowerCase()));
-            if (unsupportedRemoveKeys.length > 0) {
-                throw new PmCliError(`--remove identifies a linked artifact by path only and does not accept ${unsupportedRemoveKeys
-                    .map((key) => `"${key}"`)
-                    .join(", ")}. Pass just the path (path=<value>, path:<value>, or a bare path); record removal context with --message "<why removed>".`, EXIT_CODE.USAGE);
-            }
-            assertNoUnknownCsvKeys(kv, "--remove", LINKED_ARTIFACT_REMOVE_KEYS);
-            if (!kv.path) {
-                throw new PmCliError("--remove key/value form requires path=<value>", EXIT_CODE.USAGE);
-            }
-            return kv.path;
-        }
-        return trimmed;
-    });
-}
-/** Implements parse migrate entries for the public runtime surface of this module. */
-export function parseMigrateEntries(raw) {
-    if (!raw)
-        return [];
-    return raw.map((entry) => {
-        const kv = parseCsvKv(entry, "--migrate");
-        assertNoUnknownCsvKeys(kv, "--migrate", LINKED_ARTIFACT_MIGRATE_KEYS);
-        const from = kv.from?.trim();
-        const to = kv.to?.trim();
-        if (!from || !to) {
-            throw new PmCliError("--migrate requires from=<value> and to=<value>", EXIT_CODE.USAGE);
-        }
-        return { from, to };
-    });
-}
-/** Implements apply path migrations for the public runtime surface of this module. */
-export function applyPathMigrations(artifactPath, migrations) {
-    let next = artifactPath;
-    for (const migration of migrations) {
-        if (next.startsWith(migration.from)) {
-            next = `${migration.to}${next.slice(migration.from.length)}`;
-        }
-    }
-    return next;
-}
-/** Reject a transaction that resolves the same linked path into both add and remove sets. */
-export function assertLinkedArtifactMutationIsUnambiguous(adds, removes, migrations = []) {
-    if (adds.length === 0 || removes.length === 0) {
-        return;
-    }
-    const addedPaths = new Set(adds.map((entry) => applyPathMigrations(entry.path, migrations)));
-    const conflicts = [
-        ...new Set(removes
-            .map((entry) => applyPathMigrations(entry, migrations))
-            .filter((entry) => addedPaths.has(entry))),
-    ].sort((left, right) => left.localeCompare(right));
-    if (conflicts.length === 0) {
-        return;
-    }
-    throw new PmCliError(`Linked artifact mutation cannot add and remove the same normalized path in one transaction: ${conflicts.join(", ")}. Split the replacement into separate commands so each history event has one unambiguous intent.`, EXIT_CODE.USAGE, {
-        code: "linked_artifact_mutation_conflict",
-        reason: "same_path_added_and_removed",
-        required: "Use distinct normalized paths for --add and --remove in one invocation.",
-        why: "Conflicting batch intent cannot be applied deterministically without silently discarding metadata or a removal.",
-        nextSteps: [
-            "Run the removal and addition as separate commands with a --message describing each intent.",
-        ],
-    });
-}
-/** Implements normalize linked path for the public runtime surface of this module. */
-export function normalizeLinkedPath(value) {
-    return value.split(path.sep).join("/");
-}
-/** Anchor a local linked path to the project workspace while preserving remote references and absolute paths. */
-export function anchorLinkedPath(value, workspaceRoot, invocationRoot = process.cwd()) {
-    const trimmed = value.trim();
-    if (isRemoteLinkedArtifactReference(trimmed)) {
-        return trimmed;
-    }
-    if (path.isAbsolute(trimmed) || /^[A-Za-z]:[\\/]/.test(trimmed)) {
-        return normalizeLinkedPath(trimmed.replaceAll("\\", path.sep));
-    }
-    const invocationRelativeToWorkspace = path.relative(workspaceRoot, invocationRoot);
-    if (invocationRelativeToWorkspace.startsWith(`..${path.sep}`) ||
-        invocationRelativeToWorkspace === ".." ||
-        path.isAbsolute(invocationRelativeToWorkspace)) {
-        return normalizeLinkedPath(path.normalize(trimmed));
-    }
-    return normalizeLinkedPath(path.relative(workspaceRoot, path.resolve(invocationRoot, trimmed)));
-}
-/** Implements expand add glob entries for the public runtime surface of this module. */
-export async function expandAddGlobEntries(entries, workspaceRoot = process.cwd(), invocationRoot = process.cwd()) {
-    const expanded = [];
-    for (const entry of entries) {
-        const absolutePattern = path.isAbsolute(entry.pattern);
-        const matches = await fg(entry.pattern, {
-            cwd: invocationRoot,
-            absolute: absolutePattern,
-            onlyFiles: true,
-            dot: true,
-            unique: true,
-            followSymbolicLinks: true,
-        });
-        const sortedMatches = [
-            ...new Set(matches.map((match) => anchorLinkedPath(match, workspaceRoot, invocationRoot))),
-        ].sort((left, right) => left.localeCompare(right));
-        for (const matchedPath of sortedMatches) {
-            expanded.push({
-                path: matchedPath,
-                scope: entry.scope,
-                note: entry.note,
-            });
-        }
-    }
-    return expanded;
-}
-/** GH-170 (pm-pfnx): apply a standalone --note to the links added in this invocation. Semantics (documented on pm-pfnx): the note is attached to EVERY entry added via --add/--add-glob so a single flag annotates the whole batch predictably; a per-entry embedded `note=` wins over the standalone flag; and --note without any --add/--add-glob flag is a usage error because there is nothing to annotate (it never retro-edits existing links). `hasAddFlags` reflects flag presence, not match count, so a glob that legitimately matches zero files is not an error. */
-export function applyStandaloneNote(adds, note, hasAddFlags) {
-    if (note === undefined) {
-        return adds;
-    }
-    if (!hasAddFlags) {
-        throw new PmCliError("--note requires --add or --add-glob in the same invocation (the note annotates the links being added)", EXIT_CODE.USAGE);
-    }
-    const trimmed = note.trim();
-    if (trimmed.length === 0) {
-        return adds;
-    }
-    return adds.map((entry) => entry.note === undefined ? { ...entry, note: trimmed } : entry);
-}
-/** Implements artifact key for the public runtime surface of this module. */
-export function artifactKey(value) {
-    return `${value.path}::${value.scope}`;
-}
-/** Implements sort linked artifacts for the public runtime surface of this module. */
-export function sortLinkedArtifacts(artifacts) {
-    return [...artifacts].sort((left, right) => {
-        const byPath = left.path.localeCompare(right.path);
-        if (byPath !== 0)
-            return byPath;
-        return left.scope.localeCompare(right.scope);
-    });
-}
-/** Implements dedupe linked artifacts for the public runtime surface of this module. */
-export function dedupeLinkedArtifacts(artifacts) {
-    return [
-        ...new Map(artifacts.map((entry) => [artifactKey(entry), entry])).values(),
-    ].map((entry) => ({
-        ...entry,
-        note: entry.note?.trim() || undefined,
-    }));
-}
-/** Implements validate linked paths for the public runtime surface of this module. */
-export async function validateLinkedPaths(paths, workspaceRoot = process.cwd()) {
-    const uniquePaths = [...new Set(paths)].sort((left, right) => left.localeCompare(right));
-    const existingFiles = [];
-    const missingPaths = [];
-    const nonFilePaths = [];
-    const remoteReferences = [];
-    for (const relativePath of uniquePaths) {
-        // Remote references (https:// PR/issue/design-doc URLs) are not local
-        // files; report them separately (trimmed, to match buildFilesCheck's
-        // output shape) instead of probing a meaningless path.
-        if (isRemoteLinkedArtifactReference(relativePath)) {
-            remoteReferences.push(relativePath.trim());
-            continue;
-        }
-        const resolvedPath = path.isAbsolute(relativePath)
-            ? relativePath
-            : path.resolve(workspaceRoot, relativePath);
-        try {
-            const stats = await fs.stat(resolvedPath);
-            if (stats.isFile()) {
-                existingFiles.push(relativePath);
-            }
-            else {
-                nonFilePaths.push(relativePath);
-            }
-        }
-        catch (error) {
-            if (typeof error === "object" &&
-                error !== null &&
-                "code" in error &&
-                isFileAbsentError(error)) {
-                missingPaths.push(relativePath);
-                continue;
-            }
-            nonFilePaths.push(relativePath);
-        }
-    }
-    return {
-        checked: uniquePaths.length,
-        existing_files: existingFiles,
-        missing_paths: missingPaths,
-        non_file_paths: nonFilePaths,
-        remote_references: remoteReferences,
-    };
-}
-function applyLinkedArtifactMigrations(current, adds, removes, migrations) {
-    let count = 0;
-    for (let index = 0; index < current.length; index += 1) {
-        const migratedPath = applyPathMigrations(current[index].path, migrations);
-        if (migratedPath !== current[index].path) {
-            current[index] = { ...current[index], path: migratedPath };
-            count += 1;
-        }
-    }
-    const migratedAdds = adds.map((entry) => {
-        const migratedPath = applyPathMigrations(entry.path, migrations);
-        if (migratedPath !== entry.path)
-            count += 1;
-        return { ...entry, path: migratedPath };
-    });
-    return {
-        adds: migratedAdds,
-        removes: removes.map((entry) => applyPathMigrations(entry, migrations)),
-        count,
-    };
-}
-function mergeLinkedArtifactChanges(current, adds, removes, appendStable) {
-    for (const add of adds) {
-        if (!current.some((entry) => entry.path === add.path && entry.scope === add.scope)) {
-            current.push(add);
-        }
-    }
-    if (removes.length > 0) {
-        for (let index = current.length - 1; index >= 0; index -= 1) {
-            if (removes.includes(current[index].path))
-                current.splice(index, 1);
-        }
-    }
-    const deduped = dedupeLinkedArtifacts(current);
-    return appendStable ? deduped : sortLinkedArtifacts(deduped);
-}
-async function buildLinkedArtifactResult(params) {
-    const paths = params.artifacts.map((entry) => entry.path);
-    return {
-        id: params.id,
-        artifacts: params.artifacts,
-        changed: params.changed,
-        count: params.artifacts.length,
-        migrations_applied: params.migrationsApplied && params.migrationsApplied > 0
-            ? params.migrationsApplied
-            : undefined,
-        validation: params.options.validatePaths || params.changed
-            ? await validateLinkedPaths(paths, params.workspaceRoot)
-            : undefined,
-    };
-}
-/** Shared linked-artifact list/mutate command core used by runFiles and runDocs. The kind config selects metadata key, op, bare-path noun, and whether append-stable ordering is honored, preserving each twin's exact semantics. */
-export async function runLinkedArtifacts(id, options, global, config) {
-    const { metadataKey } = config;
-    const stdinResolver = createStdinTokenResolver();
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    const workspaceRoot = resolveWorkspaceRoot(pmRoot);
-    const invocationRoot = process.cwd();
-    await assertInitializedTracker(pmRoot);
-    const settings = await readSettings(pmRoot);
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const resolvedAdds = await stdinResolver.resolveList(options.add, "--add");
-    const resolvedAddGlobs = await stdinResolver.resolveList(options.addGlob, "--add-glob");
-    const resolvedRemoves = await stdinResolver.resolveList(options.remove, "--remove");
-    const resolvedMigrations = await stdinResolver.resolveList(options.migrate, "--migrate");
-    const parsedAdds = parseAddEntries(resolvedAdds, config.bareNoun).map((entry) => ({
-        ...entry,
-        path: anchorLinkedPath(entry.path, workspaceRoot, invocationRoot),
-    }));
-    const addGlobs = parseAddGlobEntries(resolvedAddGlobs);
-    const expandedGlobAdds = await expandAddGlobEntries(addGlobs, workspaceRoot, invocationRoot);
-    const adds = applyStandaloneNote([...parsedAdds, ...expandedGlobAdds], options.note, parsedAdds.length > 0 || addGlobs.length > 0);
-    const removes = parseRemoveEntries(resolvedRemoves).map((entry) => anchorLinkedPath(entry, workspaceRoot, invocationRoot));
-    const migrations = parseMigrateEntries(resolvedMigrations);
-    assertLinkedArtifactMutationIsUnambiguous(adds, removes, migrations);
-    const shouldMutate = adds.length > 0 || removes.length > 0 || migrations.length > 0;
-    if (!shouldMutate) {
-        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 artifacts = loaded.document.metadata[metadataKey] ?? [];
-        return buildLinkedArtifactResult({
-            id: located.id,
-            artifacts,
-            changed: false,
-            options,
-            workspaceRoot,
-        });
-    }
-    const author = resolveAuthor(options.author, settings.author_default);
-    const result = await mutateItem({
-        pmRoot,
-        settings,
-        id,
-        op: config.op,
-        author,
-        message: options.message,
-        force: options.force,
-        skipNoop: true,
-        mutate(document) {
-            const metadata = document.metadata;
-            const current = metadata[metadataKey] ?? [];
-            const next = [...current];
-            const migrated = applyLinkedArtifactMigrations(next, adds, removes, migrations);
-            const normalized = mergeLinkedArtifactChanges(next, migrated.adds, migrated.removes, config.supportsAppendStable && options.appendStable === true);
-            if (normalized.length > 0) {
-                metadata[metadataKey] = normalized;
-            }
-            else {
-                delete metadata[metadataKey];
-            }
-            const changed = !stableValueEquals(current, normalized);
-            return {
-                changedFields: changed ? [metadataKey] : [],
-                warnings: changed && migrated.count > 0
-                    ? [`path_migrations_applied:${migrated.count}`]
-                    : [],
-            };
-        },
-    });
-    const artifacts = result.item[metadataKey] ?? [];
-    const migrationWarning = result.warnings.find((warning) => warning.startsWith("path_migrations_applied:"));
-    const migrationCount = migrationWarning
-        ? Number(migrationWarning.slice("path_migrations_applied:".length))
-        : 0;
-    return buildLinkedArtifactResult({
-        id: result.item.id,
-        artifacts,
-        changed: result.changedFields.includes(metadataKey),
-        migrationsApplied: migrationCount,
-        options,
-        workspaceRoot,
-    });
-}
-/** Re-key the generic `artifacts` field to the resource-specific name (files/docs) while preserving the original key order and presence so kind-specific result shapes (and their deterministic JSON key ordering) stay byte-identical. */
-export function renameArtifactsResultKey(result, key) {
-    const out = {};
-    for (const [field, value] of Object.entries(result)) {
-        out[field === "artifacts" ? key : field] = value;
-    }
-    return out;
-}
+!(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]="02743545-3a44-565d-932c-7fe736d17eb8")}catch(e2){}})();import{assertInitializedTracker}from"./environment/tracker-preflight.js";import fs from"node:fs/promises";import path from"node:path";import fg from"fast-glob";import{isFileAbsentError}from"../core/fs/fs-utils.js";import{getActiveExtensionRegistrations}from"../core/extensions/index.js";import{assertNoAmbiguousBareCommaEntry,assertNoUnknownCsvKeys,createStdinTokenResolver,looksLikeGenericKeyValueEntry,parseCsvKv}from"../core/item/parse.js";import{resolveItemTypeRegistry}from"../core/item/type-registry.js";import{isRemoteLinkedArtifactReference}from"../core/validate/linked-artifact-reference.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{stableValueEquals}from"../core/shared/serialization.js";import{locateItem,mutateItem,readLocatedItem}from"../core/store/item-store.js";import{resolvePmRoot,resolveWorkspaceRoot}from"../core/store/paths.js";import{readSettings}from"../core/store/settings.js";import{SCOPE_VALUES}from"../types/index.js";import{resolveAuthor}from"../core/shared/author.js";const LINKED_ARTIFACT_ADD_KEYS=["path","scope","note"];const LINKED_ARTIFACT_ADD_GLOB_KEYS=["pattern","glob","path","scope","note"];const LINKED_ARTIFACT_REMOVE_KEYS=["path"];const LINKED_ARTIFACT_MIGRATE_KEYS=["from","to"];const LINKED_ARTIFACT_REMOVE_UNSUPPORTED_KEYS=new Set(["note","scope"]);function ensureScope(raw){const value=raw??"project";if(!SCOPE_VALUES.includes(value)){throw new PmCliError(`Invalid scope "${raw}". Valid scopes: ${SCOPE_VALUES.join(", ")} (default: project).`,EXIT_CODE.USAGE)}return value}function looksLikeStructuredPathEntry(raw){if(raw.startsWith("```")||raw.includes("\n")){return true}if(/^(?:[-*+]\s+)?(?:path|scope|note)\s*[:=]/i.test(raw)){return true}const firstCommaIndex=raw.indexOf(",");const leadingSegment=raw.slice(0,firstCommaIndex>=0?firstCommaIndex:raw.length);const equalsIndex=leadingSegment.indexOf("=");if(equalsIndex>=0&&!/\s/u.test(raw)&&(/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(raw)||/^(?:[A-Za-z]:[\\/]|[\\/]{1,2}|\.\.?(?:[\\/]))/u.test(raw)||[raw.indexOf("/"),raw.indexOf("\\")].some(separatorIndex=>separatorIndex>=0&&separatorIndex<equalsIndex))){return false}return leadingSegment.includes("=")||looksLikeGenericKeyValueEntry(raw)}function hasBalancedParentheses(value){let depth=0;for(const character of value){if(character==="(")depth+=1;if(character===")")depth-=1;if(depth<0)return false}return depth===0}function parseDocumentationReference(trimmed){if(/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(trimmed)&&!looksLikeStructuredPathEntry(trimmed)){return{path:trimmed,scope:"project",note:void 0}}const labelEnd=trimmed.indexOf("](");if(trimmed.startsWith("[")&&labelEnd>0&&trimmed.endsWith(")")){const destination2=trimmed.slice(labelEnd+2,-1).trim();if(destination2.length>0&&hasBalancedParentheses(destination2)){return{path:destination2,scope:"project",note:trimmed.slice(1,labelEnd).trim()||void 0}}}const delimiterIndex=trimmed.indexOf(",");if(delimiterIndex<0)return void 0;const label=trimmed.slice(0,delimiterIndex).trim();const destination=trimmed.slice(delimiterIndex+1).trim();if(label.length===0||!/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(destination)){return void 0}return{path:destination,scope:"project",note:label}}function parseAddEntries(raw,bareNoun){if(!raw)return[];return raw.flatMap(entry=>{const trimmed=entry.trim();if(bareNoun==="doc"){const reference=parseDocumentationReference(trimmed);if(reference!==void 0)return[reference]}assertNoAmbiguousBareCommaEntry(trimmed,"--add",`${bareNoun} path`,looksLikeStructuredPathEntry(trimmed));const kv=looksLikeStructuredPathEntry(trimmed)?parseCsvKv(entry,"--add"):{path:trimmed};assertNoUnknownCsvKeys(kv,"--add",LINKED_ARTIFACT_ADD_KEYS);if(!kv.path){throw new PmCliError(`--add requires path=<value> or a bare ${bareNoun} path`,EXIT_CODE.USAGE)}return[{path:kv.path,scope:ensureScope(kv.scope),note:kv.note?.trim()||void 0}]})}function parseAddGlobEntries(raw){if(!raw)return[];return raw.map(entry=>{const trimmed=entry.trim();if(!trimmed){throw new PmCliError("--add-glob requires a glob pattern value",EXIT_CODE.USAGE)}if(trimmed.includes("=")||/^(?:[-*+]\s+)?(?:pattern|glob|path)\s*[:=]/i.test(trimmed)||trimmed.startsWith("```")){const kv=parseCsvKv(trimmed,"--add-glob");assertNoUnknownCsvKeys(kv,"--add-glob",LINKED_ARTIFACT_ADD_GLOB_KEYS);const pattern=kv.pattern?.trim()||kv.glob?.trim()||kv.path?.trim();if(!pattern){throw new PmCliError("--add-glob key/value form requires pattern=<glob>",EXIT_CODE.USAGE)}return{pattern,scope:ensureScope(kv.scope),note:kv.note?.trim()||void 0}}return{pattern:trimmed,scope:"project"}})}function parseRemoveEntries(raw){if(!raw)return[];return raw.map(entry=>{const trimmed=entry.trim();if(!trimmed){throw new PmCliError("--remove requires a path value",EXIT_CODE.USAGE)}if(trimmed.includes("=")||/^(?:[-*+]\s+)?path\s*[:=]/i.test(trimmed)||trimmed.startsWith("```")){const kv=parseCsvKv(trimmed,"--remove");const unsupportedRemoveKeys=Object.keys(kv).filter(key=>LINKED_ARTIFACT_REMOVE_UNSUPPORTED_KEYS.has(key.toLowerCase()));if(unsupportedRemoveKeys.length>0){throw new PmCliError(`--remove identifies a linked artifact by path only and does not accept ${unsupportedRemoveKeys.map(key=>`"${key}"`).join(", ")}. Pass just the path (path=<value>, path:<value>, or a bare path); record removal context with --message "<why removed>".`,EXIT_CODE.USAGE)}assertNoUnknownCsvKeys(kv,"--remove",LINKED_ARTIFACT_REMOVE_KEYS);if(!kv.path){throw new PmCliError("--remove key/value form requires path=<value>",EXIT_CODE.USAGE)}return kv.path}return trimmed})}function parseMigrateEntries(raw){if(!raw)return[];return raw.map(entry=>{const kv=parseCsvKv(entry,"--migrate");assertNoUnknownCsvKeys(kv,"--migrate",LINKED_ARTIFACT_MIGRATE_KEYS);const from=kv.from?.trim();const to=kv.to?.trim();if(!from||!to){throw new PmCliError("--migrate requires from=<value> and to=<value>",EXIT_CODE.USAGE)}return{from,to}})}function applyPathMigrations(artifactPath,migrations){let next=artifactPath;for(const migration of migrations){if(next.startsWith(migration.from)){next=`${migration.to}${next.slice(migration.from.length)}`}}return next}function assertLinkedArtifactMutationIsUnambiguous(adds,removes,migrations=[]){if(adds.length===0||removes.length===0){return}const addedPaths=new Set(adds.map(entry=>applyPathMigrations(entry.path,migrations)));const conflicts=[...new Set(removes.map(entry=>applyPathMigrations(entry,migrations)).filter(entry=>addedPaths.has(entry)))].sort((left,right)=>left.localeCompare(right));if(conflicts.length===0){return}throw new PmCliError(`Linked artifact mutation cannot add and remove the same normalized path in one transaction: ${conflicts.join(", ")}. Split the replacement into separate commands so each history event has one unambiguous intent.`,EXIT_CODE.USAGE,{code:"linked_artifact_mutation_conflict",reason:"same_path_added_and_removed",required:"Use distinct normalized paths for --add and --remove in one invocation.",why:"Conflicting batch intent cannot be applied deterministically without silently discarding metadata or a removal.",nextSteps:["Run the removal and addition as separate commands with a --message describing each intent."]})}function normalizeLinkedPath(value){return value.split(path.sep).join("/")}function anchorLinkedPath(value,workspaceRoot,invocationRoot=process.cwd()){const trimmed=value.trim();if(isRemoteLinkedArtifactReference(trimmed)){return trimmed}if(path.isAbsolute(trimmed)||/^[A-Za-z]:[\\/]/.test(trimmed)){return normalizeLinkedPath(trimmed.replaceAll("\\",path.sep))}const invocationRelativeToWorkspace=path.relative(workspaceRoot,invocationRoot);if(invocationRelativeToWorkspace.startsWith(`..${path.sep}`)||invocationRelativeToWorkspace===".."||path.isAbsolute(invocationRelativeToWorkspace)){return normalizeLinkedPath(path.normalize(trimmed))}return normalizeLinkedPath(path.relative(workspaceRoot,path.resolve(invocationRoot,trimmed)))}async function expandAddGlobEntries(entries,workspaceRoot=process.cwd(),invocationRoot=process.cwd()){const expanded=[];for(const entry of entries){const absolutePattern=path.isAbsolute(entry.pattern);const matches=await fg(entry.pattern,{cwd:invocationRoot,absolute:absolutePattern,onlyFiles:true,dot:true,unique:true,followSymbolicLinks:true});const sortedMatches=[...new Set(matches.map(match=>anchorLinkedPath(match,workspaceRoot,invocationRoot)))].sort((left,right)=>left.localeCompare(right));for(const matchedPath of sortedMatches){expanded.push({path:matchedPath,scope:entry.scope,note:entry.note})}}return expanded}function applyStandaloneNote(adds,note,hasAddFlags){if(note===void 0){return adds}if(!hasAddFlags){throw new PmCliError("--note requires --add or --add-glob in the same invocation (the note annotates the links being added)",EXIT_CODE.USAGE)}const trimmed=note.trim();if(trimmed.length===0){return adds}return adds.map(entry=>entry.note===void 0?{...entry,note:trimmed}:entry)}function artifactKey(value){return`${value.path}::${value.scope}`}function sortLinkedArtifacts(artifacts){return[...artifacts].sort((left,right)=>{const byPath=left.path.localeCompare(right.path);if(byPath!==0)return byPath;return left.scope.localeCompare(right.scope)})}function dedupeLinkedArtifacts(artifacts){return[...new Map(artifacts.map(entry=>[artifactKey(entry),entry])).values()].map(entry=>({...entry,note:entry.note?.trim()||void 0}))}async function validateLinkedPaths(paths,workspaceRoot=process.cwd()){const uniquePaths=[...new Set(paths)].sort((left,right)=>left.localeCompare(right));const existingFiles=[];const missingPaths=[];const nonFilePaths=[];const remoteReferences=[];for(const relativePath of uniquePaths){if(isRemoteLinkedArtifactReference(relativePath)){remoteReferences.push(relativePath.trim());continue}const resolvedPath=path.isAbsolute(relativePath)?relativePath:path.resolve(workspaceRoot,relativePath);try{const stats=await fs.stat(resolvedPath);if(stats.isFile()){existingFiles.push(relativePath)}else{nonFilePaths.push(relativePath)}}catch(error){if(typeof error==="object"&&error!==null&&"code"in error&&isFileAbsentError(error)){missingPaths.push(relativePath);continue}nonFilePaths.push(relativePath)}}return{checked:uniquePaths.length,existing_files:existingFiles,missing_paths:missingPaths,non_file_paths:nonFilePaths,remote_references:remoteReferences}}function applyLinkedArtifactMigrations(current,adds,removes,migrations){let count=0;for(let index=0;index<current.length;index+=1){const migratedPath=applyPathMigrations(current[index].path,migrations);if(migratedPath!==current[index].path){current[index]={...current[index],path:migratedPath};count+=1}}const migratedAdds=adds.map(entry=>{const migratedPath=applyPathMigrations(entry.path,migrations);if(migratedPath!==entry.path)count+=1;return{...entry,path:migratedPath}});return{adds:migratedAdds,removes:removes.map(entry=>applyPathMigrations(entry,migrations)),count}}function mergeLinkedArtifactChanges(current,adds,removes,appendStable){for(const add of adds){if(!current.some(entry=>entry.path===add.path&&entry.scope===add.scope)){current.push(add)}}if(removes.length>0){for(let index=current.length-1;index>=0;index-=1){if(removes.includes(current[index].path))current.splice(index,1)}}const deduped=dedupeLinkedArtifacts(current);return appendStable?deduped:sortLinkedArtifacts(deduped)}async function buildLinkedArtifactResult(params){const paths=params.artifacts.map(entry=>entry.path);return{id:params.id,artifacts:params.artifacts,changed:params.changed,count:params.artifacts.length,migrations_applied:params.migrationsApplied&&params.migrationsApplied>0?params.migrationsApplied:void 0,validation:params.options.validatePaths||params.changed?await validateLinkedPaths(paths,params.workspaceRoot):void 0}}async function runLinkedArtifacts(id,options,global2,config){const{metadataKey}=config;const stdinResolver=createStdinTokenResolver();const pmRoot=resolvePmRoot(process.cwd(),global2.path);const workspaceRoot=resolveWorkspaceRoot(pmRoot);const invocationRoot=process.cwd();await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot);const typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations());const resolvedAdds=await stdinResolver.resolveList(options.add,"--add");const resolvedAddGlobs=await stdinResolver.resolveList(options.addGlob,"--add-glob");const resolvedRemoves=await stdinResolver.resolveList(options.remove,"--remove");const resolvedMigrations=await stdinResolver.resolveList(options.migrate,"--migrate");const parsedAdds=parseAddEntries(resolvedAdds,config.bareNoun).map(entry=>({...entry,path:anchorLinkedPath(entry.path,workspaceRoot,invocationRoot)}));const addGlobs=parseAddGlobEntries(resolvedAddGlobs);const expandedGlobAdds=await expandAddGlobEntries(addGlobs,workspaceRoot,invocationRoot);const adds=applyStandaloneNote([...parsedAdds,...expandedGlobAdds],options.note,parsedAdds.length>0||addGlobs.length>0);const removes=parseRemoveEntries(resolvedRemoves).map(entry=>anchorLinkedPath(entry,workspaceRoot,invocationRoot));const migrations=parseMigrateEntries(resolvedMigrations);assertLinkedArtifactMutationIsUnambiguous(adds,removes,migrations);const shouldMutate=adds.length>0||removes.length>0||migrations.length>0;if(!shouldMutate){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 artifacts2=loaded.document.metadata[metadataKey]??[];return buildLinkedArtifactResult({id:located.id,artifacts:artifacts2,changed:false,options,workspaceRoot})}const author=resolveAuthor(options.author,settings.author_default);const result=await mutateItem({pmRoot,settings,id,op:config.op,author,message:options.message,force:options.force,skipNoop:true,mutate(document){const metadata=document.metadata;const current=metadata[metadataKey]??[];const next=[...current];const migrated=applyLinkedArtifactMigrations(next,adds,removes,migrations);const normalized=mergeLinkedArtifactChanges(next,migrated.adds,migrated.removes,config.supportsAppendStable&&options.appendStable===true);if(normalized.length>0){metadata[metadataKey]=normalized}else{delete metadata[metadataKey]}const changed=!stableValueEquals(current,normalized);return{changedFields:changed?[metadataKey]:[],warnings:changed&&migrated.count>0?[`path_migrations_applied:${migrated.count}`]:[]}}});const artifacts=result.item[metadataKey]??[];const migrationWarning=result.warnings.find(warning=>warning.startsWith("path_migrations_applied:"));const migrationCount=migrationWarning?Number(migrationWarning.slice("path_migrations_applied:".length)):0;return buildLinkedArtifactResult({id:result.item.id,artifacts,changed:result.changedFields.includes(metadataKey),migrationsApplied:migrationCount,options,workspaceRoot})}function renameArtifactsResultKey(result,key){const out={};for(const[field,value]of Object.entries(result)){out[field==="artifacts"?key:field]=value}return out}export{LINKED_ARTIFACT_ADD_GLOB_KEYS,LINKED_ARTIFACT_ADD_KEYS,LINKED_ARTIFACT_MIGRATE_KEYS,LINKED_ARTIFACT_REMOVE_KEYS,anchorLinkedPath,applyPathMigrations,applyStandaloneNote,artifactKey,assertLinkedArtifactMutationIsUnambiguous,dedupeLinkedArtifacts,ensureScope,expandAddGlobEntries,looksLikeStructuredPathEntry,normalizeLinkedPath,parseAddEntries,parseAddGlobEntries,parseMigrateEntries,parseRemoveEntries,renameArtifactsResultKey,runLinkedArtifacts,sortLinkedArtifacts,validateLinkedPaths};
 //# sourceMappingURL=linked-artifacts.js.map
-//# debugId=accd0229-6974-5950-8cea-74f517706878