aman-intelligence 0.1.0

package/dist/registry/slug-utils.js

@@ -0,0 +1,51 @@
+import path from 'path';
+import { RegistryError } from './errors.js';
+import { isValidSlug } from '../utils/slug.js';
+export function parseRegistryReference(input) {
+    const trimmed = input.trim();
+    const match = trimmed.match(/^(@[a-z0-9][a-z0-9-]*(?:~private)?\/[a-z0-9]+(?:-[a-z0-9]+)*)@(\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)$/);
+    if (!match)
+        return null;
+    return { slug: match[1], version: match[2] };
+}
+export function namespaceFromSlug(slug) {
+    const slash = slug.indexOf('/');
+    if (slash < 2 || slug[0] !== '@') {
+        throw new RegistryError('INVALID_SLUG', `Invalid slug: ${slug}`);
+    }
+    return slug.slice(1, slash);
+}
+export function normalizeRegistrySlug(scope, slug) {
+    if (slug.startsWith('@')) {
+        if (!isValidSlug(slug)) {
+            throw new RegistryError('INVALID_SLUG', `Invalid slug format: ${slug}`);
+        }
+        return slug;
+    }
+    if (!scope) {
+        throw new RegistryError('SCOPE_REQUIRED', `Scope required to resolve unqualified slug "${slug}"`);
+    }
+    const ns = scope.startsWith('@') ? scope.slice(1) : scope;
+    const full = `@${ns}/${slug}`;
+    if (!isValidSlug(full)) {
+        throw new RegistryError('INVALID_SLUG', `Invalid slug after scope qualification: ${full}`);
+    }
+    return full;
+}
+export function slugIndexFilePath(registryRoot, slug) {
+    const ns = namespaceFromSlug(slug);
+    const name = slug.slice(slug.indexOf('/') + 1);
+    return path.join(registryRoot, 'slug-index', ns, `${name}.json`);
+}
+export function assetRootPath(registryRoot, id) {
+    return path.join(registryRoot, 'assets', id);
+}
+export function versionRecordPath(registryRoot, id, version) {
+    return path.join(assetRootPath(registryRoot, id), 'versions', version, 'record.json');
+}
+export function versionContentPath(registryRoot, id, version) {
+    return path.join(assetRootPath(registryRoot, id), 'versions', version, 'content');
+}
+export function assetIndexPath(registryRoot, id) {
+    return path.join(assetRootPath(registryRoot, id), 'asset.json');
+}

package/dist/registry/types.d.ts

