@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/research/services/quality.js

@@ -0,0 +1,370 @@
+/**
+ * Quality service for assessing research source quality
+ *
+ * @module research/services/quality
+ */
+/**
+ * Quality service for assessing and reporting on source quality
+ */
+export class QualityService {
+    constructor(_config = {}) {
+        // Config values will be used when threshold checking is implemented
+    }
+    /**
+     * Assess GRADE evidence quality level
+     */
+    assessGRADE(source) {
+        const paper = source.paper;
+        // Start with baseline based on publication type
+        let level = this.getBaselineGRADE(paper.type);
+        // Adjust based on other factors
+        if (paper.type === 'preprint' && !paper.doi) {
+            level = this.downgrade(level); // Not peer-reviewed and no DOI
+        }
+        if (paper.citationCount && paper.citationCount > 100) {
+            level = this.upgrade(level); // High citation count indicates quality
+        }
+        if (!paper.abstract) {
+            level = this.downgrade(level); // Missing metadata
+        }
+        return level;
+    }
+    /**
+     * Validate FAIR compliance
+     */
+    validateFAIR(source) {
+        const findable = this.assessFindable(source);
+        const accessible = this.assessAccessible(source);
+        const interoperable = this.assessInteroperable(source);
+        const reusable = this.assessReusable(source);
+        const overall = (findable.score +
+            accessible.score +
+            interoperable.score +
+            reusable.score) / 4;
+        const notes = [];
+        if (overall >= 0.9) {
+            notes.push('Excellent FAIR compliance');
+        }
+        else if (overall >= 0.7) {
+            notes.push('Good FAIR compliance with room for improvement');
+        }
+        else if (overall >= 0.5) {
+            notes.push('Moderate FAIR compliance - consider enhancements');
+        }
+        else {
+            notes.push('Low FAIR compliance - significant improvements needed');
+        }
+        return {
+            overall,
+            findable,
+            accessible,
+            interoperable,
+            reusable,
+            notes,
+        };
+    }
+    /**
+     * Calculate multi-dimensional quality score
+     */
+    calculateQualityScore(source) {
+        const gradeLevel = this.assessGRADE(source);
+        const fairScore = source.fairScore || this.validateFAIR(source);
+        const dimensions = {
+            methodological: this.assessMethodological(source),
+            evidential: this.assessEvidential(source),
+            transparency: this.assessTransparency(source),
+            reproducibility: this.assessReproducibility(source),
+            fairCompliance: fairScore.overall,
+        };
+        const overall = (dimensions.methodological +
+            dimensions.evidential +
+            dimensions.transparency +
+            dimensions.reproducibility +
+            dimensions.fairCompliance) / 5;
+        const notes = [];
+        if (overall >= 0.8) {
+            notes.push('High-quality source suitable for critical decisions');
+        }
+        else if (overall >= 0.6) {
+            notes.push('Moderate-quality source suitable for general reference');
+        }
+        else {
+            notes.push('Lower-quality source - use with caution');
+        }
+        return {
+            overall,
+            dimensions,
+            gradeLevel,
+            sourceType: source.paper.type || 'other',
+            notes,
+        };
+    }
+    /**
+     * Generate aggregate quality report
+     */
+    generateReport(sources) {
+        const gradeDistribution = {
+            HIGH: 0,
+            MODERATE: 0,
+            LOW: 0,
+            VERY_LOW: 0,
+        };
+        const sourceTypeDistribution = {};
+        let totalMethodological = 0;
+        let totalEvidential = 0;
+        let totalTransparency = 0;
+        let totalReproducibility = 0;
+        let totalFAIR = 0;
+        let totalOverall = 0;
+        for (const source of sources) {
+            const grade = this.assessGRADE(source);
+            gradeDistribution[grade]++;
+            const type = source.paper.type || 'other';
+            sourceTypeDistribution[type] = (sourceTypeDistribution[type] || 0) + 1;
+            const quality = this.calculateQualityScore(source);
+            totalMethodological += quality.dimensions.methodological;
+            totalEvidential += quality.dimensions.evidential;
+            totalTransparency += quality.dimensions.transparency;
+            totalReproducibility += quality.dimensions.reproducibility;
+            totalFAIR += quality.dimensions.fairCompliance;
+            totalOverall += quality.overall;
+        }
+        const count = sources.length;
+        const averageScores = {
+            overall: totalOverall / count,
+            methodological: totalMethodological / count,
+            evidential: totalEvidential / count,
+            transparency: totalTransparency / count,
+            reproducibility: totalReproducibility / count,
+            fairCompliance: totalFAIR / count,
+        };
+        const summary = this.buildSummary(count, averageScores.overall, gradeDistribution);
+        const recommendations = this.buildRecommendations(averageScores, gradeDistribution);
+        return {
+            generatedAt: new Date().toISOString(),
+            totalSources: count,
+            gradeDistribution,
+            sourceTypeDistribution,
+            averageScores,
+            summary,
+            recommendations,
+        };
+    }
+    /**
+     * Get baseline GRADE level for publication type
+     */
+    getBaselineGRADE(type) {
+        if (type === 'journal')
+            return 'HIGH';
+        if (type === 'conference')
+            return 'HIGH';
+        if (type === 'preprint')
+            return 'MODERATE';
+        if (type === 'thesis')
+            return 'MODERATE';
+        return 'LOW';
+    }
+    /**
+     * Upgrade GRADE level
+     */
+    upgrade(level) {
+        const levels = ['HIGH', 'MODERATE', 'LOW', 'VERY_LOW'];
+        const index = levels.indexOf(level);
+        return index > 0 ? levels[index - 1] : level;
+    }
+    /**
+     * Downgrade GRADE level
+     */
+    downgrade(level) {
+        const levels = ['HIGH', 'MODERATE', 'LOW', 'VERY_LOW'];
+        const index = levels.indexOf(level);
+        return index < levels.length - 1 ? levels[index + 1] : level;
+    }
+    /**
+     * Assess Findable dimension
+     */
+    assessFindable(source) {
+        const criteria = [
+            {
+                id: 'F1',
+                description: 'Assigned globally unique identifier',
+                met: !!source.refId,
+            },
+            {
+                id: 'F2',
+                description: 'Rich metadata',
+                met: !!source.paper.abstract && source.paper.authors.length > 0,
+            },
+            {
+                id: 'F3',
+                description: 'Metadata includes identifier',
+                met: !!(source.paper.doi || source.paper.arxivId),
+            },
+            {
+                id: 'F4',
+                description: 'Indexed in searchable resource',
+                met: true,
+            },
+        ];
+        const score = criteria.filter((c) => c.met).length / criteria.length;
+        return { score, criteria };
+    }
+    /**
+     * Assess Accessible dimension
+     */
+    assessAccessible(source) {
+        const criteria = [
+            {
+                id: 'A1',
+                description: 'Retrievable by identifier',
+                met: !!source.filePath,
+            },
+            {
+                id: 'A2',
+                description: 'Metadata accessible',
+                met: true,
+            },
+        ];
+        const score = criteria.filter((c) => c.met).length / criteria.length;
+        return { score, criteria };
+    }
+    /**
+     * Assess Interoperable dimension
+     */
+    assessInteroperable(source) {
+        const criteria = [
+            {
+                id: 'I1',
+                description: 'Formal knowledge representation',
+                met: true,
+            },
+            {
+                id: 'I2',
+                description: 'FAIR-compliant vocabularies',
+                met: true,
+            },
+            {
+                id: 'I3',
+                description: 'Qualified references',
+                met: !!(source.paper.doi || source.paper.arxivId),
+            },
+        ];
+        const score = criteria.filter((c) => c.met).length / criteria.length;
+        return { score, criteria };
+    }
+    /**
+     * Assess Reusable dimension
+     */
+    assessReusable(source) {
+        const criteria = [
+            {
+                id: 'R1',
+                description: 'Accurate metadata',
+                met: !!source.paper.abstract,
+            },
+            {
+                id: 'R2',
+                description: 'Detailed provenance',
+                met: !!source.acquiredAt,
+            },
+            {
+                id: 'R3',
+                description: 'Meets community standards',
+                met: true,
+            },
+        ];
+        const score = criteria.filter((c) => c.met).length / criteria.length;
+        return { score, criteria };
+    }
+    /**
+     * Assess methodological quality
+     */
+    assessMethodological(source) {
+        let score = 0.5; // Base score
+        if (source.paper.type === 'journal' || source.paper.type === 'conference') {
+            score += 0.3; // Peer-reviewed
+        }
+        if (source.paper.abstract && source.paper.abstract.length > 100) {
+            score += 0.1; // Substantial abstract
+        }
+        if (source.paper.venue) {
+            score += 0.1; // Published in venue
+        }
+        return Math.min(score, 1.0);
+    }
+    /**
+     * Assess evidential quality
+     */
+    assessEvidential(source) {
+        let score = 0.5; // Base score
+        if (source.paper.citationCount) {
+            // Log scale for citation count
+            const citationScore = Math.log10(source.paper.citationCount + 1) / 3;
+            score += Math.min(citationScore, 0.3);
+        }
+        if (source.paper.year && source.paper.year >= new Date().getFullYear() - 5) {
+            score += 0.2; // Recent publication
+        }
+        return Math.min(score, 1.0);
+    }
+    /**
+     * Assess transparency
+     */
+    assessTransparency(source) {
+        let score = 0.5; // Base score
+        if (source.paper.doi) {
+            score += 0.2; // Has DOI
+        }
+        if (source.paper.pdfUrl) {
+            score += 0.2; // Accessible PDF
+        }
+        if (source.paper.authors.length > 0) {
+            score += 0.1; // Author information
+        }
+        return Math.min(score, 1.0);
+    }
+    /**
+     * Assess reproducibility
+     */
+    assessReproducibility(source) {
+        let score = 0.5; // Base score
+        if (source.checksum) {
+            score += 0.2; // File integrity
+        }
+        if (source.paper.source) {
+            score += 0.2; // Source tracked
+        }
+        if (source.acquiredAt) {
+            score += 0.1; // Acquisition metadata
+        }
+        return Math.min(score, 1.0);
+    }
+    /**
+     * Build summary text
+     */
+    buildSummary(count, averageOverall, gradeDistribution) {
+        const highCount = gradeDistribution.HIGH;
+        const percentage = ((averageOverall * 100) | 0);
+        return `Analyzed ${count} sources with average quality score of ${percentage}%. ${highCount} sources rated as HIGH quality.`;
+    }
+    /**
+     * Build recommendations
+     */
+    buildRecommendations(averageScores, gradeDistribution) {
+        const recommendations = [];
+        if (averageScores.methodological < 0.7) {
+            recommendations.push('Consider increasing proportion of peer-reviewed sources');
+        }
+        if (averageScores.fairCompliance < 0.7) {
+            recommendations.push('Improve FAIR compliance by ensuring all sources have DOIs or persistent identifiers');
+        }
+        if (averageScores.reproducibility < 0.7) {
+            recommendations.push('Enhance reproducibility by maintaining complete acquisition metadata');
+        }
+        if (gradeDistribution.VERY_LOW > 0) {
+            recommendations.push('Review VERY_LOW quality sources and consider replacement with higher-quality alternatives');
+        }
+        return recommendations;
+    }
+}
+//# sourceMappingURL=quality.js.map

