aman-intelligence 0.1.0

package/dist/services/pack.service.js

@@ -0,0 +1,193 @@
+import path from 'path';
+import os from 'os';
+import archiver from 'archiver';
+import { createWriteStream } from 'fs';
+import { spawnSync } from 'child_process';
+import { exists, ensureDir, removeDir } from '../storage/filesystem.js';
+import { environmentService } from './environment.service.js';
+import { lockService } from './lock.service.js';
+import { defaultSlugForName } from '../utils/slug.js';
+import { randomUUID } from 'crypto';
+import { assetDir, migrateScopeLayout, contentFilePath } from '../storage/asset-layout.js';
+import { mcpRequiresLocalConfig } from '../utils/mcp-local.js';
+export class PackService {
+    async create(name, packData, outputPath) {
+        await ensureDir(path.dirname(outputPath));
+        return new Promise((resolve, reject) => {
+            const output = createWriteStream(outputPath);
+            const archive = archiver('zip', { zlib: { level: 9 } });
+            output.on('close', () => resolve());
+            archive.on('error', (err) => reject(err));
+            archive.pipe(output);
+            // Add manifest
+            archive.append(JSON.stringify(packData, null, 2), { name: 'manifest.json' });
+            // Add skills
+            for (const skill of packData.skills) {
+                const skillPath = path.join(environmentService.getActiveEnvironmentDir(), 'skills', skill);
+                if (exists(skillPath)) {
+                    archive.directory(skillPath, `skills/${skill}`);
+                }
+            }
+            const envDir = environmentService.getActiveEnvironmentDir();
+            const promptsRoot = path.join(envDir, 'prompts');
+            const mcpsRoot = path.join(envDir, 'mcps');
+            for (const prompt of packData.prompts) {
+                const promptDir = assetDir('prompt', promptsRoot, prompt);
+                if (exists(promptDir)) {
+                    archive.directory(promptDir, `prompts/${prompt}`);
+                }
+            }
+            for (const mcp of packData.mcps) {
+                const mcpDirPath = assetDir('mcp', mcpsRoot, mcp);
+                if (exists(mcpDirPath)) {
+                    archive.directory(mcpDirPath, `mcps/${mcp}`);
+                }
+            }
+            // Add stacks
+            for (const stack of packData.stacks) {
+                const stackPath = path.join(environmentService.getActiveEnvironmentDir(), 'stacks', `${stack}.json`);
+                if (exists(stackPath)) {
+                    archive.file(stackPath, { name: `stacks/${stack}.json` });
+                }
+            }
+            archive.finalize();
+        });
+    }
+    async install(packPath, scope, onProgress) {
+        if (!exists(packPath))
+            throw new Error(`Pack not found: ${packPath}`);
+        const tempDir = path.join(os.tmpdir(), `aman-pack-${Date.now()}`);
+        await ensureDir(tempDir);
+        try {
+            this.extractPack(packPath, tempDir);
+            onProgress?.(25);
+            const files = await this.walk(tempDir);
+            const { isPathSafe, readJson, copyDir } = await import('../storage/filesystem.js');
+            for (const file of files) {
+                const safe = await isPathSafe(file, tempDir);
+                if (!safe) {
+                    throw new Error('Security Exception: Path traversal escape attempt detected inside pack archive!');
+                }
+            }
+            onProgress?.(50);
+            const manifestPath = path.join(tempDir, 'manifest.json');
+            const manifest = await readJson(manifestPath);
+            if (!manifest)
+                throw new Error('Invalid pack manifest');
+            const targetBase = scope === 'global'
+                ? await environmentService.ensureActiveEnvironment()
+                : await environmentService.ensureProjectEnvironment();
+            // Copy skills
+            if (exists(path.join(tempDir, 'skills'))) {
+                await copyDir(path.join(tempDir, 'skills'), path.join(targetBase, 'skills'));
+            }
+            // Copy prompts
+            if (exists(path.join(tempDir, 'prompts'))) {
+                await copyDir(path.join(tempDir, 'prompts'), path.join(targetBase, 'prompts'));
+            }
+            // Copy mcps
+            if (exists(path.join(tempDir, 'mcps'))) {
+                await copyDir(path.join(tempDir, 'mcps'), path.join(targetBase, 'mcps'));
+            }
+            // Copy stacks
+            if (exists(path.join(tempDir, 'stacks'))) {
+                await copyDir(path.join(tempDir, 'stacks'), path.join(targetBase, 'stacks'));
+            }
+            await migrateScopeLayout(targetBase);
+            onProgress?.(80);
+            const packRef = manifest.slug ?? defaultSlugForName(manifest.name);
+            const packVersion = manifest.version ?? '1.0.0';
+            const installedAt = new Date().toISOString();
+            const placeholderChecksum = 'sha256:0000000000000000000000000000000000000000000000000000000000000000';
+            const addPackEntry = async (localName, type) => {
+                let requiresLocalConfig = false;
+                if (type === 'mcp') {
+                    const mcpDir = assetDir('mcp', path.join(targetBase, 'mcps'), localName);
+                    const mcpData = await readJson(contentFilePath(mcpDir, 'mcp'));
+                    requiresLocalConfig = mcpData ? mcpRequiresLocalConfig(mcpData) : false;
+                }
+                await lockService.addEntry(scope, {
+                    id: randomUUID(),
+                    slug: defaultSlugForName(localName),
+                    type,
+                    localName,
+                    version: packVersion,
+                    integrity: { algorithm: 'sha256', checksum: placeholderChecksum },
+                    source: { kind: 'pack', ref: `pack:${packRef}@${packVersion}` },
+                    scope,
+                    installedAt,
+                    dependencies: [],
+                    requiresLocalConfig,
+                });
+            };
+            for (const skill of manifest.skills || []) {
+                await addPackEntry(skill, 'skill');
+            }
+            for (const prompt of manifest.prompts || []) {
+                await addPackEntry(prompt, 'prompt');
+            }
+            for (const mcp of manifest.mcps || []) {
+                await addPackEntry(mcp, 'mcp');
+            }
+            onProgress?.(100);
+        }
+        finally {
+            await removeDir(tempDir);
+        }
+    }
+    async inspect(packPath) {
+        if (!exists(packPath))
+            throw new Error(`Pack not found: ${packPath}`);
+        // Simplistic inspect by extracting manifest
+        const tempDir = path.join(os.tmpdir(), `aman-pack-inspect-${Date.now()}`);
+        await ensureDir(tempDir);
+        try {
+            this.extractPack(packPath, tempDir);
+            const files = await this.walk(tempDir);
+            const { isPathSafe, readJson } = await import('../storage/filesystem.js');
+            for (const file of files) {
+                const safe = await isPathSafe(file, tempDir);
+                if (!safe) {
+                    throw new Error('Security Exception: Path traversal escape attempt detected inside pack archive!');
+                }
+            }
+            const manifestPath = path.join(tempDir, 'manifest.json');
+            if (!exists(manifestPath))
+                throw new Error('Invalid pack: missing manifest.json');
+            const manifest = await readJson(manifestPath);
+            return manifest;
+        }
+        finally {
+            await removeDir(tempDir);
+        }
+    }
+    async walk(root) {
+        const fsPromises = (await import('fs')).promises;
+        const entries = await fsPromises.readdir(root, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            const fullPath = path.join(root, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...await this.walk(fullPath));
+            }
+            else if (entry.isFile()) {
+                files.push(fullPath);
+            }
+        }
+        return files;
+    }
+    extractPack(packPath, tempDir) {
+        const result = process.platform === 'win32'
+            ? spawnSync('tar', ['-xf', packPath, '-C', tempDir], { stdio: 'pipe' })
+            : spawnSync('unzip', ['-o', packPath, '-d', tempDir], { stdio: 'pipe' });
+        if (result.status !== 0) {
+            const stderr = result.stderr?.toString() || '';
+            const stdout = result.stdout?.toString() || '';
+            if (stderr.includes('..') || stderr.includes('path') || stdout.includes('..')) {
+                throw new Error('Security Exception: Path traversal escape attempt detected inside pack archive!');
+            }
+            throw new Error('Could not extract pack.');
+        }
+    }
+}
+export const packService = new PackService();