@@ -0,0 +1,160 @@
+import { AssetType } from '../types/index.js';
+import { AssetVisibility } from '../types/asset-metadata.js';
+/** Publisher namespace (without leading `@`), e.g. `aman`, `acme~private`. */
+export type RegistryNamespace = string;
+/**
+ * Access context for scoped resolution (private org assets in future).
+ * V1 local adapter ignores `authToken` and treats all records as readable.
+ */
+export interface RegistryAccessContext {
+    authToken?: string;
+}
+export interface RegistryIntegrity {
+    algorithm: 'sha256';
+    checksum: string;
+    signature: string | null;
+}
+/** Exact-version dependency reference (V1 — no ranges). */
+export interface RegistryDependencyRef {
+    slug: string;
+    version: string;
+}
+export interface RegistryDeprecation {
+    at: string;
+    reason: string;
+    successor?: string;
+}
+export interface RegistryTrustSignals {
+    verified: boolean;
+    downloads: number;
+    rating: number | null;
+    publisher: string;
+    deprecated: boolean;
+}
+export interface RegistryVersionRecord {
+    schemaVersion: 1;
+    recordType: 'asset';
+    id: string;
+    slug: string;
+    type: AssetType;
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    tags: string[];
+    visibility: AssetVisibility;
+    publishedAt: string;
+    integrity: RegistryIntegrity;
+    dependencies: RegistryDependencyRef[];
+    trust: RegistryTrustSignals;
+    deprecated: RegistryDeprecation | null;
+}
+export interface RegistrySlugIndexEntry {
+    schemaVersion: 1;
+    slug: string;
+    id: string;
+    latestVersion: string;
+    visibility: AssetVisibility;
+    namespace: RegistryNamespace;
+    redirectFrom: string[];
+}
+export interface RegistryAssetIndex {
+    schemaVersion: 1;
+    id: string;
+    slug: string;
+    aliases: string[];
+    type: AssetType;
+    visibility: AssetVisibility;
+}
+export type RegistryContentLocation = {
+    kind: 'filesystem';
+    path: string;
+} | {
+    kind: 'http';
+    url: string;
+};
+export interface RegistryResolveRequest {
+    /** Disambiguates abbreviated slugs (`react-best-practices` + scope `aman`). */
+    scope?: RegistryNamespace;
+    slug: string;
+    version: string;
+    context?: RegistryAccessContext;
+}
+export interface RegistryResolveByIdRequest {
+    id: string;
+    version: string;
+    context?: RegistryAccessContext;
+}
+export interface RegistryResolveResult {
+    record: RegistryVersionRecord;
+    content: RegistryContentLocation;
+}
+export interface RegistryPublishRequest {
+    scope?: RegistryNamespace;
+    slug: string;
+    version: string;
+    type: AssetType;
+    metadata: Omit<RegistryVersionRecord, 'schemaVersion' | 'recordType' | 'publishedAt' | 'integrity' | 'trust' | 'deprecated'> & {
+        integrity?: Partial<RegistryIntegrity>;
+        trust?: Partial<RegistryTrustSignals>;
+    };
+    /** Canonical asset directory on disk (SKILL.md / PROMPT.md / mcp.json layout). */
+    contentDirectory: string;
+    context?: RegistryAccessContext;
+}
+export interface RegistryPublishResult {
+    record: RegistryVersionRecord;
+}
+export interface RegistryDeprecateRequest {
+    scope?: RegistryNamespace;
+    slug: string;
+    version: string;
+    reason: string;
+    successor?: string;
+    context?: RegistryAccessContext;
+}
+export interface RegistryDeprecateResult {
+    record: RegistryVersionRecord;
+}
+export interface RegistryListRequest {
+    scope?: RegistryNamespace;
+    slug: string;
+    context?: RegistryAccessContext;
+}
+export interface RegistryListResult {
+    slug: string;
+    id: string;
+    versions: RegistryVersionRecord[];
+}
+export interface RegistrySearchFilters {
+    type?: AssetType;
+    namespace?: RegistryNamespace;
+    visibility?: AssetVisibility;
+    includeDeprecated?: boolean;
+}
+export interface RegistrySearchRequest {
+    query: string;
+    filters?: RegistrySearchFilters;
+    context?: RegistryAccessContext;
+}
+export interface RegistrySearchHit {
+    record: RegistryVersionRecord;
+    slug: string;
+    latestVersion: string;
+}
+export interface RegistrySearchResult {
+    hits: RegistrySearchHit[];
+    total: number;
+}
+export interface RegistryVerifyRequest {
+    scope?: RegistryNamespace;
+    slug: string;
+    version: string;
+    checksum: string;
+    context?: RegistryAccessContext;
+}
+export interface RegistryVerifyResult {
+    valid: boolean;
+    expected: string;
+    actual: string;
+}

package/dist/registry/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,12 @@
+import { AssetType, Scope, AssetMetadata, AssetListItem } from '../types/index.js';
+export declare class AssetService {
+    private scopeRoot;
+    private getTypeRoot;
+    private getBundledDir;
+    private ensureCanonicalLayout;
+    install(name: string, type: AssetType, scope: Scope, sourcePath?: string, source?: string, metadataOverride?: Partial<AssetMetadata>): Promise<void>;
+    remove(name: string, type: AssetType, scope: Scope): Promise<boolean>;
+    private ensureBundledCanonical;
+    list(type: AssetType, scope?: Scope): Promise<AssetListItem[]>;
+}
+export declare const assetService: AssetService;

package/dist/services/asset.service.js