package/dist/src/research/services/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for Research Framework services
+ *
+ * @module research/services/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/research/storage-cli.js

@@ -0,0 +1,20 @@
+/**
+ * Research storage CLI — `aiwg research-store <subcommand>`
+ *
+ * Thin wrapper around `runSubsystemCli('research', ...)`. Used by
+ * research-acquire / corpus-* skills (#968) so the research corpus
+ * honors `.aiwg/storage.config` redirection (e.g., `roots.research`
+ * pointing at a secondary drive — one of the headline use cases in #934).
+ *
+ * Note: AIWG already has many `research-*` commands (research-discover,
+ * research-acquire, etc.). This new command is named `research-store`
+ * to disambiguate — it's the storage primitive layer, not a workflow.
+ *
+ * @issue #934
+ * @issue #968
+ */
+import { runSubsystemCli } from '../storage/subsystem-cli.js';
+export async function main(args) {
+    await runSubsystemCli('research', args, { displayName: 'research-store' });
+}
+//# sourceMappingURL=storage-cli.js.map

package/dist/src/research/types.js

@@ -0,0 +1,47 @@
+/**
+ * Type definitions for the Research Framework
+ *
+ * @module research/types
+ */
+/**
+ * Research Framework error codes
+ */
+export var ResearchErrorCode;
+(function (ResearchErrorCode) {
+    // RF-1xx: Client errors
+    ResearchErrorCode["RF_100"] = "RF-100: Invalid request parameters";
+    ResearchErrorCode["RF_101"] = "RF-101: Missing required parameter";
+    ResearchErrorCode["RF_102"] = "RF-102: Invalid API key";
+    ResearchErrorCode["RF_103"] = "RF-103: Rate limit exceeded";
+    ResearchErrorCode["RF_104"] = "RF-104: Request timeout";
+    // RF-2xx: Server errors
+    ResearchErrorCode["RF_200"] = "RF-200: API server error";
+    ResearchErrorCode["RF_201"] = "RF-201: Service unavailable";
+    ResearchErrorCode["RF_202"] = "RF-202: Gateway timeout";
+    // RF-3xx: Data errors
+    ResearchErrorCode["RF_300"] = "RF-300: Resource not found";
+    ResearchErrorCode["RF_301"] = "RF-301: Invalid response format";
+    ResearchErrorCode["RF_302"] = "RF-302: Missing required field";
+    // RF-4xx: Cache errors
+    ResearchErrorCode["RF_400"] = "RF-400: Cache read error";
+    ResearchErrorCode["RF_401"] = "RF-401: Cache write error";
+    ResearchErrorCode["RF_402"] = "RF-402: Cache invalidation error";
+    // RF-5xx: Network errors
+    ResearchErrorCode["RF_500"] = "RF-500: Network error";
+    ResearchErrorCode["RF_501"] = "RF-501: Connection refused";
+    ResearchErrorCode["RF_502"] = "RF-502: DNS resolution failed";
+})(ResearchErrorCode || (ResearchErrorCode = {}));
+/**
+ * Research Framework error
+ */
+export class ResearchError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'ResearchError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/src/resources/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./web-release.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/resources/index.js

