@aiwg/cli 2026.8.1 → 2026.8.3

package/dist/src/packages/adapters/git.js

@@ -11,7 +11,7 @@
  */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { mkdir, readFile } from 'fs/promises';
+import { mkdir, mkdtemp, readFile, rename, rm } from 'fs/promises';
 import { join } from 'path';
 import { homedir } from 'os';
 import { existsSync } from 'fs';
@@ -82,6 +82,41 @@ async function resolveLatestTag(gitUrl) {
     }
     return 'latest';
 }
+async function resolveRemoteCommit(gitUrl, requestedRef) {
+    if (/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(requestedRef))
+        return requestedRef;
+    const patterns = requestedRef === 'HEAD'
+        ? ['HEAD']
+        : [`refs/tags/${requestedRef}^{}`, `refs/tags/${requestedRef}`, `refs/heads/${requestedRef}`, requestedRef];
+    try {
+        const output = await git(['ls-remote', gitUrl, ...patterns]);
+        const rows = output.split('\n').filter(Boolean).map((line) => {
+            const [oid = '', ref = ''] = line.split(/\s+/, 2);
+            return { oid, ref };
+        });
+        const peeled = rows.find((row) => row.ref.endsWith('^{}'));
+        const selected = peeled ?? rows[0];
+        return selected && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(selected.oid)
+            ? selected.oid
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function urlCacheIdentity(gitUrl) {
+    const urlKey = gitUrl
+        .replace(/^https?:\/\//, '')
+        .replace(/^ssh:\/\//, '')
+        .replace(/^git@/, '')
+        .replace(/\.git$/, '')
+        .replace(/[:/]/g, '_');
+    const parts = urlKey.split('_').filter(Boolean);
+    return {
+        name: parts[parts.length - 1] ?? 'package',
+        owner: parts[parts.length - 2] ?? 'unknown',
+    };
+}
 /**
  * GitAdapter
  *
@@ -111,38 +146,53 @@ export class GitAdapter {
         };
     }
     async fetch(source, options = {}) {
-        // Determine version
-        let version = source.ref;
-        if (!version) {
-            version = await resolveLatestTag(source.gitUrl);
-        }
-        // Build cache key from URL
-        const urlKey = source.gitUrl
-            .replace(/^https?:\/\//, '')
-            .replace(/^git@/, '')
-            .replace(/\.git$/, '')
-            .replace(/[:/]/g, '_');
-        const parts = urlKey.split('_');
-        const name = parts[parts.length - 1] ?? 'package';
-        const owner = parts[parts.length - 2] ?? 'unknown';
-        const cachePath = buildCachePath(owner, name, version);
-        if (!options.refresh && existsSync(cachePath)) {
-            return cachePath;
+        // Resolve discovery inputs before any deployment and cache by immutable
+        // commit rather than by a movable tag/branch name (#2009).
+        let requestedRef = source.ref;
+        if (!requestedRef) {
+            const latest = await resolveLatestTag(source.gitUrl);
+            requestedRef = latest === 'latest' ? 'HEAD' : latest;
+            source.ref = requestedRef;
         }
-        await mkdir(cachePath, { recursive: true });
-        if (existsSync(join(cachePath, '.git'))) {
-            // Update existing clone
-            await git(['fetch', '--tags', '--prune'], cachePath);
+        const advertisedCommit = await resolveRemoteCommit(source.gitUrl, requestedRef);
+        const { owner, name } = urlCacheIdentity(source.gitUrl);
+        if (advertisedCommit) {
+            const existing = buildCachePath(owner, name, advertisedCommit);
+            if (!options.refresh && existsSync(join(existing, '.git'))) {
+                const existingCommit = await git(['rev-parse', 'HEAD^{commit}'], existing);
+                if (existingCommit !== advertisedCommit)
+                    throw new Error(`Immutable package cache mismatch at ${existing}`);
+                return existing;
+            }
         }
-        else {
-            // Fresh clone (no --depth to get tags)
-            await git(['clone', source.gitUrl, cachePath]);
+        const ownerDir = join(getCacheRoot(), owner);
+        await mkdir(ownerDir, { recursive: true });
+        const stage = await mkdtemp(join(ownerDir, `.${name}.resolve-`));
+        try {
+            await git(['clone', '--no-checkout', source.gitUrl, stage]);
+            await git(['checkout', '--detach', requestedRef], stage);
+            const resolvedCommit = await git(['rev-parse', 'HEAD^{commit}'], stage);
+            if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(resolvedCommit)) {
+                throw new Error(`Git resolved '${requestedRef}' to invalid commit '${resolvedCommit}'`);
+            }
+            if (advertisedCommit && resolvedCommit !== advertisedCommit) {
+                throw new Error(`Git ref '${requestedRef}' moved during resolution (${advertisedCommit} -> ${resolvedCommit})`);
+            }
+            const cachePath = buildCachePath(owner, name, resolvedCommit);
+            if (existsSync(join(cachePath, '.git'))) {
+                const cachedCommit = await git(['rev-parse', 'HEAD^{commit}'], cachePath);
+                if (cachedCommit !== resolvedCommit)
+                    throw new Error(`Immutable package cache mismatch at ${cachePath}`);
+                await rm(stage, { recursive: true, force: true });
+                return cachePath;
+            }
+            await rename(stage, cachePath);
+            return cachePath;
         }
-        // Checkout requested ref
-        if (version && version !== 'latest') {
-            await git(['checkout', version], cachePath);
+        catch (error) {
+            await rm(stage, { recursive: true, force: true });
+            throw error;
         }
-        return cachePath;
     }
     /** GitAdapter does not list packages */
     async list() {

package/dist/src/packages/package-discovery.js

@@ -0,0 +1,81 @@
+/**
+ * Resolve a fetched Git checkout to one deployable package without executing it.
+ * Supports root bundles and the documented standalone .aiwg/plugins layout.
+ *
+ * @implements #1997
+ * @implements #2009
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { discoverProjectLocalBundles, loadAndValidateManifest } from '../extensions/project-local-discovery.js';
+const TYPES = new Set(['framework', 'addon', 'extension', 'plugin', 'provider']);
+function formatErrors(errors) {
+    return errors.map((error) => `${error.field}: expected ${error.expected}, got ${error.actual}${error.hint ? `; ${error.hint}` : ''}`).join('\n  - ');
+}
+async function rootManifest(checkoutPath) {
+    try {
+        const value = JSON.parse(await readFile(path.join(checkoutPath, 'manifest.json'), 'utf8'));
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function discoverInstallablePackage(checkoutPath, selector) {
+    const checkout = path.resolve(checkoutPath);
+    const root = await rootManifest(checkout);
+    if (root) {
+        const declaredType = String(root.type ?? '');
+        if (root.manifestVersion === '1' && TYPES.has(declaredType)) {
+            const validation = await loadAndValidateManifest(path.join(checkout, 'manifest.json'), declaredType, checkout);
+            if (!validation.bundle) {
+                throw new Error(`Root package manifest validation failed:\n  - ${formatErrors(validation.errors)}`);
+            }
+            if (selector && selector !== validation.bundle.id) {
+                throw new Error(`Package selector '${selector}' does not match root package '${validation.bundle.id}'`);
+            }
+            return {
+                manifest: validation.bundle.manifest,
+                type: validation.bundle.type === 'provider' ? 'unknown' : validation.bundle.type,
+                wrapperPath: checkout,
+                artifactPath: validation.bundle.artifactPath,
+            };
+        }
+        // Legacy root manifests remain installable for compatibility, but unknown
+        // roots no longer report a successful zero-artifact deployment.
+        if (['framework', 'addon', 'extension'].includes(String(root.type))) {
+            const name = String(root.id ?? root.name ?? '');
+            if (selector && selector !== name)
+                throw new Error(`Package selector '${selector}' does not match root package '${name}'`);
+            return {
+                manifest: root,
+                type: root.type,
+                wrapperPath: checkout,
+                artifactPath: checkout,
+            };
+        }
+    }
+    const discovery = await discoverProjectLocalBundles(checkout);
+    if (discovery.errors.length) {
+        throw new Error(`Standalone package discovery failed:\n  - ${formatErrors(discovery.errors)}`);
+    }
+    let candidates = discovery.bundles.filter((bundle) => bundle.type === 'plugin');
+    if (selector)
+        candidates = candidates.filter((bundle) => bundle.id === selector);
+    if (candidates.length === 0) {
+        throw new Error(selector
+            ? `No valid standalone plugin '${selector}' exists in this Git repository`
+            : 'Git repository contains no valid root package or standalone .aiwg/plugins wrapper');
+    }
+    if (candidates.length > 1) {
+        throw new Error(`Git repository contains multiple standalone plugins (${candidates.map((bundle) => bundle.id).sort().join(', ')}); select one with --package <id>`);
+    }
+    const selected = candidates[0];
+    return {
+        manifest: selected.manifest,
+        type: 'plugin',
+        wrapperPath: selected.bundlePath,
+        artifactPath: selected.artifactPath,
+    };
+}
+//# sourceMappingURL=package-discovery.js.map

package/dist/src/packages/package-registry.js

@@ -137,6 +137,8 @@ export async function listPackages(configDir) {
             source: entry.source,
             installedAt: entry.installedAt,
             deployCount: entry.deployedTo?.length ?? 0,
+            ...(entry.provenance?.lockId ? { lockId: entry.provenance.lockId } : {}),
+            ...(entry.provenance?.verificationStatus ? { verificationStatus: entry.provenance.verificationStatus } : {}),
         };
     });
 }

package/dist/src/packages/registry.js

@@ -7,13 +7,17 @@
  * @implements #557
  */
 import { readFile } from 'fs/promises';
-import { join } from 'path';
-import { GitAdapter, detectManifestType } from './adapters/git.js';
+import { existsSync } from 'fs';
+import { join, relative, sep } from 'path';
+import { GitAdapter } from './adapters/git.js';
 import { GiteaAdapter } from './adapters/gitea.js';
 import { GitHubAdapter } from './adapters/github.js';
 import { ClawHubPackageAdapter } from './adapters/clawhub.js';
 import { LocalCacheAdapter } from './adapters/local-cache.js';
-import { setPackageEntry, listPackages as listFromRegistry, removePackageEntry, } from './package-registry.js';
+import { getPackageEntry, setPackageEntry, listPackages as listFromRegistry, removePackageEntry, } from './package-registry.js';
+import { discoverInstallablePackage } from './package-discovery.js';
+import { buildFortemiEnvelopeShard, canonicalJson, createOperationReceipt, createProvenanceEnvelope, sha256, validateProvenanceEnvelope, verifyProvenanceEnvelope, } from '../marketplace/provenance.js';
+import { findIndexedPackage, readMarketplaceIndex, readTrustStore, recordInstalledPackage, } from '../marketplace/exchange.js';
 /**
  * All adapters in resolution priority order
  * (Scheme-prefixed adapters first so explicit prefixes are matched before
@@ -26,6 +30,9 @@ const ALL_ADAPTERS = [
     new GitAdapter(),
 ];
 const CACHE_ADAPTER = new LocalCacheAdapter();
+function pathSeparatorSafe(parent, child) {
+    return relative(parent, child).replaceAll(sep, '/') || '.';
+}
 /**
  * Parse a raw reference string into a PackageRef
  *
@@ -176,26 +183,118 @@ export async function installPackage(rawRef, options = {}) {
             `  git@host:owner/name.git (SSH URL)`);
     }
     const { source, adapter } = resolved;
+    if (options.ref)
+        source.ref = options.ref;
     const cachePath = await adapter.fetch(source, { refresh: options.refresh });
-    // Detect type from manifest.json
-    const type = await detectManifestType(cachePath);
-    // Build registry key
-    const key = ref.owner && ref.name
-        ? `${ref.owner}/${ref.name}`
-        : source.label.replace(/https?:\/\/[^/]+\//, '').replace(/\.git$/, '');
-    const version = ref.version ?? source.ref ?? 'latest';
-    // Resolve namespace for artifact deployment isolation (#804)
-    const namespace = await readPackageNamespace(cachePath, rawRef);
-    // Register in packages.yaml
-    await setPackageEntry(key, {
-        version,
-        source: source.gitUrl,
-        type,
+    const discovered = await discoverInstallablePackage(cachePath, options.packageSelector);
+    const standardEnvelopePaths = [
+        join(cachePath, '.aiwg', 'marketplace', 'envelope.json'),
+        join(cachePath, 'aiwg-marketplace-envelope.json'),
+    ];
+    let envelope = options.expectedEnvelope;
+    if (!envelope) {
+        for (const filename of standardEnvelopePaths) {
+            if (!existsSync(filename))
+                continue;
+            const value = JSON.parse(await readFile(filename, 'utf8'));
+            validateProvenanceEnvelope(value);
+            envelope = value;
+            break;
+        }
+    }
+    if (!envelope) {
+        envelope = await createProvenanceEnvelope({
+            checkoutPath: cachePath,
+            artifactPath: discovered.artifactPath,
+            wrapperPath: pathSeparatorSafe(cachePath, discovered.wrapperPath),
+            manifest: discovered.manifest,
+            requestedRef: source.ref ?? ref.version ?? 'HEAD',
+            remote: source.gitUrl,
+            publisher: String(discovered.manifest.author ?? discovered.manifest.namespace ?? ref.owner ?? 'unverified'),
+        });
+    }
+    const key = `${envelope.package.namespace}/${envelope.package.name}`;
+    const namespace = envelope.package.namespace;
+    const type = discovered.type;
+    const existingEntry = await getPackageEntry(key, options.configDir);
+    let previousLock;
+    if (existingEntry?.provenance?.lockId) {
+        previousLock = (await findIndexedPackage(existingEntry.provenance.lockId, { configDir: options.configDir }))?.lock;
+    }
+    const localIndex = await readMarketplaceIndex({ configDir: options.configDir });
+    const installedLocks = Object.fromEntries(Object.values(localIndex.packages).map((entry) => [entry.lock.identity, entry.lock.lockId]));
+    const trustStore = options.trustStore ?? await readTrustStore({ configDir: options.configDir });
+    const verification = await verifyProvenanceEnvelope({
+        envelope,
+        contentRoot: discovered.artifactPath,
+        checkoutPath: cachePath,
+        trustStore,
+        policy: options.verify
+            ? { requireSignature: true, allowIntegrityOnly: false, ...options.verificationPolicy }
+            : options.verificationPolicy,
+        installedLocks,
+        previousLock,
+    });
+    if (!verification.ok)
+        throw new Error(`Package verification failed: ${verification.errors.join('; ')}`);
+    if (options.expectedLockId && verification.lock.lockId !== options.expectedLockId) {
+        throw new Error(`Catalog/direct lock mismatch: expected ${options.expectedLockId}, got ${verification.lock.lockId}`);
+    }
+    if (options.expectedEnvelope && sha256(canonicalJson(options.expectedEnvelope)) !== verification.envelopeSha256) {
+        throw new Error('Catalog envelope changed before installation');
+    }
+    const fortemi = await buildFortemiEnvelopeShard(envelope);
+    const receipt = createOperationReceipt({
+        operation: 'install',
+        lock: verification.lock,
+        actor: options.actor ?? 'aiwg',
+        verificationStatus: verification.status,
+        evidence: {
+            source: source.gitUrl,
+            requestedRef: envelope.source.requestedRef,
+            resolvedCommit: envelope.source.resolvedCommit,
+            catalog: options.catalogId ?? null,
+            directGit: !options.catalogId,
+        },
+        conformance: fortemi.conformance,
+    });
+    await recordInstalledPackage({
+        configDir: options.configDir,
+        envelope,
+        lock: verification.lock,
+        receipt,
         cachePath,
-        installedAt: new Date().toISOString(),
-        deployedTo: [],
+        artifactPath: discovered.artifactPath,
+        verificationStatus: verification.status,
+        fortemiShard: fortemi.archive,
+        catalogId: options.catalogId,
+    });
+    await setPackageEntry(key, {
+        version: envelope.package.version,
+        source: envelope.source.canonicalRemote,
+        type: type === 'plugin' ? 'extension' : type,
+        cachePath: discovered.artifactPath,
+        installedAt: receipt.occurredAt,
+        deployedTo: existingEntry?.deployedTo ?? [],
+        provenance: {
+            lockId: verification.lock.lockId,
+            resolvedCommit: verification.lock.resolvedCommit,
+            treeSha256: verification.lock.treeSha256,
+            artifactSha256: verification.lock.artifactSha256,
+            envelopeSha256: verification.lock.envelopeSha256,
+            verificationStatus: verification.status,
+        },
     }, options.configDir);
-    return { cachePath, key, type, namespace };
+    return {
+        cachePath: discovered.artifactPath,
+        checkoutPath: cachePath,
+        key,
+        type,
+        namespace,
+        envelope,
+        lock: verification.lock,
+        verification,
+    };
 }
 /**
  * Refresh all registered remote packages (used by `aiwg sync`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.1",
+  "version": "2026.8.3",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",
@@ -64,7 +64,7 @@
   },
   "dependencies": {
     "@fortemi/core": "2026.7.15",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "chalk": "^4.1.2",
     "chokidar": "^4.0.3",
     "commander": "^12.1.0",