@solaqua/skul 0.1.0

package/dist/root-instruction-render.d.ts

@@ -0,0 +1,31 @@
+import { type ToolName } from "./tool-mapping";
+/** Joins root-instruction parts into one normalized document body. */
+export declare function composeRootInstructionContent(parts: Array<string | undefined>): string;
+export interface RenderTrackedRootInstructionShadowOptions {
+    baseContent?: string;
+    overlayContent: string;
+    bundleName: string;
+    toolName: ToolName;
+    strategy: "append" | "prepend" | "replace";
+    allowReplace?: boolean;
+}
+export interface RenderTrackedRootInstructionShadowResult {
+    overlay: string;
+    rendered: string;
+    overlayFingerprint: string;
+    renderedFingerprint: string;
+}
+/**
+ * Renders a deterministic tracked root-instruction shadow plus the
+ * fingerprints later lifecycle commands use to detect stale overlays and
+ * local manual edits.
+ */
+export declare function renderTrackedRootInstructionShadow(options: RenderTrackedRootInstructionShadowOptions): RenderTrackedRootInstructionShadowResult;
+/** Wraps one bundle's root-instruction content with explicit boundary markers. */
+export declare function wrapRootInstructionBundleContent(options: {
+    bundleName: string;
+    source?: string;
+    content: string;
+}): string;
+/** Returns whether a repo-relative path is a managed root-instruction file. */
+export declare function isRootInstructionPath(repoRelativePath: string): boolean;

package/dist/root-instruction-render.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeRootInstructionContent = composeRootInstructionContent;
+exports.renderTrackedRootInstructionShadow = renderTrackedRootInstructionShadow;
+exports.wrapRootInstructionBundleContent = wrapRootInstructionBundleContent;
+exports.isRootInstructionPath = isRootInstructionPath;
+const node_crypto_1 = require("node:crypto");
+const tool_mapping_1 = require("./tool-mapping");
+const ROOT_INSTRUCTION_PATHS = new Set([
+    ...(0, tool_mapping_1.listToolDefinitions)()
+        .map((tool) => tool.targets.root_instruction?.path)
+        .filter((p) => p !== undefined),
+    ...(0, tool_mapping_1.listGlobalToolDefinitions)()
+        .map((tool) => tool.targets.root_instruction?.path)
+        .filter((p) => p !== undefined),
+]);
+/** Joins root-instruction parts into one normalized document body. */
+function composeRootInstructionContent(parts) {
+    return parts
+        .map((part) => normalizeRootInstructionPart(part))
+        .filter((part) => part.length > 0)
+        .join("\n\n");
+}
+/**
+ * Renders a deterministic tracked root-instruction shadow plus the
+ * fingerprints later lifecycle commands use to detect stale overlays and
+ * local manual edits.
+ */
+function renderTrackedRootInstructionShadow(options) {
+    if (options.strategy === "replace" && options.allowReplace !== true) {
+        throw new Error(`Tracked root-instruction replace strategy for ${options.toolName} requires explicit confirmation`);
+    }
+    const normalizedOverlayContent = normalizeRootInstructionPart(options.overlayContent);
+    const overlay = options.strategy === "replace"
+        ? normalizedOverlayContent
+        : formatTrackedRootInstructionShadowBlock({
+            bundleName: options.bundleName,
+            content: normalizedOverlayContent,
+        });
+    const rendered = renderTrackedRootInstructionDocument({
+        baseContent: options.baseContent,
+        overlay,
+        strategy: options.strategy,
+    });
+    return {
+        overlay,
+        rendered,
+        overlayFingerprint: fingerprintRootInstructionContent(overlay),
+        renderedFingerprint: fingerprintRootInstructionContent(rendered),
+    };
+}
+/** Wraps one bundle's root-instruction content with explicit boundary markers. */
+function wrapRootInstructionBundleContent(options) {
+    const normalizedContent = normalizeRootInstructionPart(options.content);
+    if (normalizedContent.length === 0) {
+        return "";
+    }
+    const label = options.source
+        ? `${options.bundleName} (${options.source})`
+        : options.bundleName;
+    return [
+        `<!-- BEGIN SKUL BUNDLE: ${label} -->`,
+        normalizedContent,
+        `<!-- END SKUL BUNDLE: ${label} -->`,
+    ].join("\n");
+}
+/** Wraps tracked shadow overlay content with deterministic marker boundaries. */
+function formatTrackedRootInstructionShadowBlock(options) {
+    const normalizedContent = normalizeRootInstructionPart(options.content);
+    if (normalizedContent.length === 0) {
+        return "";
+    }
+    return [
+        `<!-- SKUL SHADOW START bundle=${options.bundleName} -->`,
+        normalizedContent,
+        "<!-- SKUL SHADOW END -->",
+    ].join("\n");
+}
+/** Returns whether content still matches the recorded shadow render fingerprint. */
+function hasTrackedRootInstructionManualEdit(options) {
+    return (fingerprintRootInstructionContent(options.content) !==
+        options.renderedFingerprint);
+}
+/** Returns whether a repo-relative path is a managed root-instruction file. */
+function isRootInstructionPath(repoRelativePath) {
+    return ROOT_INSTRUCTION_PATHS.has(repoRelativePath);
+}
+function renderTrackedRootInstructionDocument(options) {
+    if (options.strategy === "replace") {
+        return ensureTrailingNewline(options.overlay);
+    }
+    if (options.overlay.length === 0) {
+        return options.baseContent ?? "";
+    }
+    if (!options.baseContent || options.baseContent.length === 0) {
+        return ensureTrailingNewline(options.overlay);
+    }
+    if (options.strategy === "prepend") {
+        return `${options.overlay}\n\n${options.baseContent}`;
+    }
+    return `${options.baseContent}${selectAppendSeparator(options.baseContent)}${options.overlay}\n`;
+}
+function fingerprintRootInstructionContent(content) {
+    return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
+}
+function ensureTrailingNewline(content) {
+    return content.length === 0 ? "" : `${content}\n`;
+}
+function selectAppendSeparator(baseContent) {
+    if (baseContent.endsWith("\n\n")) {
+        return "";
+    }
+    if (baseContent.endsWith("\n")) {
+        return "\n";
+    }
+    return "\n\n";
+}
+function normalizeRootInstructionPart(part) {
+    return part?.replace(/\s+$/, "") ?? "";
+}
+//# sourceMappingURL=root-instruction-render.js.map

