@zivis/cli 0.1.0-alpha.40 → 0.1.0-alpha.41

package/dist/internal/inventory-sync.js

@@ -0,0 +1,189 @@
+export function validateInventorySyncInput(raw) {
+    const errors = [];
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, errors: ["input must be a JSON object"] };
+    }
+    const obj = raw;
+    const allowedKeys = new Set(["endpoints", "features", "technologyStack"]);
+    for (const key of Object.keys(obj)) {
+        if (!allowedKeys.has(key))
+            errors.push(`unknown field "${key}"`);
+    }
+    let endpoints;
+    if (obj.endpoints !== undefined) {
+        if (!Array.isArray(obj.endpoints)) {
+            errors.push("endpoints must be an array");
+        }
+        else {
+            endpoints = [];
+            obj.endpoints.forEach((ep, i) => {
+                if (typeof ep !== "object" || ep === null) {
+                    errors.push(`endpoints[${i}] must be an object`);
+                    return;
+                }
+                const e = ep;
+                if (typeof e.path !== "string" || !e.path) {
+                    errors.push(`endpoints[${i}].path must be a non-empty string`);
+                }
+                if (typeof e.method !== "string" || !e.method) {
+                    errors.push(`endpoints[${i}].method must be a non-empty string`);
+                }
+                if (e.tags !== undefined && (!Array.isArray(e.tags) || !e.tags.every((t) => typeof t === "string"))) {
+                    errors.push(`endpoints[${i}].tags must be an array of strings`);
+                }
+                if (errors.length === 0 || (typeof e.path === "string" && typeof e.method === "string")) {
+                    endpoints.push({
+                        path: e.path,
+                        method: e.method,
+                        summary: typeof e.summary === "string" ? e.summary : undefined,
+                        description: typeof e.description === "string" ? e.description : undefined,
+                        authRequired: typeof e.authRequired === "boolean" ? e.authRequired : undefined,
+                        tags: Array.isArray(e.tags) ? e.tags : undefined,
+                        deprecated: typeof e.deprecated === "boolean" ? e.deprecated : undefined,
+                    });
+                }
+            });
+        }
+    }
+    const validCriticalities = new Set(["critical", "high", "medium", "low"]);
+    let features;
+    if (obj.features !== undefined) {
+        if (!Array.isArray(obj.features)) {
+            errors.push("features must be an array");
+        }
+        else {
+            features = [];
+            obj.features.forEach((f, i) => {
+                if (typeof f !== "object" || f === null) {
+                    errors.push(`features[${i}] must be an object`);
+                    return;
+                }
+                const feat = f;
+                if (typeof feat.name !== "string" || !feat.name) {
+                    errors.push(`features[${i}].name must be a non-empty string`);
+                }
+                if (feat.criticality !== undefined && !validCriticalities.has(feat.criticality)) {
+                    errors.push(`features[${i}].criticality must be one of: ${[...validCriticalities].join(", ")}`);
+                }
+                if (feat.endpoints !== undefined && (!Array.isArray(feat.endpoints) || !feat.endpoints.every((p) => typeof p === "string"))) {
+                    errors.push(`features[${i}].endpoints must be an array of strings`);
+                }
+                if (typeof feat.name === "string" && feat.name) {
+                    features.push({
+                        name: feat.name,
+                        description: typeof feat.description === "string" ? feat.description : undefined,
+                        criticality: validCriticalities.has(feat.criticality)
+                            ? feat.criticality
+                            : undefined,
+                        endpoints: Array.isArray(feat.endpoints) ? feat.endpoints : undefined,
+                        tags: Array.isArray(feat.tags) ? feat.tags : undefined,
+                    });
+                }
+            });
+        }
+    }
+    let technologyStack;
+    if (obj.technologyStack !== undefined) {
+        if (!Array.isArray(obj.technologyStack) || !obj.technologyStack.every((t) => typeof t === "string")) {
+            errors.push("technologyStack must be an array of strings");
+        }
+        else {
+            technologyStack = obj.technologyStack;
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    if (endpoints === undefined && features === undefined && technologyStack === undefined) {
+        return { ok: false, errors: ["input must include at least one of: endpoints, features, technologyStack"] };
+    }
+    const secretHits = scanForSecrets({ endpoints, features, technologyStack });
+    if (secretHits.length > 0) {
+        return {
+            ok: false,
+            errors: secretHits.map((hit) => `${hit} looks like it contains a credential/token — refusing to sync`),
+        };
+    }
+    return { ok: true, value: { endpoints, features, technologyStack } };
+}
+const SECRET_PATTERNS = [
+    /sk-[a-zA-Z0-9]{20,}/,
+    /ghp_[a-zA-Z0-9]{30,}/,
+    /gh[oprs]_[a-zA-Z0-9]{30,}/,
+    /AKIA[0-9A-Z]{16}/,
+    /-----BEGIN[ A-Z]*PRIVATE KEY-----/,
+    /\bBearer\s+[a-zA-Z0-9._-]{20,}/i,
+    /\bAuthorization\s*:\s*\S+/i,
+];
+function looksLikeSecret(value) {
+    return SECRET_PATTERNS.some((pattern) => pattern.test(value));
+}
+function scanForSecrets(input) {
+    const hits = [];
+    const check = (label, value) => {
+        if (value && looksLikeSecret(value))
+            hits.push(label);
+    };
+    (input.endpoints ?? []).forEach((ep, i) => {
+        check(`endpoints[${i}].summary`, ep.summary);
+        check(`endpoints[${i}].description`, ep.description);
+        (ep.tags ?? []).forEach((t, j) => check(`endpoints[${i}].tags[${j}]`, t));
+    });
+    (input.features ?? []).forEach((f, i) => {
+        check(`features[${i}].name`, f.name);
+        check(`features[${i}].description`, f.description);
+        (f.tags ?? []).forEach((t, j) => check(`features[${i}].tags[${j}]`, t));
+    });
+    (input.technologyStack ?? []).forEach((t, i) => check(`technologyStack[${i}]`, t));
+    return hits;
+}
+function toEndpointReconcilePayload(input, provenance) {
+    return {
+        endpoints: input.endpoints,
+        gitCommitSha: provenance.gitCommitSha ?? undefined,
+        source: provenance.source,
+    };
+}
+function toFeatureReconcilePayload(input, provenance) {
+    return {
+        features: (input.features ?? []).map((f) => ({
+            name: f.name,
+            description: f.description,
+            criticality: f.criticality ?? "medium",
+            endpoint_count: f.endpoints?.length ?? 0,
+            endpoints: f.endpoints ?? [],
+            tags: f.tags ?? [],
+        })),
+        endpoints: [],
+        integrations: [],
+        frameworks: [],
+        repos_scanned: 1,
+        files_scanned: 0,
+        gitCommitSha: provenance.gitCommitSha ?? undefined,
+        source: provenance.source,
+    };
+}
+function toTechStackPayload(input) {
+    return { technologies: input.technologyStack };
+}
+export async function syncApplicationInventory(params) {
+    const { client, applicationId, input, provenance } = params;
+    const summary = {};
+    if (input.technologyStack !== undefined) {
+        const result = await client.put(`/api/rt/applications/${encodeURIComponent(applicationId)}/technology-stack`, toTechStackPayload(input));
+        summary.technologyStack = { count: result.techStack.length };
+    }
+    if (input.endpoints !== undefined) {
+        summary.endpoints = await client.post(`/api/rt/applications/${encodeURIComponent(applicationId)}/endpoints/reconcile`, toEndpointReconcilePayload(input, provenance));
+    }
+    if (input.features !== undefined) {
+        summary.features = await client.post(`/api/features/applications/${encodeURIComponent(applicationId)}/reconcile`, toFeatureReconcilePayload(input, provenance));
+    }
+    if (provenance.repoFullName && provenance.gitCommitSha) {
+        summary.repo = await client.put(`/api/rt/applications/${encodeURIComponent(applicationId)}/repos/sync`, {
+            repoFullName: provenance.repoFullName,
+            latestCommitSha: provenance.gitCommitSha,
+            defaultBranch: provenance.defaultBranch ?? undefined,
+        });
+    }
+    return summary;
+}

package/dist/internal/packs/cache.d.ts

@@ -0,0 +1,8 @@
+import type { PackManifestV1, PackType } from "./types.js";
+export declare function writeVerifiedPackToCache(packType: PackType, version: string, manifest: PackManifestV1, contentByPath: Map<string, string>): Promise<string>;
+export declare function loadVerifiedFromCache(packType: PackType, version: string): Promise<{
+    manifest: PackManifestV1;
+    contentByPath: Map<string, string>;
+    cacheDir: string;
+} | null>;
+export declare function listCachedVersions(packType: PackType): Promise<string[]>;

package/dist/internal/packs/cache.js

@@ -0,0 +1,60 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { packTypeDir, packVersionDir } from "./local-paths.js";
+import { verifyPack } from "./integrity.js";
+function contentPaths(manifest) {
+    return [manifest.base.path, ...(manifest.scopes ?? []).map((s) => s.path)];
+}
+export async function writeVerifiedPackToCache(packType, version, manifest, contentByPath) {
+    const dir = packVersionDir(packType, version);
+    await fs.mkdir(dir, { recursive: true });
+    await atomicWrite(path.join(dir, "manifest.json"), JSON.stringify(manifest, null, 2));
+    for (const relPath of contentPaths(manifest)) {
+        const content = contentByPath.get(relPath);
+        if (content === undefined)
+            continue;
+        const target = path.join(dir, relPath);
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await atomicWrite(target, content);
+    }
+    return dir;
+}
+async function atomicWrite(target, content) {
+    const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+    await fs.writeFile(tmp, content, "utf-8");
+    await fs.rename(tmp, target);
+}
+export async function loadVerifiedFromCache(packType, version) {
+    const dir = packVersionDir(packType, version);
+    let manifest;
+    try {
+        const raw = await fs.readFile(path.join(dir, "manifest.json"), "utf-8");
+        manifest = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const contentByPath = new Map();
+    for (const relPath of contentPaths(manifest)) {
+        try {
+            contentByPath.set(relPath, await fs.readFile(path.join(dir, relPath), "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    const result = verifyPack(manifest, contentByPath);
+    if (!result.valid) {
+        return null;
+    }
+    return { manifest, contentByPath, cacheDir: dir };
+}
+export async function listCachedVersions(packType) {
+    try {
+        const entries = await fs.readdir(packTypeDir(packType), { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/internal/packs/index.d.ts

@@ -0,0 +1,10 @@
+export type { PackType, PackContentEntry, PackScopeEntry, PackSignature, PackManifestV1, PackVersionSummary, PackVersionListing, PackSource, ResolvedScope, ResolvedPack, PackRegistryClient, } from "./types.js";
+export { PackIntegrityError, PackUnavailableError, UnknownScopeError } from "./types.js";
+export { resolveCompatiblePack, resolveScope, listAvailableScopes } from "./resolve.js";
+export type { ResolveOptions } from "./resolve.js";
+export { HttpPackRegistryClient, LocalPackRegistryClient, registryDirOverride, } from "./registry-client.js";
+export type { MinimalApiClient } from "./registry-client.js";
+export { userCacheRoot, packsRoot, packTypeDir, packVersionDir } from "./local-paths.js";
+export { verifyManifestSignature, manifestSigningPayload, DEV_PACK_SIGNING_KEY_ID } from "./signing.js";
+export { sha256Hex, verifyContentHash, verifyPack } from "./integrity.js";
+export { compareVersions, satisfiesMinVersion, parseVersion } from "./semver.js";

package/dist/internal/packs/index.js

@@ -0,0 +1,7 @@
+export { PackIntegrityError, PackUnavailableError, UnknownScopeError } from "./types.js";
+export { resolveCompatiblePack, resolveScope, listAvailableScopes } from "./resolve.js";
+export { HttpPackRegistryClient, LocalPackRegistryClient, registryDirOverride, } from "./registry-client.js";
+export { userCacheRoot, packsRoot, packTypeDir, packVersionDir } from "./local-paths.js";
+export { verifyManifestSignature, manifestSigningPayload, DEV_PACK_SIGNING_KEY_ID } from "./signing.js";
+export { sha256Hex, verifyContentHash, verifyPack } from "./integrity.js";
+export { compareVersions, satisfiesMinVersion, parseVersion } from "./semver.js";

package/dist/internal/packs/integrity.d.ts

@@ -0,0 +1,9 @@
+import type { PackContentEntry, PackManifestV1 } from "./types.js";
+export declare function sha256Hex(content: string): string;
+export declare function verifyContentHash(content: string, entry: PackContentEntry): boolean;
+export declare function verifyPack(manifest: PackManifestV1, contentByPath: Map<string, string>): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};

package/dist/internal/packs/integrity.js

@@ -0,0 +1,24 @@
+import * as crypto from "node:crypto";
+import { verifyManifestSignature } from "./signing.js";
+export function sha256Hex(content) {
+    return crypto.createHash("sha256").update(content, "utf8").digest("hex");
+}
+export function verifyContentHash(content, entry) {
+    return sha256Hex(content) === entry.sha256;
+}
+export function verifyPack(manifest, contentByPath) {
+    if (!verifyManifestSignature(manifest)) {
+        return { valid: false, reason: "manifest signature verification failed" };
+    }
+    const entries = [manifest.base, ...(manifest.scopes ?? [])];
+    for (const entry of entries) {
+        const content = contentByPath.get(entry.path);
+        if (content === undefined) {
+            return { valid: false, reason: `missing content for "${entry.path}"` };
+        }
+        if (!verifyContentHash(content, entry)) {
+            return { valid: false, reason: `content hash mismatch for "${entry.path}"` };
+        }
+    }
+    return { valid: true };
+}

package/dist/internal/packs/jcs.d.ts

@@ -0,0 +1,2 @@
+export declare function canonicalize(value: unknown): string;
+export declare function jcsSha256Hex(value: unknown): string;

package/dist/internal/packs/jcs.js

@@ -0,0 +1,57 @@
+import crypto from "node:crypto";
+function compareUtf16(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function serialize(value) {
+    if (value !== null &&
+        typeof value === "object" &&
+        typeof value.toJSON === "function") {
+        value = value.toJSON();
+    }
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            if (!Number.isFinite(value)) {
+                throw new TypeError(`JCS: non-finite number is not representable in JSON: ${value}`);
+            }
+            return JSON.stringify(value);
+        case "string":
+            return JSON.stringify(value);
+        case "bigint":
+            throw new TypeError("JCS: BigInt values are not representable in JSON");
+        case "undefined":
+        case "function":
+        case "symbol":
+            return undefined;
+        case "object": {
+            if (Array.isArray(value)) {
+                const items = value.map((item) => serialize(item) ?? "null");
+                return `[${items.join(",")}]`;
+            }
+            const keys = Object.keys(value).sort(compareUtf16);
+            const parts = [];
+            for (const key of keys) {
+                const serialized = serialize(value[key]);
+                if (serialized !== undefined) {
+                    parts.push(`${JSON.stringify(key)}:${serialized}`);
+                }
+            }
+            return `{${parts.join(",")}}`;
+        }
+        default:
+            throw new TypeError(`JCS: cannot canonicalize value of type ${typeof value}`);
+    }
+}
+export function canonicalize(value) {
+    const result = serialize(value);
+    if (result === undefined) {
+        throw new TypeError("JCS: top-level value has no JSON representation");
+    }
+    return result;
+}
+export function jcsSha256Hex(value) {
+    return crypto.createHash("sha256").update(canonicalize(value), "utf8").digest("hex");
+}

package/dist/internal/packs/local-paths.d.ts

@@ -0,0 +1,4 @@
+export declare function userCacheRoot(): string;
+export declare function packsRoot(): string;
+export declare function packVersionDir(packType: string, version: string): string;
+export declare function packTypeDir(packType: string): string;

package/dist/internal/packs/local-paths.js

@@ -0,0 +1,26 @@
+import * as os from "node:os";
+import * as path from "node:path";
+export function userCacheRoot() {
+    if (process.env.ZIVIS_CACHE_ROOT) {
+        return process.env.ZIVIS_CACHE_ROOT;
+    }
+    const home = os.homedir();
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Caches", "zivis");
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+        return path.join(localAppData, "zivis", "Cache");
+    }
+    const xdgCacheHome = process.env.XDG_CACHE_HOME ?? path.join(home, ".cache");
+    return path.join(xdgCacheHome, "zivis");
+}
+export function packsRoot() {
+    return path.join(userCacheRoot(), "packs");
+}
+export function packVersionDir(packType, version) {
+    return path.join(packsRoot(), packType, version);
+}
+export function packTypeDir(packType) {
+    return path.join(packsRoot(), packType);
+}

package/dist/internal/packs/registry-client.d.ts

@@ -0,0 +1,20 @@
+import type { PackManifestV1, PackRegistryClient, PackType, PackVersionListing } from "./types.js";
+export interface MinimalApiClient {
+    get<T>(path: string): Promise<T>;
+    getText(path: string): Promise<string>;
+}
+export declare class HttpPackRegistryClient implements PackRegistryClient {
+    private readonly apiClient;
+    constructor(apiClient: MinimalApiClient);
+    listVersions(packType: PackType): Promise<PackVersionListing>;
+    getManifest(packType: PackType, version: string): Promise<PackManifestV1>;
+    getContent(packType: PackType, version: string, relativePath: string): Promise<string>;
+}
+export declare class LocalPackRegistryClient implements PackRegistryClient {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    listVersions(packType: PackType): Promise<PackVersionListing>;
+    getManifest(packType: PackType, version: string): Promise<PackManifestV1>;
+    getContent(packType: PackType, version: string, relativePath: string): Promise<string>;
+}
+export declare function registryDirOverride(): string | null;

package/dist/internal/packs/registry-client.js

@@ -0,0 +1,40 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+export class HttpPackRegistryClient {
+    apiClient;
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    listVersions(packType) {
+        return this.apiClient.get(`/api/zivis-packs/${packType}`);
+    }
+    getManifest(packType, version) {
+        return this.apiClient.get(`/api/zivis-packs/${packType}/${version}/manifest.json`);
+    }
+    getContent(packType, version, relativePath) {
+        return this.apiClient.getText(`/api/zivis-packs/${packType}/${version}/content/${relativePath}`);
+    }
+}
+export class LocalPackRegistryClient {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    async listVersions(packType) {
+        const listingPath = path.join(this.rootDir, packType, "versions.json");
+        const raw = await fs.readFile(listingPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    async getManifest(packType, version) {
+        const manifestPath = path.join(this.rootDir, packType, version, "manifest.json");
+        const raw = await fs.readFile(manifestPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    async getContent(packType, version, relativePath) {
+        const contentPath = path.join(this.rootDir, packType, version, relativePath);
+        return fs.readFile(contentPath, "utf-8");
+    }
+}
+export function registryDirOverride() {
+    return process.env.ZIVIS_PACK_REGISTRY_DIR || null;
+}

package/dist/internal/packs/resolve.d.ts

@@ -0,0 +1,8 @@
+import type { PackRegistryClient, PackScopeEntry, PackType, ResolvedPack, ResolvedScope } from "./types.js";
+export interface ResolveOptions {
+    registryClient: PackRegistryClient;
+    cliVersion: string;
+}
+export declare function resolveCompatiblePack(packType: PackType, opts: ResolveOptions): Promise<ResolvedPack>;
+export declare function resolveScope(resolved: ResolvedPack, scopeId: string): Promise<ResolvedScope>;
+export declare function listAvailableScopes(resolved: ResolvedPack): Pick<PackScopeEntry, "id" | "label" | "description">[];

package/dist/internal/packs/resolve.js

@@ -0,0 +1,89 @@
+import { PackIntegrityError, PackUnavailableError, UnknownScopeError } from "./types.js";
+import { verifyPack } from "./integrity.js";
+import { compareVersions, satisfiesMinVersion } from "./semver.js";
+import { listCachedVersions, loadVerifiedFromCache, writeVerifiedPackToCache } from "./cache.js";
+import { packVersionDir } from "./local-paths.js";
+function contentPaths(manifest) {
+    return [manifest.base.path, ...(manifest.scopes ?? []).map((s) => s.path)];
+}
+async function fetchAndVerify(packType, version, client) {
+    const manifest = await client.getManifest(packType, version);
+    const contentByPath = new Map();
+    for (const relPath of contentPaths(manifest)) {
+        contentByPath.set(relPath, await client.getContent(packType, version, relPath));
+    }
+    const result = verifyPack(manifest, contentByPath);
+    if (!result.valid) {
+        throw new PackIntegrityError(`Downloaded ${packType} pack ${version} failed verification: ${result.reason}`);
+    }
+    return { manifest, contentByPath };
+}
+function toResolvedPack(manifest, contentByPath, source, cacheDir) {
+    return {
+        packId: manifest.pack_id,
+        packType: manifest.pack_type,
+        version: manifest.version,
+        minCliVersion: manifest.min_cli_version,
+        source,
+        basePath: `${cacheDir}/${manifest.base.path}`,
+        baseContent: contentByPath.get(manifest.base.path) ?? "",
+        scopes: manifest.scopes ?? [],
+        cacheDir,
+    };
+}
+export async function resolveCompatiblePack(packType, opts) {
+    try {
+        const listing = await opts.registryClient.listVersions(packType);
+        const compatible = listing.versions
+            .filter((v) => satisfiesMinVersion(opts.cliVersion, v.min_cli_version))
+            .sort((a, b) => compareVersions(b.version, a.version));
+        if (compatible.length === 0) {
+            throw new PackUnavailableError(`No ${packType} pack is compatible with @zivis/cli ${opts.cliVersion}. ` +
+                `Available versions: ${listing.versions.map((v) => v.version).join(", ") || "(none)"}`);
+        }
+        const target = compatible[0];
+        const cached = await loadVerifiedFromCache(packType, target.version);
+        if (cached) {
+            return toResolvedPack(cached.manifest, cached.contentByPath, "cache-verified", cached.cacheDir);
+        }
+        const { manifest, contentByPath } = await fetchAndVerify(packType, target.version, opts.registryClient);
+        const cacheDir = await writeVerifiedPackToCache(packType, target.version, manifest, contentByPath);
+        return toResolvedPack(manifest, contentByPath, "network", cacheDir);
+    }
+    catch (err) {
+        if (err instanceof PackIntegrityError || err instanceof PackUnavailableError) {
+            throw err;
+        }
+        return resolveFromOfflineCache(packType, opts.cliVersion, err);
+    }
+}
+async function resolveFromOfflineCache(packType, cliVersion, networkError) {
+    const cachedVersions = await listCachedVersions(packType);
+    const verified = [];
+    for (const version of cachedVersions) {
+        const entry = await loadVerifiedFromCache(packType, version);
+        if (entry && satisfiesMinVersion(cliVersion, entry.manifest.min_cli_version)) {
+            verified.push(entry);
+        }
+    }
+    if (verified.length === 0) {
+        const reason = networkError instanceof Error ? networkError.message : String(networkError);
+        throw new PackUnavailableError(`Could not reach the ZIVIS pack registry (${reason}), and no previously verified ${packType} ` +
+            `pack compatible with @zivis/cli ${cliVersion} is cached at ${packVersionDir(packType, "*")}.`);
+    }
+    verified.sort((a, b) => compareVersions(b.manifest.version, a.manifest.version));
+    const best = verified[0];
+    return toResolvedPack(best.manifest, best.contentByPath, "cache-offline", best.cacheDir);
+}
+export async function resolveScope(resolved, scopeId) {
+    const scope = resolved.scopes.find((s) => s.id === scopeId);
+    if (!scope) {
+        throw new UnknownScopeError(scopeId, resolved.scopes);
+    }
+    const fs = await import("node:fs/promises");
+    const content = await fs.readFile(`${resolved.cacheDir}/${scope.path}`, "utf-8");
+    return { id: scope.id, label: scope.label, description: scope.description, content };
+}
+export function listAvailableScopes(resolved) {
+    return resolved.scopes.map(({ id, label, description }) => ({ id, label, description }));
+}

package/dist/internal/packs/semver.d.ts

@@ -0,0 +1,9 @@
+export interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: (string | number)[];
+}
+export declare function parseVersion(version: string): ParsedVersion;
+export declare function compareVersions(a: string, b: string): number;
+export declare function satisfiesMinVersion(cliVersion: string, minCliVersion: string): boolean;

package/dist/internal/packs/semver.js

@@ -0,0 +1,57 @@
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/;
+export function parseVersion(version) {
+    const m = SEMVER_RE.exec(version.trim());
+    if (!m) {
+        throw new Error(`Not a valid semver-like version: "${version}"`);
+    }
+    const [, major, minor, patch, prerelease] = m;
+    return {
+        major: Number(major),
+        minor: Number(minor),
+        patch: Number(patch),
+        prerelease: prerelease
+            ? prerelease.split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : part))
+            : [],
+    };
+}
+function compareIdentifier(a, b) {
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    const as = String(a);
+    const bs = String(b);
+    if (typeof a === "number")
+        return -1;
+    if (typeof b === "number")
+        return 1;
+    return as < bs ? -1 : as > bs ? 1 : 0;
+}
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (pa.major !== pb.major)
+        return pa.major - pb.major;
+    if (pa.minor !== pb.minor)
+        return pa.minor - pb.minor;
+    if (pa.patch !== pb.patch)
+        return pa.patch - pb.patch;
+    if (pa.prerelease.length === 0 && pb.prerelease.length === 0)
+        return 0;
+    if (pa.prerelease.length === 0)
+        return 1;
+    if (pb.prerelease.length === 0)
+        return -1;
+    const len = Math.max(pa.prerelease.length, pb.prerelease.length);
+    for (let i = 0; i < len; i++) {
+        if (i >= pa.prerelease.length)
+            return -1;
+        if (i >= pb.prerelease.length)
+            return 1;
+        const cmp = compareIdentifier(pa.prerelease[i], pb.prerelease[i]);
+        if (cmp !== 0)
+            return cmp;
+    }
+    return 0;
+}
+export function satisfiesMinVersion(cliVersion, minCliVersion) {
+    return compareVersions(cliVersion, minCliVersion) >= 0;
+}

package/dist/internal/packs/signing.d.ts

@@ -0,0 +1,5 @@
+import type { PackManifestV1, PackSignature } from "./types.js";
+export declare const DEV_PACK_SIGNING_KEY_ID = "zivis-pack-dev-2026-08";
+export declare function manifestSigningPayload(manifest: Omit<PackManifestV1, "signature">): string;
+export declare function verifyManifestSignature(manifest: PackManifestV1): boolean;
+export declare function signManifestDev(manifest: Omit<PackManifestV1, "signature">, privateKeySpkiB64: string): PackSignature;