@@ -0,0 +1,2 @@
+export * from "./web-release.js";
+//# sourceMappingURL=index.js.map

package/dist/src/resources/web-release.d.ts

@@ -0,0 +1,89 @@
+export declare const DEFAULT_RESOURCE_BASE_URL = "https://releases.aiwg.io";
+export declare const AIWG_RELEASE_PUBLIC_KEY_PEM = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA8BsJ2vjuHBReexz328sknfL7MKUtxynX6MGfqFVMD38=\n-----END PUBLIC KEY-----";
+export type ResourceSource = "local" | "web" | "auto";
+export type ResourceSelector = {
+    kind: "exact";
+    value: string;
+} | {
+    kind: "channel";
+    value: string;
+};
+export interface ResourceFetchResponse {
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    body?: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel?(reason?: unknown): Promise<void>;
+        };
+    } | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export type ResourceFetcher = (input: string | URL, init?: {
+    redirect?: "error";
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<ResourceFetchResponse>;
+export interface WebReleaseOptions {
+    selector?: string;
+    offline?: boolean;
+    baseUrl?: string;
+    cacheRoot?: string;
+    publicKeyPem?: string | Buffer;
+    fetcher?: ResourceFetcher;
+    /** Test/development escape hatch. HTTP remains restricted to loopback. */
+    allowInsecureLoopbackHttp?: boolean;
+}
+export interface VerifiedReleaseDescriptor {
+    path: string;
+    size: number;
+    sha256: string;
+}
+export interface VerifiedWebRelease {
+    selector: string;
+    selectorKind: ResourceSelector["kind"];
+    version: string;
+    manifestDigest: string;
+    baseUrl: string;
+    manifestUrl: string;
+    cacheDir: string;
+    releaseManifestPath: string;
+    releaseSignaturePath: string;
+    fortemiManifestPath: string;
+    fortemiExportPath: string;
+    fortemiManifestSha256: string;
+    fortemiManifestSize: number;
+    fortemiExportSha256: string;
+    fortemiExportSize: number;
+    channelSequence?: number;
+    descriptors: ReadonlyMap<string, VerifiedReleaseDescriptor>;
+}
+export interface VerifiedRawResourceOptions extends Pick<WebReleaseOptions, "baseUrl" | "fetcher" | "allowInsecureLoopbackHttp"> {
+    offline?: boolean;
+}
+export declare function verifySignedResourceBytes(bytes: Uint8Array, signatureBytes: Uint8Array, publicKeyPem?: string | Buffer, label?: string): string;
+export declare function parseResourceSelector(selector: string): ResourceSelector;
+export declare function getResourceCacheRoot(cacheRoot?: string): string;
+export interface BoundedFileReadOptions {
+    label: string;
+    maxBytes: number;
+    expectedSize?: number;
+    expectedSha256?: string;
+}
+/**
+ * Read a bounded regular file through one descriptor. O_NOFOLLOW closes the
+ * final-component symlink race on platforms that support it; lstat/fstat and
+ * digest checks retain fail-closed behavior elsewhere.
+ */
+export declare function readVerifiedRegularFile(pathname: string, options: BoundedFileReadOptions): Buffer;
+export declare function loadResourceTrustRootFile(pathname: string): Buffer;
+export declare function resolveWebRelease(options?: WebReleaseOptions): Promise<VerifiedWebRelease>;
+export declare function fetchVerifiedRawResource(release: VerifiedWebRelease, resourcePath: string, options?: VerifiedRawResourceOptions): Promise<Buffer>;
+export declare function createWebReleaseTestOptions(baseUrl: string, overrides?: Omit<WebReleaseOptions, "baseUrl" | "allowInsecureLoopbackHttp">): WebReleaseOptions;
+//# sourceMappingURL=web-release.d.ts.map