package/dist/root-instruction-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-instruction-render.js","sourceRoot":"","sources":["../src/root-instruction-render.ts"],"names":[],"mappings":"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"}

package/dist/root-instruction-state.d.ts

@@ -0,0 +1,41 @@
+import type { CachedBundle } from "./bundle-discovery";
+import type { DesiredBundleEntry, MaterializedState } from "./registry";
+/** Captures pre-existing root-instruction file contents before Skul starts managing them. */
+export declare function captureRootInstructionBaseContents(options: {
+    repoRoot: string;
+    targetPaths: Set<string>;
+    existingBaseContents?: Record<string, string>;
+    managedTargetPaths?: Set<string>;
+}): Record<string, string> | undefined;
+/** Rebuilds shared root-instruction files from desired bundle state and returns the rewritten paths. */
+export declare function syncManagedRootInstructionFiles(options: {
+    repoRoot: string;
+    desiredState: DesiredBundleEntry[];
+    materializedBundles: MaterializedState["bundles"];
+    rootInstructionBaseContents?: Record<string, string>;
+    targetPaths?: Set<string>;
+    resolveCachedBundle: (entry: DesiredBundleEntry) => CachedBundle;
+    repoRelPathRemapper?: (toolName: string, relPath: string) => string;
+}): Set<string>;
+/** Restores preserved base content for root-instruction files that Skul no longer manages. */
+export declare function restoreRootInstructionBaseContents(options: {
+    repoRoot: string;
+    baseContents?: Record<string, string>;
+    targetPaths: Set<string>;
+}): Set<string>;
+/** Refreshes fingerprints for a subset of managed files after they are rewritten in place. */
+export declare function refreshManagedFileFingerprintsForPaths(repoRoot: string, bundles: MaterializedState["bundles"], filePaths: Set<string>): MaterializedState["bundles"];
+/** Returns every root-instruction path currently owned by managed bundles. */
+export declare function collectManagedRootInstructionTargets(bundles: MaterializedState["bundles"]): Set<string>;
+/** Verifies that every bundle needed for shared root-instruction recomposition is cached. */
+export declare function assertManagedRootInstructionSyncSourcesCached(options: {
+    desiredState: DesiredBundleEntry[];
+    materializedBundles: MaterializedState["bundles"];
+    targetPaths: Set<string>;
+    resolveCachedBundle: (entry: DesiredBundleEntry) => CachedBundle;
+}): void;
+/** Collects other bundles that already own root-instruction paths targeted by an upcoming write. */
+export declare function collectSharedRootInstructionState(bundles: MaterializedState["bundles"], plannedWriteTargets: string[], excludedBundleName: string): {
+    files: string[];
+    file_fingerprints: Record<string, string>;
+};

