aman-intelligence 0.1.0

package/dist/storage/filesystem.js

@@ -0,0 +1,113 @@
+import fs from 'fs/promises';
+import { existsSync } from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+export async function ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+}
+export async function readJson(filePath) {
+    try {
+        const data = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeJson(filePath, data) {
+    await writeJsonAtomic(filePath, data);
+}
+/** Atomic JSON write (temp file + rename) to avoid corrupted half-writes. */
+export async function writeJsonAtomic(filePath, data) {
+    await ensureDir(path.dirname(filePath));
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    const payload = JSON.stringify(data, null, 2);
+    await fs.writeFile(tmpPath, payload, 'utf-8');
+    await fs.rename(tmpPath, filePath);
+}
+export async function copyDir(src, dest) {
+    if (!existsSync(src))
+        return;
+    await ensureDir(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 copyDir(srcPath, destPath);
+        }
+        else {
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
+export async function removeDir(dirPath) {
+    if (!existsSync(dirPath))
+        return;
+    await fs.rm(dirPath, { recursive: true, force: true });
+}
+export async function listDirs(dirPath) {
+    if (!existsSync(dirPath))
+        return [];
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+export async function listFiles(dirPath, ext) {
+    if (!existsSync(dirPath))
+        return [];
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isFile() && (!ext || e.name.endsWith(ext)))
+        .map((e) => e.name);
+}
+export function exists(targetPath) {
+    return existsSync(targetPath);
+}
+export async function readFrontmatter(mdPath) {
+    try {
+        const content = await fs.readFile(mdPath, 'utf-8');
+        const match = content.match(/^---\n([\s\S]*?)\n---/);
+        if (match && match[1]) {
+            const parsed = yaml.load(match[1]);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function isPathSafe(targetPath, rootDir) {
+    try {
+        const resolvedRoot = await fs.realpath(path.resolve(rootDir));
+        const absoluteTarget = path.resolve(targetPath);
+        let current = absoluteTarget;
+        let resolvedTarget = absoluteTarget;
+        while (current) {
+            if (existsSync(current)) {
+                const realCurrent = await fs.realpath(current);
+                resolvedTarget = path.join(realCurrent, path.relative(current, absoluteTarget));
+                break;
+            }
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        const relative = path.relative(resolvedRoot, resolvedTarget);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            return false;
+        }
+        if (!resolvedTarget.startsWith(resolvedRoot)) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/storage/scan-by-type.d.ts

@@ -0,0 +1,2 @@
+import { AssetListItem, AssetType } from '../types/index.js';
+export declare function scanAssetsByType(type: AssetType, dir: string, source: string): Promise<AssetListItem[]>;

package/dist/storage/scan-by-type.js

@@ -0,0 +1,8 @@
+import { scanSkills, scanPrompts, scanMcps } from './scanner.js';
+export async function scanAssetsByType(type, dir, source) {
+    if (type === 'skill')
+        return scanSkills(dir, source);
+    if (type === 'prompt')
+        return scanPrompts(dir, source);
+    return scanMcps(dir, source);
+}

package/dist/storage/scanner.d.ts

@@ -0,0 +1,11 @@
+import { Skill, Prompt, McpConfig, Stack } from '../types/index.js';
+export declare function scanSkills(dir: string, source?: string): Promise<Skill[]>;
+export declare function scanPrompts(dir: string, source?: string): Promise<Prompt[]>;
+export declare function scanMcps(dir: string, source?: string): Promise<McpConfig[]>;
+export declare function scanStacks(dir: string, source?: string): Promise<Stack[]>;
+export declare function scanAll(dir: string, source?: string): Promise<{
+    skills: Skill[];
+    prompts: Prompt[];
+    mcps: McpConfig[];
+    stacks: Stack[];
+}>;

package/dist/storage/scanner.js

@@ -0,0 +1,188 @@
+import path from 'path';
+import { promises as fs } from 'fs';
+import { exists, listDirs, listFiles, readFrontmatter, readJson } from './filesystem.js';
+import { normalizeStack } from '../utils/stack-normalize.js';
+import { assetDir, contentFilePath, metadataFilePath, isCanonicalAssetDir, } from './asset-layout.js';
+const SCAN_CONCURRENCY = 20;
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const tags = value.filter((item) => typeof item === 'string' && item.trim().length > 0);
+    return tags.length > 0 ? tags : undefined;
+}
+async function boundedMap(items, limit, fn) {
+    if (items.length === 0)
+        return [];
+    const results = new Array(items.length);
+    let index = 0;
+    async function worker() {
+        while (index < items.length) {
+            const currentIdx = index++;
+            results[currentIdx] = await fn(items[currentIdx]);
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, items.length) }, worker);
+    await Promise.all(workers);
+    return results;
+}
+export async function scanSkills(dir, source = 'local') {
+    if (!exists(dir))
+        return [];
+    const skillDirs = await listDirs(dir);
+    const skills = await boundedMap(skillDirs, SCAN_CONCURRENCY, async (name) => {
+        const skillPath = assetDir('skill', dir, name);
+        const mdPath = contentFilePath(skillPath, 'skill');
+        const metadataPath = metadataFilePath(skillPath);
+        const hasMd = exists(mdPath);
+        let description;
+        let tags;
+        let category;
+        let installs;
+        let rating;
+        let updated;
+        let version;
+        let organization;
+        let originalName;
+        let slug;
+        let id;
+        if (hasMd) {
+            const frontmatter = await readFrontmatter(mdPath);
+            if (frontmatter) {
+                if (typeof frontmatter.description === 'string')
+                    description = frontmatter.description;
+                tags = stringArray(frontmatter.tags);
+                const meta = frontmatter.metadata;
+                if (meta && typeof meta === 'object' && !Array.isArray(meta)) {
+                    const metaObj = meta;
+                    if (typeof metaObj.version === 'string')
+                        version = metaObj.version;
+                    if (typeof metaObj.author === 'string')
+                        organization = metaObj.author;
+                }
+            }
+        }
+        const metadata = await readJson(metadataPath);
+        if (metadata) {
+            description = description || metadata.abstract;
+            tags = tags || stringArray(metadata.tags);
+            category = metadata.category;
+            installs = metadata.installs;
+            rating = metadata.rating;
+            updated = metadata.updated || metadata.date;
+            version = version || metadata.version;
+            organization = organization || metadata.organization;
+            originalName = metadata.originalName;
+            if (typeof metadata.slug === 'string')
+                slug = metadata.slug;
+            if (typeof metadata.id === 'string')
+                id = metadata.id;
+        }
+        return {
+            name,
+            path: skillPath,
+            description,
+            tags,
+            category,
+            installs,
+            rating,
+            updated,
+            version,
+            organization,
+            hasSkillMd: hasMd,
+            source,
+            originalName,
+            slug,
+            id,
+        };
+    });
+    return skills.filter((s) => s.hasSkillMd).sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function scanPrompts(dir, source = 'local') {
+    if (!exists(dir))
+        return [];
+    const promptDirs = await listDirs(dir);
+    const prompts = await boundedMap(promptDirs, SCAN_CONCURRENCY, async (name) => {
+        const promptPath = assetDir('prompt', dir, name);
+        if (!isCanonicalAssetDir('prompt', promptPath))
+            return null;
+        const mdPath = contentFilePath(promptPath, 'prompt');
+        let description;
+        try {
+            const content = await fs.readFile(mdPath, 'utf-8');
+            const lines = content.split('\n');
+            const firstLine = lines.find((l) => l.trim().length > 0 && !l.startsWith('#'));
+            if (firstLine)
+                description = firstLine.trim();
+        }
+        catch {
+            // Ignore
+        }
+        const meta = await readJson(metadataFilePath(promptPath));
+        let slug;
+        let id;
+        if (meta) {
+            if (typeof meta.description === 'string')
+                description = meta.description || description;
+            if (typeof meta.slug === 'string')
+                slug = meta.slug;
+            if (typeof meta.id === 'string')
+                id = meta.id;
+        }
+        return {
+            name,
+            path: promptPath,
+            description,
+            source,
+            slug,
+            id,
+        };
+    });
+    const valid = prompts.filter((p) => p !== null);
+    return valid.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function scanMcps(dir, source = 'local') {
+    if (!exists(dir))
+        return [];
+    const mcpDirs = await listDirs(dir);
+    const mcps = await boundedMap(mcpDirs, SCAN_CONCURRENCY, async (name) => {
+        const mcpPath = assetDir('mcp', dir, name);
+        if (!isCanonicalAssetDir('mcp', mcpPath))
+            return null;
+        const jsonPath = contentFilePath(mcpPath, 'mcp');
+        const data = await readJson(jsonPath);
+        const meta = await readJson(metadataFilePath(mcpPath));
+        return {
+            name: (typeof data?.name === 'string' ? data.name : name),
+            path: mcpPath,
+            command: data?.command,
+            args: data?.args,
+            env: data?.env,
+            source,
+            slug: typeof meta?.slug === 'string' ? meta.slug : undefined,
+            id: typeof meta?.id === 'string' ? meta.id : undefined,
+        };
+    });
+    const validMcps = mcps.filter((m) => m !== null);
+    return validMcps.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function scanStacks(dir, source = 'local') {
+    if (!exists(dir))
+        return [];
+    const stackFiles = await listFiles(dir, '.json');
+    const stacks = await boundedMap(stackFiles, SCAN_CONCURRENCY, async (file) => {
+        const jsonPath = path.join(dir, file);
+        const data = await readJson(jsonPath);
+        return normalizeStack(data);
+    });
+    const validStacks = stacks.filter((s) => s !== null);
+    return validStacks.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function scanAll(dir, source = 'local') {
+    const [skills, prompts, mcps, stacks] = await Promise.all([
+        scanSkills(path.join(dir, 'skills'), source),
+        scanPrompts(path.join(dir, 'prompts'), source),
+        scanMcps(path.join(dir, 'mcps'), source),
+        scanStacks(path.join(dir, 'stacks'), source),
+    ]);
+    return { skills, prompts, mcps, stacks };
+}

package/dist/types/asset-metadata.d.ts

@@ -0,0 +1,84 @@
+import { AssetType, Scope } from './index.js';
+import { INTEGRITY_ALGORITHM } from '../utils/integrity.js';
+export type AssetVisibility = 'public' | 'org' | 'private';
+export interface AssetIntegrity {
+    algorithm: typeof INTEGRITY_ALGORITHM;
+    checksum: string;
+    signature: string | null;
+}
+export interface AssetDependency {
+    type: 'asset';
+    slug: string;
+    versionRange: string;
+    optional: boolean;
+}
+export interface DeprecatedMetadata {
+    at: string;
+    reason: string;
+    replacement?: string;
+}
+export interface AssetTrustSignals {
+    verified: boolean;
+    downloads: number;
+    rating: number | null;
+    publisher: string | null;
+}
+/** Unified metadata schema for skills, prompts, and MCPs (AMAN-ASSET-SPEC-V1). */
+export interface AssetMetadata {
+    schemaVersion: 1;
+    id: string;
+    slug: string;
+    type: AssetType;
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    tags: string[];
+    scope: Scope;
+    visibility: AssetVisibility;
+    createdAt: string;
+    updatedAt: string;
+    integrity: AssetIntegrity;
+    dependencies: AssetDependency[];
+    trust: AssetTrustSignals;
+    deprecated: DeprecatedMetadata | null;
+    /** Local provenance; not required for registry publication. */
+    source?: string;
+    installedAt?: string;
+    originalName?: string;
+    originalSlug?: string;
+    /** Import provenance — tracks which tool and path an asset was imported from. */
+    provenance?: {
+        tool: string;
+        sourcePath: string;
+        importedAt: string;
+    };
+}
+export interface CreateAssetMetadataInput {
+    id?: string;
+    slug?: string;
+    description?: string;
+    tags?: string[];
+    version?: string;
+    author?: string;
+    scope?: Scope;
+    visibility?: AssetVisibility;
+    checksum?: string;
+    dependencies?: AssetDependency[];
+    trust?: Partial<AssetTrustSignals>;
+    deprecated?: DeprecatedMetadata | null;
+    source?: string;
+    installedAt?: string;
+    originalName?: string;
+    originalSlug?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    provenance?: {
+        tool: string;
+        sourcePath: string;
+        importedAt: string;
+    };
+}
+export declare function createAssetMetadata(type: AssetType, name: string, overrides?: CreateAssetMetadataInput): AssetMetadata;
+/** Merge partial legacy metadata.json into canonical shape for reads. */
+export declare function normalizeAssetMetadata(raw: Record<string, unknown>, type: AssetType, name: string): AssetMetadata;

package/dist/types/asset-metadata.js

@@ -0,0 +1,104 @@
+import { randomUUID } from 'crypto';
+import { defaultSlugForName } from '../utils/slug.js';
+import { INTEGRITY_ALGORITHM } from '../utils/integrity.js';
+export function createAssetMetadata(type, name, overrides = {}) {
+    const now = new Date().toISOString();
+    const slug = overrides.slug ?? defaultSlugForName(name);
+    const checksum = overrides.checksum ?? 'sha256:0000000000000000000000000000000000000000000000000000000000000000';
+    return {
+        schemaVersion: 1,
+        id: overrides.id ?? randomUUID(),
+        slug,
+        type,
+        name,
+        description: overrides.description ?? '',
+        version: overrides.version ?? '1.0.0',
+        author: overrides.author ?? 'unknown',
+        tags: overrides.tags ?? [],
+        scope: overrides.scope ?? 'global',
+        visibility: overrides.visibility ?? 'public',
+        createdAt: overrides.createdAt ?? now,
+        updatedAt: overrides.updatedAt ?? now,
+        integrity: {
+            algorithm: INTEGRITY_ALGORITHM,
+            checksum,
+            signature: null,
+        },
+        dependencies: overrides.dependencies ?? [],
+        trust: {
+            verified: overrides.trust?.verified ?? false,
+            downloads: overrides.trust?.downloads ?? 0,
+            rating: overrides.trust?.rating ?? null,
+            publisher: overrides.trust?.publisher ?? null,
+        },
+        deprecated: overrides.deprecated ?? null,
+        source: overrides.source,
+        installedAt: overrides.installedAt,
+        originalName: overrides.originalName ?? name,
+        originalSlug: overrides.originalSlug,
+        provenance: overrides.provenance,
+    };
+}
+/** Merge partial legacy metadata.json into canonical shape for reads. */
+export function normalizeAssetMetadata(raw, type, name) {
+    const base = createAssetMetadata(type, name, {
+        id: typeof raw.id === 'string' ? raw.id : undefined,
+        slug: typeof raw.slug === 'string' ? raw.slug : undefined,
+        description: typeof raw.description === 'string' ? raw.description : undefined,
+        tags: Array.isArray(raw.tags) ? raw.tags.filter((t) => typeof t === 'string') : undefined,
+        version: typeof raw.version === 'string' ? raw.version : undefined,
+        author: typeof raw.author === 'string' ? raw.author : undefined,
+        scope: raw.scope === 'project' || raw.scope === 'global' ? raw.scope : undefined,
+        visibility: raw.visibility === 'public' || raw.visibility === 'org' || raw.visibility === 'private'
+            ? raw.visibility
+            : undefined,
+        source: typeof raw.source === 'string' ? raw.source : undefined,
+        installedAt: typeof raw.installedAt === 'string' ? raw.installedAt : undefined,
+        originalName: typeof raw.originalName === 'string' ? raw.originalName : undefined,
+        createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : undefined,
+    });
+    const integrityRaw = raw.integrity;
+    if (integrityRaw && typeof integrityRaw.checksum === 'string') {
+        base.integrity.checksum = integrityRaw.checksum;
+    }
+    if (Array.isArray(raw.dependencies)) {
+        base.dependencies = raw.dependencies.filter((d) => typeof d === 'object' &&
+            d !== null &&
+            d.type === 'asset' &&
+            typeof d.slug === 'string');
+    }
+    const trustRaw = raw.trust;
+    if (trustRaw) {
+        if (typeof trustRaw.verified === 'boolean')
+            base.trust.verified = trustRaw.verified;
+        if (typeof trustRaw.downloads === 'number')
+            base.trust.downloads = trustRaw.downloads;
+        if (typeof trustRaw.rating === 'number' || trustRaw.rating === null)
+            base.trust.rating = trustRaw.rating;
+        if (typeof trustRaw.publisher === 'string' || trustRaw.publisher === null) {
+            base.trust.publisher = trustRaw.publisher;
+        }
+    }
+    if (raw.deprecated && typeof raw.deprecated === 'object') {
+        const dep = raw.deprecated;
+        if (typeof dep.at === 'string' && typeof dep.reason === 'string') {
+            base.deprecated = {
+                at: dep.at,
+                reason: dep.reason,
+                replacement: typeof dep.replacement === 'string' ? dep.replacement : undefined,
+            };
+        }
+    }
+    if (typeof raw.updatedAt === 'string') {
+        base.updatedAt = raw.updatedAt;
+    }
+    const provRaw = raw.provenance;
+    if (provRaw && typeof provRaw.tool === 'string' && typeof provRaw.sourcePath === 'string' && typeof provRaw.importedAt === 'string') {
+        base.provenance = {
+            tool: provRaw.tool,
+            sourcePath: provRaw.sourcePath,
+            importedAt: provRaw.importedAt,
+        };
+    }
+    return base;
+}