@@ -0,0 +1,142 @@
+import path from 'path';
+import { LOCAL_DIR, BUNDLED_SKILLS, BUNDLED_PROMPTS, BUNDLED_MCPS } from '../config/paths.js';
+import { removeDir, exists, readJson, writeJson } from '../storage/filesystem.js';
+import { scanAssetsByType } from '../storage/scan-by-type.js';
+import { lockService } from './lock.service.js';
+import { createAssetMetadata, } from '../types/index.js';
+import { environmentService } from './environment.service.js';
+import { computeAssetChecksum } from '../utils/integrity.js';
+import { defaultSlugForName } from '../utils/slug.js';
+import { parseLockSource } from '../utils/lock-migrate.js';
+import { assetDir, materializeAssetDirectory, metadataFilePath, migrateScopeLayout, migrateTypeRootLayout, resolveBundledSource, contentFilePath, } from '../storage/asset-layout.js';
+import { ensureMcpLocalGitignore, mcpRequiresLocalConfig, scaffoldMcpLocalConfig, } from '../utils/mcp-local.js';
+export class AssetService {
+    scopeRoot(scope) {
+        return scope === 'global' ? environmentService.getActiveEnvironmentDir() : LOCAL_DIR;
+    }
+    getTypeRoot(type, scope) {
+        const root = this.scopeRoot(scope);
+        if (type === 'skill')
+            return path.join(root, 'skills');
+        if (type === 'prompt')
+            return path.join(root, 'prompts');
+        return path.join(root, 'mcps');
+    }
+    getBundledDir(type) {
+        if (type === 'skill')
+            return BUNDLED_SKILLS;
+        if (type === 'prompt')
+            return BUNDLED_PROMPTS;
+        return BUNDLED_MCPS;
+    }
+    async ensureCanonicalLayout(scope) {
+        await migrateScopeLayout(this.scopeRoot(scope));
+    }
+    async install(name, type, scope, sourcePath, source = 'local', metadataOverride) {
+        if (scope === 'global') {
+            await environmentService.ensureActiveEnvironment();
+        }
+        else {
+            await environmentService.ensureProjectEnvironment();
+        }
+        await this.ensureCanonicalLayout(scope);
+        const typeRoot = this.getTypeRoot(type, scope);
+        const destDir = assetDir(type, typeRoot, name);
+        let src = sourcePath;
+        if (!src) {
+            src = resolveBundledSource(type, this.getBundledDir(type), name);
+        }
+        if (!exists(src)) {
+            throw new Error(`Asset not found: ${src}`);
+        }
+        if (exists(destDir)) {
+            await removeDir(destDir);
+        }
+        await materializeAssetDirectory(type, src, destDir);
+        const installedAt = new Date().toISOString();
+        const slug = metadataOverride?.slug ?? defaultSlugForName(metadataOverride?.originalName ?? name);
+        const checksum = await computeAssetChecksum(type, destDir);
+        let requiresLocalConfig = false;
+        if (type === 'mcp') {
+            await ensureMcpLocalGitignore(this.scopeRoot(scope));
+            const mcpData = await readJson(contentFilePath(destDir, 'mcp'));
+            requiresLocalConfig = mcpData ? mcpRequiresLocalConfig(mcpData) : false;
+            if (requiresLocalConfig) {
+                await scaffoldMcpLocalConfig(destDir);
+            }
+        }
+        const metadataContent = createAssetMetadata(type, name, {
+            slug,
+            source,
+            scope,
+            installedAt,
+            originalName: metadataOverride?.originalName ?? name,
+            description: metadataOverride?.description,
+            tags: metadataOverride?.tags,
+            version: metadataOverride?.version ?? '1.0.0',
+            author: metadataOverride?.author,
+            id: metadataOverride?.id,
+            visibility: metadataOverride?.visibility,
+            dependencies: metadataOverride?.dependencies,
+            trust: metadataOverride?.trust,
+            deprecated: metadataOverride?.deprecated,
+            checksum,
+            updatedAt: installedAt,
+        });
+        await writeJson(metadataFilePath(destDir), metadataContent);
+        await lockService.addEntry(scope, {
+            id: metadataContent.id,
+            slug: metadataContent.slug,
+            type,
+            localName: name,
+            version: metadataContent.version,
+            originalName: metadataContent.originalName,
+            integrity: {
+                algorithm: 'sha256',
+                checksum: metadataContent.integrity.checksum,
+            },
+            source: parseLockSource(source),
+            scope,
+            installedAt,
+            dependencies: [],
+            requiresLocalConfig,
+        });
+    }
+    async remove(name, type, scope) {
+        await this.ensureCanonicalLayout(scope);
+        const typeRoot = this.getTypeRoot(type, scope);
+        const destDir = assetDir(type, typeRoot, name);
+        if (!exists(destDir)) {
+            return false;
+        }
+        await removeDir(destDir);
+        await lockService.removeEntry(scope, name, type);
+        return true;
+    }
+    async ensureBundledCanonical(type) {
+        if (type === 'skill')
+            return;
+        await migrateTypeRootLayout(type, this.getBundledDir(type));
+    }
+    async list(type, scope) {
+        const bundledDir = this.getBundledDir(type);
+        await this.ensureBundledCanonical(type);
+        const bundled = await scanAssetsByType(type, bundledDir, 'bundled');
+        let installed = [];
+        if (scope) {
+            await this.ensureCanonicalLayout(scope);
+            installed = await scanAssetsByType(type, this.getTypeRoot(type, scope), 'installed');
+        }
+        else {
+            await this.ensureCanonicalLayout('global');
+            installed = await scanAssetsByType(type, this.getTypeRoot(type, 'global'), 'installed');
+        }
+        const mergedMap = new Map();
+        for (const item of bundled)
+            mergedMap.set(item.name, item);
+        for (const item of installed)
+            mergedMap.set(item.name, item);
+        return Array.from(mergedMap.values()).sort((a, b) => a.name.localeCompare(b.name));
+    }
+}
+export const assetService = new AssetService();

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