package/dist/root-instruction-state.js

@@ -0,0 +1,273 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureRootInstructionBaseContents = captureRootInstructionBaseContents;
+exports.syncManagedRootInstructionFiles = syncManagedRootInstructionFiles;
+exports.restoreRootInstructionBaseContents = restoreRootInstructionBaseContents;
+exports.refreshManagedFileFingerprintsForPaths = refreshManagedFileFingerprintsForPaths;
+exports.collectManagedRootInstructionTargets = collectManagedRootInstructionTargets;
+exports.assertManagedRootInstructionSyncSourcesCached = assertManagedRootInstructionSyncSourcesCached;
+exports.collectSharedRootInstructionState = collectSharedRootInstructionState;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const root_instruction_content_1 = require("./root-instruction-content");
+const root_instruction_render_1 = require("./root-instruction-render");
+const tool_mapping_1 = require("./tool-mapping");
+/** Captures pre-existing root-instruction file contents before Skul starts managing them. */
+function captureRootInstructionBaseContents(options) {
+    if (options.targetPaths.size === 0) {
+        return options.existingBaseContents;
+    }
+    const nextBaseContents = { ...(options.existingBaseContents ?? {}) };
+    for (const repoRelativePath of options.targetPaths) {
+        if (repoRelativePath in nextBaseContents) {
+            continue;
+        }
+        if (options.managedTargetPaths?.has(repoRelativePath)) {
+            continue;
+        }
+        const targetPath = node_path_1.default.join(options.repoRoot, repoRelativePath);
+        if (!node_fs_1.default.existsSync(targetPath) || !node_fs_1.default.statSync(targetPath).isFile()) {
+            continue;
+        }
+        nextBaseContents[repoRelativePath] = node_fs_1.default.readFileSync(targetPath, "utf8");
+    }
+    return Object.keys(nextBaseContents).length > 0
+        ? nextBaseContents
+        : undefined;
+}
+/** Rebuilds shared root-instruction files from desired bundle state and returns the rewritten paths. */
+function syncManagedRootInstructionFiles(options) {
+    const contentByPath = collectRootInstructionContentByPath(options);
+    const writtenPaths = new Set();
+    for (const [repoRelativePath, parts] of contentByPath.entries()) {
+        const baseContent = options.rootInstructionBaseContents?.[repoRelativePath];
+        const targetPath = node_path_1.default.join(options.repoRoot, repoRelativePath);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(targetPath), { recursive: true });
+        node_fs_1.default.writeFileSync(targetPath, `${(0, root_instruction_render_1.composeRootInstructionContent)([baseContent, ...parts])}\n`);
+        writtenPaths.add(repoRelativePath);
+    }
+    return writtenPaths;
+}
+function collectRootInstructionContentByPath(options) {
+    const contentByPath = new Map();
+    const seenBundleTargets = new Set();
+    for (const desiredEntry of options.desiredState) {
+        const materializedBundleState = options.materializedBundles[desiredEntry.bundle];
+        if (!materializedBundleState) {
+            continue;
+        }
+        const cachedBundle = options.resolveCachedBundle(desiredEntry);
+        const toolNames = Object.keys(materializedBundleState.tools);
+        if (options.repoRelPathRemapper) {
+            // In global mode, tools that share a project path (e.g. AGENTS.md) may remap to different
+            // global targets (e.g. .github/copilot-instructions.md vs .gemini/GEMINI.md). Collect and
+            // remap per-tool so each tool maps to its own global path independently.
+            // Only process globally-capable tools; non-global tools in the materialized state (e.g. from
+            // registry corruption) would pass through the remapper unchanged and write to homeDir at the
+            // project-level path.
+            const globalTools = (0, tool_mapping_1.globalCapableToolNames)();
+            for (const toolName of toolNames.filter((t) => globalTools.includes(t))) {
+                const rawToolContentByPath = (0, root_instruction_content_1.collectComposedRootInstructionContents)({
+                    bundleDir: node_path_1.default.dirname(cachedBundle.manifestFile),
+                    manifest: cachedBundle.manifest,
+                    toolNames: [toolName],
+                    targetPaths: undefined,
+                    itemSelectors: desiredEntry.items,
+                });
+                const toolContentByPath = Object.fromEntries(Object.entries(rawToolContentByPath).map(([k, v]) => [
+                    options.repoRelPathRemapper(toolName, k),
+                    v,
+                ]));
+                for (const repoRelativePath of materializedBundleState.tools[toolName]
+                    .files) {
+                    if (!(0, root_instruction_render_1.isRootInstructionPath)(repoRelativePath)) {
+                        continue;
+                    }
+                    if (options.targetPaths &&
+                        !options.targetPaths.has(repoRelativePath)) {
+                        continue;
+                    }
+                    const content = toolContentByPath[repoRelativePath];
+                    if (content === undefined) {
+                        continue;
+                    }
+                    const bundleTargetKey = `${desiredEntry.bundle}:${repoRelativePath}`;
+                    if (seenBundleTargets.has(bundleTargetKey)) {
+                        continue;
+                    }
+                    seenBundleTargets.add(bundleTargetKey);
+                    const existingParts = contentByPath.get(repoRelativePath) ?? [];
+                    existingParts.push((0, root_instruction_render_1.wrapRootInstructionBundleContent)({
+                        bundleName: desiredEntry.bundle,
+                        source: desiredEntry.source,
+                        content,
+                    }));
+                    contentByPath.set(repoRelativePath, existingParts);
+                }
+            }
+        }
+        else {
+            // Non-global mode: collect all tools at once so tools sharing a path (e.g. multiple tools
+            // targeting AGENTS.md) have their content properly aggregated before writing.
+            const rawBundleContentByPath = (0, root_instruction_content_1.collectComposedRootInstructionContents)({
+                bundleDir: node_path_1.default.dirname(cachedBundle.manifestFile),
+                manifest: cachedBundle.manifest,
+                toolNames,
+                targetPaths: options.targetPaths,
+                itemSelectors: desiredEntry.items,
+            });
+            for (const toolName of toolNames) {
+                for (const repoRelativePath of materializedBundleState.tools[toolName]
+                    .files) {
+                    if (!(0, root_instruction_render_1.isRootInstructionPath)(repoRelativePath)) {
+                        continue;
+                    }
+                    if (options.targetPaths &&
+                        !options.targetPaths.has(repoRelativePath)) {
+                        continue;
+                    }
+                    const content = rawBundleContentByPath[repoRelativePath];
+                    if (content === undefined) {
+                        continue;
+                    }
+                    const bundleTargetKey = `${desiredEntry.bundle}:${repoRelativePath}`;
+                    if (seenBundleTargets.has(bundleTargetKey)) {
+                        continue;
+                    }
+                    seenBundleTargets.add(bundleTargetKey);
+                    const existingParts = contentByPath.get(repoRelativePath) ?? [];
+                    existingParts.push((0, root_instruction_render_1.wrapRootInstructionBundleContent)({
+                        bundleName: desiredEntry.bundle,
+                        source: desiredEntry.source,
+                        content,
+                    }));
+                    contentByPath.set(repoRelativePath, existingParts);
+                }
+            }
+        }
+    }
+    return contentByPath;
+}
+/** Restores preserved base content for root-instruction files that Skul no longer manages. */
+function restoreRootInstructionBaseContents(options) {
+    if (!options.baseContents || options.targetPaths.size === 0) {
+        return new Set();
+    }
+    const restoredPaths = new Set();
+    for (const repoRelativePath of options.targetPaths) {
+        const baseContent = options.baseContents[repoRelativePath];
+        if (baseContent === undefined) {
+            continue;
+        }
+        const targetPath = node_path_1.default.join(options.repoRoot, repoRelativePath);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(targetPath), { recursive: true });
+        node_fs_1.default.writeFileSync(targetPath, baseContent);
+        restoredPaths.add(repoRelativePath);
+    }
+    return restoredPaths;
+}
+/** Refreshes fingerprints for a subset of managed files after they are rewritten in place. */
+function refreshManagedFileFingerprintsForPaths(repoRoot, bundles, filePaths) {
+    if (filePaths.size === 0) {
+        return bundles;
+    }
+    return Object.fromEntries(Object.entries(bundles).map(([bundleName, bundleState]) => [
+        bundleName,
+        {
+            ...bundleState,
+            tools: Object.fromEntries(Object.entries(bundleState.tools).map(([toolName, toolState]) => [
+                toolName,
+                {
+                    ...toolState,
+                    file_fingerprints: {
+                        ...(toolState.file_fingerprints ?? {}),
+                        ...captureManagedFileFingerprints(repoRoot, toolState.files.filter((filePath) => filePaths.has(filePath))),
+                    },
+                },
+            ])),
+        },
+    ]));
+}
+function captureManagedFileFingerprints(repoRoot, files) {
+    return Object.fromEntries(files.map((relativePath) => [
+        relativePath,
+        fingerprintFile(node_path_1.default.join(repoRoot, relativePath)),
+    ]));
+}
+function fingerprintFile(filePath) {
+    try {
+        return (0, node_crypto_1.createHash)("sha256").update(node_fs_1.default.readFileSync(filePath)).digest("hex");
+    }
+    catch {
+        // On read failure treat the file as modified so callers prompt before deletion
+        // rather than silently skipping a managed file that may still exist.
+        return "";
+    }
+}
+/** Returns every root-instruction path currently owned by managed bundles. */
+function collectManagedRootInstructionTargets(bundles) {
+    return new Set(Object.values(bundles).flatMap((bundleState) => Object.values(bundleState.tools).flatMap((toolState) => toolState.files.filter((filePath) => (0, root_instruction_render_1.isRootInstructionPath)(filePath)))));
+}
+/** Verifies that every bundle needed for shared root-instruction recomposition is cached. */
+function assertManagedRootInstructionSyncSourcesCached(options) {
+    if (options.targetPaths.size === 0) {
+        return;
+    }
+    for (const desiredEntry of options.desiredState) {
+        const materializedBundleState = options.materializedBundles[desiredEntry.bundle];
+        if (!materializedBundleState) {
+            continue;
+        }
+        const ownsTargetPath = Object.values(materializedBundleState.tools).some((toolState) => toolState.files.some((filePath) => options.targetPaths.has(filePath)));
+        if (!ownsTargetPath) {
+            continue;
+        }
+        options.resolveCachedBundle(desiredEntry);
+    }
+}
+/** Collects other bundles that already own root-instruction paths targeted by an upcoming write. */
+function collectSharedRootInstructionState(bundles, plannedWriteTargets, excludedBundleName) {
+    const sharedRootTargets = new Set(plannedWriteTargets.filter((filePath) => (0, root_instruction_render_1.isRootInstructionPath)(filePath)));
+    const files = new Set();
+    const fileFingerprints = {};
+    for (const [bundleName, bundleState] of Object.entries(bundles)) {
+        if (bundleName === excludedBundleName) {
+            continue;
+        }
+        const flattenedState = flattenBundleState(bundleState);
+        for (const filePath of flattenedState.files) {
+            if (!sharedRootTargets.has(filePath)) {
+                continue;
+            }
+            files.add(filePath);
+            if (flattenedState.file_fingerprints[filePath]) {
+                fileFingerprints[filePath] = flattenedState.file_fingerprints[filePath];
+            }
+        }
+    }
+    return {
+        files: Array.from(files),
+        file_fingerprints: fileFingerprints,
+    };
+}
+function flattenBundleState(bundleState) {
+    const files = new Set();
+    const fileFingerprints = {};
+    for (const toolState of Object.values(bundleState.tools)) {
+        for (const file of toolState.files) {
+            files.add(file);
+        }
+        if (toolState.file_fingerprints) {
+            Object.assign(fileFingerprints, toolState.file_fingerprints);
+        }
+    }
+    return {
+        files: Array.from(files),
+        file_fingerprints: fileFingerprints,
+    };
+}
+//# sourceMappingURL=root-instruction-state.js.map

