aman-intelligence 0.1.0

package/dist/registry/adapter.interface.d.ts

@@ -0,0 +1,16 @@
+import { RegistryDeprecateRequest, RegistryDeprecateResult, RegistryListRequest, RegistryListResult, RegistryPublishRequest, RegistryPublishResult, RegistryResolveByIdRequest, RegistryResolveRequest, RegistryResolveResult, RegistrySearchRequest, RegistrySearchResult, RegistryVerifyRequest, RegistryVerifyResult } from './types.js';
+/**
+ * Canonical registry adapter contract (Phase 3 — locked).
+ * Local filesystem, GitHub mirror, and future HTTP server MUST implement this interface.
+ */
+export interface RegistryAdapter {
+    readonly name: string;
+    available(): Promise<boolean>;
+    resolve(request: RegistryResolveRequest): Promise<RegistryResolveResult>;
+    resolveById(request: RegistryResolveByIdRequest): Promise<RegistryResolveResult>;
+    publish(request: RegistryPublishRequest): Promise<RegistryPublishResult>;
+    deprecate(request: RegistryDeprecateRequest): Promise<RegistryDeprecateResult>;
+    list(request: RegistryListRequest): Promise<RegistryListResult>;
+    search(request: RegistrySearchRequest): Promise<RegistrySearchResult>;
+    verify(request: RegistryVerifyRequest): Promise<RegistryVerifyResult>;
+}

package/dist/registry/adapter.interface.js

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

package/dist/registry/errors.d.ts

@@ -0,0 +1,5 @@
+export type RegistryErrorCode = 'INVALID_SLUG' | 'SCOPE_REQUIRED' | 'NOT_FOUND' | 'VERSION_EXISTS' | 'VERSION_NOT_FOUND' | 'CHECKSUM_MISMATCH' | 'IMMUTABLE_VIOLATION' | 'UNAUTHORIZED' | 'CIRCULAR_DEPENDENCY' | 'ADAPTER_UNAVAILABLE';
+export declare class RegistryError extends Error {
+    readonly code: RegistryErrorCode;
+    constructor(code: RegistryErrorCode, message: string);
+}

package/dist/registry/errors.js

@@ -0,0 +1,8 @@
+export class RegistryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'RegistryError';
+        this.code = code;
+    }
+}

package/dist/registry/filesystem-registry.adapter.d.ts

@@ -0,0 +1,25 @@
+import { RegistryAdapter } from './adapter.interface.js';
+import { RegistryDeprecateRequest, RegistryDeprecateResult, RegistryListRequest, RegistryListResult, RegistryPublishRequest, RegistryPublishResult, RegistryResolveByIdRequest, RegistryResolveRequest, RegistryResolveResult, RegistrySearchRequest, RegistrySearchResult, RegistrySlugIndexEntry, RegistryVerifyRequest, RegistryVerifyResult } from './types.js';
+/**
+ * Shared filesystem layout for local and GitHub-backed registry mirrors.
+ * Layout: `{root}/slug-index/{namespace}/{name}.json`, `{root}/assets/{id}/versions/{version}/`.
+ */
+export declare class FilesystemRegistryAdapter implements RegistryAdapter {
+    protected readonly registryRoot: string;
+    readonly name: string;
+    constructor(registryRoot: string, name?: string);
+    available(): Promise<boolean>;
+    resolve(request: RegistryResolveRequest): Promise<RegistryResolveResult>;
+    resolveById(request: RegistryResolveByIdRequest): Promise<RegistryResolveResult>;
+    publish(request: RegistryPublishRequest): Promise<RegistryPublishResult>;
+    deprecate(request: RegistryDeprecateRequest): Promise<RegistryDeprecateResult>;
+    list(request: RegistryListRequest): Promise<RegistryListResult>;
+    search(request: RegistrySearchRequest): Promise<RegistrySearchResult>;
+    verify(request: RegistryVerifyRequest): Promise<RegistryVerifyResult>;
+    protected resolveSlugToId(slug: string): Promise<{
+        id: string;
+        entry: RegistrySlugIndexEntry;
+    }>;
+    private findIdByRedirect;
+    private resolveRecord;
+}