@@ -0,0 +1,8 @@
+export declare class BackupService {
+    save(name?: string, onProgress?: (progress: number) => void): Promise<string>;
+    list(): Promise<string[]>;
+    restore(id: string, onProgress?: (progress: number) => void): Promise<void>;
+    private verifyRestore;
+    delete(id: string): Promise<void>;
+}
+export declare const backupService: BackupService;

package/dist/services/backup.service.js

@@ -0,0 +1,169 @@
+import path from 'path';
+import { copyDir, removeDir, exists, ensureDir, listDirs } from '../storage/filesystem.js';
+import { promises as fs } from 'fs';
+import { environmentService } from './environment.service.js';
+export class BackupService {
+    async save(name, onProgress) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const backupName = name ? `${timestamp}-${name}` : timestamp;
+        const baseDir = environmentService.getActiveEnvironmentDir();
+        const backupDir = path.join(baseDir, 'backups', backupName);
+        await ensureDir(backupDir);
+        onProgress?.(20);
+        // Copy relevant directories
+        const dirsToBackup = ['skills', 'prompts', 'mcps', 'stacks', 'config'];
+        for (const dir of dirsToBackup) {
+            const src = path.join(baseDir, dir);
+            if (exists(src)) {
+                await copyDir(src, path.join(backupDir, dir));
+            }
+        }
+        onProgress?.(80);
+        // Also backup aman.lock if exists
+        const lockfile = path.join(baseDir, 'aman.lock');
+        if (exists(lockfile)) {
+            await fs.copyFile(lockfile, path.join(backupDir, 'aman.lock'));
+        }
+        onProgress?.(100);
+        return backupName;
+    }
+    async list() {
+        return await listDirs(path.join(environmentService.getActiveEnvironmentDir(), 'backups'));
+    }
+    async restore(id, onProgress) {
+        const baseDir = environmentService.getActiveEnvironmentDir();
+        const backupDir = path.join(baseDir, 'backups', id);
+        if (!exists(backupDir)) {
+            throw new Error(`Backup not found: ${id}`);
+        }
+        const manifestProbe = path.join(backupDir, 'skills');
+        const hasContent = exists(manifestProbe) ||
+            exists(path.join(backupDir, 'prompts')) ||
+            exists(path.join(backupDir, 'mcps')) ||
+            exists(path.join(backupDir, 'aman.lock'));
+        if (!hasContent) {
+            throw new Error(`Backup appears corrupted or empty: ${id}`);
+        }
+        const dirsToRestore = ['skills', 'prompts', 'mcps', 'stacks', 'config'];
+        const timestamp = Date.now();
+        const rollbackSuffix = `.rollback-${timestamp}`;
+        const backedUpDirs = [];
+        let lockfileRollbackExists = false;
+        const lockfilePath = path.join(baseDir, 'aman.lock');
+        try {
+            // 1. Staging: Move current active environment directories to rollback paths
+            for (const dir of dirsToRestore) {
+                const dest = path.join(baseDir, dir);
+                if (exists(dest)) {
+                    const rollbackPath = `${dest}${rollbackSuffix}`;
+                    await fs.rename(dest, rollbackPath);
+                    backedUpDirs.push(dir);
+                }
+            }
+            // Rollback lockfile
+            const lockfileRollback = `${lockfilePath}${rollbackSuffix}`;
+            if (exists(lockfilePath)) {
+                await fs.rename(lockfilePath, lockfileRollback);
+                lockfileRollbackExists = true;
+            }
+            onProgress?.(30);
+            // 2. Restore new content
+            for (const dir of dirsToRestore) {
+                const src = path.join(backupDir, dir);
+                const dest = path.join(baseDir, dir);
+                if (exists(src)) {
+                    await copyDir(src, dest);
+                }
+            }
+            const lockfileSrc = path.join(backupDir, 'aman.lock');
+            if (exists(lockfileSrc)) {
+                await fs.copyFile(lockfileSrc, lockfilePath);
+            }
+            onProgress?.(70);
+            // 3. Verification: Explicitly verify that restore succeeded
+            await this.verifyRestore(baseDir, backupDir);
+            onProgress?.(90);
+            // 4. Cleanup: Delete rollback directories on success
+            for (const dir of backedUpDirs) {
+                const rollbackPath = `${path.join(baseDir, dir)}${rollbackSuffix}`;
+                await removeDir(rollbackPath).catch(() => { });
+            }
+            if (lockfileRollbackExists) {
+                await fs.unlink(`${lockfilePath}${rollbackSuffix}`).catch(() => { });
+            }
+            onProgress?.(100);
+        }
+        catch (err) {
+            // 5. Transaction-like rollback on failure!
+            // Wipe corrupt/incomplete folders
+            for (const dir of dirsToRestore) {
+                const dest = path.join(baseDir, dir);
+                if (exists(dest)) {
+                    await removeDir(dest).catch(() => { });
+                }
+            }
+            if (exists(lockfilePath)) {
+                await fs.unlink(lockfilePath).catch(() => { });
+            }
+            // Move rollback dirs back into place
+            for (const dir of backedUpDirs) {
+                const dest = path.join(baseDir, dir);
+                const rollbackPath = `${dest}${rollbackSuffix}`;
+                if (exists(rollbackPath)) {
+                    await fs.rename(rollbackPath, dest).catch(() => { });
+                }
+            }
+            if (lockfileRollbackExists) {
+                const lockfileRollback = `${lockfilePath}${rollbackSuffix}`;
+                await fs.rename(lockfileRollback, lockfilePath).catch(() => { });
+            }
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new Error(`Restore failed. Environment successfully rolled back. Detail: ${detail}`);
+        }
+    }
+    async verifyRestore(baseDir, backupDir) {
+        const { readJson } = await import('../storage/filesystem.js');
+        // 1. Verify lockfile when the backup included one
+        const lockPath = path.join(baseDir, 'aman.lock');
+        const backupLockPath = path.join(backupDir, 'aman.lock');
+        if (exists(backupLockPath)) {
+            const lockfileContent = await readJson(lockPath);
+            if (!lockfileContent) {
+                throw new Error('Lockfile (aman.lock) is corrupted/unreadable after restore');
+            }
+        }
+        // 2. Read the backup directories and verify existence of expected assets
+        const dirsToRestore = ['skills', 'prompts', 'mcps', 'stacks', 'config'];
+        for (const dir of dirsToRestore) {
+            const srcDir = path.join(backupDir, dir);
+            const destDir = path.join(baseDir, dir);
+            if (exists(srcDir)) {
+                if (!exists(destDir)) {
+                    throw new Error(`Directory ${dir} was not created during restore`);
+                }
+                const fsPromises = (await import('fs')).promises;
+                const srcFiles = await fsPromises.readdir(srcDir);
+                const destFiles = await fsPromises.readdir(destDir);
+                for (const file of srcFiles) {
+                    const destFilePath = path.join(destDir, file);
+                    if (!exists(destFilePath)) {
+                        throw new Error(`Expected asset file/folder ${file} was not restored under ${dir}`);
+                    }
+                    if (dir === 'skills' || dir === 'prompts' || dir === 'mcps') {
+                        const metaPath = path.join(destFilePath, 'metadata.json');
+                        if (!exists(metaPath)) {
+                            throw new Error(`metadata.json is missing for ${dir}/${file}`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    async delete(id) {
+        const backupDir = path.join(environmentService.getActiveEnvironmentDir(), 'backups', id);
+        if (exists(backupDir)) {
+            await removeDir(backupDir);
+        }
+    }
+}
+export const backupService = new BackupService();

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

@@ -0,0 +1,31 @@
+import { AssetType } from '../types/index.js';
+export interface ClassificationResult {
+    file: string;
+    type: AssetType | 'stack' | 'unknown';
+    confidence: number;
+    reason: string;
+}
+export declare class ClassificationService {
+    private memory;
+    private loadMemory;
+    private saveMemory;
+    remember(relativePath: string, type: AssetType | 'stack'): Promise<void>;
+    rememberBatch(decisions: Record<string, AssetType | 'stack'>): Promise<void>;
+    getRemembered(relativePath: string): Promise<AssetType | 'stack' | undefined>;
+    private walk;
+    private classifyFile;
+    private classifyJson;
+    private classifyMarkdown;
+    classifyDirectory(rootDir: string): Promise<ClassificationResult[]>;
+    summarize(results: ClassificationResult[]): {
+        skills: number;
+        prompts: number;
+        mcps: number;
+        stacks: number;
+        unknown: number;
+    };
+    /** Auto-import threshold: 50%+ per import confidence bands; below 50 is manual review only. */
+    highConfidence(results: ClassificationResult[], threshold?: number): ClassificationResult[];
+    lowConfidence(results: ClassificationResult[], threshold?: number): ClassificationResult[];
+}
+export declare const classificationService: ClassificationService;