package/dist/root-instruction-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-instruction-state.js","sourceRoot":"","sources":["../src/root-instruction-state.ts"],"names":[],"mappings":"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"}

package/dist/state-layout.d.ts

@@ -0,0 +1,11 @@
+export interface GlobalStateLayout {
+    rootDir: string;
+    registryFile: string;
+    libraryDir: string;
+    resolveLibraryPath(...segments: string[]): string;
+}
+export interface ResolveGlobalStateLayoutOptions {
+    homeDir: string;
+}
+/** Resolves the on-disk layout Skul uses for global state under one home directory. */
+export declare function resolveGlobalStateLayout(options: ResolveGlobalStateLayoutOptions): GlobalStateLayout;

package/dist/state-layout.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGlobalStateLayout = resolveGlobalStateLayout;
+const node_path_1 = __importDefault(require("node:path"));
+const STATE_DIR_NAME = ".skul";
+const REGISTRY_FILE_NAME = "registry.json";
+const LIBRARY_DIR_NAME = "library";
+/** Resolves the on-disk layout Skul uses for global state under one home directory. */
+function resolveGlobalStateLayout(options) {
+    const homeDir = options.homeDir.trim();
+    if (!homeDir) {
+        throw new Error("A home directory is required to resolve the global state layout");
+    }
+    const rootDir = node_path_1.default.join(homeDir, STATE_DIR_NAME);
+    const libraryDir = node_path_1.default.join(rootDir, LIBRARY_DIR_NAME);
+    return {
+        rootDir,
+        registryFile: node_path_1.default.join(rootDir, REGISTRY_FILE_NAME),
+        libraryDir,
+        resolveLibraryPath: (...segments) => node_path_1.default.join(libraryDir, ...segments),
+    };
+}
+//# sourceMappingURL=state-layout.js.map