package/dist/registry/filesystem-registry.adapter.js

@@ -0,0 +1,288 @@
+import path from 'path';
+import { RegistryError } from './errors.js';
+import { assetIndexPath, assetRootPath, normalizeRegistrySlug, namespaceFromSlug, slugIndexFilePath, versionContentPath, versionRecordPath, } from './slug-utils.js';
+import { copyDir, ensureDir, exists, listDirs, readJson, writeJson } from '../storage/filesystem.js';
+import { computeAssetChecksum } from '../utils/integrity.js';
+import { isCanonicalAssetDir } from '../storage/asset-layout.js';
+function compareVersions(a, b) {
+    const ap = a.split('.').map((p) => parseInt(p, 10) || 0);
+    const bp = b.split('.').map((p) => parseInt(p, 10) || 0);
+    const len = Math.max(ap.length, bp.length);
+    for (let i = 0; i < len; i++) {
+        const diff = (ap[i] ?? 0) - (bp[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * Shared filesystem layout for local and GitHub-backed registry mirrors.
+ * Layout: `{root}/slug-index/{namespace}/{name}.json`, `{root}/assets/{id}/versions/{version}/`.
+ */
+export class FilesystemRegistryAdapter {
+    registryRoot;
+    name;
+    constructor(registryRoot, name = 'local') {
+        this.registryRoot = registryRoot;
+        this.name = name;
+    }
+    async available() {
+        await ensureDir(this.registryRoot);
+        return true;
+    }
+    async resolve(request) {
+        const slug = normalizeRegistrySlug(request.scope, request.slug);
+        const { id } = await this.resolveSlugToId(slug);
+        return this.resolveRecord(id, slug, request.version);
+    }
+    async resolveById(request) {
+        const assetIndex = await readJson(assetIndexPath(this.registryRoot, request.id));
+        if (!assetIndex) {
+            throw new RegistryError('NOT_FOUND', `Asset id not found: ${request.id}`);
+        }
+        return this.resolveRecord(request.id, assetIndex.slug, request.version);
+    }
+    async publish(request) {
+        const slug = normalizeRegistrySlug(request.scope, request.slug);
+        const version = request.version.trim();
+        const contentDir = request.contentDirectory;
+        if (!exists(contentDir) || !isCanonicalAssetDir(request.type, contentDir)) {
+            throw new RegistryError('CHECKSUM_MISMATCH', `Content directory is not a canonical ${request.type} layout: ${contentDir}`);
+        }
+        const checksum = await computeAssetChecksum(request.type, contentDir);
+        if (request.metadata.integrity?.checksum && request.metadata.integrity.checksum !== checksum) {
+            throw new RegistryError('CHECKSUM_MISMATCH', `Submitted checksum does not match content (expected ${request.metadata.integrity.checksum}, got ${checksum})`);
+        }
+        const id = request.metadata.id;
+        const versionDir = versionContentPath(this.registryRoot, id, version);
+        if (exists(versionRecordPath(this.registryRoot, id, version))) {
+            throw new RegistryError('VERSION_EXISTS', `Version ${version} already published for ${slug} (${id}). Published versions are immutable.`);
+        }
+        const publishedAt = new Date().toISOString();
+        const namespace = namespaceFromSlug(slug);
+        const record = {
+            schemaVersion: 1,
+            recordType: 'asset',
+            id,
+            slug,
+            type: request.type,
+            name: request.metadata.name,
+            description: request.metadata.description,
+            version,
+            author: request.metadata.author,
+            tags: request.metadata.tags ?? [],
+            visibility: request.metadata.visibility ?? 'public',
+            publishedAt,
+            integrity: {
+                algorithm: 'sha256',
+                checksum,
+                signature: request.metadata.integrity?.signature ?? null,
+            },
+            dependencies: request.metadata.dependencies ?? [],
+            trust: {
+                verified: request.metadata.trust?.verified ?? false,
+                downloads: request.metadata.trust?.downloads ?? 0,
+                rating: request.metadata.trust?.rating ?? null,
+                publisher: request.metadata.trust?.publisher ?? `@${namespace}`,
+                deprecated: false,
+            },
+            deprecated: null,
+        };
+        await ensureDir(versionDir);
+        await copyDir(contentDir, versionDir);
+        await writeJson(versionRecordPath(this.registryRoot, id, version), record);
+        const assetIndex = {
+            schemaVersion: 1,
+            id,
+            slug,
+            aliases: [],
+            type: request.type,
+            visibility: record.visibility,
+        };
+        await writeJson(assetIndexPath(this.registryRoot, id), assetIndex);
+        const slugIndexPath = slugIndexFilePath(this.registryRoot, slug);
+        const existingSlug = await readJson(slugIndexPath);
+        const latestVersion = existingSlug && compareVersions(existingSlug.latestVersion, version) > 0
+            ? existingSlug.latestVersion
+            : version;
+        const slugEntry = {
+            schemaVersion: 1,
+            slug,
+            id,
+            latestVersion,
+            visibility: record.visibility,
+            namespace,
+            redirectFrom: existingSlug?.redirectFrom ?? [],
+        };
+        await writeJson(slugIndexPath, slugEntry);
+        return { record };
+    }
+    async deprecate(request) {
+        const slug = normalizeRegistrySlug(request.scope, request.slug);
+        const { id } = await this.resolveSlugToId(slug);
+        const recordPath = versionRecordPath(this.registryRoot, id, request.version);
+        const record = await readJson(recordPath);
+        if (!record) {
+            throw new RegistryError('VERSION_NOT_FOUND', `Version ${request.version} not found for ${slug}`);
+        }
+        const at = new Date().toISOString();
+        record.deprecated = {
+            at,
+            reason: request.reason,
+            successor: request.successor,
+        };
+        record.trust = { ...record.trust, deprecated: true };
+        await writeJson(recordPath, record);
+        return { record };
+    }
+    async list(request) {
+        const slug = normalizeRegistrySlug(request.scope, request.slug);
+        const { id } = await this.resolveSlugToId(slug);
+        const versionsDir = path.join(assetRootPath(this.registryRoot, id), 'versions');
+        if (!exists(versionsDir)) {
+            return { slug, id, versions: [] };
+        }
+        const versionNames = await listDirs(versionsDir);
+        const versions = [];
+        for (const version of versionNames) {
+            const record = await readJson(versionRecordPath(this.registryRoot, id, version));
+            if (record)
+                versions.push(record);
+        }
+        versions.sort((a, b) => compareVersions(b.version, a.version));
+        return { slug, id, versions };
+    }
+    async search(request) {
+        const slugIndexRoot = path.join(this.registryRoot, 'slug-index');
+        if (!exists(slugIndexRoot)) {
+            return { hits: [], total: 0 };
+        }
+        const query = request.query.trim().toLowerCase();
+        const hits = [];
+        const namespaces = await listDirs(slugIndexRoot);
+        for (const ns of namespaces) {
+            if (request.filters?.namespace && request.filters.namespace !== ns)
+                continue;
+            const nsDir = path.join(slugIndexRoot, ns);
+            const files = await listSlugIndexFiles(nsDir);
+            for (const file of files) {
+                const entry = await readJson(file);
+                if (!entry)
+                    continue;
+                if (request.filters?.visibility && entry.visibility !== request.filters.visibility)
+                    continue;
+                const record = await readJson(versionRecordPath(this.registryRoot, entry.id, entry.latestVersion));
+                if (!record)
+                    continue;
+                if (request.filters?.type && record.type !== request.filters.type)
+                    continue;
+                if (!request.filters?.includeDeprecated && record.deprecated)
+                    continue;
+                const haystack = [
+                    entry.slug,
+                    record.name,
+                    record.description,
+                    ...(record.tags ?? []),
+                ]
+                    .join(' ')
+                    .toLowerCase();
+                if (query && !haystack.includes(query))
+                    continue;
+                hits.push({
+                    slug: entry.slug,
+                    latestVersion: entry.latestVersion,
+                    record,
+                });
+            }
+        }
+        hits.sort((a, b) => a.slug.localeCompare(b.slug));
+        return { hits, total: hits.length };
+    }
+    async verify(request) {
+        const resolved = await this.resolve({
+            scope: request.scope,
+            slug: request.slug,
+            version: request.version,
+            context: request.context,
+        });
+        if (resolved.content.kind !== 'filesystem') {
+            throw new RegistryError('ADAPTER_UNAVAILABLE', 'Verify requires filesystem content location');
+        }
+        const actual = await computeAssetChecksum(resolved.record.type, resolved.content.path);
+        const expected = request.checksum;
+        return {
+            valid: actual === expected,
+            expected,
+            actual,
+        };
+    }
+    async resolveSlugToId(slug) {
+        const direct = await readJson(slugIndexFilePath(this.registryRoot, slug));
+        if (direct) {
+            return { id: direct.id, entry: direct };
+        }
+        const redirectId = await this.findIdByRedirect(slug);
+        if (redirectId) {
+            const assetIndex = await readJson(assetIndexPath(this.registryRoot, redirectId));
+            if (assetIndex) {
+                const canonical = await readJson(slugIndexFilePath(this.registryRoot, assetIndex.slug));
+                if (canonical) {
+                    return {
+                        id: redirectId,
+                        entry: {
+                            ...canonical,
+                            slug,
+                            redirectFrom: canonical.redirectFrom,
+                        },
+                    };
+                }
+            }
+        }
+        throw new RegistryError('NOT_FOUND', `Slug not found in registry: ${slug}`);
+    }
+    async findIdByRedirect(slug) {
+        const slugIndexRoot = path.join(this.registryRoot, 'slug-index');
+        if (!exists(slugIndexRoot))
+            return null;
+        const namespaces = await listDirs(slugIndexRoot);
+        for (const ns of namespaces) {
+            const files = await listSlugIndexFiles(path.join(slugIndexRoot, ns));
+            for (const file of files) {
+                const entry = await readJson(file);
+                if (entry?.redirectFrom?.includes(slug)) {
+                    return entry.id;
+                }
+            }
+        }
+        return null;
+    }
+    async resolveRecord(id, slug, version) {
+        const recordPath = versionRecordPath(this.registryRoot, id, version);
+        const record = await readJson(recordPath);
+        if (!record) {
+            throw new RegistryError('VERSION_NOT_FOUND', `Version ${version} not found for ${slug}`);
+        }
+        const contentPath = versionContentPath(this.registryRoot, id, version);
+        if (!exists(contentPath)) {
+            throw new RegistryError('NOT_FOUND', `Content missing for ${slug}@${version}`);
+        }
+        record.trust = {
+            ...record.trust,
+            downloads: (record.trust.downloads ?? 0) + 1,
+        };
+        await writeJson(recordPath, record);
+        return {
+            record,
+            content: { kind: 'filesystem', path: contentPath },
+        };
+    }
+}
+async function listSlugIndexFiles(dir) {
+    const { promises: fs } = await import('fs');
+    if (!exists(dir))
+        return [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isFile() && e.name.endsWith('.json'))
+        .map((e) => path.join(dir, e.name));
+}

package/dist/registry/github-registry.adapter.d.ts

@@ -0,0 +1,11 @@
+import { FilesystemRegistryAdapter } from './filesystem-registry.adapter.js';
+/**
+ * GitHub mirror using the same on-disk layout under the cloned environment repo.
+ * Path: `~/.aman/repositories/{repo}/registry/`
+ */
+export declare class GitHubRegistryAdapter extends FilesystemRegistryAdapter {
+    constructor();
+    static resolveRoot(): string;
+    available(): Promise<boolean>;
+}
+export declare const githubRegistryAdapter: GitHubRegistryAdapter;

package/dist/registry/github-registry.adapter.js

@@ -0,0 +1,32 @@
+import path from 'path';
+import { GLOBAL_DIR } from '../config/paths.js';
+import { exists } from '../storage/filesystem.js';
+import { environmentService } from '../services/environment.service.js';
+import { FilesystemRegistryAdapter } from './filesystem-registry.adapter.js';
+function repoSlugToDirName(repository) {
+    return repository.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'aman-environment';
+}
+/**
+ * GitHub mirror using the same on-disk layout under the cloned environment repo.
+ * Path: `~/.aman/repositories/{repo}/registry/`
+ */
+export class GitHubRegistryAdapter extends FilesystemRegistryAdapter {
+    constructor() {
+        super(GitHubRegistryAdapter.resolveRoot(), 'github');
+    }
+    static resolveRoot() {
+        const storage = environmentService.getStorage();
+        if (storage.type !== 'github' || !storage.repository) {
+            return path.join(GLOBAL_DIR, 'repositories', '_unconfigured', 'registry');
+        }
+        const repoDir = path.join(GLOBAL_DIR, 'repositories', repoSlugToDirName(storage.repository));
+        return path.join(repoDir, 'registry');
+    }
+    async available() {
+        const storage = environmentService.getStorage();
+        if (storage.type !== 'github' || !storage.repository)
+            return false;
+        return exists(this.registryRoot);
+    }
+}
+export const githubRegistryAdapter = new GitHubRegistryAdapter();

package/dist/registry/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './adapter.interface.js';
+export * from './slug-utils.js';
+export * from './filesystem-registry.adapter.js';
+export * from './local-registry.adapter.js';
+export * from './github-registry.adapter.js';
+export * from './registry.service.js';

package/dist/registry/index.js

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './adapter.interface.js';
+export * from './slug-utils.js';
+export * from './filesystem-registry.adapter.js';
+export * from './local-registry.adapter.js';
+export * from './github-registry.adapter.js';
+export * from './registry.service.js';

package/dist/registry/local-registry.adapter.d.ts

@@ -0,0 +1,6 @@
+import { FilesystemRegistryAdapter } from './filesystem-registry.adapter.js';
+/** V1 canonical registry at `~/.aman/registry/`. */
+export declare class LocalRegistryAdapter extends FilesystemRegistryAdapter {
+    constructor(registryRoot?: string);
+}
+export declare const localRegistryAdapter: LocalRegistryAdapter;

package/dist/registry/local-registry.adapter.js

@@ -0,0 +1,9 @@
+import { GLOBAL_REGISTRY_DIR } from '../config/paths.js';
+import { FilesystemRegistryAdapter } from './filesystem-registry.adapter.js';
+/** V1 canonical registry at `~/.aman/registry/`. */
+export class LocalRegistryAdapter extends FilesystemRegistryAdapter {
+    constructor(registryRoot = GLOBAL_REGISTRY_DIR) {
+        super(registryRoot, 'local');
+    }
+}
+export const localRegistryAdapter = new LocalRegistryAdapter();

package/dist/registry/registry.service.d.ts

@@ -0,0 +1,44 @@
+import { RegistryAdapter } from './adapter.interface.js';
+import { RegistryDeprecateRequest, RegistryDeprecateResult, RegistryListRequest, RegistryListResult, RegistryPublishRequest, RegistryPublishResult, RegistryResolveRequest, RegistrySearchRequest, RegistrySearchResult, RegistryVersionRecord } from './types.js';
+import { Scope } from '../types/index.js';
+export type RegistryBackend = 'local' | 'github';
+export interface RegistryInstallResult {
+    slug: string;
+    version: string;
+    localName: string;
+    warnings: string[];
+}
+interface DependencyNode {
+    slug: string;
+    version: string;
+}
+export declare class RegistryService {
+    private backend;
+    constructor();
+    setBackend(backend: RegistryBackend): void;
+    getBackend(): RegistryBackend;
+    getAdapter(): RegistryAdapter;
+    /** Search merges local registry hits (V1 primary). */
+    search(request: RegistrySearchRequest): Promise<RegistrySearchResult>;
+    resolve(request: RegistryResolveRequest): Promise<import("./types.js").RegistryResolveResult>;
+    publish(request: RegistryPublishRequest): Promise<RegistryPublishResult>;
+    deprecate(request: RegistryDeprecateRequest): Promise<RegistryDeprecateResult>;
+    list(request: RegistryListRequest): Promise<RegistryListResult>;
+    verifyChecksum(slug: string, version: string, checksum: string): Promise<import("./types.js").RegistryVerifyResult>;
+    /**
+     * Resolves the full dependency tree (exact versions, asset-only, no cycles).
+     */
+    resolveDependencyTree(slug: string, version: string, warnings?: string[]): Promise<DependencyNode[]>;
+    collectInstallWarnings(record: RegistryVersionRecord): string[];
+    installFromRegistry(slug: string, version: string, scope: Scope, options?: {
+        localName?: string;
+    }): Promise<RegistryInstallResult>;
+    parseInstallReference(name: string): {
+        slug: string;
+        version: string;
+    } | null;
+    newPublishId(): string;
+}
+export declare const registryService: RegistryService;
+export declare function isRegistryInstallReference(name: string): boolean;
+export {};

package/dist/registry/registry.service.js

@@ -0,0 +1,163 @@
+import { randomUUID } from 'crypto';
+import { RegistryError } from './errors.js';
+import { localRegistryAdapter } from './local-registry.adapter.js';
+import { githubRegistryAdapter } from './github-registry.adapter.js';
+import { parseRegistryReference } from './slug-utils.js';
+import { assetService } from '../services/asset.service.js';
+import { localNameFromSlug } from '../utils/slug.js';
+function readRegistryBackendFromEnv() {
+    const value = process.env.AMAN_REGISTRY_BACKEND?.trim().toLowerCase();
+    return value === 'github' ? 'github' : 'local';
+}
+export class RegistryService {
+    backend;
+    constructor() {
+        this.backend = readRegistryBackendFromEnv();
+    }
+    setBackend(backend) {
+        this.backend = backend;
+    }
+    getBackend() {
+        return this.backend;
+    }
+    getAdapter() {
+        return this.backend === 'github' ? githubRegistryAdapter : localRegistryAdapter;
+    }
+    /** Search merges local registry hits (V1 primary). */
+    async search(request) {
+        const adapter = localRegistryAdapter;
+        if (!(await adapter.available())) {
+            return { hits: [], total: 0 };
+        }
+        return adapter.search(request);
+    }
+    async resolve(request) {
+        return this.getAdapter().resolve(request);
+    }
+    async publish(request) {
+        return this.getAdapter().publish(request);
+    }
+    async deprecate(request) {
+        return this.getAdapter().deprecate(request);
+    }
+    async list(request) {
+        return this.getAdapter().list(request);
+    }
+    async verifyChecksum(slug, version, checksum) {
+        const verify = await this.getAdapter().verify({ slug, version, checksum });
+        if (!verify.valid) {
+            throw new RegistryError('CHECKSUM_MISMATCH', `Checksum mismatch for ${slug}@${version}: expected ${verify.expected}, got ${verify.actual}`);
+        }
+        return verify;
+    }
+    /**
+     * Resolves the full dependency tree (exact versions, asset-only, no cycles).
+     */
+    async resolveDependencyTree(slug, version, warnings = []) {
+        const ordered = [];
+        const visiting = new Set();
+        const visited = new Set();
+        const walk = async (nodeSlug, nodeVersion) => {
+            const key = `${nodeSlug}@${nodeVersion}`;
+            if (visited.has(key))
+                return;
+            if (visiting.has(key)) {
+                throw new RegistryError('CIRCULAR_DEPENDENCY', `Circular dependency detected at ${key}`);
+            }
+            visiting.add(key);
+            const resolved = await this.getAdapter().resolve({ slug: nodeSlug, version: nodeVersion });
+            if (resolved.record.deprecated) {
+                const d = resolved.record.deprecated;
+                warnings.push(`Dependency ${nodeSlug}@${nodeVersion} is deprecated: ${d.reason}${d.successor ? ` (successor: ${d.successor})` : ''}`);
+            }
+            for (const dep of resolved.record.dependencies) {
+                try {
+                    await this.getAdapter().resolve({ slug: dep.slug, version: dep.version });
+                }
+                catch (err) {
+                    if (err instanceof RegistryError && err.code === 'NOT_FOUND') {
+                        warnings.push(`Missing dependency ${dep.slug}@${dep.version} required by ${nodeSlug}`);
+                        continue;
+                    }
+                    throw err;
+                }
+                await walk(dep.slug, dep.version);
+            }
+            visiting.delete(key);
+            visited.add(key);
+            ordered.push({ slug: nodeSlug, version: nodeVersion });
+        };
+        await walk(slug, version);
+        return ordered;
+    }
+    collectInstallWarnings(record) {
+        const warnings = [];
+        if (record.deprecated) {
+            const d = record.deprecated;
+            warnings.push(`WARNING: ${record.slug}@${record.version} is deprecated — ${d.reason}${d.successor ? `. Successor: ${d.successor}` : ''}`);
+        }
+        if (!record.trust.verified) {
+            warnings.push(`Note: ${record.slug}@${record.version} is not verified by a human reviewer.`);
+        }
+        return warnings;
+    }
+    async installFromRegistry(slug, version, scope, options) {
+        const warnings = [];
+        const tree = await this.resolveDependencyTree(slug, version, warnings);
+        for (const node of tree) {
+            const resolved = await this.getAdapter().resolve({ slug: node.slug, version: node.version });
+            await this.verifyChecksum(node.slug, node.version, resolved.record.integrity.checksum);
+            warnings.push(...this.collectInstallWarnings(resolved.record));
+            if (resolved.content.kind !== 'filesystem') {
+                throw new RegistryError('ADAPTER_UNAVAILABLE', 'Install requires filesystem content');
+            }
+            const localName = options?.localName ?? localNameFromSlug(node.slug);
+            const deprecated = resolved.record.deprecated
+                ? {
+                    at: resolved.record.deprecated.at,
+                    reason: resolved.record.deprecated.reason,
+                    replacement: resolved.record.deprecated.successor,
+                }
+                : null;
+            await assetService.install(localName, resolved.record.type, scope, resolved.content.path, `registry:${node.slug}@${node.version}`, {
+                id: resolved.record.id,
+                slug: resolved.record.slug,
+                version: resolved.record.version,
+                description: resolved.record.description,
+                tags: resolved.record.tags,
+                author: resolved.record.author,
+                visibility: resolved.record.visibility,
+                dependencies: resolved.record.dependencies.map((d) => ({
+                    type: 'asset',
+                    slug: d.slug,
+                    versionRange: d.version,
+                    optional: false,
+                })),
+                trust: {
+                    verified: resolved.record.trust.verified,
+                    downloads: resolved.record.trust.downloads,
+                    rating: resolved.record.trust.rating,
+                    publisher: resolved.record.trust.publisher,
+                },
+                deprecated,
+            });
+        }
+        const root = tree[tree.length - 1] ?? { slug, version };
+        return {
+            slug: root.slug,
+            version: root.version,
+            localName: options?.localName ?? localNameFromSlug(root.slug),
+            warnings,
+        };
+    }
+    parseInstallReference(name) {
+        return parseRegistryReference(name);
+    }
+    newPublishId() {
+        return randomUUID();
+    }
+}
+export const registryService = new RegistryService();
+export function isRegistryInstallReference(name) {
+    return parseRegistryReference(name) !== null;
+}

package/dist/registry/slug-utils.d.ts

@@ -0,0 +1,12 @@
+import { RegistryNamespace } from './types.js';
+export declare function parseRegistryReference(input: string): {
+    slug: string;
+    version: string;
+} | null;
+export declare function namespaceFromSlug(slug: string): RegistryNamespace;
+export declare function normalizeRegistrySlug(scope: RegistryNamespace | undefined, slug: string): string;
+export declare function slugIndexFilePath(registryRoot: string, slug: string): string;
+export declare function assetRootPath(registryRoot: string, id: string): string;
+export declare function versionRecordPath(registryRoot: string, id: string, version: string): string;
+export declare function versionContentPath(registryRoot: string, id: string, version: string): string;
+export declare function assetIndexPath(registryRoot: string, id: string): string;