@apexops/cli 0.10.0-next.0

package/dist/assets.d.ts

@@ -0,0 +1,69 @@
+export interface BundledAssetMapping {
+    id: string;
+    mode: "copy-tree" | "copy-entries" | "compose-json" | "render-client-projections";
+    sourceRoot?: string;
+    generatedRoot?: string;
+    generatedPath?: string;
+}
+export interface BundledAssetSource {
+    kind: "repository-file" | "generated";
+    path?: string;
+    mapping?: string;
+    composition?: string;
+    roleId?: string;
+    sourcePath?: string;
+    sourceHash?: string;
+    clientId?: string;
+    target?: string;
+    adapterVersion?: string;
+}
+export interface BundledAssetFile {
+    path: string;
+    source: BundledAssetSource;
+    sha256: string;
+    bytes: number;
+}
+export interface BundledClientProjection {
+    id: "github-copilot-cli" | "github-copilot-vscode";
+    files: string[];
+    digest: string;
+}
+export interface BundledAssetManifest {
+    version: 1;
+    sources: {
+        customizations: string;
+        config: string;
+    };
+    composition: {
+        authority: "npm:@apexops/cli";
+        generator: "packages/cli/scripts/prepare-assets.mjs";
+        formatVersion: 1;
+        mappings: BundledAssetMapping[];
+    };
+    projections: BundledClientProjection[];
+    files: BundledAssetFile[];
+    lock: {
+        algorithm: "sha256";
+        canonicalization: "apex-bundled-assets-v1";
+        digest: string;
+    };
+}
+export interface BundledAssets {
+    root: string;
+    customizations: string;
+    clientProjections: Readonly<Record<BundledClientProjection["id"], string>>;
+    config: string;
+    capabilityPacks: string;
+    capabilityPackRegistry: string;
+    manifest: BundledAssetManifest;
+}
+export declare function readBundledFile(root: string, relativePath: string, beforeOpen?: () => Promise<void>, expectedIdentity?: {
+    dev: bigint;
+    ino: bigint;
+}): Promise<Buffer>;
+export declare function verifyBundleDeclarations(manifest: BundledAssetManifest, customizationManifest: Record<string, unknown>, runtimeBundle: Record<string, unknown>): void;
+export declare function clientProjectionDigest(projection: Pick<BundledClientProjection, "id" | "files">, files: BundledAssetFile[]): string;
+export declare function bundleLockDigest(input: Pick<BundledAssetManifest, "sources" | "composition" | "projections" | "files">): string;
+export declare function verifyBundledAssetManifest(root: string, manifest: BundledAssetManifest): Promise<void>;
+export declare function resolveBundledAssets(): Promise<BundledAssets>;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.js