package/dist/services/stack.service.d.ts

@@ -0,0 +1,9 @@
+import { Stack, Scope } from '../types/index.js';
+export declare class StackService {
+    private getTargetDir;
+    create(scope: Scope, name: string, skills: string[], prompts: string[], mcps: string[], description?: string): Promise<void>;
+    update(scope: Scope, name: string, updates: Partial<Pick<Stack, 'skills' | 'prompts' | 'mcps' | 'description'>>): Promise<void>;
+    remove(scope: Scope, name: string): Promise<void>;
+    list(scope: Scope): Promise<Stack[]>;
+}
+export declare const stackService: StackService;

package/dist/services/stack.service.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'crypto';
+import path from 'path';
+import { LOCAL_DIR } from '../config/paths.js';
+import { writeJson, exists, ensureDir, readJson } from '../storage/filesystem.js';
+import { scanStacks } from '../storage/scanner.js';
+import { promises as fs } from 'fs';
+import { environmentService } from './environment.service.js';
+import { defaultSlugForName } from '../utils/slug.js';
+function buildMembers(skills, prompts, mcps, version = '1.0.0') {
+    return {
+        skills: skills.map((localName) => ({
+            localName,
+            slug: defaultSlugForName(localName),
+            version,
+        })),
+        prompts: prompts.map((localName) => ({
+            localName,
+            slug: defaultSlugForName(localName),
+            version,
+        })),
+        mcps: mcps.map((localName) => ({
+            localName,
+            slug: defaultSlugForName(localName),
+            version,
+        })),
+    };
+}
+export class StackService {
+    getTargetDir(scope) {
+        return scope === 'global'
+            ? path.join(environmentService.getActiveEnvironmentDir(), 'stacks')
+            : path.join(LOCAL_DIR, 'stacks');
+    }
+    async create(scope, name, skills, prompts, mcps, description) {
+        const now = new Date().toISOString();
+        const stack = {
+            schemaVersion: 1,
+            recordType: 'stack',
+            id: randomUUID(),
+            slug: `@local/${name}`,
+            name,
+            description,
+            visibility: 'private',
+            members: buildMembers(skills, prompts, mcps),
+            skills,
+            prompts,
+            mcps,
+            packs: [],
+            deprecated: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const targetDir = this.getTargetDir(scope);
+        await ensureDir(targetDir);
+        const destPath = path.join(targetDir, `${name}.json`);
+        await writeJson(destPath, stack);
+    }
+    async update(scope, name, updates) {
+        const targetDir = this.getTargetDir(scope);
+        const destPath = path.join(targetDir, `${name}.json`);
+        if (!exists(destPath)) {
+            throw new Error(`Stack "${name}" not found in scope "${scope}"`);
+        }
+        const stack = await readJson(destPath);
+        if (!stack) {
+            throw new Error(`Failed to read stack "${name}" in scope "${scope}"`);
+        }
+        const skills = updates.skills ?? stack.skills;
+        const prompts = updates.prompts ?? stack.prompts;
+        const mcps = updates.mcps ?? stack.mcps;
+        const updatedStack = {
+            ...stack,
+            ...updates,
+            skills,
+            prompts,
+            mcps,
+            members: buildMembers(skills, prompts, mcps),
+            updatedAt: new Date().toISOString(),
+        };
+        await writeJson(destPath, updatedStack);
+    }
+    async remove(scope, name) {
+        const targetDir = this.getTargetDir(scope);
+        const destPath = path.join(targetDir, `${name}.json`);
+        if (exists(destPath)) {
+            await fs.unlink(destPath);
+        }
+    }
+    async list(scope) {
+        const targetDir = this.getTargetDir(scope);
+        return await scanStacks(targetDir, scope);
+    }
+}
+export const stackService = new StackService();

package/dist/storage/asset-layout.d.ts

@@ -0,0 +1,46 @@
+import { AssetType } from '../types/index.js';
+export declare const CONTENT_FILES: Record<AssetType, string>;
+export declare function assetDir(type: AssetType, typeRoot: string, localName: string): string;
+export declare function contentFilePath(assetDirectory: string, type: AssetType): string;
+export declare function metadataFilePath(assetDirectory: string): string;
+export declare function mcpLocalFilePath(assetDirectory: string): string;
+export declare function isCanonicalAssetDir(type: AssetType, dirPath: string): boolean;
+/** Flat prompt: prompts/{name}.md + optional prompts/{name}.md.metadata.json */
+export declare function flatPromptPaths(typeRoot: string, localName: string): {
+    md: string;
+    metadata: string;
+};
+/** Flat MCP: mcps/{name}.json + optional mcps/{name}.json.metadata.json */
+export declare function flatMcpPaths(typeRoot: string, localName: string): {
+    json: string;
+    metadata: string;
+    local: string;
+};
+export declare function detectPromptLayout(typeRoot: string, localName: string): 'canonical' | 'flat' | 'missing';
+export declare function detectMcpLayout(typeRoot: string, localName: string): 'canonical' | 'flat' | 'missing';
+/**
+ * Migrates flat prompt/MCP files into canonical directory layout.
+ * Preserves content bytes (checksum unchanged). Removes flat files after success.
+ */
+export declare function migratePromptFlatToCanonical(typeRoot: string, localName: string): Promise<boolean>;
+export declare function migrateMcpFlatToCanonical(typeRoot: string, localName: string): Promise<boolean>;
+/** Scan type root for flat files and migrate each. Returns count migrated. */
+export declare function migrateTypeRootLayout(type: 'prompt' | 'mcp', typeRoot: string): Promise<number>;
+/** Migrate prompts/ and mcps/ under a scope root (.aman or global env). */
+export declare function migrateScopeLayout(scopeRoot: string): Promise<{
+    prompts: number;
+    mcps: number;
+}>;
+export interface LayoutViolation {
+    type: AssetType;
+    localName: string;
+    issue: string;
+}
+/** Lists assets not in canonical directory layout (post-migration). */
+export declare function findLayoutViolations(scopeRoot: string): Promise<LayoutViolation[]>;
+/**
+ * Install content from src (file or directory) into canonical asset directory.
+ */
+export declare function materializeAssetDirectory(type: AssetType, src: string, destDir: string): Promise<void>;
+/** Resolve bundled/default source path (flat file or directory). */
+export declare function resolveBundledSource(type: AssetType, bundledDir: string, localName: string): string;

package/dist/storage/asset-layout.js

@@ -0,0 +1,277 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { exists, ensureDir, readJson, writeJson, listDirs, listFiles } from './filesystem.js';
+import { computeAssetChecksum } from '../utils/integrity.js';
+import { normalizeAssetMetadata } from '../types/asset-metadata.js';
+export const CONTENT_FILES = {
+    skill: 'SKILL.md',
+    prompt: 'PROMPT.md',
+    mcp: 'mcp.json',
+};
+export function assetDir(type, typeRoot, localName) {
+    return path.join(typeRoot, localName);
+}
+export function contentFilePath(assetDirectory, type) {
+    return path.join(assetDirectory, CONTENT_FILES[type]);
+}
+export function metadataFilePath(assetDirectory) {
+    return path.join(assetDirectory, 'metadata.json');
+}
+export function mcpLocalFilePath(assetDirectory) {
+    return path.join(assetDirectory, 'mcp.local.json');
+}
+export function isCanonicalAssetDir(type, dirPath) {
+    if (!exists(dirPath))
+        return false;
+    return exists(contentFilePath(dirPath, type)) && exists(metadataFilePath(dirPath));
+}
+/** Flat prompt: prompts/{name}.md + optional prompts/{name}.md.metadata.json */
+export function flatPromptPaths(typeRoot, localName) {
+    return {
+        md: path.join(typeRoot, `${localName}.md`),
+        metadata: path.join(typeRoot, `${localName}.md.metadata.json`),
+    };
+}
+/** Flat MCP: mcps/{name}.json + optional mcps/{name}.json.metadata.json */
+export function flatMcpPaths(typeRoot, localName) {
+    return {
+        json: path.join(typeRoot, `${localName}.json`),
+        metadata: path.join(typeRoot, `${localName}.json.metadata.json`),
+        local: path.join(typeRoot, `${localName}.local.json`),
+    };
+}
+export function detectPromptLayout(typeRoot, localName) {
+    const dir = assetDir('prompt', typeRoot, localName);
+    if (isCanonicalAssetDir('prompt', dir))
+        return 'canonical';
+    const flat = flatPromptPaths(typeRoot, localName);
+    if (exists(flat.md))
+        return 'flat';
+    return 'missing';
+}
+export function detectMcpLayout(typeRoot, localName) {
+    const dir = assetDir('mcp', typeRoot, localName);
+    if (isCanonicalAssetDir('mcp', dir))
+        return 'canonical';
+    const flat = flatMcpPaths(typeRoot, localName);
+    if (exists(flat.json))
+        return 'flat';
+    return 'missing';
+}
+async function readMetadataFromFlatOrDir(type, typeRoot, localName, layout) {
+    if (layout === 'canonical') {
+        return readJson(metadataFilePath(assetDir(type, typeRoot, localName)));
+    }
+    const flatMeta = type === 'prompt'
+        ? flatPromptPaths(typeRoot, localName).metadata
+        : flatMcpPaths(typeRoot, localName).metadata;
+    return readJson(flatMeta);
+}
+/**
+ * Migrates flat prompt/MCP files into canonical directory layout.
+ * Preserves content bytes (checksum unchanged). Removes flat files after success.
+ */
+export async function migratePromptFlatToCanonical(typeRoot, localName) {
+    const layout = detectPromptLayout(typeRoot, localName);
+    if (layout !== 'flat')
+        return layout === 'canonical';
+    const flat = flatPromptPaths(typeRoot, localName);
+    const destDir = assetDir('prompt', typeRoot, localName);
+    await ensureDir(destDir);
+    await fs.copyFile(flat.md, contentFilePath(destDir, 'prompt'));
+    const existingMeta = await readMetadataFromFlatOrDir('prompt', typeRoot, localName, 'flat');
+    const metadata = existingMeta
+        ? normalizeAssetMetadata(existingMeta, 'prompt', localName)
+        : normalizeAssetMetadata({}, 'prompt', localName);
+    const checksum = await computeAssetChecksum('prompt', destDir);
+    metadata.integrity.checksum = checksum;
+    await writeJson(metadataFilePath(destDir), metadata);
+    await fs.unlink(flat.md);
+    if (exists(flat.metadata))
+        await fs.unlink(flat.metadata);
+    return true;
+}
+export async function migrateMcpFlatToCanonical(typeRoot, localName) {
+    const layout = detectMcpLayout(typeRoot, localName);
+    if (layout !== 'flat')
+        return layout === 'canonical';
+    const flat = flatMcpPaths(typeRoot, localName);
+    const destDir = assetDir('mcp', typeRoot, localName);
+    await ensureDir(destDir);
+    await fs.copyFile(flat.json, contentFilePath(destDir, 'mcp'));
+    if (exists(flat.local)) {
+        await fs.copyFile(flat.local, mcpLocalFilePath(destDir));
+    }
+    const existingMeta = await readMetadataFromFlatOrDir('mcp', typeRoot, localName, 'flat');
+    const metadata = existingMeta
+        ? normalizeAssetMetadata(existingMeta, 'mcp', localName)
+        : normalizeAssetMetadata({}, 'mcp', localName);
+    const checksum = await computeAssetChecksum('mcp', destDir);
+    metadata.integrity.checksum = checksum;
+    await writeJson(metadataFilePath(destDir), metadata);
+    await fs.unlink(flat.json);
+    if (exists(flat.metadata))
+        await fs.unlink(flat.metadata);
+    if (exists(flat.local))
+        await fs.unlink(flat.local);
+    return true;
+}
+/** Scan type root for flat files and migrate each. Returns count migrated. */
+export async function migrateTypeRootLayout(type, typeRoot) {
+    if (!exists(typeRoot))
+        return 0;
+    let migrated = 0;
+    if (type === 'prompt') {
+        const flatFiles = await listFiles(typeRoot, '.md');
+        for (const file of flatFiles) {
+            if (file.endsWith('.metadata.json'))
+                continue;
+            const localName = file.replace(/\.md$/, '');
+            if (await migratePromptFlatToCanonical(typeRoot, localName))
+                migrated++;
+        }
+    }
+    else {
+        const flatFiles = await listFiles(typeRoot, '.json');
+        for (const file of flatFiles) {
+            if (file.endsWith('.metadata.json') || file.endsWith('.local.json'))
+                continue;
+            const localName = file.replace(/\.json$/, '');
+            if (await migrateMcpFlatToCanonical(typeRoot, localName))
+                migrated++;
+        }
+    }
+    return migrated;
+}
+/** Migrate prompts/ and mcps/ under a scope root (.aman or global env). */
+export async function migrateScopeLayout(scopeRoot) {
+    const promptsRoot = path.join(scopeRoot, 'prompts');
+    const mcpsRoot = path.join(scopeRoot, 'mcps');
+    const result = {
+        prompts: await migrateTypeRootLayout('prompt', promptsRoot),
+        mcps: await migrateTypeRootLayout('mcp', mcpsRoot),
+    };
+    if (exists(mcpsRoot)) {
+        const { ensureMcpLocalGitignore } = await import('../utils/mcp-local.js');
+        await ensureMcpLocalGitignore(scopeRoot);
+    }
+    return result;
+}
+/** Lists assets not in canonical directory layout (post-migration). */
+export async function findLayoutViolations(scopeRoot) {
+    const violations = [];
+    const skillsRoot = path.join(scopeRoot, 'skills');
+    if (exists(skillsRoot)) {
+        for (const name of await listDirs(skillsRoot)) {
+            const dir = assetDir('skill', skillsRoot, name);
+            if (!isCanonicalAssetDir('skill', dir)) {
+                violations.push({ type: 'skill', localName: name, issue: 'missing SKILL.md or metadata.json in asset directory' });
+            }
+        }
+        for (const file of await listFiles(skillsRoot, '.md')) {
+            violations.push({ type: 'skill', localName: file, issue: 'unexpected flat file in skills/' });
+        }
+    }
+    const promptsRoot = path.join(scopeRoot, 'prompts');
+    if (exists(promptsRoot)) {
+        for (const file of await listFiles(promptsRoot, '.md')) {
+            violations.push({
+                type: 'prompt',
+                localName: file.replace(/\.md$/, ''),
+                issue: 'flat prompt file (expected prompts/{name}/PROMPT.md)',
+            });
+        }
+        for (const name of await listDirs(promptsRoot)) {
+            const dir = assetDir('prompt', promptsRoot, name);
+            if (!isCanonicalAssetDir('prompt', dir)) {
+                violations.push({ type: 'prompt', localName: name, issue: 'prompt directory missing PROMPT.md or metadata.json' });
+            }
+        }
+    }
+    const mcpsRoot = path.join(scopeRoot, 'mcps');
+    if (exists(mcpsRoot)) {
+        for (const file of await listFiles(mcpsRoot, '.json')) {
+            if (file.endsWith('.metadata.json') || file.endsWith('.local.json')) {
+                violations.push({ type: 'mcp', localName: file, issue: 'flat MCP sidecar at mcps/ root (expected directory layout)' });
+                continue;
+            }
+            violations.push({
+                type: 'mcp',
+                localName: file.replace(/\.json$/, ''),
+                issue: 'flat mcp.json file (expected mcps/{name}/mcp.json)',
+            });
+        }
+        for (const name of await listDirs(mcpsRoot)) {
+            const dir = assetDir('mcp', mcpsRoot, name);
+            if (!isCanonicalAssetDir('mcp', dir)) {
+                violations.push({ type: 'mcp', localName: name, issue: 'MCP directory missing mcp.json or metadata.json' });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Install content from src (file or directory) into canonical asset directory.
+ */
+export async function materializeAssetDirectory(type, src, destDir) {
+    await ensureDir(destDir);
+    const contentDest = contentFilePath(destDir, type);
+    if (type === 'skill') {
+        if (exists(path.join(src, 'SKILL.md'))) {
+            await copyDirContents(src, destDir);
+            return;
+        }
+        throw new Error(`Invalid skill source: ${src}`);
+    }
+    if (type === 'prompt') {
+        const canonicalSrc = path.join(src, 'PROMPT.md');
+        if (exists(canonicalSrc)) {
+            await copyDirContents(src, destDir);
+            return;
+        }
+        if (src.endsWith('.md') && exists(src)) {
+            await fs.copyFile(src, contentDest);
+            return;
+        }
+        throw new Error(`Invalid prompt source: ${src}`);
+    }
+    const canonicalMcp = path.join(src, 'mcp.json');
+    if (exists(canonicalMcp)) {
+        await copyDirContents(src, destDir);
+        return;
+    }
+    if (src.endsWith('.json') && exists(src)) {
+        await fs.copyFile(src, contentDest);
+        return;
+    }
+    throw new Error(`Invalid MCP source: ${src}`);
+}
+async function copyDirContents(src, dest) {
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await ensureDir(destPath);
+            await copyDirContents(srcPath, destPath);
+        }
+        else {
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
+/** Resolve bundled/default source path (flat file or directory). */
+export function resolveBundledSource(type, bundledDir, localName) {
+    const dir = assetDir(type, bundledDir, localName);
+    if (type === 'skill' && exists(path.join(dir, 'SKILL.md')))
+        return dir;
+    if (type === 'prompt' && exists(path.join(dir, 'PROMPT.md')))
+        return dir;
+    if (type === 'mcp' && exists(path.join(dir, 'mcp.json')))
+        return dir;
+    if (type === 'skill')
+        return dir;
+    if (type === 'prompt')
+        return path.join(bundledDir, `${localName}.md`);
+    return path.join(bundledDir, `${localName}.json`);
+}

package/dist/storage/filesystem.d.ts

@@ -0,0 +1,12 @@
+export declare function ensureDir(dirPath: string): Promise<void>;
+export declare function readJson<T>(filePath: string): Promise<T | null>;
+export declare function writeJson<T>(filePath: string, data: T): Promise<void>;
+/** Atomic JSON write (temp file + rename) to avoid corrupted half-writes. */
+export declare function writeJsonAtomic<T>(filePath: string, data: T): Promise<void>;
+export declare function copyDir(src: string, dest: string): Promise<void>;
+export declare function removeDir(dirPath: string): Promise<void>;
+export declare function listDirs(dirPath: string): Promise<string[]>;
+export declare function listFiles(dirPath: string, ext?: string): Promise<string[]>;
+export declare function exists(targetPath: string): boolean;
+export declare function readFrontmatter(mdPath: string): Promise<Record<string, unknown> | null>;
+export declare function isPathSafe(targetPath: string, rootDir: string): Promise<boolean>;