package/dist/state-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-layout.js","sourceRoot":"","sources":["../src/state-layout.ts"],"names":[],"mappings":";;;;;AAkBA,4DAqBC;AAvCD,0DAA6B;AAE7B,MAAM,cAAc,GAAG,OAAO,CAAC;AAC/B,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAC3C,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAanC,uFAAuF;AACvF,SAAgB,wBAAwB,CACtC,OAAwC;IAExC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAEvC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IAExD,OAAO;QACL,OAAO;QACP,YAAY,EAAE,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC;QACpD,UAAU;QACV,kBAAkB,EAAE,CAAC,GAAG,QAAkB,EAAE,EAAE,CAC5C,mBAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,QAAQ,CAAC;KACrC,CAAC;AACJ,CAAC"}

package/dist/tool-mapping.d.ts

@@ -0,0 +1,35 @@
+export type ToolName = "claude-code" | "cursor" | "opencode" | "codex" | "copilot" | "kiro" | "antigravity";
+export type ToolTargetName = "skills" | "commands" | "agents" | "root_instruction";
+export type ToolTargetEntryKind = "directory" | "file";
+export interface ToolTargetDefinition {
+    path: string;
+    kind: ToolTargetEntryKind;
+}
+export interface ToolDefinition {
+    name: ToolName;
+    targets: Partial<Record<ToolTargetName, ToolTargetDefinition>>;
+}
+export interface ToolMaterializationLayout {
+    remapRepoRelPath(toolName: string, repoRelPath: string): string;
+    resolveToolTargetPath(toolName: string, targetName: ToolTargetName, rootDir: string): string | null;
+}
+/** Returns a defensive copy of all supported tool definitions. */
+export declare function listToolDefinitions(): ToolDefinition[];
+/** Returns all tool definitions for global (~/) materialization. */
+export declare function listGlobalToolDefinitions(): ToolDefinition[];
+/** Returns the global tool definition for one tool, or null if not supported globally.
+ * Exported for use by external consumers inspecting global installation layout. */
+export declare function getGlobalToolDefinition(name: string): ToolDefinition | null;
+/** Returns the names of tools that support global installation. */
+export declare function globalCapableToolNames(): ToolName[];
+/** Returns the path remapper for global mode. Takes the tool name so that tools sharing
+ * the same project path (e.g. AGENTS.md) can each remap to their own global path. */
+export declare function buildGlobalRepoRelPathRemapper(): (toolName: string, p: string) => string;
+/** Looks up one tool definition by name and returns a defensive copy when found. */
+export declare function getToolDefinition(name: string): ToolDefinition | null;
+/** Resolves the absolute target root path for one tool target inside a repository. */
+export declare function resolveToolTargetPath(toolName: string, targetName: ToolTargetName, repoRoot: string): string | null;
+/** Resolves the absolute target root path for one global tool target under a home directory. */
+export declare function resolveGlobalToolTargetPath(toolName: string, targetName: ToolTargetName, homeDir: string): string | null;
+export declare const PROJECT_TOOL_MATERIALIZATION_LAYOUT: ToolMaterializationLayout;
+export declare const GLOBAL_TOOL_MATERIALIZATION_LAYOUT: ToolMaterializationLayout;