@@ -0,0 +1,336 @@
+import { canonicalJsonBytes, sha256Bytes } from "@apexops/kernel";
+import { constants } from "node:fs";
+import { lstat, open, readFile, readdir, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const LOCK_DOMAIN = "apex-bundled-assets-v1\0";
+const PROJECTION_DOMAIN = "apex-client-projection-v1\0";
+const PROJECTION_TARGETS = {
+    "github-copilot-cli": "github-copilot",
+    "github-copilot-vscode": "vscode",
+};
+const SHA256 = /^[a-f0-9]{64}$/u;
+function projectionTarget(clientId) {
+    const target = PROJECTION_TARGETS[clientId];
+    if (target === undefined)
+        throw new Error(`Unsupported bundled client projection: ${clientId ?? "missing"}`);
+    return target;
+}
+function portablePath(path) {
+    return path.split(sep).join("/");
+}
+function safeRelativePath(path) {
+    return (path.length > 0 &&
+        !path.includes("\\") &&
+        !path.includes("\0") &&
+        !path.includes(":") &&
+        !isAbsolute(path) &&
+        path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== ".."));
+}
+function assertContained(root, path) {
+    const child = relative(resolve(root), resolve(path));
+    if (child === "" || child === ".." || child.startsWith(`..${sep}`) || isAbsolute(child)) {
+        throw new Error(`Unsafe bundled asset path: ${path}`);
+    }
+}
+export async function readBundledFile(root, relativePath, beforeOpen = async () => { }, expectedIdentity) {
+    const path = resolve(root, relativePath);
+    assertContained(root, path);
+    const resolved = await realpath(path);
+    assertContained(root, resolved);
+    const initialMetadata = await lstat(path, { bigint: true });
+    const identity = expectedIdentity ?? { dev: initialMetadata.dev, ino: initialMetadata.ino };
+    if (initialMetadata.isSymbolicLink() || !initialMetadata.isFile()) {
+        throw new Error(`Unsupported bundled asset entry: ${relativePath}`);
+    }
+    await beforeOpen();
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const descriptorMetadata = await handle.stat({ bigint: true });
+        if (!descriptorMetadata.isFile())
+            throw new Error(`Unsupported bundled asset entry: ${relativePath}`);
+        const pathMetadata = await lstat(path, { bigint: true });
+        if (pathMetadata.isSymbolicLink() ||
+            descriptorMetadata.dev !== identity.dev ||
+            descriptorMetadata.ino !== identity.ino ||
+            pathMetadata.dev !== descriptorMetadata.dev ||
+            pathMetadata.ino !== descriptorMetadata.ino) {
+            throw new Error(`Bundled asset path changed during verification: ${relativePath}`);
+        }
+        const descriptorPath = process.platform === "linux" ? `/proc/self/fd/${handle.fd}` : path;
+        const openedPath = await realpath(descriptorPath);
+        assertContained(root, openedPath);
+        if (openedPath !== resolved) {
+            throw new Error(`Bundled asset path changed during verification: ${relativePath}`);
+        }
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function verifyBundleDeclarations(manifest, customizationManifest, runtimeBundle) {
+    const bundle = customizationManifest.bundle;
+    const components = runtimeBundle.components;
+    const component = components?.customizationBundle;
+    const mapping = manifest.composition.mappings.find(({ id }) => id === "customizations");
+    if (bundle === undefined ||
+        component === undefined ||
+        bundle.id !== "apex-managed-workspace" ||
+        bundle.authority !== manifest.composition.authority ||
+        bundle.composition !== mapping?.mode ||
+        bundle.sourceRoot !== mapping?.sourceRoot ||
+        bundle.generatedRoot !== mapping?.generatedRoot ||
+        customizationManifest.version !== manifest.sources.customizations ||
+        runtimeBundle.bundleVersion !== manifest.sources.customizations ||
+        runtimeBundle.schemaVersion !== manifest.sources.config ||
+        component.version !== manifest.sources.customizations ||
+        component.manifest !== "@apexops/cli/assets/customizations/manifest.json" ||
+        component.assetManifest !== "@apexops/cli/assets/manifest.json" ||
+        component.compositionId !== bundle.id) {
+        throw new Error("Bundle composition declarations are inconsistent");
+    }
+}
+export function clientProjectionDigest(projection, files) {
+    const metadata = new Map(files.map((file) => [file.path, file.sha256]));
+    const projectionFiles = projection.files.map((path) => {
+        const sha256 = metadata.get(path);
+        if (sha256 === undefined)
+            throw new Error(`Client projection references missing asset: ${path}`);
+        return { path, sha256 };
+    });
+    return sha256Bytes(Buffer.concat([
+        Buffer.from(PROJECTION_DOMAIN, "utf8"),
+        canonicalJsonBytes({ id: projection.id, files: projectionFiles }),
+    ]));
+}
+export function bundleLockDigest(input) {
+    const payload = {
+        sources: input.sources,
+        composition: input.composition,
+        projections: input.projections,
+        files: input.files,
+    };
+    return sha256Bytes(Buffer.concat([Buffer.from(LOCK_DOMAIN, "utf8"), canonicalJsonBytes(payload)]));
+}
+async function bundledPayloadFiles(root, directory = root, expectedIdentity) {
+    const before = await lstat(directory, { bigint: true });
+    const identity = expectedIdentity ?? { dev: before.dev, ino: before.ino };
+    if (!before.isDirectory() || before.isSymbolicLink() || before.dev !== identity.dev || before.ino !== identity.ino) {
+        throw new Error(`Bundled asset directory changed during verification: ${portablePath(relative(root, directory))}`);
+    }
+    const files = [];
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))) {
+        const path = join(directory, entry.name);
+        const metadata = await lstat(path, { bigint: true });
+        if (metadata.isSymbolicLink())
+            throw new Error(`Bundled asset contains a symlink: ${portablePath(relative(root, path))}`);
+        if (metadata.isDirectory()) {
+            files.push(...(await bundledPayloadFiles(root, path, { dev: metadata.dev, ino: metadata.ino })));
+        }
+        else if (metadata.isFile() && portablePath(relative(root, path)) !== "manifest.json") {
+            files.push({
+                path: portablePath(relative(root, path)),
+                identity: { dev: metadata.dev, ino: metadata.ino },
+            });
+        }
+        else if (!metadata.isFile())
+            throw new Error(`Unsupported bundled asset entry: ${path}`);
+    }
+    const after = await lstat(directory, { bigint: true });
+    if (!after.isDirectory() || after.isSymbolicLink() || after.dev !== identity.dev || after.ino !== identity.ino) {
+        throw new Error(`Bundled asset directory changed during verification: ${portablePath(relative(root, directory))}`);
+    }
+    return files;
+}
+export async function verifyBundledAssetManifest(root, manifest) {
+    if (manifest.version !== 1 ||
+        manifest.composition?.authority !== "npm:@apexops/cli" ||
+        manifest.composition.generator !== "packages/cli/scripts/prepare-assets.mjs" ||
+        manifest.composition.formatVersion !== 1 ||
+        manifest.lock?.algorithm !== "sha256" ||
+        manifest.lock.canonicalization !== "apex-bundled-assets-v1" ||
+        typeof manifest.sources?.customizations !== "string" ||
+        manifest.sources.customizations.length === 0 ||
+        typeof manifest.sources.config !== "string" ||
+        manifest.sources.config.length === 0 ||
+        !Array.isArray(manifest.files) ||
+        !Array.isArray(manifest.projections) ||
+        !Array.isArray(manifest.composition.mappings)) {
+        throw new Error("Unsupported bundled asset manifest");
+    }
+    const mappings = new Map(manifest.composition.mappings.map((mapping) => [mapping.id, mapping]));
+    if (mappings.size !== manifest.composition.mappings.length)
+        throw new Error("Duplicate bundled asset mapping ID");
+    const generatedDestinations = [];
+    for (const mapping of mappings.values()) {
+        if (!["copy-tree", "copy-entries", "compose-json", "render-client-projections"].includes(mapping.mode)) {
+            throw new Error(`Invalid bundled asset mapping: ${mapping.id}`);
+        }
+        if (mapping.mode === "compose-json") {
+            if (!safeRelativePath(mapping.generatedPath ?? "") ||
+                mapping.sourceRoot !== undefined ||
+                mapping.generatedRoot !== undefined)
+                throw new Error(`Invalid bundled asset mapping: ${mapping.id}`);
+            generatedDestinations.push(mapping.generatedPath);
+        }
+        else if (!safeRelativePath(mapping.sourceRoot ?? "") ||
+            !safeRelativePath(mapping.generatedRoot ?? "") ||
+            mapping.generatedPath !== undefined) {
+            throw new Error(`Invalid bundled asset mapping: ${mapping.id}`);
+        }
+        else
+            generatedDestinations.push(`${mapping.generatedRoot}/`);
+    }
+    for (const [index, destination] of generatedDestinations.entries()) {
+        if (generatedDestinations.some((candidate, candidateIndex) => candidateIndex !== index && (destination.startsWith(candidate) || candidate.startsWith(destination))))
+            throw new Error(`Overlapping bundled asset mapping destination: ${destination}`);
+    }
+    const paths = new Set();
+    for (const file of manifest.files) {
+        if (!safeRelativePath(file.path))
+            throw new Error(`Unsafe bundled asset path: ${file.path}`);
+        if (paths.has(file.path))
+            throw new Error(`Duplicate bundled asset path: ${file.path}`);
+        paths.add(file.path);
+        if (!SHA256.test(file.sha256) || !Number.isSafeInteger(file.bytes) || file.bytes < 0) {
+            throw new Error(`Invalid bundled asset metadata: ${file.path}`);
+        }
+        if (file.source.kind === "repository-file") {
+            const mapping = mappings.get(file.source.mapping ?? "");
+            if (!safeRelativePath(file.source.path ?? "") ||
+                mapping === undefined ||
+                mapping.mode === "compose-json" ||
+                !file.source.path.startsWith(`${mapping.sourceRoot}/`) ||
+                !file.path.startsWith(`${mapping.generatedRoot}/`) ||
+                relative(mapping.sourceRoot, file.source.path).split(sep).join("/") !==
+                    relative(mapping.generatedRoot, file.path).split(sep).join("/")) {
+                throw new Error(`Invalid bundled asset source: ${file.path}`);
+            }
+        }
+        else if (file.source.kind === "generated") {
+            const mapping = mappings.get(file.source.composition ?? "");
+            if (mapping === undefined ||
+                (mapping.mode === "compose-json"
+                    ? mapping.generatedPath !== file.path
+                    : mapping.mode !== "render-client-projections" || !file.path.startsWith(`${mapping.generatedRoot}/`))) {
+                throw new Error(`Invalid bundled asset source: ${file.path}`);
+            }
+            if (mapping.mode === "render-client-projections") {
+                const expectedPrefix = `${mapping.generatedRoot}/${file.source.clientId}/`;
+                if (!["github-copilot-cli", "github-copilot-vscode"].includes(file.source.clientId ?? "") ||
+                    file.source.adapterVersion !== "1.1.0" ||
+                    !safeRelativePath(file.source.target ?? "") ||
+                    !file.path.startsWith(expectedPrefix) ||
+                    file.path !== `${expectedPrefix}${file.source.target}` ||
+                    !safeRelativePath(file.source.sourcePath ?? "") ||
+                    !SHA256.test(file.source.sourceHash ?? "")) {
+                    throw new Error(`Invalid generated client projection provenance: ${file.path}`);
+                }
+            }
+        }
+        else
+            throw new Error(`Invalid bundled asset source: ${file.path}`);
+    }
+    const projectionIds = new Set();
+    for (const projection of manifest.projections) {
+        if (!["github-copilot-cli", "github-copilot-vscode"].includes(projection.id) ||
+            projectionIds.has(projection.id) ||
+            !Array.isArray(projection.files) ||
+            projection.files.length !== new Set(projection.files).size ||
+            projection.files.some((path) => !safeRelativePath(path) || !paths.has(path)) ||
+            !SHA256.test(projection.digest) ||
+            clientProjectionDigest(projection, manifest.files) !== projection.digest) {
+            throw new Error(`Invalid bundled client projection: ${projection.id}`);
+        }
+        projectionIds.add(projection.id);
+    }
+    if (projectionIds.size !== 2)
+        throw new Error("Bundled client projections are incomplete");
+    const actualFiles = (await bundledPayloadFiles(root)).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    if (JSON.stringify(actualFiles.map(({ path }) => path)) !== JSON.stringify(manifest.files.map(({ path }) => path))) {
+        throw new Error("Bundled asset inventory mismatch");
+    }
+    const identities = new Map(actualFiles.map(({ path, identity }) => [path, identity]));
+    for (const file of manifest.files) {
+        const bytes = await readBundledFile(root, file.path, async () => { }, identities.get(file.path));
+        if (bytes.byteLength !== file.bytes || sha256Bytes(bytes) !== file.sha256) {
+            throw new Error(`Bundled asset hash mismatch: ${file.path}`);
+        }
+    }
+    const customizationManifest = JSON.parse((await readBundledFile(root, "customizations/manifest.json")).toString("utf8"));
+    const runtimeBundle = JSON.parse((await readBundledFile(root, "config/runtime-bundle.v1.json")).toString("utf8"));
+    verifyBundleDeclarations(manifest, customizationManifest, runtimeBundle);
+    const sharedFiles = customizationManifest.sharedFiles;
+    const sharedDirectories = (customizationManifest.sharedDirectories ?? []);
+    const roles = customizationManifest.roles;
+    const declarations = customizationManifest.clientProjections;
+    if (!Array.isArray(sharedFiles) ||
+        sharedFiles.length !== new Set(sharedFiles).size ||
+        !Array.isArray(sharedDirectories) ||
+        sharedDirectories.length !== new Set(sharedDirectories).size ||
+        sharedDirectories.some((path) => typeof path !== "string" || !safeRelativePath(path)) ||
+        !Array.isArray(declarations) ||
+        !Array.isArray(roles) ||
+        declarations.length !== manifest.projections.length ||
+        declarations.length !== new Set(declarations.map(({ id }) => id)).size) {
+        throw new Error("Client projection declarations are missing");
+    }
+    const sourceMetadata = new Map(manifest.files.map((file) => [file.path, file]));
+    for (const file of manifest.files.filter(({ source }) => source.kind === "generated" && source.composition === "client-projections")) {
+        const target = projectionTarget(file.source.clientId);
+        const role = file.source.roleId === undefined ? undefined : roles.find(({ id }) => id === file.source.roleId);
+        const canonical = sourceMetadata.get(`customizations/${file.source.sourcePath}`);
+        if ((file.source.roleId !== undefined &&
+            (role === undefined || role.source !== file.source.sourcePath || !role.supportedTargets.includes(target))) ||
+            canonical?.source.kind !== "repository-file" ||
+            canonical.sha256 !== file.source.sourceHash) {
+            throw new Error(`Generated client projection source binding mismatch: ${file.path}`);
+        }
+    }
+    const sharedDirectoryFiles = manifest.files
+        .filter(({ path, source }) => source.kind === "repository-file" &&
+        sharedDirectories.some((directory) => path.startsWith(`customizations/${directory}/`)))
+        .map(({ path }) => path.slice("customizations/".length));
+    for (const declaration of declarations) {
+        const target = projectionTarget(declaration.id);
+        const projection = manifest.projections.find(({ id }) => id === declaration.id);
+        if (!Array.isArray(declaration.files) || declaration.files.length !== new Set(declaration.files).size) {
+            throw new Error(`Bundled client projection disagrees with its declaration: ${declaration.id}`);
+        }
+        const expectedTargets = [
+            ...sharedFiles,
+            ...sharedDirectoryFiles,
+            ...declaration.files,
+            ...roles.filter(({ supportedTargets }) => supportedTargets.includes(target)).map(({ source }) => source),
+        ];
+        const expected = [...new Set(expectedTargets)].map((path) => `${declaration.generatedRoot}/${path}`).sort();
+        if (!safeRelativePath(declaration.generatedRoot) ||
+            projection === undefined ||
+            JSON.stringify(projection.files) !== JSON.stringify(expected)) {
+            throw new Error(`Bundled client projection disagrees with its declaration: ${declaration.id}`);
+        }
+    }
+    if (!SHA256.test(manifest.lock.digest) || bundleLockDigest(manifest) !== manifest.lock.digest) {
+        throw new Error("Bundled asset lock mismatch");
+    }
+}
+export async function resolveBundledAssets() {
+    const root = fileURLToPath(new URL("../assets/", import.meta.url));
+    const manifest = JSON.parse(await readFile(join(root, "manifest.json"), "utf8"));
+    await verifyBundledAssetManifest(root, manifest);
+    return {
+        root: dirname(join(root, "manifest.json")),
+        customizations: join(root, "customizations"),
+        clientProjections: {
+            "github-copilot-cli": join(root, "client-projections", "github-copilot-cli"),
+            "github-copilot-vscode": join(root, "client-projections", "github-copilot-vscode"),
+        },
+        config: join(root, "config"),
+        capabilityPacks: join(root, "capability-packs"),
+        capabilityPackRegistry: join(root, "capability-packs", "registry.v1.json"),
+        manifest,
+    };
+}
+//# sourceMappingURL=assets.js.map

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { type ServiceOptions } from "./service.js";
+export declare function execute(argv: string[], root?: string, options?: ServiceOptions): Promise<unknown>;
+//# sourceMappingURL=cli.d.ts.map